okengine 0.18.4 → 0.19.0

package/site/content/docs/elements/channel/receipts.mdx

@@ -0,0 +1,206 @@
+---
+title: "Receipts"
+description: "Delivery ledger, seven-state outcomes, consent opt-out, and hard-bounce suppression — process-local by default."
+icon: "ReceiptText"
+source: "docs/spec/unified-theory.md"
+---
+
+Every Channel send records a **receipt** — success (`sent` / `fallback`), suppression, or a
+classified failure. Provider bounces and complaints update that ledger through normalized
+outcomes. There is no `oke_receipts` SQL table and no `fx.channel.getReceipt` helper.
+
+For operators watching deliverability — Console projects the ledger; Flows only see send
+results via `fx.send`’s `{ ok: true }` gate.
+
+<Callout title="The one rule">
+  Consent and prior hard bounces suppress **before** any driver runs. Default suppression / consent
+  / receipts stores are **process-local memory** — inject shared stores for multi-instance, or run a
+  single Channel consumer, until a durable driver ships.
+</Callout>
+
+## Smallest Example
+
+<Steps>
+
+<Step>
+### Send and accept the receipt
+
+```typescript
+const result = await fx.send(noteCreatedMail, {
+  to: "alice@example.com",
+  data: { id: "n1", title: "Hi" },
+});
+// result.ok === true on the fx gate when the capability succeeds;
+// the runtime ledger still stores status, attempts, and messageId.
+```
+
+Dry-run never contacts a provider and still records _would have fired_.
+
+</Step>
+
+<Step>
+### Understand statuses
+
+| Status                    | Meaning                                                         |
+| ------------------------- | --------------------------------------------------------------- |
+| `sent`                    | First (or only) attempt succeeded                               |
+| `fallback`                | An earlier attempt failed; a later same-medium driver succeeded |
+| `suppressed/opted-out`    | Consent store blocked the address                               |
+| `suppressed/prior-bounce` | Prior hard bounce on the suppression list                       |
+| `failed` / `opted-out`    | Legacy aliases kept for older callers                           |
+
+</Step>
+
+<Step>
+### Watch the boot warning
+
+```text
+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.
+```
+
+</Step>
+
+</Steps>
+
+## Progressive Patterns
+
+<Tabs items={["Suppression", "Outcomes", "Inject stores"]}>
+
+<Tab value="Suppression">
+
+Opt-out or prior bounce never hits SMTP / SMS:
+
+```typescript
+// Runtime path (not on fx): consent.optOut(subject, medium | "all")
+// Next fx.send → receipt status suppressed/opted-out, driverId "suppression", ok: false
+```
+
+Errors on the receipt: `"opted out"` or `"prior hard bounce"`.
+
+</Tab>
+
+<Tab value="Outcomes">
+
+Post-send taxonomy (`DeliveryOutcomeState`):
+
+| State                       | Verdict    |
+| --------------------------- | ---------- |
+| `suppressed/opted-out`      | `correct`  |
+| `suppressed/prior-bounce`   | `correct`  |
+| `blocked/invalid-address`   | `review`   |
+| `soft-bounce`               | `retry`    |
+| `hard-bounce`               | `suppress` |
+| `provider-error`            | `retry`    |
+| `delivered-then-complained` | `review`   |
+
+`ingestOutcome({ messageId, state })` updates the receipt. Hard bounce also adds the address
+to suppression (`prior-bounce`). Invalid-address heuristics include patterns such as
+`550 5.1.1` on attempt errors.
+
+</Tab>
+
+<Tab value="Inject stores">
+
+Pass shared implementations on boot:
+
+```typescript
+oke({
+  channel: {
+    suppression: mySuppressionStore,
+    consent: myConsentStore,
+    receipts: myReceiptLedger,
+  },
+});
+```
+
+Shapes: `SuppressionStore`, `ConsentStore`, `ReceiptLedger` from `okengine` — `record` /
+`all` / `forTemplate` / `byMessageId` / `updateStatus` on the ledger.
+
+</Tab>
+
+</Tabs>
+
+## Receipt shape
+
+| Field                    | Meaning                                     |
+| ------------------------ | ------------------------------------------- |
+| `id`                     | Runtime receipt id                          |
+| `template`               | Template name                               |
+| `to`                     | Recipient                                   |
+| `medium`                 | `email` · `sms` · `whatsapp` · `push` · …   |
+| `locale` / `localeChain` | Resolved locale + chain steps               |
+| `status`                 | Success, legacy, or outcome state           |
+| `messageId`              | Provider / runtime message id               |
+| `driverId`               | Winning driver (or `suppression`)           |
+| `attempts`               | Every try (`driverId`, `ok`, `error`, `at`) |
+| `at`                     | Epoch ms                                    |
+| `error`                  | Aggregated attempt errors when failed       |
+
+## Consent & suppression
+
+| Store       | Role                                                             |
+| ----------- | ---------------------------------------------------------------- |
+| Consent     | `isOptedOut` / `optOut` / `optIn` / `list` per subject + medium  |
+| Suppression | Reasons `"opted-out"` \| `"prior-bounce"`; checked on every send |
+
+**Consequence:** suppression is not failure — verdict `correct` for opted-out and prior-bounce
+rows. Complaints (`delivered-then-complained`) outrank many hard bounces in consequence weight.
+
+There is no Flow helper to query receipts today — use Console projection or an injected ledger
+from operator tooling.
+
+## Troubleshooting
+
+<Accordions>
+
+<Accordion title="Process-local memory boot warning">
+  Expected on single-node `oke dev`. For replicas, inject shared `suppression` / `consent` /
+  `receipts` or pin Channel work to one consumer.
+</Accordion>
+
+<Accordion title="Send returns ok but Mailpit / provider empty">
+  Check receipt status — `suppressed/*` never calls a driver. Opt-in the address or clear prior
+  bounce on the suppression store.
+</Accordion>
+
+<Accordion title="Status fallback with multiple attempts">
+  Same-medium `via` (or ordered driver chain) recovered after a provider error. Inspect `attempts[]`
+  for which driver failed and which succeeded.
+</Accordion>
+
+<Accordion title="No fx.channel.getReceipt">
+  That API does not exist. Use the runtime `receipts` store (injected or Console), not a Flow
+  method. `fx.send` only returns `{ ok: true }` after the capability gate.
+</Accordion>
+
+<Accordion title="Hard bounce still getting mail">
+  `ingestOutcome` with `hard-bounce` must run (webhook → normalized outcome). Without ingestion,
+  suppression never learns the bounce.
+</Accordion>
+
+</Accordions>
+
+## Learn more
+
+- [Channel overview](/docs/elements/channel) — send path and `ChannelPhysics`
+- [Email](/docs/elements/channel/email) — SMTP / provider drivers
+- [fx](/docs/reference/fx) — dry-run send behavior
+
+## Next
+
+<Cards>
+  <Card
+    title="Channel Overview"
+    description="Templates, fx.send, and drivers."
+    href="/docs/elements/channel"
+  />
+  <Card
+    title="Email"
+    description="Mailpit and production email drivers."
+    href="/docs/elements/channel/email"
+  />
+  <Card title="AI Element" description="Models, prompts, and agents." href="/docs/elements/ai" />
+</Cards>

