@openlup/platform 0.16.0 → 0.18.0

package/src/communications/resend/index.ts

@@ -0,0 +1,350 @@
+import { createHmac, timingSafeEqual } from "node:crypto";
+import { createGuardedEmailTransport, type EmailEgressPolicy, type EmailEgressContext } from "../emailEgress.js";
+import type { EmailMessage, EmailSendResult, EmailTransport } from "../emailTransport.js";
+import { processEmailObservation, type EmailObservationPort } from "../emailObservation.js";
+import { runDeliveryReconciliation, type DeliveryReconciliationPort, type DeliveryReconciliationResult } from "../deliveryReconciliation.js";
+
+/** Opt-in Node sender. Every send obtains a fresh validated host egress decision. */
+export function createResendTransport(input: {
+  policy: EmailEgressPolicy;
+  environmentTagName: string;
+  fetch?: typeof fetch;
+}): EmailTransport {
+  return createGuardedEmailTransport({
+    providerKind: "resend",
+    policy: input.policy,
+    send: (message, context) => postResendEmail(message, context, input.environmentTagName, input.fetch ?? fetch),
+  });
+}
+
+const RESEND_ENDPOINT = "https://api.resend.com/emails";
+const PROVIDER_ERROR_MAX = 240;
+const PROVIDER_ERROR_CODE_MAX = 80;
+const EMAIL_ADDRESS_PATTERN = /[A-Z0-9._%+-]+@[A-Z0-9.-]+\.[A-Z]{2,}/gi;
+
+function truncate(value: string, max: number): string {
+  return value.length > max ? `${value.slice(0, max - 1)}...` : value;
+}
+
+function sanitizeProviderText(value: string): string {
+  return truncate(value.replace(EMAIL_ADDRESS_PATTERN, "[email]").replace(/\s+/g, " ").trim(), PROVIDER_ERROR_MAX);
+}
+
+function sanitizeProviderCode(value: string): string {
+  return truncate(value.replace(/[^A-Za-z0-9._:-]/g, "_"), PROVIDER_ERROR_CODE_MAX);
+}
+
+function providerErrorFromBody(body: Record<string, unknown>, httpStatus: number): string {
+  const errField = body.error;
+  if (typeof errField === "string") return sanitizeProviderText(errField);
+  if (errField && typeof errField === "object") {
+    const message = (errField as Record<string, unknown>).message;
+    if (typeof message === "string") return sanitizeProviderText(message);
+  }
+  if (typeof body.message === "string") return sanitizeProviderText(body.message);
+  return `Resend HTTP ${httpStatus}`;
+}
+
+function providerErrorCodeFromBody(body: Record<string, unknown>): string | null {
+  const errField = body.error;
+  const errorRecord = errField && typeof errField === "object"
+    ? (errField as Record<string, unknown>)
+    : {};
+  const candidates = [
+    errorRecord.code,
+    errorRecord.name,
+    errorRecord.type,
+    body.code,
+    body.name,
+    body.type,
+  ];
+  const value = candidates.find((candidate) => typeof candidate === "string" && candidate.trim() !== "");
+  return typeof value === "string" ? sanitizeProviderCode(value) : null;
+}
+
+function providerErrorResponse(body: Record<string, unknown>, httpStatus: number): Record<string, unknown> {
+  const providerErrorMessage = providerErrorFromBody(body, httpStatus);
+  const providerErrorCode = providerErrorCodeFromBody(body);
+  return {
+    http_status: httpStatus,
+    provider_error_message: providerErrorMessage,
+    ...(providerErrorCode ? { provider_error_code: providerErrorCode } : {}),
+  };
+}
+
+async function postResendEmail(
+  input: EmailMessage, context: Readonly<EmailEgressContext>, environmentTagName: string, fetcher: typeof fetch,
+): Promise<EmailSendResult> {
+  const headers: Record<string, string> = {
+    Authorization: `Bearer ${context.credential}`,
+    "Content-Type": "application/json",
+  };
+  if (input.idempotencyKey !== undefined) headers["Idempotency-Key"] = input.idempotencyKey;
+  if (context.mode === "sandbox_sink") headers["X-Original-Recipient"] = context.intendedRecipient;
+  try {
+    const res = await fetcher(RESEND_ENDPOINT, {
+      method: "POST",
+      headers,
+      body: JSON.stringify({
+        from: input.from,
+        to: [context.recipient],
+        subject: input.subject,
+        html: input.html,
+        ...(input.text === undefined ? {} : { text: input.text }),
+        ...(input.replyTo === undefined ? {} : { reply_to: input.replyTo }),
+        ...(input.attachments === undefined ? {} : { attachments: input.attachments }),
+        tags: [{
+          name: environmentTagName,
+          value: context.environmentTag,
+        }],
+      }),
+      signal: input.signal,
+    });
+    const parsed = await res.json().catch(() => ({}));
+    const body = typeof parsed === "object" && parsed !== null
+      ? (parsed as Record<string, unknown>)
+      : {};
+    if (!res.ok) {
+      const providerErrorMessage = providerErrorFromBody(body, res.status);
+      const providerErrorCode = providerErrorCodeFromBody(body);
+      return {
+        outcome: {
+          ok: false,
+          resendId: null,
+          httpStatus: res.status,
+          providerError: providerErrorMessage,
+          providerErrorCode,
+          aborted: false,
+          egressMode: context.mode,
+          egressReason: context.reason,
+        },
+        providerResponse: providerErrorResponse(body, res.status),
+      };
+    }
+    const id = typeof body.id === "string" ? body.id : null;
+    return {
+      outcome: {
+        ok: true,
+        resendId: id,
+        httpStatus: res.status,
+        providerError: null,
+        aborted: false,
+        egressMode: context.mode,
+        egressReason: context.reason,
+      },
+      providerResponse: { id },
+    };
+  } catch (err) {
+    const aborted =
+      input.signal?.aborted === true ||
+      (err instanceof Error && err.name === "AbortError");
+    const msg = err instanceof Error ? err.message : String(err);
+    return {
+      outcome: {
+        ok: false,
+        resendId: null,
+        httpStatus: 0,
+        providerError: sanitizeProviderText(msg),
+        aborted,
+        egressMode: context.mode,
+        egressReason: context.reason,
+      },
+      providerResponse: { exception: true, aborted },
+    };
+  }
+}
+
+interface ResendEmailReadResult {
+  ok: boolean;
+  httpStatus: number;
+  lastEvent: string | null;
+  recipientEmail: string | null;
+  providerError: string | null;
+}
+
+function readFirstRecipient(value: unknown): string | null {
+  if (typeof value === "string" && value.includes("@")) return value;
+  if (!Array.isArray(value)) return null;
+  return value.find((recipient): recipient is string =>
+    typeof recipient === "string" && recipient.includes("@")
+  ) ?? null;
+}
+
+// Read-only status retrieval for the delivery reconciliation poller
+// (docs/platform/RUNTIME_AND_SELF_HOSTING.md Wave 4). No egress gating needed: this never
+// sends mail — it only reads the provider's view of an already-sent message.
+async function getResendEmail(input: {
+  apiKey: string;
+  resendId: string;
+  signal?: AbortSignal;
+}, fetcher: typeof fetch): Promise<ResendEmailReadResult> {
+  try {
+    const res = await fetcher(`${RESEND_ENDPOINT}/${encodeURIComponent(input.resendId)}`, {
+      method: "GET",
+      headers: { Authorization: `Bearer ${input.apiKey}` },
+      signal: input.signal,
+    });
+    const parsed = (await res.json().catch(() => ({}))) as Record<string, unknown>;
+    if (!res.ok) {
+      return {
+        ok: false,
+        httpStatus: res.status,
+        lastEvent: null,
+        recipientEmail: null,
+        providerError: providerErrorFromBody(parsed, res.status),
+      };
+    }
+    const lastEvent = typeof parsed.last_event === "string" ? parsed.last_event : null;
+    return {
+      ok: true,
+      httpStatus: res.status,
+      lastEvent,
+      recipientEmail: readFirstRecipient(parsed.to),
+      providerError: null,
+    };
+  } catch (error) {
+    return {
+      ok: false,
+      httpStatus: 0,
+      lastEvent: null,
+      recipientEmail: null,
+      providerError: error instanceof Error ? sanitizeProviderCode(error.message) : "fetch_failed",
+    };
+  }
+}
+
+/** Poll existing IDs through the neutral runner; never retries a send. */
+export function runResendDeliveryReconciliation(input: {
+  port: DeliveryReconciliationPort;
+  now: string;
+  graceMinutes: number;
+  limit: number;
+  apiKey: string;
+  fetch?: typeof fetch;
+  signal?: AbortSignal;
+}): Promise<DeliveryReconciliationResult> {
+  return runDeliveryReconciliation({
+    port: input.port, now: input.now, graceMinutes: input.graceMinutes, limit: input.limit,
+    readEmail: messageId => getResendEmail({ apiKey: input.apiKey, resendId: messageId, signal: input.signal }, input.fetch ?? fetch),
+    observationFor: read => {
+      const status = read.lastEvent;
+      if (!status || !["delivered", "delivery_delayed", "bounced", "complained", "failed"].includes(status)) return null;
+      return { eventType: `email.${status}`, terminal: ["bounced", "complained", "failed"].includes(status) };
+    },
+  });
+}
+
+const eventKinds = new Map([
+  ["email.sent", "sent"], ["email.delivered", "delivered"], ["email.delivery_delayed", "delivery_delayed"],
+  ["email.opened", "open"], ["email.clicked", "click"], ["email.bounced", "bounce"],
+  ["email.complained", "complaint"], ["email.failed", "failed"], ["email.suppressed", "suppressed"], ["email.scheduled", "scheduled"],
+]);
+
+/** Authenticate untouched bytes before decoding. now returns UTC seconds; receiver defaults to non-production. */
+export function createResendWebhookHandler(input: {
+  port: EmailObservationPort;
+  webhookSecret: string;
+  environmentTagName: string;
+  resolveReceiverEnvironmentTag?: () => "production" | "non_production";
+  now?: () => number;
+  receivedAt?: () => Date;
+}): (request: {
+  method?: string;
+  rawBody: string | Uint8Array;
+  headers: { webhookId?: string; timestamp?: string; signature?: string };
+}) => Promise<{ status: number; body: Record<string, unknown> | "ok" }> {
+  return async request => {
+    if (request.method === "OPTIONS") return { status: 200, body: "ok" };
+    if (!verifyResendWebhookSignature({ ...request.headers, rawBody: request.rawBody, secret: input.webhookSecret, now: input.now })) {
+      return { status: 401, body: { error: "Invalid signature" } };
+    }
+    try {
+      const payload: unknown = JSON.parse(typeof request.rawBody === "string" ? request.rawBody : Buffer.from(request.rawBody).toString("utf8"));
+      const type = isRecord(payload) ? payload.type : null;
+      const data = isRecord(payload) ? payload.data : null;
+      if (typeof type !== "string" || !eventKinds.has(type)) return { status: 200, body: { ignored: true } };
+      const messageId = isRecord(data) && typeof data.email_id === "string" ? data.email_id : null;
+      if (!messageId) return { status: 200, body: { ignored: true, reason: "missing_email_id" } };
+      const tag = readEnvironmentTag(data, input.environmentTagName);
+      if (tag && tag !== (input.resolveReceiverEnvironmentTag?.() ?? "non_production")) {
+        return { status: 200, body: { ignored: true, reason: "foreign_send_not_found" } };
+      }
+      const disposition = await processEmailObservation({
+        port: input.port, messageId,
+        observation: () => {
+          const time = resolveEventTime(isRecord(payload) ? payload.created_at : null, request.headers.timestamp, input.receivedAt?.() ?? new Date());
+          return { eventType: type, eventAt: time.eventAt, metadata: {
+            providerEventId: request.headers.webhookId ?? null, eventMetadata: data ?? {},
+            link: isRecord(data) && isRecord(data.click) && typeof data.click.link === "string" ? data.click.link : null,
+            source: "resend-webhook", eventTimeSource: time.source,
+          } };
+        },
+      });
+      return disposition.outcome === "send_not_found"
+        ? { status: 200, body: { ignored: true, reason: "send_not_found" } }
+        : { status: 200, body: { success: true } };
+    } catch {
+      return { status: 500, body: { error: "Webhook processing failed" } };
+    }
+  };
+}
+
+function isRecord(value: unknown): value is Record<string, unknown> {
+  return Boolean(value && typeof value === "object" && !Array.isArray(value));
+}
+function readEnvironmentTag(data: unknown, tagName: string): "production" | "non_production" | null {
+  if (!isRecord(data)) return null;
+  const tags = data.tags;
+  const value = Array.isArray(tags)
+    ? tags.find(entry => isRecord(entry) && entry.name === tagName)?.value
+    : isRecord(tags) ? tags[tagName] : null;
+  return value === "production" || value === "non_production" ? value : null;
+}
+function resolveEventTime(createdAt: unknown, timestamp: string | undefined, receivedAt: Date) {
+  if (typeof createdAt === "string" && Number.isFinite(Date.parse(createdAt))) {
+    return { eventAt: new Date(createdAt).toISOString(), source: "provider_created_at" };
+  }
+  const seconds = Number(timestamp);
+  if (Number.isFinite(seconds) && seconds > 0) return { eventAt: new Date(seconds * 1000).toISOString(), source: "svix_timestamp" };
+  return { eventAt: receivedAt.toISOString(), source: "received_at" };
+}
+
+function verifyResendWebhookSignature(input: { rawBody: string | Uint8Array; webhookId?: string; timestamp?: string; signature?: string; secret: string; now?: () => number }): boolean {
+  const { webhookId, timestamp, signature, rawBody, secret } = input;
+  if (!webhookId || !timestamp || !signature || !secret) return false;
+
+  const timestampSeconds = Number(timestamp);
+  if (!Number.isFinite(timestampSeconds)) return false;
+  const now = input.now ?? (() => Math.floor(Date.now() / 1000));
+  if (Math.abs(now() - timestampSeconds) > 300) return false;
+
+  const secretKey = signingSecret(secret);
+  if (secretKey === null) return false;
+
+  const expected = createHmac("sha256", secretKey)
+    .update(`${webhookId}.${timestamp}.`).update(rawBody)
+    .digest("base64");
+  return signature.split(" ").some((member) =>
+    timingSafeStringEqual(member, `v1,${expected}`) || timingSafeStringEqual(member, expected));
+}
+
+function signingSecret(secret: string): Buffer | string | null {
+  if (!secret.startsWith("whsec_")) return secret;
+  // Svix encodes endpoint secrets after the whsec_ prefix. Buffer preserves the
+  // decoded bytes for node:crypto rather than treating the base64 text as a key.
+  // Buffer.from(base64) is deliberately permissive, so reject empty, malformed,
+  // or non-canonical input before it can silently become an empty/partial key.
+  const encoded = secret.slice("whsec_".length);
+  if (!encoded || !/^[A-Za-z0-9+/]+={0,2}$/.test(encoded) || encoded.length % 4 === 1) return null;
+  const decoded = Buffer.from(encoded, "base64");
+  if (decoded.length === 0) return null;
+  const canonicalPadded = decoded.toString("base64");
+  const canonicalUnpadded = canonicalPadded.replace(/=+$/, "");
+  return encoded === canonicalPadded || encoded === canonicalUnpadded ? decoded : null;
+}
+
+function timingSafeStringEqual(left: string, right: string): boolean {
+  const leftBuffer = Buffer.from(left);
+  const rightBuffer = Buffer.from(right);
+  return leftBuffer.length === rightBuffer.length && timingSafeEqual(leftBuffer, rightBuffer);
+}

