okengine 0.6.0 → 0.6.1

package/src/drivers/channel-fcm.ts

@@ -1,7 +1,9 @@
 /**
- * `fcm` channel driver — Firebase Cloud Messaging HTTP v1 (protocol-shaped).
+ * `fcm` channel driver — Firebase Cloud Messaging HTTP v1 via sently.
  */
 
+import { FcmTransport } from "sently/transports/fcm";
+import { mapSentlySendError, mapSentlySendResult } from "./channel-sently-map.ts";
 import type {
   ChannelDriver,
   ChannelMessage,
@@ -13,70 +15,64 @@ import type {
 /**
  * Open an FCM push driver.
  *
- * @param options - `token` (OAuth access token) + `from` (project id)
+ * Prefer service-account credentials (`clientEmail` + `privateKey` + `from`/
+ * `projectId`). For tests, pass `token` as a pre-fetched access token via
+ * `getAccessToken` (still requires `from` / project id).
+ *
+ * @param options - Project id + service account or injectable token
  */
 export function openFcmChannel(options: ChannelOpenOptions = {}): ChannelDriver {
+  const projectId = options.projectId ?? options.from;
+  if (!projectId) {
+    throw new Error("fcm channel: projectId (or from) is required");
+  }
+
+  const clientEmail = options.clientEmail ?? options.user;
+  const privateKey = options.privateKey ?? options.pass;
   const accessToken = options.token ?? options.apiKey;
-  const projectId = options.from;
-  const fetchFn = options.fetch ?? globalThis.fetch;
-  const base = options.url ?? "https://fcm.googleapis.com";
+
+  if (!accessToken && !(clientEmail && privateKey)) {
+    throw new Error(
+      "fcm channel: clientEmail+privateKey (service account) or token (access token) required",
+    );
+  }
+  if ((clientEmail && !privateKey) || (!clientEmail && privateKey)) {
+    throw new Error("fcm channel: clientEmail and privateKey must be provided together");
+  }
+
+  // Token-only mode (tests / pre-fetched OAuth): sently still requires placeholder
+  // service-account fields; getAccessToken skips JWT exchange.
+  const transport = new FcmTransport({
+    projectId,
+    clientEmail: clientEmail ?? "oke-fcm@local",
+    privateKey:
+      privateKey ??
+      "-----BEGIN PRIVATE KEY-----\nMIIEowIBAAKCAQEA0Z3VS5JJcds3xfn/ygWyF6PZGFw=\n-----END PRIVATE KEY-----\n",
+    ...(accessToken ? { getAccessToken: async () => accessToken } : {}),
+  });
 
   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(),
-            },
-          ],
-        };
+      try {
+        const title = message.subject ?? message.template ?? "notification";
+        const body = message.text ?? "";
+        const result = await transport.send({
+          token: message.to,
+          title,
+          body,
+          ...(message.data ? { data: { ...message.data } } : {}),
+        });
+        return mapSentlySendResult("fcm", result);
+      } catch (err) {
+        return mapSentlySendError("fcm", err);
       }
-      return {
-        ok: true,
-        messageId: id,
-        driverId: "fcm",
-        attempts: [{ driverId: "fcm", ok: true, at: Date.now(), messageId: id }],
-      };
     },
+    verify: () => transport.verify(),
   };
 
-  return { id: "fcm", channel };
+  return { id: "fcm", channel, pushTransport: transport };
 }
 
 /** FCM driver factory. */

package/src/drivers/channel-msegat.ts

