Configuración de ImageKit

Overview

Este archivo centraliza la creación y exposición del cliente de ImageKit para el backend. También ofrece un acceso separado a la configuración pública que otras rutas necesitan para generar autenticación o mostrar datos de conexión sin revelar la private key. El módulo se conecta con las rutas de subida y con los servicios de media que consumen ImageKit desde un único punto de integración fileciteturn0file13turn0file15turn0file18.

[!NOTE] En entorno de pruebas, getImageKitClient() se comporta como “no configurado” si no hay override explícito. Esto evita que los tests usen almacenamiento real, incluso si el .env local contiene credenciales fileciteturn0file13turn0file1turn0file4.

How it works

El módulo mantiene dos estados internos: una caché del cliente real y un override para tests. Cuando se pide el cliente, primero devuelve el override si existe; si no, reutiliza el cliente ya creado; y solo si no hay ninguno, valida la configuración antes de construir una nueva instancia de ImageKit .

Si falta env.imagekitPrivateKey, o el proceso está en NODE_ENV="test", o existe process.env.NODE_TEST_CONTEXT, el módulo lanza un error estable con code: "IMAGEKIT_NOT_CONFIGURED". Ese código permite que las rutas distingan entre un entorno sin storage y un fallo real del proveedor fileciteturn0file13turn0file0.

La configuración pública no crea clientes ni hace validaciones adicionales. Solo devuelve publicKey y urlEndpoint desde env, y esas claves pueden llegar vacías si el entorno no las define fileciteturn0file13turn0file0.

Key components

{
    "title": "getImageKitClient",
    "content": "Devuelve el cliente de ImageKit activo. Usa primero el override de pruebas, luego la cach\u00e9 interna, y si no existe construye una nueva instancia con `env.imagekitPrivateKey`.",
    "type": "function",
    "filePath": "services/api/src/config/imagekit.js",
    "badges": [
        "public"
    ]
}

{
    "title": "setImageKitClientForTests",
    "content": "Permite inyectar un cliente falso solo cuando `NODE_ENV` es `test`. Fuera de pruebas lanza un error.",
    "type": "function",
    "filePath": "services/api/src/config/imagekit.js",
    "badges": [
        "public"
    ]
}

{
    "title": "resetImageKitClientForTests",
    "content": "Borra el override de pruebas cuando el proceso est\u00e1 en `test`. Sirve para restaurar el estado entre casos de prueba.",
    "type": "function",
    "filePath": "services/api/src/config/imagekit.js",
    "badges": [
        "public"
    ]
}

{
    "title": "getImageKitPublicConfig",
    "content": "Devuelve la configuraci\u00f3n p\u00fablica de ImageKit: `publicKey` y `urlEndpoint`. No expone la private key ni crea clientes.",
    "type": "function",
    "filePath": "services/api/src/config/imagekit.js",
    "badges": [
        "public"
    ]
}

Data & fields

[
    {
        "name": "imagekitClient",
        "type": "ImageKit | null",
        "description": "Caché interna del cliente real. Empieza en `null` y se reutiliza después de la primera creación."
    },
    {
        "name": "clientOverride",
        "type": "unknown",
        "description": "Override inyectable para tests. Tiene prioridad sobre el cliente real mientras exista."
    },
    {
        "name": "env.imagekitPrivateKey",
        "type": "string",
        "required": true,
        "description": "Clave privada usada para construir el cliente real. Si falta, el módulo lanza `IMAGEKIT_NOT_CONFIGURED`."
    },
    {
        "name": "env.imagekitPublicKey",
        "type": "string",
        "description": "Clave pública expuesta por `getImageKitPublicConfig()`."
    },
    {
        "name": "env.imagekitUrlEndpoint",
        "type": "string",
        "description": "Endpoint público expuesto por `getImageKitPublicConfig()`."
    }
]

[
    {
        "name": "publicKey",
        "type": "string",
        "required": true,
        "description": "Clave pública de ImageKit tomada de `env.imagekitPublicKey`."
    },
    {
        "name": "urlEndpoint",
        "type": "string",
        "required": true,
        "description": "URL pública de ImageKit tomada de `env.imagekitUrlEndpoint`."
    }
]

Behaviors

  • getImageKitClient() — Devuelve un cliente de ImageKit reutilizable, o lanza IMAGEKIT_NOT_CONFIGURED cuando el storage no está disponible.
  • setImageKitClientForTests(client) — Registra un cliente alternativo para pruebas y devuelve undefined.
  • resetImageKitClientForTests() — Limpia el override de pruebas y devuelve undefined.
  • getImageKitPublicConfig() — Devuelve un objeto con publicKey y urlEndpoint.

Gotchas & edge cases

[!WARNING] setImageKitClientForTests() solo acepta overrides dentro de NODE_ENV="test". Si se llama fuera de pruebas, lanza ImageKit client overrides are only available in tests .

[!CAUTION] getImageKitClient() no crea el cliente real en NODE_ENV="test" ni cuando existe NODE_TEST_CONTEXT. Esa regla aparece para impedir acceso accidental al almacenamiento real durante la suite de pruebas fileciteturn0file13turn0file1turn0file4.

[!NOTE] resetImageKitClientForTests() solo modifica el override cuando el proceso sigue en test. Fuera de ese entorno, no hace cambios visibles .

[!IMPORTANT] El error IMAGEKIT_NOT_CONFIGURED tiene un código estable. Las rutas pueden usarlo para responder como “entorno sin almacenamiento” en vez de confundirlo con un fallo genérico del proveedor .

Este módulo es consumido por services/api/src/modules/uploads/uploads.routes.js, donde /imagekit-auth usa getImageKitClient() para generar parámetros de autenticación y getImageKitPublicConfig() para devolver credenciales públicas al cliente . También aparece en el flujo de media, donde services/api/src/modules/media/media.service.js importa getImageKitClient() para operar sobre ImageKit desde la capa de negocio .

La configuración que alimenta este módulo vive en services/api/src/config/env.js, donde se leen IMAGEKIT_PUBLIC_KEY, IMAGEKIT_PRIVATE_KEY e IMAGEKIT_URL_ENDPOINT desde el entorno fileciteturn0file0turn0file5. Los tests del repositorio usan setImageKitClientForTests() y resetImageKitClientForTests() para sustituir el cliente real por dobles controlados fileciteturn0file1turn0file3turn0file4turn0file6.

Updated