@contractspec/integration.runtime 2.9.0 → 3.0.0

package/dist/channel/dispatcher.d.ts

@@ -0,0 +1,37 @@
+import type { ChannelOutboxActionRecord } from './types';
+import type { ChannelRuntimeStore } from './store';
+import type { ChannelTelemetryEmitter } from './telemetry';
+export interface DispatchSendResult {
+    providerMessageId?: string;
+    responseStatus?: number;
+    responseBody?: string;
+}
+export interface ChannelMessageSender {
+    send(action: ChannelOutboxActionRecord): Promise<DispatchSendResult>;
+}
+export interface ChannelOutboxDispatcherOptions {
+    batchSize?: number;
+    maxRetries?: number;
+    baseBackoffMs?: number;
+    jitter?: boolean;
+    now?: () => Date;
+    telemetry?: ChannelTelemetryEmitter;
+}
+export interface ChannelDispatchSummary {
+    claimed: number;
+    sent: number;
+    retried: number;
+    deadLettered: number;
+}
+export declare class ChannelOutboxDispatcher {
+    private readonly store;
+    private readonly batchSize;
+    private readonly maxRetries;
+    private readonly baseBackoffMs;
+    private readonly jitter;
+    private readonly now;
+    private readonly telemetry?;
+    constructor(store: ChannelRuntimeStore, options?: ChannelOutboxDispatcherOptions);
+    dispatchBatch(resolveSender: (providerKey: string) => ChannelMessageSender | null | Promise<ChannelMessageSender | null>, limit?: number): Promise<ChannelDispatchSummary>;
+    private calculateBackoffMs;
+}

package/dist/channel/dispatcher.js

@@ -0,0 +1,130 @@
+// @bun
+// src/channel/dispatcher.ts
+class ChannelOutboxDispatcher {
+  store;
+  batchSize;
+  maxRetries;
+  baseBackoffMs;
+  jitter;
+  now;
+  telemetry;
+  constructor(store, options = {}) {
+    this.store = store;
+    this.batchSize = Math.max(1, options.batchSize ?? 20);
+    this.maxRetries = Math.max(1, options.maxRetries ?? 3);
+    this.baseBackoffMs = Math.max(100, options.baseBackoffMs ?? 1000);
+    this.jitter = options.jitter ?? true;
+    this.now = options.now ?? (() => new Date);
+    this.telemetry = options.telemetry;
+  }
+  async dispatchBatch(resolveSender, limit) {
+    const actions = await this.store.claimPendingOutboxActions(Math.max(1, limit ?? this.batchSize), this.now());
+    const summary = {
+      claimed: actions.length,
+      sent: 0,
+      retried: 0,
+      deadLettered: 0
+    };
+    for (const action of actions) {
+      const startedAtMs = Date.now();
+      try {
+        const sender = await resolveSender(action.providerKey);
+        if (!sender) {
+          throw Object.assign(new Error("No sender configured for provider"), {
+            code: "SENDER_NOT_CONFIGURED"
+          });
+        }
+        const sendResult = await sender.send(action);
+        const latencyMs = Date.now() - startedAtMs;
+        await this.store.recordDeliveryAttempt({
+          actionId: action.id,
+          attempt: action.attemptCount,
+          responseStatus: sendResult.responseStatus,
+          responseBody: sendResult.responseBody,
+          latencyMs
+        });
+        await this.store.markOutboxSent(action.id, sendResult.providerMessageId);
+        summary.sent += 1;
+        this.telemetry?.record({
+          stage: "dispatch",
+          status: "sent",
+          workspaceId: action.workspaceId,
+          providerKey: action.providerKey,
+          actionId: action.id,
+          attempt: action.attemptCount,
+          latencyMs
+        });
+      } catch (error) {
+        const latencyMs = Date.now() - startedAtMs;
+        const errorCode = getErrorCode(error);
+        const errorMessage = error instanceof Error ? error.message : String(error);
+        await this.store.recordDeliveryAttempt({
+          actionId: action.id,
+          attempt: action.attemptCount,
+          responseBody: errorMessage,
+          latencyMs
+        });
+        if (action.attemptCount >= this.maxRetries) {
+          await this.store.markOutboxDeadLetter({
+            actionId: action.id,
+            lastErrorCode: errorCode,
+            lastErrorMessage: errorMessage
+          });
+          summary.deadLettered += 1;
+          this.telemetry?.record({
+            stage: "dispatch",
+            status: "dead_letter",
+            workspaceId: action.workspaceId,
+            providerKey: action.providerKey,
+            actionId: action.id,
+            attempt: action.attemptCount,
+            latencyMs,
+            metadata: {
+              errorCode
+            }
+          });
+        } else {
+          const nextAttemptAt = new Date(this.now().getTime() + this.calculateBackoffMs(action.attemptCount));
+          await this.store.markOutboxRetry({
+            actionId: action.id,
+            nextAttemptAt,
+            lastErrorCode: errorCode,
+            lastErrorMessage: errorMessage
+          });
+          summary.retried += 1;
+          this.telemetry?.record({
+            stage: "dispatch",
+            status: "retry",
+            workspaceId: action.workspaceId,
+            providerKey: action.providerKey,
+            actionId: action.id,
+            attempt: action.attemptCount,
+            latencyMs,
+            metadata: {
+              errorCode
+            }
+          });
+        }
+      }
+    }
+    return summary;
+  }
+  calculateBackoffMs(attempt) {
+    const exponent = Math.max(0, attempt - 1);
+    const base = this.baseBackoffMs * Math.pow(2, exponent);
+    if (!this.jitter) {
+      return Math.round(base);
+    }
+    const jitterFactor = 0.8 + Math.random() * 0.4;
+    return Math.round(base * jitterFactor);
+  }
+}
+function getErrorCode(error) {
+  if (typeof error === "object" && error !== null && "code" in error && typeof error.code === "string") {
+    return error.code;
+  }
+  return "DISPATCH_FAILED";
+}
+export {
+  ChannelOutboxDispatcher
+};

