@tangle-network/agent-integrations 0.26.0 → 0.28.0

package/dist/webhooks/index.d.ts

@@ -1,150 +1,5 @@
-/**
- * @stable Provider-agnostic inbound webhook router.
- *
- * Consumer hooks a single HTTP handler at `/webhook/:provider/:event`
- * (or whatever pathing they prefer) and forwards the request through
- * `WebhookRouter.handle()`. The router:
- *
- *   1. Resolves the registered provider entry.
- *   2. Calls the provider's `verifySignature(rawBody, headers, secrets)`.
- *      Failure → 401 fast, no downstream work.
- *   3. Calls the provider's `parse(rawBody, headers)` to extract zero or
- *      more normalized events.
- *   4. Enqueues each event for async processing via the consumer-supplied
- *      `deliver(event)` callback (best-effort fire-and-forget — the
- *      router does NOT block the HTTP response on the consumer's work).
- *   5. Returns 200 fast with `{received: events.length}`.
- *
- * Replay protection: providers that sign timestamps (Stripe, Slack)
- * already reject stale signatures inside `verifySignature`. For providers
- * that don't (DocuSeal, GDrive push), the router exposes a pluggable
- * `idempotency` hook: if `idempotency.seen(providerEventId)` returns
- * true, the router 200s without invoking `deliver()`. Consumers wire
- * this to a durable kv (D1 / Redis / Postgres unique-index).
- *
- * Why a router and not a per-provider express app: the runtime contract
- * a product cares about is "an inbound event came in, here's the
- * normalized envelope". Verification, parsing, and idempotency-dedup
- * are mechanical and provider-specific — the router owns them. The
- * consumer's `deliver()` is the only place product logic runs.
- *
- * Stability: `@stable` — additions to `WebhookEnvelope` must be
- * additive; the router's HTTP contract (paths, status codes) is frozen
- * at 200 (ok), 400 (bad request), 401 (bad signature), 404 (unknown
- * provider), 405 (provider has no inbound surface).
- */
-interface WebhookHeaders {
-    [name: string]: string | string[] | undefined;
-}
-/** Normalized inbound event the router emits after parsing. */
-interface WebhookEnvelope<TPayload = unknown> {
-    /** Provider id (matches the `:provider` path segment). */
-    provider: string;
-    /** Optional event class — e.g., 'customer.subscription.deleted'. The
-     *  provider's parser decides. Used for routing inside `deliver()`. */
-    eventType: string;
-    /** Provider-emitted event id, when present. Used for the idempotency
-     *  short-circuit. */
-    providerEventId?: string;
-    /** Wall-clock receive time. */
-    receivedAt: number;
-    /** Provider payload, normalized to the provider's documented event
-     *  shape. The router does NOT reshape this — `parse()` is the contract. */
-    payload: TPayload;
-    /** Headers passed through for downstream handlers that want them
-     *  (e.g., to extract custom routing metadata). Always lowercased keys. */
-    headers: Record<string, string>;
-}
-type SignatureVerification = {
-    valid: true;
-} | {
-    valid: false;
-    reason: string;
-};
-/** Per-provider plug-in. Stateless — the router calls `verifySignature`
- *  then `parse` on every request. The provider's HTTP-shape concerns
- *  (e.g., raw body required) are documented per provider. */
-interface WebhookProvider {
-    /** Stable provider id (`stripe`, `docuseal`, `gdrive`, ...). */
-    id: string;
-    /** Verify the inbound signature. Receives the EXACT raw body string —
-     *  consumers MUST preserve raw bytes through their HTTP server (do not
-     *  parse JSON before forwarding here). */
-    verifySignature(input: {
-        rawBody: string;
-        headers: WebhookHeaders;
-        secret: string;
-    }): SignatureVerification;
-    /** Parse the validated raw body into zero or more normalized events.
-     *  A single push payload may carry multiple events (e.g., Slack bulk
-     *  delivery). Return [] to ack the push as a no-op. */
-    parse(input: {
-        rawBody: string;
-        headers: WebhookHeaders;
-        now?: number;
-    }): WebhookEnvelope[] | Promise<WebhookEnvelope[]>;
-}
-interface WebhookIdempotencyStore {
-    /** Returns true if this providerEventId has been processed already.
-     *  Implementations should be O(1) (Redis SETNX, D1 UNIQUE constraint). */
-    seen(providerEventId: string): Promise<boolean> | boolean;
-    /** Marks a providerEventId as processed. Called AFTER `deliver()` has
-     *  been invoked. */
-    remember(providerEventId: string, ttlMs: number): Promise<void> | void;
-}
-interface WebhookRouterOptions {
-    /** Provider registry. Pass any number of providers; routing is by id. */
-    providers: WebhookProvider[];
-    /** Async callback invoked with every accepted event. Fire-and-forget
-     *  from the router's perspective — the HTTP response is sent before
-     *  this resolves. Throws are caught and reported via `onError`. */
-    deliver(event: WebhookEnvelope): Promise<void> | void;
-    /** Resolve the signing secret for a provider id at request time. The
-     *  router never holds secrets — the consumer's vault resolves them. */
-    resolveSecret(providerId: string, headers: WebhookHeaders): Promise<string | null> | string | null;
-    /** Optional idempotency-dedup hook. Required for providers that don't
-     *  sign timestamps in their signature scheme (DocuSeal, Drive push). */
-    idempotency?: WebhookIdempotencyStore;
-    /** TTL on idempotency entries. Default 7 days — long enough that a
-     *  provider's normal retry-window can't re-deliver. */
-    idempotencyTtlMs?: number;
-    /** Surface delivery errors. Default: console.error. */
-    onError?(err: unknown, context: {
-        provider: string;
-        eventType?: string;
-        providerEventId?: string;
-    }): void;
-    /** Override `now()` for tests. */
-    now?(): number;
-}
-interface WebhookRouterRequest {
-    providerId: string;
-    rawBody: string;
-    headers: WebhookHeaders;
-}
-interface WebhookRouterResponse {
-    status: number;
-    body: unknown;
-    headers?: Record<string, string>;
-}
-/**
- * Router instance. Stateless aside from the provider registry — safe to
- * share across requests; build once per process.
- */
-declare class WebhookRouter {
-    private readonly providers;
-    private readonly deliver;
-    private readonly resolveSecret;
-    private readonly idempotency?;
-    private readonly idempotencyTtlMs;
-    private readonly onError;
-    private readonly nowFn;
-    constructor(opts: WebhookRouterOptions);
-    /** Process one inbound webhook request. Pure with respect to side-
-     *  effects on the router instance — safe to call concurrently. */
-    handle(request: WebhookRouterRequest): Promise<WebhookRouterResponse>;
-    private deliverEach;
-}
+import { W as WebhookProvider } from '../router-BncoovUh.js';
+export { S as SignatureVerification, a as WebhookEnvelope, b as WebhookHeaders, c as WebhookIdempotencyStore, d as WebhookRouter, e as WebhookRouterOptions, f as WebhookRouterRequest, g as WebhookRouterResponse } from '../router-BncoovUh.js';
 
 /**
  * Pre-built `WebhookProvider` implementations for the inbound surfaces
@@ -190,4 +45,4 @@ declare function genericHmacWebhookProvider(options: {
     parse?: WebhookProvider['parse'];
 }): WebhookProvider;
 
-export { type SignatureVerification, type WebhookEnvelope, type WebhookHeaders, type WebhookIdempotencyStore, type WebhookProvider, WebhookRouter, type WebhookRouterOptions, type WebhookRouterRequest, type WebhookRouterResponse, docusealWebhookProvider, gdriveWebhookProvider, genericHmacWebhookProvider, gmailWebhookProvider, slackWebhookProvider, stripeWebhookProvider };
+export { WebhookProvider, docusealWebhookProvider, gdriveWebhookProvider, genericHmacWebhookProvider, gmailWebhookProvider, slackWebhookProvider, stripeWebhookProvider };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tangle-network/agent-integrations",
-  "version": "0.26.0",
+  "version": "0.28.0",
   "description": "Vendor-neutral integration contracts and runtime helpers for sandbox and agent apps.",
   "homepage": "https://github.com/tangle-network/agent-integrations#readme",
   "repository": {
@@ -34,6 +34,16 @@
       "import": "./dist/connectors/adapters/index.js",
       "default": "./dist/connectors/adapters/index.js"
     },
+    "./connect": {
+      "types": "./dist/connect/index.d.ts",
+      "import": "./dist/connect/index.js",
+      "default": "./dist/connect/index.js"
+    },
+    "./middleware": {
+      "types": "./dist/middleware/index.d.ts",
+      "import": "./dist/middleware/index.js",
+      "default": "./dist/middleware/index.js"
+    },
     "./webhooks": {
       "types": "./dist/webhooks/index.d.ts",
       "import": "./dist/webhooks/index.js",
@@ -54,6 +64,11 @@
       "import": "./dist/specs.js",
       "default": "./dist/specs.js"
     },
+    "./stripe": {
+      "types": "./dist/stripe/index.d.ts",
+      "import": "./dist/stripe/index.js",
+      "default": "./dist/stripe/index.js"
+    },
     "./tangle-catalog-runtime": {
       "types": "./dist/tangle-catalog-runtime.d.ts",
       "import": "./dist/tangle-catalog-runtime.js",