@ownichat/sdk 0.1.0

package/CHANGELOG.md

@@ -0,0 +1,21 @@
+# Changelog
+
+All notable changes to `@ownichat/sdk` are documented here. This project follows
+[Semantic Versioning](https://semver.org/): breaking changes to the owni.chat API surface
+(a removed field, a changed response shape) ship as a major release.
+
+## 0.1.0
+
+First public release.
+
+- `createOwniClient()` — typed client for the owni.chat external API
+- `me()` — resolve the project, workspace and widget key a server key is bound to
+- `products` — `list`, `get`, `upsert`, `delete`, and `bulkUpsert` with automatic
+  splitting into the API's 100-item batches
+- `knowledge` — create URL, text and FAQ sources, upload files, trigger reindexing
+- `domains` — register, list and remove the origins the widget may load on
+- `@ownichat/sdk/webhooks` — `verifyWebhookSignature` and `parseWebhookRequest` for
+  HMAC-SHA256 signed deliveries, with replay protection
+- `@ownichat/sdk/widget` — browser client for the public widget API
+- Automatic retry with exponential backoff on 429 and 5xx, honouring `Retry-After`
+- Typed errors: `OwniApiError`, `OwniConnectionError`

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 owni.chat
+
+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,201 @@
+<div align="center">
+
+# @ownichat/sdk
+
+**Official API client for [owni.chat](https://owni.chat)** — the AI chat widget that answers
+from your real catalog.
+
+[![npm](https://img.shields.io/npm/v/@ownichat/sdk?color=306cf1)](https://www.npmjs.com/package/@ownichat/sdk)
+[![bundle](https://img.shields.io/bundlephobia/minzip/@ownichat/sdk?color=306cf1)](https://bundlephobia.com/package/@ownichat/sdk)
+[![types](https://img.shields.io/npm/types/@ownichat/sdk?color=306cf1)](https://www.npmjs.com/package/@ownichat/sdk)
+[![license](https://img.shields.io/npm/l/@ownichat/sdk?color=306cf1)](./LICENSE)
+
+</div>
+
+```sh
+npm install @ownichat/sdk
+```
+
+| | |
+| --- | --- |
+| 🛍️ **Catalog sync** | Push products, prices and stock — batching handled for you |
+| 📚 **Knowledge** | Create URL, text and FAQ sources, upload files, trigger reindexing |
+| 🌐 **Domains** | Register the origins the widget may load on |
+| 🔐 **Webhooks** | Verify HMAC-signed deliveries, with replay protection |
+| 💬 **Widget API** | Talk to the public chat API when building your own UI |
+
+**Zero runtime dependencies.** Node 18+ (uses the global `fetch`), and works in Deno, Bun,
+Cloudflare Workers and other edge runtimes. Ships ESM and CJS with types for both.
+
+## Quick start
+
+Create an API key in the owni.chat dashboard under **Settings → API keys**. It looks like
+`ak_live_…` and must stay server-side.
+
+```ts
+import { createOwniClient } from '@ownichat/sdk';
+
+const owni = createOwniClient({ apiKey: process.env.OWNI_API_KEY! });
+
+// Everything the key is bound to — including the public key for the widget script tag
+const { project } = await owni.me();
+console.log(project.project_key); // pk_…
+```
+
+That single call is what makes one-field installs possible: the merchant pastes the API key,
+and your integration discovers the project id and the widget key on its own.
+
+## Sync a product catalog
+
+```ts
+await owni.products.bulkUpsert([
+  {
+    external_id: '1042',                       // your shop's product id
+    title: 'Merino wool scarf',
+    description: 'Lightweight, 100% merino.',
+    url: 'https://shop.example.com/p/1042',    // required
+    price: '49.00',
+    old_price: '69.00',
+    currency: 'EUR',
+    image_url: 'https://shop.example.com/i/1042.jpg',
+    availability: 'in_stock',
+    category: 'Accessories',
+    brand: 'Example',
+    attributes: [{ name: 'Colour', value: 'Charcoal' }],
+  },
+]);
+```
+
+`bulkUpsert` accepts any number of products and splits them into the API's 100-item batches
+for you, sequentially, so a full catalog sync stays within the rate limit.
+
+Other catalog calls:
+
+```ts
+await owni.products.list({ page: 1, pageSize: 50 });
+await owni.products.get('1042');
+await owni.products.upsert({ external_id: '1042', title: '…', url: '…' });
+await owni.products.delete('1042');
+```
+
+Keep `external_id` equal to your shop's own product id — it is what the widget's
+"add to cart" snippet interpolates when a visitor buys from a product card.
+
+## Allowed domains
+
+The widget only loads on origins registered for the project. Register the storefront you're
+installed on so staging sites and secondary domains work without dashboard edits:
+
+```ts
+await owni.domains.add('staging.shop.example.com'); // idempotent
+await owni.domains.list();
+```
+
+## Knowledge sources
+
+```ts
+await owni.knowledge.createSource({ type: 'url', name: 'Shipping policy', source_url: 'https://shop.example.com/shipping' });
+await owni.knowledge.createSource({ type: 'faq', name: 'FAQ', raw_text: 'Q: …\nA: …' });
+
+const file = new Blob([await readFile('./returns.pdf')]);
+await owni.knowledge.uploadFile({ file, filename: 'returns.pdf' });
+```
+
+## Webhooks
+
+owni.chat signs outgoing webhooks with `X-Owni-Signature` (HMAC-SHA256 over
+`<timestamp>.<raw body>`) and `X-Owni-Timestamp`. Verify both — the timestamp is what stops
+a captured delivery from being replayed later.
+
+```ts
+import { parseWebhookRequest } from '@ownichat/sdk/webhooks';
+
+export async function POST(request: Request) {
+  const body = await request.text(); // raw body, not request.json()
+
+  const result = parseWebhookRequest({
+    body,
+    headers: request.headers,
+    secret: process.env.OWNI_WEBHOOK_SECRET!,
+  });
+
+  if (!result.valid) {
+    return new Response(result.reason, { status: 401 });
+  }
+
+  if (result.event.event === 'lead_captured') {
+    // …
+  }
+  return new Response('ok');
+}
+```
+
+`verifyWebhookSignature` is available separately if you already parse the body yourself. Both
+work with a `Headers` object and with a plain Node header record.
+
+The signing secret is shown once when you connect the webhook integration, and can be
+regenerated from **Integrations → Webhooks → Rotate secret**. Integrations created before
+signing existed keep receiving unsigned deliveries until you rotate.
+
+## Widget API (browser)
+
+Only needed when building a custom chat UI — the standard embed script already does this.
+
+```ts
+import { createWidgetClient } from '@ownichat/sdk/widget';
+
+const widget = createWidgetClient({ projectKey: 'pk_…' });
+const config = await widget.getConfig();
+const session = await widget.createSession({ source_page_url: location.href });
+```
+
+Requests are origin-checked server-side, so the page must run on the project domain or one of
+its registered domains.
+
+## Errors and retries
+
+```ts
+import { OwniApiError, OwniConnectionError } from '@ownichat/sdk';
+
+try {
+  await owni.products.bulkUpsert(products);
+} catch (error) {
+  if (error instanceof OwniApiError && error.isAuthError) {
+    // wrong, revoked, expired or under-scoped key — retrying will not help
+  }
+}
+```
+
+429 and 5xx responses are retried automatically with exponential backoff, honouring
+`Retry-After`. Configure with `maxRetries` (default 3) and `timeoutMs` (default 30 000).
+
+## Options
+
+| Option | Default | Notes |
+| --- | --- | --- |
+| `apiKey` | — | Required. `ak_live_…`, server-side only. |
+| `baseUrl` | `https://app.owni.chat` | Point at your own instance if self-hosting. |
+| `projectId` | resolved via `me()` | Supply it to skip one round trip. |
+| `fetch` | global `fetch` | Inject your own for tests or proxies. |
+| `maxRetries` | `3` | Applies to 429 and 5xx only. |
+| `timeoutMs` | `30000` | Per request, including retries individually. |
+
+## Related packages
+
+| Package | For |
+| --- | --- |
+| [`@ownichat/react`](https://www.npmjs.com/package/@ownichat/react) | Widget provider, hooks and inline chat panel |
+| [`@ownichat/next`](https://www.npmjs.com/package/@ownichat/next) | Next.js server component, client hooks and webhook route |
+
+Running a ready-made platform? owni.chat ships official plugins for WordPress/WooCommerce,
+Shopify and OpenCart — see [owni.chat/integrations](https://owni.chat/integrations).
+
+## Notes
+
+The widget bundle shipped by owni.chat has its own copy of the browser API types; the two are
+kept in sync by hand for now. If you spot a drift, the backend's Joi schemas are the source of
+truth.
+
+## License
+
+MIT © [owni.chat](https://owni.chat)

package/dist/chunk-2OWJTVJ3.js

@@ -0,0 +1,29 @@
+// src/errors.ts
+var OwniApiError = class extends Error {
+  status;
+  body;
+  constructor(status, message, body) {
+    super(message);
+    this.name = "OwniApiError";
+    this.status = status;
+    this.body = body;
+  }
+  /** 401/403 — a wrong, revoked, expired or under-scoped API key. Retrying never helps. */
+  get isAuthError() {
+    return this.status === 401 || this.status === 403;
+  }
+  /** 429 — the external API allows 60 requests per minute per key. */
+  get isRateLimited() {
+    return this.status === 429;
+  }
+};
+var OwniConnectionError = class extends Error {
+  cause;
+  constructor(message, cause) {
+    super(message);
+    this.name = "OwniConnectionError";
+    this.cause = cause;
+  }
+};
+
+export { OwniApiError, OwniConnectionError };

package/dist/index.cjs

@@ -0,0 +1,318 @@
+'use strict';
+
+// src/errors.ts
+var OwniApiError = class extends Error {
+  status;
+  body;
+  constructor(status, message, body) {
+    super(message);
+    this.name = "OwniApiError";
+    this.status = status;
+    this.body = body;
+  }
+  /** 401/403 — a wrong, revoked, expired or under-scoped API key. Retrying never helps. */
+  get isAuthError() {
+    return this.status === 401 || this.status === 403;
+  }
+  /** 429 — the external API allows 60 requests per minute per key. */
+  get isRateLimited() {
+    return this.status === 429;
+  }
+};
+var OwniConnectionError = class extends Error {
+  cause;
+  constructor(message, cause) {
+    super(message);
+    this.name = "OwniConnectionError";
+    this.cause = cause;
+  }
+};
+
+// src/http.ts
+var DEFAULT_MAX_RETRIES = 3;
+var DEFAULT_TIMEOUT_MS = 3e4;
+var sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));
+var retryDelayMs = (attempt, retryAfterHeader) => {
+  if (retryAfterHeader) {
+    const seconds = Number(retryAfterHeader);
+    if (Number.isFinite(seconds) && seconds >= 0) {
+      return Math.min(seconds * 1e3, 6e4);
+    }
+  }
+  const base = Math.min(2 ** attempt * 500, 16e3);
+  return base + Math.random() * 250;
+};
+var isRetryableStatus = (status) => status === 429 || status >= 500;
+var HttpClient = class {
+  baseUrl;
+  apiKey;
+  fetchImpl;
+  maxRetries;
+  timeoutMs;
+  constructor(options) {
+    if (!options.apiKey) {
+      throw new Error("An owni.chat API key is required (ak_live_\u2026).");
+    }
+    this.baseUrl = options.baseUrl.replace(/\/+$/, "");
+    this.apiKey = options.apiKey;
+    this.maxRetries = options.maxRetries ?? DEFAULT_MAX_RETRIES;
+    this.timeoutMs = options.timeoutMs ?? DEFAULT_TIMEOUT_MS;
+    const resolvedFetch = options.fetch ?? globalThis.fetch;
+    if (!resolvedFetch) {
+      throw new Error(
+        "No fetch implementation found. Use Node 18+ or pass `fetch` in the client options."
+      );
+    }
+    this.fetchImpl = resolvedFetch;
+  }
+  async request(options) {
+    const url = this.buildUrl(options.path, options.query);
+    const headers = {
+      Authorization: `Bearer ${this.apiKey}`,
+      Accept: "application/json",
+      ...options.headers
+    };
+    let body = options.body;
+    if (options.json !== void 0) {
+      headers["Content-Type"] = "application/json";
+      body = JSON.stringify(options.json);
+    }
+    let lastError;
+    for (let attempt = 0; attempt <= this.maxRetries; attempt += 1) {
+      let response;
+      try {
+        response = await this.fetchWithTimeout(url, {
+          method: options.method ?? "GET",
+          headers,
+          body
+        });
+      } catch (error) {
+        lastError = new OwniConnectionError(`Request to ${url} failed`, error);
+        if (attempt === this.maxRetries) throw lastError;
+        await sleep(retryDelayMs(attempt, null));
+        continue;
+      }
+      if (response.ok) {
+        return await this.parseJson(response);
+      }
+      if (isRetryableStatus(response.status) && attempt < this.maxRetries) {
+        await sleep(retryDelayMs(attempt, response.headers.get("retry-after")));
+        continue;
+      }
+      throw await this.toApiError(response);
+    }
+    throw lastError ?? new OwniConnectionError(`Request to ${url} failed`);
+  }
+  buildUrl(path, query) {
+    const url = new URL(`${this.baseUrl}${path}`);
+    for (const [key, value] of Object.entries(query ?? {})) {
+      if (value !== void 0) {
+        url.searchParams.set(key, String(value));
+      }
+    }
+    return url.toString();
+  }
+  async fetchWithTimeout(url, init) {
+    const controller = new AbortController();
+    const timer = setTimeout(() => controller.abort(), this.timeoutMs);
+    try {
+      return await this.fetchImpl(url, { ...init, signal: controller.signal });
+    } finally {
+      clearTimeout(timer);
+    }
+  }
+  async parseJson(response) {
+    const text = await response.text();
+    if (!text) return null;
+    try {
+      return JSON.parse(text);
+    } catch {
+      return text;
+    }
+  }
+  async toApiError(response) {
+    const body = await this.parseJson(response);
+    const message = body && typeof body === "object" && "message" in body && typeof body.message === "string" ? body.message : `owni.chat API responded with status ${response.status}`;
+    return new OwniApiError(response.status, message, body);
+  }
+};
+
+// src/client.ts
+var DEFAULT_BASE_URL = "https://app.owni.chat";
+var BULK_CHUNK_SIZE = 100;
+var OwniClient = class {
+  http;
+  projectIdPromise = null;
+  products;
+  knowledge;
+  domains;
+  constructor(options) {
+    this.http = new HttpClient({
+      baseUrl: options.baseUrl ?? DEFAULT_BASE_URL,
+      apiKey: options.apiKey,
+      fetch: options.fetch,
+      maxRetries: options.maxRetries,
+      timeoutMs: options.timeoutMs
+    });
+    if (options.projectId) {
+      this.projectIdPromise = Promise.resolve(options.projectId);
+    }
+    this.products = new ProductsResource(this);
+    this.knowledge = new KnowledgeResource(this);
+    this.domains = new DomainsResource(this);
+  }
+  /**
+   * Everything the key is bound to, including the `project_key` a plugin needs for the
+   * widget script tag. This is what makes "paste one API key" installs possible.
+   */
+  me() {
+    return this.http.request({ path: "/api/external/v1/me" });
+  }
+  /** Resolved once per client and cached; concurrent callers share the same request. */
+  projectId() {
+    if (!this.projectIdPromise) {
+      this.projectIdPromise = this.me().then((identity) => identity.project.id).catch((error) => {
+        this.projectIdPromise = null;
+        throw error;
+      });
+    }
+    return this.projectIdPromise;
+  }
+  /** @internal */
+  async projectRequest(options) {
+    const projectId = await this.projectId();
+    return this.http.request({
+      method: options.method,
+      path: options.path(projectId),
+      query: options.query,
+      json: options.json,
+      body: options.body,
+      headers: options.headers
+    });
+  }
+};
+var ProductsResource = class {
+  constructor(client) {
+    this.client = client;
+  }
+  client;
+  list(input = {}) {
+    return this.client.projectRequest({
+      path: (projectId) => `/api/external/v1/projects/${projectId}/products`,
+      query: { page: input.page, page_size: input.pageSize }
+    });
+  }
+  async get(externalId) {
+    const data = await this.client.projectRequest({
+      path: (projectId) => `/api/external/v1/projects/${projectId}/products/${encodeURIComponent(externalId)}`
+    });
+    return data.product;
+  }
+  async upsert(product) {
+    return this.client.projectRequest({
+      method: "PUT",
+      path: (projectId) => `/api/external/v1/projects/${projectId}/products/${encodeURIComponent(product.external_id)}`,
+      json: product
+    });
+  }
+  async delete(externalId) {
+    const data = await this.client.projectRequest({
+      method: "DELETE",
+      path: (projectId) => `/api/external/v1/projects/${projectId}/products/${encodeURIComponent(externalId)}`
+    });
+    return data.product;
+  }
+  /**
+   * Sends products in chunks of {@link BULK_CHUNK_SIZE} and merges the results, so a
+   * full catalog can be passed in one call. Chunks are sequential on purpose: the API
+   * re-indexes embeddings after each batch and parallel writes just trip the rate limit.
+   */
+  async bulkUpsert(products) {
+    const merged = { upserted: 0, created: 0, updated: 0, items: [] };
+    if (products.length === 0) return merged;
+    for (let index = 0; index < products.length; index += BULK_CHUNK_SIZE) {
+      const chunk = products.slice(index, index + BULK_CHUNK_SIZE);
+      const result = await this.client.projectRequest({
+        method: "POST",
+        path: (projectId) => `/api/external/v1/projects/${projectId}/products/bulk`,
+        json: { products: chunk }
+      });
+      merged.upserted += result.upserted;
+      merged.created += result.created;
+      merged.updated += result.updated;
+      merged.items.push(...result.items);
+    }
+    return merged;
+  }
+};
+var KnowledgeResource = class {
+  constructor(client) {
+    this.client = client;
+  }
+  client;
+  async createSource(input) {
+    const data = await this.client.projectRequest({
+      method: "POST",
+      path: (projectId) => `/api/external/v1/projects/${projectId}/knowledge-sources`,
+      json: input
+    });
+    return data.knowledge_source;
+  }
+  /** `file` is a Blob/File; in Node 18+ use `new Blob([buffer])` or `fs.openAsBlob`. */
+  async uploadFile(input) {
+    const form = new FormData();
+    form.append("file", input.file, input.filename);
+    if (input.name) form.append("name", input.name);
+    const data = await this.client.projectRequest({
+      method: "POST",
+      path: (projectId) => `/api/external/v1/projects/${projectId}/knowledge-sources/upload`,
+      body: form
+    });
+    return data.knowledge_source;
+  }
+  async reindex(sourceId) {
+    const data = await this.client.projectRequest({
+      method: "POST",
+      path: (projectId) => `/api/external/v1/projects/${projectId}/knowledge-sources/${encodeURIComponent(sourceId)}/reindex`
+    });
+    return data.embedding_job;
+  }
+};
+var DomainsResource = class {
+  constructor(client) {
+    this.client = client;
+  }
+  client;
+  async list() {
+    const data = await this.client.projectRequest({
+      path: (projectId) => `/api/external/v1/projects/${projectId}/domains`
+    });
+    return data.domains;
+  }
+  /**
+   * Registers an origin the widget is allowed to load on. Idempotent — re-sending an
+   * existing domain returns `created: false` instead of failing, so plugins can call
+   * this on every settings save.
+   */
+  add(domain) {
+    return this.client.projectRequest({
+      method: "POST",
+      path: (projectId) => `/api/external/v1/projects/${projectId}/domains`,
+      json: { domain }
+    });
+  }
+  remove(domainId) {
+    return this.client.projectRequest({
+      method: "DELETE",
+      path: (projectId) => `/api/external/v1/projects/${projectId}/domains/${encodeURIComponent(domainId)}`
+    });
+  }
+};
+var createOwniClient = (options) => new OwniClient(options);
+
+exports.BULK_CHUNK_SIZE = BULK_CHUNK_SIZE;
+exports.DEFAULT_BASE_URL = DEFAULT_BASE_URL;
+exports.OwniApiError = OwniApiError;
+exports.OwniClient = OwniClient;
+exports.OwniConnectionError = OwniConnectionError;
+exports.createOwniClient = createOwniClient;