xmemory 1.0.0 → 1.0.1

package/dist/client.d.ts

@@ -0,0 +1,37 @@
+/**
+ * xmemory HTTP client for Node.js.
+ */
+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;
+}
+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;
+}
+/**
+ * Create an xmemory client.
+ */
+export declare function xmemoryInstance(options?: XmemoryInstanceOptions): Promise<XmemoryClient>;

package/dist/client.js

@@ -0,0 +1,140 @@
+/**
+ * xmemory HTTP client for Node.js.
+ */
+export { SchemaType } from "./types.js";
+const DEFAULT_BASE_URL = "http://0.0.0.0:8000";
+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;
+}
+export class XmemoryClient {
+    baseUrl;
+    timeoutMs;
+    token;
+    instanceId = null;
+    constructor(options = {}) {
+        this.baseUrl = options.url ?? "";
+        this.timeoutMs = (options.timeout ?? 60) * 1000;
+        this.token = options.token;
+    }
+    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 });
+        await client.checkHealth();
+        return client;
+    }
+    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);
+        }
+    }
+    requireInstanceId(op) {
+        if (!this.instanceId) {
+            throw new XmemoryAPIError(`instance_id is required for ${op}() but none was provided or saved.`);
+        }
+        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;
+        }
+        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);
+    }
+    get instance_id() {
+        return this.instanceId;
+    }
+}
+/**
+ * Create an xmemory client.
+ */
+export async function xmemoryInstance(options = {}) {
+    return XmemoryClient.create(options);
+}

package/dist/types.d.ts

@@ -0,0 +1,39 @@
+/**
+ * Types 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 interface CreateInstanceResponse {
+    status: "ok" | "error";
+    instance_id?: string | null;
+    error_message?: string | null;
+}
+export interface WriteRequest {
+    instance_id: string;
+    text: string;
+    extraction_logic?: "fast" | "regular" | "deep";
+}
+export interface WriteResponse {
+    status: "ok" | "error";
+    error_message?: string | null;
+}
+export interface ReadRequest {
+    instance_id: string;
+    query: string;
+    mode?: "single-answer" | "raw-tables" | "xresponse";
+}
+export interface ReaderResult {
+    answer?: string;
+    [key: string]: unknown;
+}
+export interface ReadResponse {
+    status: "ok" | "error";
+    reader_result?: ReaderResult | null;
+    error_message?: string | null;
+}

package/dist/types.js

@@ -0,0 +1,7 @@
+/**
+ * Types for the xmemory API.
+ */
+export const SchemaType = {
+    YML: 0,
+    JSON: 1,
+};

package/package.json

@@ -1,8 +1,10 @@
 {
   "name": "xmemory",
-  "version": "1.0.0",
+  "version": "1.0.1",
   "description": "xmemory",
-  "keywords": [ "xmemory" ],
+  "keywords": [
+    "xmemory"
+  ],
   "homepage": "https://github.com/xmemory-ai/xmemory-npm",
   "bugs": {
     "url": "https://github.com/xmemory-ai/xmemory-npm/issues"
@@ -13,12 +15,20 @@
   },
   "license": "MIT",
   "author": "Dima Korolev",
-  "type": "commonjs",
-  "main": "index.js",
-  "bin": {
-    "xmemory": "cli.js"
-  },
+  "type": "module",
+  "main": "dist/client.js",
+  "types": "dist/client.d.ts",
+  "files": [
+    "dist"
+  ],
   "scripts": {
-    "test": "echo \"Error: no test specified\" && exit 1"
+    "build": "tsc",
+    "test": "tsc --noEmit && node --import tsx test.ts",
+    "prepublishOnly": "npm run build"
+  },
+  "devDependencies": {
+    "@types/node": "^25.4.0",
+    "tsx": "^4.21.0",
+    "typescript": "^5.6.0"
   }
 }

package/cli.js

@@ -1,6 +0,0 @@
-#!/usr/bin/env node
-
-const greet = require("./index");
-
-const name = process.argv[2];
-console.log(greet(name));

package/index.js

@@ -1,11 +0,0 @@
-// NOTE(dkorolev): There will be more to this module.
-// For now it's just the prompt to connect `xmemory` to Mastra.
-
-function greet(name) {
-  if (name) {
-    return `Hello, ${name}!`;
-  }
-  return "Hello, xmemory!";
-}
-
-module.exports = greet;