@theokit/gateway-whatsapp 0.5.0 → 0.6.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 +37 -0
- package/README.md +6 -3
- package/dist/index.cjs +44 -26
- package/dist/index.cjs.map +1 -1
- package/dist/index.d.cts +28 -19
- package/dist/index.d.ts +28 -19
- package/dist/index.js +44 -26
- package/dist/index.js.map +1 -1
- package/package.json +2 -2
package/dist/index.d.cts
CHANGED
|
@@ -258,26 +258,19 @@ interface WhatsAppBackend {
|
|
|
258
258
|
* the gateway's event shape, as functions of their inputs (the only state is the set of foreign
|
|
259
259
|
* numbers already reported, which the caller owns). `WhatsAppAdapter` holds the configuration and
|
|
260
260
|
* passes it in; every adapter path that decides an inbound message goes through
|
|
261
|
-
* `decideForOwnNumber` (own-number.ts), which calls `isForAnotherNumber` and
|
|
262
|
-
* there is one rule set to keep.
|
|
263
|
-
* messages and for status receipts, so a route built on the backend alone is scoped to its number
|
|
264
|
-
* too.
|
|
261
|
+
* `decideForOwnNumber` (own-number.ts), which calls `isForAnotherNumber` (foreign-number.ts) and
|
|
262
|
+
* `decideInbound`, so there is one rule set to keep.
|
|
265
263
|
*/
|
|
266
264
|
|
|
267
265
|
/** EC-7: digit-only normalizer for mention comparison (handles `+`, `-`, `()`, spaces). */
|
|
268
266
|
declare function digitsOnly(s: string): string;
|
|
269
267
|
|
|
270
268
|
/**
|
|
271
|
-
* `WhatsAppAdapter`
|
|
272
|
-
* (Adoption Roadmap v1.4 #2; ADRs D303-D314).
|
|
273
|
-
*
|
|
274
|
-
* Multi-backend (Cloud + Web) — backend chosen via `WhatsAppAdapterOptions.backend`.
|
|
275
|
-
* Backend-agnostic adapter delegates lifecycle + send + subscribe through the
|
|
276
|
-
* `WhatsAppBackend` seam (D303).
|
|
269
|
+
* The options `WhatsAppAdapter` is built from: one config per backend and the options they share.
|
|
277
270
|
*
|
|
278
|
-
*
|
|
271
|
+
* Moved out of `adapter.ts` unchanged (B-674), so that file stays within its 500-line budget.
|
|
272
|
+
* `adapter.ts` re-exports every type here, so no import of them changes.
|
|
279
273
|
*/
|
|
280
|
-
|
|
281
274
|
/** Cloud (Meta WhatsApp Business Cloud API) backend config (ADR D304). */
|
|
282
275
|
interface WhatsAppCloudConfig {
|
|
283
276
|
/**
|
|
@@ -389,6 +382,18 @@ interface WhatsAppAdapterCommonOptions {
|
|
|
389
382
|
*/
|
|
390
383
|
readonly allowedSenders?: string;
|
|
391
384
|
}
|
|
385
|
+
|
|
386
|
+
/**
|
|
387
|
+
* `WhatsAppAdapter` — WhatsApp platform adapter for `@theokit/gateway`
|
|
388
|
+
* (Adoption Roadmap v1.4 #2; ADRs D303-D314).
|
|
389
|
+
*
|
|
390
|
+
* Multi-backend (Cloud + Web) — backend chosen via `WhatsAppAdapterOptions.backend`.
|
|
391
|
+
* Backend-agnostic adapter delegates lifecycle + send + subscribe through the
|
|
392
|
+
* `WhatsAppBackend` seam (D303).
|
|
393
|
+
*
|
|
394
|
+
* @public
|
|
395
|
+
*/
|
|
396
|
+
|
|
392
397
|
/**
|
|
393
398
|
* Adapter facade. Implements `BasePlatformAdapter` (D172).
|
|
394
399
|
*
|
|
@@ -494,6 +499,7 @@ declare class WhatsAppAdapter extends BasePlatformAdapter {
|
|
|
494
499
|
connect(): Promise<boolean>;
|
|
495
500
|
disconnect(): Promise<void>;
|
|
496
501
|
sendMessage(out: OutboundMessage): Promise<SendResult>;
|
|
502
|
+
private sendText;
|
|
497
503
|
onInbound(handler: (event: MessageEvent) => Promise<void>): () => void;
|
|
498
504
|
/**
|
|
499
505
|
* The event `onInbound` would hand its handler for this inbound message, or `undefined` when the
|
|
@@ -1003,18 +1009,21 @@ declare class WhatsAppCloudBackend implements WhatsAppBackend {
|
|
|
1003
1009
|
* `WhatsAppAdapter` applies too).
|
|
1004
1010
|
*
|
|
1005
1011
|
* @returns `true` if the signature is valid and the body was dispatched (or held nothing to
|
|
1006
|
-
* dispatch). `false` if the signature is invalid, if the
|
|
1007
|
-
*
|
|
1008
|
-
*
|
|
1009
|
-
*
|
|
1010
|
-
*
|
|
1011
|
-
*
|
|
1012
|
+
* dispatch). `false` if the signature is invalid (answer 401), or if the body holds a
|
|
1013
|
+
* message for this number while no inbound handler is subscribed (before `onInbound`,
|
|
1014
|
+
* or after `disconnect()`): the whole body is refused, never a part of it dropped, and
|
|
1015
|
+
* one line on stderr says which; answer non-2xx so Meta redelivers once a handler is
|
|
1016
|
+
* subscribed. `"unreadable_body"` if the signature is valid but the body is not JSON
|
|
1017
|
+
* or has a shape {@link parseWebhookPayload} refuses: nothing is dispatched and one
|
|
1018
|
+
* line on stderr says why. This is not forgery, and redelivery cannot recover it:
|
|
1019
|
+
* Meta resends the same bytes, which are refused again. Answer it differently from a
|
|
1020
|
+
* bad signature (the README example answers 200 so Meta stops retrying). Status receipts with no status handler subscribed
|
|
1012
1021
|
* are discarded on purpose: subscribing to receipts is optional, and refusing them
|
|
1013
1022
|
* would make Meta redeliver every receipt to a route that never wants one.
|
|
1014
1023
|
* @throws {ConfigurationError} `missing_option` when this backend's `appSecret` is empty or
|
|
1015
1024
|
* whitespace only: a signature under an empty key proves nothing.
|
|
1016
1025
|
*/
|
|
1017
|
-
handleWebhookPayload(rawBody: Buffer | string, signatureHeader: string | undefined): Promise<boolean>;
|
|
1026
|
+
handleWebhookPayload(rawBody: Buffer | string, signatureHeader: string | undefined): Promise<boolean | "unreadable_body">;
|
|
1018
1027
|
/**
|
|
1019
1028
|
* Hand each status receipt addressed to this backend's number to the status handler.
|
|
1020
1029
|
*
|
package/dist/index.d.ts
CHANGED
|
@@ -258,26 +258,19 @@ interface WhatsAppBackend {
|
|
|
258
258
|
* the gateway's event shape, as functions of their inputs (the only state is the set of foreign
|
|
259
259
|
* numbers already reported, which the caller owns). `WhatsAppAdapter` holds the configuration and
|
|
260
260
|
* passes it in; every adapter path that decides an inbound message goes through
|
|
261
|
-
* `decideForOwnNumber` (own-number.ts), which calls `isForAnotherNumber` and
|
|
262
|
-
* there is one rule set to keep.
|
|
263
|
-
* messages and for status receipts, so a route built on the backend alone is scoped to its number
|
|
264
|
-
* too.
|
|
261
|
+
* `decideForOwnNumber` (own-number.ts), which calls `isForAnotherNumber` (foreign-number.ts) and
|
|
262
|
+
* `decideInbound`, so there is one rule set to keep.
|
|
265
263
|
*/
|
|
266
264
|
|
|
267
265
|
/** EC-7: digit-only normalizer for mention comparison (handles `+`, `-`, `()`, spaces). */
|
|
268
266
|
declare function digitsOnly(s: string): string;
|
|
269
267
|
|
|
270
268
|
/**
|
|
271
|
-
* `WhatsAppAdapter`
|
|
272
|
-
* (Adoption Roadmap v1.4 #2; ADRs D303-D314).
|
|
273
|
-
*
|
|
274
|
-
* Multi-backend (Cloud + Web) — backend chosen via `WhatsAppAdapterOptions.backend`.
|
|
275
|
-
* Backend-agnostic adapter delegates lifecycle + send + subscribe through the
|
|
276
|
-
* `WhatsAppBackend` seam (D303).
|
|
269
|
+
* The options `WhatsAppAdapter` is built from: one config per backend and the options they share.
|
|
277
270
|
*
|
|
278
|
-
*
|
|
271
|
+
* Moved out of `adapter.ts` unchanged (B-674), so that file stays within its 500-line budget.
|
|
272
|
+
* `adapter.ts` re-exports every type here, so no import of them changes.
|
|
279
273
|
*/
|
|
280
|
-
|
|
281
274
|
/** Cloud (Meta WhatsApp Business Cloud API) backend config (ADR D304). */
|
|
282
275
|
interface WhatsAppCloudConfig {
|
|
283
276
|
/**
|
|
@@ -389,6 +382,18 @@ interface WhatsAppAdapterCommonOptions {
|
|
|
389
382
|
*/
|
|
390
383
|
readonly allowedSenders?: string;
|
|
391
384
|
}
|
|
385
|
+
|
|
386
|
+
/**
|
|
387
|
+
* `WhatsAppAdapter` — WhatsApp platform adapter for `@theokit/gateway`
|
|
388
|
+
* (Adoption Roadmap v1.4 #2; ADRs D303-D314).
|
|
389
|
+
*
|
|
390
|
+
* Multi-backend (Cloud + Web) — backend chosen via `WhatsAppAdapterOptions.backend`.
|
|
391
|
+
* Backend-agnostic adapter delegates lifecycle + send + subscribe through the
|
|
392
|
+
* `WhatsAppBackend` seam (D303).
|
|
393
|
+
*
|
|
394
|
+
* @public
|
|
395
|
+
*/
|
|
396
|
+
|
|
392
397
|
/**
|
|
393
398
|
* Adapter facade. Implements `BasePlatformAdapter` (D172).
|
|
394
399
|
*
|
|
@@ -494,6 +499,7 @@ declare class WhatsAppAdapter extends BasePlatformAdapter {
|
|
|
494
499
|
connect(): Promise<boolean>;
|
|
495
500
|
disconnect(): Promise<void>;
|
|
496
501
|
sendMessage(out: OutboundMessage): Promise<SendResult>;
|
|
502
|
+
private sendText;
|
|
497
503
|
onInbound(handler: (event: MessageEvent) => Promise<void>): () => void;
|
|
498
504
|
/**
|
|
499
505
|
* The event `onInbound` would hand its handler for this inbound message, or `undefined` when the
|
|
@@ -1003,18 +1009,21 @@ declare class WhatsAppCloudBackend implements WhatsAppBackend {
|
|
|
1003
1009
|
* `WhatsAppAdapter` applies too).
|
|
1004
1010
|
*
|
|
1005
1011
|
* @returns `true` if the signature is valid and the body was dispatched (or held nothing to
|
|
1006
|
-
* dispatch). `false` if the signature is invalid, if the
|
|
1007
|
-
*
|
|
1008
|
-
*
|
|
1009
|
-
*
|
|
1010
|
-
*
|
|
1011
|
-
*
|
|
1012
|
+
* dispatch). `false` if the signature is invalid (answer 401), or if the body holds a
|
|
1013
|
+
* message for this number while no inbound handler is subscribed (before `onInbound`,
|
|
1014
|
+
* or after `disconnect()`): the whole body is refused, never a part of it dropped, and
|
|
1015
|
+
* one line on stderr says which; answer non-2xx so Meta redelivers once a handler is
|
|
1016
|
+
* subscribed. `"unreadable_body"` if the signature is valid but the body is not JSON
|
|
1017
|
+
* or has a shape {@link parseWebhookPayload} refuses: nothing is dispatched and one
|
|
1018
|
+
* line on stderr says why. This is not forgery, and redelivery cannot recover it:
|
|
1019
|
+
* Meta resends the same bytes, which are refused again. Answer it differently from a
|
|
1020
|
+
* bad signature (the README example answers 200 so Meta stops retrying). Status receipts with no status handler subscribed
|
|
1012
1021
|
* are discarded on purpose: subscribing to receipts is optional, and refusing them
|
|
1013
1022
|
* would make Meta redeliver every receipt to a route that never wants one.
|
|
1014
1023
|
* @throws {ConfigurationError} `missing_option` when this backend's `appSecret` is empty or
|
|
1015
1024
|
* whitespace only: a signature under an empty key proves nothing.
|
|
1016
1025
|
*/
|
|
1017
|
-
handleWebhookPayload(rawBody: Buffer | string, signatureHeader: string | undefined): Promise<boolean>;
|
|
1026
|
+
handleWebhookPayload(rawBody: Buffer | string, signatureHeader: string | undefined): Promise<boolean | "unreadable_body">;
|
|
1018
1027
|
/**
|
|
1019
1028
|
* Hand each status receipt addressed to this backend's number to the status handler.
|
|
1020
1029
|
*
|
package/dist/index.js
CHANGED
|
@@ -781,23 +781,6 @@ function redactedSender(fromPhone) {
|
|
|
781
781
|
function lastFourDigits(value) {
|
|
782
782
|
return digitsOnly(value).slice(-4);
|
|
783
783
|
}
|
|
784
|
-
function redactedNumberId(phoneNumberId) {
|
|
785
|
-
if (phoneNumberId === void 0) return "no phone number id";
|
|
786
|
-
const tail = lastFourDigits(phoneNumberId);
|
|
787
|
-
return tail.length > 0 ? `a phone number id ending in ${tail}` : "a phone number id with no digits";
|
|
788
|
-
}
|
|
789
|
-
function isForAnotherNumber(inbound, ownPhoneNumberId, reported) {
|
|
790
|
-
if (ownPhoneNumberId === void 0 || inbound.phoneNumberId === ownPhoneNumberId) return false;
|
|
791
|
-
const other = redactedNumberId(inbound.phoneNumberId);
|
|
792
|
-
if (!reported.has(other)) {
|
|
793
|
-
reported.add(other);
|
|
794
|
-
process.stderr.write(
|
|
795
|
-
`[whatsapp] dropped inbound addressed to ${other}: this adapter answers for "${ownPhoneNumberId}". Logged once per id ending.
|
|
796
|
-
`
|
|
797
|
-
);
|
|
798
|
-
}
|
|
799
|
-
return true;
|
|
800
|
-
}
|
|
801
784
|
function shouldDropGroupMessage(inbound, requireMention, botPhoneId) {
|
|
802
785
|
if (inbound.conversationType !== "group" || !requireMention) return false;
|
|
803
786
|
if (botPhoneId.length === 0) {
|
|
@@ -832,6 +815,25 @@ function decideInbound(inbound, rules) {
|
|
|
832
815
|
return toMessageEvent(inbound);
|
|
833
816
|
}
|
|
834
817
|
|
|
818
|
+
// src/foreign-number.ts
|
|
819
|
+
function redactedNumberId(phoneNumberId) {
|
|
820
|
+
if (phoneNumberId === void 0) return "no phone number id";
|
|
821
|
+
const tail = lastFourDigits(phoneNumberId);
|
|
822
|
+
return tail.length > 0 ? `a phone number id ending in ${tail}` : "a phone number id with no digits";
|
|
823
|
+
}
|
|
824
|
+
function isForAnotherNumber(inbound, ownPhoneNumberId, reported) {
|
|
825
|
+
if (ownPhoneNumberId === void 0 || inbound.phoneNumberId === ownPhoneNumberId) return false;
|
|
826
|
+
const other = redactedNumberId(inbound.phoneNumberId);
|
|
827
|
+
if (!reported.has(other)) {
|
|
828
|
+
reported.add(other);
|
|
829
|
+
process.stderr.write(
|
|
830
|
+
`[whatsapp] dropped inbound addressed to ${other}: this adapter answers for "${ownPhoneNumberId}". Logged once per id ending.
|
|
831
|
+
`
|
|
832
|
+
);
|
|
833
|
+
}
|
|
834
|
+
return true;
|
|
835
|
+
}
|
|
836
|
+
|
|
835
837
|
// src/backend/cloud/client.ts
|
|
836
838
|
var WhatsAppCloudClient = class {
|
|
837
839
|
constructor(opts) {
|
|
@@ -1328,12 +1330,15 @@ var WhatsAppCloudBackend = class {
|
|
|
1328
1330
|
* `WhatsAppAdapter` applies too).
|
|
1329
1331
|
*
|
|
1330
1332
|
* @returns `true` if the signature is valid and the body was dispatched (or held nothing to
|
|
1331
|
-
* dispatch). `false` if the signature is invalid, if the
|
|
1332
|
-
*
|
|
1333
|
-
*
|
|
1334
|
-
*
|
|
1335
|
-
*
|
|
1336
|
-
*
|
|
1333
|
+
* dispatch). `false` if the signature is invalid (answer 401), or if the body holds a
|
|
1334
|
+
* message for this number while no inbound handler is subscribed (before `onInbound`,
|
|
1335
|
+
* or after `disconnect()`): the whole body is refused, never a part of it dropped, and
|
|
1336
|
+
* one line on stderr says which; answer non-2xx so Meta redelivers once a handler is
|
|
1337
|
+
* subscribed. `"unreadable_body"` if the signature is valid but the body is not JSON
|
|
1338
|
+
* or has a shape {@link parseWebhookPayload} refuses: nothing is dispatched and one
|
|
1339
|
+
* line on stderr says why. This is not forgery, and redelivery cannot recover it:
|
|
1340
|
+
* Meta resends the same bytes, which are refused again. Answer it differently from a
|
|
1341
|
+
* bad signature (the README example answers 200 so Meta stops retrying). Status receipts with no status handler subscribed
|
|
1337
1342
|
* are discarded on purpose: subscribing to receipts is optional, and refusing them
|
|
1338
1343
|
* would make Meta redeliver every receipt to a route that never wants one.
|
|
1339
1344
|
* @throws {ConfigurationError} `missing_option` when this backend's `appSecret` is empty or
|
|
@@ -1344,13 +1349,13 @@ var WhatsAppCloudBackend = class {
|
|
|
1344
1349
|
return false;
|
|
1345
1350
|
}
|
|
1346
1351
|
const json = this.parseBody(rawBody);
|
|
1347
|
-
if (json === void 0) return
|
|
1352
|
+
if (json === void 0) return "unreadable_body";
|
|
1348
1353
|
const envelope = parseWebhookPayload(json);
|
|
1349
1354
|
if (envelope === null) {
|
|
1350
1355
|
process.stderr.write(
|
|
1351
1356
|
"[whatsapp-cloud] signed webhook body has a shape the parser refuses (no object, no entry array, or a malformed entry, change or list); refused whole, nothing dispatched\n"
|
|
1352
1357
|
);
|
|
1353
|
-
return
|
|
1358
|
+
return "unreadable_body";
|
|
1354
1359
|
}
|
|
1355
1360
|
const messages = normalizeInboundMessages(envelope).filter(
|
|
1356
1361
|
(event) => !isForAnotherNumber(event, this.phoneNumberId, this.reportedForeignNumbers)
|
|
@@ -1805,6 +1810,15 @@ function requireOwnPhoneNumberId(ownPhoneNumberId, method) {
|
|
|
1805
1810
|
message: `gateway-whatsapp: ${method} needs the backend to declare its phoneNumberId. One Meta app signs every number's webhooks with one secret, so without it this adapter would deliver every number's messages. Use fromCloud, or expose phoneNumberId on a backend that wraps WhatsAppCloudBackend.`
|
|
1806
1811
|
});
|
|
1807
1812
|
}
|
|
1813
|
+
|
|
1814
|
+
// src/refuse-attachments.ts
|
|
1815
|
+
function refuseAttachments(out) {
|
|
1816
|
+
if (out.attachments == null || out.attachments.length === 0) return void 0;
|
|
1817
|
+
return {
|
|
1818
|
+
ok: false,
|
|
1819
|
+
error: { code: "attachments_unsupported", message: "whatsapp adapter cannot send attachments" }
|
|
1820
|
+
};
|
|
1821
|
+
}
|
|
1808
1822
|
var WHATSAPP_MAX_TEXT = 4096;
|
|
1809
1823
|
function splitForWhatsApp(text) {
|
|
1810
1824
|
return chunkText(text, {
|
|
@@ -1813,7 +1827,8 @@ function splitForWhatsApp(text) {
|
|
|
1813
1827
|
lastResort: "last-boundary",
|
|
1814
1828
|
surrogateGuard: true,
|
|
1815
1829
|
stripLeading: /^\s+/,
|
|
1816
|
-
trimParts: true
|
|
1830
|
+
trimParts: true,
|
|
1831
|
+
keepTableRows: true
|
|
1817
1832
|
});
|
|
1818
1833
|
}
|
|
1819
1834
|
|
|
@@ -2025,6 +2040,9 @@ var WhatsAppAdapter = class _WhatsAppAdapter extends BasePlatformAdapter {
|
|
|
2025
2040
|
await this.backendImpl.disconnect();
|
|
2026
2041
|
}
|
|
2027
2042
|
async sendMessage(out) {
|
|
2043
|
+
return refuseAttachments(out) ?? this.sendText(out);
|
|
2044
|
+
}
|
|
2045
|
+
async sendText(out) {
|
|
2028
2046
|
if (out.text.length === 0) {
|
|
2029
2047
|
return { ok: false, error: { code: "empty_text", message: "Empty text rejected." } };
|
|
2030
2048
|
}
|