@anhora/sdk 0.1.0 → 0.3.0

package/README.md

@@ -1,30 +1,48 @@
 # @anhora/sdk
 
-Framework-agnostic Anhora API client: connectors ingest/sync, content upsert, deployment runtime, embed release config.
-
-```bash
-npm install @anhora/sdk
-```
+Server SDK for Anhora deployments and universal integration ingest. Connector
+writes use a stable integration id, namespace, idempotent delta events, and
+atomic paged snapshots.
 
 ```ts
-import { createAnhora } from '@anhora/sdk'
+import { createAnhora } from "@anhora/sdk";
 
 const anhora = createAnhora({
-  apiBase: 'https://api.anhora.net/api',
+  apiBase: process.env.ANHORA_API_BASE,
   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')
+  installationId: process.env.ANHORA_INTEGRATION_ID!,
+  namespace: "my_cms.content",
+  eventId: `page:${page.id}:${page.version}`,
+  document: {
+    externalId: page.id,
+    title: page.title,
+    content: page.plainText,
+    url: page.url,
+    sourceSequence: page.version,
+    sourceUpdatedAt: page.updatedAt.toISOString(),
+  },
+});
 ```
 
-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)
+Deletes are first-class tombstones:
+
+```ts
+await anhora.content.delete({
+  installationId,
+  namespace: "my_cms.content",
+  externalId: page.id,
+  eventId: `page:${page.id}:deleted:${page.version}`,
+  sourceSequence: page.version,
+});
+```
+
+Use `content.replaceAll()` for a bounded in-memory source. For large or streamed
+sources, use `connectors.replaceSnapshot()` with pages of at most 500 items.
+An empty snapshot is valid and removes the previous contents of that namespace.
+
+The ingest secret is server-only. The integration id selects ownership; a widget
+id is not part of the V2 write contract. See
+[`docs/sdk-backend-integration.md`](../../docs/sdk-backend-integration.md).

package/dist/client.d.ts

@@ -21,14 +21,14 @@ export type AnhoraClient = {
  * })
  *
  * await anhora.content.upsert({
- *   widgetId: '...',
- *   source: 'payload',
- *   externalId: page.id,
- *   title: page.title,
- *   content: plainText,
+ *   installationId: '...',
+ *   namespace: 'payload.pages',
+ *   document: {
+ *     externalId: page.id,
+ *     title: page.title,
+ *     content: plainText,
+ *   },
  * })
- *
- * await anhora.connectors.sync({ widgetId: '...' })
  * await anhora.deployments.getRuntime(deploymentKey, { origin })
  * await anhora.embed.getWidgetRelease('stable')
  * ```

package/dist/client.js

@@ -16,14 +16,14 @@ const http_1 = require("./http");
  * })
  *
  * await anhora.content.upsert({
- *   widgetId: '...',
- *   source: 'payload',
- *   externalId: page.id,
- *   title: page.title,
- *   content: plainText,
+ *   installationId: '...',
+ *   namespace: 'payload.pages',
+ *   document: {
+ *     externalId: page.id,
+ *     title: page.title,
+ *     content: plainText,
+ *   },
  * })
- *
- * await anhora.connectors.sync({ widgetId: '...' })
  * await anhora.deployments.getRuntime(deploymentKey, { origin })
  * await anhora.embed.getWidgetRelease('stable')
  * ```

package/dist/connectors.d.ts

@@ -1,54 +1,90 @@
-import type { ConnectorIngestRequest, ConnectorIngestResponse, ConnectorSyncRequest, IngestCatalogItem, IngestKnowledgeItem } from '@anhora/shared-types';
+import type { BeginConnectorSnapshotRequest, ConnectorEntityType, ConnectorEvent, ConnectorEventsAcceptedResponse, ConnectorSnapshotPageRequest, ConnectorDocumentMetadata } from '@anhora/shared-types';
 import type { AnhoraHttp } from './http';
