sently 0.8.0 → 0.9.1

package/site/content/docs/guides/send-bulk.mdx

@@ -0,0 +1,18 @@
+---
+title: Bulk sending
+description: Send multiple email messages with concurrency and batch-aware transports.
+icon: Layers
+source: "src/mailer.ts"
+---
+
+<Callout title="The one rule">Use `sendBulk` for independent messages; it reports per-message failures instead of throwing the entire batch result away.</Callout>
+
+```ts
+const result = await mailer.sendBulk(messages, { concurrency: 5, stopOnError: false });
+```
+
+Resend and SendGrid can use transport batch support; messages with attachments are sent individually.
+
+<Accordions><Accordion title="How are errors represented?">Each result entry is either `{ status: "sent", result }` or `{ status: "failed", error }`.</Accordion></Accordions>
+
+<Cards><Card title="Mail options" href="/docs/reference/mail-options" /></Cards>

package/site/content/docs/guides/vendor-extras-otp.mdx

@@ -0,0 +1,18 @@
+---
+title: Vendor OTP helpers
+description: Use OTP helpers only on concrete SMS transport instances.
+icon: BadgeCheck
+source: "src/transports/msegat.ts"
+---
+
+<Callout title="The one rule">OTP methods are provider extras; they are not part of `SmsSender` or `SmsTransport`.</Callout>
+
+```ts
+const msegat = new MsegatTransport({ userName: "...", apiKey: "...", sender: "MyBrand" });
+const otp = await msegat.sendOtp({ to: "+9665...", lang: "En" });
+await msegat.verifyOtp({ id: otp.id, code: "1234", lang: "En" });
+```
+
+Taqnyat SMS also exposes `sendOtp` and `verifyOtp` on its transport.
+
+<Cards><Card title="Msegat" href="/docs/transports/msegat" /><Card title="Taqnyat SMS" href="/docs/transports/taqnyat-sms" /></Cards>

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

@@ -0,0 +1,120 @@
+---
+title: Webhooks
+description: Parse provider delivery events into a shared EmailEvent shape, with optional signature checks.
+icon: Webhook
+source: "src/webhooks.ts"
+---
+
+Use webhooks when a provider posts delivery updates (delivered, bounced, and similar).
+sently turns each provider payload into `EmailEvent[]` so your app can share one handler.
+
+<Callout title="The one rule">
+  Verify the signature against the unmodified raw request body before you trust or act on the event.
+</Callout>
+
+## Quick start
+
+<Steps>
+
+<Step>
+### Import one provider subpath
+
+Prefer `sently/webhooks/<provider>` so runtimes without a bundler do not load every parser.
+
+```ts
+import { parse, verifySignature } from "sently/webhooks/sndr";
+```
+
+</Step>
+
+<Step>
+### Verify, then parse
+
+```ts
+const rawBody = await request.text(); // exact bytes as a string
+const signature = request.headers.get("x-sndr-signature") ?? "";
+
+const ok = await verifySignature(
+  rawBody,
+  signature,
+  process.env.SNDR_WEBHOOK_SECRET!,
+);
+if (!ok) {
+  return new Response("bad signature", { status: 400 });
+}
+
+const events = parse(JSON.parse(rawBody));
+```
+
+</Step>
+
+<Step>
+### Handle normalized events
+
+```ts
+for (const event of events) {
+  if (event.type === "bounced") {
+    // suppress or alert using event.messageId / event.recipient
+  }
+}
+```
+
+</Step>
+
+</Steps>
+
+## Provider entrypoints
+
+| Import | Parse export | Verify export |
+| ------ | ------------ | ------------- |
+| `sently/webhooks/brevo` | `parse` | — |
+| `sently/webhooks/mailgun` | `parse` | `verifySignature`, `verifyPayload` |
+| `sently/webhooks/postmark` | `parse` | — |
+| `sently/webhooks/resend` | `parse` | `verifySignature` |
+| `sently/webhooks/sendgrid` | `parse` | — |
+| `sently/webhooks/ses` | `parse` | — |
+| `sently/webhooks/sndr` | `parse` | `verifySignature` |
+
+The convenience barrel `sently/webhooks` re-exports named helpers such as `parseSndrWebhook` and `verifySndrSignature`.
+Bundlers tree-shake unused names; Node/Deno without a bundler evaluate every re-export.
+
+## SNDR signatures
+
+SNDR signs with `X-Sndr-Signature: t=<unix>,v1=<hex>`.
+The digest is HMAC-SHA256 over `` `${t}.${rawBody}` ``.
+
+**Consequence:** Re-serializing JSON changes whitespace and key order and breaks verification — always use the raw body string.
+
+Default timestamp tolerance is 300 seconds. Pass `{ toleranceSeconds: 0 }` to disable the freshness check.
+
+## Troubleshooting
+
+<Accordions>
+
+<Accordion title="Signature verifies in docs but fails in production">
+
+Most frameworks parse JSON before your handler runs. Read the raw body first (`request.text()`, `express.raw()`, or equivalent), verify, then `JSON.parse`.
+
+</Accordion>
+
+<Accordion title="Which providers are supported?">
+
+Brevo, Mailgun, Postmark, Resend, SendGrid, SES, and SNDR. Import each from its `sently/webhooks/<provider>` subpath.
+
+</Accordion>
+
+</Accordions>
+
+## Learn more
+
+- [Webhook events](/docs/reference/webhook-events) — `EmailEvent` fields and type unions
+- [SNDR transport](/docs/transports/sndr) — send path that produces those message ids
+- [Exports](/docs/reference/exports) — package entrypoints
+
+## Next
+
+<Cards>
+  <Card title="Webhook events" description="Normalized EmailEvent fields." href="/docs/reference/webhook-events" />
+  <Card title="SNDR" description="Send email through SNDR." href="/docs/transports/sndr" />
+  <Card title="Exports" description="Public package entrypoints." href="/docs/reference/exports" />
+</Cards>

