okengine 0.1.4

package/src/elements/channel.test.ts

@@ -0,0 +1,232 @@
+/**
+ * Channel element acceptance:
+ * - a fallback chain records both attempts
+ * - delivery receipts are recorded
+ * - consent / opt-out blocks send
+ * - templates with i18n
+ * - sently Transport interface (console / fake transports)
+ */
+
+import { describe, expect, test } from "bun:test";
+import type { MailOptions, SendResult, Transport } from "sently";
+import {
+  createChannelInbox,
+  openConsoleChannel,
+  type ChannelDriver,
+} from "../drivers/index.ts";
+import {
+  channel,
+  createChannelRuntime,
+  createConsentStore,
+  FallbackTransport,
+} from "./channel.ts";
+
+/** Create a sently-compatible transport that always fails. */
+function failingTransport(provider: string): Transport {
+  return {
+    provider,
+    async send(_options: MailOptions): Promise<SendResult> {
+      throw new Error(`${provider} down`);
+    },
+  };
+}
+
+/** Create a sently-compatible transport that succeeds. */
+function okTransport(provider: string): Transport {
+  return {
+    provider,
+    async send(options: MailOptions): Promise<SendResult> {
+      const to = addressToString(options.to);
+      const from = addressToString(options.from);
+      return {
+        messageId: `${provider}-msg`,
+        accepted: [to],
+        rejected: [],
+        response: "ok",
+        envelope: { from, to: [to] },
+        provider,
+      };
+    },
+  };
+}
+
+function addressToString(input: MailOptions["to"]): string {
+  if (typeof input === "string") return input;
+  if (Array.isArray(input)) return "batch";
+  return input.address;
+}
+
+function driverFromTransport(
+  id: ChannelDriver["id"],
+  transport: Transport,
+): ChannelDriver {
+  return { id, transport };
+}
+
+describe("channel declaration", () => {
+  test("template and medium binders", () => {
+    const t = channel.template("otp-code", {
+      medium: "any",
+      locales: ["en", "ar"],
+    });
+    expect(t.name).toBe("otp-code");
+    expect(t.medium).toBe("any");
+    expect(t.locales).toEqual(["en", "ar"]);
+
+    const mail = channel.email({ from: "noreply@oke.dev" });
+    const order = mail.template("order-confirmed");
+    expect(order.medium).toBe("email");
+    expect(order.from).toBe("noreply@oke.dev");
+  });
+});
+
+describe("fallback chain records both attempts", () => {
+  test("failed then succeeded — both attempts on the receipt", async () => {
+    const inbox = createChannelInbox();
+    const runtime = createChannelRuntime({
+      templates: [
+        channel.template("booking-confirmed", {
+          medium: "email",
+          locales: ["en"],
+        }),
+      ],
+      drivers: [
+        driverFromTransport("smtp", failingTransport("smtp")),
+        driverFromTransport("resend", okTransport("resend")),
+        openConsoleChannel({ inbox }),
+      ],
+      catalog: {
+        "booking-confirmed": {
+          en: {
+            subject: "Booked {{id}}",
+            text: "Hello {{name}}",
+          },
+        },
+      },
+    });
+
+    const result = await runtime.send("booking-confirmed", {
+      to: "user@example.com",
+      data: { id: "B1", name: "Ali" },
+      locale: "en",
+    });
+
+    expect(result.ok).toBe(true);
+    expect(result.attempts.length).toBeGreaterThanOrEqual(2);
+    expect(result.attempts.some((a) => a.driverId === "smtp" && !a.ok)).toBe(
+      true,
+    );
+    expect(result.attempts.some((a) => a.ok)).toBe(true);
+
+    const receipts = runtime.receipts.forTemplate("booking-confirmed");
+    expect(receipts).toHaveLength(1);
+    expect(receipts[0]!.attempts.length).toBeGreaterThanOrEqual(2);
+    expect(receipts[0]!.status).toBe("fallback");
+  });
+
+  test("sently FallbackTransport is the same interface", async () => {
+    const fb = new FallbackTransport([
+      failingTransport("a"),
+      okTransport("b"),
+    ]);
+    const r = await fb.send({
+      from: "a@b.c",
+      to: "d@e.f",
+      subject: "hi",
+      text: "x",
+    });
+    expect(r.provider).toBe("b");
+  });
+});
+
+describe("consent and i18n", () => {
+  test("opt-out blocks send and records receipt", async () => {
+    const consent = createConsentStore();
+    consent.optOut("user@example.com", "email");
+    const runtime = createChannelRuntime({
+      templates: [channel.template("news", { medium: "email" })],
+      drivers: [openConsoleChannel()],
+      consent,
+    });
+    const result = await runtime.send("news", { to: "user@example.com" });
+    expect(result.ok).toBe(false);
+    expect(runtime.receipts.all()[0]!.status).toBe("suppressed/opted-out");
+  });
+
+  test("prior hard bounce suppresses and records protective state", async () => {
+    const runtime = createChannelRuntime({
+      templates: [channel.template("news", { medium: "email" })],
+      drivers: [openConsoleChannel()],
+    });
+    await runtime.send("news", { to: "bounce@example.com" });
+    const sent = runtime.receipts.all()[0]!;
+    runtime.ingestOutcome({
+      messageId: sent.messageId!,
+      state: "hard-bounce",
+      to: "bounce@example.com",
+      medium: "email",
+    });
+    const blocked = await runtime.send("news", { to: "bounce@example.com" });
+    expect(blocked.ok).toBe(false);
+    expect(runtime.receipts.all().at(-1)!.status).toBe(
+      "suppressed/prior-bounce",
+    );
+  });
+
+  test("locale chain is recorded on the receipt", async () => {
+    const runtime = createChannelRuntime({
+      templates: [channel.template("hello", { medium: "email" })],
+      drivers: [openConsoleChannel()],
+      defaultLocale: "en",
+      catalog: { hello: { ar: { text: "أهلا" }, en: { text: "Hi" } } },
+    });
+    await runtime.send("hello", {
+      to: "a@b.c",
+      acceptLanguage: "ar-SA,en;q=0.8",
+    });
+    const receipt = runtime.receipts.all()[0]!;
+    expect(receipt.locale).toBe("ar-SA");
+    expect(receipt.localeChain).toEqual(["accept-language:ar-SA"]);
+  });
+
+  test("locale selects catalog body", async () => {
+    const inbox = createChannelInbox();
+    const runtime = createChannelRuntime({
+      templates: [
+        channel.template("hello", { medium: "email", locales: ["en", "ar"] }),
+      ],
+      drivers: [openConsoleChannel({ inbox })],
+      catalog: {
+        hello: {
+          en: { subject: "Hi", text: "Hello" },
+          ar: { subject: "مرحبا", text: "أهلا" },
+        },
+      },
+    });
+    await runtime.send("hello", { to: "a@b.c", locale: "ar" });
+    expect(inbox.entries[0]!.subject).toBe("مرحبا");
+    expect(inbox.entries[0]!.text).toBe("أهلا");
+  });
+});
+
+describe("console driver", () => {
+  test("dev inbox captures every medium", async () => {
+    const inbox = createChannelInbox();
+    const runtime = createChannelRuntime({
+      templates: [
+        channel.template("sms-otp", { medium: "sms" }),
+      ],
+      drivers: [openConsoleChannel({ inbox })],
+      catalog: {
+        "sms-otp": { en: { text: "code {{code}}" } },
+      },
+    });
+    await runtime.send("sms-otp", {
+      to: "+966500000000",
+      data: { code: "1234" },
+    });
+    expect(inbox.entries).toHaveLength(1);
+    expect(inbox.entries[0]!.medium).toBe("sms");
+    expect(inbox.entries[0]!.text).toBe("code 1234");
+  });
+});

