okengine 0.1.4

package/src/drivers/bun-native-completeness.test.ts

@@ -0,0 +1,155 @@
+/**
+ * Bun native-client completeness — gaps closed vs platform limitations.
+ *
+ * Checked against Bun 1.3.14 (runtime + bun-types). Do not invent custom
+ * protocol clients where Bun still lacks an API.
+ */
+
+import { describe, expect, test } from "bun:test";
+import { createBunRedisClient } from "./redis.ts";
+import {
+  createBunSignalRedisClient,
+  parseXreadgroupReply,
+} from "./signal-redis.ts";
+
+/** One row in the completeness report. */
+export interface BunNativeGapRow {
+  readonly surface: string;
+  readonly capability: string;
+  readonly status: "closed" | "bun_limitation";
+  readonly note: string;
+}
+
+/**
+ * Report table: which Bun client gaps closed vs genuine platform limits.
+ *
+ * Kept as a pure function so the gate test and human report share one source.
+ */
+export function bunNativeCompletenessReport(): readonly BunNativeGapRow[] {
+  const redisProto = Bun.RedisClient.prototype as unknown as Record<
+    string,
+    unknown
+  >;
+  const hasTypedScan = typeof redisProto.scan === "function";
+  const hasTypedPublish = typeof redisProto.publish === "function";
+  const hasTypedSubscribe = typeof redisProto.subscribe === "function";
+  const hasTypedSend = typeof redisProto.send === "function";
+  const hasTypedXadd = typeof redisProto.xadd === "function";
+  const hasTypedEval = typeof redisProto.eval === "function";
+
+  return [
+    {
+      surface: "redis kv",
+      capability: "SCAN (typed)",
+      status: hasTypedScan ? "closed" : "bun_limitation",
+      note: hasTypedScan
+        ? "createBunRedisClient binds RedisClient.scan"
+        : "Bun.redis.scan unavailable — would keep send(SCAN)",
+    },
+    {
+      surface: "redis kv",
+      capability: "EVAL (typed)",
+      status: hasTypedEval ? "closed" : "bun_limitation",
+      note: hasTypedEval
+        ? "typed eval bound"
+        : "Bun 1.3.14 has no typed eval — driver uses send(EVAL)",
+    },
+    {
+      surface: "redis signal",
+      capability: "native Bun bind (publish/subscribe)",
+      status:
+        hasTypedPublish && hasTypedSubscribe ? "closed" : "bun_limitation",
+      note:
+        hasTypedPublish && hasTypedSubscribe
+          ? "createBunSignalRedisClient uses typed publish/subscribe"
+          : "pub/sub still unavailable on Bun.RedisClient",
+    },
+    {
+      surface: "redis signal",
+      capability: "XADD / XREADGROUP (typed)",
+      status: hasTypedXadd ? "closed" : "bun_limitation",
+      note: hasTypedXadd
+        ? "typed stream helpers bound"
+        : "Bun 1.3.14 has no typed xadd — Streams use send (native, not a custom client)",
+    },
+    {
+      surface: "redis signal",
+      capability: "send escape hatch",
+      status: hasTypedSend ? "closed" : "bun_limitation",
+      note: hasTypedSend
+        ? "send present — Streams/EVAL ride the native client"
+        : "Bun.RedisClient.send missing",
+    },
+    {
+      surface: "postgres signal",
+      capability: "LISTEN / NOTIFY on Bun.SQL",
+      status: "bun_limitation",
+      note: "Bun.SQL has no listen/notify API — injectable PostgresSignalSql + fake remain",
+    },
+    {
+      surface: "postgres sql",
+      capability: "Bun.SQL.unsafe query/exec",
+      status: "closed",
+      note: "postgres driver already binds Bun.SQL; fake only for CI without a server",
+    },
+    {
+      surface: "s3 files",
+      capability: "Bun.S3Client file/list",
+      status: "closed",
+      note: "s3 driver binds write/arrayBuffer/exists/delete/list; presign/multipart unused by FilesBucket",
+    },
+  ];
+}
+
+describe("Bun native client completeness", () => {
+  test("report table is exact and matches runtime Bun 1.3.x", () => {
+    const rows = bunNativeCompletenessReport();
+    expect(rows.length).toBe(8);
+
+    const closed = rows.filter((r) => r.status === "closed").map((r) => r.capability);
+    const limited = rows
+      .filter((r) => r.status === "bun_limitation")
+      .map((r) => r.capability);
+
+    // Closed on Bun 1.3.14
+    expect(closed).toContain("SCAN (typed)");
+    expect(closed).toContain("native Bun bind (publish/subscribe)");
+    expect(closed).toContain("send escape hatch");
+    expect(closed).toContain("Bun.SQL.unsafe query/exec");
+    expect(closed).toContain("Bun.S3Client file/list");
+
+    // Genuine Bun platform limitations (do not invent workarounds)
+    expect(limited).toContain("EVAL (typed)");
+    expect(limited).toContain("XADD / XREADGROUP (typed)");
+    expect(limited).toContain("LISTEN / NOTIFY on Bun.SQL");
+  });
+
+  test("createBunRedisClient exposes native scan", () => {
+    const client = createBunRedisClient();
+    expect(typeof client.scan).toBe("function");
+  });
+
+  test("createBunSignalRedisClient exposes stream + pub/sub surface", () => {
+    const client = createBunSignalRedisClient();
+    expect(typeof client.xadd).toBe("function");
+    expect(typeof client.publish).toBe("function");
+    expect(typeof client.subscribe).toBe("function");
+  });
+
+  test("parseXreadgroupReply reads nested Redis arrays", () => {
+    const parsed = parseXreadgroupReply([
+      [
+        "oke:signal:order",
+        [
+          ["1-0", ["payload", "{\"a\":1}", "signal", "order"]],
+          ["1-1", ["payload", "{}", "signal", "order"]],
+        ],
+      ],
+    ]);
+    expect(parsed).toEqual([
+      { id: "1-0", fields: { payload: "{\"a\":1}", signal: "order" } },
+      { id: "1-1", fields: { payload: "{}", signal: "order" } },
+    ]);
+    expect(parseXreadgroupReply(null)).toEqual([]);
+  });
+});

