@wazzapi/wazzapi 0.2.0

package/docs/messages.md

@@ -0,0 +1,151 @@
+# Messages
+
+Send and manage WhatsApp messages.
+
+## Send a text message
+
+```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);
+```
+
+## Send media
+
+```ts
+await client.messages.sendImage({
+  phone_number: "+6281234567890",
+  whatsapp_account_id: "your-whatsapp-account-id",
+  media_url: "https://example.com/image.jpg",
+  caption: "Check this out",
+});
+
+await client.messages.sendVideo({
+  phone_number: "+6281234567890",
+  whatsapp_account_id: "your-whatsapp-account-id",
+  media_url: "https://example.com/video.mp4",
+  caption: "Watch this",
+});
+
+await client.messages.sendDocument({
+  phone_number: "+6281234567890",
+  whatsapp_account_id: "your-whatsapp-account-id",
+  media_url: "https://example.com/doc.pdf",
+});
+
+await client.messages.sendVoice({
+  phone_number: "+6281234567890",
+  whatsapp_account_id: "your-whatsapp-account-id",
+  media_url: "https://example.com/voice.ogg",
+});
+```
+
+## Send a location
+
+```ts
+await client.messages.sendLocation({
+  phone_number: "+6281234567890",
+  whatsapp_account_id: "your-whatsapp-account-id",
+  latitude: -6.2088,
+  longitude: 106.8456,
+  location_title: "Jakarta",
+  location_address: "Indonesia",
+});
+```
+
+## Send a contact card
+
+```ts
+await client.messages.sendContact({
+  phone_number: "+6281234567890",
+  whatsapp_account_id: "your-whatsapp-account-id",
+  contacts: [{ name: "Alice", phone_number: "+6281234567891" }],
+});
+```
+
+## Send interactive buttons
+
+```ts
+await client.messages.sendButtons({
+  phone_number: "+6281234567890",
+  whatsapp_account_id: "your-whatsapp-account-id",
+  body: "Choose an option:",
+  buttons: [
+    { id: "yes", title: "Yes" },
+    { id: "no", title: "No" },
+  ],
+  footer: "Powered by WazzAPI",
+});
+```
+
+## Send an interactive list
+
+```ts
+await client.messages.sendList({
+  phone_number: "+6281234567890",
+  whatsapp_account_id: "your-whatsapp-account-id",
+  body: "Select a plan:",
+  button_text: "View plans",
+  sections: [
+    {
+      title: "Plans",
+      rows: [
+        { id: "basic", title: "Basic", description: "$9/mo" },
+        { id: "pro", title: "Pro", description: "$29/mo" },
+      ],
+    },
+  ],
+});
+```
+
+## List messages
+
+```ts
+const response = await client.messages.list({ limit: 50, status: "sent" });
+
+for (const message of response.messages) {
+  console.log(message.id, message.status, message.phone_number);
+}
+```
+
+## Get a message
+
+```ts
+const message = await client.messages.get("msg-id");
+console.log(message.status, message.content);
+```
+
+## Retry a failed message
+
+```ts
+const result = await client.messages.retry("msg-id");
+console.log(result.status);
+```
+
+## Cancel a scheduled message
+
+```ts
+const result = await client.messages.cancel("msg-id");
+console.log(result.status);
+```
+
+## Lookup by WhatsApp message ID
+
+```ts
+const message = await client.messages.lookup("wamid.xxx");
+console.log(message.id);
+```
+
+## Message stats
+
+```ts
+const stats = await client.messages.stats();
+console.log(stats.total, stats.by_status);
+```

package/docs/templates.md