package/src/elements/channel.ts

@@ -0,0 +1,109 @@
+/**
+ * Channel element — reaching humans.
+ *
+ * Physics: email · SMS · WhatsApp · push.
+ * Drivers: `console` · `smtp` · `resend` · `unifonic` · `wa-cloud` · `fcm` · `webpush`.
+ *
+ * Transport interface is identical to sently's so its transports run unchanged.
+ * MIME, attachments, retry, and the unified error hierarchy come from sently.
+ * OKE adds: declared templates with i18n, consent/opt-out, fallback chains
+ * recorded as chains, and delivery receipts.
+ */
+
+export { channel } from "./channel/declare.ts";
+export type {
+  ChannelMediumBinder,
+  ChannelMediumOptions,
+  ChannelTemplateDecl,
+  ChannelTemplateOptions,
+} from "./channel/declare.ts";
+
+export {
+  createChannelRuntime,
+} from "./channel/runtime.ts";
+export type {
+  ChannelRuntime,
+  ChannelSendOptions,
+  CreateChannelRuntimeOptions,
+  TemplateCatalog,
+} from "./channel/runtime.ts";
+
+export {
+  createConsentStore,
+  type ConsentStore,
+  type OptOut,
+} from "./channel/consent.ts";
+
+export {
+  createSuppressionStore,
+  type SuppressionEntry,
+  type SuppressionReason,
+  type SuppressionStore,
+} from "./channel/suppression.ts";
+
+export {
+  createReceiptLedger,
+  type DeliveryReceipt,
+  type DeliveryStatus,
+  type IngestOutcomeInput,
+  type ReceiptLedger,
+} from "./channel/receipts.ts";
+
+export {
+  buildOutcomeRows,
+  CONSEQUENCE_WEIGHT,
+  DELIVERY_OUTCOME_STATES,
+  formatAttemptChain,
+  isDeliveryOutcomeState,
+  rankByConsequence,
+  VERDICT_BY_STATE,
+  type DeliveryOutcomeState,
+  type DeliveryVerdict,
+  type OutcomeRow,
+} from "./channel/outcomes.ts";
+
+export {
+  formatLocaleChain,
+  isRtlLocale,
+  parseAcceptLanguage,
+  resolveLocale,
+  type LocaleChainStep,
+  type LocaleResolution,
+  type ResolveLocaleOptions,
+} from "./channel/locale.ts";
+
+export {
+  costOf,
+  DEFAULT_MEDIUM_COSTS,
+  fallbackWeeklyCostDelta,
+  type FallbackWeeklyCostDelta,
+  type MediumCosts,
+} from "./channel/costs.ts";
+
+export {
+  CHANNEL_PII_MASK,
+  maskEmail,
+  maskPhone,
+  maskRecipient,
+} from "./channel/mask.ts";
+
+export {
+  domainFromFrom,
+  verifyEmailAuth,
+  type AuthCheckStatus,
+  type DnsTxtLookup,
+  type EmailAuthResult,
+  type VerifyEmailAuthOptions,
+} from "./channel/email-auth.ts";
+
+export {
+  SentlyError,
+  RetryTransport,
+  FallbackTransport,
+  FallbackError,
+  type Attachment,
+  type MailOptions,
+  type SendResult,
+  type Transport,
+  type FallbackAttempt,
+} from "./channel/mime.ts";

