> ## Documentation Index
> Fetch the complete documentation index at: https://docs.omnicommerce.sg/llms.txt
> Use this file to discover all available pages before exploring further.

# TypeScript SDK

> Typed JavaScript/TypeScript client for every OmniCommerce REST endpoint.

The TypeScript SDK (`@omni-commerce/sdk`) is generated from the public OpenAPI spec, so every documented REST operation is a typed resource method. The command-line client uses the same spec — see [Omni CLI](/cli/omni-cli).

The unscoped npm name `omnicommerce` is reserved. The public org is `@omni-commerce`.

## Install

```bash theme={null}
npm install @omni-commerce/sdk
```

Requires Node 18+ (global `fetch`). Named export only:

```ts theme={null}
import { OmniClient } from "@omni-commerce/sdk";
```

## Authenticate

Use an organization API key (`omni_sk_...`) as a bearer token. Do not send `organizationId` on API-key requests.

```ts theme={null}
const client = new OmniClient({
  apiKey: process.env.OMNI_API_KEY,
});
```

Omit `apiKey` to read `OMNI_API_KEY`. Override the host with `baseUrl` or `environment` (`https://omnicommerce.sg` by default). See [Authentication](/authentication).

```ts theme={null}
const client = new OmniClient({
  apiKey: process.env.OMNI_API_KEY,
  environment: "http://localhost:3000",
  timeoutInSeconds: 60,
  maxRetries: 2,
});
```

## Resource clients

Each call takes one request object (path params, query, and JSON body together), then optional request options:

```ts theme={null}
const products = await client.products.list({ q: "lamp" });

const job = await client.products.create({
  product: {
    sku: "SKU-100",
    title: "Sample product",
    price: 29.9,
    currency: "SGD",
    images: ["https://cdn.example.com/product.jpg"],
  },
});

await client.jobs.wait({ jobId: job.jobId });

await client.products.publish({
  productId: "prod_123",
  marketplaces: ["shopee"],
});

const delist = await client.products.delist({
  productId: "prod_123",
  marketplaces: ["shopee", "lazada"],
});
await client.jobs.wait({ jobId: delist.jobId });
```

Per-request overrides:

```ts theme={null}
await client.orders.get(
  { orderId: "ord_123" },
  { timeoutInSeconds: 15, abortSignal: controller.signal },
);
```

`await request.withRawResponse()` returns `{ data, rawResponse }` with status and headers.

## Coverage

| Client                    | Examples                                                                                 |
| ------------------------- | ---------------------------------------------------------------------------------------- |
| `client.products`         | `list`, `create`, `get`, `update`, `delete`, `publish`, `delist`, `bulkImport`, `enrich` |
| `client.orders`           | `list`, `create`, `get`, `update`                                                        |
| `client.promotions`       | `list`, `create`, `get`, `update`, `delete`, `sync`                                      |
| `client.priceBooks`       | `list`, `create`, `get`, `update`, `delete`, `preview`                                   |
| `client.aop`              | `create`, `execute`, `getConfig`, `updateConfig`, `retry`                                |
| `client.jobs`             | `get`, `cancel`, `wait`                                                                  |
| `client.webhooks`         | `list`, `create`                                                                         |
| `client.checkoutSessions` | `create`, `get`, `update`, `complete`, `cancel`                                          |
| `client.ucp`              | `checkoutSessions`, `orders`                                                             |
| `client.oauth`            | `token`, `revoke`                                                                        |

Looks, returns, settlements, marketplaces, search, evaluate, monitor, sync, Zalora, and the remaining documented tags follow the same pattern. The generator covers every REST operation in the [API reference](/api-reference).

## Errors

Non-2xx responses throw `OmniError` subclasses. See [SDK errors](/sdk/errors).

GET/HEAD/OPTIONS/PUT/DELETE retry on 5xx and network failures. 408 and 429 retry for every method. POST/PATCH are not retried on 5xx.

## Webhooks

```ts theme={null}
import { constructEvent } from "@omni-commerce/sdk";

const event = await constructEvent(
  rawBody,
  request.headers,
  process.env.OMNI_WEBHOOK_SECRET,
);
```

HMAC-SHA256 over `{timestamp}.{rawBody}` compared to `X-Omni-Signature`. See [Webhooks](/webhooks/overview).

## Regenerate

From this repository:

```bash theme={null}
yarn sdk:generate
```