@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 +73 -0
- package/README.md +12 -1
- package/dist/index.cjs +69 -5
- package/dist/index.cjs.map +1 -1
- package/dist/index.d.cts +55 -0
- package/dist/index.d.ts +55 -0
- package/dist/index.js +69 -5
- package/dist/index.js.map +1 -1
- package/package.json +2 -2
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
|
|
661
|
-
|
|
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;
|