Ana içeriğe atla
Otomasyonlar, bir uygulamanın kendi başına çalışan bölümleridir — bir zamanlamaya göre veya dış bir hizmet bir olay gönderdiğinde. Bunları kazzle.config.ts dosyasında bir process bileşeni üzerinde tanımlarsınız. Bir bileşen ihtiyacınız kadar çok tetikleyiciye sahip olabilir.

Yapı

{
  name: 'events',
  type: 'process',
  path: './components/events/index.ts',
  processMode: 'persistent', // veya 'triggered'
  triggers: [
    { name: 'daily-digest', kind: 'schedule', schedule: '0 9 * * *', path: '/cron/daily-digest' },
    { name: 'stripe',       kind: 'webhook',                          path: '/webhook/stripe' },
  ],
}
Burada iki şey olup bitiyor:
  • processMode yaşam döngüsünü seçer — uzun süre çalışan sunucu veya tetikleyici başına tek seferlik çalışma.
  • triggers[] bu bileşeni tetiklemesi gereken olayları listeler.
İki parça bağımsızdır. Kalıcı bir sunucu cron’a sahip olabilir. Geçici bir işlem webhook’a sahip olabilir. İş yüküne uygun yaşam döngüsünü seçin, ardından istediğiniz kadar çok tetikleyici ekleyin.

processMode

ModNe çalışırNe zaman kullanılır
persistent (varsayılan)Uzun süre çalışan HTTP sunucusu. Tetikleyiciler buna POST edilir.Bileşen zaten HTTP sunuyor veya bellekte durum tutuyor (kuyruklar, websocket’ler, önbellekler).
triggeredGiriş betiği tetikleyici başına oluşturulur ve çıkar.Saf arka plan işleri — gece temizliği, tek Stripe webhook işleyicisi, vb. Boş sunucular yok.

Tetikleyiciler

Her tetikleyicinin bir name (bileşen içinde benzersiz), bir kind ve — moda bağlı olarak — bir schedule ve/veya path vardır.
AlanNe zaman gerekliNotlar
nameher zamanWebhook URL segmentinde ve günlüklerde kullanılır. Kebab-case.
kindher zaman'schedule' veya 'webhook'.
schedulekind: 'schedule' olduğunda5 alanlı cron ifadesi. Dakika çözünürlüğü minimum.
pathprocessMode: 'persistent' olduğundaTetikleyicinin iniş yaptığı sunucunuzda HTTP rotası.

Kalıcı mod — sunucuya HTTP

Kalıcı bir bileşen için tetikleyici ateşlendiğinde, Kazzle belirtilen path adresinde sunucunuza POST yapar. İstek şunları taşır:
BaşlıkNe söyler
Authorization: Bearer ${KAZZLE_TRIGGER_SECRET}Bunu doğrulayın. Eşleşmeyenleri reddedin.
x-kazzle-trigger-nameManifestten tetikleyicinin name değeri.
x-kazzle-trigger-run-idGünlük korelasyonu için opak kimlik.
x-kazzle-triggered-bycron | webhook | manual.
Webhook tetikleyicileri için orijinal istek gövdesi POST gövdesi olarak iletilir. Zamanlama tetikleyicileri için gövde boştur.
// components/events/index.ts (kalıcı mod)
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 });
  },
});

Tetiklenen mod — tetikleyici başına tek seferlik

triggered bileşen için tetikleyici ateşlendiğinde, Kazzle giriş betiğini yeni oluşturur ve çıkmasını bekler. path yoktur; betik hangi tetikleyicinin ateşlendiğini ortam değişkenlerinden öğrenir.
Ortam değişkeniDeğer
TRIGGER_NAMEManifestten tetikleyicinin name değeri.
TRIGGERED_BYcron | webhook | manual.
RUN_IDGünlük korelasyonu için opak kimlik.
WEBHOOK_PAYLOADJSON gövdesi (yalnızca webhook tetikleyicileri).
// components/events/index.ts (tetiklenen mod)
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`);
Tetiklenen bileşenlerin üretimde boş makineleri yoktur — çağrı başına başlatılırlar ve çıkışta kapatılırlar.

Webhook URL’leri

POST https://api.kazzle.app/webhooks/{spaceId}/{appId}/{componentName}/{triggerName}
triggerName segmenti o bileşenin triggers[] içinde bir kind: 'webhook' girişiyle eşleşmelidir. Bilinmeyen tetikleyici adları 404 döndürür.

Zamanlama çözünürlüğü

Cron ifadeleri 5 alanlıdır (dakika, saat, ayın günü, ay, haftanın günü) ve dakika çözünürlüğü minimumdur. Dakika altı zamanlamalar manifest doğrulama sırasında reddedilir.

Çalışmalar nasıl kaydedilir

Her tetikleyici ateşlemesi, trigger_name, triggered_by, run_id ve çalışmanın çıkış durumunu içeren bir process_runs satırı yazar. Bunları kendi kodunuzdan sorgulayabilir veya uygulamanın çalışmalar görünümünde inceleyebilirsiniz.

Krediler tükenmek

Başarısız bir çalışma kaydedilir ve günlüğe alınır, ancak zamanlama normal temposuyla çalışmaya devam eder — hatalı bir çalışma tetikleyiciyi asla devre dışı bırakmaz. Bir çalışmayı durduran tek şey kredilerdir: her tetikleyici ateşlemesi alanın bakiyesine karşı kontrol edilir ve alan kredileri bittiğinde (veya faturalandırma ayarlanmadığında) çalışmalar 402 ile atlanır. Bu kendi kendini iyileştirir — zamanlama silahlı kalır ve bakiyeyi doldurduktan sonraki sonraki ateşleme normal şekilde çalışır, manuel devam etmeye gerek yoktur.

Otomasyonları daha sonra ekleme

Basit bir uygulama tetikleyici olmadan başlayabilir ve daha sonra bunları kazanabilir — günlük bir özet ekleyin, Stripe’ı bağlayın, temizliği çalıştırın. Bileşenin yaşam döngüsü (processMode) ve tetikleyicileri (triggers[]) bağımsızdır, bu nedenle uygulamanın geri kalanını yeniden yazmadan bunları değiştirebilirsiniz.