TypeScript / JavaScript#

@kivox/sdk es el SDK oficial de Kivox para TypeScript y JavaScript. Se publica exclusivamente en JSR y es un cliente HTTP tipado, generado a partir del mismo contrato OpenAPI que respalda la API, junto con utilidades adicionales para streaming SSE y transferencia de archivos que la API por sí sola no resuelve.

Esta página cubre lo específico del paquete. El comportamiento de cada operación está documentado de forma agnóstica en el resto de la sección de desarrolladores, con ejemplos en TypeScript incluidos ahí mismo.

#Instalación

El paquete oficial se distribuye exclusivamente desde JSR. Consulte también la página de @kivox/sdk en JSR.

npm jsr add @kivox/sdk

yarn jsr add @kivox/sdk

pnpm jsr add @kivox/sdk

bun jsr add @kivox/sdk

deno jsr npm:add npm:@kivox/sdk

Para npm, Bun y otros gestores que utilizan node_modules, el CLI de JSR configura automáticamente la compatibilidad necesaria. Por ejemplo:

bunx jsr add @kivox/sdk

añadirá una dependencia equivalente a:

{
    "dependencies": {
        "@kivox/sdk": "npm:@jsr/kivox__sdk"
    }
}

y configurará .npmrc con el registro de JSR:

@jsr:registry=https://npm.jsr.io

Este archivo debe incluirse en el control de versiones del proyecto.

#ESM

Los paquetes publicados en JSR son ESM-only. Los proyectos Node.js que consuman @kivox/sdk deben utilizar ES modules, por ejemplo mediante:

{
    "type": "module"
}

En TypeScript, configure el proyecto con el modo de módulos correspondiente al entorno Node.js.

import { Kivox } from "@kivox/sdk";

Consulte la documentación de JSR para Node.js para más detalles sobre el uso de paquetes JSR en Node.js.

#Crear un cliente

import { Kivox } from "@kivox/sdk";

const client = new Kivox({
    headers: {
        Authorization: `Bearer ${process.env.KIVOX_API_KEY}`,
    },
});

#Extraer tipos del contrato

El SDK expone ApiSchema para acceder a los tipos generados directamente desde el contrato de la API:

import type { ApiSchema } from "@kivox/sdk";

const agent: ApiSchema<"Agent"> = {
    // ...
};

const knowledgeBase: ApiSchema<"KnowledgeBase"> = {
    // ...
};

Esto es preferible a copiar manualmente los campos de cada recurso. Cuando el contrato de la API cambia, los tipos generados se actualizan junto con el paquete.

#Cancelación

Todo método del SDK que realiza una solicitud de red acepta un signal: AbortSignal opcional, de forma consistente en todo el paquete.

const controller = new AbortController();

kivox.POST("/v1/workspaces/{workspace_id}/agents", {
    // ...
    signal: controller.signal,
});

controller.abort();

Llamar a abort() cancela la operación en curso y propaga la señal al mecanismo de transporte utilizado por el SDK.

#Referencia del paquete

La fuente oficial de distribución y versiones del SDK es JSR:

https://jsr.io/@kivox/sdk