@ownichat/sdk 0.1.0

package/dist/webhooks.cjs

@@ -0,0 +1,60 @@
+'use strict';
+
+var crypto = require('crypto');
+
+// src/webhooks.ts
+var SIGNATURE_HEADER = "x-owni-signature";
+var TIMESTAMP_HEADER = "x-owni-timestamp";
+var DEFAULT_TOLERANCE_SECONDS = 300;
+var computeWebhookSignature = (secret, timestamp, body) => `sha256=${crypto.createHmac("sha256", secret).update(`${timestamp}.${body}`).digest("hex")}`;
+var safeEquals = (a, b) => {
+  const bufferA = Buffer.from(a);
+  const bufferB = Buffer.from(b);
+  if (bufferA.length !== bufferB.length) return false;
+  return crypto.timingSafeEqual(bufferA, bufferB);
+};
+var verifyWebhookSignature = (input) => {
+  if (!input.signature || !input.timestamp) {
+    return { valid: false, reason: "missing_headers" };
+  }
+  const timestampSeconds = Number(input.timestamp);
+  if (!Number.isFinite(timestampSeconds)) {
+    return { valid: false, reason: "stale_timestamp" };
+  }
+  const now = input.nowSeconds ?? Math.floor(Date.now() / 1e3);
+  const tolerance = input.toleranceSeconds ?? DEFAULT_TOLERANCE_SECONDS;
+  if (Math.abs(now - timestampSeconds) > tolerance) {
+    return { valid: false, reason: "stale_timestamp" };
+  }
+  const expected = computeWebhookSignature(input.secret, input.timestamp, input.body);
+  if (!safeEquals(expected, input.signature)) {
+    return { valid: false, reason: "bad_signature" };
+  }
+  return { valid: true };
+};
+var readHeader = (headers, name) => {
+  if (typeof headers.get === "function") {
+    return headers.get(name);
+  }
+  const record = headers;
+  const value = record[name] ?? record[name.toLowerCase()];
+  return Array.isArray(value) ? value[0] ?? null : value ?? null;
+};
+var parseWebhookRequest = (input) => {
+  const result = verifyWebhookSignature({
+    body: input.body,
+    signature: readHeader(input.headers, SIGNATURE_HEADER),
+    timestamp: readHeader(input.headers, TIMESTAMP_HEADER),
+    secret: input.secret,
+    toleranceSeconds: input.toleranceSeconds
+  });
+  if (!result.valid) return result;
+  return { valid: true, event: JSON.parse(input.body) };
+};
+
+exports.DEFAULT_TOLERANCE_SECONDS = DEFAULT_TOLERANCE_SECONDS;
+exports.SIGNATURE_HEADER = SIGNATURE_HEADER;
+exports.TIMESTAMP_HEADER = TIMESTAMP_HEADER;
+exports.computeWebhookSignature = computeWebhookSignature;
+exports.parseWebhookRequest = parseWebhookRequest;
+exports.verifyWebhookSignature = verifyWebhookSignature;

package/dist/webhooks.d.cts

@@ -0,0 +1,51 @@
+declare const SIGNATURE_HEADER = "x-owni-signature";
+declare const TIMESTAMP_HEADER = "x-owni-timestamp";
+/** Deliveries older than this are rejected, so a captured request can't be replayed. */
+declare const DEFAULT_TOLERANCE_SECONDS = 300;
+type OwniWebhookEvent<TData = Record<string, unknown>> = {
+    event: string;
+    data: TData;
+    sent_at: string;
+};
+type LeadCapturedEvent = OwniWebhookEvent<{
+    conversation_id?: string;
+    project_id?: string;
+    fields?: Record<string, unknown>;
+    [key: string]: unknown;
+}>;
+type VerifyWebhookInput = {
+    /** The raw request body, exactly as received. Re-serialized JSON will not verify. */
+    body: string;
+    signature: string | null | undefined;
+    timestamp: string | null | undefined;
+    secret: string;
+    toleranceSeconds?: number;
+    /** Injectable for tests; defaults to the current time. */
+    nowSeconds?: number;
+};
+type VerifyWebhookResult = {
+    valid: true;
+} | {
+    valid: false;
+    reason: 'missing_headers' | 'bad_signature' | 'stale_timestamp';
+};
+declare const computeWebhookSignature: (secret: string, timestamp: string, body: string) => string;
+declare const verifyWebhookSignature: (input: VerifyWebhookInput) => VerifyWebhookResult;
+type HeaderSource = Headers | Record<string, string | string[] | undefined>;
+/**
+ * Verifies and parses in one step. Works with both a `Headers` object (fetch/Next.js
+ * route handlers) and a plain header record (Express, Node http).
+ */
+declare const parseWebhookRequest: <TData = Record<string, unknown>>(input: {
+    body: string;
+    headers: HeaderSource;
+    secret: string;
+    toleranceSeconds?: number;
+}) => {
+    valid: true;
+    event: OwniWebhookEvent<TData>;
+} | (VerifyWebhookResult & {
+    valid: false;
+});
+
+export { DEFAULT_TOLERANCE_SECONDS, type HeaderSource, type LeadCapturedEvent, type OwniWebhookEvent, SIGNATURE_HEADER, TIMESTAMP_HEADER, type VerifyWebhookInput, type VerifyWebhookResult, computeWebhookSignature, parseWebhookRequest, verifyWebhookSignature };