@@ -0,0 +1,61 @@
+/**
+ * `msegat` channel driver — SMS via sently's Msegat transport.
+ */
+
+import { MsegatTransport } from "sently/transports/msegat";
+import { mapSentlySendError, mapSentlySendResult } from "./channel-sently-map.ts";
+import type {
+  ChannelDriver,
+  ChannelMessage,
+  ChannelOpenOptions,
+  ChannelSendResult,
+  ChannelTransport,
+} from "./channel-types.ts";
+
+/**
+ * Open a Msegat SMS driver.
+ *
+ * @param options - `userName`/`user` + `apiKey` + `sender`/`from`
+ */
+export function openMsegatChannel(options: ChannelOpenOptions = {}): ChannelDriver {
+  const userName = options.userName ?? options.user;
+  const apiKey = options.apiKey;
+  const sender = options.sender ?? options.from;
+  if (!userName) {
+    throw new Error("msegat channel: userName (or user) is required");
+  }
+  if (!apiKey) {
+    throw new Error("msegat channel: apiKey is required");
+  }
+  if (!sender) {
+    throw new Error("msegat channel: sender (or from) is required");
+  }
+
+  const transport = new MsegatTransport({ userName, apiKey, sender });
+
+  const channel: ChannelTransport = {
+    provider: "msegat",
+    mediums: ["sms"],
+    async send(message: ChannelMessage): Promise<ChannelSendResult> {
+      try {
+        const result = await transport.send({
+          to: message.to,
+          body: message.text ?? String(message.data?.code ?? ""),
+          ...(message.from ? { from: message.from } : {}),
+        });
+        return mapSentlySendResult("msegat", result);
+      } catch (err) {
+        return mapSentlySendError("msegat", err);
+      }
+    },
+    verify: () => transport.verify(),
+  };
+
+  return { id: "msegat", channel, smsTransport: transport };
+}
+
+/** Msegat driver factory. */
+export const msegatChannelDriver = {
+  id: "msegat" as const,
+  open: openMsegatChannel,
+};

package/src/drivers/channel-sently-map.ts

@@ -0,0 +1,57 @@
+/**
+ * Map sently channel send results into OKE {@link ChannelSendResult}.
+ */
+
+import { toChannelSendResult, type AnySendResult } from "sently/channel-result";
+import type { ChannelSendResult } from "./channel-types.ts";
+
+/**
+ * Convert a sently email/SMS/WhatsApp/push result into an OKE channel result.
+ *
+ * @param driverId - OKE driver id fallback when provider is missing
+ * @param result - Sently channel-specific send result
+ * @param at - Attempt timestamp
+ */
+export function mapSentlySendResult(
+  driverId: string,
+  result: AnySendResult,
+  at: number = Date.now(),
+): ChannelSendResult {
+  const normalized = toChannelSendResult(result);
+  const id = normalized.provider ?? driverId;
+  return {
+    ok: normalized.accepted,
+    messageId: normalized.messageId || crypto.randomUUID(),
+    driverId: id,
+    attempts: [
+      {
+        driverId: id,
+        ok: normalized.accepted,
+        at,
+        ...(normalized.messageId ? { messageId: normalized.messageId } : {}),
+      },
+    ],
+  };
+}
+
+/**
+ * Build a failed OKE channel result from a thrown error.
+ *
+ * @param driverId - Driver id
+ * @param err - Error
+ * @param at - Timestamp
+ */
+export function mapSentlySendError(
+  driverId: string,
+  err: unknown,
+  at: number = Date.now(),
+): ChannelSendResult {
+  const error = err instanceof Error ? err.message : String(err);
+  const id = crypto.randomUUID();
+  return {
+    ok: false,
+    messageId: id,
+    driverId,
+    attempts: [{ driverId, ok: false, error, at }],
+  };
+}

package/src/drivers/channel-sently.test.ts

