@wazzapi/wazzapi 0.2.0

package/docs/README.md

@@ -0,0 +1,61 @@
+# WazzAPI Node SDK Docs
+
+Official documentation for the WazzAPI Node.js and TypeScript SDK.
+
+## What you can do
+
+- Send direct WhatsApp messages, including text, image, video, voice, document, location, contact cards, buttons, and lists
+- Manage WhatsApp groups, including participants, invite links, and group settings
+- Manage contacts and contact groups
+- Create, preview, update, and delete reusable templates
+- Verify and parse incoming webhook payloads
+- Download and decrypt encrypted WhatsApp media files
+- Work with typed request and response models in TypeScript
+
+## Requirements
+
+- Node.js 20+
+- A WazzAPI account
+- A WazzAPI API key
+
+## Install
+
+With Bun:
+
+```bash
+bun add @wazzapi/wazzapi
+```
+
+With npm:
+
+```bash
+npm install @wazzapi/wazzapi
+```
+
+## Quick start
+
+```ts
+import { WazzapiClient } from "@wazzapi/wazzapi";
+
+const client = new WazzapiClient({ apiKey: process.env.WAZZAPI_API_KEY });
+
+const response = await client.messages.send({
+  phone_number: "+6281234567890",
+  whatsapp_account_id: "your-whatsapp-account-id",
+  content: "Hello from WazzAPI!",
+});
+
+console.log(response.message_id);
+```
+
+## Topics
+
+- [Authentication](./authentication.md)
+- [Client](./client.md)
+- [Messages](./messages.md)
+- [Groups](./groups.md)
+- [Contacts](./contacts.md)
+- [Templates](./templates.md)
+- [Webhooks](./webhooks.md)
+- [Media](./media.md)
+- [Errors](./errors.md)

package/docs/authentication.md

@@ -0,0 +1,37 @@
+# Authentication
+
+The SDK authenticates using an API key. You can find yours in the WazzAPI dashboard.
+
+## API key
+
+Pass it directly to the client:
+
+```ts
+import { WazzapiClient } from "@wazzapi/wazzapi";
+
+const client = new WazzapiClient({ apiKey: "your-api-key" });
+```
+
+Or load it from the environment:
+
+```ts
+import { WazzapiClient } from "@wazzapi/wazzapi";
+
+const client = new WazzapiClient({
+  apiKey: process.env.WAZZAPI_API_KEY,
+});
+```
+
+The SDK automatically prefixes the key with `Bearer` if it is not already present.
+
+## Webhook secret
+
+If you plan to receive webhooks, you also need your webhook secret:
+
+```ts
+import { WebhookHandler } from "@wazzapi/wazzapi";
+
+const handler = new WebhookHandler(process.env.WAZZAPI_WEBHOOK_SECRET || "");
+```
+
+You can find the webhook secret in the WazzAPI dashboard under webhook settings.

package/docs/client.md

@@ -0,0 +1,68 @@
+# Client
+
+`WazzapiClient` is the main entry point for all API calls.
+
+## Initialize
+
+```ts
+import { WazzapiClient } from "@wazzapi/wazzapi";
+
+const client = new WazzapiClient({ apiKey: "your-api-key" });
+```
+
+## Close the client
+
+The SDK uses `fetch`, so there is no long-lived HTTP session to tear down, but `close()` is available for API symmetry:
+
+```ts
+await client.close();
+```
+
+## Custom base URL
+
+For testing or custom deployments:
+
+```ts
+const client = new WazzapiClient({
+  baseUrl: "https://api.example.com",
+  apiKey: "your-api-key",
+});
+```
+
+## Custom timeout
+
+```ts
+const client = new WazzapiClient({
+  apiKey: "your-api-key",
+  timeout: 60_000,
+});
+```
+
+## Bring your own fetch
+
+```ts
+const client = new WazzapiClient({
+  apiKey: "your-api-key",
+  fetch: async (input, init) => fetch(input, init),
+});
+```
+
+## Custom headers
+
+```ts
+const client = new WazzapiClient({
+  apiKey: "your-api-key",
+  headers: {
+    "X-SDK-Example": "custom-header",
+  },
+});
+```
+
+## Resources
+
+The client exposes resources as properties:
+
+- `client.contacts` — contact and contact-group management
+- `client.groups` — WhatsApp group management
+- `client.messages` — send and manage messages
+- `client.templates` — template management

