sently 0.8.0 → 0.9.1

package/AGENTS.md

@@ -0,0 +1,33 @@
+# sently — agent contract
+
+sently is a runtime-agnostic TypeScript messaging library (email, SMS, WhatsApp, Web Push) for Node.js, Bun, Deno, and Cloudflare Workers. ESM-only, zero runtime dependencies.
+
+## Sently-first provider model
+
+Apps use **channel senders**, not vendor SDKs:
+
+| Channel | Sender | Contract |
+|---------|--------|----------|
+| Email | `createMailer` / `createSMTPMailer` | `Transport` |
+| SMS | `createSmsSender` | `SmsTransport` |
+| WhatsApp | `createWhatsAppSender` | `WhatsAppTransport` |
+| Push | `createPushSender` | `PushTransport` |
+
+Providers are transports under those senders. Vendor extras (OTP, account utilities) live on the concrete transport class — never on the shared channel contract.
+
+## Docs
+
+- Handbook: `site/content/docs/` (Fumadocs)
+- Machine index: `/llms.txt` on the docs site
+
+## Commands
+
+```sh
+bun install
+bun test
+bun run site:dev
+bun run site:build
+bun run verify
+```
+
+Do not invent APIs. Prefer imports from published subpaths (`sently/mailer`, `sently/sms`, `sently/transports/*`).

package/CHANGELOG.md

@@ -2,9 +2,48 @@
 
 ## [Unreleased]
 
+## [0.9.1] — 2026-08-01
+
+### 🐛 Fixed
+
+- **SNDR live suite opt-in** — require `SNDR_LIVE=1` (plus credentials) so
+  `bun run verify` stays offline-safe when `.env` has keys
+- **Docs header geometry gate** — assert the home brand cell against
+  `HeroIntro`'s left-pane width after the hero split moved out of `page.tsx`
+
+## [0.9.0] — 2026-08-01
+
+### ✨ Added
+
+- **Channel senders** — `createSmsSender` (`sently/sms`), `createWhatsAppSender`
+  (`sently/whatsapp`), `createPushSender` (`sently/push`) alongside email; each
+  sender supports plugins and lifecycle hooks
+- **SMS transports** — Twilio, Taqnyat SMS, Msegat (`sently/transports/twilio-sms`,
+  `taqnyat-sms`, `msegat`); vendor OTP helpers stay on the transport class
+- **WhatsApp transports** — WhatsApp Cloud API, Taqnyat WhatsApp
+  (`sently/transports/whatsapp-cloud`, `taqnyat-whatsapp`)
+- **Web Push transport** — VAPID Web Push (`sently/transports/webpush`)
+- **Email transports** — Sndr, Taqnyat Mail (`sently/transports/sndr`,
+  `taqnyat-mail`)
+- **Sndr webhooks** — `parseSndrWebhook` / `verifySndrSignature`
+  (`sently/webhooks/sndr`, also via `sently/webhooks`)
+- **Per-provider webhook subpaths** — `sently/webhooks/{brevo,mailgun,postmark,
+  resend,sendgrid,ses,sndr}` for tree-shakeable imports
+- **Docs site** — Next.js + Fumadocs handbook under `site/` (`bun run site:dev`)
+- **Web Push interop example** — `examples/webpush-interop`
+- **`AGENTS.md`** — agent contract for the sently-first provider model (replaces
+  `CLAUDE.md`; published with the package)
+
+### ♻️ Changed
+
+- **Library scope** — channel-first messaging (email, SMS, WhatsApp, push), not
+  email-only; package description and README updated accordingly
+- **Docs site branding** — real sently wordmark / mark in the header, homepage,
+  404, favicon, Apple touch icon, and docs OG images; README shows the logo
+
 ## [0.8.0] — 2026-06-07
 
-### Added
+### ✨ Added
 
 - **`FallbackTransport`** (`sently/transports/fallback`) — provider failover through an ordered transport list; composes with `RetryTransport`; `FallbackError.attempts` records `{ provider, error }` per failed attempt
 - **Five HTTP providers:** MailerSend, Plunk, SparkPost, Mailtrap, Loops (`sently/transports/mailersend`, `plunk`, `sparkpost`, `mailtrap`, `loops`)
