okengine 0.7.0 → 0.9.0

package/src/elements/channel/runtime.ts

@@ -11,7 +11,12 @@ import type {
   ChannelAttempt,
   ChannelDriver,
   ChannelMessage,
+  ChannelOtpSendOptions,
+  ChannelOtpSendResult,
+  ChannelOtpVerifyOptions,
+  ChannelOtpVerifyResult,
   ChannelSendResult,
+  SmsOtpTransport,
 } from "../../drivers/channel-types.ts";
 import type { ChannelMedium } from "../../manifest/types.ts";
 import type { ConsentStore } from "./consent.ts";
@@ -27,6 +32,11 @@ import {
   type ReceiptLedger,
 } from "./receipts.ts";
 import { createSuppressionStore, type SuppressionStore } from "./suppression.ts";
+import {
+  deliverOtpAcrossChannels,
+  type DeliverOtpOptions,
+  type DeliverOtpResult,
+} from "./otp-delivery.ts";
 
 /** Locale catalog: template → locale → rendered body. */
 export type TemplateCatalog = Readonly<
@@ -85,6 +95,8 @@ export interface ChannelRuntime {
   readonly suppression: SuppressionStore;
   readonly receipts: ReceiptLedger;
   readonly costs: MediumCosts;
+  /** Bound driver chain (email + SMS + …). */
+  readonly drivers: readonly ChannelDriver[];
   /**
    * Send a template through the driver chain.
    *
@@ -92,6 +104,29 @@ export interface ChannelRuntime {
    * @param options - Recipient / data / locale / via
    */
   send(template: string, options: ChannelSendOptions): Promise<ChannelSendResult>;
+  /**
+   * Send a provider-managed OTP via the bound Taqnyat SMS driver.
+   *
+   * Vendor extra (Taqnyat Verify API) — only valid when the configured SMS
+   * driver supports it. Throws loudly when no SMS driver is bound or the
+   * bound driver does not support provider-managed OTP.
+   *
+   * @param options - Recipient + requestId (+ lang / note / from)
+   */
+  sendOtp(options: ChannelOtpSendOptions): Promise<ChannelOtpSendResult>;
+  /**
+   * Verify a provider-managed OTP code via the bound Taqnyat SMS driver.
+   *
+   * @param options - Recipient + requestId + code (+ lang / note / from)
+   */
+  verifyOtp(options: ChannelOtpVerifyOptions): Promise<ChannelOtpVerifyResult>;
+  /**
+   * Tier-2 OTP delivery across declared channels (sently FallbackTransport).
+   * Pass `only` for explicit single-channel resend (no cross-medium failover).
+   *
+   * @param options - Channels, templates, addresses, OTP data
+   */
+  deliverOtp(options: DeliverOtpOptions): Promise<DeliverOtpResult>;
   /**
    * Ingest a post-send provider outcome (bounce / complaint / …).
    * Hard bounce auto-adds suppression. Console projects the ledger — never
@@ -107,15 +142,33 @@ export interface ChannelRuntime {
  *
  * @param options - Templates + drivers + catalog
  */
+let channelProcessLocalWarned = false;
+
+/** Test helper — reset the one-shot Channel process-local warn. */
+export function resetChannelProcessLocalWarnForTests(): void {
+  channelProcessLocalWarned = false;
+}
+
 export function createChannelRuntime(options: CreateChannelRuntimeOptions = {}): ChannelRuntime {
   const templates = new Map<string, ChannelTemplateDecl>();
   for (const t of options.templates ?? []) {
     templates.set(t.name, t);
   }
+  const usingDefaultSuppression = options.suppression === undefined;
+  const usingDefaultReceipts = options.receipts === undefined;
   const suppression =
     options.suppression ??
     createSuppressionStore(options.consent ? { consent: options.consent } : {});
   const receipts = options.receipts ?? createReceiptLedger();
+  if ((usingDefaultSuppression || usingDefaultReceipts) && !channelProcessLocalWarned) {
+    channelProcessLocalWarned = true;
+    console.warn(
+      "oke boot: Channel suppression/consent/receipts default to process-local memory — " +
+        "opt-out, bounce, and receipt state on one instance is invisible to others. " +
+        "Inject shared stores for multi-instance, or run a single Channel consumer, until a " +
+        "durable driver ships.",
+    );
+  }
   const costs = options.costs ?? { ...DEFAULT_MEDIUM_COSTS };
   const catalog = options.catalog ?? {};
   const defaultLocale = options.defaultLocale ?? "en";
@@ -391,11 +444,160 @@ export function createChannelRuntime(options: CreateChannelRuntimeOptions = {}):
     return "provider-error";
   }
 
+  function otpSmsDriver(): { driver: ChannelDriver; otp: SmsOtpTransport } {
+    const sms = drivers.filter((d) => d.smsTransport);
+    if (sms.length === 0) {
+      throw new Error(
+        "channel: no SMS driver bound — bind drivers.channel.sms (e.g. taqnyat) to send provider OTP",
+      );
+    }
+    for (const d of sms) {
+      const t = d.smsTransport as Partial<SmsOtpTransport> | undefined;
+      if (t && typeof t.sendOtp === "function" && typeof t.verifyOtp === "function") {
+        return { driver: d, otp: t as SmsOtpTransport };
+      }
+    }
+    const id = sms[0]?.id ?? "unknown";
+    throw new Error(
+      `channel: SMS driver "${id}" does not support provider-managed OTP; use exposeDevOtp locally or set drivers.channel.sms to "taqnyat"`,
+    );
+  }
+
+  async function sendTemplate(
+    template: string,
+    opts: ChannelSendOptions,
+  ): Promise<ChannelSendResult> {
+    const decl = templates.get(template);
+    if (!decl) {
+      throw new Error(`channel: unknown template "${template}"`);
+    }
+    const medium = decl.medium;
+    const checkMedium: ChannelMedium = medium === "any" ? "email" : medium;
+
+    const suppressed = suppression.isSuppressed(opts.to, checkMedium);
+    if (suppressed.suppressed) {
+      const status: DeliveryStatus =
+        suppressed.reason === "opted-out" ? "suppressed/opted-out" : "suppressed/prior-bounce";
+      const resolved = resolveLocale({
+        locale: opts.locale,
+        profileLocale: opts.profileLocale,
+        acceptLanguage: opts.acceptLanguage,
+        defaultLocale,
+      });
+      const receipt: DeliveryReceipt = {
+        id: crypto.randomUUID(),
+        template,
+        to: opts.to,
+        medium,
+        locale: resolved.locale,
+        localeChain: resolved.chain,
+        status,
+        attempts: [],
+        at: now(),
+        error: suppressed.reason === "opted-out" ? "opted out" : "prior hard bounce",
+      };
+      receipts.record(receipt);
+      return {
+        ok: false,
+        messageId: receipt.id,
+        driverId: "suppression",
+        attempts: [],
+      };
+    }
+
+    const resolved = resolveLocale({
+      locale: opts.locale,
+      profileLocale: opts.profileLocale,
+      acceptLanguage: opts.acceptLanguage,
+      defaultLocale,
+    });
+    const locale = resolved.locale;
+    const localeChain: readonly LocaleChainStep[] = resolved.chain;
+    const body = resolveBody(template, locale, opts.data ?? {});
+    const chain = driversFor(medium, opts.via);
+
+    let result: ChannelSendResult;
+    let attempts: ChannelAttempt[];
+
+    if (medium === "email" || (medium === "any" && chain.some((d) => d.transport))) {
+      const from = decl.from ?? "oke@localhost";
+      const sendResult = await sendViaEmailChain(chain, {
+        from,
+        to: opts.to,
+        subject: opts.subject ?? body.subject ?? template,
+        text: body.text,
+        html: body.html,
+        template,
+        data: opts.data ? { ...opts.data } : undefined,
+      });
+      result = sendResult.result;
+      attempts = sendResult.attempts;
+    } else {
+      const sendResult = await sendViaChannelChain(chain, {
+        medium: medium === "any" ? "sms" : medium,
+        to: opts.to,
+        from: decl.from,
+        subject: opts.subject ?? body.subject,
+        text: body.text,
+        html: body.html,
+        data: opts.data,
+        locale,
+        template,
+        pushSubscription: opts.pushSubscription,
+      });
+      result = sendResult.result;
+      attempts = sendResult.attempts;
+    }
+
+    let status: DeliveryStatus;
+    if (result.ok) {
+      status = attempts.filter((a) => !a.ok).length > 0 ? "fallback" : "sent";
+    } else {
+      status = classifySendFailure(attempts);
+    }
+
+    receipts.record({
+      id: crypto.randomUUID(),
+      template,
+      to: opts.to,
+      medium,
+      locale,
+      localeChain,
+      status,
+      messageId: result.messageId,
+      driverId: result.driverId,
+      attempts,
+      at: now(),
+      ...(result.ok
+        ? {}
+        : {
+            error: attempts
+              .map((a) => a.error)
+              .filter(Boolean)
+              .join("; "),
+          }),
+    });
+
+    return { ...result, attempts };
+  }
+
   return {
     templates,
     suppression,
     receipts,
     costs,
+    drivers,
+    async sendOtp(opts) {
+      const { otp } = otpSmsDriver();
+      return otp.sendOtp(opts);
+    },
+    async verifyOtp(opts) {
+      const { otp } = otpSmsDriver();
+      return otp.verifyOtp(opts);
+    },
+    async deliverOtp(opts) {
+      return deliverOtpAcrossChannels(drivers, sendTemplate, opts, now);
+    },
     ingestOutcome(input) {
       const at = input.at ?? now();
       const existing = receipts.byMessageId(input.messageId);
@@ -430,119 +632,6 @@ export function createChannelRuntime(options: CreateChannelRuntimeOptions = {}):
       receipts.record(receipt);
       return receipt;
     },
-    async send(template, opts) {
-      const decl = templates.get(template);
-      if (!decl) {
-        throw new Error(`channel: unknown template "${template}"`);
-      }
-      const medium = decl.medium;
-      const checkMedium: ChannelMedium = medium === "any" ? "email" : medium;
-
-      const suppressed = suppression.isSuppressed(opts.to, checkMedium);
-      if (suppressed.suppressed) {
-        const status: DeliveryStatus =
-          suppressed.reason === "opted-out" ? "suppressed/opted-out" : "suppressed/prior-bounce";
-        const resolved = resolveLocale({
-          locale: opts.locale,
-          profileLocale: opts.profileLocale,
-          acceptLanguage: opts.acceptLanguage,
-          defaultLocale,
-        });
-        const receipt: DeliveryReceipt = {
-          id: crypto.randomUUID(),
-          template,
-          to: opts.to,
-          medium,
-          locale: resolved.locale,
-          localeChain: resolved.chain,
-          status,
-          attempts: [],
-          at: now(),
-          error: suppressed.reason === "opted-out" ? "opted out" : "prior hard bounce",
-        };
-        receipts.record(receipt);
-        return {
-          ok: false,
-          messageId: receipt.id,
-          driverId: "suppression",
-          attempts: [],
-        };
-      }
-
-      const resolved = resolveLocale({
-        locale: opts.locale,
-        profileLocale: opts.profileLocale,
-        acceptLanguage: opts.acceptLanguage,
-        defaultLocale,
-      });
-      const locale = resolved.locale;
-      const localeChain: readonly LocaleChainStep[] = resolved.chain;
-      const body = resolveBody(template, locale, opts.data ?? {});
-      const chain = driversFor(medium, opts.via);
-
-      let result: ChannelSendResult;
-      let attempts: ChannelAttempt[];
-
-      if (medium === "email" || (medium === "any" && chain.some((d) => d.transport))) {
-        const from = decl.from ?? "oke@localhost";
-        const sendResult = await sendViaEmailChain(chain, {
-          from,
-          to: opts.to,
-          subject: opts.subject ?? body.subject ?? template,
-          text: body.text,
-          html: body.html,
-          template,
-          data: opts.data ? { ...opts.data } : undefined,
-        });
-        result = sendResult.result;
-        attempts = sendResult.attempts;
-      } else {
-        const sendResult = await sendViaChannelChain(chain, {
-          medium: medium === "any" ? "sms" : medium,
-          to: opts.to,
-          from: decl.from,
-          subject: opts.subject ?? body.subject,
-          text: body.text,
-          html: body.html,
-          data: opts.data,
-          locale,
-          template,
-          pushSubscription: opts.pushSubscription,
-        });
-        result = sendResult.result;
-        attempts = sendResult.attempts;
-      }
-
-      let status: DeliveryStatus;
-      if (result.ok) {
-        status = attempts.filter((a) => !a.ok).length > 0 ? "fallback" : "sent";
-      } else {
-        status = classifySendFailure(attempts);
-      }
-
-      receipts.record({
-        id: crypto.randomUUID(),
-        template,
-        to: opts.to,
-        medium,
-        locale,
-        localeChain,
-        status,
-        messageId: result.messageId,
-        driverId: result.driverId,
-        attempts,
-        at: now(),
-        ...(result.ok
-          ? {}
-          : {
-              error: attempts
-                .map((a) => a.error)
-                .filter(Boolean)
-                .join("; "),
-            }),
-      });
-
-      return { ...result, attempts };
-    },
+    send: sendTemplate,
   };
 }

