sently 0.8.0 → 0.9.1

package/site/content/docs/get-started/entrypoints.mdx

@@ -0,0 +1,114 @@
+---
+title: Entrypoints
+description: Use focused subpaths to import only the channel or integration you need.
+icon: Route
+source: "package.json"
+---
+
+sently exports focused subpaths so a channel can import its sender and a single provider transport.
+The main `sently` package exports shared email factories and a few helpers — not every HTTP provider.
+
+<Callout title="The one rule">
+  Import a sender from its channel entrypoint and its provider from a `sently/transports/*`
+  entrypoint.
+</Callout>
+
+## Quick start
+
+<Steps>
+
+<Step>
+### Pick an email entrypoint
+
+```ts
+import { createMailer } from "sently/mailer";
+import { SndrTransport } from "sently/transports/sndr";
+
+const mailer = await createMailer({
+  transport: new SndrTransport({
+    apiKey: process.env.SNDR_API_KEY!,
+  }),
+});
+```
+
+</Step>
+
+<Step>
+### Use SMTP only when you have relay configuration
+
+```ts
+import { createSMTPMailer } from "sently/smtp";
+
+const mailer = await createSMTPMailer({
+  host: "smtp.example.com",
+  port: 587,
+  auth: { user: "you@example.com", pass: process.env.SMTP_PASS! },
+});
+```
+
+</Step>
+
+</Steps>
+
+## Channel entrypoints
+
+| Import | Exports | Use |
+| ------ | ------- | --- |
+| `sently` | Shared factories, types, OAuth2, errors, Fallback / WeightedFallback / Cloudflare Email | General email entrypoint. |
+| `sently/mailer` | `createMailer` | Email with an explicit transport (smallest HTTP path). |
+| `sently/smtp` | `createSMTPMailer` | SMTP relay configuration. |
+| `sently/sms` | `createSmsSender` | SMS sender. |
+| `sently/whatsapp` | `createWhatsAppSender` | WhatsApp sender. |
+| `sently/push` | `createPushSender` | Web Push sender. |
+
+## Supporting entrypoints
+
+| Import | Use |
+| ------ | --- |
+| `sently/transports/*` | One provider or email decorator transport. |
+| `sently/webhooks/<provider>` | One webhook parser (smallest graph). |
+| `sently/webhooks` | Convenience barrel of all webhook helpers. |
+| `sently/errors` | Stable sently error classes and codes. |
+| `sently/plugins/template` | Template plugin and simple engine. |
+| `sently/auth/oauth2` | SMTP OAuth2 client. |
+| `sently/pool` | SMTP connection pool. |
+| `sently/dkim` | DKIM signing entrypoint. |
+| `sently/idempotency` | Idempotency transport and memory store. |
+
+## Troubleshooting
+
+<Accordions>
+
+<Accordion title="Can I pass SMTP host and port to createMailer?">
+
+No. `createMailer` requires a transport. Import `createSMTPMailer` from `sently/smtp` for relay configuration.
+
+</Accordion>
+
+<Accordion title="Where do provider transports come from?">
+
+Import the concrete transport from its exported `sently/transports/*` subpath, such as `sently/transports/sndr` or `sently/transports/resend`.
+
+</Accordion>
+
+<Accordion title="Why is Plunk or SNDR missing from import sently?">
+
+HTTP providers were removed from the main barrel so bare Node/Deno imports do not load every client. Use the transport subpath.
+
+</Accordion>
+
+</Accordions>
+
+## Learn more
+
+- [Export reference](/docs/reference/exports) — full entrypoint map
+- [All transports](/docs/transports) — providers by channel
+- [Bundle size](/docs/guides/bundle-size) — keep stacks small
+
+## Next
+
+<Cards>
+  <Card title="Exports reference" description="Public package entrypoints." href="/docs/reference/exports" />
+  <Card title="Email channel" description="createMailer and MailOptions." href="/docs/channels/email" />
+  <Card title="SNDR" description="HTTP email via SNDR." href="/docs/transports/sndr" />
+</Cards>

package/site/content/docs/get-started/index.mdx

@@ -0,0 +1,14 @@
+---
+title: Get started
+description: Install sently and send your first message.
+icon: FolderOpen
+source: "README.md"
+---
+
+Install sently and send your first message.
+
+<Cards>
+  <Card title="Introduction" href="/docs/get-started/introduction" />
+  <Card title="Installation" href="/docs/get-started/installation" />
+  <Card title="Quick start" href="/docs/quick-start" />
+</Cards>

