okengine 0.9.0 → 0.10.0

package/src/elements/channel/hard-bounce.test.ts

@@ -0,0 +1,82 @@
+/**
+ * Hard-bounce auto-suppression adversarial proofs:
+ * - ingestOutcome(hard-bounce) adds prior-bounce suppression
+ * - subsequent send is blocked before the transport is called
+ * - soft-bounce / complaint do not auto-suppress
+ */
+
+import { describe, expect, test } from "bun:test";
+import { channel, createChannelRuntime } from "../channel.ts";
+import { countingOkTransport, driverFromTransport } from "./test-helpers.ts";
+
+describe("hard-bounce auto-suppression", () => {
+  test("hard bounce auto-adds suppression and blocks the next send before transport", async () => {
+    const { transport, calls } = countingOkTransport("smtp");
+    const runtime = createChannelRuntime({
+      templates: [channel.template("news", { medium: "email" })],
+      drivers: [driverFromTransport("smtp", transport)],
+      catalog: { news: { en: { subject: "Hi", text: "Hello" } } },
+    });
+
+    const first = await runtime.send("news", { to: "bounce@example.com" });
+    expect(first.ok).toBe(true);
+    expect(calls.count).toBe(1);
+
+    const sent = runtime.receipts.all()[0]!;
+    runtime.ingestOutcome({
+      messageId: sent.messageId!,
+      state: "hard-bounce",
+      to: "bounce@example.com",
+      medium: "email",
+    });
+
+    const listed = runtime.suppression.list();
+    expect(
+      listed.some((e) => e.subject === "bounce@example.com" && e.reason === "prior-bounce"),
+    ).toBe(true);
+
+    const blocked = await runtime.send("news", { to: "bounce@example.com" });
+    expect(blocked.ok).toBe(false);
+    expect(blocked.driverId).toBe("suppression");
+    expect(blocked.attempts).toEqual([]);
+    expect(calls.count).toBe(1);
+
+    const last = runtime.receipts.all().at(-1)!;
+    expect(last.status).toBe("suppressed/prior-bounce");
+    expect(last.attempts).toEqual([]);
+  });
+
+  test("soft-bounce and complaint do not auto-add prior-bounce suppression", async () => {
+    const { transport, calls } = countingOkTransport("smtp");
+    const runtime = createChannelRuntime({
+      templates: [channel.template("news", { medium: "email" })],
+      drivers: [driverFromTransport("smtp", transport)],
+    });
+
+    await runtime.send("news", { to: "soft@example.com" });
+    const softId = runtime.receipts.all()[0]!.messageId!;
+    runtime.ingestOutcome({
+      messageId: softId,
+      state: "soft-bounce",
+      to: "soft@example.com",
+      medium: "email",
+    });
+    expect(runtime.suppression.list().some((e) => e.reason === "prior-bounce")).toBe(false);
+
+    await runtime.send("news", { to: "complaint@example.com" });
+    const complaintId = runtime.receipts
+      .all()
+      .find((r) => r.to === "complaint@example.com")!.messageId!;
+    runtime.ingestOutcome({
+      messageId: complaintId,
+      state: "delivered-then-complained",
+      to: "complaint@example.com",
+      medium: "email",
+    });
+    expect(runtime.suppression.list().some((e) => e.reason === "prior-bounce")).toBe(false);
+
+    const again = await runtime.send("news", { to: "soft@example.com" });
+    expect(again.ok).toBe(true);
+    expect(calls.count).toBeGreaterThanOrEqual(3);
+  });
+});

package/src/elements/channel/injection.test.ts

