@firela/billclaw-core 0.1.4 → 0.2.0

package/dist/webhooks/handlers/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/webhooks/handlers/index.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,cAAc,YAAY,CAAA;AAC1B,cAAc,iBAAiB,CAAA;AAC/B,cAAc,YAAY,CAAA"}

package/dist/webhooks/handlers/plaid.d.ts

@@ -0,0 +1,73 @@
+/**
+ * Plaid webhook handler
+ *
+ * Processes webhooks from Plaid:
+ * - TRANSACTIONS.SYNC_UPDATES_AVAILABLE: Trigger sync for the item
+ * - ITEM.ERROR: Emit account error event
+ * - ITEM.LOGIN_REQUIRED: Notify user to re-authenticate
+ */
+import type { WebhookHandler, WebhookRequest, WebhookResponse } from "../types.js";
+import type { Logger } from "../../errors/errors.js";
+/**
+ * Plaid webhook handler configuration
+ */
+export interface PlaidWebhookHandlerConfig {
+    /**
+     * Logger instance
+     */
+    logger: Logger;
+    /**
+     * Find account by Plaid item ID
+     */
+    findAccountByItemId: (itemId: string) => Promise<any | null>;
+    /**
+     * Trigger sync for an account
+     */
+    triggerSync?: (accountId: string) => Promise<void>;
+    /**
+     * Emit events to configured webhook endpoints
+     */
+    emitEvent?: (eventType: string, data: unknown) => Promise<void>;
+    /**
+     * Webhook configurations for event emission
+     */
+    webhooks?: any[];
+    /**
+     * Rate limiter for sync operations
+     */
+    rateLimiter?: {
+        isWebhookSyncAllowed: (accountId: string) => boolean;
+        recordWebhookSync: (accountId: string) => void;
+    };
+}
+/**
+ * Plaid webhook handler
+ *
+ * Handles inbound webhooks from Plaid.
+ */
+export declare class PlaidWebhookHandler implements WebhookHandler {
+    readonly source: "plaid";
+    private readonly logger;
+    private readonly findAccountByItemId;
+    private readonly triggerSync?;
+    private readonly emitEvent?;
+    private readonly webhooks?;
+    private readonly rateLimiter?;
+    constructor(config: PlaidWebhookHandlerConfig);
+    handle(request: WebhookRequest): Promise<WebhookResponse>;
+    verify(_request: WebhookRequest, _secret: string): boolean;
+    getSupportedEvents(): string[];
+    /**
+     * Handle SYNC_UPDATES_AVAILABLE webhook
+     */
+    private handleSyncUpdatesAvailable;
+    /**
+     * Handle ITEM.ERROR or ITEM.LOGIN_REQUIRED webhook
+     */
+    private handleItemError;
+}
+/**
+ * Create a Plaid webhook handler
+ */
+export declare function createPlaidWebhookHandler(config: PlaidWebhookHandlerConfig): PlaidWebhookHandler;
+//# sourceMappingURL=plaid.d.ts.map

package/dist/webhooks/handlers/plaid.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"plaid.d.ts","sourceRoot":"","sources":["../../../src/webhooks/handlers/plaid.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAEH,OAAO,KAAK,EACV,cAAc,EACd,cAAc,EACd,eAAe,EAChB,MAAM,aAAa,CAAA;AACpB,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,wBAAwB,CAAA;AAgBpD;;GAEG;AACH,MAAM,WAAW,yBAAyB;IACxC;;OAEG;IACH,MAAM,EAAE,MAAM,CAAA;IAEd;;OAEG;IACH,mBAAmB,EAAE,CAAC,MAAM,EAAE,MAAM,KAAK,OAAO,CAAC,GAAG,GAAG,IAAI,CAAC,CAAA;IAE5D;;OAEG;IACH,WAAW,CAAC,EAAE,CAAC,SAAS,EAAE,MAAM,KAAK,OAAO,CAAC,IAAI,CAAC,CAAA;IAElD;;OAEG;IACH,SAAS,CAAC,EAAE,CAAC,SAAS,EAAE,MAAM,EAAE,IAAI,EAAE,OAAO,KAAK,OAAO,CAAC,IAAI,CAAC,CAAA;IAE/D;;OAEG;IACH,QAAQ,CAAC,EAAE,GAAG,EAAE,CAAA;IAEhB;;OAEG;IACH,WAAW,CAAC,EAAE;QACZ,oBAAoB,EAAE,CAAC,SAAS,EAAE,MAAM,KAAK,OAAO,CAAA;QACpD,iBAAiB,EAAE,CAAC,SAAS,EAAE,MAAM,KAAK,IAAI,CAAA;KAC/C,CAAA;CACF;AAED;;;;GAIG;AACH,qBAAa,mBAAoB,YAAW,cAAc;IACxD,QAAQ,CAAC,MAAM,EAAG,OAAO,CAAS;IAClC,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAQ;IAC/B,OAAO,CAAC,QAAQ,CAAC,mBAAmB,CAAyC;IAC7E,OAAO,CAAC,QAAQ,CAAC,WAAW,CAAC,CAAsC;IACnE,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAC,CAAqD;IAChF,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAC,CAAO;IACjC,OAAO,CAAC,QAAQ,CAAC,WAAW,CAAC,CAG5B;gBAEW,MAAM,EAAE,yBAAyB;IASvC,MAAM,CAAC,OAAO,EAAE,cAAc,GAAG,OAAO,CAAC,eAAe,CAAC;IAyC/D,MAAM,CAAC,QAAQ,EAAE,cAAc,EAAE,OAAO,EAAE,MAAM,GAAG,OAAO;IAM1D,kBAAkB,IAAI,MAAM,EAAE;IAQ9B;;OAEG;YACW,0BAA0B;IAqExC;;OAEG;YACW,eAAe;CAkC9B;AAED;;GAEG;AACH,wBAAgB,yBAAyB,CACvC,MAAM,EAAE,yBAAyB,GAChC,mBAAmB,CAErB"}