package/src/communications/shipmentNotifications.ts

@@ -0,0 +1,78 @@
+import { z } from "./validation.js";
+
+export const shipmentNotificationEventSchema = z
+  .object({
+    orderId: z.guid(),
+    clientId: z.guid(),
+    // Preserve published declaration order without changing runtime enum options.
+    status: z.enum(["dispatched", "shipped", "delivered", "exception"]) as z.ZodEnum<{
+      delivered: "delivered";
+      exception: "exception";
+      dispatched: "dispatched";
+      shipped: "shipped";
+    }>,
+    trackingNumbers: z.array(z.string().trim().min(1).max(160)).max(20),
+    trackingReferences: z
+      .array(
+        z
+          .object({
+            providerKind: z.string().trim().min(1).max(80),
+            carrierKind: z.string().trim().min(1).max(80).nullable(),
+            service: z.string().trim().min(1).max(120).nullable(),
+            trackingNumber: z.string().trim().min(1).max(160),
+            trackingUrl: z.string().url().max(500).nullable(),
+          })
+          .strict(),
+      )
+      .max(20)
+      .optional(),
+    trackingUrl: z.string().url().max(500).nullable(),
+    occurredAt: z.string().datetime({ offset: true }),
+  })
+  .strict();
+
+export const shipmentNotificationPlanSchema = z
+  .object({
+    templateSlug: z.enum([
+      "commerce-shipment-dispatched",
+      "commerce-shipment-delivered",
+      "commerce-shipment-exception",
+    ]),
+    source: z.literal("shipment-status"),
+    idempotencyKey: z.string().min(1).max(200),
+    shouldNotifyCustomer: z.boolean(),
+  })
+  .strict();
+
+export function planShipmentNotification(
+  event: ShipmentNotificationEvent,
+): ShipmentNotificationPlan {
+  const templateSlug = templateForStatus(event.status);
+  return {
+    templateSlug,
+    source: "shipment-status",
+    idempotencyKey: [
+      "shipment-status",
+      event.orderId,
+      event.status,
+      trackingNumbersForIdempotency(event).join(","),
+      event.occurredAt,
+    ].join(":"),
+    shouldNotifyCustomer: event.status !== "shipped" || trackingNumbersForIdempotency(event).length > 0,
+  };
+}
+
+function templateForStatus(
+  status: ShipmentNotificationEvent["status"],
+): ShipmentNotificationPlan["templateSlug"] {
+  if (status === "delivered") return "commerce-shipment-delivered";
+  if (status === "exception") return "commerce-shipment-exception";
+  return "commerce-shipment-dispatched";
+}
+
+function trackingNumbersForIdempotency(event: ShipmentNotificationEvent): string[] {
+  return event.trackingReferences?.map((ref) => ref.trackingNumber) ?? event.trackingNumbers;
+}
+
+export type ShipmentNotificationEvent = z.infer<typeof shipmentNotificationEventSchema>;
+export type ShipmentNotificationPlan = z.infer<typeof shipmentNotificationPlanSchema>;

