Skip to content

TypeScript SDK ​

You already installed @nimobase/sdk (see Overview). This page goes from the import to the first call, in both runtimes.

On your server ​

You need a secret key (sk_…) created by an OWNER or ADMIN; see API Keys.

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

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

Your first call:

ts
const page = await client.companies.list({ page: 1, limit: 20 });
console.log(page.data, page.total, page.page, page.limit);

List endpoints return the API's envelope:

FieldWhat it holds
dataThe items on this page
totalThe total number of items
pageThe page number returned
limitThe page size used

HTTP 4xx/5xx errors are translated into 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);
  }
}

Branch on err.code, not on the message: codes are stable, text is not.

In the browser ​

A browser cannot keep a secret: everything you send it can be read by whoever uses your app. That is why the browser SDK accepts publishable keys only (pk_…) and rejects an sk_ at initialisation time, before making any request.

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

const client = Nimobase({
  publishableKey: 'pk_live_…',
  accessToken: userJwt, // required for notifications
});

Authentication is twofold: the publishable key identifies your app and the user JWT identifies the person. With pk_ you can read users, companies and settings; list invoices and entitlements; start billing checkout or the portal; and list and mark the current user's notifications (they require a JWT). Any other write, administration, or invitations operation answers 403 from the API. The full matrix lives in API Keys.

The embeddable launcher ​

mountLauncher embeds the floating chat and/or feedback widget in your page: it is a mounted component, not an iframe or a redirect, and your users never leave your app.

ts
import { Nimobase, mountLauncher } from '@nimobase/sdk/browser';

const client = Nimobase({ publishableKey: 'pk_live_…' });

const handle = mountLauncher({
  client, // required for a usable chat
  container: document.body, // HTMLElement or CSS selector
  modules: {
    chat: {
      enabled: true,
      mode: 'public', // or 'authenticated'
      assistantId: 'asst_…',
    },
    feedback: true,
  },
  theme: 'dark', // catalog: listLauncherThemes() → ['light', 'dark']
  tokens: { primary: '#2563eb', surface: '#0f172a', radius: 12 },
  locale: 'es',
});

handle.open('chat');
handle.destroy();

The theme catalog is deliberately minimal (light and dark) and the tokens are bounded (primary, surface, radius): free-form CSS is not accepted.

Environment and version ​

By default the client talks to production and uses the latest published contract version. Only two options change that pair:

OptionWhat it doesIf omitted
sandbox: trueWork against the Sandbox environmentProduction
version: 'v1'Pin the contract version the integration consumesThe latest published
ts
const sandboxClient = Nimobase({ secretKey, sandbox: true });
const pinnedClient = Nimobase({ secretKey, version: 'v1' });

Environments and the contract version are explained in Environments.

Walking pages ​

The per-request ceiling is 100 items (the API's limit). To concatenate every page without dropping rows, use the collectAllPages helper, exported by both surfaces:

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

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

Next steps ​