okengine 0.6.0 → 0.7.0

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. */

package/src/drivers/channel-wa-cloud.ts

@@ -1,7 +1,9 @@
 /**
- * `wa-cloud` channel driver — WhatsApp Cloud API (Meta).
+ * `wa-cloud` channel driver — WhatsApp Cloud API via sently.
  */
 
+import { WhatsAppCloudTransport } from "sently/transports/whatsapp-cloud";
+import { mapSentlySendError, mapSentlySendResult } from "./channel-sently-map.ts";
 import type {
   ChannelDriver,
   ChannelMessage,
@@ -13,64 +15,48 @@ import type {
 /**
  * Open a WhatsApp Cloud API driver.
  *
- * @param options - `token` (access token) + `from` (phone number id)
+ * @param options - `token`/`apiKey` (access token) + `from` (phone number id)
  */
 export function openWaCloudChannel(options: ChannelOpenOptions = {}): ChannelDriver {
-  const token = options.token ?? options.apiKey;
+  const accessToken = options.token ?? options.apiKey;
   const phoneNumberId = options.from;
-  const fetchFn = options.fetch ?? globalThis.fetch;
-  const base = options.url ?? "https://graph.facebook.com/v19.0";
+  if (!accessToken || !phoneNumberId) {
+    throw new Error("wa-cloud: token and from (phone number id) are required");
+  }
+
+  const transport = new WhatsAppCloudTransport({ accessToken, phoneNumberId });
 
   const channel: ChannelTransport = {
     provider: "wa-cloud",
     mediums: ["whatsapp"],
     async send(message: ChannelMessage): Promise<ChannelSendResult> {
-      if (!token || !phoneNumberId) {
-        throw new Error("wa-cloud: token and from (phone number id) are required");
-      }
-      const res = await fetchFn(`${base}/${phoneNumberId}/messages`, {
-        method: "POST",
-        headers: {
-          Authorization: `Bearer ${token}`,
-          "Content-Type": "application/json",
-        },
-        body: JSON.stringify({
-          messaging_product: "whatsapp",
-          to: message.to,
-          type: "text",
-          text: { body: message.text ?? "" },
-        }),
-      });
-      const body = (await res.json().catch(() => ({}))) as {
-        messages?: Array<{ id?: string }>;
-        error?: { message?: string };
-      };
-      const id = body.messages?.[0]?.id ?? crypto.randomUUID();
-      if (!res.ok) {
-        return {
-          ok: false,
-          messageId: id,
-          driverId: "wa-cloud",
-          attempts: [
-            {
-              driverId: "wa-cloud",
-              ok: false,
-              error: body.error?.message ?? `HTTP ${res.status}`,
-              at: Date.now(),
-            },
-          ],
-        };
+      try {
+        const templateName =
+          message.template ??
+          (typeof message.data?.template === "string" ? message.data.template : undefined);
+        const language =
+          message.locale ??
+          (typeof message.data?.language === "string" ? message.data.language : "en_US");
+
+        const result = templateName
+          ? await transport.send({
+              to: message.to,
+              template: { name: templateName, language },
+            })
+          : await transport.send({
+              to: message.to,
+              text: message.text ?? "",
+            });
+
+        return mapSentlySendResult("wa-cloud", result);
+      } catch (err) {
+        return mapSentlySendError("wa-cloud", err);
       }
-      return {
-        ok: true,
-        messageId: id,
-        driverId: "wa-cloud",
-        attempts: [{ driverId: "wa-cloud", ok: true, at: Date.now(), messageId: id }],
-      };
     },
+    verify: () => transport.verify(),
   };
 
-  return { id: "wa-cloud", channel };
+  return { id: "wa-cloud", channel, whatsappTransport: transport };
 }
 
 /** WhatsApp Cloud driver factory. */