okengine 0.1.4

package/src/elements/channel/mask.ts

@@ -0,0 +1,60 @@
+/**
+ * Recipient PII masking for Channel receipts / inbox (console §9.9 · §4.2).
+ */
+
+/** Default mask token when no structured form applies. */
+export const CHANNEL_PII_MASK = "[redacted]";
+
+/**
+ * Mask an email or phone recipient for operator display.
+ *
+ * @param to - Cleartext recipient
+ */
+export function maskRecipient(to: string): string {
+  const trimmed = to.trim();
+  if (!trimmed) return CHANNEL_PII_MASK;
+
+  if (trimmed.includes("@")) {
+    return maskEmail(trimmed);
+  }
+  if (/^\+?\d[\d\s()-]{5,}$/.test(trimmed)) {
+    return maskPhone(trimmed);
+  }
+  if (trimmed.length <= 2) return CHANNEL_PII_MASK;
+  return `${trimmed[0]!}${"*".repeat(Math.min(trimmed.length - 2, 6))}${trimmed.at(-1)!}`;
+}
+
+/**
+ * Mask an email address: `a***@e***.com`.
+ *
+ * @param email - Cleartext email
+ */
+export function maskEmail(email: string): string {
+  const [local, domain] = email.split("@");
+  if (!local || !domain) return CHANNEL_PII_MASK;
+  const localMask =
+    local.length <= 1 ? "*" : `${local[0]!}${"*".repeat(Math.min(3, local.length - 1))}`;
+  const parts = domain.split(".");
+  const name = parts[0] ?? domain;
+  const tld = parts.length > 1 ? parts.slice(1).join(".") : "";
+  const domainMask =
+    name.length <= 1
+      ? "*"
+      : `${name[0]!}${"*".repeat(Math.min(3, name.length - 1))}`;
+  return tld ? `${localMask}@${domainMask}.${tld}` : `${localMask}@${domainMask}`;
+}
+
+/**
+ * Mask a phone number, keeping country prefix + last digits.
+ *
+ * @param phone - Cleartext phone
+ */
+export function maskPhone(phone: string): string {
+  const digits = phone.replace(/\D/g, "");
+  if (digits.length < 6) return CHANNEL_PII_MASK;
+  const last = digits.slice(-3);
+  const prefix = phone.trim().startsWith("+")
+    ? `+${digits.slice(0, Math.min(3, digits.length - 3))}`
+    : digits.slice(0, Math.min(3, digits.length - 3));
+  return `${prefix}***${last}`;
+}

package/src/elements/channel/mime.ts

@@ -0,0 +1,23 @@
+/**
+ * MIME building, attachments, retry, and error hierarchy — adopted from sently.
+ *
+ * Transport interface is identical so sently transports (`SMTPTransport`,
+ * `ResendTransport`, …) run unchanged. MIME generation lives inside those
+ * transports; OKE does not re-implement it.
+ */
+
+export type {
+  Attachment,
+  MailOptions,
+  SendResult,
+  Transport,
+  RetryConfig,
+} from "sently";
+
+export { SentlyError } from "sently/errors";
+export { RetryTransport } from "sently/transports/retry";
+export {
+  FallbackTransport,
+  FallbackError,
+  type FallbackAttempt,
+} from "sently/transports/fallback";

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

@@ -0,0 +1,40 @@
+/**
+ * Seven-state taxonomy + consequence ranking (console §9.9).
+ */
+
+import { describe, expect, test } from "bun:test";
+import {
+  buildOutcomeRows,
+  formatAttemptChain,
+  VERDICT_BY_STATE,
+} from "./outcomes.ts";
+
+describe("delivery outcome taxonomy", () => {
+  test("every state carries a verdict", () => {
+    expect(VERDICT_BY_STATE["suppressed/opted-out"]).toBe("correct");
+    expect(VERDICT_BY_STATE["hard-bounce"]).toBe("suppress");
+    expect(VERDICT_BY_STATE["delivered-then-complained"]).toBe("review");
+    expect(VERDICT_BY_STATE["soft-bounce"]).toBe("retry");
+  });
+
+  test("complaints outrank many hard bounces by consequence weight", () => {
+    const ranked = buildOutcomeRows({
+      "hard-bounce": 14,
+      "delivered-then-complained": 4,
+      "soft-bounce": 20,
+    });
+    expect(ranked[0]!.state).toBe("delivered-then-complained");
+    expect(ranked[0]!.verdict).toBe("review");
+    expect(ranked[0]!.count).toBe(4);
+    expect(ranked.find((r) => r.state === "hard-bounce")!.count).toBe(14);
+  });
+
+  test("formatAttemptChain records both attempts", () => {
+    expect(
+      formatAttemptChain([
+        { driverId: "whatsapp", ok: false },
+        { driverId: "sms", ok: true },
+      ]),
+    ).toBe("whatsapp failed → sms succeeded");
+  });
+});

