sently 0.8.0 → 0.9.0

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

@@ -0,0 +1,15 @@
+---
+title: WhatsApp options
+description: Template and session text shapes accepted by `WhatsAppSender.send`.
+icon: MessagesSquare
+source: "src/core/whatsapp-types.ts"
+---
+
+| Shape | Required fields |
+| --- | --- |
+| Template | `to`, `template.name`, `template.language` |
+| Text | `to`, `text` |
+
+Both shapes accept optional `messageId`. Template components can include `header`, `body`, or `button` parameters.
+
+<Cards><Card title="WhatsApp channel" href="/docs/channels/whatsapp" /></Cards>

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

@@ -0,0 +1,40 @@
+---
+title: Brevo
+description: Send email through the Brevo HTTP API.
+icon: Truck
+source: "src/transports/brevo.ts"
+---
+
+Send email through the Brevo HTTP API.
+
+<Callout title="The one rule">Create this transport under the matching sently channel sender.</Callout>
+
+## Configuration
+
+| Option | Type | Default or requirement |
+| --- | --- | --- |
+| `apiKey` | `string` | required |
+
+<Steps>
+  <Step title="Configure the transport">
+
+```ts
+import { createMailer } from "sently/mailer";
+import { BrevoTransport } from "sently/transports/brevo";
+
+const sender = createMailer({ transport: new BrevoTransport({ apiKey: process.env.BREVO_API_KEY! }) });
+```
+
+  </Step>
+  <Step title="Send with the channel API">
+
+```ts
+await sender.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>
+
+<Cards><Card title="Email channel" href="/docs/channels/email" /></Cards>

package/site/content/docs/transports/cloudflare-email.mdx

@@ -0,0 +1,40 @@
+---
+title: Cloudflare Email
+description: Use a Cloudflare Workers send_email binding.
+icon: Truck
+source: "src/transports/cloudflare-email.ts"
+---
+
+Use a Cloudflare Workers send_email binding.
+
+<Callout title="The one rule">Create this transport under the matching sently channel sender.</Callout>
+
+## Configuration
+
+| Option | Type | Default or requirement |
+| --- | --- | --- |
+| `sendEmail` | `CloudflareSendEmailFn` | required |
+
+<Steps>
+  <Step title="Configure the transport">
+
+```ts
+import { createMailer } from "sently/mailer";
+import { CloudflareEmailTransport } from "sently/transports/cloudflare-email";
+
+const sender = createMailer({ transport: new CloudflareEmailTransport({ sendEmail: env.SEND_EMAIL }) });
+```
+
+  </Step>
+  <Step title="Send with the channel API">
+
+```ts
+await sender.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>
+
+<Cards><Card title="Email channel" href="/docs/channels/email" /></Cards>

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

