Automações

Automações são as partes de um app que rodam por conta própria — em um cronograma, ou quando um serviço externo envia um evento. Você as declara em um componente process em kazzle.config.ts. Um componente pode ter quantos triggers você precisar.

A estrutura

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

Duas coisas estão acontecendo aqui:

processMode escolhe o ciclo de vida — servidor de longa duração, ou uma execução única por trigger.
triggers[] lista os eventos que devem disparar este componente.

Os dois são independentes. Um servidor persistente pode ter um cron. Um processo efêmero pode ter um webhook. Escolha o ciclo de vida que se adequa à carga de trabalho e anexe quantos triggers quiser.

`processMode`

Modo	O que roda	Quando usar
`persistent` (padrão)	Um servidor HTTP de longa duração. Triggers são POSTados para ele.	O componente já serve HTTP, ou mantém estado em memória (filas, websockets, caches).
`triggered`	O script de entrada é executado por trigger e sai.	Tarefas de background puro — limpeza noturna, handler único de webhook Stripe, etc. Sem servidores ociosos.

Triggers

Cada trigger tem um name (único dentro do componente), um kind, e — dependendo do modo — um schedule e/ou path.

Campo	Quando obrigatório	Notas
`name`	sempre	Usado no segmento da URL do webhook e em logs. Kebab-case.
`kind`	sempre	`'schedule'` ou `'webhook'`.
`schedule`	quando `kind: 'schedule'`	Expressão cron de 5 campos. Resolução de minuto é o mínimo.
`path`	quando `processMode: 'persistent'`	Rota HTTP no seu servidor onde o trigger chega.

Modo persistente — HTTP para o servidor

Quando um trigger dispara para um componente persistente, Kazzle faz POST no seu servidor no path declarado. A requisição carrega:

Header	O que informa
`Authorization: Bearer ${KAZZLE_TRIGGER_SECRET}`	Valide isto. Rejeite chamadas que não correspondem.
`x-kazzle-trigger-name`	O `name` do trigger do manifesto.
`x-kazzle-trigger-run-id`	ID opaco para correlação de logs.
`x-kazzle-triggered-by`	`cron` \| `webhook` \| `manual`.

Para triggers de webhook, o corpo da requisição original é encaminhado como corpo do POST. Para triggers de cronograma o corpo está vazio.

// 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 triggered — uma execução por trigger

Quando um trigger dispara para um componente triggered, Kazzle executa o script de entrada do zero e aguarda sua saída. Não há path; o script aprende qual trigger disparou através de variáveis de ambiente.

Variável de ambiente	Valor
`TRIGGER_NAME`	O `name` do trigger do manifesto.
`TRIGGERED_BY`	`cron` \| `webhook` \| `manual`.
`RUN_ID`	ID opaco para correlação de logs.
`WEBHOOK_PAYLOAD`	Corpo JSON (apenas triggers de webhook).

// components/events/index.ts (modo triggered)
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`);

Componentes triggered não têm máquinas ociosas em produção — eles iniciam por chamada e desligam na saída.

URLs de webhook

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

O segmento triggerName deve corresponder a uma entrada kind: 'webhook' em triggers[] daquele componente. Nomes de trigger desconhecidos retornam 404.

Resolução de cronograma

Expressões cron são de 5 campos (minuto, hora, dia do mês, mês, dia da semana) e resolução de minuto é o mínimo. Cronogramas sub-minuto são rejeitados na validação do manifesto.

Como as execuções são registradas

Cada disparo de trigger escreve uma linha process_runs com trigger_name, triggered_by, run_id e o status de saída da execução. Você pode consultá-las do seu próprio código ou inspecioná-las na visualização de execuções do app.

Ficando sem créditos

Uma execução com falha é registrada e registrada em log, mas o cronograma continua rodando em seu ritmo normal — uma execução instável nunca desativa o trigger. A única coisa que para uma execução é créditos: cada disparo de trigger é verificado contra o saldo do espaço, e enquanto o espaço está sem créditos (ou não tem cobrança configurada) as execuções são puladas com um 402. Isto é auto-recuperável — o cronograma permanece armado e o próximo disparo após você recarregar roda normalmente, sem retomada manual.

Adicionando automações depois

Um app simples pode começar sem triggers e ganhá-los depois — adicione um resumo diário, conecte Stripe, execute limpeza. O ciclo de vida do componente (processMode) e triggers (triggers[]) são independentes, então você pode alterá-los sem reescrever o resto do app.

Sobre Kazzle

Trabalho

Navegação

Código

Apps

Segurança

Plataforma

A estrutura

`processMode`

Triggers

Modo persistente — HTTP para o servidor

Modo triggered — uma execução por trigger

URLs de webhook

Resolução de cronograma

Como as execuções são registradas

Ficando sem créditos

Adicionando automações depois

​A estrutura

​processMode

​Triggers

​Modo persistente — HTTP para o servidor

​Modo triggered — uma execução por trigger

​URLs de webhook

​Resolução de cronograma

​Como as execuções são registradas

​Ficando sem créditos

​Adicionando automações depois

A estrutura

`processMode`

Triggers

Modo persistente — HTTP para o servidor

Modo triggered — uma execução por trigger

URLs de webhook

Resolução de cronograma

Como as execuções são registradas

Ficando sem créditos

Adicionando automações depois