package/src/elements/channel/outcomes.ts

@@ -0,0 +1,126 @@
+/**
+ * Seven-state taxonomy of "did not arrive" (console §9.9).
+ *
+ * Suppression is not failure. Weight follows consequence, not magnitude.
+ */
+
+/** Canonical delivery-outcome states for the deliverability console. */
+export type DeliveryOutcomeState =
+  | "suppressed/opted-out"
+  | "suppressed/prior-bounce"
+  | "blocked/invalid-address"
+  | "soft-bounce"
+  | "hard-bounce"
+  | "provider-error"
+  | "delivered-then-complained";
+
+/** Operator verdict next to each state count. */
+export type DeliveryVerdict = "correct" | "retry" | "suppress" | "review";
+
+/** Verdict for each of the seven states. */
+export const VERDICT_BY_STATE: Readonly<
+  Record<DeliveryOutcomeState, DeliveryVerdict>
+> = {
+  "suppressed/opted-out": "correct",
+  "suppressed/prior-bounce": "correct",
+  "blocked/invalid-address": "review",
+  "soft-bounce": "retry",
+  "hard-bounce": "suppress",
+  "provider-error": "retry",
+  "delivered-then-complained": "review",
+};
+
+/**
+ * Consequence weight — higher is worse for sender reputation.
+ * Complaints outrank many hard bounces.
+ */
+export const CONSEQUENCE_WEIGHT: Readonly<
+  Record<DeliveryOutcomeState, number>
+> = {
+  "suppressed/opted-out": 0,
+  "suppressed/prior-bounce": 1,
+  "blocked/invalid-address": 3,
+  "soft-bounce": 4,
+  "hard-bounce": 5,
+  "provider-error": 4,
+  "delivered-then-complained": 10,
+};
+
+/** Ordered list of the seven states (stable catalog order). */
+export const DELIVERY_OUTCOME_STATES: readonly DeliveryOutcomeState[] = [
+  "suppressed/opted-out",
+  "suppressed/prior-bounce",
+  "blocked/invalid-address",
+  "soft-bounce",
+  "hard-bounce",
+  "provider-error",
+  "delivered-then-complained",
+];
+
+/** One row in the deliverability taxonomy table. */
+export interface OutcomeRow {
+  readonly state: DeliveryOutcomeState;
+  readonly count: number;
+  readonly verdict: DeliveryVerdict;
+  readonly weight: number;
+}
+
+/**
+ * Rank outcome rows by consequence weight (desc), then count (desc).
+ *
+ * @param rows - Taxonomy rows with counts
+ */
+export function rankByConsequence(
+  rows: readonly OutcomeRow[],
+): readonly OutcomeRow[] {
+  return [...rows].sort((a, b) => {
+    if (b.weight !== a.weight) return b.weight - a.weight;
+    return b.count - a.count;
+  });
+}
+
+/**
+ * Build taxonomy rows from state → count, attaching verdict + weight.
+ *
+ * @param counts - Counts keyed by outcome state
+ */
+export function buildOutcomeRows(
+  counts: Readonly<Partial<Record<DeliveryOutcomeState, number>>>,
+): readonly OutcomeRow[] {
+  const rows: OutcomeRow[] = DELIVERY_OUTCOME_STATES.map((state) => ({
+    state,
+    count: counts[state] ?? 0,
+    verdict: VERDICT_BY_STATE[state],
+    weight: CONSEQUENCE_WEIGHT[state],
+  }));
+  return rankByConsequence(rows);
+}
+
+/**
+ * Whether a receipt status is one of the seven "did not arrive" states.
+ *
+ * @param status - Receipt status
+ */
+export function isDeliveryOutcomeState(
+  status: string,
+): status is DeliveryOutcomeState {
+  return (DELIVERY_OUTCOME_STATES as readonly string[]).includes(status);
+}
+
+/**
+ * Format a fallback attempt chain as human-readable prose.
+ *
+ * @param attempts - Ordered send attempts
+ * @returns e.g. `"whatsapp failed → sms succeeded"`
+ */
+export function formatAttemptChain(
+  attempts: readonly {
+    readonly driverId: string;
+    readonly ok: boolean;
+  }[],
+): string {
+  if (attempts.length === 0) return "";
+  return attempts
+    .map((a) => `${a.driverId} ${a.ok ? "succeeded" : "failed"}`)
+    .join(" → ");
+}