@@ -20,14 +59,14 @@
 
 ## [0.7.2] — 2026-05-31
 
-### Fixed
+### 🐛 Fixed
 
 - Publish workflow runs `bun run build` before registry steps and publishes **npm before JSR** so a failed npm step does not leave JSR ahead of npm
 - `scripts/publish.ts` `syncVersion()` skips rewriting `jsr.json` when content is unchanged (avoids dirty working tree between CI publish steps)
 
 ## [0.7.1] — 2026-05-31
 
-### Documentation
+### 📚 Documentation
 
 - README Nodemailer comparison updated for **v8.0.10** (~58 KB gzip, zero deps, 2026 releases)
 - Bundle size figures refreshed from `bun run measure:size:md` (~6.1 KB HTTP, ~15 KB SMTP, ~2.6 KB `sently/mailer`)
@@ -35,7 +74,7 @@
 
 ## [0.7.0] — 2026-05-31
 
-### Breaking + Migration
+### 💥 Breaking + Migration
 
 Summary:
 
@@ -53,13 +92,13 @@ Summary:
   transport-only main `createMailer`; v0.5.x bulk-send behavior (native batch, default
   2 req/s throttle, `SendResult.batchError`).
 
-### Added
+### ✨ Added
 
 - **`INVALID_CONFIG`** stable error code for misconfigured mailer factories
 - **`SMTPMailerOptions`** type for SMTP factory config
 - README decision-tree section and Microsoft 365 OAuth2 example
 
-### Changed
+### ♻️ Changed
 
 - **`BulkSendOptions.concurrency` TSDoc** — documents default `1` (matches implementation)
 - Bundle size budgets updated for slimmer main entry
@@ -67,12 +106,12 @@ Summary:
 
 ## [0.6.2] — 2026-05-31
 
-### Added
+### ✨ Added
 
 - **`sently/smtp`** subpath — SMTP `createMailer` (`host` / `port` / `auth`, pooling,
   adapters) isolated from the main entry for smaller HTTP app bundles
 
-### Changed
+### ♻️ Changed
 
 - **Breaking:** main `createMailer` from `sently` is transport-only (same as
   `sently/mailer`). SMTP relay apps use `import { createMailer } from "sently/smtp"`
@@ -88,18 +127,18 @@ Summary:
 
 ## [0.6.1] — 2026-05-31
 
-### Fixed
+### 🐛 Fixed
 
 - **Build** — emit `dist/core/errors.js` so the main barrel and Node/Deno smoke
   tests resolve `SentlyError` imports after `bun run build`
 
-### Changed
+### ♻️ Changed
 
 - Bundle size budgets adjusted for minor measurement drift on CI runners
 
 ## [0.6.0] — 2026-05-31
 
-### Added
+### ✨ Added
 
 - **`sently/errors`** — unified `SentlyError` base class with stable machine-readable
   codes (`RATE_LIMITED`, `BAD_REQUEST`, `SMTP_AUTH_FAILED`, etc.); all existing
@@ -112,13 +151,13 @@ Summary:
 - **`AUDIT-v0.6.md`** — README capability audit with file/line proof (all claims
   verified implemented, including CRAM-MD5)
 
-### Changed
+### ♻️ Changed
 
 - Bundle size budgets updated for expanded mailer (hooks) and error hierarchy
 
 ## [0.5.2] — 2026-05-31
 
-### Fixed
+### 🐛 Fixed
 
 - **Build** — `dist/webhooks.js` and `dist/react.js` are generated from source instead
   of bundled with code-splitting, fixing `SyntaxError: Export 'k' is not defined` when
@@ -126,12 +165,12 @@ Summary:
 
 ## [0.5.1] — 2026-05-31
 
-### Breaking
+### 💥 Breaking
 
 - **Main barrel** — `reactPlugin` and `ReactMailOptions` are no longer exported from
   `"sently"`. Import them from `"sently/react"` instead.
 
-### Fixed
+### 🐛 Fixed
 
 - **Webhook signatures** — `verifyResendSignature` and `verifyMailgunSignature` now
   compare decoded signature bytes with constant-time `timingSafeEqual` (Web Crypto only)