package/site/content/docs/get-started/installation.mdx

@@ -0,0 +1,78 @@
+---
+title: Installation
+description: Install sently with Bun or use its published ESM package.
+icon: Package
+source: "package.json"
+---
+
+sently is an ESM package for applications that send email, SMS, WhatsApp, or browser push.
+Install it in the application that owns your delivery credentials and provider transport configuration.
+
+<Callout title="The one rule">Import the narrowest sently entrypoint that contains the sender or transport you use.</Callout>
+
+<Steps>
+  <Step title="Add the package">
+
+```bash
+bun add sently
+```
+
+  </Step>
+  <Step title="Import a focused entrypoint">
+
+```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!,
+  }),
+});
+```
+
+  </Step>
+</Steps>
+
+## Install and runtime requirements
+
+| Requirement | Details |
+| --- | --- |
+| Package manager | Bun: `bun add sently`. |
+| Module format | Use ESM imports. |
+| Node.js | Version 18 or later. |
+| Bun | Version 1 or later. |
+| Email via SMTP | Use an SMTP-capable runtime adapter; HTTP transports are the portable option. |
+
+## Common imports
+
+| Need | Import |
+| --- | --- |
+| Email with a transport | `sently/mailer` |
+| Email over SMTP | `sently/smtp` |
+| SMS | `sently/sms` |
+| WhatsApp | `sently/whatsapp` |
+| Web Push | `sently/push` |
+
+## Troubleshooting
+
+<Accordions>
+  <Accordion title="Why cannot my runtime resolve sently?">
+    Use ESM package imports such as `sently/mailer`, rather than a file path into the package.
+  </Accordion>
+  <Accordion title="Should I import every transport from the main package?">
+    No. Provider transports are exported from their own `sently/transports/*` subpaths.
+  </Accordion>
+</Accordions>
+
+## Learn more
+
+- [Entrypoints](./entrypoints)
+- [Transports](../transports)
+
+## Next
+
+<Cards>
+  <Card title="Entrypoints" href="/docs/get-started/entrypoints" />
+  <Card title="Choose a channel" href="/docs/channels" />
+</Cards>

package/site/content/docs/get-started/introduction.mdx

@@ -0,0 +1,77 @@
+---
+title: Introduction
+description: Choose a sender for the channel and a transport for the provider.
+icon: Compass
+source: "README.md"
+---
+
+sently sends email, SMS, WhatsApp, and browser push without making provider SDK calls your application API.
+Choose the channel sender first, then attach the provider transport that performs delivery.
+
+<Callout title="The one rule">Use `createMailer`, `createSmsSender`, `createWhatsAppSender`, or `createPushSender` in app code; swap transports when provider configuration changes.</Callout>
+
+<Steps>
+  <Step title="Install the package">
+
+```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!,
+  }),
+});
+
+await mailer.send({
+  from: "hello@example.com",
+  to: "person@example.com",
+  subject: "Welcome",
+  text: "Thanks for joining.",
+});
+```
+
+  </Step>
+</Steps>
+
+## Choose a channel
+
+| Channel | Factory | Delivery contract |
+| --- | --- | --- |
+| Email | `createMailer` / `createSMTPMailer` | `Transport` |
+| SMS | `createSmsSender` | `SmsTransport` |
+| WhatsApp | `createWhatsAppSender` | `WhatsAppTransport` |
+| Push | `createPushSender` | `PushTransport` |
+
+Email factories are asynchronous. The other channel factories return their sender synchronously; all send operations are asynchronous.
+
+## Troubleshooting
+
+<Accordions>
+  <Accordion title="Which factory should I use for SMTP?">
+    Use `createSMTPMailer` with SMTP host, port, and authentication. Use `createMailer` when you already have a transport.
+  </Accordion>
+  <Accordion title="Can I replace a provider later?">
+    Yes. Keep your channel sender calls and construct it with another transport that implements the same channel contract.
+  </Accordion>
+</Accordions>
+
+## Learn more
+
+- [Install sently](./installation)
+- [Choose an entrypoint](./entrypoints)
+- [Explore channels](../channels)
+
+## Next
+
+<Cards>
+  <Card title="Email quick start" href="/docs/quick-start/email" />
+  <Card title="Channels" href="/docs/channels" />
+</Cards>

