{"_id":"z-api-sdk","name":"z-api-sdk","dist-tags":{"latest":"0.0.1"},"versions":{"0.0.1":{"name":"z-api-sdk","version":"0.0.1","description":"Typed TypeScript SDK for the Z-API WhatsApp API, with an ergonomic resource-oriented client.","keywords":["z-api","zapi","whatsapp","whatsapp-api","sdk","typescript","client"],"license":"MIT","author":{"name":"Gabriel Ribeiro","email":"gabriel.ribeiro@grupovorp.com"},"homepage":"https://github.com/garaujoribeiro/z-api-sdk#readme","repository":{"type":"git","url":"git+https://github.com/garaujoribeiro/z-api-sdk.git"},"bugs":{"url":"https://github.com/garaujoribeiro/z-api-sdk/issues"},"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"},"./package.json":"./package.json"},"sideEffects":false,"engines":{"node":">=18"},"publishConfig":{"access":"public"},"scripts":{"build":"tsup src/index.ts --format cjs,esm --dts","dev":"tsup src/index.ts --format cjs,esm --dts --watch","typecheck":"tsc --noEmit","test":"vitest run","test:watch":"vitest","prepublishOnly":"npm run typecheck && npm run test && npm run build"},"dependencies":{"axios":"^1.7.9"},"devDependencies":{"@types/node":"^25.9.1","msw":"^2.7.0","tsup":"^8.5.1","typescript":"^6.0.3","vitest":"^2.1.8"},"_id":"z-api-sdk@0.0.1","gitHead":"cfcbc998f3af33d2b20447b4aea0823fcfec3ee7","_nodeVersion":"22.18.0","_npmVersion":"10.9.3","dist":{"integrity":"sha512-lnBjtlbHLND0tSP/9nWebVr4J8Qq4Hu8FscNHwLT/II0o9FLgGErIDWCtdP4dkW/tudDT0by6E/VppSX977z/A==","shasum":"995c7c93d853b5c1669f347562cf76b1d30fd7cc","tarball":"https://registry.npmjs.org/z-api-sdk/-/z-api-sdk-0.0.1.tgz","fileCount":8,"unpackedSize":177091,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEQCID9NDXlgHedzIs6yZCEJ5kqODw4Fao383R2/OEhy3wGAAiBu7FH5SK5AOY0qNoVOS7U89clyyNzkxAGMrGGQsqA+Tw=="}]},"_npmUser":{"name":"garaujoribeiro","email":"garaujoribeirodev@gmail.com"},"directories":{},"maintainers":[{"name":"garaujoribeiro","email":"garaujoribeirodev@gmail.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/z-api-sdk_0.0.1_1779955731242_0.40292435708044283"},"_hasShrinkwrap":false}},"time":{"created":"2026-05-28T08:08:51.102Z","0.0.1":"2026-05-28T08:08:51.396Z","modified":"2026-05-28T08:08:51.567Z"},"maintainers":[{"name":"garaujoribeiro","email":"garaujoribeirodev@gmail.com"}],"description":"Typed TypeScript SDK for the Z-API WhatsApp API, with an ergonomic resource-oriented client.","homepage":"https://github.com/garaujoribeiro/z-api-sdk#readme","keywords":["z-api","zapi","whatsapp","whatsapp-api","sdk","typescript","client"],"repository":{"type":"git","url":"git+https://github.com/garaujoribeiro/z-api-sdk.git"},"author":{"name":"Gabriel Ribeiro","email":"gabriel.ribeiro@grupovorp.com"},"bugs":{"url":"https://github.com/garaujoribeiro/z-api-sdk/issues"},"license":"MIT","readme":"# z-api-sdk\n\nA typed TypeScript client for the [Z-API](https://z-api.io) WhatsApp API, with an ergonomic, resource-oriented design inspired by the Anthropic SDK.\n\n```ts\nimport { ZAPI } from \"z-api-sdk\";\n\nconst client = new ZAPI({\n  instanceId: process.env.ZAPI_INSTANCE_ID, // defaults to this env var; can be omitted\n  token: process.env.ZAPI_TOKEN,\n  clientToken: process.env.ZAPI_CLIENT_TOKEN,\n});\n\nconst res = await client.messages.sendText({\n  phone: \"5511999999999\",\n  message: \"Hello from the SDK\",\n});\nconsole.log(res.messageId);\n```\n\n## Installation\n\n```bash\nnpm install z-api-sdk\n```\n\n## Configuration\n\nThe client needs three credentials from your Z-API dashboard. Each can be passed\nto the constructor or read from an environment variable:\n\n| Option        | Env var              | Required |\n| ------------- | -------------------- | -------- |\n| `instanceId`  | `ZAPI_INSTANCE_ID`   | yes      |\n| `token`       | `ZAPI_TOKEN`         | yes      |\n| `clientToken` | `ZAPI_CLIENT_TOKEN`  | recommended (sent as the `Client-Token` header) |\n\nAdditional options: `baseURL` (default `https://api.z-api.io`), `timeout` (ms,\ndefault `60000`), and `maxRetries` (default `2`; retries network errors, `429`,\nand `5xx` with exponential backoff).\n\n```ts\nconst client = new ZAPI(); // reads all three from the environment\n```\n\n## Resources\n\nThe client exposes resources as properties. Each method maps to a Z-API endpoint\nand returns a `Promise`.\n\n### messages\n\n```ts\nawait client.messages.sendText({ phone, message });\nawait client.messages.sendImage({ phone, image: \"https://…/pic.png\", caption });\nawait client.messages.sendAudio({ phone, audio });\nawait client.messages.sendVideo({ phone, video, caption });\nawait client.messages.sendDocument({ extension: \"pdf\", phone, document, fileName });\nawait client.messages.sendLocation({ phone, title, address, latitude, longitude });\nawait client.messages.sendContact({ phone, contactName, contactPhone });\nawait client.messages.sendLink({ phone, message, image, linkUrl, title, linkDescription });\nawait client.messages.sendReaction({ phone, messageId, reaction: \"👍\" });\nawait client.messages.removeReaction({ phone, messageId });\nawait client.messages.forward({ phone, messageId, messagePhone });\nawait client.messages.sendButtonList({ phone, message, buttonList });\nawait client.messages.sendOptionList({ phone, message, optionList });\nawait client.messages.sendPoll({ phone, message, poll: [{ name: \"A\" }, { name: \"B\" }] });\nawait client.messages.readMessage({ phone, messageId });\nawait client.messages.delete({ phone, messageId, owner: true });\n```\n\n### instance\n\n```ts\nawait client.instance.getStatus();\nawait client.instance.getDevice();\nawait client.instance.getQrCodeImage();\nawait client.instance.restart();\nawait client.instance.disconnect();\nawait client.instance.updateName(\"My Bot\");\nawait client.instance.updateProfileName(\"My Bot\");\n```\n\n### chats\n\n```ts\nawait client.chats.list({ page: 1, pageSize: 50 });\nawait client.chats.get(\"5511999999999\");\nawait client.chats.modify({ phone: \"5511999999999\", action: \"archive\" });\nawait client.chats.setExpiration({ phone: \"5511999999999\", chatExpiration: \"7_DAYS\" });\n```\n\n### contacts\n\n```ts\nawait client.contacts.list({ page: 1, pageSize: 100 });\nawait client.contacts.get(\"5511999999999\");\nawait client.contacts.phoneExists(\"5511999999999\");\nawait client.contacts.phoneExistsBatch({ phones: [\"5511999999999\"] });\nawait client.contacts.getProfilePicture(\"5511999999999\");\nawait client.contacts.modifyBlocked({ phone: \"5511999999999\", action: \"block\" });\n```\n\n### groups\n\n```ts\nawait client.groups.create({ groupName: \"Team\", phones: [\"5511999999999\"] });\nawait client.groups.addParticipant({ groupId, phones });\nawait client.groups.removeParticipant({ groupId, phones });\nawait client.groups.addAdmin({ groupId, phones });\nawait client.groups.getMetadata(groupPhone);\nawait client.groups.updateSettings({ phone: groupId, adminOnlyMessage: true });\n```\n\n### webhooks\n\n```ts\nawait client.webhooks.updateReceived(\"https://my.app/webhook\");\nawait client.webhooks.updateMessageStatus(\"https://my.app/status\");\nawait client.webhooks.updateConnected(\"https://my.app/connected\");\n```\n\n## Partners (multi-instance management)\n\nPartner/integrator accounts manage instances at the account level using a\n**partner token** (`Authorization: Bearer`) against the API root — a different\nauth scheme and base path than the per-instance client. Use `ZAPIPartner` to\ncreate/list/subscribe/cancel instances, then construct a normal `ZAPI` from the\nreturned credentials.\n\n```ts\nimport { ZAPIPartner, ZAPI } from \"z-api-sdk\";\n\nconst partner = new ZAPIPartner({\n  partnerToken: process.env.ZAPI_PARTNER_TOKEN, // or set the env var and omit\n});\n\nconst created = await partner.createInstance({\n  name: \"Customer A\",\n  businessDevice: true,\n  receivedCallbackUrl: \"https://my.app/received\",\n});\n\n// Persist created.id / created.token to your DB, then talk to the instance:\nconst client = new ZAPI({ instanceId: created.id, token: created.token });\n\nawait partner.listInstances({ page: 1, pageSize: 15 });\nawait partner.subscribe({ instanceId: created.id!, instanceToken: created.token! });\nawait partner.cancel({ instanceId: created.id!, instanceToken: created.token! });\n```\n\n`partnerToken` falls back to the `ZAPI_PARTNER_TOKEN` environment variable.\n\n## Error handling\n\nFailed requests reject with typed errors. All extend `ZAPIError`.\n\n```ts\nimport { ZAPI, NotFoundError, RateLimitError, APIError } from \"z-api-sdk\";\n\ntry {\n  await client.messages.sendText({ phone, message });\n} catch (err) {\n  if (err instanceof RateLimitError) {\n    // 429 — back off\n  } else if (err instanceof NotFoundError) {\n    // 404\n  } else if (err instanceof APIError) {\n    console.error(err.status, err.body);\n  }\n}\n```\n\n`APIError` subclasses: `BadRequestError` (400), `AuthenticationError` (401),\n`PermissionDeniedError` (403), `NotFoundError` (404), `ConflictError` (409),\n`UnprocessableEntityError` (422), `RateLimitError` (429), `InternalServerError`\n(5xx). Network/timeout failures throw `APIConnectionError` / `APITimeoutError`.\n\n## Per-request options\n\nEvery method accepts an optional second argument to override defaults for that call:\n\n```ts\nawait client.messages.sendText(\n  { phone, message },\n  { timeout: 5000, maxRetries: 0, signal: controller.signal },\n);\n```\n\n## Full coverage\n\nThe SDK wraps the entire Z-API collection across these resources:\n\n`messages`, `instance`, `chats`, `contacts`, `groups`, `webhooks`, `calls`,\n`privacy`, `mobile`, `status`, `queue`, `communities`, `newsletters`,\n`business`, plus the account-level `ZAPIPartner` client.\n\nSee [USAGE.md](./USAGE.md) for an example of every method and a complete\ncoverage table.\n\n## Development\n\n```bash\nnpm install\nnpm run typecheck   # tsc --noEmit\nnpm test            # vitest (HTTP mocked with MSW)\nnpm run build       # tsup → dist/ (ESM + CJS + .d.ts)\n```\n","readmeFilename":"README.md","_rev":"1-f8b56ebeb9140c27cc3ded2fefea20ed"}