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.
import { Nimobase } from '@nimobase/sdk/node';
const client = Nimobase({
secretKey: process.env.NIMOBASE_SECRET_KEY!, // sk_…
});Your first call:
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:
| Field | What it holds |
|---|---|
data | The items on this page |
total | The total number of items |
page | The page number returned |
limit | The page size used |
HTTP 4xx/5xx errors are translated into 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);
}
}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.
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.
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:
| Option | What it does | If omitted |
|---|---|---|
sandbox: true | Work against the Sandbox environment | Production |
version: 'v1' | Pin the contract version the integration consumes | The latest published |
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:
import { collectAllPages } from '@nimobase/sdk/node';
const allCompanies = await collectAllPages((page, limit) =>
client.companies.list({ page, limit }),
);Next steps
- Features and methods — the platform feature index, with the methods each SDK exposes.
- Python SDK — the server SDK in Python.
- Modules — what each platform module offers.