@absolutejs/dispatch-twilio 0.0.1

package/README.md

@@ -0,0 +1,81 @@
+# @absolutejs/dispatch-twilio
+
+Twilio-backed `SmsAdapter` for
+[@absolutejs/dispatch](https://github.com/absolutejs/dispatch).
+
+## Install
+
+```sh
+bun add @absolutejs/dispatch @absolutejs/dispatch-twilio twilio
+```
+
+## Usage
+
+```ts
+import twilio from 'twilio';
+import { createDispatcher } from '@absolutejs/dispatch';
+import { createTwilioAdapter } from '@absolutejs/dispatch-twilio';
+
+const twilioClient = twilio(
+  process.env.TWILIO_ACCOUNT_SID!,
+  process.env.TWILIO_AUTH_TOKEN!
+);
+
+const dispatcher = createDispatcher({
+  sms: createTwilioAdapter({
+    client: twilioClient,
+    defaultFrom: '+15551234567',
+    // OR — instead of a single from number, use a Messaging Service:
+    // messagingServiceSid: 'MG...',
+    // Optional webhook for status updates (queued → sent → delivered/failed):
+    // statusCallback: 'https://hooks.acme.io/twilio',
+  }),
+});
+
+const result = await dispatcher.sms({
+  to: '+12025550100',
+  body: 'Your verification code: 482910',
+});
+
+console.log(result.id); // Twilio Message SID (SM...)
+```
+
+## API
+
+```ts
+createTwilioAdapter({
+  client,                  // Required — your twilio(sid, token)
+  defaultFrom?,            // E.164 origination — required if no service
+  messagingServiceSid?,    // Use service-based routing instead of `from`
+  statusCallback?,         // Webhook URL for delivery status updates
+});
+```
+
+### Sender precedence
+
+1. `message.from` (per-call) — always wins
+2. `defaultFrom` (adapter option)
+3. `messagingServiceSid` (adapter option)
+
+If none are set, the adapter throws.
+
+## Error mapping
+
+Twilio's SDK rejects on most errors (rate limit, invalid number,
+account suspended). The adapter lets the rejection propagate so
+`@absolutejs/dispatch`'s error path runs (failed counter, ERROR span,
+`dispatch.sms.failed` audit).
+
+A returned response with `errorCode != null` is the
+bulk-send/queue-rejection case — Twilio doesn't throw but signals
+the error in the response. The adapter throws on this too:
+
+```ts
+{ errorCode: 21610, errorMessage: 'Recipient unsubscribed' }
+// → throws "Twilio errorCode 21610: Recipient unsubscribed"
+```
+
+## License
+
+[Apache 2.0](../LICENSE). Tier B substrate-adjacent — rides
+`@absolutejs/dispatch` (BSL Tier A) and `twilio` (MIT).

package/dist/index.d.ts

