sently 0.10.0 → 1.0.0

package/AGENTS.md

@@ -1,6 +1,6 @@
 # sently — agent contract
 
-sently is a runtime-agnostic TypeScript messaging library (email, SMS, WhatsApp, Web Push, FCM) for Node.js, Bun, Deno, and Cloudflare Workers. ESM-only, zero runtime dependencies.
+sently is a runtime-agnostic TypeScript channel-delivery library (email, SMS, WhatsApp, Web Push, FCM) for Node.js, Bun, Deno, and Cloudflare Workers. ESM-only, zero runtime dependencies. One sender shape / error model / retry path as channels grow — not a hosted orchestration platform.
 
 ## Sently-first provider model
 

package/CHANGELOG.md

@@ -2,6 +2,46 @@
 
 ## [Unreleased]
 
+## [1.0.0] — 2026-08-01
+
+First stable release. Channel contracts and Supported transports are semver-frozen;
+npm publishes ship with provenance attestations and Trusted Publishing (OIDC).
+sently is the channel-delivery layer — preference centers, digests, workflows, and
+in-app inboxes sit on top (custom or Novu / Knock / Courier), not instead of it.
+
+### ✨ Added
+
+- **Stability policy** — what is frozen at 1.x vs allowed without a major
+  (`PushOptions` union, `providerIndex`, email-only preview / idempotency)
+- **Support matrix** — Supported vs Available transports and runtimes
+- **Non-goals** — library-not-platform boundaries (no preference centers /
+  digests / workflow builders inside sently)
+- **Security policy** — root `SECURITY.md` (private reporting, response targets,
+  supported versions for patches, Trusted Publisher setup notes)
+- **Compare guide** — positioning vs vendor SDK piles, Nodemailer, and
+  Novu / Knock / Courier
+- **Failover guide** — cross-channel retry-then-fallback recipes
+- **Mailpit transport** — `sently/transports/mailpit` for local email capture
+  (SMTP defaults `localhost:1025`, REST helpers for list / get / delete)
+
+### ♻️ Changed
+
+- **Messaging positioning** — homepage, README, `llms.txt`, and package
+  description/keywords lead with multi-channel scope creep (one sender / error /
+  retry model); bundle size as supporting evidence for edge / Workers; FCM
+  documented as current HTTP API support, not a feature boast
+- **Handbook landing** — install → send loop, channel map, where-next table,
+  and library-vs-platform troubleshooting
+- **Docs IA** — remove duplicate Quick start section; Channels is the first-send
+  path; cross-links for stability, support matrix, failover, and security
+- **Migrate from Nodemailer** — diff-style transporter and `sendMail` → `send`
+  swaps, field map, SMTP → HTTP follow-on, fuller options tables
+- **npm publish** — OIDC Trusted Publishing first, optional `NPM_TOKEN`
+  fallback; continues to use `npm publish --provenance` from CI (npm CLI ≥11.5.1
+  check in the publish workflow)
+- **Semver** — public channel factories, contracts, hooks, `SentlyError` codes,
+  `ChannelSendResult`, and published subpaths follow 1.x stability
+
 ## [0.10.0] — 2026-08-01
 
 ### ✨ Added
@@ -14,8 +54,8 @@
   WhatsApp / push senders wire `onRetry` / `onFallback` like email
 - **Unifonic SMS** — `sently/transports/unifonic` (`AppSid` + el.cloud REST
   send); webhook parser at `sently/webhooks/unifonic`
-- **FCM push** — `sently/transports/fcm` (HTTP v1 + service-account JWT, zero
-  Google SDK)
+- **FCM push** — `sently/transports/fcm` (current FCM HTTP API + service-account
+  JWT, no Google SDK)
 - **Non-email webhooks** — `DeliveryEvent` plus parsers for Twilio SMS and
   WhatsApp Cloud (`sently/webhooks/twilio-sms`, `whatsapp-cloud`);
   `toDeliveryEvent` maps `EmailEvent` into the shared shape; Twilio and

package/README.md

@@ -23,7 +23,7 @@
 </p>
 
 <p align="center">
-  <em>Stop wiring vendor SDKs into every channel. One sender shape for email, SMS, WhatsApp, and push — swap the transport, keep your call sites. Node, Bun, Deno, Workers.</em>
+  <em>Start with email, add SMS and push later — one sender shape, one error model, one retry path. Swap the transport; keep your call sites. Node, Bun, Deno, Workers.</em>
 </p>
 
 <p align="center">
@@ -33,11 +33,6 @@
   <a href="https://www.npmjs.com/package/sently"><code>sently</code></a>
 </p>
 
