sently 0.9.1 → 0.10.0

package/site/content/docs/guides/webhooks.mdx

@@ -1,12 +1,13 @@
 ---
 title: Webhooks
-description: Parse provider delivery events into a shared EmailEvent shape, with optional signature checks.
+description: Parse provider delivery events into EmailEvent or DeliveryEvent shapes, with optional signature checks.
 icon: Webhook
 source: "src/webhooks.ts"
 ---
 
-Use webhooks when a provider posts delivery updates (delivered, bounced, and similar).
-sently turns each provider payload into `EmailEvent[]` so your app can share one handler.
+Use webhooks when a provider posts delivery updates (delivered, bounced, failed, and similar).
+Email parsers return `EmailEvent[]`. SMS and WhatsApp parsers return `DeliveryEvent[]`.
+Map email events with `toDeliveryEvent` when you want one ingest pipeline.
 
 <Callout title="The one rule">
   Verify the signature against the unmodified raw request body before you trust or act on the event.
@@ -53,7 +54,7 @@ const events = parse(JSON.parse(rawBody));
 
 ```ts
 for (const event of events) {
-  if (event.type === "bounced") {
+  if (event.type === "bounced" || event.type === "failed") {
     // suppress or alert using event.messageId / event.recipient
   }
 }
@@ -65,19 +66,32 @@ for (const event of events) {
 
 ## Provider entrypoints
 
-| Import | Parse export | Verify export |
-| ------ | ------------ | ------------- |
-| `sently/webhooks/brevo` | `parse` | — |
-| `sently/webhooks/mailgun` | `parse` | `verifySignature`, `verifyPayload` |
-| `sently/webhooks/postmark` | `parse` | — |
-| `sently/webhooks/resend` | `parse` | `verifySignature` |
-| `sently/webhooks/sendgrid` | `parse` | — |
-| `sently/webhooks/ses` | `parse` | — |
-| `sently/webhooks/sndr` | `parse` | `verifySignature` |
-
-The convenience barrel `sently/webhooks` re-exports named helpers such as `parseSndrWebhook` and `verifySndrSignature`.
+| Import | Channel | Parse export | Verify export |
+| ------ | ------- | ------------ | ------------- |
+| `sently/webhooks/brevo` | Email | `parse` → `EmailEvent[]` | — |
+| `sently/webhooks/mailgun` | Email | `parse` | `verifySignature`, `verifyPayload` |
+| `sently/webhooks/postmark` | Email | `parse` | — |
+| `sently/webhooks/resend` | Email | `parse` | `verifySignature` |
+| `sently/webhooks/sendgrid` | Email | `parse` | — |
+| `sently/webhooks/ses` | Email | `parse` | — |
+| `sently/webhooks/sndr` | Email | `parse` | `verifySignature` |
+| `sently/webhooks/twilio-sms` | SMS | `parse` → `DeliveryEvent[]` | `verifySignature` (`X-Twilio-Signature`) |
+| `sently/webhooks/unifonic` | SMS | `parse` → `DeliveryEvent[]` | — |
+| `sently/webhooks/whatsapp-cloud` | WhatsApp | `parse` → `DeliveryEvent[]` | `verifySignature` (`X-Hub-Signature-256`) |
+
+The convenience barrel `sently/webhooks` re-exports named helpers such as `parseSndrWebhook`, `parseTwilioSmsWebhook`, and `toDeliveryEvent`.
 Bundlers tree-shake unused names; Node/Deno without a bundler evaluate every re-export.
 
+## SMS status callbacks
+
+Twilio posts form fields (`MessageSid`, `MessageStatus`, `To`). Pass a parsed object or `URLSearchParams`:
+
+```ts
+import { parse } from "sently/webhooks/twilio-sms";
+
+const events = parse(await request.formData().then((fd) => Object.fromEntries(fd)));
+```
+
 ## SNDR signatures
 
 SNDR signs with `X-Sndr-Signature: t=<unix>,v1=<hex>`.
@@ -99,7 +113,9 @@ Most frameworks parse JSON before your handler runs. Read the raw body first (`r
 
 <Accordion title="Which providers are supported?">
 