package/src/drivers/channel-console.ts

@@ -0,0 +1,118 @@
+/**
+ * `console` channel driver — dev inbox for every medium.
+ */
+
+import type { AddressInput, MailOptions, SendResult, Transport } from "sently";
+import type {
+  ChannelDriver,
+  ChannelInbox,
+  ChannelMessage,
+  ChannelOpenOptions,
+  ChannelSendResult,
+  ChannelTransport,
+} from "./channel-types.ts";
+import { createChannelInbox } from "./channel-types.ts";
+
+/**
+ * Flatten a sently {@link AddressInput} to a comma-separated string.
+ *
+ * @param input - Address input
+ */
+function formatAddressInput(input: AddressInput): string {
+  if (typeof input === "string") return input;
+  if (Array.isArray(input)) {
+    return input
+      .map((t) => (typeof t === "string" ? t : t.address))
+      .join(",");
+  }
+  return input.address;
+}
+
+/**
+ * Open a console channel driver bound to an inbox.
+ *
+ * @param options - Optional shared inbox
+ */
+export function openConsoleChannel(
+  options: ChannelOpenOptions = {},
+): ChannelDriver {
+  const inbox = options.inbox ?? createChannelInbox();
+
+  const channel: ChannelTransport = {
+    provider: "console",
+    mediums: ["email", "sms", "whatsapp", "push", "any"],
+    async send(message: ChannelMessage): Promise<ChannelSendResult> {
+      const id = crypto.randomUUID();
+      inbox.push({
+        id,
+        medium: message.medium,
+        to: message.to,
+        subject: message.subject,
+        text: message.text,
+        html: message.html,
+        data: message.data,
+        template: message.template,
+        locale: message.locale,
+        at: Date.now(),
+      });
+      return {
+        ok: true,
+        messageId: id,
+        driverId: "console",
+        attempts: [
+          {
+            driverId: "console",
+            ok: true,
+            at: Date.now(),
+            messageId: id,
+          },
+        ],
+      };
+    },
+  };
+
+  const transport: Transport = {
+    provider: "console",
+    async send(mail: MailOptions): Promise<SendResult> {
+      const to = formatAddressInput(mail.to);
+      const from = formatAddressInput(mail.from);
+      const id = crypto.randomUUID();
+      inbox.push({
+        id,
+        medium: "email",
+        to,
+        subject: mail.subject,
+        text: mail.text,
+        html: mail.html,
+        data: mail.data,
+        template: mail.template,
+        at: Date.now(),
+      });
+      const recipients = to.split(",").map((s) => s.trim()).filter(Boolean);
+      return {
+        messageId: id,
+        accepted: recipients,
+        rejected: [],
+        response: "console: accepted",
+        envelope: {
+          from,
+          to: recipients,
+        },
+        provider: "console",
+        providerIndex: 0,
+      };
+    },
+  };
+
+  return { id: "console", transport, channel };
+}
+
+/**
+ * Console driver factory (stateless open via {@link openConsoleChannel}).
+ */
+export const consoleChannelDriver = {
+  id: "console" as const,
+  open: openConsoleChannel,
+};
+
+export type { ChannelInbox };

