@owlmeans/bot-whatsapp 0.0.0-stage → 0.2.0-alpha.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.
Files changed (60) hide show
  1. package/README.md +74 -2
  2. package/agent-meta/manifest.json +16 -0
  3. package/agent-meta/skills/bot-whatsapp/SKILL.md +104 -0
  4. package/build/api.d.ts +7 -0
  5. package/build/api.d.ts.map +1 -0
  6. package/build/api.js +50 -0
  7. package/build/api.js.map +1 -0
  8. package/build/append.d.ts +10 -0
  9. package/build/append.d.ts.map +1 -0
  10. package/build/append.js +13 -0
  11. package/build/append.js.map +1 -0
  12. package/build/consts.d.ts +57 -0
  13. package/build/consts.d.ts.map +1 -0
  14. package/build/consts.js +183 -0
  15. package/build/consts.js.map +1 -0
  16. package/build/errors.d.ts +22 -0
  17. package/build/errors.d.ts.map +1 -0
  18. package/build/errors.js +34 -0
  19. package/build/errors.js.map +1 -0
  20. package/build/index.d.ts +7 -0
  21. package/build/index.d.ts.map +1 -0
  22. package/build/index.js +6 -0
  23. package/build/index.js.map +1 -0
  24. package/build/mock.d.ts +9 -0
  25. package/build/mock.d.ts.map +1 -0
  26. package/build/mock.js +198 -0
  27. package/build/mock.js.map +1 -0
  28. package/build/normalize.d.ts +4 -0
  29. package/build/normalize.d.ts.map +1 -0
  30. package/build/normalize.js +109 -0
  31. package/build/normalize.js.map +1 -0
  32. package/build/plugin.d.ts +13 -0
  33. package/build/plugin.d.ts.map +1 -0
  34. package/build/plugin.js +147 -0
  35. package/build/plugin.js.map +1 -0
  36. package/build/signature.d.ts +4 -0
  37. package/build/signature.d.ts.map +1 -0
  38. package/build/signature.js +20 -0
  39. package/build/signature.js.map +1 -0
  40. package/build/types.d.ts +179 -0
  41. package/build/types.d.ts.map +1 -0
  42. package/build/types.js +2 -0
  43. package/build/types.js.map +1 -0
  44. package/package.json +56 -4
  45. package/src/api.ts +62 -0
  46. package/src/append.ts +18 -0
  47. package/src/consts.ts +206 -0
  48. package/src/errors.ts +37 -0
  49. package/src/index.ts +6 -0
  50. package/src/mock.ts +243 -0
  51. package/src/normalize.ts +131 -0
  52. package/src/plugin.ts +183 -0
  53. package/src/signature.ts +27 -0
  54. package/src/types.ts +174 -0
  55. package/tests/context.ts +85 -0
  56. package/tests/descriptor.spec.ts +64 -0
  57. package/tests/mock-ids.spec.ts +38 -0
  58. package/tests/tsconfig.json +12 -0
  59. package/tests/whatsapp.spec.ts +485 -0
  60. package/tsconfig.json +16 -0