-Brevo, Mailgun, Postmark, Resend, SendGrid, SES, and SNDR. Import each from its `sently/webhooks/<provider>` subpath.
+Email: Brevo, Mailgun, Postmark, Resend, SendGrid, SES, SNDR.
+SMS / WhatsApp: Twilio SMS, Unifonic, WhatsApp Cloud.
+Import each from its `sently/webhooks/<provider>` subpath.
 
 </Accordion>
 
@@ -107,14 +123,13 @@ Brevo, Mailgun, Postmark, Resend, SendGrid, SES, and SNDR. Import each from its
 
 ## Learn more
 
-- [Webhook events](/docs/reference/webhook-events) — `EmailEvent` fields and type unions
-- [SNDR transport](/docs/transports/sndr) — send path that produces those message ids
+- [Webhook events](/docs/reference/webhook-events) — `EmailEvent` / `DeliveryEvent` fields
 - [Exports](/docs/reference/exports) — package entrypoints
 
 ## Next
 
 <Cards>
-  <Card title="Webhook events" description="Normalized EmailEvent fields." href="/docs/reference/webhook-events" />
-  <Card title="SNDR" description="Send email through SNDR." href="/docs/transports/sndr" />
+  <Card title="Webhook events" description="Normalized event fields." href="/docs/reference/webhook-events" />
+  <Card title="Channel send result" description="Shared accepted mapping." href="/docs/reference/channel-result" />
   <Card title="Exports" description="Public package entrypoints." href="/docs/reference/exports" />
 </Cards>

package/site/content/docs/index.mdx

@@ -1,6 +1,6 @@
 ---
 title: sently handbook
-description: Channel-first messaging for email, SMS, WhatsApp, and web push.
+description: Channel-first messaging for email, SMS, WhatsApp, and push (Web Push / FCM).
 icon: BookOpen
 source: "README.md"
 ---

package/site/content/docs/quick-start/push.mdx

@@ -1,14 +1,20 @@
 ---
 title: Push
-description: Send a browser notification through a channel sender.
+description: Send a Web Push or FCM notification through a channel sender.
 icon: Bell
 source: "src/push.ts"
 ---
 
-<Callout title="The one rule">Store the browser subscription and send it back unchanged as `subscription`.</Callout>
+Send a browser Web Push or FCM device notification through `createPushSender`.
+
+<Callout title="The one rule">
+  Use `subscription` with `WebPushTransport`, or `token` with `FcmTransport` — not both shapes on the wrong transport.
+</Callout>
+
+## Quick start
 
 <Steps>
-  <Step title="Create the sender">
+  <Step title="Create a Web Push sender">
 
 ```ts
 import { createPushSender } from "sently/push";
@@ -27,10 +33,21 @@ const push = createPushSender({
   <Step title="Send">
 
 ```ts