package/dist/webhooks/handlers/plaid.js

@@ -0,0 +1,169 @@
+/**
+ * Plaid webhook handler
+ *
+ * Processes webhooks from Plaid:
+ * - TRANSACTIONS.SYNC_UPDATES_AVAILABLE: Trigger sync for the item
+ * - ITEM.ERROR: Emit account error event
+ * - ITEM.LOGIN_REQUIRED: Notify user to re-authenticate
+ */
+import { emitSyncStarted, emitAccountError } from "../../services/event-emitter.js";
+/**
+ * Plaid webhook handler
+ *
+ * Handles inbound webhooks from Plaid.
+ */
+export class PlaidWebhookHandler {
+    source = "plaid";
+    logger;
+    findAccountByItemId;
+    triggerSync;
+    emitEvent;
+    webhooks;
+    rateLimiter;
+    constructor(config) {
+        this.logger = config.logger;
+        this.findAccountByItemId = config.findAccountByItemId;
+        this.triggerSync = config.triggerSync;
+        this.emitEvent = config.emitEvent;
+        this.webhooks = config.webhooks;
+        this.rateLimiter = config.rateLimiter;
+    }
+    async handle(request) {
+        try {
+            const body = request.body;
+            const webhookType = body.webhook_type;
+            const webhookCode = body.webhook_code;
+            const itemId = body.item_id;
+            this.logger.info?.(`Received Plaid webhook: ${webhookType}.${webhookCode} for item ${itemId}`);
+            switch (webhookType) {
+                case "TRANSACTIONS":
+                    if (webhookCode === "SYNC_UPDATES_AVAILABLE") {
+                        return this.handleSyncUpdatesAvailable(itemId);
+                    }
+                    break;
+                case "ITEM":
+                    if (webhookCode === "ERROR" || webhookCode === "LOGIN_REQUIRED") {
+                        return this.handleItemError(body);
+                    }
+                    break;
+                default:
+                    this.logger.debug?.(`Unhandled Plaid webhook: ${webhookType}.${webhookCode}`);
+            }
+            return { status: 200, body: { received: true } };
+        }
+        catch (error) {
+            this.logger.error?.(`Error handling Plaid webhook:`, error);
+            return {
+                status: 500,
+                body: {
+                    received: false,
+                    error: error instanceof Error ? error.message : "Internal server error",
+                },
+            };
+        }
+    }
+    verify(_request, _secret) {
+        // Plaid uses headers: plaid-verification, plaid-timestamp
+        // Signature verification should be done by security layer
+        return true;
+    }
+    getSupportedEvents() {
+        return [
+            "TRANSACTIONS.SYNC_UPDATES_AVAILABLE",
+            "ITEM.ERROR",
+            "ITEM.LOGIN_REQUIRED",
+        ];
+    }
+    /**
+     * Handle SYNC_UPDATES_AVAILABLE webhook
+     */
+    async handleSyncUpdatesAvailable(itemId) {
+        try {
+            // Find account associated with this item
+            const account = await this.findAccountByItemId(itemId);
+            if (!account) {
+                this.logger.warn?.(`No account found for Plaid item: ${itemId}`);
+                return { status: 200, body: { received: true, processed: false } };
+            }
+            if (!account.enabled) {
+                this.logger.debug?.(`Account ${account.id} is disabled, skipping sync`);
+                return { status: 200, body: { received: true, processed: false } };
+            }
+            // Check rate limiter
+            if (this.rateLimiter) {
+                if (!this.rateLimiter.isWebhookSyncAllowed(account.id)) {
+                    this.logger.warn?.(`Webhook-triggered sync blocked for ${account.id}: rate limit exceeded`);
+                    return {
+                        status: 429,
+                        body: {
+                            received: true,
+                            processed: false,
+                            error: "Rate limit exceeded",
+                        },
+                    };
+                }
+                this.rateLimiter.recordWebhookSync(account.id);
+            }
+            // Emit sync started event
+            const syncId = `sync_${Date.now()}_${Math.random().toString(36).substring(2, 15)}`;
+            if (this.emitEvent) {
+                await emitSyncStarted(this.logger, this.webhooks || [], account.id, syncId);
+            }
+            // Trigger async sync (don't wait for completion)
+            if (this.triggerSync) {
+                this.triggerSync(account.id).catch((error) => {
+                    this.logger.error?.(`Webhook-triggered sync failed for ${account.id}:`, error);
+                    // P1: Emit sync.failed event
+                    if (this.emitEvent) {
+                        emitAccountError(this.logger, this.webhooks || [], account.id, "plaid", error instanceof Error ? error.message : String(error)).catch((err) => this.logger.debug?.(`Event emission failed:`, err));
+                    }
+                });
+            }
+            return { status: 200, body: { received: true, processed: true } };
+        }
+        catch (error) {
+            this.logger.error?.(`Error handling SYNC_UPDATES_AVAILABLE:`, error);
+            return {
+                status: 500,
+                body: {
+                    received: false,
+                    error: error instanceof Error ? error.message : "Internal server error",
+                },
+            };
+        }
+    }
+    /**
+     * Handle ITEM.ERROR or ITEM.LOGIN_REQUIRED webhook
+     */
+    async handleItemError(body) {
+        try {
+            const error = body.error ?? {
+                error_code: body.webhook_code,
+                error_message: "Item login required",
+            };
+            this.logger.warn?.(`Plaid item error for ${body.item_id}: ${error.error_code} - ${error.error_message}`);
+            // Emit account error event
+            if (this.emitEvent) {
+                await emitAccountError(this.logger, this.webhooks || [], body.item_id, "plaid", JSON.stringify(error));
+            }
+            return { status: 200, body: { received: true } };
+        }
+        catch (error) {
+            this.logger.error?.(`Error handling item error:`, error);
+            return {
+                status: 500,
+                body: {
+                    received: false,
+                    error: error instanceof Error ? error.message : "Internal server error",
+                },
+            };
+        }
+    }
+}
+/**
+ * Create a Plaid webhook handler
+ */
+export function createPlaidWebhookHandler(config) {
+    return new PlaidWebhookHandler(config);
+}
+//# sourceMappingURL=plaid.js.map

