Automatizaciones

Las automatizaciones son las partes de una app que se ejecutan por sí solas — en una programación, o cuando un servicio externo envía un evento. Las declaras en un componente process en kazzle.config.ts. Un componente puede llevar tantos triggers como necesites.

La estructura

{
  name: 'events',
  type: 'process',
  path: './components/events/index.ts',
  processMode: 'persistent', // o 'triggered'
  triggers: [
    { name: 'daily-digest', kind: 'schedule', schedule: '0 9 * * *', path: '/cron/daily-digest' },
    { name: 'stripe',       kind: 'webhook',                          path: '/webhook/stripe' },
  ],
}

Aquí suceden dos cosas:

processMode elige el ciclo de vida — servidor de larga duración, o una ejecución única por trigger.
triggers[] lista los eventos que deben activar este componente.

Las dos partes son independientes. Un servidor persistente puede tener un cron. Un proceso efímero puede tener un webhook. Elige el ciclo de vida que se ajuste a la carga de trabajo, luego adjunta tantos triggers como quieras.

`processMode`

Modo	Qué se ejecuta	Cuándo usar
`persistent` (predeterminado)	Un servidor HTTP de larga duración. Los triggers se envían por POST.	El componente ya sirve HTTP, o mantiene estado en memoria (colas, websockets, cachés).
`triggered`	El script de entrada se genera por trigger y sale.	Trabajos de fondo puros — limpieza nocturna, manejador único de webhook de Stripe, etc. Sin servidores inactivos.

Triggers

Cada trigger tiene un name (único dentro del componente), un kind, y — dependiendo del modo — un schedule y/o path.

Campo	Cuándo es requerido	Notas
`name`	siempre	Se usa como segmento de URL de webhook y en logs. Kebab-case.
`kind`	siempre	`'schedule'` o `'webhook'`.
`schedule`	cuando `kind: 'schedule'`	Expresión cron de 5 campos. La resolución de minutos es el mínimo.
`path`	cuando `processMode: 'persistent'`	Ruta HTTP en tu servidor donde llega el trigger.

Modo persistente — HTTP hacia el servidor

Cuando un trigger se activa para un componente persistente, Kazzle envía un POST a tu servidor en el path declarado. La solicitud lleva:

Encabezado	Qué te dice
`Authorization: Bearer ${KAZZLE_TRIGGER_SECRET}`	Valida esto. Rechaza llamadas que no coincidan.
`x-kazzle-trigger-name`	El `name` del trigger del manifiesto.
`x-kazzle-trigger-run-id`	ID opaco para correlación de logs.
`x-kazzle-triggered-by`	`cron` \| `webhook` \| `manual`.

Para triggers de webhook, el cuerpo de la solicitud original se reenvía como cuerpo POST. Para triggers de programación el cuerpo está vacío.

// components/events/index.ts (modo persistente)
const TRIGGER_SECRET = process.env.KAZZLE_TRIGGER_SECRET ?? '';

Bun.serve({
  port: Number(process.env.PORT),
  hostname: process.env.HOST,
  async fetch(req) {
    const url = new URL(req.url);

    if (req.method === 'POST' && url.pathname === '/cron/daily-digest') {
      if (req.headers.get('authorization') !== `Bearer ${TRIGGER_SECRET}`) {
        return new Response('Unauthorized', { status: 401 });
      }
      await sendDigest();
      return Response.json({ ok: true });
    }

    if (req.method === 'POST' && url.pathname === '/webhook/stripe') {
      if (req.headers.get('authorization') !== `Bearer ${TRIGGER_SECRET}`) {
        return new Response('Unauthorized', { status: 401 });
      }
      const event = await req.json();
      await handleStripe(event);
      return Response.json({ ok: true });
    }

    return new Response('not found', { status: 404 });
  },
});

Modo activado — una ejecución única por trigger

Cuando un trigger se activa para un componente triggered, Kazzle genera el script de entrada nuevo y espera a que salga. No hay path; el script aprende qué trigger se activó desde variables de entorno.

Variable de entorno	Valor
`TRIGGER_NAME`	El `name` del trigger del manifiesto.
`TRIGGERED_BY`	`cron` \| `webhook` \| `manual`.
`RUN_ID`	ID opaco para correlación de logs.
`WEBHOOK_PAYLOAD`	Cuerpo JSON (solo triggers de webhook).

// components/events/index.ts (modo activado)
const trigger = process.env.TRIGGER_NAME;
const runId = process.env.RUN_ID;

if (trigger === 'daily-digest') {
  await sendDigest();
} else if (trigger === 'stripe') {
  const event = JSON.parse(process.env.WEBHOOK_PAYLOAD ?? '{}');
  await handleStripe(event);
}

console.log(`run ${runId} done`);

Los componentes activados no tienen máquinas inactivas en producción — se inician por llamada y se apagan al salir.

URLs de webhook

POST https://api.kazzle.app/webhooks/{spaceId}/{appId}/{componentName}/{triggerName}

El segmento triggerName debe coincidir con una entrada kind: 'webhook' en el triggers[] de ese componente. Los nombres de trigger desconocidos devuelven 404.

Resolución de programación

Las expresiones cron son de 5 campos (minuto, hora, día del mes, mes, día de la semana) y la resolución de minutos es el mínimo. Las programaciones sub-minuto se rechazan en el tiempo de validación del manifiesto.

Cómo se registran las ejecuciones

Cada activación de trigger escribe una fila process_runs con el trigger_name, triggered_by, run_id, y el estado de salida de la ejecución. Puedes consultar estos desde tu propio código o inspeccionarlos en la vista de ejecuciones de la app.

Agotamiento de créditos

Una ejecución fallida se registra y se registra, pero la programación sigue ejecutándose en su cadencia normal — una ejecución inestable nunca desactiva el trigger. Lo único que detiene una ejecución son los créditos: cada activación de trigger se verifica contra el saldo del espacio, y mientras el espacio no tenga créditos (o no tenga facturación configurada) las ejecuciones se omiten con un 402. Esto se recupera automáticamente — la programación permanece armada y la siguiente activación después de que recargues se ejecuta normalmente, sin reanudación manual.

Agregar automatizaciones después

Una app simple puede comenzar sin triggers y ganarlos después — agregar un resumen diario, conectar Stripe, ejecutar limpieza. El ciclo de vida del componente (processMode) y los triggers (triggers[]) son independientes, así que puedes cambiarlos sin reescribir el resto de la app.

Acerca de Kazzle

Trabajo

Navegar

Código

Apps

Seguridad

Plataforma

Automatizaciones

La estructura

`processMode`

Triggers

Modo persistente — HTTP hacia el servidor

Modo activado — una ejecución única por trigger

URLs de webhook

Resolución de programación

Cómo se registran las ejecuciones

Agotamiento de créditos

Agregar automatizaciones después

​La estructura

​processMode

​Triggers

​Modo persistente — HTTP hacia el servidor

​Modo activado — una ejecución única por trigger

​URLs de webhook

​Resolución de programación

​Cómo se registran las ejecuciones

​Agotamiento de créditos

​Agregar automatizaciones después

La estructura

`processMode`

Triggers

Modo persistente — HTTP hacia el servidor

Modo activado — una ejecución única por trigger

URLs de webhook

Resolución de programación

Cómo se registran las ejecuciones

Agotamiento de créditos

Agregar automatizaciones después