-await push.send({ subscription, title: "Update", body: "Your report is ready." });
+await push.send({
+  subscription,
+  title: "Update",
+  body: "Your report is ready.",
+});
 ```
 
   </Step>
 </Steps>
 
-<Cards><Card title="Push channel" href="/docs/channels/push" /></Cards>
+For FCM device tokens, use `FcmTransport` and `token` instead of `subscription` — see [FCM](/docs/transports/fcm).
+
+## Next
+
+<Cards>
+  <Card title="Push channel" href="/docs/channels/push" />
+  <Card title="FCM transport" href="/docs/transports/fcm" />
+</Cards>

package/site/content/docs/reference/channel-result.mdx

@@ -0,0 +1,82 @@
+---
+title: Channel send result
+description: Map email, SMS, WhatsApp, and push results to a shared accepted shape.
+icon: Boxes
+source: "src/core/channel-result.ts"
+---
+
+Adapters that span channels can normalize every send into
+`{ messageId, provider, accepted }` without inventing per-provider glue.
+Use this after `mailer.send`, `sms.send`, `whatsapp.send`, or `push.send`.
+
+<Callout title="The one rule">
+  Keep channel-specific fields on the original result; use `toChannelSendResult` only for the shared slice.
+</Callout>
+
+## Quick start
+
+<Steps>
+  <Step title="Send on any channel">
+
+```ts
+import { createSmsSender } from "sently/sms";
+import { toChannelSendResult } from "sently/channel-result";
+import { UnifonicTransport } from "sently/transports/unifonic";
+
+const sms = createSmsSender({
+  transport: new UnifonicTransport({
+    appSid: process.env.UNIFONIC_APPSID!,
+    senderId: "MyBrand",
+  }),
+});
+const result = await sms.send({ to: "+15551234567", body: "Hi" });
+```
+
+  </Step>
+  <Step title="Normalize for your adapter">
+
+```ts
+const shared = toChannelSendResult(result);
+// { messageId, provider?, accepted }
+```
+
+  </Step>
+</Steps>
+
+## ChannelSendResult
+
+| Field | Type | Meaning |
+| --- | --- | --- |
+| `messageId` | `string` | Provider or client message id |
+| `provider` | `string?` | Transport id when set |
+| `accepted` | `boolean` | Provider accepted the send (not end-user delivery) |
+
+## Mapping
+
+| Channel result | `accepted` |
+| --- | --- |
+| Email `SendResult` | `accepted.length > 0` and `rejected.length === 0` |
+| SMS / WhatsApp / Push | `status` in `accepted` / `queued` / `sending` / `sent` / `delivered` / `read` / `success` (case-insensitive) |
+
+Import from `sently/channel-result` or the main `sently` barrel.
+
+## Troubleshooting
+
+<Accordions>
+  <Accordion title="Why is accepted true but the user never got the message?">
+    Acceptance means the provider took the message. Use [webhooks](/docs/guides/webhooks) for delivered / failed outcomes.
+  </Accordion>
+</Accordions>
+
+## Learn more
+
+- [Webhook events](./webhook-events)
+- [SMS options](./sms-options)
+- [Exports](./exports)
+
+## Next
+
+<Cards>
+  <Card title="Webhook events" href="/docs/reference/webhook-events" />
+  <Card title="Exports" href="/docs/reference/exports" />
+</Cards>

package/site/content/docs/reference/exports.mdx

@@ -17,12 +17,13 @@ The main `sently` package is for shared types and factories — not every provid
 
 | Import | Primary API |
 | ------ | ----------- |
-| `sently` | `createMailer`, `createSMTPMailer`, types, OAuth2, `SentlyError`, `consoleObserver`, `FallbackTransport`, `WeightedFallbackTransport`, `CloudflareEmailTransport` |
+| `sently` | `createMailer`, `createSMTPMailer`, types, OAuth2, `SentlyError`, `consoleObserver`, `toChannelSendResult`, `FallbackTransport`, `WeightedFallbackTransport`, `CloudflareEmailTransport` |
 | `sently/mailer` | `createMailer` only |
 | `sently/smtp` | `createSMTPMailer` |
 | `sently/sms` | `createSmsSender` |
 | `sently/whatsapp` | `createWhatsAppSender` |
 | `sently/push` | `createPushSender` |
+| `sently/channel-result` | `toChannelSendResult`, `ChannelSendResult` |
 | `sently/errors` | `SentlyError` hierarchy |
 | `sently/idempotency` | `IdempotencyTransport` |
 | `sently/dkim` | DKIM signing |
@@ -36,7 +37,7 @@ The main `sently` package is for shared types and factories — not every provid
 
 | Import | Use |
 | ------ | --- |
-| `sently/transports/<name>` | One provider or email decorator (e.g. `sndr`, `resend`, `twilio-sms`) |
+| `sently/transports/<name>` | One provider or decorator (e.g. `sndr`, `unifonic`, `fcm`, `retry`) |
 
 HTTP providers such as SNDR, Resend, and Plunk are **not** re-exported from `sently`.
 
@@ -47,7 +48,8 @@ HTTP providers such as SNDR, Resend, and Plunk are **not** re-exported from `sen
 | `sently/webhooks/<provider>` | One parser (+ verify helper when exported) |
 | `sently/webhooks` | Convenience barrel of all named helpers |
 
-Providers: `brevo`, `mailgun`, `postmark`, `resend`, `sendgrid`, `ses`, `sndr`.
+Email: `brevo`, `mailgun`, `postmark`, `resend`, `sendgrid`, `ses`, `sndr`.
+SMS / WhatsApp: `twilio-sms` (+ verify), `unifonic`, `whatsapp-cloud` (+ verify).
 
 ## Adapters
 

package/site/content/docs/reference/meta.json

@@ -9,6 +9,7 @@
     "whatsapp-options",
     "push-options",
     "transport-contracts",
