> ## 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 todos los planes, incluido el gratuito.** La API v1 y los SDK oficiales están habilitados para toda cuenta de woku. [Conoce los planes](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, etiquetarla con el
tracker, 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.
const tool = await woku.npsTools.create({
  name: 'Post-compra',
  npsMessage: '¿Qué tan probable es que nos recomiendes?',
});

// 3. Asignar un valor del tracker a la herramienta NPS, para que cada respuesta
//    quede etiquetada con la tienda y el reporte se agrupe por ella.
await woku.trackers.assignToEntity('nps', tool._id, {
  name: tracker.name,
  value: 'TX-42',
});

// 4. Enviarla por correo o WhatsApp.
await woku.nps.sendInvitations({
  channel: 'email',
  npsToolId: tool._id,
  recipients: ['ana@example.com'],
});

// 5. 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 y gestiona los planes de acción dentro de woku: cambia su estado y
administra sus tareas.

```ts theme={null}
await woku.actionPlans.approve('plan_123');

// Leer el detalle y la línea de tiempo del plan.
const plan = await woku.actionPlans.get('plan_123');
const events = await woku.actionPlans.events('plan_123');

// Cerrar o reabrir el plan.
await woku.actionPlans.complete('plan_123');
```

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

## Referencia

Referencia completa de namespaces y métodos. Para las formas exactas de request y response, consulta el [API reference](https://woku.app/docs/api-reference).

### actionPlans

Lee y gestiona planes de acción, incluido el kanban gestionado (tareas, conversación IA y transiciones de estado).

| Método                                | Retorno                     | Descripción                                                                  |
| ------------------------------------- | --------------------------- | ---------------------------------------------------------------------------- |
| `list(params?, opts?)`                | `Promise<Page<WokuRecord>>` | Lista los planes de acción, con filtros opcionales y paginación.             |
| `get(id, opts?)`                      | `Promise<WokuRecord>`       | Obtiene un plan de acción por id.                                            |
| `events(id, opts?)`                   | `Promise<WokuRecord[]>`     | Devuelve la línea de tiempo del plan (eventos, más antiguos primero).        |
| `getConversation(id, opts?)`          | `Promise<WokuRecord>`       | Devuelve la conversación IA del plan (solo lectura).                         |
| `reply(id, text, opts?)`              | `Promise<WokuRecord>`       | Responde al agente IA del plan (turno pago, compuesto de forma asincrónica). |
| `createTask(id, body, opts?)`         | `Promise<WokuRecord>`       | Crea una tarea en el plan (idempotente).                                     |
| `updateTask(id, taskId, body, opts?)` | `Promise<WokuRecord>`       | Actualiza una tarea del plan.                                                |
| `reorderTasks(id, body, opts?)`       | `Promise<WokuRecord>`       | Reordena las tareas del plan.                                                |
| `deleteTask(id, taskId, opts?)`       | `Promise<WokuRecord>`       | Elimina una tarea del plan.                                                  |
| `approve(id, opts?)`                  | `Promise<WokuRecord>`       | Aprueba el plan.                                                             |
| `reopen(id, opts?)`                   | `Promise<WokuRecord>`       | Reabre el plan.                                                              |
| `cancel(id, opts?)`                   | `Promise<WokuRecord>`       | Cancela el plan.                                                             |
| `complete(id, opts?)`                 | `Promise<WokuRecord>`       | Marca el plan como completado.                                               |
| `resume(id, opts?)`                   | `Promise<WokuRecord>`       | Reanuda el plan.                                                             |

### actionPlanGroups

Gestiona los grupos de planes de acción (listar, obtener con stats, crear, actualizar, habilitar/deshabilitar y eliminar).

| Método                           | Retorno                 | Descripción                               |
| -------------------------------- | ----------------------- | ----------------------------------------- |
| `list(params?, opts?)`           | `Promise<WokuRecord[]>` | Lista los grupos, con busqueda opcional.  |
| `get(id, opts?)`                 | `Promise<WokuRecord>`   | Obtiene un grupo con sus stats embebidas. |
| `create(body, opts?)`            | `Promise<WokuRecord>`   | Crea un grupo (idempotente).              |
| `update(id, body, opts?)`        | `Promise<WokuRecord>`   | Actualiza un grupo.                       |
| `setEnabled(id, enabled, opts?)` | `Promise<WokuRecord>`   | Habilita o deshabilita el grupo.          |
| `delete(id, opts?)`              | `Promise<WokuRecord>`   | Elimina el grupo.                         |

### company

Gestiona la empresa que hace la llamada y su clave de API en /v1/companies/me.

| Método             | Retorno                 | Descripción                                                       |
| ------------------ | ----------------------- | ----------------------------------------------------------------- |
| `me(opts?)`        | `Promise<WokuRecord>`   | Obtiene la empresa que hace la llamada.                           |
| `rotateKey(opts?)` | `Promise<ApiKeyResult>` | Rota la clave secreta y devuelve la nueva (invalida la anterior). |
| `revokeKey(opts?)` | `Promise<WokuRecord>`   | Revoca la clave secreta.                                          |

### dispatches

Seguimiento de entrega sobre los envios de invitaciones (/v1/dispatches).

| Método                  | Retorno                   | Descripción                                              |
| ----------------------- | ------------------------- | -------------------------------------------------------- |
| `list(params?, opts?)`  | `Promise<Page<Dispatch>>` | Lista los envios con estado de entrega, sin PII.         |
| `stats(params?, opts?)` | `Promise<DispatchStats>`  | Devuelve metricas de tasa de respuesta sobre los envios. |

### flows

Acceso de solo lectura a los flujos de datos (/v1/flows).

| Método                 | Retorno                     | Descripción                          |
| ---------------------- | --------------------------- | ------------------------------------ |
| `list(params?, opts?)` | `Promise<Page<WokuRecord>>` | Lista los flujos de datos, paginado. |
| `get(id, opts?)`       | `Promise<WokuRecord>`       | Obtiene un flujo de datos por id.    |

### forms

Lee formularios y sus respuestas, y envia invitaciones de formulario (/v1/forms).

| Método                              | Retorno                      | Descripción                                              |
| ----------------------------------- | ---------------------------- | -------------------------------------------------------- |
| `list(params?, opts?)`              | `Promise<Page<WokuRecord>>`  | Lista los formularios, paginado.                         |
| `get(id, opts?)`                    | `Promise<WokuRecord>`        | Obtiene un formulario por id.                            |
| `listResponses(id, params?, opts?)` | `Promise<Page<WokuRecord>>`  | Lista las respuestas de un formulario, paginado.         |
| `sendInvitations(id, body, opts?)`  | `Promise<InvitationsResult>` | Envia un formulario por correo o WhatsApp (idempotente). |

### quarantines

Verifica si un contacto esta en cuarentena (/v1/quarantines).

| Método                 | Retorno               | Descripción                                                    |
| ---------------------- | --------------------- | -------------------------------------------------------------- |
| `check(params, opts?)` | `Promise<WokuRecord>` | Verifica si un contacto (email o teléfono) esta en cuarentena. |

### reports

Lee reportes NPS (/v1/reports): a nivel empresa y por herramienta NPS.

| Método                               | Retorno               | Descripción                                    |
| ------------------------------------ | --------------------- | ---------------------------------------------- |
| `companyNps(params?, opts?)`         | `Promise<WokuRecord>` | Obtiene el reporte NPS a nivel empresa.        |
| `npsTool(npsToolId, params?, opts?)` | `Promise<WokuRecord>` | Obtiene el reporte NPS de una herramienta NPS. |

### nps

Envia la encuesta NPS y lee sus respuestas (/v1/nps).

| Método                          | Retorno                      | Descripción                                                |
| ------------------------------- | ---------------------------- | ---------------------------------------------------------- |
| `sendInvitations(body, opts?)`  | `Promise<InvitationsResult>` | Envia la encuesta NPS por correo o WhatsApp (idempotente). |
| `listResponses(params?, opts?)` | `Page<WokuRecord>`           | Lista las respuestas NPS, paginado.                        |
| `getResponse(id, opts?)`        | `Promise<WokuRecord>`        | Obtiene una respuesta NPS por id.                          |

### csat

Envia la encuesta CSAT y lee sus respuestas (/v1/csat).

| Método                          | Retorno                      | Descripción                                |
| ------------------------------- | ---------------------------- | ------------------------------------------ |
| `sendInvitations(body, opts?)`  | `Promise<InvitationsResult>` | Envia las invitaciones CSAT (idempotente). |
| `listResponses(params?, opts?)` | `Page<WokuRecord>`           | Lista las respuestas CSAT, paginado.       |
| `getResponse(id, opts?)`        | `Promise<WokuRecord>`        | Obtiene una respuesta CSAT por id.         |

### ces

Envia la encuesta CES y lee sus respuestas (/v1/ces).

| Método                          | Retorno                      | Descripción                               |
| ------------------------------- | ---------------------------- | ----------------------------------------- |
| `sendInvitations(body, opts?)`  | `Promise<InvitationsResult>` | Envia las invitaciones CES (idempotente). |
| `listResponses(params?, opts?)` | `Page<WokuRecord>`           | Lista las respuestas CES, paginado.       |
| `getResponse(id, opts?)`        | `Promise<WokuRecord>`        | Obtiene una respuesta CES por id.         |

### tickets

Lee y cura los tickets de soporte generados por IA (/v1/tickets).

| Método                    | Retorno                 | Descripción                                               |
| ------------------------- | ----------------------- | --------------------------------------------------------- |
| `list(params?, opts?)`    | `Promise<Page<Ticket>>` | Lista los tickets con filtros opcionales.                 |
| `stats(params?, opts?)`   | `Promise<TicketStats>`  | Devuelve conteos agregados por herramienta y por destino. |
| `get(id, opts?)`          | `Promise<Ticket>`       | Obtiene un ticket por id.                                 |
| `update(id, body, opts?)` | `Promise<Ticket>`       | Actualiza (patch) un ticket.                              |

### ticketDestinations

Gestiona los destinos de tickets SAC (/v1/ticket-destinations).

| Método                    | Retorno                         | Descripción                                                                 |
| ------------------------- | ------------------------------- | --------------------------------------------------------------------------- |
| `list(opts?)`             | `Promise<WokuRecord[]>`         | Lista todos los destinos configurados.                                      |
| `get(id, opts?)`          | `Promise<WokuRecord>`           | Obtiene un destino por id.                                                  |
| `create(body, opts?)`     | `Promise<WokuRecord>`           | Crea un destino (idempotente).                                              |
| `update(id, body, opts?)` | `Promise<WokuRecord>`           | Actualiza (patch) un destino.                                               |
| `delete(id, opts?)`       | `Promise<WokuRecord>`           | Elimina un destino.                                                         |
| `test(id, opts?)`         | `Promise<TestConnectionResult>` | Envia una prueba de conectividad real al destino (confirm:true automatico). |

### trackers

Gestiona definiciones de tracker externas y asigna/quita valores de tracker en wokus y entidades VoC (/v1/external-trackers).

| Método                                                 | Retorno                       | Descripción                                                                     |
| ------------------------------------------------------ | ----------------------------- | ------------------------------------------------------------------------------- |
| `list(params?, opts?)`                                 | `Promise<Page<Tracker>>`      | Lista las definiciones de tracker, paginado.                                    |
| `create(body, opts?)`                                  | `Promise<Tracker>`            | Crea una definición de tracker (idempotente).                                   |
| `get(id, opts?)`                                       | `Promise<Tracker>`            | Obtiene una definición de tracker por id.                                       |
| `update(id, body, opts?)`                              | `Promise<Tracker>`            | Actualiza una definición de tracker.                                            |
| `activate(id, opts?)`                                  | `Promise<Tracker>`            | Activa una definición de tracker.                                               |
| `deactivate(id, opts?)`                                | `Promise<Tracker>`            | Desactiva una definición de tracker.                                            |
| `searchEntities(body, opts?)`                          | `Promise<EntitiesByTrackers>` | Busca entidades VoC cuyos trackers cumplen todos los filtros (AND).             |
| `listWokuValues(wokuId, opts?)`                        | `Promise<WokuRecord[]>`       | Lista los valores de tracker asignados a un woku.                               |
| `assignToWoku(wokuId, body, opts?)`                    | `Promise<WokuRecord>`         | Asigna (upsert) un valor de tracker a un woku por nombre (idempotente).         |
| `removeFromWoku(wokuId, trackerName, opts?)`           | `Promise<WokuRecord>`         | Quita un valor de tracker de un woku por nombre.                                |
| `searchWokus(params, opts?)`                           | `Promise<Page<WokuRecord>>`   | Busca wokus por un par exacto (nombre de tracker, valor), paginado.             |
| `listEntityValues(entityType, id, opts?)`              | `Promise<WokuRecord[]>`       | Lista los valores de tracker de una entidad VoC (nps/csat/ces/form/flow).       |
| `assignToEntity(entityType, id, body, opts?)`          | `Promise<WokuRecord>`         | Asigna (upsert) un valor de tracker a una entidad VoC por nombre (idempotente). |
| `removeFromEntity(entityType, id, trackerName, opts?)` | `Promise<WokuRecord>`         | Quita un valor de tracker de una entidad VoC por nombre.                        |

### npsTools

Gestiona las definiciones de herramientas NPS (/v1/nps-tools).

| Método                    | Retorno                  | Descripción                                 |
| ------------------------- | ------------------------ | ------------------------------------------- |
| `list(params?, opts?)`    | `Promise<Page<NpsTool>>` | Lista las definiciones NPS, paginado.       |
| `create(body, opts?)`     | `Promise<NpsTool>`       | Crea una definición NPS (POST idempotente). |
| `get(id, opts?)`          | `Promise<NpsTool>`       | Obtiene una herramienta NPS por id.         |
| `update(id, body, opts?)` | `Promise<NpsTool>`       | Actualiza (patch) una herramienta NPS.      |
| `delete(id, opts?)`       | `Promise<DeletedResult>` | Elimina una herramienta NPS por id.         |

### csatTools

Gestiona las definiciones de herramientas CSAT (/v1/csat-tools).

| Método                    | Retorno                   | Descripción                                  |
| ------------------------- | ------------------------- | -------------------------------------------- |
| `list(params?, opts?)`    | `Promise<Page<CsatTool>>` | Lista las definiciones CSAT, paginado.       |
| `create(body, opts?)`     | `Promise<CsatTool>`       | Crea una definición CSAT (POST idempotente). |
| `get(id, opts?)`          | `Promise<CsatTool>`       | Obtiene una herramienta CSAT por id.         |
| `update(id, body, opts?)` | `Promise<CsatTool>`       | Actualiza (patch) una herramienta CSAT.      |
| `delete(id, opts?)`       | `Promise<DeletedResult>`  | Elimina una herramienta CSAT por id.         |

### cesTools

Gestiona las definiciones de herramientas CES (/v1/ces-tools).

| Método                    | Retorno                  | Descripción                                 |
| ------------------------- | ------------------------ | ------------------------------------------- |
| `list(params?, opts?)`    | `Promise<Page<CesTool>>` | Lista las definiciones CES, paginado.       |
| `create(body, opts?)`     | `Promise<CesTool>`       | Crea una definición CES (POST idempotente). |
| `get(id, opts?)`          | `Promise<CesTool>`       | Obtiene una herramienta CES por id.         |
| `update(id, body, opts?)` | `Promise<CesTool>`       | Actualiza (patch) una herramienta CES.      |
| `delete(id, opts?)`       | `Promise<DeletedResult>` | Elimina una herramienta CES por id.         |

### wokus

Gestiona los wokus (herramientas de captura) (/v1/wokus): reseñas, settings, mover de carpeta, invitaciones y compartir.

| Método                             | Retorno                       | Descripción                                                         |
| ---------------------------------- | ----------------------------- | ------------------------------------------------------------------- |
| `list(params?, opts?)`             | `Promise<Page<WokuResource>>` | Lista los wokus de la empresa, paginado.                            |
| `create(body, opts?)`              | `Promise<WokuResource>`       | Crea un woku (POST idempotente).                                    |
| `get(id, opts?)`                   | `Promise<WokuResource>`       | Obtiene un woku con sus stats de reseñas.                           |
| `update(id, body, opts?)`          | `Promise<WokuResource>`       | Actualiza (patch) los campos de un woku.                            |
| `delete(id, opts?)`                | `Promise<DeletedResult>`      | Elimina un woku.                                                    |
| `updateSettings(id, body, opts?)`  | `Promise<WokuResource>`       | Aplica los settings booleanos del woku (idempotente).               |
| `move(id, body, opts?)`            | `Promise<WokuResource>`       | Mueve el woku a una carpeta, o a la raiz con folderId null.         |
| `listReviews(id, params?, opts?)`  | `Promise<Page<WokuRecord>>`   | Lista las reseñas de un woku, paginado.                             |
| `sendInvitations(id, body, opts?)` | `Promise<InvitationsResult>`  | Envia una invitacion de reseña por correo o WhatsApp (idempotente). |
| `share(id, body, opts?)`           | `Promise<WokuRecord>`         | Comparte el link de reseña de un woku por correo.                   |

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