@blokjs/trigger-webhook 0.2.1 → 0.6.2

package/dist/WebhookTrigger.d.ts

@@ -1,129 +1,112 @@
 /**
- * WebhookTrigger - Handle webhook events from external services
+ * WebhookTrigger — v0.7 PR 4 — Inbound webhook trigger that mounts
+ * verified POST routes on the shared Hono app. One route per workflow
+ * whose `trigger.webhook` config is registered.
  *
- * Extends TriggerBase to process webhook events from:
- * - GitHub (push, pull_request, issues, etc.)
- * - Stripe (payment_intent, checkout.session, etc.)
- * - Shopify (orders, products, customers)
- * - Custom webhooks
+ * **Authoring surface (built-in provider):**
  *
- * Features:
- * - Signature verification for security
- * - Event type filtering
- * - Retry support
- * - Dead letter handling
- */
-import type { HelperResponse, WebhookTriggerOpts } from "@blok/helper";
-import { DefaultLogger, type GlobalOptions, type BlokService, TriggerBase, type TriggerResponse } from "@blok/runner";
-/**
- * Webhook event structure
- */
-export interface WebhookEvent {
-    /** Unique event ID */
-    id: string;
-    /** Source service (github, stripe, shopify, custom) */
-    source: string;
-    /** Event type (e.g., push, payment_intent.succeeded) */
-    eventType: string;
-    /** Event payload */
-    payload: unknown;
-    /** Request headers */
-    headers: Record<string, string>;
-    /** Signature (if provided) */
-    signature?: string;
-    /** Timestamp */
-    timestamp: Date;
-    /** Raw request body */
-    rawBody: string;
-}
-/**
- * Signature verification result
- */
-export interface VerificationResult {
-    valid: boolean;
-    error?: string;
-}
-/**
- * Webhook source handlers
- */
-export interface WebhookSourceHandler {
-    /** Extract event type from request */
-    getEventType(headers: Record<string, string>, body: unknown): string;
-    /** Get signature from request */
-    getSignature(headers: Record<string, string>): string | undefined;
-    /** Verify signature */
-    verifySignature(rawBody: string, signature: string, secret: string): VerificationResult;
-    /** Get event ID */
-    getEventId(headers: Record<string, string>, body: unknown): string;
-}
-/**
- * Workflow model with webhook trigger configuration
+ * ```json
+ * {
+ *   "name": "stripe-events",
+ *   "trigger": {
+ *     "webhook": {
+ *       "provider": "stripe",
+ *       "path": "/webhooks/stripe",
+ *       "secretEnv": "STRIPE_WEBHOOK_SECRET",
+ *       "namespace": "stripe",
+ *       "idempotencyKey": "js/ctx.request.body.id"
+ *     }
+ *   },
+ *   "steps": [
+ *     { "id": "dispatch", "subworkflow": "js/ctx.request.body.type", "inputs": { "stripeEvent": "js/ctx.request.body" } }
+ *   ]
+ * }
+ * ```
+ *
+ * **Pipeline (per inbound request):**
+ *
+ *   1. Read raw body — verifiers MUST sign the bytes that crossed
+ *      the wire, not the JSON-re-stringified body (Stripe / GitHub /
+ *      Slack all sign raw bytes).
+ *   2. Verify the signature via the per-provider strategy
+ *      (`verifiers.ts`). On failure, return 401 with structured
+ *      `{ error, reason, message }`.
+ *   3. Replay check: if `idempotencyKey` is configured, look up
+ *      `(workflowName, eventId)` in the idempotency cache (same store
+ *      as Tier 1 step caching). On hit, return 200 with
+ *      `{ status: "duplicate", eventId }` and DON'T run the workflow.
+ *   4. Events allowlist: if `events: [...]` is configured, skip
+ *      workflow runs whose event type isn't in the list — return
+ *      200 with `{ status: "ignored", eventType }` so the sender
+ *      doesn't retry.
+ *   5. Run the workflow through `TriggerBase.run` so middleware,
+ *      tracing, retries, concurrency, etc. apply uniformly.
+ *   6. Cache the eventId so a retry within the TTL window returns
+ *      the duplicate response.
+ *
+ * **Hono integration:** identical to WebSocket and SSE — accepts the
+ * shared `Hono<any, any, any>` app and an optional `HttpTriggerLike`
+ * exposing `addPreCatchAllHook` so webhook routes mount BEFORE the
+ * legacy `/:workflow{.+}` catch-all and win Hono's first-match
+ * dispatch.
+ *
+ * See [additional-triggers-plan.mdx](../../../docs/c/devtools/additional-triggers-plan.mdx#webhook-trigger)
+ * for the full v0.7 design.
  */
