sently 0.8.0 → 0.9.1

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

@@ -0,0 +1,81 @@
+---
+title: Channels
+description: Send through a stable channel API while transports handle providers.
+icon: FolderOpen
+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.
+
+<Callout title="The one rule">Application code calls a sently channel sender; provider-specific code stays in its transport.</Callout>
+
+<Steps>
+  <Step title="Choose the message channel">
+
+| Channel | Sender | Send shape |
+| --- | --- | --- |
+| Email | `createMailer` or `createSMTPMailer` | Sender, recipient, subject, and body. |
+| SMS | `createSmsSender` | Recipient number and body. |
+| WhatsApp | `createWhatsAppSender` | Template or text message. |
+| Push | `createPushSender` | Browser subscription, title, and body. |
+
+  </Step>
+  <Step title="Wire in a transport">
+
+```ts
+import { createSmsSender } from "sently/sms";
+import { TwilioSmsTransport } from "sently/transports/twilio-sms";
+
+const sms = createSmsSender({
+  transport: new TwilioSmsTransport({
+    accountSid: process.env.TWILIO_ACCOUNT_SID!,
+    authToken: process.env.TWILIO_AUTH_TOKEN!,
+  }),
+});
+
+await sms.send({
+  to: "+15551234567",
+  body: "Your order is on its way.",
+  from: "+15557654321",
+});
+```
+
+  </Step>
+</Steps>
+
+## Channel factories
+
+| Factory | Async | When to use it |
+| --- | --- | --- |
+| `createMailer` | Yes | Email with an explicit transport. |
+| `createSMTPMailer` | Yes | Email configured with SMTP host, port, and authentication. |
+| `createSmsSender` | No | SMS with an `SmsTransport`. |
+| `createWhatsAppSender` | No | WhatsApp with a `WhatsAppTransport`. |
+| `createPushSender` | No | Web Push with a `PushTransport`. |
+
+## Troubleshooting
+
+<Accordions>
+  <Accordion title="Should I call a provider SDK directly?">
+    Use the matching sently sender for normal delivery. Provider-only features belong on the concrete transport rather than the shared channel contract.
+  </Accordion>
+  <Accordion title="How do I switch providers?">
+    Keep the sender call and create it with a different transport for the same channel.
+  </Accordion>
+</Accordions>
+
+## Learn more
+
+- [Choose an entrypoint](../get-started/entrypoints)
+- [Browse transports](../transports)
+
+## Next
+
+<Cards>
+  <Card title="Email" href="/docs/channels/email" />
+  <Card title="SMS" href="/docs/channels/sms" />
+  <Card title="WhatsApp" href="/docs/channels/whatsapp" />
+  <Card title="Push" href="/docs/channels/push" />
+  <Card title="Hooks" href="/docs/channels/hooks" />
+</Cards>

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

@@ -0,0 +1,12 @@
+{
+  "title": "Channels",
+  "icon": "Send",
+  "pages": [
+    "index",
+    "email",
+    "sms",
+    "whatsapp",
+    "push",
+    "hooks"
+  ]
+}

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

