sently 0.10.0 → 1.0.1

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

@@ -0,0 +1,123 @@
+---
+title: Mailpit
+description: Catch outbound email in a local Mailpit instance during development.
+icon: Inbox
+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.
+
+<Callout title="The one rule">
+  Use Mailpit only in development — swap to a production transport before you deploy.
+</Callout>
+
+## Quick start
+
+Start Mailpit (SMTP `1025`, UI `8025`):
+
+```sh
+docker run -d --rm -p 1025:1025 -p 8025:8025 axllent/mailpit
+```
+
+<Steps>
+  <Step title="Create the transport">
+
+```ts
+import { createMailer } from "sently/mailer";
+import { MailpitTransport } from "sently/transports/mailpit";
+
+const mailpit = new MailpitTransport();
+const mailer = await createMailer({ transport: mailpit });
+```
+
+  </Step>
+  <Step title="Send through the mailer">
+
+```ts
+await mailer.send({
+  from: "dev@example.com",
+  to: "you@example.com",
+  subject: "Hello",
+  text: "Captured by Mailpit",
+});
+```
+
+  </Step>
+  <Step title="Inspect the inbox">
+
+Open `http://localhost:8025`, or list messages from code:
+
+```ts
+const inbox = await mailpit.messages();
+console.log(inbox.messages[0]?.Subject);
+```
+
+  </Step>
+</Steps>
+
+## Configuration
+
+| Option | Type | Default | Meaning |
+| --- | --- | --- | --- |
+| `host` | `string` | `"localhost"` | SMTP hostname |
+| `port` | `number` | `1025` | 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:8025"` | Web UI / REST API base |
+| `apiAuth` | `{ user, pass }` | — | Basic auth for the UI/API |
+
+`provider` is `"mailpit"`. `verify()` checks SMTP; `close()` closes the socket adapter.
+
+## REST helpers
+
+Vendor extras stay on the transport instance (not on `createMailer`):
+
+| 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`) |
+
+```ts
+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`.
+
+## Troubleshooting
+
+<Accordions>
+  <Accordion title="Connection refused on port 1025">
+    Mailpit is not running, or the SMTP port is remapped. Start the container above, or set `host` / `port` to match your install.
+  </Accordion>
+  <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="Should I use createSMTPMailer instead?">
+    Yes, if you only need SMTP. `MailpitTransport` adds local defaults and REST helpers for tests and inspection.
+  </Accordion>
+</Accordions>
+
+## Learn more
+
+- [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
+
+## Next
+
+<Cards>
+  <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

@@ -15,6 +15,7 @@
     "plunk",
     "sparkpost",
     "mailtrap",
+    "mailpit",
     "loops",
     "cloudflare-email",
     "sndr",

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

@@ -1,47 +1,86 @@
 ---
 title: SMTP
-description: Connect to an SMTP relay with an explicit transport.
+description: Connect to an SMTP relay with host, port, and auth.
 icon: Truck
 source: "src/transports/smtp.ts"
 ---
 
-Connect to an SMTP relay with an explicit transport.
+Connect to an SMTP relay for production or a local catcher.
+Prefer `createSMTPMailer` when your config starts with host and port — it picks a runtime adapter for you.
 
-<Callout title="The one rule">Create this transport under the matching sently channel sender.</Callout>
+<Callout title="The one rule">
+  Use `createSMTPMailer` for host/port config; use `createMailer` only with an explicit `SMTPTransport` that already has an adapter.
+</Callout>
 
-## Configuration
-
-| Option | Type | Default or requirement |
-| --- | --- | --- |
-| `host` | `string` | required |
-| `port` | `number` | 587 or 465 based on secure |
-| `secure` | `boolean` | false |
-| `auth` | `SMTPAuth` | optional |
-| `requireTLS` | `boolean` | true when auth is set |
-| `adapter` | `SocketAdapter` | optional |
-| `pool` | `boolean` | false |
-| `dkim` | `DKIMConfig` | optional |
+## Quick start
 
 <Steps>
-  <Step title="Configure the transport">
+  <Step title="Create an SMTP mailer">
 
 ```ts
-import { createMailer } from "sently/mailer";
-import { SMTPTransport } from "sently/transports/smtp";
+import { createSMTPMailer } from "sently/smtp";
 
-const sender = createMailer({ transport: new SMTPTransport({ host: "smtp.example.com", auth: { user: "user@example.com", pass: "..." } }) });
+const mailer = await createSMTPMailer({
+  host: "smtp.example.com",
+  port: 587,
+  auth: { user: "you@example.com", pass: process.env.SMTP_PASSWORD! },
+});
 ```
 
   </Step>
   <Step title="Send with the channel API">
 
 ```ts