package/src/elements/channel.test.ts

@@ -10,6 +10,7 @@
 import { describe, expect, test } from "bun:test";
 import type { MailOptions, SendResult, Transport } from "sently";
 import { createChannelInbox, openConsoleChannel, type ChannelDriver } from "../drivers/index.ts";
+import type { SmsOtpTransport, SmsTransport } from "../drivers/channel-types.ts";
 import { channel, createChannelRuntime, createConsentStore, FallbackTransport } from "./channel.ts";
 
 /** Create a sently-compatible transport that always fails. */
@@ -207,3 +208,73 @@ describe("console driver", () => {
     expect(inbox.entries[0]!.text).toBe("code 1234");
   });
 });
+
+describe("provider-managed OTP (Taqnyat Verify)", () => {
+  function taqnyatSmsDriver(): ChannelDriver {
+    const otpTransport: SmsTransport & SmsOtpTransport = {
+      provider: "taqnyat-sms",
+      async send() {
+        return { messageId: "m", to: "", status: "sent", response: "" };
+      },
+      async sendOtp(opts) {
+        return {
+          requestId: opts.requestId,
+          to: opts.to,
+          code: 5,
+          response: "sent",
+          provider: "taqnyat-sms",
+        };
+      },
+      async verifyOtp(opts) {
+        return {
+          ok: true as const,
+          code: opts.code === "0000" ? 13 : 10,
+          message: "verified",
+          response: "ok",
+          provider: "taqnyat-sms",
+        };
+      },
+    };
+    return { id: "taqnyat", smsTransport: otpTransport };
+  }
+
+  test("sendOtp / verifyOtp dispatch to the taqnyat smsTransport", async () => {
+    const runtime = createChannelRuntime({ drivers: [taqnyatSmsDriver()] });
+    const sent = await runtime.sendOtp({ to: "+966500000000", requestId: "r1", lang: "en" });
+    expect(sent.code).toBe(5);
+    expect(sent.requestId).toBe("r1");
+    const verified = await runtime.verifyOtp({
+      to: "+966500000000",
+      requestId: "r1",
+      code: "6240",
+    });
+    expect(verified.ok).toBe(true);
+    expect(verified.code).toBe(10);
+  });
+
+  test("throws loudly when no SMS driver is bound", async () => {
+    const runtime = createChannelRuntime({});
+    await expect(runtime.sendOtp({ to: "+966500000000", requestId: "r1" })).rejects.toThrow(
+      "no SMS driver bound",
+    );
+  });
+
+  test("throws loudly naming the driver when SMS driver lacks OTP support", async () => {
+    const twilioLike: ChannelDriver = {
+      id: "msegat",
+      smsTransport: {
+        provider: "msegat",
+        async send() {
+          return { messageId: "m", to: "", status: "sent", response: "" };
+        },
+      },
+    };
+    const runtime = createChannelRuntime({ drivers: [twilioLike] });
+    await expect(runtime.sendOtp({ to: "+966500000000", requestId: "r1" })).rejects.toThrow(
+      /SMS driver "msegat" does not support provider-managed OTP/,
+    );
+    await expect(
+      runtime.verifyOtp({ to: "+966500000000", requestId: "r1", code: "1234" }),
+    ).rejects.toThrow(/does not support provider-managed OTP/);
+  });
+});