package/dist/webhooks/handlers/plaid.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"plaid.js","sourceRoot":"","sources":["../../../src/webhooks/handlers/plaid.ts"],"names":[],"mappings":"AAAA;;;;;;;GAOG;AAQH,OAAO,EAAE,eAAe,EAAE,gBAAgB,EAAE,MAAM,iCAAiC,CAAA;AAqDnF;;;;GAIG;AACH,MAAM,OAAO,mBAAmB;IACrB,MAAM,GAAG,OAAgB,CAAA;IACjB,MAAM,CAAQ;IACd,mBAAmB,CAAyC;IAC5D,WAAW,CAAuC;IAClD,SAAS,CAAsD;IAC/D,QAAQ,CAAQ;IAChB,WAAW,CAG3B;IAED,YAAY,MAAiC;QAC3C,IAAI,CAAC,MAAM,GAAG,MAAM,CAAC,MAAM,CAAA;QAC3B,IAAI,CAAC,mBAAmB,GAAG,MAAM,CAAC,mBAAmB,CAAA;QACrD,IAAI,CAAC,WAAW,GAAG,MAAM,CAAC,WAAW,CAAA;QACrC,IAAI,CAAC,SAAS,GAAG,MAAM,CAAC,SAAS,CAAA;QACjC,IAAI,CAAC,QAAQ,GAAG,MAAM,CAAC,QAAQ,CAAA;QAC/B,IAAI,CAAC,WAAW,GAAG,MAAM,CAAC,WAAW,CAAA;IACvC,CAAC;IAED,KAAK,CAAC,MAAM,CAAC,OAAuB;QAClC,IAAI,CAAC;YACH,MAAM,IAAI,GAAG,OAAO,CAAC,IAAwB,CAAA;YAC7C,MAAM,WAAW,GAAG,IAAI,CAAC,YAAY,CAAA;YACrC,MAAM,WAAW,GAAG,IAAI,CAAC,YAAY,CAAA;YACrC,MAAM,MAAM,GAAG,IAAI,CAAC,OAAO,CAAA;YAE3B,IAAI,CAAC,MAAM,CAAC,IAAI,EAAE,CAChB,2BAA2B,WAAW,IAAI,WAAW,aAAa,MAAM,EAAE,CAC3E,CAAA;YAED,QAAQ,WAAW,EAAE,CAAC;gBACpB,KAAK,cAAc;oBACjB,IAAI,WAAW,KAAK,wBAAwB,EAAE,CAAC;wBAC7C,OAAO,IAAI,CAAC,0BAA0B,CAAC,MAAM,CAAC,CAAA;oBAChD,CAAC;oBACD,MAAK;gBAEP,KAAK,MAAM;oBACT,IAAI,WAAW,KAAK,OAAO,IAAI,WAAW,KAAK,gBAAgB,EAAE,CAAC;wBAChE,OAAO,IAAI,CAAC,eAAe,CAAC,IAAI,CAAC,CAAA;oBACnC,CAAC;oBACD,MAAK;gBAEP;oBACE,IAAI,CAAC,MAAM,CAAC,KAAK,EAAE,CAAC,4BAA4B,WAAW,IAAI,WAAW,EAAE,CAAC,CAAA;YACjF,CAAC;YAED,OAAO,EAAE,MAAM,EAAE,GAAG,EAAE,IAAI,EAAE,EAAE,QAAQ,EAAE,IAAI,EAAE,EAAE,CAAA;QAClD,CAAC;QAAC,OAAO,KAAK,EAAE,CAAC;YACf,IAAI,CAAC,MAAM,CAAC,KAAK,EAAE,CAAC,+BAA+B,EAAE,KAAK,CAAC,CAAA;YAC3D,OAAO;gBACL,MAAM,EAAE,GAAG;gBACX,IAAI,EAAE;oBACJ,QAAQ,EAAE,KAAK;oBACf,KAAK,EAAE,KAAK,YAAY,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,uBAAuB;iBACxE;aACF,CAAA;QACH,CAAC;IACH,CAAC;IAED,MAAM,CAAC,QAAwB,EAAE,OAAe;QAC9C,0DAA0D;QAC1D,0DAA0D;QAC1D,OAAO,IAAI,CAAA;IACb,CAAC;IAED,kBAAkB;QAChB,OAAO;YACL,qCAAqC;YACrC,YAAY;YACZ,qBAAqB;SACtB,CAAA;IACH,CAAC;IAED;;OAEG;IACK,KAAK,CAAC,0BAA0B,CAAC,MAAc;QACrD,IAAI,CAAC;YACH,yCAAyC;YACzC,MAAM,OAAO,GAAG,MAAM,IAAI,CAAC,mBAAmB,CAAC,MAAM,CAAC,CAAA;YAEtD,IAAI,CAAC,OAAO,EAAE,CAAC;gBACb,IAAI,CAAC,MAAM,CAAC,IAAI,EAAE,CAAC,oCAAoC,MAAM,EAAE,CAAC,CAAA;gBAChE,OAAO,EAAE,MAAM,EAAE,GAAG,EAAE,IAAI,EAAE,EAAE,QAAQ,EAAE,IAAI,EAAE,SAAS,EAAE,KAAK,EAAE,EAAE,CAAA;YACpE,CAAC;YAED,IAAI,CAAC,OAAO,CAAC,OAAO,EAAE,CAAC;gBACrB,IAAI,CAAC,MAAM,CAAC,KAAK,EAAE,CAAC,WAAW,OAAO,CAAC,EAAE,6BAA6B,CAAC,CAAA;gBACvE,OAAO,EAAE,MAAM,EAAE,GAAG,EAAE,IAAI,EAAE,EAAE,QAAQ,EAAE,IAAI,EAAE,SAAS,EAAE,KAAK,EAAE,EAAE,CAAA;YACpE,CAAC;YAED,qBAAqB;YACrB,IAAI,IAAI,CAAC,WAAW,EAAE,CAAC;gBACrB,IAAI,CAAC,IAAI,CAAC,WAAW,CAAC,oBAAoB,CAAC,OAAO,CAAC,EAAE,CAAC,EAAE,CAAC;oBACvD,IAAI,CAAC,MAAM,CAAC,IAAI,EAAE,CAChB,sCAAsC,OAAO,CAAC,EAAE,uBAAuB,CACxE,CAAA;oBACD,OAAO;wBACL,MAAM,EAAE,GAAG;wBACX,IAAI,EAAE;4BACJ,QAAQ,EAAE,IAAI;4BACd,SAAS,EAAE,KAAK;4BAChB,KAAK,EAAE,qBAAqB;yBAC7B;qBACF,CAAA;gBACH,CAAC;gBACD,IAAI,CAAC,WAAW,CAAC,iBAAiB,CAAC,OAAO,CAAC,EAAE,CAAC,CAAA;YAChD,CAAC;YAED,0BAA0B;YAC1B,MAAM,MAAM,GAAG,QAAQ,IAAI,CAAC,GAAG,EAAE,IAAI,IAAI,CAAC,MAAM,EAAE,CAAC,QAAQ,CAAC,EAAE,CAAC,CAAC,SAAS,CAAC,CAAC,EAAE,EAAE,CAAC,EAAE,CAAA;YAClF,IAAI,IAAI,CAAC,SAAS,EAAE,CAAC;gBACnB,MAAM,eAAe,CAAC,IAAI,CAAC,MAAM,EAAE,IAAI,CAAC,QAAQ,IAAI,EAAE,EAAE,OAAO,CAAC,EAAE,EAAE,MAAM,CAAC,CAAA;YAC7E,CAAC;YAED,iDAAiD;YACjD,IAAI,IAAI,CAAC,WAAW,EAAE,CAAC;gBACrB,IAAI,CAAC,WAAW,CAAC,OAAO,CAAC,EAAE,CAAC,CAAC,KAAK,CAAC,CAAC,KAAK,EAAE,EAAE;oBAC3C,IAAI,CAAC,MAAM,CAAC,KAAK,EAAE,CAAC,qCAAqC,OAAO,CAAC,EAAE,GAAG,EAAE,KAAK,CAAC,CAAA;oBAC9E,6BAA6B;oBAC7B,IAAI,IAAI,CAAC,SAAS,EAAE,CAAC;wBACnB,gBAAgB,CACd,IAAI,CAAC,MAAM,EACX,IAAI,CAAC,QAAQ,IAAI,EAAE,EACnB,OAAO,CAAC,EAAE,EACV,OAAO,EACP,KAAK,YAAY,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,MAAM,CAAC,KAAK,CAAC,CACvD,CAAC,KAAK,CAAC,CAAC,GAAG,EAAE,EAAE,CAAC,IAAI,CAAC,MAAM,CAAC,KAAK,EAAE,CAAC,wBAAwB,EAAE,GAAG,CAAC,CAAC,CAAA;oBACtE,CAAC;gBACH,CAAC,CAAC,CAAA;YACJ,CAAC;YAED,OAAO,EAAE,MAAM,EAAE,GAAG,EAAE,IAAI,EAAE,EAAE,QAAQ,EAAE,IAAI,EAAE,SAAS,EAAE,IAAI,EAAE,EAAE,CAAA;QACnE,CAAC;QAAC,OAAO,KAAK,EAAE,CAAC;YACf,IAAI,CAAC,MAAM,CAAC,KAAK,EAAE,CAAC,wCAAwC,EAAE,KAAK,CAAC,CAAA;YACpE,OAAO;gBACL,MAAM,EAAE,GAAG;gBACX,IAAI,EAAE;oBACJ,QAAQ,EAAE,KAAK;oBACf,KAAK,EAAE,KAAK,YAAY,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,uBAAuB;iBACxE;aACF,CAAA;QACH,CAAC;IACH,CAAC;IAED;;OAEG;IACK,KAAK,CAAC,eAAe,CAAC,IAAsB;QAClD,IAAI,CAAC;YACH,MAAM,KAAK,GAAG,IAAI,CAAC,KAAK,IAAI;gBAC1B,UAAU,EAAE,IAAI,CAAC,YAAY;gBAC7B,aAAa,EAAE,qBAAqB;aACrC,CAAA;YAED,IAAI,CAAC,MAAM,CAAC,IAAI,EAAE,CAChB,wBAAwB,IAAI,CAAC,OAAO,KAAK,KAAK,CAAC,UAAU,MAAM,KAAK,CAAC,aAAa,EAAE,CACrF,CAAA;YAED,2BAA2B;YAC3B,IAAI,IAAI,CAAC,SAAS,EAAE,CAAC;gBACnB,MAAM,gBAAgB,CACpB,IAAI,CAAC,MAAM,EACX,IAAI,CAAC,QAAQ,IAAI,EAAE,EACnB,IAAI,CAAC,OAAO,EACZ,OAAO,EACP,IAAI,CAAC,SAAS,CAAC,KAAK,CAAC,CACtB,CAAA;YACH,CAAC;YAED,OAAO,EAAE,MAAM,EAAE,GAAG,EAAE,IAAI,EAAE,EAAE,QAAQ,EAAE,IAAI,EAAE,EAAE,CAAA;QAClD,CAAC;QAAC,OAAO,KAAK,EAAE,CAAC;YACf,IAAI,CAAC,MAAM,CAAC,KAAK,EAAE,CAAC,4BAA4B,EAAE,KAAK,CAAC,CAAA;YACxD,OAAO;gBACL,MAAM,EAAE,GAAG;gBACX,IAAI,EAAE;oBACJ,QAAQ,EAAE,KAAK;oBACf,KAAK,EAAE,KAAK,YAAY,KAAK,CAAC,CAAC,CAAC,KAAK,CAAC,OAAO,CAAC,CAAC,CAAC,uBAAuB;iBACxE;aACF,CAAA;QACH,CAAC;IACH,CAAC;CACF;AAED;;GAEG;AACH,MAAM,UAAU,yBAAyB,CACvC,MAAiC;IAEjC,OAAO,IAAI,mBAAmB,CAAC,MAAM,CAAC,CAAA;AACxC,CAAC"}