package/src/types.ts ADDED
@@ -0,0 +1,174 @@
1
+ import type { BotConnection } from '@owlmeans/bot'
2
+ import type { BotHookRequest } from '@owlmeans/server-bot'
3
+ import type { BotNormalizedUpdate, BotPlatformConnection, BotPlatformMock, BotPlatformSession } from '@owlmeans/server-bot'
4
+
5
+ // ─── Native Cloud API shapes (https://developers.facebook.com/documentation/business-messaging/whatsapp/webhooks/reference/messages) — the fields used ───
6
+
7
+ export interface WhatsAppMetadata {
8
+ display_phone_number: string
9
+ phone_number_id: string
10
+ }
11
+
12
+ export interface WhatsAppContact {
13
+ profile?: { name?: string }
14
+ wa_id: string
15
+ }
16
+
17
+ /** The quoted message (a reply), or a forwarded flag. */
18
+ export interface WhatsAppContext {
19
+ /** Who wrote the quoted message — the business number when it is the bot's. */
20
+ from?: string
21
+ id?: string
22
+ forwarded?: boolean
23
+ frequently_forwarded?: boolean
24
+ }
25
+
26
+ export interface WhatsAppInteractive {
27
+ type: 'button_reply' | 'list_reply' | string
28
+ button_reply?: { id: string, title: string }
29
+ list_reply?: { id: string, title: string, description?: string }
30
+ }
31
+
32
+ export interface WhatsAppMedia {
33
+ id?: string
34
+ caption?: string
35
+ mime_type?: string
36
+ }
37
+
38
+ export interface WhatsAppMessage {
39
+ /** The customer's WhatsApp id (`wa_id`). */
40
+ from: string
41
+ /** `wamid.…` */
42
+ id: string
43
+ /** Unix seconds, as text. */
44
+ timestamp: string
45
+ type: string
46
+ text?: { body: string }
47
+ interactive?: WhatsAppInteractive
48
+ /** A template's quick-reply button. */
49
+ button?: { text?: string, payload?: string }
50
+ image?: WhatsAppMedia
51
+ video?: WhatsAppMedia
52
+ document?: WhatsAppMedia
53
+ context?: WhatsAppContext
54
+ }
55
+
56
+ /** A delivery receipt of a message the business sent. */
57
+ export interface WhatsAppStatus {
58
+ id: string
59
+ status: string
60
+ timestamp: string
61
+ recipient_id: string
62
+ }
63
+
64
+ export interface WhatsAppValue {
65
+ messaging_product: string
66
+ metadata: WhatsAppMetadata
67
+ contacts?: WhatsAppContact[]
68
+ messages?: WhatsAppMessage[]
69
+ statuses?: WhatsAppStatus[]
70
+ }
71
+
72
+ export interface WhatsAppChange {
73
+ field: string
74
+ value: WhatsAppValue
75
+ }
76
+
77
+ export interface WhatsAppEntry {
78
+ /** The WhatsApp Business Account id. */
79
+ id: string
80
+ changes: WhatsAppChange[]
81
+ }
82
+
83
+ /** One webhook POST — Meta may batch several entries, changes and messages. */
84
+ export interface WhatsAppWebhook {
85
+ object: string
86
+ entry: WhatsAppEntry[]
87
+ }
88
+
89
+ /** `GET /<phone-number-id>?fields=display_phone_number,verified_name` */
90
+ export interface WhatsAppPhoneNumber {
91
+ id: string
92
+ display_phone_number?: string
93
+ verified_name?: string
94
+ }
95
+
96
+ /** `POST /<phone-number-id>/messages` — what it answers. */
97
+ export interface WhatsAppSendAnswer {
98
+ messaging_product: string
99
+ contacts?: { input: string, wa_id: string }[]
100
+ messages: { id: string, message_status?: string }[]
101
+ }
102
+
103
+ /** Every Graph API refusal. */
104
+ export interface WhatsAppErrorEnvelope {
105
+ error: {
106
+ message: string
107
+ type?: string
108
+ code: number
109
+ error_subcode?: number
110
+ error_data?: { messaging_product?: string, details?: string }
111
+ fbtrace_id?: string
112
+ }
113
+ }
114
+
115
+ // ─── The plugin's parts ───
116
+
117
+ export interface WhatsAppBotPlatformOptions {
118
+ /** The Graph API host, default `https://graph.facebook.com`. */
119
+ base?: string
120
+ /** The Graph API version, default `v26.0`; calls go to `<base>/<version>/…`. */
121
+ version?: string
122
+ }
123
+
124
+ export interface WhatsAppCallOptions {
125
+ signal?: AbortSignal
126
+ timeoutMs?: number
127
+ }
128
+
129
+ /** The Graph API over a session's transport, the access token as a Bearer header. */
130
+ export interface WhatsAppApi {
131
+ /** GET `<root>/<path>?<query>`. @throws {WhatsAppApiError} an `error` answer */
132
+ get: <T>(path: string, query?: Record<string, string>, opts?: WhatsAppCallOptions) => Promise<T>
133
+ /** POST `<root>/<path>` with a JSON body. @throws {WhatsAppApiError} an `error` answer */
134
+ post: <T>(path: string, body: Record<string, unknown>, opts?: WhatsAppCallOptions) => Promise<T>
135
+ }
136
+
137
+ export interface WhatsAppApiFactory {
138
+ /** `root` = `<base>/<version>`. */
139
+ (session: Pick<BotPlatformSession, 'connection' | 'fetch'>, root: string): WhatsAppApi
140
+ }
141
+
142
+ /** Meta's `X-Hub-Signature-256` — HMAC-SHA256 of the raw body, keyed by the app secret. */
143
+ export interface WhatsAppSignatureHelper {
144
+ /** The header value for `rawBody`: `sha256=<lower-case hex>`. */
145
+ sign: (rawBody: string, secret: string) => string
146
+ /** Whether `header` signs `rawBody` with `secret` — timing-safe; an empty secret never matches. */
147
+ verify: (header: string | undefined, rawBody: string, secret: string) => boolean
148
+ }
149
+
150
+ export interface WhatsAppNormalizer {
151
+ /**
152
+ * Every `messages[]` of every change of a `whatsapp_business_account` payload → one update each
153
+ * (text, interactive and button replies, media captions); statuses and other kinds → none.
154
+ */
155
+ normalize: (payload: unknown, connection: BotConnection) => BotNormalizedUpdate[]
156
+ }
157
+
158
+ export interface WhatsAppMock extends BotPlatformMock {
159
+ /** The phone number id the fake API answers for a connection (its `phoneNumberId`, else one derived from its id). */
160
+ phoneNumberIdOf: (connection: BotPlatformConnection) => string
161
+ /** The business number the fake API shows for a connection (`1555…`). */
162
+ displayNumberOf: (connection: BotPlatformConnection) => string
163
+ /** The subscription handshake Meta sends (GET `hub.*`) — with the connection's verify token unless one is given. */
164
+ challenge: (connection: BotPlatformConnection, opts?: { challenge?: string, verifyToken?: string }) => BotHookRequest
165
+ }
166
+
167
+ /** One mock connection's state. */
168
+ export interface WhatsAppMockState {
169
+ calls: { method: string, params: Record<string, unknown>, at: string }[]
170
+ /** Message ids the fake business sent — a simulated reply to one quotes the bot. */
171
+ sent: Set<string>
172
+ /** Payloads `feed` was handed — WhatsApp has no receiver, so nothing drains them. */
173
+ fed: unknown[]
174
+ }
@@ -0,0 +1,85 @@
1
+ import { randomUUID } from 'node:crypto'
2
+ import { AppType, makeBasicContext, type BasicConfig, type BasicContext } from '@owlmeans/context'
3
+ import { configureLog } from '@owlmeans/log'
4
+ import type { Resource } from '@owlmeans/resource'
5
+ import {
6
+ appendBot, RES_BOT_ACTIVITY, RES_BOT_CONNECTION, RES_BOT_UPDATE, type BotActivityRecord, type BotConnectionRecord,
7
+ type BotService, type BotServiceOptions, type BotUpdateRecord,
8
+ } from '@owlmeans/server-bot'
9
+ import { makeBotMockHelper } from '@owlmeans/server-bot/mock'
10
+ import { createStaticResource } from '@owlmeans/static-resource'
11
+ import { whatsappBotPlatform } from '../src/plugin.js'
12
+
13
+ export const SECRET = 'bot-whatsapp-tests-secret'
14
+
15
+ // Refusals and handler failures are expected here; `LOG_LEVEL=debug bun test` shows every line.
16
+ configureLog({ level: process.env.LOG_LEVEL ?? 'error' })
17
+
18
+ /** Native, signed payloads of the ready plugin instance — the one every `makeTestBot()` registers. */
19
+ export const botMockHelper = makeBotMockHelper([whatsappBotPlatform])
20
+
21
+ export interface TestBot {
22
+ /** The store key: another `makeTestBot(options, store)` reads and writes the same rows (a restart). */
23
+ store: string
24
+ context: BasicContext<BasicConfig>
25
+ service: BotService
26
+ connections: Resource<BotConnectionRecord>
27
+ updates: Resource<BotUpdateRecord>
28
+ activities: Resource<BotActivityRecord>
29
+ }
30
+
31
+ let stores = 0
32
+
33
+ /**
34
+ * One real context per test: the three resources as `@owlmeans/static-resource` stores (a fresh key
35
+ * each time, unless `store` names an earlier bot's — that bot's process restarted), then `appendBot`
36
+ * with this package's ready plugin instance (unless `options.platforms` names others). A fast
37
+ * dispatcher; the secret is a fixture.
38
+ */
39
+ export const makeTestBot = (options: BotServiceOptions = {}, store?: string): TestBot => {
40
+ const key = store ?? `bot-whatsapp-tests-${++stores}`
41
+ const context = makeBasicContext<BasicConfig>({ ready: false, service: 'bot-whatsapp-tests', type: AppType.Backend, services: {} })
42
+ const connections = createStaticResource<BotConnectionRecord>(RES_BOT_CONNECTION, `${key}-connection`)
43
+ const updates = createStaticResource<BotUpdateRecord>(RES_BOT_UPDATE, `${key}-update`)
44
+ const activities = createStaticResource<BotActivityRecord>(RES_BOT_ACTIVITY, `${key}-activity`)
45
+ context.registerResource(connections)
46
+ context.registerResource(updates)
47
+ context.registerResource(activities)
48
+ const service = appendBot(context, {
49
+ secret: () => SECRET, pollMs: 5, reconcileMs: 20, ...options, platforms: options.platforms ?? [whatsappBotPlatform],
50
+ })
51
+
52
+ return { store: key, context, service, connections, updates, activities }
53
+ }
54
+
55
+ export const scopeOf = (): string => `scope-${randomUUID()}`
56
+
57
+ /** A response the bound handler resolves or rejects — the smallest the transport needs. */
58
+ export const invoke = async (entrypoint: object, request: Record<string, unknown>): Promise<any> => {
59
+ const response: any = {
60
+ resolve: (value: unknown) => { response.value = value },
61
+ reject: (error: Error) => { response.error = error },
62
+ }
63
+ await (entrypoint as { handle: (req: unknown, res: unknown) => Promise<unknown> }).handle({
64
+ alias: 'test', headers: {}, params: {}, query: {}, body: {}, path: '/', ...request,
65
+ }, response)
66
+ if (response.error != null) {
67
+ throw response.error
68
+ }
69
+
70
+ return response.value
71
+ }
72
+
73
+ export const sleep = async (ms: number): Promise<void> => { await new Promise(resolve => setTimeout(resolve, ms)) }
74
+
75
+ /** Poll until `probe` holds (or fail after `timeoutMs`). */
76
+ export const until = async (probe: () => Promise<boolean>, timeoutMs: number = 3_000): Promise<void> => {
77
+ const deadline = Date.now() + timeoutMs
78
+ while (Date.now() < deadline) {
79
+ if (await probe()) {
80
+ return
81
+ }
82
+ await sleep(10)
83
+ }
84
+ throw new Error('condition not reached')
85
+ }
@@ -0,0 +1,64 @@
1
+ import { describe, expect, test } from 'bun:test'
2
+ import { BOT_PLATFORM_ID_PATTERN, BotActionKind, BotTransport, type BotTexts } from '@owlmeans/bot'
3
+ import { BotInboxStatus, botHandler } from '@owlmeans/server-bot'
4
+ import { WHATSAPP_DESCRIPTOR, WHATSAPP_PLATFORM } from '../src/consts.js'
5
+ import { makeWhatsAppBotPlatform } from '../src/plugin.js'
6
+ import { makeTestBot, scopeOf } from './context.js'
7
+
8
+ /** The languages the bot panels ship — every text a descriptor carries is complete in each. */
9
+ const LANGUAGES = ['en', 'pl', 'ru', 'be', 'uk', 'es', 'de', 'fr']
10
+
11
+ const complete = (texts: BotTexts | undefined, what: string): void => {
12
+ for (const language of LANGUAGES) {
13
+ expect([what, language, typeof texts?.[language] === 'string' && texts[language].trim() !== '']).toEqual([what, language, true])
14
+ }
15
+ }
16
+
17
+ describe('@owlmeans/bot-whatsapp — the descriptor', () => {
18
+ test('names a well-formed, stable platform id and is the plugin\'s own', () => {
19
+ expect(WHATSAPP_PLATFORM).toBe('whatsapp')
20
+ expect(new RegExp(BOT_PLATFORM_ID_PATTERN).test(WHATSAPP_PLATFORM)).toBe(true)
21
+ const plugin = makeWhatsAppBotPlatform()
22
+ expect([plugin.platform, plugin.descriptor]).toEqual([WHATSAPP_PLATFORM, WHATSAPP_DESCRIPTOR])
23
+ expect(WHATSAPP_DESCRIPTOR.platform).toBe(WHATSAPP_PLATFORM)
24
+ })
25
+
26
+ test('carries every label and hint in all eight panel languages', () => {
27
+ complete(WHATSAPP_DESCRIPTOR.hint, 'hint')
28
+ for (const field of WHATSAPP_DESCRIPTOR.credentials) {
29
+ complete(field.label, `${field.key}.label`)
30
+ complete(field.hint, `${field.key}.hint`)
31
+ }
32
+ if (WHATSAPP_DESCRIPTOR.link != null) {
33
+ complete(WHATSAPP_DESCRIPTOR.link.label, 'link.label')
34
+ complete(WHATSAPP_DESCRIPTOR.link.pending, 'link.pending')
35
+ }
36
+ })
37
+
38
+ test('lists platform calls only (never note) and a glyph, docs and a receive mode', () => {
39
+ expect(WHATSAPP_DESCRIPTOR.actions).not.toContain(BotActionKind.Note)
40
+ expect(WHATSAPP_DESCRIPTOR.receive.length).toBeGreaterThan(0)
41
+ expect(WHATSAPP_DESCRIPTOR.docs).toStartWith('https://')
42
+ expect(['send', 'phone', 'messages', 'hash', 'chat']).toContain(WHATSAPP_DESCRIPTOR.glyph)
43
+ expect(Object.isFrozen(WHATSAPP_DESCRIPTOR) && Object.isFrozen(WHATSAPP_DESCRIPTOR.credentials)).toBe(true)
44
+ })
45
+
46
+ test('a message simulated after a restart (fresh plugin, same connection and store) is stored and dispatched', async () => {
47
+ const scope = scopeOf()
48
+ const before = makeTestBot({ platforms: [makeWhatsAppBotPlatform()] })
49
+ const saved = await before.service.connections.save(scope, { platform: WHATSAPP_PLATFORM, label: 'Mock', transport: BotTransport.Mock })
50
+ await before.service.connections.verify(scope, saved.id)
51
+ const first = await before.service.simulate(scope, saved.id, { text: 'before the restart' })
52
+ expect(await before.service.runtime([botHandler('seen', async () => undefined)]).dispatch()).toBe(1)
53
+
54
+ const after = makeTestBot({ platforms: [makeWhatsAppBotPlatform()] }, before.store)
55
+ const seen: string[] = []
56
+ const runtime = after.service.runtime([botHandler('seen', async update => { seen.push(update.id) })])
57
+ const second = await after.service.simulate(scope, saved.id, { text: 'after the restart' })
58
+
59
+ expect([first.duplicate, second.duplicate, second.update === first.update]).toEqual([false, false, false])
60
+ expect(await runtime.dispatch()).toBe(1)
61
+ expect(seen).toEqual([second.update])
62
+ expect((await after.updates.get(second.update)).status).toBe(BotInboxStatus.Done)
63
+ })
64
+ })
@@ -0,0 +1,38 @@
1
+ import { describe, expect, test } from 'bun:test'
2
+ import { BotConnectionStatus, BotTransport, type BotSimulateInput } from '@owlmeans/bot'
3
+ import type { BotPlatformConnection, BotPlatformMock } from '@owlmeans/server-bot'
4
+ import { WHATSAPP_DESCRIPTOR } from '../src/consts.js'
5
+ import { makeWhatsAppBotPlatform } from '../src/plugin.js'
6
+ import type { WhatsAppMock } from '../src/types.js'
7
+
8
+ /** One stored mock connection, as each "process" of a test opens it. */
9
+ const connectionOf = (platform: string): BotPlatformConnection => ({
10
+ id: `conn-${platform}`, scope: 'org', platform, label: 'Mock', transport: BotTransport.Mock,
11
+ status: BotConnectionStatus.Connected, enabled: true, receive: WHATSAPP_DESCRIPTOR.receive[0], credentialsSet: [],
12
+ createdAt: '2026-10-01T00:00:00.000Z', updatedAt: '2026-10-01T00:00:00.000Z', credentials: {}, hookSecret: 'hook-secret',
13
+ })
14
+
15
+ const input: BotSimulateInput = { text: 'hello' }
16
+
17
+ /** The native body of a simulated message, built by `mock`. */
18
+ const bodyOf = (mock: BotPlatformMock, platform: string): any => mock.inbound(input, connectionOf(platform)).body
19
+
20
+ /** Eight fresh mocks — eight process lifetimes of the same connection. */
21
+ const lifetimes = <T>(make: () => { mock: BotPlatformMock }, read: (mock: BotPlatformMock) => T): T[] =>
22
+ Array.from({ length: 8 }, () => read(make().mock))
23
+
24
+ describe('@owlmeans/bot-whatsapp — mock ids: the platform\'s shapes, unique across restarts and processes', () => {
25
+ test('WhatsApp: every wamid (inbound and sent) is fresh and random', async () => {
26
+ const plugin = makeWhatsAppBotPlatform()
27
+ const idOf = (mock: BotPlatformMock): string => bodyOf(mock, 'whatsapp').entry[0].changes[0].value.messages[0].id
28
+ const connection = connectionOf('whatsapp')
29
+ const sent: any = await (await plugin.mock.fetch(connection)(
30
+ `https://graph.facebook.com/v26.0/${(plugin.mock as WhatsAppMock).phoneNumberIdOf(connection)}/messages`,
31
+ { method: 'POST', body: JSON.stringify({ messaging_product: 'whatsapp', to: '15550001', type: 'text', text: { body: 'hi' } }) }
32
+ )).json()
33
+ const ids = [idOf(plugin.mock), sent.messages[0].id, ...lifetimes(makeWhatsAppBotPlatform, idOf)]
34
+
35
+ expect(ids.every(id => /^wamid\.[A-Za-z0-9+/]+=*$/.test(id))).toBe(true)
36
+ expect(new Set(ids).size).toBe(ids.length)
37
+ })
38
+ })
@@ -0,0 +1,12 @@
1
+ {
2
+ "extends": [
3
+ "@owlmeans/dep-config/tsconfig.base.json",
4
+ "@owlmeans/dep-config/tsconfig.node.json"
5
+ ],
6
+ "compilerOptions": {
7
+ "types": ["bun"],
8
+ "rootDir": "../",
9
+ "noEmit": true
10
+ },
11
+ "include": ["./**/*", "../src/**/*"]
12
+ }