sently 0.9.2 → 0.10.0

package/site/content/docs/index.mdx

@@ -1,6 +1,6 @@
 ---
 title: sently handbook
-description: Channel-first messaging for email, SMS, WhatsApp, and web push.
+description: Channel-first messaging for email, SMS, WhatsApp, and push (Web Push / FCM).
 icon: BookOpen
 source: "README.md"
 ---

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

@@ -1,14 +1,20 @@
 ---
 title: Push
-description: Send a browser notification through a channel sender.
+description: Send a Web Push or FCM 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>
+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 the sender">
+  <Step title="Create a Web Push sender">
 
 ```ts
 import { createPushSender } from "sently/push";
@@ -27,10 +33,21 @@ const push = createPushSender({
   <Step title="Send">
 
 ```ts
-await push.send({ subscription, title: "Update", body: "Your report is ready." });
+await push.send({
+  subscription,
+  title: "Update",
+  body: "Your report is ready.",
+});
 ```
 
   </Step>
 </Steps>
 
-<Cards><Card title="Push channel" href="/docs/channels/push" /></Cards>
+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/reference/channel-result.mdx

@@ -0,0 +1,82 @@
+---
+title: Channel send result
+description: Map email, SMS, WhatsApp, and push results to a shared accepted shape.
+icon: Boxes
+source: "src/core/channel-result.ts"
+---
+
+Adapters that span channels can normalize every send into
+`{ messageId, provider, accepted }` without inventing per-provider glue.
+Use this after `mailer.send`, `sms.send`, `whatsapp.send`, or `push.send`.
+
+<Callout title="The one rule">
+  Keep channel-specific fields on the original result; use `toChannelSendResult` only for the shared slice.
+</Callout>
+
+## Quick start
+
+<Steps>
+  <Step title="Send on any channel">
+
+```ts
+import { createSmsSender } from "sently/sms";
+import { toChannelSendResult } from "sently/channel-result";
+import { UnifonicTransport } from "sently/transports/unifonic";
+
+const sms = createSmsSender({
+  transport: new UnifonicTransport({
+    appSid: process.env.UNIFONIC_APPSID!,
+    senderId: "MyBrand",
+  }),
+});
+const result = await sms.send({ to: "+15551234567", body: "Hi" });
+```
+
+  </Step>
+  <Step title="Normalize for your adapter">
+
+```ts
+const shared = toChannelSendResult(result);
+// { messageId, provider?, accepted }
+```
+
+  </Step>
+</Steps>
+
+## ChannelSendResult
+
+| Field | Type | Meaning |
+| --- | --- | --- |
+| `messageId` | `string` | Provider or client message id |
+| `provider` | `string?` | Transport id when set |
+| `accepted` | `boolean` | Provider accepted the send (not end-user delivery) |
+
+## Mapping
+
+| Channel result | `accepted` |
+| --- | --- |
+| Email `SendResult` | `accepted.length > 0` and `rejected.length === 0` |
+| SMS / WhatsApp / Push | `status` in `accepted` / `queued` / `sending` / `sent` / `delivered` / `read` / `success` (case-insensitive) |
+
+Import from `sently/channel-result` or the main `sently` barrel.
+
+## Troubleshooting
+
+<Accordions>
+  <Accordion title="Why is accepted true but the user never got the message?">
+    Acceptance means the provider took the message. Use [webhooks](/docs/guides/webhooks) for delivered / failed outcomes.
+  </Accordion>
+</Accordions>
+
+## Learn more
+
+- [Webhook events](./webhook-events)
+- [SMS options](./sms-options)
+- [Exports](./exports)
+
+## Next
+
+<Cards>
+  <Card title="Webhook events" href="/docs/reference/webhook-events" />
+  <Card title="Exports" href="/docs/reference/exports" />
+</Cards>

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

@@ -17,12 +17,13 @@ The main `sently` package is for shared types and factories — not every provid
 
 | Import | Primary API |
 | ------ | ----------- |
-| `sently` | `createMailer`, `createSMTPMailer`, types, OAuth2, `SentlyError`, `consoleObserver`, `FallbackTransport`, `WeightedFallbackTransport`, `CloudflareEmailTransport` |
+| `sently` | `createMailer`, `createSMTPMailer`, types, OAuth2, `SentlyError`, `consoleObserver`, `toChannelSendResult`, `FallbackTransport`, `WeightedFallbackTransport`, `CloudflareEmailTransport` |
 | `sently/mailer` | `createMailer` only |
 | `sently/smtp` | `createSMTPMailer` |
 | `sently/sms` | `createSmsSender` |
 | `sently/whatsapp` | `createWhatsAppSender` |
 | `sently/push` | `createPushSender` |
+| `sently/channel-result` | `toChannelSendResult`, `ChannelSendResult` |
 | `sently/errors` | `SentlyError` hierarchy |
 | `sently/idempotency` | `IdempotencyTransport` |
 | `sently/dkim` | DKIM signing |
@@ -36,7 +37,7 @@ The main `sently` package is for shared types and factories — not every provid
 
 | Import | Use |
 | ------ | --- |
-| `sently/transports/<name>` | One provider or email decorator (e.g. `sndr`, `resend`, `twilio-sms`) |
+| `sently/transports/<name>` | One provider or decorator (e.g. `sndr`, `unifonic`, `fcm`, `retry`) |
 
 HTTP providers such as SNDR, Resend, and Plunk are **not** re-exported from `sently`.
 
@@ -47,7 +48,8 @@ HTTP providers such as SNDR, Resend, and Plunk are **not** re-exported from `sen
 | `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`.
