okengine 0.1.4

package/src/elements/channel/consent.ts

@@ -0,0 +1,81 @@
+/**
+ * Consent / opt-out — Channel will not send without consent.
+ */
+
+import type { ChannelMedium } from "../../manifest/types.ts";
+
+/** Opt-out record. */
+export interface OptOut {
+  readonly subject: string;
+  readonly medium: ChannelMedium | "all";
+  readonly at: number;
+}
+
+/** Consent store surface. */
+export interface ConsentStore {
+  /**
+   * Whether the subject has opted out of this medium.
+   *
+   * @param subject - User / address id
+   * @param medium - Channel medium
+   */
+  isOptedOut(subject: string, medium: ChannelMedium): boolean;
+  /**
+   * Record an opt-out.
+   *
+   * @param subject - User / address id
+   * @param medium - Medium or `all`
+   */
+  optOut(subject: string, medium: ChannelMedium | "all"): void;
+  /**
+   * Clear an opt-out (re-consent).
+   *
+   * @param subject - User / address id
+   * @param medium - Medium or `all`
+   */
+  optIn(subject: string, medium: ChannelMedium | "all"): void;
+  /** Snapshot of all opt-outs. */
+  list(): readonly OptOut[];
+}
+
+/**
+ * Create an in-memory consent store.
+ */
+export function createConsentStore(): ConsentStore {
+  const rows: OptOut[] = [];
+
+  function matches(
+    subject: string,
+    medium: ChannelMedium,
+  ): boolean {
+    return rows.some(
+      (r) =>
+        r.subject === subject &&
+        (r.medium === "all" || r.medium === medium),
+    );
+  }
+
+  return {
+    isOptedOut(subject, medium) {
+      return matches(subject, medium);
+    },
+    optOut(subject, medium) {
+      if (
+        !rows.some((r) => r.subject === subject && r.medium === medium)
+      ) {
+        rows.push({ subject, medium, at: Date.now() });
+      }
+    },
+    optIn(subject, medium) {
+      for (let i = rows.length - 1; i >= 0; i--) {
+        const r = rows[i]!;
+        if (r.subject === subject && r.medium === medium) {
+          rows.splice(i, 1);
+        }
+      }
+    },
+    list() {
+      return [...rows];
+    },
+  };
+}

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

@@ -0,0 +1,62 @@
+/**
+ * Fallback weekly cost delta (console §9.9 · §9.12).
+ */
+
+import { describe, expect, test } from "bun:test";
+import { fallbackWeeklyCostDelta } from "./costs.ts";
+import type { DeliveryReceipt } from "./receipts.ts";
+
+describe("fallbackWeeklyCostDelta", () => {
+  test("projects fallback rate into a weekly USD delta", () => {
+    const weekStart = Date.UTC(2026, 6, 20);
+    const receipts: DeliveryReceipt[] = [
+      {
+        id: "1",
+        template: "otp-code",
+        to: "a",
+        medium: "any",
+        status: "fallback",
+        attempts: [
+          { driverId: "wa-cloud", ok: false, at: weekStart + 1 },
+          { driverId: "unifonic", ok: true, at: weekStart + 2 },
+        ],
+        at: weekStart + 3,
+      },
+      {
+        id: "2",
+        template: "otp-code",
+        to: "b",
+        medium: "whatsapp",
+        status: "sent",
+        attempts: [{ driverId: "wa-cloud", ok: true, at: weekStart + 4 }],
+        at: weekStart + 5,
+      },
+      {
+        id: "3",
+        template: "otp-code",
+        to: "c",
+        medium: "any",
+        status: "fallback",
+        attempts: [
+          { driverId: "wa-cloud", ok: false, at: weekStart + 6 },
+          { driverId: "unifonic", ok: true, at: weekStart + 7 },
+        ],
+        at: weekStart + 8,
+      },
+    ];
+
+    const delta = fallbackWeeklyCostDelta(receipts, {
+      weekStartMs: weekStart,
+      weekEndMs: weekStart + 86_400_000 * 7,
+      costs: { whatsapp: 0.005, sms: 0.0075 },
+    });
+
+    expect(delta.totalCount).toBe(3);
+    expect(delta.fallbackCount).toBe(2);
+    expect(delta.fallbackRate).toBeCloseTo(2 / 3, 5);
+    // Each fallback: sms 0.0075 − whatsapp 0.005 = 0.0025
+    expect(delta.weeklyDeltaUsd).toBeCloseTo(0.005, 5);
+    expect(delta.primaryMedium).toBe("whatsapp");
+    expect(delta.fallbackMedium).toBe("sms");
+  });
+});