package/dist/channel/dispatcher.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/channel/github.d.ts

@@ -0,0 +1,47 @@
+import type { ChannelInboundEvent } from './types';
+export interface GithubIssueCommentPayload {
+    action?: string;
+    repository?: {
+        full_name?: string;
+        name?: string;
+        owner?: {
+            login?: string;
+        };
+    };
+    issue?: {
+        number?: number;
+        body?: string;
+    };
+    pull_request?: {
+        number?: number;
+        body?: string;
+    };
+    comment?: {
+        id?: number;
+        body?: string;
+    };
+    sender?: {
+        login?: string;
+    };
+}
+export interface GithubSignatureVerificationInput {
+    webhookSecret: string;
+    signatureHeader: string | null;
+    rawBody: string;
+}
+export interface GithubSignatureVerificationResult {
+    valid: boolean;
+    reason?: string;
+}
+export declare function verifyGithubSignature(input: GithubSignatureVerificationInput): GithubSignatureVerificationResult;
+export declare function parseGithubWebhookPayload(rawBody: string): GithubIssueCommentPayload;
+export interface NormalizeGithubEventInput {
+    workspaceId: string;
+    payload: GithubIssueCommentPayload;
+    deliveryId: string;
+    eventName: string;
+    signatureValid: boolean;
+    traceId?: string;
+    rawBody?: string;
+}
+export declare function normalizeGithubInboundEvent(input: NormalizeGithubEventInput): ChannelInboundEvent | null;

package/dist/channel/github.js

@@ -0,0 +1,58 @@
+// @bun
+// src/channel/github.ts
+import { createHmac, timingSafeEqual } from "crypto";
+function verifyGithubSignature(input) {
+  if (!input.signatureHeader) {
+    return { valid: false, reason: "missing_signature" };
+  }
+  const expected = `sha256=${createHmac("sha256", input.webhookSecret).update(input.rawBody).digest("hex")}`;
+  const expectedBuffer = Buffer.from(expected, "utf8");
+  const providedBuffer = Buffer.from(input.signatureHeader, "utf8");
+  if (expectedBuffer.length !== providedBuffer.length) {
+    return { valid: false, reason: "signature_length_mismatch" };
+  }
+  return timingSafeEqual(expectedBuffer, providedBuffer) ? { valid: true } : { valid: false, reason: "signature_mismatch" };
+}
+function parseGithubWebhookPayload(rawBody) {
+  return JSON.parse(rawBody);
+}
+function normalizeGithubInboundEvent(input) {
+  const owner = input.payload.repository?.owner?.login;
+  const repo = input.payload.repository?.name;
+  const issueNumber = input.payload.issue?.number ?? input.payload.pull_request?.number;
+  const messageText = input.payload.comment?.body ?? input.payload.issue?.body ?? input.payload.pull_request?.body;
+  if (!owner || !repo || !issueNumber || !messageText) {
+    return null;
+  }
+  return {
+    workspaceId: input.workspaceId,
+    providerKey: "messaging.github",
+    externalEventId: input.deliveryId,
+    eventType: `github.${input.eventName}.${input.payload.action ?? "unknown"}`,
+    occurredAt: new Date,
+    signatureValid: input.signatureValid,
+    traceId: input.traceId,
+    rawPayload: input.rawBody,
+    thread: {
+      externalThreadId: `${owner}/${repo}#${issueNumber}`,
+      externalChannelId: `${owner}/${repo}`,
+      externalUserId: input.payload.sender?.login
+    },
+    message: {
+      text: messageText,
+      externalMessageId: input.payload.comment?.id != null ? String(input.payload.comment.id) : undefined
+    },
+    metadata: {
+      owner,
+      repo,
+      issueNumber: String(issueNumber),
+      action: input.payload.action ?? "unknown",
+      githubEvent: input.eventName
+    }
+  };
+}
+export {
+  verifyGithubSignature,
+  parseGithubWebhookPayload,
+  normalizeGithubInboundEvent
+};

package/dist/channel/github.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/channel/index.d.ts

@@ -0,0 +1,14 @@
+export * from './types';
+export * from './policy';
+export * from './store';
+export * from './memory-store';
+export * from './telemetry';
+export * from './service';
+export * from './dispatcher';
+export * from './slack';
+export * from './github';
+export * from './whatsapp-meta';
+export * from './whatsapp-twilio';
+export * from './postgres-schema';
+export * from './postgres-store';
+export * from './replay-fixtures';