xmemory 1.0.1 → 2.0.0

package/README.md

@@ -1,8 +1,210 @@
-# `xmemory`
+# xmemory
 
-Integration code with `xmemory`.
+TypeScript/JavaScript client library for the [Xmemory](https://xmemory.ai) API.
 
-For now just the Mastra prompt.
+## Installation
+
+```bash
+npm install xmemory
+```
+
+## Quick start
+
+```typescript
+import { XmemoryClient } from "xmemory";
+
+const xm = new XmemoryClient({
+  url: "https://api.xmemory.ai",  // or set XMEM_API_URL env var
+  token: "<your-token>",          // or set XMEM_AUTH_TOKEN env var
+});
+
+// Write and read from an existing instance
+const inst = xm.instance("<your-instance-id>");
+
+await inst.write("Alice is a software engineer who loves TypeScript.");
+const result = await inst.read("What does Alice do?");
+console.log(result.reader_result);
+```
+
+## Configuration
+
+| Parameter   | Env var           | Default                    | Description                            |
+|-------------|-------------------|----------------------------|----------------------------------------|
+| `url`       | `XMEM_API_URL`    | `https://api.xmemory.ai`  | Base URL of the Xmemory API            |
+| `token`     | `XMEM_AUTH_TOKEN` | `undefined`                | Bearer token for authentication        |
+| `timeoutMs` | —                 | `60000`                    | Default request timeout in milliseconds |
+
+## Creating a client
+
+```typescript
+import { XmemoryClient, xmemoryInstance } from "xmemory";
+
+// Option 1: constructor (no health check)
+const xm1 = new XmemoryClient({ token: "..." });
+
+// Option 2: factory with health check
+const xm2 = await XmemoryClient.create({ token: "..." });
+
+// Option 3: convenience function (same as Option 2)
+const xm3 = await xmemoryInstance({ token: "..." });
+```
+
+## Admin operations
+
+All cluster and instance management lives under `client.admin`.
+
+### Clusters
+
+```typescript
+const clusters = await xm.admin.listClusters();
+const cluster = await xm.admin.getCluster(clusterId);
+```
+
+### Create an instance
+
+```typescript
+import { SchemaType } from "xmemory";
+
+const inst = await xm.admin.createInstance(
+  clusterId,
+  "my-instance",
+  schemaYml,
+  SchemaType.YML,
+  { description: "User profiles" },
+);
+
+// inst is an InstanceHandle — use it directly for data operations
+await inst.write("Alice joined the team.");
+```
+
+### List and get instances
+
+```typescript
+const instances = await xm.admin.listInstances();
+const info = await xm.admin.getInstance(instanceId);
+```
+
+### Schema operations
+
+```typescript
+const schema = await xm.admin.getInstanceSchema(instanceId);
+await xm.admin.updateInstanceSchema(instanceId, newYml, SchemaType.YML);
+```
+
+### Generate schema
+
+```typescript
+const result = await xm.admin.generateSchema(clusterId, "Track user profiles and preferences");
+console.log(result.data_schema);
+```
+
+### Update metadata and delete
+
+```typescript
+await xm.admin.updateInstanceMetadata(instanceId, "new-name", "new description");
+const deletedIds = await xm.admin.deleteInstance(instanceId);
+```
+
+## Instance data operations
+
+Get a handle to an instance and use it for reads, writes, and extractions.
+
+```typescript
+const inst = xm.instance("<instance-id>");
+```
+
+### `inst.write(text, options?)` → `WriteResult`
+
+Extract and store structured objects from text.
+
+```typescript
+const result = await inst.write("Bob is a designer based in Berlin.");
+console.log(result.write_id, result.trace_id);
+```
+
+Options: `{ extractionLogic?, diffEngine?, timeoutMs? }` — `extractionLogic` defaults to `"deep"`.
+
+### `inst.writeAsync(text, options?)` → `AsyncWriteResult`
+
+Start an asynchronous write. Returns a `write_id` for tracking.
+
+```typescript
+const { write_id } = await inst.writeAsync("Carol manages the London office.");
+```
+
+### `inst.writeStatus(writeId, options?)` → `WriteStatusResult`
+
+Poll the status of an async write.
+
+```typescript
+const status = await inst.writeStatus(write_id);
+console.log(status.write_status); // "queued" | "processing" | "completed" | "failed" | "not_found"
+```
+
+### `inst.read(query, options?)` → `ReadResult`
+
+Query the instance.
+
+```typescript
+const result = await inst.read("Who is on the team?");
+console.log(result.reader_result);
+```
+
+Options: `{ readMode?, traceId?, timeoutMs? }` — `readMode` defaults to `"single-answer"`.
+
+### `inst.extract(text, options?)` → `ExtractResult`
+
+Extract objects from text without storing them.
+
+```typescript
+const result = await inst.extract("Dave is an engineer in Tokyo.");
+console.log(result.objects_extracted);
+```
+
+### `inst.getSchema(options?)` → `InstanceSchemaInfo`
+
+```typescript
+const schema = await inst.getSchema();
+console.log(schema.data_schema);
+```
+
+## Error handling
+
+All errors throw `XmemoryAPIError`. Health check failures throw `XmemoryHealthCheckError` (a subclass).
+
+```typescript
+import { XmemoryClient, XmemoryAPIError, XmemoryHealthCheckError } from "xmemory";
+
+try {
+  const xm = await XmemoryClient.create({ token: "..." });
+} catch (e) {
+  if (e instanceof XmemoryHealthCheckError) {
+    console.error("Server unreachable:", e.message);
+  }
+}
+
+try {
+  await inst.read("query");
+} catch (e) {
+  if (e instanceof XmemoryAPIError) {
+    console.error(`API error (HTTP ${e.status}): ${e.message}`);
+  }
+}
+```
+
+## All timeouts are per-request
+
+Every method accepts an optional `timeoutMs` in its options bag, overriding the client default.
+
+```typescript
+const result = await inst.read("query", { timeoutMs: 120_000 });
+```
+
+---
+
+## Mastra integration
+
+You can also use `xmemory` as an MCP server within [Mastra.ai](https://mastra.ai).
 
 First, create a local Mastra instance:
 

package/dist/client.d.ts

@@ -1,37 +1,44 @@
 /**
- * xmemory HTTP client for Node.js.
+ * XmemoryClient — main entry point for the xmemory API.
  */
-import type { ReadResponse, SchemaTypeValue, WriteResponse } from "./types.js";
-export { SchemaType } from "./types.js";
-export type { SchemaTypeValue, CreateInstanceResponse, WriteResponse, ReadResponse, ReaderResult } from "./types.js";
-export declare class XmemoryAPIError extends Error {
-    readonly status?: number | undefined;
-    constructor(message: string, status?: number | undefined);
-}
-export interface XmemoryInstanceOptions {
-    url?: string;
-    token?: string;
-    timeout?: number;
+import { InstanceHandle } from "./instance.js";
+import { type ClusterInfo, type CreateInstanceOptions, type GenerateSchemaOptions, type GenerateSchemaResult, type InstanceInfo, type InstanceSchemaInfo, type RequestOptions, type SchemaTypeValue, type XmemoryClientOptions } from "./types.js";
+export interface AdminNamespace {
+    listClusters(options?: RequestOptions & {
+        ids?: string[];
+    }): Promise<ClusterInfo[]>;
+    getCluster(clusterId: string, options?: RequestOptions): Promise<ClusterInfo>;
+    createInstance(clusterId: string, name: string, schemaText: string, schemaType: SchemaTypeValue, options?: CreateInstanceOptions): Promise<InstanceHandle>;
+    listInstances(options?: RequestOptions & {
+        ids?: string[];
+    }): Promise<InstanceInfo[]>;
+    getInstance(instanceId: string, options?: RequestOptions): Promise<InstanceInfo>;
+    deleteInstance(instanceId: string, options?: RequestOptions): Promise<string[]>;
+    getInstanceSchema(instanceId: string, options?: RequestOptions): Promise<InstanceSchemaInfo>;
+    updateInstanceSchema(instanceId: string, schemaText: string, schemaType: SchemaTypeValue, options?: RequestOptions): Promise<InstanceInfo>;
+    updateInstanceMetadata(instanceId: string, name: string, description: string, options?: RequestOptions): Promise<InstanceInfo>;
+    generateSchema(clusterId: string, schemaDescription: string, options?: GenerateSchemaOptions): Promise<GenerateSchemaResult>;
 }
 export declare class XmemoryClient {
-    readonly baseUrl: string;
-    readonly timeoutMs: number;
-    readonly token: string | undefined;
-    instanceId: string | null;
-    constructor(options?: XmemoryInstanceOptions);
-    static create(options?: XmemoryInstanceOptions): Promise<XmemoryClient>;
-    private checkHealth;
-    private requireInstanceId;
-    createInstance(schemaText: string, schemaType: SchemaTypeValue, timeout?: number): Promise<boolean>;
-    write(text: string, options?: {
-        timeout?: number;
-    }): Promise<WriteResponse>;
-    read(query: string, options?: {
-        timeout?: number;
-    }): Promise<ReadResponse>;
-    get instance_id(): string | null;
+    private readonly _baseUrl;
+    private readonly _timeoutMs;
+    private readonly _token;
+    readonly admin: AdminNamespace;
+    constructor(options?: XmemoryClientOptions);
+    /** Factory that performs a health check before returning the client. */
+    static create(options?: XmemoryClientOptions): Promise<XmemoryClient>;
+    /** Return an InstanceHandle scoped to the given instance ID. */
+    instance(instanceId: string): InstanceHandle;
+    /** GET /healthz — throws XmemoryHealthCheckError on failure. */
+    checkHealth(): Promise<void>;
+    private _fetch;
+    private _headers;
+    /** Core request — returns the raw API wrapper `{ids, items, errors}`. */
+    private _request;
+    private _requestOne;
+    private _requestList;
+    private _requestIds;
+    private _buildAdmin;
 }
-/**
- * Create an xmemory client.
- */
-export declare function xmemoryInstance(options?: XmemoryInstanceOptions): Promise<XmemoryClient>;
+/** Convenience factory — creates a client with a health check. */
+export declare function xmemoryInstance(options?: XmemoryClientOptions): Promise<XmemoryClient>;

package/dist/client.js

@@ -1,140 +1,208 @@
 /**
- * xmemory HTTP client for Node.js.
+ * XmemoryClient — main entry point for the xmemory API.
  */
-export { SchemaType } from "./types.js";
-const DEFAULT_BASE_URL = "http://0.0.0.0:8000";
+import { InstanceHandle } from "./instance.js";
+import { XmemoryAPIError, XmemoryHealthCheckError, buildInstanceSchema, } from "./types.js";
+const DEFAULT_BASE_URL = "https://api.xmemory.ai";
 const DEFAULT_TIMEOUT_MS = 60_000;
-export class XmemoryAPIError extends Error {
-    status;
-    constructor(message, status) {
-        super(message);
-        this.status = status;
-        this.name = "XmemoryAPIError";
-    }
-}
-async function getEnv(name) {
-    if (typeof process !== "undefined" && process.env) {
-        return process.env[name];
-    }
-    return undefined;
-}
-async function fetchWithTimeout(url, options) {
-    const { timeoutMs = DEFAULT_TIMEOUT_MS, ...fetchOptions } = options;
-    const controller = new AbortController();
-    const id = setTimeout(() => controller.abort(), timeoutMs);
-    try {
-        const res = await fetch(url, {
-            ...fetchOptions,
-            signal: controller.signal,
-        });
-        return res;
-    }
-    finally {
-        clearTimeout(id);
-    }
-}
-async function postJson(baseUrl, path, body, token, timeoutMs) {
-    const url = `${baseUrl.replace(/\/$/, "")}${path}`;
-    const headers = {
-        Accept: "application/json",
-        "Content-Type": "application/json",
-    };
-    if (token) {
-        headers["Authorization"] = `Bearer ${token}`;
-    }
-    const res = await fetchWithTimeout(url, {
-        method: "POST",
-        headers,
-        body: JSON.stringify(body),
-        timeoutMs,
-    });
-    const raw = await res.text();
-    let payload;
-    try {
-        payload = raw ? JSON.parse(raw) : {};
-    }
-    catch {
-        throw new XmemoryAPIError(`Invalid JSON from server (${res.status})`, res.status);
-    }
-    if (typeof payload === "object" && payload !== null && payload.status === "error") {
-        const err = payload;
-        const msg = err.error_message || err.error || String(payload);
-        throw new XmemoryAPIError(`${path} failed: ${msg}`, res.status);
-    }
-    if (!res.ok) {
-        throw new XmemoryAPIError(`HTTP ${res.status}: ${raw.slice(0, 200)}`, res.status);
-    }
-    return payload;
-}
+// ---------------------------------------------------------------------------
+// Client
+// ---------------------------------------------------------------------------
 export class XmemoryClient {
-    baseUrl;
-    timeoutMs;
-    token;
-    instanceId = null;
+    _baseUrl;
+    _timeoutMs;
+    _token;
+    admin;
     constructor(options = {}) {
-        this.baseUrl = options.url ?? "";
-        this.timeoutMs = (options.timeout ?? 60) * 1000;
-        this.token = options.token;
+        const env = typeof process !== "undefined" ? process.env : undefined;
+        this._baseUrl = (options.url ?? env?.XMEM_API_URL ?? DEFAULT_BASE_URL).replace(/\/+$/, "");
+        this._token = options.token ?? env?.XMEM_AUTH_TOKEN;
+        this._timeoutMs = options.timeoutMs ?? DEFAULT_TIMEOUT_MS;
+        this.admin = this._buildAdmin();
     }
+    /** Factory that performs a health check before returning the client. */
     static async create(options = {}) {
-        const url = options.url ?? (await getEnv("XMEM_API_URL")) ?? DEFAULT_BASE_URL;
-        const token = options.token ?? (await getEnv("XMEM_AUTH_TOKEN"));
-        const client = new XmemoryClient({ ...options, url, token });
+        const client = new XmemoryClient(options);
         await client.checkHealth();
         return client;
     }
+    /** Return an InstanceHandle scoped to the given instance ID. */
+    instance(instanceId) {
+        return new InstanceHandle(instanceId, this._requestOne.bind(this));
+    }
+    /** GET /healthz — throws XmemoryHealthCheckError on failure. */
     async checkHealth() {
-        const url = `${this.baseUrl.replace(/\/$/, "")}/api/healthz`;
-        const res = await fetchWithTimeout(url, {
-            method: "GET",
-            headers: { Accept: "application/json" },
-            timeoutMs: this.timeoutMs,
-        });
-        if (!res.ok) {
-            throw new XmemoryAPIError(`Health check failed: ${res.status} at ${url}`, res.status);
+        const url = `${this._baseUrl}/healthz`;
+        try {
+            const res = await this._fetch(url, { method: "GET" }, this._timeoutMs);
+            if (!res.ok) {
+                throw new XmemoryHealthCheckError(`Health check failed: HTTP ${res.status} at ${url}`, res.status);
+            }
         }
-    }
-    requireInstanceId(op) {
-        if (!this.instanceId) {
-            throw new XmemoryAPIError(`instance_id is required for ${op}() but none was provided or saved.`);
+        catch (err) {
+            if (err instanceof XmemoryHealthCheckError)
+                throw err;
+            throw new XmemoryHealthCheckError(`Health check failed: ${err instanceof Error ? err.message : String(err)}`);
         }
-        return this.instanceId;
     }
-    async createInstance(schemaText, schemaType, timeout) {
-        const path = "/instance/create";
-        const body = schemaType === 0 ? { yml_schema: schemaText } : { json_schema: schemaText };
-        const timeoutMs = timeout != null ? timeout * 1000 : this.timeoutMs;
-        const response = await postJson(this.baseUrl, path, body, this.token, timeoutMs);
-        if (response.status === "ok" && response.instance_id) {
-            this.instanceId = response.instance_id;
+    // -----------------------------------------------------------------------
+    // Private: HTTP layer
+    // -----------------------------------------------------------------------
+    async _fetch(url, init, timeoutMs) {
+        const controller = new AbortController();
+        const timer = setTimeout(() => controller.abort(), timeoutMs);
+        try {
+            return await fetch(url, { ...init, signal: controller.signal });
+        }
+        finally {
+            clearTimeout(timer);
         }
-        return response.status === "ok";
-    }
-    async write(text, options) {
-        const iid = this.requireInstanceId("write");
-        const timeoutMs = options?.timeout != null ? options.timeout * 1000 : this.timeoutMs;
-        return postJson(this.baseUrl, "/write", {
-            instance_id: iid,
-            text,
-            extraction_logic: "deep",
-        }, this.token, timeoutMs);
     }
-    async read(query, options) {
-        const iid = this.requireInstanceId("read");
-        const timeoutMs = options?.timeout != null ? options.timeout * 1000 : this.timeoutMs;
-        return postJson(this.baseUrl, "/read", {
-            instance_id: iid,
-            query,
-            mode: "single-answer",
-        }, this.token, timeoutMs);
+    _headers(hasBody = false) {
+        const h = {
+            Accept: "application/json",
+        };
+        if (hasBody)
+            h["Content-Type"] = "application/json";
+        if (this._token)
+            h["Authorization"] = `Bearer ${this._token}`;
+        return h;
+    }
+    /** Core request — returns the raw API wrapper `{ids, items, errors}`. */
+    async _request(method, path, options) {
+        let url = `${this._baseUrl}${path}`;
+        if (options?.params) {
+            const sp = new URLSearchParams();
+            for (const [key, val] of Object.entries(options.params)) {
+                if (Array.isArray(val)) {
+                    for (const v of val)
+                        sp.append(key, v);
+                }
+                else {
+                    sp.append(key, val);
+                }
+            }
+            const qs = sp.toString();
+            if (qs)
+                url += `?${qs}`;
+        }
+        const timeoutMs = options?.timeoutMs ?? this._timeoutMs;
+        const hasBody = !!(options?.body && method !== "GET");
+        const init = { method, headers: this._headers(hasBody) };
+        if (hasBody) {
+            init.body = JSON.stringify(options.body);
+        }
+        const res = await this._fetch(url, init, timeoutMs);
+        const raw = await res.text();
+        let payload;
+        try {
+            payload = raw ? JSON.parse(raw) : {};
+        }
+        catch {
+            throw new XmemoryAPIError(`Invalid JSON from server (${res.status}): ${raw.slice(0, 200)}`, res.status);
+        }
+        if (!res.ok) {
+            const msg = typeof payload === "object" && payload !== null && "message" in payload
+                ? String(payload.message)
+                : raw.slice(0, 200);
+            throw new XmemoryAPIError(`HTTP ${res.status}: ${msg}`, res.status);
+        }
+        const response = payload;
+        if (response.errors?.length) {
+            const first = response.errors[0];
+            throw new XmemoryAPIError(`API error: ${first.message} (${first.code})`, res.status);
+        }
+        return response;
     }
-    get instance_id() {
-        return this.instanceId;
+    async _requestOne(method, path, options) {
+        const response = await this._request(method, path, options);
+        const items = response.items ?? [];
+        if (items.length === 0) {
+            throw new XmemoryAPIError(`Expected one item from ${method} ${path}, got none`);
+        }
+        if (items.length > 1) {
+            throw new XmemoryAPIError(`Expected one item from ${method} ${path}, got ${items.length}`);
+        }
+        return items[0];
+    }
+    async _requestList(method, path, options) {
+        const response = await this._request(method, path, options);
+        return (response.items ?? []);
+    }
+    async _requestIds(method, path, options) {
+        const response = await this._request(method, path, options);
+        return response.ids ?? [];
+    }
+    // -----------------------------------------------------------------------
+    // Private: build admin namespace
+    // -----------------------------------------------------------------------
+    _buildAdmin() {
+        return {
+            listClusters: async (options) => {
+                const params = options?.ids ? { ids: options.ids } : undefined;
+                return this._requestList("GET", "/clusters", { params, timeoutMs: options?.timeoutMs });
+            },
+            getCluster: async (clusterId, options) => {
+                return this._requestOne("GET", `/clusters/${clusterId}`, {
+                    timeoutMs: options?.timeoutMs,
+                });
+            },
+            createInstance: async (clusterId, name, schemaText, schemaType, options) => {
+                const body = {
+                    name,
+                    instance_schema: buildInstanceSchema(schemaText, schemaType),
+                };
+                if (options?.description != null)
+                    body.description = options.description;
+                if (options?.schemaDescription != null)
+                    body.schema_description = options.schemaDescription;
+                const info = await this._requestOne("POST", `/clusters/${clusterId}/instances`, {
+                    body,
+                    timeoutMs: options?.timeoutMs,
+                });
+                return this.instance(info.id);
+            },
+            listInstances: async (options) => {
+                const params = options?.ids ? { ids: options.ids } : undefined;
+                return this._requestList("GET", "/instances", { params, timeoutMs: options?.timeoutMs });
+            },
+            getInstance: async (instanceId, options) => {
+                return this._requestOne("GET", `/instances/${instanceId}`, {
+                    timeoutMs: options?.timeoutMs,
+                });
+            },
+            deleteInstance: async (instanceId, options) => {
+                return this._requestIds("DELETE", `/instances/${instanceId}`, {
+                    timeoutMs: options?.timeoutMs,
+                });
+            },
+            getInstanceSchema: async (instanceId, options) => {
+                return this._requestOne("GET", `/instances/${instanceId}/schema`, {
+                    timeoutMs: options?.timeoutMs,
+                });
+            },
+            updateInstanceSchema: async (instanceId, schemaText, schemaType, options) => {
+                return this._requestOne("PUT", `/instances/${instanceId}/schema`, {
+                    body: { instance_schema: buildInstanceSchema(schemaText, schemaType) },
+                    timeoutMs: options?.timeoutMs,
+                });
+            },
+            updateInstanceMetadata: async (instanceId, name, description, options) => {
+                return this._requestOne("PUT", `/instances/${instanceId}`, {
+                    body: { name, description },
+                    timeoutMs: options?.timeoutMs,
+                });
+            },
+            generateSchema: async (clusterId, schemaDescription, options) => {
+                const body = { schema_description: schemaDescription };
+                if (options?.currentYmlSchema != null)
+                    body.current_yml_schema = options.currentYmlSchema;
+                return this._requestOne("POST", `/clusters/${clusterId}/instances/generate_schema`, { body, timeoutMs: options?.timeoutMs });
+            },
+        };
     }
 }
-/**
- * Create an xmemory client.
- */
+/** Convenience factory — creates a client with a health check. */
 export async function xmemoryInstance(options = {}) {
     return XmemoryClient.create(options);
 }

package/dist/index.d.ts

@@ -0,0 +1,11 @@
+/**
+ * xmemory — TypeScript client for the xmemory API.
+ */
+export { XmemoryClient, xmemoryInstance } from "./client.js";
+export type { AdminNamespace } from "./client.js";
+export { InstanceHandle } from "./instance.js";
+export { XmemoryAPIError, XmemoryHealthCheckError } from "./types.js";
+export { SchemaType } from "./types.js";
+export type { SchemaTypeValue, ExtractionLogic, ReadMode, WriteQueueStatus } from "./types.js";
+export type { XmemoryClientOptions, RequestOptions, ReadOptions, WriteOptions, ExtractOptions, CreateInstanceOptions, GenerateSchemaOptions, } from "./types.js";
+export type { ClusterInfo, InstanceInfo, InstanceSchemaInfo, ReadResult, WriteResult, AsyncWriteResult, WriteStatusResult, ExtractResult, GenerateSchemaResult, } from "./types.js";

package/dist/index.js

@@ -0,0 +1,11 @@
+/**
+ * xmemory — TypeScript client for the xmemory API.
+ */
+// Client
+export { XmemoryClient, xmemoryInstance } from "./client.js";
+// Instance handle
+export { InstanceHandle } from "./instance.js";
+// Error classes
+export { XmemoryAPIError, XmemoryHealthCheckError } from "./types.js";
+// Enums
+export { SchemaType } from "./types.js";

package/dist/instance.d.ts

@@ -0,0 +1,15 @@
+/**
+ * InstanceHandle — scoped data operations on a single xmemory instance.
+ */
+import type { AsyncWriteResult, ExtractOptions, ExtractResult, InstanceSchemaInfo, ReadOptions, ReadResult, RequestOneFn, RequestOptions, WriteOptions, WriteResult, WriteStatusResult } from "./types.js";
+export declare class InstanceHandle {
+    readonly id: string;
+    private readonly _requestOne;
+    constructor(id: string, requestOne: RequestOneFn);
+    read(query: string, options?: ReadOptions): Promise<ReadResult>;
+    write(text: string, options?: WriteOptions): Promise<WriteResult>;
+    writeAsync(text: string, options?: WriteOptions): Promise<AsyncWriteResult>;
+    writeStatus(writeId: string, options?: RequestOptions): Promise<WriteStatusResult>;
+    extract(text: string, options?: ExtractOptions): Promise<ExtractResult>;
+    getSchema(options?: RequestOptions): Promise<InstanceSchemaInfo>;
+}

package/dist/instance.js

@@ -0,0 +1,68 @@
+/**
+ * InstanceHandle — scoped data operations on a single xmemory instance.
+ */
+export class InstanceHandle {
+    id;
+    _requestOne;
+    constructor(id, requestOne) {
+        this.id = id;
+        this._requestOne = requestOne;
+    }
+    async read(query, options) {
+        const body = {
+            query,
+            mode: options?.readMode ?? "single-answer",
+        };
+        if (options?.traceId != null)
+            body.trace_id = options.traceId;
+        return this._requestOne("POST", `/instances/${this.id}/read`, {
+            body,
+            timeoutMs: options?.timeoutMs,
+        });
+    }
+    async write(text, options) {
+        const body = {
+            text,
+            extraction_logic: options?.extractionLogic ?? "deep",
+        };
+        if (options?.diffEngine != null)
+            body.diff_engine = options.diffEngine;
+        return this._requestOne("POST", `/instances/${this.id}/write`, {
+            body,
+            timeoutMs: options?.timeoutMs,
+        });
+    }
+    async writeAsync(text, options) {
+        const body = {
+            text,
+            extraction_logic: options?.extractionLogic ?? "deep",
+        };
+        if (options?.diffEngine != null)
+            body.diff_engine = options.diffEngine;
+        return this._requestOne("POST", `/instances/${this.id}/write_async`, {
+            body,
+            timeoutMs: options?.timeoutMs,
+        });
+    }
+    async writeStatus(writeId, options) {
+        return this._requestOne("POST", `/instances/${this.id}/write_status`, {
+            body: { write_id: writeId },
+            timeoutMs: options?.timeoutMs,
+        });
+    }
+    async extract(text, options) {
+        const body = {
+            text,
+            extraction_logic: options?.extractionLogic ?? "deep",
+        };
+        return this._requestOne("POST", `/instances/${this.id}/extract`, {
+            body,
+            timeoutMs: options?.timeoutMs,
+        });
+    }
+    async getSchema(options) {
+        return this._requestOne("GET", `/instances/${this.id}/schema`, {
+            timeoutMs: options?.timeoutMs,
+        });
+    }
+}

package/dist/types.d.ts

@@ -1,39 +1,111 @@
 /**
- * Types for the xmemory API.
+ * Types, enums, and error classes for the xmemory API.
  */
 export declare const SchemaType: {
     readonly YML: 0;
     readonly JSON: 1;
 };
 export type SchemaTypeValue = (typeof SchemaType)[keyof typeof SchemaType];
-export interface CreateInstanceYMLRequest {
-    yml_schema: string;
+export type ExtractionLogic = "fast" | "regular" | "deep";
+export type ReadMode = "single-answer" | "raw-tables" | "xresponse";
+export type WriteQueueStatus = "queued" | "processing" | "completed" | "failed" | "not_found";
+export declare class XmemoryAPIError extends Error {
+    readonly status?: number | undefined;
+    constructor(message: string, status?: number | undefined);
 }
-export interface CreateInstanceResponse {
-    status: "ok" | "error";
-    instance_id?: string | null;
-    error_message?: string | null;
+export declare class XmemoryHealthCheckError extends XmemoryAPIError {
+    constructor(message: string, status?: number);
 }
-export interface WriteRequest {
-    instance_id: string;
-    text: string;
-    extraction_logic?: "fast" | "regular" | "deep";
+export interface ClusterInfo {
+    readonly id: string;
+    readonly org_id: string;
+    readonly name: string;
+    readonly description: string | null;
 }
-export interface WriteResponse {
-    status: "ok" | "error";
-    error_message?: string | null;
+export interface InstanceInfo {
+    readonly id: string;
+    readonly cluster_id: string;
+    readonly name: string;
+    readonly description: string | null;
+    readonly data_schema: Record<string, unknown> | null;
 }
-export interface ReadRequest {
-    instance_id: string;
-    query: string;
-    mode?: "single-answer" | "raw-tables" | "xresponse";
+export interface InstanceSchemaInfo {
+    readonly data_schema: Record<string, unknown>;
 }
-export interface ReaderResult {
-    answer?: string;
-    [key: string]: unknown;
+export interface ReadResult {
+    readonly trace_id: string | null;
+    readonly reader_result: unknown;
 }
-export interface ReadResponse {
-    status: "ok" | "error";
-    reader_result?: ReaderResult | null;
-    error_message?: string | null;
+export interface WriteResult {
+    readonly write_id: string;
+    readonly trace_id: string | null;
+    readonly cleaned_objects: unknown;
+    readonly diff_plan: unknown;
 }
+export interface AsyncWriteResult {
+    readonly write_id: string;
+}
+export interface WriteStatusResult {
+    readonly write_id: string;
+    readonly write_status: WriteQueueStatus;
+    readonly error_detail: string | null;
+    readonly completed_at: string | null;
+}
+export interface ExtractResult {
+    readonly trace_id: string | null;
+    readonly objects_extracted: unknown;
+}
+export interface GenerateSchemaResult {
+    readonly data_schema: Record<string, unknown>;
+}
+export interface XmemoryClientOptions {
+    url?: string;
+    token?: string;
+    timeoutMs?: number;
+}
+export interface RequestOptions {
+    timeoutMs?: number;
+}
+export interface ReadOptions {
+    readMode?: ReadMode;
+    traceId?: string;
+    timeoutMs?: number;
+}
+export interface WriteOptions {
+    extractionLogic?: ExtractionLogic;
+    diffEngine?: boolean;
+    timeoutMs?: number;
+}
+export interface ExtractOptions {
+    extractionLogic?: ExtractionLogic;
+    timeoutMs?: number;
+}
+export interface CreateInstanceOptions {
+    description?: string;
+    schemaDescription?: string;
+    timeoutMs?: number;
+}
+export interface GenerateSchemaOptions {
+    currentYmlSchema?: string;
+    timeoutMs?: number;
+}
+export interface ApiError {
+    readonly code: string;
+    readonly message: string;
+    readonly field?: string;
+    readonly resource_id?: string;
+}
+export interface RawApiResponse {
+    readonly ids?: string[];
+    readonly items?: unknown[];
+    readonly errors?: ApiError[];
+}
+export interface InternalRequestOptions {
+    body?: Record<string, unknown>;
+    params?: Record<string, string | string[]>;
+    timeoutMs?: number;
+}
+export type RequestOneFn = <T>(method: string, path: string, options?: InternalRequestOptions) => Promise<T>;
+export type RequestListFn = <T>(method: string, path: string, options?: InternalRequestOptions) => Promise<T[]>;
+export type RequestIdsFn = (method: string, path: string, options?: InternalRequestOptions) => Promise<string[]>;
+export declare function buildInstanceSchema(schemaText: string, schemaType: SchemaTypeValue): Record<string, unknown>;

package/dist/types.js

@@ -1,7 +1,30 @@
 /**
- * Types for the xmemory API.
+ * Types, enums, and error classes for the xmemory API.
  */
-export const SchemaType = {
-    YML: 0,
-    JSON: 1,
-};
+// ---------------------------------------------------------------------------
+// Enums
+// ---------------------------------------------------------------------------
+export const SchemaType = { YML: 0, JSON: 1 };
+// ---------------------------------------------------------------------------
+// Error classes
+// ---------------------------------------------------------------------------
+export class XmemoryAPIError extends Error {
+    status;
+    constructor(message, status) {
+        super(message);
+        this.status = status;
+        this.name = "XmemoryAPIError";
+    }
+}
+export class XmemoryHealthCheckError extends XmemoryAPIError {
+    constructor(message, status) {
+        super(message, status);
+        this.name = "XmemoryHealthCheckError";
+    }
+}
+export function buildInstanceSchema(schemaText, schemaType) {
+    if (schemaType === SchemaType.YML) {
+        return { yml: { value: schemaText } };
+    }
+    return { json_schema: { value: schemaText } };
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "xmemory",
-  "version": "1.0.1",
+  "version": "2.0.0",
   "description": "xmemory",
   "keywords": [
     "xmemory"
@@ -16,14 +16,15 @@
   "license": "MIT",
   "author": "Dima Korolev",
   "type": "module",
-  "main": "dist/client.js",
-  "types": "dist/client.d.ts",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
   "files": [
     "dist"
   ],
   "scripts": {
     "build": "tsc",
     "test": "tsc --noEmit && node --import tsx test.ts",
+    "test:types": "tsc --noEmit",
     "prepublishOnly": "npm run build"
   },
   "devDependencies": {