package/site/content/docs/get-started/meta.json

@@ -0,0 +1,12 @@
+{
+  "title": "Get started",
+  "icon": "Rocket",
+  "pages": [
+    "index",
+    "introduction",
+    "installation",
+    "entrypoints",
+    "runtimes",
+    "migrate-nodemailer"
+  ]
+}

package/site/content/docs/get-started/migrate-nodemailer.mdx

@@ -0,0 +1,23 @@
+---
+title: Migrate from Nodemailer
+description: Move SMTP configuration and message fields to sently incrementally.
+icon: ArrowRightLeft
+source: "README.md"
+---
+
+Keep your message object, replace transporter construction, and await the sently factory.
+
+```ts
+import { createSMTPMailer } from "sently/smtp";
+
+const mailer = await createSMTPMailer({
+  host: "smtp.example.com",
+  auth: { user: "user@example.com", pass: process.env.SMTP_PASSWORD! },
+});
+```
+
+<Callout title="The one rule">Use `createSMTPMailer` for relay configuration; use `createMailer` only with an explicit transport.</Callout>
+
+<Accordions><Accordion title="Why does transport-only createMailer reject host?">It only accepts a `transport`. Move relay configuration to `createSMTPMailer`.</Accordion></Accordions>
+
+<Cards><Card title="Email channel" href="/docs/channels/email" /></Cards>

package/site/content/docs/get-started/runtimes.mdx

@@ -0,0 +1,17 @@
+---
+title: Runtimes
+description: sently supports Node.js, Bun, Deno, and Cloudflare Workers through focused integrations.
+icon: Monitor
+source: "README.md"
+---
+
+HTTP transports use `fetch` and suit the supported runtimes. SMTP requires an adapter when automatic detection is unavailable.
+
+| Runtime | SMTP adapter subpath |
+| --- | --- |
+| Node.js | `sently/adapters/node` |
+| Bun | `sently/adapters/bun` |
+| Deno | `sently/adapters/deno` |
+| Cloudflare Workers | `sently/adapters/cf` |
+
+<Cards><Card title="Adapters" href="/docs/guides/adapters" /></Cards>

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

@@ -0,0 +1,26 @@
+---
+title: Adapters
+description: Configure an explicit SMTP socket adapter for a supported runtime.
+icon: Plug
+source: "src/adapters/node.ts"
+---
+
+<Callout title="The one rule">Use an adapter only when SMTP auto-detection is not suitable for your runtime.</Callout>
+
+| Runtime | Import | Class |
+| --- | --- | --- |
+| Node.js | `sently/adapters/node` | `NodeAdapter` |
+| Bun | `sently/adapters/bun` | `BunAdapter` |
+| Deno | `sently/adapters/deno` | `DenoAdapter` |
+| Cloudflare Workers | `sently/adapters/cf` | `CloudflareAdapter` |
+
+```ts
+import { createSMTPMailer } from "sently/smtp";
+import { NodeAdapter } from "sently/adapters/node";
+
+const mailer = await createSMTPMailer({ host: "smtp.example.com", adapter: new NodeAdapter() });
+```
+
+<Accordions><Accordion title="Why does SMTP fail on an edge runtime?">Use an HTTP transport, or provide the runtime's supported SMTP adapter.</Accordion></Accordions>
+
+<Cards><Card title="SMTP transport" href="/docs/transports/smtp" /></Cards>

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

@@ -0,0 +1,19 @@
+---
+title: Attachments
+description: Attach bytes, strings, or runtime-supported file paths to email.
+icon: Paperclip
+source: "src/core/types.ts"
+---
+
+<Callout title="The one rule">Use `content` for portable attachments; `path` is available only on Node.js and Bun.</Callout>
+
+```ts
+await mailer.send({
+  from: "hello@example.com", to: "person@example.com", subject: "Invoice",
+  attachments: [{ filename: "invoice.txt", content: "Paid" }],
+});
+```
+
+Attachments can set `contentType`, `encoding`, `contentId`, `inline`, and MIME `headers`.
+
+<Cards><Card title="Mail options" href="/docs/reference/mail-options" /></Cards>

package/site/content/docs/guides/bundle-size.mdx

