Crear una extensión

Guía práctica para crear una extensión. Antes, lee el contrato y el modelo de seguridad.

Paso a paso#

1. Crea bloomx-extensions/<nombre>/manifest.json con, como mínimo, id, name y version.
2. Si necesita lógica de servidor, crea server.js y declara en api.functions cada handler que use la interfaz, un mount o un hook.
3. Cada handler tiene la firma handler(ctx): un solo parámetro. Lee ctx.args, ctx.env, ctx.user, ctx.domain…
4. Si necesita secretos (claves de API), decláralos con "permissions": ["ENV_READ:MI_CLAVE"]; cada empresa los configura en el panel (extensiones → credenciales). Nunca los pongas en el manifest ni en el código.
5. Valida: npm test en bloomx-extensions comprueba el schema de cada manifest y el contrato de los handlers.
6. Publica en el backend y luego instálala en un dominio (ver abajo).
7. Prueba en la interfaz: el frontend recibe las extensiones del dominio por GET /api/config y pinta los mounts.

Ejemplo mínimo#

Un botón en la barra del editor que llama a una función del servidor y muestra el resultado.

{
  "manifestVersion": "1.0",
  "id": "core-hello",
  "version": "1.0.0",
  "name": "Hello",
  "description": "Ejemplo mínimo",
  "permissions": [],
  "api": {
    "runtime": "nodejs",
    "entry": "server.js",
    "functions": { "hello": { "handler": "hello", "timeout": 5000 } }
  },
  "mounts": [
    {
      "point": "COMPOSER_TOOLBAR",
      "component": {
        "type": "BUTTON",
        "props": {
          "label": "Hello",
          "variant": "ghost",
          "onClick": {
            "action": "CALL_BACKEND",
            "function": "hello",
            "args": { "name": "${context.subject}" },
            "onSuccess": { "action": "TOAST", "message": "${result.message}" },
            "onError": { "action": "TOAST", "message": "${error}", "variant": "error" }
          }
        }
      }
    }
  ]
}

// bloomx-extensions/hello/server.js
module.exports = {
    hello: async (ctx) => {                                  // UN solo parámetro
        const name = String((ctx.args && ctx.args.name) || 'mundo').slice(0, 100);
        return { success: true, message: `Hola ${name} desde ${ctx.domain.displayName}` };
    },
};

• ${context.subject} y ${result.message} son expresiones que evalúa el intérprete del frontend (sin eval).
• Los nombres label, variant, onClick, onSuccess, onError y message siguen los de las extensiones existentes (composer-helper, organizer). No se ejecutó este ejemplo contra un backend real: úsalo como punto de partida y ajusta según el renderer.

Un hook#

// Un hook que bloquea el envío si el asunto contiene una palabra prohibida.
// manifest: "intercepts": [{ "point": "EMAIL_PRE_SEND", "handler": "check", "priority": "HIGH", "onError": "block" }]
// y "api.functions": { "check": { "handler": "check", "timeout": 3000 } }
module.exports = {
    check: async (ctx) => {
        const banned = String(ctx.env.BANNED_WORDS || '').split(',').map((w) => w.trim().toLowerCase()).filter(Boolean);
        const text = String(ctx.subject || '').toLowerCase();
        const hit = banned.find((w) => text.includes(w));
        return hit ? { stop: true, message: 'Palabra no permitida: ' + hit } : { success: true };
    },
};   // declara "permissions": ["ENV_READ:BANNED_WORDS"] y configura BANNED_WORDS en el panel

Devolver {stop: true, message} bloquea el envío (422). {modify: {subject, html, text}} reescribe el contenido. Ver Hooks para la semántica y los límites (MONITOR, onError).

Usar servicios y eventos#

Además de fetch, una extensión puede usar los servicios autorizados (services.calendar, contacts, storage, notify, formats) y suscribirse a los eventos de ciclo de vida (CONTACT_SAVED, EMAIL_SENT…). Referencia completa: servicios, formats y eventos.

1. Declara en permissions solo lo necesario: CALENDAR_READ/CALENDAR_WRITE, CONTACTS_READ/CONTACTS_WRITE, STORAGE, NOTIFY, FORMATS. El administrador verá la lista legible y debe confirmarla al instalar (ver permisos).
2. En el handler toma el servicio de ctx.services y comprueba que existe: solo hay servicios en dominios firmados; en modo legado no existen.
3. Llama con un objeto de argumentos (calendar.listEvents({from, to})). El userId nunca se pasa: lo fija el host.
4. Envuelve las llamadas en try/catch: los errores empiezan por CALENDAR_, CONTACTS_, STORAGE_, NOTIFY_ o FORMATS_ (..._PERMISSION_DENIED, ..._INVALID_ARGS, ..._ERROR: <code>, ..._CALL_BUDGET…).
5. Para reaccionar a un evento, añade en el manifest "hooks": [{ "point": "CONTACT_SAVED", "handler": "onContactSaved" }] y declara el handler en api.functions (con timeout ≤ 10 s). Los eventos no bloquean ni modifican nada, y lo que hagas con services.* no los vuelve a disparar.
6. Para pintar un panel en un punto nuevo (EMAIL_READER_SIDEBAR, SETTINGS_PANEL…) mira antes si ya está montado en la interfaz: la tabla de puntos de montaje lo indica.

