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

# Omneo SDK

> Install the Omneo SDK and pick the right client for your runtime.

The **Omneo SDK** ([`@omneo/omneo-sdk`](https://github.com/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

```shell theme={null}
npm install @omneo/omneo-sdk
```

```shell theme={null}
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:

```html theme={null}
<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                             |

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 surface | [`ID`](/dev-guides/frontend/omneo-id)     |
| A backend service, batch import, or admin tool           | [`Omneo`](/dev-guides/frontend/omneo-sdk) |

## Migration from the legacy Shapes SDK

<Info>
  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`.
</Info>

The legacy library was event-driven. The current SDK is promise-based with typed namespaces. Common patterns map as follows:

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

## Related

* [Using the Omneo SDK](/dev-guides/frontend/omneo-sdk) (the `Omneo` admin client)
* [Using Omneo ID](/dev-guides/frontend/omneo-id) (the `ID` profile-scoped client)
* [Omneo SDK concept](/concepts/platform-surfaces/omneo-sdk)
* [API tokens](/dev-guides/core-setup/api-tokens)