package/src/elements/channel/costs.ts

@@ -0,0 +1,130 @@
+/**
+ * Channel medium unit costs — fallback rate as a weekly bill (console §9.9 · §9.12).
+ */
+
+import type { ChannelMedium } from "../../manifest/types.ts";
+import type { DeliveryReceipt } from "./receipts.ts";
+
+/** USD per message by medium. */
+export type MediumCosts = Readonly<Partial<Record<ChannelMedium, number>>>;
+
+/**
+ * Default unit costs (USD / message). Overridable on the runtime.
+ * Rough public-cloud ballparks — the unit that matters is the weekly delta.
+ */
+export const DEFAULT_MEDIUM_COSTS: MediumCosts = {
+  email: 0.0001,
+  sms: 0.0075,
+  whatsapp: 0.005,
+  push: 0.00005,
+  any: 0.005,
+};
+
+/** Weekly fallback cost projection. */
+export interface FallbackWeeklyCostDelta {
+  /** Fraction of sends that used a fallback (0–1). */
+  readonly fallbackRate: number;
+  /** Count of fallback receipts in the window. */
+  readonly fallbackCount: number;
+  /** Total sends in the window. */
+  readonly totalCount: number;
+  /** Extra USD this week vs primary-medium-only. */
+  readonly weeklyDeltaUsd: number;
+  /** Primary (first attempted) medium for the sample. */
+  readonly primaryMedium: string;
+  /** Winning fallback medium (last success) when available. */
+  readonly fallbackMedium: string;
+}
+
+/**
+ * Cost of one medium.
+ *
+ * @param medium - Channel medium
+ * @param costs - Unit cost table
+ */
+export function costOf(
+  medium: string,
+  costs: MediumCosts = DEFAULT_MEDIUM_COSTS,
+): number {
+  return costs[medium as ChannelMedium] ?? costs.any ?? 0.005;
+}
+
+/**
+ * Project fallback rate into a weekly cost delta vs primary-medium-only.
+ *
+ * For each fallback receipt: delta = cost(winner) − cost(primary attempt).
+ * Summed over the week window (not per-call — §9.12).
+ *
+ * @param receipts - Delivery receipts
+ * @param options - Costs + week window
+ */
+export function fallbackWeeklyCostDelta(
+  receipts: readonly DeliveryReceipt[],
+  options: {
+    readonly costs?: MediumCosts;
+    readonly weekStartMs: number;
+    readonly weekEndMs?: number;
+    readonly now?: number;
+  },
+): FallbackWeeklyCostDelta {
+  const costs = options.costs ?? DEFAULT_MEDIUM_COSTS;
+  const end = options.weekEndMs ?? options.now ?? Date.now();
+  const inWeek = receipts.filter(
+    (r) => r.at >= options.weekStartMs && r.at <= end,
+  );
+  const fallbacks = inWeek.filter((r) => r.status === "fallback");
+
+  let weeklyDeltaUsd = 0;
+  let primaryMedium = "whatsapp";
+  let fallbackMedium = "sms";
+
+  for (const r of fallbacks) {
+    const first = r.attempts[0];
+    const winner =
+      [...r.attempts].reverse().find((a) => a.ok) ?? r.attempts.at(-1);
+    if (!first || !winner) continue;
+    const primary = mediumFromDriver(first.driverId, r.medium);
+    const fb = mediumFromDriver(winner.driverId, r.medium);
+    primaryMedium = primary;
+    fallbackMedium = fb;
+    weeklyDeltaUsd += costOf(fb, costs) - costOf(primary, costs);
+  }
+
+  // If winner is cheaper, delta can be negative — still report it.
+  const totalCount = inWeek.length;
+  const fallbackCount = fallbacks.length;
+  return {
+    fallbackRate: totalCount === 0 ? 0 : fallbackCount / totalCount,
+    fallbackCount,
+    totalCount,
+    weeklyDeltaUsd,
+    primaryMedium,
+    fallbackMedium,
+  };
+}
+
+/**
+ * Best-effort map of driver id → medium for cost accounting.
+ *
+ * @param driverId - Driver / provider id
+ * @param receiptMedium - Receipt medium fallback
+ */
+function mediumFromDriver(driverId: string, receiptMedium: string): string {
+  const id = driverId.toLowerCase();
+  if (id.includes("wa") || id.includes("whatsapp")) return "whatsapp";
+  if (id.includes("sms") || id.includes("unifonic") || id.includes("twilio")) {
+    return "sms";
+  }
+  if (id.includes("push") || id.includes("fcm") || id.includes("webpush")) {
+    return "push";
+  }
+  if (
+    id.includes("smtp") ||
+    id.includes("resend") ||
+    id.includes("ses") ||
+    id.includes("email")
+  ) {
+    return "email";
+  }
+  return receiptMedium === "any" ? "email" : receiptMedium;
+}

