@wazzapi/wazzapi 0.2.0

package/README.md

@@ -0,0 +1,232 @@
+# WazzAPI Node SDK
+
+Official Node.js and TypeScript SDK for WazzAPI.
+
+This package is a modern Node.js and TypeScript SDK for WazzAPI, built with Bun-powered development, typed models, ESM/CJS output, and an API surface that feels natural in TypeScript.
+
+Use it to send WhatsApp messages, manage contacts and groups, work with templates, verify webhooks, and download encrypted WhatsApp media.
+
+## Highlights
+
+- typed `WazzapiClient` with resource-based API access
+- Node.js 20, 22, and 24 support
+- ESM and CommonJS package output
+- bundled declaration files for TypeScript consumers
+- camelCase APIs for idiomatic TS usage
+- snake_case aliases for compatibility with existing naming styles
+- built-in webhook verification helpers
+- encrypted media download and decryption helpers
+- standard and advanced runnable examples
+
+## Supported Node.js versions
+
+This library supports the following Node.js implementations:
+
+- Node.js 20
+- Node.js 22
+- Node.js 24 (LTS)
+
+TypeScript consumers are supported as long as their compiler can consume the emitted declaration files.
+
+## Warning
+
+Do not use this Node.js library in a front-end application. Doing so can expose your WazzAPI credentials to end-users as part of the bundled HTML and JavaScript sent to their browser.
+
+## Installation
+
+### Bun
+
+```bash
+bun add @wazzapi/wazzapi
+```
+
+### npm
+
+```bash
+npm install @wazzapi/wazzapi
+```
+
+## Configuration
+
+The SDK uses `https://api.wazzapi.com` by default.
+
+For most integrations, you only need:
+
+- `WAZZAPI_API_KEY`
+
+If you plan to receive webhooks, also configure:
+
+- `WAZZAPI_WEBHOOK_SECRET`
+
+Advanced media examples also use:
+
+- `WAZZAPI_MEDIA_URL`
+- `WAZZAPI_MEDIA_KEY`
+- `WAZZAPI_MEDIA_MIMETYPE`
+- `WAZZAPI_MEDIA_FILE_NAME`
+- `WAZZAPI_MEDIA_SHA256`
+- `WAZZAPI_MEDIA_ENC_SHA256`
+
+## 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, response.status);
+```
+
+## API shape
+
+The main client exposes four primary resources:
+
+- `client.contacts`
+- `client.groups`
+- `client.messages`
+- `client.templates`
+
+Preferred TypeScript method names use camelCase:
+
+- `client.contacts.listGroups()`
+- `client.groups.getParticipants()`
+- `client.messages.sendImage()`
+- `client.templates.builtinVariables()`
+
+Snake_case aliases are also available:
+
+- `client.contacts.list_groups()`
+- `client.groups.get_participants()`
+- `client.messages.send_image()`
+- `client.templates.builtin_variables()`
+
+## Error handling
+
+When the API returns a non-success response, the SDK throws `WazzapiAPIError`.
+
+```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.error(error.statusCode);
+    console.error(error.message);
+    console.error(error.details);
+  }
+}
+```
+
+## Webhook verification
+
+Use `WebhookHandler` to verify the raw request body against `X-Wazzapi-Signature` before parsing JSON.
+
+```ts
+import { WebhookHandler } from "@wazzapi/wazzapi";
+
+const handler = new WebhookHandler(process.env.WAZZAPI_WEBHOOK_SECRET || "");
+const event = handler.verifyAndParse(rawBody, request.headers);
+
+console.log(event.event_type);
+console.log(event.data);
+```
+
+WazzAPI webhook headers:
+
+- `X-Wazzapi-Signature`
+- `X-Wazzapi-Event`
+- `X-Wazzapi-Event-ID`
+
+Supported webhook event families:
+
+- message events: `message.received`, `message.sent`, `message.delivered`, `message.read`, `message.failed`
+- device events: `device.connected`, `device.disconnected`
+
+## Media downloads
+
+Use `downloadMedia()` to retrieve and decrypt WhatsApp media payloads.
+
+```ts
+import { downloadMedia } from "@wazzapi/wazzapi";
+
+const file = await downloadMedia(mediaUrl, mediaKey, mimeType, {
+  file_name: "invoice.pdf",
+  file_sha256: expectedPlainSha256,
+  file_enc_sha256: expectedEncryptedSha256,
+});
+
+console.log(file.file_name, file.file_size);
+```
+
+## Examples
+
+### Standard examples
+
+- `examples/list-contacts.ts`
+- `examples/send-message.ts`
+- `examples/create-template.ts`
+- `examples/preview-template.ts`
+- `examples/verify-webhook.ts`
+
+### Advanced examples
+
+- `advanced-examples/custom-fetch.ts` — custom fetch injection for logging and telemetry
+- `advanced-examples/download-media.ts` — encrypted media download and verification
+- `advanced-examples/http-webhook-server.ts` — minimal Node HTTP webhook receiver
+
+## Documentation
+
+Topic-based documentation is available in `docs/`:
+
+- `docs/README.md`
+- `docs/authentication.md`
+- `docs/client.md`
+- `docs/messages.md`
+- `docs/groups.md`
+- `docs/contacts.md`
+- `docs/templates.md`
+- `docs/webhooks.md`
+- `docs/media.md`
+- `docs/errors.md`
+
+Repository: <https://github.com/wazzapihq/wazzapi-node>
+
+## Try it
+
+```bash
+bun run examples/list-contacts.ts
+bun run examples/send-message.ts
+bun run examples/create-template.ts
+bun run examples/preview-template.ts
+bun run examples/verify-webhook.ts
+bun run advanced-examples/custom-fetch.ts
+bun run advanced-examples/download-media.ts
+bun run advanced-examples/http-webhook-server.ts
+```
+
+## Development
+
+```bash
+bun install
+bun run typecheck
+bun test
+bun run build
+```
+
+## Package output
+
+The build produces:
+
+- `dist/index.js` — ESM bundle
+- `dist/index.cjs` — CommonJS bundle
+- `dist/index.d.ts` — TypeScript declarations

package/advanced-examples/custom-fetch.ts

@@ -0,0 +1,40 @@
+import { WazzapiClient } from "../src";
+
+function requireEnv(name: string): string {
+	const value = process.env[name];
+	if (!value) {
+		throw new Error(`Missing required environment variable: ${name}`);
+	}
+
+	return value;
+}
+
+async function loggingFetch(
+	input: string | URL | Request,
+	init?: RequestInit,
+): Promise<Response> {
+	let url: string;
+
+	if (typeof input === "string") {
+		url = input;
+	} else if (input instanceof URL) {
+		url = input.toString();
+	} else {
+		url = input.url;
+	}
+
+	console.log(`[wazzapi] ${init?.method ?? "GET"} ${url}`);
+	return fetch(input, init);
+}
+
+const client = new WazzapiClient({
+	apiKey: requireEnv("WAZZAPI_API_KEY"),
+	fetch: loggingFetch,
+	timeout: 15000,
+	headers: {
+		"X-SDK-Example": "advanced-custom-fetch",
+	},
+});
+
+const stats = await client.messages.stats();
+console.log(stats);

package/advanced-examples/download-media.ts

@@ -0,0 +1,27 @@
+import { downloadMedia } from "../src";
+
+function requireEnv(name: string): string {
+	const value = process.env[name];
+	if (!value) {
+		throw new Error(`Missing required environment variable: ${name}`);
+	}
+
+	return value;
+}
+
+const result = await downloadMedia(
+	requireEnv("WAZZAPI_MEDIA_URL"),
+	requireEnv("WAZZAPI_MEDIA_KEY"),
+	process.env.WAZZAPI_MEDIA_MIMETYPE || "application/octet-stream",
+	{
+		file_name: process.env.WAZZAPI_MEDIA_FILE_NAME || "media.bin",
+		file_sha256: process.env.WAZZAPI_MEDIA_SHA256 || undefined,
+		file_enc_sha256: process.env.WAZZAPI_MEDIA_ENC_SHA256 || undefined,
+	},
+);
+
+console.log({
+	file_name: result.file_name,
+	file_size: result.file_size,
+	mimetype: result.mimetype,
+});

package/advanced-examples/http-webhook-server.ts

@@ -0,0 +1,80 @@
+/// <reference types="node" />
+
+import { Buffer } from "node:buffer";
+import { createServer, type IncomingMessage } from "node:http";
+
+import {
+	EVENT_HEADER,
+	EVENT_ID_HEADER,
+	SIGNATURE_HEADER,
+	WebhookHandler,
+} from "../src";
+
+function requireEnv(name: string): string {
+	const value = process.env[name];
+	if (!value) {
+		throw new Error(`Missing required environment variable: ${name}`);
+	}
+
+	return value;
+}
+
+function readRequestBody(request: IncomingMessage): Promise<Buffer> {
+	return new Promise((resolve, reject) => {
+		const chunks: Buffer[] = [];
+
+		request.on("data", (chunk: Buffer | string) => {
+			chunks.push(Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk));
+		});
+		request.on("end", () => resolve(Buffer.concat(chunks)));
+		request.on("error", reject);
+	});
+}
+
+const handler = new WebhookHandler(requireEnv("WAZZAPI_WEBHOOK_SECRET"));
+const port = Number(process.env.PORT || 3000);
+
+const server = createServer(async (request, response) => {
+	if (request.method !== "POST" || request.url !== "/webhooks/wazzapi") {
+		response.statusCode = 404;
+		response.end("Not Found");
+		return;
+	}
+
+	try {
+		const rawBody = await readRequestBody(request);
+		const headers = {
+			[SIGNATURE_HEADER]: request.headers[
+				SIGNATURE_HEADER.toLowerCase()
+			] as string,
+			[EVENT_HEADER]: request.headers[EVENT_HEADER.toLowerCase()] as string,
+			[EVENT_ID_HEADER]: request.headers[
+				EVENT_ID_HEADER.toLowerCase()
+			] as string,
+		};
+
+		const event = handler.verifyAndParse(rawBody, headers);
+		console.log(`received ${event.event_type}`);
+		console.log(event.data);
+
+		response.statusCode = 200;
+		response.setHeader("content-type", "application/json");
+		response.end(JSON.stringify({ ok: true }));
+	} catch (error) {
+		console.error(error);
+		response.statusCode = 400;
+		response.setHeader("content-type", "application/json");
+		response.end(
+			JSON.stringify({
+				ok: false,
+				error: error instanceof Error ? error.message : "unknown error",
+			}),
+		);
+	}
+});
+
+server.listen(port, () => {
+	console.log(
+		`Webhook server listening on http://localhost:${port}/webhooks/wazzapi`,
+	);
+});