package/src/communications/sql.ts

@@ -0,0 +1,7 @@
+/** Sparse projections of canonical units, never an install chain. */
+export const COMMUNICATIONS_MIGRATIONS = [
+  { id: "20260807190000_comms_outbox_rail", catalogPath: "db/platform/migrations/20260807190000_comms_outbox_rail.sql", position: 2, sha256: "dfb3e9808714846738222bb74a1bfdb38ceafdde2ca8a0c71ab835739fb333bd", url: new URL("../../sql/20260807190000_comms_outbox_rail.sql", import.meta.url) },
+  { id: "20260810120001_transactional_delivery_receipts", catalogPath: "db/platform/migrations/20260810120001_transactional_delivery_receipts.sql", position: 9, sha256: "a157f075f8684c29958c565239c19a55894bffaaff4fd80e04ee689c926e33f7", url: new URL("../../sql/20260810120001_transactional_delivery_receipts.sql", import.meta.url) },
+  { id: "20260813120000_communications_control_plane", catalogPath: "db/platform/migrations/20260813120000_communications_control_plane.sql", position: 20, sha256: "dea5fe631f1329272989e1598f6f48aeb6ce67fa070ddeb0200f69f62fcd972a", url: new URL("../../sql/20260813120000_communications_control_plane.sql", import.meta.url) },
+  { id: "20261019200000_communications_native_operations", catalogPath: "db/platform/migrations/20261019200000_communications_native_operations.sql", position: 70, sha256: "1d28380f12324c3bcccaa5a6d38c22e72332c7992bbb1f90651774dfc5e24982", url: new URL("../../sql/20261019200000_communications_native_operations.sql", import.meta.url) },
+] as const;