@@ -0,0 +1,92 @@
+---
+title: Push
+description: Send encrypted Web Push notifications through a push transport.
+icon: Bell
+source: "src/push.ts"
+---
+
+Use Web Push for browser notifications after a browser has granted permission and returned a subscription.
+The sender passes the subscription and notification payload to a push transport.
+
+<Callout title="The one rule">Treat subscription endpoints as secrets: they are long-lived delivery tokens.</Callout>
+
+<Steps>
+  <Step title="Create a Push sender">
+
+```ts
+import { createPushSender } from "sently/push";
+import { WebPushTransport } from "sently/transports/webpush";
+
+const push = createPushSender({
+  transport: new WebPushTransport({
+    vapidPublicKey: process.env.VAPID_PUBLIC_KEY!,
+    vapidPrivateKey: process.env.VAPID_PRIVATE_KEY!,
+    subject: "mailto:you@example.com",
+  }),
+});
+```
+
+  </Step>
+  <Step title="Send to a stored browser subscription">
+
+```ts
+const result = await push.send({
+  subscription: {
+    endpoint: "https://fcm.googleapis.com/fcm/send/example",
+    keys: { p256dh: "browser-public-key", auth: "browser-auth-secret" },
+  },
+  title: "Report ready",
+  body: "Your weekly report is ready to view.",
+});
+
+console.log(result.status);
+```
+
+  </Step>
+</Steps>
+
+## Sender configuration
+
+| Option | Type | Meaning |
+| --- | --- | --- |
+| `transport` | `PushTransport` | Required delivery implementation. |
+| `plugins` | `PushPlugin[]` | Optional transforms run before delivery. |
+| `hooks` | `PushHooks` | Optional callbacks for delivery activity. |
+
+## Push and VAPID options
+
+| Option | Type | Meaning |
+| --- | --- | --- |
+| `subscription` | `PushSubscription` | Required browser endpoint plus `p256dh` and `auth` keys. |
+| `title`, `body` | `string` | Required notification content. |
+| `data`, `icon` | `Record<string, unknown>`, `string` | Optional application payload and icon URL. |
+| `ttl` | `number` | Optional delivery lifetime in seconds. |
+| `subject` | `string` | Required Web Push contact URI for the VAPID transport. |
+
+## Troubleshooting
+
+<Accordions>
+  <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 is the endpoint redacted in hooks?">
+    The endpoint path can contain a long-lived delivery token, so hook context keeps only a redacted form.
+  </Accordion>
+  <Accordion title="What does verify do?">
+    `push.verify()` delegates to the transport when available; the Web Push transport checks its VAPID credential shape.
+  </Accordion>
+</Accordions>
+
+## Learn more
+
+- [Push options](../reference/push-options)
+- [Transport contracts](../reference/transport-contracts)
+- [Web Push interoperability](../guides/webpush-interop)
+- [Hooks](./hooks)
+
+## Next
+
+<Cards>
+  <Card title="Web Push transport" href="/docs/transports/webpush" />
+  <Card title="All transports" href="/docs/transports" />
+</Cards>

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

@@ -0,0 +1,88 @@
+---
+title: SMS
+description: Send SMS through a sender and an SMS transport.
+icon: MessageSquare
+source: "src/sms.ts"
+---
+
+Use SMS for short transactional messages such as codes, delivery updates, and alerts.
+The sender stays the same when you change the provider transport.
+
+<Callout title="The one rule">Put the recipient, body, and optional `from` value on `sms.send`, not on the shared sender.</Callout>
+
+<Steps>
+  <Step title="Create an SMS sender">
+
+```ts
+import { createSmsSender } from "sently/sms";
+import { TwilioSmsTransport } from "sently/transports/twilio-sms";
+
+const sms = createSmsSender({
+  transport: new TwilioSmsTransport({
+    accountSid: process.env.TWILIO_ACCOUNT_SID!,
+    authToken: process.env.TWILIO_AUTH_TOKEN!,
+  }),
+});
+```
+
+  </Step>
+  <Step title="Send a message">
+
+```ts
+const result = await sms.send({
+  to: "+15551234567",
+  body: "Your verification code is 482915.",
+  from: "+15557654321",
+});
+
+console.log(result.status);
+```
+
+  </Step>
+</Steps>
+
+## Sender configuration
+
+| Option | Type | Meaning |
+| --- | --- | --- |
+| `transport` | `SmsTransport` | Required provider delivery implementation. |
+| `plugins` | `SmsPlugin[]` | Optional transforms run before delivery. |
+| `hooks` | `SmsHooks` | Optional callbacks for delivery activity. |
+
+## Message options
+
+| Option | Type | Meaning |
+| --- | --- | --- |
+| `to` | `string` | Required recipient number; E.164 is recommended. |
+| `body` | `string` | Required message text. |
+| `from` | `string` | Optional sender number or alphanumeric sender ID. |
+| `messageId` | `string` | Optional client-supplied identifier. |
+
+Twilio also accepts a default `from` or `messagingServiceSid` when you construct its concrete transport.
+
+## Troubleshooting
+
+<Accordions>
+  <Accordion title="Why does Twilio reject my send without a sender?">
+    Twilio requires `from` on the message or its transport configuration, unless its transport has `messagingServiceSid`.
+  </Accordion>
+  <Accordion title="Can I change SMS providers?">
+    Yes. Construct the sender with another `SmsTransport`; calls to `sms.send` keep the same message shape.
+  </Accordion>
+  <Accordion title="What does verify do?">
+    `sms.verify()` delegates to the transport when available; otherwise it reports a successful sender result.
+  </Accordion>
+</Accordions>
+
+## Learn more
+
+- [SMS options](../reference/sms-options)
+- [Transport contracts](../reference/transport-contracts)
+- [Hooks](./hooks)
+
+## Next
+
+<Cards>
+  <Card title="SMS transports" href="/docs/transports" />
+  <Card title="Provider OTP extras" href="/docs/guides/vendor-extras-otp" />
+</Cards>

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

