@ownichat/sdk 0.1.0

package/dist/index.d.cts

@@ -0,0 +1,213 @@
+type FetchLike = (input: string, init?: RequestInit) => Promise<Response>;
+
+/** Mirrors `external_product_body_schema` in the owni.chat backend. */
+type OwniProductAttribute = {
+    name: string;
+    value: string;
+};
+type OwniProductInput = {
+    /** The shop's own product id. Required for bulk upserts; it is what add-to-cart snippets interpolate. */
+    external_id: string;
+    title: string;
+    description?: string | null;
+    price?: string | number | null;
+    old_price?: string | number | null;
+    currency?: string | null;
+    image_url?: string | null;
+    /** Required by the API — the product page the widget links to. */
+    url: string;
+    availability?: string | null;
+    category?: string | null;
+    brand?: string | null;
+    attributes?: OwniProductAttribute[];
+    metadata?: Record<string, unknown>;
+};
+type OwniProduct = {
+    id: string;
+    external_id: string;
+    title: string;
+    description: string | null;
+    price: string | null;
+    old_price: string | null;
+    currency: string | null;
+    image_url: string | null;
+    url: string;
+    availability: string | null;
+    category: string | null;
+    brand: string | null;
+    source_id: string;
+    created_at: string;
+    updated_at: string;
+};
+type OwniProductPage = {
+    items: OwniProduct[];
+    total: number;
+    page: number;
+    page_size: number;
+};
+type OwniBulkUpsertResult = {
+    upserted: number;
+    created: number;
+    updated: number;
+    items: Array<{
+        external_id: string;
+        created: boolean;
+        id: string;
+    }>;
+};
+type OwniIdentity = {
+    project: {
+        id: string;
+        workspace_id: string;
+        /** Public key for the widget script tag (`data-project-key`). */
+        project_key: string;
+        name: string;
+        domain: string;
+        chat_mode: string;
+        is_active: boolean;
+        install_status: string;
+    };
+    api_key: {
+        id: string;
+        name: string;
+        scopes: string[];
+        expires_at: string | null;
+    };
+};
+type OwniKnowledgeSourceType = 'text' | 'url' | 'faq' | 'product_feed' | 'website';
+type OwniKnowledgeSourceInput = {
+    type: OwniKnowledgeSourceType;
+    name: string;
+    /** Required for `url`, `product_feed` and `website`; rejected for the others. */
+    source_url?: string;
+    /** Required for `text` and `faq`; rejected for the others. */
+    raw_text?: string;
+    metadata?: {
+        feed_format?: 'auto' | 'yandex' | 'google';
+        sync_enabled?: boolean;
+        sync_cron?: string;
+    };
+};
+type OwniKnowledgeSource = {
+    id: string;
+    type: string;
+    name: string;
+    status: string;
+    created_at: string;
+};
+type OwniEmbeddingJob = {
+    id: string;
+    status: string;
+    created_at: string;
+};
+type OwniDomain = {
+    id: string;
+    domain: string;
+    source: 'manual' | 'plugin';
+    created_at: string;
+};
+
+declare const DEFAULT_BASE_URL = "https://app.owni.chat";
+/** The API rejects bulk payloads larger than this, so the client chunks for you. */
+declare const BULK_CHUNK_SIZE = 100;
+type OwniClientOptions = {
+    /** Project API key, `ak_live_…`. Server-side only — never ship it to the browser. */
+    apiKey: string;
+    baseUrl?: string;
+    /** Optional: skips one `me()` round trip on the first catalog call. */
+    projectId?: string;
+    fetch?: FetchLike;
+    maxRetries?: number;
+    timeoutMs?: number;
+};
+declare class OwniClient {
+    private readonly http;
+    private projectIdPromise;
+    readonly products: ProductsResource;
+    readonly knowledge: KnowledgeResource;
+    readonly domains: DomainsResource;
+    constructor(options: OwniClientOptions);
+    /**
+     * 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(): Promise<OwniIdentity>;
+    /** Resolved once per client and cached; concurrent callers share the same request. */
+    projectId(): Promise<string>;
+    /** @internal */
+    projectRequest<T>(options: {
+        method?: string;
+        path: (projectId: string) => string;
+        query?: Record<string, string | number | undefined>;
+        json?: unknown;
+        body?: BodyInit;
+        headers?: Record<string, string>;
+    }): Promise<T>;
+}
+declare class ProductsResource {
+    private readonly client;
+    constructor(client: OwniClient);
+    list(input?: {
+        page?: number;
+        pageSize?: number;
+    }): Promise<OwniProductPage>;
+    get(externalId: string): Promise<OwniProduct>;
+    upsert(product: OwniProductInput): Promise<{
+        product: OwniProduct;
+        created: boolean;
+    }>;
+    delete(externalId: string): Promise<OwniProduct>;
+    /**
+     * 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.
+     */
+    bulkUpsert(products: OwniProductInput[]): Promise<OwniBulkUpsertResult>;
+}
+declare class KnowledgeResource {
+    private readonly client;
+    constructor(client: OwniClient);
+    createSource(input: OwniKnowledgeSourceInput): Promise<OwniKnowledgeSource>;
+    /** `file` is a Blob/File; in Node 18+ use `new Blob([buffer])` or `fs.openAsBlob`. */
+    uploadFile(input: {
+        file: Blob;
+        filename: string;
+        name?: string;
+    }): Promise<OwniKnowledgeSource>;
+    reindex(sourceId: string): Promise<OwniEmbeddingJob>;
+}
+declare class DomainsResource {
+    private readonly client;
+    constructor(client: OwniClient);
+    list(): Promise<OwniDomain[]>;
+    /**
+     * 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: string): Promise<{
+        domain: OwniDomain;
+        created: boolean;
+    }>;
+    remove(domainId: string): Promise<{
+        status: string;
+    }>;
+}
+declare const createOwniClient: (options: OwniClientOptions) => OwniClient;
+
+declare class OwniApiError extends Error {
+    readonly status: number;
+    readonly body: unknown;
+    constructor(status: number, message: string, body?: unknown);
+    /** 401/403 — a wrong, revoked, expired or under-scoped API key. Retrying never helps. */
+    get isAuthError(): boolean;
+    /** 429 — the external API allows 60 requests per minute per key. */
+    get isRateLimited(): boolean;
+}
+/** Raised when a request exceeds the client timeout or the connection fails outright. */
+declare class OwniConnectionError extends Error {
+    readonly cause: unknown;
+    constructor(message: string, cause?: unknown);
+}
+
+export { BULK_CHUNK_SIZE, DEFAULT_BASE_URL, type FetchLike, OwniApiError, type OwniBulkUpsertResult, OwniClient, type OwniClientOptions, OwniConnectionError, type OwniDomain, type OwniEmbeddingJob, type OwniIdentity, type OwniKnowledgeSource, type OwniKnowledgeSourceInput, type OwniKnowledgeSourceType, type OwniProduct, type OwniProductAttribute, type OwniProductInput, type OwniProductPage, createOwniClient };

