@anhora/sdk 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Anhora
+
+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,30 @@
+# @anhora/sdk
+
+Framework-agnostic Anhora API client: connectors ingest/sync, content upsert, deployment runtime, embed release config.
+
+```bash
+npm install @anhora/sdk
+```
+
+```ts
+import { createAnhora } from '@anhora/sdk'
+
+const anhora = createAnhora({
+  apiBase: 'https://api.anhora.net/api',
+  ingestSecret: process.env.ANHORA_INGEST_SECRET,
+})
+
+await anhora.content.upsert({
+  widgetId: '…',
+  source: 'payload',
+  externalId: 'page-1',
+  title: 'Home',
+  content: '…',
+})
+
+await anhora.connectors.sync({ widgetId: '…' })
+await anhora.deployments.getRuntime(deploymentKey, { origin: 'https://example.com' })
+await anhora.embed.getWidgetRelease('stable')
+```
+
+Docs: [anhora.net](https://anhora.net) · Payload plugin: [`@anhora/payload`](https://www.npmjs.com/package/@anhora/payload) · Next: [`@anhora/next`](https://www.npmjs.com/package/@anhora/next)

package/dist/client.d.ts

@@ -0,0 +1,36 @@
+import { AnhoraConnectorsApi, AnhoraContentApi } from './connectors';
+import { AnhoraDeploymentsApi, AnhoraWidgetsApi } from './deployments';
+import { AnhoraEmbedApi } from './embed';
+import type { AnhoraClientConfig } from './types';
+export type AnhoraClient = {
+    readonly apiBase: string;
+    readonly connectors: AnhoraConnectorsApi;
+    readonly content: AnhoraContentApi;
+    readonly deployments: AnhoraDeploymentsApi;
+    readonly embed: AnhoraEmbedApi;
+    readonly widgets: AnhoraWidgetsApi;
+};
+/**
+ * Create the Anhora API client (framework-agnostic).
+ *
+ * @example
+ * ```ts
+ * const anhora = createAnhora({
+ *   apiBase: process.env.ANHORA_API_BASE,
+ *   ingestSecret: process.env.ANHORA_INGEST_SECRET,
+ * })
+ *
+ * await anhora.content.upsert({
+ *   widgetId: '...',
+ *   source: 'payload',
+ *   externalId: page.id,
+ *   title: page.title,
+ *   content: plainText,
+ * })
+ *
+ * await anhora.connectors.sync({ widgetId: '...' })
+ * await anhora.deployments.getRuntime(deploymentKey, { origin })
+ * await anhora.embed.getWidgetRelease('stable')
+ * ```
+ */
+export declare function createAnhora(config?: AnhoraClientConfig): AnhoraClient;

package/dist/client.js

@@ -0,0 +1,42 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createAnhora = createAnhora;
+const connectors_1 = require("./connectors");
+const deployments_1 = require("./deployments");
+const embed_1 = require("./embed");
+const http_1 = require("./http");
+/**
+ * Create the Anhora API client (framework-agnostic).
+ *
+ * @example
+ * ```ts
+ * const anhora = createAnhora({
+ *   apiBase: process.env.ANHORA_API_BASE,
+ *   ingestSecret: process.env.ANHORA_INGEST_SECRET,
+ * })
+ *
+ * await anhora.content.upsert({
+ *   widgetId: '...',
+ *   source: 'payload',
+ *   externalId: page.id,
+ *   title: page.title,
+ *   content: plainText,
+ * })
+ *
+ * await anhora.connectors.sync({ widgetId: '...' })
+ * await anhora.deployments.getRuntime(deploymentKey, { origin })
+ * await anhora.embed.getWidgetRelease('stable')
+ * ```
+ */
+function createAnhora(config = {}) {
+    const http = new http_1.AnhoraHttp(config);
+    const connectors = new connectors_1.AnhoraConnectorsApi(http);
+    return {
+        apiBase: http.apiBase,
+        connectors,
+        content: new connectors_1.AnhoraContentApi(connectors),
+        deployments: new deployments_1.AnhoraDeploymentsApi(http),
+        embed: new embed_1.AnhoraEmbedApi(http),
+        widgets: new deployments_1.AnhoraWidgetsApi(http),
+    };
+}

package/dist/connectors.d.ts

@@ -0,0 +1,54 @@
+import type { ConnectorIngestRequest, ConnectorIngestResponse, ConnectorSyncRequest, IngestCatalogItem, IngestKnowledgeItem } from '@anhora/shared-types';
+import type { AnhoraHttp } from './http';
+export type ConnectorSyncResponse = {
+    ok: true;
+    widgetId: string;
+    source: string;
+    results: Record<string, unknown>;
+};
+export type ContentUpsertInput = {
+    widgetId: string;
+    /** Source namespace for external ids, e.g. `payload`, `wordpress`. */
+    source: string;
+    externalId: string;
+    title: string;
+    content: string;
+    url?: string;
+    /** Replace prior knowledge with this source prefix. */
+    replace?: boolean;
+};
+export type ContentUpsertBatchInput = {
+    widgetId: string;
+    source: string;
+    items: Array<{
+        externalId: string;
+        title: string;
+        content: string;
+        url?: string;
+    }>;
+    replace?: boolean;
+};
+export declare class AnhoraConnectorsApi {
+    private readonly http;
+    constructor(http: AnhoraHttp);
+    ingest(body: ConnectorIngestRequest): Promise<ConnectorIngestResponse>;
+    sync(body: ConnectorSyncRequest): Promise<ConnectorSyncResponse>;
+    ingestCatalog(input: {
+        widgetId: string;
+        items: IngestCatalogItem[];
+        replace?: boolean;
+    }): Promise<ConnectorIngestResponse>;
+    ingestKnowledge(input: {
+        widgetId: string;
+        items: IngestKnowledgeItem[];
+        replace?: boolean;
+        knowledgeExternalIdPrefix?: string;
+    }): Promise<ConnectorIngestResponse>;
+}
+export declare class AnhoraContentApi {
+    private readonly connectors;
+    constructor(connectors: AnhoraConnectorsApi);
+    /** Convenience upsert for a single CMS/document knowledge row. */
+    upsert(input: ContentUpsertInput): Promise<ConnectorIngestResponse>;
+    upsertMany(input: ContentUpsertBatchInput): Promise<ConnectorIngestResponse>;
+}

package/dist/connectors.js

@@ -0,0 +1,89 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.AnhoraContentApi = exports.AnhoraConnectorsApi = void 0;
+function withSourcePrefix(source, externalId) {
+    const trimmedSource = source.trim().replace(/:+$/u, '');
+    const trimmedId = externalId.trim();
+    if (!trimmedSource)
+        return trimmedId;
+    if (trimmedId.startsWith(`${trimmedSource}:`))
+        return trimmedId;
+    return `${trimmedSource}:${trimmedId}`;
+}
+class AnhoraConnectorsApi {
+    http;
+    constructor(http) {
+        this.http = http;
+    }
+    ingest(body) {
+        return this.http.request('/v1/connectors/ingest', {
+            method: 'POST',
+            body,
+            auth: 'ingest',
+        });
+    }
+    sync(body) {
+        return this.http.request('/v1/connectors/sync', {
+            method: 'POST',
+            body,
+            auth: 'ingest',
+        });
+    }
+    ingestCatalog(input) {
+        return this.ingest({
+            widgetId: input.widgetId,
+            catalog: input.items,
+            replace: input.replace ? { catalog: true } : undefined,
+        });
+    }
+    ingestKnowledge(input) {
+        return this.ingest({
+            widgetId: input.widgetId,
+            knowledge: input.items,
+            replace: input.replace
+                ? {
+                    knowledge: true,
+                    knowledgeExternalIdPrefix: input.knowledgeExternalIdPrefix,
+                }
+                : undefined,
+        });
+    }
+}
+exports.AnhoraConnectorsApi = AnhoraConnectorsApi;
+class AnhoraContentApi {
+    connectors;
+    constructor(connectors) {
+        this.connectors = connectors;
+    }
+    /** Convenience upsert for a single CMS/document knowledge row. */
+    upsert(input) {
+        return this.upsertMany({
+            widgetId: input.widgetId,
+            source: input.source,
+            replace: input.replace,
+            items: [
+                {
+                    externalId: input.externalId,
+                    title: input.title,
+                    content: input.content,
+                    url: input.url,
+                },
+            ],
+        });
+    }
+    upsertMany(input) {
+        const prefix = input.source.trim().replace(/:+$/u, '');
+        return this.connectors.ingestKnowledge({
+            widgetId: input.widgetId,
+            knowledgeExternalIdPrefix: prefix ? `${prefix}:` : undefined,
+            replace: input.replace,
+            items: input.items.map((item) => ({
+                externalId: withSourcePrefix(input.source, item.externalId),
+                name: item.title,
+                content: item.content,
+                url: item.url,
+            })),
+        });
+    }
+}
+exports.AnhoraContentApi = AnhoraContentApi;

package/dist/deployments.d.ts

@@ -0,0 +1,19 @@
+import type { PublicWidgetConfig, PublicWidgetRuntimeConfig } from '@anhora/shared-types';
+import type { AnhoraHttp } from './http';
+export declare class AnhoraDeploymentsApi {
+    private readonly http;
+    constructor(http: AnhoraHttp);
+    /**
+     * Browser/SSR runtime bootstrap for a Site Chat deployment key.
+     * In production the API requires a matching HTTPS `Origin`.
+     */
+    getRuntime(deploymentKey: string, options?: {
+        origin?: string;
+    }): Promise<PublicWidgetRuntimeConfig>;
+}
+export declare class AnhoraWidgetsApi {
+    private readonly http;
+    constructor(http: AnhoraHttp);
+    /** Legacy public widget config by widget id (SaaS path). */
+    getConfig(widgetId: string): Promise<PublicWidgetConfig>;
+}

package/dist/deployments.js

@@ -0,0 +1,33 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.AnhoraWidgetsApi = exports.AnhoraDeploymentsApi = void 0;
+class AnhoraDeploymentsApi {
+    http;
+    constructor(http) {
+        this.http = http;
+    }
+    /**
+     * Browser/SSR runtime bootstrap for a Site Chat deployment key.
+     * In production the API requires a matching HTTPS `Origin`.
+     */
+    getRuntime(deploymentKey, options = {}) {
+        const key = encodeURIComponent(deploymentKey.trim());
+        return this.http.request(`/v1/deployments/${key}/runtime`, {
+            method: 'GET',
+            origin: options.origin,
+        });
+    }
+}
+exports.AnhoraDeploymentsApi = AnhoraDeploymentsApi;
+class AnhoraWidgetsApi {
+    http;
+    constructor(http) {
+        this.http = http;
+    }
+    /** Legacy public widget config by widget id (SaaS path). */
+    getConfig(widgetId) {
+        const id = encodeURIComponent(widgetId.trim());
+        return this.http.request(`/v1/widgets/${id}/config`);
+    }
+}
+exports.AnhoraWidgetsApi = AnhoraWidgetsApi;

package/dist/embed.d.ts

@@ -0,0 +1,16 @@
+import type { WidgetReleaseChannel, WidgetReleaseConfig } from '@anhora/shared-types';
+import type { AnhoraHttp } from './http';
+export type WidgetReleaseWithUrl = WidgetReleaseConfig & {
+    scriptUrl?: string;
+    cdnBaseUrl?: string;
+};
+export declare class AnhoraEmbedApi {
+    private readonly http;
+    constructor(http: AnhoraHttp);
+    /**
+     * Resolve stable/beta channel to a versioned widget script via the API.
+     * CDN JSON at `{cdn}/widget/channels/{channel}.json` is the primary path
+     * for the browser loader; this method is for servers/tooling.
+     */
+    getWidgetRelease(channel?: WidgetReleaseChannel): Promise<WidgetReleaseWithUrl>;
+}

package/dist/embed.js

@@ -0,0 +1,18 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.AnhoraEmbedApi = void 0;
+class AnhoraEmbedApi {
+    http;
+    constructor(http) {
+        this.http = http;
+    }
+    /**
+     * Resolve stable/beta channel to a versioned widget script via the API.
+     * CDN JSON at `{cdn}/widget/channels/{channel}.json` is the primary path
+     * for the browser loader; this method is for servers/tooling.
+     */
+    getWidgetRelease(channel = 'stable') {
+        return this.http.request(`/v1/embed/widget?channel=${encodeURIComponent(channel)}`);
+    }
+}
+exports.AnhoraEmbedApi = AnhoraEmbedApi;

package/dist/http.d.ts

@@ -0,0 +1,8 @@
+import type { AnhoraClientConfig, RequestOptions } from './types';
+export declare class AnhoraHttp {
+    readonly apiBase: string;
+    readonly ingestSecret?: string;
+    private readonly fetchImpl;
+    constructor(config?: AnhoraClientConfig);
+    request<T>(path: string, options?: RequestOptions): Promise<T>;
+}

package/dist/http.js

@@ -0,0 +1,47 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.AnhoraHttp = void 0;
+const types_1 = require("./types");
+const types_2 = require("./types");
+class AnhoraHttp {
+    apiBase;
+    ingestSecret;
+    fetchImpl;
+    constructor(config = {}) {
+        this.apiBase = (0, types_2.normalizeApiBase)(config.apiBase ?? 'https://api.anhora.net/api');
+        this.ingestSecret = config.ingestSecret?.trim() || undefined;
+        this.fetchImpl = config.fetch ?? fetch;
+    }
+    async request(path, options = {}) {
+        const headers = {
+            Accept: 'application/json',
+            ...options.headers,
+        };
+        if (options.body !== undefined) {
+            headers['Content-Type'] = 'application/json';
+        }
+        if (options.auth === 'ingest') {
+            if (!this.ingestSecret) {
+                throw new Error('Anhora ingestSecret is required for connectors.ingest / connectors.sync');
+            }
+            headers['X-Anhora-Ingest-Secret'] = this.ingestSecret;
+        }
+        if (options.origin) {
+            headers.Origin = options.origin;
+        }
+        const response = await this.fetchImpl(`${this.apiBase}${path}`, {
+            method: options.method ?? (options.body !== undefined ? 'POST' : 'GET'),
+            headers,
+            body: options.body === undefined ? undefined : JSON.stringify(options.body),
+        });
+        if (!response.ok) {
+            const text = await response.text();
+            throw new types_1.AnhoraApiError(`Anhora API ${options.method ?? 'GET'} ${path} failed: ${response.status}`, response.status, text);
+        }
+        if (response.status === 204) {
+            return undefined;
+        }
+        return (await response.json());
+    }
+}
+exports.AnhoraHttp = AnhoraHttp;

package/dist/index.d.ts

@@ -0,0 +1,9 @@
+export { createAnhora } from './client';
+export type { AnhoraClient } from './client';
+export { AnhoraApiError, normalizeApiBase } from './types';
+export type { AnhoraClientConfig, AnhoraFetch, RequestOptions, } from './types';
+export type { ConnectorSyncResponse, ContentUpsertBatchInput, ContentUpsertInput, } from './connectors';
+export type { WidgetReleaseWithUrl } from './embed';
+/** @deprecated Use `createAnhora().widgets.getConfig` / `deployments.getRuntime`. */
+export { AnhoraClient as LegacyAnhoraClient } from './legacy';
+export type { AnhoraClientOptions as LegacyAnhoraClientOptions } from './legacy';

package/dist/index.js

@@ -0,0 +1,11 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.LegacyAnhoraClient = exports.normalizeApiBase = exports.AnhoraApiError = exports.createAnhora = void 0;
+var client_1 = require("./client");
+Object.defineProperty(exports, "createAnhora", { enumerable: true, get: function () { return client_1.createAnhora; } });
+var types_1 = require("./types");
+Object.defineProperty(exports, "AnhoraApiError", { enumerable: true, get: function () { return types_1.AnhoraApiError; } });
+Object.defineProperty(exports, "normalizeApiBase", { enumerable: true, get: function () { return types_1.normalizeApiBase; } });
+/** @deprecated Use `createAnhora().widgets.getConfig` / `deployments.getRuntime`. */
+var legacy_1 = require("./legacy");
+Object.defineProperty(exports, "LegacyAnhoraClient", { enumerable: true, get: function () { return legacy_1.AnhoraClient; } });

package/dist/legacy.d.ts

@@ -0,0 +1,17 @@
+import type { ChatResponse, PublicWidgetConfig } from '@anhora/shared-types';
+/**
+ * @deprecated Prefer `createAnhora({ apiBase })`.
+ * Kept temporarily for older snippets that used widgetId + /chat.
+ */
+export interface AnhoraClientOptions {
+    baseUrl: string;
+    widgetId: string;
+}
+/** @deprecated */
+export declare class AnhoraClient {
+    private readonly anhora;
+    private readonly widgetId;
+    constructor(options: AnhoraClientOptions);
+    getWidgetConfig(): Promise<PublicWidgetConfig>;
+    sendMessage(_message: string, _sessionId?: string): Promise<ChatResponse>;
+}

package/dist/legacy.js

@@ -0,0 +1,20 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.AnhoraClient = void 0;
+const client_1 = require("./client");
+/** @deprecated */
+class AnhoraClient {
+    anhora;
+    widgetId;
+    constructor(options) {
+        this.widgetId = options.widgetId;
+        this.anhora = (0, client_1.createAnhora)({ apiBase: options.baseUrl });
+    }
+    getWidgetConfig() {
+        return this.anhora.widgets.getConfig(this.widgetId);
+    }
+    async sendMessage(_message, _sessionId) {
+        throw new Error('Legacy AnhoraClient.sendMessage is removed. Use the embed widget or POST /api/v1/chat/message with a deploymentKey.');
+    }
+}
+exports.AnhoraClient = AnhoraClient;

package/dist/types.d.ts

@@ -0,0 +1,30 @@
+export declare class AnhoraApiError extends Error {
+    readonly status: number;
+    readonly body: string;
+    constructor(message: string, status: number, body: string);
+}
+export type AnhoraFetch = typeof fetch;
+export type AnhoraClientConfig = {
+    /**
+     * API base including `/api`, e.g. `https://api.anhora.net/api`.
+     * @default 'https://api.anhora.net/api'
+     */
+    apiBase?: string;
+    /**
+     * Server-side ingest secret for `/connectors/ingest` and `/connectors/sync`.
+     * Sent as `X-Anhora-Ingest-Secret` (Bearer also accepted by the API).
+     */
+    ingestSecret?: string;
+    /** Override fetch (tests, custom agents). */
+    fetch?: AnhoraFetch;
+};
+export type RequestOptions = {
+    method?: 'GET' | 'POST' | 'PUT' | 'DELETE';
+    body?: unknown;
+    headers?: Record<string, string>;
+    /** When true, attach ingest secret headers. */
+    auth?: 'ingest';
+    /** Browser Origin for deployment runtime checks. */
+    origin?: string;
+};
+export declare function normalizeApiBase(apiBase: string): string;

package/dist/types.js

@@ -0,0 +1,27 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.AnhoraApiError = void 0;
+exports.normalizeApiBase = normalizeApiBase;
+class AnhoraApiError extends Error {
+    status;
+    body;
+    constructor(message, status, body) {
+        super(message);
+        this.name = 'AnhoraApiError';
+        this.status = status;
+        this.body = body;
+    }
+}
+exports.AnhoraApiError = AnhoraApiError;
+function normalizeApiBase(apiBase) {
+    let normalized = apiBase.trim().replace(/\/+$/u, '');
+    if (!normalized) {
+        return 'https://api.anhora.net/api';
+    }
+    // Accept both `.../api` and `.../api/v1` from older snippets.
+    normalized = normalized.replace(/\/v\d+$/u, '');
+    if (!normalized.endsWith('/api')) {
+        normalized = `${normalized}/api`;
+    }
+    return normalized;
+}

package/package.json

@@ -0,0 +1,57 @@
+{
+  "name": "@anhora/sdk",
+  "version": "0.1.0",
+  "description": "Framework-agnostic Anhora API client (connectors, content ingest, deployment runtime)",
+  "license": "MIT",
+  "author": "Anhora",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/denys-vodniakov/anhora.git",
+    "directory": "packages/sdk"
+  },
+  "homepage": "https://anhora.net",
+  "bugs": {
+    "url": "https://github.com/denys-vodniakov/anhora/issues"
+  },
+  "keywords": [
+    "anhora",
+    "sdk",
+    "chat",
+    "knowledge"
+  ],
+  "type": "commonjs",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "default": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "LICENSE",
+    "README.md"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "@anhora/shared-types": "0.1.0"
+  },
+  "devDependencies": {
+    "eslint": "^9.24.0",
+    "tsx": "^4.23.0",
+    "typescript": "^5.8.3",
+    "@anhora/eslint-config": "0.0.1"
+  },
+  "engines": {
+    "node": ">=20"
+  },
+  "scripts": {
+    "build": "tsc",
+    "lint": "eslint src/",
+    "typecheck": "tsc --noEmit",
+    "test": "node --import tsx --test test/**/*.spec.ts"
+  }
+}