@@ -0,0 +1,153 @@
+/**
+ * Injection escape hatch adversarial proofs:
+ * - custom suppression / receipts are used instead of process-local defaults
+ * - consent-only injection is wrapped into suppression
+ * - injecting both skips the process-local boot warn
+ */
+
+import { afterEach, describe, expect, test } from "bun:test";
+import type { ChannelMedium } from "../../manifest/types.ts";
+import {
+  channel,
+  createChannelRuntime,
+  createConsentStore,
+  createReceiptLedger,
+  createSuppressionStore,
+  resetChannelProcessLocalWarnForTests,
+  type DeliveryReceipt,
+  type DeliveryStatus,
+  type ReceiptLedger,
+  type SuppressionStore,
+} from "../channel.ts";
+import { driverFromTransport, okTransport } from "./test-helpers.ts";
+
+afterEach(() => {
+  resetChannelProcessLocalWarnForTests();
+});
+
+function trackingReceipts(): ReceiptLedger & { records: number; updates: number } {
+  const inner = createReceiptLedger();
+  const ledger = {
+    records: 0,
+    updates: 0,
+    record(receipt: DeliveryReceipt) {
+      ledger.records += 1;
+      inner.record(receipt);
+    },
+    all: () => inner.all(),
+    forTemplate: (t: string) => inner.forTemplate(t),
+    byMessageId: (id: string) => inner.byMessageId(id),
+    updateStatus(
+      messageId: string,
+      patch: { status: DeliveryStatus; at?: number; error?: string },
+    ) {
+      ledger.updates += 1;
+      return inner.updateStatus(messageId, patch);
+    },
+  };
+  return ledger;
+}
+
+function trackingSuppression(): SuppressionStore & {
+  checks: number;
+  bounces: number;
+} {
+  const inner = createSuppressionStore();
+  const store = {
+    checks: 0,
+    bounces: 0,
+    get consent() {
+      return inner.consent;
+    },
+    isSuppressed(subject: string, medium: ChannelMedium) {
+      store.checks += 1;
+      return inner.isSuppressed(subject, medium);
+    },
+    optOut(subject: string, medium: ChannelMedium | "all") {
+      inner.optOut(subject, medium);
+    },
+    addPriorBounce(subject: string, medium: ChannelMedium | "all") {
+      store.bounces += 1;
+      inner.addPriorBounce(subject, medium);
+    },
+    clear(subject: string, medium: ChannelMedium | "all") {
+      inner.clear(subject, medium);
+    },
+    list: () => inner.list(),
+  };
+  return store;
+}
+
+describe("channel store injection escape hatch", () => {
+  test("injected suppression and receipts are genuinely used", async () => {
+    const suppression = trackingSuppression();
+    const receipts = trackingReceipts();
+    const runtime = createChannelRuntime({
+      templates: [channel.template("news", { medium: "email" })],
+      drivers: [driverFromTransport("smtp", okTransport("smtp"))],
+      suppression,
+      receipts,
+    });
+
+    expect(runtime.suppression).toBe(suppression);
+    expect(runtime.receipts).toBe(receipts);
+
+    await runtime.send("news", { to: "a@b.c" });
+    expect(suppression.checks).toBeGreaterThanOrEqual(1);
+    expect(receipts.records).toBe(1);
+
+    const mid = receipts.all()[0]!.messageId!;
+    runtime.ingestOutcome({
+      messageId: mid,
+      state: "hard-bounce",
+      to: "a@b.c",
+      medium: "email",
+    });
+    expect(suppression.bounces).toBe(1);
+    expect(receipts.updates).toBe(1);
+
+    await runtime.send("news", { to: "a@b.c" });
+    expect(receipts.all().at(-1)!.status).toBe("suppressed/prior-bounce");
+    expect(receipts.records).toBe(2);
+  });
+
+  test("consent-only injection is consulted via wrapped suppression", async () => {
+    const consent = createConsentStore();
+    consent.optOut("x@y.z", "email");
+    const receipts = trackingReceipts();
+    const runtime = createChannelRuntime({
+      templates: [channel.template("news", { medium: "email" })],
+      drivers: [driverFromTransport("smtp", okTransport("smtp"))],
+      consent,
+      receipts,
+    });
+
+    const result = await runtime.send("news", { to: "x@y.z" });
+    expect(result.ok).toBe(false);
+    expect(receipts.records).toBe(1);
+    expect(receipts.all()[0]!.status).toBe("suppressed/opted-out");
+  });
+
+  test("injecting both suppression and receipts skips process-local warn", () => {
+    resetChannelProcessLocalWarnForTests();
+    const warns: string[] = [];
+    const original = console.warn;
+    console.warn = (...args: unknown[]) => {
+      warns.push(args.map(String).join(" "));
+    };
+    try {
+      createChannelRuntime({
+        suppression: createSuppressionStore(),
+        receipts: createReceiptLedger(),
+      });
+      expect(warns.some((w) => w.includes("process-local memory"))).toBe(false);
+
+      resetChannelProcessLocalWarnForTests();
+      warns.length = 0;
+      createChannelRuntime({});
+      expect(warns.some((w) => w.includes("process-local memory"))).toBe(true);
+    } finally {
+      console.warn = original;
+    }
+  });
+});