@@ -139,7 +178,7 @@ Summary:
 - **Batch sendBulk** — per-chunk failure isolation, per-message partial batch errors
   (`SendResult.batchError`), and rate limiting between batch HTTP requests (default 2/s)
 
-### Changed
+### ♻️ Changed
 
 - `RateLimiter` extracted to `src/core/rate-limiter.ts` (shared by pool and mailer)
 - `Transport.batchMax` on `ResendTransport`; `BulkSendOptions.rateDelta` / `rateLimit`
@@ -147,7 +186,7 @@ Summary:
 
 ## [0.5.0] — 2026-05-31
 
-### Added
+### ✨ Added
 
 - **`sently/react`** — React Email integration via `reactPlugin()`; optional peers
   `react` and `@react-email/render`; `options.react` on `MailOptions`
@@ -163,7 +202,7 @@ Summary:
   optional Mailgun HMAC and Resend Svix signature verification helpers
 - **`deduped`** flag on `SendResult` for idempotency cache hits
 
-### Changed
+### ♻️ Changed
 
 - `sendBulk` uses native batch endpoints when the transport implements
   `sendBatch`; concurrent per-message fallback unchanged for other transports
@@ -172,7 +211,7 @@ Summary:
 
 ## [0.4.7] — 2026-05-30
 
-### Added
+### ✨ Added
 
 - **`sently/mailer` entry** — transport-only `createMailer` without SMTP code in the
   bundle (~4.3 KB with HTTP transports vs ~14 KB from the main entry)
@@ -185,7 +224,7 @@ Summary:
   for docs and CI
 - **Deno and Cloudflare adapter smoke tests** in CI
 
-### Changed
+### ♻️ Changed
 
 - Lazy-load SMTP transport and pool from `createMailer` when using SMTP config
 - Extract `MailerImpl` to `src/mailer.ts`; full `createMailer` in `detect.ts` delegates
@@ -196,7 +235,7 @@ Summary:
 - **Pinned devDependency versions** (Biome 2.4.16, TypeScript 6.0.3, `@types/node`
   25.9.1, MCP SDK 1.29.0)
 
-### Documentation
+### 📚 Documentation
 
 - README **Bundle Size** section — import-path guide, common stacks, per-subpath
   tables, and HTTP stack breakdown
@@ -205,7 +244,7 @@ Summary:
 
 ## [0.4.6] — 2026-05-30
 
-### Documentation
+### 📚 Documentation
 
 - Documented all remaining exported symbols (class members, interface
   properties, and internal helpers) for 100% JSR symbol documentation
@@ -214,7 +253,7 @@ Summary:
 
 ## [0.4.5] — 2026-05-30
 
-### Documentation
+### 📚 Documentation
 
 - Added `@module` documentation to the `./pool` entrypoint
 - Documented exported interface properties and public API methods across
@@ -223,7 +262,7 @@ Summary:
 
 ## [0.4.4] — 2026-05-30
 
-### Security
+### 🔒 Security
 
 - Fixed SigV4 date format: slice(0,15) not slice(0,16) — all real
   SES requests were producing malformed x-amz-date headers
@@ -251,7 +290,7 @@ Summary:
 
 ## [0.4.3] — 2026-05-30
 
-### Added
+### ✨ Added
 
 - `llms.txt` for LLM/agent discovery (install, quick example, subpath
   exports, and when-to-use guidance)
@@ -260,7 +299,7 @@ Summary:
 - `CLAUDE.md` repository map for agents (core entry, adapters,
   transports, tests, build)
 
-### Changed
+### ♻️ Changed
 
 - README positioning, HTTP transport reference table, plugin docs
   reorder, and tree-shaking callout
@@ -268,7 +307,7 @@ Summary:
 
 ## [0.4.2] — 2026-05-30
 
-### Fixed
+### 🐛 Fixed
 
 - CI: replaced node -e dynamic import with scripts/smoke.mjs
   (top-level await ESM) for reliable Node.js smoke testing
@@ -278,7 +317,7 @@ Summary:
 
 ## [0.4.1] — 2026-05-30
 
