@zeroxsolutions/sms 0.0.2 → 0.1.0

package/CHANGELOG.md

@@ -1,3 +1,15 @@
+## 0.1.0 (2026-09-25)
+
+### 🚀 Features
+
+- **sms:** let an esms caller set the endpoint and the timeout ([d8cda41](https://github.com/zeroxsolutions/zeroxsolutions/commit/d8cda41))
+- **sms:** send through esms and read its delivery reports ([d88829b](https://github.com/zeroxsolutions/zeroxsolutions/commit/d88829b))
+
+### ❤️ Thank You
+
+- Claude Opus 5.5
+- Lương Văn Tú
+
 ## 0.0.2 (2026-09-22)
 
 ### 🚀 Features

package/README.md

@@ -18,8 +18,8 @@ pnpm add @zeroxsolutions/sms
 
 ## The port
 
-The package ships no adapter, so a consumer implements `ISmsSender` itself and calls `send` with a
-composed message:
+A consumer implements `ISmsSender` for a provider this package has no adapter for, and calls `send`
+with a composed message:
 
 ```ts
 import type { ISmsSender, SendSmsResult, SmsMessage } from '@zeroxsolutions/sms';
@@ -44,33 +44,94 @@ const { messageId } = await new ProviderSender().send({
 takes a name and an address pair. `to` is in E.164 and is not validated here: which numbers a product
 accepts, and how it normalises one, is the product's own decision.
 
-## No adapter yet
+`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.
 
-This package publishes the port and its refusals and no implementation. An adapter wraps one
-provider's SDK, and the table mapping that provider's codes onto the refusals below can only be
-written against that provider's documentation. When an account exists, the adapter arrives as its own
-subpath, `@zeroxsolutions/sms/<provider>`, with that SDK as an optional peer dependency, so a
-consumer that never imports it does not install it.
+## eSMS
 
-Two things will constrain that choice, and both are the consumer's: the SDK has to run on workerd,
-and A2P delivery in Vietnam goes through a brandname registered with the carriers, whose registration
-also fixes the text a message may carry.
+`@zeroxsolutions/sms/esms` sends through [eSMS](https://esms.vn) as customer-care SMS under a
+registered brandname, inside Vietnam. It posts to eSMS's REST API over the runtime's own `fetch`, so it
+installs nothing and runs on workerd as on Node.
+
+```ts
+import { EsmsSmsSender } from '@zeroxsolutions/sms/esms';
+
+const sender = new EsmsSmsSender({
+  apiKey: env.ESMS_API_KEY,
+  secretKey: env.ESMS_SECRET_KEY,
+  sandbox: false,
+  callbackUrl: 'https://app.example.com/esms-callback/<a secret of yours>',
+});
+
+const { messageId } = await sender.send({
+  from: 'TRIPVN',
+  to: '+84900000000',
+  text: 'Ma xac thuc cua ban la 123456.',
+  reference: 'msg_01j9',
+});
+```
+
+`send` resolving means eSMS accepted the message, not that the handset received it. A number that is
+not `+84` followed by 9 or 10 digits is refused before any request is made.
+
+| eSMS `CodeResult`                           | Refusal                                                         |
+| ------------------------------------------- | --------------------------------------------------------------- |
+| `108`                                       | `SmsRecipientInvalid`                                           |
+| `99`                                        | `SmsRecipientUnreachable`                                       |
+| `104`, `177`                                | `SmsSenderNotRegistered`                                        |
+| `146`, `201`                                | `SmsMessageRejected`                                            |
+| `103`                                       | `SmsBalanceExhausted`                                           |
+| 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`                                                 |
+
+The account has to meet four conditions no code can check:
+
+1. The brandname is registered with the carriers.
+2. The text matches the customer-care template registered for it, or eSMS answers `146`.
+3. The account does not require an IP whitelist (`140`), or `endpoint` names a relay with a fixed
+   egress address: a Worker has none.
+4. `sandbox: true` is set wherever a message must not reach a handset or be charged.
+
+`SmsProviderUnavailable` may follow a send eSMS already accepted: a timeout (`timeoutMs`, 10 s by
+default), or an answer lost in transit. A caller retrying the same message reuses its `reference`; a
+"send a new code" action uses a new one. Match a delivery report to its send by `reference` when one
+was sent. Whether eSMS records a `RequestId` on a refused attempt, `103` among them, is open: if it
+does, a retry after topping up the account answers `124` and is reported as sent. Check this in the
+sandbox before relying on `124`.
+
+### Delivery reports
+
+With `callbackUrl` set, eSMS calls it with `GET` and the message's final status in the query string,
+retrying only on a timeout. `parseEsmsDeliveryReport` reads that query into an `SmsDeliveryReport`:
+
+```ts
+import { ESMS_CALLBACK_SOURCE_ADDRESSES, parseEsmsDeliveryReport } from '@zeroxsolutions/sms/esms';
+
+const report = parseEsmsDeliveryReport(new URL(request.url).searchParams);
+// { messageId, reference?, outcome: 'delivered' | 'failed' | 'pending', cost?: { amount, currency: 'VND' } }
+```
+
+eSMS signs nothing. The route that receives the callback checks the secret in its own path and the
+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`.
 
 ## Refusals
 
 A refusal is one plain `Error` subclass per meaning a caller acts on differently - no wire status, no
 code, no envelope. A caller maps them by class.
 
-| Class | What happened |
-| --- | --- |
-| `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 |
-| `SmsMessageRejected` | the text breaks a provider or carrier rule |
-| `SmsRateLimited` | the provider is throttling this account |
-| `SmsBalanceExhausted` | the account has no credit left |
-| `SmsProviderUnavailable` | the provider failed on its own side |
-| `SmsSendFailed` | a refusal none of the above names |
+| Class                      | What happened                                             |
+| -------------------------- | --------------------------------------------------------- |
+| `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 |
+| `SmsMessageRejected`       | the text breaks a provider or carrier rule                |
+| `SmsRateLimited`           | the provider is throttling this account                   |
+| `SmsBalanceExhausted`      | the account has no credit left                            |
+| `SmsProviderUnavailable`   | the provider failed on its own side                       |
+| `SmsSendFailed`            | a refusal none of the above names                         |
+| `SmsDeliveryReportInvalid` | a provider's delivery report could not be read            |
 
 Every message is a constant. The provider's own text names the number it refused, so it stays in
 `cause`: log the class, never `cause` and never `String(error)`.

package/dist/index.d.ts

@@ -1,4 +1,4 @@
 /** The SMS seam: one composed message, the port that sends it, and the refusals a provider raises through it. */
-export { SmsBalanceExhausted, SmsMessageRejected, SmsProviderUnavailable, SmsRateLimited, SmsRecipientInvalid, SmsRecipientUnreachable, SmsSendFailed, SmsSenderNotRegistered, } from './lib/sender/errors.js';
-export type { ISmsSender, SendSmsResult, SmsMessage } from './lib/sender/port.js';
+export { SmsBalanceExhausted, SmsDeliveryReportInvalid, SmsMessageRejected, SmsProviderUnavailable, SmsRateLimited, SmsRecipientInvalid, SmsRecipientUnreachable, SmsSendFailed, SmsSenderNotRegistered, } from './lib/sender/errors.js';
+export type { ISmsSender, SendSmsResult, SmsDeliveryReport, SmsMessage } from './lib/sender/port.js';
 //# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,iHAAiH;AACjH,OAAO,EACL,mBAAmB,EACnB,kBAAkB,EAClB,sBAAsB,EACtB,cAAc,EACd,mBAAmB,EACnB,uBAAuB,EACvB,aAAa,EACb,sBAAsB,GACvB,MAAM,wBAAwB,CAAC;AAChC,YAAY,EAAE,UAAU,EAAE,aAAa,EAAE,UAAU,EAAE,MAAM,sBAAsB,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,iHAAiH;AACjH,OAAO,EACL,mBAAmB,EACnB,wBAAwB,EACxB,kBAAkB,EAClB,sBAAsB,EACtB,cAAc,EACd,mBAAmB,EACnB,uBAAuB,EACvB,aAAa,EACb,sBAAsB,GACvB,MAAM,wBAAwB,CAAC;AAChC,YAAY,EAAE,UAAU,EAAE,aAAa,EAAE,iBAAiB,EAAE,UAAU,EAAE,MAAM,sBAAsB,CAAC"}

package/dist/index.js

@@ -1,2 +1,2 @@
 /** The SMS seam: one composed message, the port that sends it, and the refusals a provider raises through it. */
-export { SmsBalanceExhausted, SmsMessageRejected, SmsProviderUnavailable, SmsRateLimited, SmsRecipientInvalid, SmsRecipientUnreachable, SmsSendFailed, SmsSenderNotRegistered, } from './lib/sender/errors.js';
+export { SmsBalanceExhausted, SmsDeliveryReportInvalid, SmsMessageRejected, SmsProviderUnavailable, SmsRateLimited, SmsRecipientInvalid, SmsRecipientUnreachable, SmsSendFailed, SmsSenderNotRegistered, } from './lib/sender/errors.js';

package/dist/lib/esms/delivery-report.d.ts

@@ -0,0 +1,13 @@
+import type { SmsDeliveryReport } from '../sender/port.js';
+/**
+ * The addresses eSMS documents its callbacks as coming from (developers.esms.vn, "Callback Url").
+ * eSMS signs nothing, so a product's callback route checks the caller's address against these and a
+ * secret in its own path.
+ */
+export declare const ESMS_CALLBACK_SOURCE_ADDRESSES: readonly string[];
+/**
+ * Reads the query eSMS calls `CallbackUrl` with. Throws `SmsDeliveryReportInvalid` for a query with no
+ * `SMSID`, or with a `SendStatus`, `SendSuccess`, `SendFailed` or `TotalPrice` that is not a number.
+ */
+export declare function parseEsmsDeliveryReport(query: URLSearchParams): SmsDeliveryReport;
+//# sourceMappingURL=delivery-report.d.ts.map

package/dist/lib/esms/delivery-report.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"delivery-report.d.ts","sourceRoot":"","sources":["../../../src/lib/esms/delivery-report.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,iBAAiB,EAAE,MAAM,mBAAmB,CAAC;AAE3D;;;;GAIG;AACH,eAAO,MAAM,8BAA8B,EAAE,SAAS,MAAM,EAI1D,CAAC;AAiBH;;;GAGG;AACH,wBAAgB,uBAAuB,CAAC,KAAK,EAAE,eAAe,GAAG,iBAAiB,CAuBjF"}

package/dist/lib/esms/delivery-report.js

@@ -0,0 +1,50 @@
+import { SmsDeliveryReportInvalid } from '../sender/errors.js';
+/**
+ * The addresses eSMS documents its callbacks as coming from (developers.esms.vn, "Callback Url").
+ * eSMS signs nothing, so a product's callback route checks the caller's address against these and a
+ * secret in its own path.
+ */
+export const ESMS_CALLBACK_SOURCE_ADDRESSES = Object.freeze([
+    '103.29.26.39',
+    '103.29.26.80',
+    '103.29.27.39',
+]);
+/** eSMS's `SendStatus` for a message whose sending has finished; `SendSuccess` and `SendFailed` then say how. */
+const SENDING_FINISHED = 5;
+/** The currency eSMS prices in. It has no minor unit, so a price is already in minor units. */
+const PRICE_CURRENCY = 'VND';
+/** The number `name` carries; `undefined` where it is absent or empty. Anything else refuses the report. */
+function numberIn(query, name) {
+    const raw = query.get(name);
+    if (raw === null || raw === '')
+        return undefined;
+    const value = Number(raw);
+    if (!Number.isFinite(value))
+        throw new SmsDeliveryReportInvalid();
+    return value;
+}
+/**
+ * Reads the query eSMS calls `CallbackUrl` with. Throws `SmsDeliveryReportInvalid` for a query with no
+ * `SMSID`, or with a `SendStatus`, `SendSuccess`, `SendFailed` or `TotalPrice` that is not a number.
+ */
+export function parseEsmsDeliveryReport(query) {
+    const messageId = query.get('SMSID');
+    if (!messageId)
+        throw new SmsDeliveryReportInvalid();
+    const status = numberIn(query, 'SendStatus');
+    const succeeded = numberIn(query, 'SendSuccess') ?? 0;
+    const failed = numberIn(query, 'SendFailed') ?? 0;
+    const price = numberIn(query, 'TotalPrice');
+    const reference = query.get('RequestId');
+    const outcome = status === SENDING_FINISHED && succeeded >= 1
+        ? 'delivered'
+        : status === SENDING_FINISHED && failed >= 1
+            ? 'failed'
+            : 'pending';
+    return {
+        messageId,
+        ...(reference ? { reference } : {}),
+        outcome,
+        ...(price === undefined ? {} : { cost: { amount: Math.round(price), currency: PRICE_CURRENCY } }),
+    };
+}

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

@@ -0,0 +1,4 @@
+/** The eSMS half: the sender backed by eSMS's REST API, and the reader of its delivery callback. */
+export { ESMS_CALLBACK_SOURCE_ADDRESSES, parseEsmsDeliveryReport } from './delivery-report.js';
+export { EsmsSmsSender, type EsmsSmsSenderOptions } from './sender.js';
+//# sourceMappingURL=index.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/lib/esms/index.ts"],"names":[],"mappings":"AAAA,oGAAoG;AACpG,OAAO,EAAE,8BAA8B,EAAE,uBAAuB,EAAE,MAAM,sBAAsB,CAAC;AAC/F,OAAO,EAAE,aAAa,EAAE,KAAK,oBAAoB,EAAE,MAAM,aAAa,CAAC"}

package/dist/lib/esms/index.js

@@ -0,0 +1,3 @@
+/** The eSMS half: the sender backed by eSMS's REST API, and the reader of its delivery callback. */
+export { ESMS_CALLBACK_SOURCE_ADDRESSES, parseEsmsDeliveryReport } from './delivery-report.js';
+export { EsmsSmsSender } from './sender.js';

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

@@ -0,0 +1,30 @@
+import type { ISmsSender, SendSmsResult, SmsMessage } from '../sender/port.js';
+/** How an `EsmsSmsSender` reaches the account. */
+export interface EsmsSmsSenderOptions {
+    readonly apiKey: string;
+    readonly secretKey: string;
+    /** `Sandbox=1`: eSMS accepts and answers, delivers nothing, and charges nothing. */
+    readonly sandbox?: boolean;
+    /** Sent as `CallbackUrl` on every message; eSMS calls it with the message's final status. */
+    readonly callbackUrl?: string;
+    /**
+     * Where the send call goes, eSMS's own URL by default. A relay with a fixed egress address goes here
+     * when the account only accepts whitelisted addresses (code `140`), since a Worker has none.
+     */
+    readonly endpoint?: string;
+    /** How long a send waits for eSMS before refusing with `SmsProviderUnavailable`, 10 000 by default. */
+    readonly timeoutMs?: number;
+}
+/**
+ * Backs the SMS port with eSMS's REST API over the runtime's own `fetch`. Delivers inside Vietnam
+ * only; `send` resolving means eSMS accepted the message, and its delivery report says whether the
+ * handset received it.
+ */
+export declare class EsmsSmsSender implements ISmsSender {
+    private readonly options;
+    constructor(options: EsmsSmsSenderOptions);
+    send(message: SmsMessage): Promise<SendSmsResult>;
+    /** Sends `body` and reads eSMS's answer; anything short of a JSON object is the provider failing. */
+    private post;
+}
+//# sourceMappingURL=sender.d.ts.map

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

@@ -0,0 +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"}

package/dist/lib/esms/sender.js

@@ -0,0 +1,122 @@
+import { SmsBalanceExhausted, SmsMessageRejected, SmsProviderUnavailable, 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. */
+const CUSTOMER_CARE = '2';
+/** The `CodeResult` eSMS answers a request it accepted with. Accepted, not delivered. */
+const ACCEPTED = '100';
+/** The `CodeResult` eSMS answers a `RequestId` it saw in the last 24 hours with. */
+const REPEATED_REQUEST = '124';
+/** The longest `RequestId` eSMS accepts. */
+const MAX_REFERENCE_LENGTH = 50;
+/** Vietnam's national prefix plus a 9- or 10-digit subscriber number, the shape eSMS delivers to. */
+const VIETNAM_PHONE = /^\+84\d{9,10}$/;
+/**
+ * How long a send waits for eSMS 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 ESMS_SEND_TIMEOUT_MS = 10_000;
+/**
+ * Every `CodeResult` eSMS documents for this call that a caller acts on differently, and the class it
+ * raises (developers.esms.vn, "Bang ma loi"). Any other code, `101` wrong keys and `140` IP not
+ * whitelisted among them, raises `SmsSendFailed`.
+ */
+const REFUSALS = {
+    '99': SmsRecipientUnreachable,
+    '103': SmsBalanceExhausted,
+    '104': SmsSenderNotRegistered,
+    '108': SmsRecipientInvalid,
+    '146': SmsMessageRejected,
+    '177': SmsSenderNotRegistered,
+    '201': SmsMessageRejected,
+};
+/** The class a `CodeResult` raises - `SmsSendFailed` wherever it is not one of the table's own keys. */
+function refusalClassOf(code) {
+    return code !== undefined && Object.hasOwn(REFUSALS, code) ? REFUSALS[code] : SmsSendFailed;
+}
+/**
+ * Whether every character of `text` is ASCII. A code-point test rather than a `[^\x00-\x7f]` class,
+ * which `no-control-regex` refuses.
+ */
+function isAscii(text) {
+    return [...text].every((character) => (character.codePointAt(0) ?? 0) <= 0x7f);
+}
+/** `+84901234567` as eSMS spells it, `0901234567`; `undefined` for a number that is not this shape. */
+function nationalNumber(e164) {
+    return VIETNAM_PHONE.test(e164) ? `0${e164.slice(3)}` : undefined;
+}
+/**
+ * Backs the SMS port with eSMS's REST API over the runtime's own `fetch`. Delivers inside Vietnam
+ * only; `send` resolving means eSMS accepted the message, and its delivery report says whether the
+ * handset received it.
+ */
+export class EsmsSmsSender {
+    options;
+    constructor(options) {
+        this.options = options;
+    }
+    async send(message) {
+        const phone = nationalNumber(message.to);
+        if (phone === undefined)
+            throw new SmsRecipientInvalid();
+        if (message.reference !== undefined &&
+            (message.reference.length === 0 || message.reference.length > MAX_REFERENCE_LENGTH)) {
+            throw new SmsSendFailed();
+        }
+        const answer = await this.post({
+            ApiKey: this.options.apiKey,
+            SecretKey: this.options.secretKey,
+            Brandname: message.from,
+            SmsType: CUSTOMER_CARE,
+            Phone: phone,
+            Content: message.text,
+            IsUnicode: isAscii(message.text) ? '0' : '1',
+            ...(this.options.sandbox ? { Sandbox: '1' } : {}),
+            ...(message.reference === undefined ? {} : { RequestId: message.reference }),
+            ...(this.options.callbackUrl === undefined ? {} : { CallbackUrl: this.options.callbackUrl }),
+        });
+        const codeResult = answer.CodeResult === undefined ? undefined : String(answer.CodeResult);
+        if (codeResult === ACCEPTED) {
+            const messageId = answer.SMSID ?? message.reference;
+            if (messageId !== undefined)
+                return { messageId };
+            throw new SmsSendFailed({ cause: answer });
+        }
+        if (codeResult === REPEATED_REQUEST && message.reference !== undefined) {
+            return { messageId: message.reference };
+        }
+        const Refusal = refusalClassOf(codeResult);
+        throw new Refusal({ cause: answer });
+    }
+    /** Sends `body` and reads eSMS's answer; anything short of a JSON object is the provider failing. */
+    async post(body) {
+        let response;
+        try {
+            response = await fetch(this.options.endpoint ?? SEND_URL, {
+                method: 'POST',
+                headers: { 'content-type': 'application/json' },
+                body: JSON.stringify(body),
+                signal: AbortSignal.timeout(this.options.timeoutMs ?? ESMS_SEND_TIMEOUT_MS),
+            });
+        }
+        catch (cause) {
+            throw new SmsProviderUnavailable({ cause });
+        }
+        if (!response.ok) {
+            await response.body?.cancel().catch(() => undefined);
+            throw new SmsProviderUnavailable({ cause: new Error(`eSMS answered ${response.status}`) });
+        }
+        let answer;
+        try {
+            answer = await response.json();
+        }
+        catch (cause) {
+            throw new SmsProviderUnavailable({ cause });
+        }
+        if (answer === null || typeof answer !== 'object' || Array.isArray(answer)) {
+            throw new SmsProviderUnavailable({ cause: answer });
+        }
+        return answer;
+    }
+}

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

@@ -1,6 +1,8 @@
 /**
  * What a provider's refusal means, one class per meaning a caller acts on differently. An adapter
  * translates its own provider's codes onto these, so nothing above the port names a provider.
+ * `SmsDeliveryReportInvalid` is the one refusal not raised by a send: it names a delivery report that
+ * cannot be read.
  *
  * Every message is a constant. The provider's own text - which often names the number - stays in
  * `cause`, so a caller logs the class and never `cause` or `String(error)`.
@@ -32,7 +34,11 @@ export declare class SmsRateLimited extends Error {
 export declare class SmsBalanceExhausted extends Error {
     constructor(options?: ErrorOptions);
 }
-/** The provider failed on its own side; the message itself may be fine. */
+/**
+ * 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`.
+ */
 export declare class SmsProviderUnavailable extends Error {
     constructor(options?: ErrorOptions);
 }
@@ -40,4 +46,8 @@ export declare class SmsProviderUnavailable extends Error {
 export declare class SmsSendFailed extends Error {
     constructor(options?: ErrorOptions);
 }
+/** A delivery report that is missing its message id or carries a number it cannot read. */
+export declare class SmsDeliveryReportInvalid extends Error {
+    constructor(options?: ErrorOptions);
+}
 //# sourceMappingURL=errors.d.ts.map

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;;;;;;;;;GASG;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,2EAA2E;AAC3E,qBAAa,sBAAuB,SAAQ,KAAK;gBACnC,OAAO,CAAC,EAAE,YAAY;CAInC;AAED,sGAAsG;AACtG,qBAAa,aAAc,SAAQ,KAAK;gBAC1B,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,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"}

package/dist/lib/sender/errors.js

@@ -1,6 +1,8 @@
 /**
  * What a provider's refusal means, one class per meaning a caller acts on differently. An adapter
  * translates its own provider's codes onto these, so nothing above the port names a provider.
+ * `SmsDeliveryReportInvalid` is the one refusal not raised by a send: it names a delivery report that
+ * cannot be read.
  *
  * Every message is a constant. The provider's own text - which often names the number - stays in
  * `cause`, so a caller logs the class and never `cause` or `String(error)`.
@@ -50,7 +52,11 @@ export class SmsBalanceExhausted extends Error {
         this.name = 'SmsBalanceExhausted';
     }
 }
-/** The provider failed on its own side; the message itself may be fine. */
+/**
+ * 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`.
+ */
 export class SmsProviderUnavailable extends Error {
     constructor(options) {
         super('The sms provider failed internally', options);
@@ -64,3 +70,10 @@ export class SmsSendFailed extends Error {
         this.name = 'SmsSendFailed';
     }
 }
+/** A delivery report that is missing its message id or carries a number it cannot read. */
+export class SmsDeliveryReportInvalid extends Error {
+    constructor(options) {
+        super('The delivery report could not be read', options);
+        this.name = 'SmsDeliveryReportInvalid';
+    }
+}

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

@@ -5,16 +5,44 @@
  *
  * `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.
+ *
+ * `reference` is the caller's own id for this message. An adapter whose provider refuses a repeated
+ * id sends it, so a retried send cannot deliver and charge twice; a provider without that check
+ * ignores it.
  */
 export interface SmsMessage {
     readonly from: string;
     readonly to: string;
     readonly text: string;
+    readonly reference?: string;
 }
-/** What the provider hands back: the id its own logs and delivery reports name this message by. */
+/**
+ * What the provider hands back. Normally the id its own logs and delivery reports name this message
+ * by; the caller's own `reference` instead, whenever the provider answered no id of its own.
+ */
 export interface SendSmsResult {
     readonly messageId: string;
 }
+/**
+ * A message's final status as a provider reports it, in one shape whichever provider sent it. It
+ * carries no phone number: the caller already holds the number through `messageId` or `reference`.
+ */
+export interface SmsDeliveryReport {
+    /** The provider's id for the message. */
+    readonly messageId: string;
+    /**
+     * The `reference` the message was sent with, when it had one. A caller that sent one matches
+     * reports by it, since `send` can answer with the reference itself instead of the provider's id,
+     * whenever the provider answered no id of its own.
+     */
+    readonly reference?: string;
+    readonly outcome: 'delivered' | 'failed' | 'pending';
+    /** What the provider charged, in integer minor units of `currency`. */
+    readonly cost?: {
+        readonly amount: number;
+        readonly currency: string;
+    };
+}
 /** Sends one composed message. The only seam a product substitutes to send an SMS. */
 export interface ISmsSender {
     send(message: SmsMessage): Promise<SendSmsResult>;

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;;;;;;GAMG;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;CACvB;AAED,mGAAmG;AACnG,MAAM,WAAW,aAAa;IAC5B,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;CAC5B;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;;;;;;;;;;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"}

package/package.json

@@ -1,10 +1,10 @@
 {
   "name": "@zeroxsolutions/sms",
-  "version": "0.0.2",
+  "version": "0.1.0",
   "private": false,
   "type": "module",
   "sideEffects": false,
-  "description": "The SMS seam: a composed message, the port that sends it, and its typed refusals. Knows nothing of templates, locales, delivery records or which provider carries the message - those stay in the product.",
+  "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.",
   "main": "./dist/index.js",
   "module": "./dist/index.js",
   "types": "./dist/index.d.ts",
@@ -20,9 +20,17 @@
       "types": "./dist/index.d.ts",
       "import": "./dist/index.js",
       "default": "./dist/index.js"
+    },
+    "./esms": {
+      "types": "./dist/lib/esms/index.d.ts",
+      "import": "./dist/lib/esms/index.js",
+      "default": "./dist/lib/esms/index.js"
     }
   },
   "dependencies": {
     "tslib": "^2.3.0"
+  },
+  "devDependencies": {
+    "msw": "2.15.0"
   }
 }