@zeroxsolutions/sms 0.0.2

package/CHANGELOG.md

@@ -0,0 +1,10 @@
+## 0.0.2 (2026-09-22)
+
+### 🚀 Features
+
+- **sms:** add the package, the send port and its refusals ([8eff593](https://github.com/zeroxsolutions/zeroxsolutions/commit/8eff593))
+
+### ❤️ Thank You
+
+- Claude Opus 5 (1M context)
+- Lương Văn Tú

package/README.md

@@ -0,0 +1,80 @@
+# @zeroxsolutions/sms
+
+The SMS seam: a composed message, the port that sends it, and its typed refusals.
+
+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
+message someone else composed and hands back the id the provider filed it under.
+
+It is a sibling of `@zeroxsolutions/mail` rather than a subpath of it. That package's concern is
+named for one channel, and a consumer installing something called mail to send an SMS reads a name
+that describes nothing.
+
+## Install
+
+```sh
+pnpm add @zeroxsolutions/sms
+```
+
+## The port
+
+The package ships no adapter, so a consumer implements `ISmsSender` itself and calls `send` with a
+composed message:
+
+```ts
+import type { ISmsSender, SendSmsResult, SmsMessage } from '@zeroxsolutions/sms';
+
+/** Yours to write: one per provider, wrapping that provider's SDK. */
+declare function sendThroughTheProviderSdk(message: SmsMessage): Promise<string>;
+
+class ProviderSender implements ISmsSender {
+  async send(message: SmsMessage): Promise<SendSmsResult> {
+    return { messageId: await sendThroughTheProviderSdk(message) };
+  }
+}
+
+const { messageId } = await new ProviderSender().send({
+  from: 'TRIPVN',
+  to: '+84900000000',
+  text: 'Ma xac thuc cua ban la 123456.',
+});
+```
+
+`from` is the brandname or short code registered with the carriers, a single string where a mailbox
+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
+
+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.
+
+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.
+
+## 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 |
+
+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)`.
+
+There is no opt-out class. The first consumer sends transactional codes, which an opt-out does not
+cover. A consumer that sends marketing adds one, and it arrives as a minor release rather than as a
+field on an existing class.

package/dist/index.d.ts

@@ -0,0 +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';
+//# sourceMappingURL=index.d.ts.map

package/dist/index.d.ts.map

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

package/dist/index.js

@@ -0,0 +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';

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

@@ -0,0 +1,43 @@
+/**
+ * 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.
+ *
+ * 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)`.
+ *
+ * There is no opt-out class. The first consumer sends transactional codes, which an opt-out does not
+ * cover; a consumer that sends marketing adds one.
+ */
+/** The number is not routable: malformed, or a range no carrier serves. Sending it again fails the same way. */
+export declare class SmsRecipientInvalid extends Error {
+    constructor(options?: ErrorOptions);
+}
+/** The carrier refused the recipient: the subscriber is absent, barred, or blocking this sender. */
+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. */
+export declare class SmsSenderNotRegistered extends Error {
+    constructor(options?: ErrorOptions);
+}
+/** The text breaks a provider or carrier rule: it departs from the registered pattern, exceeds a length, or carries a barred word. */
+export declare class SmsMessageRejected extends Error {
+    constructor(options?: ErrorOptions);
+}
+/** The provider is throttling this account's send rate; the same message may be accepted later. */
+export declare class SmsRateLimited extends Error {
+    constructor(options?: ErrorOptions);
+}
+/** The account has no credit left, so nothing more is accepted until it is topped up. */
+export declare class SmsBalanceExhausted extends Error {
+    constructor(options?: ErrorOptions);
+}
+/** The provider failed on its own side; the message itself may be fine. */
+export declare class SmsProviderUnavailable extends Error {
+    constructor(options?: ErrorOptions);
+}
+/** A refusal no other class names: a code the adapter does not know, or a throw that carried none. */
+export declare class SmsSendFailed extends Error {
+    constructor(options?: ErrorOptions);
+}
+//# sourceMappingURL=errors.d.ts.map

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

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

package/dist/lib/sender/errors.js

@@ -0,0 +1,66 @@
+/**
+ * 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.
+ *
+ * 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)`.
+ *
+ * There is no opt-out class. The first consumer sends transactional codes, which an opt-out does not
+ * cover; a consumer that sends marketing adds one.
+ */
+/** The number is not routable: malformed, or a range no carrier serves. Sending it again fails the same way. */
+export class SmsRecipientInvalid extends Error {
+    constructor(options) {
+        super('The recipient number is not routable', options);
+        this.name = 'SmsRecipientInvalid';
+    }
+}
+/** The carrier refused the recipient: the subscriber is absent, barred, or blocking this sender. */
+export class SmsRecipientUnreachable extends Error {
+    constructor(options) {
+        super('The carrier would not deliver to this recipient', options);
+        this.name = 'SmsRecipientUnreachable';
+    }
+}
+/** The sender is not a brandname this account may send under, so every message from it fails alike. */
+export class SmsSenderNotRegistered extends Error {
+    constructor(options) {
+        super('The sender is not registered with the provider', options);
+        this.name = 'SmsSenderNotRegistered';
+    }
+}
+/** The text breaks a provider or carrier rule: it departs from the registered pattern, exceeds a length, or carries a barred word. */
+export class SmsMessageRejected extends Error {
+    constructor(options) {
+        super('The provider rejected the message as composed', options);
+        this.name = 'SmsMessageRejected';
+    }
+}
+/** The provider is throttling this account's send rate; the same message may be accepted later. */
+export class SmsRateLimited extends Error {
+    constructor(options) {
+        super('The provider is limiting the send rate', options);
+        this.name = 'SmsRateLimited';
+    }
+}
+/** The account has no credit left, so nothing more is accepted until it is topped up. */
+export class SmsBalanceExhausted extends Error {
+    constructor(options) {
+        super('The sending account has no balance left', options);
+        this.name = 'SmsBalanceExhausted';
+    }
+}
+/** The provider failed on its own side; the message itself may be fine. */
+export class SmsProviderUnavailable extends Error {
+    constructor(options) {
+        super('The sms provider failed internally', options);
+        this.name = 'SmsProviderUnavailable';
+    }
+}
+/** A refusal no other class names: a code the adapter does not know, or a throw that carried none. */
+export class SmsSendFailed extends Error {
+    constructor(options) {
+        super('The sms provider refused the message', options);
+        this.name = 'SmsSendFailed';
+    }
+}

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

@@ -0,0 +1,22 @@
+/** 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.
+ *
+ * `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.
+ */
+export interface SmsMessage {
+    readonly from: string;
+    readonly to: string;
+    readonly text: string;
+}
+/** What the provider hands back: the id its own logs and delivery reports name this message by. */
+export interface SendSmsResult {
+    readonly messageId: string;
+}
+/** Sends one composed message. The only seam a product substitutes to send an SMS. */
+export interface ISmsSender {
+    send(message: SmsMessage): Promise<SendSmsResult>;
+}
+//# sourceMappingURL=port.d.ts.map

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

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

package/dist/lib/sender/port.js

@@ -0,0 +1,2 @@
+/** The port a product sends one composed message through; a runtime supplies the implementation. */
+export {};

package/package.json

@@ -0,0 +1,28 @@
+{
+  "name": "@zeroxsolutions/sms",
+  "version": "0.0.2",
+  "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.",
+  "main": "./dist/index.js",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "files": [
+    "dist",
+    "README.md",
+    "CHANGELOG.md",
+    "!**/*.tsbuildinfo"
+  ],
+  "exports": {
+    "./package.json": "./package.json",
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "default": "./dist/index.js"
+    }
+  },
+  "dependencies": {
+    "tslib": "^2.3.0"
+  }
+}