Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.omneo.io/llms.txt

Use this file to discover all available pages before exploring further.

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
The package requires Node >=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.
ClientAuthenticationRuntimeUse it for
OmneoBearer API tokenServer-side onlyBackend integrations, batch jobs, admin tooling, server-rendered profile data
IDProfile-scoped JWT (IDToken)Server-side mint, then safe in the browserStorefronts, profile portals, customer-facing UIs
The 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 surfaceID
A backend service, batch import, or admin toolOmneo

​
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.
The legacy library was event-driven. The current SDK is promise-based with typed namespaces. Common patterns map as follows:
LegacyCurrent
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