sently 0.10.0 → 1.0.1

package/site/content/docs/get-started/support-matrix.mdx

@@ -0,0 +1,62 @@
+---
+title: Support matrix
+description: Supported vs Available transports and runtimes for production use.
+icon: LayoutGrid
+source: "package.json"
+---
+
+Not every exported transport is part of the **1.x production promise**.
+**Supported** paths are documented, tested, and operable (verify, retry/fallback, and webhooks where listed).
+**Available** paths ship and have unit coverage but are not the support bar.
+
+<Callout title="The one rule">
+  Build production apps on Supported transports. Treat Available exports as optional extras you can adopt knowing the promise is thinner.
+</Callout>
+
+## Supported (v1 promise)
+
+| Channel | Supported transports | Operability |
+| --- | --- | --- |
+| Email | SMTP, Resend, SES, SendGrid, Postmark | Attachments / HTML / text, `verify`, retry / fallback, webhooks for the HTTP majors |
+| SMS | Twilio SMS, Unifonic | Webhooks for Twilio and Unifonic |
+| WhatsApp | WhatsApp Cloud | Signature verify + delivery parse |
+| Push | Web Push, FCM | Option union: `subscription` (Web Push) or `token` (FCM) |
+| Runtimes | Node ≥18, Bun, Deno, Cloudflare Workers | Adapters and smoke scripts |
+
+FCM uses the current Firebase HTTP API (service-account JWT, no Google SDK). That is baseline push support, not a special feature tier.
+
+## Available (exported, not the v1 bar)
+
+| Channel | Available examples |
+| --- | --- |
+| Email | Mailgun, Brevo, MailerSend, Plunk, SparkPost, Mailtrap, Mailpit (dev), Loops, SNDR, Taqnyat Mail, Cloudflare Email, … |
+| SMS | Taqnyat SMS, Msegat |
+| WhatsApp | Taqnyat WhatsApp |
+| Decorators | `WeightedFallbackTransport` (advanced); preview / idempotency remain email-only |
+| Local email | [Mailpit](/docs/transports/mailpit) (SMTP catcher), [Preview](/docs/decorators/preview) (disk) |
+
+Available transports stay in the package. They are promoted to Supported when docs, operability, and smoke coverage meet the bar above.
+
+## Troubleshooting
+
+<Accordions>
+  <Accordion title="Can I use an Available transport in production?">
+    Yes, at your own risk. Prefer Supported paths when you need the documented operability promise.
+  </Accordion>
+  <Accordion title="Why is Mailgun Available but Postmark Supported?">
+    The Supported set is a deliberate short list for the 1.x promise — not a popularity ranking of every working export.
+  </Accordion>
+</Accordions>
+
+## Learn more
+
+- [Stability policy](./stability)
+- [Non-goals](./non-goals)
+- [Transports](/docs/transports)
+
+## Next
+
+<Cards>
+  <Card title="Stability policy" href="/docs/get-started/stability" />
+  <Card title="Transports" href="/docs/transports" />
+</Cards>

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