+Email: `brevo`, `mailgun`, `postmark`, `resend`, `sendgrid`, `ses`, `sndr`.
+SMS / WhatsApp: `twilio-sms` (+ verify), `unifonic`, `whatsapp-cloud` (+ verify).
 
 ## Adapters
 

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

@@ -9,6 +9,7 @@
     "whatsapp-options",
     "push-options",
     "transport-contracts",
+    "channel-result",
     "errors",
     "webhook-events"
   ]

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

@@ -1,13 +1,21 @@
 ---
 title: Push options
-description: Fields accepted by `PushSender.send`.
+description: Fields accepted by `PushSender.send` for Web Push and FCM.
 icon: Bell
 source: "src/core/push-types.ts"
 ---
 
+`PushOptions` is `WebPushOptions | FcmPushOptions`.
+Pick the shape that matches your transport.
+
+<Callout title="The one rule">
+  Pass `subscription` to `WebPushTransport` and `token` to `FcmTransport`.
+</Callout>
+
+## Shared fields
+
 | Field | Type | Required |
 | --- | --- | --- |
-| `subscription` | `PushSubscription` | yes |
 | `title` | `string` | yes |
 | `body` | `string` | yes |
 | `data` | `Record<string, unknown>` | no |
@@ -15,6 +23,39 @@ source: "src/core/push-types.ts"
 | `ttl` | `number` | no |
 | `messageId` | `string` | no |
 
+## Web Push
+
+| Field | Type | Required |
+| --- | --- | --- |
+| `subscription` | `PushSubscription` | yes |
+
 A subscription contains `endpoint`, `keys.p256dh`, and `keys.auth`.
 