+    "channel-result",
     "errors",
     "webhook-events"
   ]

package/site/content/docs/reference/push-options.mdx

@@ -1,13 +1,21 @@
 ---
 title: Push options
-description: Fields accepted by `PushSender.send`.
+description: Fields accepted by `PushSender.send` for Web Push and FCM.
 icon: Bell
 source: "src/core/push-types.ts"
 ---
 
+`PushOptions` is `WebPushOptions | FcmPushOptions`.
+Pick the shape that matches your transport.
+
+<Callout title="The one rule">
+  Pass `subscription` to `WebPushTransport` and `token` to `FcmTransport`.
+</Callout>
+
+## Shared fields
+
 | Field | Type | Required |
 | --- | --- | --- |
-| `subscription` | `PushSubscription` | yes |
 | `title` | `string` | yes |
 | `body` | `string` | yes |
 | `data` | `Record<string, unknown>` | no |
@@ -15,6 +23,39 @@ source: "src/core/push-types.ts"
 | `ttl` | `number` | no |
 | `messageId` | `string` | no |
 
+## Web Push
+
+| Field | Type | Required |
+| --- | --- | --- |
+| `subscription` | `PushSubscription` | yes |
+
 A subscription contains `endpoint`, `keys.p256dh`, and `keys.auth`.
 
-<Cards><Card title="Push channel" href="/docs/channels/push" /></Cards>
+## FCM
+
+| Field | Type | Required |
+| --- | --- | --- |
+| `token` | `string` | yes |
+| `image` | `string` | no |
+
+FCM stringifies non-string `data` values before send.
+
+## Result
+
+| Field | Type | Notes |
+| --- | --- | --- |
+| `messageId` | `string` | Provider or client id |
+| `status` | `string` | e.g. `"accepted"` |
+| `response` | `string` | Often the HTTP status or FCM name |
+| `provider` | `string?` | `"webpush"` / `"fcm"`; set by fallback |
+| `providerIndex` | `number?` | Fallback chain index |
+
+Map any channel result with [channel send result](./channel-result).
+
+## Next
+
+<Cards>
+  <Card title="Push channel" href="/docs/channels/push" />
+  <Card title="FCM transport" href="/docs/transports/fcm" />
+  <Card title="Channel send result" href="/docs/reference/channel-result" />
+</Cards>

package/site/content/docs/reference/sms-options.mdx

@@ -12,6 +12,22 @@ source: "src/core/sms-types.ts"
 | `from` | `string` | no |
 | `messageId` | `string` | no |
 
-The result includes `messageId`, `to`, `status`, `response`, and optional `provider`.
+## Result
 
-<Cards><Card title="SMS channel" href="/docs/channels/sms" /></Cards>
+| Field | Type | Notes |
+| --- | --- | --- |
+| `messageId` | `string` | Provider or client id |
+| `to` | `string` | Recipient |
+| `status` | `string` | e.g. `"accepted"`, `"queued"` |
+| `response` | `string` | Provider text |
+| `provider` | `string?` | Transport id; set by fallback |
+| `providerIndex` | `number?` | Fallback chain index |
+
+Map any channel result to `{ messageId, provider, accepted }` with [channel send result](./channel-result).
+
+## Next
+
+<Cards>
+  <Card title="SMS channel" href="/docs/channels/sms" />
+  <Card title="Channel send result" href="/docs/reference/channel-result" />
+</Cards>

package/site/content/docs/reference/webhook-events.mdx

@@ -1,17 +1,29 @@
 ---
 title: Webhook events
-description: Normalized EmailEvent fields returned by every provider webhook parser.
+description: Normalized EmailEvent and DeliveryEvent fields from provider webhook parsers.
 icon: Webhook
 source: "src/webhooks/types.ts"
 ---
 
-Every parser returns `EmailEvent[]` so delivery webhooks can share one application pipeline.
-Verify signatures in the [webhooks guide](/docs/guides/webhooks) before you process events.
+Email parsers return `EmailEvent[]`. SMS and WhatsApp parsers return `DeliveryEvent[]`.
+Use `toDeliveryEvent` to put email events on the same ingest path as SMS / WhatsApp.
 
 <Callout title="The one rule">
   Branch on `event.type` and keep provider-specific details in `event.raw` when you need them.
 </Callout>
 
