sently 1.0.0 → 1.1.1

package/site/content/docs/get-started/support-matrix.mdx

@@ -29,11 +29,11 @@ FCM uses the current Firebase HTTP API (service-account JWT, no Google SDK). Tha
 
 | Channel | Available examples |
 | --- | --- |
-| Email | Mailgun, Brevo, MailerSend, Plunk, SparkPost, Mailtrap, Mailpit (dev), Loops, SNDR, Taqnyat Mail, Cloudflare Email, … |
+| Email | Mailgun, Brevo, MailerSend, Plunk, SparkPost, Mailtrap, Mailpit (dev), Inbucket (dev), Loops, SNDR, Taqnyat Mail, Cloudflare Email, … |
 | SMS | Taqnyat SMS, Msegat |
 | WhatsApp | Taqnyat WhatsApp |
 | Decorators | `WeightedFallbackTransport` (advanced); preview / idempotency remain email-only |
-| Local email | [Mailpit](/docs/transports/mailpit) (SMTP catcher), [Preview](/docs/decorators/preview) (disk) |
+| Local email | [Mailpit](/docs/transports/mailpit) / [Inbucket](/docs/transports/inbucket) (SMTP catchers), [Preview](/docs/decorators/preview) (disk) |
 
 Available transports stay in the package. They are promoted to Supported when docs, operability, and smoke coverage meet the bar above.
 

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