package/src/elements/channel/locale-ar.test.ts

@@ -0,0 +1,102 @@
+/**
+ * Arabic / RTL catalog round-trip proofs:
+ * - {{field}} interpolation inside Arabic bodies
+ * - ar vs ar-SA exact catalog key behavior
+ * - isRtlLocale for display (Channel does not rewrite HTML dir)
+ */
+
+import { describe, expect, test } from "bun:test";
+import { createChannelInbox, openConsoleChannel } from "../../drivers/index.ts";
+import { channel, createChannelRuntime, isRtlLocale } from "../channel.ts";
+
+describe("Arabic template catalog", () => {
+  test("interpolates variables inside Arabic subject and text", async () => {
+    const inbox = createChannelInbox();
+    const runtime = createChannelRuntime({
+      templates: [
+        channel.template("order-confirmed", {
+          medium: "email",
+          locales: ["en", "ar"],
+        }),
+      ],
+      drivers: [openConsoleChannel({ inbox })],
+      catalog: {
+        "order-confirmed": {
+          en: {
+            subject: "Order {{orderId}}",
+            text: "Hello {{name}}, order {{orderId}} is confirmed.",
+          },
+          ar: {
+            subject: "طلب {{orderId}}",
+            text: "مرحبًا {{name}}، تم تأكيد الطلب {{orderId}}.",
+          },
+        },
+      },
+    });
+
+    await runtime.send("order-confirmed", {
+      to: "user@example.com",
+      locale: "ar",
+      data: { name: "علي", orderId: "ORD-42" },
+    });
+
+    const entry = inbox.entries[0]!;
+    expect(entry.subject).toBe("طلب ORD-42");
+    expect(entry.text).toBe("مرحبًا علي، تم تأكيد الطلب ORD-42.");
+    expect(entry.subject).not.toContain("{{");
+    expect(entry.text).not.toContain("{{");
+    // Email console inbox omits locale; the receipt is the ledger of truth.
+    expect(runtime.receipts.all()[0]!.locale).toBe("ar");
+  });
+
+  test("Accept-Language ar-SA misses catalog key ar and falls back to default/en body", async () => {
+    const inbox = createChannelInbox();
+    const runtime = createChannelRuntime({
+      templates: [channel.template("hello", { medium: "email", locales: ["en", "ar"] })],
+      drivers: [openConsoleChannel({ inbox })],
+      defaultLocale: "en",
+      catalog: {
+        hello: {
+          en: { subject: "Hi {{name}}", text: "Hello {{name}}" },
+          ar: { subject: "مرحبا {{name}}", text: "أهلا {{name}}" },
+        },
+      },
+    });
+
+    await runtime.send("hello", {
+      to: "a@b.c",
+      acceptLanguage: "ar-SA,en;q=0.8",
+      data: { name: "سارة" },
+    });
+
+    const receipt = runtime.receipts.all()[0]!;
+    expect(receipt.locale).toBe("ar-SA");
+    // Exact key miss → defaultLocale "en" body with interpolation still applied
+    expect(inbox.entries[0]!.subject).toBe("Hi سارة");
+    expect(inbox.entries[0]!.text).toBe("Hello سارة");
+  });
+
+  test("exact ar catalog key selects Arabic when locale is ar", async () => {
+    const inbox = createChannelInbox();
+    const runtime = createChannelRuntime({
+      templates: [channel.template("hello", { medium: "email" })],
+      drivers: [openConsoleChannel({ inbox })],
+      catalog: {
+        hello: {
+          en: { subject: "Hi", text: "Hello" },
+          ar: { subject: "مرحبا {{name}}", text: "أهلا {{name}}" },
+        },
+      },
+    });
+
+    await runtime.send("hello", { to: "a@b.c", locale: "ar", data: { name: "نورة" } });
+    expect(inbox.entries[0]!.subject).toBe("مرحبا نورة");
+    expect(inbox.entries[0]!.text).toBe("أهلا نورة");
+  });
+
+  test("isRtlLocale marks Arabic (and ar-SA) as RTL for display helpers", () => {
+    expect(isRtlLocale("ar")).toBe(true);
+    expect(isRtlLocale("ar-SA")).toBe(true);
+    expect(isRtlLocale("en")).toBe(false);
+  });
+});