package/docs/contacts.md

@@ -0,0 +1,194 @@
+# Contacts
+
+Manage contacts and contact groups.
+
+## List contacts
+
+```ts
+import { WazzapiClient } from "@wazzapi/wazzapi";
+
+const client = new WazzapiClient({ apiKey: process.env.WAZZAPI_API_KEY });
+const response = await client.contacts.list({ limit: 50, search: "alice" });
+
+for (const contact of response.contacts) {
+  console.log(contact.name, contact.phone_number);
+}
+```
+
+## Get a contact
+
+```ts
+const contact = await client.contacts.get("contact-id");
+console.log(contact.phone_number, contact.tags);
+```
+
+## Create a contact
+
+```ts
+const contact = await client.contacts.create({
+  phone_number: "+6281234567890",
+  name: "Alice",
+  tags: ["customer", "vip"],
+});
+
+console.log(contact.id);
+```
+
+## Update a contact
+
+```ts
+const contact = await client.contacts.update("contact-id", {
+  name: "Alice Smith",
+  tags: ["customer"],
+});
+
+console.log(contact.name);
+```
+
+## Delete a contact
+
+```ts
+await client.contacts.delete("contact-id");
+```
+
+## Bulk delete
+
+```ts
+const result = await client.contacts.bulkDelete({
+  contact_ids: ["id-1", "id-2"],
+});
+
+console.log(result.deleted);
+```
+
+## Contact groups
+
+### List groups
+
+```ts
+const response = await client.contacts.listGroups({ limit: 20 });
+
+for (const group of response.groups) {
+  console.log(group.name, group.member_count);
+}
+```
+
+### Create a group
+
+```ts
+const group = await client.contacts.createGroup({
+  name: "VIP Customers",
+  description: "Top tier",
+});
+
+console.log(group.id);
+```
+
+### Get a group with members
+
+```ts
+const response = await client.contacts.getGroup("group-id");
+console.log(response.group.name);
+
+for (const contact of response.contacts) {
+  console.log(contact.name);
+}
+```
+
+### Update a group
+
+```ts
+const group = await client.contacts.updateGroup("group-id", {
+  name: "Updated Name",
+});
+
+console.log(group.name);
+```
+
+### Delete a group
+
+```ts
+await client.contacts.deleteGroup("group-id");
+```
+
+### Add contacts to a group
+
+```ts
+const result = await client.contacts.addToGroup("group-id", {
+  contact_ids: ["contact-1", "contact-2"],
+});
+
+console.log(result.added);
+```
+
+### Remove contacts from a group
+
+```ts
+const result = await client.contacts.removeFromGroup("group-id", {
+  contact_ids: ["contact-1"],
+});
+
+console.log(result.added);
+```
+
+## Import and export
+
+### Import from CSV
+
+```ts
+const result = await client.contacts.importCsv({
+  csv_content: "phone_number,name\n+6281234567890,Alice",
+  skip_duplicates: true,
+});
+
+console.log(result.imported, result.updated, result.errors);
+```
+
+### Export to CSV
+
+```ts
+const result = await client.contacts.exportCsv({ group_id: "group-id" });
+console.log(result.csv_data);
+```
+
+### Get import template
+
+```ts
+const template = await client.contacts.importTemplate();
+console.log(template);
+```
+
+## Sync contacts from WhatsApp
+
+### Start sync
+
+```ts
+const result = await client.contacts.sync({
+  whatsapp_account_id: "wa-123",
+  sync_type: "full",
+});
+
+console.log(result.job_id, result.status);
+```
+
+### Check sync status
+
+```ts
+const statuses = await client.contacts.syncStatus();
+for (const status of statuses) {
+  console.log(
+    status.account_name,
+    status.last_sync_status,
+    status.contacts_synced_count,
+  );
+}
+```
+
+### Sync history
+
+```ts
+const response = await client.contacts.syncHistory({ limit: 10 });
+for (const item of response.history) {
+  console.log(item.account_name, item.status, item.contacts_count);
+}
+```