@@ -0,0 +1,78 @@
+---
+title: Bundle size
+description: Keep imports focused on the channel and transport your app actually uses.
+icon: PackageOpen
+source: "package.json"
+---
+
+sently is split into subpaths so a receipt mailer does not pull SMS, SMTP pooling, or unused providers.
+Measure stacks with `bun run measure:size` in the library repo when you change imports.
+
+<Callout title="The one rule">
+  Import channel senders and provider transports from subpaths — never from a convenience barrel
+  when a focused path exists.
+</Callout>
+
+## Quick start
+
+<Steps>
+
+<Step>
+### Prefer mailer + one transport
+
+```ts
+import { createMailer } from "sently/mailer";
+import { SndrTransport } from "sently/transports/sndr";
+
+const mailer = await createMailer({
+  transport: new SndrTransport({ apiKey: process.env.SNDR_API_KEY! }),
+});
+```
+
+</Step>
+
+<Step>
+### Prefer one webhook parser
+
+```ts
+import { parse, verifySignature } from "sently/webhooks/sndr";
+```
+
+Avoid `import { … } from "sently/webhooks"` in Node/Deno without a bundler — that barrel evaluates every provider module.
+
+</Step>
+
+</Steps>
+
+## Typical stacks
+
+| Stack | Imports | Notes |
+| ----- | ------- | ----- |
+| HTTP email (SNDR) | `sently/mailer` + `sently/transports/sndr` | Small HTTP path. |
+| HTTP email (Resend) | `sently/mailer` + `sently/transports/resend` | Includes attachment helpers. |
+| SMS | `sently/sms` + `sently/transports/twilio-sms` | Channel + one SMS transport. |
+| SMTP | `sently/smtp` | Separate from `sently/mailer`. |
+
+## Troubleshooting
+
+<Accordions>
+
+<Accordion title="Why did importing createMailer from sently get larger?">
+
+With a bundler and `sideEffects: false`, unused re-exports usually shake out. Without a bundler, the main barrel still evaluates its static imports (SMTP factory, Fallback, Cloudflare Email, …). Prefer `sently/mailer` for HTTP-only apps.
+
+</Accordion>
+
+</Accordions>
+
+## Learn more
+
+- [Entrypoints](/docs/get-started/entrypoints) — which path to import
+- [Exports](/docs/reference/exports) — full map
+
+## Next
+
+<Cards>
+  <Card title="Entrypoints" description="Choose a focused import." href="/docs/get-started/entrypoints" />
+  <Card title="SNDR" description="Small HTTP email transport." href="/docs/transports/sndr" />
+</Cards>

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

@@ -0,0 +1,26 @@
+---
+title: DKIM
+description: Sign outgoing messages with RSA-SHA256 or Ed25519-SHA256.
+icon: KeyRound
+source: "src/dkim.ts"
+---
+
+<Callout title="The one rule">Keep the private key out of source control and publish the matching DNS record before sending.</Callout>
+
+<Steps><Step title="Sign a raw message">
+
+```ts
+import { signDKIM } from "sently/dkim";
+
+const result = await signDKIM(rawMessage, {
+  domainName: "example.com", keySelector: "2024", privateKey: process.env.DKIM_PRIVATE_KEY!,
+});
+```
+
+</Step></Steps>
+
+SMTP configuration also accepts `dkim`.
+
+<Accordions><Accordion title="Which keys are supported?">RSA keys of at least 1024 bits and Ed25519 keys are supported.</Accordion></Accordions>
+
+<Cards><Card title="SMTP transport" href="/docs/transports/smtp" /></Cards>

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

@@ -0,0 +1,15 @@
+---
+title: Guides
+description: Configure sently features around your delivery workflow.
+icon: FolderOpen
+source: "README.md"
+---
+
+Configure sently features around your delivery workflow.
+
+<Cards>
+  <Card title="Adapters" href="/docs/guides/adapters" />
+  <Card title="Webhooks" href="/docs/guides/webhooks" />
+  <Card title="Security" href="/docs/guides/security" />
+  <Card title="Bulk sending" href="/docs/guides/send-bulk" />
+</Cards>

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

@@ -0,0 +1,21 @@
+{
+  "title": "Guides",
+  "icon": "Map",
+  "pages": [
+    "index",
+    "adapters",
+    "dkim",
+    "oauth2",
+    "pool",
+    "plugins-template",
+    "react-email",
+    "webhooks",
+    "observability",
+    "vendor-extras-otp",
+    "security",
+    "attachments",
+    "send-bulk",
+    "webpush-interop",
+    "bundle-size"
+  ]
+}

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