package/site/content/docs/elements/channel/sms.mdx

@@ -0,0 +1,264 @@
+---
+title: "SMS"
+description: "SMS templates via channel.sms, transactional fx.send, and provider-managed OTP with fx.sendOtp / fx.verifyOtp."
+icon: "MessageSquare"
+source: "docs/spec/unified-theory.md"
+---
+
+SMS (`channel.sms`) delivers short text and provider-managed one-time codes. Pin an SMS driver
+(no default in any env), declare templates for app-owned messages, or call `fx.sendOtp` when the
+vendor owns the code.
+
+For developers verifying phones — choose raw Channel OTP vs the [`otp`](/docs/plugins/otp) plugin.
+
+<Callout title="The one rule">
+  SMS is opt-in: set `drivers.channel.sms` (e.g. `"taqnyat"`) or boot has no SMS transport. Provider
+  OTP needs a Verify-capable driver (`taqnyat`); app-owned codes use templates + `fx.deliverOtp` /
+  the OTP plugin.
+</Callout>
+
+## Smallest Example
+
+<Steps>
+
+<Step>
+### Pin an SMS driver
+
+```typescript title="oke.config.ts"
+import { defineConfig } from "okengine/config";
+
+export default defineConfig({
+  drivers: {
+    channel: {
+      sms: { prod: "taqnyat" },
+    },
+  },
+});
+```
+
+Set `TAQNYAT_BEARER_TOKEN` (or `TAQNYAT_TOKEN`) and `TAQNYAT_SENDER`.
+
+</Step>
+
+<Step>
+### Declare a template and send
+
+```typescript title="src/core/channel.ts"
+import { channel } from "okengine";
+import { z } from "zod";
+
+const sms = channel.sms({ sender: "ACME" });
+
+export const orderShippedSms = sms.template("order.shipped", {
+  locales: ["en"],
+  schema: z.object({ tracking: z.string() }),
+});
+```
+
+```typescript
+await fx.send(orderShippedSms, {
+  to: "+15551234567",
+  data: { tracking: "1Z999" },
+});
+```
+
+Add a catalog body (`text: "Shipped — track {{tracking}}"`) or accept the JSON fallback.
+
+</Step>
+
+<Step>
+### Or send a provider OTP
+
+```typescript
+await fx.sendOtp({
+  to: "+15551234567",
+  requestId: fx.id(),
+  lang: "en",
+});
+
+await fx.verifyOtp({
+  to: "+15551234567",
+  requestId, // same id
+  code: userEnteredCode,
+});
+```
+
+Effects record `sends: ["sms-otp"]`. Prefer [`otp({ mode: "provider" })`](/docs/plugins/otp) for
+`/auth/otp/*` routes.
+
+</Step>
+
+</Steps>
+
+## Progressive Patterns
+
+<Tabs items={["Template", "Provider OTP", "App OTP", "Plugin"]}>
+
+<Tab value="Template">
+
+Transactional SMS through the same `fx.send` path as email:
+
+```typescript
+const sms = channel.sms({ from: "ACME" });
+export const alertSms = sms.template("ops.alert", {
+  schema: z.object({ message: z.string() }),
+});
+
+await fx.send(alertSms, { to: phone, data: { message: "Disk 90%" } });
+```
+
+</Tab>
+
+<Tab value="Provider OTP">
+
+Vendor owns the code (Taqnyat Verify). Options:
+
+| Option      | Type             | Meaning                                   |
+| ----------- | ---------------- | ----------------------------------------- |
+| `to`        | `string`         | E.164 recipient                           |
+| `requestId` | `string`         | Correlation id (required again on verify) |
+| `lang`      | `"en"` \| `"ar"` | Message language                          |
+| `note`      | `string`         | Optional note appended to SMS             |
+| `from`      | `string`         | Sender override                           |
+
+`verifyOtp` adds required `code`. Missing Channel →
+`fx.sendOtp needs a bound Channel — declare channel and set drivers.channel.sms (e.g. taqnyat)`.
+
+</Tab>
+
+<Tab value="App OTP">
+
+Your app generates the code; Channel fans out templates:
+
+```typescript
+await fx.deliverOtp({
+  channels: ["sms", "whatsapp", "email"],
+  templates: {
+    sms: "auth-otp-sms",
+    whatsapp: "auth-otp-whatsapp",
+    email: "auth-otp-email",
+  },
+  phone: "+15551234567",
+  email: "alice@example.com",
+  data: { otp: "482910" },
+  locale: "en",
+});
+```
+
+Capability: `sends: ["auth-otp"]`. Pass `only: "sms"` for a single-channel resend (no
+cross-medium failover).
+
+</Tab>
+
+<Tab value="Plugin">
+
+```typescript
+.plug(otp({ mode: "provider" }))
+// or
+.plug(otp({ mode: "app", channels: ["sms", "email"], exposeDevOtp: true }))
+```
+
+Full routes and modes: [OTP plugin](/docs/plugins/otp).
+
+</Tab>
+
+</Tabs>
+
+## Drivers
+
+| Driver id  | OTP Verify | Env                                                         |
+| ---------- | ---------- | ----------------------------------------------------------- |
+| `taqnyat`  | yes        | `TAQNYAT_BEARER_TOKEN` / `TAQNYAT_TOKEN` + `TAQNYAT_SENDER` |
+| `msegat`   | no         | `MSEGAT_USERNAME` / `MSEGAT_API_KEY` / `MSEGAT_SENDER`      |
+| `unifonic` | no         | `UNIFONIC_APPSID`                                           |
+| `console`  | —          | Config id that opens **no** SMS driver                      |
+
+Boot errors (verbatim):
+
+```text
+oke boot: taqnyat channel needs TAQNYAT_BEARER_TOKEN
+oke boot: taqnyat channel needs TAQNYAT_SENDER
+oke boot: msegat channel needs MSEGAT_USERNAME / MSEGAT_API_KEY / MSEGAT_SENDER
+oke boot: unifonic channel needs UNIFONIC_APPSID
+```
+
+Provider OTP without a Verify driver:
+
+```text
+channel: SMS driver "…" does not support provider-managed OTP; use exposeDevOtp locally or set drivers.channel.sms to "taqnyat"
+```
+
+No SMS bound:
+
+```text
+channel: no SMS driver bound — bind drivers.channel.sms (e.g. taqnyat) to send provider OTP
+```
+
+## Options Reference
+
+### `channel.sms(options?)`
+
+Same medium options as email: `from` / `sender`.
+
+### `.template(name, options?)`
+
+`description` · `locales` · `schema` — bodies in the catalog (`text` is typical for SMS).
+
+## Troubleshooting
+
+<Accordions>
+
+<Accordion title="fx.sendOtp / verifyOtp needs a bound Channel">
+  No Channel runtime, or SMS not configured. Declare templates/drivers and set
+  `drivers.channel.sms`.
+</Accordion>
+
+<Accordion title="channel: no SMS driver bound">
+  Config has no SMS id for this env (`CHANNEL_SMS_DEFAULTS` is empty). Pin `taqnyat` / `msegat` /
+  `unifonic`.
+</Accordion>
+
+<Accordion title="SMS driver does not support provider-managed OTP">
+  Only Taqnyat exposes `sendOtp` / `verifyOtp`. Switch driver or use app-mode OTP
+  (`fx.deliverOtp` / `otp({ mode: "app" })`).
+</Accordion>
+
+<Accordion title="channel: otp delivery has no viable channel">
+  `fx.deliverOtp` had no matching address for a declared medium (need `phone` for SMS / WhatsApp,
+  `email` for email).
+</Accordion>
+
+<Accordion title="channel: otp delivery failed on all channels">
+  Every medium in the failover list failed. Check driver credentials, suppression, and template
+  catalog entries.
+</Accordion>
+
+</Accordions>
+
+## Learn more
+
+- [OTP plugin](/docs/plugins/otp) — `/auth/otp/*`
+- [WhatsApp](/docs/elements/channel/whatsapp) — medium for app-mode OTP failover
+- [Email](/docs/elements/channel/email) — email leg of `deliverOtp`
+- [Channel overview](/docs/elements/channel) — effects and drivers
+- [Environment variables](/docs/reference/environment-variables) — SMS boot binder
+
+## Next
+
+<Cards>
+  <Card
+    title="WhatsApp"
+    description="WhatsApp Cloud and Taqnyat WhatsApp drivers."
+    href="/docs/elements/channel/whatsapp"
+  />
+  <Card
+    title="OTP Plugin"
+    description="Auth routes over provider or app OTP."
+    href="/docs/plugins/otp"
+  />
+  <Card
+    title="Channel Overview"
+    description="fx.send, catalogs, and consent."
+    href="/docs/elements/channel"
+  />
+</Cards>

