@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 CHANGED
@@ -1,5 +1,42 @@
1
1
  # Changelog
2
2
 
3
+ ## 0.6.0
4
+
5
+ ### Minor Changes
6
+
7
+ - 4850c43: `WhatsAppCloudBackend.handleWebhookPayload` now resolves `"unreadable_body"` (not `false`) for a
8
+ signed body that is not JSON or that `parseWebhookPayload` refuses, so a route can answer it
9
+ differently from a bad signature (`false`, 401). The return type widens from `boolean` to
10
+ `boolean | "unreadable_body"`; the package is 0.x, so this is a minor bump. A route that tested
11
+ `!ok` and answered 401 now answers 200 for such a body, which stops Meta's useless redeliveries.
12
+
13
+ ### Patch Changes
14
+
15
+ - 3f1788d: Send an image from a gateway handler, and refuse it wherever a platform cannot show one.
16
+
17
+ `@theokit/gateway` exports `OutboundAttachment` (`kind: "image"`, `mediaType`, `data`, optional
18
+ `filename`). `OutboundMessage` gains an optional `attachments` list, `ctx.reply(text, { attachments })`
19
+ carries it to the adapter (an empty list is left out), and `BasePlatformAdapter` declares
20
+ `supportsAttachments`, `false` by default. `DeliveryRouter.send` takes the same `attachments`
21
+ field. The runner and the router refuse an outbound carrying attachments as
22
+ `attachments_unsupported`, with no `sendMessage` call, when the adapter does not declare
23
+ `supportsAttachments`.
24
+
25
+ `@theokit/gateway-telegram` reports `supportsAttachments: true` and sends each image through
26
+ `sendPhoto`, the text as the first photo's caption up to 1024 UTF-16 units and after the photos
27
+ when longer. A non-image kind is refused as `attachments_unsupported`; a missing image, more
28
+ than 10 images or an image over 10 MiB as `invalid_attachment`; all with no request.
29
+
30
+ Every other adapter, and every adapter's `editMessage`, refuses an outbound carrying attachments
31
+ with `attachments_unsupported` and makes no platform call, instead of sending the text and
32
+ dropping the image.
33
+
34
+ The runner's auto-reply to a blocking `pre_inbound` hook no longer discards a `sendMessage` that
35
+ throws: the error reaches the `on_error` hooks with the event and is written to stderr, redacted,
36
+ as a handler error is. Dispatch still does not throw.
37
+
38
+ - 17c0713: Keep Markdown table rows whole when Discord, Slack, Teams, Telegram, WhatsApp and Mattermost split a long reply. A cut that fell inside a table row now moves back to the start of that row when the row fits in a part, so each row reaches the platform byte-identical. `chunkText` gains the opt-in `keepTableRows` option; text with no table row splits into the same chunks as before.
39
+
3
40
  ## 0.5.0
4
41
 
5
42
  ### Minor Changes