-<Cards><Card title="Push channel" href="/docs/channels/push" /></Cards>
+## FCM
+
+| Field | Type | Required |
+| --- | --- | --- |
+| `token` | `string` | yes |
+| `image` | `string` | no |
+
+FCM stringifies non-string `data` values before send.
+
+## Result
+
+| Field | Type | Notes |
+| --- | --- | --- |
+| `messageId` | `string` | Provider or client id |
+| `status` | `string` | e.g. `"accepted"` |
+| `response` | `string` | Often the HTTP status or FCM name |
+| `provider` | `string?` | `"webpush"` / `"fcm"`; set by fallback |
+| `providerIndex` | `number?` | Fallback chain index |
+
+Map any channel result with [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="Channel send result" href="/docs/reference/channel-result" />
+</Cards>

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

@@ -12,6 +12,22 @@ source: "src/core/sms-types.ts"
 | `from` | `string` | no |
 | `messageId` | `string` | no |
 
-The result includes `messageId`, `to`, `status`, `response`, and optional `provider`.
+## Result
 
-<Cards><Card title="SMS channel" href="/docs/channels/sms" /></Cards>
+| Field | Type | Notes |
+| --- | --- | --- |
+| `messageId` | `string` | Provider or client id |
+| `to` | `string` | Recipient |
+| `status` | `string` | e.g. `"accepted"`, `"queued"` |
+| `response` | `string` | Provider text |
+| `provider` | `string?` | Transport id; set by fallback |
+| `providerIndex` | `number?` | Fallback chain index |
+
+Map any channel result to `{ messageId, provider, accepted }` with [channel send result](./channel-result).
+
+## Next
+
+<Cards>
+  <Card title="SMS channel" href="/docs/channels/sms" />
+  <Card title="Channel send result" href="/docs/reference/channel-result" />
+</Cards>

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

@@ -1,17 +1,29 @@
 ---
 title: Webhook events
-description: Normalized EmailEvent fields returned by every provider webhook parser.
+description: Normalized EmailEvent and DeliveryEvent fields from provider webhook parsers.
 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.
+Email parsers return `EmailEvent[]`. SMS and WhatsApp parsers return `DeliveryEvent[]`.
+Use `toDeliveryEvent` to put email events on the same ingest path as SMS / WhatsApp.
 
 <Callout title="The one rule">
   Branch on `event.type` and keep provider-specific details in `event.raw` when you need them.
 </Callout>
 
+## DeliveryEvent
+
+| Field | Type | Meaning |
+| ----- | ---- | ------- |
+| `channel` | `"email" \| "sms" \| "whatsapp" \| "push"` | Messaging channel |
+| `provider` | `string` | Parser id (e.g. `"twilio-sms"`) |
+| `type` | union below | Normalized lifecycle type |
+| `messageId` | `string?` | Provider message id when present |
+| `recipient` | `string?` | Address or phone when present |
+| `timestamp` | `Date?` | Event time when present |
+| `raw` | `unknown` | Original provider payload |
+
 ## EmailEvent
 
 | Field | Type | Meaning |
@@ -25,15 +37,27 @@ Verify signatures in the [webhooks guide](/docs/guides/webhooks) before you proc
 
 ## 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. |
+| Value | Channels | Meaning |
+| ----- | -------- | ------- |
+| `queued` | SMS | Accepted / queued by the provider |
+| `sent` | SMS / WhatsApp | Handed to the network |
+| `delivered` | All | Delivered (or mailbox accepted for email) |
+| `failed` | SMS / WhatsApp | Permanent failure |
+| `read` | SMS / WhatsApp | Read receipt |
+| `bounced` | Email | Hard failure or bounce |
+| `complained` | Email | Spam complaint |
+| `opened` | Email | Open tracking |
+| `clicked` | Email | Click tracking |
+| `deferred` | Email | Temporary deferral |
+| `unknown` | All | Unmapped or informational event |
+
+## Mapping helpers
+
+```ts
+import { toDeliveryEvent } from "sently/webhooks";
+
+const delivery = toDeliveryEvent(emailEvent);
+```
 
 ## SNDR mapping
 
@@ -51,7 +75,7 @@ SNDR `data.email_id` becomes `messageId`. Recipients come from `data.to` or `dat
 
 <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.
+The shared email `type` union has no unsubscribe value. Keep the vendor payload in `raw` if you need unsubscribe-specific handling.
 
 </Accordion>
 
@@ -60,7 +84,7 @@ The shared `EmailEvent.type` union has no unsubscribe value. Keep the vendor pay
 ## Learn more
 
 - [Webhooks guide](/docs/guides/webhooks) — verify + parse flow
-- [SNDR transport](/docs/transports/sndr) — sending side
+- [Channel send result](/docs/reference/channel-result) — send-time accepted mapping
 
 ## Next
 

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

@@ -12,4 +12,22 @@ source: "src/core/whatsapp-types.ts"
 
 Both shapes accept optional `messageId`. Template components can include `header`, `body`, or `button` parameters.
 
-<Cards><Card title="WhatsApp channel" href="/docs/channels/whatsapp" /></Cards>
+## Result
+
+| Field | Type | Notes |
+| --- | --- | --- |
+| `messageId` | `string` | Provider or client id |
+| `to` | `string` | Recipient |
+| `status` | `string` | e.g. `"accepted"` |
+| `response` | `string` | Provider text |
+| `provider` | `string?` | Transport id; set by fallback |
+| `providerIndex` | `number?` | Fallback chain index |
+
+Map any channel result with [channel send result](./channel-result).
+
+## Next
+
+<Cards>
+  <Card title="WhatsApp channel" href="/docs/channels/whatsapp" />
+  <Card title="Channel send result" href="/docs/reference/channel-result" />
+</Cards>

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

@@ -0,0 +1,80 @@
+---
+title: FCM
+description: Send mobile push through Firebase Cloud Messaging HTTP v1.
+icon: Bell
+source: "src/transports/fcm.ts"
+---
+
+Send device-token push through Firebase Cloud Messaging HTTP v1 for native Android and iOS clients.
+Use [Web Push](./webpush) when you have a browser Push API subscription instead.
+
+<Callout title="The one rule">Pass `token` in push options — not a Web Push `subscription`.</Callout>
+
+## Quick start
+
+<Steps>
+  <Step title="Configure the transport">
+
+```ts
+import { createPushSender } from "sently/push";
+import { FcmTransport } from "sently/transports/fcm";
+
+const push = createPushSender({
+  transport: new FcmTransport({
+    projectId: process.env.FCM_PROJECT_ID!,
+    clientEmail: process.env.FCM_CLIENT_EMAIL!,
+    privateKey: process.env.FCM_PRIVATE_KEY!,
+  }),
+});
+```
+
+  </Step>
+  <Step title="Send to a device token">
+
+```ts
+const result = await push.send({
+  token: deviceRegistrationToken,
+  title: "Hello",
+  body: "World",
+});
+console.log(result.messageId, result.status);
+```
+
+  </Step>
+</Steps>
+
+## Configuration
+
+| Option | Type | Default or requirement |
+| --- | --- | --- |
+| `projectId` | `string` | required |
+| `clientEmail` | `string` | service account email |
+| `privateKey` | `string` | PEM private key (env / secrets only) |
+| `getAccessToken` | `() => Promise<string>` | optional override for tests |
+
+Literal `\n` sequences in `privateKey` env strings are normalized to newlines.
+The transport mints a short-lived OAuth2 token with scope `firebase.messaging` — no Google SDK.
+
+## Troubleshooting
+
+<Accordions>
+  <Accordion title="Can I pass a browser subscription?">
+    No. `FcmTransport` requires `token`. Use `WebPushTransport` for VAPID subscriptions.
+  </Accordion>
+  <Accordion title="Where do I get the private key?">
+    Download a Firebase / GCP service account JSON and pass `project_id`, `client_email`, and `private_key` from that file via environment variables.
+  </Accordion>
+</Accordions>
+
+## Learn more
+
+- [Push channel](/docs/channels/push)
+- [Push options](/docs/reference/push-options)
+- [Web Push](./webpush)
+
+## Next
+
+<Cards>
+  <Card title="Push channel" href="/docs/channels/push" />
+  <Card title="Web Push" href="/docs/transports/webpush" />
+</Cards>

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

@@ -63,9 +63,11 @@ Every import below is an exported package subpath.
 | [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` |
 
 For retry, fallback, preview, and idempotency wrappers, see [Decorators](../decorators).
 
@@ -85,7 +87,7 @@ For retry, fallback, preview, and idempotency wrappers, see [Decorators](../deco
     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`.
+    Wrap any channel transport with a [decorator](../decorators), then pass the wrapper to the matching sender.
   </Accordion>
 </Accordions>
 

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

@@ -23,10 +23,12 @@
     "twilio-sms",
     "taqnyat-sms",
     "msegat",
+    "unifonic",
     "---WhatsApp---",
     "whatsapp-cloud",
     "taqnyat-whatsapp",
     "---Push---",
-    "webpush"
+    "webpush",
+    "fcm"
   ]
 }

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

@@ -0,0 +1,85 @@
+---
+title: Unifonic
+description: Send SMS through the Unifonic el.cloud REST API.
+icon: Truck
+source: "src/transports/unifonic.ts"
+---
+
+Send SMS through Unifonic’s el.cloud REST API for transactional texts such as OTPs and alerts.
+Wire the transport into `createSmsSender` so app code stays on the SMS channel API.
+
+<Callout title="The one rule">Create this transport under `createSmsSender` — do not call Unifonic from app code directly.</Callout>
+
+## Quick start
+
+<Steps>
+  <Step title="Configure the transport">
+
+```ts
+import { createSmsSender } from "sently/sms";
+import { UnifonicTransport } from "sently/transports/unifonic";
+
+const sender = createSmsSender({
+  transport: new UnifonicTransport({
+    appSid: process.env.UNIFONIC_APPSID!,
+    senderId: "MyBrand",
+  }),
+});
+```
+
+  </Step>
+  <Step title="Send with the channel API">
+
+```ts
+const result = await sender.send({ to: "+9665xxxxxxxx", body: "Hello" });
+console.log(result.messageId, result.status);
+```
+
+  </Step>
+</Steps>
+
+## Configuration
+
+| Option | Type | Default or requirement |
+| --- | --- | --- |
+| `appSid` | `string` | required (`AppSid`) |
+| `senderId` | `string` | required on send unless `options.from` is set |
+| `statusCallback` | `string` | optional public HTTPS DLR URL |
+| `async` | `boolean` | `false` |
+
+`options.from` maps to `SenderID`. `options.messageId` maps to `CorrelationID`.
+Phone numbers are normalized to international digits without `+` or leading `00`.
+
+## Delivery webhooks
+
+Parse Unifonic status callbacks with `sently/webhooks/unifonic` into `DeliveryEvent[]`.
+
+```ts
+import { parse } from "sently/webhooks/unifonic";
+
+const events = parse(await request.json());
+```
+
+## Troubleshooting
+
+<Accordions>
+  <Accordion title="Should I call the Unifonic SDK?">
+    No. Use the sently SMS sender; this transport posts to `el.cloud.unifonic.com` for you.
+  </Accordion>
+  <Accordion title="Why do I get a SenderID error?">
+    Set `senderId` on the transport or pass `from` on each `send`.
+  </Accordion>
+</Accordions>
+
+## Learn more
+
+- [SMS channel](/docs/channels/sms)
+- [Webhooks](/docs/guides/webhooks)
+- [Channel send result](/docs/reference/channel-result)
+
+## Next
+
+<Cards>
+  <Card title="SMS channel" href="/docs/channels/sms" />
+  <Card title="Webhooks" href="/docs/guides/webhooks" />
+</Cards>

package/dist/chunk-0gqy32pe.js.map

@@ -1,10 +0,0 @@
-{
-  "version": 3,
-  "sources": ["../src/transports/fallback.ts"],
-  "sourcesContent": [
-    "/**\n * @module\n * FallbackTransport — routes through an ordered list of transports,\n * advancing to the next when the current one fails. Use for provider\n * failover: if your primary provider has an outage, the next takes over.\n * Composes with RetryTransport — wrap each entry in RetryTransport to\n * retry within a provider before failing over to the next.\n *\n * @example\n * ```ts\n * import { FallbackTransport } from \"sently/transports/fallback\";\n * import { RetryTransport } from \"sently/transports/retry\";\n * import { ResendTransport } from \"sently/transports/resend\";\n * import { SESTransport } from \"sently/transports/ses\";\n *\n * const transport = new FallbackTransport(\n *   [\n *     new RetryTransport(new ResendTransport({ apiKey })),\n *     new RetryTransport(new SESTransport({ accessKeyId, secretAccessKey })),\n *   ],\n *   { cooldownMs: 300_000 },\n * );\n * ```\n */\nimport { SentlyError } from \"../core/errors.js\";\nimport { getProviderLabel } from \"../core/provider-label.js\";\nimport type { MailOptions, SendResult, Transport, VerifyResult } from \"../core/types.js\";\n\n/** One failed provider attempt collected during failover. */\nexport interface FallbackAttempt {\n  /** Provider label (e.g. `\"resend\"`, `\"ses\"`). */\n  provider: string;\n  /** Error thrown by that transport. */\n  error: unknown;\n}\n\n/** Per-provider result from {@link FallbackTransport.verifyAll}. */\nexport interface FallbackProviderVerifyResult {\n  /** Provider label. */\n  provider: string;\n  /** Whether this provider verified successfully. */\n  ok: boolean;\n  /** Human-readable status from the provider verify call. */\n  message?: string;\n}\n\n/** Result of verifying every transport in a fallback chain. */\nexport interface FallbackVerifyAllResult {\n  /** True when at least one provider in the chain verified successfully. */\n  ok: boolean;\n  /** Per-provider verify results in chain order. */\n  providers: FallbackProviderVerifyResult[];\n}\n\n/** Options for {@link FallbackTransport} failover behavior. */\nexport interface FallbackOptions {\n  /**\n   * Decide whether a given error should trigger failover to the next\n   * transport. Default: fail over on everything EXCEPT permanent client\n   * errors (HTTP 400/401/403, SMTP permanent 5xx auth failures), since\n   * those will fail identically on every provider.\n   */\n  shouldFallback?: (error: unknown) => boolean;\n  /** Optional callback fired before advancing to the next transport. */\n  onFallback?: (failedIndex: number, error: unknown) => void;\n  /**\n   * After a failed send, skip this provider until the cooldown expires (ms).\n   * Prevents hammering a failing provider during an outage.\n   */\n  cooldownMs?: number;\n  /** Injectable clock for cooldown and testing. Default: `Date.now`. */\n  now?: () => number;\n  /**\n   * Shared cooldown state across fallback instances (e.g. {@link WeightedFallbackTransport}).\n   * @internal\n   */\n  cooldownState?: Map<string, number>;\n}\n\n/**\n * Thrown when every transport in the chain fails.\n * {@link FallbackAttempt} entries record which provider failed and why.\n */\nexport class FallbackError extends Error {\n  /** All failed attempts in order — which provider failed and why. */\n  readonly attempts: FallbackAttempt[];\n\n  /** Creates an error summarizing every failed transport attempt. */\n  constructor(attempts: FallbackAttempt[]) {\n    super(`All ${attempts.length} transports failed`);\n    this.name = \"FallbackError\";\n    this.attempts = attempts;\n  }\n}\n\n/** @deprecated Use {@link getProviderLabel} from `sently/core` patterns. */\nexport const inferProviderLabel = getProviderLabel;\n\nfunction defaultShouldFallback(error: unknown): boolean {\n  if (error instanceof SentlyError && error.sentlyCode === \"SMTP_AUTH_FAILED\") {\n    return false;\n  }\n\n  const status = (error as { statusCode?: number })?.statusCode;\n  if (typeof status === \"number\") {\n    if (status === 400 || status === 401 || status === 403) {\n      return false;\n    }\n    return true;\n  }\n\n  const code = (error as { code?: number })?.code;\n  if (code === 535) {\n    return false;\n  }\n\n  return true;\n}\n\ntype MailerOnFallback = (\n  failedProvider: string,\n  nextProvider: string,\n  error: unknown,\n) => void | Promise<void>;\n\n/**\n * Decorator transport that fails over through an ordered list of transports.\n */\nexport class FallbackTransport implements Transport {\n  readonly provider = \"fallback\";\n\n  private readonly shouldFallback: (error: unknown) => boolean;\n  private readonly onFallback?: FallbackOptions[\"onFallback\"];\n  private readonly cooldownMs: number;\n  private readonly now: () => number;\n  private readonly unhealthyUntil: Map<string, number>;\n  private mailerOnFallback: MailerOnFallback | undefined;\n\n  /**\n   * Creates a failover transport over an ordered list of backends.\n   * @throws {Error} When the transports array is empty.\n   */\n  constructor(\n    private readonly transports: Transport[],\n    options?: FallbackOptions,\n  ) {\n    if (transports.length === 0) {\n      throw new Error(\"FallbackTransport requires at least one transport\");\n    }\n    this.shouldFallback = options?.shouldFallback ?? defaultShouldFallback;\n    this.onFallback = options?.onFallback;\n    this.cooldownMs = options?.cooldownMs ?? 0;\n    this.now = options?.now ?? (() => Date.now());\n    this.unhealthyUntil = options?.cooldownState ?? new Map<string, number>();\n  }\n\n  /**\n   * Register a per-send onFallback callback from mailer lifecycle hooks.\n   * @internal Used by {@link MailerImpl}; cleared after each send.\n   */\n  setMailerOnFallback(callback: MailerOnFallback | undefined): void {\n    this.mailerOnFallback = callback;\n  }\n\n  private isCoolingDown(provider: string): boolean {\n    const until = this.unhealthyUntil.get(provider);\n    if (until === undefined) {\n      return false;\n    }\n    if (this.now() >= until) {\n      this.unhealthyUntil.delete(provider);\n      return false;\n    }\n    return true;\n  }\n\n  private markUnhealthy(provider: string): void {\n    if (this.cooldownMs > 0) {\n      this.unhealthyUntil.set(provider, this.now() + this.cooldownMs);\n    }\n  }\n\n  /** Sends through transports in order until one succeeds. */\n  async send(message: MailOptions): Promise<SendResult> {\n    const attempts: FallbackAttempt[] = [];\n    const skipped: FallbackAttempt[] = [];\n\n    for (let i = 0; i < this.transports.length; i++) {\n      const transport = this.transports[i] as Transport;\n      const provider = getProviderLabel(transport);\n\n      if (this.isCoolingDown(provider)) {\n        skipped.push({\n          provider,\n          error: new Error(`Provider ${provider} is in cooldown`),\n        });\n        continue;\n      }\n\n      try {\n        const result = await transport.send(message);\n        return {\n          ...result,\n          provider,\n          providerIndex: i,\n        };\n      } catch (err) {\n        attempts.push({ provider, error: err });\n        this.markUnhealthy(provider);\n\n        const nextIndex = this.findNextTryIndex(i);\n        if (nextIndex === -1) {\n          break;\n        }\n        if (this.shouldFallback(err) === false) {\n          throw err;\n        }\n\n        const nextProvider = getProviderLabel(this.transports[nextIndex] as Transport);\n        this.onFallback?.(i, err);\n        if (this.mailerOnFallback !== undefined) {\n          await this.mailerOnFallback(provider, nextProvider, err);\n        }\n      }\n    }\n\n    const allAttempts = [...attempts, ...skipped];\n    if (allAttempts.length === 0) {\n      throw new FallbackError([\n        { provider: \"fallback\", error: new Error(\"All providers are in cooldown\") },\n      ]);\n    }\n\n    throw new FallbackError(allAttempts);\n  }\n\n  private findNextTryIndex(currentIndex: number): number {\n    for (let j = currentIndex + 1; j < this.transports.length; j++) {\n      const provider = getProviderLabel(this.transports[j] as Transport);\n      if (!this.isCoolingDown(provider)) {\n        return j;\n      }\n    }\n    return -1;\n  }\n\n  /**\n   * Returns the result of the first transport whose verify() returns `ok: true`.\n   * Use {@link verifyAll} for full-chain visibility.\n   */\n  async verify(): Promise<VerifyResult> {\n    const all = await this.verifyAll();\n    const firstOk = all.providers.find((entry) => entry.ok);\n    if (firstOk !== undefined) {\n      return {\n        ok: true,\n        provider: firstOk.provider,\n        ...(firstOk.message !== undefined ? { message: firstOk.message } : {}),\n      };\n    }\n\n    return {\n      ok: false,\n      provider: \"fallback\",\n      message: \"no transport verified\",\n    };\n  }\n\n  /** Verifies every transport in the chain and returns per-provider results. */\n  async verifyAll(): Promise<FallbackVerifyAllResult> {\n    const providers: FallbackProviderVerifyResult[] = [];\n\n    for (const transport of this.transports) {\n      const provider = getProviderLabel(transport);\n      if (transport.verify === undefined) {\n        providers.push({ provider, ok: false, message: \"no verify() method\" });\n        continue;\n      }\n\n      try {\n        const result = await transport.verify();\n        providers.push({\n          provider,\n          ok: result.ok,\n          ...(result.message !== undefined ? { message: result.message } : {}),\n        });\n      } catch (err) {\n        providers.push({\n          provider,\n          ok: false,\n          message: err instanceof Error ? err.message : String(err),\n        });\n      }\n    }\n\n    return {\n      ok: providers.some((entry) => entry.ok),\n      providers,\n    };\n  }\n\n  /** Calls close() on every transport; one failure does not block the others. */\n  async close(): Promise<void> {\n    await Promise.allSettled(this.transports.map((transport) => transport.close?.()));\n  }\n}\n"
-  ],
-  "mappings": "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",
-  "debugId": "833078D22947C91264756E2164756E21",
-  "names": []
-}

