@theokit/gateway-whatsapp 0.7.0 → 0.9.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 +12 -0
- package/README.md +47 -0
- package/dist/index.cjs +246 -4
- package/dist/index.cjs.map +1 -1
- package/dist/index.d.cts +82 -1
- package/dist/index.d.ts +82 -1
- package/dist/index.js +247 -5
- package/dist/index.js.map +1 -1
- package/package.json +3 -3
package/CHANGELOG.md
CHANGED
|
@@ -1,5 +1,17 @@
|
|
|
1
1
|
# Changelog
|
|
2
2
|
|
|
3
|
+
## 0.9.0
|
|
4
|
+
|
|
5
|
+
### Minor Changes
|
|
6
|
+
|
|
7
|
+
- 3158f63: The `whatsappChannel` Cloud variant and `smsChannel` descriptors now declare `transport: "webhook"` with a `webhook.handle`, so a host mounts them with `createWebhookHandler`. WhatsApp answers Meta's subscription check and verifies `x-hub-signature-256`; SMS verifies Twilio's signature against the configured `publicUrl`. The Express listeners are unchanged.
|
|
8
|
+
|
|
9
|
+
## 0.8.0
|
|
10
|
+
|
|
11
|
+
### Minor Changes
|
|
12
|
+
|
|
13
|
+
- 9d477da: Export a `ChannelDescriptor` with env bindings: `whatsappChannel` (variants `cloud` and `baileys`), `teamsChannel` and `googleChatChannel`, for `createChannels` and `configFromEnv`. The `@theokit/gateway` peer range is now `>=0.20.0 <1.0.0`.
|
|
14
|
+
|
|
3
15
|
## 0.7.0
|
|
4
16
|
|
|
5
17
|
### Minor Changes
|
package/README.md
CHANGED
|
@@ -211,3 +211,50 @@ it exists (B-001).
|
|
|
211
211
|
## Capabilities
|
|
212
212
|
|
|
213
213
|
`adapter.capabilities.maxMessageChars` is `4096` (the splitter limit) and `threads` is `false`. See `@theokit/gateway` for the field meanings.
|
|
214
|
+
|
|
215
|
+
## Channel descriptor
|
|
216
|
+
|
|
217
|
+
`whatsappChannel` describes the channel as data, for `createChannels` and `configFromEnv` from
|
|
218
|
+
`@theokit/gateway`. It has two variants, chosen with `selectVariant(whatsappChannel, name)`; the
|
|
219
|
+
descriptor itself is the `cloud` shape.
|
|
220
|
+
|
|
221
|
+
| Variant | Field | Env | Required | Secret |
|
|
222
|
+
| --- | --- | --- | --- | --- |
|
|
223
|
+
| `cloud` | `accessToken` | `WHATSAPP_ACCESS_TOKEN` | yes | yes |
|
|
224
|
+
| `cloud` | `phoneNumberId` | `WHATSAPP_PHONE_NUMBER_ID` | yes | no |
|
|
225
|
+
| `cloud` | `appSecret` | `WHATSAPP_APP_SECRET` | yes | yes |
|
|
226
|
+
| `cloud` | `verifyToken` | `WHATSAPP_VERIFY_TOKEN` | no | yes |
|
|
227
|
+
| `baileys` | `sessionDir` | `WHATSAPP_SESSION_DIR` | yes | no |
|
|
228
|
+
| `baileys` | `botPhoneId` | `WHATSAPP_BOT_PHONE_ID` | no | no |
|
|
229
|
+
| both | `requireMention` | `WHATSAPP_REQUIRE_MENTION` | no | no |
|
|
230
|
+
|
|
231
|
+
`verifyToken` is not an adapter option: the webhook half uses it to answer Meta's subscription
|
|
232
|
+
check. The `cloud` descriptor declares `transport: "webhook"` with `methods: ["GET", "POST"]`;
|
|
233
|
+
`baileys` stays `"socket"`.
|
|
234
|
+
|
|
235
|
+
### Mounting the route
|
|
236
|
+
|
|
237
|
+
GET answers the subscription check (200 with `hub.challenge` as `text/plain`, else 403). POST checks
|
|
238
|
+
`x-hub-signature-256` with `appSecret` (401 on a mismatch), answers 400 for a body that is not JSON,
|
|
239
|
+
delivers each event and answers 200 (500 or 503 when the handler threw or none is subscribed).
|
|
240
|
+
|
|
241
|
+
```ts
|
|
242
|
+
import { createChannels, createWebhookHandler, selectVariant } from "@theokit/gateway";
|
|
243
|
+
import { whatsappChannel } from "@theokit/gateway-whatsapp";
|
|
244
|
+
|
|
245
|
+
const descriptor = selectVariant(whatsappChannel, "cloud");
|
|
246
|
+
const { channels } = createChannels([{ descriptor, config }]);
|
|
247
|
+
const handle = createWebhookHandler({ channels, isStarted: () => true });
|
|
248
|
+
// GET and POST /webhooks/whatsapp -> handle(request)
|
|
249
|
+
```
|
|
250
|
+
|
|
251
|
+
```ts
|
|
252
|
+
import { configFromEnv, createChannels, selectVariant } from "@theokit/gateway";
|
|
253
|
+
import { whatsappChannel } from "@theokit/gateway-whatsapp";
|
|
254
|
+
|
|
255
|
+
const descriptor = selectVariant(whatsappChannel, "cloud");
|
|
256
|
+
const { config, missing } = configFromEnv(descriptor, process.env, "APP_");
|
|
257
|
+
const { adapters, rejected } = createChannels([{ descriptor, config }]);
|
|
258
|
+
```
|
|
259
|
+
|
|
260
|
+
`create` refuses a value of the wrong type with `ConfigurationError` (`invalid_config`, naming the key).
|
package/dist/index.cjs
CHANGED
|
@@ -1939,14 +1939,14 @@ var WhatsAppAdapter = class _WhatsAppAdapter extends gateway.BasePlatformAdapter
|
|
|
1939
1939
|
* @throws {ConfigurationError} when a required option is missing or empty.
|
|
1940
1940
|
* @public
|
|
1941
1941
|
*/
|
|
1942
|
-
static from(options,
|
|
1942
|
+
static from(options, common2 = {}) {
|
|
1943
1943
|
switch (options.backend) {
|
|
1944
1944
|
case "cloud":
|
|
1945
|
-
return _WhatsAppAdapter.fromCloud(options.cloud,
|
|
1945
|
+
return _WhatsAppAdapter.fromCloud(options.cloud, common2);
|
|
1946
1946
|
case "web":
|
|
1947
|
-
return _WhatsAppAdapter.fromWeb(options.web,
|
|
1947
|
+
return _WhatsAppAdapter.fromWeb(options.web, common2);
|
|
1948
1948
|
case "baileys":
|
|
1949
|
-
return _WhatsAppAdapter.fromBaileys(options.baileys,
|
|
1949
|
+
return _WhatsAppAdapter.fromBaileys(options.baileys, common2);
|
|
1950
1950
|
}
|
|
1951
1951
|
}
|
|
1952
1952
|
/**
|
|
@@ -2193,6 +2193,247 @@ var WhatsAppAdapter = class _WhatsAppAdapter extends gateway.BasePlatformAdapter
|
|
|
2193
2193
|
async deliver(event) {
|
|
2194
2194
|
return this.runHandler(this.handler, event);
|
|
2195
2195
|
}
|
|
2196
|
+
/**
|
|
2197
|
+
* Deliver like {@link deliver}, but a throwing handler is logged by name only: its message can
|
|
2198
|
+
* carry the inbound text, which the webhook route must not write to a log line.
|
|
2199
|
+
*
|
|
2200
|
+
* @internal
|
|
2201
|
+
*/
|
|
2202
|
+
async deliverQuietly(event) {
|
|
2203
|
+
const handler = this.handler;
|
|
2204
|
+
if (handler === void 0) return "no_handler";
|
|
2205
|
+
try {
|
|
2206
|
+
await handler(event);
|
|
2207
|
+
} catch {
|
|
2208
|
+
process.stderr.write(`[whatsapp] handler threw
|
|
2209
|
+
`);
|
|
2210
|
+
return "handler_threw";
|
|
2211
|
+
}
|
|
2212
|
+
return "ok";
|
|
2213
|
+
}
|
|
2214
|
+
};
|
|
2215
|
+
var configs = /* @__PURE__ */ new WeakMap();
|
|
2216
|
+
function rememberWebhookConfig(adapter, config) {
|
|
2217
|
+
configs.set(adapter, config);
|
|
2218
|
+
}
|
|
2219
|
+
function headerValue(headers, name) {
|
|
2220
|
+
for (const [key, value] of Object.entries(headers)) {
|
|
2221
|
+
if (key.toLowerCase() === name) return value;
|
|
2222
|
+
}
|
|
2223
|
+
return void 0;
|
|
2224
|
+
}
|
|
2225
|
+
function safeEqual(a, b) {
|
|
2226
|
+
const ha = crypto.createHash("sha256").update(a).digest();
|
|
2227
|
+
const hb = crypto.createHash("sha256").update(b).digest();
|
|
2228
|
+
return crypto.timingSafeEqual(ha, hb);
|
|
2229
|
+
}
|
|
2230
|
+
function statusFor(outcomes) {
|
|
2231
|
+
let status = 200;
|
|
2232
|
+
for (const outcome of outcomes) {
|
|
2233
|
+
if (outcome === "handler_threw") status = 500;
|
|
2234
|
+
else if (outcome === "no_handler" && status === 200) status = 503;
|
|
2235
|
+
}
|
|
2236
|
+
return status;
|
|
2237
|
+
}
|
|
2238
|
+
function signatureValid(adapter, request) {
|
|
2239
|
+
const config = configs.get(adapter);
|
|
2240
|
+
if (config === void 0 || config.appSecret.trim().length === 0) return false;
|
|
2241
|
+
const header = headerValue(request.headers, "x-hub-signature-256");
|
|
2242
|
+
return verifyWebhookSignature(request.rawBody, header, config.appSecret);
|
|
2243
|
+
}
|
|
2244
|
+
function subscriptionChallenge(adapter, request) {
|
|
2245
|
+
const expected = configs.get(adapter)?.verifyToken;
|
|
2246
|
+
if (expected === void 0 || expected.length === 0 || request.url === void 0) {
|
|
2247
|
+
return void 0;
|
|
2248
|
+
}
|
|
2249
|
+
let params;
|
|
2250
|
+
try {
|
|
2251
|
+
params = new URL(request.url).searchParams;
|
|
2252
|
+
} catch {
|
|
2253
|
+
return void 0;
|
|
2254
|
+
}
|
|
2255
|
+
const token = params.get("hub.verify_token");
|
|
2256
|
+
const challenge = params.get("hub.challenge");
|
|
2257
|
+
if (params.get("hub.mode") !== "subscribe" || token === null || !safeEqual(token, expected)) {
|
|
2258
|
+
return void 0;
|
|
2259
|
+
}
|
|
2260
|
+
return challenge === null || challenge.length === 0 ? void 0 : challenge;
|
|
2261
|
+
}
|
|
2262
|
+
function requestValid(adapter, request) {
|
|
2263
|
+
const method = request.method?.toUpperCase();
|
|
2264
|
+
if (method === "GET") return subscriptionChallenge(adapter, request) !== void 0;
|
|
2265
|
+
if (method === "POST") return signatureValid(adapter, request);
|
|
2266
|
+
return false;
|
|
2267
|
+
}
|
|
2268
|
+
function isEnvelope(payload) {
|
|
2269
|
+
return payload !== null && typeof payload === "object" && !Array.isArray(payload);
|
|
2270
|
+
}
|
|
2271
|
+
async function deliverEnvelope(adapter, payload) {
|
|
2272
|
+
const outcomes = await deliverAll(adapter, payload);
|
|
2273
|
+
if (outcomes === void 0) return "malformed";
|
|
2274
|
+
return statusFor(outcomes) === 200 ? "delivered" : "no_handler";
|
|
2275
|
+
}
|
|
2276
|
+
async function deliverAll(adapter, payload) {
|
|
2277
|
+
if (!isEnvelope(payload)) return void 0;
|
|
2278
|
+
const outcomes = [];
|
|
2279
|
+
for (const event of adapter.toDeliverableEvents(payload)) {
|
|
2280
|
+
outcomes.push(await adapter.deliverQuietly(event));
|
|
2281
|
+
}
|
|
2282
|
+
return outcomes;
|
|
2283
|
+
}
|
|
2284
|
+
var cloudWebhook = {
|
|
2285
|
+
methods: ["GET", "POST"],
|
|
2286
|
+
verify(adapter, request) {
|
|
2287
|
+
return requestValid(adapter, request);
|
|
2288
|
+
},
|
|
2289
|
+
async ingest(adapter, payload) {
|
|
2290
|
+
return deliverEnvelope(adapter, payload);
|
|
2291
|
+
},
|
|
2292
|
+
async handle(adapter, request) {
|
|
2293
|
+
const isGet = request.method?.toUpperCase() === "GET";
|
|
2294
|
+
if (!requestValid(adapter, request)) return { status: isGet ? 403 : 401 };
|
|
2295
|
+
if (isGet) {
|
|
2296
|
+
return {
|
|
2297
|
+
status: 200,
|
|
2298
|
+
body: subscriptionChallenge(adapter, request),
|
|
2299
|
+
contentType: "text/plain"
|
|
2300
|
+
};
|
|
2301
|
+
}
|
|
2302
|
+
let payload;
|
|
2303
|
+
try {
|
|
2304
|
+
payload = JSON.parse(request.rawBody);
|
|
2305
|
+
} catch {
|
|
2306
|
+
return { status: 400 };
|
|
2307
|
+
}
|
|
2308
|
+
const outcomes = await deliverAll(adapter, payload);
|
|
2309
|
+
if (outcomes === void 0) return { status: 400 };
|
|
2310
|
+
return { status: statusFor(outcomes) };
|
|
2311
|
+
}
|
|
2312
|
+
};
|
|
2313
|
+
|
|
2314
|
+
// src/channel.ts
|
|
2315
|
+
function invalid(key, expected) {
|
|
2316
|
+
return new ConfigurationError({
|
|
2317
|
+
code: "invalid_config",
|
|
2318
|
+
message: `gateway-whatsapp: config.${key} must be ${expected}`,
|
|
2319
|
+
detail: key
|
|
2320
|
+
});
|
|
2321
|
+
}
|
|
2322
|
+
function read(config, key, kind) {
|
|
2323
|
+
const value = config[key];
|
|
2324
|
+
if (value === void 0 || value === null || value === "") return void 0;
|
|
2325
|
+
if (kind === "string" && typeof value === "string") return value;
|
|
2326
|
+
if (kind === "boolean" && typeof value === "boolean") return value;
|
|
2327
|
+
if (kind === "boolean" && (value === "true" || value === "false")) return value === "true";
|
|
2328
|
+
throw invalid(key, kind === "string" ? "a string" : 'a boolean or the string "true" or "false"');
|
|
2329
|
+
}
|
|
2330
|
+
function requiredString(config, key) {
|
|
2331
|
+
const value = config[key] === "" ? "" : read(config, key, "string");
|
|
2332
|
+
if (typeof value !== "string") throw invalid(key, "a string");
|
|
2333
|
+
return value;
|
|
2334
|
+
}
|
|
2335
|
+
var REQUIRE_MENTION = {
|
|
2336
|
+
key: "requireMention",
|
|
2337
|
+
required: false,
|
|
2338
|
+
secret: false,
|
|
2339
|
+
env: "WHATSAPP_REQUIRE_MENTION",
|
|
2340
|
+
description: "Whether group messages must mention the bot. Default true."
|
|
2341
|
+
};
|
|
2342
|
+
var CLOUD_CONFIG = [
|
|
2343
|
+
{
|
|
2344
|
+
key: "accessToken",
|
|
2345
|
+
required: true,
|
|
2346
|
+
secret: true,
|
|
2347
|
+
env: "WHATSAPP_ACCESS_TOKEN",
|
|
2348
|
+
description: "The Meta Cloud API access token."
|
|
2349
|
+
},
|
|
2350
|
+
{
|
|
2351
|
+
key: "phoneNumberId",
|
|
2352
|
+
required: true,
|
|
2353
|
+
secret: false,
|
|
2354
|
+
env: "WHATSAPP_PHONE_NUMBER_ID",
|
|
2355
|
+
description: "The Cloud API phone number id the adapter answers for."
|
|
2356
|
+
},
|
|
2357
|
+
{
|
|
2358
|
+
key: "appSecret",
|
|
2359
|
+
required: true,
|
|
2360
|
+
secret: true,
|
|
2361
|
+
env: "WHATSAPP_APP_SECRET",
|
|
2362
|
+
description: "The Meta app secret that signs inbound webhooks."
|
|
2363
|
+
},
|
|
2364
|
+
{
|
|
2365
|
+
key: "verifyToken",
|
|
2366
|
+
required: false,
|
|
2367
|
+
secret: true,
|
|
2368
|
+
env: "WHATSAPP_VERIFY_TOKEN",
|
|
2369
|
+
description: "The token Meta's webhook subscription check sends; the webhook's GET answers 403 without it."
|
|
2370
|
+
},
|
|
2371
|
+
REQUIRE_MENTION
|
|
2372
|
+
];
|
|
2373
|
+
var BAILEYS_CONFIG = [
|
|
2374
|
+
{
|
|
2375
|
+
key: "sessionDir",
|
|
2376
|
+
required: true,
|
|
2377
|
+
secret: false,
|
|
2378
|
+
env: "WHATSAPP_SESSION_DIR",
|
|
2379
|
+
description: "Directory where the Baileys session (credentials) is stored."
|
|
2380
|
+
},
|
|
2381
|
+
{
|
|
2382
|
+
key: "botPhoneId",
|
|
2383
|
+
required: false,
|
|
2384
|
+
secret: false,
|
|
2385
|
+
env: "WHATSAPP_BOT_PHONE_ID",
|
|
2386
|
+
description: "The bot's own number; with requireMention (default), a group message must mention it or is dropped."
|
|
2387
|
+
},
|
|
2388
|
+
REQUIRE_MENTION
|
|
2389
|
+
];
|
|
2390
|
+
function common(config) {
|
|
2391
|
+
const requireMention = read(config, "requireMention", "boolean");
|
|
2392
|
+
const botPhoneId = read(config, "botPhoneId", "string");
|
|
2393
|
+
return {
|
|
2394
|
+
...requireMention === void 0 ? {} : { requireMention },
|
|
2395
|
+
...botPhoneId === void 0 ? {} : { botPhoneId }
|
|
2396
|
+
};
|
|
2397
|
+
}
|
|
2398
|
+
function createCloud(config) {
|
|
2399
|
+
const accessToken = requiredString(config, "accessToken");
|
|
2400
|
+
const phoneNumberId = requiredString(config, "phoneNumberId");
|
|
2401
|
+
const appSecret = requiredString(config, "appSecret");
|
|
2402
|
+
const verifyToken = read(config, "verifyToken", "string");
|
|
2403
|
+
const opts = common(config);
|
|
2404
|
+
const adapter = WhatsAppAdapter.from(
|
|
2405
|
+
{ backend: "cloud", cloud: { accessToken, phoneNumberId, appSecret } },
|
|
2406
|
+
opts
|
|
2407
|
+
);
|
|
2408
|
+
rememberWebhookConfig(adapter, {
|
|
2409
|
+
appSecret,
|
|
2410
|
+
...verifyToken === void 0 ? {} : { verifyToken }
|
|
2411
|
+
});
|
|
2412
|
+
return adapter;
|
|
2413
|
+
}
|
|
2414
|
+
function createBaileys(config) {
|
|
2415
|
+
const sessionDir = requiredString(config, "sessionDir");
|
|
2416
|
+
const opts = common(config);
|
|
2417
|
+
return WhatsAppAdapter.from({ backend: "baileys", baileys: { sessionDir } }, opts);
|
|
2418
|
+
}
|
|
2419
|
+
var cloudChannel = {
|
|
2420
|
+
platform: "whatsapp",
|
|
2421
|
+
transport: "webhook",
|
|
2422
|
+
webhook: cloudWebhook,
|
|
2423
|
+
senderIdentity: "authenticated",
|
|
2424
|
+
config: CLOUD_CONFIG,
|
|
2425
|
+
create: createCloud
|
|
2426
|
+
};
|
|
2427
|
+
var baileysChannel = {
|
|
2428
|
+
platform: "whatsapp",
|
|
2429
|
+
transport: "socket",
|
|
2430
|
+
senderIdentity: "authenticated",
|
|
2431
|
+
config: BAILEYS_CONFIG,
|
|
2432
|
+
create: createBaileys
|
|
2433
|
+
};
|
|
2434
|
+
var whatsappChannel = {
|
|
2435
|
+
...cloudChannel,
|
|
2436
|
+
variants: { cloud: cloudChannel, baileys: baileysChannel }
|
|
2196
2437
|
};
|
|
2197
2438
|
|
|
2198
2439
|
exports.ConfigurationError = ConfigurationError;
|
|
@@ -2216,5 +2457,6 @@ exports.parseWebhookPayload = parseWebhookPayload;
|
|
|
2216
2457
|
exports.splitForWhatsApp = splitForWhatsApp;
|
|
2217
2458
|
exports.verifyWebhookSignature = verifyWebhookSignature;
|
|
2218
2459
|
exports.verifyWebhookSubscription = verifyWebhookSubscription;
|
|
2460
|
+
exports.whatsappChannel = whatsappChannel;
|
|
2219
2461
|
//# sourceMappingURL=index.cjs.map
|
|
2220
2462
|
//# sourceMappingURL=index.cjs.map
|