@@ -0,0 +1,105 @@
+---
+title: Transports
+description: Choose a provider transport for a channel sender.
+icon: Truck
+source: "package.json"
+---
+
+Transports connect a sently channel sender to a delivery provider.
+Pick the transport that matches the channel you are sending on.
+
+<Callout title="The one rule">Keep application delivery calls on a sently channel sender and replace only its transport when you change providers.</Callout>
+
+<Steps>
+  <Step title="Import a sender and its transport">
+
+```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 through the channel">
+
+```ts
+await mailer.send({
+  from: "hello@example.com",
+  to: "person@example.com",
+  subject: "Welcome",
+  text: "Thanks for joining.",
+});
+```
+
+  </Step>
+</Steps>
+
+## Exported transports
+
+Every import below is an exported package subpath.
+
+| Transport | Channel | Import |
+| --- | --- | --- |
+| [SMTP](./smtp) | Email | `sently/transports/smtp` |
+| [Resend](./resend) | Email | `sently/transports/resend` |
+| [SendGrid](./sendgrid) | Email | `sently/transports/sendgrid` |
+| [Postmark](./postmark) | Email | `sently/transports/postmark` |
+| [Mailgun](./mailgun) | Email | `sently/transports/mailgun` |
+| [SES](./ses) | Email | `sently/transports/ses` |
+| [Brevo](./brevo) | Email | `sently/transports/brevo` |
+| [MailerSend](./mailersend) | Email | `sently/transports/mailersend` |
+| [Plunk](./plunk) | Email | `sently/transports/plunk` |
+| [SparkPost](./sparkpost) | Email | `sently/transports/sparkpost` |
+| [Mailtrap](./mailtrap) | Email | `sently/transports/mailtrap` |
+| [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` |
+| [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` |
+
+For retry, fallback, preview, and idempotency wrappers, see [Decorators](../decorators).
+
+## Channel contracts
+
+| Channel | Sender | Transport contract |
+| --- | --- | --- |
+| Email | `createMailer` / `createSMTPMailer` | `Transport` |
+| SMS | `createSmsSender` | `SmsTransport` |
+| WhatsApp | `createWhatsAppSender` | `WhatsAppTransport` |
+| Push | `createPushSender` | `PushTransport` |
+
+## Troubleshooting
+
+<Accordions>
+  <Accordion title="Can I use an email transport for SMS or WhatsApp?">
+    No. A transport implements one channel contract. Choose a transport listed for the channel sender you use.
+  </Accordion>
+  <Accordion title="How do I add retries or fallback?">
+    Wrap an email transport with a [decorator](../decorators), then pass the wrapper to `createMailer`.
+  </Accordion>
+</Accordions>
+
+## Learn more
+
+- [Decorators](../decorators)
+- [Email channel](../channels/email)
+- [SMS channel](../channels/sms)
+- [Transport contracts](../reference/transport-contracts)
+
+## Next
+
+<Cards>
+  <Card title="Decorators" href="/docs/decorators" />
+  <Card title="Email channel" href="/docs/channels/email" />
+  <Card title="SMS channel" href="/docs/channels/sms" />
+</Cards>

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

@@ -0,0 +1,41 @@
+---
+title: Loops
+description: Send template-based transactional email through Loops.
+icon: Truck
+source: "src/transports/loops.ts"
+---
+
+Send template-based transactional email through Loops.
+
+<Callout title="The one rule">Create this transport under the matching sently channel sender.</Callout>
+
+## Configuration
+
+| Option | Type | Default or requirement |
+| --- | --- | --- |
+| `apiKey` | `string` | required |
+| `defaultTransactionalId` | `string` | optional |
+
+<Steps>
+  <Step title="Configure the transport">
+
+```ts
+import { createMailer } from "sently/mailer";
+import { LoopsTransport } from "sently/transports/loops";
+
+const sender = createMailer({ transport: new LoopsTransport({ apiKey: process.env.LOOPS_API_KEY!, defaultTransactionalId: "cl..." }) });
+```
+
+  </Step>
+  <Step title="Send with the channel API">
+
+```ts
+await sender.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>
+
+<Cards><Card title="Email channel" href="/docs/channels/email" /></Cards>

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

@@ -0,0 +1,40 @@
+---
+title: MailerSend
+description: Send email through the MailerSend HTTP API.
+icon: Truck
+source: "src/transports/mailersend.ts"
+---
+
+Send email through the MailerSend HTTP API.
+
+<Callout title="The one rule">Create this transport under the matching sently channel sender.</Callout>
+
+## Configuration
+
+| Option | Type | Default or requirement |
+| --- | --- | --- |
+| `apiToken` | `string` | required |
+
+<Steps>
+  <Step title="Configure the transport">
+
+```ts
+import { createMailer } from "sently/mailer";
+import { MailerSendTransport } from "sently/transports/mailersend";
+
+const sender = createMailer({ transport: new MailerSendTransport({ apiToken: process.env.MAILERSEND_API_TOKEN! }) });
+```
+
+  </Step>
+  <Step title="Send with the channel API">
+
+```ts
+await sender.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>
+
+<Cards><Card title="Email channel" href="/docs/channels/email" /></Cards>

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

@@ -0,0 +1,42 @@
+---
+title: Mailgun
+description: Send email through the Mailgun Messages API.
+icon: Truck
+source: "src/transports/mailgun.ts"
+---
+
+Send email through the Mailgun Messages API.
+
+<Callout title="The one rule">Create this transport under the matching sently channel sender.</Callout>
+
+## Configuration
+
+| Option | Type | Default or requirement |
+| --- | --- | --- |
+| `apiKey` | `string` | required |
+| `domain` | `string` | required |
+| `region` | `"us" | "eu"` | "us" |
+
+<Steps>
+  <Step title="Configure the transport">
+
+```ts
+import { createMailer } from "sently/mailer";
+import { MailgunTransport } from "sently/transports/mailgun";
+
+const sender = createMailer({ transport: new MailgunTransport({ apiKey: process.env.MAILGUN_API_KEY!, domain: "mg.example.com" }) });
+```
+
+  </Step>
+  <Step title="Send with the channel API">
+
+```ts
+await sender.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>
+
+<Cards><Card title="Email channel" href="/docs/channels/email" /></Cards>

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

@@ -0,0 +1,42 @@
+---
+title: Mailtrap
+description: Send email through Mailtrap delivery or sandbox mode.
+icon: Truck
+source: "src/transports/mailtrap.ts"
+---
+
+Send email through Mailtrap delivery or sandbox mode.
+
+<Callout title="The one rule">Create this transport under the matching sently channel sender.</Callout>
+
+## Configuration
+
+| Option | Type | Default or requirement |
+| --- | --- | --- |
+| `apiToken` | `string` | required |
+| `sandbox` | `boolean` | false |
+| `inboxId` | `string` | required when sandbox is true |
+
+<Steps>
+  <Step title="Configure the transport">
+
+```ts
+import { createMailer } from "sently/mailer";
+import { MailtrapTransport } from "sently/transports/mailtrap";
+
+const sender = createMailer({ transport: new MailtrapTransport({ apiToken: process.env.MAILTRAP_API_TOKEN! }) });
+```
+
+  </Step>
+  <Step title="Send with the channel API">
+
+```ts
+await sender.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>
+
+<Cards><Card title="Email channel" href="/docs/channels/email" /></Cards>

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

@@ -0,0 +1,32 @@
+{
+  "title": "Transports",
+  "icon": "Truck",
+  "pages": [
+    "index",
+    "---Email---",
+    "smtp",
+    "resend",
+    "sendgrid",
+    "postmark",
+    "mailgun",
+    "ses",
+    "brevo",
+    "mailersend",
+    "plunk",
+    "sparkpost",
+    "mailtrap",
+    "loops",
+    "cloudflare-email",
+    "sndr",
+    "taqnyat-mail",
+    "---SMS---",
+    "twilio-sms",
+    "taqnyat-sms",
+    "msegat",
+    "---WhatsApp---",
+    "whatsapp-cloud",
+    "taqnyat-whatsapp",
+    "---Push---",
+    "webpush"
+  ]
+}

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

@@ -0,0 +1,42 @@
+---
+title: Msegat
+description: Send SMS through Msegat and use its concrete OTP helpers.
+icon: Truck
+source: "src/transports/msegat.ts"
+---
+
+Send SMS through Msegat and use its concrete OTP helpers.
+
+<Callout title="The one rule">Create this transport under the matching sently channel sender.</Callout>
+
+## Configuration
+
+| Option | Type | Default or requirement |
+| --- | --- | --- |
+| `userName` | `string` | required |
+| `apiKey` | `string` | required |
+| `sender` | `string` | required |
+
+<Steps>
+  <Step title="Configure the transport">
+
+```ts
+import { createSmsSender } from "sently/sms";
+import { MsegatTransport } from "sently/transports/msegat";
+
+const sender = createSmsSender({ transport: new MsegatTransport({ userName: "...", apiKey: "...", sender: "MyBrand" }) });
+```
+
+  </Step>
+  <Step title="Send with the channel API">
+
+```ts
+await sender.send({ to: "+15551234567", body: "Hello" });
+```
+
+  </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>
+
+<Cards><Card title="Sms channel" href="/docs/channels/sms" /></Cards>

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

@@ -0,0 +1,40 @@
+---
+title: Plunk
+description: Send email through the Plunk HTTP API.
+icon: Truck
+source: "src/transports/plunk.ts"
+---
+
+Send email through the Plunk HTTP API.
+
+<Callout title="The one rule">Create this transport under the matching sently channel sender.</Callout>
+
+## Configuration
+
+| Option | Type | Default or requirement |
+| --- | --- | --- |
+| `apiKey` | `string` | required |
+
+<Steps>
+  <Step title="Configure the transport">
+
+```ts
+import { createMailer } from "sently/mailer";
+import { PlunkTransport } from "sently/transports/plunk";
+
+const sender = createMailer({ transport: new PlunkTransport({ apiKey: process.env.PLUNK_API_KEY! }) });
+```
+
+  </Step>
+  <Step title="Send with the channel API">
+
+```ts
+await sender.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>
+
+<Cards><Card title="Email channel" href="/docs/channels/email" /></Cards>

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

@@ -0,0 +1,40 @@
+---
+title: Postmark
+description: Send email through the Postmark API.
+icon: Truck
+source: "src/transports/postmark.ts"
+---
+
+Send email through the Postmark API.
+
+<Callout title="The one rule">Create this transport under the matching sently channel sender.</Callout>
+
+## Configuration
+
+| Option | Type | Default or requirement |
+| --- | --- | --- |
+| `serverToken` | `string` | required |
+
+<Steps>
+  <Step title="Configure the transport">
+
+```ts
+import { createMailer } from "sently/mailer";
+import { PostmarkTransport } from "sently/transports/postmark";
+
+const sender = createMailer({ transport: new PostmarkTransport({ serverToken: process.env.POSTMARK_TOKEN! }) });
+```
+
+  </Step>
+  <Step title="Send with the channel API">
+
+```ts
+await sender.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>
+
+<Cards><Card title="Email channel" href="/docs/channels/email" /></Cards>

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

@@ -0,0 +1,43 @@
+---
+title: Resend
+description: Send email through the Resend HTTP API.
+icon: Truck
+source: "src/transports/resend.ts"
+---
+
+Send email through the Resend HTTP API.
+
+<Callout title="The one rule">Create this transport under the matching sently channel sender.</Callout>
+
+## Configuration
+
+| Option | Type | Default or requirement |
+| --- | --- | --- |
+| `apiKey` | `string` | required |
+| `baseUrl` | `string` | https://api.resend.com |
+| `rateDelta` | `number` | 2 |
+| `rateLimit` | `number` | 1000 |
+
+<Steps>
+  <Step title="Configure the transport">
+
+```ts
+import { createMailer } from "sently/mailer";
+import { ResendTransport } from "sently/transports/resend";
+
+const sender = createMailer({ transport: new ResendTransport({ apiKey: process.env.RESEND_API_KEY! }) });
+```
+
+  </Step>
+  <Step title="Send with the channel API">
+
+```ts
+await sender.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>
+
+<Cards><Card title="Email channel" href="/docs/channels/email" /></Cards>

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

@@ -0,0 +1,40 @@
+---
+title: SendGrid
+description: Send email through the SendGrid v3 API.
+icon: Truck
+source: "src/transports/sendgrid.ts"
+---
+
+Send email through the SendGrid v3 API.
+
+<Callout title="The one rule">Create this transport under the matching sently channel sender.</Callout>
+
+## Configuration
+
+| Option | Type | Default or requirement |
+| --- | --- | --- |
+| `apiKey` | `string` | required |
+
+<Steps>
+  <Step title="Configure the transport">
+
+```ts
+import { createMailer } from "sently/mailer";
+import { SendGridTransport } from "sently/transports/sendgrid";
+
+const sender = createMailer({ transport: new SendGridTransport({ apiKey: process.env.SENDGRID_API_KEY! }) });
+```
+
+  </Step>
+  <Step title="Send with the channel API">
+
+```ts
+await sender.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>
+
+<Cards><Card title="Email channel" href="/docs/channels/email" /></Cards>

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

@@ -0,0 +1,44 @@
+---
+title: Amazon SES
+description: Send email through the AWS SES v2 API.
+icon: Truck
+source: "src/transports/ses.ts"
+---
+
+Send email through the AWS SES v2 API.
+
+<Callout title="The one rule">Create this transport under the matching sently channel sender.</Callout>
+
+## Configuration
+
+| Option | Type | Default or requirement |
+| --- | --- | --- |
+| `accessKeyId` | `string` | required |
+| `secretAccessKey` | `string` | required |
+| `region` | `string` | us-east-1 |
+| `sessionToken` | `string` | optional |
+| `dkim` | `DKIMConfig` | optional |
+
+<Steps>
+  <Step title="Configure the transport">
+
+```ts
+import { createMailer } from "sently/mailer";
+import { SESTransport } from "sently/transports/ses";
+
+const sender = createMailer({ transport: new SESTransport({ accessKeyId: "...", secretAccessKey: "..." }) });
+```
+
+  </Step>
+  <Step title="Send with the channel API">
+
+```ts
+await sender.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>
+
+<Cards><Card title="Email channel" href="/docs/channels/email" /></Cards>