@kyyinfinite/zapo-message 1.0.0 → 1.0.1

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/README.md CHANGED
@@ -1,376 +1,894 @@
1
- # @kyyinfinite/zapo-message
1
+ <div align="center">
2
2
 
3
- Message toolkit untuk [ZapoJS](https://www.npmjs.com/package/zapo-js) — WhatsApp Web library.
4
- Satu import, semua builder pesan langsung menempel di client: teks, tombol native flow,
5
- tombol legacy, list, media, sticker, poll, contact, album, reaction, forward, location,
6
- dan respons rich AIRich.
3
+ # `@kyyinfinite/zapo-message`
7
4
 
8
- Setiap jenis pesan punya **dua gaya API setara** — object async dan fluent chain —
9
- dengan satu implementasi builder yang sama:
5
+ **A practical message toolkit for ZapoJS.**
6
+
7
+ Build WhatsApp messages with a small, consistent API • use a typed config object or a fluent builder, backed by the same message pipeline.
8
+
9
+ [![npm version](https://img.shields.io/npm/v/%40kyyinfinite%2Fzapo-message?style=flat-square&logo=npm&color=cb3837)](https://www.npmjs.com/package/@kyyinfinite/zapo-message)
10
+ [![Node.js](https://img.shields.io/badge/Node.js-%E2%89%A520.9-339933?style=flat-square&logo=nodedotjs&logoColor=white)](https://nodejs.org/)
11
+ [![TypeScript](https://img.shields.io/badge/TypeScript-supported-3178c6?style=flat-square&logo=typescript&logoColor=white)](https://www.typescriptlang.org/)
12
+ [![License: ISC](https://img.shields.io/badge/License-ISC-blue?style=flat-square)](LICENSE)
13
+
14
+ [Getting started](#-getting-started) · [API reference](#-api-reference) · [Payloads](#-message-payloads) · [Troubleshooting](#-troubleshooting) · [FAQ](#-faq)
15
+
16
+ </div>
17
+
18
+ ---
19
+
20
+ ## ✨ What it does
21
+
22
+ `@kyyinfinite/zapo-message` adds message builders to [ZapoJS](https://www.npmjs.com/package/zapo-js). It covers everyday messages, interactive messages, media, and AIRich responses without making you assemble protocol payloads by hand.
23
+
24
+ The package is designed around one simple idea: **one message type, two ways to call it, one implementation**.
25
+
26
+ - **Object API** • pass a typed configuration object and await the result.
27
+ - **Fluent API** • configure a builder step by step and call `.send()`.
28
+ - **Shared execution path** • both styles use the same builder, validation, payload construction, media resolution, and transport path.
29
+ - **ZapoJS integration** • import the package once and use the methods on `WaClient`.
30
+ - **Standalone factories** • use exported factories when you prefer not to patch a client prototype.
10
31
 
11
32
  ```ts
12
33
  import { createStore, WaClient } from "zapo-js";
13
34
  import "@kyyinfinite/zapo-message";
14
35
 
15
- const client = new WaClient({ store: createStore({}), sessionId: "bot" });
36
+ const client = new WaClient({
37
+ store: createStore({}),
38
+ sessionId: "my-bot",
39
+ });
40
+
16
41
  await client.connect();
17
42
 
18
- // object async — sekali panggil, langsung Promise
19
- await client.text(jid, { body: "Halo Dunia" });
20
- await client.button(jid, {
21
- body: "Pilih satu",
22
- buttons: [{ type: "quick_reply", text: "Klik saya", id: "cmd-ok" }],
23
- });
43
+ const jid = "628123456789@s.whatsapp.net";
24
44
 
25
- // fluent chain — konfigurasi bertahap
26
- await client.text().body("Halo Dunia").send(jid);
27
- await client.button().body("Pilih satu").quick_reply("Klik saya", "cmd-ok").send(jid);
45
+ await client.text(jid, { body: "Hello from Zapo Message" });
46
+ await client.text().to(jid).body("Same message, fluent style").send();
28
47
  ```
29
48
 
30
- Tidak ada `messageKit(client)`, tidak ada `extendSocket`, tidak ada registrasi manual —
31
- import sekali dan `client.text()`, `client.button()`, `client.poll()` langsung tersedia
32
- untuk semua instance `WaClient` (ESM dan CJS), lengkap dengan tipenya di TypeScript.
49
+ ## 📦 Installation
33
50
 
34
- ## Hybrid API: object async dan fluent chain
51
+ ```bash
52
+ npm install @kyyinfinite/zapo-message zapo-js
53
+ ```
54
+
55
+ Optional image processing support:
56
+
57
+ ```bash
58
+ npm install sharp
59
+ ```
35
60
 
36
- Prinsipnya: **satu jenis pesan = dua gaya pemanggilan = satu implementasi bersama**.
37
- Kedua gaya memakai builder, validasi, konstruksi payload, dan pipeline eksekusi yang
38
- sama — bentuk async hanyalah config object yang dipetakan ke method chain, lalu
39
- dieksekusi lewat `send()` builder yang sama. Payload, error class, dan error code
40
- dijamin identik (diuji di suite `hybrid*.test.ts`).
61
+ ### Requirements
41
62
 
42
- ### Object async
63
+ | Requirement | Version / notes |
64
+ | --- | --- |
65
+ | Node.js | `>=20.9.0` |
66
+ | ZapoJS | Peer dependency `>=1.11.0 <2.0.0` |
67
+ | TypeScript | Supported through published declaration files |
68
+ | `sharp` | Optional peer dependency; used for image processing and automatic thumbnail generation |
69
+
70
+ `file-type` is installed as a regular dependency and is used to detect media types from file contents.
71
+
72
+ ## 🚀 Getting started
73
+
74
+ ### 1. Import the integration
43
75
 
44
76
  ```ts
45
- await client.text(jid, { body: "Halo Dunia" });
77
+ import { createStore, WaClient } from "zapo-js";
78
+ import "@kyyinfinite/zapo-message";
46
79
 
47
- await client.button(jid, {
48
- title: "Main Menu",
49
- subtitle: "Welcome",
50
- body: "Choose one",
51
- footer: "Powered by Avelyna",
52
- buttons: [
53
- { type: "quick_reply", text: "Profile", id: "profile" },
54
- { type: "cta_url", text: "Website", url: "https://example.com" },
55
- { type: "cta_copy", text: "Copy Code", copyCode: "AVELYNA" },
56
- { type: "cta_call", text: "Contact", phoneNumber: "+628123456789" },
57
- { type: "send_location", text: "Kirim lokasi" },
58
- {
59
- type: "single_select",
60
- title: "Pilih salah satu",
61
- sections: [{ title: "Utama", rows: [{ id: "a", title: "Opsi A" }] }],
62
- },
63
- ],
80
+ const client = new WaClient({
81
+ store: createStore({}),
82
+ sessionId: "my-bot",
64
83
  });
65
84
 
66
- await client.listMessage(jid, {
67
- title: "Main Menu",
68
- body: "Choose a menu",
69
- buttonText: "Open",
70
- sections: [
71
- { title: "General", rows: [{ id: "profile", title: "Profile" }] },
72
- ],
73
- });
85
+ await client.connect();
86
+ ```
74
87
 
75
- await client.airich(jid, {
76
- sections: [
77
- { type: "text", text: "Welcome" },
78
- { type: "code", language: "javascript", code: "console.log('Hello')" },
79
- { type: "tip", text: "Helpful information" },
80
- ],
81
- footer: "Powered by Avelyna",
88
+ The package installs its methods on the `WaClient` prototype when the root package is imported. The integration skips names that already exist on the prototype and uses a marker to avoid installing the same methods twice.
89
+
90
+ ### 2. Send a message
91
+
92
+ ```ts
93
+ const jid = "628123456789@s.whatsapp.net";
94
+
95
+ await client.text(jid, { body: "Hello!" });
96
+ ```
97
+
98
+ Or use a builder:
99
+
100
+ ```ts
101
+ await client
102
+ .text()
103
+ .to(jid)
104
+ .body("Hello!")
105
+ .send();
106
+ ```
107
+
108
+ ### 3. Handle incoming messages
109
+
110
+ ```ts
111
+ client.on("message", async (event) => {
112
+ const jid = event.key.remoteJid;
113
+ if (!jid) return;
114
+
115
+ if (event.message?.conversation === "ping") {
116
+ await client.text(jid, { body: "pong" });
117
+ }
82
118
  });
119
+ ```
83
120
 
84
- await client.media(jid, { type: "image", source: pngBuffer, caption: "My image" });
85
- await client.image(jid, { source: pngBuffer, caption: "My image" });
86
- await client.poll(jid, { question: "Siapa menang?", options: ["A", "B"] });
87
- await client.contact(jid, { name: "Budi", phone: "+628123456789" });
88
- await client.location(jid, { latitude: -6.2, longitude: 106.8, name: "Jakarta" });
89
- await client.album(jid, {
90
- media: [
91
- { type: "image", source: pngA },
92
- { type: "video", source: mp4B, options: { mimetype: "video/mp4" } },
121
+ Connect the client according to your application's lifecycle and disconnect it when the process is shutting down.
122
+
123
+ ## 🔀 The hybrid API
124
+
125
+ Every integrated method has a builder form. Most methods also have a config-object form that sends immediately.
126
+
127
+ ### Object API
128
+
129
+ ```ts
130
+ await client.text(jid, { body: "Hello" });
131
+
132
+ await client.button(jid, {
133
+ body: "Choose an action",
134
+ buttons: [
135
+ { type: "quick_reply", text: "Open menu", id: "menu" },
136
+ { type: "cta_url", text: "Website", url: "https://example.com" },
93
137
  ],
94
138
  });
95
- await client.reaction({ target: incomingEvent, emoji: "🔥" });
96
- await client.forward(jidLain, { message: incomingEvent });
97
139
  ```
98
140
 
99
- ### Fluent chain
141
+ ### Fluent API
100
142
 
101
143
  ```ts
102
- await client.text().to(jid).body("Halo Dunia").send();
103
- await client.button()
144
+ await client.text().to(jid).body("Hello").send();
145
+
146
+ await client
147
+ .button()
104
148
  .to(jid)
105
- .title("Main Menu")
106
- .body("Choose one")
107
- .quick_reply("Profile", "profile")
149
+ .body("Choose an action")
150
+ .quick_reply("Open menu", "menu")
108
151
  .cta_url("Website", "https://example.com")
109
152
  .send();
110
- await client.airich().text("Welcome").code("javascript", "...").send(jid);
111
- await client.location().to(jid).coordinates(-6.2, 106.8).name("Jakarta").send();
112
153
  ```
113
154
 
114
- Semua opsi kirim (`quote`, `mentions`, `expirationSeconds`, `additionalAttributes`,
115
- `viewOnce`, `id`, plus opsi publish `ackTimeoutMs`/`maxAttempts`/`retryDelayMs`)
116
- tersedia sebagai parameter ketiga di gaya async (`MessageSendOptions`) dan argumen
117
- kedua `send()` di gaya chain. AIRich menambah `twoStep` dan `submessages`
118
- (`AIRichSendOptions`).
155
+ ### How targets are resolved
119
156
 
120
- ## Apa itu Zapo Message
157
+ A builder can receive its destination in either of these ways:
121
158
 
122
- Zapo Message adalah lapisan pengirim pesan di atas ZapoJS:
123
-
124
- - **Fluent builder** untuk semua jenis pesan WhatsApp — payload protokol dibangun
125
- sampai level field, bukan sekadar wrapper tipis.
126
- - **Integrasi otomatis** — `import "@kyyinfinite/zapo-message"` memasang builder di
127
- `WaClient` tanpa mengubah satu pun method bawaan ZapoJS.
128
- - **ZapoJS tetap sumber kebenaran protokol** — semua payload diverifikasi terhadap
129
- definisi protobuf dan implementasi `zapo-js@1.11.0`, bukan hasil tebakan.
130
- - **AIRich** — respons rich text (teks, tabel, kode, saran lanjutan) mengikuti format
131
- `richResponseMessage` WhatsApp.
132
- - **Serializer & parser** — `mSerialize`/`qSerialize` untuk membuat konten pesan
133
- terkutip (quoted), dan `extractInteractiveResponse` untuk membaca respons tombol/list.
134
- - **Duck-typed boundary** — builder hanya butuh `client.message.send` (dan
135
- `client.message.upload` untuk media), jadi mudah di-mock saat pengujian.
159
+ ```ts
160
+ await client.text().body("Hello").send(jid);
136
161
 
137
- ## Installation
162
+ await client.text().to(jid).body("Hello").send();
138
163
 
139
- ```bash
140
- npm install @kyyinfinite/zapo-message zapo-js
164
+ await client.text().defaultTo(jid).body("Hello").send();
141
165
  ```
142
166
 
143
- Untuk pemrosesan gambar otomatis (thumbnail header tombol, thumbnail PNG sticker,
144
- deteksi dimensi), instal `sharp` sebagai peer dependency opsional:
167
+ `.to(jid)` is an alias for `.defaultTo(jid)`. A destination passed to `.send(jid)` takes precedence over the builder's default destination.
145
168
 
146
- ```bash
147
- npm install sharp
169
+ The client is bound automatically when a builder is created through `client.method()`. Standalone factories can bind the client explicitly; see [Standalone factories](#standalone-factories).
170
+
171
+ ### Send options
172
+
173
+ The object API accepts a third argument for send options. The fluent API accepts the same options as the second argument to `.send()`.
174
+
175
+ ```ts
176
+ await client.text(
177
+ jid,
178
+ { body: "Replying to your message" },
179
+ { quote: incomingEvent },
180
+ );
181
+
182
+ await client
183
+ .text()
184
+ .body("Replying to your message")
185
+ .send(jid, { quote: incomingEvent });
148
186
  ```
149
187
 
150
- Tanpa `sharp`, semua fitur tetap jalan kecuali generasi thumbnail/dimensi otomatis —
151
- media tetap terkirim, dan jalur yang butuh `sharp` memberi error yang jelas.
188
+ `MessageSendOptions` currently exposes:
189
+
190
+ | Option | Type | Purpose |
191
+ | --- | --- | --- |
192
+ | `quote` | `unknown` | Message reference to quote; interpreted by ZapoJS transport |
193
+ | `mentions` | `readonly string[]` | Mention JIDs |
194
+ | `contextInfo` | `Record<string, unknown>` | Additional message context |
195
+ | `forward` | `boolean \| { score?: number }` | Forwarding metadata where supported |
196
+ | `id` | `string` | Message ID option passed to the transport |
197
+ | `expirationSeconds` | `number` | Expiration option passed to the transport |
198
+ | `additionalAttributes` | `Readonly<Record<string, string>>` | Additional transport attributes |
199
+ | `viewOnce` | `boolean` | View-once option passed to the transport |
200
+ | `messageSecret` | `Uint8Array` | Message secret passed to the transport |
201
+ | `ackTimeoutMs` | `number` | Acknowledgement timeout passed to the transport |
202
+ | `maxAttempts` | `number` | Maximum send attempts passed to the transport |
203
+ | `retryDelayMs` | `number` | Retry delay passed to the transport |
204
+
205
+ The package forwards these options to `client.message.send()`. The exact effect of transport-level options depends on the installed ZapoJS version.
206
+
207
+ > **Reaction exception:** `reaction()` accepts a config object without a JID because the target chat can be resolved from `config.target`. You can still pass a JID explicitly when needed.
208
+
209
+ ## 📚 API reference
210
+
211
+ All methods below are installed on `WaClient` by the root import. The same factories are exported from the package root.
212
+
213
+ | Method | Object API | Fluent builder | Message payload family |
214
+ | --- | --- | --- | --- |
215
+ | `text` | `text(jid, config, options?)` | `text()` | `conversation` |
216
+ | `button` | `button(jid, config, options?)` | `button()` | `interactiveMessage` |
217
+ | `legacyButton` | `legacyButton(jid, config, options?)` | `legacyButton()` | `buttonsMessage` |
218
+ | `listMessage` | `listMessage(jid, config, options?)` | `listMessage()` | `listMessage` or native-flow fallback |
219
+ | `airich` | `airich(jid, config, options?)` | `airich(options?)` | `botForwardedMessage` / `richResponseMessage` |
220
+ | `linkPreview` | `linkPreview(jid, config, options?)` | `linkPreview()` | `extendedTextMessage` |
221
+ | `media` | `media(jid, config, options?)` | `media()` | image, video, audio, or document message |
222
+ | `image` | `image(jid, config, options?)` | `image()` | image message |
223
+ | `video` | `video(jid, config, options?)` | `video()` | video message |
224
+ | `audio` | `audio(jid, config, options?)` | `audio()` | audio message |
225
+ | `document` | `document(jid, config, options?)` | `document()` | document message |
226
+ | `sticker` | `sticker(jid, config, options?)` | `sticker()` | sticker message |
227
+ | `contact` | `contact(jid, config, options?)` | `contact()` | `contactMessage` |
228
+ | `poll` | `poll(jid, config, options?)` | `poll()` | ZapoJS poll input |
229
+ | `album` | `album(jid, config, options?)` | `album()` | album message followed by media messages |
230
+ | `reaction` | `reaction(config, options?)` or `reaction(jid, config, options?)` | `reaction()` | ZapoJS reaction input |
231
+ | `forward` | `forward(jid, config, options?)` | `forward()` | original message with forward options |
232
+ | `location` | `location(jid, config, options?)` | `location()` | `locationMessage` |
233
+
234
+ ### Text
235
+
236
+ **Config**
152
237
 
153
- ## Requirements
238
+ ```ts
239
+ interface TextConfig {
240
+ body: string;
241
+ }
242
+ ```
154
243
 
155
- - Node.js `>= 20.9.0` (mengikuti zapo-js)
156
- - `zapo-js >= 1.11.0 < 2.0.0` (peer dependency, wajib)
157
- - `sharp >= 0.33` (peer dependency opsional — hanya untuk pemrosesan gambar otomatis)
158
- - Proyek ESM (`"type": "module"`). Konsumen CommonJS bisa `require()` di Node >= 22.12
159
- (fitur require-esm) atau memakai factory manual `text(client)` dan kawan-kawan.
244
+ ```ts
245
+ await client.text(jid, { body: "Hello there" });
246
+ await client.text().body("Hello there").send(jid);
247
+ ```
160
248
 
161
- ## Quick Start
249
+ **Built payload**
162
250
 
163
251
  ```ts
164
- import { createStore, WaClient } from "zapo-js";
165
- import "@kyyinfinite/zapo-message";
252
+ { conversation: "Hello there" }
253
+ ```
166
254
 
167
- const client = new WaClient({ store: createStore({}), sessionId: "bot" });
255
+ ### Native flow buttons
168
256
 
169
- client.on("message", async (event) => {
170
- if (event.message?.conversation === "ping") {
171
- await client.text().body("pong").send(event.key.remoteJid);
172
- }
173
- });
257
+ Use `button()` for interactive native-flow messages.
174
258
 
175
- await client.connect();
259
+ **Config shape**
260
+
261
+ ```ts
262
+ interface ButtonConfig {
263
+ title?: string;
264
+ subtitle?: string;
265
+ body: string;
266
+ footer?: string;
267
+ header?: InteractiveHeaderConfig;
268
+ buttons?: readonly ButtonItemConfig[];
269
+ bottomSheet?: {
270
+ limit?: number;
271
+ listTitle?: string;
272
+ buttonTitle?: string;
273
+ };
274
+ limitedTimeOffer?: {
275
+ text?: string;
276
+ url?: string;
277
+ copyCode?: string;
278
+ expiresIn?: number;
279
+ };
280
+ }
281
+
282
+ type ButtonItemConfig =
283
+ | { type: "quick_reply"; text: string; id: string }
284
+ | { type: "cta_url"; text: string; url: string }
285
+ | { type: "cta_copy"; text: string; copyCode: string }
286
+ | { type: "cta_call"; text: string; phoneNumber: string }
287
+ | { type: "send_location"; text?: string }
288
+ | {
289
+ type: "single_select";
290
+ title: string;
291
+ sections: readonly NativeSection[];
292
+ };
176
293
  ```
177
294
 
178
- ### Import sekali, langsung pakai
295
+ `InteractiveHeaderConfig` supports:
296
+
297
+ - `{ type: "image", source, ...imageOptions }`
298
+ - `{ type: "video", source, ...videoOptions }`
299
+ - `{ type: "document", source, ...documentOptions }`
300
+ - `{ type: "location", latitude, longitude, name?, address?, thumbnail? }`
301
+ - `{ type: "thumbnail", jpegThumbnail }`
179
302
 
180
- Semua method builder menempel di **setiap** `WaClient` begitu paket di-import —
181
- termasuk client yang dibuat sebelum import, dan client yang dibuat belakangan.
303
+ **Object API**
182
304
 
183
305
  ```ts
184
- import "@kyyinfinite/zapo-message";
185
- import { WaClient } from "zapo-js";
306
+ await client.button(jid, {
307
+ title: "Account",
308
+ subtitle: "Manage your profile",
309
+ body: "What would you like to do?",
310
+ footer: "Example bot",
311
+ buttons: [
312
+ { type: "quick_reply", text: "My profile", id: "profile" },
313
+ { type: "cta_url", text: "Open website", url: "https://example.com" },
314
+ { type: "cta_copy", text: "Copy code", copyCode: "WELCOME" },
315
+ { type: "cta_call", text: "Call support", phoneNumber: "+628123456789" },
316
+ { type: "send_location", text: "Share location" },
317
+ {
318
+ type: "single_select",
319
+ title: "More options",
320
+ sections: [
321
+ {
322
+ title: "Account",
323
+ rows: [{ id: "settings", title: "Settings" }],
324
+ },
325
+ ],
326
+ },
327
+ ],
328
+ });
329
+ ```
186
330
 
187
- const a = new WaClient(optionsA);
188
- const b = new WaClient(optionsB);
331
+ **Fluent API**
189
332
 
190
- await a.text().body("dari client a").send(jid);
191
- await b.poll().question("Siapa menang?").options(["A", "B"]).send(jid);
333
+ ```ts
334
+ await client
335
+ .button()
336
+ .to(jid)
337
+ .title("Account")
338
+ .subtitle("Manage your profile")
339
+ .body("What would you like to do?")
340
+ .quick_reply("My profile", "profile")
341
+ .cta_url("Open website", "https://example.com")
342
+ .cta_copy("Copy code", "WELCOME")
343
+ .cta_call("Call support", "+628123456789")
344
+ .send_location("Share location")
345
+ .single_select("More options", [
346
+ { title: "Account", rows: [{ id: "settings", title: "Settings" }] },
347
+ ])
348
+ .footer("Example bot")
349
+ .send();
192
350
  ```
193
351
 
194
- Jaminan integrasi otomatis:
352
+ The fluent button builder also supports these header and layout methods:
195
353
 
196
- - Method tidak menimpa method bawaan ZapoJS (dilewati bila nama sudah ada).
197
- - Pemasangan idempoten — import ganda atau dua salinan paket tetap aman.
198
- - Method dipasang di prototype, non-enumerable, tidak mengubah perilaku internal ZapoJS.
199
- - Tanpa circular dependency antara paket dan ZapoJS.
200
- - Tipe menempel lewat declaration merging — `client.text()` ter-typed di TypeScript.
201
- - Mekanisme manual tersedia lewat `installZapoMessage(client)` untuk client buatan sendiri.
354
+ | Method | Purpose |
355
+ | --- | --- |
356
+ | `.image(source, options?)` | Image header |
357
+ | `.video(source, options?)` | Video header |
358
+ | `.document(source, options?)` | Document header |
359
+ | `.location({ latitude, longitude, name?, address?, thumbnail? })` | Location header |
360
+ | `.thumb(bytes?)` | Location thumbnail |
361
+ | `.headerThumbnail(jpegBytes)` | JPEG header thumbnail |
362
+ | `.bottom_sheet(options?)` | Native-flow bottom-sheet parameters |
363
+ | `.limited_time_offer(options?)` | Limited-time offer metadata |
202
364
 
203
- Contoh JavaScript (tanpa tipe):
365
+ `bottom_sheet()` accepts `limit`, `listTitle`, and `buttonTitle`. `limited_time_offer()` accepts `text`, `url`, `copyCode`, and `expiresIn` (seconds). A button header can contain one content type at a time; media, location, and thumbnail header methods are mutually exclusive where enforced by the builder.
204
366
 
205
- ```js
206
- const { createStore, WaClient } = require("zapo-js");
207
- require("@kyyinfinite/zapo-message");
367
+ **Built payload family**
208
368
 
209
- const client = new WaClient({ store: createStore({}), sessionId: "bot" });
210
- await client.text().body("Halo dari CJS").send(jid);
369
+ ```ts
370
+ {
371
+ interactiveMessage: {
372
+ body: { text: "..." },
373
+ nativeFlowMessage: {
374
+ buttons: [
375
+ {
376
+ name: "quick_reply",
377
+ buttonParamsJson: "{\"display_text\":\"Open\",\"id\":\"open\"}"
378
+ }
379
+ ],
380
+ messageVersion: 1
381
+ },
382
+ footer: { text: "..." }
383
+ }
384
+ }
211
385
  ```
212
386
 
213
- ## Text message
387
+ Each native-flow button is encoded into `buttonParamsJson`. The package owns this encoding; pass the documented config rather than constructing the JSON string yourself.
214
388
 
215
- ```ts
216
- // async
217
- await client.text(jid, { body: "Halo Dunia" });
389
+ ### Legacy buttons
218
390
 
219
- // chain
220
- await client.text().body("Halo Dunia").send(jid);
391
+ Use `legacyButton()` when you specifically need the older `buttonsMessage` payload format.
221
392
 
222
- // balasan (quote) lewat opsi send
223
- await client.text(jid, { body: "balasan" }, { quote: incomingEvent });
224
- await client.text().body("balasan").send(jid, { quote: incomingEvent });
393
+ **Config**
225
394
 
226
- // tujuan default bila sering dipakai
227
- await client.text().body("hai").to(jid).send();
228
- await client.text().body("hai").defaultTo(jid).send();
395
+ ```ts
396
+ interface LegacyButtonConfig {
397
+ title?: string;
398
+ body: string;
399
+ footer?: string;
400
+ header?: LegacyButtonHeaderConfig;
401
+ buttons: readonly { id: string; text: string }[];
402
+ }
229
403
  ```
230
404
 
231
- Payload yang dikirim: `{ conversation: "..." }` — persis normalisasi string
232
- `client.message.send(jid, "Halo")` di zapo-js.
405
+ ```ts
406
+ await client.legacyButton(jid, {
407
+ title: "Quick menu",
408
+ body: "Choose one",
409
+ footer: "Example bot",
410
+ buttons: [
411
+ { id: "help", text: "Help" },
412
+ { id: "about", text: "About" },
413
+ ],
414
+ });
233
415
 
234
- ## Interactive message
416
+ await client
417
+ .legacyButton()
418
+ .to(jid)
419
+ .body("Choose one")
420
+ .button("help", "Help")
421
+ .button("about", "About")
422
+ .send();
423
+ ```
235
424
 
236
- ### Native flow buttons
425
+ **Built payload family**
237
426
 
238
427
  ```ts
239
- await client
240
- .button()
241
- .body("Silakan pilih")
242
- .title("Menu")
243
- .quick_reply("Lihat produk", "cmd produk")
244
- .cta_url("Buka web", "https://example.com")
245
- .cta_copy("Salin kode", "PROMO2026")
246
- .cta_call("Telepon CS", "+628123456789")
247
- .footer("ketuk salah satu")
248
- .send(jid);
249
-
250
- // header media / lokasi
251
- await client.button().body("Pilih").image(pngBuffer).quick_reply("OK", "ok").send(jid);
252
- await client.button().body("Pilih").location({ latitude: -6.2, longitude: 106.8 }).send(jid);
428
+ {
429
+ buttonsMessage: {
430
+ contentText: "Choose one",
431
+ buttons: [
432
+ {
433
+ buttonId: "help",
434
+ buttonText: { displayText: "Help" },
435
+ type: "RESPONSE"
436
+ }
437
+ ],
438
+ headerType: "...",
439
+ footerText: "Example bot"
440
+ }
441
+ }
253
442
  ```
254
443
 
255
- ### Tombol legacy
444
+ The implementation allows up to three legacy buttons and validates button IDs. Keep IDs unique and within the limits enforced by the library.
445
+
446
+ ### List messages
447
+
448
+ **Config**
256
449
 
257
450
  ```ts
258
- await client
259
- .legacyButton()
260
- .body("Halo")
261
- .button("b1", "Satu")
262
- .button("b2", "Dua")
263
- .send(jid);
451
+ interface ListRowInput {
452
+ id: string;
453
+ title: string;
454
+ description?: string;
455
+ header?: string;
456
+ }
457
+
458
+ interface ListMessageConfig {
459
+ title?: string;
460
+ body: string;
461
+ footer?: string;
462
+ buttonText: string;
463
+ sections: readonly {
464
+ title?: string;
465
+ rows: readonly ListRowInput[];
466
+ }[];
467
+ fallback?: "auto" | "native" | "never";
468
+ inGroup?: boolean;
469
+ }
264
470
  ```
265
471
 
266
- ### List message
472
+ ```ts
473
+ await client.listMessage(jid, {
474
+ title: "Main menu",
475
+ body: "Choose a category",
476
+ footer: "Example bot",
477
+ buttonText: "Browse",
478
+ sections: [
479
+ {
480
+ title: "General",
481
+ rows: [
482
+ { id: "profile", title: "Profile", description: "Your account" },
483
+ { id: "settings", title: "Settings" },
484
+ ],
485
+ },
486
+ ],
487
+ });
488
+ ```
267
489
 
268
490
  ```ts
269
491
  await client
270
492
  .listMessage()
271
- .title("Menu utama")
272
- .body("Pilih salah satu")
273
- .buttonText("Buka")
274
- .section("Utama", [
275
- { id: "produk", title: "Produk", description: "Lihat semua produk" },
276
- { id: "layanan", title: "Layanan" },
493
+ .to(jid)
494
+ .title("Main menu")
495
+ .body("Choose a category")
496
+ .buttonText("Browse")
497
+ .section("General", [
498
+ { id: "profile", title: "Profile", description: "Your account" },
499
+ { id: "settings", title: "Settings" },
277
500
  ])
278
- .send(jid);
501
+ .send();
279
502
  ```
280
503
 
281
- Di chat grup, list otomatis dikirim sebagai native flow (`single_select`) agar tetap
282
- tampil — perilaku yang sama persis dengan versi lama.
504
+ **Built payload family**
505
+
506
+ ```ts
507
+ {
508
+ listMessage: {
509
+ title: "Main menu",
510
+ description: "Choose a category",
511
+ buttonText: "Browse",
512
+ listType: "...",
513
+ sections: [{ title: "General", rows: [{ rowId: "profile", title: "Profile" }] }],
514
+ footerText: "Example bot"
515
+ }
516
+ }
517
+ ```
518
+
519
+ The builder supports `fallback("auto" | "native" | "never")` and `inGroup(boolean)`. In automatic mode, the implementation can convert a list to a native-flow `single_select` for group delivery. Choose `native` to force that path or `never` to disable the fallback.
283
520
 
284
521
  ### AIRich
285
522
 
523
+ AIRich builds rich-response messages from typed sections. The builder also supports node operations and a two-step placeholder/edit send flow.
524
+
525
+ **Config section types**
526
+
527
+ | `type` | Required fields | Optional fields |
528
+ | --- | --- | --- |
529
+ | `text` | `text` | `hyperlink`, `citation`, `latex`, `id` |
530
+ | `code` | `language`, `code` | `id` |
531
+ | `table` | `rows: string[][]` | `hyperlink`, `citation`, `latex`, `id` |
532
+ | `metadata` | `text` | `id` |
533
+ | `tip` | `text` | `id` |
534
+ | `suggest` | `items: string \| readonly string[]` | `scroll`, `layout`, `id` |
535
+ | `source` | `sources` | `layout`, `id` |
536
+ | `image` | `url` | `width`, `height`, `status`, `updateText`, `id` |
537
+ | `video` | `url` | `mimeType`, `fileLength`, `duration`, `status`, `id` |
538
+ | `footerAction` | `items` | `layout`, `id` |
539
+ | `widget` | `items` | `layout`, `id` |
540
+ | `product` | `items` | `layout`, `id` |
541
+ | `post` | `items` | `layout`, `id` |
542
+ | `reels` | `items` | `layout`, `id` |
543
+ | `html` | `html` | `trustedSources`, `id` |
544
+ | `raw` | `section` | `submessage`, `id` |
545
+
546
+ **Config API**
547
+
548
+ ```ts
549
+ await client.airich(jid, {
550
+ sections: [
551
+ { type: "text", text: "Order summary" },
552
+ { type: "code", language: "javascript", code: "const total = 25000" },
553
+ {
554
+ type: "table",
555
+ rows: [
556
+ ["Item", "Qty"],
557
+ ["Coffee", "2"],
558
+ ],
559
+ },
560
+ { type: "tip", text: "Your order is ready to review." },
561
+ { type: "suggest", items: ["Track order", "Contact support"] },
562
+ ],
563
+ footer: "Example bot",
564
+ });
565
+ ```
566
+
567
+ **Fluent API**
568
+
286
569
  ```ts
287
570
  await client
288
571
  .airich()
289
- .text("Ringkasan pesanan:")
290
- .table([["Item", "Qty"], ["Kopi", "2"]])
291
- .code("javascript", "const x = 1")
292
- .suggest(["ulangi pesanan", "lihat menu"])
572
+ .text("Order summary")
573
+ .code("javascript", "const total = 25000")
574
+ .table([
575
+ ["Item", "Qty"],
576
+ ["Coffee", "2"],
577
+ ])
578
+ .tip("Your order is ready to review.")
579
+ .suggest(["Track order", "Contact support"])
580
+ .footer("Example bot")
293
581
  .send(jid);
294
582
  ```
295
583
 
296
- ## Media
584
+ Additional fluent methods include `metadata`, `source`, `image`, `video`, `footerAction`, `widget`, `product`, `post`, `reels`, `html`, `raw`, `replace`, `insert`, `insertAt`, `remove`, `clear`, `context`, and `quote`. Node IDs can be supplied through the supported method options and used by node operations.
585
+
586
+ `AIRichSendOptions` extends `MessageSendOptions` with:
587
+
588
+ | Option | Type | Description |
589
+ | --- | --- | --- |
590
+ | `twoStep` | `boolean` | Controls placeholder-then-edit sending |
591
+ | `submessages` | `boolean` | Controls submessage generation |
592
+
593
+ The builder exposes `build()`, `buildPlaceholder()`, `buildEdit()`, `edit(jid, id?)`, `ids()`, `has()`, `pendingEdit(jid)`, `size`, and `lastId` for advanced workflows. `airich({ botJid })` accepts the optional bot JID used in AIRich forwarding context. Two-step sending is enabled by default; set `twoStep: false` to send the complete rich response directly. See the exported TypeScript declarations for the full node and primitive item shapes.
594
+
595
+ **Payload family**
596
+
597
+ ```ts
598
+ {
599
+ botForwardedMessage: {
600
+ message: {
601
+ richResponseMessage: {
602
+ messageType: "...",
603
+ submessages: <rich-response submessages>,
604
+ unifiedResponse: { data: new Uint8Array() },
605
+ contextInfo: {}
606
+ }
607
+ }
608
+ }
609
+ }
610
+ ```
611
+
612
+ AIRich's unified response is encoded by the library. Use `decodeUnifiedResponse()` when you need to inspect encoded unified-response data.
613
+
614
+ #### AIRich primitive inputs
615
+
616
+ The richer primitive builders accept these input shapes:
617
+
618
+ | Method | Input fields |
619
+ | --- | --- |
620
+ | `source()` | A URL string, `[icon, url, title?, subtitle?]`, or `{ favicon?, icon?, url?, title?, subtitle? }` |
621
+ | `image()` | URL plus `{ width?, height?, status?, updateText? }` |
622
+ | `video()` | URL plus `{ mimeType?, fileLength?, duration?, status? }` |
623
+ | `footerAction()` | One or more `{ text?, cta_text?, type?, cta_type?, url?, cta_url? }` objects |
624
+ | `widget()` | `{ title?, header?, sections?, actions?, body? }`; actions accept `{ label?, state?, kind?, tool_call_id?, id?, toast? }` |
625
+ | `product()` | `{ title?, brand?, price?, sale_price?, product_url?, url?, image_url?, image?, icon_url?, icon? }` |
626
+ | `post()` | `{ title?, subtitle?, username?, profile_picture_url?, profile_url?, profile?, is_verified?, verified?, thumbnail_url?, thumbnail?, post_caption?, caption?, likes_count?, like?, comments_count?, comment?, shares_count?, share?, post_url?, url?, post_deeplink?, deeplink?, source_app?, source?, footer_label?, footer?, footer_icon?, icon?, orientation?, post_type? }` |
627
+ | `reels()` | `{ videoUrl?, url?, thumbnailUrl?, thumbnail?, username?, profileIconUrl?, profile?, reels_title?, title?, likes_count?, like?, shares_count?, share?, view_count?, view?, reel_source?, source?, is_verified?, verified? }` |
628
+ | `html()` | HTML string plus `{ trustedSources? }` in the config API |
629
+
630
+ For array-based primitives, the default layout is generally `HScroll`; a single item defaults to `Single`. `source()` defaults to `Single`. You can override the layout using the relevant `layout` option. These rich primitives are marked experimental by the package; their rendering depends on WhatsApp's support for the corresponding protocol primitive.
631
+
632
+ `AIRichConfig.context` is filtered to the supported context fields: `mentionedJid`, `groupMentions`, `statusAttributions`, `expiration`, `ephemeralSettingTimestamp`, and `disappearingMode`. Builder-controlled quote and forwarding fields cannot be overwritten through `context()`.
633
+
634
+ ### Link previews
635
+
636
+ **Config**
637
+
638
+ ```ts
639
+ interface LinkPreviewConfig {
640
+ body: string;
641
+ url?: string;
642
+ title?: string;
643
+ description?: string;
644
+ thumbnail?: Uint8Array;
645
+ kind?: "image" | "video";
646
+ }
647
+ ```
297
648
 
298
649
  ```ts
299
- // image (Buffer, Uint8Array, path file, atau Readable)
300
- await client.media().image(pngBuffer, { caption: "Foto liburan" }).send(jid);
650
+ await client.linkPreview(jid, {
651
+ body: "Read the guide at https://example.com/docs",
652
+ title: "Documentation",
653
+ description: "Getting started guide",
654
+ kind: "image",
655
+ });
656
+ ```
301
657
 
302
- // video
303
- await client.media().video(mp4Path, { seconds: 30, mimetype: "video/mp4" }).send(jid);
658
+ The selected URL must appear in `body`. If `url` is omitted, the builder uses the first HTTP(S) URL it finds in the text.
304
659
 
305
- // dokumen
306
- await client.media().document(pdfBuffer, { fileName: "laporan.pdf" }).send(jid);
660
+ **Built payload**
307
661
 
308
- // audio / voice note
309
- await client.media().audio(oggBuffer, { ptt: true, mimetype: "audio/ogg; codecs=opus" }).send(jid);
662
+ ```ts
663
+ {
664
+ extendedTextMessage: {
665
+ text: "Read the guide at https://example.com/docs",
666
+ matchedText: "https://example.com/docs",
667
+ previewType: "...",
668
+ title: "Documentation",
669
+ description: "Getting started guide",
670
+ jpegThumbnail: new Uint8Array()
671
+ }
672
+ }
310
673
  ```
311
674
 
312
- Mimetype terdeteksi otomatis dari isi file (file-type); thumbnail image dibuat otomatis
313
- bila `sharp` terpasang. Upload lewat `client.message.upload` dengan media gate
314
- (admission control) bersama, sama seperti pipeline media header tombol.
675
+ ### Media
676
+
677
+ `media()` accepts one media item. Use `album()` when you need multiple images and/or videos in one album sequence.
678
+
679
+ **Supported sources**
680
+
681
+ - `Buffer`
682
+ - `Uint8Array`
683
+ - A local file path
684
+ - A Node.js `Readable` stream
315
685
 
316
- ## Sticker
686
+ **Config types**
317
687
 
318
688
  ```ts
319
- await client.sticker().source(webpBuffer).send(jid);
689
+ import type { Readable } from "node:stream";
320
690
 
321
- // opsi manual
322
- await client
323
- .sticker()
324
- .source(webpPath, { isAnimated: false, pngThumbnail: pngBytes })
325
- .send(jid);
691
+ type MediaConfig =
692
+ | { type: "image"; source: Buffer | Uint8Array | string | Readable; mimetype?: string; width?: number; height?: number; caption?: string; thumbnail?: Buffer | Uint8Array | false }
693
+ | { type: "video"; source: Buffer | Uint8Array | string | Readable; mimetype?: string; seconds?: number; width?: number; height?: number; thumbnail?: Buffer | Uint8Array | false }
694
+ | { type: "audio"; source: Buffer | Uint8Array | string | Readable; mimetype?: string; seconds?: number; ptt?: boolean; waveform?: Uint8Array }
695
+ | { type: "document"; source: Buffer | Uint8Array | string | Readable; mimetype?: string; fileName?: string; title?: string; thumbnail?: Buffer | Uint8Array | false };
696
+ ```
697
+
698
+ **Object API**
699
+
700
+ ```ts
701
+ await client.media(jid, {
702
+ type: "image",
703
+ source: "./assets/photo.jpg",
704
+ caption: "A photo",
705
+ });
706
+
707
+ await client.media(jid, {
708
+ type: "document",
709
+ source: pdfBuffer,
710
+ fileName: "report.pdf",
711
+ mimetype: "application/pdf",
712
+ });
713
+ ```
714
+
715
+ **Fluent API**
716
+
717
+ ```ts
718
+ await client.media().image(photoBuffer, { caption: "A photo" }).send(jid);
719
+ await client.media().video(videoPath, { seconds: 18 }).send(jid);
720
+ await client.media().audio(audioBuffer, { ptt: true }).send(jid);
721
+ await client.media().document(pdfBuffer, { fileName: "report.pdf" }).send(jid);
326
722
  ```
327
723
 
328
- Sumber harus file WebP. Dimensi dan status animasi dibaca langsung dari header
329
- container WebP (VP8X/VP8/VP8L + chunk ANIM) tanpa dependensi tambahan.
724
+ Convenience methods share the same media engine:
330
725
 
331
- ## Poll
726
+ ```ts
727
+ await client.image(jid, { source: photoBuffer, caption: "A photo" });
728
+ await client.video(jid, { source: videoPath, seconds: 18 });
729
+ await client.audio(jid, { source: audioBuffer, ptt: true });
730
+ await client.document(jid, { source: pdfBuffer, fileName: "report.pdf" });
731
+ ```
732
+
733
+ **Built payload families**
734
+
735
+ The media resolver creates one of these message fields after resolving and uploading the source:
332
736
 
333
737
  ```ts
334
- // satu pilihan (pollCreationMessageV3)
335
- await client.poll().question("Makan apa?").options(["Nasi goreng", "Mie ayam"]).send(jid);
738
+ imageMessage: <uploaded image metadata>
739
+ videoMessage: <uploaded video metadata>
740
+ audioMessage: <uploaded audio metadata>
741
+ documentMessage: <uploaded document metadata>
742
+ ```
743
+
744
+ The actual media payload includes upload metadata returned by ZapoJS. Do not construct these fields manually. MIME detection is attempted from the source; provide `mimetype` when detection is not possible.
745
+
746
+ ### Stickers
747
+
748
+ Sticker sources must contain WebP data.
749
+
750
+ **Config**
751
+
752
+ ```ts
753
+ interface StickerConfig {
754
+ source: Buffer | Uint8Array | string | Readable;
755
+ mimetype?: string;
756
+ isAnimated?: boolean;
757
+ pngThumbnail?: Uint8Array | false;
758
+ width?: number;
759
+ height?: number;
760
+ stickerSentTs?: number;
761
+ }
762
+ ```
763
+
764
+ ```ts
765
+ await client.sticker(jid, { source: "./assets/sticker.webp" });
766
+ await client.sticker().source(stickerBuffer).send(jid);
767
+ ```
768
+
769
+ **Built payload family**
770
+
771
+ ```ts
772
+ stickerMessage: <uploaded WebP metadata>
773
+ ```
774
+
775
+ The library inspects WebP container data to determine image dimensions and animation metadata. It does not convert arbitrary image formats into WebP for you.
776
+
777
+ ### Polls
778
+
779
+ **Config**
780
+
781
+ ```ts
782
+ interface PollConfig {
783
+ question: string;
784
+ options: readonly string[];
785
+ selectableCount?: number;
786
+ allowAddOption?: boolean;
787
+ hideParticipantName?: boolean;
788
+ }
789
+ ```
790
+
791
+ ```ts
792
+ await client.poll(jid, {
793
+ question: "Which option do you prefer?",
794
+ options: ["Option A", "Option B", "Option C"],
795
+ selectableCount: 1,
796
+ });
336
797
 
337
- // multi-pilih + boleh tambah opsi (pollCreationMessageV6)
338
798
  await client
339
799
  .poll()
340
- .question("Pilih dua")
800
+ .question("Choose two")
341
801
  .options(["A", "B", "C"])
342
802
  .selectableCount(2)
343
803
  .allowAddOption()
804
+ .hideParticipantName()
344
805
  .send(jid);
345
806
  ```
346
807
 
347
- Builder mengirim input terketik `{ type: "poll", ... }` dan zapo-js yang memilih varian
348
- protokol (V3/V6/klasik) sesuai aturan versi terpasang.
808
+ **Input passed to ZapoJS**
809
+
810
+ ```ts
811
+ {
812
+ type: "poll",
813
+ name: "Which option do you prefer?",
814
+ options: ["Option A", "Option B", "Option C"],
815
+ selectableCount: 1,
816
+ }
817
+ ```
818
+
819
+ ZapoJS is responsible for selecting the appropriate poll protocol variant. The library validates that the question is non-empty, that there are 1–12 options, and that `selectableCount` does not exceed the number of options.
820
+
821
+ ### Contacts
349
822
 
350
- ## Contact
823
+ **Config**
351
824
 
352
825
  ```ts
353
- await client.contact().name("Budi").phone("+628123456789").send(jid);
826
+ interface ContactConfig {
827
+ name?: string;
828
+ phone?: string;
829
+ organization?: string;
830
+ email?: string;
831
+ url?: string;
832
+ note?: string;
833
+ vcard?: string;
834
+ }
835
+ ```
836
+
837
+ Provide either a `vcard` or a `name` with the contact details you want to include.
838
+
839
+ ```ts
840
+ await client.contact(jid, {
841
+ name: "Taylor Smith",
842
+ phone: "+628123456789",
843
+ organization: "Example Studio",
844
+ email: "taylor@example.com",
845
+ url: "https://example.com",
846
+ note: "Project contact",
847
+ });
354
848
 
355
- // detail lengkap
356
849
  await client
357
850
  .contact()
358
- .name("Rani")
359
- .phone("+6281298765432")
360
- .organization("PT Contoh")
361
- .email("rina@contoh.id")
362
- .url("https://contoh.id")
363
- .note("Klien sejak 2024")
851
+ .name("Taylor Smith")
852
+ .phone("+628123456789")
853
+ .organization("Example Studio")
854
+ .email("taylor@example.com")
364
855
  .send(jid);
856
+ ```
857
+
858
+ A raw vCard can also be supplied:
365
859
 
366
- // vcard mentah
367
- await client.contact().vcard("BEGIN:VCARD\nVERSION:3.0\nFN:Siti\nEND:VCARD").send(jid);
860
+ ```ts
861
+ await client.contact().vcard(
862
+ "BEGIN:VCARD\nVERSION:3.0\nFN:Taylor Smith\nEND:VCARD",
863
+ ).send(jid);
368
864
  ```
369
865
 
370
- ## Location
866
+ **Built payload**
867
+
868
+ ```ts
869
+ {
870
+ contactMessage: {
871
+ displayName: "Taylor Smith",
872
+ vcard: "BEGIN:VCARD\\nVERSION:3.0\\n..."
873
+ }
874
+ }
875
+ ```
876
+
877
+ ### Locations
878
+
879
+ **Config**
880
+
881
+ ```ts
882
+ interface LocationConfig {
883
+ latitude: number;
884
+ longitude: number;
885
+ name?: string;
886
+ address?: string;
887
+ thumbnail?: Buffer | Uint8Array;
888
+ }
889
+ ```
371
890
 
372
891
  ```ts
373
- // async
374
892
  await client.location(jid, {
375
893
  latitude: -6.2,
376
894
  longitude: 106.8,
@@ -378,7 +896,6 @@ await client.location(jid, {
378
896
  address: "Indonesia",
379
897
  });
380
898
 
381
- // chain
382
899
  await client
383
900
  .location()
384
901
  .to(jid)
@@ -388,146 +905,498 @@ await client
388
905
  .send();
389
906
  ```
390
907
 
391
- Standalone location memakai payload `locationMessage` proto yang sama dengan
392
- header location interaktif (`degreesLatitude`, `degreesLongitude`, `name`,
393
- `address`, `jpegThumbnail`) — dikirim lewat jalur raw proto `client.message.send`.
394
- Ini berbeda dari tombol `send_location` (meminta lokasi lawan bicara) dan dari
395
- header location pada button.
908
+ **Built payload**
909
+
910
+ ```ts
911
+ {
912
+ locationMessage: {
913
+ degreesLatitude: -6.2,
914
+ degreesLongitude: 106.8,
915
+ name: "Jakarta",
916
+ address: "Indonesia"
917
+ }
918
+ }
919
+ ```
920
+
921
+ Latitude must be between `-90` and `90`; longitude must be between `-180` and `180`. This standalone location message is different from a location header on a button and from the `send_location` button, which requests the recipient's location.
922
+
923
+ ### Reactions
924
+
925
+ A reaction needs a message reference with a message ID. The chat JID is read from the reference when available.
926
+
927
+ ```ts
928
+ await client.reaction({ target: incomingEvent, emoji: "🔥" });
929
+
930
+ await client
931
+ .reaction()
932
+ .target(incomingEvent)
933
+ .emoji("🔥")
934
+ .send();
935
+ ```
936
+
937
+ Pass an empty string to remove your reaction:
396
938
 
397
- ## Reaction, forward, link preview, album
939
+ ```ts
940
+ await client.reaction({ target: incomingEvent, emoji: "" });
941
+ ```
942
+
943
+ **Input passed to ZapoJS**
398
944
 
399
945
  ```ts
400
- // reaksi ke pesan masuk (jid otomatis dari target)
401
- await client.reaction().target(incomingEvent).emoji("🔥").send();
402
- await client.reaction().target(incomingEvent).emoji("").send(); // hapus reaksi
946
+ {
947
+ type: "reaction",
948
+ target: incomingEvent,
949
+ emoji: "🔥"
950
+ }
951
+ ```
952
+
953
+ If the target does not contain `key.id` (or a supported direct `id`) the builder rejects it.
954
+
955
+ ### Forwarding messages
956
+
957
+ The source must be an incoming event or an object with a `message` field containing a protocol message.
403
958
 
404
- // forward pesan (skor diteruskan bila sumber pernah di-forward)
405
- await client.forward().message(incomingEvent).send(jidLain);
959
+ ```ts
960
+ await client.forward(jid, { message: incomingEvent });
406
961
 
407
- // link preview eksplisit (tanpa fetch)
408
962
  await client
409
- .linkPreview()
410
- .body("Baca https://example.com/docs ya")
411
- .title("Dokumentasi")
412
- .description("Semua yang perlu diketahui")
413
- .kind("image")
963
+ .forward()
964
+ .message(incomingEvent)
414
965
  .send(jid);
415
-
416
- // album: pesan album + tiap media mengutip id album
417
- await client.album().image(pngA).image(pngB).video(mp4C).send(jid);
418
966
  ```
419
967
 
420
- Catatan album: `albumMessage` dan mekanisme kutipan yang dipakai semuanya field
421
- protobuf terverifikasi, tetapi alur multi-pesan ini disusun oleh zapo-message
422
- (zapo-js belum punya API album bawaan) — lihat `docs/PROTOCOL_TRACEABILITY.md`.
968
+ The builder forwards the original message and carries forward the source forwarding score when it can read it. Otherwise it uses the default forward option. You can override the `forward` send option if your transport supports it.
423
969
 
424
- ## Serializer
970
+ ### Albums
971
+
972
+ Albums support images and videos.
425
973
 
426
974
  ```ts
427
- import { mSerialize, qSerialize, extractText } from "@kyyinfinite/zapo-message/serialize.js";
975
+ await client.album(jid, {
976
+ media: [
977
+ { type: "image", source: firstPhoto },
978
+ { type: "image", source: secondPhoto },
979
+ { type: "video", source: shortVideo },
980
+ ],
981
+ });
428
982
 
429
- const content = mSerialize(incomingEvent, client);
430
- const quoted = qSerialize(incomingEvent, { message: content }, client);
983
+ await client
984
+ .album()
985
+ .image(firstPhoto)
986
+ .image(secondPhoto)
987
+ .video(shortVideo)
988
+ .send(jid);
431
989
  ```
432
990
 
433
- `mSerialize` menyalin konten pesan masuk menjadi konten siap kirim,
434
- `qSerialize` membungkusnya sebagai pesan terkutip (termasuk branding opsional lewat
435
- `setReplyBranding`), dan `extractText` mengambil teks polos dari pesan apa pun.
991
+ **Album payload sequence**
992
+
993
+ 1. The library sends an `albumMessage` containing the expected image and video counts.
994
+ 2. It reads the returned album message ID.
995
+ 3. It sends each resolved media item as a separate message, quoting the album message ID.
996
+
997
+ The album operation therefore consists of multiple sends. If the initial album send does not return a message ID, the operation fails with a `PROTOCOL_SEND` error at the `album_id` stage.
998
+
999
+ ### Fluent builder methods
1000
+
1001
+ The following methods are implemented by the respective builders. Optional arguments are omitted here only where the method accepts a default.
436
1002
 
437
- ## Advanced usage
1003
+ | Builder | Fluent methods |
1004
+ | --- | --- |
1005
+ | `TextBuilder` | `body(text)` |
1006
+ | `Button` | `title(text)`, `subtitle(text)`, `body(text)`, `footer(text)`, `quick_reply(text, id)`, `cta_url(text, url)`, `cta_copy(text, code)`, `cta_call(text, phone)`, `send_location(text?)`, `single_select(title, sections)`, `image(source, options?)`, `video(source, options?)`, `document(source, options?)`, `location(options)`, `thumb(bytes?)`, `headerThumbnail(bytes)`, `bottom_sheet(options?)`, `limited_time_offer(options?)` |
1007
+ | `LegacyButton` | `title(text)`, `body(text)`, `footer(text)`, `button(id, text)`, `image(source, options?)`, `video(source, options?)`, `document(source, options?)`, `location(options)`, `thumb(bytes?)` |
1008
+ | `ListMessage` | `title(text)`, `body(text)`, `footer(text)`, `buttonText(text)`, `section(title, rows)`, `fallback(mode)`, `inGroup(flag)` |
1009
+ | `AIRich` | `text(text, options?)`, `code(language, code, options?)`, `table(rows, options?)`, `metadata(text, options?)`, `tip(text, options?)`, `suggest(items, options?)`, `source(sources, options?)`, `image(url, options?)`, `video(url, options?)`, `footerAction(items, options?)`, `widget(items, options?)`, `product(items, options?)`, `post(items, options?)`, `reels(items, options?)`, `html(html, options?)`, `raw(section, submessage?, options?)`, `replace(target, section, submessage?, options?)`, `insert(target, section, submessage?, options?)`, `insertAt(index, section, submessage?, options?)`, `remove(target)`, `clear()`, `loadPayload(payload)`, `context(info)`, `quote(message)`, `footer(text)` |
1010
+ | `LinkPreviewBuilder` | `body(text)`, `url(url)`, `title(text)`, `description(text)`, `thumbnail(bytes)`, `kind("image" | "video")` |
1011
+ | `MediaBuilder` | `image(source, options?)`, `video(source, options?)`, `audio(source, options?)`, `document(source, options?)`, `caption(text)`, `kind()`, `slot()` |
1012
+ | `StickerBuilder` | `source(source, options?)`, `slot()` |
1013
+ | `PollBuilder` | `question(text)`, `options(values)`, `selectableCount(count)`, `allowAddOption(flag?)`, `hideParticipantName(flag?)` |
1014
+ | `ContactBuilder` | `name(name)`, `vcard(value)`, `phone(phone)`, `organization(name)`, `email(email)`, `url(url)`, `note(note)` |
1015
+ | `LocationBuilder` | `coordinates(latitude, longitude)`, `name(name)`, `address(address)`, `thumbnail(bytes)` |
1016
+ | `ReactionBuilder` | `target(message)`, `emoji(emoji)` |
1017
+ | `ForwardBuilder` | `message(source)` |
1018
+ | `AlbumBuilder` | `image(source, options?)`, `video(source, options?)`, `count()` |
438
1019
 
439
- ### Factory manual & messageKit (kompatibilitas lama)
1020
+ Every builder inherits `use(client)`, `to(jid)`, `defaultTo(jid)`, `defaultQuote(reference)`, `build()`, and `send(jid?, options?)` from `BaseBuilder`, except where a specialized builder overrides the send or build lifecycle. `build()` may be asynchronous for builders that resolve media or protocol data.
1021
+
1022
+ ## 🧰 Additional utilities
1023
+
1024
+ ### Standalone factories
1025
+
1026
+ The root package exports factories for use without `WaClient` prototype methods:
440
1027
 
441
1028
  ```ts
442
- import { button, legacyButton, listMessage, airich, messageKit } from "@kyyinfinite/zapo-message";
1029
+ import {
1030
+ text,
1031
+ button,
1032
+ legacyButton,
1033
+ listMessage,
1034
+ airich,
1035
+ messageKit,
1036
+ } from "@kyyinfinite/zapo-message";
1037
+
1038
+ const textBuilder = text(client).body("Hello");
1039
+ await textBuilder.send(jid);
443
1040
 
444
- const b = button(client).body("Halo").quick_reply("OK", "ok");
445
- await b.send(jid);
1041
+ await button(client).body("Choose").quick_reply("OK", "ok").send(jid);
446
1042
 
447
1043
  const kit = messageKit(client);
448
- await kit.button().body("dari kit").send(jid);
1044
+ await kit.button().body("From the kit").send(jid);
449
1045
  ```
450
1046
 
451
- API lama (`button(client)`, `messageKit(client)`, dst.) tetap bekerja persis seperti
452
- sebelumnya — lihat `docs/API_COMPATIBILITY.md`.
1047
+ `messageKit(client)` exposes `button`, `legacyButton`, `listMessage`, and `airich` factories. Other message factories are imported directly from the package root.
453
1048
 
454
- ### Instalasi manual untuk client non-ZapoJS
1049
+ ### Manual installation
1050
+
1051
+ For a compatible custom client that implements `client.message.send`, install the methods on that client instance:
455
1052
 
456
1053
  ```ts
457
1054
  import { installZapoMessage } from "@kyyinfinite/zapo-message";
458
1055
 
459
- installZapoMessage(myDuckTypedClient); // butuh client.message.send
460
- await myDuckTypedClient.text().body("halo").send(jid);
1056
+ installZapoMessage(customClient);
1057
+ await customClient.text().body("Hello").send(jid);
461
1058
  ```
462
1059
 
463
- ### Kontrol media gate
1060
+ `installZapoMessage()` checks for a callable `message.send` method and returns the client. This does not make an arbitrary transport fully ZapoJS-compatible; message content and options still need to be supported by the transport.
1061
+
1062
+ ### Serialization and interactive replies
464
1063
 
465
1064
  ```ts
466
- import { configureSharedMediaQueue, resetSharedMediaQueue } from "@kyyinfinite/zapo-message/media-gate.js";
1065
+ import {
1066
+ mSerialize,
1067
+ qSerialize,
1068
+ extractText,
1069
+ } from "@kyyinfinite/zapo-message/serialize.js";
1070
+ import { extractInteractiveResponse } from "@kyyinfinite/zapo-message/interactive.js";
1071
+
1072
+ const message = mSerialize(incomingEvent, client);
1073
+ console.log(message.text);
1074
+ console.log(message.interactive?.id);
1075
+
1076
+ await message.reply("Thanks for your message");
1077
+ await message.react("👍");
1078
+
1079
+ const quoted = message.q;
1080
+ if (quoted) {
1081
+ console.log(quoted.text);
1082
+ await quoted.reply("Replying to the quoted message");
1083
+ }
1084
+
1085
+ const selected = extractInteractiveResponse(incomingEvent.message);
1086
+ console.log(selected?.id, selected?.displayText, selected?.flowName);
1087
+ ```
1088
+
1089
+ `mSerialize()` returns a message wrapper with `content`, `text`, `interactive`, `q`, `reply()`, `react()`, and `download()`. The `q` property is available when the message contains a quoted message. `qSerialize()` serializes the quoted wrapper from an `MSerialized` value.
1090
+
1091
+ `extractInteractiveResponse()` recognizes button, list, template-button, and supported native-flow responses. Its result includes the selected `id`, optional display text, flow name, response content type, and context info.
1092
+
1093
+ ### Media downloads
1094
+
1095
+ ```ts
1096
+ const message = mSerialize(incomingEvent, client);
1097
+ const bytes = await message.download("buffer");
1098
+ const stream = await message.download("stream");
1099
+ ```
1100
+
1101
+ The serialized message wrapper exposes `download("buffer")` and `download("stream")`. A quoted wrapper (`message.q`) exposes `download("bytes")` and `download("stream")`. The client must expose the media download capabilities required by the selected operation (`message.download` and/or `message.downloadBytes`).
1102
+
1103
+ ### Shared media queue
1104
+
1105
+ Media resolution and upload use a shared admission-controlled queue.
1106
+
1107
+ ```ts
1108
+ import {
1109
+ configureSharedMediaQueue,
1110
+ getSharedMediaQueue,
1111
+ resetSharedMediaQueue,
1112
+ } from "@kyyinfinite/zapo-message/media-gate.js";
1113
+
1114
+ configureSharedMediaQueue({
1115
+ concurrency: 4,
1116
+ capacity: 50,
1117
+ timeoutMs: 30_000,
1118
+ maxBytes: 100 * 1024 * 1024,
1119
+ });
1120
+
1121
+ const queue = getSharedMediaQueue();
1122
+ console.log(queue.snapshot());
467
1123
 
468
- configureSharedMediaQueue({ concurrency: 4, maxBytes: 100 * 1024 * 1024 });
469
1124
  resetSharedMediaQueue();
470
1125
  ```
471
1126
 
472
- ### Download media
1127
+ The queue options include `concurrency`, `capacity`, `timeoutMs`, `maxBytes`, and an optional concurrency `controller`. Use `configureSharedMediaQueue()` when you need to adjust shared media processing limits. `resetSharedMediaQueue()` clears the shared instance so it is recreated with defaults on the next access.
1128
+
1129
+ ### Reply branding
1130
+
1131
+ ```ts
1132
+ import {
1133
+ setReplyBranding,
1134
+ resetReplyBranding,
1135
+ } from "@kyyinfinite/zapo-message/branding.js";
1136
+
1137
+ setReplyBranding((text, options) => ({
1138
+ ...options,
1139
+ additionalAttributes: { source: "my-bot" },
1140
+ }));
1141
+
1142
+ resetReplyBranding();
1143
+ ```
1144
+
1145
+ The branding provider is applied by the serializer's reply helper. It does not rewrite every message sent through the client.
1146
+
1147
+ ### Status formatting
1148
+
1149
+ ```ts
1150
+ import { toBoldSans, formatStatus } from "@kyyinfinite/zapo-message/status.js";
1151
+
1152
+ const heading = toBoldSans("System status");
1153
+ const status = formatStatus("ok", "Connected");
1154
+ ```
1155
+
1156
+ `formatStatus()` accepts `"ok"`, `"warn"`, or `"fail"`.
1157
+
1158
+ ## 🧾 Message payloads at a glance
1159
+
1160
+ The following table describes the top-level content shape built by the package before it is passed to `client.message.send()`. Media fields contain protocol metadata produced after upload; AIRich and interactive messages contain nested protocol structures.
1161
+
1162
+ | API | Top-level payload / transport input |
1163
+ | --- | --- |
1164
+ | `text` | `{ conversation: string }` |
1165
+ | `button` | `{ interactiveMessage: { body, nativeFlowMessage, header?, footer? } }` |
1166
+ | `legacyButton` | `{ buttonsMessage: { contentText, buttons, headerType, ... } }` |
1167
+ | `listMessage` | `{ listMessage: { title, description, buttonText, listType, sections, ... } }` or native-flow fallback |
1168
+ | `linkPreview` | `{ extendedTextMessage: { text, matchedText, previewType, ... } }` |
1169
+ | `media` / `image` / `video` / `audio` / `document` | One of `{ imageMessage }`, `{ videoMessage }`, `{ audioMessage }`, `{ documentMessage }` |
1170
+ | `sticker` | `{ stickerMessage }` |
1171
+ | `contact` | `{ contactMessage: { displayName, vcard } }` |
1172
+ | `poll` | `{ type: "poll", name, options, ... }` input understood by ZapoJS |
1173
+ | `location` | `{ locationMessage: { degreesLatitude, degreesLongitude, ... } }` |
1174
+ | `reaction` | `{ type: "reaction", target, emoji }` input understood by ZapoJS |
1175
+ | `forward` | Original protocol message plus forward send options |
1176
+ | `album` | Album marker followed by individually uploaded media messages |
1177
+ | `airich` | `{ botForwardedMessage: { message: { richResponseMessage } } }` |
1178
+
1179
+ These are payload families, not a promise that every nested protobuf field is stable across ZapoJS versions. The package deliberately delegates transport-specific behavior to `client.message.send()` and media upload to `client.message.upload()`.
1180
+
1181
+ ## ⚠️ Validation and errors
1182
+
1183
+ The root package exports these error classes:
1184
+
1185
+ | Error class | Code | Typical cause |
1186
+ | --- | --- | --- |
1187
+ | `MessageError` | `MESSAGE_ERROR` by default | General builder or send lifecycle error |
1188
+ | `ValidationError` | `VALIDATION` | Invalid or missing config value |
1189
+ | `ItemNotFoundError` | `ITEM_NOT_FOUND` | AIRich node ID or index was not found |
1190
+ | `DuplicateIdError` | `DUPLICATE_ID` | Duplicate ID in a structure that requires unique IDs |
1191
+ | `InvalidTargetError` | `INVALID_TARGET` | Invalid message target |
1192
+ | `ProtocolSendError` | `PROTOCOL_SEND` | Placeholder edit or album send protocol step failed |
1193
+ | `MediaError` | `MEDIA` | Media read, detection, processing, or upload failed |
1194
+
1195
+ Example:
473
1196
 
474
1197
  ```ts
475
- import { mDownload, qDownload } from "@kyyinfinite/zapo-message/download.js";
1198
+ import {
1199
+ MessageError,
1200
+ ValidationError,
1201
+ MediaError,
1202
+ } from "@kyyinfinite/zapo-message";
1203
+
1204
+ try {
1205
+ await client.text(jid, { body: "" });
1206
+ } catch (error) {
1207
+ if (error instanceof ValidationError) {
1208
+ console.error("Invalid message config:", error.message);
1209
+ } else if (error instanceof MediaError) {
1210
+ console.error("Media operation failed:", error.message);
1211
+ } else if (error instanceof MessageError) {
1212
+ console.error(error.code, error.message);
1213
+ } else {
1214
+ throw error;
1215
+ }
1216
+ }
1217
+ ```
1218
+
1219
+ Errors expose a `code` property. Some errors also include structured metadata such as `cause`, `kind`, `stage`, `placeholderId`, `id`, or `availableIds`.
1220
+
1221
+ ## 🛠 Troubleshooting
1222
+
1223
+ ### `client.text is not a function`
476
1224
 
477
- const bytes = await mDownload(incomingEvent, client, { maxBytes: 20 * 1024 * 1024 });
1225
+ - Make sure the root package import runs before you call the method:
1226
+
1227
+ ```ts
1228
+ import "@kyyinfinite/zapo-message";
1229
+ ```
1230
+
1231
+ - Confirm that the client is a `WaClient` from the same resolved ZapoJS installation used by the package.
1232
+ - If you use a custom client, call `installZapoMessage(client)` and ensure it has a callable `message.send` method.
1233
+ - Check whether your bundler or runtime is loading a different copy of ZapoJS.
1234
+
1235
+ ### `NO_CLIENT`
1236
+
1237
+ The builder has no client bound to it. Create it through `client.text()` or pass a client to the standalone factory:
1238
+
1239
+ ```ts
1240
+ await text(client).body("Hello").send(jid);
478
1241
  ```
479
1242
 
480
- ## Public API
1243
+ ### `NO_TARGET`
481
1244
 
482
- Builder yang dipasang di client: `button()`, `legacyButton()`, `listMessage()`,
483
- `airich(options?)`, `text()`, `reaction()`, `media()`, `image()`, `video()`,
484
- `audio()`, `document()`, `sticker()`, `contact()`, `poll()`, `album()`,
485
- `linkPreview()`, `forward()`, `location()`.
1245
+ No destination was supplied. Pass a JID to `.send(jid)`, set `.to(jid)` / `.defaultTo(jid)`, or use a message reference that contains a chat JID where the API supports target inference.
486
1246
 
487
- Semua method di atas hybrid: tanpa argumen config mengembalikan builder (chain),
488
- dengan `(jid, config)` (atau `(config)` untuk reaction) langsung mengirim dan
489
- mengembalikan `Promise<MessageSendResult>`. `image()`/`video()`/`audio()`/
490
- `document()` adalah fasad convenience yang memakai engine media yang sama
491
- sebagai `media()`.
1247
+ ### `VALIDATION` or `DUPLICATE_ID`
492
1248
 
493
- Factory mandiri dengan nama yang sama tersedia dari root package. Referensi lengkap
494
- (signature, config, payload, error) ada di `docs/API.md`. Setiap fitur punya jejak protokol
495
- di `docs/PROTOCOL_TRACEABILITY.md`.
1249
+ Check required fields, field types, URL formats, phone formats, numeric ranges, and uniqueness constraints. Button and list IDs must be unique where the builder validates them. For AIRich operations, confirm that the referenced node ID exists before calling `replace`, `insert`, or `remove`.
496
1250
 
497
- ## Troubleshooting
1251
+ ### Media type cannot be detected
498
1252
 
499
- - **`client.text is not a function`** — pastikan `import "@kyyinfinite/zapo-message"`
500
- dieksekusi sebelum pemakaian (satu kali di entry point cukup), dan salinan
501
- `zapo-js` yang dipakai client sama dengan yang dirender paket ini. Untuk kasus
502
- khusus (bundler, client custom), pakai `installZapoMessage(client)`.
503
- - **`MEDIA ... sharp tidak tersedia`** — instal `sharp` (`npm install sharp`) untuk
504
- thumbnail/dimensi otomatis, atau berikan `thumbnail`/`width`/`height` manual.
505
- - **`mimetype ... tidak diketahui`** — sumber stream tidak bisa dideteksi isinya;
506
- berikan `options.mimetype` eksplisit.
507
- - **`VALIDATION ... fileName`** — dokumen dari Buffer/stream butuh `fileName`
508
- eksplisit (nama file tidak bisa ditebak dari bytes).
509
- - **`tujuan tidak diketahui`** — panggil `send(jid)`, set `defaultTo(jid)`, atau
510
- untuk reaksi pastikan target punya `key.remoteJid`.
511
- - **`DUPLICATE_ID`** — id baris list/tombol harus unik lintas section.
512
- - **Poll tidak muncul di grup lama** — beberapa klien lama hanya merender poll
513
- klasik; batasi `selectableCount(1)` tanpa `allowAddOption()`.
514
- - **Sticker `bukan WebP`** — WhatsApp hanya menerima WebP; konversikan dulu
515
- (mis. lewat `sharp(...).webp()`).
1253
+ Some streams and unusual file sources do not provide enough information for automatic MIME detection. Set `mimetype` explicitly in the media options:
516
1254
 
517
- ## Testing and verification
1255
+ ```ts
1256
+ await client.document(jid, {
1257
+ source: fileBuffer,
1258
+ fileName: "report.bin",
1259
+ mimetype: "application/octet-stream",
1260
+ });
1261
+ ```
1262
+
1263
+ ### Document requires a filename
1264
+
1265
+ A buffer or stream does not carry a reliable display filename. Set `fileName` explicitly:
1266
+
1267
+ ```ts
1268
+ await client.document(jid, {
1269
+ source: pdfBuffer,
1270
+ fileName: "report.pdf",
1271
+ mimetype: "application/pdf",
1272
+ });
1273
+ ```
1274
+
1275
+ ### `sharp` is unavailable or thumbnail generation fails
1276
+
1277
+ Install the optional dependency when you need automatic image processing:
518
1278
 
519
1279
  ```bash
520
- npm test # build + unit + golden + integrasi fake-server
521
- npm run test:fast # tanpa build
522
- npm run typecheck
523
- npm run lint # zero-comments + tsc
524
- npm run verify:package
525
- npm run verify:consumer
1280
+ npm install sharp
1281
+ ```
1282
+
1283
+ Alternatively, supply a suitable thumbnail or the dimensions required by the feature. Some thumbnail paths require JPEG input; others generate a JPEG thumbnail through Sharp.
1284
+
1285
+ ### Sticker rejected as an invalid image
1286
+
1287
+ Sticker input must be WebP. Convert the image to WebP before passing it to `sticker()`; the library inspects WebP data but does not convert arbitrary formats into stickers.
1288
+
1289
+ ### Reaction has no target chat
1290
+
1291
+ The target reference must include a message ID. To infer the chat automatically, it should also include `key.remoteJid`. Otherwise, pass the chat JID to the reaction send call:
1292
+
1293
+ ```ts
1294
+ await client.reaction(jid, {
1295
+ target: messageKey,
1296
+ emoji: "🔥",
1297
+ });
526
1298
  ```
527
1299
 
528
- Hasil lengkap per suite ada di `docs/TEST_REPORT.md` (termasuk 3 kegagalan bawaan
529
- yang dipertahankan setia pada perilaku sumber asli — lihat laporan).
1300
+ ### Album send fails with `PROTOCOL_SEND`
1301
+
1302
+ Album delivery requires the initial album marker send to return a non-empty message ID. If your custom transport does not return the same result shape as ZapoJS, the follow-up media messages cannot quote the album marker.
1303
+
1304
+ ### AIRich placeholder was sent but the edit failed
1305
+
1306
+ A two-step AIRich send can fail after the placeholder is already delivered. Inspect the `ProtocolSendError` fields, especially `stage` and `placeholderId`, before retrying. Sending a new response blindly may leave the original placeholder visible.
1307
+
1308
+ ### Poll display differs between WhatsApp clients
1309
+
1310
+ Poll rendering is ultimately handled by the installed ZapoJS version and the recipient's WhatsApp client. Keep poll options within the validated range and test the desired selection behavior against the clients you support.
1311
+
1312
+ ## ❓ FAQ
1313
+
1314
+ <details>
1315
+ <summary><strong>Do I have to use the fluent API?</strong></summary>
1316
+
1317
+ No. Use the object API when the full message configuration is already available. Use the fluent API when building the message step by step. Both use the same underlying builders.
1318
+
1319
+ </details>
1320
+
1321
+ <details>
1322
+ <summary><strong>Can I mix object and fluent APIs in one project?</strong></summary>
1323
+
1324
+ Yes. They are two entry points to the same message implementations. You can choose the style per message.
1325
+
1326
+ </details>
1327
+
1328
+ <details>
1329
+ <summary><strong>Does importing the package modify ZapoJS?</strong></summary>
1330
+
1331
+ The root import installs non-enumerable methods on the `WaClient` prototype. Existing method names are not overwritten, and installation is guarded against repeated execution. If you do not want prototype integration, use the exported factories instead.
1332
+
1333
+ </details>
1334
+
1335
+ <details>
1336
+ <summary><strong>Can I use a custom client?</strong></summary>
1337
+
1338
+ Yes, if it implements the expected `message.send()` interface and supports the payloads and options you use. Call `installZapoMessage()` to add the convenience methods to a client instance, or pass the client directly to a standalone factory.
1339
+
1340
+ </details>
1341
+
1342
+ <details>
1343
+ <summary><strong>Can I send several media items with `media()`?</strong></summary>
1344
+
1345
+ No. A `MediaBuilder` accepts one media kind and one source. Use `album()` for a sequence of images and videos.
1346
+
1347
+ </details>
1348
+
1349
+ <details>
1350
+ <summary><strong>Can `location()` request the recipient's location?</strong></summary>
1351
+
1352
+ No. `location()` sends a location message. Use the native-flow button item `{ type: "send_location" }` when you want to add a button that asks the recipient to share their location.
1353
+
1354
+ </details>
1355
+
1356
+ <details>
1357
+ <summary><strong>Does `linkPreview()` fetch the URL?</strong></summary>
1358
+
1359
+ No. It builds an explicit preview payload from the supplied text and metadata. Provide a thumbnail when you need one; the selected URL must appear in the message body.
1360
+
1361
+ </details>
1362
+
1363
+ <details>
1364
+ <summary><strong>Does the library convert images into WebP stickers?</strong></summary>
1365
+
1366
+ No. Sticker sources must already contain WebP data. Convert the source before calling the sticker API.
1367
+
1368
+ </details>
1369
+
1370
+ <details>
1371
+ <summary><strong>Are all AIRich primitives guaranteed to render on every WhatsApp client?</strong></summary>
1372
+
1373
+ No. Some AIRich primitive types are marked experimental in the package. Their rendering depends on WhatsApp client and protocol support. Test them with the client versions you intend to support.
1374
+
1375
+ </details>
1376
+
1377
+ <details>
1378
+ <summary><strong>Why does AIRich sometimes send a placeholder first?</strong></summary>
1379
+
1380
+ AIRich supports a two-step placeholder/edit transport flow. The `twoStep` send option controls that behavior. A failed edit may happen after the placeholder has already been sent; inspect the protocol error before retrying.
1381
+
1382
+ </details>
1383
+
1384
+ <details>
1385
+ <summary><strong>Where can I find every TypeScript type?</strong></summary>
1386
+
1387
+ The package publishes declaration files and exports the public config, option, builder, payload, and error types from its root entry point. Import the type you need directly from `@kyyinfinite/zapo-message`.
1388
+
1389
+ </details>
1390
+
1391
+
1392
+ ## 📄 License
1393
+
1394
+ ISC. See [LICENSE](LICENSE).
1395
+
1396
+ ---
1397
+
1398
+ <div align="center">
530
1399
 
531
- ## License
1400
+ Made for developers building on ZapoJS.
532
1401
 
533
- ISC — lihat [LICENSE](LICENSE).
1402
+ </div>