package/site/content/docs/guides/webpush-interop.mdx

@@ -0,0 +1,18 @@
+---
+title: Web Push interoperability
+description: Use subscriptions from the browser Push API with the Web Push transport.
+icon: BellRing
+source: "src/transports/webpush.ts"
+---
+
+<Callout title="The one rule">Pass the Push API subscription endpoint and both keys exactly as the browser returned them.</Callout>
+
+The transport accepts the standard `endpoint`, `keys.p256dh`, and `keys.auth` shape and encrypts payloads using Web Push standards.
+
+## Troubleshooting
+
+<Accordions><Accordion title="Can I allow a private push relay?">Provide exact hostnames with `allowedEndpointHosts`.</Accordion></Accordions>
+
+## Next
+
+<Cards><Card title="Web Push transport" href="/docs/transports/webpush" /></Cards>

package/site/content/docs/index.mdx

@@ -0,0 +1,15 @@
+---
+title: sently handbook
+description: Channel-first messaging for email, SMS, WhatsApp, and web push.
+icon: BookOpen
+source: "README.md"
+---
+
+Use a channel sender in application code and put provider-specific configuration in a transport.
+
+<Cards>
+  <Card title="Get started" href="/docs/get-started" />
+  <Card title="Quick start" href="/docs/quick-start" />
+  <Card title="Channels" href="/docs/channels" />
+  <Card title="Transports" href="/docs/transports" />
+</Cards>

package/site/content/docs/meta.json

@@ -0,0 +1,15 @@
+{
+  "title": "Documentation",
+  "icon": "BookOpen",
+  "pages": [
+    "index",
+    "get-started",
+    "quick-start",
+    "channels",
+    "transports",
+    "decorators",
+    "guides",
+    "reference",
+    "ai"
+  ]
+}

package/site/content/docs/quick-start/email.mdx