package/src/drivers/channel-fcm.ts

@@ -0,0 +1,96 @@
+/**
+ * `fcm` channel driver — Firebase Cloud Messaging HTTP v1 (protocol-shaped).
+ */
+
+import type {
+  ChannelDriver,
+  ChannelMessage,
+  ChannelOpenOptions,
+  ChannelSendResult,
+  ChannelTransport,
+} from "./channel-types.ts";
+
+/**
+ * Open an FCM push driver.
+ *
+ * @param options - `token` (OAuth access token) + `from` (project id)
+ */
+export function openFcmChannel(
+  options: ChannelOpenOptions = {},
+): ChannelDriver {
+  const accessToken = options.token ?? options.apiKey;
+  const projectId = options.from;
+  const fetchFn = options.fetch ?? globalThis.fetch;
+  const base = options.url ?? "https://fcm.googleapis.com";
+
+  const channel: ChannelTransport = {
+    provider: "fcm",
+    mediums: ["push"],
+    async send(message: ChannelMessage): Promise<ChannelSendResult> {
+      if (!accessToken || !projectId) {
+        throw new Error("fcm: token and from (project id) are required");
+      }
+      const res = await fetchFn(
+        `${base}/v1/projects/${projectId}/messages:send`,
+        {
+          method: "POST",
+          headers: {
+            Authorization: `Bearer ${accessToken}`,
+            "Content-Type": "application/json",
+          },
+          body: JSON.stringify({
+            message: {
+              token: message.to,
+              notification: {
+                title: message.subject ?? message.template ?? "notification",
+                body: message.text ?? "",
+              },
+              data: Object.fromEntries(
+                Object.entries(message.data ?? {}).map(([k, v]) => [
+                  k,
+                  String(v),
+                ]),
+              ),
+            },
+          }),
+        },
+      );
+      const body = (await res.json().catch(() => ({}))) as {
+        name?: string;
+        error?: { message?: string };
+      };
+      const id = body.name ?? crypto.randomUUID();
+      if (!res.ok) {
+        return {
+          ok: false,
+          messageId: id,
+          driverId: "fcm",
+          attempts: [
+            {
+              driverId: "fcm",
+              ok: false,
+              error: body.error?.message ?? `HTTP ${res.status}`,
+              at: Date.now(),
+            },
+          ],
+        };
+      }
+      return {
+        ok: true,
+        messageId: id,
+        driverId: "fcm",
+        attempts: [
+          { driverId: "fcm", ok: true, at: Date.now(), messageId: id },
+        ],
+      };
+    },
+  };
+
+  return { id: "fcm", channel };
+}
+
+/** FCM driver factory. */
+export const fcmChannelDriver = {
+  id: "fcm" as const,
+  open: openFcmChannel,
+};

package/src/drivers/channel-resend.ts

@@ -0,0 +1,27 @@
+/**
+ * `resend` channel driver — wraps sently's Resend transport unchanged.
+ */
+
+import { ResendTransport } from "sently/transports/resend";
+import type { ChannelDriver, ChannelOpenOptions } from "./channel-types.ts";
+
+/**
+ * Open a Resend channel driver.
+ *
+ * @param options - API key
+ */
+export function openResendChannel(
+  options: ChannelOpenOptions = {},
+): ChannelDriver {
+  if (!options.apiKey) {
+    throw new Error("resend channel: apiKey is required");
+  }
+  const transport = new ResendTransport({ apiKey: options.apiKey });
+  return { id: "resend", transport };
+}
+
+/** Resend driver factory. */
+export const resendChannelDriver = {
+  id: "resend" as const,
+  open: openResendChannel,
+};