package/site/content/docs/elements/channel/whatsapp.mdx

@@ -0,0 +1,220 @@
+---
+title: "WhatsApp"
+description: "WhatsApp medium — channel.whatsapp templates, wa-cloud and taqnyat-whatsapp drivers, app-mode OTP delivery."
+icon: "MessageCircle"
+source: "docs/spec/unified-theory.md"
+---
+
+WhatsApp (`channel.whatsapp`) is its own medium — not a Push subtype. Declare templates, pin a
+WhatsApp driver (opt-in; no default), and send with `fx.send` or include WhatsApp in
+`fx.deliverOtp` failover.
+
+For developers reaching users on Meta Cloud or Taqnyat WhatsApp — same Channel physics as SMS.
+
+<Callout title="The one rule">
+  Use `channel.whatsapp(…).template(…)` and set `drivers.channel.whatsapp` to `wa-cloud` or
+  `taqnyat-whatsapp`. Boot opens WhatsApp when configured; Push drivers are separate and not
+  auto-bound.
+</Callout>
+
+## Smallest Example
+
+<Steps>
+
+<Step>
+### Pin a WhatsApp driver
+
+```typescript title="oke.config.ts"
+import { defineConfig } from "okengine/config";
+
+export default defineConfig({
+  drivers: {
+    channel: {
+      whatsapp: { prod: "wa-cloud" },
+    },
+  },
+});
+```
+
+`wa-cloud` needs `WHATSAPP_TOKEN` (or `WA_CLOUD_TOKEN`) and `WHATSAPP_PHONE_NUMBER_ID`
+(or `WA_CLOUD_PHONE_NUMBER_ID`).
+
+</Step>
+
+<Step>
+### Declare and send
+
+```typescript title="src/core/channel.ts"
+import { channel } from "okengine";
+import { z } from "zod";
+
+const wa = channel.whatsapp();
+
+export const bookingReminder = wa.template("booking.reminder", {
+  locales: ["en", "ar"],
+  schema: z.object({ when: z.string(), place: z.string() }),
+});
+```
+
+```typescript
+await fx.send(bookingReminder, {
+  to: "+9665xxxxxxx",
+  data: { when: "Thu 15:00", place: "Clinic A" },
+  locale: "ar",
+});
+```
+
+</Step>
+
+<Step>
+### Confirm the effect
+
+Manifest / Console list `sends: ["booking.reminder"]`. Receipts follow the same ledger as email
+and SMS.
+
+</Step>
+
+</Steps>
+
+## Progressive Patterns
+
+<Tabs items={["Template", "Taqnyat", "App OTP"]}>
+
+<Tab value="Template">
+
+Catalog typically supplies `text` (and optional `subject` where the transport uses it):
+
+```typescript
+oke({
+  channel: {
+    catalog: {
+      "booking.reminder": {
+        en: { text: "Reminder: {{when}} at {{place}}" },
+        ar: { text: "تذكير: {{when}} — {{place}}" },
+      },
+    },
+  },
+});
+```
+
+</Tab>
+
+<Tab value="Taqnyat">
+
+```typescript
+drivers: {
+  channel: {
+    whatsapp: { prod: "taqnyat-whatsapp" },
+  },
+},
+```
+
+Needs `TAQNYAT_WHATSAPP_TOKEN` (falls back to `TAQNYAT_BEARER_TOKEN`). Missing token:
+
+```text
+oke boot: taqnyat-whatsapp channel needs TAQNYAT_WHATSAPP_TOKEN (or TAQNYAT_BEARER_TOKEN)
+```
+
+</Tab>
+
+<Tab value="App OTP">
+
+Include WhatsApp in app-owned OTP delivery (plugin or raw):
+
+```typescript
+await fx.deliverOtp({
+  channels: ["whatsapp", "sms", "email"],
+  templates: {
+    whatsapp: "auth-otp-whatsapp",
+    sms: "auth-otp-sms",
+    email: "auth-otp-email",
+  },
+  phone: "+15551234567",
+  data: { otp: "482910" },
+});
+```
+
+See [OTP plugin](/docs/plugins/otp) for `/auth/otp/*` and [SMS](/docs/elements/channel/sms) for
+provider vs app mode.
+
+</Tab>
+
+</Tabs>
+
+## Drivers
+
+| Driver id          | Env                                                                                           |
+| ------------------ | --------------------------------------------------------------------------------------------- |
+| `wa-cloud`         | `WHATSAPP_TOKEN` / `WA_CLOUD_TOKEN` + `WHATSAPP_PHONE_NUMBER_ID` / `WA_CLOUD_PHONE_NUMBER_ID` |
+| `taqnyat-whatsapp` | `TAQNYAT_WHATSAPP_TOKEN` or `TAQNYAT_BEARER_TOKEN`                                            |
+| `console`          | Config id — opens **no** WhatsApp driver                                                      |
+
+```text
+oke boot: wa-cloud channel needs WHATSAPP_TOKEN and WHATSAPP_PHONE_NUMBER_ID
+oke boot: unknown whatsapp channel driver "…"
+```
+
+## Options Reference
+
+### `channel.whatsapp(options?)`
+
+| Option   | Type     | Meaning           |
+| -------- | -------- | ----------------- |
+| `from`   | `string` | Default sender id |
+| `sender` | `string` | Alias for `from`  |
+
+### `.template(name, options?)`
+
+`description` · `locales` · `schema` — same as other mediums.
+
+## Troubleshooting
+
+<Accordions>
+
+<Accordion title="oke boot: wa-cloud channel needs WHATSAPP_TOKEN and WHATSAPP_PHONE_NUMBER_ID">
+  Both token and phone-number id are required for Meta Cloud. Check alias env names (`WA_CLOUD_*`)
+  if you use those.
+</Accordion>
+
+<Accordion title="oke boot: taqnyat-whatsapp channel needs TAQNYAT_WHATSAPP_TOKEN">
+  Set the WhatsApp-specific token or reuse `TAQNYAT_BEARER_TOKEN`.
+</Accordion>
+
+<Accordion title="fx.send succeeds nowhere — no WhatsApp in chain">
+  `drivers.channel.whatsapp` unset for this env, or id is `console`. Pin `wa-cloud` or
+  `taqnyat-whatsapp`.
+</Accordion>
+
+<Accordion title="channel: unknown template">
+  Template not auto-registered — import the `channel.whatsapp().template(…)` module before `oke()`,
+  or pass `channel.templates`.
+</Accordion>
+
+</Accordions>
+
+## Learn more
+
+- [SMS](/docs/elements/channel/sms) — OTP modes and `fx.deliverOtp`
+- [Push](/docs/elements/channel/push) — FCM / Web Push (separate medium)
+- [Channel overview](/docs/elements/channel) — locale, via, effects
+- [OTP plugin](/docs/plugins/otp) — multi-channel auth OTP
+
+## Next
+
+<Cards>
+  <Card
+    title="Push"
+    description="FCM and Web Push driver binding."
+    href="/docs/elements/channel/push"
+  />
+  <Card
+    title="SMS"
+    description="SMS templates and provider OTP."
+    href="/docs/elements/channel/sms"
+  />
+  <Card
+    title="Channel Overview"
+    description="Declare, send, and drivers."
+    href="/docs/elements/channel"
+  />
+</Cards>