@cloudwerk/trigger 0.0.1

package/dist/index.d.ts

@@ -0,0 +1,966 @@
+import { T as TriggerSource, a as TriggerConfig, b as TriggerDefinition, W as WebhookVerifier, c as TriggerContext } from './types-w3ZeMXZ9.js';
+export { A as Awaitable, B as BatchConfig, D as D1Event, d as D1EventType, e as D1TriggerSource, E as EmailEvent, f as EmailTriggerSource, I as InferEventType, Q as QueueBatchEvent, g as QueueMessage, h as QueueTriggerSource, R as R2Event, i as R2EventType, j as R2TriggerSource, k as RetryConfig, S as ScannedTrigger, l as ScheduledEvent, m as ScheduledTriggerSource, n as TailEvent, o as TailLogEntry, p as TailTriggerSource, q as TriggerEntry, r as TriggerErrorCode, s as TriggerErrorHandler, t as TriggerHandler, u as TriggerManifest, v as TriggerScanResult, w as TriggerValidationError, x as TriggerValidationWarning, y as TriggerWarningCode, z as WebhookEvent, C as WebhookTriggerSource, F as WebhookVerificationResult } from './types-w3ZeMXZ9.js';
+
+/**
+ * @cloudwerk/trigger - Error Classes
+ *
+ * Custom error classes for trigger processing.
+ */
+/**
+ * Base error class for trigger-related errors.
+ */
+declare class TriggerError extends Error {
+    /** Error code for programmatic handling */
+    readonly code: string;
+    constructor(code: string, message: string, options?: ErrorOptions);
+}
+/**
+ * Error thrown when trigger configuration is invalid.
+ *
+ * @example
+ * ```typescript
+ * throw new TriggerConfigError('timeout must be a positive number', 'timeout')
+ * ```
+ */
+declare class TriggerConfigError extends TriggerError {
+    /** The configuration field that is invalid */
+    readonly field?: string;
+    constructor(message: string, field?: string);
+}
+/**
+ * Error thrown when no handler function is defined.
+ */
+declare class TriggerNoHandlerError extends TriggerError {
+    constructor(triggerName: string);
+}
+/**
+ * Error thrown when the trigger source configuration is invalid.
+ */
+declare class TriggerInvalidSourceError extends TriggerError {
+    /** The source type that is invalid */
+    readonly sourceType?: string;
+    constructor(message: string, sourceType?: string);
+}
+/**
+ * Error thrown when a cron expression is invalid.
+ */
+declare class TriggerInvalidCronError extends TriggerError {
+    /** The invalid cron expression */
+    readonly cron: string;
+    constructor(cron: string, reason?: string);
+}
+/**
+ * Error thrown when a webhook path is invalid.
+ */
+declare class TriggerInvalidWebhookPathError extends TriggerError {
+    /** The invalid path */
+    readonly path: string;
+    constructor(path: string, reason?: string);
+}
+/**
+ * Error thrown when accessing a trigger outside of execution context.
+ */
+declare class TriggerContextError extends TriggerError {
+    constructor();
+}
+/**
+ * Error thrown when a trigger binding is not found.
+ */
+declare class TriggerNotFoundError extends TriggerError {
+    /** The trigger name that was not found */
+    readonly triggerName: string;
+    /** Available trigger names */
+    readonly availableTriggers: string[];
+    constructor(triggerName: string, availableTriggers: string[]);
+}
+/**
+ * Error thrown when trigger processing fails.
+ */
+declare class TriggerProcessingError extends TriggerError {
+    /** The trigger name that failed */
+    readonly triggerName: string;
+    /** Number of execution attempts */
+    readonly attempts: number;
+    /** The event that was being processed (if available) */
+    readonly event?: unknown;
+    constructor(message: string, triggerName: string, attempts: number, options?: ErrorOptions & {
+        event?: unknown;
+    });
+}
+/**
+ * Error thrown when a trigger execution times out.
+ */
+declare class TriggerTimeoutError extends TriggerError {
+    /** The trigger name that timed out */
+    readonly triggerName: string;
+    /** Configured timeout in milliseconds */
+    readonly timeoutMs: number;
+    constructor(triggerName: string, timeoutMs: number);
+}
+/**
+ * Error thrown when max retries are exceeded.
+ */
+declare class TriggerMaxRetriesError extends TriggerError {
+    /** The trigger name that exceeded retries */
+    readonly triggerName: string;
+    /** Maximum retries configured */
+    readonly maxRetries: number;
+    /** The original error that caused the failure */
+    readonly originalError?: Error;
+    constructor(triggerName: string, maxRetries: number, originalError?: Error);
+}
+/**
+ * Error thrown when webhook signature verification fails.
+ */
+declare class TriggerWebhookVerificationError extends TriggerError {
+    /** The trigger name */
+    readonly triggerName: string;
+    /** The verification error message */
+    readonly verificationError?: string;
+    constructor(triggerName: string, verificationError?: string);
+}
+
+/**
+ * @cloudwerk/trigger - defineTrigger()
+ *
+ * Factory function for creating trigger definitions.
+ */
+
+/**
+ * Parse a duration string into seconds.
+ *
+ * Supports formats like:
+ * - '30s' - 30 seconds
+ * - '5m' - 5 minutes
+ * - '1h' - 1 hour
+ * - 60 - number of seconds
+ *
+ * @param duration - Duration string or number
+ * @returns Duration in seconds
+ */
+declare function parseDuration(duration: string | number): number;
+/**
+ * Define a trigger consumer.
+ *
+ * This function creates a trigger definition that will be automatically
+ * discovered and registered by Cloudwerk during build.
+ *
+ * @typeParam TSource - The trigger source type
+ * @param config - Trigger configuration
+ * @returns Trigger definition
+ *
+ * @example
+ * ```typescript
+ * // app/triggers/daily-cleanup.ts
+ * import { defineTrigger } from '@cloudwerk/trigger'
+ *
+ * export default defineTrigger({
+ *   source: { type: 'scheduled', cron: '0 0 * * *' },
+ *   async handle(event, ctx) {
+ *     console.log(`[${ctx.traceId}] Running cleanup at ${event.scheduledTime}`)
+ *     await cleanupOldRecords()
+ *   }
+ * })
+ * ```
+ *
+ * @example
+ * ```typescript
+ * // app/triggers/process-uploads.ts
+ * import { defineTrigger } from '@cloudwerk/trigger'
+ *
+ * export default defineTrigger({
+ *   source: {
+ *     type: 'r2',
+ *     bucket: 'uploads',
+ *     events: ['object-create'],
+ *     prefix: 'images/',
+ *   },
+ *   retry: { maxAttempts: 5, delay: '30s' },
+ *   async handle(event, ctx) {
+ *     console.log(`New file: ${event.key}`)
+ *     await processImage(event.key)
+ *   },
+ *   async onError(error, event, ctx) {
+ *     await reportError(error, { key: event.key, traceId: ctx.traceId })
+ *   }
+ * })
+ * ```
+ *
+ * @example
+ * ```typescript
+ * // app/triggers/stripe-webhook.ts
+ * import { defineTrigger, verifiers } from '@cloudwerk/trigger'
+ *
+ * export default defineTrigger({
+ *   source: {
+ *     type: 'webhook',
+ *     path: '/webhooks/stripe',
+ *     verify: verifiers.stripe(STRIPE_WEBHOOK_SECRET),
+ *   },
+ *   async handle(event, ctx) {
+ *     switch (event.payload.type) {
+ *       case 'checkout.session.completed':
+ *         await handleCheckoutComplete(event.payload)
+ *         break
+ *     }
+ *   }
+ * })
+ * ```
+ */
+declare function defineTrigger<TSource extends TriggerSource>(config: TriggerConfig<TSource>): TriggerDefinition<TSource>;
+/**
+ * Check if a value is a trigger definition created by defineTrigger().
+ *
+ * @param value - Value to check
+ * @returns true if value is a TriggerDefinition
+ */
+declare function isTriggerDefinition(value: unknown): value is TriggerDefinition;
+/**
+ * Get the source type from a trigger definition.
+ *
+ * @param definition - Trigger definition
+ * @returns The source type string
+ */
+declare function getTriggerSourceType(definition: TriggerDefinition): TriggerSource['type'];
+
+/**
+ * Custom webhook signature verifier factory.
+ *
+ * Create verifiers for any webhook provider using common patterns.
+ */
+
+/**
+ * Signature encoding format.
+ */
+type SignatureEncoding = 'hex' | 'base64';
+/**
+ * Hash algorithm for HMAC computation.
+ */
+type HashAlgorithm = 'SHA-256' | 'SHA-1' | 'SHA-512';
+interface CustomVerifierOptions {
+    /**
+     * Name of the header containing the signature.
+     * @example 'x-webhook-signature'
+     */
+    header: string;
+    /**
+     * Hash algorithm to use.
+     * @default 'SHA-256'
+     */
+    algorithm?: HashAlgorithm;
+    /**
+     * Encoding of the signature in the header.
+     * @default 'hex'
+     */
+    encoding?: SignatureEncoding;
+    /**
+     * Prefix before the signature (e.g., 'sha256=').
+     * Will be stripped before comparison.
+     */
+    prefix?: string;
+    /**
+     * Optional timestamp header for replay attack prevention.
+     */
+    timestampHeader?: string;
+    /**
+     * Tolerance for timestamp validation in seconds.
+     * Only used if timestampHeader is set.
+     * @default 300
+     */
+    timestampTolerance?: number;
+    /**
+     * Function to build the signature base string.
+     * By default, just uses the raw body.
+     *
+     * @param body - Raw request body as string
+     * @param timestamp - Timestamp value if timestampHeader is set
+     * @returns String to compute signature over
+     */
+    buildSignatureBase?: (body: string, timestamp?: string) => string;
+}
+/**
+ * Create a custom webhook signature verifier.
+ *
+ * @param secret - Webhook signing secret
+ * @param options - Verifier configuration
+ * @returns WebhookVerifier function
+ *
+ * @example
+ * ```typescript
+ * // Simple HMAC-SHA256 with hex encoding
+ * verifiers.custom(secret, {
+ *   header: 'x-webhook-signature',
+ *   algorithm: 'SHA-256',
+ *   encoding: 'hex',
+ * })
+ *
+ * // With timestamp validation (like Stripe)
+ * verifiers.custom(secret, {
+ *   header: 'x-signature',
+ *   timestampHeader: 'x-timestamp',
+ *   timestampTolerance: 300,
+ *   buildSignatureBase: (body, timestamp) => `${timestamp}.${body}`,
+ * })
+ *
+ * // With prefix (like GitHub)
+ * verifiers.custom(secret, {
+ *   header: 'x-hub-signature-256',
+ *   prefix: 'sha256=',
+ * })
+ * ```
+ */
+declare function customVerifier(secret: string, options: CustomVerifierOptions): WebhookVerifier;
+/**
+ * Alias for customVerifier.
+ */
+declare const custom: typeof customVerifier;
+
+/**
+ * Linear webhook signature verifier.
+ *
+ * @see https://developers.linear.app/docs/graphql/webhooks#webhook-security
+ */
+
+/**
+ * Create a Linear webhook signature verifier.
+ *
+ * @param secret - Linear webhook signing secret
+ * @returns WebhookVerifier function
+ *
+ * @example
+ * ```typescript
+ * import { defineTrigger, verifiers } from '@cloudwerk/trigger'
+ *
+ * export default defineTrigger({
+ *   source: {
+ *     type: 'webhook',
+ *     path: '/webhooks/linear',
+ *     verify: verifiers.linear(process.env.LINEAR_WEBHOOK_SECRET),
+ *   },
+ *   async handle(event) {
+ *     const { action, type, data } = event.payload
+ *     switch (type) {
+ *       case 'Issue':
+ *         if (action === 'create') {
+ *           // Handle new issue
+ *         }
+ *         break
+ *     }
+ *   }
+ * })
+ * ```
+ */
+declare function linearVerifier(secret: string): WebhookVerifier;
+/**
+ * Alias for linearVerifier.
+ */
+declare const linear: typeof linearVerifier;
+
+/**
+ * Shopify webhook signature verifier.
+ *
+ * @see https://shopify.dev/docs/apps/webhooks/configuration/https#step-5-verify-the-webhook
+ */
+
+/**
+ * Create a Shopify webhook signature verifier.
+ *
+ * @param secret - Shopify webhook signing secret (from Partner Dashboard)
+ * @returns WebhookVerifier function
+ *
+ * @example
+ * ```typescript
+ * import { defineTrigger, verifiers } from '@cloudwerk/trigger'
+ *
+ * export default defineTrigger({
+ *   source: {
+ *     type: 'webhook',
+ *     path: '/webhooks/shopify',
+ *     verify: verifiers.shopify(process.env.SHOPIFY_WEBHOOK_SECRET),
+ *   },
+ *   async handle(event) {
+ *     const topic = event.headers.get('x-shopify-topic')
+ *     switch (topic) {
+ *       case 'orders/create':
+ *         // Handle new order
+ *         break
+ *       case 'products/update':
+ *         // Handle product update
+ *         break
+ *     }
+ *   }
+ * })
+ * ```
+ */
+declare function shopifyVerifier(secret: string): WebhookVerifier;
+/**
+ * Alias for shopifyVerifier.
+ */
+declare const shopify: typeof shopifyVerifier;
+
+/**
+ * Twilio webhook signature verifier.
+ *
+ * @see https://www.twilio.com/docs/usage/security#validating-requests
+ */
+
+interface TwilioVerifierOptions {
+    /**
+     * The full URL of your webhook endpoint.
+     * Required for signature validation.
+     */
+    url: string;
+}
+/**
+ * Create a Twilio webhook signature verifier.
+ *
+ * @param authToken - Twilio Auth Token
+ * @param options - Verifier options including the webhook URL
+ * @returns WebhookVerifier function
+ *
+ * @example
+ * ```typescript
+ * import { defineTrigger, verifiers } from '@cloudwerk/trigger'
+ *
+ * export default defineTrigger({
+ *   source: {
+ *     type: 'webhook',
+ *     path: '/webhooks/twilio',
+ *     verify: verifiers.twilio(process.env.TWILIO_AUTH_TOKEN, {
+ *       url: 'https://your-app.com/webhooks/twilio',
+ *     }),
+ *   },
+ *   async handle(event) {
+ *     const { From, Body } = event.payload
+ *     // Handle SMS or voice webhook
+ *   }
+ * })
+ * ```
+ */
+declare function twilioVerifier(authToken: string, options: TwilioVerifierOptions): WebhookVerifier;
+/**
+ * Alias for twilioVerifier.
+ */
+declare const twilio: typeof twilioVerifier;
+
+/**
+ * Slack webhook signature verifier.
+ *
+ * @see https://api.slack.com/authentication/verifying-requests-from-slack
+ */
+
+interface SlackVerifierOptions {
+    /**
+     * Tolerance for timestamp validation in seconds.
+     * @default 300 (5 minutes)
+     */
+    tolerance?: number;
+}
+/**
+ * Create a Slack webhook signature verifier.
+ *
+ * @param signingSecret - Slack signing secret
+ * @param options - Verifier options
+ * @returns WebhookVerifier function
+ *
+ * @example
+ * ```typescript
+ * import { defineTrigger, verifiers } from '@cloudwerk/trigger'
+ *
+ * export default defineTrigger({
+ *   source: {
+ *     type: 'webhook',
+ *     path: '/webhooks/slack',
+ *     verify: verifiers.slack(process.env.SLACK_SIGNING_SECRET),
+ *   },
+ *   async handle(event) {
+ *     const payload = event.payload
+ *     // Handle Slack event
+ *   }
+ * })
+ * ```
+ */
+declare function slackVerifier(signingSecret: string, options?: SlackVerifierOptions): WebhookVerifier;
+/**
+ * Alias for slackVerifier.
+ */
+declare const slack: typeof slackVerifier;
+
+/**
+ * GitHub webhook signature verifier.
+ *
+ * @see https://docs.github.com/en/webhooks/using-webhooks/validating-webhook-deliveries
+ */
+
+/**
+ * Create a GitHub webhook signature verifier.
+ *
+ * @param secret - GitHub webhook secret
+ * @returns WebhookVerifier function
+ *
+ * @example
+ * ```typescript
+ * import { defineTrigger, verifiers } from '@cloudwerk/trigger'
+ *
+ * export default defineTrigger({
+ *   source: {
+ *     type: 'webhook',
+ *     path: '/webhooks/github',
+ *     verify: verifiers.github(process.env.GITHUB_WEBHOOK_SECRET),
+ *   },
+ *   async handle(event) {
+ *     const githubEvent = event.headers.get('x-github-event')
+ *     switch (githubEvent) {
+ *       case 'push':
+ *         // Handle push event
+ *         break
+ *       case 'pull_request':
+ *         // Handle PR event
+ *         break
+ *     }
+ *   }
+ * })
+ * ```
+ */
+declare function githubVerifier(secret: string): WebhookVerifier;
+/**
+ * Alias for githubVerifier.
+ */
+declare const github: typeof githubVerifier;
+
+/**
+ * Stripe webhook signature verifier.
+ *
+ * @see https://stripe.com/docs/webhooks/signatures
+ */
+
+interface StripeVerifierOptions {
+    /**
+     * Tolerance for timestamp validation in seconds.
+     * @default 300 (5 minutes)
+     */
+    tolerance?: number;
+}
+/**
+ * Create a Stripe webhook signature verifier.
+ *
+ * @param secret - Stripe webhook signing secret (whsec_...)
+ * @param options - Verifier options
+ * @returns WebhookVerifier function
+ *
+ * @example
+ * ```typescript
+ * import { defineTrigger, verifiers } from '@cloudwerk/trigger'
+ *
+ * export default defineTrigger({
+ *   source: {
+ *     type: 'webhook',
+ *     path: '/webhooks/stripe',
+ *     verify: verifiers.stripe(process.env.STRIPE_WEBHOOK_SECRET),
+ *   },
+ *   async handle(event) {
+ *     const stripeEvent = event.payload
+ *     switch (stripeEvent.type) {
+ *       case 'checkout.session.completed':
+ *         // Handle checkout completion
+ *         break
+ *     }
+ *   }
+ * })
+ * ```
+ */
+declare function stripeVerifier(secret: string, options?: StripeVerifierOptions): WebhookVerifier;
+/**
+ * Alias for stripeVerifier.
+ */
+declare const stripe: typeof stripeVerifier;
+
+/**
+ * Collection of all built-in webhook verifiers.
+ *
+ * @example
+ * ```typescript
+ * import { defineTrigger, verifiers } from '@cloudwerk/trigger'
+ *
+ * export default defineTrigger({
+ *   source: {
+ *     type: 'webhook',
+ *     path: '/webhooks/stripe',
+ *     verify: verifiers.stripe(STRIPE_WEBHOOK_SECRET),
+ *   },
+ *   async handle(event) {
+ *     // Handle verified webhook
+ *   }
+ * })
+ * ```
+ */
+declare const verifiers: {
+    readonly stripe: typeof stripeVerifier;
+    readonly github: typeof githubVerifier;
+    readonly slack: typeof slackVerifier;
+    readonly twilio: typeof twilioVerifier;
+    readonly shopify: typeof shopifyVerifier;
+    readonly linear: typeof linearVerifier;
+    readonly custom: typeof customVerifier;
+};
+
+/**
+ * @cloudwerk/trigger - Trigger Chaining via emit()
+ *
+ * Allows triggers to invoke other triggers with automatic
+ * trace ID propagation for observability.
+ */
+
+/**
+ * Options for emitting to a trigger.
+ */
+interface EmitOptions {
+    /**
+     * Delay before the trigger executes (in milliseconds).
+     * @default 0
+     */
+    delay?: number;
+    /**
+     * Custom trace ID (defaults to current context's traceId).
+     */
+    traceId?: string;
+}
+/**
+ * Result of an emit operation.
+ */
+interface EmitResult {
+    /** Whether the emit was successful */
+    success: boolean;
+    /** The trace ID used for this emission */
+    traceId: string;
+    /** Target trigger name */
+    trigger: string;
+    /** Timestamp when emit was called */
+    emittedAt: Date;
+}
+/**
+ * Pending emission that was queued during execution.
+ */
+interface PendingEmission {
+    trigger: string;
+    payload: unknown;
+    options: EmitOptions;
+    traceId: string;
+    emittedAt: Date;
+}
+/**
+ * Emitter interface for different execution modes.
+ */
+interface TriggerEmitter {
+    /**
+     * Emit to a trigger.
+     */
+    emit(trigger: string, payload: unknown, options?: EmitOptions): Promise<EmitResult>;
+    /**
+     * Get all pending emissions (for testing/debugging).
+     */
+    getPendingEmissions(): PendingEmission[];
+    /**
+     * Clear pending emissions.
+     */
+    clearPendingEmissions(): void;
+}
+/**
+ * Run a function within a trigger context.
+ *
+ * @param context - Trigger context
+ * @param fn - Function to execute
+ * @returns Function result
+ */
+declare function runWithTriggerContext<T>(context: TriggerContext, fn: () => T): T;
+/**
+ * Get the current trigger context.
+ *
+ * @returns Current context or undefined if not in a trigger
+ */
+declare function getTriggerContext(): TriggerContext | undefined;
+/**
+ * Get pending emissions from the current context.
+ */
+declare function getPendingEmissions(): PendingEmission[];
+/**
+ * Generate a new trace ID.
+ *
+ * @param prefix - Optional prefix (default: 'tr')
+ * @returns Trace ID string
+ */
+declare function generateTraceId(prefix?: string): string;
+/**
+ * Create a child trace ID from a parent.
+ *
+ * @param parentTraceId - Parent trace ID
+ * @returns Child trace ID
+ */
+declare function createChildTraceId(parentTraceId: string): string;
+/**
+ * Emit an event to another trigger.
+ *
+ * This function queues an event to be processed by another trigger,
+ * with automatic trace ID propagation for distributed tracing.
+ *
+ * @param trigger - Name of the trigger to invoke
+ * @param payload - Data to pass to the trigger
+ * @param options - Emit options
+ * @returns EmitResult
+ *
+ * @example
+ * ```typescript
+ * import { defineTrigger, emit } from '@cloudwerk/trigger'
+ *
+ * export default defineTrigger({
+ *   source: { type: 'r2', bucket: 'uploads', events: ['object-create'] },
+ *   async handle(event, ctx) {
+ *     // Process the upload
+ *     const metadata = await processFile(event.key)
+ *
+ *     // Chain to other triggers
+ *     await emit('index-for-search', { key: event.key, metadata })
+ *     await emit('generate-thumbnail', { key: event.key })
+ *
+ *     // Trace ID is automatically propagated
+ *     console.log(ctx.traceId) // Same traceId in chained triggers
+ *   }
+ * })
+ * ```
+ *
+ * @example
+ * ```typescript
+ * // With delay
+ * await emit('send-reminder', { userId }, { delay: 60000 }) // 1 minute delay
+ * ```
+ */
+declare function emit(trigger: string, payload: unknown, options?: EmitOptions): Promise<EmitResult>;
+/**
+ * Emit to multiple triggers in parallel.
+ *
+ * @param emissions - Array of [trigger, payload] pairs
+ * @param options - Shared options for all emissions
+ * @returns Array of EmitResults
+ *
+ * @example
+ * ```typescript
+ * const results = await emitMany([
+ *   ['process-image', { key: 'image.jpg' }],
+ *   ['update-index', { key: 'image.jpg' }],
+ *   ['notify-user', { userId, message: 'Upload complete' }],
+ * ])
+ * ```
+ */
+declare function emitMany(emissions: [string, unknown][], options?: EmitOptions): Promise<EmitResult[]>;
+/**
+ * Default trigger emitter implementation.
+ *
+ * In production, this would be replaced with an implementation
+ * that actually dispatches to other triggers via queues or
+ * direct function calls.
+ */
+declare const defaultEmitter: TriggerEmitter;
+
+/**
+ * @cloudwerk/trigger - Observability & Metrics
+ *
+ * Utilities for tracing, metrics collection, and monitoring trigger executions.
+ */
+
+/**
+ * Trigger execution metrics.
+ */
+interface TriggerMetrics {
+    /** Trigger name */
+    name: string;
+    /** Trigger source type */
+    sourceType: TriggerSource['type'];
+    /** Execution start timestamp */
+    startedAt: Date;
+    /** Execution end timestamp */
+    endedAt?: Date;
+    /** Duration in milliseconds */
+    durationMs?: number;
+    /** Whether execution was successful */
+    success: boolean;
+    /** Error if execution failed */
+    error?: Error;
+    /** Number of retries */
+    retryCount: number;
+    /** Trace ID for distributed tracing */
+    traceId: string;
+}
+/**
+ * Trigger execution span for tracing.
+ */
+interface TriggerSpan {
+    /** Span ID */
+    spanId: string;
+    /** Trace ID */
+    traceId: string;
+    /** Parent span ID (for nested triggers) */
+    parentSpanId?: string;
+    /** Trigger name */
+    triggerName: string;
+    /** Source type */
+    sourceType: TriggerSource['type'];
+    /** Operation name */
+    operationName: string;
+    /** Start time (Unix timestamp ms) */
+    startTime: number;
+    /** End time (Unix timestamp ms) */
+    endTime?: number;
+    /** Span status */
+    status: 'ok' | 'error' | 'unset';
+    /** Attributes */
+    attributes: Record<string, string | number | boolean>;
+    /** Events that occurred during the span */
+    events: SpanEvent[];
+}
+/**
+ * Event that occurred during a span.
+ */
+interface SpanEvent {
+    /** Event name */
+    name: string;
+    /** Timestamp (Unix ms) */
+    timestamp: number;
+    /** Event attributes */
+    attributes?: Record<string, string | number | boolean>;
+}
+/**
+ * Metrics reporter interface for pluggable metrics backends.
+ */
+interface MetricsReporter {
+    /** Report execution metrics */
+    reportExecution(metrics: TriggerMetrics): void;
+    /** Report a span */
+    reportSpan(span: TriggerSpan): void;
+    /** Flush pending metrics */
+    flush(): Promise<void>;
+}
+/**
+ * Generate a span ID.
+ */
+declare function generateSpanId(): string;
+/**
+ * Create a new trigger span.
+ */
+declare function createTriggerSpan(triggerName: string, sourceType: TriggerSource['type'], traceId: string, parentSpanId?: string): TriggerSpan;
+/**
+ * End a trigger span.
+ */
+declare function endTriggerSpan(span: TriggerSpan, success: boolean, error?: Error): TriggerSpan;
+/**
+ * Add an event to a span.
+ */
+declare function addSpanEvent(span: TriggerSpan, name: string, attributes?: Record<string, string | number | boolean>): void;
+/**
+ * Add attributes to a span.
+ */
+declare function setSpanAttributes(span: TriggerSpan, attributes: Record<string, string | number | boolean>): void;
+/**
+ * Timer for measuring trigger execution duration.
+ */
+declare class ExecutionTimer {
+    private startTime;
+    private endTime?;
+    private marks;
+    constructor();
+    /**
+     * Mark a point in time.
+     */
+    mark(name: string): void;
+    /**
+     * Get time since start to a mark.
+     */
+    getMarkDuration(name: string): number | undefined;
+    /**
+     * Stop the timer.
+     */
+    stop(): number;
+    /**
+     * Get total duration in milliseconds.
+     */
+    get duration(): number;
+    /**
+     * Get all marks with their durations.
+     */
+    getMarks(): Record<string, number>;
+}
+/**
+ * Console-based metrics reporter for development.
+ */
+declare class ConsoleMetricsReporter implements MetricsReporter {
+    private prefix;
+    constructor(prefix?: string);
+    reportExecution(metrics: TriggerMetrics): void;
+    reportSpan(span: TriggerSpan): void;
+    flush(): Promise<void>;
+}
+/**
+ * No-op metrics reporter that discards all metrics.
+ */
+declare class NoOpMetricsReporter implements MetricsReporter {
+    reportExecution(_metrics: TriggerMetrics): void;
+    reportSpan(_span: TriggerSpan): void;
+    flush(): Promise<void>;
+}
+/**
+ * Collect and aggregate trigger metrics.
+ */
+declare class MetricsCollector {
+    private executions;
+    private spans;
+    private reporter;
+    constructor(reporter?: MetricsReporter);
+    /**
+     * Record a trigger execution.
+     */
+    recordExecution(metrics: TriggerMetrics): void;
+    /**
+     * Record a span.
+     */
+    recordSpan(span: TriggerSpan): void;
+    /**
+     * Get execution count for a trigger.
+     */
+    getExecutionCount(triggerName: string): number;
+    /**
+     * Get success rate for a trigger.
+     */
+    getSuccessRate(triggerName: string): number;
+    /**
+     * Get average duration for a trigger.
+     */
+    getAverageDuration(triggerName: string): number | undefined;
+    /**
+     * Get percentile duration for a trigger.
+     */
+    getPercentileDuration(triggerName: string, percentile: number): number | undefined;
+    /**
+     * Get summary statistics for a trigger.
+     */
+    getSummary(triggerName: string): {
+        count: number;
+        successRate: number;
+        avgDurationMs?: number;
+        p50DurationMs?: number;
+        p95DurationMs?: number;
+        p99DurationMs?: number;
+    };
+    /**
+     * Flush metrics to the reporter.
+     */
+    flush(): Promise<void>;
+    /**
+     * Clear collected metrics.
+     */
+    clear(): void;
+}
+/**
+ * Create trigger metrics from an execution.
+ */
+declare function createTriggerMetrics(name: string, sourceType: TriggerSource['type'], ctx: TriggerContext, timer: ExecutionTimer, success: boolean, error?: Error, retryCount?: number): TriggerMetrics;
+
+export { ConsoleMetricsReporter, type CustomVerifierOptions, type EmitOptions, type EmitResult, ExecutionTimer, type HashAlgorithm, MetricsCollector, type MetricsReporter, NoOpMetricsReporter, type PendingEmission, type SignatureEncoding, type SlackVerifierOptions, type SpanEvent, type StripeVerifierOptions, TriggerConfig, TriggerConfigError, TriggerContext, TriggerContextError, TriggerDefinition, type TriggerEmitter, TriggerError, TriggerInvalidCronError, TriggerInvalidSourceError, TriggerInvalidWebhookPathError, TriggerMaxRetriesError, type TriggerMetrics, TriggerNoHandlerError, TriggerNotFoundError, TriggerProcessingError, TriggerSource, type TriggerSpan, TriggerTimeoutError, TriggerWebhookVerificationError, type TwilioVerifierOptions, WebhookVerifier, addSpanEvent, createChildTraceId, createTriggerMetrics, createTriggerSpan, custom, customVerifier, defaultEmitter, defineTrigger, emit, emitMany, endTriggerSpan, generateSpanId, generateTraceId, getPendingEmissions, getTriggerContext, getTriggerSourceType, github, githubVerifier, isTriggerDefinition, linear, linearVerifier, parseDuration, runWithTriggerContext, setSpanAttributes, shopify, shopifyVerifier, slack, slackVerifier, stripe, stripeVerifier, twilio, twilioVerifier, verifiers };