@@ -0,0 +1,99 @@
+/**
+ * Sently-backed channel drivers — construction and message mapping.
+ */
+
+import { describe, expect, test } from "bun:test";
+import { openFcmChannel } from "./channel-fcm.ts";
+import { openMsegatChannel } from "./channel-msegat.ts";
+import { openSndrChannel } from "./channel-sndr.ts";
+import { openTaqnyatChannel } from "./channel-taqnyat.ts";
+import { openUnifonicChannel } from "./channel-unifonic.ts";
+import { openWaCloudChannel } from "./channel-wa-cloud.ts";
+import { openWebPushChannel } from "./channel-webpush.ts";
+
+describe("sently channel drivers", () => {
+  test("sndr requires apiKey", () => {
+    expect(() => openSndrChannel({})).toThrow("apiKey");
+    const d = openSndrChannel({ apiKey: "sndr_test_x" });
+    expect(d.id).toBe("sndr");
+    expect(d.transport?.provider).toBe("sndr");
+  });
+
+  test("taqnyat requires bearer + sender", () => {
+    expect(() => openTaqnyatChannel({ bearerToken: "t" })).toThrow("sender");
+    const d = openTaqnyatChannel({ bearerToken: "t", sender: "Brand" });
+    expect(d.id).toBe("taqnyat");
+    expect(d.channel?.mediums).toContain("sms");
+  });
+
+  test("msegat requires userName + apiKey + sender", () => {
+    expect(() => openMsegatChannel({ userName: "u", apiKey: "k" })).toThrow("sender");
+    const d = openMsegatChannel({ userName: "u", apiKey: "k", sender: "Brand" });
+    expect(d.id).toBe("msegat");
+    expect(d.smsTransport?.provider).toBe("msegat");
+  });
+
+  test("unifonic requires appSid and exposes smsTransport", () => {
+    expect(() => openUnifonicChannel({})).toThrow("appSid");
+    const d = openUnifonicChannel({ appSid: "sid", sender: "Brand" });
+    expect(d.id).toBe("unifonic");
+    expect(d.smsTransport?.provider).toBe("unifonic");
+  });
+
+  test("fcm accepts access-token mode", () => {
+    const d = openFcmChannel({ from: "my-project", token: "ya29.test" });
+    expect(d.id).toBe("fcm");
+    expect(d.pushTransport?.provider).toBe("fcm");
+  });
+
+  test("wa-cloud maps text and template sends", async () => {
+    const calls: unknown[] = [];
+    const originalFetch = globalThis.fetch;
+    globalThis.fetch = (async (_url: string | URL | Request, init?: RequestInit) => {
+      calls.push(JSON.parse(String(init?.body ?? "{}")));
+      return new Response(JSON.stringify({ messages: [{ id: "wamid.1" }] }), { status: 200 });
+    }) as typeof fetch;
+    try {
+      const d = openWaCloudChannel({ token: "tok", from: "123" });
+      const text = await d.channel!.send({
+        medium: "whatsapp",
+        to: "15551234567",
+        text: "hi",
+      });
+      expect(text.ok).toBe(true);
+      expect(text.messageId).toBe("wamid.1");
+      expect(calls[0]).toMatchObject({
+        messaging_product: "whatsapp",
+        to: "15551234567",
+        type: "text",
+      });
+
+      const tpl = await d.channel!.send({
+        medium: "whatsapp",
+        to: "15551234567",
+        template: "welcome",
+        locale: "en_US",
+      });
+      expect(tpl.ok).toBe(true);
+      expect(calls[1]).toMatchObject({
+        type: "template",
+        template: { name: "welcome", language: { code: "en_US" } },
+      });
+    } finally {
+      globalThis.fetch = originalFetch;
+    }
+  });
+
+  test("webpush requires subscription keys", async () => {
+    const d = openWebPushChannel({
+      vapidPublicKey: "BPtestpublickeythatislongenoughforvapidxxxxxxxxxxxx",
+      vapidPrivateKey: "dGVzdC1wcml2YXRlLWtleS0zMmJ5dGVzLW9rISEh",
+      vapidSubject: "mailto:ops@example.com",
+    });
+    expect(d.id).toBe("webpush");
+    expect(d.pushTransport?.provider).toBe("webpush");
+    await expect(
+      d.channel!.send({ medium: "push", to: "https://fcm.googleapis.com/fcm/send/x" }),
+    ).rejects.toThrow("pushSubscription");
+  });
+});

package/src/drivers/channel-sndr.ts

@@ -0,0 +1,28 @@
+/**
+ * `sndr` channel driver — wraps sently's SNDR transport unchanged.
+ */
+
+import { SndrTransport } from "sently/transports/sndr";
+import type { ChannelDriver, ChannelOpenOptions } from "./channel-types.ts";
+
+/**
+ * Open an SNDR channel driver.
+ *
+ * @param options - API key
+ */
+export function openSndrChannel(options: ChannelOpenOptions = {}): ChannelDriver {
+  if (!options.apiKey) {
+    throw new Error("sndr channel: apiKey is required");
+  }
+  const transport = new SndrTransport({
+    apiKey: options.apiKey,
+    ...(options.url ? { baseUrl: options.url } : {}),
+  });
+  return { id: "sndr", transport };
+}
+
+/** SNDR driver factory. */
+export const sndrChannelDriver = {
+  id: "sndr" as const,
+  open: openSndrChannel,
+};