package/README.md CHANGED
@@ -97,9 +97,12 @@ whose `id`, `from` or `text.body` is not a string, a contact whose `wa_id` or `p
97
97
  a string, or a status whose `id`, `status` or `recipient_id` is not a string. The whole body is refused, not just its bad entries, so the route
98
98
  answers it (400 in the example) instead of dropping part of a batch unseen. Any non-null envelope
99
99
  is safe to hand to `toDeliverableEvents` and `normalizeStatusReceipts`: neither throws on it.
100
- `WhatsAppCloudBackend.handleWebhookPayload` refuses such a body the same way: it answers `false`,
101
- as it does for a signed body that is not JSON, dispatches nothing and writes one line to stderr,
102
- so a route built on it answers non-2xx and Meta redelivers instead of losing the batch. It also
100
+ `WhatsAppCloudBackend.handleWebhookPayload` refuses such a body too, and tells it from a forgery: a
101
+ bad signature answers `false` (answer 401), while a signed body that is not JSON or that the parser
102
+ refuses answers `"unreadable_body"`. Either way it dispatches nothing; the second also writes one
103
+ line to stderr. A route should answer `"unreadable_body"` with something other than 401, such as 200:
104
+ the signature proves Meta sent it, and a non-2xx only makes Meta redeliver the same bytes, which are
105
+ refused again until Meta gives up, so redelivery cannot recover it (fix the parser, not the retry). It also
103
106
  answers `false` for a body holding a message for its number while no inbound handler is
104
107
  subscribed, before `onInbound` or after `disconnect()`. Status receipts with no status handler are
105
108
  discarded, because subscribing to them is optional.
package/dist/index.cjs CHANGED
@@ -805,23 +805,6 @@ function redactedSender(fromPhone) {
805
805
  function lastFourDigits(value) {
806
806
  return digitsOnly(value).slice(-4);
807
807
  }
808
- function redactedNumberId(phoneNumberId) {
809
- if (phoneNumberId === void 0) return "no phone number id";
810
- const tail = lastFourDigits(phoneNumberId);
811
- return tail.length > 0 ? `a phone number id ending in ${tail}` : "a phone number id with no digits";
812
- }
813
- function isForAnotherNumber(inbound, ownPhoneNumberId, reported) {
814
- if (ownPhoneNumberId === void 0 || inbound.phoneNumberId === ownPhoneNumberId) return false;
815
- const other = redactedNumberId(inbound.phoneNumberId);
816
- if (!reported.has(other)) {
817
- reported.add(other);
818
- process.stderr.write(
819
- `[whatsapp] dropped inbound addressed to ${other}: this adapter answers for "${ownPhoneNumberId}". Logged once per id ending.
820
- `
821
- );
822
- }
823
- return true;
824
- }
825
808
  function shouldDropGroupMessage(inbound, requireMention, botPhoneId) {
826
809
  if (inbound.conversationType !== "group" || !requireMention) return false;
827
810
  if (botPhoneId.length === 0) {
@@ -856,6 +839,25 @@ function decideInbound(inbound, rules) {
856
839
  return toMessageEvent(inbound);
857
840
  }
858
841
 
842
+ // src/foreign-number.ts
843
+ function redactedNumberId(phoneNumberId) {
844
+ if (phoneNumberId === void 0) return "no phone number id";
845
+ const tail = lastFourDigits(phoneNumberId);
846
+ return tail.length > 0 ? `a phone number id ending in ${tail}` : "a phone number id with no digits";
847
+ }
848
+ function isForAnotherNumber(inbound, ownPhoneNumberId, reported) {
849
+ if (ownPhoneNumberId === void 0 || inbound.phoneNumberId === ownPhoneNumberId) return false;
850
+ const other = redactedNumberId(inbound.phoneNumberId);
851
+ if (!reported.has(other)) {
852
+ reported.add(other);
853
+ process.stderr.write(
854
+ `[whatsapp] dropped inbound addressed to ${other}: this adapter answers for "${ownPhoneNumberId}". Logged once per id ending.
855
+ `
856
+ );
857
+ }
858
+ return true;
859
+ }
860
+
859
861
  // src/backend/cloud/client.ts
860
862
  var WhatsAppCloudClient = class {
861
863
  constructor(opts) {
@@ -1352,12 +1354,15 @@ var WhatsAppCloudBackend = class {
1352
1354
  * `WhatsAppAdapter` applies too).
1353
1355
  *
1354
1356
  * @returns `true` if the signature is valid and the body was dispatched (or held nothing to
1355
- * dispatch). `false` if the signature is invalid, if the signed body is not JSON or
1356
- * has a shape {@link parseWebhookPayload} refuses, or if it holds a message for this
1357
- * number while no inbound handler is subscribed (before `onInbound`, or after
1358
- * `disconnect()`): the whole body is refused, never a part of it dropped, and one line
1359
- * on stderr says which. Answer `false` with a non-2xx (401 for a bad signature) so the
1360
- * drop is seen and Meta redelivers. Status receipts with no status handler subscribed
1357
+ * dispatch). `false` if the signature is invalid (answer 401), or if the body holds a
1358
+ * message for this number while no inbound handler is subscribed (before `onInbound`,
1359
+ * or after `disconnect()`): the whole body is refused, never a part of it dropped, and
1360
+ * one line on stderr says which; answer non-2xx so Meta redelivers once a handler is
1361
+ * subscribed. `"unreadable_body"` if the signature is valid but the body is not JSON
1362
+ * or has a shape {@link parseWebhookPayload} refuses: nothing is dispatched and one
1363
+ * line on stderr says why. This is not forgery, and redelivery cannot recover it:
1364
+ * Meta resends the same bytes, which are refused again. Answer it differently from a
1365
+ * bad signature (the README example answers 200 so Meta stops retrying). Status receipts with no status handler subscribed
1361
1366
  * are discarded on purpose: subscribing to receipts is optional, and refusing them
1362
1367
  * would make Meta redeliver every receipt to a route that never wants one.
1363
1368
  * @throws {ConfigurationError} `missing_option` when this backend's `appSecret` is empty or
@@ -1368,13 +1373,13 @@ var WhatsAppCloudBackend = class {
1368
1373
  return false;
1369
1374
  }
1370
1375
  const json = this.parseBody(rawBody);
1371
- if (json === void 0) return false;
1376
+ if (json === void 0) return "unreadable_body";
1372
1377
  const envelope = parseWebhookPayload(json);
1373
1378
  if (envelope === null) {
1374
1379
  process.stderr.write(
1375
1380
  "[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"
1376
1381
  );
1377
- return false;
1382
+ return "unreadable_body";
1378
1383
  }
1379
1384
  const messages = normalizeInboundMessages(envelope).filter(
1380
1385
  (event) => !isForAnotherNumber(event, this.phoneNumberId, this.reportedForeignNumbers)
@@ -1829,6 +1834,15 @@ function requireOwnPhoneNumberId(ownPhoneNumberId, method) {
1829
1834
  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.`
1830
1835
  });
1831
1836
  }
1837
+
1838
+ // src/refuse-attachments.ts
1839
+ function refuseAttachments(out) {
1840
+ if (out.attachments == null || out.attachments.length === 0) return void 0;
1841
+ return {
1842
+ ok: false,
1843
+ error: { code: "attachments_unsupported", message: "whatsapp adapter cannot send attachments" }
1844
+ };
1845
+ }
1832
1846
  var WHATSAPP_MAX_TEXT = 4096;
1833
1847
  function splitForWhatsApp(text) {
1834
1848
  return gateway.chunkText(text, {
@@ -1837,7 +1851,8 @@ function splitForWhatsApp(text) {
1837
1851
  lastResort: "last-boundary",
1838
1852
  surrogateGuard: true,
1839
1853
  stripLeading: /^\s+/,
1840
- trimParts: true
1854
+ trimParts: true,
1855
+ keepTableRows: true
1841
1856
  });
1842
1857
  }
1843
1858
 
@@ -2049,6 +2064,9 @@ var WhatsAppAdapter = class _WhatsAppAdapter extends gateway.BasePlatformAdapter
2049
2064
  await this.backendImpl.disconnect();
2050
2065
  }
2051
2066
  async sendMessage(out) {
2067
+ return refuseAttachments(out) ?? this.sendText(out);
2068
+ }
2069
+ async sendText(out) {
2052
2070
  if (out.text.length === 0) {
2053
2071
  return { ok: false, error: { code: "empty_text", message: "Empty text rejected." } };
2054
2072
  }