package/src/communications/standardWebhooks.ts

@@ -0,0 +1,84 @@
+/**
+ * Node-native Standard Webhooks verifier for the inactive Auth email candidate.
+ * It intentionally mirrors the deployed Edge algorithm: `id.timestamp.rawBody`
+ * is signed with a decoded `whsec_` key and any space-separated v1 signature may
+ * match. Keep this independent of deployable Edge packaging.
+ */
+import { createHmac } from "node:crypto";
+
+const DEFAULT_TOLERANCE_SECONDS = 5 * 60;
+
+export interface StandardWebhookHeaders {
+  id: string | null;
+  timestamp: string | null;
+  signature: string | null;
+}
+
+export function timingSafeEqual(a: string, b: string): boolean {
+  if (a.length !== b.length) return false;
+  let diff = 0;
+  for (let index = 0; index < a.length; index += 1) diff |= a.charCodeAt(index) ^ b.charCodeAt(index);
+  return diff === 0;
+}
+
+export function standardWebhookKeyBytes(secret: string): Uint8Array {
+  let value = secret.trim();
+  if (!value) throw new Error("standard_webhook_secret_empty");
+  if (value.startsWith("v1,")) value = value.slice("v1,".length);
+  if (value.startsWith("whsec_")) {
+    const decoded = decodeStandardWebhookKey(value.slice("whsec_".length));
+    // An empty `whsec_` would make a publicly reproducible empty-key HMAC. It
+    // is not a usable Standard Webhooks secret even though it is valid base64.
+    if (decoded.length === 0) throw new Error("standard_webhook_secret_empty");
+    return Uint8Array.from(decoded, (character) => character.charCodeAt(0));
+  }
+  return new TextEncoder().encode(value);
+}
+
+function decodeStandardWebhookKey(base64: string): string {
+  if (base64.length === 0) return "";
+  if (!/^[A-Za-z0-9+/]+={0,2}$/.test(base64) || base64.length % 4 === 1) {
+    throw new Error("standard_webhook_secret_invalid_base64");
+  }
+  const decoded = atob(base64);
+  const canonicalPadded = Buffer.from(decoded, "latin1").toString("base64");
+  const canonicalUnpadded = canonicalPadded.replace(/=+$/, "");
+  if (base64 !== canonicalPadded && base64 !== canonicalUnpadded) {
+    throw new Error("standard_webhook_secret_invalid_base64");
+  }
+  return decoded;
+}
+
+async function hmacSha256Base64(keyBytes: Uint8Array, message: string): Promise<string> {
+  return createHmac("sha256", Buffer.from(keyBytes)).update(message).digest("base64");
+}
+
+export async function verifyStandardWebhookSignature(opts: {
+  headers: StandardWebhookHeaders;
+  rawBody: string;
+  secret: string;
+  toleranceSeconds?: number;
+  now?: () => number;
+}): Promise<boolean> {
+  const { headers, rawBody, secret } = opts;
+  if (!secret || !headers.id || !headers.timestamp || !headers.signature) return false;
+  const timestampSeconds = Number(headers.timestamp);
+  if (!Number.isFinite(timestampSeconds)) return false;
+  const nowSeconds = Math.floor((opts.now?.() ?? Date.now()) / 1000);
+  if (Math.abs(nowSeconds - timestampSeconds) > (opts.toleranceSeconds ?? DEFAULT_TOLERANCE_SECONDS)) return false;
+  let expected: string;
+  try {
+    expected = await hmacSha256Base64(
+      standardWebhookKeyBytes(secret),
+      `${headers.id}.${headers.timestamp}.${rawBody}`,
+    );
+  } catch {
+    // A malformed whsec_ value is an invalid verification key, never a reason
+    // to bypass signature verification or surface an unhandled request error.
+    return false;
+  }
+  return headers.signature
+    .split(" ")
+    .map((part) => (part.includes(",") ? part.slice(part.indexOf(",") + 1) : part))
+    .some((candidate) => timingSafeEqual(candidate, expected));
+}