package/src/elements/clock/actions.ts

@@ -0,0 +1,170 @@
+/**
+ * Clock operator actions — pause, edit schedule, wake early (console §9.6).
+ *
+ * Edit is refused unless `overridable`. Wake-early sets journal `wakeAt` to
+ * now and resumes the durable run immediately (Vault §9.8 cross-ref).
+ */
+
+import type { AnyFlowDef } from "../../kernel/flow.ts";
+import type { JournalStore } from "../../kernel/journal.ts";
+import { runDurable, type DurableResult } from "./durable.ts";
+import type { CronRow, CronStore } from "./reconcile.ts";
+
+/** Error when edit is refused. */
+export class ScheduleNotOverridableError extends Error {
+  override readonly name = "ScheduleNotOverridableError";
+  /** Cron name that refused edit. */
+  readonly cronName: string;
+
+  /**
+   * @param cronName - Cron name
+   */
+  constructor(cronName: string) {
+    super(`clock "${cronName}" is not overridable`);
+    this.cronName = cronName;
+  }
+}
+
+/** Error when a cron / run is missing. */
+export class ClockResourceNotFoundError extends Error {
+  override readonly name = "ClockResourceNotFoundError";
+  /** Resource kind. */
+  readonly kind: "cron" | "run";
+  /** Name or run id. */
+  readonly id: string;
+
+  /**
+   * @param kind - Resource kind
+   * @param id - Name or run id
+   */
+  constructor(kind: "cron" | "run", id: string) {
+    super(`${kind} "${id}" not found`);
+    this.kind = kind;
+    this.id = id;
+  }
+}
+
+/**
+ * Pause a cron (status → `"paused"`). Scheduler skips paused rows.
+ *
+ * @param store - Cron store
+ * @param name - Cron name
+ */
+export async function pauseCron(
+  store: CronStore,
+  name: string,
+): Promise<CronRow> {
+  const row = await store.get(name);
+  if (!row) throw new ClockResourceNotFoundError("cron", name);
+  const next: CronRow = { ...row, status: "paused" };
+  await store.put(next);
+  return next;
+}
+
+/** Schedule edit input (override fields). */
+export interface EditScheduleInput {
+  readonly name: string;
+  readonly cron?: string;
+  readonly every?: string;
+}
+
+/**
+ * Override an overridable schedule in the Store (console §4.1 / §5).
+ *
+ * @param store - Cron store
+ * @param input - Name + override cron and/or every
+ */
+export async function editSchedule(
+  store: CronStore,
+  input: EditScheduleInput,
+): Promise<CronRow> {
+  const row = await store.get(input.name);
+  if (!row) throw new ClockResourceNotFoundError("cron", input.name);
+  if (!row.overridable) {
+    throw new ScheduleNotOverridableError(input.name);
+  }
+  const overrideCron =
+    input.cron !== undefined ? input.cron : row.overrideCron;
+  const overrideEvery =
+    input.every !== undefined ? input.every : row.overrideEvery;
+  const next: CronRow = {
+    ...row,
+    overrideCron,
+    overrideEvery,
+    effectiveCron: overrideCron ?? row.declaredCron,
+    effectiveEvery: overrideEvery ?? row.declaredEvery,
+  };
+  await store.put(next);
+  return next;
+}
+
+/** Options for {@link wakeEarly}. */
+export interface WakeEarlyOptions {
+  readonly journal: JournalStore;
+  readonly runId: string;
+  readonly now?: () => number;
+  /**
+   * Optional flow registry — when provided, resumes immediately via
+   * {@link runDurable}. Without it, only `wakeAt` is advanced.
+   */
+  readonly resolveFlow?: (flowName: string) => AnyFlowDef | undefined;
+  /** Extra fx options forwarded to resume. */
+  readonly fx?: Parameters<typeof runDurable>[0]["fx"];
+}
+
+/** Outcome of wake-early. */
+export interface WakeEarlyResult {
+  readonly runId: string;
+  readonly wakeAt: number;
+  readonly resumed: boolean;
+  readonly durable?: DurableResult;
+}
+
+/**
+ * Wake a sleeping durable run early: set `wakeAt` to now and resume.
+ *
+ * @param options - Journal, run id, optional flow resolver
+ */
+export async function wakeEarly(
+  options: WakeEarlyOptions,
+): Promise<WakeEarlyResult> {
+  const now = options.now ?? (() => Date.now());
+  const t = now();
+  const run = await options.journal.get(options.runId);
+  if (!run || run.status !== "sleeping") {
+    throw new ClockResourceNotFoundError("run", options.runId);
+  }
+
+  const entries = run.entries.map((e) =>
+    e.kind === "sleep" && e.wakeAt === run.wakeAt
+      ? { ...e, wakeAt: t }
+      : e,
+  );
+  await options.journal.put({
+    ...run,
+    entries,
+    wakeAt: t,
+    updatedAt: t,
+  });
+
+  const flow = options.resolveFlow?.(run.flow);
+  if (!flow) {
+    return { runId: run.id, wakeAt: t, resumed: false };
+  }
+
+  const durable = await runDurable({
+    flow,
+    input: run.input,
+    journalStore: options.journal,
+    runId: run.id,
+    now,
+    fx: options.fx,
+  });
+
+  return {
+    runId: run.id,
+    wakeAt: t,
+    resumed: true,
+    durable,
+  };
+}