@@ -0,0 +1,76 @@
+# Templates
+
+Create and manage reusable message templates.
+
+## List templates
+
+```ts
+import { WazzapiClient } from "@wazzapi/wazzapi";
+
+const client = new WazzapiClient({ apiKey: process.env.WAZZAPI_API_KEY });
+const response = await client.templates.list({
+  limit: 20,
+  category: "marketing",
+});
+
+for (const template of response.data) {
+  console.log(template.name, template.variables);
+}
+```
+
+## Get a template
+
+```ts
+const template = await client.templates.get("template-id");
+console.log(template.content, template.variables);
+```
+
+## Create a template
+
+```ts
+const template = await client.templates.create({
+  name: "welcome-message",
+  category: "marketing",
+  content: "Hi {{name}}, welcome to WazzAPI!",
+});
+
+console.log(template.id);
+```
+
+## Update a template
+
+```ts
+const template = await client.templates.update("template-id", {
+  content: "Hi {{name}}, welcome! Your code is {{code}}.",
+});
+
+console.log(template.content);
+```
+
+## Delete a template
+
+```ts
+await client.templates.delete("template-id");
+```
+
+## Preview a template
+
+```ts
+const preview = await client.templates.preview({
+  content: "Hi {{name}}, your code is {{code}}.",
+  custom_variables: { name: "Alice", code: "WZ-1234" },
+});
+
+console.log(preview.preview);
+console.log(preview.missing_variables);
+```
+
+## Built-in variables
+
+```ts
+const response = await client.templates.builtinVariables();
+
+for (const variable of response.variables) {
+  console.log(variable.name, variable.description, variable.example);
+}
+```

package/docs/webhooks.md

@@ -0,0 +1,101 @@
+# Webhooks
+
+WazzAPI sends webhook events to your endpoint for incoming messages, message status updates, and device status changes.
+
+## Verify and parse
+
+Always verify the signature before parsing the payload:
+
+```ts
+import { WebhookHandler } from "@wazzapi/wazzapi";
+
+const handler = new WebhookHandler("your-webhook-secret");
+const webhook = handler.verifyAndParse(rawBody, request.headers);
+
+console.log(webhook.event_type);
+console.log(webhook.data);
+```
+
+## Headers
+
+WazzAPI sends these headers with every webhook:
+
+- `X-Wazzapi-Signature` — HMAC-SHA256 signature of the raw body
+- `X-Wazzapi-Event` — event type such as `message.received`
+- `X-Wazzapi-Event-ID` — unique event ID
+
+## Supported events
+
+### Message events
+
+- `message.received` — incoming message
+- `message.sent` — outbound message accepted by WhatsApp
+- `message.delivered` — outbound message delivered
+- `message.read` — outbound message read by recipient
+- `message.failed` — outbound message failed
+
+### Device events
+
+- `device.connected` — WhatsApp device connected
+- `device.disconnected` — WhatsApp device disconnected
+
+## Working with message webhooks
+
+```ts
+import { WebhookHandler } from "@wazzapi/wazzapi";
+import type { PublicMessageWebhook } from "@wazzapi/wazzapi";
+
+const handler = new WebhookHandler("your-webhook-secret");
+const webhook = handler.verifyAndParse(rawBody, request.headers);
+
+if (webhook.event_type.startsWith("message.")) {
+  const messageWebhook = webhook as PublicMessageWebhook;
+  console.log(messageWebhook.data.phone_number);
+  console.log(messageWebhook.data.status);
+  console.log(messageWebhook.data.message_type);
+}
+```
+
+## Working with device webhooks
+
+```ts
+import { WebhookHandler } from "@wazzapi/wazzapi";
+import type { PublicDeviceWebhook } from "@wazzapi/wazzapi";
+
+const handler = new WebhookHandler("your-webhook-secret");
+const webhook = handler.verifyAndParse(rawBody, request.headers);
+
+if (webhook.event_type.startsWith("device.")) {
+  const deviceWebhook = webhook as PublicDeviceWebhook;
+  console.log(deviceWebhook.data.status);
+  console.log(deviceWebhook.data.reason);
+}
+```
+
+## Parse only
+
+For debugging or if you handle verification separately:
+
+```ts
+const handler = new WebhookHandler("your-webhook-secret");
+const webhook = handler.parse(rawBody);
+console.log(webhook.event_type);
+```
+
+## Low-level signature verification
+
+```ts
+import {
+  generateWebhookSignature,
+  verifyWebhookSignature,
+} from "@wazzapi/wazzapi";
+
+const expected = generateWebhookSignature(rawBody, "your-webhook-secret");
+const isValid = verifyWebhookSignature(
+  rawBody,
+  request.headers["x-wazzapi-signature"] as string,
+  "your-webhook-secret",
+);
+
+console.log(expected, isValid);
+```

package/examples/create-template.ts