package/dist/webhooks/index.d.ts

@@ -0,0 +1,15 @@
+/**
+ * Webhook processing layer for BillClaw
+ *
+ * Framework-agnostic inbound webhook processing with security and concurrency handling.
+ *
+ * @packageDocumentation
+ */
+export * from "./types.js";
+export * from "./processor.js";
+export * from "./router.js";
+export * from "./security.js";
+export * from "./deduplication.js";
+export * from "./sync-rate-limiter.js";
+export * from "./handlers/index.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/webhooks/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/webhooks/index.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAGH,cAAc,YAAY,CAAA;AAC1B,cAAc,gBAAgB,CAAA;AAC9B,cAAc,aAAa,CAAA;AAC3B,cAAc,eAAe,CAAA;AAC7B,cAAc,oBAAoB,CAAA;AAClC,cAAc,wBAAwB,CAAA;AAGtC,cAAc,qBAAqB,CAAA"}

package/dist/webhooks/index.js

@@ -0,0 +1,17 @@
+/**
+ * Webhook processing layer for BillClaw
+ *
+ * Framework-agnostic inbound webhook processing with security and concurrency handling.
+ *
+ * @packageDocumentation
+ */
+// Public API exports
+export * from "./types.js";
+export * from "./processor.js";
+export * from "./router.js";
+export * from "./security.js";
+export * from "./deduplication.js";
+export * from "./sync-rate-limiter.js";
+// Handlers
+export * from "./handlers/index.js";
+//# sourceMappingURL=index.js.map

