xmem-ai 1.1.0 → 2.0.1

package/README.md

@@ -0,0 +1,95 @@
+# xmem-ai
+
+TypeScript SDK for the [XMem](https://github.com/xmem-ai/xmem) long-term memory API.
+
+## Install
+
+```bash
+npm install xmem-ai
+```
+
+## Usage
+
+All constructor arguments are required: API base URL, API key, and username (sent on every request via the `X-XMem-Username` header).
+
+```typescript
+import { XMemClient } from "xmem-ai";
+
+const client = new XMemClient(
+  "http://localhost:8000",
+  process.env.XMEM_API_KEY!,
+  "alice",
+);
+
+const ready = await client.isReady();
+
+await client.ingest({
+  user_query: "Hello",
+  user_id: "user_42",
+});
+
+const answer = await client.retrieve({
+  query: "What did we talk about?",
+  user_id: "user_42",
+});
+```
+
+### Error handling
+
+```typescript
+import {
+  XMemClient,
+  AuthenticationError,
+  RateLimitError,
+} from "xmem-ai";
+
+try {
+  await client.ingest({ user_query: "test", user_id: "u1" });
+} catch (e) {
+  if (e instanceof AuthenticationError) {
+    console.error(`Auth failed: ${e.message}`);
+  } else if (e instanceof RateLimitError) {
+    console.error(`Rate limited, retry after ${e.retryAfter}s`);
+  }
+}
+```
+
+## Migrating from 1.x
+
+Version **2.0.0** is a breaking release.
+
+### Constructor
+
+**Before (1.x):**
+
+```typescript
+new XMemClient(); // defaults: localhost, no API key
+new XMemClient(apiUrl);
+new XMemClient(apiUrl, apiKey);
+```
+
+Optional arguments fell back to `process.env.XMEM_API_URL`, `process.env.XMEM_API_KEY`, and defaults.
+
+**After (2.x):**
+
+```typescript
+new XMemClient(apiUrl, apiKey, username);
+```
+
+- `apiUrl`, `apiKey`, and `username` are **required** strings.
+- Passing `undefined`, `null`, or whitespace-only values throws **`Error`** immediately (before any network call).
+- Username is included on **every** request as the **`X-XMem-Username`** HTTP header.
+
+Replace previous env-only setups by reading variables yourself and passing them explicitly:
+
+```typescript
+const apiUrl = process.env.XMEM_API_URL ?? "http://localhost:8000";
+const apiKey = process.env.XMEM_API_KEY!;
+const username = process.env.XMEM_USERNAME!;
+
+const client = new XMemClient(apiUrl, apiKey, username);
+```
+
+---
+
+Apache-2.0 License

package/dist/index.d.ts

@@ -1,3 +1,3 @@
-export { XMemClient } from "./src/client";
+export { XMemClient, XMEM_USERNAME_HEADER } from "./src/client";
 export type { APIEnvelope, CodeQueryParams, CodeQueryResult, DirectoryNode, DirectoryTreeResult, DomainResult, HealthStatus, IngestParams, IngestResult, OperationDetail, RepoListResult, RetrieveParams, RetrieveResult, SearchParams, SearchResult, SourceRecord, WeaverSummary, } from "./src/types";
 export { XMemSDKError, AuthenticationError, ConnectionError, NotReadyError, RateLimitError, ServerError, ValidationError, } from "./src/error";

package/dist/index.js

@@ -1,8 +1,9 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.ValidationError = exports.ServerError = exports.RateLimitError = exports.NotReadyError = exports.ConnectionError = exports.AuthenticationError = exports.XMemSDKError = exports.XMemClient = void 0;
+exports.ValidationError = exports.ServerError = exports.RateLimitError = exports.NotReadyError = exports.ConnectionError = exports.AuthenticationError = exports.XMemSDKError = exports.XMEM_USERNAME_HEADER = exports.XMemClient = void 0;
 var client_1 = require("./src/client");
 Object.defineProperty(exports, "XMemClient", { enumerable: true, get: function () { return client_1.XMemClient; } });
+Object.defineProperty(exports, "XMEM_USERNAME_HEADER", { enumerable: true, get: function () { return client_1.XMEM_USERNAME_HEADER; } });
 var error_1 = require("./src/error");
 Object.defineProperty(exports, "XMemSDKError", { enumerable: true, get: function () { return error_1.XMemSDKError; } });
 Object.defineProperty(exports, "AuthenticationError", { enumerable: true, get: function () { return error_1.AuthenticationError; } });

package/dist/src/client.d.ts

@@ -2,19 +2,21 @@
  * XMem TypeScript client.
  *
  * ```ts
- * import { XMemClient } from "@xmem/sdk";
+ * import { XMemClient } from "xmem-ai";
  *
- * const client = new XMemClient("http://localhost:8000", "sk-...");
+ * const client = new XMemClient("http://localhost:8000", "sk-...", "alice");
  * const result = await client.ingest({ user_query: "I love hiking", user_id: "u1" });
  * const answer = await client.retrieve({ query: "hobbies", user_id: "u1" });
  * console.log(answer.answer);
  * ```
  */
 import type { CodeQueryParams, CodeQueryResult, DirectoryTreeResult, HealthStatus, IngestParams, IngestResult, RepoListResult, RetrieveParams, RetrieveResult, SearchParams, SearchResult } from "./types";
+/** HTTP header name used to send the SDK username on every request. */
+export declare const XMEM_USERNAME_HEADER = "X-XMem-Username";
 export declare class XMemClient {
     private readonly baseUrl;
     private readonly headers;
-    constructor(apiUrl?: string, apiKey?: string);
+    constructor(apiUrl: string, apiKey: string, username: string);
     private req;
     ping(): Promise<HealthStatus>;
     isReady(): Promise<boolean>;

package/dist/src/client.js

@@ -3,24 +3,39 @@
  * XMem TypeScript client.
  *
  * ```ts
- * import { XMemClient } from "@xmem/sdk";
+ * import { XMemClient } from "xmem-ai";
  *
- * const client = new XMemClient("http://localhost:8000", "sk-...");
+ * const client = new XMemClient("http://localhost:8000", "sk-...", "alice");
  * const result = await client.ingest({ user_query: "I love hiking", user_id: "u1" });
  * const answer = await client.retrieve({ query: "hobbies", user_id: "u1" });
  * console.log(answer.answer);
  * ```
  */
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.XMemClient = void 0;
+exports.XMemClient = exports.XMEM_USERNAME_HEADER = void 0;
 const network_1 = require("./network");
+/** HTTP header name used to send the SDK username on every request. */
+exports.XMEM_USERNAME_HEADER = "X-XMem-Username";
+function requireNonEmptyString(paramName, value) {
+    if (value === undefined || value === null) {
+        throw new Error(`XMemClient: ${paramName} is required`);
+    }
+    const s = String(value).trim();
+    if (!s) {
+        throw new Error(`XMemClient: ${paramName} cannot be empty`);
+    }
+    return s;
+}
 class XMemClient {
-    constructor(apiUrl, apiKey) {
-        this.baseUrl = (apiUrl || process.env.XMEM_API_URL || "http://localhost:8000").replace(/\/$/, "");
-        const key = apiKey || process.env.XMEM_API_KEY || "";
+    constructor(apiUrl, apiKey, username) {
+        const url = requireNonEmptyString("apiUrl", apiUrl);
+        const key = requireNonEmptyString("apiKey", apiKey);
+        const user = requireNonEmptyString("username", username);
+        this.baseUrl = url.replace(/\/$/, "");
         this.headers = {
             "Content-Type": "application/json",
-            ...(key ? { Authorization: `Bearer ${key}` } : {}),
+            Authorization: `Bearer ${key}`,
+            [exports.XMEM_USERNAME_HEADER]: user,
         };
     }
     async req(method, path, body) {

package/dist/src/index.d.ts

@@ -1,3 +1,3 @@
-export { XMemClient } from './client';
+export { XMemClient, XMEM_USERNAME_HEADER } from './client';
 export * from './types';
 export { XMemSDKError } from './error';

package/dist/src/index.js

@@ -14,9 +14,10 @@ var __exportStar = (this && this.__exportStar) || function(m, exports) {
     for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
 };
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.XMemSDKError = exports.XMemClient = void 0;
+exports.XMemSDKError = exports.XMEM_USERNAME_HEADER = exports.XMemClient = void 0;
 var client_1 = require("./client");
 Object.defineProperty(exports, "XMemClient", { enumerable: true, get: function () { return client_1.XMemClient; } });
+Object.defineProperty(exports, "XMEM_USERNAME_HEADER", { enumerable: true, get: function () { return client_1.XMEM_USERNAME_HEADER; } });
 __exportStar(require("./types"), exports);
 var error_1 = require("./error");
 Object.defineProperty(exports, "XMemSDKError", { enumerable: true, get: function () { return error_1.XMemSDKError; } });

package/dist/src/types.d.ts

@@ -21,6 +21,7 @@ export interface IngestParams {
     agent_response?: string;
     session_datetime?: string;
     image_url?: string;
+    effort_level?: "low" | "high";
 }
 export interface OperationDetail {
     type: string;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "xmem-ai",
-  "version": "1.1.0",
+  "version": "2.0.1",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
   "files": [