@@ -0,0 +1,95 @@
+---
+title: WhatsApp
+description: Send template or session text messages through a WhatsApp transport.
+icon: MessagesSquare
+source: "src/whatsapp.ts"
+---
+
+Use WhatsApp for customer messages sent through a WhatsApp provider transport.
+Send a template for business-initiated delivery, or text during an open customer-service window.
+
+<Callout title="The one rule">Use templates for business-initiated messages outside the 24-hour customer-service window.</Callout>
+
+<Steps>
+  <Step title="Create a WhatsApp sender">
+
+```ts
+import { createWhatsAppSender } from "sently/whatsapp";
+import { WhatsAppCloudTransport } from "sently/transports/whatsapp-cloud";
+
+const whatsapp = createWhatsAppSender({
+  transport: new WhatsAppCloudTransport({
+    accessToken: process.env.WHATSAPP_TOKEN!,
+    phoneNumberId: process.env.WHATSAPP_PHONE_NUMBER_ID!,
+  }),
+});
+```
+
+  </Step>
+  <Step title="Send an approved template">
+
+```ts
+const result = await whatsapp.send({
+  to: "15551234567",
+  template: {
+    name: "welcome",
+    language: "en_US",
+  },
+});
+
+console.log(result.messageId);
+```
+
+  </Step>
+</Steps>
+
+## Sender configuration
+
+| Option | Type | Meaning |
+| --- | --- | --- |
+| `transport` | `WhatsAppTransport` | Required provider delivery implementation. |
+| `plugins` | `WhatsAppPlugin[]` | Optional transforms run before delivery. |
+| `hooks` | `WhatsAppHooks` | Optional callbacks for delivery activity. |
+
+## Message options
+
+| Shape | Required fields | Use |
+| --- | --- | --- |
+| Template | `to`, `template.name`, `template.language` | Business-initiated delivery. |
+| Text | `to`, `text` | An open 24-hour customer-service window. |
+
+Template messages may include `template.components` for header, body, or button parameters.
+
+```ts
+await whatsapp.send({
+  to: "15551234567",
+  text: "Thanks—we received your reply.",
+});
+```
+
+## Troubleshooting
+
+<Accordions>
+  <Accordion title="Why did my free-text message fail?">
+    Free text is valid only during an open customer-service window. Use a pre-approved template outside that window.
+  </Accordion>
+  <Accordion title="Can I change WhatsApp providers?">
+    Yes. Construct the sender with another `WhatsAppTransport`; message shapes remain template or text.
+  </Accordion>
+  <Accordion title="What does verify do?">
+    `whatsapp.verify()` delegates to the transport when available; otherwise it reports a successful sender result.
+  </Accordion>
+</Accordions>
+
+## Learn more
+
+- [WhatsApp options](../reference/whatsapp-options)
+- [Transport contracts](../reference/transport-contracts)
+- [Hooks](./hooks)
+
+## Next
+
+<Cards>
+  <Card title="WhatsApp Cloud transport" href="/docs/transports/whatsapp-cloud" />
+  <Card title="All transports" href="/docs/transports" />
+</Cards>

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