package/dist/chunk-5915vbcj.js

@@ -1,4 +0,0 @@
-import{N as S}from"./chunk-gp4fwrs8.js";import{O as E}from"./chunk-0qxws3kj.js";import{S as D}from"./chunk-93vqxxj2.js";import{W as z,X as f}from"./chunk-qtkd5bak.js";import{ca as k}from"./chunk-tamww15j.js";function N(j){return typeof j.setMailerOnRetry==="function"}function P(j){return typeof j.setMailerOnFallback==="function"}var v="SMTP config passed to transport-only createMailer. Use: import { createSMTPMailer } from 'sently' or import { createSMTPMailer } from 'sently/smtp'.";async function c(j){if(j.transport===void 0||"host"in j&&j.transport===void 0)throw new k(v,"INVALID_CONFIG");return new M(j.transport,j.plugins??[],j.hooks)}function b(j){return j.attachments!==void 0&&j.attachments.length>0}function y(j){return S(j)}function _(j,K){return{...j.messageId!==void 0?{messageId:j.messageId}:{},to:D(j.to),subject:j.subject,provider:y(K)}}class M{transport;plugins;hooks;constructor(j,K=[],V){this.transport=j;this.plugins=K;this.hooks=V}async send(j){let K=await f(j,this.plugins),V=_(K,this.transport);if(await z(this.hooks?.onSend,V),this.hooks?.onRetry!==void 0&&N(this.transport))this.transport.setMailerOnRetry((w,C)=>{z(this.hooks?.onRetry,V,w,C)});if(this.hooks?.onFallback!==void 0&&P(this.transport))this.transport.setMailerOnFallback((w,C,T)=>{z(this.hooks?.onFallback,V,w,C,T)});let A=performance.now();try{let w=await this.transport.send(K),C={...V,messageId:w.messageId};return await z(this.hooks?.onSuccess,C,w,performance.now()-A),w}catch(w){throw await z(this.hooks?.onError,V,w,performance.now()-A),w}finally{if(N(this.transport))this.transport.setMailerOnRetry(void 0);if(P(this.transport))this.transport.setMailerOnFallback(void 0)}}async processMessage(j){return f(j,this.plugins)}async sendBulk(j,K){if(j.length===0)return{total:0,sent:0,failed:0,results:[]};let V=Array(j.length),A=K?.stopOnError??!1,w=!1,C=async(X,$,B,Q,Z)=>{if(V[$]={status:"sent",result:B},Q!==void 0&&this.hooks!==void 0){let W=_(Q,this.transport);await z(this.hooks.onSend,W),await z(this.hooks.onSuccess,{...W,messageId:B.messageId},B,Z)}K?.onSuccess?.(X,$,B)},T=async(X,$,B,Q,Z)=>{if(V[$]={status:"failed",error:B},Q!==void 0&&this.hooks!==void 0){let W=_(Q,this.transport);await z(this.hooks.onSend,W),await z(this.hooks.onError,W,B,Z)}if(K?.onError?.(X,$,B),A)w=!0};if(this.transport.sendBatch){let X=[],$=[];for(let[B,Q]of j.entries())if(b(Q))$.push({index:B,message:Q});else X.push({index:B,message:Q});if(X.length>0&&!w){let B=this.transport.batchMax??X.length,Q=K?.rateDelta??2,Z=Q>0?new E(Q,K?.rateLimit??1000,K?.now):null;for(let W=0;W<X.length&&!w;W+=B){let U=X.slice(W,W+B);if(Z)await Z.acquire();try{let Y=await Promise.all(U.map(({message:G})=>this.processMessage(G))),J=performance.now(),H=await this.transport.sendBatch(Y),I=performance.now()-J;for(let G=0;G<U.length;G++){let R=U[G],L=Y[G],F=H[G];if(F===void 0)await T(R.message,R.index,Error("Batch response missing result for message"),L,I);else if(F.batchError!==void 0)await T(R.message,R.index,F.batchError,L,I);else await C(R.message,R.index,F,L,I)}}catch(Y){let J=await Promise.all(U.map(({message:H})=>this.processMessage(H)));for(let H=0;H<U.length;H++){if(w)break;let I=U[H];await T(I.message,I.index,Y,J[H])}}}}if($.length>0&&!w){let B=K?.concurrency??1,Q=[...$],Z=0;await new Promise((W)=>{let U=()=>{if(Q.length===0&&Z===0||w)W()},Y=()=>{if(Q.length===0||w){U();return}let J=Q.shift();if(J===void 0){U();return}Z++,this.send(J.message).then((H)=>{V[J.index]={status:"sent",result:H},K?.onSuccess?.(J.message,J.index,H)}).catch((H)=>{if(V[J.index]={status:"failed",error:H},K?.onError?.(J.message,J.index,H),A)w=!0}).finally(()=>{Z--,Y(),U()})};for(let J=0;J<B;J++)Y()})}}else{let X=K?.concurrency??1,$=[...j.entries()],B=0;await new Promise((Q)=>{let Z=()=>{if($.length===0&&B===0||w)Q()},W=()=>{if($.length===0||w){Z();return}let U=$.shift();if(U===void 0){Z();return}let[Y,J]=U;B++,this.send(J).then((H)=>{V[Y]={status:"sent",result:H},K?.onSuccess?.(J,Y,H)}).catch((H)=>{if(V[Y]={status:"failed",error:H},K?.onError?.(J,Y,H),A)w=!0}).finally(()=>{B--,W(),Z()})};for(let U=0;U<X;U++)W()})}let q=0,O=0;for(let X of V){if(X===void 0)continue;if(X.status==="sent")q++;else O++}return{total:j.length,sent:q,failed:O,results:V}}verify(){if(this.transport.verify)return this.transport.verify();return Promise.resolve({ok:!0,provider:"mailer"})}close(){if(this.transport.close)return this.transport.close();return Promise.resolve()}}
-export{c as L,M};
-
-//# debugId=DF7737883683888864756E2164756E21