@kyyinfinite/zapo-message 0.0.0-stage → 1.0.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 (191) hide show
  1. package/CHANGELOG.md +159 -0
  2. package/LICENSE +20 -0
  3. package/README.md +532 -2
  4. package/build.config.json +28 -0
  5. package/dist/airich/airich.d.ts +180 -0
  6. package/dist/airich/airich.js +548 -0
  7. package/dist/airich/context.d.ts +24 -0
  8. package/dist/airich/context.js +48 -0
  9. package/dist/airich/encode.d.ts +3 -0
  10. package/dist/airich/encode.js +16 -0
  11. package/dist/airich/index.d.ts +20 -0
  12. package/dist/airich/index.js +11 -0
  13. package/dist/airich/inline.d.ts +45 -0
  14. package/dist/airich/inline.js +152 -0
  15. package/dist/airich/nodes.d.ts +30 -0
  16. package/dist/airich/nodes.js +121 -0
  17. package/dist/airich/primitives.d.ts +144 -0
  18. package/dist/airich/primitives.js +230 -0
  19. package/dist/airich/protocol.d.ts +35 -0
  20. package/dist/airich/protocol.js +65 -0
  21. package/dist/airich/table.d.ts +22 -0
  22. package/dist/airich/table.js +35 -0
  23. package/dist/airich/tokenizer.d.ts +13 -0
  24. package/dist/airich/tokenizer.js +717 -0
  25. package/dist/airich/transport.d.ts +15 -0
  26. package/dist/airich/transport.js +56 -0
  27. package/dist/branding.d.ts +5 -0
  28. package/dist/branding.js +9 -0
  29. package/dist/btn/builders.d.ts +246 -0
  30. package/dist/btn/builders.js +710 -0
  31. package/dist/btn/media-slot.d.ts +28 -0
  32. package/dist/btn/media-slot.js +323 -0
  33. package/dist/btn/media-source.d.ts +38 -0
  34. package/dist/btn/media-source.js +116 -0
  35. package/dist/btn/sharp-loader.d.ts +5 -0
  36. package/dist/btn/sharp-loader.js +18 -0
  37. package/dist/btn/thumbnail.d.ts +21 -0
  38. package/dist/btn/thumbnail.js +124 -0
  39. package/dist/btn/validators.d.ts +40 -0
  40. package/dist/btn/validators.js +135 -0
  41. package/dist/btn.d.ts +1 -0
  42. package/dist/btn.js +1 -0
  43. package/dist/core/async-send.d.ts +20 -0
  44. package/dist/core/async-send.js +1 -0
  45. package/dist/core/base-builder.d.ts +20 -0
  46. package/dist/core/base-builder.js +67 -0
  47. package/dist/core/errors.d.ts +30 -0
  48. package/dist/core/errors.js +61 -0
  49. package/dist/download.d.ts +24 -0
  50. package/dist/download.js +123 -0
  51. package/dist/index.d.ts +38 -0
  52. package/dist/index.js +22 -0
  53. package/dist/integration/augment.d.ts +97 -0
  54. package/dist/integration/augment.js +1 -0
  55. package/dist/integration/auto.d.ts +8 -0
  56. package/dist/integration/auto.js +79 -0
  57. package/dist/integration/index.d.ts +4 -0
  58. package/dist/integration/index.js +2 -0
  59. package/dist/integration/methods.d.ts +25 -0
  60. package/dist/integration/methods.js +24 -0
  61. package/dist/interactive.d.ts +24 -0
  62. package/dist/interactive.js +121 -0
  63. package/dist/media-gate.d.ts +99 -0
  64. package/dist/media-gate.js +322 -0
  65. package/dist/message/album.d.ts +33 -0
  66. package/dist/message/album.js +107 -0
  67. package/dist/message/contact.d.ts +29 -0
  68. package/dist/message/contact.js +123 -0
  69. package/dist/message/forward.d.ts +23 -0
  70. package/dist/message/forward.js +77 -0
  71. package/dist/message/index.d.ts +26 -0
  72. package/dist/message/index.js +13 -0
  73. package/dist/message/link-preview.d.ts +28 -0
  74. package/dist/message/link-preview.js +98 -0
  75. package/dist/message/location.d.ts +24 -0
  76. package/dist/message/location.js +94 -0
  77. package/dist/message/media.d.ts +90 -0
  78. package/dist/message/media.js +123 -0
  79. package/dist/message/poll.d.ts +24 -0
  80. package/dist/message/poll.js +98 -0
  81. package/dist/message/reaction.d.ts +20 -0
  82. package/dist/message/reaction.js +71 -0
  83. package/dist/message/sticker.d.ts +29 -0
  84. package/dist/message/sticker.js +44 -0
  85. package/dist/message/target.d.ts +18 -0
  86. package/dist/message/target.js +24 -0
  87. package/dist/message/text.d.ts +17 -0
  88. package/dist/message/text.js +29 -0
  89. package/dist/message/vcard.d.ts +9 -0
  90. package/dist/message/vcard.js +23 -0
  91. package/dist/message/webp.d.ts +6 -0
  92. package/dist/message/webp.js +57 -0
  93. package/dist/payloads.d.ts +180 -0
  94. package/dist/payloads.js +1 -0
  95. package/dist/serialize.d.ts +41 -0
  96. package/dist/serialize.js +93 -0
  97. package/dist/status.d.ts +3 -0
  98. package/dist/status.js +21 -0
  99. package/dist/zapo-client.d.ts +44 -0
  100. package/dist/zapo-client.js +1 -0
  101. package/examples/airich.ts +59 -0
  102. package/examples/buttons.ts +48 -0
  103. package/examples/client-methods.ts +58 -0
  104. package/examples/hybrid.ts +133 -0
  105. package/examples/serialize.ts +61 -0
  106. package/package.json +271 -4
  107. package/scripts/check-no-comments.mjs +101 -0
  108. package/scripts/compare-golden.mjs +461 -0
  109. package/scripts/lib-config.mjs +9 -0
  110. package/scripts/smoke-auto.mjs +75 -0
  111. package/scripts/test-external-consumer.mjs +316 -0
  112. package/scripts/verify-package.mjs +78 -0
  113. package/src/airich/airich.ts +970 -0
  114. package/src/airich/context.ts +96 -0
  115. package/src/airich/encode.ts +25 -0
  116. package/src/airich/index.ts +98 -0
  117. package/src/airich/inline.ts +272 -0
  118. package/src/airich/nodes.ts +174 -0
  119. package/src/airich/primitives.ts +474 -0
  120. package/src/airich/protocol.ts +133 -0
  121. package/src/airich/table.ts +70 -0
  122. package/src/airich/tokenizer.ts +799 -0
  123. package/src/airich/transport.ts +106 -0
  124. package/src/branding.ts +23 -0
  125. package/src/btn/builders.ts +1073 -0
  126. package/src/btn/media-slot.ts +486 -0
  127. package/src/btn/media-source.ts +189 -0
  128. package/src/btn/sharp-loader.ts +23 -0
  129. package/src/btn/thumbnail.ts +182 -0
  130. package/src/btn/validators.ts +237 -0
  131. package/src/btn.ts +8 -0
  132. package/src/core/async-send.ts +28 -0
  133. package/src/core/base-builder.ts +104 -0
  134. package/src/core/errors.ts +82 -0
  135. package/src/download.ts +212 -0
  136. package/src/index.ts +229 -0
  137. package/src/integration/augment.ts +262 -0
  138. package/src/integration/auto.ts +103 -0
  139. package/src/integration/index.ts +8 -0
  140. package/src/integration/methods.ts +45 -0
  141. package/src/interactive.ts +188 -0
  142. package/src/media-gate.ts +499 -0
  143. package/src/message/album.ts +187 -0
  144. package/src/message/contact.ts +170 -0
  145. package/src/message/forward.ts +123 -0
  146. package/src/message/index.ts +83 -0
  147. package/src/message/link-preview.ts +148 -0
  148. package/src/message/location.ts +150 -0
  149. package/src/message/media.ts +323 -0
  150. package/src/message/poll.ts +158 -0
  151. package/src/message/reaction.ts +133 -0
  152. package/src/message/sticker.ts +100 -0
  153. package/src/message/target.ts +38 -0
  154. package/src/message/text.ts +61 -0
  155. package/src/message/vcard.ts +36 -0
  156. package/src/message/webp.ts +78 -0
  157. package/src/payloads.ts +204 -0
  158. package/src/serialize.ts +180 -0
  159. package/src/status.ts +29 -0
  160. package/src/zapo-client.ts +84 -0
  161. package/test/airich-inline.test.ts +200 -0
  162. package/test/airich-primitives.test.ts +226 -0
  163. package/test/airich-tokenizer.test.ts +145 -0
  164. package/test/airich.golden.test.ts +406 -0
  165. package/test/airich.test.ts +1006 -0
  166. package/test/btn-button.test.ts +416 -0
  167. package/test/btn-header.test.ts +646 -0
  168. package/test/btn-legacy.test.ts +342 -0
  169. package/test/btn-lifecycle.test.ts +295 -0
  170. package/test/btn-list.test.ts +261 -0
  171. package/test/btn-media-source.test.ts +150 -0
  172. package/test/btn-thumbnail.test.ts +160 -0
  173. package/test/builder-compat.test.ts +264 -0
  174. package/test/helpers.ts +27 -0
  175. package/test/hybrid-airich.test.ts +345 -0
  176. package/test/hybrid-client.test.ts +239 -0
  177. package/test/hybrid-errors.test.ts +557 -0
  178. package/test/hybrid-interactive.test.ts +455 -0
  179. package/test/hybrid.golden.test.ts +349 -0
  180. package/test/hybrid.test.ts +479 -0
  181. package/test/integration-auto.test.ts +159 -0
  182. package/test/integration.fakeserver.test.ts +440 -0
  183. package/test/media-gate.test.ts +215 -0
  184. package/test/message-album.test.ts +145 -0
  185. package/test/message-builders.test.ts +401 -0
  186. package/test/message-media.test.ts +303 -0
  187. package/test/message.fakeserver.test.ts +284 -0
  188. package/test/message.golden.test.ts +254 -0
  189. package/test/serializer.test.ts +448 -0
  190. package/tsconfig.json +26 -0
  191. package/tsconfig.test.json +10 -0