package/dist/webhooks/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/webhooks/index.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,qBAAqB;AACrB,cAAc,YAAY,CAAA;AAC1B,cAAc,gBAAgB,CAAA;AAC9B,cAAc,aAAa,CAAA;AAC3B,cAAc,eAAe,CAAA;AAC7B,cAAc,oBAAoB,CAAA;AAClC,cAAc,wBAAwB,CAAA;AAEtC,WAAW;AACX,cAAc,qBAAqB,CAAA"}

package/dist/webhooks/processor.d.ts

@@ -0,0 +1,76 @@
+/**
+ * Webhook processor interface
+ *
+ * Main interface for processing inbound webhooks from various sources.
+ */
+import type { Logger } from "../errors/errors.js";
+import type { WebhookRequest, WebhookResponse, WebhookHandler } from "./types.js";
+import type { WebhookSecurity } from "./security.js";
+/**
+ * Webhook processor options
+ */
+export interface WebhookProcessorOptions {
+    /**
+     * Logger instance
+     */
+    logger: Logger;
+    /**
+     * Webhook secret for signature verification
+     */
+    webhookSecret?: string;
+    /**
+     * Security layer for replay protection and signature verification
+     */
+    security?: WebhookSecurity;
+}
+/**
+ * Webhook processor
+ *
+ * Main entry point for processing inbound webhooks.
+ * Routes requests to appropriate handlers and applies security checks.
+ */
+export declare class WebhookProcessor {
+    private readonly handlers;
+    private readonly logger;
+    private readonly webhookSecret?;
+    private readonly security?;
+    constructor(options: WebhookProcessorOptions);
+    /**
+     * Register a webhook handler for a specific source
+     *
+     * @param source - Webhook source identifier
+     * @param handler - Handler implementation
+     */
+    registerHandler(source: string, handler: WebhookHandler): void;
+    /**
+     * Process incoming webhook request
+     *
+     * Applies security checks and routes to appropriate handler.
+     *
+     * @param request - Normalized webhook request
+     * @returns Processing response
+     */
+    process(request: WebhookRequest): Promise<WebhookResponse>;
+    /**
+     * Get registered handler by source
+     *
+     * @param source - Webhook source identifier
+     * @returns Handler or undefined if not found
+     */
+    getHandler(source: string): WebhookHandler | undefined;
+    /**
+     * Get all registered handlers
+     *
+     * @returns Map of source to handler
+     */
+    getAllHandlers(): Map<string, WebhookHandler>;
+    /**
+     * Create error response
+     */
+    private createErrorResponse;
+}
+/**
+ * Create a webhook processor with default configuration
+ */
+export declare function createWebhookProcessor(logger: Logger, options?: Partial<WebhookProcessorOptions>): WebhookProcessor;
+//# sourceMappingURL=processor.d.ts.map

