@theokit/gateway-whatsapp 0.3.3 → 0.4.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,78 @@
1
1
  # Changelog
2
2
 
3
+ ## 0.4.0
4
+
5
+ ### Minor Changes
6
+
7
+ - b38172b: **The peer floor on `@theokit/gateway` rises with this release.** Every adapter now implements
8
+ `deliver` over `runHandler`, and neither exists in an older core — an adapter installed against one
9
+ does not build. `dep-check` caught that by building the whole workspace against the floor each
10
+ package claimed, which is the one thing a version range cannot tell you by reading it.
11
+
12
+ The floor is set in the version commit rather than here, because a range cannot name a version that
13
+ does not exist yet: raised in the workspace, the same gate then fails the other way round — every
14
+ adapter declaring a floor above the core installed beside it. That is the shape `fa70153` used when
15
+ these ranges were first written.
16
+
17
+ `deliver(event)` — every adapter can now be handed an event that arrived out of band (#83).
18
+
19
+ `onInbound` was the seam every adapter implemented and it had no public counterpart. Six platforms
20
+ self-deliver once connected — long polling, a gateway socket, Socket Mode, a sync loop, IMAP — so
21
+ the asymmetry stayed invisible: `GatewayRunner` worked for eight platforms and silently did nothing
22
+ for LINE and WhatsApp Cloud, whose payloads arrive on an HTTP route the application owns. Every app
23
+ wired those two by hand, beside the runner rather than through it.
24
+
25
+ ```ts
26
+ const outcome = await adapter.deliver(event); // "ok" | "no_handler" | "handler_threw"
27
+ ```
28
+
29
+ The three outcomes are distinguished because a caller acts on them differently: answering a webhook
30
+ 200 when nobody was subscribed tells the provider to stop retrying a message nothing received.
31
+
32
+ `BasePlatformAdapter.runHandler` holds the containment once, where ten copies of it used to live —
33
+ a handler is user code, its throw is named as the handler's failure rather than the platform's, and
34
+ delivery continues. Each adapter's `deliver` is one line over it.
35
+
36
+ Also: `gateway-sms`'s `createWebhookServer` now signs against the configured `publicUrl` (#90).
37
+ Twilio verifies against the URL it POSTed to, and behind a proxy that rewrites `host` — a tunnel, an
38
+ ingress, a load balancer terminating TLS — the reconstruction from headers yields the internal
39
+ address, so a correct signature fails on every delivery. `publicUrl` is required by all three
40
+ backend option shapes and documented as "used by signature verifier"; until now no source file read
41
+ it. The header reconstruction stays as the fallback for an app served directly.
42
+
43
+ - 348bc02: WhatsApp: send to the address that routes, and answer where the message came from (#82, #84).
44
+
45
+ **A send that WhatsApp discards no longer reports success.** Baileys hands back a
46
+ locally-generated `wamid` whether or not the JID routes anywhere, and the backend treated that id
47
+ as proof of delivery — so a message nobody received was recorded as a success by the caller's log,
48
+ its metrics and its retry logic. Measured on a real account: `5535998838687` and `553598838687` are
49
+ the same Brazilian line, both answered `ok: true`, and only the second arrived.
50
+
51
+ `send` now asks WhatsApp which form it routes to before sending, and refuses a number the server
52
+ does not know with `undeliverable` naming the number. That fixes the Brazilian ninth digit without a
53
+ Brazil-specific rule anywhere in this package — the answer is whatever the server says, for any
54
+ country. The lookup is cached for the life of the session, so it costs one round-trip per recipient.
55
+
56
+ **An inbound event now carries the address it arrived on**, as `whatsapp.channelJid`. `channel.id`
57
+ is normalised to digits — which is what an allowlist compares — and that normalisation strips the
58
+ domain, the part that says whether an address is a phone, a group, or an account's linked identity.
59
+ A note-to-self arrives addressed by LID, so replying to `channel.id` rebuilt `…@s.whatsapp.net`, an
60
+ address that does not exist.
61
+
62
+ **`send` accepts a qualified JID verbatim.** A `to` containing `@` is already an address and is
63
+ passed through untouched, where it used to become `231116569108705@lid@s.whatsapp.net`. So
64
+ answering an inbound event is now:
65
+
66
+ ```ts
67
+ await adapter.sendMessage({
68
+ channel: { id: event.whatsapp.channelJid ?? event.channel.id, type: "dm" },
69
+ text,
70
+ });
71
+ ```
72
+
73
+ Not affected: the Cloud backend. Meta rejects an unroutable recipient with an error code, so the
74
+ same mistake surfaces there instead of vanishing.
75
+
3
76
  ## 0.3.3
4
77
 
5
78
  ### Patch Changes
package/README.md CHANGED
@@ -7,6 +7,18 @@ subprocess bridge, and a `baileys` socket.
7
7
  Pre-1.0 contract per ADR D314 — breaking changes allowed within 0.x. (This line used to
8
8
  pin a version number, and named 0.1.0 while the package shipped 0.3.2.)
9
9
 
10
+
11
+ ## How inbound arrives
12
+
13
+ **It depends on the backend**, and the two are not alike.
14
+
15
+ `cloud` is an **HTTP webhook** the application must authenticate: Meta signs with
16
+ `X-Hub-Signature-256` over the raw body, and `theokit/server/webhook` exports `whatsapp()` and
17
+ `whatsappSubscribe()` for the signature and the GET handshake. Parsed events go to
18
+ `adapter.deliver(event)`.
19
+
20
+ `baileys` and `web` hold **their own socket** — there is no webhook to host, and messages reach
21
+ `onInbound` once `connect()` resolves.
10
22
  ## Choosing a backend
11
23
 
12
24
  | Backend | Needs | Exercised against real WhatsApp |
@@ -81,4 +93,3 @@ PUPPETEER_EXECUTABLE_PATH=/usr/bin/google-chrome node your-app.js
81
93
  The bridge spawns without an explicit `env`, so it inherits yours and the variable
82
94
  reaches Puppeteer. `WhatsAppBaileysBackend` needs no browser at all, which is the reason
83
95
  it exists (B-001).
84
-
package/dist/index.cjs CHANGED
@@ -101,7 +101,7 @@ function resolveParties(key, remoteJid) {
101
101
  const fromPhone = normalizeWhatsAppId(senderJid);
102
102
  const channelId = normalizeWhatsAppId(remoteJid);
103
103
  if (fromPhone.length === 0 || channelId.length === 0) return void 0;
104
- return { fromPhone, channelId, isGroup };
104
+ return { fromPhone, channelId, channelJid: remoteJid, isGroup };
105
105
  }
106
106
  function isDispatchable(key, remoteJid, wamid, ctx) {
107
107
  if (remoteJid === STATUS_BROADCAST_JID) return "no";
@@ -138,6 +138,7 @@ function normalizeBaileysMessage(raw, ctx) {
138
138
  fromPhone: parties.fromPhone,
139
139
  conversationType: parties.isGroup ? "group" : "dm",
140
140
  channelId: parties.channelId,
141
+ channelJid: parties.channelJid,
141
142
  text,
142
143
  receivedAt: seconds * 1e3,
143
144
  backend: "baileys",
@@ -312,6 +313,7 @@ function endQuietly(socket) {
312
313
  }
313
314
  var DEFAULT_CONNECT_TIMEOUT_MS = 6e4;
314
315
  var DEFAULT_SEND_TIMEOUT_MS = 3e4;
316
+ var UNROUTABLE = "__unroutable__";
315
317
  var SENT_WAMID_WINDOW = 256;
316
318
  var WhatsAppBaileysBackend = class {
317
319
  constructor(opts) {
@@ -407,6 +409,14 @@ var WhatsAppBaileysBackend = class {
407
409
  * the failure it guards against is a message delivered to the wrong person.
408
410
  */
409
411
  sendQueue = Promise.resolve();
412
+ /**
413
+ * What WhatsApp answered about each recipient, for the life of the session.
414
+ *
415
+ * Holds the routable JID, or {@link UNROUTABLE} for a number the server does not know. Both are
416
+ * worth remembering: a second send to a number that does not exist should refuse as fast as the
417
+ * first, without another round-trip.
418
+ */
419
+ jidCache = /* @__PURE__ */ new Map();
410
420
  /**
411
421
  * Open the socket and wait for it to report `open`.
412
422
  *
@@ -655,10 +665,20 @@ var WhatsAppBaileysBackend = class {
655
665
  inFlight: Promise.resolve()
656
666
  };
657
667
  }
658
- const jid = `${message.to}@${message.isGroup ? "g.us" : "s.whatsapp.net"}`;
659
668
  const timeoutMs = this.opts.sendTimeoutMs ?? DEFAULT_SEND_TIMEOUT_MS;
660
- const inFlight = socket.sendMessage(jid, { text: message.text });
661
- const result = this.raceSend(inFlight, timeoutMs).then((outcome) => {
669
+ const send = this.resolveJid(socket, message).then(
670
+ async (jid) => jid === void 0 ? UNROUTABLE : await socket.sendMessage(jid, { text: message.text })
671
+ );
672
+ const result = this.raceSend(send, timeoutMs).then((outcome) => {
673
+ if (outcome === UNROUTABLE) {
674
+ return {
675
+ ok: false,
676
+ error: {
677
+ code: "undeliverable",
678
+ message: `WhatsApp does not route to "${message.to}" \u2014 the number is not registered, or not in the form this account can reach. Nothing was sent.`
679
+ }
680
+ };
681
+ }
662
682
  if (outcome === "timeout") {
663
683
  return {
664
684
  ok: false,
@@ -678,7 +698,41 @@ var WhatsAppBaileysBackend = class {
678
698
  message: err instanceof Error ? err.message : String(err)
679
699
  }
680
700
  }));
681
- return { result, inFlight };
701
+ return { result, inFlight: send };
702
+ }
703
+ /**
704
+ * The JID WhatsApp routes this message to, or `undefined` when it routes to nobody.
705
+ *
706
+ * A group id is not a phone number and `onWhatsApp` answers about numbers, so groups pass
707
+ * straight through — asking would refuse every group message.
708
+ *
709
+ * The answer is cached for the life of the session. It is a fact about a number's registration,
710
+ * which does not change while a socket lives, and paying a round-trip per message would make
711
+ * every send slower for something already known.
712
+ *
713
+ * A socket without `onWhatsApp` — an older Baileys, or a fake predating this — sends to the
714
+ * number as given, which is the behaviour from before #82. Refusing on a missing capability
715
+ * would turn an upgrade problem into an outage.
716
+ */
717
+ async resolveJid(socket, message) {
718
+ if (message.to.includes("@")) return message.to;
719
+ if (message.isGroup) return `${message.to}@g.us`;
720
+ if (socket.onWhatsApp === void 0) return `${message.to}@s.whatsapp.net`;
721
+ const cached = this.jidCache.get(message.to);
722
+ if (cached !== void 0) return cached === UNROUTABLE ? void 0 : cached;
723
+ let answer;
724
+ try {
725
+ answer = await socket.onWhatsApp(message.to);
726
+ } catch {
727
+ return `${message.to}@s.whatsapp.net`;
728
+ }
729
+ const entry = answer?.[0];
730
+ if (entry?.exists !== true || entry.jid === void 0 || entry.jid === "") {
731
+ this.jidCache.set(message.to, UNROUTABLE);
732
+ return void 0;
733
+ }
734
+ this.jidCache.set(message.to, entry.jid);
735
+ return entry.jid;
682
736
  }
683
737
  /** Subscribe to inbound events. EC-H: a second call REPLACES the first. */
684
738
  onInbound(handler) {
@@ -1837,6 +1891,7 @@ var WhatsAppAdapter = class _WhatsAppAdapter extends gateway.BasePlatformAdapter
1837
1891
  wamid: inbound.wamid,
1838
1892
  phoneNumberId: inbound.phoneNumberId,
1839
1893
  contactName: inbound.contactName,
1894
+ channelJid: inbound.channelJid,
1840
1895
  backend: inbound.backend,
1841
1896
  raw: inbound.raw
1842
1897
  }
@@ -1876,6 +1931,15 @@ var WhatsAppAdapter = class _WhatsAppAdapter extends gateway.BasePlatformAdapter
1876
1931
  }
1877
1932
  };
1878
1933
  }
1934
+ /**
1935
+ * Deliver an event that arrived out of band — the ingest `onInbound` had no counterpart for (#83).
1936
+ *
1937
+ * One line over `runHandler`, which owns the containment: a handler is user code, its throw is
1938
+ * named as the handler's failure rather than the platform's, and delivery continues.
1939
+ */
1940
+ async deliver(event) {
1941
+ return this.runHandler(this.handler, event);
1942
+ }
1879
1943
  };
1880
1944
 
1881
1945
  exports.ConfigurationError = ConfigurationError;