package/dist/webhooks.d.ts

@@ -0,0 +1,51 @@
+declare const SIGNATURE_HEADER = "x-owni-signature";
+declare const TIMESTAMP_HEADER = "x-owni-timestamp";
+/** Deliveries older than this are rejected, so a captured request can't be replayed. */
+declare const DEFAULT_TOLERANCE_SECONDS = 300;
+type OwniWebhookEvent<TData = Record<string, unknown>> = {
+    event: string;
+    data: TData;
+    sent_at: string;
+};
+type LeadCapturedEvent = OwniWebhookEvent<{
+    conversation_id?: string;
+    project_id?: string;
+    fields?: Record<string, unknown>;
+    [key: string]: unknown;
+}>;
+type VerifyWebhookInput = {
+    /** The raw request body, exactly as received. Re-serialized JSON will not verify. */
+    body: string;
+    signature: string | null | undefined;
+    timestamp: string | null | undefined;
+    secret: string;
+    toleranceSeconds?: number;
+    /** Injectable for tests; defaults to the current time. */
+    nowSeconds?: number;
+};
+type VerifyWebhookResult = {
+    valid: true;
+} | {
+    valid: false;
+    reason: 'missing_headers' | 'bad_signature' | 'stale_timestamp';
+};
+declare const computeWebhookSignature: (secret: string, timestamp: string, body: string) => string;
+declare const verifyWebhookSignature: (input: VerifyWebhookInput) => VerifyWebhookResult;
+type HeaderSource = Headers | Record<string, string | string[] | undefined>;
+/**
+ * Verifies and parses in one step. Works with both a `Headers` object (fetch/Next.js
+ * route handlers) and a plain header record (Express, Node http).
+ */
+declare const parseWebhookRequest: <TData = Record<string, unknown>>(input: {
+    body: string;
+    headers: HeaderSource;
+    secret: string;
+    toleranceSeconds?: number;
+}) => {
+    valid: true;
+    event: OwniWebhookEvent<TData>;
+} | (VerifyWebhookResult & {
+    valid: false;
+});
+
+export { DEFAULT_TOLERANCE_SECONDS, type HeaderSource, type LeadCapturedEvent, type OwniWebhookEvent, SIGNATURE_HEADER, TIMESTAMP_HEADER, type VerifyWebhookInput, type VerifyWebhookResult, computeWebhookSignature, parseWebhookRequest, verifyWebhookSignature };

package/dist/webhooks.js

@@ -0,0 +1,53 @@
+import { createHmac, timingSafeEqual } from 'crypto';
+
+// src/webhooks.ts
+var SIGNATURE_HEADER = "x-owni-signature";
+var TIMESTAMP_HEADER = "x-owni-timestamp";
+var DEFAULT_TOLERANCE_SECONDS = 300;
+var computeWebhookSignature = (secret, timestamp, body) => `sha256=${createHmac("sha256", secret).update(`${timestamp}.${body}`).digest("hex")}`;
+var safeEquals = (a, b) => {
+  const bufferA = Buffer.from(a);
+  const bufferB = Buffer.from(b);
+  if (bufferA.length !== bufferB.length) return false;
+  return timingSafeEqual(bufferA, bufferB);
+};
+var verifyWebhookSignature = (input) => {
+  if (!input.signature || !input.timestamp) {
+    return { valid: false, reason: "missing_headers" };
+  }
+  const timestampSeconds = Number(input.timestamp);
+  if (!Number.isFinite(timestampSeconds)) {
+    return { valid: false, reason: "stale_timestamp" };
+  }
+  const now = input.nowSeconds ?? Math.floor(Date.now() / 1e3);
+  const tolerance = input.toleranceSeconds ?? DEFAULT_TOLERANCE_SECONDS;
+  if (Math.abs(now - timestampSeconds) > tolerance) {
+    return { valid: false, reason: "stale_timestamp" };
+  }
+  const expected = computeWebhookSignature(input.secret, input.timestamp, input.body);
+  if (!safeEquals(expected, input.signature)) {
+    return { valid: false, reason: "bad_signature" };
+  }
+  return { valid: true };
+};
+var readHeader = (headers, name) => {
+  if (typeof headers.get === "function") {
+    return headers.get(name);
+  }
+  const record = headers;
+  const value = record[name] ?? record[name.toLowerCase()];
+  return Array.isArray(value) ? value[0] ?? null : value ?? null;
+};
+var parseWebhookRequest = (input) => {
+  const result = verifyWebhookSignature({
+    body: input.body,
+    signature: readHeader(input.headers, SIGNATURE_HEADER),
+    timestamp: readHeader(input.headers, TIMESTAMP_HEADER),
+    secret: input.secret,
+    toleranceSeconds: input.toleranceSeconds
+  });
+  if (!result.valid) return result;
+  return { valid: true, event: JSON.parse(input.body) };
+};
+
+export { DEFAULT_TOLERANCE_SECONDS, SIGNATURE_HEADER, TIMESTAMP_HEADER, computeWebhookSignature, parseWebhookRequest, verifyWebhookSignature };