-> [!WARNING]
-> **Early development (`v0.x`) — API may change.**
->
-> Pin an exact version for production until v1.0.0. See [CHANGELOG](CHANGELOG.md).
-
 ## Install
 
 ```bash
@@ -78,18 +73,24 @@ Full walkthrough: [Get started](https://sently.omqkhafi.dev/docs/get-started).
 
 ## Why sently?
 
-Nodemailer is Node.js–only and ships the full mail stack on every import (~59 KB gzip for [v9.0.3](https://bundlephobia.com/package/nodemailer@9.0.3)). sently is tree-shakeable, multi-runtime, and multi-channel.
+Teams usually start on one channel (often email), then add SMS and push. Each vendor SDK brings its own auth, retries, and error shapes. sently keeps **one sender shape**, **one `SentlyError` model**, and **one retry/fallback path** as you add channels.
+
+**Library, not platform.** sently is the channel-delivery layer. Preference centers, digests, workflow builders, and in-app inboxes — custom logic or tools like [Novu](https://novu.co), [Knock](https://knock.app), or [Courier](https://www.courier.com) — sit **on top of** sently, not instead of it.
+
+Compared with email-only stacks (e.g. Nodemailer) and a pile of vendor clients:
+
+|                   | Typical stack                         | sently                                      |
+| ----------------- | ------------------------------------- | ------------------------------------------- |
+| As channels grow  | New SDK per channel                   | Same sender factories                       |
+| Failures          | Per-vendor exceptions                 | Stable `SentlyError` codes                  |
+| Reliability       | Ad-hoc per client                     | `RetryTransport` + `FallbackTransport`      |
+| Providers         | Vendor clients in app code            | Pluggable transports                        |
+| Runtimes          | Often Node only                       | Node, Bun, Deno, CF Workers                 |
+| Edge / Workers    | Fat SDKs hurt cold start              | Tree-shakeable (~6.3 KB HTTP · ~14.9 KB SMTP) |
+| Module format     | Often CJS                             | ESM only                                    |
+| Dependencies      | Varies                                | 0 runtime deps                              |
 
-|                   | Nodemailer              | sently                                      |
-| ----------------- | ----------------------- | ------------------------------------------- |
-| Bundle size       | ~59 KB gzip always      | ~6.3 KB HTTP · ~14.9 KB SMTP                |
-| Runtimes          | Node.js only            | Node, Bun, Deno, CF Workers                 |
-| Module format     | CommonJS                | ESM only                                    |
-| Dependencies      | 0                       | 0                                           |
-| Channels          | Email                   | Email · SMS · WhatsApp · Push               |
-| HTTP transports   | via plugins             | built-in subpaths                           |
-| Provider failover | —                       | `FallbackTransport` + weighted routing      |
-| TypeScript        | `@types/nodemailer`     | built-in                                    |
+More detail: [Compare](https://sently.omqkhafi.dev/docs/guides/compare) · [Stability](https://sently.omqkhafi.dev/docs/get-started/stability) · [Support matrix](https://sently.omqkhafi.dev/docs/get-started/support-matrix).
 
 ## Entrypoints
 
@@ -113,10 +114,12 @@ Nodemailer is Node.js–only and ships the full mail stack on every import (~59
 | Get started  | [/docs/get-started](https://sently.omqkhafi.dev/docs/get-started)     |
 | Channels     | [/docs/channels](https://sently.omqkhafi.dev/docs/channels)           |
 | Transports   | [/docs/transports](https://sently.omqkhafi.dev/docs/transports)       |
+| Compare      | [/docs/guides/compare](https://sently.omqkhafi.dev/docs/guides/compare) |
 | Agents index | [/llms.txt](https://sently.omqkhafi.dev/llms.txt)                     |
 | Changelog    | [`CHANGELOG.md`](CHANGELOG.md)                               |
+| Security     | [`SECURITY.md`](SECURITY.md)                                 |
 | Agents       | [`AGENTS.md`](AGENTS.md)                                     |
 
 Local docs: `bun run site:dev`. Verify: `bun run verify`.
 
-Pre-1.0. Published on [npm](https://www.npmjs.com/package/sently) and [JSR](https://jsr.io/@alialnaghmoush/sently). MIT.
+**1.0.0** — semver-stable channel contracts. Published on [npm](https://www.npmjs.com/package/sently) (provenance + Trusted Publishing) and [JSR](https://jsr.io/@alialnaghmoush/sently). MIT.

package/SECURITY.md

@@ -0,0 +1,59 @@
+# Security Policy
+
+sently is a messaging library that holds provider API keys and tokens in the installing application at runtime. Treat compromised publishes and credential leaks as high severity.
+
+## Reporting a vulnerability
+
+**Do not open a public GitHub issue for security reports.**
+
+Use [GitHub Security Advisories](https://github.com/alialnaghmoush/sently/security/advisories/new) for this repository so the report stays private until a fix is ready.
+
+Include:
+
+- Affected package version(s)
+- Impact (credential exfiltration, unauthorized send, SSRF, signature bypass, …)
+- Reproduction steps or a minimal proof of concept when possible
+
+## Response targets
+
+| Stage | Target |
+| --- | --- |
+| Initial acknowledgement | Within **72 hours** |
+| Triage (severity / severity) | Within **7 days** of acknowledgement |
+| Fix or mitigation guidance | As soon as practical; critical issues are prioritized over feature work |
+
+These are goals, not SLAs. Complex issues may take longer; we will keep the reporter updated.
+
+## Supported versions (security patches)
+
+After **1.0.0**, security fixes land on the current **1.x** line (latest minor/patch). See the [stability policy](https://sently.omqkhafi.dev/docs/get-started/stability) for what is semver-frozen.
+
+| Version | Security patches |
+| --- | --- |
+| `1.x` | Yes |
+| `0.x` | Best effort only (pre-1.0; prefer upgrading to 1.x) |
+
+## Release integrity
+
+npm publishes from CI (`.github/workflows/publish.yml`) use:
+
+- **`npm publish --provenance`** — attestations linking the tarball to this public repository and the build
+- **Trusted Publishing (OIDC)** — preferred path so a long-lived `NPM_TOKEN` is not required
+
+### One-time setup (package owner)
+
+On [npmjs.com/package/sently](https://www.npmjs.com/package/sently) → **Settings** → **Trusted Publisher**:
+
+1. Bind **GitHub Actions**
+2. Repository: `alialnaghmoush/sently`
+3. Workflow: `publish.yml` (`.github/workflows/publish.yml`)
+4. Environment: `production` (must match the workflow `environment`)
+5. Confirm the npm package repository URL matches `package.json` → `repository`
+
+Until one OIDC publish has succeeded, CI may fall back to a repository secret `NPM_TOKEN` / `NODE_AUTH_TOKEN` if present. Remove that secret after OIDC is verified.
+
+## Related hardening in the library
+
+- Web Push endpoint allowlisting / SSRF checks
+- Redaction of push endpoints and FCM tokens in hooks
+- Webhook signature verification helpers for Supported providers

package/dist/chunk-z1589fjk.js.map

@@ -2,7 +2,7 @@
   "version": 3,
   "sources": ["../src/core/push-types.ts"],
   "sourcesContent": [
-    "/**\n * @module\n * Shared push channel contracts — sibling types to email MailOptions/Transport/Hooks.\n *\n * Sently-first: this contract is the stable push surface. Provider transports\n * implement {@link PushTransport}. Web Push uses a browser subscription; FCM\n * uses a device registration token.\n */\nimport type { VerifyResult } from \"./types.js\";\n\n/** Browser push subscription as returned by the Push API. */\nexport interface PushSubscription {\n  /** Push service endpoint URL. */\n  endpoint: string;\n  /** Client encryption keys for RFC 8291 payload encryption. */\n  keys: {\n    /** Base64url-encoded P-256 ECDH public key. */\n    p256dh: string;\n    /** Base64url-encoded authentication secret. */\n    auth: string;\n  };\n}\n\n/** Shared notification fields for Web Push and FCM. */\ninterface PushNotificationFields {\n  /** Notification title. */\n  title: string;\n  /** Notification body text. */\n  body: string;\n  /** Arbitrary application data attached to the notification. */\n  data?: Record<string, unknown>;\n  /** Notification icon URL (Web Push / some FCM platforms). */\n  icon?: string;\n  /** Time-to-live in seconds for the push message. */\n  ttl?: number;\n  /** Client-supplied message identifier when known. */\n  messageId?: string;\n}\n\n/** Options for sending a Web Push notification (VAPID / browser subscription). */\nexport interface WebPushOptions extends PushNotificationFields {\n  /** Target browser push subscription. */\n  subscription: PushSubscription;\n}\n\n/**\n * Options for sending via Firebase Cloud Messaging HTTP v1 (device token).\n * Data values are stringified by the FCM transport when needed.\n */\nexport interface FcmPushOptions extends PushNotificationFields {\n  /** FCM registration token for the target device. */\n  token: string;\n  /** Optional image URL for the notification. */\n  image?: string;\n}\n\n/** Options for sending a push notification (Web Push or FCM). */\nexport type PushOptions = WebPushOptions | FcmPushOptions;\n\n/** True when options target FCM (device token) rather than Web Push. */\nexport function isFcmPushOptions(options: PushOptions): options is FcmPushOptions {\n  return \"token\" in options && typeof (options as FcmPushOptions).token === \"string\";\n}\n\n/** True when options target Web Push (browser subscription). */\nexport function isWebPushOptions(options: PushOptions): options is WebPushOptions {\n  return (\n    \"subscription\" in options &&\n    typeof (options as WebPushOptions).subscription?.endpoint === \"string\"\n  );\n}\n\n/** Result returned after a push notification is accepted by the push service. */\nexport interface PushSendResult {\n  /** Client-generated or assigned message identifier. */\n  messageId: string;\n  /** Delivery status string (e.g. `\"accepted\"`). */\n  status: string;\n  /** Human-readable or raw status text (often the HTTP status). */\n  response: string;\n  /** Transport or provider identifier (e.g. `\"webpush\"`, `\"fcm\"`). */\n  provider?: string;\n  /**\n   * Zero-based index of the transport that handled the send in a fallback chain.\n   * Set by {@link FallbackTransport}.\n   */\n  providerIndex?: number;\n}\n\n/** Pluggable push delivery backend (Web Push, FCM, …). */\nexport interface PushTransport {\n  /**\n   * Stable provider identifier for observability (e.g. `\"webpush\"`, `\"fcm\"`).\n   * Prefer this over constructor-name inference in hooks.\n   */\n  readonly provider?: string;\n  /** Send a push notification through this transport. */\n  send(options: PushOptions): Promise<PushSendResult>;\n  /** Test connectivity and credentials without sending. */\n  verify?(): Promise<VerifyResult>;\n  /** Release resources held by the transport. */\n  close?(): Promise<void>;\n}\n\n/**\n * Context passed to push lifecycle hooks.\n * Uses a redacted subscription endpoint or device-token fingerprint (no natural `to`).\n */\nexport interface PushHookContext {\n  /** Message-ID when known (from options or send result). */\n  messageId?: string;\n  /**\n   * Redacted push target for observability: `origin/#<short-hash>` (Web Push)\n   * or `fcm:#<short-hash>` (FCM device token).\n   * Never the full endpoint URL or raw device token.\n   */\n  endpoint: string;\n  /** Transport or provider identifier (e.g. `\"webpush\"`, `\"fcm\"`). */\n  provider: string;\n}\n\n/** Optional lifecycle hooks for metrics, tracing, and observability on every push send. */\nexport interface PushHooks {\n  /** Fired before the transport sends the notification. */\n  onSend?: (ctx: PushHookContext) => void | Promise<void>;\n  /**\n   * Fired after a successful send.\n   * @param durationMs — elapsed milliseconds from send start to success (optional third argument).\n   */\n  onSuccess?: (\n    ctx: PushHookContext,\n    result: PushSendResult,\n    durationMs?: number,\n  ) => void | Promise<void>;\n  /**\n   * Fired when a send throws (error is re-thrown after the hook runs).\n   * @param durationMs — elapsed milliseconds from send start to failure (optional third argument).\n   */\n  onError?: (ctx: PushHookContext, error: unknown, durationMs?: number) => void | Promise<void>;\n  /** Fired before each retry attempt (requires {@link RetryTransport}). */\n  onRetry?: (ctx: PushHookContext, attempt: number, error: unknown) => void | Promise<void>;\n  /**\n   * Fired when {@link FallbackTransport} fails over to the next provider.\n   * Requires a fallback (or weighted fallback) transport in the push stack.\n   */\n  onFallback?: (\n    ctx: PushHookContext,\n    failedProvider: string,\n    nextProvider: string,\n    error: unknown,\n  ) => void | Promise<void>;\n}\n\n/**\n * A push plugin transforms {@link PushOptions} before the transport sends.\n * Plugins run sequentially. Each receives the output of the previous.\n * Return a new options object — do not mutate the input.\n */\nexport type PushPlugin =\n  | ((options: PushOptions) => PushOptions)\n  | ((options: PushOptions) => Promise<PushOptions>);\n"
+    "/**\n * @module\n * Shared push channel contracts — sibling types to email MailOptions/Transport/Hooks.\n *\n * Sently-first: this contract is the stable push surface. Provider transports\n * implement {@link PushTransport}. Web Push uses a browser subscription; FCM\n * uses a device registration token.\n */\nimport type { VerifyResult } from \"./types.js\";\n\n/** Browser push subscription as returned by the Push API. */\nexport interface PushSubscription {\n  /** Push service endpoint URL. */\n  endpoint: string;\n  /** Client encryption keys for RFC 8291 payload encryption. */\n  keys: {\n    /** Base64url-encoded P-256 ECDH public key. */\n    p256dh: string;\n    /** Base64url-encoded authentication secret. */\n    auth: string;\n  };\n}\n\n/** Shared notification fields for Web Push and FCM. */\ninterface PushNotificationFields {\n  /** Notification title. */\n  title: string;\n  /** Notification body text. */\n  body: string;\n  /** Arbitrary application data attached to the notification. */\n  data?: Record<string, unknown>;\n  /** Notification icon URL (Web Push / some FCM platforms). */\n  icon?: string;\n  /** Time-to-live in seconds for the push message. */\n  ttl?: number;\n  /** Client-supplied message identifier when known. */\n  messageId?: string;\n}\n\n/** Options for sending a Web Push notification (VAPID / browser subscription). */\nexport interface WebPushOptions extends PushNotificationFields {\n  /** Target browser push subscription. */\n  subscription: PushSubscription;\n}\n\n/**\n * Options for sending via Firebase Cloud Messaging (device token).\n * Data values are stringified by the FCM transport when needed.\n */\nexport interface FcmPushOptions extends PushNotificationFields {\n  /** FCM registration token for the target device. */\n  token: string;\n  /** Optional image URL for the notification. */\n  image?: string;\n}\n\n/** Options for sending a push notification (Web Push or FCM). */\nexport type PushOptions = WebPushOptions | FcmPushOptions;\n\n/** True when options target FCM (device token) rather than Web Push. */\nexport function isFcmPushOptions(options: PushOptions): options is FcmPushOptions {\n  return \"token\" in options && typeof (options as FcmPushOptions).token === \"string\";\n}\n\n/** True when options target Web Push (browser subscription). */\nexport function isWebPushOptions(options: PushOptions): options is WebPushOptions {\n  return (\n    \"subscription\" in options &&\n    typeof (options as WebPushOptions).subscription?.endpoint === \"string\"\n  );\n}\n\n/** Result returned after a push notification is accepted by the push service. */\nexport interface PushSendResult {\n  /** Client-generated or assigned message identifier. */\n  messageId: string;\n  /** Delivery status string (e.g. `\"accepted\"`). */\n  status: string;\n  /** Human-readable or raw status text (often the HTTP status). */\n  response: string;\n  /** Transport or provider identifier (e.g. `\"webpush\"`, `\"fcm\"`). */\n  provider?: string;\n  /**\n   * Zero-based index of the transport that handled the send in a fallback chain.\n   * Set by {@link FallbackTransport}.\n   */\n  providerIndex?: number;\n}\n\n/** Pluggable push delivery backend (Web Push, FCM, …). */\nexport interface PushTransport {\n  /**\n   * Stable provider identifier for observability (e.g. `\"webpush\"`, `\"fcm\"`).\n   * Prefer this over constructor-name inference in hooks.\n   */\n  readonly provider?: string;\n  /** Send a push notification through this transport. */\n  send(options: PushOptions): Promise<PushSendResult>;\n  /** Test connectivity and credentials without sending. */\n  verify?(): Promise<VerifyResult>;\n  /** Release resources held by the transport. */\n  close?(): Promise<void>;\n}\n\n/**\n * Context passed to push lifecycle hooks.\n * Uses a redacted subscription endpoint or device-token fingerprint (no natural `to`).\n */\nexport interface PushHookContext {\n  /** Message-ID when known (from options or send result). */\n  messageId?: string;\n  /**\n   * Redacted push target for observability: `origin/#<short-hash>` (Web Push)\n   * or `fcm:#<short-hash>` (FCM device token).\n   * Never the full endpoint URL or raw device token.\n   */\n  endpoint: string;\n  /** Transport or provider identifier (e.g. `\"webpush\"`, `\"fcm\"`). */\n  provider: string;\n}\n\n/** Optional lifecycle hooks for metrics, tracing, and observability on every push send. */\nexport interface PushHooks {\n  /** Fired before the transport sends the notification. */\n  onSend?: (ctx: PushHookContext) => void | Promise<void>;\n  /**\n   * Fired after a successful send.\n   * @param durationMs — elapsed milliseconds from send start to success (optional third argument).\n   */\n  onSuccess?: (\n    ctx: PushHookContext,\n    result: PushSendResult,\n    durationMs?: number,\n  ) => void | Promise<void>;\n  /**\n   * Fired when a send throws (error is re-thrown after the hook runs).\n   * @param durationMs — elapsed milliseconds from send start to failure (optional third argument).\n   */\n  onError?: (ctx: PushHookContext, error: unknown, durationMs?: number) => void | Promise<void>;\n  /** Fired before each retry attempt (requires {@link RetryTransport}). */\n  onRetry?: (ctx: PushHookContext, attempt: number, error: unknown) => void | Promise<void>;\n  /**\n   * Fired when {@link FallbackTransport} fails over to the next provider.\n   * Requires a fallback (or weighted fallback) transport in the push stack.\n   */\n  onFallback?: (\n    ctx: PushHookContext,\n    failedProvider: string,\n    nextProvider: string,\n    error: unknown,\n  ) => void | Promise<void>;\n}\n\n/**\n * A push plugin transforms {@link PushOptions} before the transport sends.\n * Plugins run sequentially. Each receives the output of the previous.\n * Return a new options object — do not mutate the input.\n */\nexport type PushPlugin =\n  | ((options: PushOptions) => PushOptions)\n  | ((options: PushOptions) => Promise<PushOptions>);\n"
   ],
   "mappings": "AA4DO,SAAS,CAAgB,CAAC,EAAiD,CAChF,MAAO,UAAW,GAAW,OAAQ,EAA2B,QAAU,SAIrE,SAAS,CAAgB,CAAC,EAAiD,CAChF,MACE,iBAAkB,GAClB,OAAQ,EAA2B,cAAc,WAAa",
   "debugId": "F4A2DC6CC43BC46D64756E2164756E21",