package/src/elements/channel/declare.ts

@@ -0,0 +1,141 @@
+/**
+ * Channel declaration — templates with i18n, medium helpers.
+ *
+ * Physics: email · SMS · WhatsApp · push.
+ */
+
+import type { ChannelMedium } from "../../manifest/types.ts";
+
+/** Options for a medium binder (`channel.email`, …). */
+export interface ChannelMediumOptions {
+  readonly from?: string;
+  readonly sender?: string;
+}
+
+/** Options for {@link channel.template} / medium `.template`. */
+export interface ChannelTemplateOptions {
+  readonly medium?: ChannelMedium;
+  readonly locales?: string[];
+  readonly schema?: unknown;
+  readonly from?: string;
+}
+
+/** Declared channel template handle. */
+export interface ChannelTemplateDecl {
+  readonly kind: "template";
+  readonly name: string;
+  readonly medium: ChannelMedium;
+  readonly locales?: string[];
+  readonly schema?: unknown;
+  readonly from?: string;
+}
+
+/** Medium binder that can declare templates. */
+export interface ChannelMediumBinder {
+  readonly medium: ChannelMedium;
+  readonly from?: string;
+  /**
+   * Declare a template on this medium.
+   *
+   * @param name - Template id
+   * @param options - Schema / locales
+   */
+  template(
+    name: string,
+    options?: Omit<ChannelTemplateOptions, "medium" | "from">,
+  ): ChannelTemplateDecl;
+}
+
+/**
+ * Create a medium binder.
+ *
+ * @param medium - Medium id
+ * @param options - Default from / sender
+ */
+function mediumBinder(
+  medium: ChannelMedium,
+  options: ChannelMediumOptions = {},
+): ChannelMediumBinder {
+  const from = options.from ?? options.sender;
+  return {
+    medium,
+    ...(from !== undefined ? { from } : {}),
+    template(name, opts = {}) {
+      return {
+        kind: "template",
+        name,
+        medium,
+        ...(opts.locales ? { locales: opts.locales } : {}),
+        ...(opts.schema !== undefined ? { schema: opts.schema } : {}),
+        ...(from !== undefined ? { from } : {}),
+      };
+    },
+  };
+}
+
+/**
+ * Shape of the {@link channel} element namespace.
+ */
+export interface ChannelNamespace {
+  /**
+   * Medium-agnostic template.
+   *
+   * @param name - Template id
+   * @param options - Medium / locales / schema
+   */
+  template(name: string, options?: ChannelTemplateOptions): ChannelTemplateDecl;
+  /** Email medium binder. */
+  email(options?: ChannelMediumOptions): ChannelMediumBinder;
+  /** SMS medium binder. */
+  sms(options?: ChannelMediumOptions): ChannelMediumBinder;
+  /** WhatsApp medium binder. */
+  whatsapp(options?: ChannelMediumOptions): ChannelMediumBinder;
+  /** Push medium binder. */
+  push(options?: ChannelMediumOptions): ChannelMediumBinder;
+}
+
+/**
+ * Channel element namespace.
+ */
+export const channel: ChannelNamespace = {
+  /**
+   * Medium-agnostic template.
+   *
+   * @param name - Template id
+   * @param options - Medium / locales / schema
+   */
+  template(
+    name: string,
+    options: ChannelTemplateOptions = {},
+  ): ChannelTemplateDecl {
+    if (!name) throw new TypeError("channel.template: name is required");
+    return {
+      kind: "template",
+      name,
+      medium: options.medium ?? "email",
+      ...(options.locales ? { locales: options.locales } : {}),
+      ...(options.schema !== undefined ? { schema: options.schema } : {}),
+      ...(options.from !== undefined ? { from: options.from } : {}),
+    };
+  },
+
+  /** Email medium binder. */
+  email(options?: ChannelMediumOptions): ChannelMediumBinder {
+    return mediumBinder("email", options);
+  },
+
+  /** SMS medium binder. */
+  sms(options?: ChannelMediumOptions): ChannelMediumBinder {
+    return mediumBinder("sms", options);
+  },
+
+  /** WhatsApp medium binder. */
+  whatsapp(options?: ChannelMediumOptions): ChannelMediumBinder {
+    return mediumBinder("whatsapp", options);
+  },
+
+  /** Push medium binder. */
+  push(options?: ChannelMediumOptions): ChannelMediumBinder {
+    return mediumBinder("push", options);
+  },
+};