package/src/elements/channel/otp-delivery.ts

@@ -73,8 +73,11 @@ type MediumSendResult = {
 };
 
 /**
- * Whether an error should advance to the next medium (provider outage),
- * not permanent client mistakes (invalid address).
+ * Whether an error should advance to the next transport / medium
+ * (provider outage), not permanent client mistakes (invalid address).
+ *
+ * Shared by OTP cross-medium delivery and same-medium email/SMS
+ * {@link FallbackTransport} chains on the Channel runtime.
  *
  * @param error - Thrown error
  */

package/src/elements/channel/receipts-ledger.test.ts

@@ -0,0 +1,100 @@
+/**
+ * Receipt ledger adversarial proofs — status progression with Signal-like rigor:
+ * sent → fallback → suppressed/* → ingestOutcome hard-bounce update →
+ * blocked/invalid-address
+ */
+
+import { describe, expect, test } from "bun:test";
+import { channel, createChannelRuntime, createConsentStore } from "../channel.ts";
+import {
+  countingOkTransport,
+  driverFromTransport,
+  failingTransport,
+  okTransport,
+} from "./test-helpers.ts";
+
+describe("receipt ledger accuracy", () => {
+  test("clean send records sent with messageId lookup", async () => {
+    const runtime = createChannelRuntime({
+      templates: [channel.template("hello", { medium: "email" })],
+      drivers: [driverFromTransport("smtp", okTransport("smtp"))],
+      catalog: { hello: { en: { subject: "Hi", text: "Hello" } } },
+    });
+
+    const result = await runtime.send("hello", { to: "a@b.c" });
+    expect(result.ok).toBe(true);
+
+    const receipt = runtime.receipts.forTemplate("hello")[0]!;
+    expect(receipt.status).toBe("sent");
+    expect(receipt.attempts).toHaveLength(1);
+    expect(receipt.attempts[0]!.ok).toBe(true);
+    expect(receipt.messageId).toBe(result.messageId);
+    expect(runtime.receipts.byMessageId(result.messageId)?.id).toBe(receipt.id);
+  });
+
+  test("failover send records fallback with ordered attempts", async () => {
+    const runtime = createChannelRuntime({
+      templates: [channel.template("hello", { medium: "email" })],
+      drivers: [
+        driverFromTransport("smtp", failingTransport("smtp")),
+        driverFromTransport("resend", okTransport("resend")),
+      ],
+    });
+
+    await runtime.send("hello", { to: "a@b.c", via: ["smtp", "resend"] });
+    const receipt = runtime.receipts.forTemplate("hello")[0]!;
+    expect(receipt.status).toBe("fallback");
+    expect(receipt.attempts.length).toBeGreaterThanOrEqual(2);
+    expect(receipt.attempts[0]!.ok).toBe(false);
+    expect(receipt.attempts.some((a) => a.ok)).toBe(true);
+  });
+
+  test("opt-out and prior-bounce leave empty attempts", async () => {
+    const consent = createConsentStore();
+    consent.optOut("out@example.com", "email");
+    const { transport, calls } = countingOkTransport("smtp");
+    const runtime = createChannelRuntime({
+      templates: [channel.template("news", { medium: "email" })],
+      drivers: [driverFromTransport("smtp", transport)],
+      consent,
+    });
+
+    const opted = await runtime.send("news", { to: "out@example.com" });
+    expect(opted.ok).toBe(false);
+    expect(runtime.receipts.all()[0]!.status).toBe("suppressed/opted-out");
+    expect(runtime.receipts.all()[0]!.attempts).toEqual([]);
+    expect(calls.count).toBe(0);
+
+    await runtime.send("news", { to: "bounce@example.com" });
+    const sent = runtime.receipts.all().find((r) => r.to === "bounce@example.com")!;
+    runtime.ingestOutcome({
+      messageId: sent.messageId!,
+      state: "hard-bounce",
+      to: "bounce@example.com",
+      medium: "email",
+    });
+    expect(runtime.receipts.byMessageId(sent.messageId!)!.status).toBe("hard-bounce");
+
+    const blocked = await runtime.send("news", { to: "bounce@example.com" });
+    expect(blocked.ok).toBe(false);
+    const last = runtime.receipts.all().at(-1)!;
+    expect(last.status).toBe("suppressed/prior-bounce");
+    expect(last.attempts).toEqual([]);
+  });
+
+  test("invalid-address failure classifies as blocked/invalid-address", async () => {
+    const runtime = createChannelRuntime({
+      templates: [channel.template("hello", { medium: "email" })],
+      drivers: [
+        driverFromTransport(
+          "smtp",
+          failingTransport("smtp", new Error("invalid recipient address")),
+        ),
+      ],
+    });
+
+    const result = await runtime.send("hello", { to: "bad" });
+    expect(result.ok).toBe(false);
+    expect(runtime.receipts.forTemplate("hello")[0]!.status).toBe("blocked/invalid-address");
+  });
+});