-### Fixed
+### 🐛 Fixed
 
 - CI: use locally installed tsc (node_modules/.bin/tsc) in build.ts
   instead of bunx tsc to avoid runtime npm downloads in CI
@@ -289,7 +328,7 @@ Summary:
 
 ## [0.4.0] — 2026-05-30
 
-### Added
+### ✨ Added
 
 - `PreviewTransport` — writes emails to disk as .eml or HTML for local development
 - `RetryTransport` — decorator transport with exponential/linear/fixed backoff
@@ -302,14 +341,14 @@ Summary:
 - `attachment.path` basePath guard (opt-in) in resolveAttachments
 - GitHub Actions CI matrix: unit tests (Bun), smoke test (Node 22), SMTP integration (Mailpit)
 
-### Fixed
+### 🐛 Fixed
 
 - `detectRuntime()` priority hardened: Bun checked before Node.js process globals
 - Cloudflare Workers detection uses positive signature (caches + UA), not absence of other runtimes
 
 ## [0.3.4] — 2026-05-30
 
-### Fixed
+### 🐛 Fixed
 
 - Stale `sendx` references in package.json, build.ts, PROGRESS.md
 - JSR badge URL now matches jsr.json scope exactly
@@ -319,25 +358,25 @@ Summary:
   and uses Promise.allSettled to drain in-flight messages
 - Audited all buildMIME() call sites — await confirmed present
 
-### Added
+### ✨ Added
 
 - `engines` field in package.json (Node >= 18, Bun >= 1.0)
 
 ## [0.3.3] — 2026-05-29
 
-### Fixed
+### 🐛 Fixed
 
 - Corrected JSR package name in README from `@sently/sently` to `@alialnaghmoush/sently`
 
 ## [0.3.2] — 2026-05-29
 
-### Fixed
+### 🐛 Fixed
 
 - Biome formatting in MIME header builder (`src/core/mime.ts`) so `bun lint` passes
 
 ## [0.3.1] — 2026-05-29
 
-### Security
+### 🔒 Security
 
 - Fixed CRLF header injection: `sanitizeHeaderValue()` strips CR/LF
   from Subject, display names, and custom headers in MIME builder
@@ -353,7 +392,7 @@ Summary:
 
 ## [0.3.0] — 2026-05-29
 
-### Added
+### ✨ Added
 
 - Plugin system: `plugins` array in `createMailer()` config
   Plugins are `(options: MailOptions) => MailOptions | Promise<MailOptions>` functions
@@ -363,14 +402,14 @@ Summary:
 - `BrevoTransport` — Brevo (formerly Sendinblue) HTTP API
 - `TLSOptions.minVersion` — set minimum TLS version for legacy SMTP servers
 
-### Parity milestone
+### 🏁 Parity milestone
 
 sently now covers ~98% of Nodemailer feature parity for modern use cases.
 Remaining gaps (SOCKS proxy, iCal) are out of scope by design.
 
 ## [0.2.0] — 2026-05-29
 
-### Added
+### ✨ Added
 
 - DKIM signing (RSA-SHA256 and Ed25519-SHA256) via `SMTPConfig.dkim`
 - OAuth2 / XOAUTH2 authentication via `SMTPAuth.type = 'OAUTH2'`
@@ -378,7 +417,7 @@ Remaining gaps (SOCKS proxy, iCal) are out of scope by design.
 - Rate limiting via `PoolConfig.rateDelta` / `PoolConfig.rateLimit`
 - CRAM-MD5 authentication (pure-JS HMAC-MD5)
 
-### Changed
+### ♻️ Changed
 
 - npm package name is `sently`; JSR package name is `@sently/sently`
 - `SMTPAuth.pass` is now optional (was required in v0.1)
@@ -386,10 +425,12 @@ Remaining gaps (SOCKS proxy, iCal) are out of scope by design.
 - `selectAuthMethod` priority: XOAUTH2 > CRAM-MD5 > LOGIN > PLAIN
 - `createMailer()` uses `SMTPPool` automatically when `pool: true`
 
-### Fixed
+### 🐛 Fixed
 
 - CRAM-MD5 stub now fully implemented
 
 ## [0.1.0] — 2026-05-29
 
-Initial release.
+### ✨ Added
+
+- Initial release.