+## DeliveryEvent
+
+| Field | Type | Meaning |
+| ----- | ---- | ------- |
+| `channel` | `"email" \| "sms" \| "whatsapp" \| "push"` | Messaging channel |
+| `provider` | `string` | Parser id (e.g. `"twilio-sms"`) |
+| `type` | union below | Normalized lifecycle type |
+| `messageId` | `string?` | Provider message id when present |
+| `recipient` | `string?` | Address or phone when present |
+| `timestamp` | `Date?` | Event time when present |
+| `raw` | `unknown` | Original provider payload |
+
 ## EmailEvent
 
 | Field | Type | Meaning |
@@ -25,15 +37,27 @@ Verify signatures in the [webhooks guide](/docs/guides/webhooks) before you proc
 
 ## Normalized `type` values
 
-| Value | Meaning |
-| ----- | ------- |
-| `delivered` | Accepted / delivered to the mailbox provider. |
-| `bounced` | Hard failure or bounce. |
-| `complained` | Spam complaint. |
-| `opened` | Open tracking. |
-| `clicked` | Click tracking. |
-| `deferred` | Temporary deferral. |
-| `unknown` | Unmapped or informational provider event. |
+| Value | Channels | Meaning |
+| ----- | -------- | ------- |
+| `queued` | SMS | Accepted / queued by the provider |
+| `sent` | SMS / WhatsApp | Handed to the network |
+| `delivered` | All | Delivered (or mailbox accepted for email) |
+| `failed` | SMS / WhatsApp | Permanent failure |
+| `read` | SMS / WhatsApp | Read receipt |
+| `bounced` | Email | Hard failure or bounce |
+| `complained` | Email | Spam complaint |
+| `opened` | Email | Open tracking |
+| `clicked` | Email | Click tracking |
+| `deferred` | Email | Temporary deferral |
+| `unknown` | All | Unmapped or informational event |
+
+## Mapping helpers
+
+```ts
+import { toDeliveryEvent } from "sently/webhooks";
+
+const delivery = toDeliveryEvent(emailEvent);
+```
 
 ## SNDR mapping
 