package/src/communications/status.ts

@@ -0,0 +1,51 @@
+import type { EmailSendDecision, EmailSendStatus } from "./contracts/types.js";
+
+const TERMINAL_EMAIL_STATUSES = new Set<EmailSendStatus>([
+  "bounced",
+  "complained",
+  "failed",
+  "skipped",
+]);
+
+export function isTerminalEmailSendStatus(status: string | null): status is EmailSendStatus {
+  return status !== null && TERMINAL_EMAIL_STATUSES.has(status as EmailSendStatus);
+}
+
+export function buildEmailSendDedupeKey(input: {
+  recipientId: string;
+  templateSlug: string;
+}): string {
+  return `email:${input.recipientId.trim()}:${input.templateSlug.trim()}`;
+}
+
+export function decideEmailSend(input: {
+  sequencePaused: boolean | null;
+  existingNonFailedMessageId: string | null;
+  templateAvailable: boolean;
+}): EmailSendDecision {
+  if (input.sequencePaused) {
+    return {
+      outcome: "skip",
+      reason: "sequence_paused",
+      existingMessageId: null,
+    };
+  }
+
+  if (input.existingNonFailedMessageId) {
+    return {
+      outcome: "skip",
+      reason: "already_sent",
+      existingMessageId: input.existingNonFailedMessageId,
+    };
+  }
+
+  if (!input.templateAvailable) {
+    return {
+      outcome: "skip",
+      reason: "template_unavailable",
+      existingMessageId: null,
+    };
+  }
+
+  return { outcome: "send" };
+}