package/docs/errors.md

@@ -0,0 +1,57 @@
+# Errors
+
+The SDK throws typed error classes for API, media, and webhook failures.
+
+## `WazzapiAPIError`
+
+Raised when the API returns a non-2xx response:
+
+```ts
+import { WazzapiAPIError, WazzapiClient } from "@wazzapi/wazzapi";
+
+try {
+  const client = new WazzapiClient({ apiKey: process.env.WAZZAPI_API_KEY });
+  await client.messages.get("missing-message-id");
+} catch (error) {
+  if (error instanceof WazzapiAPIError) {
+    console.log(error.statusCode);
+    console.log(error.message);
+    console.log(error.details);
+  }
+}
+```
+
+## `WazzapiMediaError`
+
+Raised when media download or decryption fails:
+
+```ts
+import { WazzapiMediaError, downloadMedia } from "@wazzapi/wazzapi";
+
+try {
+  await downloadMedia("https://example.com/missing.jpg", "media-key", "image/jpeg");
+} catch (error) {
+  if (error instanceof WazzapiMediaError) {
+    console.log(error.message);
+  }
+}
+```
+
+## Webhook errors
+
+The webhook helpers raise these classes:
+
+- `WazzapiWebhookError`
+- `WazzapiWebhookVerificationError`
+- `WazzapiWebhookParseError`
+
+## Error hierarchy
+
+```text
+WazzapiError
+├── WazzapiAPIError
+├── WazzapiMediaError
+└── WazzapiWebhookError
+    ├── WazzapiWebhookVerificationError
+    └── WazzapiWebhookParseError
+```

package/docs/groups.md