@@ -0,0 +1,40 @@
+---
+title: Email
+description: Send email through an HTTP transport.
+icon: Mail
+source: "src/mailer.ts"
+---
+
+<Callout title="The one rule">`createMailer` is asynchronous; await it before sending.</Callout>
+
+<Steps>
+  <Step title="Create a transport-backed mailer">
+
+```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>
+  <Step title="Send email">
+
+```ts
+await mailer.send({
+  from: "hello@example.com",
+  to: "person@example.com",
+  subject: "Welcome",
+  text: "Thanks for joining.",
+});
+```
+
+  </Step>
+</Steps>
+
+<Cards>
+  <Card title="Email channel" href="/docs/channels/email" />
+  <Card title="Resend transport" href="/docs/transports/resend" />
+</Cards>

package/site/content/docs/quick-start/index.mdx

@@ -0,0 +1,15 @@
+---
+title: Quick start
+description: Send your first message on each channel.
+icon: Zap
+source: "README.md"
+---
+
+Pick a channel and send in a few lines. Same model every time — sender, transport, send.
+
+<Cards>
+  <Card title="Email" href="/docs/quick-start/email" />
+  <Card title="SMS" href="/docs/quick-start/sms" />
+  <Card title="WhatsApp" href="/docs/quick-start/whatsapp" />
+  <Card title="Push" href="/docs/quick-start/push" />
+</Cards>

package/site/content/docs/quick-start/meta.json

@@ -0,0 +1,5 @@
+{
+  "title": "Quick start",
+  "icon": "Zap",
+  "pages": ["index", "email", "sms", "whatsapp", "push"]
+}

package/site/content/docs/quick-start/push.mdx

@@ -0,0 +1,36 @@
+---
+title: Push
+description: Send a browser notification through a channel sender.
+icon: Bell
+source: "src/push.ts"
+---
+
+<Callout title="The one rule">Store the browser subscription and send it back unchanged as `subscription`.</Callout>
+
+<Steps>
+  <Step title="Create the 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">
+
+```ts
+await push.send({ subscription, title: "Update", body: "Your report is ready." });
+```
+
+  </Step>
+</Steps>
+
+<Cards><Card title="Push channel" href="/docs/channels/push" /></Cards>

package/site/content/docs/quick-start/sms.mdx

@@ -0,0 +1,36 @@
+---
+title: SMS
+description: Send an SMS through a channel sender.
+icon: MessageSquareText
+source: "src/sms.ts"
+---
+
+<Callout title="The one rule">Create the SMS sender once, then call `send` with `to` and `body`.</Callout>
+
+<Steps>
+  <Step title="Create the 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!,
+    from: "+15557654321",
+  }),
+});
+```
+
+  </Step>
+  <Step title="Send">
+
+```ts
+await sms.send({ to: "+15551234567", body: "Your code is ready." });
+```
+
+  </Step>
+</Steps>
+
+<Cards><Card title="SMS channel" href="/docs/channels/sms" /></Cards>

package/site/content/docs/quick-start/whatsapp.mdx

@@ -0,0 +1,38 @@
+---
+title: WhatsApp
+description: Send a WhatsApp message through a channel sender.
+icon: MessagesSquare
+source: "src/whatsapp.ts"
+---
+
+<Callout title="The one rule">Use a template outside the open customer-service window; use free text only inside it.</Callout>
+
+<Steps>
+  <Step title="Create the 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 a template">
+
+```ts
+await whatsapp.send({
+  to: "15551234567",
+  template: { name: "welcome", language: "en_US" },
+});
+```
+
+  </Step>
+</Steps>
+
+<Cards><Card title="WhatsApp channel" href="/docs/channels/whatsapp" /></Cards>

package/site/content/docs/reference/errors.mdx

@@ -0,0 +1,22 @@
+---
+title: Errors
+description: Handle stable sently error codes and provider-specific error instances.
+icon: CircleAlert
+source: "src/core/errors.ts"
+---
+
+All library transport and protocol failures derive from `SentlyError`; use `sentlyCode` for stable handling.
+
+```ts
+import { SentlyError } from "sently/errors";
+
+try {
+  await mailer.send(message);
+} catch (error) {
+  if (error instanceof SentlyError) console.error(error.sentlyCode);
+}
+```
+
+Provider error classes also retain provider response details where their transport exposes them.
+
+<Cards><Card title="Security" href="/docs/guides/security" /></Cards>

package/site/content/docs/reference/exports.mdx