package/src/drivers/channel-taqnyat.ts

@@ -0,0 +1,57 @@
+/**
+ * `taqnyat` channel driver — SMS via sently's Taqnyat transport.
+ */
+
+import { TaqnyatSmsTransport } from "sently/transports/taqnyat-sms";
+import { mapSentlySendError, mapSentlySendResult } from "./channel-sently-map.ts";
+import type {
+  ChannelDriver,
+  ChannelMessage,
+  ChannelOpenOptions,
+  ChannelSendResult,
+  ChannelTransport,
+} from "./channel-types.ts";
+
+/**
+ * Open a Taqnyat SMS driver.
+ *
+ * @param options - `bearerToken`/`token`/`apiKey` + `sender`/`from`
+ */
+export function openTaqnyatChannel(options: ChannelOpenOptions = {}): ChannelDriver {
+  const bearerToken = options.bearerToken ?? options.token ?? options.apiKey;
+  const sender = options.sender ?? options.from;
+  if (!bearerToken) {
+    throw new Error("taqnyat channel: bearerToken (or token/apiKey) is required");
+  }
+  if (!sender) {
+    throw new Error("taqnyat channel: sender (or from) is required");
+  }
+
+  const transport = new TaqnyatSmsTransport({ bearerToken, sender });
+
+  const channel: ChannelTransport = {
+    provider: "taqnyat",
+    mediums: ["sms"],
+    async send(message: ChannelMessage): Promise<ChannelSendResult> {
+      try {
+        const result = await transport.send({
+          to: message.to,
+          body: message.text ?? String(message.data?.code ?? ""),
+          ...(message.from ? { from: message.from } : {}),
+        });
+        return mapSentlySendResult("taqnyat", result);
+      } catch (err) {
+        return mapSentlySendError("taqnyat", err);
+      }
+    },
+    verify: () => transport.verify(),
+  };
+
+  return { id: "taqnyat", channel, smsTransport: transport };
+}
+
+/** Taqnyat driver factory. */
+export const taqnyatChannelDriver = {
+  id: "taqnyat" as const,
+  open: openTaqnyatChannel,
+};

package/src/drivers/channel-types.ts

@@ -2,7 +2,8 @@
  * 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}.
+ * run unchanged. Non-email media expose sently SMS / WhatsApp / Push transports
+ * plus a {@link ChannelTransport} adapter for the OKE runtime.
  */
 
 import type { MailOptions, SendResult, Transport, VerifyResult } from "sently";
@@ -19,11 +20,66 @@ export type {
   RetryConfig,
 } from "sently";
 
+/**
+ * Sently-compatible SMS transport (structural — sently keeps `SmsTransport` on
+ * internal sms-types; OKE drivers wrap concrete sently transports).
+ */
+export interface SmsTransport {
+  readonly provider?: string;
+  send(options: {
+    readonly to: string;
+    readonly body: string;
+    readonly from?: string;
+    readonly messageId?: string;
+  }): Promise<{
+    readonly messageId: string;
+    readonly to: string;
+    readonly status: string;
+    readonly response: string;
+    readonly provider?: string;
+    readonly providerIndex?: number;
+  }>;
+  verify?(): Promise<VerifyResult>;
+  close?(): Promise<void>;
+}
+
+/** Sently-compatible WhatsApp transport (structural). */
+export interface WhatsAppTransport {
+  readonly provider?: string;
+  send(options: unknown): Promise<{
+    readonly messageId: string;
+    readonly to: string;
+    readonly status: string;
+    readonly response: string;
+    readonly provider?: string;
+    readonly providerIndex?: number;
+  }>;
+  verify?(): Promise<VerifyResult>;
+  close?(): Promise<void>;
+}
+
+/** Sently-compatible push transport (structural). */
+export interface PushTransport {
+  readonly provider?: string;
+  send(options: unknown): Promise<{
+    readonly messageId: string;
+    readonly status: string;
+    readonly response: string;
+    readonly provider?: string;
+    readonly providerIndex?: number;
+  }>;
+  verify?(): Promise<VerifyResult>;
+  close?(): Promise<void>;
+}
+
 /** Protocol ids for channel drivers. */
 export type ChannelDriverId =
   | "console"
   | "smtp"
   | "resend"