package/README.md CHANGED
@@ -1,3 +1,533 @@
1
- # Temporary Holding Version
1
+ # @kyyinfinite/zapo-message
2
2
 
3
- This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
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.
7
+
8
+ Setiap jenis pesan punya **dua gaya API setara** — object async dan fluent chain —
9
+ dengan satu implementasi builder yang sama:
10
+
11
+ ```ts
12
+ import { createStore, WaClient } from "zapo-js";
13
+ import "@kyyinfinite/zapo-message";
14
+
15
+ const client = new WaClient({ store: createStore({}), sessionId: "bot" });
16
+ await client.connect();
17
+
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
+ });
24
+
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);
28
+ ```
29
+
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.
33
+
34
+ ## Hybrid API: object async dan fluent chain
35
+
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`).
41
+
42
+ ### Object async
43
+
44
+ ```ts
45
+ await client.text(jid, { body: "Halo Dunia" });
46
+
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
+ ],
64
+ });
65
+
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
+ });
74
+
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",
82
+ });
83
+
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" } },
93
+ ],
94
+ });
95
+ await client.reaction({ target: incomingEvent, emoji: "🔥" });
96
+ await client.forward(jidLain, { message: incomingEvent });
97
+ ```
98
+
99
+ ### Fluent chain
100
+
101
+ ```ts
102
+ await client.text().to(jid).body("Halo Dunia").send();
103
+ await client.button()
104
+ .to(jid)
105
+ .title("Main Menu")
106
+ .body("Choose one")
107
+ .quick_reply("Profile", "profile")
108
+ .cta_url("Website", "https://example.com")
109
+ .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
+ ```
113
+
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`).
119
+
120
+ ## Apa itu Zapo Message
121
+
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.
136
+
137
+ ## Installation
138
+
139
+ ```bash
140
+ npm install @kyyinfinite/zapo-message zapo-js
141
+ ```
142
+
143
+ Untuk pemrosesan gambar otomatis (thumbnail header tombol, thumbnail PNG sticker,
144
+ deteksi dimensi), instal `sharp` sebagai peer dependency opsional:
145
+
146
+ ```bash
147
+ npm install sharp
148
+ ```
149
+
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.
152
+
153
+ ## Requirements
154
+
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.
160
+
161
+ ## Quick Start
162
+
163
+ ```ts
164
+ import { createStore, WaClient } from "zapo-js";
165
+ import "@kyyinfinite/zapo-message";
166
+
167
+ const client = new WaClient({ store: createStore({}), sessionId: "bot" });
168
+
169
+ client.on("message", async (event) => {
170
+ if (event.message?.conversation === "ping") {
171
+ await client.text().body("pong").send(event.key.remoteJid);
172
+ }
173
+ });
174
+
175
+ await client.connect();
176
+ ```
177
+
178
+ ### Import sekali, langsung pakai
179
+
180
+ Semua method builder menempel di **setiap** `WaClient` begitu paket di-import —
181
+ termasuk client yang dibuat sebelum import, dan client yang dibuat belakangan.
182
+
183
+ ```ts
184
+ import "@kyyinfinite/zapo-message";
185
+ import { WaClient } from "zapo-js";
186
+
187
+ const a = new WaClient(optionsA);
188
+ const b = new WaClient(optionsB);
189
+
190
+ await a.text().body("dari client a").send(jid);
191
+ await b.poll().question("Siapa menang?").options(["A", "B"]).send(jid);
192
+ ```
193
+
194
+ Jaminan integrasi otomatis:
195
+
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.
202
+
203
+ Contoh JavaScript (tanpa tipe):
204
+
205
+ ```js
206
+ const { createStore, WaClient } = require("zapo-js");
207
+ require("@kyyinfinite/zapo-message");
208
+
209
+ const client = new WaClient({ store: createStore({}), sessionId: "bot" });
210
+ await client.text().body("Halo dari CJS").send(jid);
211
+ ```
212
+
213
+ ## Text message
214
+
215
+ ```ts
216
+ // async
217
+ await client.text(jid, { body: "Halo Dunia" });
218
+
219
+ // chain
220
+ await client.text().body("Halo Dunia").send(jid);
221
+
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 });
225
+
226
+ // tujuan default bila sering dipakai
227
+ await client.text().body("hai").to(jid).send();
228
+ await client.text().body("hai").defaultTo(jid).send();
229
+ ```
230
+
231
+ Payload yang dikirim: `{ conversation: "..." }` — persis normalisasi string
232
+ `client.message.send(jid, "Halo")` di zapo-js.
233
+
234
+ ## Interactive message
235
+
236
+ ### Native flow buttons
237
+
238
+ ```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);
253
+ ```
254
+
255
+ ### Tombol legacy
256
+
257
+ ```ts
258
+ await client
259
+ .legacyButton()
260
+ .body("Halo")
261
+ .button("b1", "Satu")
262
+ .button("b2", "Dua")
263
+ .send(jid);
264
+ ```
265
+
266
+ ### List message
267
+
268
+ ```ts
269
+ await client
270
+ .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" },
277
+ ])
278
+ .send(jid);
279
+ ```
280
+
281
+ Di chat grup, list otomatis dikirim sebagai native flow (`single_select`) agar tetap
282
+ tampil — perilaku yang sama persis dengan versi lama.
283
+
284
+ ### AIRich
285
+
286
+ ```ts
287
+ await client
288
+ .airich()
289
+ .text("Ringkasan pesanan:")
290
+ .table([["Item", "Qty"], ["Kopi", "2"]])
291
+ .code("javascript", "const x = 1")
292
+ .suggest(["ulangi pesanan", "lihat menu"])
293
+ .send(jid);
294
+ ```
295
+
296
+ ## Media
297
+
298
+ ```ts
299
+ // image (Buffer, Uint8Array, path file, atau Readable)
300
+ await client.media().image(pngBuffer, { caption: "Foto liburan" }).send(jid);
301
+
302
+ // video
303
+ await client.media().video(mp4Path, { seconds: 30, mimetype: "video/mp4" }).send(jid);
304
+
305
+ // dokumen
306
+ await client.media().document(pdfBuffer, { fileName: "laporan.pdf" }).send(jid);
307
+
308
+ // audio / voice note
309
+ await client.media().audio(oggBuffer, { ptt: true, mimetype: "audio/ogg; codecs=opus" }).send(jid);
310
+ ```
311
+
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.
315
+
316
+ ## Sticker
317
+
318
+ ```ts
319
+ await client.sticker().source(webpBuffer).send(jid);
320
+
321
+ // opsi manual
322
+ await client
323
+ .sticker()
324
+ .source(webpPath, { isAnimated: false, pngThumbnail: pngBytes })
325
+ .send(jid);
326
+ ```
327
+
328
+ Sumber harus file WebP. Dimensi dan status animasi dibaca langsung dari header
329
+ container WebP (VP8X/VP8/VP8L + chunk ANIM) tanpa dependensi tambahan.
330
+
331
+ ## Poll
332
+
333
+ ```ts
334
+ // satu pilihan (pollCreationMessageV3)
335
+ await client.poll().question("Makan apa?").options(["Nasi goreng", "Mie ayam"]).send(jid);
336
+
337
+ // multi-pilih + boleh tambah opsi (pollCreationMessageV6)
338
+ await client
339
+ .poll()
340
+ .question("Pilih dua")
341
+ .options(["A", "B", "C"])
342
+ .selectableCount(2)
343
+ .allowAddOption()
344
+ .send(jid);
345
+ ```
346
+
347
+ Builder mengirim input terketik `{ type: "poll", ... }` dan zapo-js yang memilih varian
348
+ protokol (V3/V6/klasik) sesuai aturan versi terpasang.
349
+
350
+ ## Contact
351
+
352
+ ```ts
353
+ await client.contact().name("Budi").phone("+628123456789").send(jid);
354
+
355
+ // detail lengkap
356
+ await client
357
+ .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")
364
+ .send(jid);
365
+
366
+ // vcard mentah
367
+ await client.contact().vcard("BEGIN:VCARD\nVERSION:3.0\nFN:Siti\nEND:VCARD").send(jid);
368
+ ```
369
+
370
+ ## Location
371
+
372
+ ```ts
373
+ // async
374
+ await client.location(jid, {
375
+ latitude: -6.2,
376
+ longitude: 106.8,
377
+ name: "Jakarta",
378
+ address: "Indonesia",
379
+ });
380
+
381
+ // chain
382
+ await client
383
+ .location()
384
+ .to(jid)
385
+ .coordinates(-6.2, 106.8)
386
+ .name("Jakarta")
387
+ .address("Indonesia")
388
+ .send();
389
+ ```
390
+
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.
396
+
397
+ ## Reaction, forward, link preview, album
398
+
399
+ ```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
403
+
404
+ // forward pesan (skor diteruskan bila sumber pernah di-forward)
405
+ await client.forward().message(incomingEvent).send(jidLain);
406
+
407
+ // link preview eksplisit (tanpa fetch)
408
+ await client
409
+ .linkPreview()
410
+ .body("Baca https://example.com/docs ya")
411
+ .title("Dokumentasi")
412
+ .description("Semua yang perlu diketahui")
413
+ .kind("image")
414
+ .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
+ ```
419
+
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`.
423
+
424
+ ## Serializer
425
+
426
+ ```ts
427
+ import { mSerialize, qSerialize, extractText } from "@kyyinfinite/zapo-message/serialize.js";
428
+
429
+ const content = mSerialize(incomingEvent, client);
430
+ const quoted = qSerialize(incomingEvent, { message: content }, client);
431
+ ```
432
+
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.
436
+
437
+ ## Advanced usage
438
+
439
+ ### Factory manual & messageKit (kompatibilitas lama)
440
+
441
+ ```ts
442
+ import { button, legacyButton, listMessage, airich, messageKit } from "@kyyinfinite/zapo-message";
443
+
444
+ const b = button(client).body("Halo").quick_reply("OK", "ok");
445
+ await b.send(jid);
446
+
447
+ const kit = messageKit(client);
448
+ await kit.button().body("dari kit").send(jid);
449
+ ```
450
+
451
+ API lama (`button(client)`, `messageKit(client)`, dst.) tetap bekerja persis seperti
452
+ sebelumnya — lihat `docs/API_COMPATIBILITY.md`.
453
+
454
+ ### Instalasi manual untuk client non-ZapoJS
455
+
456
+ ```ts
457
+ import { installZapoMessage } from "@kyyinfinite/zapo-message";
458
+
459
+ installZapoMessage(myDuckTypedClient); // butuh client.message.send
460
+ await myDuckTypedClient.text().body("halo").send(jid);
461
+ ```
462
+
463
+ ### Kontrol media gate
464
+
465
+ ```ts
466
+ import { configureSharedMediaQueue, resetSharedMediaQueue } from "@kyyinfinite/zapo-message/media-gate.js";
467
+
468
+ configureSharedMediaQueue({ concurrency: 4, maxBytes: 100 * 1024 * 1024 });
469
+ resetSharedMediaQueue();
470
+ ```
471
+
472
+ ### Download media
473
+
474
+ ```ts
475
+ import { mDownload, qDownload } from "@kyyinfinite/zapo-message/download.js";
476
+
477
+ const bytes = await mDownload(incomingEvent, client, { maxBytes: 20 * 1024 * 1024 });
478
+ ```
479
+
480
+ ## Public API
481
+
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()`.
486
+
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()`.
492
+
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`.
496
+
497
+ ## Troubleshooting
498
+
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()`).
516
+
517
+ ## Testing and verification
518
+
519
+ ```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
526
+ ```
527
+
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).
530
+
531
+ ## License
532
+
533
+ ISC — lihat [LICENSE](LICENSE).
@@ -0,0 +1,28 @@
1
+ {
2
+ "noComments": {
3
+ "include": ["src/**/*.ts", "test/**/*.ts", "examples/**/*.ts"],
4
+ "allowUrlsInStrings": true,
5
+ "allowStringsStartingWithSlashSlashOrSlashStar": true
6
+ },
7
+ "package": {
8
+ "allowedTopLevel": [
9
+ "src",
10
+ "test",
11
+ "examples",
12
+ "docs",
13
+ "scripts",
14
+ "dist",
15
+ "package.json",
16
+ "tsconfig.json",
17
+ "tsconfig.test.json",
18
+ "build.config.json",
19
+ "README.md",
20
+ "CHANGELOG.md",
21
+ "LICENSE"
22
+ ]
23
+ },
24
+ "consumer": {
25
+ "nodeModulesCopy": ["zapo-js"],
26
+ "compileFile": "consumer-entry.ts"
27
+ }
28
+ }