@@ -0,0 +1,34 @@
+---
+title: Fallback
+description: Fail over across ordered email transports.
+icon: GitBranch
+source: "src/transports/fallback.ts"
+---
+
+Fail over across ordered email transports.
+
+<Callout title="The one rule">Permanent client errors do not fall through by default.</Callout>
+
+## Configuration
+
+Pass a non-empty transport array; options include `shouldFallback`, `onFallback`, and `cooldownMs`.
+
+<Steps><Step title="Wrap an email transport">
+
+```ts
+import { FallbackTransport } from "sently/transports/fallback";
+
+const transport = new FallbackTransport([primary, secondary], { cooldownMs: 300_000 });
+```
+
+</Step><Step title="Create the mailer">
+
+```ts
+const mailer = await createMailer({ transport });
+```
+
+</Step></Steps>
+
+<Accordions><Accordion title="Does this replace the inner provider?">No. It delegates sends to the wrapped transport.</Accordion></Accordions>
+
+<Cards><Card title="Email channel" href="/docs/channels/email" /></Cards>

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

@@ -0,0 +1,34 @@
+---
+title: Idempotency
+description: Deduplicate replayed email sends with an idempotency key.
+icon: KeyRound
+source: "src/idempotency.ts"
+---
+
+Deduplicate replayed email sends with an idempotency key.
+
+<Callout title="The one rule">Wrap it outside RetryTransport so all retry attempts share a key.</Callout>
+
+## Configuration
+
+The optional options are `store` and `ttlMs`; memory is the default store.
+
+<Steps><Step title="Wrap an email transport">
+
+```ts
+import { IdempotencyTransport } from "sently/idempotency";
+
+const transport = new IdempotencyTransport(inner, { ttlMs: 86_400_000 });
+```
+
+</Step><Step title="Create the mailer">
+
+```ts
+const mailer = await createMailer({ transport });
+```
+
+</Step></Steps>
+
+<Accordions><Accordion title="Does this replace the inner provider?">No. It delegates sends to the wrapped transport.</Accordion></Accordions>
+
+<Cards><Card title="Email channel" href="/docs/channels/email" /></Cards>

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

@@ -0,0 +1,50 @@
+---
+title: Decorators
+description: Wrap an email transport with retry, fallback, preview, or idempotency.
+icon: Layers
+source: "src/transports/retry.ts"
+---
+
+Decorators wrap another email transport. The mailer still calls `send` the same way — only the transport path changes.
+
+<Callout title="The one rule">Pass the outermost decorator to `createMailer`. Inner transports stay providers (or other decorators).</Callout>
+
+## Available decorators
+
+| Decorator | Import |
+| --- | --- |
+| [Preview](./preview) | `sently/transports/preview` |
+| [Retry](./retry) | `sently/transports/retry` |
+| [Fallback](./fallback) | `sently/transports/fallback` |
+| [Weighted fallback](./weighted-fallback) | `sently/transports/weighted-fallback` |
+| [Idempotency](./idempotency) | `sently/idempotency` |
+
+## Typical stack
+
+```ts
+import { createMailer } from "sently/mailer";
+import { ResendTransport } from "sently/transports/resend";
+import { RetryTransport } from "sently/transports/retry";
+import { FallbackTransport } from "sently/transports/fallback";
+
+const transport = new FallbackTransport([
+  new RetryTransport(new ResendTransport({ apiKey: process.env.RESEND_API_KEY! })),
+  new ResendTransport({ apiKey: process.env.RESEND_BACKUP_KEY! }),
+]);
+
+const mailer = await createMailer({ transport });
+```
+
+## Learn more
+
+- [Transports](../transports)
+- [Email channel](../channels/email)
+- [Hooks](../channels/hooks)
+
+## Next
+
+<Cards>
+  <Card title="Retry" href="/docs/decorators/retry" />
+  <Card title="Fallback" href="/docs/decorators/fallback" />
+  <Card title="Transports" href="/docs/transports" />
+</Cards>

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

