@cloudwerk/trigger 0.0.1

package/dist/types-w3ZeMXZ9.d.ts

@@ -0,0 +1,510 @@
+/**
+ * @cloudwerk/trigger - Type Definitions
+ *
+ * Core types for event-driven triggers in Cloudwerk.
+ */
+/**
+ * Type that can be either a value or a Promise of that value.
+ * Used throughout the trigger package for async-friendly APIs.
+ */
+type Awaitable<T> = T | Promise<T>;
+/**
+ * Batch configuration for queue and R2 triggers.
+ */
+interface BatchConfig {
+    /**
+     * Maximum number of events to deliver in a batch.
+     * @default 10
+     */
+    size?: number;
+    /**
+     * Maximum time to wait for a batch to fill.
+     * Supports duration strings like '5s', '30s'.
+     * @default '5s'
+     */
+    timeout?: string;
+}
+/**
+ * Retry configuration for triggers.
+ */
+interface RetryConfig {
+    /**
+     * Maximum number of retry attempts.
+     * @default 3
+     */
+    maxAttempts?: number;
+    /**
+     * Delay between retries. Supports duration strings like '30s', '1m'.
+     * @default '1m'
+     */
+    delay?: string;
+    /**
+     * Backoff strategy for retries.
+     * - 'linear': Fixed delay between retries
+     * - 'exponential': Delay doubles with each retry
+     * @default 'linear'
+     */
+    backoff?: 'linear' | 'exponential';
+}
+/**
+ * Result of webhook signature verification.
+ */
+interface WebhookVerificationResult {
+    /** Whether the signature is valid */
+    valid: boolean;
+    /** Error message if verification failed */
+    error?: string;
+}
+/**
+ * Webhook signature verifier function.
+ *
+ * @param request - The incoming request
+ * @param rawBody - The raw request body as ArrayBuffer
+ * @returns Verification result
+ */
+type WebhookVerifier = (request: Request, rawBody: ArrayBuffer) => Awaitable<WebhookVerificationResult>;
+/**
+ * R2 event types that can trigger a handler.
+ */
+type R2EventType = 'object-create' | 'object-delete';
+/**
+ * D1 event types that can trigger a handler.
+ */
+type D1EventType = 'insert' | 'update' | 'delete';
+/**
+ * Queue trigger source configuration.
+ */
+interface QueueTriggerSource {
+    type: 'queue';
+    /** Name of the queue to consume from */
+    queue: string;
+    /** Batch configuration */
+    batch?: BatchConfig;
+}
+/**
+ * Scheduled (cron) trigger source configuration.
+ */
+interface ScheduledTriggerSource {
+    type: 'scheduled';
+    /** Cron expression (e.g., '0 0 * * *' for daily at midnight) */
+    cron: string;
+}
+/**
+ * R2 bucket trigger source configuration.
+ */
+interface R2TriggerSource {
+    type: 'r2';
+    /** Name of the R2 bucket */
+    bucket: string;
+    /** Event types to trigger on */
+    events: R2EventType[];
+    /** Optional prefix filter */
+    prefix?: string;
+    /** Optional suffix filter */
+    suffix?: string;
+}
+/**
+ * Webhook trigger source configuration.
+ */
+interface WebhookTriggerSource {
+    type: 'webhook';
+    /** URL path for the webhook (e.g., '/webhooks/stripe') */
+    path: string;
+    /** Optional signature verifier */
+    verify?: WebhookVerifier;
+    /** HTTP methods to accept (default: ['POST']) */
+    methods?: ('POST' | 'PUT' | 'PATCH')[];
+}
+/**
+ * Email trigger source configuration.
+ */
+interface EmailTriggerSource {
+    type: 'email';
+    /** Email address pattern to match */
+    address: string;
+}
+/**
+ * D1 database trigger source configuration.
+ */
+interface D1TriggerSource {
+    type: 'd1';
+    /** Name of the D1 database binding */
+    database: string;
+    /** Table to watch */
+    table: string;
+    /** Event types to trigger on */
+    events: D1EventType[];
+}
+/**
+ * Tail trigger source configuration (for consuming logs from other workers).
+ */
+interface TailTriggerSource {
+    type: 'tail';
+    /** Worker names to consume logs from */
+    consumers: string[];
+}
+/**
+ * Union of all trigger source types.
+ */
+type TriggerSource = QueueTriggerSource | ScheduledTriggerSource | R2TriggerSource | WebhookTriggerSource | EmailTriggerSource | D1TriggerSource | TailTriggerSource;
+/**
+ * Scheduled event passed to cron trigger handlers.
+ */
+interface ScheduledEvent {
+    /** The cron expression that triggered this event */
+    cron: string;
+    /** Unix timestamp (milliseconds) when the event was scheduled */
+    scheduledTime: number;
+    /**
+     * Prevent automatic retry on failure.
+     * Call this if the error is not recoverable.
+     */
+    noRetry(): void;
+}
+/**
+ * Single message in a queue batch.
+ */
+interface QueueMessage<T = unknown> {
+    /** Unique message ID */
+    readonly id: string;
+    /** Message payload */
+    readonly body: T;
+    /** When the message was sent */
+    readonly timestamp: Date;
+    /** Number of delivery attempts */
+    readonly attempts: number;
+    /** Acknowledge successful processing */
+    ack(): void;
+    /** Request retry with optional delay */
+    retry(options?: {
+        delaySeconds?: number;
+    }): void;
+}
+/**
+ * Queue batch event passed to queue trigger handlers.
+ */
+interface QueueBatchEvent<T = unknown> {
+    /** Array of messages in the batch */
+    messages: QueueMessage<T>[];
+    /** Name of the queue */
+    queue: string;
+    /** Acknowledge all messages in the batch */
+    ackAll(): void;
+    /** Retry all messages in the batch */
+    retryAll(): void;
+}
+/**
+ * R2 object event passed to R2 trigger handlers.
+ */
+interface R2Event {
+    /** Type of event */
+    type: 'object-create' | 'object-delete';
+    /** Name of the R2 bucket */
+    bucket: string;
+    /** Object key (path) */
+    key: string;
+    /** ETag of the object (for create events) */
+    etag?: string;
+    /** Size in bytes (for create events) */
+    size?: number;
+    /** Upload timestamp (for create events) */
+    uploadedAt?: Date;
+    /** Account ID */
+    account: string;
+    /** Event ID for deduplication */
+    eventId: string;
+}
+/**
+ * Webhook event passed to webhook trigger handlers.
+ */
+interface WebhookEvent<T = unknown> {
+    /** Parsed payload (JSON) */
+    payload: T;
+    /** Request headers */
+    headers: Headers;
+    /** Signature header value (if present) */
+    signature: string | null;
+    /** Raw request body for manual verification */
+    rawBody: ArrayBuffer;
+    /** Whether signature verification passed */
+    verified: boolean;
+    /** HTTP method used */
+    method: string;
+    /** URL path */
+    path: string;
+}
+/**
+ * Email event passed to email trigger handlers.
+ */
+interface EmailEvent {
+    /** Sender email address */
+    from: string;
+    /** Recipient email address */
+    to: string;
+    /** Email subject */
+    subject: string;
+    /** Raw email as a stream */
+    rawEmail: ReadableStream;
+    /** Parse the email body as text */
+    text(): Promise<string>;
+    /** Parse the email body as HTML */
+    html(): Promise<string | null>;
+}
+/**
+ * D1 change event passed to D1 trigger handlers.
+ */
+interface D1Event {
+    /** Type of database operation */
+    type: 'insert' | 'update' | 'delete';
+    /** Database name */
+    database: string;
+    /** Table name */
+    table: string;
+    /** Primary key values of the affected row */
+    primaryKey: Record<string, unknown>;
+    /** New values (for insert/update) */
+    newValues?: Record<string, unknown>;
+    /** Old values (for update/delete) */
+    oldValues?: Record<string, unknown>;
+}
+/**
+ * Tail event passed to tail trigger handlers.
+ */
+interface TailEvent {
+    /** Array of log entries */
+    logs: TailLogEntry[];
+    /** Worker that produced the logs */
+    worker: string;
+}
+/**
+ * Single log entry in a tail event.
+ */
+interface TailLogEntry {
+    /** Log level */
+    level: 'log' | 'debug' | 'info' | 'warn' | 'error';
+    /** Log message */
+    message: string;
+    /** Timestamp */
+    timestamp: Date;
+    /** Additional data */
+    data?: unknown;
+}
+/**
+ * Infer the event type from a trigger source.
+ *
+ * @example
+ * ```typescript
+ * type Event = InferEventType<{ type: 'scheduled'; cron: '0 0 * * *' }>
+ * // Event = ScheduledEvent
+ * ```
+ */
+type InferEventType<TSource extends TriggerSource> = TSource extends ScheduledTriggerSource ? ScheduledEvent : TSource extends QueueTriggerSource ? QueueBatchEvent : TSource extends R2TriggerSource ? R2Event : TSource extends WebhookTriggerSource ? WebhookEvent : TSource extends EmailTriggerSource ? EmailEvent : TSource extends D1TriggerSource ? D1Event : TSource extends TailTriggerSource ? TailEvent : never;
+/**
+ * Context passed to trigger handlers.
+ */
+interface TriggerContext {
+    /**
+     * Unique trace ID for this trigger execution.
+     * Propagated through trigger chains for observability.
+     */
+    traceId: string;
+    /**
+     * Extend the lifetime of the trigger execution.
+     * Use for background tasks that should complete after the handler returns.
+     */
+    waitUntil(promise: Promise<unknown>): void;
+    /**
+     * Allow the request to pass through on exception.
+     * Only applicable for certain trigger types.
+     */
+    passThroughOnException(): void;
+    /**
+     * Access to Cloudflare bindings (D1, KV, R2, etc.).
+     */
+    env: Record<string, unknown>;
+}
+/**
+ * Trigger handler function signature.
+ */
+type TriggerHandler<TEvent> = (event: TEvent, ctx: TriggerContext) => Awaitable<void>;
+/**
+ * Error handler function signature.
+ */
+type TriggerErrorHandler<TEvent> = (error: Error, event: TEvent, ctx: TriggerContext) => Awaitable<void>;
+/**
+ * Configuration for defining a trigger.
+ *
+ * @typeParam TSource - The trigger source type
+ *
+ * @example
+ * ```typescript
+ * // Scheduled trigger
+ * defineTrigger({
+ *   source: { type: 'scheduled', cron: '0 0 * * *' },
+ *   async handle(event, ctx) {
+ *     console.log(`Running at ${event.scheduledTime}`)
+ *   }
+ * })
+ *
+ * // R2 trigger
+ * defineTrigger({
+ *   source: { type: 'r2', bucket: 'uploads', events: ['object-create'] },
+ *   async handle(event, ctx) {
+ *     console.log(`New file: ${event.key}`)
+ *   }
+ * })
+ * ```
+ */
+interface TriggerConfig<TSource extends TriggerSource> {
+    /**
+     * Optional trigger name override.
+     * By default, derived from the filename.
+     */
+    name?: string;
+    /**
+     * The event source configuration.
+     */
+    source: TSource;
+    /**
+     * Retry configuration for failed executions.
+     */
+    retry?: RetryConfig;
+    /**
+     * Execution timeout in milliseconds.
+     * @default 30000 (30 seconds)
+     */
+    timeout?: number;
+    /**
+     * The trigger handler function.
+     */
+    handle: TriggerHandler<InferEventType<TSource>>;
+    /**
+     * Optional error handler for logging/reporting failures.
+     */
+    onError?: TriggerErrorHandler<InferEventType<TSource>>;
+}
+/**
+ * A defined trigger, returned by defineTrigger().
+ *
+ * @typeParam TSource - The trigger source type
+ */
+interface TriggerDefinition<TSource extends TriggerSource = TriggerSource> {
+    /** Internal marker identifying this as a trigger definition */
+    readonly __brand: 'cloudwerk-trigger';
+    /** Trigger name (derived from filename or explicitly set) */
+    readonly name: string | undefined;
+    /** The event source configuration */
+    readonly source: TSource;
+    /** Retry configuration */
+    readonly retry: RetryConfig;
+    /** Execution timeout in milliseconds */
+    readonly timeout: number;
+    /** The trigger handler function */
+    readonly handle: TriggerHandler<InferEventType<TSource>>;
+    /** Optional error handler */
+    readonly onError: TriggerErrorHandler<InferEventType<TSource>> | undefined;
+}
+/**
+ * A scanned trigger file from the app/triggers/ directory.
+ */
+interface ScannedTrigger {
+    /** Relative path from app/triggers/ (e.g., 'daily-cleanup.ts') */
+    relativePath: string;
+    /** Absolute filesystem path */
+    absolutePath: string;
+    /** File name without extension (e.g., 'daily-cleanup') */
+    name: string;
+    /** File extension (e.g., '.ts') */
+    extension: string;
+    /** If this is in a fan-out subdirectory, the group name */
+    fanOutGroup?: string;
+}
+/**
+ * Result of scanning the app/triggers/ directory.
+ */
+interface TriggerScanResult {
+    /** All discovered trigger files */
+    triggers: ScannedTrigger[];
+    /** Fan-out groups detected (directory name -> trigger names) */
+    fanOutGroups: Map<string, string[]>;
+}
+/**
+ * A compiled trigger entry in the manifest.
+ */
+interface TriggerEntry {
+    /** Trigger name derived from filename (e.g., 'dailyCleanup') */
+    name: string;
+    /** Binding name for wrangler.toml (e.g., 'DAILY_CLEANUP_TRIGGER') */
+    bindingName: string;
+    /** Relative path to the trigger definition file */
+    filePath: string;
+    /** Absolute path to the trigger definition file */
+    absolutePath: string;
+    /** Trigger source configuration */
+    source: TriggerSource;
+    /** Whether onError handler is defined */
+    hasOnError: boolean;
+    /** Retry configuration */
+    retry?: RetryConfig;
+    /** Execution timeout */
+    timeout?: number;
+    /** Fan-out group name (if part of a fan-out) */
+    fanOutGroup?: string;
+}
+/**
+ * Error codes for trigger validation.
+ */
+type TriggerErrorCode = 'NO_HANDLER' | 'INVALID_SOURCE' | 'DUPLICATE_NAME' | 'INVALID_CRON' | 'INVALID_WEBHOOK_PATH' | 'INVALID_CONFIG' | 'INVALID_NAME' | 'MISSING_SOURCE';
+/**
+ * Warning codes for trigger validation.
+ */
+type TriggerWarningCode = 'NO_ERROR_HANDLER' | 'DUPLICATE_CRON' | 'SHORT_TIMEOUT' | 'MISSING_RETRY' | 'WEBHOOK_NO_VERIFY';
+/**
+ * Validation error for a trigger definition.
+ */
+interface TriggerValidationError {
+    /** Trigger file path */
+    file: string;
+    /** Error message */
+    message: string;
+    /** Error code for programmatic handling */
+    code: TriggerErrorCode;
+}
+/**
+ * Validation warning for a trigger definition.
+ */
+interface TriggerValidationWarning {
+    /** Trigger file path */
+    file: string;
+    /** Warning message */
+    message: string;
+    /** Warning code */
+    code: TriggerWarningCode;
+}
+/**
+ * Complete trigger manifest generated during build.
+ */
+interface TriggerManifest {
+    /** All compiled trigger entries */
+    triggers: TriggerEntry[];
+    /** Scheduled triggers grouped by cron expression */
+    scheduled: Map<string, TriggerEntry[]>;
+    /** Queue triggers grouped by queue name */
+    queues: Map<string, TriggerEntry[]>;
+    /** R2 triggers grouped by bucket name */
+    r2: Map<string, TriggerEntry[]>;
+    /** Webhook triggers mapped by path */
+    webhooks: Map<string, TriggerEntry>;
+    /** Email triggers mapped by address pattern */
+    emails: Map<string, TriggerEntry>;
+    /** Validation errors (trigger won't be registered) */
+    errors: TriggerValidationError[];
+    /** Validation warnings (trigger will be registered with warning) */
+    warnings: TriggerValidationWarning[];
+    /** When the manifest was generated */
+    generatedAt: Date;
+    /** Root directory of the app */
+    rootDir: string;
+}
+
+export type { Awaitable as A, BatchConfig as B, WebhookTriggerSource as C, D1Event as D, EmailEvent as E, WebhookVerificationResult as F, InferEventType as I, QueueBatchEvent as Q, R2Event as R, ScannedTrigger as S, TriggerSource as T, WebhookVerifier as W, TriggerConfig as a, TriggerDefinition as b, TriggerContext as c, D1EventType as d, D1TriggerSource as e, EmailTriggerSource as f, QueueMessage as g, QueueTriggerSource as h, R2EventType as i, R2TriggerSource as j, RetryConfig as k, ScheduledEvent as l, ScheduledTriggerSource as m, TailEvent as n, TailLogEntry as o, TailTriggerSource as p, TriggerEntry as q, TriggerErrorCode as r, TriggerErrorHandler as s, TriggerHandler as t, TriggerManifest as u, TriggerScanResult as v, TriggerValidationError as w, TriggerValidationWarning as x, TriggerWarningCode as y, WebhookEvent as z };

package/package.json

@@ -0,0 +1,40 @@
+{
+  "name": "@cloudwerk/trigger",
+  "version": "0.0.1",
+  "description": "Event-driven triggers for Cloudwerk (scheduled, queue, R2, webhooks)",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/squirrelsoft-dev/cloudwerk.git",
+    "directory": "packages/trigger"
+  },
+  "type": "module",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    },
+    "./testing": {
+      "types": "./dist/testing.d.ts",
+      "import": "./dist/testing.js"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "dependencies": {
+    "@cloudwerk/core": "0.12.0"
+  },
+  "devDependencies": {
+    "typescript": "^5.4.0",
+    "vitest": "^1.0.0",
+    "tsup": "^8.0.0"
+  },
+  "peerDependencies": {
+    "typescript": "^5.0.0"
+  },
+  "scripts": {
+    "build": "tsup",
+    "test": "vitest --run",
+    "test:watch": "vitest"
+  }
+}