@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/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 `decideInbound`, so
262
- * there is one rule set to keep. `WhatsAppCloudBackend.handleWebhookPayload` calls `isForAnotherNumber` as well, for
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` — WhatsApp platform adapter for `@theokit/gateway`
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
- * @public
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 signed body is not JSON or
1007
- * has a shape {@link parseWebhookPayload} refuses, or if it holds a message for this
1008
- * number while no inbound handler is subscribed (before `onInbound`, or after
1009
- * `disconnect()`): the whole body is refused, never a part of it dropped, and one line
1010
- * on stderr says which. Answer `false` with a non-2xx (401 for a bad signature) so the
1011
- * drop is seen and Meta redelivers. Status receipts with no status handler subscribed
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 `decideInbound`, so
262
- * there is one rule set to keep. `WhatsAppCloudBackend.handleWebhookPayload` calls `isForAnotherNumber` as well, for
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` — WhatsApp platform adapter for `@theokit/gateway`
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
- * @public
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 signed body is not JSON or
1007
- * has a shape {@link parseWebhookPayload} refuses, or if it holds a message for this
1008
- * number while no inbound handler is subscribed (before `onInbound`, or after
1009
- * `disconnect()`): the whole body is refused, never a part of it dropped, and one line
1010
- * on stderr says which. Answer `false` with a non-2xx (401 for a bad signature) so the
1011
- * drop is seen and Meta redelivers. Status receipts with no status handler subscribed
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 signed body is not JSON or
1332
- * has a shape {@link parseWebhookPayload} refuses, or if it holds a message for this
1333
- * number while no inbound handler is subscribed (before `onInbound`, or after
1334
- * `disconnect()`): the whole body is refused, never a part of it dropped, and one line
1335
- * on stderr says which. Answer `false` with a non-2xx (401 for a bad signature) so the
1336
- * drop is seen and Meta redelivers. Status receipts with no status handler subscribed
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 false;
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 false;
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
  }