package/src/elements/channel/email-auth.test.ts

@@ -0,0 +1,47 @@
+/**
+ * SPF / DKIM / DMARC verification with injectable DNS.
+ */
+
+import { describe, expect, test } from "bun:test";
+import { domainFromFrom, verifyEmailAuth } from "./email-auth.ts";
+
+describe("verifyEmailAuth", () => {
+  test("extracts domain from From address", () => {
+    expect(domainFromFrom("noreply@skyport.dev")).toBe("skyport.dev");
+  });
+
+  test("classifies SPF DKIM DMARC from TXT records", async () => {
+    const result = await verifyEmailAuth("skyport.dev", {
+      dkimSelector: "oke",
+      now: () => 1,
+      async lookup(name) {
+        if (name === "skyport.dev") return ["v=spf1 include:_spf.google.com ~all"];
+        if (name === "oke._domainkey.skyport.dev") {
+          return ["v=DKIM1; k=rsa; p=MIIB"];
+        }
+        if (name === "_dmarc.skyport.dev") {
+          return ["v=DMARC1; p=quarantine; rua=mailto:d@skyport.dev"];
+        }
+        return [];
+      },
+    });
+    expect(result).toEqual({
+      domain: "skyport.dev",
+      spf: "pass",
+      dkim: "pass",
+      dmarc: "pass",
+      checkedAt: 1,
+    });
+  });
+
+  test("missing records are missing, not fail", async () => {
+    const result = await verifyEmailAuth("empty.test", {
+      async lookup() {
+        return [];
+      },
+    });
+    expect(result.spf).toBe("missing");
+    expect(result.dkim).toBe("missing");
+    expect(result.dmarc).toBe("missing");
+  });
+});