package/src/elements/channel/receipts.ts

@@ -0,0 +1,121 @@
+/**
+ * Delivery receipts — recorded for every send attempt / outcome.
+ */
+
+import type { ChannelAttempt } from "../../drivers/channel-types.ts";
+import type { DeliveryOutcomeState } from "./outcomes.ts";
+import type { LocaleChainStep } from "./locale.ts";
+
+/** Successful / in-flight send statuses. */
+export type DeliverySuccessStatus = "sent" | "fallback";
+
+/** Legacy alias kept for callers that still say "failed" / "opted-out". */
+export type DeliveryLegacyStatus = "failed" | "opted-out";
+
+/** Full receipt status — success paths + seven-state taxonomy. */
+export type DeliveryStatus =
+  | DeliverySuccessStatus
+  | DeliveryLegacyStatus
+  | DeliveryOutcomeState;
+
+/** Delivery receipt. */
+export interface DeliveryReceipt {
+  readonly id: string;
+  readonly template: string;
+  readonly to: string;
+  readonly medium: string;
+  readonly locale?: string;
+  readonly localeChain?: readonly LocaleChainStep[];
+  readonly status: DeliveryStatus;
+  readonly messageId?: string;
+  readonly driverId?: string;
+  readonly attempts: readonly ChannelAttempt[];
+  readonly at: number;
+  readonly error?: string;
+}
+
+/** Ingest a post-send provider outcome against an existing receipt. */
+export interface IngestOutcomeInput {
+  readonly messageId: string;
+  readonly state: DeliveryOutcomeState;
+  readonly at?: number;
+  readonly error?: string;
+  /** Recipient — used when creating a synthetic receipt if messageId is unknown. */
+  readonly to?: string;
+  readonly template?: string;
+  readonly medium?: string;
+}
+
+/** Receipt ledger. */
+export interface ReceiptLedger {
+  /** Append a receipt. */
+  record(receipt: DeliveryReceipt): void;
+  /** All receipts. */
+  all(): readonly DeliveryReceipt[];
+  /**
+   * Receipts for a template.
+   *
+   * @param template - Template name
+   */
+  forTemplate(template: string): readonly DeliveryReceipt[];
+  /**
+   * Find by provider message id.
+   *
+   * @param messageId - Provider / runtime message id
+   */
+  byMessageId(messageId: string): DeliveryReceipt | undefined;
+  /**
+   * Update an existing receipt's status (post-send bounce / complaint).
+   *
+   * @param messageId - Provider message id
+   * @param patch - Status + optional error
+   */
+  updateStatus(
+    messageId: string,
+    patch: {
+      readonly status: DeliveryStatus;
+      readonly at?: number;
+      readonly error?: string;
+    },
+  ): DeliveryReceipt | undefined;
+}
+
+/**
+ * Create an in-memory receipt ledger.
+ */
+export function createReceiptLedger(): ReceiptLedger {
+  const rows: DeliveryReceipt[] = [];
+  return {
+    record(receipt) {
+      rows.push(receipt);
+    },
+    all() {
+      return [...rows];
+    },
+    forTemplate(template) {
+      return rows.filter((r) => r.template === template);
+    },
+    byMessageId(messageId) {
+      for (let i = rows.length - 1; i >= 0; i--) {
+        const r = rows[i]!;
+        if (r.messageId === messageId || r.id === messageId) return r;
+      }
+      return undefined;
+    },
+    updateStatus(messageId, patch) {
+      const idx = rows.findIndex(
+        (r) => r.messageId === messageId || r.id === messageId,
+      );
+      if (idx < 0) return undefined;
+      const prev = rows[idx]!;
+      const next: DeliveryReceipt = {
+        ...prev,
+        status: patch.status,
+        at: patch.at ?? prev.at,
+        ...(patch.error !== undefined ? { error: patch.error } : {}),
+      };
+      rows[idx] = next;
+      return next;
+    },
+  };
+}