package/src/communications/transactionalDelivery.ts

@@ -0,0 +1,114 @@
+import { isTransactionalDeliveryIdentifier } from "./transactionalDeliveryIdentifier.js";
+import { createHash } from "node:crypto";
+
+import type {
+  CapturedTransactionalDeliveryPort,
+  TransactionalDeliveryCommand,
+  TransactionalDeliveryReceipt,
+  TransactionalDeliveryReceiptStore,
+} from "./contracts/transactionalDelivery.js";
+
+const FINGERPRINT = /^[a-f0-9]{64}$/;
+const FAILURE_CODE = /^[a-z][a-z0-9_.-]{0,127}$/;
+
+export class TransactionalDeliveryValidationError extends Error {
+  constructor() {
+    super("transactional_delivery_command_invalid");
+  }
+}
+
+export class TransactionalDeliveryConflictError extends Error {
+  constructor() {
+    super("transactional_delivery_command_conflict");
+  }
+}
+
+export class TransactionalDeliveryUnavailableError extends Error {
+  constructor() {
+    super("transactional_delivery_unavailable");
+  }
+}
+
+function fingerprint(command: TransactionalDeliveryCommand): string {
+  return createHash("sha256")
+    .update(JSON.stringify({
+      recipientReference: command.recipientReference,
+      templateReference: command.templateReference,
+      accessGrantReference: command.accessGrantReference ?? null,
+    }))
+    .digest("hex");
+}
+
+function validate(command: TransactionalDeliveryCommand): void {
+  if (!isTransactionalDeliveryIdentifier(command.idempotencyKey)
+    || !isTransactionalDeliveryIdentifier(command.recipientReference)
+    || !isTransactionalDeliveryIdentifier(command.templateReference)
+    || (command.accessGrantReference !== undefined
+      && !isTransactionalDeliveryIdentifier(command.accessGrantReference))) {
+    throw new TransactionalDeliveryValidationError();
+  }
+}
+
+function accepted(
+  receipt: TransactionalDeliveryReceipt,
+  idempotencyKey: string,
+  commandFingerprint: string,
+): TransactionalDeliveryReceipt {
+  if (receipt.idempotencyKey !== idempotencyKey || receipt.commandFingerprint !== commandFingerprint
+    || receipt.state !== "accepted" || !isTransactionalDeliveryIdentifier(receipt.deliveryReference)
+    || !Number.isInteger(receipt.attemptCount) || receipt.attemptCount < 1) {
+    throw new Error("transactional_delivery_receipt_invalid");
+  }
+  return receipt;
+}
+
+/** One direct command, one captured delivery attempt, and one durable receipt transition. */
+export function createTransactionalDelivery(
+  deps: {
+    store: TransactionalDeliveryReceiptStore;
+    delivery: CapturedTransactionalDeliveryPort;
+  },
+  options: { fingerprint?: (command: TransactionalDeliveryCommand) => string } = {},
+): { send(command: TransactionalDeliveryCommand): Promise<TransactionalDeliveryReceipt> } {
+  const commandFingerprint = options.fingerprint ?? fingerprint;
+  return {
+    async send(command): Promise<TransactionalDeliveryReceipt> {
+      validate(command);
+      const digest = commandFingerprint(command);
+      if (!FINGERPRINT.test(digest)) throw new Error("transactional_delivery_fingerprint_invalid");
+      const prior = await deps.store.readReceipt(command.idempotencyKey);
+      if (prior) {
+        if (prior.commandFingerprint !== digest) throw new TransactionalDeliveryConflictError();
+        if (prior.state === "accepted") return accepted(prior, command.idempotencyKey, digest);
+      }
+
+      try {
+        const { deliveryReference } = await deps.delivery.deliver(command);
+        if (!isTransactionalDeliveryIdentifier(deliveryReference)) throw new Error("captured_delivery_reference_invalid");
+        try {
+          return accepted(await deps.store.recordAccepted({
+            idempotencyKey: command.idempotencyKey,
+            commandFingerprint: digest,
+            deliveryReference,
+          }), command.idempotencyKey, digest);
+        } catch {
+          // Delivery may already have happened. Never turn an accepted-write
+          // failure into a durable failed receipt for the same command.
+          throw new TransactionalDeliveryUnavailableError();
+        }
+      } catch (error) {
+        if (error instanceof TransactionalDeliveryUnavailableError) throw error;
+        try {
+          await deps.store.recordFailed({
+            idempotencyKey: command.idempotencyKey,
+            commandFingerprint: digest,
+            errorCode: "captured_delivery_failed",
+          });
+        } catch {
+          // The caller still receives the same sanitized unavailable result.
+        }
+        throw new TransactionalDeliveryUnavailableError();
+      }
+    },
+  };
+}