package/dist/index.d.ts

@@ -0,0 +1,213 @@
+type FetchLike = (input: string, init?: RequestInit) => Promise<Response>;
+
+/** Mirrors `external_product_body_schema` in the owni.chat backend. */
+type OwniProductAttribute = {
+    name: string;
+    value: string;
+};
+type OwniProductInput = {
+    /** The shop's own product id. Required for bulk upserts; it is what add-to-cart snippets interpolate. */
+    external_id: string;
+    title: string;
+    description?: string | null;
+    price?: string | number | null;
+    old_price?: string | number | null;
+    currency?: string | null;
+    image_url?: string | null;
+    /** Required by the API — the product page the widget links to. */
+    url: string;
+    availability?: string | null;
+    category?: string | null;
+    brand?: string | null;
+    attributes?: OwniProductAttribute[];
+    metadata?: Record<string, unknown>;
+};
+type OwniProduct = {
+    id: string;
+    external_id: string;
+    title: string;
+    description: string | null;
+    price: string | null;
+    old_price: string | null;
+    currency: string | null;
+    image_url: string | null;
+    url: string;
+    availability: string | null;
+    category: string | null;
+    brand: string | null;
+    source_id: string;
+    created_at: string;
+    updated_at: string;
+};
+type OwniProductPage = {
+    items: OwniProduct[];
+    total: number;
+    page: number;
+    page_size: number;
+};
+type OwniBulkUpsertResult = {
+    upserted: number;
+    created: number;
+    updated: number;
+    items: Array<{
+        external_id: string;
+        created: boolean;
+        id: string;
+    }>;
+};
+type OwniIdentity = {
+    project: {
+        id: string;
+        workspace_id: string;
+        /** Public key for the widget script tag (`data-project-key`). */
+        project_key: string;
+        name: string;
+        domain: string;
+        chat_mode: string;
+        is_active: boolean;
+        install_status: string;
+    };
+    api_key: {
+        id: string;
+        name: string;
+        scopes: string[];
+        expires_at: string | null;
+    };
+};
+type OwniKnowledgeSourceType = 'text' | 'url' | 'faq' | 'product_feed' | 'website';
+type OwniKnowledgeSourceInput = {
+    type: OwniKnowledgeSourceType;
+    name: string;
+    /** Required for `url`, `product_feed` and `website`; rejected for the others. */
+    source_url?: string;
+    /** Required for `text` and `faq`; rejected for the others. */
+    raw_text?: string;
+    metadata?: {
+        feed_format?: 'auto' | 'yandex' | 'google';
+        sync_enabled?: boolean;
+        sync_cron?: string;
+    };
+};
+type OwniKnowledgeSource = {
+    id: string;
+    type: string;
+    name: string;
+    status: string;
+    created_at: string;
+};
+type OwniEmbeddingJob = {
+    id: string;
+    status: string;
+    created_at: string;
+};
+type OwniDomain = {
+    id: string;
+    domain: string;
+    source: 'manual' | 'plugin';
+    created_at: string;
+};
+
+declare const DEFAULT_BASE_URL = "https://app.owni.chat";
+/** The API rejects bulk payloads larger than this, so the client chunks for you. */
+declare const BULK_CHUNK_SIZE = 100;
+type OwniClientOptions = {
+    /** Project API key, `ak_live_…`. Server-side only — never ship it to the browser. */
+    apiKey: string;
+    baseUrl?: string;
+    /** Optional: skips one `me()` round trip on the first catalog call. */
+    projectId?: string;
+    fetch?: FetchLike;
+    maxRetries?: number;
+    timeoutMs?: number;
+};
+declare class OwniClient {
+    private readonly http;
+    private projectIdPromise;
+    readonly products: ProductsResource;
+    readonly knowledge: KnowledgeResource;
+    readonly domains: DomainsResource;
+    constructor(options: OwniClientOptions);
+    /**
+     * 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(): Promise<OwniIdentity>;
+    /** Resolved once per client and cached; concurrent callers share the same request. */
+    projectId(): Promise<string>;
+    /** @internal */
+    projectRequest<T>(options: {
+        method?: string;
+        path: (projectId: string) => string;
+        query?: Record<string, string | number | undefined>;
+        json?: unknown;
+        body?: BodyInit;
+        headers?: Record<string, string>;
+    }): Promise<T>;
+}
+declare class ProductsResource {
+    private readonly client;
+    constructor(client: OwniClient);
+    list(input?: {
+        page?: number;
+        pageSize?: number;
+    }): Promise<OwniProductPage>;
+    get(externalId: string): Promise<OwniProduct>;
+    upsert(product: OwniProductInput): Promise<{
+        product: OwniProduct;
+        created: boolean;
+    }>;
+    delete(externalId: string): Promise<OwniProduct>;
+    /**
+     * 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.
+     */
+    bulkUpsert(products: OwniProductInput[]): Promise<OwniBulkUpsertResult>;
+}
+declare class KnowledgeResource {
+    private readonly client;
+    constructor(client: OwniClient);
+    createSource(input: OwniKnowledgeSourceInput): Promise<OwniKnowledgeSource>;
+    /** `file` is a Blob/File; in Node 18+ use `new Blob([buffer])` or `fs.openAsBlob`. */
+    uploadFile(input: {
+        file: Blob;
+        filename: string;
+        name?: string;
+    }): Promise<OwniKnowledgeSource>;
+    reindex(sourceId: string): Promise<OwniEmbeddingJob>;
+}
+declare class DomainsResource {
+    private readonly client;
+    constructor(client: OwniClient);
+    list(): Promise<OwniDomain[]>;
+    /**
+     * 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: string): Promise<{
+        domain: OwniDomain;
+        created: boolean;
+    }>;
+    remove(domainId: string): Promise<{
+        status: string;
+    }>;
+}
+declare const createOwniClient: (options: OwniClientOptions) => OwniClient;
+
+declare class OwniApiError extends Error {
+    readonly status: number;
+    readonly body: unknown;
+    constructor(status: number, message: string, body?: unknown);
+    /** 401/403 — a wrong, revoked, expired or under-scoped API key. Retrying never helps. */
+    get isAuthError(): boolean;
+    /** 429 — the external API allows 60 requests per minute per key. */
+    get isRateLimited(): boolean;
+}
+/** Raised when a request exceeds the client timeout or the connection fails outright. */
+declare class OwniConnectionError extends Error {
+    readonly cause: unknown;
+    constructor(message: string, cause?: unknown);
+}
+
+export { BULK_CHUNK_SIZE, DEFAULT_BASE_URL, type FetchLike, OwniApiError, type OwniBulkUpsertResult, OwniClient, type OwniClientOptions, OwniConnectionError, type OwniDomain, type OwniEmbeddingJob, type OwniIdentity, type OwniKnowledgeSource, type OwniKnowledgeSourceInput, type OwniKnowledgeSourceType, type OwniProduct, type OwniProductAttribute, type OwniProductInput, type OwniProductPage, createOwniClient };

package/dist/index.js

@@ -0,0 +1,286 @@
+import { OwniConnectionError, OwniApiError } from './chunk-2OWJTVJ3.js';
+export { OwniApiError, OwniConnectionError } from './chunk-2OWJTVJ3.js';
+
+// 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);
+
+export { BULK_CHUNK_SIZE, DEFAULT_BASE_URL, OwniClient, createOwniClient };