package/src/elements/channel/runtime.ts

@@ -19,6 +19,7 @@ import type {
   SmsOtpTransport,
 } from "../../drivers/channel-types.ts";
 import type { ChannelMedium } from "../../manifest/types.ts";
+import { emitBootWarn } from "../../runtime/boot-warn.ts";
 import type { ConsentStore } from "./consent.ts";
 import type { ChannelTemplateDecl } from "./declare.ts";
 import { DEFAULT_MEDIUM_COSTS, type MediumCosts } from "./costs.ts";
@@ -34,6 +35,7 @@ import {
 import { createSuppressionStore, type SuppressionStore } from "./suppression.ts";
 import {
   deliverOtpAcrossChannels,
+  shouldFallbackOtpMedium,
   type DeliverOtpOptions,
   type DeliverOtpResult,
 } from "./otp-delivery.ts";
@@ -162,7 +164,7 @@ export function createChannelRuntime(options: CreateChannelRuntimeOptions = {}):
   const receipts = options.receipts ?? createReceiptLedger();
   if ((usingDefaultSuppression || usingDefaultReceipts) && !channelProcessLocalWarned) {
     channelProcessLocalWarned = true;
-    console.warn(
+    emitBootWarn(
       "oke boot: Channel suppression/consent/receipts default to process-local memory — " +
         "opt-out, bounce, and receipt state on one instance is invisible to others. " +
         "Inject shared stores for multi-instance, or run a single Channel consumer, until a " +
@@ -233,6 +235,8 @@ export function createChannelRuntime(options: CreateChannelRuntimeOptions = {}):
 
     const recorded: FallbackAttempt[] = [];
     const fallback = new FallbackTransport(transports, {
+      // Same permanent-vs-provider distinction as OTP cross-medium failover.
+      shouldFallback: shouldFallbackOtpMedium,
       onFallback(failedIndex, error) {
         const provider =
           transports[failedIndex]?.provider ?? chain[failedIndex]?.id ?? `driver-${failedIndex}`;
@@ -287,6 +291,16 @@ export function createChannelRuntime(options: CreateChannelRuntimeOptions = {}):
           });
         }
       }
+      // Permanent client errors abort failover by rethrowing the original error
+      // (no FallbackError.attempts / onFallback) — still record the failed try.
+      if (attempts.length === 0) {
+        attempts.push({
+          driverId: transports[0]?.provider ?? chain[0]?.id ?? "email",
+          ok: false,
+          error: err instanceof Error ? err.message : String(err),
+          at: now(),
+        });
+      }
       return {
         result: {
           ok: false,
@@ -318,6 +332,7 @@ export function createChannelRuntime(options: CreateChannelRuntimeOptions = {}):
       options.retry ? new RetryTransport(transport) : transport,
     );
     const fallback = new FallbackTransport(transports, {
+      shouldFallback: shouldFallbackOtpMedium,
       onFallback(failedIndex, error) {
         const provider =
           transports[failedIndex]?.provider ?? sms[failedIndex]?.driver.id ?? `sms-${failedIndex}`;
@@ -376,6 +391,14 @@ export function createChannelRuntime(options: CreateChannelRuntimeOptions = {}):
           });
         }
       }
+      if (attempts.length === 0) {
+        attempts.push({
+          driverId: transports[0]?.provider ?? sms[0]?.driver.id ?? "sms",
+          ok: false,
+          error: err instanceof Error ? err.message : String(err),
+          at: now(),
+        });
+      }
       return {
         result: {
           ok: false,

package/src/elements/channel/test-helpers.ts

@@ -0,0 +1,60 @@
+/**
+ * Shared fakes for Channel adversarial tests.
+ */
+
+import type { MailOptions, SendResult, Transport } from "sently";
+import type { ChannelDriver } from "../../drivers/channel-types.ts";
+
+/** Flatten a sently address field for fake SendResult envelopes. */
+export function addressToString(input: MailOptions["to"]): string {
+  if (typeof input === "string") return input;
+  if (Array.isArray(input)) return "batch";
+  return input.address;
+}
+
+/** Create a sently-compatible transport that always fails with `error`. */
+export function failingTransport(
+  provider: string,
+  error: unknown = new Error(`${provider} down`),
+): Transport {
+  return {
+    provider,
+    async send(_options: MailOptions): Promise<SendResult> {
+      throw error;
+    },
+  };
+}
+
+/** Create a sently-compatible transport that succeeds. */
+export function okTransport(provider: string, calls?: { count: number }): Transport {
+  return {
+    provider,
+    async send(options: MailOptions): Promise<SendResult> {
+      if (calls) calls.count += 1;
+      const to = addressToString(options.to);
+      const from = addressToString(options.from);
+      return {
+        messageId: `${provider}-msg`,
+        accepted: [to],
+        rejected: [],
+        response: "ok",
+        envelope: { from, to: [to] },
+        provider,
+      };
+    },
+  };
+}
+
+/** Counting success transport — proves a send actually hit the wire. */
+export function countingOkTransport(provider: string): {
+  transport: Transport;
+  calls: { count: number };
+} {
+  const calls = { count: 0 };
+  return { transport: okTransport(provider, calls), calls };
+}
+
+/** Wrap a Transport as a ChannelDriver. */
+export function driverFromTransport(id: ChannelDriver["id"], transport: Transport): ChannelDriver {
+  return { id, transport };
+}