sently 0.9.2 → 1.0.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,15 +1,89 @@
 ---
 title: sently handbook
-description: Channel-first messaging for email, SMS, WhatsApp, and web push.
+description: Channel-delivery for email, SMS, WhatsApp, and push — one sender shape as channels grow.
 icon: BookOpen
 source: "README.md"
 ---
 
-Use a channel sender in application code and put provider-specific configuration in a transport.
+sently is the channel-delivery layer for the order confirmation email, the OTP SMS, and the device push that follow.
+Apps call a channel sender; providers live in transports you can swap without rewriting send sites.
+
+<Callout title="The one rule">
+  Use `createMailer`, `createSmsSender`, `createWhatsAppSender`, or `createPushSender` in app code — never a vendor SDK as your application API.
+</Callout>
+
+## Quick start
+
+<Steps>
+  <Step title="Install">
+
+```bash
+bun add sently
+```
+
+  </Step>
+  <Step title="Send with a channel sender">
+
+```ts
+import { createMailer } from "sently/mailer";
+import { ResendTransport } from "sently/transports/resend";
+
+const mailer = await createMailer({
+  transport: new ResendTransport({
+    apiKey: process.env.RESEND_API_KEY!,
+  }),
+});
+
+const result = await mailer.send({
+  from: "hello@example.com",
+  to: "person@example.com",
+  subject: "Welcome",
+  text: "Thanks for joining.",
+});
+console.log(result.messageId);
+```
+
+  </Step>
+</Steps>
+
+## Channels
+
+| Channel | Sender | Start here |
+| --- | --- | --- |
+| Email | `createMailer` / `createSMTPMailer` | [Email](/docs/channels/email) |
+| SMS | `createSmsSender` | [SMS](/docs/channels/sms) |
+| WhatsApp | `createWhatsAppSender` | [WhatsApp](/docs/channels/whatsapp) |
+| Push | `createPushSender` | [Push](/docs/channels/push) |
+
+Email factories are asynchronous. SMS, WhatsApp, and push factories return the sender synchronously; every `send` is async.
+
+## Where next
+
+| Path | When |
+| --- | --- |
+| [Get started](/docs/get-started) | Install, entrypoints, runtimes, migrate from Nodemailer |
+| [Channels](/docs/channels) | Full sender docs + lifecycle hooks |
+| [Transports](/docs/transports) | Provider list by channel |
+| [Failover](/docs/guides/failover) | Retry inside a provider, then fail over |
+| [Support matrix](/docs/get-started/support-matrix) | Supported vs Available for production |
+| [Compare](/docs/guides/compare) | vs vendor SDKs, Nodemailer, Novu / Knock / Courier |
+| [Stability](/docs/get-started/stability) | What is frozen at 1.x |
+
+## Troubleshooting
+
+<Accordions>
+  <Accordion title="Is sently a notification platform like Novu or Knock?">
+    No. It is the delivery layer. Preference centers, digests, workflows, and in-app inboxes sit on top — custom code or those tools. See [Compare](/docs/guides/compare).
+  </Accordion>
+  <Accordion title="Where should I send first?">
+    Start with [Email](/docs/channels/email) or [Installation](/docs/get-started/installation), then open the channel page for SMS, WhatsApp, or push when you add that channel.
+  </Accordion>
+</Accordions>
+
+## Next
 
 <Cards>
   <Card title="Get started" href="/docs/get-started" />
-  <Card title="Quick start" href="/docs/quick-start" />
   <Card title="Channels" href="/docs/channels" />
-  <Card title="Transports" href="/docs/transports" />
+  <Card title="Support matrix" href="/docs/get-started/support-matrix" />
 </Cards>

package/site/content/docs/meta.json

@@ -4,7 +4,6 @@
   "pages": [
     "index",
     "get-started",
-    "quick-start",
     "channels",
     "transports",
     "decorators",

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`, `mailpit`, `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
 
@@ -73,11 +75,14 @@ Provider transports live on `sently/transports/*` so bare Node/Deno imports of `
 ## Learn more
 
 - [Entrypoints](/docs/get-started/entrypoints) — which import to pick first
-- [Bundle size](/docs/guides/bundle-size) — measured stacks
+- [Stability policy](/docs/get-started/stability) — frozen entrypoints at 1.x
+- [Support matrix](/docs/get-started/support-matrix) — Supported vs Available
+- [Bundle size](/docs/guides/bundle-size) — measured stacks (supporting for Workers)
 
 ## Next
 
 <Cards>
   <Card title="Entrypoints" description="Choose a channel import path." href="/docs/get-started/entrypoints" />
+  <Card title="Support matrix" description="Production support promise." href="/docs/get-started/support-matrix" />
   <Card title="Transports" description="Provider list by channel." href="/docs/transports" />
 </Cards>

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,53 @@ 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).
+
+## Troubleshooting
+
+<Accordions>
+  <Accordion title="Can I send both subscription and token?">
+    No. Each call is either Web Push (`subscription`) or FCM (`token`). Match the shape to the transport.
+  </Accordion>
+</Accordions>
+
+## Learn more
+
+- [Push channel](/docs/channels/push)
+- [Stability policy](/docs/get-started/stability) — union shape is frozen at 1.x
+- [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,84 @@
+---
+title: FCM
+description: Send mobile push through Firebase Cloud Messaging (current HTTP API).
+icon: Bell
+source: "src/transports/fcm.ts"
+---
+
+Send device-token push through Firebase Cloud Messaging for native Android and iOS clients.
+The transport uses the current FCM HTTP API with a service-account JWT — no Google SDK.
+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="Verify credentials, then send">
+
+```ts
+const check = await push.verify();
+console.log(check.ok, check.message);
+
+const result = await push.send({
+  token: deviceRegistrationToken,
+  title: "Hello",
+  body: "World",
+});
+console.log(result.messageId, result.status, result.provider);
+```
+
+  </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>