@@ -0,0 +1,87 @@
+---
+title: Compare
+description: How sently fits next to vendor SDKs, Nodemailer, and orchestration platforms.
+icon: Scale
+source: "README.md"
+---
+
+Teams often start with one channel — usually email via SendGrid or Resend — then add SMS and push.
+Each new vendor SDK brings its own auth, retries, and error shapes into app code.
+
+<Callout title="The one rule">
+  Treat sently as the channel-delivery layer. Put preference centers, digests, workflow builders, and in-app inboxes on top of it — custom code or a tool like Novu, Knock, or Courier — not instead of it.
+</Callout>
+
+## What sently replaces
+
+| Instead of… | Use sently for… |
+| --- | --- |
+| A growing pile of vendor SDKs in call sites | Channel senders + pluggable transports |
+| Per-channel retry and error glue | Shared `SentlyError` codes and retry/fallback decorators |
+| Nodemailer when you need multi-channel or non-Node runtimes | `createMailer` / `createSMTPMailer` plus SMS, WhatsApp, and push |
+
+## What sently does not replace
+
+| Need | Where it lives |
+| --- | --- |
+| Preference centers and unsubscribe UX | Your product, or Novu / Knock / Courier |
+| Digest / batching product logic | Your product, or an orchestration platform |
+| Workflow builders and multi-step journeys | Your product, or Novu / Knock / Courier |
+| In-app notification inboxes | Your product, or an orchestration platform |
+
+Those tools (or your own routing) call sently — or any transport — to deliver. sently does not ship dashboards or per-send SaaS.
+
+## Versus a vendor SDK pile
+
+| Concern | Typical stack | sently |
+| --- | --- | --- |
+| As you add channels | New SDK, new auth, new retries | Same sender factories |
+| Failures | Per-vendor exceptions | Stable `SentlyError` codes |
+| Reliability | Ad-hoc loops per client | `RetryTransport` + `FallbackTransport` |
+| Provider swap | Rewrite call sites | Swap the transport |
+
+## Versus Nodemailer
+
+| Concern | Nodemailer | sently |
+| --- | --- | --- |
+| Channels | Email | Email · SMS · WhatsApp · Push |
+| Runtimes | Node.js | Node · Bun · Deno · CF Workers |
+| Module format | CommonJS | ESM only |
+| Edge / Workers weight | Full mail stack on import | Tree-shakeable subpaths (~6.3 KB HTTP) |
+
+Bundle size matters most on Workers and cold starts. It is supporting evidence, not the primary reason to adopt.
+
+## Versus Novu, Knock, and Courier
+
+| Concern | Orchestration platforms | sently |
+| --- | --- | --- |
+| Role | Workflows, preferences, digests, in-app | Channel delivery / transports |
+| Hosting | Usually hosted SaaS | Library in your process |
+| Pricing model | Often per-send or seat | MIT package; you pay providers |
+
+Use both when you need product orchestration **and** a typed, multi-runtime delivery layer underneath.
+
+## Troubleshooting
+
+<Accordions>
+  <Accordion title="Do I need sently if I already use Novu or Knock?">
+    Only if you want local, typed transports under your own routing — or to send outside that platform. Many teams use an orchestration tool for preferences and journeys, and a library like sently for direct transactional sends.
+  </Accordion>
+  <Accordion title="Is sently a Nodemailer drop-in?">
+    No. Migrate email with [Migrate from Nodemailer](/docs/get-started/migrate-nodemailer), then add other channels with the same sender pattern.
+  </Accordion>
+</Accordions>
+
+## Learn more
+
+- [Introduction](/docs/get-started/introduction)
+- [Stability policy](/docs/get-started/stability)
+- [Support matrix](/docs/get-started/support-matrix)
+- [Migrate from Nodemailer](/docs/get-started/migrate-nodemailer)
+
+## Next
+
+<Cards>
+  <Card title="Introduction" href="/docs/get-started/introduction" />
+  <Card title="Support matrix" href="/docs/get-started/support-matrix" />
+</Cards>

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