-await sender.send({ from: "hello@example.com", to: "person@example.com", subject: "Hello", text: "Hi" });
+await mailer.send({
+  from: "hello@example.com",
+  to: "person@example.com",
+  subject: "Hello",
+  text: "Hi",
+});
 ```
 
   </Step>
 </Steps>
 
-<Accordions><Accordion title="Should I call the provider SDK?">No. Use the sently sender; provider-specific extras stay on the transport instance.</Accordion></Accordions>
+## Configuration
+
+| Option | Type | Default or requirement |
+| --- | --- | --- |
+| `host` | `string` | required |
+| `port` | `number` | `587`, or `465` when `secure` |
+| `secure` | `boolean` | `false` |
+| `auth` | `SMTPAuth` | optional |
+| `requireTLS` | `boolean` | `true` when `auth` is set |
+| `adapter` | `SocketAdapter` | auto via `createSMTPMailer` |
+| `pool` | `boolean` | `false` |
+| `dkim` | `DKIMConfig` | optional |
+
+For local capture with defaults and REST helpers, use [Mailpit](./mailpit) instead of hand-wiring `localhost:1025`.
+
+## Troubleshooting
+
+<Accordions>
+  <Accordion title="Should I call the provider SDK?">
+    No. Use the sently sender; provider-specific extras stay on the transport instance.
+  </Accordion>
+  <Accordion title="createMailer rejects host and port">
+    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).
+  </Accordion>
+</Accordions>
+
+## Learn more
+
+- [Mailpit](./mailpit) — local SMTP catcher with inbox API
+- [Email channel](/docs/channels/email) — `createMailer` / `createSMTPMailer`
+- [Runtimes](/docs/get-started/runtimes) — socket adapters
+
+## Next
 
-<Cards><Card title="Email channel" href="/docs/channels/email" /></Cards>
+<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/webpush.mdx

@@ -15,7 +15,7 @@ Encrypt and send browser notifications with VAPID.
 | --- | --- | --- |
 | `vapidPublicKey` | `string` | required |
 | `vapidPrivateKey` | `string` | required |
-| `subject` | `string` | required |
+| `subject` | `string` | required — `mailto:you@example.com` or `https://example.com/contact` (validated at construction) |
 | `allowedEndpointHosts` | `string[]` | optional |
 
 <Steps>
@@ -38,6 +38,13 @@ await sender.send({ subscription, title: "Hello", body: "World" });
   </Step>
 </Steps>
 
-<Accordions><Accordion title="Should I call the provider SDK?">No. Use the sently sender; provider-specific extras stay on the transport instance.</Accordion></Accordions>
+<Accordions>
+  <Accordion title="Should I call the provider SDK?">
+    No. Use the sently sender; provider-specific extras stay on the transport instance.
+  </Accordion>
+  <Accordion title="Why does construction throw on subject?">
+    VAPID `subject` must be a real `mailto:` address or `https:` URL. Values like `@oke.local` (no prefix) are rejected immediately as `WebPushError` so push services never return a confusing 403 later.
+  </Accordion>
+</Accordions>
 
 <Cards><Card title="Push channel" href="/docs/channels/push" /></Cards>

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

@@ -1,40 +0,0 @@
----
-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

@@ -1,15 +0,0 @@
----
-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

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

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

@@ -1,53 +0,0 @@
----
-title: Push
-description: Send a Web Push or FCM notification through a channel sender.
-icon: Bell
-source: "src/push.ts"
----
-
-Send a browser Web Push or FCM device notification through `createPushSender`.
-
-<Callout title="The one rule">
-  Use `subscription` with `WebPushTransport`, or `token` with `FcmTransport` — not both shapes on the wrong transport.
-</Callout>
-
-## Quick start
-
-<Steps>
-  <Step title="Create a Web 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">
-
-```ts
-await push.send({
-  subscription,
-  title: "Update",
-  body: "Your report is ready.",
-});
-```
-
-  </Step>
-</Steps>
-
-For FCM device tokens, use `FcmTransport` and `token` instead of `subscription` — see [FCM](/docs/transports/fcm).
-
-## Next
-
-<Cards>
-  <Card title="Push channel" href="/docs/channels/push" />
-  <Card title="FCM transport" href="/docs/transports/fcm" />
-</Cards>

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

@@ -1,36 +0,0 @@
----
-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

@@ -1,38 +0,0 @@
----
-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>