okengine 0.8.0 → 0.9.0

package/src/elements/channel/otp-delivery.ts

@@ -0,0 +1,291 @@
+/**
+ * Tier-2 OTP multi-medium delivery via sently {@link FallbackTransport}.
+ *
+ * Within each medium, {@link ChannelRuntime.send} already runs the existing
+ * email/SMS FallbackTransport chains. This module reuses FallbackTransport
+ * again for **cross-medium** provider-error failover — adapters normalize
+ * per-medium sends to one options shape. Explicit user resend never calls
+ * this chain; it delivers a single channel only.
+ */
+
+import { FallbackError, FallbackTransport } from "sently/transports/fallback";
+import type { TaqnyatWhatsAppFailover } from "sently/transports/taqnyat-whatsapp";
+import type { OtpChannel } from "../../auth/verification.ts";
+import { hasWhatsAppSendWithFailover } from "../../drivers/channel-taqnyat-whatsapp.ts";
+import type {
+  ChannelAttempt,
+  ChannelDriver,
+  ChannelSendResult,
+} from "../../drivers/channel-types.ts";
+
+/** Minimal send surface used by OTP multi-medium delivery. */
+export type OtpChannelSend = (
+  template: string,
+  options: {
+    readonly to: string;
+    readonly data?: Readonly<Record<string, unknown>>;
+    readonly locale?: string;
+  },
+) => Promise<ChannelSendResult>;
+
+/** Template names keyed by OTP channel. */
+export type OtpTemplateMap = Readonly<Partial<Record<OtpChannel, string>>>;
+
+/** Options for cross-medium OTP delivery. */
+export interface DeliverOtpOptions {
+  /** Preferred channel order (build-time declaration). */
+  readonly channels: readonly OtpChannel[];
+  /** Template name per medium. */
+  readonly templates: OtpTemplateMap;
+  readonly email?: string;
+  readonly phone?: string;
+  readonly data: Readonly<Record<string, unknown>>;
+  readonly locale?: string;
+  /**
+   * When set, deliver **only** this channel (explicit resend) — no
+   * cross-medium FallbackTransport walk.
+   */
+  readonly only?: OtpChannel;
+}
+
+/** Result of a Tier-2 OTP delivery attempt. */
+export interface DeliverOtpResult {
+  readonly ok: true;
+  readonly channel: OtpChannel;
+  readonly attempts: readonly ChannelAttempt[];
+  readonly messageId: string;
+  readonly driverId: string;
+}
+
+type MediumSendOpts = {
+  readonly channel: OtpChannel;
+  readonly to: string;
+  readonly template: string;
+  readonly data: Readonly<Record<string, unknown>>;
+  readonly locale?: string;
+};
+
+type MediumSendResult = {
+  readonly messageId: string;
+  readonly status: string;
+  readonly provider: string;
+  readonly channel: OtpChannel;
+};
+
+/**
+ * Whether an error should advance to the next medium (provider outage),
+ * not permanent client mistakes (invalid address).
+ *
+ * @param error - Thrown error
+ */
+export function shouldFallbackOtpMedium(error: unknown): boolean {
+  const msg = (error instanceof Error ? error.message : String(error)).toLowerCase();
+  if (
+    /invalid.*(address|email|recipient|phone)|unknown user|no such user|mailbox unavailable|550 5\.1\.1/.test(
+      msg,
+    )
+  ) {
+    return false;
+  }
+  const status = (error as { statusCode?: number })?.statusCode;
+  if (status === 400 || status === 401 || status === 403) return false;
+  return true;
+}
+
+/**
+ * Resolve the recipient address for a channel.
+ *
+ * @param channel - Medium
+ * @param email - Email when present
+ * @param phone - Phone when present
+ */
+export function addressForChannel(
+  channel: OtpChannel,
+  email: string | undefined,
+  phone: string | undefined,
+): string | undefined {
+  if (channel === "email") return email;
+  return phone;
+}
+
+/**
+ * Deliver an OTP across declared channels using sently FallbackTransport.
+ *
+ * @param drivers - Bound drivers (for Taqnyat WhatsApp sendWithFailover)
+ * @param send - ChannelRuntime.send bound function
+ * @param opts - Delivery options
+ * @param now - Clock
+ */
+export async function deliverOtpAcrossChannels(
+  drivers: readonly ChannelDriver[],
+  send: OtpChannelSend,
+  opts: DeliverOtpOptions,
+  now: () => number = () => Date.now(),
+): Promise<DeliverOtpResult> {
+  const ordered = opts.only ? [opts.only] : [...opts.channels];
+  const adapters: Array<{
+    readonly provider: string;
+    send(o: MediumSendOpts): Promise<MediumSendResult>;
+  }> = [];
+
+  for (const channel of ordered) {
+    const template = opts.templates[channel];
+    const to = addressForChannel(channel, opts.email, opts.phone);
+    if (!template || !to) continue;
+
+    if (channel === "whatsapp" && !opts.only) {
+      const wa = drivers.find((d) => hasWhatsAppSendWithFailover(d.whatsappTransport));
+      if (wa && hasWhatsAppSendWithFailover(wa.whatsappTransport)) {
+        const transport = wa.whatsappTransport;
+        const failover = buildTaqnyatWhatsAppFailover(opts, ordered);
+        if (failover.sms || failover.mail) {
+          adapters.push({
+            provider: "taqnyat-whatsapp",
+            async send() {
+              const result = await transport.sendWithFailover(
+                { to, text: String(opts.data.otp ?? "") },
+                failover,
+              );
+              return {
+                messageId: result.messageId,
+                status: result.status,
+                provider: "taqnyat-whatsapp",
+                channel: "whatsapp" as const,
+              };
+            },
+          });
+          // Provider-side failover already covers later sms/email — skip client adapters for those.
+          break;
+        }
+      }
+    }
+
+    adapters.push({
+      provider: channel,
+      async send() {
+        const result = await send(template, {
+          to,
+          data: opts.data,
+          ...(opts.locale ? { locale: opts.locale } : {}),
+        });
+        if (!result.ok) {
+          const errMsg =
+            result.attempts
+              .map((a) => a.error)
+              .filter(Boolean)
+              .join("; ") || `${channel} delivery failed`;
+          const err = new Error(errMsg) as Error & { statusCode?: number };
+          if (/invalid.*(address|email|recipient|phone)/i.test(errMsg)) {
+            err.statusCode = 400;
+          }
+          throw err;
+        }
+        return {
+          messageId: result.messageId,
+          status: "sent",
+          provider: result.driverId,
+          channel,
+        };
+      },
+    });
+  }
+
+  if (adapters.length === 0) {
+    throw new Error(
+      "channel: otp delivery has no viable channel — need a matching address for a declared channel",
+    );
+  }
+
+  const attempts: ChannelAttempt[] = [];
+  const fallback = new FallbackTransport(adapters, {
+    shouldFallback: shouldFallbackOtpMedium,
+    onFallback(failedIndex, error) {
+      const provider = adapters[failedIndex]?.provider ?? `medium-${failedIndex}`;
+      attempts.push({
+        driverId: provider,
+        ok: false,
+        error: error instanceof Error ? error.message : String(error),
+        at: now(),
+      });
+    },
+  });
+
+  try {
+    const first = ordered.find((ch) => {
+      const template = opts.templates[ch];
+      const to = addressForChannel(ch, opts.email, opts.phone);
+      return !!template && !!to;
+    });
+    if (!first) {
+      throw new Error("channel: otp delivery has no viable channel");
+    }
+    const template = opts.templates[first]!;
+    const to = addressForChannel(first, opts.email, opts.phone)!;
+    const result = await fallback.send({
+      channel: first,
+      to,
+      template,
+      data: opts.data,
+      ...(opts.locale ? { locale: opts.locale } : {}),
+    });
+    attempts.push({
+      driverId: result.provider,
+      ok: true,
+      at: now(),
+      messageId: result.messageId,
+    });
+    return {
+      ok: true,
+      channel: result.channel,
+      attempts,
+      messageId: result.messageId,
+      driverId: result.provider,
+    };
+  } catch (err) {
+    if (err instanceof FallbackError) {
+      for (const a of err.attempts) {
+        if (!attempts.some((x) => x.driverId === a.provider && !x.ok)) {
+          attempts.push({
+            driverId: a.provider,
+            ok: false,
+            error: a.error instanceof Error ? a.error.message : String(a.error),
+            at: now(),
+          });
+        }
+      }
+      throw new Error(
+        `channel: otp delivery failed on all channels (${err.attempts.map((a) => a.provider).join(" → ")})`,
+      );
+    }
+    throw err;
+  }
+}
+
+function buildTaqnyatWhatsAppFailover(
+  opts: DeliverOtpOptions,
+  ordered: readonly OtpChannel[],
+): TaqnyatWhatsAppFailover {
+  const waIndex = ordered.indexOf("whatsapp");
+  const rest = waIndex >= 0 ? ordered.slice(waIndex + 1) : [];
+  const otp = String(opts.data.otp ?? "");
+  const sender = process.env.TAQNYAT_SENDER?.trim() ?? "";
+  const campaign = process.env.TAQNYAT_CAMPAIGN?.trim() ?? "oke-otp";
+  const out: TaqnyatWhatsAppFailover = {};
+  if (rest.includes("sms") && opts.phone && sender) {
+    out.sms = {
+      sender,
+      campaign,
+      body: `Your sign-in code is: ${otp}`,
+    };
+  }
+  if (rest.includes("email") && opts.email) {
+    out.mail = {
+      from: process.env.TAQNYAT_MAIL_FROM?.trim() ?? "OKE <no-reply@oke.local>",
+      to: opts.email,
+      campaign,
+      subject: "Your sign-in code",
+      msg: `Your one-time sign-in code is: ${otp}`,
+    };
+  }
+  return out;
+}

package/src/elements/channel/runtime.ts

@@ -32,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<
@@ -115,6 +120,13 @@ export interface ChannelRuntime {
    * @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
@@ -130,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";
@@ -433,6 +463,124 @@ export function createChannelRuntime(options: CreateChannelRuntimeOptions = {}):
     );
   }
 
+  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,
@@ -447,6 +595,9 @@ export function createChannelRuntime(options: CreateChannelRuntimeOptions = {}):
       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);
@@ -481,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.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 {

package/src/index.ts

@@ -41,8 +41,11 @@ export {
   PluginNeedsError,
   assertPluginNeeds,
   freezePrincipal,
+  installGracefulShutdown,
+  releaseInstanceLeases,
   type OkeApp,
   type OkeOptions,
+  type ReadyState,
   type FlowDef,
   type FlowFailure,
   type FlowErrorValue,