@theokit/gateway-sms 0.1.0

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
package/CHANGELOG.md ADDED
@@ -0,0 +1,35 @@
1
+ # Changelog
2
+
3
+ ## 2.0.0
4
+
5
+ ### Patch Changes
6
+
7
+ - Updated dependencies
8
+ - @theokit/sdk@1.3.0
9
+ - @theokit/gateway@2.0.0
10
+
11
+ ## 1.0.0
12
+
13
+ ### Patch Changes
14
+
15
+ - Updated dependencies
16
+ - @theokit/sdk@1.2.0
17
+ - @theokit/gateway@1.0.0
18
+
19
+ ## [Unreleased]
20
+
21
+ ### Added — `@theokit/gateway-sms@0.1.0` (ADRs D389-D396)
22
+
23
+ - Initial release of the SMS platform adapter for `@theokit/gateway`.
24
+ - Multi-backend opt-in: Twilio + Plivo + Vonage (D389). Each peer-dep is optional; install only what you use.
25
+ - `SMSAdapter` extending `BasePlatformAdapter` with:
26
+ - `connect()` / `disconnect()` lifecycle (idempotent)
27
+ - `sendMessage()` outbound with multipart `(i/N)` segmentation up to 1600 chars per part (D393), Intl.Segmenter surrogate-safe
28
+ - `onInbound()` subscription (single-handler replace semantics — EC-H)
29
+ - `createWebhookServer()` Express helper with per-backend routes (`/sms/twilio`, `/sms/plivo`, `/sms/vonage`) and per-backend HMAC signature validation (D392) — rejects with 401 BEFORE handler dispatch.
30
+ - Constructor enforces signing secret (EC-1 absorbed): missing `authToken` throws `ConfigurationError` at construction time, never permits unsigned mode.
31
+ - `normalizeE164(input, defaultCountry?)` strict phone normalization via `libphonenumber-js` (D391). Accepts mobile + toll-free US numbers (EC-6).
32
+ - `splitForSMS(text, limit=1600)` UTF-16 / grapheme-cluster safe segmentation (EC-7).
33
+ - Tracks `SMSInbound` → `SMSMessageEvent` normalization with E.164 enforcement.
34
+ - No threading model: SMS conversations are flat per phone-pair (D394). `channel.type` always `"dm"`.
35
+ - MMS, group SMS, and budget-charge-per-message are deferred to v0.2 (D395, D396).
package/README.md ADDED
@@ -0,0 +1,105 @@
1
+ # @theokit/gateway-sms
2
+
3
+ SMS platform adapter for [`@theokit/gateway`](../gateway).
4
+
5
+ Three backends, opt-in via peer-dep:
6
+
7
+ | Backend | Peer-dep | Inbound signature header |
8
+ |---|---|---|
9
+ | Twilio | `twilio` | `X-Twilio-Signature` (HMAC-SHA1 over URL+params) |
10
+ | Plivo | `plivo` | `X-Plivo-Signature-V3` (HMAC-SHA256) |
11
+ | Vonage | `@vonage/server-sdk` | `Authorization: Bearer <JWT>` |
12
+
13
+ ## Install
14
+
15
+ ```bash
16
+ pnpm add @theokit/sdk @theokit/gateway @theokit/gateway-sms
17
+
18
+ # Then install ONE of the backends you actually use:
19
+ pnpm add twilio # for Twilio
20
+ pnpm add plivo # for Plivo
21
+ pnpm add @vonage/server-sdk # for Vonage
22
+ ```
23
+
24
+ You also need `libphonenumber-js` (E.164 normalization) and `express` (webhook server). Both are listed as optional peer-deps and resolved on first use.
25
+
26
+ ## Quick start (Twilio)
27
+
28
+ ```ts
29
+ import { Agent } from "@theokit/sdk";
30
+ import { GatewayRunner } from "@theokit/gateway";
31
+ import { SMSAdapter, createWebhookServer } from "@theokit/gateway-sms";
32
+
33
+ const adapter = new SMSAdapter({
34
+ backend: "twilio",
35
+ accountSid: process.env.TWILIO_ACCOUNT_SID!,
36
+ authToken: process.env.TWILIO_AUTH_TOKEN!,
37
+ fromNumber: process.env.TWILIO_FROM!,
38
+ // Public URL where Twilio will POST inbound — required for signature validation.
39
+ publicUrl: process.env.PUBLIC_URL!, // e.g. https://abc.ngrok.io
40
+ });
41
+
42
+ const runner = new GatewayRunner({
43
+ adapters: [adapter],
44
+ handler: async (event, ctx) => {
45
+ if (event.platform !== "sms") return;
46
+ await ctx.reply(`Echo: ${event.text}`);
47
+ },
48
+ });
49
+
50
+ await runner.start();
51
+ const server = createWebhookServer({ adapter, port: 3000 });
52
+ await server.start();
53
+ ```
54
+
55
+ ### Twilio Console setup
56
+
57
+ 1. Create a Twilio number with SMS capability.
58
+ 2. In the number's *Voice & Messaging* configuration, set **A message comes in** → `Webhook` → `https://your-public-url/sms/twilio`.
59
+ 3. Method: `HTTP POST`.
60
+
61
+ For local development, `ngrok http 3000` and use the `https://*.ngrok.io` URL.
62
+
63
+ ## Signature enforcement (D392)
64
+
65
+ `SMSAdapter` refuses to start with an empty `authToken` — webhook public endpoint without HMAC validation is a known security hole. The constructor throws `ConfigurationError({ code: "signing_secret_required" })` if you try.
66
+
67
+ If a request arrives without (or with invalid) signature, the webhook responds `401 Unauthorized` BEFORE any handler dispatch.
68
+
69
+ ## Multipart split (D393)
70
+
71
+ Outbound messages longer than 1600 chars are split into `(1/N) ...` / `(2/N) ...` parts. Split is grapheme-cluster safe (`Intl.Segmenter`) so emoji and combining characters are not severed.
72
+
73
+ Each part is one billable outbound message at the carrier. Plan accordingly.
74
+
75
+ ## E.164 normalization (D391)
76
+
77
+ All phone numbers — inbound `sender.id`, outbound `channel.id` — are normalized to E.164 (`+5511999999999`) via `libphonenumber-js`. Non-parseable inputs throw `ConfigurationError`.
78
+
79
+ US toll-free numbers (`+18001234567`) are accepted (EC-6).
80
+
81
+ ## What's NOT supported in v0.1
82
+
83
+ | Feature | Status | Workaround |
84
+ |---|---|---|
85
+ | MMS (image/audio attachment) | Deferred to v0.2 (D395) | Use Twilio API direct via `adapter.getBackendClient()` |
86
+ | Group SMS (MMS group thread on US carriers) | Not supported (D394) | — |
87
+ | Auto budget per-message charge | Deferred to v0.2 (D396) | Charge via your own counter |
88
+ | Delivery status callback (delivered/failed post-200) | Deferred to v0.2 (EC-13) | Subscribe via Twilio statusCallback URL |
89
+
90
+ ## Live smoke
91
+
92
+ ```bash
93
+ SMS_LIVE_SMOKE=1 \
94
+ TWILIO_ACCOUNT_SID=... \
95
+ TWILIO_AUTH_TOKEN=... \
96
+ TWILIO_FROM=+1... \
97
+ TWILIO_TO=+55... \
98
+ pnpm --filter @theokit/gateway-sms test
99
+ ```
100
+
101
+ The live smoke sends one real SMS through Twilio's API (test creds work; they cost ~$0.01/SMS in production accounts). Skip by leaving `SMS_LIVE_SMOKE` unset (default).
102
+
103
+ ## ADRs
104
+
105
+ D389 – D396 in `.claude/knowledge-base/adrs/`.