@@ -0,0 +1,68 @@
+/**
+ * @absolutejs/dispatch-twilio — Twilio-backed `SmsAdapter` for
+ * `@absolutejs/dispatch`.
+ *
+ * Takes the user's Twilio client. Maps `SmsMessage` to Twilio's
+ * `messages.create` params; surfaces the Message SID as
+ * `DispatchResult.id`.
+ *
+ * Twilio's `messages.create` throws on API errors (rate limiting,
+ * invalid number, account suspended, etc), so the adapter's error
+ * path is "let Twilio's rejection propagate." `@absolutejs/dispatch`
+ * captures it on the `dispatch.sms.send` span, bumps the failed
+ * counter, and emits `dispatch.sms.failed`.
+ *
+ * **Two ways to identify the sender.** Twilio supports either a phone
+ * number (`from`) OR a Messaging Service SID (`messagingServiceSid`).
+ * Pass `messagingServiceSid` in adapter options to use service-based
+ * sending (per-region routing, sender pool, content opt-out
+ * management); leave it unset to require `from` per message or
+ * `defaultFrom`.
+ */
+import type { SmsAdapter } from '@absolutejs/dispatch';
+/**
+ * Minimal subset of Twilio's client we use. `client.messages.create`
+ * is the canonical send entry. Twilio's typed SDK is large; we don't
+ * pull its types in — `TwilioClientLike` describes only the shape
+ * we touch.
+ */
+export type TwilioClientLike = {
+    messages: {
+        create: (params: {
+            to: string;
+            body: string;
+            from?: string;
+            messagingServiceSid?: string;
+            statusCallback?: string;
+        }) => Promise<{
+            sid?: string;
+            status?: string;
+            errorCode?: number | null;
+            errorMessage?: string | null;
+        }>;
+    };
+};
+export type CreateTwilioAdapterOptions = {
+    /** The Twilio client (`twilio(accountSid, authToken)`). */
+    client: TwilioClientLike;
+    /**
+     * Default origination number (E.164). Required if your messages
+     * don't supply `from` AND you're not using a Messaging Service.
+     */
+    defaultFrom?: string;
+    /**
+     * Twilio Messaging Service SID. When set, the adapter uses
+     * service-based routing instead of a single origination number.
+     * Pass this OR `defaultFrom`, not both — per-message `from`
+     * overrides this on a per-call basis.
+     */
+    messagingServiceSid?: string;
+    /**
+     * Twilio status callback URL — invoked when message status
+     * changes (queued → sent → delivered/failed). Wire this to your
+     * own webhook to record delivery in audit.
+     */
+    statusCallback?: string;
+};
+export declare const createTwilioAdapter: (options: CreateTwilioAdapterOptions) => SmsAdapter;
+//# 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;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,OAAO,KAAK,EAAE,UAAU,EAAc,MAAM,sBAAsB,CAAC;AAEnE;;;;;GAKG;AACH,MAAM,MAAM,gBAAgB,GAAG;IAC9B,QAAQ,EAAE;QACT,MAAM,EAAE,CAAC,MAAM,EAAE;YAChB,EAAE,EAAE,MAAM,CAAC;YACX,IAAI,EAAE,MAAM,CAAC;YACb,IAAI,CAAC,EAAE,MAAM,CAAC;YACd,mBAAmB,CAAC,EAAE,MAAM,CAAC;YAC7B,cAAc,CAAC,EAAE,MAAM,CAAC;SACxB,KAAK,OAAO,CAAC;YACb,GAAG,CAAC,EAAE,MAAM,CAAC;YACb,MAAM,CAAC,EAAE,MAAM,CAAC;YAChB,SAAS,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;YAC1B,YAAY,CAAC,EAAE,MAAM,GAAG,IAAI,CAAC;SAC7B,CAAC,CAAC;KACH,CAAC;CACF,CAAC;AAEF,MAAM,MAAM,0BAA0B,GAAG;IACxC,2DAA2D;IAC3D,MAAM,EAAE,gBAAgB,CAAC;IACzB;;;OAGG;IACH,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB;;;;;OAKG;IACH,mBAAmB,CAAC,EAAE,MAAM,CAAC;IAC7B;;;;OAIG;IACH,cAAc,CAAC,EAAE,MAAM,CAAC;CACxB,CAAC;AAEF,eAAO,MAAM,mBAAmB,GAC/B,SAAS,0BAA0B,KACjC,UA+CF,CAAC"}

package/dist/index.js