-interface WebhookWorkflowModel {
-    path: string;
-    config: {
-        name: string;
-        version: string;
-        trigger?: {
-            webhook?: WebhookTriggerOpts;
-            [key: string]: unknown;
-        };
-        [key: string]: unknown;
+import { DefaultLogger, type GlobalOptions as RunnerGlobalOptions, TriggerBase } from "@blokjs/runner";
+import type { Hono } from "hono";
+interface WebhookTriggerConfig {
+    provider?: "github" | "stripe" | "slack" | "shopify" | "svix";
+    path?: string;
+    events?: string[];
+    secretEnv?: string;
+    signature?: {
+        scheme?: "hmac-sha256" | "hmac-sha1" | "hmac-sha512";
+        header: string;
+        format?: string;
+        secretEnv: string;
+        tolerance?: number;
+        timestampHeader?: string;
     };
+    tolerance?: number;
+    idempotencyKey?: string;
+    namespace?: string;
+    middleware?: string[];
 }
-/**
- * Built-in source handlers
- */
-declare const sourceHandlers: Record<string, WebhookSourceHandler>;
-/**
- * WebhookTrigger - Handle webhook events
- */
-export declare abstract class WebhookTrigger extends TriggerBase {
-    protected nodeMap: GlobalOptions;
-    protected readonly tracer: import("@opentelemetry/api").Tracer;
+interface HttpTriggerLike {
+    addPreCatchAllHook(cb: () => void | Promise<void>): void;
+}
+export default class WebhookTrigger extends TriggerBase {
+    protected nodeMap: RunnerGlobalOptions;
     protected readonly logger: DefaultLogger;
-    protected webhookWorkflows: WebhookWorkflowModel[];
-    protected abstract nodes: Record<string, BlokService<unknown>>;
-    protected abstract workflows: Record<string, HelperResponse>;
-    constructor();
-    /**
-     * Load nodes into the node map
-     */
-    loadNodes(): void;
-    /**
-     * Load workflows into the workflow map
-     */
-    loadWorkflows(): void;
+    protected readonly tracer: import("@opentelemetry/api").Tracer;
+    private readonly meter;
+    private readonly counterReceived;
+    private readonly counterRejected;
+    private readonly counterAccepted;
+    private readonly app;
+    private readonly httpTrigger;
+    private wired;
+    constructor(app: Hono<any, any, any>, httpTrigger?: HttpTriggerLike);
     /**
-     * Initialize webhook trigger (call after loading workflows)
+     * Inject the runner's GlobalOptions (nodes + workflows). Called by
+     * the orchestrator AFTER constructing the trigger but BEFORE
+     * `listen()`. Shares HttpTrigger's nodeMap so per-request workflow
+     * runs resolve helpers + sub-workflows through the same registry.
      */
+    setNodeMap(nodeMap: RunnerGlobalOptions): void;
     listen(): Promise<number>;
-    /**
-     * Stop the webhook trigger
-     */
     stop(): Promise<void>;
-    protected onHmrWorkflowChange(): Promise<void>;
-    /**
-     * Process an incoming webhook request
-     * Call this from your HTTP endpoint handler
-     */
-    handleWebhook(source: string, rawBody: string, headers: Record<string, string>): Promise<TriggerResponse | null>;
-    /**
-     * Get all workflows that have webhook triggers
-     */
-    protected getWebhookWorkflows(): WebhookWorkflowModel[];
-    /**
-     * Find workflow matching the webhook event
-     */
-    protected findMatchingWorkflow(event: WebhookEvent): WebhookWorkflowModel | null;
-    /**
-     * Execute a workflow for a webhook event
-     */
-    protected executeWorkflow(event: WebhookEvent, workflow: WebhookWorkflowModel, _config: WebhookTriggerOpts): Promise<TriggerResponse>;
-    /**
-     * Register a custom source handler
-     */
-    static registerSourceHandler(source: string, handler: WebhookSourceHandler): void;
+    private registerRoutesFromRegistry;
+    private registerWebhookRoute;
+    private handleRequest;
+    private resolveVerifier;
+    private dispatchWorkflow;
+    getStats(): {
+        workflowsRegistered: number;
+    };
+    private getWebhookWorkflows;
 }
-export default WebhookTrigger;
-export { sourceHandlers };
+export declare function _setActiveWebhookTrigger(trigger: WebhookTrigger | null): void;
+export declare function _getActiveWebhookTrigger(): WebhookTrigger | null;
+export type { WebhookTriggerConfig };