// bloomx-extensions/agenda/server.js
// manifest: "permissions": ["CALENDAR_READ", "FORMATS", "STORAGE"]
module.exports = {
    today: async (ctx) => {
        const { calendar, formats, storage } = ctx.services || {};
        if (!calendar) return { success: false, code: 'CALENDAR_SERVICE_UNAVAILABLE' };   // modo legado o sin servicio: degradar
        const from = new Date(); from.setUTCHours(0, 0, 0, 0);
        const to = new Date(from.getTime() + 86400000);
        try {
            const { events } = await calendar.listEvents({ from: from.toISOString(), to: to.toISOString(), limit: 20 });
            const rows = [];
            for (const e of events) {
                const start = formats ? await formats.formatDate({ value: e.startsAt, locale: 'es-ES', style: 'time' }) : e.startsAt;
                rows.push({ title: e.title, start });
            }
            if (storage) await storage.set({ key: 'last-run', value: { at: new Date().toISOString(), count: rows.length } }).catch(() => {});
            return { success: true, rows };
        } catch (error) {
            return { success: false, code: String(error.message).split(':')[0] };   // p. ej. CALENDAR_PERMISSION_DENIED
        }
    },
};

Publicar e instalar#

# 1) Validar localmente (Node >= 22.6)
cd bloomx-extensions && npm test

# 2) Publicar en el backend (lee ../bloomx-extensions; necesita B2_* y DATABASE_URL reales en .env)
cd ../bloomx-backend && node --env-file=.env sync-extensions.mjs

# 3) Instalar en un dominio (sesión de manager dueño del dominio)
curl -sS -X POST "$BACKEND/api/manager/extensions/install" -H 'content-type: application/json' \
  -b 'auth_session=<cookie>' -d '{"domainId":"<id>","extensionId":"core-hello"}'

• sync-extensions.mjs (en la raíz de bloomx-backend) sube server.js a b2://<bucket>/extensions/<id>/server.js y hace upsert de la extensión con el manifest completo como template. Las extensiones sin server.js (solo cliente) se publican con scriptUrl = null. No valida el manifest, por eso el paso 1 es imprescindible. Sale con código 1 si falta alguna variable B2_* o DATABASE_URL.
• Existe una variante, scripts/sync-repository-extensions.mjs (B2 opcional; clave de objeto extensions/<id>-v<version>.js).
• Alternativa con el super-admin de plataforma: POST /api/admin/extensions (multipart, Basic Auth con ADMIN_EMAIL/ADMIN_PASSWORD) sí valida el manifest con el schema (400 con detalle) y sube a extensions/<id>/<version>/server.js.
• Si cambias el schema (_shared/manifest-schema.ts), copia el archivo a bloomx-backend/src/lib/extensions/ y a bloomx/src/lib/expansions/; un test comprueba que las copias sean idénticas.
• Extensiones de pago (isPaid): la instalación exige una transacción APPROVED (402 PAYMENT_REQUIRED).

Lista de comprobación#

• El manifest valida (npm test) y cada función referenciada existe en api.functions.
• Los handlers tienen un solo parámetro y devuelven JSON serializable (≤ 5 MB) dentro de 25 s (o el timeout declarado, 100–60000 ms).
• Solo usas fetch https y los globals disponibles en el sandbox (sin require).
• Los secretos van en ENV_READ:* y se configuran por dominio.
• Si usas services.mail, declaras READ_EMAIL o MAIL_LABEL y el dominio está en modo firmado.
• Si usas services.calendar|contacts|storage|notify|formats, declaras su permiso (CALENDAR_*, CONTACTS_*, STORAGE, NOTIFY, FORMATS) y degradas cuando ctx.services.<x> no existe (modo legado).
• Si te suscribes a un evento de ciclo de vida, tu handler no lanza (devuelve {success:false}), termina en menos de 10 s y no depende de bloquear ni modificar nada.
• Si dependes de hooks EMAIL_RECEIVED o CRON, recuerda que el dominio debe estar en modo firmado y que CRON hoy no lo dispara nadie.

Para una página completa (un mount PAGE con cabecera, indicadores, gráficos y tabla) y su entrada en la barra lateral o en la consola de administración (navEntries, con insignia opcional), sigue la guía Página completa y navegación.

Documentos internos antiguos#

Los archivos de bloomorg-updates/ (planes 01/02) describen el diseño original y están desactualizados (hablan de node:vm, de JWT/secretos compartidos y de Sealer/Organizer deshabilitados). Esta documentación y expansions/howto.md son la referencia vigente. Esos archivos pueden contener credenciales de prueba: no los versiones y rota cualquier credencial que haya estado en ellos.