package/src/elements/clock/declare.ts

@@ -0,0 +1,58 @@
+/**
+ * Clock declaration — recurring schedules (cron / every).
+ *
+ * Named clocks are reconciled into the Store at boot; the scheduler reads
+ * the effective state from the Store (console §5), never the code directly.
+ */
+
+/** Options for {@link clock}. */
+export interface ClockOptions {
+  /** Cron expression (`m h dom mon dow`). */
+  readonly cron?: string;
+  /** Fixed interval (`"10m"`, `"1h"`). */
+  readonly every?: string;
+  /** IANA timezone (defaults to `"UTC"`). */
+  readonly timezone?: string;
+  /**
+   * When true, the Console may override the schedule in the Store.
+   * Without it, no override is possible (console §4.1).
+   */
+  readonly overridable?: boolean;
+}
+
+/**
+ * Declared clock handle — reconciled into `oke_crons` at boot.
+ */
+export interface ClockDecl {
+  /** Schedule name (manifest / store key). */
+  readonly name: string;
+  /** Cron expression when declared. */
+  readonly cron?: string;
+  /** Interval when declared. */
+  readonly every?: string;
+  /** IANA timezone. */
+  readonly timezone: string;
+  /** Whether Console override is allowed. */
+  readonly overridable: boolean;
+}
+
+/**
+ * Declare a named clock / cron schedule.
+ *
+ * @param name - Schedule name
+ * @param options - `cron` and/or `every`, timezone, overridable
+ */
+export function clock(name: string, options: ClockOptions = {}): ClockDecl {
+  if (!options.cron && !options.every) {
+    throw new TypeError(
+      `clock("${name}"): require cron or every`,
+    );
+  }
+  return {
+    name,
+    cron: options.cron,
+    every: options.every,
+    timezone: options.timezone ?? "UTC",
+    overridable: options.overridable ?? false,
+  };
+}