@zeroxsolutions/sms 0.1.0 → 0.1.2

package/CHANGELOG.md

@@ -1,3 +1,29 @@
+## 0.1.2 (2026-10-08)
+
+### 🚀 Features
+
+- **sms:** send through twilio for numbers outside vietnam ([1d94662](https://github.com/zeroxsolutions/zeroxsolutions/commit/1d94662))
+
+### 💅 Refactors
+
+- **sms:** name the twilio option for the origin it holds ([8c69c31](https://github.com/zeroxsolutions/zeroxsolutions/commit/8c69c31))
+
+### ❤️ Thank You
+
+- Claude Opus 5.5
+- Lương Văn Tú
+
+## 0.1.1 (2026-09-25)
+
+### 🩹 Fixes
+
+- **sms:** raise esms's tps refusal as a rate limit ([88b1ed1](https://github.com/zeroxsolutions/zeroxsolutions/commit/88b1ed1))
+
+### ❤️ Thank You
+
+- Claude Opus 5.5
+- Lương Văn Tú
+
 ## 0.1.0 (2026-09-25)
 
 ### 🚀 Features

package/README.md

@@ -1,6 +1,7 @@
 # @zeroxsolutions/sms
 
-The SMS seam: a composed message, the port that sends it, and its typed refusals.
+The SMS seam: a composed message, the port that sends it, its typed refusals, and the eSMS and
+Twilio adapters behind it.
 
 What it does not own is the reason an SMS exists at all - templates, message keys, locales, delivery
 records, queues and retries are product decisions and stay in the product. This package takes a
@@ -45,7 +46,8 @@ takes a name and an address pair. `to` is in E.164 and is not validated here: wh
 accepts, and how it normalises one, is the product's own decision.
 
 `reference` is optional: the caller's own id for the message. An adapter whose provider refuses a
-repeated id sends it, so a send retried after a lost answer cannot deliver and charge twice.
+repeated id sends it, so a send retried after a lost answer cannot deliver and charge twice. Twilio
+takes no such id, so its adapter ignores `reference`.
 
 ## eSMS
 
@@ -81,6 +83,7 @@ not `+84` followed by 9 or 10 digits is refused before any request is made.
 | `104`, `177`                                | `SmsSenderNotRegistered`                                        |
 | `146`, `201`                                | `SmsMessageRejected`                                            |
 | `103`                                       | `SmsBalanceExhausted`                                           |
+| `160`                                       | `SmsRateLimited`                                                |
 | not 2xx, not JSON, or no answer in time     | `SmsProviderUnavailable`                                        |
 | `124` with a `reference`                    | none: answered as sent, with the `reference` as its `messageId` |
 | any other                                   | `SmsSendFailed`                                                 |
@@ -116,6 +119,58 @@ eSMS signs nothing. The route that receives the callback checks the secret in it
 caller's address against `ESMS_CALLBACK_SOURCE_ADDRESSES`, redacts the query in its access log (it
 carries the number), and answers quickly. A query it cannot read throws `SmsDeliveryReportInvalid`.
 
+## Twilio
+
+`@zeroxsolutions/sms/twilio` sends through [Twilio](https://www.twilio.com)'s Messages API, for
+numbers outside the countries a local provider covers. It posts a form body with Basic auth over the
+runtime's own `fetch`, so it installs nothing and runs on workerd as on Node.
+
+```ts
+import { TwilioSmsSender } from '@zeroxsolutions/sms/twilio';
+
+const sender = new TwilioSmsSender({
+  accountSid: env.TWILIO_ACCOUNT_SID,
+  authToken: env.TWILIO_AUTH_TOKEN,
+});
+
+const { messageId } = await sender.send({
+  from: 'MG0123456789abcdef0123456789abcdef',
+  to: '+821012345678',
+  text: 'Your code is 123456.',
+});
+```
+
+`from` is a Messaging Service id (`MG` and 32 hex digits), sent as `MessagingServiceSid`, or a Twilio
+number or alphanumeric sender id, sent as `From`. A Messaging Service picks the sender per destination
+from a pool the account configures. A `to` that is not E.164 is refused before any request is made.
+
+`send` resolving means Twilio queued the message, not that the handset received it.
+
+| Twilio error `code`                 | Refusal                   |
+| ----------------------------------- | ------------------------- |
+| `21211`, `21614`                    | `SmsRecipientInvalid`     |
+| `21612`, `21610`                    | `SmsRecipientUnreachable` |
+| `21212`, `21606`, `21408`           | `SmsSenderNotRegistered`  |
+| `21617`                             | `SmsMessageRejected`      |
+| `20429`, `21611`, or HTTP 429       | `SmsRateLimited`          |
+| 5xx, not JSON, or no answer in time | `SmsProviderUnavailable`  |
+| any other                           | `SmsSendFailed`           |
+
+`21610` is a recipient who replied STOP. `21408` is the account's geographic permissions refusing the
+destination country. Twilio has no code for an empty balance: a suspended account answers `20005`,
+which is `SmsSendFailed`.
+
+Twilio takes no idempotency key. `SmsProviderUnavailable` may follow a send Twilio already queued, and
+retrying it can deliver and charge twice.
+
+The account has to meet three conditions no code can check:
+
+1. Each destination country is enabled in its geographic permissions, or Twilio answers `21408`.
+2. The sender suits each destination. The United States accepts no alphanumeric sender id.
+3. A trial account sends only to numbers verified in it.
+
+Test credentials, with `+15005550006` as `from`, send nothing and charge nothing.
+
 ## Refusals
 
 A refusal is one plain `Error` subclass per meaning a caller acts on differently - no wire status, no
@@ -125,7 +180,7 @@ code, no envelope. A caller maps them by class.
 | -------------------------- | --------------------------------------------------------- |
 | `SmsRecipientInvalid`      | the number is not routable                                |
 | `SmsRecipientUnreachable`  | the carrier would not deliver to the subscriber           |
-| `SmsSenderNotRegistered`   | the sender is not a brandname this account may send under |
+| `SmsSenderNotRegistered`   | the account may not send from this sender or to this destination |
 | `SmsMessageRejected`       | the text breaks a provider or carrier rule                |
 | `SmsRateLimited`           | the provider is throttling this account                   |
 | `SmsBalanceExhausted`      | the account has no credit left                            |

package/dist/lib/esms/sender.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"sender.d.ts","sourceRoot":"","sources":["../../../src/lib/esms/sender.ts"],"names":[],"mappings":"AASA,OAAO,KAAK,EAAE,UAAU,EAAE,aAAa,EAAE,UAAU,EAAE,MAAM,mBAAmB,CAAC;AAgD/E,kDAAkD;AAClD,MAAM,WAAW,oBAAoB;IACnC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,oFAAoF;IACpF,QAAQ,CAAC,OAAO,CAAC,EAAE,OAAO,CAAC;IAC3B,6FAA6F;IAC7F,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,CAAC;IAC9B;;;OAGG;IACH,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,CAAC;IAC3B,uGAAuG;IACvG,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,CAAC;CAC7B;AAoBD;;;;GAIG;AACH,qBAAa,aAAc,YAAW,UAAU;IAClC,OAAO,CAAC,QAAQ,CAAC,OAAO;gBAAP,OAAO,EAAE,oBAAoB;IAEpD,IAAI,CAAC,OAAO,EAAE,UAAU,GAAG,OAAO,CAAC,aAAa,CAAC;IAoCvD,qGAAqG;YACvF,IAAI;CA2BnB"}
+{"version":3,"file":"sender.d.ts","sourceRoot":"","sources":["../../../src/lib/esms/sender.ts"],"names":[],"mappings":"AAUA,OAAO,KAAK,EAAE,UAAU,EAAE,aAAa,EAAE,UAAU,EAAE,MAAM,mBAAmB,CAAC;AAiD/E,kDAAkD;AAClD,MAAM,WAAW,oBAAoB;IACnC,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,oFAAoF;IACpF,QAAQ,CAAC,OAAO,CAAC,EAAE,OAAO,CAAC;IAC3B,6FAA6F;IAC7F,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,CAAC;IAC9B;;;OAGG;IACH,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,CAAC;IAC3B,uGAAuG;IACvG,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,CAAC;CAC7B;AAoBD;;;;GAIG;AACH,qBAAa,aAAc,YAAW,UAAU;IAClC,OAAO,CAAC,QAAQ,CAAC,OAAO;gBAAP,OAAO,EAAE,oBAAoB;IAEpD,IAAI,CAAC,OAAO,EAAE,UAAU,GAAG,OAAO,CAAC,aAAa,CAAC;IAoCvD,qGAAqG;YACvF,IAAI;CA2BnB"}

package/dist/lib/esms/sender.js

@@ -1,4 +1,4 @@
-import { SmsBalanceExhausted, SmsMessageRejected, SmsProviderUnavailable, SmsRecipientInvalid, SmsRecipientUnreachable, SmsSendFailed, SmsSenderNotRegistered, } from '../sender/errors.js';
+import { SmsBalanceExhausted, SmsMessageRejected, SmsProviderUnavailable, SmsRateLimited, SmsRecipientInvalid, SmsRecipientUnreachable, SmsSendFailed, SmsSenderNotRegistered, } from '../sender/errors.js';
 /** eSMS's call that sends one message (developers.esms.vn, "Tin CSKH"); the default `endpoint`. */
 const SEND_URL = 'https://rest.esms.vn/MainService.svc/json/SendMultipleMessage_V4_post_json/';
 /** `SmsType` 2, customer care: the type a brandname sends a one-time code as. */
@@ -28,6 +28,7 @@ const REFUSALS = {
     '104': SmsSenderNotRegistered,
     '108': SmsRecipientInvalid,
     '146': SmsMessageRejected,
+    '160': SmsRateLimited,
     '177': SmsSenderNotRegistered,
     '201': SmsMessageRejected,
 };

package/dist/lib/sender/errors.d.ts

@@ -18,7 +18,10 @@ export declare class SmsRecipientInvalid extends Error {
 export declare class SmsRecipientUnreachable extends Error {
     constructor(options?: ErrorOptions);
 }
-/** The sender is not a brandname this account may send under, so every message from it fails alike. */
+/**
+ * The account may not send from this sender, or to this destination. An operator fixes it in the
+ * account, and every message it covers fails alike until then.
+ */
 export declare class SmsSenderNotRegistered extends Error {
     constructor(options?: ErrorOptions);
 }
@@ -37,7 +40,8 @@ export declare class SmsBalanceExhausted extends Error {
 /**
  * The provider failed on its own side; the message itself may be fine. This refusal can follow a send
  * the provider already accepted - a timeout or a lost answer - so a retry must reuse the same
- * `reference`.
+ * `reference`. An adapter whose provider takes no idempotency key, Twilio's, cannot make that retry
+ * safe, so a retry may deliver twice.
  */
 export declare class SmsProviderUnavailable extends Error {
     constructor(options?: ErrorOptions);

package/dist/lib/sender/errors.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../../../src/lib/sender/errors.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,gHAAgH;AAChH,qBAAa,mBAAoB,SAAQ,KAAK;gBAChC,OAAO,CAAC,EAAE,YAAY;CAInC;AAED,oGAAoG;AACpG,qBAAa,uBAAwB,SAAQ,KAAK;gBACpC,OAAO,CAAC,EAAE,YAAY;CAInC;AAED,uGAAuG;AACvG,qBAAa,sBAAuB,SAAQ,KAAK;gBACnC,OAAO,CAAC,EAAE,YAAY;CAInC;AAED,sIAAsI;AACtI,qBAAa,kBAAmB,SAAQ,KAAK;gBAC/B,OAAO,CAAC,EAAE,YAAY;CAInC;AAED,mGAAmG;AACnG,qBAAa,cAAe,SAAQ,KAAK;gBAC3B,OAAO,CAAC,EAAE,YAAY;CAInC;AAED,yFAAyF;AACzF,qBAAa,mBAAoB,SAAQ,KAAK;gBAChC,OAAO,CAAC,EAAE,YAAY;CAInC;AAED;;;;GAIG;AACH,qBAAa,sBAAuB,SAAQ,KAAK;gBACnC,OAAO,CAAC,EAAE,YAAY;CAInC;AAED,sGAAsG;AACtG,qBAAa,aAAc,SAAQ,KAAK;gBAC1B,OAAO,CAAC,EAAE,YAAY;CAInC;AAED,2FAA2F;AAC3F,qBAAa,wBAAyB,SAAQ,KAAK;gBACrC,OAAO,CAAC,EAAE,YAAY;CAInC"}
+{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../../../src/lib/sender/errors.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAEH,gHAAgH;AAChH,qBAAa,mBAAoB,SAAQ,KAAK;gBAChC,OAAO,CAAC,EAAE,YAAY;CAInC;AAED,oGAAoG;AACpG,qBAAa,uBAAwB,SAAQ,KAAK;gBACpC,OAAO,CAAC,EAAE,YAAY;CAInC;AAED;;;GAGG;AACH,qBAAa,sBAAuB,SAAQ,KAAK;gBACnC,OAAO,CAAC,EAAE,YAAY;CAInC;AAED,sIAAsI;AACtI,qBAAa,kBAAmB,SAAQ,KAAK;gBAC/B,OAAO,CAAC,EAAE,YAAY;CAInC;AAED,mGAAmG;AACnG,qBAAa,cAAe,SAAQ,KAAK;gBAC3B,OAAO,CAAC,EAAE,YAAY;CAInC;AAED,yFAAyF;AACzF,qBAAa,mBAAoB,SAAQ,KAAK;gBAChC,OAAO,CAAC,EAAE,YAAY;CAInC;AAED;;;;;GAKG;AACH,qBAAa,sBAAuB,SAAQ,KAAK;gBACnC,OAAO,CAAC,EAAE,YAAY;CAInC;AAED,sGAAsG;AACtG,qBAAa,aAAc,SAAQ,KAAK;gBAC1B,OAAO,CAAC,EAAE,YAAY;CAInC;AAED,2FAA2F;AAC3F,qBAAa,wBAAyB,SAAQ,KAAK;gBACrC,OAAO,CAAC,EAAE,YAAY;CAInC"}

package/dist/lib/sender/errors.js

@@ -24,7 +24,10 @@ export class SmsRecipientUnreachable extends Error {
         this.name = 'SmsRecipientUnreachable';
     }
 }
-/** The sender is not a brandname this account may send under, so every message from it fails alike. */
+/**
+ * The account may not send from this sender, or to this destination. An operator fixes it in the
+ * account, and every message it covers fails alike until then.
+ */
 export class SmsSenderNotRegistered extends Error {
     constructor(options) {
         super('The sender is not registered with the provider', options);
@@ -55,7 +58,8 @@ export class SmsBalanceExhausted extends Error {
 /**
  * The provider failed on its own side; the message itself may be fine. This refusal can follow a send
  * the provider already accepted - a timeout or a lost answer - so a retry must reuse the same
- * `reference`.
+ * `reference`. An adapter whose provider takes no idempotency key, Twilio's, cannot make that retry
+ * safe, so a retry may deliver twice.
  */
 export class SmsProviderUnavailable extends Error {
     constructor(options) {

package/dist/lib/sender/port.d.ts

@@ -1,7 +1,9 @@
 /** The port a product sends one composed message through; a runtime supplies the implementation. */
 /**
  * One message, already composed. `from` is a single string where a mailbox takes a name and an
- * address pair, because an SMS sender is a brandname or a short code registered with the carriers.
+ * address pair. Its form depends on the provider: a brandname or short code registered with the
+ * carriers, or through Twilio an E.164 number, an alphanumeric sender id or an `MG...` Messaging
+ * Service id.
  *
  * `to` is in E.164 and is not branded: which numbers a product accepts, and how it normalises one,
  * is the product's decision and not something this package can hold for it.

package/dist/lib/sender/port.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"port.d.ts","sourceRoot":"","sources":["../../../src/lib/sender/port.ts"],"names":[],"mappings":"AAAA,oGAAoG;AAEpG;;;;;;;;;;GAUG;AACH,MAAM,WAAW,UAAU;IACzB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IACpB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,CAAC;CAC7B;AAED;;;GAGG;AACH,MAAM,WAAW,aAAa;IAC5B,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;CAC5B;AAED;;;GAGG;AACH,MAAM,WAAW,iBAAiB;IAChC,yCAAyC;IACzC,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B;;;;OAIG;IACH,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,OAAO,EAAE,WAAW,GAAG,QAAQ,GAAG,SAAS,CAAC;IACrD,uEAAuE;IACvE,QAAQ,CAAC,IAAI,CAAC,EAAE;QAAE,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;QAAC,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAA;KAAE,CAAC;CACxE;AAED,sFAAsF;AACtF,MAAM,WAAW,UAAU;IACzB,IAAI,CAAC,OAAO,EAAE,UAAU,GAAG,OAAO,CAAC,aAAa,CAAC,CAAC;CACnD"}
+{"version":3,"file":"port.d.ts","sourceRoot":"","sources":["../../../src/lib/sender/port.ts"],"names":[],"mappings":"AAAA,oGAAoG;AAEpG;;;;;;;;;;;;GAYG;AACH,MAAM,WAAW,UAAU;IACzB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,EAAE,EAAE,MAAM,CAAC;IACpB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,CAAC;CAC7B;AAED;;;GAGG;AACH,MAAM,WAAW,aAAa;IAC5B,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;CAC5B;AAED;;;GAGG;AACH,MAAM,WAAW,iBAAiB;IAChC,yCAAyC;IACzC,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B;;;;OAIG;IACH,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,OAAO,EAAE,WAAW,GAAG,QAAQ,GAAG,SAAS,CAAC;IACrD,uEAAuE;IACvE,QAAQ,CAAC,IAAI,CAAC,EAAE;QAAE,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;QAAC,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAA;KAAE,CAAC;CACxE;AAED,sFAAsF;AACtF,MAAM,WAAW,UAAU;IACzB,IAAI,CAAC,OAAO,EAAE,UAAU,GAAG,OAAO,CAAC,aAAa,CAAC,CAAC;CACnD"}

package/dist/lib/twilio/index.d.ts

@@ -0,0 +1,3 @@
+/** The Twilio adapter: the sender backed by Twilio's Messages API. */
+export { TwilioSmsSender, type TwilioSmsSenderOptions } from './sender.js';
+//# sourceMappingURL=index.d.ts.map

package/dist/lib/twilio/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/lib/twilio/index.ts"],"names":[],"mappings":"AAAA,sEAAsE;AACtE,OAAO,EAAE,eAAe,EAAE,KAAK,sBAAsB,EAAE,MAAM,aAAa,CAAC"}

package/dist/lib/twilio/index.js

@@ -0,0 +1,2 @@
+/** The Twilio adapter: the sender backed by Twilio's Messages API. */
+export { TwilioSmsSender } from './sender.js';

package/dist/lib/twilio/sender.d.ts

@@ -0,0 +1,25 @@
+import type { ISmsSender, SendSmsResult, SmsMessage } from '../sender/port.js';
+/** How a `TwilioSmsSender` reaches the account. */
+export interface TwilioSmsSenderOptions {
+    /** The account's `AC...` id: the path segment and the Basic-auth user. */
+    readonly accountSid: string;
+    /** The account's auth token: the Basic-auth password. */
+    readonly authToken: string;
+    /** Scheme and host the API path is appended to, Twilio's own by default. */
+    readonly origin?: string;
+    /** How long a send waits for Twilio before refusing with `SmsProviderUnavailable`, 10 000 by default. */
+    readonly timeoutMs?: number;
+}
+/**
+ * Backs the SMS port with Twilio's Messages API over the runtime's own `fetch`. `send` resolving
+ * means Twilio queued the message, not that the handset received it. Twilio takes no idempotency key,
+ * so `reference` is not sent and a send retried after a lost answer can deliver twice.
+ */
+export declare class TwilioSmsSender implements ISmsSender {
+    private readonly options;
+    constructor(options: TwilioSmsSenderOptions);
+    send(message: SmsMessage): Promise<SendSmsResult>;
+    /** Sends `form` to the account's Messages resource; a rejected or timed-out call is the provider failing. */
+    private post;
+}
+//# sourceMappingURL=sender.d.ts.map

package/dist/lib/twilio/sender.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"sender.d.ts","sourceRoot":"","sources":["../../../src/lib/twilio/sender.ts"],"names":[],"mappings":"AASA,OAAO,KAAK,EAAE,UAAU,EAAE,aAAa,EAAE,UAAU,EAAE,MAAM,mBAAmB,CAAC;AAwC/E,mDAAmD;AACnD,MAAM,WAAW,sBAAsB;IACrC,0EAA0E;IAC1E,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B,yDAAyD;IACzD,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,4EAA4E;IAC5E,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC;IACzB,yGAAyG;IACzG,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,CAAC;CAC7B;AAaD;;;;GAIG;AACH,qBAAa,eAAgB,YAAW,UAAU;IACpC,OAAO,CAAC,QAAQ,CAAC,OAAO;gBAAP,OAAO,EAAE,sBAAsB;IAEtD,IAAI,CAAC,OAAO,EAAE,UAAU,GAAG,OAAO,CAAC,aAAa,CAAC;IAgCvD,6GAA6G;YAC/F,IAAI;CAgBnB"}

package/dist/lib/twilio/sender.js

@@ -0,0 +1,101 @@
+import { SmsMessageRejected, SmsProviderUnavailable, SmsRateLimited, SmsRecipientInvalid, SmsRecipientUnreachable, SmsSendFailed, SmsSenderNotRegistered, } from '../sender/errors.js';
+/** Twilio's REST host; the default `origin`. */
+const TWILIO_ORIGIN = 'https://api.twilio.com';
+/** A Messaging Service id, which Twilio takes as `MessagingServiceSid` rather than `From`. */
+const MESSAGING_SERVICE_SID = /^MG[0-9a-fA-F]{32}$/;
+/** E.164: a plus, then 8 to 15 digits, the first not 0. Anything else never reaches the form body. */
+const E164 = /^\+[1-9]\d{7,14}$/;
+/** HTTP 429: Twilio throttling the account, whatever the body says. */
+const TOO_MANY_REQUESTS = 429;
+/**
+ * How long a send waits for Twilio before giving up, unless `timeoutMs` says otherwise. A Worker waits
+ * on a stalled subrequest as long as its client stays connected, so a send with no bound would hang
+ * the caller rather than fail fast.
+ */
+const TWILIO_SEND_TIMEOUT_MS = 10_000;
+/**
+ * Every Twilio error `code` a caller acts on differently, and the class it raises (Twilio's error
+ * dictionary). `21408` is the account's geographic permissions refusing the country, fixed in the
+ * account as a sender is registered. Any other code, `20003` and `20005` among them, raises
+ * `SmsSendFailed`.
+ */
+const REFUSALS = {
+    '20429': SmsRateLimited,
+    '21211': SmsRecipientInvalid,
+    '21212': SmsSenderNotRegistered,
+    '21408': SmsSenderNotRegistered,
+    '21606': SmsSenderNotRegistered,
+    '21610': SmsRecipientUnreachable,
+    '21611': SmsRateLimited,
+    '21612': SmsRecipientUnreachable,
+    '21614': SmsRecipientInvalid,
+    '21617': SmsMessageRejected,
+};
+/** The class a Twilio error `code` raises - `SmsSendFailed` wherever it is not one of the table's own keys. */
+function refusalClassOf(code) {
+    const key = typeof code === 'number' || typeof code === 'string' ? String(code) : undefined;
+    return key !== undefined && Object.hasOwn(REFUSALS, key) ? REFUSALS[key] : SmsSendFailed;
+}
+/** Whether `value` is a JSON object rather than an array, a primitive or null. */
+function isObject(value) {
+    return value !== null && typeof value === 'object' && !Array.isArray(value);
+}
+/**
+ * Backs the SMS port with Twilio's Messages API over the runtime's own `fetch`. `send` resolving
+ * means Twilio queued the message, not that the handset received it. Twilio takes no idempotency key,
+ * so `reference` is not sent and a send retried after a lost answer can deliver twice.
+ */
+export class TwilioSmsSender {
+    options;
+    constructor(options) {
+        this.options = options;
+    }
+    async send(message) {
+        if (!E164.test(message.to))
+            throw new SmsRecipientInvalid();
+        const form = new URLSearchParams({ To: message.to });
+        form.set(MESSAGING_SERVICE_SID.test(message.from) ? 'MessagingServiceSid' : 'From', message.from);
+        form.set('Body', message.text);
+        const response = await this.post(form);
+        if (response.status === TOO_MANY_REQUESTS) {
+            const body = await response.text().catch(() => undefined);
+            throw new SmsRateLimited({ cause: { status: response.status, body } });
+        }
+        if (response.status >= 500) {
+            const body = await response.text().catch(() => undefined);
+            throw new SmsProviderUnavailable({ cause: { status: response.status, body } });
+        }
+        let answer;
+        try {
+            answer = await response.json();
+        }
+        catch (cause) {
+            throw new SmsProviderUnavailable({ cause });
+        }
+        if (response.ok) {
+            if (isObject(answer) && typeof answer['sid'] === 'string')
+                return { messageId: answer['sid'] };
+            throw new SmsSendFailed({ cause: answer });
+        }
+        const Refusal = refusalClassOf(isObject(answer) ? answer['code'] : undefined);
+        throw new Refusal({ cause: answer });
+    }
+    /** Sends `form` to the account's Messages resource; a rejected or timed-out call is the provider failing. */
+    async post(form) {
+        const origin = (this.options.origin ?? TWILIO_ORIGIN).replace(/\/+$/, '');
+        try {
+            return await fetch(`${origin}/2010-04-01/Accounts/${encodeURIComponent(this.options.accountSid)}/Messages.json`, {
+                method: 'POST',
+                headers: {
+                    authorization: `Basic ${btoa(`${this.options.accountSid}:${this.options.authToken}`)}`,
+                    'content-type': 'application/x-www-form-urlencoded',
+                },
+                body: form,
+                signal: AbortSignal.timeout(this.options.timeoutMs ?? TWILIO_SEND_TIMEOUT_MS),
+            });
+        }
+        catch (cause) {
+            throw new SmsProviderUnavailable({ cause });
+        }
+    }
+}

package/package.json

@@ -1,10 +1,10 @@
 {
   "name": "@zeroxsolutions/sms",
-  "version": "0.1.0",
+  "version": "0.1.2",
   "private": false,
   "type": "module",
   "sideEffects": false,
-  "description": "The SMS seam: a composed message, the port that sends it, its typed refusals, and the eSMS adapter behind that port. Knows nothing of templates, locales or delivery records - those stay in the product.",
+  "description": "The SMS seam: a composed message, the port that sends it, its typed refusals, and the eSMS and Twilio adapters behind that port. Knows nothing of templates, locales or delivery records - those stay in the product.",
   "main": "./dist/index.js",
   "module": "./dist/index.js",
   "types": "./dist/index.d.ts",
@@ -25,6 +25,11 @@
       "types": "./dist/lib/esms/index.d.ts",
       "import": "./dist/lib/esms/index.js",
       "default": "./dist/lib/esms/index.js"
+    },
+    "./twilio": {
+      "types": "./dist/lib/twilio/index.d.ts",
+      "import": "./dist/lib/twilio/index.js",
+      "default": "./dist/lib/twilio/index.js"
     }
   },
   "dependencies": {