package/dist/webhooks/processor.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"processor.d.ts","sourceRoot":"","sources":["../../src/webhooks/processor.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,qBAAqB,CAAA;AACjD,OAAO,KAAK,EACV,cAAc,EACd,eAAe,EACf,cAAc,EAEf,MAAM,YAAY,CAAA;AACnB,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,eAAe,CAAA;AAEpD;;GAEG;AACH,MAAM,WAAW,uBAAuB;IACtC;;OAEG;IACH,MAAM,EAAE,MAAM,CAAA;IAEd;;OAEG;IACH,aAAa,CAAC,EAAE,MAAM,CAAA;IAEtB;;OAEG;IACH,QAAQ,CAAC,EAAE,eAAe,CAAA;CAC3B;AAED;;;;;GAKG;AACH,qBAAa,gBAAgB;IAC3B,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAoC;IAC7D,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAQ;IAC/B,OAAO,CAAC,QAAQ,CAAC,aAAa,CAAC,CAAQ;IACvC,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAC,CAAiB;gBAE/B,OAAO,EAAE,uBAAuB;IAM5C;;;;;OAKG;IACH,eAAe,CAAC,MAAM,EAAE,MAAM,EAAE,OAAO,EAAE,cAAc,GAAG,IAAI;IAK9D;;;;;;;OAOG;IACG,OAAO,CAAC,OAAO,EAAE,cAAc,GAAG,OAAO,CAAC,eAAe,CAAC;IAsDhE;;;;;OAKG;IACH,UAAU,CAAC,MAAM,EAAE,MAAM,GAAG,cAAc,GAAG,SAAS;IAItD;;;;OAIG;IACH,cAAc,IAAI,GAAG,CAAC,MAAM,EAAE,cAAc,CAAC;IAI7C;;OAEG;IACH,OAAO,CAAC,mBAAmB;CAkB5B;AAED;;GAEG;AACH,wBAAgB,sBAAsB,CACpC,MAAM,EAAE,MAAM,EACd,OAAO,CAAC,EAAE,OAAO,CAAC,uBAAuB,CAAC,GACzC,gBAAgB,CAKlB"}

