Skip to content

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.

ts
import { Nimobase } from '@nimobase/sdk/node';

const client = Nimobase({
  secretKey: process.env.NIMOBASE_SECRET_KEY!, // sk_…
});

Tu primera llamada:

ts
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:

CampoQué contiene
dataLos elementos de esta página
totalEl total de elementos
pageEl número de página devuelto
limitEl tamaño de página usado

Los errores HTTP 4xx/5xx se traducen a NimobaseError:

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

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

ts
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ónQué hacerSi lo omites
sandbox: trueTrabajar en el entorno SandboxProducción
version: 'v1'Fijar la versión del contrato que consume la integraciónLa última publicada
ts
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:

ts
import { collectAllPages } from '@nimobase/sdk/node';

const allCompanies = await collectAllPages((page, limit) =>
  client.companies.list({ page, limit }),
);

Siguientes pasos ​