@@ -0,0 +1,23 @@
+---
+title: OAuth2
+description: Refresh OAuth2 tokens and use them for SMTP XOAUTH2 authentication.
+icon: Key
+source: "src/auth/oauth2.ts"
+---
+
+<Callout title="The one rule">Use a refresh token or `getToken`; do not embed a short-lived access token in application code.</Callout>
+
+```ts
+import { OAuth2Client } from "sently/auth/oauth2";
+
+const client = new OAuth2Client({
+  user: "me@example.com", clientId: "...", clientSecret: "...", refreshToken: "...",
+});
+const token = await client.getAccessToken();
+```
+
+`OAuth2Client` caches tokens in memory and refreshes them before expiry.
+
+<Accordions><Accordion title="Can I supply tokens myself?">Yes. Provide `getToken` in the OAuth2 configuration.</Accordion></Accordions>
+
+<Cards><Card title="SMTP transport" href="/docs/transports/smtp" /></Cards>

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

@@ -0,0 +1,16 @@
+---
+title: Observability
+description: Attach lifecycle hooks or use the console observer for delivery diagnostics.
+icon: ChartNoAxesColumn
+source: "src/observability/console.ts"
+---
+
+<Callout title="The one rule">Capture metadata and durations, not message content or credentials.</Callout>
+
+```ts
+import { consoleObserver } from "sently/observability";
+
+const mailer = await createMailer({ transport, hooks: consoleObserver("[mail]") });
+```
+
+<Cards><Card title="Hooks" href="/docs/channels/hooks" /></Cards>

package/site/content/docs/guides/plugins-template.mdx

@@ -0,0 +1,22 @@
+---
+title: Template plugin
+description: Render named HTML email templates before delivery.
+icon: FileCode
+source: "src/plugins/template.ts"
+---
+
+<Callout title="The one rule">Return a new message object from plugins; do not mutate the input.</Callout>
+
+```ts
+import { simpleEngine, templatePlugin } from "sently/plugins/template";
+
+const plugin = templatePlugin({
+  engine: simpleEngine, templates: { welcome: "<h1>Hello, {{name}}!</h1>" },
+});
+```
+
+Send with `template: "welcome"` and `data: { name: "Ada" }`.
+
+<Accordions><Accordion title="What happens to missing variables?">`simpleEngine` renders unknown variables as an empty string.</Accordion></Accordions>
+
+<Cards><Card title="Mail options" href="/docs/reference/mail-options" /></Cards>

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

@@ -0,0 +1,24 @@
+---
+title: SMTP pooling
+description: Reuse SMTP connections and apply shared rate limits.
+icon: Network
+source: "src/core/types.ts"
+---
+
+<Callout title="The one rule">Enable pooling only for a long-lived process that sends more than one message.</Callout>
+
+```ts
+import { createSMTPMailer } from "sently/smtp";
+
+const mailer = await createSMTPMailer({
+  host: "smtp.example.com", pool: true, maxConnections: 5, maxMessages: 100,
+});
+```
+
+| Option | Default |
+| --- | --- |
+| `maxConnections` | 5 |
+| `maxMessages` | 100 |
+| `rateLimit` | 1000 ms |
+
+<Cards><Card title="SMTP transport" href="/docs/transports/smtp" /></Cards>

package/site/content/docs/guides/react-email.mdx

@@ -0,0 +1,20 @@
+---
+title: React Email
+description: Render a React email element through the optional sently React plugin.
+icon: Atom
+source: "src/react.ts"
+---
+
+Install the optional `react` and `@react-email/render` peer dependencies before using this integration.
+
+<Callout title="The one rule">Import the React plugin from `sently/react`; it is not part of the main entrypoint.</Callout>
+
+```ts
+import { reactPlugin } from "sently/react";
+
+const mailer = await createMailer({ transport, plugins: [reactPlugin()] });
+```
+
+Pass the element as `react` in the mail options.
+
+<Cards><Card title="Mail options" href="/docs/reference/mail-options" /></Cards>

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

@@ -0,0 +1,17 @@
+---
+title: Security
+description: Protect credentials, delivery endpoints, and webhook integrity.
+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>
+
+- 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.
+
+<Accordions><Accordion title="Why is a push endpoint redacted in hooks?">Its path can contain a long-lived delivery token.</Accordion></Accordions>
+
+<Cards><Card title="Webhooks" href="/docs/guides/webhooks" /></Cards>