@@ -0,0 +1,12 @@
+{
+  "title": "Decorators",
+  "icon": "Layers",
+  "pages": [
+    "index",
+    "preview",
+    "retry",
+    "fallback",
+    "weighted-fallback",
+    "idempotency"
+  ]
+}

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

@@ -0,0 +1,34 @@
+---
+title: Preview
+description: Write email previews to disk instead of delivering them.
+icon: Eye
+source: "src/transports/preview.ts"
+---
+
+Write email previews to disk instead of delivering them.
+
+<Callout title="The one rule">Preview is for development, not delivery.</Callout>
+
+## Configuration
+
+`outDir`, `open`, and `format` are optional; defaults are `./.emails`, false, and `eml`.
+
+<Steps><Step title="Wrap an email transport">
+
+```ts
+import { PreviewTransport } from "sently/transports/preview";
+
+const transport = new PreviewTransport({ outDir: ".emails", open: true });
+```
+
+</Step><Step title="Create the mailer">
+
+```ts
+const mailer = await createMailer({ transport });
+```
+
+</Step></Steps>
+
+<Accordions><Accordion title="Does this replace the inner provider?">No. It delegates sends to the wrapped transport.</Accordion></Accordions>
+
+<Cards><Card title="Email channel" href="/docs/channels/email" /></Cards>

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

@@ -0,0 +1,34 @@
+---
+title: Retry
+description: Retry failed email sends with configurable backoff.
+icon: RotateCw
+source: "src/transports/retry.ts"
+---
+
+Retry failed email sends with configurable backoff.
+
+<Callout title="The one rule">Authentication errors are not retried.</Callout>
+
+## Configuration
+
+`maxAttempts`, `backoff`, `baseDelay`, `retryOn`, and `onRetry` are optional.
+
+<Steps><Step title="Wrap an email transport">
+
+```ts
+import { RetryTransport } from "sently/transports/retry";
+
+const transport = new RetryTransport(new ResendTransport({ apiKey: "..." }), { maxAttempts: 3 });
+```
+
+</Step><Step title="Create the mailer">
+
+```ts
+const mailer = await createMailer({ transport });
+```
+
+</Step></Steps>
+
+<Accordions><Accordion title="Does this replace the inner provider?">No. It delegates sends to the wrapped transport.</Accordion></Accordions>
+
+<Cards><Card title="Email channel" href="/docs/channels/email" /></Cards>

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

@@ -0,0 +1,34 @@
+---
+title: Weighted fallback
+description: Choose a weighted primary transport and fail over on errors.
+icon: Scale
+source: "src/transports/weighted-fallback.ts"
+---
+
+Choose a weighted primary transport and fail over on errors.
+
+<Callout title="The one rule">At least one entry with positive total weight is required.</Callout>
+
+## Configuration
+
+Each entry has `transport` and positive `weight`; it accepts fallback options and optional `random`.
+
+<Steps><Step title="Wrap an email transport">
+
+```ts
+import { WeightedFallbackTransport } from "sently/transports/weighted-fallback";
+
+const transport = new WeightedFallbackTransport([{ transport: primary, weight: 80 }, { transport: secondary, weight: 20 }]);
+```
+
+</Step><Step title="Create the mailer">
+
+```ts
+const mailer = await createMailer({ transport });
+```
+
+</Step></Steps>
+
+<Accordions><Accordion title="Does this replace the inner provider?">No. It delegates sends to the wrapped transport.</Accordion></Accordions>
+
+<Cards><Card title="Email channel" href="/docs/channels/email" /></Cards>