@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.
- package/CHANGELOG.md +159 -0
- package/LICENSE +20 -0
- package/README.md +532 -2
- package/build.config.json +28 -0
- package/dist/airich/airich.d.ts +180 -0
- package/dist/airich/airich.js +548 -0
- package/dist/airich/context.d.ts +24 -0
- package/dist/airich/context.js +48 -0
- package/dist/airich/encode.d.ts +3 -0
- package/dist/airich/encode.js +16 -0
- package/dist/airich/index.d.ts +20 -0
- package/dist/airich/index.js +11 -0
- package/dist/airich/inline.d.ts +45 -0
- package/dist/airich/inline.js +152 -0
- package/dist/airich/nodes.d.ts +30 -0
- package/dist/airich/nodes.js +121 -0
- package/dist/airich/primitives.d.ts +144 -0
- package/dist/airich/primitives.js +230 -0
- package/dist/airich/protocol.d.ts +35 -0
- package/dist/airich/protocol.js +65 -0
- package/dist/airich/table.d.ts +22 -0
- package/dist/airich/table.js +35 -0
- package/dist/airich/tokenizer.d.ts +13 -0
- package/dist/airich/tokenizer.js +717 -0
- package/dist/airich/transport.d.ts +15 -0
- package/dist/airich/transport.js +56 -0
- package/dist/branding.d.ts +5 -0
- package/dist/branding.js +9 -0
- package/dist/btn/builders.d.ts +246 -0
- package/dist/btn/builders.js +710 -0
- package/dist/btn/media-slot.d.ts +28 -0
- package/dist/btn/media-slot.js +323 -0
- package/dist/btn/media-source.d.ts +38 -0
- package/dist/btn/media-source.js +116 -0
- package/dist/btn/sharp-loader.d.ts +5 -0
- package/dist/btn/sharp-loader.js +18 -0
- package/dist/btn/thumbnail.d.ts +21 -0
- package/dist/btn/thumbnail.js +124 -0
- package/dist/btn/validators.d.ts +40 -0
- package/dist/btn/validators.js +135 -0
- package/dist/btn.d.ts +1 -0
- package/dist/btn.js +1 -0
- package/dist/core/async-send.d.ts +20 -0
- package/dist/core/async-send.js +1 -0
- package/dist/core/base-builder.d.ts +20 -0
- package/dist/core/base-builder.js +67 -0
- package/dist/core/errors.d.ts +30 -0
- package/dist/core/errors.js +61 -0
- package/dist/download.d.ts +24 -0
- package/dist/download.js +123 -0
- package/dist/index.d.ts +38 -0
- package/dist/index.js +22 -0
- package/dist/integration/augment.d.ts +97 -0
- package/dist/integration/augment.js +1 -0
- package/dist/integration/auto.d.ts +8 -0
- package/dist/integration/auto.js +79 -0
- package/dist/integration/index.d.ts +4 -0
- package/dist/integration/index.js +2 -0
- package/dist/integration/methods.d.ts +25 -0
- package/dist/integration/methods.js +24 -0
- package/dist/interactive.d.ts +24 -0
- package/dist/interactive.js +121 -0
- package/dist/media-gate.d.ts +99 -0
- package/dist/media-gate.js +322 -0
- package/dist/message/album.d.ts +33 -0
- package/dist/message/album.js +107 -0
- package/dist/message/contact.d.ts +29 -0
- package/dist/message/contact.js +123 -0
- package/dist/message/forward.d.ts +23 -0
- package/dist/message/forward.js +77 -0
- package/dist/message/index.d.ts +26 -0
- package/dist/message/index.js +13 -0
- package/dist/message/link-preview.d.ts +28 -0
- package/dist/message/link-preview.js +98 -0
- package/dist/message/location.d.ts +24 -0
- package/dist/message/location.js +94 -0
- package/dist/message/media.d.ts +90 -0
- package/dist/message/media.js +123 -0
- package/dist/message/poll.d.ts +24 -0
- package/dist/message/poll.js +98 -0
- package/dist/message/reaction.d.ts +20 -0
- package/dist/message/reaction.js +71 -0
- package/dist/message/sticker.d.ts +29 -0
- package/dist/message/sticker.js +44 -0
- package/dist/message/target.d.ts +18 -0
- package/dist/message/target.js +24 -0
- package/dist/message/text.d.ts +17 -0
- package/dist/message/text.js +29 -0
- package/dist/message/vcard.d.ts +9 -0
- package/dist/message/vcard.js +23 -0
- package/dist/message/webp.d.ts +6 -0
- package/dist/message/webp.js +57 -0
- package/dist/payloads.d.ts +180 -0
- package/dist/payloads.js +1 -0
- package/dist/serialize.d.ts +41 -0
- package/dist/serialize.js +93 -0
- package/dist/status.d.ts +3 -0
- package/dist/status.js +21 -0
- package/dist/zapo-client.d.ts +44 -0
- package/dist/zapo-client.js +1 -0
- package/examples/airich.ts +59 -0
- package/examples/buttons.ts +48 -0
- package/examples/client-methods.ts +58 -0
- package/examples/hybrid.ts +133 -0
- package/examples/serialize.ts +61 -0
- package/package.json +271 -4
- package/scripts/check-no-comments.mjs +101 -0
- package/scripts/compare-golden.mjs +461 -0
- package/scripts/lib-config.mjs +9 -0
- package/scripts/smoke-auto.mjs +75 -0
- package/scripts/test-external-consumer.mjs +316 -0
- package/scripts/verify-package.mjs +78 -0
- package/src/airich/airich.ts +970 -0
- package/src/airich/context.ts +96 -0
- package/src/airich/encode.ts +25 -0
- package/src/airich/index.ts +98 -0
- package/src/airich/inline.ts +272 -0
- package/src/airich/nodes.ts +174 -0
- package/src/airich/primitives.ts +474 -0
- package/src/airich/protocol.ts +133 -0
- package/src/airich/table.ts +70 -0
- package/src/airich/tokenizer.ts +799 -0
- package/src/airich/transport.ts +106 -0
- package/src/branding.ts +23 -0
- package/src/btn/builders.ts +1073 -0
- package/src/btn/media-slot.ts +486 -0
- package/src/btn/media-source.ts +189 -0
- package/src/btn/sharp-loader.ts +23 -0
- package/src/btn/thumbnail.ts +182 -0
- package/src/btn/validators.ts +237 -0
- package/src/btn.ts +8 -0
- package/src/core/async-send.ts +28 -0
- package/src/core/base-builder.ts +104 -0
- package/src/core/errors.ts +82 -0
- package/src/download.ts +212 -0
- package/src/index.ts +229 -0
- package/src/integration/augment.ts +262 -0
- package/src/integration/auto.ts +103 -0
- package/src/integration/index.ts +8 -0
- package/src/integration/methods.ts +45 -0
- package/src/interactive.ts +188 -0
- package/src/media-gate.ts +499 -0
- package/src/message/album.ts +187 -0
- package/src/message/contact.ts +170 -0
- package/src/message/forward.ts +123 -0
- package/src/message/index.ts +83 -0
- package/src/message/link-preview.ts +148 -0
- package/src/message/location.ts +150 -0
- package/src/message/media.ts +323 -0
- package/src/message/poll.ts +158 -0
- package/src/message/reaction.ts +133 -0
- package/src/message/sticker.ts +100 -0
- package/src/message/target.ts +38 -0
- package/src/message/text.ts +61 -0
- package/src/message/vcard.ts +36 -0
- package/src/message/webp.ts +78 -0
- package/src/payloads.ts +204 -0
- package/src/serialize.ts +180 -0
- package/src/status.ts +29 -0
- package/src/zapo-client.ts +84 -0
- package/test/airich-inline.test.ts +200 -0
- package/test/airich-primitives.test.ts +226 -0
- package/test/airich-tokenizer.test.ts +145 -0
- package/test/airich.golden.test.ts +406 -0
- package/test/airich.test.ts +1006 -0
- package/test/btn-button.test.ts +416 -0
- package/test/btn-header.test.ts +646 -0
- package/test/btn-legacy.test.ts +342 -0
- package/test/btn-lifecycle.test.ts +295 -0
- package/test/btn-list.test.ts +261 -0
- package/test/btn-media-source.test.ts +150 -0
- package/test/btn-thumbnail.test.ts +160 -0
- package/test/builder-compat.test.ts +264 -0
- package/test/helpers.ts +27 -0
- package/test/hybrid-airich.test.ts +345 -0
- package/test/hybrid-client.test.ts +239 -0
- package/test/hybrid-errors.test.ts +557 -0
- package/test/hybrid-interactive.test.ts +455 -0
- package/test/hybrid.golden.test.ts +349 -0
- package/test/hybrid.test.ts +479 -0
- package/test/integration-auto.test.ts +159 -0
- package/test/integration.fakeserver.test.ts +440 -0
- package/test/media-gate.test.ts +215 -0
- package/test/message-album.test.ts +145 -0
- package/test/message-builders.test.ts +401 -0
- package/test/message-media.test.ts +303 -0
- package/test/message.fakeserver.test.ts +284 -0
- package/test/message.golden.test.ts +254 -0
- package/test/serializer.test.ts +448 -0
- package/tsconfig.json +26 -0
- package/tsconfig.test.json +10 -0
package/README.md
CHANGED
|
@@ -1,3 +1,533 @@
|
|
|
1
|
-
#
|
|
1
|
+
# @kyyinfinite/zapo-message
|
|
2
2
|
|
|
3
|
-
|
|
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
|
+
}
|