@tangle-network/agent-integrations 0.26.0 → 0.28.0

package/dist/router-BncoovUh.d.ts

@@ -0,0 +1,149 @@
+/**
+ * @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;
+}
+
+export { type SignatureVerification as S, type WebhookProvider as W, type WebhookEnvelope as a, type WebhookHeaders as b, type WebhookIdempotencyStore as c, WebhookRouter as d, type WebhookRouterOptions as e, type WebhookRouterRequest as f, type WebhookRouterResponse as g };

package/dist/runtime.d.ts

@@ -1,4 +1,8 @@
 export { f as InMemoryIntegrationGrantStore, g as IntegrationCapabilityBinding, h as IntegrationGrant, j as IntegrationGrantStore, k as IntegrationManifest, l as IntegrationManifestResolution, m as IntegrationRequirement, n as IntegrationRequirementMode, o as IntegrationRequirementResolution, q as IntegrationRequirementStatus, r as IntegrationRuntime, u as IntegrationRuntimeHub, v as IntegrationRuntimeOptions, w as IntegrationSandboxBundle, x as createIntegrationRuntime } from './registry.js';
-import './index-D4D4CEKX.js';
+import './tangle-id-CTU4kGId.js';
+import './errors-Bg3_rxnQ.js';
+import './connect/index.js';
+import './middleware/index.js';
 import './connectors/index.js';
+import './connectors/adapters/index.js';
 import 'node:http';

package/dist/runtime.js

@@ -2,11 +2,15 @@ import {
   InMemoryIntegrationGrantStore,
   IntegrationRuntime,
   createIntegrationRuntime
-} from "./chunk-ALCIWTIR.js";
+} from "./chunk-UWRYFPJW.js";
+import "./chunk-SVQ4PHDZ.js";
+import "./chunk-H4XYLS7T.js";
 import "./chunk-4JQ754PA.js";
 import "./chunk-376UBTNB.js";
-import "./chunk-GA4VTE3U.js";
+import "./chunk-JU25UDN2.js";
 import "./chunk-2TW2QKGZ.js";
+import "./chunk-P24T3MLM.js";
+import "./chunk-ATYHZXLL.js";
 export {
   InMemoryIntegrationGrantStore,
   IntegrationRuntime,

package/dist/specs.d.ts

@@ -1,4 +1,8 @@
 export { U as ApiKeyAuthSpec, V as ConsoleStep, W as CredentialFieldSpec, X as CredentialValidationInput, Y as CredentialValidationResult, Z as CustomAuthSpec, _ as HealthcheckPlan, $ as HealthcheckSpec, a0 as HmacAuthSpec, a1 as INTEGRATION_FAMILIES, a2 as IntegrationAuthMode, a3 as IntegrationAuthSpec, a4 as IntegrationFamilyId, a5 as IntegrationFamilySpec, a6 as IntegrationLifecycleSpec, a7 as IntegrationPlannerHints, a8 as IntegrationSetupSpec, a9 as IntegrationSpec, aa as IntegrationSpecStatus, ab as IntegrationSpecValidationIssue, ac as IntegrationSpecValidationResult, ad as NoneAuthSpec, ae as NormalizedPermission, af as OAuth2AuthSpec, ag as PermissionDescriptor, ah as PostSetupCheck, ai as Quirk, aj as RenderSpecOptions, ak as RenderedConsoleStep, al as ScopeDescriptor, am as assertValidIntegrationSpec, an as buildHealthcheckPlan, ao as consoleStepsToText, ap as getIntegrationFamily, aq as getIntegrationSpec, ar as integrationSpecToConnector, as as listExecutableIntegrationSpecs, at as listIntegrationSpecs, au as renderAgentToolDescription, av as renderConsoleSteps, aw as renderRunbookMarkdown, ax as specAuthToConnectorAuth, ay as validateCredentialFormat, az as validateCredentialSet, aA as validateIntegrationSpec } from './registry.js';
-import './index-D4D4CEKX.js';
+import './tangle-id-CTU4kGId.js';
+import './errors-Bg3_rxnQ.js';
+import './connect/index.js';
+import './middleware/index.js';
 import './connectors/index.js';
+import './connectors/adapters/index.js';
 import 'node:http';