Automazioni

Le automazioni sono le parti di un’app che funzionano autonomamente — secondo una pianificazione, o quando un servizio esterno invia un evento. Le dichiari su un componente process in kazzle.config.ts. Un componente può avere tutti i trigger di cui hai bisogno.

La struttura

{
  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' },
  ],
}

Due cose stanno accadendo qui:

processMode sceglie il ciclo di vita — server long-running, o esecuzione una tantum per trigger.
triggers[] elenca gli eventi che devono attivare questo componente.

I due elementi sono indipendenti. Un server persistente può avere un cron. Un processo effimero può avere un webhook. Scegli il ciclo di vita che si adatta al carico di lavoro, poi allega tutti i trigger che vuoi.

`processMode`

Modalità	Cosa viene eseguito	Quando usare
`persistent` (predefinito)	Un server HTTP long-running. I trigger vengono POSTati al suo interno.	Il componente già serve HTTP, o mantiene lo stato in memoria (code, websocket, cache).
`triggered`	Lo script di entry viene generato per trigger ed esce.	Job di background puri — pulizia notturna, singolo handler webhook Stripe, ecc. Nessun server inattivo.

Trigger

Ogni trigger ha un name (univoco all’interno del componente), un kind, e — a seconda della modalità — uno schedule e/o un path.

Campo	Quando richiesto	Note
`name`	sempre	Usato come segmento URL webhook e nei log. Kebab-case.
`kind`	sempre	`'schedule'` o `'webhook'`.
`schedule`	quando `kind: 'schedule'`	Espressione cron a 5 campi. La risoluzione al minuto è il minimo.
`path`	quando `processMode: 'persistent'`	Rotta HTTP sul tuo server dove il trigger arriva.

Modalità persistente — HTTP nel server

Quando un trigger si attiva per un componente persistente, Kazzle POSTa al tuo server al path dichiarato. La richiesta contiene:

Header	Cosa ti dice
`Authorization: Bearer ${KAZZLE_TRIGGER_SECRET}`	Convalidalo. Rifiuta le chiamate che non corrispondono.
`x-kazzle-trigger-name`	Il `name` del trigger dal manifest.
`x-kazzle-trigger-run-id`	ID opaco per la correlazione dei log.
`x-kazzle-triggered-by`	`cron` \| `webhook` \| `manual`.

Per i trigger webhook, il corpo della richiesta originale viene inoltrato come corpo POST. Per i trigger di pianificazione il corpo è vuoto.

// components/events/index.ts (modalità 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 });
  },
});

Modalità triggered — una tantum per trigger

Quando un trigger si attiva per un componente triggered, Kazzle genera lo script di entry da zero e attende che esca. Non c’è path; lo script apprende quale trigger si è attivato dalle variabili d’ambiente.

Variabile d’ambiente	Valore
`TRIGGER_NAME`	Il `name` del trigger dal manifest.
`TRIGGERED_BY`	`cron` \| `webhook` \| `manual`.
`RUN_ID`	ID opaco per la correlazione dei log.
`WEBHOOK_PAYLOAD`	Corpo JSON (solo trigger webhook).

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

I componenti triggered non hanno macchine inattive in produzione — si avviano per chiamata e si spengono all’uscita.

URL dei webhook

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

Il segmento triggerName deve corrispondere a una voce kind: 'webhook' in triggers[] di quel componente. I nomi di trigger sconosciuti restituiscono 404.

Risoluzione della pianificazione

Le espressioni cron sono a 5 campi (minuto, ora, giorno del mese, mese, giorno della settimana) e la risoluzione al minuto è il minimo. Le pianificazioni sub-minuto vengono rifiutate al momento della convalida del manifest.

Come vengono registrate le esecuzioni

Ogni attivazione di trigger scrive una riga process_runs con trigger_name, triggered_by, run_id, e lo stato di uscita dell’esecuzione. Puoi interrogarle dal tuo codice o ispezionarle nella vista esecuzioni dell’app.

Esaurimento dei crediti

Un’esecuzione non riuscita viene registrata e registrata, ma la pianificazione continua al suo ritmo normale — un’esecuzione instabile non disabilita mai il trigger. L’unica cosa che ferma un’esecuzione è il credito: ogni attivazione di trigger viene controllata rispetto al saldo dello spazio, e mentre lo spazio è senza crediti (o non ha alcuna fatturazione configurata) le esecuzioni vengono saltate con un 402. Questo è auto-recuperabile — la pianificazione rimane armata e l’attivazione successiva dopo il rifornimento viene eseguita normalmente, senza ripresa manuale.

Aggiunta di automazioni in seguito

Un’app semplice può iniziare senza trigger e acquisirli in seguito — aggiungi un riepilogo giornaliero, connetti Stripe, esegui la pulizia. Il ciclo di vita del componente (processMode) e i trigger (triggers[]) sono indipendenti, quindi puoi modificarli senza riscrivere il resto dell’app.

Informazioni su Kazzle

Lavoro

Navigazione

Codice

App

Sicurezza

Piattaforma

La struttura

`processMode`

Trigger

Modalità persistente — HTTP nel server

Modalità triggered — una tantum per trigger

URL dei webhook

Risoluzione della pianificazione

Come vengono registrate le esecuzioni

Esaurimento dei crediti

Aggiunta di automazioni in seguito

​La struttura

​processMode

​Trigger

​Modalità persistente — HTTP nel server

​Modalità triggered — una tantum per trigger

​URL dei webhook

​Risoluzione della pianificazione

​Come vengono registrate le esecuzioni

​Esaurimento dei crediti

​Aggiunta di automazioni in seguito

La struttura

`processMode`

Trigger

Modalità persistente — HTTP nel server

Modalità triggered — una tantum per trigger

URL dei webhook

Risoluzione della pianificazione

Come vengono registrate le esecuzioni

Esaurimento dei crediti

Aggiunta di automazioni in seguito