-export type ConnectorSyncResponse = {
+export type BeginSnapshotResponse = {
     ok: true;
-    widgetId: string;
-    source: string;
-    results: Record<string, unknown>;
+    runId: string;
+    status: 'receiving';
+    maxItemsPerPage: number;
+    startedAt: string;
 };
-export type ContentUpsertInput = {
-    widgetId: string;
-    /** Source namespace for external ids, e.g. `payload`, `wordpress`. */
-    source: string;
+export type SnapshotPageResponse = {
+    ok: true;
+    runId: string;
+    page: number;
+    accepted: number;
+    duplicate: boolean;
+    checksum: string;
+};
+export type CommitSnapshotResponse = {
+    ok: true;
+    runId: string;
+    status: 'completed';
+    pages: number;
+    items: number;
+};
+export type ContentDocumentInput = {
     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;
+    locale?: string;
+    sourceVersion?: string;
+    sourceSequence?: number;
+    sourceUpdatedAt?: string;
+    document?: ConnectorDocumentMetadata;
 };
 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>;
+    events(input: {
+        installationId: string;
+        namespace: string;
+        events: ConnectorEvent[];
+    }): Promise<ConnectorEventsAcceptedResponse>;
+    beginSnapshot(installationId: string, input: BeginConnectorSnapshotRequest): Promise<BeginSnapshotResponse>;
+    uploadSnapshotPage(installationId: string, runId: string, page: number, input: ConnectorSnapshotPageRequest): Promise<SnapshotPageResponse>;
+    commitSnapshot(installationId: string, runId: string, expectedPages: number): Promise<CommitSnapshotResponse>;
+    abortSnapshot(installationId: string, runId: string): Promise<void>;
+    replaceSnapshot(input: {
+        installationId: string;
+        namespace: string;
+        entityType: ConnectorEntityType;
+        /** Synchronous ownership/cancellation guard before each new begin/page/commit request. */
+        beforeRequest?: () => void;
+        pages: Iterable<ConnectorSnapshotPageRequest> | AsyncIterable<ConnectorSnapshotPageRequest>;
+    }): Promise<CommitSnapshotResponse>;
 }
 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>;
+    upsert(input: {
+        installationId: string;
+        namespace: string;
+        document: ContentDocumentInput;
+        eventId?: string;
+        entityType?: 'knowledge_document' | 'content_document';
+    }): Promise<ConnectorEventsAcceptedResponse>;
+    delete(input: {
+        installationId: string;
+        namespace: string;
+        externalId: string;
+        eventId: string;
+        entityType?: 'knowledge_document' | 'content_document';
+        sourceSequence?: number;
+        sourceUpdatedAt?: string;
+    }): Promise<ConnectorEventsAcceptedResponse>;
+    upsertMany(input: {
+        installationId: string;
+        namespace: string;
+        documents: ContentDocumentInput[];
+        eventIdFor: (document: ContentDocumentInput) => string;
+        entityType?: 'knowledge_document' | 'content_document';
+    }): Promise<ConnectorEventsAcceptedResponse>;
+    replaceAll(input: {
+        installationId: string;
+        namespace: string;
+        documents: ContentDocumentInput[];
+        entityType?: 'knowledge_document' | 'content_document';
+        pageSize?: number;
+    }): Promise<CommitSnapshotResponse>;
 }

package/dist/connectors.js

@@ -1,89 +1,154 @@
 "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', {
+    events(input) {
+        const id = encodeURIComponent(input.installationId.trim());
+        return this.http.request(`/v2/integrations/${id}/events`, {
             method: 'POST',
-            body,
             auth: 'ingest',
+            body: {
+                schemaVersion: 2,
+                namespace: input.namespace,
+                events: input.events,
+            },
         });
     }
