> ## Documentation Index
> Fetch the complete documentation index at: https://woku.app/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# JavaScript SDK

> Manage your entire woku account from your backend with @wokuapp/sdk: trackers, VoC tools (NPS, CSAT, CES), wokus, tickets, action plans and sends over the v1 API

<Info>
  **Available on the Corporate plan.** This capability is part of woku's enterprise features. [Talk to our sales team](https://woku.app/pricing).
</Info>

The **`@wokuapp/sdk`** SDK is the official **server-side** client for the woku
management API. With a single typed client you manage external trackers, VoC
tools (**NPS**, **CSAT**, **CES**), wokus, forms, flows, action plans, support
tickets, survey sends and delivery tracking, all over the public **v1** API.

<Warning>
  This is a **server-side** SDK. The company secret key grants full management
  access, so it must live only on your backend. Never ship it in a browser
  bundle, a mobile app or any client you do not control. To capture feedback from
  a mobile app use the [React Native SDK](/docs/en/development/sdk-react-native), which
  uses a public capture key.
</Warning>

## Installation

```bash theme={null}
npm install @wokuapp/sdk
```

Requires Node.js 18 or later (uses the global `fetch`). It has zero runtime
dependencies.

## Initialization

Create a `Woku` instance once and reuse it.

```ts theme={null}
import { Woku } from '@wokuapp/sdk';

const woku = new Woku({ apiKey: process.env.WOKU_API_KEY });
```

If you omit `apiKey`, the SDK reads the `WOKU_API_KEY` environment variable. You
can also pass the key directly: `new Woku('sk_...')`.

| Option       | Required | Description                                                 |
| ------------ | -------- | ----------------------------------------------------------- |
| `apiKey`     | yes      | Company secret key. Defaults to `process.env.WOKU_API_KEY`. |
| `baseURL`    | no       | API base URL. Defaults to `https://clientapi.woku.app`.     |
| `timeout`    | no       | Per-request timeout in ms. Defaults to `60000`.             |
| `maxRetries` | no       | Automatic retries for transient failures. Defaults to `2`.  |

## Authentication

The SDK authenticates with the **Company Key**, the same secret key the
[API](/docs/en/development/api) uses. The company owner gets it from the company
**Information** section in the admin app:
[admin.woku.app](https://admin.woku.app).

```
Authorization: Bearer <Company-Key>
```

The SDK adds that header for you on every call.

### Rotate or revoke the key

Since the secret key grants full access, you can rotate or revoke it from the
SDK itself. Rotating generates a new key and **immediately invalidates the
previous one**; store the returned key before continuing.

```ts theme={null}
const { secretKey } = await woku.company.rotateKey();
// store secretKey securely; the previous key stops working

await woku.company.revokeKey(); // leaves the account without an active key
```

## Quickstart

An end-to-end flow: create a tracker, create an NPS tool, send it and read the
response rate.

```ts theme={null}
import { Woku } from '@wokuapp/sdk';

const woku = new Woku({ apiKey: process.env.WOKU_API_KEY });

// 1. Create a tracker definition (idempotent).
const tracker = await woku.trackers.create({
  name: 'Store #1',
  system: 'retail',
});

// 2. Create an NPS tool and send it by email or WhatsApp.
const tool = await woku.npsTools.create({
  name: 'Post-purchase',
  npsMessage: 'How likely are you to recommend us?',
});
await woku.nps.sendInvitations({
  channel: 'email',
  npsToolId: tool._id,
  recipients: ['ana@example.com'],
});

// 3. Read delivery and response rate.
const stats = await woku.dispatches.stats({ channel: 'email' });
console.log(stats.responseRate);
```

## Main flows

### VoC tools

Create and manage NPS, CSAT and CES tools, and capture their responses.

```ts theme={null}
const csat = await woku.csatTools.create({
  name: 'Support',
  question: 'How satisfied were you with the support?',
});

// Send, then read responses.
await woku.csat.sendInvitations({
  channel: 'email',
  csatToolId: csat._id,
  recipients: ['ana@example.com'],
});
for await (const response of await woku.csat.listResponses()) {
  console.log(response);
}
```

### Support tickets

Tickets are generated by woku's AI. You can list, filter and curate them.

```ts theme={null}
for await (const ticket of await woku.tickets.list({ severity: 'high' })) {
  console.log(ticket.title);
}

const stats = await woku.tickets.stats();
```

### Action plans

Approve plans, send them to an external tool or manage them inside woku.

```ts theme={null}
await woku.actionPlans.approve('plan_123');
await woku.actionPlans.send('plan_123', {
  provider: 'jira',
  target: { projectId: '10032', issueTypeId: '10001' },
});
```

## Pagination

List methods return a `Page`. Iterate every item across pages, or walk page by
page:

```ts theme={null}
for await (const ticket of await woku.tickets.list({ severity: 'high' })) {
  console.log(ticket.title);
}

const first = await woku.dispatches.list({ channel: 'whatsapp' });
if (first.hasNextPage()) {
  const second = await first.getNextPage();
}
```

## Idempotency

Creates carry an automatic `Idempotency-Key`, so a retry after a transient
failure never creates twice. Actions (send, test, reply) are **not** retried on
their own so an effect is never repeated. You can pass your own key per call:

```ts theme={null}
await woku.npsTools.create(body, { idempotencyKey: 'my-key' });
```

## Error handling

Every failure is a `WokuError`. HTTP errors are typed subclasses carrying the
server `status`, body and `requestId`:

```ts theme={null}
import { NotFoundError, RateLimitError } from '@wokuapp/sdk';

try {
  await woku.tickets.get('nonexistent');
} catch (err) {
  if (err instanceof NotFoundError) {
    console.error(err.status, err.requestId); // 404, "req_..."
  } else if (err instanceof RateLimitError) {
    console.error('retry after', err.retryAfterSeconds);
  }
}
```

Transport failures (DNS, TLS, timeout) are `WokuConnectionError` and
`WokuTimeoutError`. The SDK retries GETs and idempotent writes automatically
with backoff, honoring the `Retry-After` header.

## Per-call configuration

Every method accepts overrides in its last argument:

```ts theme={null}
await woku.tickets.list(
  { severity: 'high' },
  { timeout: 10_000, maxRetries: 0 },
);
```

## Resources

`trackers`, `npsTools` / `csatTools` / `cesTools`, `nps` / `csat` / `ces`,
`wokus`, `forms`, `flows`, `actionPlans`, `actionPlanGroups`, `tickets`,
`ticketDestinations`, `dispatches`, `reports`, `company`, `quarantines`.

## Versioning

The SDK follows **semantic versioning** (`MAJOR.MINOR.PATCH`). The current
published version is **`0.1.0`**. We recommend pinning a compatible range (for
example `^0.1.0`) and reviewing the changelog before a MAJOR bump. Versions and
their notes are on the
[npm package](https://www.npmjs.com/package/@wokuapp/sdk) and the
[GitHub releases](https://github.com/wokuApp/sdks/releases).

## Resources

* **npm package:** [@wokuapp/sdk](https://www.npmjs.com/package/@wokuapp/sdk)
* **Code and examples:** [github.com/wokuApp/sdks](https://github.com/wokuApp/sdks)
* **Equivalent Python SDK:** [Python SDK](/docs/en/development/sdk-python)
* **API reference:** [API Integration Guide](/docs/en/development/api)