@@ -14,5 +14,6 @@ await msegat.verifyOtp({ id: otp.id, code: "1234", lang: "En" });
 ```
 
 Taqnyat SMS also exposes `sendOtp` and `verifyOtp` on its transport.
+See [Taqnyat](/docs/transports/taqnyat#sms-vendor-extras) for balance, senders, schedule, WhatsApp templates, opt-in, and failover extras.
 
-<Cards><Card title="Msegat" href="/docs/transports/msegat" /><Card title="Taqnyat SMS" href="/docs/transports/taqnyat-sms" /></Cards>
+<Cards><Card title="Msegat" href="/docs/transports/msegat" /><Card title="Taqnyat" href="/docs/transports/taqnyat#sms" /></Cards>

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

@@ -99,6 +99,8 @@ 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.
 
+Normalized event types include queued → `deferred`, delivered, bounced, complained, opened, clicked, and failed / unsubscribed → `unknown`. See [SNDR](/docs/transports/sndr#webhooks).
+
 Default timestamp tolerance is 300 seconds. Pass `{ toleranceSeconds: 0 }` to disable the freshness check.
 
 ## Troubleshooting

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

@@ -8,10 +8,18 @@ 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.
+Generate server keys with `generateVapidKeys()` from `sently/transports/webpush` and use the same public key in `pushManager.subscribe({ applicationServerKey })`.
 
 ## Troubleshooting
 
-<Accordions><Accordion title="Can I allow a private push relay?">Provide exact hostnames with `allowedEndpointHosts`.</Accordion></Accordions>
+<Accordions>
+  <Accordion title="Can I allow a private push relay?">
+    Provide exact hostnames with `allowedEndpointHosts`.
+  </Accordion>
+  <Accordion title="Can I send without showing a notification?">
+    Pass `data` without `title` / `body`, or set `silent: true` with `data`. The service worker must handle `push` without calling `showNotification`.
+  </Accordion>
+</Accordions>
 
 ## Next
 

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

@@ -37,7 +37,7 @@ The main `sently` package is for shared types and factories — not every provid
 
 | Import | Use |
 | ------ | --- |
-| `sently/transports/<name>` | One provider or decorator (e.g. `sndr`, `mailpit`, `fcm`, `retry`) |
+| `sently/transports/<name>` | One provider or decorator (e.g. `sndr`, `inbucket`, `fcm`, `retry`) |
 
 HTTP providers such as SNDR, Resend, and Plunk are **not** re-exported from `sently`.
 

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

@@ -16,9 +16,9 @@ Pick the shape that matches your transport.
 
 | Field | Type | Required |
 | --- | --- | --- |
-| `title` | `string` | yes |
-| `body` | `string` | yes |
-| `data` | `Record<string, unknown>` | no |
+| `title` | `string` | FCM always; Web Push for visible notifications |
+| `body` | `string` | FCM always; Web Push for visible notifications |
+| `data` | `Record<string, unknown>` | no (required for Web Push `silent` / data-only) |
 | `icon` | `string` | no |
 | `ttl` | `number` | no |
 | `messageId` | `string` | no |
@@ -28,14 +28,27 @@ Pick the shape that matches your transport.
 | Field | Type | Required |
 | --- | --- | --- |
 | `subscription` | `PushSubscription` | yes |
+| `urgency` | `"very-low" \| "low" \| "normal" \| "high"` | no — RFC 8030 header |
+| `topic` | `string` | no — 1–32 printable ASCII collapse key |
+| `badge` | `string` | no |
+| `image` | `string` | no |
+| `tag` | `string` | no |
+| `actions` | `{ action, title, icon? }[]` | no |
+| `requireInteraction` | `boolean` | no |
+| `renotify` | `boolean` | no |
+| `silent` | `boolean` | no — encrypt only `data` |
 
 A subscription contains `endpoint`, `keys.p256dh`, and `keys.auth`.
 
+Omit `title` / `body` and pass `data` for a data-only Web Push (or set `silent: true`).
+
 ## FCM
 
 | Field | Type | Required |
 | --- | --- | --- |
 | `token` | `string` | yes |
+| `title` | `string` | yes |
+| `body` | `string` | yes |
 | `image` | `string` | no |
 
 FCM stringifies non-string `data` values before send.
@@ -58,18 +71,22 @@ Map any channel result with [channel send result](./channel-result).
   <Accordion title="Can I send both subscription and token?">
     No. Each call is either Web Push (`subscription`) or FCM (`token`). Match the shape to the transport.
   </Accordion>
+  <Accordion title="Can FCM send silent / data-only the same way?">
+    No. FCM still requires `title` and `body` on this union. Use Web Push `silent` / data-only for background browser sync.
+  </Accordion>
 </Accordions>
 
 ## Learn more
 
 - [Push channel](/docs/channels/push)
-- [Stability policy](/docs/get-started/stability) — union shape is frozen at 1.x
+- [Web Push transport](/docs/transports/webpush)
+- [Stability policy](/docs/get-started/stability) — optional fields may grow in 1.x
 - [Channel send result](./channel-result)
 
 ## Next
 
 <Cards>
   <Card title="Push channel" href="/docs/channels/push" />
-  <Card title="FCM transport" href="/docs/transports/fcm" />
+  <Card title="Web Push transport" href="/docs/transports/webpush" />
   <Card title="Channel send result" href="/docs/reference/channel-result" />
 </Cards>

package/site/content/docs/transports/inbucket.mdx

@@ -0,0 +1,200 @@
+---
+title: Inbucket
+description: Catch outbound email in a local Inbucket instance during development.
+icon: Inbox
+source: "src/transports/inbucket.ts"
+---
+
+Catch outbound email in a local [Inbucket](https://inbucket.org/) instance while you develop.
+Use it for the welcome email or password-reset flow before you point at a production provider.
+
+<LiveVerified>
+Email send against a local Inbucket instance succeeded in sently’s live suite (SMTP capture + REST list/get/source/markSeen/purge).
+</LiveVerified>
+
+<Callout title="The one rule">
+  Use Inbucket only in development — swap to a production transport before you deploy.
+  Vendor extras stay on the `InbucketTransport` instance — never on `createMailer`.
+</Callout>
+
+## Quick start
+
+Start Inbucket (SMTP `2500`, UI `9000`):
+
+```sh
+docker run -d --rm --name inbucket -p 9000:9000 -p 2500:2500 -p 1100:1100 inbucket/inbucket
+```
+
+<Steps>
+  <Step title="Create the transport">
+
+```ts
+import { createMailer } from "sently/mailer";
+import { InbucketTransport } from "sently/transports/inbucket";
+
+const inbucket = new InbucketTransport();
+const mailer = await createMailer({ transport: inbucket });
+```
+
+  </Step>
+  <Step title="Send through the mailer">
+
+```ts
+await mailer.send({
+  from: "dev@example.com",
+  to: "you@example.com",
+  subject: "Hello",
+  text: "Captured by Inbucket",
+});
+```
+
+  </Step>
+  <Step title="Inspect the mailbox">
+
+Open `http://localhost:9000`, or list messages from code.
+Stock Inbucket stores `you@example.com` under mailbox `you`:
+
+```ts
+const mailbox = inbucket.mailboxForAddress("you@example.com");
+const inbox = await inbucket.listMailbox(mailbox);
+console.log(inbox[0]?.subject);
+```
+
+  </Step>
+</Steps>
+
+## Configuration
+
+| Option | Type | Default | Meaning |
+| --- | --- | --- | --- |
+| `host` | `string` | `"localhost"` | SMTP hostname |
+| `port` | `number` | `2500` | SMTP port |
+| `secure` | `boolean` | `false` | Implicit TLS on connect |
+| `requireTLS` | `boolean` | `false` | Refuse AUTH without TLS |
+| `auth` | `SMTPAuth` | — | Optional SMTP credentials |
+| `tls` | `TLSOptions` | — | TLS options when TLS is enabled |
+| `connectionTimeout` | `number` | — | Socket connect timeout (ms) |
+| `adapter` | `SocketAdapter` | auto-detected | Runtime TCP adapter |
+| `apiUrl` | `string` | `"http://localhost:9000"` | Web UI / REST API base |
+| `mailboxNaming` | `"local" \| "full" \| "domain"` | `"local"` | How `mailboxForAddress` maps an email |
+
+`provider` is `"inbucket"`. `verify()` checks SMTP; `close()` closes the socket adapter.
+`webUrl` is the UI base (same as `apiUrl`).
+
+## Features
+
+Pick a branch. Channel send goes through `mailer`; everything else is called on `inbucket`.
+Inbucket is mailbox-centric — pass a mailbox name (or derive it with `mailboxForAddress`).
+
+<Tabs items={["Send", "List", "Message", "Source", "Mark seen", "Delete", "Purge"]}>
+  <Tab value="Send">
+
+Transactional send via the channel mailer (SMTP into Inbucket).
+
+```ts
+await mailer.send({
+  from: "dev@example.com",
+  to: "you@example.com",
+  subject: "Welcome",
+  html: "<h1>Hello</h1>",
+  text: "Hello",
+});
+```
+
+  </Tab>
+  <Tab value="List">
+
+List messages in a mailbox (`GET /api/v1/mailbox/{name}`).
+
+```ts
+const mailbox = inbucket.mailboxForAddress("you@example.com");
+const inbox = await inbucket.listMailbox(mailbox);
+console.log(inbox.length, inbox[0]?.subject);
+```
+
+  </Tab>
+  <Tab value="Message">
+
+Full body, headers, and attachments for a message id.
+
+```ts
+const full = await inbucket.getMessage(mailbox, inbox[0]!.id);
+console.log(full.body.text, full.body.html, full.header.Subject);
+```
+
+  </Tab>
+  <Tab value="Source">
+
+Raw RFC822 source (`GET …/source`) for MIME assertions.
+
+```ts
+const source = await inbucket.getSource(mailbox, inbox[0]!.id);
+console.log(source.includes("Subject: Welcome"));
+```
+
+  </Tab>
+  <Tab value="Mark seen">
+
+Mark one message as seen (`PATCH` with `{ seen: true }`).
+
+```ts
+await inbucket.markSeen(mailbox, inbox[0]!.id);
+```
+
+  </Tab>
+  <Tab value="Delete">
+
+Delete one message by id.
+
+```ts
+await inbucket.deleteMessage(mailbox, inbox[0]!.id);
+```
+
+  </Tab>
+  <Tab value="Purge">
+
+Clear every message in a mailbox.
+
+```ts
+await inbucket.purgeMailbox(mailbox);
+```
+
+  </Tab>
+</Tabs>
+
+REST failures throw `InbucketError` (`provider: "inbucket"`).
+Empty mailbox / id arguments throw with status `400`.
+
+## Troubleshooting
+
+<Accordions>
+  <Accordion title="Connection refused on port 2500">
+    Inbucket is not running, or the SMTP port is remapped. Start the container above, or set `host` / `port` to match your install.
+  </Accordion>
+  <Accordion title="listMailbox returns empty after send">
+    Check mailbox naming. Stock Inbucket uses the local-part (`you` for `you@example.com`).
+    If your instance sets `INBUCKET_MAILBOXNAMING=full` or `domain`, match that with `mailboxNaming`.
+  </Accordion>
+  <Accordion title="API helpers fail but send works">
+    SMTP and the UI/API can bind to different hosts. Set `apiUrl` to the web base (default `http://localhost:9000`).
+  </Accordion>
+  <Accordion title="Should I use createSMTPMailer instead?">
+    Yes, if you only need SMTP. `InbucketTransport` adds local defaults and REST helpers for tests and inspection.
+  </Accordion>
+</Accordions>
+
+## Learn more
+
+- [Mailpit](./mailpit) — another local SMTP catcher with a different REST shape
+- [SMTP](./smtp) — generic SMTP when you are not on a catcher
+- [Preview](/docs/decorators/preview) — write `.eml` files to disk instead
+- [Email channel](/docs/channels/email) — `createMailer` contract
+- [Inbucket REST API](https://github.com/inbucket/inbucket/wiki/REST-API) — mailbox endpoints on the catcher
+
+## Next
+
+<Cards>
+  <Card title="Mailpit" href="/docs/transports/mailpit" />
+  <Card title="Email channel" href="/docs/channels/email" />
+  <Card title="Transports" href="/docs/transports" />
+</Cards>

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

@@ -57,18 +57,17 @@ Every import below is an exported package subpath.
 | [SparkPost](./sparkpost) | Email | `sently/transports/sparkpost` |
 | [Mailtrap](./mailtrap) | Email | `sently/transports/mailtrap` |
 | [Mailpit](./mailpit) | Email (dev) | `sently/transports/mailpit` |
+| [Inbucket](./inbucket) | Email (dev) | `sently/transports/inbucket` |
 | [Loops](./loops) | Email | `sently/transports/loops` |
 | [Cloudflare Email](./cloudflare-email) | Email | `sently/transports/cloudflare-email` |
 | [SNDR](./sndr) | Email | `sently/transports/sndr` |
-| [Taqnyat Mail](./taqnyat-mail) | Email | `sently/transports/taqnyat-mail` |
 | [Twilio SMS](./twilio-sms) | SMS | `sently/transports/twilio-sms` |
-| [Taqnyat SMS](./taqnyat-sms) | SMS | `sently/transports/taqnyat-sms` |
 | [Msegat](./msegat) | SMS | `sently/transports/msegat` |
 | [Unifonic](./unifonic) | SMS | `sently/transports/unifonic` |
 | [WhatsApp Cloud](./whatsapp-cloud) | WhatsApp | `sently/transports/whatsapp-cloud` |
-| [Taqnyat WhatsApp](./taqnyat-whatsapp) | WhatsApp | `sently/transports/taqnyat-whatsapp` |
 | [Web Push](./webpush) | Push | `sently/transports/webpush` |
 | [FCM](./fcm) | Push | `sently/transports/fcm` |
+| [Taqnyat](./taqnyat) | Email · SMS · WhatsApp | `sently/transports/taqnyat-mail`, `taqnyat-sms`, `taqnyat-whatsapp` |
 
 For retry, fallback, preview, and idempotency wrappers, see [Decorators](../decorators).
 

package/site/content/docs/transports/mailpit.mdx

@@ -8,8 +8,13 @@ source: "src/transports/mailpit.ts"
 Catch outbound email in a local [Mailpit](https://github.com/axllent/mailpit) instance while you develop.
 Use it for the welcome email or password-reset flow before you point at a production provider.
 
+<LiveVerified>
+Email send against a local Mailpit instance succeeded in sently’s integration suite (SMTP capture + REST list/get).
+</LiveVerified>
+
 <Callout title="The one rule">
   Use Mailpit only in development — swap to a production transport before you deploy.
+  Vendor extras stay on the `MailpitTransport` instance — never on `createMailer`.
 </Callout>
 
 ## Quick start
@@ -72,27 +77,117 @@ console.log(inbox.messages[0]?.Subject);
 | `apiAuth` | `{ user, pass }` | — | Basic auth for the UI/API |
 
 `provider` is `"mailpit"`. `verify()` checks SMTP; `close()` closes the socket adapter.
+`webUrl` is the UI base (same as `apiUrl`).
+
+## Features
 
-## REST helpers
+Pick a branch. Channel send goes through `mailer`; everything else is called on `mailpit`.
+Message ids may be a Mailpit id or `"latest"`.
 
-Vendor extras stay on the transport instance (not on `createMailer`):
+<Tabs items={["Send", "List", "Search", "Message", "Headers", "HTML check", "Link check", "Read", "Delete"]}>
+  <Tab value="Send">
 
-| Method | Mailpit API | Meaning |
-| --- | --- | --- |
-| `messages({ limit?, start? })` | `GET /api/v1/messages` | List captured messages (newest first) |
-| `getMessage(id)` | `GET /api/v1/message/{id}` | Full message body |
-| `deleteMessages(ids)` | `DELETE /api/v1/messages` | Delete by id |
-| `deleteAll()` | `DELETE` with empty `IDs` | Clear the inbox |
-| `webUrl` | — | UI base URL (same as `apiUrl`) |
+Transactional send via the channel mailer (SMTP into Mailpit).
 
 ```ts
+await mailer.send({
+  from: "dev@example.com",
+  to: "you@example.com",
+  subject: "Welcome",
+  html: "<h1>Hello</h1><a href=\"https://example.com\">Go</a>",
+  text: "Hello",
+});
+```
+
+  </Tab>
+  <Tab value="List">
+
+List captured messages (`GET /api/v1/messages`), newest first.
+
+```ts
+const inbox = await mailpit.messages({ limit: 10, start: 0 });
+console.log(inbox.total, inbox.messages[0]?.Subject);
+```
+
+  </Tab>
+  <Tab value="Search">
+
+Find a message with Mailpit’s query syntax (`subject:`, `to:`, `tag:`, …).
+
+```ts
+const found = await mailpit.search("subject:Welcome", { limit: 1 });
+console.log(found.messages[0]?.ID);
+```
+
+  </Tab>
+  <Tab value="Message">
+
+Full body for the message id (or `"latest"`).
+
+```ts
+const full = await mailpit.getMessage("latest");
+console.log(full.Text, full.HTML);
+```
+
+  </Tab>
+  <Tab value="Headers">
+
+Header map for assertions (`Message-Id`, custom headers, …).
+
+```ts
+const headers = await mailpit.getHeaders("latest");
+console.log(headers.Subject, headers["Message-Id"]);
+```
+
+  </Tab>
+  <Tab value="HTML check">
+
+Client HTML/CSS compatibility score from Mailpit’s checker.
+
+```ts
+const html = await mailpit.htmlCheck("latest");
+console.log(html.Total.Supported, html.Total.Unsupported, html.Warnings.length);
+```
+
+Needs an HTML part — plain-text-only messages can return `400`.
+
+  </Tab>
+  <Tab value="Link check">
+
+Probe links and images in the message (`follow` optional).
+
+```ts
+const links = await mailpit.linkCheck("latest", { follow: true });
+console.log(links.Errors, links.Links);
+```
+
+  </Tab>
+  <Tab value="Read">
+
+Mark messages read or unread between assertions.
+
+```ts
+const inbox = await mailpit.messages({ limit: 1 });
+await mailpit.setRead([inbox.messages[0]!.ID], true);
+// empty ids → update every message
+await mailpit.setRead([], false);
+```
+
+  </Tab>
+  <Tab value="Delete">
+
+Delete by id, or clear the whole inbox.
+
+```ts
+await mailpit.deleteMessages(["abc"]);
 await mailpit.deleteAll();
-await mailer.send({ from: "a@test.com", to: "b@test.com", subject: "T", text: "ok" });
-const list = await mailpit.messages({ limit: 1 });
-const full = await mailpit.getMessage(list.messages[0]!.ID);
 ```
 
-REST failures throw `MailpitError` (`provider: "mailpit"`). Empty `getMessage("")` throws with status `400`.
+  </Tab>
+</Tabs>
+
+REST failures throw `MailpitError` (`provider: "mailpit"`).
+Empty `getMessage("")` / `search("")` throws with status `400`.
 
 ## Troubleshooting
 
@@ -103,6 +198,9 @@ REST failures throw `MailpitError` (`provider: "mailpit"`). Empty `getMessage(""
   <Accordion title="API helpers fail but send works">
     SMTP and the UI/API can bind to different hosts. Set `apiUrl` (and `apiAuth` if the UI requires Basic auth).
   </Accordion>
+  <Accordion title="htmlCheck returns 400">
+    The message has no HTML part, or Mailpit could not parse it. Send `html` (not only `text`) and retry with `"latest"` or the message id.
+  </Accordion>
   <Accordion title="Should I use createSMTPMailer instead?">
     Yes, if you only need SMTP. `MailpitTransport` adds local defaults and REST helpers for tests and inspection.
   </Accordion>
@@ -110,14 +208,16 @@ REST failures throw `MailpitError` (`provider: "mailpit"`). Empty `getMessage(""
 
 ## Learn more
 
+- [Inbucket](./inbucket) — another local SMTP catcher with a mailbox REST API
 - [SMTP](./smtp) — generic SMTP when you are not on Mailpit
 - [Preview](/docs/decorators/preview) — write `.eml` files to disk instead
 - [Email channel](/docs/channels/email) — `createMailer` contract
+- [Mailpit API](https://mailpit.axllent.org/docs/api-v1/) — full REST surface on the catcher
 
 ## Next
 
 <Cards>
+  <Card title="Inbucket" href="/docs/transports/inbucket" />
   <Card title="Email channel" href="/docs/channels/email" />
-  <Card title="SMTP" href="/docs/transports/smtp" />
   <Card title="Transports" href="/docs/transports" />
 </Cards>

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

@@ -3,6 +3,8 @@
   "icon": "Truck",
   "pages": [
     "index",
+    "---Multi-channel---",
+    "taqnyat",
     "---Email---",
     "smtp",
     "resend",
@@ -15,19 +17,18 @@
     "plunk",
     "sparkpost",
     "mailtrap",
-    "mailpit",
     "loops",
     "cloudflare-email",
     "sndr",
-    "taqnyat-mail",
+    "---Email Dev---",
+    "mailpit",
+    "inbucket",
     "---SMS---",
     "twilio-sms",
-    "taqnyat-sms",
     "msegat",
     "unifonic",
     "---WhatsApp---",
     "whatsapp-cloud",
-    "taqnyat-whatsapp",
     "---Push---",
     "webpush",
     "fcm"

package/site/content/docs/transports/smtp.mdx

@@ -55,7 +55,7 @@ await mailer.send({
 | `pool` | `boolean` | `false` |
 | `dkim` | `DKIMConfig` | optional |
 
-For local capture with defaults and REST helpers, use [Mailpit](./mailpit) instead of hand-wiring `localhost:1025`.
+For local capture with defaults and REST helpers, use [Mailpit](./mailpit) or [Inbucket](./inbucket) instead of hand-wiring SMTP ports.
 
 ## Troubleshooting
 
@@ -67,13 +67,14 @@ For local capture with defaults and REST helpers, use [Mailpit](./mailpit) inste
     Pass an explicit transport, or use `createSMTPMailer` for relay configuration.
   </Accordion>
   <Accordion title="Local development without a real relay">
-    Use [Mailpit](./mailpit) (`sently/transports/mailpit`) or [Preview](/docs/decorators/preview).
+    Use [Mailpit](./mailpit), [Inbucket](./inbucket), or [Preview](/docs/decorators/preview).
   </Accordion>
 </Accordions>
 
 ## Learn more
 
 - [Mailpit](./mailpit) — local SMTP catcher with inbox API
+- [Inbucket](./inbucket) — local SMTP catcher with mailbox REST API
 - [Email channel](/docs/channels/email) — `createMailer` / `createSMTPMailer`
 - [Runtimes](/docs/get-started/runtimes) — socket adapters