package/src/elements/channel/email-auth.ts

@@ -0,0 +1,109 @@
+/**
+ * SPF / DKIM / DMARC verification for sending domains (console §9.9).
+ *
+ * DNS is injected — the element never opens a side-channel.
+ */
+
+/** Auth check result for one mechanism. */
+export type AuthCheckStatus = "pass" | "fail" | "missing";
+
+/** SPF / DKIM / DMARC verification result. */
+export interface EmailAuthResult {
+  readonly domain: string;
+  readonly spf: AuthCheckStatus;
+  readonly dkim: AuthCheckStatus;
+  readonly dmarc: AuthCheckStatus;
+  readonly checkedAt: number;
+}
+
+/** Injectable DNS TXT lookup. */
+export type DnsTxtLookup = (name: string) => Promise<readonly string[]>;
+
+/** Options for {@link verifyEmailAuth}. */
+export interface VerifyEmailAuthOptions {
+  readonly lookup: DnsTxtLookup;
+  readonly dkimSelector?: string;
+  readonly now?: () => number;
+}
+
+/**
+ * Extract the domain from a From address / domain string.
+ *
+ * @param from - `noreply@example.com` or `example.com`
+ */
+export function domainFromFrom(from: string): string {
+  const trimmed = from.trim();
+  if (trimmed.includes("@")) {
+    return trimmed.split("@")[1]?.toLowerCase() ?? trimmed.toLowerCase();
+  }
+  // Strip display-name angle brackets: Name <a@b.c>
+  const angle = trimmed.match(/<([^>]+)>/);
+  if (angle?.[1]?.includes("@")) {
+    return angle[1].split("@")[1]!.toLowerCase();
+  }
+  return trimmed.toLowerCase();
+}
+
+/**
+ * Verify SPF, DKIM (selector), and DMARC TXT records for a domain.
+ *
+ * @param domainOrFrom - Domain or From address
+ * @param options - DNS lookup + optional DKIM selector
+ */
+export async function verifyEmailAuth(
+  domainOrFrom: string,
+  options: VerifyEmailAuthOptions,
+): Promise<EmailAuthResult> {
+  const domain = domainFromFrom(domainOrFrom);
+  const selector = options.dkimSelector ?? "oke";
+  const now = options.now ?? (() => Date.now());
+
+  const [spfRecords, dkimRecords, dmarcRecords] = await Promise.all([
+    safeLookup(options.lookup, domain),
+    safeLookup(options.lookup, `${selector}._domainkey.${domain}`),
+    safeLookup(options.lookup, `_dmarc.${domain}`),
+  ]);
+
+  return {
+    domain,
+    spf: classifySpf(spfRecords),
+    dkim: classifyDkim(dkimRecords),
+    dmarc: classifyDmarc(dmarcRecords),
+    checkedAt: now(),
+  };
+}
+
+async function safeLookup(
+  lookup: DnsTxtLookup,
+  name: string,
+): Promise<readonly string[]> {
+  try {
+    return await lookup(name);
+  } catch {
+    return [];
+  }
+}
+
+function classifySpf(records: readonly string[]): AuthCheckStatus {
+  const joined = records.join(" ");
+  if (!joined) return "missing";
+  if (/v=spf1/i.test(joined)) {
+    return /[-~?]all|all/i.test(joined) ? "pass" : "fail";
+  }
+  return "missing";
+}
+
+function classifyDkim(records: readonly string[]): AuthCheckStatus {
+  const joined = records.join(" ");
+  if (!joined) return "missing";
+  return /v=DKIM1/i.test(joined) || /p=/i.test(joined) ? "pass" : "fail";
+}
+
+function classifyDmarc(records: readonly string[]): AuthCheckStatus {
+  const joined = records.join(" ");
+  if (!joined) return "missing";
+  if (/v=DMARC1/i.test(joined)) {
+    return /p=(none|quarantine|reject)/i.test(joined) ? "pass" : "fail";
+  }
+  return "missing";
+}