package/dist/widget.cjs

@@ -0,0 +1,102 @@
+'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;
+  }
+};
+
+// src/widget.ts
+var OwniWidgetClient = class {
+  baseUrl;
+  projectKey;
+  fetchImpl;
+  constructor(options) {
+    this.baseUrl = (options.baseUrl ?? "https://app.owni.chat").replace(/\/+$/, "");
+    this.projectKey = options.projectKey;
+    const resolved = options.fetch ?? globalThis.fetch;
+    if (!resolved) {
+      throw new Error("No fetch implementation found. Pass `fetch` in the client options.");
+    }
+    this.fetchImpl = resolved;
+  }
+  async request(path, init) {
+    const url = `${this.baseUrl}/api/widget/${encodeURIComponent(this.projectKey)}${path}`;
+    const response = await this.fetchImpl(url, {
+      ...init,
+      headers: { "Content-Type": "application/json", ...init?.headers ?? {} },
+      credentials: "omit",
+      mode: "cors"
+    });
+    if (!response.ok) {
+      let message = `Widget API responded with status ${response.status}`;
+      let body = null;
+      try {
+        body = await response.json();
+        if (body && typeof body === "object" && "message" in body && typeof body.message === "string") {
+          message = body.message;
+        }
+      } catch {
+      }
+      throw new OwniApiError(response.status, message, body);
+    }
+    return await response.json();
+  }
+  getConfig() {
+    return this.request("/config");
+  }
+  createSession(input = {}) {
+    return this.request("/session", {
+      method: "POST",
+      body: JSON.stringify(input)
+    });
+  }
+  listMessages(input) {
+    const query = new URLSearchParams({
+      visitor_id: input.visitorId,
+      visitor_token: input.visitorToken
+    });
+    return this.request(
+      `/conversations/${encodeURIComponent(input.conversationId)}/messages?${query.toString()}`
+    );
+  }
+  sendMessage(input) {
+    return this.request(`/conversations/${encodeURIComponent(input.conversationId)}/messages`, {
+      method: "POST",
+      body: JSON.stringify({
+        visitor_id: input.visitorId,
+        visitor_token: input.visitorToken,
+        content: input.content
+      })
+    });
+  }
+  lookupOrder(input) {
+    return this.request("/order-lookup", {
+      method: "POST",
+      body: JSON.stringify({
+        order_number: input.orderNumber,
+        email: input.email,
+        visitor_id: input.visitorId,
+        visitor_token: input.visitorToken
+      })
+    });
+  }
+};
+var createWidgetClient = (options) => new OwniWidgetClient(options);
+
+exports.OwniWidgetClient = OwniWidgetClient;
+exports.createWidgetClient = createWidgetClient;

package/dist/widget.d.cts