-    sync(body) {
-        return this.http.request('/v1/connectors/sync', {
-            method: 'POST',
-            body,
-            auth: 'ingest',
-        });
+    beginSnapshot(installationId, input) {
+        const id = encodeURIComponent(installationId.trim());
+        return this.http.request(`/v2/integrations/${id}/snapshots`, { method: 'POST', auth: 'ingest', body: input });
     }
-    ingestCatalog(input) {
-        return this.ingest({
-            widgetId: input.widgetId,
-            catalog: input.items,
-            replace: input.replace ? { catalog: true } : undefined,
-        });
+    uploadSnapshotPage(installationId, runId, page, input) {
+        const installation = encodeURIComponent(installationId.trim());
+        const run = encodeURIComponent(runId.trim());
+        return this.http.request(`/v2/integrations/${installation}/snapshots/${run}/pages/${page}`, { method: 'PUT', auth: 'ingest', body: input });
+    }
+    commitSnapshot(installationId, runId, expectedPages) {
+        const installation = encodeURIComponent(installationId.trim());
+        const run = encodeURIComponent(runId.trim());
+        return this.http.request(`/v2/integrations/${installation}/snapshots/${run}/commit`, { method: 'POST', auth: 'ingest', body: { expectedPages } });
     }
-    ingestKnowledge(input) {
-        return this.ingest({
-            widgetId: input.widgetId,
-            knowledge: input.items,
-            replace: input.replace
-                ? {
-                    knowledge: true,
-                    knowledgeExternalIdPrefix: input.knowledgeExternalIdPrefix,
-                }
-                : undefined,
+    abortSnapshot(installationId, runId) {
+        const installation = encodeURIComponent(installationId.trim());
+        const run = encodeURIComponent(runId.trim());
+        return this.http.request(`/v2/integrations/${installation}/snapshots/${run}/abort`, { method: 'POST', auth: 'ingest' });
+    }
+    async replaceSnapshot(input) {
+        input.beforeRequest?.();
+        const run = await this.beginSnapshot(input.installationId, {
+            schemaVersion: 2,
+            namespace: input.namespace,
+            entityType: input.entityType,
         });
+        let page = 0;
+        try {
+            for await (const body of input.pages) {
+                input.beforeRequest?.();
+                await this.uploadSnapshotPage(input.installationId, run.runId, page, body);
+                page += 1;
+            }
+            input.beforeRequest?.();
+            return await this.commitSnapshot(input.installationId, run.runId, page);
+        }
+        catch (error) {
+            await this.abortSnapshot(input.installationId, run.runId).catch(() => undefined);
+            throw error;
+        }
     }
 }
 exports.AnhoraConnectorsApi = AnhoraConnectorsApi;
+function eventId(prefix, externalId, supplied) {
+    return supplied?.trim() || `${prefix}:${externalId}:${crypto.randomUUID()}`;
+}
+function contentPayload(item) {
+    return {
+        title: item.title,
+        content: item.content,
+        ...(item.url ? { url: item.url } : {}),
+        ...(item.locale ? { locale: item.locale } : {}),
+        ...(item.document ? { document: item.document } : {}),
+    };
+}
 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: [
+        const item = input.document;
+        return this.connectors.events({
+            installationId: input.installationId,
+            namespace: input.namespace,
+            events: [
+                {
+                    eventId: eventId(input.namespace, item.externalId, input.eventId),
+                    entityType: input.entityType ?? 'content_document',
+                    externalId: item.externalId,
+                    operation: 'upsert',
+                    sourceVersion: item.sourceVersion,
+                    sourceSequence: item.sourceSequence,
+                    sourceUpdatedAt: item.sourceUpdatedAt,
+                    payload: contentPayload(item),
+                },
+            ],
+        });
+    }
+    delete(input) {
+        return this.connectors.events({
+            installationId: input.installationId,
+            namespace: input.namespace,
+            events: [
                 {
+                    eventId: input.eventId,
+                    entityType: input.entityType ?? 'content_document',
                     externalId: input.externalId,
-                    title: input.title,
-                    content: input.content,
-                    url: input.url,
+                    operation: 'delete',
+                    sourceSequence: input.sourceSequence,
+                    sourceUpdatedAt: input.sourceUpdatedAt,
                 },
             ],
         });
     }
     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,
+        return this.connectors.events({
+            installationId: input.installationId,
+            namespace: input.namespace,
+            events: input.documents.map((item) => ({
+                eventId: input.eventIdFor(item),
+                entityType: input.entityType ?? 'content_document',
+                externalId: item.externalId,
+                operation: 'upsert',
+                sourceVersion: item.sourceVersion,
+                sourceSequence: item.sourceSequence,
+                sourceUpdatedAt: item.sourceUpdatedAt,
+                payload: contentPayload(item),
             })),
         });
     }
+    replaceAll(input) {
+        const pageSize = Math.max(1, Math.min(input.pageSize ?? 500, 500));
+        const pages = [];
+        for (let offset = 0; offset < input.documents.length; offset += pageSize) {
+            pages.push({
+                items: input.documents.slice(offset, offset + pageSize).map((item) => ({
+                    externalId: item.externalId,
+                    sourceVersion: item.sourceVersion,
+                    sourceSequence: item.sourceSequence,
+                    sourceUpdatedAt: item.sourceUpdatedAt,
+                    payload: contentPayload(item),
+                })),
+            });
+        }
+        return this.connectors.replaceSnapshot({
+            installationId: input.installationId,
+            namespace: input.namespace,
+            entityType: input.entityType ?? 'content_document',
+            pages,
+        });
+    }
 }
 exports.AnhoraContentApi = AnhoraContentApi;

package/dist/http.js

@@ -22,7 +22,7 @@ class AnhoraHttp {
         }
         if (options.auth === 'ingest') {
             if (!this.ingestSecret) {
-                throw new Error('Anhora ingestSecret is required for connectors.ingest / connectors.sync');
+                throw new Error('Anhora ingestSecret is required for connector events and snapshots');
             }
             headers['X-Anhora-Ingest-Secret'] = this.ingestSecret;
         }

package/dist/index.d.ts

@@ -1,8 +1,8 @@
 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 { AnhoraClientConfig, AnhoraFetch, RequestOptions } from './types';
+export type { BeginSnapshotResponse, CommitSnapshotResponse, ContentDocumentInput, SnapshotPageResponse, } from './connectors';
 export type { WidgetReleaseWithUrl } from './embed';
 /** @deprecated Use `createAnhora().widgets.getConfig` / `deployments.getRuntime`. */
 export { AnhoraClient as LegacyAnhoraClient } from './legacy';

package/dist/legacy.js

@@ -14,6 +14,8 @@ class AnhoraClient {
         return this.anhora.widgets.getConfig(this.widgetId);
     }
     async sendMessage(_message, _sessionId) {
+        void _message;
+        void _sessionId;
         throw new Error('Legacy AnhoraClient.sendMessage is removed. Use the embed widget or POST /api/v1/chat/message with a deploymentKey.');
     }
 }

package/dist/types.d.ts

@@ -11,7 +11,7 @@ export type AnhoraClientConfig = {
      */
     apiBase?: string;
     /**
-     * Server-side ingest secret for `/connectors/ingest` and `/connectors/sync`.
+     * Server-side ingest secret for V2 integration events and snapshots.
      * Sent as `X-Anhora-Ingest-Secret` (Bearer also accepted by the API).
      */
     ingestSecret?: string;

package/dist/types.js

@@ -14,12 +14,18 @@ class AnhoraApiError extends Error {
 }
 exports.AnhoraApiError = AnhoraApiError;
 function normalizeApiBase(apiBase) {
-    let normalized = apiBase.trim().replace(/\/+$/u, '');
+    let normalized = apiBase.trim();
+    while (normalized.endsWith('/')) {
+        normalized = normalized.slice(0, -1);
+    }
     if (!normalized) {
         return 'https://api.anhora.net/api';
     }
     // Accept both `.../api` and `.../api/v1` from older snippets.
-    normalized = normalized.replace(/\/v\d+$/u, '');
+    const versionSuffix = normalized.match(/\/v\d+$/u);
+    if (versionSuffix) {
+        normalized = normalized.slice(0, -versionSuffix[0].length);
+    }
     if (!normalized.endsWith('/api')) {
         normalized = `${normalized}/api`;
     }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@anhora/sdk",
-  "version": "0.1.0",
+  "version": "0.3.0",
   "description": "Framework-agnostic Anhora API client (connectors, content ingest, deployment runtime)",
   "license": "MIT",
   "author": "Anhora",
@@ -37,7 +37,7 @@
     "access": "public"
   },
   "dependencies": {
-    "@anhora/shared-types": "0.1.0"
+    "@anhora/shared-types": "0.3.0"
   },
   "devDependencies": {
     "eslint": "^9.24.0",