xmemory 2.1.0 → 2.1.1

package/README.md

@@ -15,7 +15,7 @@ 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
+  apiKey: "<your-api-key>",       // or set XMEM_API_KEY env var
 });
 
 // Write and read from an existing instance
@@ -28,11 +28,13 @@ 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 |
+| Parameter   | Env var          | Default                   | Description                             |
+|-------------|------------------|---------------------------|-----------------------------------------|
+| `url`       | `XMEM_API_URL`   | `https://api.xmemory.ai`  | Base URL of the Xmemory API             |
+| `apiKey`    | `XMEM_API_KEY`   | `undefined`               | Bearer API key for authentication       |
+| `timeoutMs` | —                | `60000`                   | Default request timeout in milliseconds |
+
+The legacy `token` option and `XMEM_AUTH_TOKEN` env var are still accepted for backwards compatibility but are deprecated and will be removed in a future release. Using them prints a deprecation warning. If both the new and legacy values are set, the new ones win.
 
 ## Creating a client
 
@@ -40,13 +42,13 @@ console.log(result.reader_result);
 import { XmemoryClient, xmemoryInstance } from "xmemory";
 
 // Option 1: constructor (no health check)
-const xm1 = new XmemoryClient({ token: "..." });
+const xm1 = new XmemoryClient({ apiKey: "..." });
 
 // Option 2: factory with health check
-const xm2 = await XmemoryClient.create({ token: "..." });
+const xm2 = await XmemoryClient.create({ apiKey: "..." });
 
 // Option 3: convenience function (same as Option 2)
-const xm3 = await xmemoryInstance({ token: "..." });
+const xm3 = await xmemoryInstance({ apiKey: "..." });
 ```
 
 ## Admin operations
@@ -189,7 +191,7 @@ All errors throw `XmemoryAPIError`. Health check failures throw `XmemoryHealthCh
 import { XmemoryClient, XmemoryAPIError, XmemoryHealthCheckError } from "xmemory";
 
 try {
-  const xm = await XmemoryClient.create({ token: "..." });
+  const xm = await XmemoryClient.create({ apiKey: "..." });
 } catch (e) {
   if (e instanceof XmemoryHealthCheckError) {
     console.error("Server unreachable:", e.message);

package/dist/client.d.ts

@@ -22,9 +22,10 @@ export interface AdminNamespace {
 export declare class XmemoryClient {
     private readonly _baseUrl;
     private readonly _timeoutMs;
-    private readonly _token;
+    private readonly _apiKey;
     readonly admin: AdminNamespace;
     constructor(options?: XmemoryClientOptions);
+    private static _resolveApiKey;
     /** 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. */

package/dist/client.js

@@ -5,21 +5,41 @@ 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;
+const ORANGE = "\x1b[38;5;208m";
+const RESET = "\x1b[0m";
+function deprecationWarning(message) {
+    console.warn(`${ORANGE}[xmemory] DEPRECATION: ${message}${RESET}`);
+}
 // ---------------------------------------------------------------------------
 // Client
 // ---------------------------------------------------------------------------
 export class XmemoryClient {
     _baseUrl;
     _timeoutMs;
-    _token;
+    _apiKey;
     admin;
     constructor(options = {}) {
         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._apiKey = XmemoryClient._resolveApiKey(options, env);
         this._timeoutMs = options.timeoutMs ?? DEFAULT_TIMEOUT_MS;
         this.admin = this._buildAdmin();
     }
+    static _resolveApiKey(options, env) {
+        if (options.apiKey != null)
+            return options.apiKey;
+        if (options.token != null) {
+            deprecationWarning("The `token` constructor option is deprecated and will be removed soon. Use `apiKey` instead.");
+            return options.token;
+        }
+        if (env?.XMEM_API_KEY)
+            return env.XMEM_API_KEY;
+        if (env?.XMEM_AUTH_TOKEN) {
+            deprecationWarning("The `XMEM_AUTH_TOKEN` environment variable is deprecated and will be removed soon. Use `XMEM_API_KEY` instead.");
+            return env.XMEM_AUTH_TOKEN;
+        }
+        return undefined;
+    }
     /** Factory that performs a health check before returning the client. */
     static async create(options = {}) {
         const client = new XmemoryClient(options);
@@ -64,8 +84,8 @@ export class XmemoryClient {
         };
         if (hasBody)
             h["Content-Type"] = "application/json";
-        if (this._token)
-            h["Authorization"] = `Bearer ${this._token}`;
+        if (this._apiKey)
+            h["Authorization"] = `Bearer ${this._apiKey}`;
         return h;
     }
     /** Core request — returns the raw API wrapper `{ids, items, errors}`. */

package/dist/types.d.ts

@@ -82,6 +82,8 @@ export interface RawDescribeResult {
 }
 export interface XmemoryClientOptions {
     url?: string;
+    apiKey?: string;
+    /** @deprecated Use `apiKey` instead. Will be removed in a future release. */
     token?: string;
     timeoutMs?: number;
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "xmemory",
-  "version": "2.1.0",
+  "version": "2.1.1",
   "description": "xmemory",
   "keywords": [
     "xmemory"