@@ -0,0 +1,41 @@
+// @bun
+// src/index.ts
+var createTwilioAdapter = (options) => {
+  const { client } = options;
+  return {
+    name: "twilio",
+    send: async (message) => {
+      const from = message.from ?? options.defaultFrom;
+      if (from === undefined && options.messagingServiceSid === undefined) {
+        throw new Error("[dispatch-twilio] no sender configured. " + "Pass `message.from`, `createTwilioAdapter({ defaultFrom })`, or " + "`createTwilioAdapter({ messagingServiceSid })`.");
+      }
+      const params = {
+        body: message.body,
+        to: message.to
+      };
+      if (from !== undefined)
+        params.from = from;
+      else if (options.messagingServiceSid !== undefined) {
+        params.messagingServiceSid = options.messagingServiceSid;
+      }
+      if (options.statusCallback !== undefined) {
+        params.statusCallback = options.statusCallback;
+      }
+      const response = await client.messages.create(params);
+      if (response.errorCode !== null && response.errorCode !== undefined) {
+        throw new Error(`[dispatch-twilio] Twilio errorCode ${response.errorCode}: ${response.errorMessage ?? "(no message)"}`);
+      }
+      return {
+        at: Date.now(),
+        ...response.sid !== undefined ? { id: response.sid } : {},
+        provider: "twilio"
+      };
+    }
+  };
+};
+export {
+  createTwilioAdapter
+};
+
+//# debugId=92068E85E39BDEE164756E2164756E21
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1,10 @@
+{
+  "version": 3,
+  "sources": ["../src/index.ts"],
+  "sourcesContent": [
+    "/**\n * @absolutejs/dispatch-twilio — Twilio-backed `SmsAdapter` for\n * `@absolutejs/dispatch`.\n *\n * Takes the user's Twilio client. Maps `SmsMessage` to Twilio's\n * `messages.create` params; surfaces the Message SID as\n * `DispatchResult.id`.\n *\n * Twilio's `messages.create` throws on API errors (rate limiting,\n * invalid number, account suspended, etc), so the adapter's error\n * path is \"let Twilio's rejection propagate.\" `@absolutejs/dispatch`\n * captures it on the `dispatch.sms.send` span, bumps the failed\n * counter, and emits `dispatch.sms.failed`.\n *\n * **Two ways to identify the sender.** Twilio supports either a phone\n * number (`from`) OR a Messaging Service SID (`messagingServiceSid`).\n * Pass `messagingServiceSid` in adapter options to use service-based\n * sending (per-region routing, sender pool, content opt-out\n * management); leave it unset to require `from` per message or\n * `defaultFrom`.\n */\nimport type { SmsAdapter, SmsMessage } from '@absolutejs/dispatch';\n\n/**\n * Minimal subset of Twilio's client we use. `client.messages.create`\n * is the canonical send entry. Twilio's typed SDK is large; we don't\n * pull its types in — `TwilioClientLike` describes only the shape\n * we touch.\n */\nexport type TwilioClientLike = {\n\tmessages: {\n\t\tcreate: (params: {\n\t\t\tto: string;\n\t\t\tbody: string;\n\t\t\tfrom?: string;\n\t\t\tmessagingServiceSid?: string;\n\t\t\tstatusCallback?: string;\n\t\t}) => Promise<{\n\t\t\tsid?: string;\n\t\t\tstatus?: string;\n\t\t\terrorCode?: number | null;\n\t\t\terrorMessage?: string | null;\n\t\t}>;\n\t};\n};\n\nexport type CreateTwilioAdapterOptions = {\n\t/** The Twilio client (`twilio(accountSid, authToken)`). */\n\tclient: TwilioClientLike;\n\t/**\n\t * Default origination number (E.164). Required if your messages\n\t * don't supply `from` AND you're not using a Messaging Service.\n\t */\n\tdefaultFrom?: string;\n\t/**\n\t * Twilio Messaging Service SID. When set, the adapter uses\n\t * service-based routing instead of a single origination number.\n\t * Pass this OR `defaultFrom`, not both — per-message `from`\n\t * overrides this on a per-call basis.\n\t */\n\tmessagingServiceSid?: string;\n\t/**\n\t * Twilio status callback URL — invoked when message status\n\t * changes (queued → sent → delivered/failed). Wire this to your\n\t * own webhook to record delivery in audit.\n\t */\n\tstatusCallback?: string;\n};\n\nexport const createTwilioAdapter = (\n\toptions: CreateTwilioAdapterOptions\n): SmsAdapter => {\n\tconst { client } = options;\n\n\treturn {\n\t\tname: 'twilio',\n\t\tsend: async (message: SmsMessage) => {\n\t\t\tconst from = message.from ?? options.defaultFrom;\n\t\t\tif (\n\t\t\t\tfrom === undefined &&\n\t\t\t\toptions.messagingServiceSid === undefined\n\t\t\t) {\n\t\t\t\tthrow new Error(\n\t\t\t\t\t'[dispatch-twilio] no sender configured. ' +\n\t\t\t\t\t\t'Pass `message.from`, `createTwilioAdapter({ defaultFrom })`, or ' +\n\t\t\t\t\t\t'`createTwilioAdapter({ messagingServiceSid })`.'\n\t\t\t\t);\n\t\t\t}\n\t\t\tconst params: Parameters<TwilioClientLike['messages']['create']>[0] = {\n\t\t\t\tbody: message.body,\n\t\t\t\tto: message.to\n\t\t\t};\n\t\t\tif (from !== undefined) params.from = from;\n\t\t\telse if (options.messagingServiceSid !== undefined) {\n\t\t\t\tparams.messagingServiceSid = options.messagingServiceSid;\n\t\t\t}\n\t\t\tif (options.statusCallback !== undefined) {\n\t\t\t\tparams.statusCallback = options.statusCallback;\n\t\t\t}\n\t\t\tconst response = await client.messages.create(params);\n\t\t\t// Twilio's SDK rejects on API errors via thrown errors, so a\n\t\t\t// returned response with `errorCode != null` is the\n\t\t\t// unusual-but-documented case (some bulk-send flows).\n\t\t\tif (\n\t\t\t\tresponse.errorCode !== null &&\n\t\t\t\tresponse.errorCode !== undefined\n\t\t\t) {\n\t\t\t\tthrow new Error(\n\t\t\t\t\t`[dispatch-twilio] Twilio errorCode ${response.errorCode}: ${response.errorMessage ?? '(no message)'}`\n\t\t\t\t);\n\t\t\t}\n\t\t\treturn {\n\t\t\t\tat: Date.now(),\n\t\t\t\t...(response.sid !== undefined ? { id: response.sid } : {}),\n\t\t\t\tprovider: 'twilio'\n\t\t\t};\n\t\t}\n\t};\n};\n"
+  ],
+  "mappings": ";;AAqEO,IAAM,sBAAsB,CAClC,YACgB;AAAA,EAChB,QAAQ,WAAW;AAAA,EAEnB,OAAO;AAAA,IACN,MAAM;AAAA,IACN,MAAM,OAAO,YAAwB;AAAA,MACpC,MAAM,OAAO,QAAQ,QAAQ,QAAQ;AAAA,MACrC,IACC,SAAS,aACT,QAAQ,wBAAwB,WAC/B;AAAA,QACD,MAAM,IAAI,MACT,6CACC,qEACA,iDACF;AAAA,MACD;AAAA,MACA,MAAM,SAAgE;AAAA,QACrE,MAAM,QAAQ;AAAA,QACd,IAAI,QAAQ;AAAA,MACb;AAAA,MACA,IAAI,SAAS;AAAA,QAAW,OAAO,OAAO;AAAA,MACjC,SAAI,QAAQ,wBAAwB,WAAW;AAAA,QACnD,OAAO,sBAAsB,QAAQ;AAAA,MACtC;AAAA,MACA,IAAI,QAAQ,mBAAmB,WAAW;AAAA,QACzC,OAAO,iBAAiB,QAAQ;AAAA,MACjC;AAAA,MACA,MAAM,WAAW,MAAM,OAAO,SAAS,OAAO,MAAM;AAAA,MAIpD,IACC,SAAS,cAAc,QACvB,SAAS,cAAc,WACtB;AAAA,QACD,MAAM,IAAI,MACT,sCAAsC,SAAS,cAAc,SAAS,gBAAgB,gBACvF;AAAA,MACD;AAAA,MACA,OAAO;AAAA,QACN,IAAI,KAAK,IAAI;AAAA,WACT,SAAS,QAAQ,YAAY,EAAE,IAAI,SAAS,IAAI,IAAI,CAAC;AAAA,QACzD,UAAU;AAAA,MACX;AAAA;AAAA,EAEF;AAAA;",
+  "debugId": "92068E85E39BDEE164756E2164756E21",
+  "names": []
+}