@@ -0,0 +1,121 @@
+---
+title: Failover
+description: Retry inside a provider, then fail over across providers on any channel.
+icon: GitBranch
+source: "src/transports/fallback.ts"
+---
+
+When a provider blips, retry that transport first, then fail over to the next.
+The same decorator pattern works for email, SMS, WhatsApp, and push.
+
+<Callout title="The one rule">
+  Wrap each provider in `RetryTransport`, then pass the list to `FallbackTransport`. Use the channel sender that matches the transport contract.
+</Callout>
+
+## Quick start
+
+<Steps>
+  <Step title="Email — Resend then SES">
+
+```ts
+import { createMailer } from "sently/mailer";
+import { FallbackTransport } from "sently/transports/fallback";
+import { RetryTransport } from "sently/transports/retry";
+import { ResendTransport } from "sently/transports/resend";
+import { SESTransport } from "sently/transports/ses";
+
+const mailer = await createMailer({
+  transport: new FallbackTransport(
+    [
+      new RetryTransport(new ResendTransport({ apiKey: process.env.RESEND_API_KEY! })),
+      new RetryTransport(
+        new SESTransport({
+          region: process.env.AWS_REGION!,
+          accessKeyId: process.env.AWS_ACCESS_KEY_ID!,
+          secretAccessKey: process.env.AWS_SECRET_ACCESS_KEY!,
+        }),
+      ),
+    ],
+    { cooldownMs: 300_000 },
+  ),
+});
+```
+
+  </Step>
+  <Step title="SMS — Twilio then Unifonic">
+
+```ts
+import { createSmsSender } from "sently/sms";
+import { FallbackTransport } from "sently/transports/fallback";
+import { RetryTransport } from "sently/transports/retry";
+import { TwilioSmsTransport } from "sently/transports/twilio-sms";
+import { UnifonicTransport } from "sently/transports/unifonic";
+
+const sms = createSmsSender({
+  transport: new FallbackTransport(
+    [
+      new RetryTransport(
+        new TwilioSmsTransport({
+          accountSid: process.env.TWILIO_ACCOUNT_SID!,
+          authToken: process.env.TWILIO_AUTH_TOKEN!,
+        }),
+      ),
+      new RetryTransport(
+        new UnifonicTransport({
+          appSid: process.env.UNIFONIC_APPSID!,
+          senderId: "MyBrand",
+        }),
+      ),
+    ],
+    { cooldownMs: 300_000 },
+  ),
+});
+```
+
+  </Step>
+  <Step title="Inspect which provider won">
+
+```ts
+const result = await sms.send({
+  to: "+15551234567",
+  body: "Hello",
+  from: "+15557654321",
+});
+console.log(result.provider, result.providerIndex);
+```
+
+  </Step>
+</Steps>
+
+## Behavior
+
+| Behavior | Default |
+| --- | --- |
+| Fail over on 5xx / network | Yes |
+| Fail over on 400 / 401 / 403 | No (same client error on every provider) |
+| `cooldownMs` | Skip a failed provider until the cooldown ends |
+| Hooks | `onRetry` / `onFallback` on the channel sender when wired |
+
+## Troubleshooting
+
+<Accordions>
+  <Accordion title="Why did both providers reject the same message?">
+    Permanent client errors do not fail over by default. Fix the payload or credentials before expecting a second provider to succeed.
+  </Accordion>
+  <Accordion title="Can I mix email and SMS in one FallbackTransport?">
+    No. Every entry must implement the same channel contract as the sender.
+  </Accordion>
+</Accordions>
+
+## Learn more
+
+- [Retry](/docs/decorators/retry)
+- [Fallback](/docs/decorators/fallback)
+- [Support matrix](/docs/get-started/support-matrix)
+
+## Next
+
+<Cards>
+  <Card title="Fallback decorator" href="/docs/decorators/fallback" />
+  <Card title="Retry decorator" href="/docs/decorators/retry" />
+</Cards>

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

@@ -8,6 +8,8 @@ source: "README.md"
 Configure sently features around your delivery workflow.
 
 <Cards>
+  <Card title="Compare" href="/docs/guides/compare" />
+  <Card title="Failover" href="/docs/guides/failover" />
   <Card title="Adapters" href="/docs/guides/adapters" />
   <Card title="Webhooks" href="/docs/guides/webhooks" />
   <Card title="Security" href="/docs/guides/security" />

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