@@ -0,0 +1,82 @@
+type WidgetProductCard = {
+    type: 'product';
+    product_id?: string | null;
+    external_id?: string | null;
+    title: string;
+    price?: string | number | null;
+    old_price?: string | number | null;
+    currency?: string | null;
+    image_url?: string | null;
+    url: string;
+    attributes?: Array<{
+        name: string;
+        value: string;
+    }>;
+};
+type WidgetSessionInput = {
+    visitor_id?: string | null;
+    source_page_url?: string | null;
+    timezone?: string | null;
+    referrer?: string | null;
+    language?: string | null;
+};
+type WidgetSession = {
+    visitor_id: string;
+    visitor_token: string;
+    conversation_id?: string;
+    [key: string]: unknown;
+};
+type WidgetMessage = {
+    id: string;
+    conversation_id: string;
+    sender_type: string;
+    content: string;
+    created_at: string;
+    cards?: WidgetProductCard[];
+    [key: string]: unknown;
+};
+type OrderLookupResult = {
+    connected: boolean;
+    provider: string | null;
+    found: boolean;
+    email_matches: boolean;
+    order: Record<string, unknown> | null;
+};
+type WidgetClientOptions = {
+    projectKey: string;
+    baseUrl?: string;
+    fetch?: typeof fetch;
+};
+declare class OwniWidgetClient {
+    private readonly baseUrl;
+    private readonly projectKey;
+    private readonly fetchImpl;
+    constructor(options: WidgetClientOptions);
+    private request;
+    getConfig<T = Record<string, unknown>>(): Promise<T>;
+    createSession(input?: WidgetSessionInput): Promise<WidgetSession>;
+    listMessages(input: {
+        conversationId: string;
+        visitorId: string;
+        visitorToken: string;
+    }): Promise<{
+        messages: WidgetMessage[];
+    }>;
+    sendMessage(input: {
+        conversationId: string;
+        visitorId: string;
+        visitorToken: string;
+        content: string;
+    }): Promise<{
+        message: WidgetMessage;
+    }>;
+    lookupOrder(input: {
+        orderNumber: string;
+        email: string;
+        visitorId: string;
+        visitorToken: string;
+    }): Promise<OrderLookupResult>;
+}
+declare const createWidgetClient: (options: WidgetClientOptions) => OwniWidgetClient;
+
+export { type OrderLookupResult, OwniWidgetClient, type WidgetClientOptions, type WidgetMessage, type WidgetProductCard, type WidgetSession, type WidgetSessionInput, createWidgetClient };

package/dist/widget.d.ts

@@ -0,0 +1,82 @@
+type WidgetProductCard = {
+    type: 'product';
+    product_id?: string | null;
+    external_id?: string | null;
+    title: string;
+    price?: string | number | null;
+    old_price?: string | number | null;
+    currency?: string | null;
+    image_url?: string | null;
+    url: string;
+    attributes?: Array<{
+        name: string;
+        value: string;
+    }>;
+};
+type WidgetSessionInput = {
+    visitor_id?: string | null;
+    source_page_url?: string | null;
+    timezone?: string | null;
+    referrer?: string | null;
+    language?: string | null;
+};
+type WidgetSession = {
+    visitor_id: string;
+    visitor_token: string;
+    conversation_id?: string;
+    [key: string]: unknown;
+};
+type WidgetMessage = {
+    id: string;
+    conversation_id: string;
+    sender_type: string;
+    content: string;
+    created_at: string;
+    cards?: WidgetProductCard[];
+    [key: string]: unknown;
+};
+type OrderLookupResult = {
+    connected: boolean;
+    provider: string | null;
+    found: boolean;
+    email_matches: boolean;
+    order: Record<string, unknown> | null;
+};
+type WidgetClientOptions = {
+    projectKey: string;
+    baseUrl?: string;
+    fetch?: typeof fetch;
+};
+declare class OwniWidgetClient {
+    private readonly baseUrl;
+    private readonly projectKey;
+    private readonly fetchImpl;
+    constructor(options: WidgetClientOptions);
+    private request;
+    getConfig<T = Record<string, unknown>>(): Promise<T>;
+    createSession(input?: WidgetSessionInput): Promise<WidgetSession>;
+    listMessages(input: {
+        conversationId: string;
+        visitorId: string;
+        visitorToken: string;
+    }): Promise<{
+        messages: WidgetMessage[];
+    }>;
+    sendMessage(input: {
+        conversationId: string;
+        visitorId: string;
+        visitorToken: string;
+        content: string;
+    }): Promise<{
+        message: WidgetMessage;
+    }>;
+    lookupOrder(input: {
+        orderNumber: string;
+        email: string;
+        visitorId: string;
+        visitorToken: string;
+    }): Promise<OrderLookupResult>;
+}
+declare const createWidgetClient: (options: WidgetClientOptions) => OwniWidgetClient;
+
+export { type OrderLookupResult, OwniWidgetClient, type WidgetClientOptions, type WidgetMessage, type WidgetProductCard, type WidgetSession, type WidgetSessionInput, createWidgetClient };

package/dist/widget.js

