The Omneo SDK (@omneo/omneo-sdk) is the typed JavaScript and TypeScript client for the Omneo API. Install it once and use it in Node or in the browser.
Installation
npm install @omneo/omneo-sdk
yarn add @omneo/omneo-sdk
>=20. It ships ESM and CJS builds with TypeScript types.
For browser-only loading without a bundler, import the ESM build from unpkg:
<script type="module">
import { Omneo, ID } from 'https://unpkg.com/@omneo/omneo-sdk/dist/index.js'
</script>
Two clients
The SDK exports two classes from a single package. Pick the one that matches your runtime and authentication context.
| Client | Authentication | Runtime | Use it for |
|---|
Omneo | Bearer API token | Server-side only | Backend integrations, batch jobs, admin tooling, server-rendered profile data |
ID | Profile-scoped JWT (IDToken) | Server-side mint, then safe in the browser | Storefronts, profile portals, customer-facing UIs |
Omneo client carries the full admin API surface and a token with broad scopes. Never ship that token to a browser.
The ID client is initialised once on a trusted server with an admin token to mint a short-lived, profile-scoped IDToken. You can then hand that token to the browser, where new ID({ tenant, IDToken }) is safe to use against the customer’s own profile only.
Picking a client
| Building… | Use |
|---|
| A storefront, customer UI, or any browser-facing surface | ID |
| A backend service, batch import, or admin tool | Omneo |
Migration from the legacy Shapes SDK
The previous script-tag library at cdn.getomneo.com/sdk/omneo.js, with OmneoSDK.init() (also referred to as ShapesSDK.init()), .hydrate(), .find(), .on(), and .off(), is deprecated. New integrations must use @omneo/omneo-sdk.
| Legacy | Current |
|---|
ShapesSDK.init({ url, token }) | new ID({ tenant, IDToken }) |
client.hydrate('profile') + client.on('profile.ready', fn) | await id.profile.get() |
client.hydrate('transactions') + client.on('transactions.ready', fn) | await id.profile.transactions.list() |
client.get('transactions?include=product') | await id.profile.transactions.list({ include: 'product' }) or id.call({ method: 'GET', endpoint: '/profile/transactions', params: { include: 'product' } }) |
client.find('balances.combined_balance_dollars') | await id.profile.balances.list() |
client.off(event, handler) | Not required, calls are one-shot promises |