package/src/elements/channel/locale.ts

@@ -0,0 +1,97 @@
+/**
+ * Locale resolution chain — profile → Accept-Language → default (console §9.9).
+ */
+
+/** One step in the locale resolution chain. */
+export type LocaleChainStep =
+  | `profile:${string}`
+  | `accept-language:${string}`
+  | `default:${string}`;
+
+/** Result of {@link resolveLocale}. */
+export interface LocaleResolution {
+  readonly locale: string;
+  readonly chain: readonly LocaleChainStep[];
+}
+
+/** Inputs for locale resolution. */
+export interface ResolveLocaleOptions {
+  readonly profileLocale?: string;
+  readonly acceptLanguage?: string;
+  readonly defaultLocale?: string;
+  /** Explicit override (wins; still recorded in the chain when provided). */
+  readonly locale?: string;
+}
+
+/**
+ * Whether a locale is written right-to-left.
+ *
+ * @param locale - BCP 47 locale tag
+ */
+export function isRtlLocale(locale: string): boolean {
+  const base = locale.toLowerCase().split("-")[0] ?? locale;
+  return (
+    base === "ar" ||
+    base === "he" ||
+    base === "fa" ||
+    base === "ur" ||
+    base === "yi"
+  );
+}
+
+/**
+ * Parse the first language tag from an Accept-Language header.
+ *
+ * @param header - Raw Accept-Language value
+ */
+export function parseAcceptLanguage(header: string | undefined): string | undefined {
+  if (!header?.trim()) return undefined;
+  const first = header.split(",")[0]?.trim();
+  if (!first) return undefined;
+  const tag = first.split(";")[0]?.trim();
+  return tag || undefined;
+}
+
+/**
+ * Resolve locale with a full chain for the Console to display.
+ *
+ * Precedence: explicit `locale` → profile → Accept-Language → default.
+ *
+ * @param options - Resolution inputs
+ */
+export function resolveLocale(
+  options: ResolveLocaleOptions = {},
+): LocaleResolution {
+  const defaultLocale = options.defaultLocale ?? "en";
+  const chain: LocaleChainStep[] = [];
+
+  if (options.locale?.trim()) {
+    const locale = options.locale.trim();
+    chain.push(`profile:${locale}`);
+    return { locale, chain };
+  }
+
+  if (options.profileLocale?.trim()) {
+    const locale = options.profileLocale.trim();
+    chain.push(`profile:${locale}`);
+    return { locale, chain };
+  }
+
+  const fromHeader = parseAcceptLanguage(options.acceptLanguage);
+  if (fromHeader) {
+    chain.push(`accept-language:${fromHeader}`);
+    return { locale: fromHeader, chain };
+  }
+
+  chain.push(`default:${defaultLocale}`);
+  return { locale: defaultLocale, chain };
+}
+
+/**
+ * Format a locale chain for display.
+ *
+ * @param chain - Resolution steps
+ */
+export function formatLocaleChain(chain: readonly LocaleChainStep[]): string {
+  return chain.join(" → ");
+}

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

@@ -0,0 +1,19 @@
+/**
+ * Recipient PII masking.
+ */
+
+import { describe, expect, test } from "bun:test";
+import { maskRecipient } from "./mask.ts";
+
+describe("maskRecipient", () => {
+  test("masks email local + domain", () => {
+    expect(maskRecipient("alice@example.com")).toBe("a***@e***.com");
+  });
+
+  test("masks phone keeping prefix and last digits", () => {
+    const masked = maskRecipient("+966501234567");
+    expect(masked.startsWith("+966")).toBe(true);
+    expect(masked.endsWith("567")).toBe(true);
+    expect(masked).toContain("***");
+  });
+});