@@ -0,0 +1,83 @@
+---
+title: Exports
+description: Public package entrypoints and what each one is for.
+icon: Boxes
+source: "package.json"
+---
+
+Import the channel sender and one transport subpath for the smallest install surface.
+The main `sently` package is for shared types and factories — not every provider.
+
+<Callout title="The one rule">
+  Prefer `sently/mailer` + `sently/transports/<provider>` (or the matching SMS / WhatsApp / push
+  entrypoints) over pulling providers from the main barrel.
+</Callout>
+
+## Channel and core
+
+| Import | Primary API |
+| ------ | ----------- |
+| `sently` | `createMailer`, `createSMTPMailer`, types, OAuth2, `SentlyError`, `consoleObserver`, `FallbackTransport`, `WeightedFallbackTransport`, `CloudflareEmailTransport` |
+| `sently/mailer` | `createMailer` only |
+| `sently/smtp` | `createSMTPMailer` |
+| `sently/sms` | `createSmsSender` |
+| `sently/whatsapp` | `createWhatsAppSender` |
+| `sently/push` | `createPushSender` |
+| `sently/errors` | `SentlyError` hierarchy |
+| `sently/idempotency` | `IdempotencyTransport` |
+| `sently/dkim` | DKIM signing |
+| `sently/react` | `reactPlugin` |
+| `sently/plugins/template` | template plugin |
+| `sently/auth/oauth2` | `OAuth2Client` |
+| `sently/pool` | `SMTPPool` |
+| `sently/observability` | `consoleObserver` |
+
+## Transports
+
+| Import | Use |
+| ------ | --- |
+| `sently/transports/<name>` | One provider or email decorator (e.g. `sndr`, `resend`, `twilio-sms`) |
+
+HTTP providers such as SNDR, Resend, and Plunk are **not** re-exported from `sently`.
+
+## Webhooks
+
+| Import | Use |
+| ------ | --- |
+| `sently/webhooks/<provider>` | One parser (+ verify helper when exported) |
+| `sently/webhooks` | Convenience barrel of all named helpers |
+
+Providers: `brevo`, `mailgun`, `postmark`, `resend`, `sendgrid`, `ses`, `sndr`.
+
+## Adapters
+
+| Import | Use |
+| ------ | --- |
+| `sently/adapters/node` | Node TCP/TLS |
+| `sently/adapters/bun` | Bun TCP/TLS |
+| `sently/adapters/deno` | Deno TCP/TLS |
+| `sently/adapters/cf` | Cloudflare `cloudflare:sockets` |
+
+## Troubleshooting
+
+<Accordions>
+
+<Accordion title="Why is SndrTransport missing from import sently?">
+
+Provider transports live on `sently/transports/*` so bare Node/Deno imports of `sently` do not load every HTTP client. Use `sently/transports/sndr`.
+
+</Accordion>
+
+</Accordions>
+
+## Learn more
+
+- [Entrypoints](/docs/get-started/entrypoints) — which import to pick first
+- [Bundle size](/docs/guides/bundle-size) — measured stacks
+
+## Next
+
+<Cards>
+  <Card title="Entrypoints" description="Choose a channel import path." href="/docs/get-started/entrypoints" />
+  <Card title="Transports" description="Provider list by channel." href="/docs/transports" />
+</Cards>

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

@@ -0,0 +1,15 @@
+---
+title: Reference
+description: Public types, exports, and normalized events.
+icon: FolderOpen
+source: "README.md"
+---
+
+Public types, exports, and normalized events.
+
+<Cards>
+  <Card title="Exports" href="/docs/reference/exports" />
+  <Card title="Mail options" href="/docs/reference/mail-options" />
+  <Card title="Transport contracts" href="/docs/reference/transport-contracts" />
+  <Card title="Errors" href="/docs/reference/errors" />
+</Cards>

package/site/content/docs/reference/mail-options.mdx

@@ -0,0 +1,22 @@
+---
+title: Mail options
+description: Fields accepted by `mailer.send` and `mailer.sendBulk`.
+icon: Mail
+source: "src/core/types.ts"
+---
+
+| Field | Type |
+| --- | --- |
+| `from`, `to` | `AddressInput` |
+| `subject` | `string` |
+| `text`, `html` | `string` |
+| `cc`, `bcc`, `replyTo` | `AddressInput` |
+| `attachments` | `Attachment[]` |
+| `headers` | `Record<string, string>` |
+| `messageId`, `idempotencyKey` | `string` |
+| `template`, `data` | template plugin fields |
+| `react` | React plugin field |
+
+`AddressInput` accepts a string, `{ address, name? }`, or an array of either.
+
+<Cards><Card title="Attachments" href="/docs/guides/attachments" /></Cards>

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

@@ -0,0 +1,15 @@
+{
+  "title": "Reference",
+  "icon": "Code",
+  "pages": [
+    "index",
+    "exports",
+    "mail-options",
+    "sms-options",
+    "whatsapp-options",
+    "push-options",
+    "transport-contracts",
+    "errors",
+    "webhook-events"
+  ]
+}

package/site/content/docs/reference/push-options.mdx

@@ -0,0 +1,20 @@
+---
+title: Push options
+description: Fields accepted by `PushSender.send`.
+icon: Bell
+source: "src/core/push-types.ts"
+---
+
+| Field | Type | Required |
+| --- | --- | --- |
+| `subscription` | `PushSubscription` | yes |
+| `title` | `string` | yes |
+| `body` | `string` | yes |
+| `data` | `Record<string, unknown>` | no |
+| `icon` | `string` | no |
+| `ttl` | `number` | no |
+| `messageId` | `string` | no |
+
+A subscription contains `endpoint`, `keys.p256dh`, and `keys.auth`.
+
+<Cards><Card title="Push channel" href="/docs/channels/push" /></Cards>