@@ -0,0 +1,10 @@
+import { WazzapiClient } from "../src";
+
+const client = new WazzapiClient({ apiKey: process.env.WAZZAPI_API_KEY });
+const template = await client.templates.create({
+	name: "welcome-message",
+	category: "marketing",
+	content: "Hi {{name}}, welcome to WazzAPI!",
+});
+
+console.log(template);

package/examples/list-contacts.ts

@@ -0,0 +1,8 @@
+import { WazzapiClient } from "../src";
+
+const client = new WazzapiClient({ apiKey: process.env.WAZZAPI_API_KEY });
+const response = await client.contacts.list({ limit: 20, search: "alice" });
+
+response.contacts.forEach((contact) => {
+	console.log(contact);
+});

package/examples/preview-template.ts

@@ -0,0 +1,9 @@
+import { WazzapiClient } from "../src";
+
+const client = new WazzapiClient({ apiKey: process.env.WAZZAPI_API_KEY });
+const preview = await client.templates.preview({
+	content: "Hi {{name}}, your code is {{code}}.",
+	custom_variables: { name: "Alice", code: "WZ-1234" },
+});
+
+console.log(preview);

package/examples/send-message.ts

@@ -0,0 +1,10 @@
+import { WazzapiClient } from "../src";
+
+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);

package/examples/verify-webhook.ts

@@ -0,0 +1,33 @@
+import {
+	EVENT_HEADER,
+	EVENT_ID_HEADER,
+	SIGNATURE_HEADER,
+	WebhookHandler,
+} from "../src";
+
+const secret = process.env.WAZZAPI_WEBHOOK_SECRET || "your-webhook-secret";
+const handler = new WebhookHandler(secret);
+const payload = JSON.stringify({
+	id: "webhook_1",
+	event_type: "message.received",
+	timestamp: "2026-04-26T09:15:30Z",
+	organization_id: "org_1",
+	webhook_id: "wh_1",
+	data: {
+		message_id: "msg_1",
+		phone_number: "6281234567890",
+		status: "delivered",
+		direction: "inbound",
+		message_type: "text",
+		whatsapp_account_id: "wa_1",
+	},
+});
+
+const headers = {
+	[SIGNATURE_HEADER]: handler.generateSignature(payload),
+	[EVENT_HEADER]: "message.received",
+	[EVENT_ID_HEADER]: "evt_1",
+};
+
+const webhook = handler.verifyAndParse(payload, headers);
+console.log(webhook);

package/package.json

@@ -0,0 +1,57 @@
+{
+	"name": "@wazzapi/wazzapi",
+	"version": "0.2.0",
+	"description": "Typed Node.js SDK for WazzAPI",
+	"license": "MIT",
+	"type": "module",
+	"main": "./dist/index.cjs",
+	"module": "./dist/index.js",
+	"types": "./dist/index.d.ts",
+	"exports": {
+		".": {
+			"types": "./dist/index.d.ts",
+			"import": "./dist/index.js",
+			"require": "./dist/index.cjs"
+		}
+	},
+	"files": [
+		"dist",
+		"advanced-examples",
+		"docs",
+		"examples",
+		"README.md"
+	],
+	"engines": {
+		"node": ">=20"
+	},
+	"keywords": [
+		"api",
+		"sdk",
+		"wazzapi",
+		"webhook",
+		"whatsapp"
+	],
+	"homepage": "https://github.com/wazzapihq/wazzapi-node",
+	"repository": {
+		"type": "git",
+		"url": "git+https://github.com/wazzapihq/wazzapi-node.git"
+	},
+	"bugs": {
+		"url": "https://github.com/wazzapihq/wazzapi-node/issues"
+	},
+	"publishConfig": {
+		"access": "public"
+	},
+	"scripts": {
+		"build": "tsup src/index.ts --format esm,cjs --dts --clean",
+		"typecheck": "tsc --noEmit",
+		"test": "bun test",
+		"prepublishOnly": "bun run typecheck && bun run test && bun run build"
+	},
+	"devDependencies": {
+		"@biomejs/biome": "2.4.15",
+		"@types/node": "^24.0.0",
+		"tsup": "^8.5.0",
+		"typescript": "^5.8.3"
+	}
+}