package/src/drivers/channel-smtp.ts

@@ -0,0 +1,33 @@
+/**
+ * `smtp` channel driver — wraps sently's SMTP transport unchanged.
+ */
+
+import { SMTPTransport } from "sently/transports/smtp";
+import type { ChannelDriver, ChannelOpenOptions } from "./channel-types.ts";
+
+/**
+ * Open an SMTP channel driver.
+ *
+ * @param options - Host / port / auth
+ */
+export function openSmtpChannel(
+  options: ChannelOpenOptions = {},
+): ChannelDriver {
+  if (!options.host) {
+    throw new Error("smtp channel: host is required");
+  }
+  const transport = new SMTPTransport({
+    host: options.host,
+    port: options.port ?? 587,
+    ...(options.user && options.pass
+      ? { auth: { user: options.user, pass: options.pass } }
+      : {}),
+  });
+  return { id: "smtp", transport };
+}
+
+/** SMTP driver factory. */
+export const smtpChannelDriver = {
+  id: "smtp" as const,
+  open: openSmtpChannel,
+};

package/src/drivers/channel-types.ts

@@ -0,0 +1,160 @@
+/**
+ * Protocol-named channel driver contracts.
+ *
+ * Email transports implement sently's {@link Transport} so sently transports
+ * run unchanged. Non-email media (sms / whatsapp / push) use {@link ChannelTransport}.
+ */
+
+import type {
+  MailOptions,
+  SendResult,
+  Transport,
+  VerifyResult,
+} from "sently";
+
+export type {
+  Address,
+  AddressInput,
+  Attachment,
+  MailOptions,
+  SendResult,
+  Transport,
+  VerifyResult,
+  Envelope,
+  RetryConfig,
+} from "sently";
+
+/** Protocol ids for channel drivers. */
+export type ChannelDriverId =
+  | "console"
+  | "smtp"
+  | "resend"
+  | "unifonic"
+  | "wa-cloud"
+  | "fcm"
+  | "webpush";
+
+/** Channel medium. */
+export type ChannelMediumId =
+  | "email"
+  | "sms"
+  | "whatsapp"
+  | "push"
+  | "any";
+
+/** Unified outbound message (medium-agnostic). */
+export interface ChannelMessage {
+  readonly medium: ChannelMediumId;
+  readonly to: string;
+  readonly from?: string;
+  readonly subject?: string;
+  readonly text?: string;
+  readonly html?: string;
+  readonly data?: Readonly<Record<string, unknown>>;
+  readonly locale?: string;
+  readonly template?: string;
+  /** Raw email options when medium is email (sently-compatible). */
+  readonly mail?: MailOptions;
+  /** Web Push subscription endpoint + keys. */
+  readonly pushSubscription?: {
+    readonly endpoint: string;
+    readonly keys: { readonly p256dh: string; readonly auth: string };
+  };
+}
+
+/** Delivery attempt record (fallback chains record every try). */
+export interface ChannelAttempt {
+  readonly driverId: ChannelDriverId | string;
+  readonly ok: boolean;
+  readonly error?: string;
+  readonly at: number;
+  readonly messageId?: string;
+}
+
+/** Result of a channel send including chain history. */
+export interface ChannelSendResult {
+  readonly ok: boolean;
+  readonly messageId: string;
+  readonly driverId: string;
+  readonly attempts: readonly ChannelAttempt[];
+  /** Present when an email transport returned a sently {@link SendResult}. */
+  readonly mail?: SendResult;
+}
+
+/** Medium-agnostic transport (sms / whatsapp / push / console). */
+export interface ChannelTransport {
+  readonly provider: string;
+  readonly mediums: readonly ChannelMediumId[];
+  send(message: ChannelMessage): Promise<ChannelSendResult>;
+  verify?(): Promise<VerifyResult>;
+  close?(): Promise<void>;
+}
+
+/**
+ * Dual-shape driver: email drivers expose a sently {@link Transport};
+ * others expose a {@link ChannelTransport}.
+ */
+export interface ChannelDriver {
+  readonly id: ChannelDriverId;
+  /** Sently-compatible email transport (smtp / resend / console-email). */
+  readonly transport?: Transport;
+  /** Medium-agnostic transport. */
+  readonly channel?: ChannelTransport;
+}
+
+/** Open options shared by channel drivers. */
+export interface ChannelOpenOptions {
+  readonly apiKey?: string;
+  readonly from?: string;
+  readonly host?: string;
+  readonly port?: number;
+  readonly user?: string;
+  readonly pass?: string;
+  readonly url?: string;
+  readonly token?: string;
+  /** VAPID keys for webpush. */
+  readonly vapidPublicKey?: string;
+  readonly vapidPrivateKey?: string;
+  readonly vapidSubject?: string;
+  /** Injected fetch for HTTP drivers. */
+  readonly fetch?: typeof globalThis.fetch;
+  /** Dev inbox sink for console driver. */
+  readonly inbox?: ChannelInbox;
+}
+
+/** Dev inbox entry. */
+export interface ChannelInboxEntry {
+  readonly id: string;
+  readonly medium: ChannelMediumId;
+  readonly to: string;
+  readonly subject?: string;
+  readonly text?: string;
+  readonly html?: string;
+  readonly data?: Readonly<Record<string, unknown>>;
+  readonly template?: string;
+  readonly locale?: string;
+  readonly at: number;
+}
+
+/** Mutable dev inbox. */
+export interface ChannelInbox {
+  readonly entries: ChannelInboxEntry[];
+  push(entry: ChannelInboxEntry): void;
+  clear(): void;
+}
+
+/**
+ * Create an in-memory inbox for the console driver.
+ */
+export function createChannelInbox(): ChannelInbox {
+  const entries: ChannelInboxEntry[] = [];
+  return {
+    entries,
+    push(entry) {
+      entries.push(entry);
+    },
+    clear() {
+      entries.length = 0;
+    },
+  };
+}