@@ -3,6 +3,8 @@
   "icon": "Map",
   "pages": [
     "index",
+    "compare",
+    "failover",
     "adapters",
     "dkim",
     "oauth2",

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

@@ -1,17 +1,47 @@
 ---
 title: Security
-description: Protect credentials, delivery endpoints, and webhook integrity.
+description: Protect credentials, delivery endpoints, webhook integrity, and publish trust.
 icon: ShieldCheck
 source: "src/transports/webpush.ts"
 ---
 
-<Callout title="The one rule">Keep provider keys and VAPID private keys in a secrets manager or environment variables.</Callout>
+Provider API keys, VAPID private keys, and push endpoints are long-lived credentials.
+Keep them out of source control and out of unstructured logs.
 
-- Enable TLS for SMTP authentication; `requireTLS` defaults to true when auth is set.
-- Verify provider webhook signatures before parsing trusted events.
-- Do not log email bodies, SMS bodies, or full push subscription endpoints.
-- Treat a push endpoint as a delivery token.
+<Callout title="The one rule">
+  Keep provider keys and VAPID private keys in a secrets manager or environment variables.
+</Callout>
 
-<Accordions><Accordion title="Why is a push endpoint redacted in hooks?">Its path can contain a long-lived delivery token.</Accordion></Accordions>
+## Checklist
 
-<Cards><Card title="Webhooks" href="/docs/guides/webhooks" /></Cards>
+| Practice | Detail |
+| --- | --- |
+| SMTP TLS | `requireTLS` defaults to true when auth is set |
+| Webhooks | Verify signatures before trusting parsed events |
+| Logging | Do not log email/SMS bodies or full push endpoints |
+| Push | Treat subscription endpoints and FCM tokens as delivery tokens |
+| Reporting | Use private advisories — see root `SECURITY.md` |
+
+## Troubleshooting
+
+<Accordions>
+  <Accordion title="Why is a push endpoint redacted in hooks?">
+    Its path can contain a long-lived delivery token. Hook context keeps a short fingerprint.
+  </Accordion>
+  <Accordion title="Where do I report a vulnerability?">
+    Open a private GitHub Security Advisory for this repository. Do not file a public issue. Details and response targets are in [`SECURITY.md`](https://github.com/alialnaghmoush/sently/blob/main/SECURITY.md).
+  </Accordion>
+</Accordions>
+
+## Learn more
+
+- [Stability policy](/docs/get-started/stability)
+- [Webhooks](/docs/guides/webhooks)
+- [Web Push](/docs/transports/webpush)
+
+## Next
+
+<Cards>
+  <Card title="Webhooks" href="/docs/guides/webhooks" />
+  <Card title="Stability policy" href="/docs/get-started/stability" />
+</Cards>

package/site/content/docs/index.mdx

@@ -1,15 +1,89 @@
 ---
 title: sently handbook
-description: Channel-first messaging for email, SMS, WhatsApp, and push (Web Push / FCM).
+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/exports.mdx

@@ -37,7 +37,7 @@ The main `sently` package is for shared types and factories — not every provid
 
 | Import | Use |
 | ------ | --- |
-| `sently/transports/<name>` | One provider or decorator (e.g. `sndr`, `unifonic`, `fcm`, `retry`) |
+| `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`.
 
@@ -75,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/push-options.mdx

@@ -52,6 +52,20 @@ FCM stringifies non-string `data` values before send.
 
 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>

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

@@ -1,11 +1,12 @@
 ---
 title: FCM
-description: Send mobile push through Firebase Cloud Messaging HTTP v1.
+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 HTTP v1 for native Android and iOS clients.
+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>
@@ -29,15 +30,18 @@ const push = createPushSender({
 ```
 
   </Step>
-  <Step title="Send to a device token">
+  <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);
+console.log(result.messageId, result.status, result.provider);
 ```
 
   </Step>

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

@@ -56,6 +56,7 @@ Every import below is an exported package subpath.
 | [Plunk](./plunk) | Email | `sently/transports/plunk` |
 | [SparkPost](./sparkpost) | Email | `sently/transports/sparkpost` |
 | [Mailtrap](./mailtrap) | Email | `sently/transports/mailtrap` |
+| [Mailpit](./mailpit) | Email (dev) | `sently/transports/mailpit` |
 | [Loops](./loops) | Email | `sently/transports/loops` |
 | [Cloudflare Email](./cloudflare-email) | Email | `sently/transports/cloudflare-email` |
 | [SNDR](./sndr) | Email | `sently/transports/sndr` |
@@ -87,13 +88,18 @@ 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 any channel transport with a [decorator](../decorators), then pass the wrapper to the matching sender.
+    Wrap any channel transport with a [decorator](../decorators), then pass the wrapper to the matching sender. See also the [failover guide](../guides/failover).
+  </Accordion>
+  <Accordion title="Is every exported transport equally Supported?">
+    No. See the [support matrix](../get-started/support-matrix) for Supported vs Available.
   </Accordion>
 </Accordions>
 
 ## Learn more
 
+- [Support matrix](../get-started/support-matrix)
 - [Decorators](../decorators)
+- [Failover](../guides/failover)
 - [Email channel](../channels/email)
 - [SMS channel](../channels/sms)
 - [Transport contracts](../reference/transport-contracts)
@@ -101,7 +107,7 @@ For retry, fallback, preview, and idempotency wrappers, see [Decorators](../deco
 ## Next
 
 <Cards>
+  <Card title="Support matrix" href="/docs/get-started/support-matrix" />
   <Card title="Decorators" href="/docs/decorators" />
-  <Card title="Email channel" href="/docs/channels/email" />
-  <Card title="SMS channel" href="/docs/channels/sms" />
+  <Card title="Failover" href="/docs/guides/failover" />
 </Cards>