package/src/elements/channel.ts

@@ -2,7 +2,8 @@
  * Channel element — reaching humans.
  *
  * Physics: email · SMS · WhatsApp · push.
- * Drivers: `console` · `smtp` · `resend` · `sndr` · `taqnyat` · `msegat` · `unifonic` · `wa-cloud` · `fcm` · `webpush`.
+ * Drivers: `console` · `smtp` · `resend` · `sndr` · `taqnyat` · `taqnyat-mail` ·
+ * `taqnyat-whatsapp` · `msegat` · `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.
@@ -19,7 +20,7 @@ export type {
   ChannelTemplateOptions,
 } from "./channel/declare.ts";
 
-export { createChannelRuntime } from "./channel/runtime.ts";
+export { createChannelRuntime, resetChannelProcessLocalWarnForTests } from "./channel/runtime.ts";
 export type {
   ChannelRuntime,
   ChannelSendOptions,
@@ -27,6 +28,15 @@ export type {
   TemplateCatalog,
 } from "./channel/runtime.ts";
 
+export {
+  deliverOtpAcrossChannels,
+  shouldFallbackOtpMedium,
+  addressForChannel,
+  type DeliverOtpOptions,
+  type DeliverOtpResult,
+  type OtpTemplateMap,
+} from "./channel/otp-delivery.ts";
+
 export { createConsentStore, type ConsentStore, type OptOut } from "./channel/consent.ts";
 
 export {