+  | "sndr"
+  | "taqnyat"
+  | "msegat"
   | "unifonic"
   | "wa-cloud"
   | "fcm"
@@ -82,12 +138,19 @@ export interface ChannelTransport {
 
 /**
  * Dual-shape driver: email drivers expose a sently {@link Transport};
- * others expose a {@link ChannelTransport}.
+ * SMS / WhatsApp / push expose the matching sently transport plus a
+ * {@link ChannelTransport} adapter.
  */
 export interface ChannelDriver {
   readonly id: ChannelDriverId;
   /** Sently-compatible email transport (smtp / resend / console-email). */
   readonly transport?: Transport;
+  /** Sently SMS transport (used by runtime FallbackTransport chains). */
+  readonly smsTransport?: SmsTransport;
+  /** Sently WhatsApp transport. */
+  readonly whatsappTransport?: WhatsAppTransport;
+  /** Sently push transport (webpush / fcm). */
+  readonly pushTransport?: PushTransport;
   /** Medium-agnostic transport. */
   readonly channel?: ChannelTransport;
 }
@@ -102,6 +165,20 @@ export interface ChannelOpenOptions {
   readonly pass?: string;
   readonly url?: string;
   readonly token?: string;
+  /** Taqnyat bearer (alias of `token` / `apiKey`). */
+  readonly bearerToken?: string;
+  /** Msegat account username (alias of `user`). */
+  readonly userName?: string;
+  /** SMS alphanumeric sender id (alias of `from`). */
+  readonly sender?: string;
+  /** Unifonic AppSid (alias of `apiKey`). */
+  readonly appSid?: string;
+  /** FCM / GCP project id (alias of `from`). */
+  readonly projectId?: string;
+  /** FCM service-account client email. */
+  readonly clientEmail?: string;
+  /** FCM service-account PEM private key. */
+  readonly privateKey?: string;
   /** VAPID keys for webpush. */
   readonly vapidPublicKey?: string;
   readonly vapidPrivateKey?: string;

package/src/drivers/channel-unifonic.ts

@@ -1,7 +1,9 @@
 /**
- * `unifonic` channel driver — SMS via Unifonic REST API.
+ * `unifonic` channel driver — SMS via sently's Unifonic transport.
  */
 
+import { UnifonicTransport } from "sently/transports/unifonic";
+import { mapSentlySendError, mapSentlySendResult } from "./channel-sently-map.ts";
 import type {
   ChannelDriver,
   ChannelMessage,
@@ -13,59 +15,40 @@ import type {
 /**
  * Open a Unifonic SMS driver.
  *
- * @param options - `apiKey` + optional `from` (sender id)
+ * @param options - `apiKey`/`appSid` (AppSid) + optional `sender`/`from` (SenderID)
  */
 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 appSid = options.appSid ?? options.apiKey;
+  const senderId = options.sender ?? options.from;
+  if (!appSid) {
+    throw new Error("unifonic channel: appSid (or apiKey) is required");
+  }
+
+  const transport = new UnifonicTransport({
+    appSid,
+    ...(senderId ? { senderId } : {}),
+    ...(options.url?.startsWith("https://") ? { statusCallback: options.url } : {}),
+  });
 
   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(),
-            },
-          ],
-        };
+      try {
+        const result = await transport.send({
+          to: message.to,
+          body: message.text ?? String(message.data?.code ?? ""),
+          ...(message.from ? { from: message.from } : {}),
+        });
+        return mapSentlySendResult("unifonic", result);
+      } catch (err) {
+        return mapSentlySendError("unifonic", err);
       }
-      return {
-        ok: true,
-        messageId: id,
-        driverId: "unifonic",
-        attempts: [{ driverId: "unifonic", ok: true, at: Date.now(), messageId: id }],
-      };
     },
+    verify: () => transport.verify(),
   };
 
-  return { id: "unifonic", channel };
+  return { id: "unifonic", channel, smsTransport: transport };
 }
 
 /** Unifonic driver factory. */