@theokit/gateway-sms 0.5.0 → 0.6.1
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 +12 -0
- package/README.md +21 -6
- package/dist/index.cjs +147 -58
- package/dist/index.cjs.map +1 -1
- package/dist/index.d.cts +28 -6
- package/dist/index.d.ts +28 -6
- package/dist/index.js +147 -58
- package/dist/index.js.map +1 -1
- package/package.json +2 -2
package/CHANGELOG.md
CHANGED
|
@@ -1,5 +1,17 @@
|
|
|
1
1
|
# Changelog
|
|
2
2
|
|
|
3
|
+
## 0.6.1
|
|
4
|
+
|
|
5
|
+
### Patch Changes
|
|
6
|
+
|
|
7
|
+
- 8585427: README status lines say "0.x, pre-1.0" instead of a hard-coded version.
|
|
8
|
+
|
|
9
|
+
## 0.6.0
|
|
10
|
+
|
|
11
|
+
### Minor Changes
|
|
12
|
+
|
|
13
|
+
- 3158f63: The `whatsappChannel` Cloud variant and `smsChannel` descriptors now declare `transport: "webhook"` with a `webhook.handle`, so a host mounts them with `createWebhookHandler`. WhatsApp answers Meta's subscription check and verifies `x-hub-signature-256`; SMS verifies Twilio's signature against the configured `publicUrl`. The Express listeners are unchanged.
|
|
14
|
+
|
|
3
15
|
## 0.5.0
|
|
4
16
|
|
|
5
17
|
### Minor Changes
|
package/README.md
CHANGED
|
@@ -111,14 +111,14 @@ All phone numbers — inbound `sender.id`, outbound `channel.id` — are normali
|
|
|
111
111
|
|
|
112
112
|
US toll-free numbers (`+18001234567`) are accepted (EC-6).
|
|
113
113
|
|
|
114
|
-
## What's NOT supported
|
|
114
|
+
## What's NOT supported yet
|
|
115
115
|
|
|
116
116
|
| Feature | Status | Workaround |
|
|
117
117
|
|---|---|---|
|
|
118
|
-
| MMS (image/audio attachment) | Deferred
|
|
118
|
+
| MMS (image/audio attachment) | Deferred (D395) | Use Twilio API direct via `adapter.getBackendClient()` |
|
|
119
119
|
| Group SMS (MMS group thread on US carriers) | Not supported (D394) | — |
|
|
120
|
-
| Auto budget per-message charge | Deferred
|
|
121
|
-
| Delivery status callback (delivered/failed post-200) | Deferred
|
|
120
|
+
| Auto budget per-message charge | Deferred (D396) | Charge via your own counter |
|
|
121
|
+
| Delivery status callback (delivered/failed post-200) | Deferred (EC-13) | Subscribe via Twilio statusCallback URL |
|
|
122
122
|
|
|
123
123
|
## Live smoke
|
|
124
124
|
|
|
@@ -158,5 +158,20 @@ const { adapters, rejected } = createChannels([{ descriptor: smsChannel, config
|
|
|
158
158
|
| `publicUrl` | `SMS_PUBLIC_URL` | yes | no |
|
|
159
159
|
|
|
160
160
|
`create` throws `ConfigurationError` (`invalid_config`) naming the key for a missing or non-string
|
|
161
|
-
value. The descriptor declares `transport: "
|
|
162
|
-
|
|
161
|
+
value. The descriptor declares `transport: "webhook"`; `createWebhookServer` (Express) keeps working.
|
|
162
|
+
|
|
163
|
+
### Mounting the route
|
|
164
|
+
|
|
165
|
+
`webhook.handle` verifies `X-Twilio-Signature` against the configured `publicUrl` (never the
|
|
166
|
+
request's Host header), answers 401 on a bad signature, 400 when the form body holds no message,
|
|
167
|
+
and otherwise delivers and answers 200 (500 or 503 when the handler threw or none is subscribed).
|
|
168
|
+
|
|
169
|
+
```ts
|
|
170
|
+
import { createChannels, createWebhookHandler } from "@theokit/gateway";
|
|
171
|
+
import { smsChannel } from "@theokit/gateway-sms";
|
|
172
|
+
|
|
173
|
+
const { channels } = createChannels([{ descriptor: smsChannel, config }]);
|
|
174
|
+
const handle = createWebhookHandler({ channels, isStarted: () => true });
|
|
175
|
+
// POST /webhooks/sms -> handle(request)
|
|
176
|
+
```
|
|
177
|
+
|
package/dist/index.cjs
CHANGED
|
@@ -618,6 +618,24 @@ var SMSAdapter = class extends gateway.BasePlatformAdapter {
|
|
|
618
618
|
async deliver(event) {
|
|
619
619
|
return this.runHandler(this.inboundHandler, event);
|
|
620
620
|
}
|
|
621
|
+
/**
|
|
622
|
+
* Deliver like {@link deliver}, but a throwing handler is logged by name only: its message can
|
|
623
|
+
* carry the inbound text, which the webhook route must not write to a log line.
|
|
624
|
+
*
|
|
625
|
+
* @internal
|
|
626
|
+
*/
|
|
627
|
+
async deliverQuietly(event) {
|
|
628
|
+
const handler = this.inboundHandler;
|
|
629
|
+
if (handler === void 0) return "no_handler";
|
|
630
|
+
try {
|
|
631
|
+
await handler(event);
|
|
632
|
+
} catch {
|
|
633
|
+
process.stderr.write(`[sms] handler threw
|
|
634
|
+
`);
|
|
635
|
+
return "handler_threw";
|
|
636
|
+
}
|
|
637
|
+
return "ok";
|
|
638
|
+
}
|
|
621
639
|
};
|
|
622
640
|
function secretFromOpts(opts) {
|
|
623
641
|
switch (opts.backend) {
|
|
@@ -633,6 +651,128 @@ function secretFromOpts(opts) {
|
|
|
633
651
|
}
|
|
634
652
|
}
|
|
635
653
|
|
|
654
|
+
// src/parse-inbound.ts
|
|
655
|
+
function parseInbound(options2, ctx) {
|
|
656
|
+
const backend = createBackend(options2);
|
|
657
|
+
let inbound;
|
|
658
|
+
try {
|
|
659
|
+
inbound = backend.parseInbound(ctx);
|
|
660
|
+
} catch {
|
|
661
|
+
return null;
|
|
662
|
+
}
|
|
663
|
+
if (inbound.messageId === "") return null;
|
|
664
|
+
return inboundToMessageEvent(inbound, options2.backend);
|
|
665
|
+
}
|
|
666
|
+
function decode(s) {
|
|
667
|
+
return decodeURIComponent(s.replace(/\+/g, " "));
|
|
668
|
+
}
|
|
669
|
+
function parseForm(body) {
|
|
670
|
+
const out = [];
|
|
671
|
+
for (const pair of body.split("&")) {
|
|
672
|
+
if (pair.length === 0) continue;
|
|
673
|
+
const eq = pair.indexOf("=");
|
|
674
|
+
out.push([decode(eq < 0 ? pair : pair.slice(0, eq)), decode(eq < 0 ? "" : pair.slice(eq + 1))]);
|
|
675
|
+
}
|
|
676
|
+
return out;
|
|
677
|
+
}
|
|
678
|
+
function compare(a, b) {
|
|
679
|
+
if (a === b) return 0;
|
|
680
|
+
return a < b ? -1 : 1;
|
|
681
|
+
}
|
|
682
|
+
function sign(authToken, url, pairs) {
|
|
683
|
+
const sorted = [...pairs].sort((x, y) => compare(x[0], y[0]) || compare(x[1], y[1]));
|
|
684
|
+
let data = url;
|
|
685
|
+
for (const [k, v] of sorted) data += k + v;
|
|
686
|
+
return crypto.createHmac("sha1", authToken).update(data, "utf8").digest("base64");
|
|
687
|
+
}
|
|
688
|
+
function verifyTwilioSignature(authToken, url, rawBody, signature) {
|
|
689
|
+
if (signature === void 0 || signature.length === 0) return false;
|
|
690
|
+
let pairs;
|
|
691
|
+
try {
|
|
692
|
+
pairs = parseForm(rawBody);
|
|
693
|
+
} catch {
|
|
694
|
+
return false;
|
|
695
|
+
}
|
|
696
|
+
const expected = Buffer.from(sign(authToken, url, pairs));
|
|
697
|
+
const actual = Buffer.from(signature);
|
|
698
|
+
return expected.length === actual.length && crypto.timingSafeEqual(expected, actual);
|
|
699
|
+
}
|
|
700
|
+
function twilioRequestVerifier(opts) {
|
|
701
|
+
return async (request) => {
|
|
702
|
+
const header = request.headers.get("x-twilio-signature");
|
|
703
|
+
if (header === null || header.length === 0) {
|
|
704
|
+
return { ok: false, reason: "missing X-Twilio-Signature header" };
|
|
705
|
+
}
|
|
706
|
+
const ok = verifyTwilioSignature(
|
|
707
|
+
opts.authToken,
|
|
708
|
+
opts.publicUrl ?? request.url,
|
|
709
|
+
await request.text(),
|
|
710
|
+
header
|
|
711
|
+
);
|
|
712
|
+
if (!ok) return { ok: false, reason: "signature mismatch" };
|
|
713
|
+
return { ok: true };
|
|
714
|
+
};
|
|
715
|
+
}
|
|
716
|
+
|
|
717
|
+
// src/fetch-webhook.ts
|
|
718
|
+
var options = /* @__PURE__ */ new WeakMap();
|
|
719
|
+
function rememberSmsOptions(adapter, opts) {
|
|
720
|
+
options.set(adapter, opts);
|
|
721
|
+
}
|
|
722
|
+
function statusFor(outcomes) {
|
|
723
|
+
let status = 200;
|
|
724
|
+
for (const outcome of outcomes) {
|
|
725
|
+
if (outcome === "handler_threw") status = 500;
|
|
726
|
+
else if (outcome === "no_handler" && status === 200) status = 503;
|
|
727
|
+
}
|
|
728
|
+
return status;
|
|
729
|
+
}
|
|
730
|
+
function lowerHeaders(headers) {
|
|
731
|
+
const out = {};
|
|
732
|
+
for (const [key, value] of Object.entries(headers)) {
|
|
733
|
+
if (value !== void 0) out[key.toLowerCase()] = value;
|
|
734
|
+
}
|
|
735
|
+
return out;
|
|
736
|
+
}
|
|
737
|
+
function verified(opts, request) {
|
|
738
|
+
if (opts === void 0 || opts.authToken.trim().length === 0) return false;
|
|
739
|
+
return verifyTwilioSignature(
|
|
740
|
+
opts.authToken,
|
|
741
|
+
opts.publicUrl,
|
|
742
|
+
request.rawBody,
|
|
743
|
+
lowerHeaders(request.headers)["x-twilio-signature"]
|
|
744
|
+
);
|
|
745
|
+
}
|
|
746
|
+
function toEvent(opts, rawBody, headers) {
|
|
747
|
+
return parseInbound(opts, { headers, rawBody, url: opts.publicUrl });
|
|
748
|
+
}
|
|
749
|
+
var twilioWebhook = {
|
|
750
|
+
methods: ["POST"],
|
|
751
|
+
/** The same check `handle` makes; needs no connection. */
|
|
752
|
+
verify(adapter, request) {
|
|
753
|
+
return verified(options.get(adapter), request);
|
|
754
|
+
},
|
|
755
|
+
/** A payload of form fields (as an object) is parsed like the form body and delivered. */
|
|
756
|
+
async ingest(adapter, payload) {
|
|
757
|
+
const opts = options.get(adapter);
|
|
758
|
+
if (opts === void 0 || payload === null || typeof payload !== "object") return "malformed";
|
|
759
|
+
const form = new URLSearchParams();
|
|
760
|
+
for (const [key, value] of Object.entries(payload)) {
|
|
761
|
+
if (typeof value === "string") form.set(key, value);
|
|
762
|
+
}
|
|
763
|
+
const event = toEvent(opts, form.toString(), {});
|
|
764
|
+
if (event === null) return "malformed";
|
|
765
|
+
return statusFor([await adapter.deliverQuietly(event)]) === 200 ? "delivered" : "no_handler";
|
|
766
|
+
},
|
|
767
|
+
async handle(adapter, request) {
|
|
768
|
+
const opts = options.get(adapter);
|
|
769
|
+
if (opts === void 0 || !verified(opts, request)) return { status: 401 };
|
|
770
|
+
const event = toEvent(opts, request.rawBody, lowerHeaders(request.headers));
|
|
771
|
+
if (event === null) return { status: 400 };
|
|
772
|
+
return { status: statusFor([await adapter.deliverQuietly(event)]) };
|
|
773
|
+
}
|
|
774
|
+
};
|
|
775
|
+
|
|
636
776
|
// src/channel.ts
|
|
637
777
|
var KEYS = ["accountSid", "authToken", "fromNumber", "publicUrl"];
|
|
638
778
|
function readString(config, key) {
|
|
@@ -678,75 +818,24 @@ var CONFIG = [
|
|
|
678
818
|
];
|
|
679
819
|
var smsChannel = {
|
|
680
820
|
platform: "sms",
|
|
681
|
-
transport: "
|
|
821
|
+
transport: "webhook",
|
|
822
|
+
webhook: twilioWebhook,
|
|
682
823
|
config: CONFIG,
|
|
683
824
|
create(config) {
|
|
684
825
|
const [accountSid, authToken, fromNumber, publicUrl] = KEYS.map((k) => readString(config, k));
|
|
685
|
-
|
|
826
|
+
const opts = {
|
|
686
827
|
backend: "twilio",
|
|
687
828
|
accountSid,
|
|
688
829
|
authToken,
|
|
689
830
|
fromNumber,
|
|
690
831
|
publicUrl
|
|
691
|
-
}
|
|
832
|
+
};
|
|
833
|
+
const adapter = new SMSAdapter(opts);
|
|
834
|
+
rememberSmsOptions(adapter, opts);
|
|
835
|
+
return adapter;
|
|
692
836
|
}
|
|
693
837
|
};
|
|
694
838
|
|
|
695
|
-
// src/parse-inbound.ts
|
|
696
|
-
function parseInbound(options, ctx) {
|
|
697
|
-
const backend = createBackend(options);
|
|
698
|
-
let inbound;
|
|
699
|
-
try {
|
|
700
|
-
inbound = backend.parseInbound(ctx);
|
|
701
|
-
} catch {
|
|
702
|
-
return null;
|
|
703
|
-
}
|
|
704
|
-
if (inbound.messageId === "") return null;
|
|
705
|
-
return inboundToMessageEvent(inbound, options.backend);
|
|
706
|
-
}
|
|
707
|
-
function decode(s) {
|
|
708
|
-
return decodeURIComponent(s.replace(/\+/g, " "));
|
|
709
|
-
}
|
|
710
|
-
function parseForm(body) {
|
|
711
|
-
const out = [];
|
|
712
|
-
for (const pair of body.split("&")) {
|
|
713
|
-
if (pair.length === 0) continue;
|
|
714
|
-
const eq = pair.indexOf("=");
|
|
715
|
-
out.push([decode(eq < 0 ? pair : pair.slice(0, eq)), decode(eq < 0 ? "" : pair.slice(eq + 1))]);
|
|
716
|
-
}
|
|
717
|
-
return out;
|
|
718
|
-
}
|
|
719
|
-
function compare(a, b) {
|
|
720
|
-
if (a === b) return 0;
|
|
721
|
-
return a < b ? -1 : 1;
|
|
722
|
-
}
|
|
723
|
-
function sign(authToken, url, pairs) {
|
|
724
|
-
const sorted = [...pairs].sort((x, y) => compare(x[0], y[0]) || compare(x[1], y[1]));
|
|
725
|
-
let data = url;
|
|
726
|
-
for (const [k, v] of sorted) data += k + v;
|
|
727
|
-
return crypto.createHmac("sha1", authToken).update(data, "utf8").digest("base64");
|
|
728
|
-
}
|
|
729
|
-
function twilioRequestVerifier(opts) {
|
|
730
|
-
return async (request) => {
|
|
731
|
-
const header = request.headers.get("x-twilio-signature");
|
|
732
|
-
if (header === null || header.length === 0) {
|
|
733
|
-
return { ok: false, reason: "missing X-Twilio-Signature header" };
|
|
734
|
-
}
|
|
735
|
-
let pairs;
|
|
736
|
-
try {
|
|
737
|
-
pairs = parseForm(await request.text());
|
|
738
|
-
} catch {
|
|
739
|
-
return { ok: false, reason: "unparseable body" };
|
|
740
|
-
}
|
|
741
|
-
const expected = Buffer.from(sign(opts.authToken, opts.publicUrl ?? request.url, pairs));
|
|
742
|
-
const actual = Buffer.from(header);
|
|
743
|
-
if (expected.length !== actual.length || !crypto.timingSafeEqual(expected, actual)) {
|
|
744
|
-
return { ok: false, reason: "signature mismatch" };
|
|
745
|
-
}
|
|
746
|
-
return { ok: true };
|
|
747
|
-
};
|
|
748
|
-
}
|
|
749
|
-
|
|
750
839
|
// src/twiml.ts
|
|
751
840
|
var ILLEGAL = /[\u0000-\u0008\u000B\u000C\u000E-\u001F]/g;
|
|
752
841
|
function esc(s) {
|