package/dist/webhooks/processor.js

@@ -0,0 +1,116 @@
+/**
+ * Webhook processor interface
+ *
+ * Main interface for processing inbound webhooks from various sources.
+ */
+/**
+ * Webhook processor
+ *
+ * Main entry point for processing inbound webhooks.
+ * Routes requests to appropriate handlers and applies security checks.
+ */
+export class WebhookProcessor {
+    handlers = new Map();
+    logger;
+    webhookSecret;
+    security;
+    constructor(options) {
+        this.logger = options.logger;
+        this.webhookSecret = options.webhookSecret;
+        this.security = options.security;
+    }
+    /**
+     * Register a webhook handler for a specific source
+     *
+     * @param source - Webhook source identifier
+     * @param handler - Handler implementation
+     */
+    registerHandler(source, handler) {
+        this.handlers.set(source, handler);
+        this.logger.info?.(`Registered webhook handler for source: ${source}`);
+    }
+    /**
+     * Process incoming webhook request
+     *
+     * Applies security checks and routes to appropriate handler.
+     *
+     * @param request - Normalized webhook request
+     * @returns Processing response
+     */
+    async process(request) {
+        try {
+            // Security: Replay protection
+            if (this.security && request.timestamp && request.nonce) {
+                const isValid = await this.security.validateReplayProtection(request.timestamp, request.nonce);
+                if (!isValid) {
+                    return this.createErrorResponse("REPLAY_DETECTED", 401, "Replay detected", false);
+                }
+            }
+            // Security: Signature verification
+            if (this.security && request.signature && this.webhookSecret) {
+                const payload = JSON.stringify(request.body);
+                const isValid = this.security.verifySignature(payload, request.signature, this.webhookSecret);
+                if (!isValid) {
+                    return this.createErrorResponse("INVALID_SIGNATURE", 401, "Invalid signature", false);
+                }
+            }
+            // Get handler for source
+            const handler = this.handlers.get(request.source);
+            if (!handler) {
+                this.logger.warn?.(`No handler registered for source: ${request.source}`);
+                return this.createErrorResponse("INTERNAL_ERROR", 400, `No handler for source: ${request.source}`, false);
+            }
+            // Process with handler
+            this.logger.debug?.(`Processing webhook from ${request.source}`);
+            const response = await handler.handle(request);
+            return response;
+        }
+        catch (error) {
+            this.logger.error?.(`Error processing webhook from ${request.source}:`, error);
+            return this.createErrorResponse("INTERNAL_ERROR", 500, error instanceof Error ? error.message : "Unknown error", true);
+        }
+    }
+    /**
+     * Get registered handler by source
+     *
+     * @param source - Webhook source identifier
+     * @returns Handler or undefined if not found
+     */
+    getHandler(source) {
+        return this.handlers.get(source);
+    }
+    /**
+     * Get all registered handlers
+     *
+     * @returns Map of source to handler
+     */
+    getAllHandlers() {
+        return new Map(this.handlers);
+    }
+    /**
+     * Create error response
+     */
+    createErrorResponse(code, status, message, retryable) {
+        return {
+            status,
+            body: {
+                received: false,
+                error: {
+                    code,
+                    message,
+                    retryable,
+                },
+            },
+        };
+    }
+}
+/**
+ * Create a webhook processor with default configuration
+ */
+export function createWebhookProcessor(logger, options) {
+    return new WebhookProcessor({
+        logger,
+        ...options,
+    });
+}
+//# sourceMappingURL=processor.js.map

