@omni-commerce/sdk 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) OmniCommerce
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,125 @@
+# @omni-commerce/sdk
+
+TypeScript / JavaScript client for the [OmniCommerce API](https://docs.omnicommerce.sg/api-reference).
+
+The client is generated from the public OpenAPI spec so every documented REST endpoint is typed. The npm org is `@omni-commerce` because the unscoped `omnicommerce` name is reserved.
+
+The surface is a resource client with one request object per call, dual ESM/CJS builds, and typed HTTP errors.
+
+## Install
+
+```bash
+yarn add @omni-commerce/sdk
+# or: npm install @omni-commerce/sdk
+```
+
+Node 18+ (global `fetch`). Works in Node, Bun, and other fetch runtimes.
+
+## Usage
+
+Named export only — there is no default export.
+
+```ts
+import { OmniClient } from "@omni-commerce/sdk";
+
+const client = new OmniClient({
+  apiKey: process.env.OMNI_API_KEY, // or omit to read OMNI_API_KEY
+});
+
+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"],
+  },
+});
+
+const created = await client.jobs.wait({ jobId: job.jobId });
+```
+
+API keys are organization-scoped. Do not send `organizationId` on API-key requests.
+
+### Options
+
+```ts
+const client = new OmniClient({
+  apiKey: "omni_sk_...",
+  environment: "http://localhost:3000", // default https://omnicommerce.sg
+  timeoutInSeconds: 60,
+  maxRetries: 2,
+});
+```
+
+Per-request overrides:
+
+```ts
+await client.orders.get(
+  { orderId: "ord_123" },
+  { timeoutInSeconds: 15, abortSignal: controller.signal },
+);
+```
+
+`await request.withRawResponse()` returns `{ data, rawResponse }` with status and headers.
+
+## Resources
+
+| Client                        | Examples                                                                       |
+| ----------------------------- | ------------------------------------------------------------------------------ |
+| `client.products`             | `list`, `create`, `get`, `update`, `delete`, `publish`, `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` | Universal Commerce Protocol checkout                                           |
+| `client.oauth`                | `token`, `revoke`                                                              |
+
+Every other documented tag (looks, returns, settlements, marketplaces, search, evaluate, monitor, sync, …) is exposed the same way.
+
+## Errors
+
+Non-2xx responses throw a subclass of `OmniError`:
+
+```ts
+import { OmniClient, NotFoundError, OmniError } from "@omni-commerce/sdk";
+
+try {
+  await client.products.get({ productId: "missing" });
+} catch (error) {
+  if (error instanceof NotFoundError) {
+    // 404
+  } else if (error instanceof OmniError) {
+    console.error(error.statusCode, error.body);
+  }
+}
+```
+
+## Webhooks
+
+```ts
+import { constructEvent } from "@omni-commerce/sdk";
+
+const event = await constructEvent(
+  rawBody,
+  headers,
+  process.env.OMNI_WEBHOOK_SECRET,
+);
+```
+
+Signature: HMAC-SHA256 over `{timestamp}.{rawBody}` compared to `X-Omni-Signature`.
+
+## Regenerate from OpenAPI
+
+From the monorepo root:
+
+```bash
+yarn sdk:generate
+```
+
+That refreshes `docs/openapi.json`, the OpenAPI TypeScript types, and `src/generated/resources.ts`.