SDK de TypeScript
Ya instalaste @nimobase/sdk (ver Visión general). Esta página va del import a la primera llamada, en los dos entornos de ejecución.
En tu servidor
Necesitas una clave secreta (sk_…) creada por un OWNER o ADMIN; consulta API Keys.
import { Nimobase } from '@nimobase/sdk/node';
const client = Nimobase({
secretKey: process.env.NIMOBASE_SECRET_KEY!, // sk_…
});Tu primera llamada:
const page = await client.companies.list({ page: 1, limit: 20 });
console.log(page.data, page.total, page.page, page.limit);Los listados devuelven el envelope del API:
| Campo | Qué contiene |
|---|---|
data | Los elementos de esta página |
total | El total de elementos |
page | El número de página devuelto |
limit | El tamaño de página usado |
Los errores HTTP 4xx/5xx se traducen a NimobaseError:
import { NimobaseError } from '@nimobase/sdk/node';
try {
await client.companies.get('missing-id');
} catch (err) {
if (err instanceof NimobaseError) {
console.error(err.statusCode, err.message, err.code);
}
}Toma decisiones por err.code, no por el mensaje: los códigos son estables, el texto no.
En el navegador
Un navegador no puede guardar un secreto: todo lo que le envías puede leerlo quien use tu app. Por eso el SDK browser acepta solo claves publicables (pk_…) y rechaza una sk_ en la inicialización, sin llegar a hacer ninguna petición.
import { Nimobase } from '@nimobase/sdk/browser';
const client = Nimobase({
publishableKey: 'pk_live_…',
accessToken: userJwt, // necesario para notificaciones
});La autenticación es doble: la clave publicable acredita tu app y el JWT de usuario acredita a la persona. Con pk_ puedes leer usuarios, empresas y ajustes; consultar facturas y entitlements; iniciar el checkout o el portal de billing; y listar y marcar las notificaciones del usuario actual (requieren JWT). Cualquier otra operación de escritura, administración o invitaciones responde 403 desde la API. La matriz completa está en API Keys.
El launcher embebible
mountLauncher incrusta el widget flotante de chat y/o feedback en tu página: es un componente montado, no un iframe ni un redirect, y tus usuarios nunca salen de tu app.
import { Nimobase, mountLauncher } from '@nimobase/sdk/browser';
const client = Nimobase({ publishableKey: 'pk_live_…' });
const handle = mountLauncher({
client, // necesario para un chat usable
container: document.body, // HTMLElement o selector CSS
modules: {
chat: {
enabled: true,
mode: 'public', // o 'authenticated'
assistantId: 'asst_…',
},
feedback: true,
},
theme: 'dark', // catálogo: listLauncherThemes() → ['light', 'dark']
tokens: { primary: '#2563eb', surface: '#0f172a', radius: 12 },
locale: 'es',
});
handle.open('chat');
handle.destroy();El catálogo de temas es deliberadamente mínimo (light y dark) y los tokens están acotados (primary, surface, radius): no se acepta CSS libre.
Entorno y versión
Por defecto el cliente apunta a producción y usa la última versión publicada del contrato. Solo hay dos opciones para cambiar ese par:
| Opción | Qué hacer | Si lo omites |
|---|---|---|
sandbox: true | Trabajar en el entorno Sandbox | Producción |
version: 'v1' | Fijar la versión del contrato que consume la integración | La última publicada |
const sandboxClient = Nimobase({ secretKey, sandbox: true });
const pinnedClient = Nimobase({ secretKey, version: 'v1' });Los entornos y la versión del contrato se explican en Entornos.
Recorrer páginas
El tope por petición es 100 elementos (límite del API). Para concatenar todas las páginas sin perder filas, usa el helper collectAllPages, exportado por ambas superficies:
import { collectAllPages } from '@nimobase/sdk/node';
const allCompanies = await collectAllPages((page, limit) =>
client.companies.list({ page, limit }),
);Siguientes pasos
- Funcionalidades y métodos — el índice de capacidades de la plataforma con los métodos que las expone cada SDK.
- SDK de Python — paridad del server SDK en Python.
- Módulos — qué ofrece cada módulo de la plataforma.