> ## 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.

# SDK de JavaScript

> Gestiona toda tu cuenta de woku desde tu backend con @wokuapp/sdk: trackers, herramientas VoC (NPS, CSAT, CES), wokus, tickets, planes de accion y envios sobre la API v1

<Info>
  **Disponible en el plan Corporate.** Esta funcionalidad forma parte de las capacidades empresariales de woku. [Conversa con nuestro equipo comercial](https://woku.app/pricing).
</Info>

El SDK **`@wokuapp/sdk`** es el cliente oficial **de servidor** para la API de
gestion de woku. Con un solo cliente tipado administras trackers externos,
herramientas VoC (**NPS**, **CSAT**, **CES**), wokus, formularios, flows,
planes de accion, tickets de soporte, envios de encuestas y seguimiento de
entrega, todo sobre la API pública **v1**.

<Warning>
  Es un SDK **de servidor**. La clave secreta de compañía otorga acceso completo
  de gestion, asi que debe vivir solo en tu backend. Nunca la incluyas en un
  bundle de navegador, una app móvil ni ningún cliente que no controles. Para
  capturar feedback desde una app móvil usa el [SDK de React
  Native](/docs/development/sdk-react-native), que usa una clave pública de captura.
</Warning>

## Instalación

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

Requiere Node.js 18 o superior (usa el `fetch` global). No tiene dependencias
de runtime.

## Inicialización

Crea una instancia de `Woku` una sola vez y reutilízala.

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

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

Si omites `apiKey`, el SDK lee la variable de entorno `WOKU_API_KEY`. También
puedes pasar la clave directamente: `new Woku('sk_...')`.

| Opción       | Requerida | Descripción                                                        |
| ------------ | --------- | ------------------------------------------------------------------ |
| `apiKey`     | sí        | Clave secreta de compañía. Por defecto `process.env.WOKU_API_KEY`. |
| `baseURL`    | no        | URL base de la API. Por defecto `https://clientapi.woku.app`.      |
| `timeout`    | no        | Tiempo máximo por solicitud en ms. Por defecto `60000`.            |
| `maxRetries` | no        | Reintentos automáticos ante fallos transitorios. Por defecto `2`.  |

## Autenticación

El SDK autentica con la **Clave de Compañía**, la misma clave secreta que usa
la [API](/docs/development/api). La obtiene el propietario de la empresa desde la
sección **Información** de la empresa en la aplicación administrativa:
[admin.woku.app](https://admin.woku.app).

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

El SDK agrega ese header por ti en cada llamada.

### Rotar o revocar la clave

Como la clave secreta otorga acceso completo, puedes rotarla o revocarla desde
el propio SDK. Rotar genera una clave nueva e **invalida de inmediato la
anterior**; guarda la que devuelve antes de continuar.

```ts theme={null}
const { secretKey } = await woku.company.rotateKey();
// guarda secretKey de forma segura; la clave anterior deja de funcionar

await woku.company.revokeKey(); // deja la cuenta sin clave activa
```

## Quickstart

Un flujo completo: crear un tracker, crear una herramienta NPS, enviarla y leer
la tasa de respuesta.

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

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

// 1. Crear una definición de tracker (idempotente).
const tracker = await woku.trackers.create({
  name: 'Tienda #1',
  system: 'retail',
});

// 2. Crear una herramienta NPS y enviarla por correo o WhatsApp.
const tool = await woku.npsTools.create({
  name: 'Post-compra',
  npsMessage: '¿Qué tan probable es que nos recomiendes?',
});
await woku.nps.sendInvitations({
  channel: 'email',
  npsToolId: tool._id,
  recipients: ['ana@example.com'],
});

// 3. Leer la entrega y la tasa de respuesta.
const stats = await woku.dispatches.stats({ channel: 'email' });
console.log(stats.responseRate);
```

## Flujos principales

### Herramientas VoC

Crea y administra herramientas NPS, CSAT y CES, y captura sus respuestas.

```ts theme={null}
const csat = await woku.csatTools.create({
  name: 'Soporte',
  question: '¿Qué tan satisfecho quedaste con la atención?',
});

// Enviar y luego leer respuestas.
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);
}
```

### Tickets de soporte

Los tickets los genera la IA de woku. Puedes listarlos, filtrarlos y curarlos.

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

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

### Planes de acción

Aprueba planes, envíalos a una herramienta externa o gestiónalos dentro de
woku.

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

## Paginación

Los métodos de listado devuelven una `Page`. Recorre cada elemento a través de
las páginas, o página por página:

```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();
}
```

## Idempotencia

Los `create` incluyen automáticamente una `Idempotency-Key`, asi que un
reintento tras un fallo transitorio nunca crea dos veces. Las acciones (enviar,
probar, responder) **no** se reintentan solas para no repetir un efecto. Puedes
pasar tu propia clave por llamada:

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

## Manejo de errores

Cada fallo es un `WokuError`. Los errores HTTP son subclases tipadas que llevan
el `status`, el cuerpo y el `requestId` del servidor:

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

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

Los fallos de transporte (DNS, TLS, timeout) son `WokuConnectionError` y
`WokuTimeoutError`. El SDK reintenta automáticamente los GET y las escrituras
idempotentes con backoff y respeto del header `Retry-After`.

## Configuración por llamada

Cada método acepta overrides en su último argumento:

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

## Recursos

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

## Versionado

El SDK sigue **versionado semántico** (`MAJOR.MINOR.PATCH`). La versión actual
publicada es la **`0.1.0`**. Te recomendamos fijar un rango compatible (por
ejemplo `^0.1.0`) y revisar el changelog antes de subir de versión MAJOR. Las
versiones y sus notas están en el
[paquete npm](https://www.npmjs.com/package/@wokuapp/sdk) y en los
[releases de GitHub](https://github.com/wokuApp/sdks/releases).

## Recursos

* **Paquete npm:** [@wokuapp/sdk](https://www.npmjs.com/package/@wokuapp/sdk)
* **Código y ejemplos:** [github.com/wokuApp/sdks](https://github.com/wokuApp/sdks)
* **SDK de Python equivalente:** [SDK de Python](/docs/development/sdk-python)
* **Referencia de la API:** [Guía de Integración API](/docs/development/api)