@@ -0,0 +1,233 @@
+# Groups
+
+Manage WhatsApp groups.
+
+## List groups
+
+```ts
+import { WazzapiClient } from "@wazzapi/wazzapi";
+
+const client = new WazzapiClient({ apiKey: process.env.WAZZAPI_API_KEY });
+const response = await client.groups.list({ session_name: "main", limit: 50 });
+
+for (const group of response.groups) {
+  console.log(group.id, group.name, group.participants_count);
+}
+```
+
+## Get a group
+
+```ts
+const group = await client.groups.get("123456789@g.us", {
+  session_name: "main",
+});
+
+console.log(group.name, group.description);
+```
+
+## Get group participants
+
+```ts
+const response = await client.groups.getParticipants("123456789@g.us", {
+  session_name: "main",
+});
+
+for (const participant of response.participants) {
+  console.log(participant.id, participant.is_admin, participant.is_super_admin);
+}
+```
+
+## Create a group
+
+```ts
+const result = await client.groups.create({
+  session_name: "main",
+  name: "My New Group",
+  participants: ["+6281234567890", "+6281234567891"],
+});
+
+console.log(result.jid);
+```
+
+## Send text to a group
+
+```ts
+const result = await client.groups.sendText({
+  session_name: "main",
+  group_jid: "123456789@g.us",
+  text: "Hello everyone!",
+});
+
+console.log(result.message_id);
+```
+
+## Send media to a group
+
+```ts
+const result = await client.groups.sendMedia({
+  session_name: "main",
+  group_jid: "123456789@g.us",
+  media_url: "https://example.com/image.jpg",
+  media_type: "image",
+  caption: "Group photo",
+});
+
+console.log(result.message_id);
+```
+
+## Add a participant
+
+```ts
+const result = await client.groups.addParticipant("123456789@g.us", {
+  session_name: "main",
+  participant_jid: "6281234567890@s.whatsapp.net",
+});
+
+console.log(result.details);
+```
+
+## Remove a participant
+
+```ts
+const result = await client.groups.removeParticipant("123456789@g.us", {
+  session_name: "main",
+  participant_jid: "6281234567890@s.whatsapp.net",
+});
+
+console.log(result.details);
+```
+
+## Update participants
+
+```ts
+const result = await client.groups.updateParticipants({
+  session_name: "main",
+  group_jid: "123456789@g.us",
+  action: "promote",
+  participants: ["6281234567890@s.whatsapp.net"],
+});
+
+console.log(result.details);
+```
+
+## Get invite link
+
+```ts
+const result = await client.groups.getInviteLink("123456789@g.us", {
+  session_name: "main",
+});
+
+console.log(result.invite_link);
+```
+
+## Get invite info
+
+```ts
+const result = await client.groups.getInviteInfo({
+  session_name: "main",
+  invite_link: "https://chat.whatsapp.com/AbCdEfGh",
+});
+
+console.log(result.jid, result.name);
+```
+
+## Join a group
+
+```ts
+const result = await client.groups.join({
+  session_name: "main",
+  invite_link: "https://chat.whatsapp.com/AbCdEfGh",
+});
+
+console.log(result.details);
+```
+
+## Leave a group
+
+```ts
+const result = await client.groups.leave("123456789@g.us", {
+  session_name: "main",
+});
+
+console.log(result.details);
+```
+
+## Set group name
+
+```ts
+const result = await client.groups.setName("123456789@g.us", {
+  session_name: "main",
+  name: "New Group Name",
+});
+
+console.log(result.details);
+```
+
+## Set group topic
+
+```ts
+const result = await client.groups.setTopic("123456789@g.us", {
+  session_name: "main",
+  topic: "New topic description",
+});
+
+console.log(result.details);
+```
+
+## Set group photo
+
+```ts
+const result = await client.groups.setPhoto("123456789@g.us", {
+  session_name: "main",
+  image_data_uri: "data:image/png;base64,iVBORw0KGgo...",
+});
+
+console.log(result.details);
+```
+
+## Remove group photo
+
+```ts
+const result = await client.groups.removePhoto("123456789@g.us", {
+  session_name: "main",
+});
+
+console.log(result.details);
+```
+
+## Set announce mode
+
+Only admins can send messages when announce mode is enabled.
+
+```ts
+const result = await client.groups.setAnnounce("123456789@g.us", {
+  session_name: "main",
+  announce: true,
+});
+
+console.log(result.details);
+```
+
+## Set locked mode
+
+Only admins can edit group info when locked mode is enabled.
+
+```ts
+const result = await client.groups.setLocked("123456789@g.us", {
+  session_name: "main",
+  locked: true,
+});
+
+console.log(result.details);
+```
+
+## Set ephemeral messages
+
+```ts
+const result = await client.groups.setEphemeral("123456789@g.us", {
+  session_name: "main",
+  duration: "24h",
+});
+
+console.log(result.details);
+```

package/docs/media.md

@@ -0,0 +1,38 @@
+# Media
+
+Download and decrypt encrypted WhatsApp media files.
+
+## Download media
+
+```ts
+import { downloadMedia } from "@wazzapi/wazzapi";
+
+const result = await downloadMedia(
+  "https://example.com/media",
+  "your-media-key",
+  "image/jpeg",
+  {
+    file_name: "photo.jpg",
+    file_sha256: "expected-plain-sha256-base64",
+    file_enc_sha256: "expected-encrypted-sha256-base64",
+  },
+);
+
+console.log(result.file_name);
+console.log(result.mimetype);
+console.log(result.file_size);
+```
+
+## `MediaDownloadResult`
+
+- `content` — decrypted file contents as `Buffer`
+- `mimetype` — MIME type passed to the downloader
+- `file_name` — file name from options or fallback name
+- `file_size` — decrypted content size in bytes
+
+## Low-level helpers
+
+If you need lower-level primitives, the SDK also exports:
+
+- `_decryptWaMedia()` / `_decrypt_wa_media()`
+- `_mediaInfoBytes()` / `_media_info_bytes()`