package/src/drivers/channel-unifonic.ts

@@ -0,0 +1,79 @@
+/**
+ * `unifonic` channel driver — SMS via Unifonic REST API.
+ */
+
+import type {
+  ChannelDriver,
+  ChannelMessage,
+  ChannelOpenOptions,
+  ChannelSendResult,
+  ChannelTransport,
+} from "./channel-types.ts";
+
+/**
+ * Open a Unifonic SMS driver.
+ *
+ * @param options - `apiKey` + optional `from` (sender id)
+ */
+export function openUnifonicChannel(
+  options: ChannelOpenOptions = {},
+): ChannelDriver {
+  const apiKey = options.apiKey;
+  const from = options.from ?? "OKE";
+  const fetchFn = options.fetch ?? globalThis.fetch;
+  const base = options.url ?? "https://el.cloud.unifonic.com";
+
+  const channel: ChannelTransport = {
+    provider: "unifonic",
+    mediums: ["sms"],
+    async send(message: ChannelMessage): Promise<ChannelSendResult> {
+      if (!apiKey) {
+        throw new Error("unifonic: apiKey is required");
+      }
+      const body = new URLSearchParams({
+        AppSid: apiKey,
+        Recipient: message.to,
+        Body: message.text ?? String(message.data?.code ?? ""),
+        SenderID: message.from ?? from,
+      });
+      const res = await fetchFn(`${base}/rest/SMS/messages`, {
+        method: "POST",
+        headers: { "Content-Type": "application/x-www-form-urlencoded" },
+        body,
+      });
+      const text = await res.text();
+      const id = crypto.randomUUID();
+      if (!res.ok) {
+        return {
+          ok: false,
+          messageId: id,
+          driverId: "unifonic",
+          attempts: [
+            {
+              driverId: "unifonic",
+              ok: false,
+              error: text || `HTTP ${res.status}`,
+              at: Date.now(),
+            },
+          ],
+        };
+      }
+      return {
+        ok: true,
+        messageId: id,
+        driverId: "unifonic",
+        attempts: [
+          { driverId: "unifonic", ok: true, at: Date.now(), messageId: id },
+        ],
+      };
+    },
+  };
+
+  return { id: "unifonic", channel };
+}
+
+/** Unifonic driver factory. */
+export const unifonicChannelDriver = {
+  id: "unifonic" as const,
+  open: openUnifonicChannel,
+};