@@ -51,7 +75,7 @@ SNDR `data.email_id` becomes `messageId`. Recipients come from `data.to` or `dat
 
 <Accordion title="Why is unsubscribed mapped to unknown?">
 
-The shared `EmailEvent.type` union has no unsubscribe value. Keep the vendor payload in `raw` if you need unsubscribe-specific handling.
+The shared email `type` union has no unsubscribe value. Keep the vendor payload in `raw` if you need unsubscribe-specific handling.
 
 </Accordion>
 
@@ -60,7 +84,7 @@ The shared `EmailEvent.type` union has no unsubscribe value. Keep the vendor pay
 ## Learn more
 
 - [Webhooks guide](/docs/guides/webhooks) — verify + parse flow
-- [SNDR transport](/docs/transports/sndr) — sending side
+- [Channel send result](/docs/reference/channel-result) — send-time accepted mapping
 
 ## Next
 

package/site/content/docs/reference/whatsapp-options.mdx

@@ -12,4 +12,22 @@ source: "src/core/whatsapp-types.ts"
 
 Both shapes accept optional `messageId`. Template components can include `header`, `body`, or `button` parameters.
 
-<Cards><Card title="WhatsApp channel" href="/docs/channels/whatsapp" /></Cards>
+## Result
+
+| Field | Type | Notes |
+| --- | --- | --- |
+| `messageId` | `string` | Provider or client id |
+| `to` | `string` | Recipient |
+| `status` | `string` | e.g. `"accepted"` |
+| `response` | `string` | Provider text |
+| `provider` | `string?` | Transport id; set by fallback |
+| `providerIndex` | `number?` | Fallback chain index |
+
+Map any channel result with [channel send result](./channel-result).
+
+## Next
+
+<Cards>
+  <Card title="WhatsApp channel" href="/docs/channels/whatsapp" />
+  <Card title="Channel send result" href="/docs/reference/channel-result" />
+</Cards>

package/site/content/docs/transports/fcm.mdx

@@ -0,0 +1,80 @@
+---
+title: FCM
+description: Send mobile push through Firebase Cloud Messaging HTTP v1.
+icon: Bell
+source: "src/transports/fcm.ts"
+---
+
+Send device-token push through Firebase Cloud Messaging HTTP v1 for native Android and iOS clients.
+Use [Web Push](./webpush) when you have a browser Push API subscription instead.
+
+<Callout title="The one rule">Pass `token` in push options — not a Web Push `subscription`.</Callout>
+
+## Quick start
+
+<Steps>
+  <Step title="Configure the transport">
+
+```ts
+import { createPushSender } from "sently/push";
+import { FcmTransport } from "sently/transports/fcm";
+
+const push = createPushSender({
+  transport: new FcmTransport({
+    projectId: process.env.FCM_PROJECT_ID!,
+    clientEmail: process.env.FCM_CLIENT_EMAIL!,
+    privateKey: process.env.FCM_PRIVATE_KEY!,
+  }),
+});
+```
+
+  </Step>
+  <Step title="Send to a device token">
+
+```ts
+const result = await push.send({
+  token: deviceRegistrationToken,
+  title: "Hello",
+  body: "World",
+});
+console.log(result.messageId, result.status);
+```
+
+  </Step>
+</Steps>
+
+## Configuration
+
+| Option | Type | Default or requirement |
+| --- | --- | --- |
+| `projectId` | `string` | required |
+| `clientEmail` | `string` | service account email |
+| `privateKey` | `string` | PEM private key (env / secrets only) |
+| `getAccessToken` | `() => Promise<string>` | optional override for tests |
+
+Literal `\n` sequences in `privateKey` env strings are normalized to newlines.
+The transport mints a short-lived OAuth2 token with scope `firebase.messaging` — no Google SDK.
+
+## Troubleshooting
+
+<Accordions>
+  <Accordion title="Can I pass a browser subscription?">
+    No. `FcmTransport` requires `token`. Use `WebPushTransport` for VAPID subscriptions.
+  </Accordion>
+  <Accordion title="Where do I get the private key?">
+    Download a Firebase / GCP service account JSON and pass `project_id`, `client_email`, and `private_key` from that file via environment variables.
+  </Accordion>
+</Accordions>
+
+## Learn more
+
+- [Push channel](/docs/channels/push)
+- [Push options](/docs/reference/push-options)
+- [Web Push](./webpush)
+
+## Next
+
+<Cards>
+  <Card title="Push channel" href="/docs/channels/push" />
+  <Card title="Web Push" href="/docs/transports/webpush" />
+</Cards>

package/site/content/docs/transports/index.mdx

@@ -63,9 +63,11 @@ Every import below is an exported package subpath.
 | [Twilio SMS](./twilio-sms) | SMS | `sently/transports/twilio-sms` |
 | [Taqnyat SMS](./taqnyat-sms) | SMS | `sently/transports/taqnyat-sms` |
 | [Msegat](./msegat) | SMS | `sently/transports/msegat` |
+| [Unifonic](./unifonic) | SMS | `sently/transports/unifonic` |
 | [WhatsApp Cloud](./whatsapp-cloud) | WhatsApp | `sently/transports/whatsapp-cloud` |
 | [Taqnyat WhatsApp](./taqnyat-whatsapp) | WhatsApp | `sently/transports/taqnyat-whatsapp` |
 | [Web Push](./webpush) | Push | `sently/transports/webpush` |
+| [FCM](./fcm) | Push | `sently/transports/fcm` |
 
 For retry, fallback, preview, and idempotency wrappers, see [Decorators](../decorators).
 
@@ -85,7 +87,7 @@ For retry, fallback, preview, and idempotency wrappers, see [Decorators](../deco
     No. A transport implements one channel contract. Choose a transport listed for the channel sender you use.
   </Accordion>
   <Accordion title="How do I add retries or fallback?">
-    Wrap an email transport with a [decorator](../decorators), then pass the wrapper to `createMailer`.
+    Wrap any channel transport with a [decorator](../decorators), then pass the wrapper to the matching sender.
   </Accordion>
 </Accordions>
 

package/site/content/docs/transports/meta.json

@@ -23,10 +23,12 @@
     "twilio-sms",
     "taqnyat-sms",
     "msegat",
+    "unifonic",
     "---WhatsApp---",
     "whatsapp-cloud",
     "taqnyat-whatsapp",
     "---Push---",
-    "webpush"
+    "webpush",
+    "fcm"
   ]
 }