package/dist/core/push-types.d.ts

@@ -40,7 +40,7 @@ export interface WebPushOptions extends PushNotificationFields {
     subscription: PushSubscription;
 }
 /**
- * Options for sending via Firebase Cloud Messaging HTTP v1 (device token).
+ * Options for sending via Firebase Cloud Messaging (device token).
  * Data values are stringified by the FCM transport when needed.
  */
 export interface FcmPushOptions extends PushNotificationFields {

package/dist/transports/mailpit.d.ts

@@ -0,0 +1,166 @@
+import { SentlyError } from "../core/errors.js";
+import type { MailOptions, SendResult, SMTPAuth, SocketAdapter, TLSOptions, Transport, VerifyResult } from "../core/types.js";
+/** Default SMTP host for a local Mailpit instance. */
+export declare const MAILPIT_DEFAULT_HOST = "localhost";
+/** Default SMTP port for a local Mailpit instance. */
+export declare const MAILPIT_DEFAULT_PORT = 1025;
+/** Default web UI / REST API base URL for a local Mailpit instance. */
+export declare const MAILPIT_DEFAULT_API_URL = "http://localhost:8025";
+/** Mailpit development transport configuration. */
+export interface MailpitConfig {
+    /** SMTP hostname. Default: `"localhost"`. */
+    host?: string;
+    /** SMTP port. Default: `1025`. */
+    port?: number;
+    /** Use implicit TLS on connect. Default: `false` (Mailpit is plain SMTP). */
+    secure?: boolean;
+    /**
+     * Refuse AUTH over a non-TLS connection.
+     * Default: `false` so optional local SMTP auth works without TLS.
+     */
+    requireTLS?: boolean;
+    /** Optional SMTP authentication (Mailpit can accept any credentials). */
+    auth?: SMTPAuth;
+    /** TLS options when STARTTLS or implicit TLS is enabled. */
+    tls?: TLSOptions;
+    /** Socket connect timeout in milliseconds. */
+    connectionTimeout?: number;
+    /** Runtime socket adapter. Auto-detected on first send when omitted. */
+    adapter?: SocketAdapter;
+    /**
+     * Mailpit web UI / REST API base URL (no trailing slash).
+     * Default: `"http://localhost:8025"`.
+     */
+    apiUrl?: string;
+    /** Basic auth for the Mailpit UI/API when the instance requires it. */
+    apiAuth?: {
+        user: string;
+        pass: string;
+    };
+}
+/** Address object returned by the Mailpit REST API. */
+export interface MailpitAddress {
+    /** Display name, may be empty. */
+    Name: string;
+    /** Email address. */
+    Address: string;
+}
+/** Summary row from `GET /api/v1/messages`. */
+export interface MailpitMessageSummary {
+    /** Mailpit message id. */
+    ID: string;
+    /** MIME Message-ID. */
+    MessageID: string;
+    /** Sender. */
+    From: MailpitAddress;
+    /** Recipients. */
+    To: MailpitAddress[];
+    /** Subject line. */
+    Subject: string;
+    /** ISO created timestamp. */
+    Created: string;
+    /** Attachment count. */
+    Attachments: number;
+    /** Whether the message has been read in the UI. */
+    Read: boolean;
+    /** Short plain-text snippet. */
+    Snippet: string;
+}
+/** Response from `GET /api/v1/messages`. */
+export interface MailpitMessageList {
+    /** Total messages stored. */
+    total: number;
+    /** Unread message count. */
+    unread: number;
+    /** Messages returned in this page. */
+    count: number;
+    /** Message summaries (newest first). */
+    messages: MailpitMessageSummary[];
+}
+/** Full message from `GET /api/v1/message/{id}`. */
+export interface MailpitMessage {
+    /** Mailpit message id. */
+    ID: string;
+    /** MIME Message-ID. */
+    MessageID: string;
+    /** Sender. */
+    From: MailpitAddress;
+    /** Recipients. */
+    To: MailpitAddress[];
+    /** CC recipients. */
+    Cc?: MailpitAddress[];
+    /** BCC recipients. */
+    Bcc?: MailpitAddress[];
+    /** Subject line. */
+    Subject: string;
+    /** Plain-text body. */
+    Text: string;
+    /** HTML body. */
+    HTML: string;
+    /** ISO created timestamp. */
+    Date: string;
+    /** Attachment count. */
+    Attachments: number;
+}
+/** Options for {@link MailpitTransport.messages}. */
+export interface MailpitMessagesOptions {
+    /** Max messages to return. */
+    limit?: number;
+    /** Pagination offset. */
+    start?: number;
+}
+/** Error thrown when the Mailpit REST API returns a non-success response. */
+export declare class MailpitError extends SentlyError {
+    readonly statusCode: number;
+    readonly apiError: unknown;
+    /** Creates a Mailpit API error with status code (`0` = network/connect failure). */
+    constructor(message: string, statusCode: number, apiError: unknown);
+}
+/**
+ * Development transport for [Mailpit](https://github.com/axllent/mailpit).
+ *
+ * Sends via SMTP (defaults: `localhost:1025`) and exposes REST helpers for
+ * listing, reading, and deleting captured messages.
+ */
+export declare class MailpitTransport implements Transport {
+    readonly provider = "mailpit";
+    private readonly host;
+    private readonly port;
+    private readonly secure;
+    private readonly requireTLS;
+    private readonly auth?;
+    private readonly tls?;
+    private readonly connectionTimeout?;
+    private readonly adapter?;
+    private readonly apiUrl;
+    private readonly apiAuth?;
+    private smtp;
+    /** Creates a Mailpit transport with local-dev defaults. */
+    constructor(config?: MailpitConfig);
+    /** Web UI base URL (same origin as the REST API). */
+    get webUrl(): string;
+    /** Sends an email to Mailpit over SMTP. */
+    send(options: MailOptions): Promise<SendResult>;
+    /** Verifies SMTP connectivity to Mailpit. */
+    verify(): Promise<VerifyResult>;
+    /** Closes the underlying SMTP adapter if connected. */
+    close(): Promise<void>;
+    /**
+     * Lists captured messages via `GET /api/v1/messages`.
+     * Newest messages appear first.
+     */
+    messages(options?: MailpitMessagesOptions): Promise<MailpitMessageList>;
+    /** Fetches a full message via `GET /api/v1/message/{id}`. */
+    getMessage(id: string): Promise<MailpitMessage>;
+    /**
+     * Deletes messages by id via `DELETE /api/v1/messages`.
+     * Pass an empty array (or call {@link deleteAll}) to clear the inbox.
+     */
+    deleteMessages(ids: string[]): Promise<void>;
+    /** Deletes every captured message. */
+    deleteAll(): Promise<void>;
+    private getSmtp;
+    private apiHeaders;
+    private apiGet;
+    private apiDelete;
+}

package/dist/transports/mailpit.js

@@ -0,0 +1,3 @@
+import{n as X}from"../chunk-a057jzsy.js";import"../chunk-f5x8vesr.js";import"../chunk-yg3kj723.js";import"../chunk-w4c9kj70.js";import"../chunk-1ke3nmyg.js";import{M as N}from"../chunk-d5aw5vag.js";import"../chunk-8kpgbrba.js";import{da as Q}from"../chunk-hnzmn4s4.js";import{ja as V,ka as W}from"../chunk-ttbwyxmh.js";import"../chunk-th4cwrpb.js";var Y="localhost",Z=1025,$="http://localhost:8025";class K extends V{statusCode;apiError;constructor(w,z,G){super(w,z===0?"CONNECTION_FAILED":W(z),{...z>0?{statusCode:z}:{},provider:"mailpit",cause:G});this.statusCode=z;this.apiError=G;this.name="MailpitError"}}class k{provider="mailpit";host;port;secure;requireTLS;auth;tls;connectionTimeout;adapter;apiUrl;apiAuth;smtp=null;constructor(w={}){if(this.host=w.host??Y,this.port=w.port??Z,this.secure=w.secure??!1,this.requireTLS=w.requireTLS??!1,w.auth!==void 0)this.auth=w.auth;if(w.tls!==void 0)this.tls=w.tls;if(w.connectionTimeout!==void 0)this.connectionTimeout=w.connectionTimeout;if(w.adapter!==void 0)this.adapter=w.adapter;if(this.apiUrl=(w.apiUrl??$).replace(/\/$/,""),w.apiAuth!==void 0)this.apiAuth=w.apiAuth}get webUrl(){return this.apiUrl}async send(w){return(await this.getSmtp()).send(w)}async verify(){return{...await(await this.getSmtp()).verify(),provider:"mailpit"}}async close(){if(this.smtp)await this.smtp.close()}async messages(w={}){let z=new URLSearchParams;if(w.limit!==void 0)z.set("limit",String(w.limit));if(w.start!==void 0)z.set("start",String(w.start));let G=z.toString(),J=G?`/api/v1/messages?${G}`:"/api/v1/messages";return this.apiGet(J)}async getMessage(w){if(!w)throw new K("Message id is required",400,{code:"INVALID_CONFIG"});return this.apiGet(`/api/v1/message/${encodeURIComponent(w)}`)}async deleteMessages(w){await this.apiDelete("/api/v1/messages",{IDs:w})}async deleteAll(){await this.deleteMessages([])}async getSmtp(){if(!this.smtp){let w=this.adapter??await N({secure:this.secure,...this.connectionTimeout!==void 0?{connectionTimeout:this.connectionTimeout}:{},...this.tls!==void 0?{tls:this.tls}:{}});this.smtp=new X({host:this.host,port:this.port,secure:this.secure,requireTLS:this.requireTLS,adapter:w,...this.auth!==void 0?{auth:this.auth}:{},...this.tls!==void 0?{tls:this.tls}:{},...this.connectionTimeout!==void 0?{connectionTimeout:this.connectionTimeout}:{}})}return this.smtp}apiHeaders(){let w={Accept:"application/json","Content-Type":"application/json"};if(this.apiAuth){let z=Q(`${this.apiAuth.user}:${this.apiAuth.pass}`).replace(/\r\n/g,"");w.Authorization=`Basic ${z}`}return w}async apiGet(w){let z;try{z=await fetch(`${this.apiUrl}${w}`,{method:"GET",headers:this.apiHeaders()})}catch(G){throw new K(G instanceof Error?G.message:"Mailpit API request failed",0,G)}if(!z.ok){let G=await z.text().catch(()=>"");throw new K(G||`Mailpit API error (${z.status})`,z.status,G)}return await z.json()}async apiDelete(w,z){let G;try{G=await fetch(`${this.apiUrl}${w}`,{method:"DELETE",headers:this.apiHeaders(),body:JSON.stringify(z)})}catch(J){throw new K(J instanceof Error?J.message:"Mailpit API request failed",0,J)}if(!G.ok){let J=await G.text().catch(()=>"");throw new K(J||`Mailpit API error (${G.status})`,G.status,J)}}}export{k as MailpitTransport,K as MailpitError,Z as MAILPIT_DEFAULT_PORT,Y as MAILPIT_DEFAULT_HOST,$ as MAILPIT_DEFAULT_API_URL};
+
+//# debugId=A41842358B8E380464756E2164756E21

package/dist/transports/mailpit.js.map

@@ -0,0 +1,10 @@
+{
+  "version": 3,
+  "sources": ["../src/transports/mailpit.ts"],
+  "sourcesContent": [
+    "/**\n * @module\n * Mailpit development transport — SMTP to a local Mailpit catcher with\n * REST helpers for inspecting and clearing captured messages.\n *\n * Defaults match a stock Mailpit install: SMTP `localhost:1025`,\n * UI/API `http://localhost:8025`.\n *\n * @example\n * ```ts\n * import { createMailer } from \"sently/mailer\";\n * import { MailpitTransport } from \"sently/transports/mailpit\";\n *\n * const mailpit = new MailpitTransport();\n * const mailer = await createMailer({ transport: mailpit });\n *\n * await mailer.send({\n *   from: \"dev@example.com\",\n *   to: \"you@example.com\",\n *   subject: \"Hello\",\n *   text: \"Captured by Mailpit\",\n * });\n *\n * const inbox = await mailpit.messages();\n * console.log(inbox.messages[0]?.Subject);\n * ```\n */\nimport { encodeBase64 } from \"../core/base64.js\";\nimport { httpStatusToSentlyCode, SentlyError } from \"../core/errors.js\";\nimport type {\n  MailOptions,\n  SendResult,\n  SMTPAuth,\n  SocketAdapter,\n  TLSOptions,\n  Transport,\n  VerifyResult,\n} from \"../core/types.js\";\nimport { createDefaultAdapter } from \"../detect.js\";\nimport { SMTPTransport } from \"./smtp.js\";\n\n/** Default SMTP host for a local Mailpit instance. */\nexport const MAILPIT_DEFAULT_HOST = \"localhost\";\n\n/** Default SMTP port for a local Mailpit instance. */\nexport const MAILPIT_DEFAULT_PORT = 1025;\n\n/** Default web UI / REST API base URL for a local Mailpit instance. */\nexport const MAILPIT_DEFAULT_API_URL = \"http://localhost:8025\";\n\n/** Mailpit development transport configuration. */\nexport interface MailpitConfig {\n  /** SMTP hostname. Default: `\"localhost\"`. */\n  host?: string;\n  /** SMTP port. Default: `1025`. */\n  port?: number;\n  /** Use implicit TLS on connect. Default: `false` (Mailpit is plain SMTP). */\n  secure?: boolean;\n  /**\n   * Refuse AUTH over a non-TLS connection.\n   * Default: `false` so optional local SMTP auth works without TLS.\n   */\n  requireTLS?: boolean;\n  /** Optional SMTP authentication (Mailpit can accept any credentials). */\n  auth?: SMTPAuth;\n  /** TLS options when STARTTLS or implicit TLS is enabled. */\n  tls?: TLSOptions;\n  /** Socket connect timeout in milliseconds. */\n  connectionTimeout?: number;\n  /** Runtime socket adapter. Auto-detected on first send when omitted. */\n  adapter?: SocketAdapter;\n  /**\n   * Mailpit web UI / REST API base URL (no trailing slash).\n   * Default: `\"http://localhost:8025\"`.\n   */\n  apiUrl?: string;\n  /** Basic auth for the Mailpit UI/API when the instance requires it. */\n  apiAuth?: { user: string; pass: string };\n}\n\n/** Address object returned by the Mailpit REST API. */\nexport interface MailpitAddress {\n  /** Display name, may be empty. */\n  Name: string;\n  /** Email address. */\n  Address: string;\n}\n\n/** Summary row from `GET /api/v1/messages`. */\nexport interface MailpitMessageSummary {\n  /** Mailpit message id. */\n  ID: string;\n  /** MIME Message-ID. */\n  MessageID: string;\n  /** Sender. */\n  From: MailpitAddress;\n  /** Recipients. */\n  To: MailpitAddress[];\n  /** Subject line. */\n  Subject: string;\n  /** ISO created timestamp. */\n  Created: string;\n  /** Attachment count. */\n  Attachments: number;\n  /** Whether the message has been read in the UI. */\n  Read: boolean;\n  /** Short plain-text snippet. */\n  Snippet: string;\n}\n\n/** Response from `GET /api/v1/messages`. */\nexport interface MailpitMessageList {\n  /** Total messages stored. */\n  total: number;\n  /** Unread message count. */\n  unread: number;\n  /** Messages returned in this page. */\n  count: number;\n  /** Message summaries (newest first). */\n  messages: MailpitMessageSummary[];\n}\n\n/** Full message from `GET /api/v1/message/{id}`. */\nexport interface MailpitMessage {\n  /** Mailpit message id. */\n  ID: string;\n  /** MIME Message-ID. */\n  MessageID: string;\n  /** Sender. */\n  From: MailpitAddress;\n  /** Recipients. */\n  To: MailpitAddress[];\n  /** CC recipients. */\n  Cc?: MailpitAddress[];\n  /** BCC recipients. */\n  Bcc?: MailpitAddress[];\n  /** Subject line. */\n  Subject: string;\n  /** Plain-text body. */\n  Text: string;\n  /** HTML body. */\n  HTML: string;\n  /** ISO created timestamp. */\n  Date: string;\n  /** Attachment count. */\n  Attachments: number;\n}\n\n/** Options for {@link MailpitTransport.messages}. */\nexport interface MailpitMessagesOptions {\n  /** Max messages to return. */\n  limit?: number;\n  /** Pagination offset. */\n  start?: number;\n}\n\n/** Error thrown when the Mailpit REST API returns a non-success response. */\nexport class MailpitError extends SentlyError {\n  /** Creates a Mailpit API error with status code (`0` = network/connect failure). */\n  constructor(\n    message: string,\n    public readonly statusCode: number,\n    public readonly apiError: unknown,\n  ) {\n    super(message, statusCode === 0 ? \"CONNECTION_FAILED\" : httpStatusToSentlyCode(statusCode), {\n      ...(statusCode > 0 ? { statusCode } : {}),\n      provider: \"mailpit\",\n      cause: apiError,\n    });\n    this.name = \"MailpitError\";\n  }\n}\n\n/**\n * Development transport for [Mailpit](https://github.com/axllent/mailpit).\n *\n * Sends via SMTP (defaults: `localhost:1025`) and exposes REST helpers for\n * listing, reading, and deleting captured messages.\n */\nexport class MailpitTransport implements Transport {\n  readonly provider = \"mailpit\";\n\n  private readonly host: string;\n  private readonly port: number;\n  private readonly secure: boolean;\n  private readonly requireTLS: boolean;\n  private readonly auth?: SMTPAuth;\n  private readonly tls?: TLSOptions;\n  private readonly connectionTimeout?: number;\n  private readonly adapter?: SocketAdapter;\n  private readonly apiUrl: string;\n  private readonly apiAuth?: { user: string; pass: string };\n\n  private smtp: SMTPTransport | null = null;\n\n  /** Creates a Mailpit transport with local-dev defaults. */\n  constructor(config: MailpitConfig = {}) {\n    this.host = config.host ?? MAILPIT_DEFAULT_HOST;\n    this.port = config.port ?? MAILPIT_DEFAULT_PORT;\n    this.secure = config.secure ?? false;\n    this.requireTLS = config.requireTLS ?? false;\n    if (config.auth !== undefined) {\n      this.auth = config.auth;\n    }\n    if (config.tls !== undefined) {\n      this.tls = config.tls;\n    }\n    if (config.connectionTimeout !== undefined) {\n      this.connectionTimeout = config.connectionTimeout;\n    }\n    if (config.adapter !== undefined) {\n      this.adapter = config.adapter;\n    }\n    this.apiUrl = (config.apiUrl ?? MAILPIT_DEFAULT_API_URL).replace(/\\/$/, \"\");\n    if (config.apiAuth !== undefined) {\n      this.apiAuth = config.apiAuth;\n    }\n  }\n\n  /** Web UI base URL (same origin as the REST API). */\n  get webUrl(): string {\n    return this.apiUrl;\n  }\n\n  /** Sends an email to Mailpit over SMTP. */\n  async send(options: MailOptions): Promise<SendResult> {\n    return (await this.getSmtp()).send(options);\n  }\n\n  /** Verifies SMTP connectivity to Mailpit. */\n  async verify(): Promise<VerifyResult> {\n    const result = await (await this.getSmtp()).verify();\n    return {\n      ...result,\n      provider: \"mailpit\",\n    };\n  }\n\n  /** Closes the underlying SMTP adapter if connected. */\n  async close(): Promise<void> {\n    if (this.smtp) {\n      await this.smtp.close();\n    }\n  }\n\n  /**\n   * Lists captured messages via `GET /api/v1/messages`.\n   * Newest messages appear first.\n   */\n  async messages(options: MailpitMessagesOptions = {}): Promise<MailpitMessageList> {\n    const params = new URLSearchParams();\n    if (options.limit !== undefined) {\n      params.set(\"limit\", String(options.limit));\n    }\n    if (options.start !== undefined) {\n      params.set(\"start\", String(options.start));\n    }\n    const query = params.toString();\n    const path = query ? `/api/v1/messages?${query}` : \"/api/v1/messages\";\n    return this.apiGet<MailpitMessageList>(path);\n  }\n\n  /** Fetches a full message via `GET /api/v1/message/{id}`. */\n  async getMessage(id: string): Promise<MailpitMessage> {\n    if (!id) {\n      throw new MailpitError(\"Message id is required\", 400, { code: \"INVALID_CONFIG\" });\n    }\n    return this.apiGet<MailpitMessage>(`/api/v1/message/${encodeURIComponent(id)}`);\n  }\n\n  /**\n   * Deletes messages by id via `DELETE /api/v1/messages`.\n   * Pass an empty array (or call {@link deleteAll}) to clear the inbox.\n   */\n  async deleteMessages(ids: string[]): Promise<void> {\n    await this.apiDelete(\"/api/v1/messages\", { IDs: ids });\n  }\n\n  /** Deletes every captured message. */\n  async deleteAll(): Promise<void> {\n    await this.deleteMessages([]);\n  }\n\n  private async getSmtp(): Promise<SMTPTransport> {\n    if (!this.smtp) {\n      const adapter =\n        this.adapter ??\n        (await createDefaultAdapter({\n          secure: this.secure,\n          ...(this.connectionTimeout !== undefined\n            ? { connectionTimeout: this.connectionTimeout }\n            : {}),\n          ...(this.tls !== undefined ? { tls: this.tls } : {}),\n        }));\n\n      this.smtp = new SMTPTransport({\n        host: this.host,\n        port: this.port,\n        secure: this.secure,\n        requireTLS: this.requireTLS,\n        adapter,\n        ...(this.auth !== undefined ? { auth: this.auth } : {}),\n        ...(this.tls !== undefined ? { tls: this.tls } : {}),\n        ...(this.connectionTimeout !== undefined\n          ? { connectionTimeout: this.connectionTimeout }\n          : {}),\n      });\n    }\n    return this.smtp;\n  }\n\n  private apiHeaders(): HeadersInit {\n    const headers: Record<string, string> = {\n      Accept: \"application/json\",\n      \"Content-Type\": \"application/json\",\n    };\n    if (this.apiAuth) {\n      const token = encodeBase64(`${this.apiAuth.user}:${this.apiAuth.pass}`).replace(/\\r\\n/g, \"\");\n      headers.Authorization = `Basic ${token}`;\n    }\n    return headers;\n  }\n\n  private async apiGet<T>(path: string): Promise<T> {\n    let response: Response;\n    try {\n      response = await fetch(`${this.apiUrl}${path}`, {\n        method: \"GET\",\n        headers: this.apiHeaders(),\n      });\n    } catch (err) {\n      throw new MailpitError(\n        err instanceof Error ? err.message : \"Mailpit API request failed\",\n        0,\n        err,\n      );\n    }\n\n    if (!response.ok) {\n      const body = await response.text().catch(() => \"\");\n      throw new MailpitError(\n        body || `Mailpit API error (${response.status})`,\n        response.status,\n        body,\n      );\n    }\n\n    return (await response.json()) as T;\n  }\n\n  private async apiDelete(path: string, body: unknown): Promise<void> {\n    let response: Response;\n    try {\n      response = await fetch(`${this.apiUrl}${path}`, {\n        method: \"DELETE\",\n        headers: this.apiHeaders(),\n        body: JSON.stringify(body),\n      });\n    } catch (err) {\n      throw new MailpitError(\n        err instanceof Error ? err.message : \"Mailpit API request failed\",\n        0,\n        err,\n      );\n    }\n\n    if (!response.ok) {\n      const text = await response.text().catch(() => \"\");\n      throw new MailpitError(\n        text || `Mailpit API error (${response.status})`,\n        response.status,\n        text,\n      );\n    }\n  }\n}\n"
+  ],
+  "mappings": "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",
+  "debugId": "A41842358B8E380464756E2164756E21",
+  "names": []
+}

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "sently",
-  "version": "0.10.0",
-  "description": "Runtime-agnostic messaging library for Node.js, Bun, Deno, and Cloudflare Workers. Channel-first email, SMS, WhatsApp, and push with pluggable provider transports.",
+  "version": "1.0.0",
+  "description": "Runtime-agnostic channel-delivery library for Node.js, Bun, Deno, and Cloudflare Workers. One sender shape, one error model, and one retry path across email, SMS, WhatsApp, and push — with pluggable provider transports.",
   "type": "module",
   "sideEffects": false,
   "main": "./dist/index.js",
@@ -11,6 +11,7 @@
     "README.md",
     "LICENSE",
     "CHANGELOG.md",
+    "SECURITY.md",
     "AGENTS.md",
     "site/content/docs"
   ],