@@ -0,0 +1,81 @@
+import { OwniApiError } from './chunk-2OWJTVJ3.js';
+
+// src/widget.ts
+var OwniWidgetClient = class {
+  baseUrl;
+  projectKey;
+  fetchImpl;
+  constructor(options) {
+    this.baseUrl = (options.baseUrl ?? "https://app.owni.chat").replace(/\/+$/, "");
+    this.projectKey = options.projectKey;
+    const resolved = options.fetch ?? globalThis.fetch;
+    if (!resolved) {
+      throw new Error("No fetch implementation found. Pass `fetch` in the client options.");
+    }
+    this.fetchImpl = resolved;
+  }
+  async request(path, init) {
+    const url = `${this.baseUrl}/api/widget/${encodeURIComponent(this.projectKey)}${path}`;
+    const response = await this.fetchImpl(url, {
+      ...init,
+      headers: { "Content-Type": "application/json", ...init?.headers ?? {} },
+      credentials: "omit",
+      mode: "cors"
+    });
+    if (!response.ok) {
+      let message = `Widget API responded with status ${response.status}`;
+      let body = null;
+      try {
+        body = await response.json();
+        if (body && typeof body === "object" && "message" in body && typeof body.message === "string") {
+          message = body.message;
+        }
+      } catch {
+      }
+      throw new OwniApiError(response.status, message, body);
+    }
+    return await response.json();
+  }
+  getConfig() {
+    return this.request("/config");
+  }
+  createSession(input = {}) {
+    return this.request("/session", {
+      method: "POST",
+      body: JSON.stringify(input)
+    });
+  }
+  listMessages(input) {
+    const query = new URLSearchParams({
+      visitor_id: input.visitorId,
+      visitor_token: input.visitorToken
+    });
+    return this.request(
+      `/conversations/${encodeURIComponent(input.conversationId)}/messages?${query.toString()}`
+    );
+  }
+  sendMessage(input) {
+    return this.request(`/conversations/${encodeURIComponent(input.conversationId)}/messages`, {
+      method: "POST",
+      body: JSON.stringify({
+        visitor_id: input.visitorId,
+        visitor_token: input.visitorToken,
+        content: input.content
+      })
+    });
+  }
+  lookupOrder(input) {
+    return this.request("/order-lookup", {
+      method: "POST",
+      body: JSON.stringify({
+        order_number: input.orderNumber,
+        email: input.email,
+        visitor_id: input.visitorId,
+        visitor_token: input.visitorToken
+      })
+    });
+  }
+};
+var createWidgetClient = (options) => new OwniWidgetClient(options);
+
+export { OwniWidgetClient, createWidgetClient };

package/package.json

@@ -0,0 +1,92 @@
+{
+  "name": "@ownichat/sdk",
+  "version": "0.1.0",
+  "description": "Official owni.chat API client: product catalog sync, knowledge sources, allowed domains, webhook verification and the public widget API.",
+  "license": "MIT",
+  "homepage": "https://owni.chat",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/UpMon-app/chats.git",
+    "directory": "integrations/javascript/packages/sdk"
+  },
+  "keywords": [
+    "owni",
+    "ownichat",
+    "live chat",
+    "ai chat widget",
+    "ecommerce",
+    "product catalog"
+  ],
+  "type": "module",
+  "sideEffects": false,
+  "exports": {
+    ".": {
+      "import": {
+        "types": "./dist/index.d.ts",
+        "default": "./dist/index.js"
+      },
+      "require": {
+        "types": "./dist/index.d.cts",
+        "default": "./dist/index.cjs"
+      }
+    },
+    "./webhooks": {
+      "import": {
+        "types": "./dist/webhooks.d.ts",
+        "default": "./dist/webhooks.js"
+      },
+      "require": {
+        "types": "./dist/webhooks.d.cts",
+        "default": "./dist/webhooks.cjs"
+      }
+    },
+    "./widget": {
+      "import": {
+        "types": "./dist/widget.d.ts",
+        "default": "./dist/widget.js"
+      },
+      "require": {
+        "types": "./dist/widget.d.cts",
+        "default": "./dist/widget.cjs"
+      }
+    },
+    "./package.json": "./package.json"
+  },
+  "main": "./dist/index.cjs",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "files": [
+    "dist",
+    "README.md",
+    "CHANGELOG.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "build": "tsup",
+    "test": "vitest run",
+    "typecheck": "tsc --noEmit"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "devDependencies": {
+    "@types/node": "^22.20.1"
+  },
+  "typesVersions": {
+    "*": {
+      "webhooks": [
+        "./dist/webhooks.d.ts"
+      ],
+      "widget": [
+        "./dist/widget.d.ts"
+      ]
+    }
+  },
+  "bugs": {
+    "url": "https://github.com/UpMon-app/chats/issues"
+  },
+  "author": "owni.chat"
+}