package/dist/webhooks/processor.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"processor.js","sourceRoot":"","sources":["../../src/webhooks/processor.ts"],"names":[],"mappings":"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"}

package/dist/webhooks/router.d.ts

@@ -0,0 +1,80 @@
+/**
+ * Webhook router registry
+ *
+ * Registry pattern for managing webhook handlers.
+ * Provides handler registration and lookup functionality.
+ */
+import type { WebhookRequest, WebhookResponse, WebhookHandler, WebhookSource } from "./types.js";
+import type { Logger } from "../errors/errors.js";
+/**
+ * Webhook router options
+ */
+export interface WebhookRouterOptions {
+    /**
+     * Logger instance
+     */
+    logger: Logger;
+}
+/**
+ * Webhook router
+ *
+ * Registry for webhook handlers with routing functionality.
+ */
+export declare class WebhookRouter {
+    private readonly handlers;
+    private readonly logger;
+    constructor(options: WebhookRouterOptions);
+    /**
+     * Register a webhook handler for a specific source
+     *
+     * @param source - Webhook source identifier
+     * @param handler - Handler implementation
+     */
+    register(source: WebhookSource, handler: WebhookHandler): void;
+    /**
+     * Unregister a handler for a specific source
+     *
+     * @param source - Webhook source identifier
+     */
+    unregister(source: WebhookSource): void;
+    /**
+     * Get handler by source
+     *
+     * @param source - Webhook source identifier
+     * @returns Handler or undefined if not found
+     */
+    getHandler(source: WebhookSource): WebhookHandler | undefined;
+    /**
+     * Check if handler is registered for source
+     *
+     * @param source - Webhook source identifier
+     * @returns True if handler exists
+     */
+    hasHandler(source: WebhookSource): boolean;
+    /**
+     * Get all registered sources
+     *
+     * @returns Array of registered source identifiers
+     */
+    getSources(): WebhookSource[];
+    /**
+     * Route request to appropriate handler
+     *
+     * @param request - Webhook request
+     * @returns Response from handler or error if not found
+     */
+    route(request: WebhookRequest): Promise<WebhookResponse>;
+    /**
+     * Clear all registered handlers
+     */
+    clear(): void;
+    /**
+     * Get number of registered handlers
+     */
+    get size(): number;
+}
+/**
+ * Create a webhook router with default configuration
+ */
+export declare function createWebhookRouter(logger: Logger): WebhookRouter;
+//# sourceMappingURL=router.d.ts.map

package/dist/webhooks/router.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"router.d.ts","sourceRoot":"","sources":["../../src/webhooks/router.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,KAAK,EACV,cAAc,EACd,eAAe,EACf,cAAc,EACd,aAAa,EACd,MAAM,YAAY,CAAA;AACnB,OAAO,KAAK,EAAE,MAAM,EAAE,MAAM,qBAAqB,CAAA;AAEjD;;GAEG;AACH,MAAM,WAAW,oBAAoB;IACnC;;OAEG;IACH,MAAM,EAAE,MAAM,CAAA;CACf;AAED;;;;GAIG;AACH,qBAAa,aAAa;IACxB,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAA2C;IACpE,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAQ;gBAEnB,OAAO,EAAE,oBAAoB;IAIzC;;;;;OAKG;IACH,QAAQ,CAAC,MAAM,EAAE,aAAa,EAAE,OAAO,EAAE,cAAc,GAAG,IAAI;IAS9D;;;;OAIG;IACH,UAAU,CAAC,MAAM,EAAE,aAAa,GAAG,IAAI;IAMvC;;;;;OAKG;IACH,UAAU,CAAC,MAAM,EAAE,aAAa,GAAG,cAAc,GAAG,SAAS;IAI7D;;;;;OAKG;IACH,UAAU,CAAC,MAAM,EAAE,aAAa,GAAG,OAAO;IAI1C;;;;OAIG;IACH,UAAU,IAAI,aAAa,EAAE;IAI7B;;;;;OAKG;IACG,KAAK,CAAC,OAAO,EAAE,cAAc,GAAG,OAAO,CAAC,eAAe,CAAC;IAiB9D;;OAEG;IACH,KAAK,IAAI,IAAI;IAKb;;OAEG;IACH,IAAI,IAAI,IAAI,MAAM,CAEjB;CACF;AAED;;GAEG;AACH,wBAAgB,mBAAmB,CAAC,MAAM,EAAE,MAAM,GAAG,aAAa,CAEjE"}