@@ -58,11 +59,18 @@
     "typescript": "6.0.3"
   },
   "keywords": [
+    "messaging",
     "email",
+    "sms",
+    "whatsapp",
+    "push",
+    "web-push",
+    "fcm",
     "smtp",
     "mailer",
     "nodemailer",
     "nodemailer-alternative",
+    "channel-first",
     "bun",
     "deno",
     "cloudflare-workers",
@@ -75,6 +83,7 @@
     "ses",
     "aws-ses",
     "brevo",
+    "twilio",
     "dkim",
     "oauth2",
     "transactional-email",
@@ -179,6 +188,10 @@
       "import": "./dist/transports/mailtrap.js",
       "types": "./dist/transports/mailtrap.d.ts"
     },
+    "./transports/mailpit": {
+      "import": "./dist/transports/mailpit.js",
+      "types": "./dist/transports/mailpit.d.ts"
+    },
     "./transports/loops": {
       "import": "./dist/transports/loops.js",
       "types": "./dist/transports/loops.d.ts"

package/site/content/docs/ai/llms-txt.mdx

@@ -6,7 +6,52 @@ source: "site/app/llms.txt/route.ts"
 ---
 
 The docs site serves `/llms.txt` and `/llms-full.txt` for concise and complete machine-readable documentation.
+Use the live site indexes when an agent needs current handbook navigation.
 
-Use `/llms.txt` for navigation and `/llms-full.txt` when an agent needs page content.
+<Callout title="The one rule">
+  Prefer the docs site `/llms.txt` over the repo-root `llms.txt` file when both exist — the site index is generated from the handbook MDX.
+</Callout>
 
-<Cards><Card title="MCP" href="/docs/ai/mcp" /></Cards>
+## Quick start
+
+<Steps>
+  <Step title="Fetch the short index">
+
+```text
+https://sently.omqkhafi.dev/llms.txt
+```
+
+  </Step>
+  <Step title="Fetch full page text when needed">
+
+```text
+https://sently.omqkhafi.dev/llms-full.txt
+```
+
+  </Step>
+</Steps>
+
+## Related agent surfaces
+
+| Resource | Use |
+| --- | --- |
+| Site `/llms.txt` | Navigation + short model |
+| Site `/llms-full.txt` | Full handbook dump |
+| Repo `AGENTS.md` | Channel-first contract |
+| [Stability](/docs/get-started/stability) | What is frozen at 1.x |
+| [Compare](/docs/guides/compare) | Library vs platform positioning |
+
+## Troubleshooting
+
+<Accordions>
+  <Accordion title="Why does the repo-root llms.txt disagree with the site?">
+    The live route is built from `site/content/docs`. Refresh or regenerate from the handbook after docs changes.
+  </Accordion>
+</Accordions>
+
+## Next
+
+<Cards>
+  <Card title="MCP" href="/docs/ai/mcp" />
+  <Card title="Introduction" href="/docs/get-started/introduction" />
+</Cards>

package/site/content/docs/channels/email.mdx

@@ -91,10 +91,13 @@ const mailer = await createSMTPMailer({
 - [Email options](../reference/mail-options)
 - [Transport contracts](../reference/transport-contracts)
 - [Hooks](./hooks)
+- [Mailpit](../transports/mailpit) — local catcher for development
+- [Preview](../decorators/preview) — write `.eml` files to disk
 
 ## Next
 
 <Cards>
   <Card title="Transports" href="/docs/transports" />
+  <Card title="Mailpit" href="/docs/transports/mailpit" />
   <Card title="Send in bulk" href="/docs/guides/send-bulk" />
 </Cards>

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

@@ -6,7 +6,7 @@ source: "README.md"
 ---
 
 Choose a channel sender for the kind of message your application sends.
-Each sender accepts a provider transport, so delivery providers can change without rewriting send calls.
+Each sender accepts a provider transport — retry, fallback, and `SentlyError` codes stay the same as you add channels.
 
 <Callout title="The one rule">Application code calls a sently channel sender; provider-specific code stays in its transport.</Callout>
 
@@ -68,6 +68,8 @@ await sms.send({
 ## Learn more
 
 - [Choose an entrypoint](../get-started/entrypoints)
+- [Support matrix](../get-started/support-matrix)
+- [Failover](../guides/failover)
 - [Browse transports](../transports)
 
 ## Next

package/site/content/docs/channels/push.mdx

@@ -78,6 +78,9 @@ Shared fields: `title`, `body`, optional `data`, `icon`, `ttl`, `messageId`.
   <Accordion title="Why does the transport reject my endpoint?">
     Web Push validates subscription endpoint hosts before sending. Add only exact private relay hostnames with `allowedEndpointHosts` when needed.
   </Accordion>
+  <Accordion title="Why does FCM reject my subscription object?">
+    `FcmTransport` requires `token`. Pass a Web Push `subscription` only to `WebPushTransport`.
+  </Accordion>
   <Accordion title="Why is the endpoint redacted in hooks?">
     Endpoint paths and FCM tokens are long-lived credentials, so hook context keeps only a redacted fingerprint.
   </Accordion>
@@ -88,6 +91,7 @@ Shared fields: `title`, `body`, optional `data`, `icon`, `ttl`, `messageId`.
 - [Push options](../reference/push-options)
 - [Web Push](../transports/webpush)
 - [FCM](../transports/fcm)
+- [Failover](../guides/failover)
 - [Hooks](./hooks)
 
 ## Next

package/site/content/docs/decorators/fallback.mdx

@@ -53,9 +53,14 @@ Successful sends include `provider` and `providerIndex` for the transport that h
   </Accordion>
 </Accordions>
 
+## Learn more
+
+- [Failover guide](/docs/guides/failover) — retry-then-fallback recipes across channels
+
 ## Next
 
 <Cards>
+  <Card title="Failover guide" href="/docs/guides/failover" />
   <Card title="Weighted fallback" href="/docs/decorators/weighted-fallback" />
   <Card title="Retry" href="/docs/decorators/retry" />
 </Cards>