package/site/content/docs/reference/sms-options.mdx

@@ -0,0 +1,17 @@
+---
+title: SMS options
+description: Fields accepted by `SmsSender.send`.
+icon: MessageSquare
+source: "src/core/sms-types.ts"
+---
+
+| Field | Type | Required |
+| --- | --- | --- |
+| `to` | `string` | yes |
+| `body` | `string` | yes |
+| `from` | `string` | no |
+| `messageId` | `string` | no |
+
+The result includes `messageId`, `to`, `status`, `response`, and optional `provider`.
+
+<Cards><Card title="SMS channel" href="/docs/channels/sms" /></Cards>

package/site/content/docs/reference/transport-contracts.mdx

@@ -0,0 +1,17 @@
+---
+title: Transport contracts
+description: Implement a channel transport to integrate a provider not shipped by sently.
+icon: FileType
+source: "src/core/types.ts"
+---
+
+| Contract | Required method | Optional methods |
+| --- | --- | --- |
+| `Transport` | `send(MailOptions)` | `sendBatch`, `verify`, `close` |
+| `SmsTransport` | `send(SmsOptions)` | `verify`, `close` |
+| `WhatsAppTransport` | `send(WhatsAppOptions)` | `verify`, `close` |
+| `PushTransport` | `send(PushOptions)` | `verify`, `close` |
+
+Each contract can expose a stable optional `provider` identifier for hooks and observability.
+
+<Cards><Card title="Channels" href="/docs/channels" /></Cards>

package/site/content/docs/reference/webhook-events.mdx

@@ -0,0 +1,70 @@
+---
+title: Webhook events
+description: Normalized EmailEvent fields returned by every provider webhook parser.
+icon: Webhook
+source: "src/webhooks/types.ts"
+---
+
+Every parser returns `EmailEvent[]` so delivery webhooks can share one application pipeline.
+Verify signatures in the [webhooks guide](/docs/guides/webhooks) before you process events.
+
+<Callout title="The one rule">
+  Branch on `event.type` and keep provider-specific details in `event.raw` when you need them.
+</Callout>
+
+## EmailEvent
+
+| Field | Type | Meaning |
+| ----- | ---- | ------- |
+| `provider` | `string` | Parser id (e.g. `"sndr"`, `"resend"`). |
+| `type` | union below | Normalized lifecycle type. |
+| `messageId` | `string?` | Provider message id when present. |
+| `recipient` | `string?` | Primary recipient when present. |
+| `timestamp` | `Date?` | Event time when present. |
+| `raw` | `unknown` | Original provider payload. |
+
+## Normalized `type` values
+
+| Value | Meaning |
+| ----- | ------- |
+| `delivered` | Accepted / delivered to the mailbox provider. |
+| `bounced` | Hard failure or bounce. |
+| `complained` | Spam complaint. |
+| `opened` | Open tracking. |
+| `clicked` | Click tracking. |
+| `deferred` | Temporary deferral. |
+| `unknown` | Unmapped or informational provider event. |
+
+## SNDR mapping
+
+| SNDR `type` | Normalized `type` |
+| ----------- | ----------------- |
+| `email.delivered` | `delivered` |
+| `email.bounced` | `bounced` |
+| `email.unsubscribed` | `unknown` |
+
+SNDR `data.email_id` becomes `messageId`. Recipients come from `data.to` or `data.addresses`.
+
+## Troubleshooting
+
+<Accordions>
+
+<Accordion title="Why is unsubscribed mapped to unknown?">
+
+The shared `EmailEvent.type` union has no unsubscribe value. Keep the vendor payload in `raw` if you need unsubscribe-specific handling.
+
+</Accordion>
+
+</Accordions>
+
+## Learn more
+
+- [Webhooks guide](/docs/guides/webhooks) — verify + parse flow
+- [SNDR transport](/docs/transports/sndr) — sending side
+
+## Next
+
+<Cards>
+  <Card title="Webhooks" description="Parse and verify provider payloads." href="/docs/guides/webhooks" />
+  <Card title="Exports" description="Package entrypoints." href="/docs/reference/exports" />
+</Cards>