package/package.json

@@ -0,0 +1,54 @@
+{
+	"name": "@absolutejs/dispatch-twilio",
+	"version": "0.0.1",
+	"description": "Twilio-backed SmsAdapter for @absolutejs/dispatch. Maps SmsMessage to Twilio messages.create; surfaces the Message SID as DispatchResult.id.",
+	"repository": {
+		"type": "git",
+		"url": "https://github.com/absolutejs/dispatch-adapters.git",
+		"directory": "twilio"
+	},
+	"main": "./dist/index.js",
+	"module": "./dist/index.js",
+	"types": "./dist/index.d.ts",
+	"type": "module",
+	"license": "Apache-2.0",
+	"author": "Alex Kahn",
+	"publishConfig": {
+		"access": "public"
+	},
+	"keywords": [
+		"dispatch",
+		"sms",
+		"twilio",
+		"absolutejs",
+		"transactional"
+	],
+	"scripts": {
+		"build": "rm -rf dist && bun build src/index.ts --outdir dist --sourcemap --target=bun --external @absolutejs/dispatch --external twilio && tsc --project tsconfig.build.json",
+		"test": "bun test",
+		"typecheck": "tsc --noEmit",
+		"format": "prettier --write \"./**/*.{ts,json,md}\"",
+		"release": "bun run format && bun run build && bun publish"
+	},
+	"peerDependencies": {
+		"@absolutejs/dispatch": ">= 0.0.1",
+		"twilio": ">= 5.0.0"
+	},
+	"devDependencies": {
+		"@absolutejs/dispatch": "^0.0.1",
+		"@types/bun": "1.3.14",
+		"prettier": "3.5.3",
+		"typescript": "5.8.3"
+	},
+	"exports": {
+		".": {
+			"types": "./dist/index.d.ts",
+			"import": "./dist/index.js",
+			"default": "./dist/index.js"
+		}
+	},
+	"files": [
+		"dist",
+		"README.md"
+	]
+}