{"_id":"@chakrahq/chakra-chat-sdk","_rev":"3-962da81c6773cae1ef29b1c7210f4956","name":"@chakrahq/chakra-chat-sdk","dist-tags":{"latest":"1.1.3"},"versions":{"1.0.0":{"name":"@chakrahq/chakra-chat-sdk","version":"1.0.0","keywords":["chakra","chat","whatsapp","sdk","coexistence","cloud","api"],"author":{"name":"ChakraHQ"},"license":"ISC","_id":"@chakrahq/chakra-chat-sdk@1.0.0","maintainers":[{"name":"chakrahq","email":"engineering@chakrahq.com"}],"dist":{"shasum":"ffe890ff2e34c1740da4d1f5a13eb7563e5bf905","tarball":"https://registry.npmjs.org/@chakrahq/chakra-chat-sdk/-/chakra-chat-sdk-1.0.0.tgz","fileCount":8,"integrity":"sha512-ox/X8BmGYoz2BPvxS/kQT0tfBntG9f6FdXLl5r8A1va1pYOkuIPjsmroDVepZiJWDuq6kX4YrL3i2zgbHN2hkA==","signatures":[{"sig":"MEUCIQCXwuZd/WQvTAc6/uY2VQyX8gEz7i5E8VSPa+UfYriHmwIgXF+J4wf6hUljTJhCwKNPjkctIXMn40Ru6Uk8ZrVmn4k=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":76304},"main":"./dist/index.cjs","type":"module","types":"./dist/index.d.ts","module":"./dist/index.js","engines":{"node":">=18"},"exports":{".":{"import":{"types":"./dist/index.d.ts","default":"./dist/index.js"},"require":{"types":"./dist/index.d.cts","default":"./dist/index.cjs"}}},"gitHead":"455d05ed998c37e141fff2266a9c7c7b0a77f19f","scripts":{"dev":"tsup --watch","test":"vitest run","build":"tsup","typecheck":"tsc --noEmit","test:watch":"vitest"},"_npmUser":{"name":"chakrahq","email":"engineering@chakrahq.com"},"_npmVersion":"11.6.1","description":"TypeScript SDK for Chakra Chat and WhatsApp APIs","directories":{},"_nodeVersion":"24.11.0","_hasShrinkwrap":false,"devDependencies":{"tsup":"^8.5.0","vitest":"^3.2.4","typescript":"^5.8.3","@types/node":"^22.15.21"},"_npmOperationalInternal":{"tmp":"tmp/chakra-chat-sdk_1.0.0_1782723752406_0.19814085653863156","host":"s3://npm-registry-packages-npm-production"}},"1.0.1":{"name":"@chakrahq/chakra-chat-sdk","version":"1.0.1","keywords":["chakra","chat","whatsapp","sdk","coexistence","cloud","api"],"author":{"name":"ChakraHQ"},"license":"ISC","_id":"@chakrahq/chakra-chat-sdk@1.0.1","maintainers":[{"name":"chakrahq","email":"engineering@chakrahq.com"}],"dist":{"shasum":"0520d94ee8b8e4ce2f2f0bab89a8737fef9c5ee0","tarball":"https://registry.npmjs.org/@chakrahq/chakra-chat-sdk/-/chakra-chat-sdk-1.0.1.tgz","fileCount":8,"integrity":"sha512-BNSZjxQwqWO3SX/pe+9rnbojHdi+QjKmNLVThzUL7t6dkWcJ0co/YP5Mr/yuu/Ry6Nd6Qod/jepKRYHPnkVx8w==","signatures":[{"sig":"MEQCIGkIBSO5W+5x/IvGuLlkSz95R4GDkLxl5JUnnrHQssWgAiAD/UsyQcwFeKxuymy63eDaf5Gc6llNC6PuYbFpYkAlgA==","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":76987},"main":"./dist/index.cjs","type":"module","types":"./dist/index.d.ts","module":"./dist/index.js","engines":{"node":">=18"},"exports":{".":{"import":{"types":"./dist/index.d.ts","default":"./dist/index.js"},"require":{"types":"./dist/index.d.cts","default":"./dist/index.cjs"}}},"gitHead":"436cd19260e1f0b8800a3cfc6e8af0ba4c67fd55","scripts":{"dev":"tsup --watch","test":"vitest run","build":"tsup","typecheck":"tsc --noEmit","test:watch":"vitest"},"_npmUser":{"name":"chakrahq","email":"engineering@chakrahq.com"},"_npmVersion":"11.6.1","description":"TypeScript SDK for Chakra Chat and WhatsApp APIs","directories":{},"_nodeVersion":"24.11.0","_hasShrinkwrap":false,"devDependencies":{"tsup":"^8.5.0","vitest":"^3.2.4","typescript":"^5.8.3","@types/node":"^22.15.21"},"_npmOperationalInternal":{"tmp":"tmp/chakra-chat-sdk_1.0.1_1782725341741_0.800815705778813","host":"s3://npm-registry-packages-npm-production"}},"1.1.3":{"name":"@chakrahq/chakra-chat-sdk","version":"1.1.3","description":"TypeScript SDK for Chakra Chat and WhatsApp APIs","type":"module","main":"./dist/index.cjs","module":"./dist/index.js","types":"./dist/index.d.ts","exports":{".":{"import":{"types":"./dist/index.d.ts","default":"./dist/index.js"},"require":{"types":"./dist/index.d.cts","default":"./dist/index.cjs"}}},"scripts":{"build":"tsup","dev":"tsup --watch","typecheck":"tsc --noEmit","test":"vitest run","test:watch":"vitest"},"keywords":["chakra","chat","whatsapp","sdk","coexistence","cloud","api"],"author":{"name":"ChakraHQ"},"license":"ISC","devDependencies":{"@types/node":"^22.15.21","tsup":"^8.5.0","typescript":"^5.8.3","vitest":"^3.2.4"},"engines":{"node":">=18"},"gitHead":"0dee662f27279f716855f34b7e1f6036681fbbc4","_id":"@chakrahq/chakra-chat-sdk@1.1.3","_nodeVersion":"24.11.0","_npmVersion":"11.6.1","dist":{"integrity":"sha512-bACqpho+MIJHf2O1avdvgQg8NGAYdDEWeXNfRZcCno40sVryBxl7w1RWa11DIlWFkralAgpxiONm8I70ApXA8Q==","shasum":"b384bfbcdb4681f06a26754d7ee10535c0ffd550","tarball":"https://registry.npmjs.org/@chakrahq/chakra-chat-sdk/-/chakra-chat-sdk-1.1.3.tgz","fileCount":8,"unpackedSize":209535,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEUCIQC5Vg5tdYT8q7Wc9HKCgR0I8kqNISuxoXu6K0poXPXM+QIgemaZLB4PYjxUTtPnlKkn7at4H36qSgUlTN67J3hI8LM="}]},"_npmUser":{"name":"chakrahq","email":"engineering@chakrahq.com"},"directories":{},"maintainers":[{"name":"chakrahq","email":"engineering@chakrahq.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/chakra-chat-sdk_1.1.3_1782980877905_0.008873311309449461"},"_hasShrinkwrap":false}},"time":{"created":"2026-06-29T09:02:32.255Z","modified":"2026-07-02T08:27:58.168Z","1.0.0":"2026-06-29T09:02:32.638Z","1.0.1":"2026-06-29T09:29:01.863Z","1.1.3":"2026-07-02T08:27:58.067Z"},"author":{"name":"ChakraHQ"},"license":"ISC","keywords":["chakra","chat","whatsapp","sdk","coexistence","cloud","api"],"description":"TypeScript SDK for Chakra Chat and WhatsApp APIs","maintainers":[{"name":"chakrahq","email":"engineering@chakrahq.com"}],"readme":"# chakra-chat-sdk\n\nTypeScript SDK for the [Chakra Chat](https://chakrahq.com) and WhatsApp APIs. Works in **Node.js** (18+) and **browser** environments.\n\n## Installation\n\n```bash\nnpm install chakra-chat-sdk\n```\n\nWebRTC calling uses the browser's native `RTCPeerConnection` API — no additional dependencies required.\n\n## Quick start\n\n```typescript\nimport { ChakraChat } from \"chakra-chat-sdk\";\n\nconst client = new ChakraChat({\n  accessToken: process.env.CHAKRA_ACCESS_TOKEN,\n});\n```\n\nAll API requests are authenticated with the bearer access token provided at initialization.\n\n## Configuration\n\n```typescript\nconst client = new ChakraChat({\n  accessToken: \"your-bearer-token\",       // required\n  baseUrl: \"https://api.chakrahq.com\",      // optional, this is the default\n  timeoutMs: 30000,                        // optional, default 30 seconds\n  fetch: customFetch,                       // optional, for testing or polyfills\n});\n```\n\n\n| Option        | Required | Default                    | Description                         |\n| ------------- | -------- | -------------------------- | ----------------------------------- |\n| `accessToken` | Yes      | —                          | Bearer token for API authentication |\n| `baseUrl`     | No       | `https://api.chakrahq.com` | Chakra API base URL                 |\n| `timeoutMs`   | No       | `30000`                    | Request timeout in milliseconds     |\n| `fetch`       | No       | global `fetch`             | Custom fetch implementation         |\n\n\n\n\n## Usage\n\n\n\n### Send template message\n\nSend a WhatsApp template message to a phone number.\n\n[API docs](https://apidocs.chakrahq.com/api-11312774)\n\n```typescript\nconst message = await client.whatsapp.templateMessages.send({\n  pluginId: \"d83e1d23-50b8-4d87-8f92-842a0ac516f6\",\n  toPhoneNumber: \"919999999999\",\n  whatsappPhoneNumberId: \"775966265503012\",\n  templateName: \"christmas_promo_23\",\n  mapping: [\n    { schemaPropertyName: \"1\", schemaPropertyValue: \"John\" },\n  ],\n  imageUrl: \"https://example.com/promo.png\",\n});\n\nconsole.log(message.id, message.deliveryStatus);\n```\n\n**OTP / authentication template:**\n\n```typescript\nawait client.whatsapp.templateMessages.send({\n  pluginId: \"d83e1d23-50b8-4d87-8f92-842a0ac516f6\",\n  toPhoneNumber: \"919999999999\",\n  whatsappPhoneNumberId: \"105966260583426\",\n  templateName: \"login_otp\",\n  otpCode: \"496093\",\n});\n```\n\nPhone numbers must be fully qualified with country code and without `+` or formatting characters (e.g. `919999999999`, `13323458424`).\n\n### Send session message\n\nSend a WhatsApp session message via the Cloud API pass-through endpoint. The `message` payload follows the [WhatsApp Cloud API](https://developers.facebook.com/docs/whatsapp/cloud-api/guides/send-messages) format.\n\n[API docs](https://apidocs.chakrahq.com/api-11313675)\n\n**Text message:**\n\n```typescript\nconst result = await client.whatsapp.sessionMessages.send({\n  pluginId: \"d83e1d23-50b8-4d87-8f92-842a0ac516f6\",\n  whatsappApiVersion: \"v19.0\",\n  whatsappPhoneNumberId: \"775966265503012\",\n  message: {\n    messaging_product: \"whatsapp\",\n    to: \"919999999999\",\n    type: \"text\",\n    text: { body: \"Hello from Chakra!\" },\n  },\n});\n\nconsole.log(result.whatsappMessageId);\n```\n\n**Template message (via pass-through):**\n\n```typescript\nawait client.whatsapp.sessionMessages.send({\n  pluginId,\n  whatsappApiVersion: \"v19.0\",\n  whatsappPhoneNumberId,\n  message: {\n    messaging_product: \"whatsapp\",\n    recipient_type: \"individual\",\n    to: \"919999999999\",\n    type: \"template\",\n    template: {\n      name: \"hello_world\",\n      language: { policy: \"deterministic\", code: \"en_US\" },\n      components: [{ type: \"body\", parameters: [] }],\n    },\n  },\n});\n```\n\n\n\n### Upload public media\n\nUpload a file to Chakra public storage. Use the returned URL when sending template messages with media headers.\n\n[API docs](https://apidocs.chakrahq.com/api-11313630)\n\n**Node.js:**\n\n```typescript\nimport { readFile } from \"node:fs/promises\";\n\nconst file = await readFile(\"./image.png\");\n\nconst { publicMediaUrl } = await client.whatsapp.media.uploadPublic({\n  pluginId: \"d83e1d23-50b8-4d87-8f92-842a0ac516f6\",\n  file,\n  filename: \"image.png\",\n});\n\nconsole.log(publicMediaUrl);\n```\n\n**Browser:**\n\n```typescript\nconst input = document.querySelector(\"input[type=file]\") as HTMLInputElement;\nconst file = input.files![0];\n\nconst { publicMediaUrl } = await client.whatsapp.media.uploadPublic({\n  pluginId,\n  file,\n  filename: file.name,\n});\n```\n\nAccepted file types: `Blob`, `ArrayBuffer`, or `Uint8Array`.\n\n> **Note:** Media uploaded via this API is publicly accessible to anyone with the URL.\n\n\n\n### WhatsApp calling\n\nPass-through APIs and a WebRTC calling client for the [Meta WhatsApp Calling API](https://developers.facebook.com/documentation/business-messaging/whatsapp/calling/reference). Request and response bodies follow Meta's format.\n\nOpenAPI spec: [`chakra-api/openapi/whatsapp-calling.yaml`](https://github.com/chakrahq/chakra-api/blob/main/openapi/whatsapp-calling.yaml)\n\n**Webhook handling is your responsibility.** The SDK does not receive Meta webhooks. Your app should listen for calling webhook events (e.g. Call Connect, Terminate) and pass the SDP payloads into the SDK methods below when needed.\n\n**Shared params** for all calling methods:\n\n```typescript\nconst callingConfig = {\n  whatsappApiVersion: \"v22.0\",\n  whatsappPhoneNumberId: \"775966265503012\",\n};\n```\n\n\n\n#### Pass-through APIs\n\n**Get calling settings:**\n\n```typescript\nconst settings = await client.whatsapp.calling.getSettings(callingConfig);\nconsole.log(settings.calling?.status);\n```\n\n**Update calling settings:**\n\n```typescript\nawait client.whatsapp.calling.updateSettings({\n  ...callingConfig,\n  settings: {\n    calling: {\n      status: \"ENABLED\",\n      callback_permission_status: \"ENABLED\",\n    },\n  },\n});\n```\n\n**Get call permissions for a user:**\n\n```typescript\nconst permissions = await client.whatsapp.calling.getPermissions({\n  ...callingConfig,\n  userWaId: \"919999999999\",\n});\n\nconsole.log(permissions.permission?.status);\n```\n\n**Call actions:**\n\n```typescript\n// Outbound — SDK auto-creates the WebRTC SDP offer (browser only)\nconst { calls, session } = await client.whatsapp.calling.connect({\n  ...callingConfig,\n  to: \"919999999999\",\n});\n\n// Inbound — pass SDP from your webhook handler\nawait client.whatsapp.calling.preAccept({\n  ...callingConfig,\n  callId: \"wacid.xxx\",\n  session: { sdp_type: \"answer\", sdp: answerSdp },\n});\n\nawait client.whatsapp.calling.accept({\n  ...callingConfig,\n  callId: \"wacid.xxx\",\n  session: { sdp_type: \"answer\", sdp: answerSdp },\n});\n\nawait client.whatsapp.calling.reject({\n  ...callingConfig,\n  callId: \"wacid.xxx\",\n});\n\nawait client.whatsapp.calling.terminate({\n  ...callingConfig,\n  callId: \"wacid.xxx\",\n});\n```\n\n\n\n#### WebRTC calling (ADVANCED)\n\nUses native `RTCPeerConnection` for media (no third-party WebRTC/SIP libraries). **Browser only.**\nThe following APIs need not be used. They are only useful if you want direct access and control of the underlying webrtc object and session.\n\n```typescript\nconst webrtc = client.whatsapp.calling.createWebRtcClient(callingConfig);\n```\n\n**Outbound call** — the SDK creates the WebRTC offer and calls `connect`. Pass the SDP answer from your webhook handler:\n\n```typescript\nconst { callId, session } = await webrtc.initiateOutbound({\n  to: \"919999999999\",\n});\n\n// Your webhook handler receives the Call Connect event with SDP answer:\nawait webrtc.completeOutbound(session, {\n  sdp_type: \"answer\",\n  sdp: remoteSdpFromWebhook,\n});\n\n// Later, end the call:\nawait webrtc.terminate({ callId });\nsession.close();\n```\n\n**Inbound call** — pass the SDP offer from your webhook handler:\n\n```typescript\nconst { callId, session } = await webrtc.acceptInbound({\n  callId: \"wacid.xxx\",\n  remoteOffer: {\n    sdp_type: \"offer\",\n    sdp: offerSdpFromWebhook,\n  },\n});\n\n// Later:\nawait webrtc.terminate({ callId });\nsession.close();\n```\n\n**Reject an inbound call:**\n\n```typescript\nawait webrtc.reject({ callId: \"wacid.xxx\" });\n```\n\n**Low-level session helpers** are also exported if you need manual control over the WebRTC peer connection:\n\n```typescript\nimport { createInboundAnswerSession } from \"chakra-chat-sdk\";\n\nconst session = await createInboundAnswerSession({\n  sdp_type: \"offer\",\n  sdp: offerSdpFromWebhook,\n});\n```\n\n## Error handling\n\nAPI errors throw `ChakraChatError`. Request timeouts throw `ChakraChatTimeoutError`.\n\n```typescript\nimport { ChakraChat, ChakraChatError, ChakraChatTimeoutError } from \"chakra-chat-sdk\";\n\ntry {\n  await client.whatsapp.templateMessages.send(params);\n} catch (error) {\n  if (error instanceof ChakraChatError) {\n    console.error(error.statusCode, error.errors, error.responseBody);\n  } else if (error instanceof ChakraChatTimeoutError) {\n    console.error(\"Request timed out\");\n  } else {\n    throw error;\n  }\n}\n```\n\n\n\n## Request cancellation\n\nPass an `AbortSignal` to cancel in-flight requests:\n\n```typescript\nconst controller = new AbortController();\n\nconst promise = client.whatsapp.sessionMessages.send(params, {\n  signal: controller.signal,\n});\n\ncontroller.abort();\n```\n\n\n\n## Project structure\n\n```\nchakra-chat-sdk/\n├── src/\n│   ├── index.ts                          # Main entry — ChakraChat class and public exports\n│   ├── errors.ts                         # ChakraChatError, ChakraChatTimeoutError\n│   ├── http/\n│   │   └── client.ts                     # Shared HTTP client (fetch, auth, timeouts)\n│   ├── types/\n│   │   ├── common.ts                     # ChakraChatConfig, ChakraApiResponse, TemplateMapping\n│   │   ├── template-messages.ts          # Template message request/response types\n│   │   ├── session-messages.ts           # Session message request/response types\n│   │   ├── media.ts                      # Media upload request/response types\n│   │   ├── calling.ts                    # Calling API request/response types\n│   │   └── index.ts                      # Type re-exports\n│   └── resources/\n│       ├── index.ts                      # Root resource namespace\n│       └── whatsapp/\n│           ├── index.ts                  # WhatsAppResource — groups WhatsApp endpoints\n│           ├── template-messages.ts      # POST .../send-template-message\n│           ├── session-messages.ts       # POST .../messages (Cloud API pass-through)\n│           ├── media.ts                  # POST .../upload-public-media\n│           ├── calling.ts                # Calling pass-through APIs (settings, permissions, calls)\n│           ├── webrtc-session.ts         # Native RTCPeerConnection session helpers\n│           └── webrtc-calling-client.ts  # High-level WebRTC calling client\n├── package.json\n├── tsconfig.json\n└── tsup.config.ts\n```\n\n\n\n### Architecture\n\nThe SDK is organized in layers:\n\n1. `ChakraChat` — top-level client; initialized with config and exposes resource namespaces.\n2. `resources/` — one class per API domain (e.g. `WhatsAppResource`). Add new domains here as the SDK grows.\n3. `resources/whatsapp/` — one class per WhatsApp endpoint group. Add new WhatsApp APIs here.\n4. `http/client.ts` — shared HTTP layer handling bearer auth, JSON/form requests, timeouts, and error parsing.\n5. `types/` — TypeScript interfaces for config, requests, and responses.\n\nTo add a new API:\n\n1. Define types in `src/types/`.\n2. Create a resource class in the appropriate `src/resources/` subdirectory.\n3. Register it on the parent resource (e.g. `WhatsAppResource` or `Resources`).\n4. Re-export new types from `src/types/index.ts`.\n\n\n\n## Development\n\n```bash\nnpm install\nnpm run build       # compile to dist/ (ESM + CJS + declarations)\nnpm run dev         # watch mode\nnpm run typecheck   # TypeScript check without emit\nnpm run test        # run tests\n```\n\n\n\n## Requirements\n\n- **Node.js** 18+ (uses native `fetch`)\n- **Browsers** with `fetch` and `FormData` support\n- **WebRTC calling** requires a browser with native `RTCPeerConnection` and microphone access\n\n\n\n## License\n\nISC","readmeFilename":"README.md"}