@quorex/sdk 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Quorex
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,100 @@
+# @quorex/sdk
+
+Official JavaScript / TypeScript SDK for **Quorex** — the memory layer for AI agents.
+Store, retrieve and inject persistent user context into any LLM in one call.
+
+Works in Node 18+, edge/serverless runtimes and the browser. Zero dependencies.
+
+## Install
+
+```bash
+npm install @quorex/sdk
+```
+
+## Quickstart
+
+```ts
+import { Quorex } from "@quorex/sdk";
+
+const qx = new Quorex({ apiKey: "qx_live_..." }); // or set QUOREX_API_KEY
+
+// Store a memory for one of your end-users
+await qx.remember("user_123", "I switched to Vue.js, React feels too verbose");
+
+// Recall the relevant context before calling your LLM
+const memories = await qx.recall("user_123", "what framework does this user prefer?");
+for (const m of memories) {
+  console.log(m.text, m.finalScore);
+}
+```
+
+Get your secret key from the [dashboard](https://quorex.fr) → API Keys.
+
+## Client
+
+```ts
+new Quorex({
+  apiKey?: string,   // or QUOREX_API_KEY env var
+  baseUrl?: string,  // default "https://api.quorex.fr"
+  timeout?: number,  // ms, default 30000
+});
+```
+
+## API
+
+| Method | Description |
+| --- | --- |
+| `remember(userId, text, { action?, metadata?, timestamp? })` | Store a memory → `{ vecId }` |
+| `recall(userId, query, { topK?, threshold? })` | Ranked memories → `Memory[]` |
+| `explain(userId, query, { topK? })` | Memories + score breakdown → `ExplainResult[]` |
+| `forget(userId, vecId)` | Delete one memory → `{ deleted, vecId }` |
+| `purge(userId)` | GDPR — delete all of a user's memories → `number` |
+| `export(userId)` | GDPR — export all data → `ExportResult` |
+| `freeze(userId)` | Stop temporal decay → `boolean` |
+| `stats(userId?)` | Usage stats for the key → `Stats` |
+
+### Examples
+
+```ts
+const r = await qx.remember("user_123", "prefers dark mode", { action: "preference" });
+r.vecId; // 42
+
+const explained = await qx.explain("user_123", "ui preference?");
+explained[0].explanation;
+explained[0].scoreBreakdown;
+
+await qx.forget("user_123", 42);
+const removed = await qx.purge("user_123");
+const data = await qx.export("user_123");
+await qx.freeze("user_123");
+const usage = await qx.stats();
+```
+
+## Errors
+
+All errors extend `QuorexError` (with a `statusCode`). Catch the specific type:
+
+```ts
+import { Quorex, AuthenticationError, QuorexError } from "@quorex/sdk";
+
+try {
+  await qx.recall("user_123", "...");
+} catch (e) {
+  if (e instanceof AuthenticationError) console.error("Check your API key");
+  else if (e instanceof QuorexError) console.error("Quorex error:", e.message);
+}
+```
+
+`AuthenticationError` (401) · `NotFoundError` (404) · `RateLimitError` (429) · `ServerError` (5xx).
+
+## Develop
+
+```bash
+npm install
+npm run build      # ESM + CJS + .d.ts in dist/
+npm run typecheck
+```
+
+## License
+
+MIT

package/dist/index.cjs

@@ -0,0 +1,235 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/index.ts
+var index_exports = {};
+__export(index_exports, {
+  AuthenticationError: () => AuthenticationError,
+  NotFoundError: () => NotFoundError,
+  Quorex: () => Quorex,
+  QuorexError: () => QuorexError,
+  RateLimitError: () => RateLimitError,
+  ServerError: () => ServerError
+});
+module.exports = __toCommonJS(index_exports);
+
+// src/errors.ts
+var QuorexError = class extends Error {
+  constructor(message, statusCode) {
+    super(message);
+    this.name = "QuorexError";
+    this.statusCode = statusCode;
+    Object.setPrototypeOf(this, new.target.prototype);
+  }
+};
+var AuthenticationError = class extends QuorexError {
+  constructor(message = "Invalid or missing API key.", statusCode = 401) {
+    super(message, statusCode);
+    this.name = "AuthenticationError";
+  }
+};
+var NotFoundError = class extends QuorexError {
+  constructor(message = "Resource not found.", statusCode = 404) {
+    super(message, statusCode);
+    this.name = "NotFoundError";
+  }
+};
+var RateLimitError = class extends QuorexError {
+  constructor(message = "Rate limit exceeded.", statusCode = 429) {
+    super(message, statusCode);
+    this.name = "RateLimitError";
+  }
+};
+var ServerError = class extends QuorexError {
+  constructor(message = "Quorex server error.", statusCode = 500) {
+    super(message, statusCode);
+    this.name = "ServerError";
+  }
+};
+
+// src/client.ts
+var DEFAULT_BASE_URL = "https://api.quorex.fr";
+var DEFAULT_TIMEOUT = 3e4;
+var VERSION = "0.1.0";
+function envApiKey() {
+  try {
+    return typeof process !== "undefined" ? process.env?.QUOREX_API_KEY : void 0;
+  } catch {
+    return void 0;
+  }
+}
+function toMemory(m) {
+  return {
+    vecId: m?.vec_id ?? null,
+    text: m?.text ?? "",
+    action: m?.action ?? "",
+    timestamp: m?.timestamp ?? null,
+    finalScore: m?.final_score ?? null,
+    cosineSim: m?.cosine_sim ?? null,
+    decayWeight: m?.decay_weight ?? null,
+    freqWeight: m?.freq_weight ?? null,
+    hoursAgo: m?.hours_ago ?? null,
+    reinforcements: m?.reinforcements ?? null,
+    meta: m?.meta ?? {}
+  };
+}
+var Quorex = class {
+  constructor(options = {}) {
+    const key = options.apiKey ?? envApiKey();
+    if (!key) {
+      throw new AuthenticationError(
+        "API key is required. Pass { apiKey } or set the QUOREX_API_KEY environment variable."
+      );
+    }
+    this.apiKey = key;
+    this.baseUrl = (options.baseUrl ?? DEFAULT_BASE_URL).replace(/\/+$/, "");
+    this.timeout = options.timeout ?? DEFAULT_TIMEOUT;
+  }
+  async request(method, path, init = {}) {
+    const url = new URL(this.baseUrl + path);
+    if (init.query) {
+      for (const [k, v] of Object.entries(init.query)) {
+        if (v !== void 0 && v !== null) url.searchParams.set(k, String(v));
+      }
+    }
+    const controller = new AbortController();
+    const timer = setTimeout(() => controller.abort(), this.timeout);
+    let res;
+    try {
+      res = await fetch(url.toString(), {
+        method,
+        headers: {
+          "Content-Type": "application/json",
+          Authorization: `Bearer ${this.apiKey}`,
+          "X-Quorex-Client": `quorex-js/${VERSION}`
+        },
+        body: init.body !== void 0 ? JSON.stringify(init.body) : void 0,
+        signal: controller.signal
+      });
+    } catch (err) {
+      clearTimeout(timer);
+      if (err?.name === "AbortError") throw new QuorexError("Request timed out.");
+      throw new QuorexError(`Network error: ${err?.message ?? String(err)}`);
+    }
+    clearTimeout(timer);
+    return this.handle(res);
+  }
+  async handle(res) {
+    let data = null;
+    const text = await res.text();
+    if (text) {
+      try {
+        data = JSON.parse(text);
+      } catch {
+        data = text;
+      }
+    }
+    if (res.ok) return data;
+    const detail = data && (data.detail || data.error) || res.statusText || "Unknown error";
+    if (res.status === 401) throw new AuthenticationError(detail, 401);
+    if (res.status === 404) throw new NotFoundError(detail, 404);
+    if (res.status === 429) throw new RateLimitError(detail, 429);
+    if (res.status >= 500) throw new ServerError(detail, res.status);
+    throw new QuorexError(`API error (${res.status}): ${detail}`, res.status);
+  }
+  /** Store a memory for one of your end-users. */
+  async remember(userId, text, opts = {}) {
+    const data = await this.request("POST", "/sdk/v1/remember", {
+      body: {
+        user_id: userId,
+        text,
+        action: opts.action ?? "memory",
+        metadata: opts.metadata ?? {},
+        timestamp: opts.timestamp ?? Date.now() / 1e3
+      }
+    });
+    return { vecId: data.vec_id };
+  }
+  /** Retrieve the most relevant memories for a query, ranked by final score. */
+  async recall(userId, query, opts = {}) {
+    const data = await this.request("POST", "/sdk/v1/recall", {
+      body: { user_id: userId, query, top_k: opts.topK ?? 5, threshold: opts.threshold ?? 0.05 }
+    });
+    return (data.memories ?? []).map(toMemory);
+  }
+  /** Like recall(), but each result includes a human-readable score breakdown. */
+  async explain(userId, query, opts = {}) {
+    const data = await this.request("POST", "/sdk/v1/explain", {
+      body: { user_id: userId, query, top_k: opts.topK ?? 1 }
+    });
+    return (data.results ?? []).map((r) => ({
+      memory: toMemory(r),
+      explanation: r?.explanation ?? "",
+      scoreBreakdown: {
+        finalScore: r?.score_breakdown?.final_score,
+        cosineSim: r?.score_breakdown?.cosine_sim,
+        decayWeight: r?.score_breakdown?.decay_weight,
+        freqWeight: r?.score_breakdown?.freq_weight,
+        reinforcements: r?.score_breakdown?.reinforcements,
+        hoursAgo: r?.score_breakdown?.hours_ago
+      }
+    }));
+  }
+  /** Delete a single memory by its vector id. */
+  async forget(userId, vecId) {
+    const data = await this.request("DELETE", "/sdk/v1/forget", {
+      body: { user_id: userId, vec_id: vecId }
+    });
+    return { deleted: data.deleted ?? false, vecId };
+  }
+  /** GDPR — delete ALL memories for an end-user. Returns the count removed. */
+  async purge(userId) {
+    const data = await this.request("DELETE", "/sdk/v1/purge", {
+      body: { user_id: userId }
+    });
+    return data.deleted ?? 0;
+  }
+  /** GDPR — export all memories for an end-user. */
+  async export(userId) {
+    const data = await this.request("GET", "/sdk/v1/export", { query: { user_id: userId } });
+    return {
+      userId: data?.user_id ?? userId,
+      count: data?.count ?? (data?.memories?.length ?? 0),
+      memories: (data?.memories ?? []).map(toMemory)
+    };
+  }
+  /** Stop temporal decay for an end-user (pins their scores in time). */
+  async freeze(userId) {
+    const data = await this.request("POST", "/sdk/v1/freeze", {
+      body: { user_id: userId }
+    });
+    return data.frozen ?? false;
+  }
+  /** Usage statistics for the authenticated API key (optionally scoped to one user). */
+  async stats(userId) {
+    return this.request("GET", "/sdk/v1/stats", {
+      query: userId ? { user_id: userId } : void 0
+    });
+  }
+};
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  AuthenticationError,
+  NotFoundError,
+  Quorex,
+  QuorexError,
+  RateLimitError,
+  ServerError
+});
+//# sourceMappingURL=index.cjs.map

package/dist/index.cjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/index.ts","../src/errors.ts","../src/client.ts"],"sourcesContent":["export { Quorex } from './client'\nexport {\n  QuorexError,\n  AuthenticationError,\n  NotFoundError,\n  RateLimitError,\n  ServerError,\n} from './errors'\nexport type {\n  QuorexOptions,\n  Memory,\n  StoreResult,\n  ForgetResult,\n  ScoreBreakdown,\n  ExplainResult,\n  ExportResult,\n  Stats,\n  RememberOptions,\n  RecallOptions,\n  ExplainOptions,\n} from './types'\n","/** Base class for all Quorex SDK errors. */\nexport class QuorexError extends Error {\n  statusCode?: number\n  constructor(message: string, statusCode?: number) {\n    super(message)\n    this.name = 'QuorexError'\n    this.statusCode = statusCode\n    // Restore prototype chain (TS targeting ES5/ES2015 quirk).\n    Object.setPrototypeOf(this, new.target.prototype)\n  }\n}\n\n/** API key missing, invalid or revoked (HTTP 401). */\nexport class AuthenticationError extends QuorexError {\n  constructor(message = 'Invalid or missing API key.', statusCode = 401) {\n    super(message, statusCode)\n    this.name = 'AuthenticationError'\n  }\n}\n\n/** Requested resource does not exist (HTTP 404). */\nexport class NotFoundError extends QuorexError {\n  constructor(message = 'Resource not found.', statusCode = 404) {\n    super(message, statusCode)\n    this.name = 'NotFoundError'\n  }\n}\n\n/** Rate limit exceeded (HTTP 429). */\nexport class RateLimitError extends QuorexError {\n  constructor(message = 'Rate limit exceeded.', statusCode = 429) {\n    super(message, statusCode)\n    this.name = 'RateLimitError'\n  }\n}\n\n/** Server-side error (HTTP 5xx). */\nexport class ServerError extends QuorexError {\n  constructor(message = 'Quorex server error.', statusCode = 500) {\n    super(message, statusCode)\n    this.name = 'ServerError'\n  }\n}\n","import {\n  AuthenticationError,\n  NotFoundError,\n  QuorexError,\n  RateLimitError,\n  ServerError,\n} from './errors'\nimport type {\n  ExplainOptions,\n  ExplainResult,\n  ExportResult,\n  ForgetResult,\n  Memory,\n  QuorexOptions,\n  RecallOptions,\n  RememberOptions,\n  Stats,\n  StoreResult,\n} from './types'\n\nconst DEFAULT_BASE_URL = 'https://api.quorex.fr'\nconst DEFAULT_TIMEOUT = 30_000\nconst VERSION = '0.1.0'\n\nfunction envApiKey(): string | undefined {\n  try {\n    return typeof process !== 'undefined' ? process.env?.QUOREX_API_KEY : undefined\n  } catch {\n    return undefined\n  }\n}\n\n/* eslint-disable @typescript-eslint/no-explicit-any */\nfunction toMemory(m: any): Memory {\n  return {\n    vecId: m?.vec_id ?? null,\n    text: m?.text ?? '',\n    action: m?.action ?? '',\n    timestamp: m?.timestamp ?? null,\n    finalScore: m?.final_score ?? null,\n    cosineSim: m?.cosine_sim ?? null,\n    decayWeight: m?.decay_weight ?? null,\n    freqWeight: m?.freq_weight ?? null,\n    hoursAgo: m?.hours_ago ?? null,\n    reinforcements: m?.reinforcements ?? null,\n    meta: m?.meta ?? {},\n  }\n}\n\ninterface RequestInitLite {\n  body?: unknown\n  query?: Record<string, string | number | undefined | null>\n}\n\n/**\n * Quorex client — the memory layer for AI agents.\n *\n * ```ts\n * import { Quorex } from \"@quorex/sdk\";\n * const qx = new Quorex({ apiKey: \"qx_live_...\" });\n * await qx.remember(\"user_123\", \"prefers Vue.js over React\");\n * const memories = await qx.recall(\"user_123\", \"preferred framework?\");\n * ```\n */\nexport class Quorex {\n  private readonly apiKey: string\n  private readonly baseUrl: string\n  private readonly timeout: number\n\n  constructor(options: QuorexOptions = {}) {\n    const key = options.apiKey ?? envApiKey()\n    if (!key) {\n      throw new AuthenticationError(\n        'API key is required. Pass { apiKey } or set the QUOREX_API_KEY environment variable.'\n      )\n    }\n    this.apiKey = key\n    this.baseUrl = (options.baseUrl ?? DEFAULT_BASE_URL).replace(/\\/+$/, '')\n    this.timeout = options.timeout ?? DEFAULT_TIMEOUT\n  }\n\n  private async request<T>(method: string, path: string, init: RequestInitLite = {}): Promise<T> {\n    const url = new URL(this.baseUrl + path)\n    if (init.query) {\n      for (const [k, v] of Object.entries(init.query)) {\n        if (v !== undefined && v !== null) url.searchParams.set(k, String(v))\n      }\n    }\n\n    const controller = new AbortController()\n    const timer = setTimeout(() => controller.abort(), this.timeout)\n\n    let res: Response\n    try {\n      res = await fetch(url.toString(), {\n        method,\n        headers: {\n          'Content-Type': 'application/json',\n          Authorization: `Bearer ${this.apiKey}`,\n          'X-Quorex-Client': `quorex-js/${VERSION}`,\n        },\n        body: init.body !== undefined ? JSON.stringify(init.body) : undefined,\n        signal: controller.signal,\n      })\n    } catch (err: any) {\n      clearTimeout(timer)\n      if (err?.name === 'AbortError') throw new QuorexError('Request timed out.')\n      throw new QuorexError(`Network error: ${err?.message ?? String(err)}`)\n    }\n    clearTimeout(timer)\n    return this.handle<T>(res)\n  }\n\n  private async handle<T>(res: Response): Promise<T> {\n    let data: any = null\n    const text = await res.text()\n    if (text) {\n      try {\n        data = JSON.parse(text)\n      } catch {\n        data = text\n      }\n    }\n\n    if (res.ok) return data as T\n\n    const detail: string = (data && (data.detail || data.error)) || res.statusText || 'Unknown error'\n    if (res.status === 401) throw new AuthenticationError(detail, 401)\n    if (res.status === 404) throw new NotFoundError(detail, 404)\n    if (res.status === 429) throw new RateLimitError(detail, 429)\n    if (res.status >= 500) throw new ServerError(detail, res.status)\n    throw new QuorexError(`API error (${res.status}): ${detail}`, res.status)\n  }\n\n  /** Store a memory for one of your end-users. */\n  async remember(userId: string, text: string, opts: RememberOptions = {}): Promise<StoreResult> {\n    const data = await this.request<{ vec_id: number }>('POST', '/sdk/v1/remember', {\n      body: {\n        user_id: userId,\n        text,\n        action: opts.action ?? 'memory',\n        metadata: opts.metadata ?? {},\n        timestamp: opts.timestamp ?? Date.now() / 1000,\n      },\n    })\n    return { vecId: data.vec_id }\n  }\n\n  /** Retrieve the most relevant memories for a query, ranked by final score. */\n  async recall(userId: string, query: string, opts: RecallOptions = {}): Promise<Memory[]> {\n    const data = await this.request<{ memories: any[] }>('POST', '/sdk/v1/recall', {\n      body: { user_id: userId, query, top_k: opts.topK ?? 5, threshold: opts.threshold ?? 0.05 },\n    })\n    return (data.memories ?? []).map(toMemory)\n  }\n\n  /** Like recall(), but each result includes a human-readable score breakdown. */\n  async explain(userId: string, query: string, opts: ExplainOptions = {}): Promise<ExplainResult[]> {\n    const data = await this.request<{ results: any[] }>('POST', '/sdk/v1/explain', {\n      body: { user_id: userId, query, top_k: opts.topK ?? 1 },\n    })\n    return (data.results ?? []).map((r: any) => ({\n      memory: toMemory(r),\n      explanation: r?.explanation ?? '',\n      scoreBreakdown: {\n        finalScore: r?.score_breakdown?.final_score,\n        cosineSim: r?.score_breakdown?.cosine_sim,\n        decayWeight: r?.score_breakdown?.decay_weight,\n        freqWeight: r?.score_breakdown?.freq_weight,\n        reinforcements: r?.score_breakdown?.reinforcements,\n        hoursAgo: r?.score_breakdown?.hours_ago,\n      },\n    }))\n  }\n\n  /** Delete a single memory by its vector id. */\n  async forget(userId: string, vecId: number): Promise<ForgetResult> {\n    const data = await this.request<{ deleted: boolean }>('DELETE', '/sdk/v1/forget', {\n      body: { user_id: userId, vec_id: vecId },\n    })\n    return { deleted: data.deleted ?? false, vecId }\n  }\n\n  /** GDPR — delete ALL memories for an end-user. Returns the count removed. */\n  async purge(userId: string): Promise<number> {\n    const data = await this.request<{ deleted: number }>('DELETE', '/sdk/v1/purge', {\n      body: { user_id: userId },\n    })\n    return data.deleted ?? 0\n  }\n\n  /** GDPR — export all memories for an end-user. */\n  async export(userId: string): Promise<ExportResult> {\n    const data = await this.request<any>('GET', '/sdk/v1/export', { query: { user_id: userId } })\n    return {\n      userId: data?.user_id ?? userId,\n      count: data?.count ?? (data?.memories?.length ?? 0),\n      memories: (data?.memories ?? []).map(toMemory),\n    }\n  }\n\n  /** Stop temporal decay for an end-user (pins their scores in time). */\n  async freeze(userId: string): Promise<boolean> {\n    const data = await this.request<{ frozen: boolean }>('POST', '/sdk/v1/freeze', {\n      body: { user_id: userId },\n    })\n    return data.frozen ?? false\n  }\n\n  /** Usage statistics for the authenticated API key (optionally scoped to one user). */\n  async stats(userId?: string): Promise<Stats> {\n    return this.request<Stats>('GET', '/sdk/v1/stats', {\n      query: userId ? { user_id: userId } : undefined,\n    })\n  }\n}\n"],"mappings":"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","names":[]}

package/dist/index.d.cts

@@ -0,0 +1,123 @@
+interface QuorexOptions {
+    /** Secret key (qx_live_...). Falls back to process.env.QUOREX_API_KEY in Node. */
+    apiKey?: string;
+    /** API base URL. Default "https://api.quorex.fr". */
+    baseUrl?: string;
+    /** Request timeout in milliseconds. Default 30000. */
+    timeout?: number;
+}
+/** A recalled memory with its full re-ranking breakdown. */
+interface Memory {
+    vecId: number | null;
+    text: string;
+    action: string;
+    timestamp: number | null;
+    finalScore: number | null;
+    cosineSim: number | null;
+    decayWeight: number | null;
+    freqWeight: number | null;
+    hoursAgo: number | null;
+    reinforcements: number | null;
+    meta: Record<string, unknown>;
+}
+interface StoreResult {
+    vecId: number;
+}
+interface ForgetResult {
+    deleted: boolean;
+    vecId: number;
+}
+interface ScoreBreakdown {
+    finalScore?: number;
+    cosineSim?: number;
+    decayWeight?: number;
+    freqWeight?: number;
+    reinforcements?: number;
+    hoursAgo?: number;
+}
+interface ExplainResult {
+    memory: Memory;
+    explanation: string;
+    scoreBreakdown: ScoreBreakdown;
+}
+interface ExportResult {
+    userId: string;
+    count: number;
+    memories: Memory[];
+}
+interface Stats {
+    [key: string]: unknown;
+}
+interface RememberOptions {
+    /** Category label. Default "memory". */
+    action?: string;
+    metadata?: Record<string, unknown>;
+    /** Unix timestamp in seconds. Defaults to now. */
+    timestamp?: number;
+}
+interface RecallOptions {
+    topK?: number;
+    threshold?: number;
+}
+interface ExplainOptions {
+    topK?: number;
+}
+
+/**
+ * Quorex client — the memory layer for AI agents.
+ *
+ * ```ts
+ * import { Quorex } from "@quorex/sdk";
+ * const qx = new Quorex({ apiKey: "qx_live_..." });
+ * await qx.remember("user_123", "prefers Vue.js over React");
+ * const memories = await qx.recall("user_123", "preferred framework?");
+ * ```
+ */
+declare class Quorex {
+    private readonly apiKey;
+    private readonly baseUrl;
+    private readonly timeout;
+    constructor(options?: QuorexOptions);
+    private request;
+    private handle;
+    /** Store a memory for one of your end-users. */
+    remember(userId: string, text: string, opts?: RememberOptions): Promise<StoreResult>;
+    /** Retrieve the most relevant memories for a query, ranked by final score. */
+    recall(userId: string, query: string, opts?: RecallOptions): Promise<Memory[]>;
+    /** Like recall(), but each result includes a human-readable score breakdown. */
+    explain(userId: string, query: string, opts?: ExplainOptions): Promise<ExplainResult[]>;
+    /** Delete a single memory by its vector id. */
+    forget(userId: string, vecId: number): Promise<ForgetResult>;
+    /** GDPR — delete ALL memories for an end-user. Returns the count removed. */
+    purge(userId: string): Promise<number>;
+    /** GDPR — export all memories for an end-user. */
+    export(userId: string): Promise<ExportResult>;
+    /** Stop temporal decay for an end-user (pins their scores in time). */
+    freeze(userId: string): Promise<boolean>;
+    /** Usage statistics for the authenticated API key (optionally scoped to one user). */
+    stats(userId?: string): Promise<Stats>;
+}
+
+/** Base class for all Quorex SDK errors. */
+declare class QuorexError extends Error {
+    statusCode?: number;
+    constructor(message: string, statusCode?: number);
+}
+/** API key missing, invalid or revoked (HTTP 401). */
+declare class AuthenticationError extends QuorexError {
+    constructor(message?: string, statusCode?: number);
+}
+/** Requested resource does not exist (HTTP 404). */
+declare class NotFoundError extends QuorexError {
+    constructor(message?: string, statusCode?: number);
+}
+/** Rate limit exceeded (HTTP 429). */
+declare class RateLimitError extends QuorexError {
+    constructor(message?: string, statusCode?: number);
+}
+/** Server-side error (HTTP 5xx). */
+declare class ServerError extends QuorexError {
+    constructor(message?: string, statusCode?: number);
+}
+
+export { AuthenticationError, type ExplainOptions, type ExplainResult, type ExportResult, type ForgetResult, type Memory, NotFoundError, Quorex, QuorexError, type QuorexOptions, RateLimitError, type RecallOptions, type RememberOptions, type ScoreBreakdown, ServerError, type Stats, type StoreResult };

package/dist/index.d.ts

@@ -0,0 +1,123 @@
+interface QuorexOptions {
+    /** Secret key (qx_live_...). Falls back to process.env.QUOREX_API_KEY in Node. */
+    apiKey?: string;
+    /** API base URL. Default "https://api.quorex.fr". */
+    baseUrl?: string;
+    /** Request timeout in milliseconds. Default 30000. */
+    timeout?: number;
+}
+/** A recalled memory with its full re-ranking breakdown. */
+interface Memory {
+    vecId: number | null;
+    text: string;
+    action: string;
+    timestamp: number | null;
+    finalScore: number | null;
+    cosineSim: number | null;
+    decayWeight: number | null;
+    freqWeight: number | null;
+    hoursAgo: number | null;
+    reinforcements: number | null;
+    meta: Record<string, unknown>;
+}
+interface StoreResult {
+    vecId: number;
+}
+interface ForgetResult {
+    deleted: boolean;
+    vecId: number;
+}
+interface ScoreBreakdown {
+    finalScore?: number;
+    cosineSim?: number;
+    decayWeight?: number;
+    freqWeight?: number;
+    reinforcements?: number;
+    hoursAgo?: number;
+}
+interface ExplainResult {
+    memory: Memory;
+    explanation: string;
+    scoreBreakdown: ScoreBreakdown;
+}
+interface ExportResult {
+    userId: string;
+    count: number;
+    memories: Memory[];
+}
+interface Stats {
+    [key: string]: unknown;
+}
+interface RememberOptions {
+    /** Category label. Default "memory". */
+    action?: string;
+    metadata?: Record<string, unknown>;
+    /** Unix timestamp in seconds. Defaults to now. */
+    timestamp?: number;
+}
+interface RecallOptions {
+    topK?: number;
+    threshold?: number;
+}
+interface ExplainOptions {
+    topK?: number;
+}
+
+/**
+ * Quorex client — the memory layer for AI agents.
+ *
+ * ```ts
+ * import { Quorex } from "@quorex/sdk";
+ * const qx = new Quorex({ apiKey: "qx_live_..." });
+ * await qx.remember("user_123", "prefers Vue.js over React");
+ * const memories = await qx.recall("user_123", "preferred framework?");
+ * ```
+ */
+declare class Quorex {
+    private readonly apiKey;
+    private readonly baseUrl;
+    private readonly timeout;
+    constructor(options?: QuorexOptions);
+    private request;
+    private handle;
+    /** Store a memory for one of your end-users. */
+    remember(userId: string, text: string, opts?: RememberOptions): Promise<StoreResult>;
+    /** Retrieve the most relevant memories for a query, ranked by final score. */
+    recall(userId: string, query: string, opts?: RecallOptions): Promise<Memory[]>;
+    /** Like recall(), but each result includes a human-readable score breakdown. */
+    explain(userId: string, query: string, opts?: ExplainOptions): Promise<ExplainResult[]>;
+    /** Delete a single memory by its vector id. */
+    forget(userId: string, vecId: number): Promise<ForgetResult>;
+    /** GDPR — delete ALL memories for an end-user. Returns the count removed. */
+    purge(userId: string): Promise<number>;
+    /** GDPR — export all memories for an end-user. */
+    export(userId: string): Promise<ExportResult>;
+    /** Stop temporal decay for an end-user (pins their scores in time). */
+    freeze(userId: string): Promise<boolean>;
+    /** Usage statistics for the authenticated API key (optionally scoped to one user). */
+    stats(userId?: string): Promise<Stats>;
+}
+
+/** Base class for all Quorex SDK errors. */
+declare class QuorexError extends Error {
+    statusCode?: number;
+    constructor(message: string, statusCode?: number);
+}
+/** API key missing, invalid or revoked (HTTP 401). */
+declare class AuthenticationError extends QuorexError {
+    constructor(message?: string, statusCode?: number);
+}
+/** Requested resource does not exist (HTTP 404). */
+declare class NotFoundError extends QuorexError {
+    constructor(message?: string, statusCode?: number);
+}
+/** Rate limit exceeded (HTTP 429). */
+declare class RateLimitError extends QuorexError {
+    constructor(message?: string, statusCode?: number);
+}
+/** Server-side error (HTTP 5xx). */
+declare class ServerError extends QuorexError {
+    constructor(message?: string, statusCode?: number);
+}
+
+export { AuthenticationError, type ExplainOptions, type ExplainResult, type ExportResult, type ForgetResult, type Memory, NotFoundError, Quorex, QuorexError, type QuorexOptions, RateLimitError, type RecallOptions, type RememberOptions, type ScoreBreakdown, ServerError, type Stats, type StoreResult };

package/dist/index.js

@@ -0,0 +1,203 @@
+// src/errors.ts
+var QuorexError = class extends Error {
+  constructor(message, statusCode) {
+    super(message);
+    this.name = "QuorexError";
+    this.statusCode = statusCode;
+    Object.setPrototypeOf(this, new.target.prototype);
+  }
+};
+var AuthenticationError = class extends QuorexError {
+  constructor(message = "Invalid or missing API key.", statusCode = 401) {
+    super(message, statusCode);
+    this.name = "AuthenticationError";
+  }
+};
+var NotFoundError = class extends QuorexError {
+  constructor(message = "Resource not found.", statusCode = 404) {
+    super(message, statusCode);
+    this.name = "NotFoundError";
+  }
+};
+var RateLimitError = class extends QuorexError {
+  constructor(message = "Rate limit exceeded.", statusCode = 429) {
+    super(message, statusCode);
+    this.name = "RateLimitError";
+  }
+};
+var ServerError = class extends QuorexError {
+  constructor(message = "Quorex server error.", statusCode = 500) {
+    super(message, statusCode);
+    this.name = "ServerError";
+  }
+};
+
+// src/client.ts
+var DEFAULT_BASE_URL = "https://api.quorex.fr";
+var DEFAULT_TIMEOUT = 3e4;
+var VERSION = "0.1.0";
+function envApiKey() {
+  try {
+    return typeof process !== "undefined" ? process.env?.QUOREX_API_KEY : void 0;
+  } catch {
+    return void 0;
+  }
+}
+function toMemory(m) {
+  return {
+    vecId: m?.vec_id ?? null,
+    text: m?.text ?? "",
+    action: m?.action ?? "",
+    timestamp: m?.timestamp ?? null,
+    finalScore: m?.final_score ?? null,
+    cosineSim: m?.cosine_sim ?? null,
+    decayWeight: m?.decay_weight ?? null,
+    freqWeight: m?.freq_weight ?? null,
+    hoursAgo: m?.hours_ago ?? null,
+    reinforcements: m?.reinforcements ?? null,
+    meta: m?.meta ?? {}
+  };
+}
+var Quorex = class {
+  constructor(options = {}) {
+    const key = options.apiKey ?? envApiKey();
+    if (!key) {
+      throw new AuthenticationError(
+        "API key is required. Pass { apiKey } or set the QUOREX_API_KEY environment variable."
+      );
+    }
+    this.apiKey = key;
+    this.baseUrl = (options.baseUrl ?? DEFAULT_BASE_URL).replace(/\/+$/, "");
+    this.timeout = options.timeout ?? DEFAULT_TIMEOUT;
+  }
+  async request(method, path, init = {}) {
+    const url = new URL(this.baseUrl + path);
+    if (init.query) {
+      for (const [k, v] of Object.entries(init.query)) {
+        if (v !== void 0 && v !== null) url.searchParams.set(k, String(v));
+      }
+    }
+    const controller = new AbortController();
+    const timer = setTimeout(() => controller.abort(), this.timeout);
+    let res;
+    try {
+      res = await fetch(url.toString(), {
+        method,
+        headers: {
+          "Content-Type": "application/json",
+          Authorization: `Bearer ${this.apiKey}`,
+          "X-Quorex-Client": `quorex-js/${VERSION}`
+        },
+        body: init.body !== void 0 ? JSON.stringify(init.body) : void 0,
+        signal: controller.signal
+      });
+    } catch (err) {
+      clearTimeout(timer);
+      if (err?.name === "AbortError") throw new QuorexError("Request timed out.");
+      throw new QuorexError(`Network error: ${err?.message ?? String(err)}`);
+    }
+    clearTimeout(timer);
+    return this.handle(res);
+  }
+  async handle(res) {
+    let data = null;
+    const text = await res.text();
+    if (text) {
+      try {
+        data = JSON.parse(text);
+      } catch {
+        data = text;
+      }
+    }
+    if (res.ok) return data;
+    const detail = data && (data.detail || data.error) || res.statusText || "Unknown error";
+    if (res.status === 401) throw new AuthenticationError(detail, 401);
+    if (res.status === 404) throw new NotFoundError(detail, 404);
+    if (res.status === 429) throw new RateLimitError(detail, 429);
+    if (res.status >= 500) throw new ServerError(detail, res.status);
+    throw new QuorexError(`API error (${res.status}): ${detail}`, res.status);
+  }
+  /** Store a memory for one of your end-users. */
+  async remember(userId, text, opts = {}) {
+    const data = await this.request("POST", "/sdk/v1/remember", {
+      body: {
+        user_id: userId,
+        text,
+        action: opts.action ?? "memory",
+        metadata: opts.metadata ?? {},
+        timestamp: opts.timestamp ?? Date.now() / 1e3
+      }
+    });
+    return { vecId: data.vec_id };
+  }
+  /** Retrieve the most relevant memories for a query, ranked by final score. */
+  async recall(userId, query, opts = {}) {
+    const data = await this.request("POST", "/sdk/v1/recall", {
+      body: { user_id: userId, query, top_k: opts.topK ?? 5, threshold: opts.threshold ?? 0.05 }
+    });
+    return (data.memories ?? []).map(toMemory);
+  }
+  /** Like recall(), but each result includes a human-readable score breakdown. */
+  async explain(userId, query, opts = {}) {
+    const data = await this.request("POST", "/sdk/v1/explain", {
+      body: { user_id: userId, query, top_k: opts.topK ?? 1 }
+    });
+    return (data.results ?? []).map((r) => ({
+      memory: toMemory(r),
+      explanation: r?.explanation ?? "",
+      scoreBreakdown: {
+        finalScore: r?.score_breakdown?.final_score,
+        cosineSim: r?.score_breakdown?.cosine_sim,
+        decayWeight: r?.score_breakdown?.decay_weight,
+        freqWeight: r?.score_breakdown?.freq_weight,
+        reinforcements: r?.score_breakdown?.reinforcements,
+        hoursAgo: r?.score_breakdown?.hours_ago
+      }
+    }));
+  }
+  /** Delete a single memory by its vector id. */
+  async forget(userId, vecId) {
+    const data = await this.request("DELETE", "/sdk/v1/forget", {
+      body: { user_id: userId, vec_id: vecId }
+    });
+    return { deleted: data.deleted ?? false, vecId };
+  }
+  /** GDPR — delete ALL memories for an end-user. Returns the count removed. */
+  async purge(userId) {
+    const data = await this.request("DELETE", "/sdk/v1/purge", {
+      body: { user_id: userId }
+    });
+    return data.deleted ?? 0;
+  }
+  /** GDPR — export all memories for an end-user. */
+  async export(userId) {
+    const data = await this.request("GET", "/sdk/v1/export", { query: { user_id: userId } });
+    return {
+      userId: data?.user_id ?? userId,
+      count: data?.count ?? (data?.memories?.length ?? 0),
+      memories: (data?.memories ?? []).map(toMemory)
+    };
+  }
+  /** Stop temporal decay for an end-user (pins their scores in time). */
+  async freeze(userId) {
+    const data = await this.request("POST", "/sdk/v1/freeze", {
+      body: { user_id: userId }
+    });
+    return data.frozen ?? false;
+  }
+  /** Usage statistics for the authenticated API key (optionally scoped to one user). */
+  async stats(userId) {
+    return this.request("GET", "/sdk/v1/stats", {
+      query: userId ? { user_id: userId } : void 0
+    });
+  }
+};
+export {
+  AuthenticationError,
+  NotFoundError,
+  Quorex,
+  QuorexError,
+  RateLimitError,
+  ServerError
+};
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/errors.ts","../src/client.ts"],"sourcesContent":["/** Base class for all Quorex SDK errors. */\nexport class QuorexError extends Error {\n  statusCode?: number\n  constructor(message: string, statusCode?: number) {\n    super(message)\n    this.name = 'QuorexError'\n    this.statusCode = statusCode\n    // Restore prototype chain (TS targeting ES5/ES2015 quirk).\n    Object.setPrototypeOf(this, new.target.prototype)\n  }\n}\n\n/** API key missing, invalid or revoked (HTTP 401). */\nexport class AuthenticationError extends QuorexError {\n  constructor(message = 'Invalid or missing API key.', statusCode = 401) {\n    super(message, statusCode)\n    this.name = 'AuthenticationError'\n  }\n}\n\n/** Requested resource does not exist (HTTP 404). */\nexport class NotFoundError extends QuorexError {\n  constructor(message = 'Resource not found.', statusCode = 404) {\n    super(message, statusCode)\n    this.name = 'NotFoundError'\n  }\n}\n\n/** Rate limit exceeded (HTTP 429). */\nexport class RateLimitError extends QuorexError {\n  constructor(message = 'Rate limit exceeded.', statusCode = 429) {\n    super(message, statusCode)\n    this.name = 'RateLimitError'\n  }\n}\n\n/** Server-side error (HTTP 5xx). */\nexport class ServerError extends QuorexError {\n  constructor(message = 'Quorex server error.', statusCode = 500) {\n    super(message, statusCode)\n    this.name = 'ServerError'\n  }\n}\n","import {\n  AuthenticationError,\n  NotFoundError,\n  QuorexError,\n  RateLimitError,\n  ServerError,\n} from './errors'\nimport type {\n  ExplainOptions,\n  ExplainResult,\n  ExportResult,\n  ForgetResult,\n  Memory,\n  QuorexOptions,\n  RecallOptions,\n  RememberOptions,\n  Stats,\n  StoreResult,\n} from './types'\n\nconst DEFAULT_BASE_URL = 'https://api.quorex.fr'\nconst DEFAULT_TIMEOUT = 30_000\nconst VERSION = '0.1.0'\n\nfunction envApiKey(): string | undefined {\n  try {\n    return typeof process !== 'undefined' ? process.env?.QUOREX_API_KEY : undefined\n  } catch {\n    return undefined\n  }\n}\n\n/* eslint-disable @typescript-eslint/no-explicit-any */\nfunction toMemory(m: any): Memory {\n  return {\n    vecId: m?.vec_id ?? null,\n    text: m?.text ?? '',\n    action: m?.action ?? '',\n    timestamp: m?.timestamp ?? null,\n    finalScore: m?.final_score ?? null,\n    cosineSim: m?.cosine_sim ?? null,\n    decayWeight: m?.decay_weight ?? null,\n    freqWeight: m?.freq_weight ?? null,\n    hoursAgo: m?.hours_ago ?? null,\n    reinforcements: m?.reinforcements ?? null,\n    meta: m?.meta ?? {},\n  }\n}\n\ninterface RequestInitLite {\n  body?: unknown\n  query?: Record<string, string | number | undefined | null>\n}\n\n/**\n * Quorex client — the memory layer for AI agents.\n *\n * ```ts\n * import { Quorex } from \"@quorex/sdk\";\n * const qx = new Quorex({ apiKey: \"qx_live_...\" });\n * await qx.remember(\"user_123\", \"prefers Vue.js over React\");\n * const memories = await qx.recall(\"user_123\", \"preferred framework?\");\n * ```\n */\nexport class Quorex {\n  private readonly apiKey: string\n  private readonly baseUrl: string\n  private readonly timeout: number\n\n  constructor(options: QuorexOptions = {}) {\n    const key = options.apiKey ?? envApiKey()\n    if (!key) {\n      throw new AuthenticationError(\n        'API key is required. Pass { apiKey } or set the QUOREX_API_KEY environment variable.'\n      )\n    }\n    this.apiKey = key\n    this.baseUrl = (options.baseUrl ?? DEFAULT_BASE_URL).replace(/\\/+$/, '')\n    this.timeout = options.timeout ?? DEFAULT_TIMEOUT\n  }\n\n  private async request<T>(method: string, path: string, init: RequestInitLite = {}): Promise<T> {\n    const url = new URL(this.baseUrl + path)\n    if (init.query) {\n      for (const [k, v] of Object.entries(init.query)) {\n        if (v !== undefined && v !== null) url.searchParams.set(k, String(v))\n      }\n    }\n\n    const controller = new AbortController()\n    const timer = setTimeout(() => controller.abort(), this.timeout)\n\n    let res: Response\n    try {\n      res = await fetch(url.toString(), {\n        method,\n        headers: {\n          'Content-Type': 'application/json',\n          Authorization: `Bearer ${this.apiKey}`,\n          'X-Quorex-Client': `quorex-js/${VERSION}`,\n        },\n        body: init.body !== undefined ? JSON.stringify(init.body) : undefined,\n        signal: controller.signal,\n      })\n    } catch (err: any) {\n      clearTimeout(timer)\n      if (err?.name === 'AbortError') throw new QuorexError('Request timed out.')\n      throw new QuorexError(`Network error: ${err?.message ?? String(err)}`)\n    }\n    clearTimeout(timer)\n    return this.handle<T>(res)\n  }\n\n  private async handle<T>(res: Response): Promise<T> {\n    let data: any = null\n    const text = await res.text()\n    if (text) {\n      try {\n        data = JSON.parse(text)\n      } catch {\n        data = text\n      }\n    }\n\n    if (res.ok) return data as T\n\n    const detail: string = (data && (data.detail || data.error)) || res.statusText || 'Unknown error'\n    if (res.status === 401) throw new AuthenticationError(detail, 401)\n    if (res.status === 404) throw new NotFoundError(detail, 404)\n    if (res.status === 429) throw new RateLimitError(detail, 429)\n    if (res.status >= 500) throw new ServerError(detail, res.status)\n    throw new QuorexError(`API error (${res.status}): ${detail}`, res.status)\n  }\n\n  /** Store a memory for one of your end-users. */\n  async remember(userId: string, text: string, opts: RememberOptions = {}): Promise<StoreResult> {\n    const data = await this.request<{ vec_id: number }>('POST', '/sdk/v1/remember', {\n      body: {\n        user_id: userId,\n        text,\n        action: opts.action ?? 'memory',\n        metadata: opts.metadata ?? {},\n        timestamp: opts.timestamp ?? Date.now() / 1000,\n      },\n    })\n    return { vecId: data.vec_id }\n  }\n\n  /** Retrieve the most relevant memories for a query, ranked by final score. */\n  async recall(userId: string, query: string, opts: RecallOptions = {}): Promise<Memory[]> {\n    const data = await this.request<{ memories: any[] }>('POST', '/sdk/v1/recall', {\n      body: { user_id: userId, query, top_k: opts.topK ?? 5, threshold: opts.threshold ?? 0.05 },\n    })\n    return (data.memories ?? []).map(toMemory)\n  }\n\n  /** Like recall(), but each result includes a human-readable score breakdown. */\n  async explain(userId: string, query: string, opts: ExplainOptions = {}): Promise<ExplainResult[]> {\n    const data = await this.request<{ results: any[] }>('POST', '/sdk/v1/explain', {\n      body: { user_id: userId, query, top_k: opts.topK ?? 1 },\n    })\n    return (data.results ?? []).map((r: any) => ({\n      memory: toMemory(r),\n      explanation: r?.explanation ?? '',\n      scoreBreakdown: {\n        finalScore: r?.score_breakdown?.final_score,\n        cosineSim: r?.score_breakdown?.cosine_sim,\n        decayWeight: r?.score_breakdown?.decay_weight,\n        freqWeight: r?.score_breakdown?.freq_weight,\n        reinforcements: r?.score_breakdown?.reinforcements,\n        hoursAgo: r?.score_breakdown?.hours_ago,\n      },\n    }))\n  }\n\n  /** Delete a single memory by its vector id. */\n  async forget(userId: string, vecId: number): Promise<ForgetResult> {\n    const data = await this.request<{ deleted: boolean }>('DELETE', '/sdk/v1/forget', {\n      body: { user_id: userId, vec_id: vecId },\n    })\n    return { deleted: data.deleted ?? false, vecId }\n  }\n\n  /** GDPR — delete ALL memories for an end-user. Returns the count removed. */\n  async purge(userId: string): Promise<number> {\n    const data = await this.request<{ deleted: number }>('DELETE', '/sdk/v1/purge', {\n      body: { user_id: userId },\n    })\n    return data.deleted ?? 0\n  }\n\n  /** GDPR — export all memories for an end-user. */\n  async export(userId: string): Promise<ExportResult> {\n    const data = await this.request<any>('GET', '/sdk/v1/export', { query: { user_id: userId } })\n    return {\n      userId: data?.user_id ?? userId,\n      count: data?.count ?? (data?.memories?.length ?? 0),\n      memories: (data?.memories ?? []).map(toMemory),\n    }\n  }\n\n  /** Stop temporal decay for an end-user (pins their scores in time). */\n  async freeze(userId: string): Promise<boolean> {\n    const data = await this.request<{ frozen: boolean }>('POST', '/sdk/v1/freeze', {\n      body: { user_id: userId },\n    })\n    return data.frozen ?? false\n  }\n\n  /** Usage statistics for the authenticated API key (optionally scoped to one user). */\n  async stats(userId?: string): Promise<Stats> {\n    return this.request<Stats>('GET', '/sdk/v1/stats', {\n      query: userId ? { user_id: userId } : undefined,\n    })\n  }\n}\n"],"mappings":";AACO,IAAM,cAAN,cAA0B,MAAM;AAAA,EAErC,YAAY,SAAiB,YAAqB;AAChD,UAAM,OAAO;AACb,SAAK,OAAO;AACZ,SAAK,aAAa;AAElB,WAAO,eAAe,MAAM,WAAW,SAAS;AAAA,EAClD;AACF;AAGO,IAAM,sBAAN,cAAkC,YAAY;AAAA,EACnD,YAAY,UAAU,+BAA+B,aAAa,KAAK;AACrE,UAAM,SAAS,UAAU;AACzB,SAAK,OAAO;AAAA,EACd;AACF;AAGO,IAAM,gBAAN,cAA4B,YAAY;AAAA,EAC7C,YAAY,UAAU,uBAAuB,aAAa,KAAK;AAC7D,UAAM,SAAS,UAAU;AACzB,SAAK,OAAO;AAAA,EACd;AACF;AAGO,IAAM,iBAAN,cAA6B,YAAY;AAAA,EAC9C,YAAY,UAAU,wBAAwB,aAAa,KAAK;AAC9D,UAAM,SAAS,UAAU;AACzB,SAAK,OAAO;AAAA,EACd;AACF;AAGO,IAAM,cAAN,cAA0B,YAAY;AAAA,EAC3C,YAAY,UAAU,wBAAwB,aAAa,KAAK;AAC9D,UAAM,SAAS,UAAU;AACzB,SAAK,OAAO;AAAA,EACd;AACF;;;ACtBA,IAAM,mBAAmB;AACzB,IAAM,kBAAkB;AACxB,IAAM,UAAU;AAEhB,SAAS,YAAgC;AACvC,MAAI;AACF,WAAO,OAAO,YAAY,cAAc,QAAQ,KAAK,iBAAiB;AAAA,EACxE,QAAQ;AACN,WAAO;AAAA,EACT;AACF;AAGA,SAAS,SAAS,GAAgB;AAChC,SAAO;AAAA,IACL,OAAO,GAAG,UAAU;AAAA,IACpB,MAAM,GAAG,QAAQ;AAAA,IACjB,QAAQ,GAAG,UAAU;AAAA,IACrB,WAAW,GAAG,aAAa;AAAA,IAC3B,YAAY,GAAG,eAAe;AAAA,IAC9B,WAAW,GAAG,cAAc;AAAA,IAC5B,aAAa,GAAG,gBAAgB;AAAA,IAChC,YAAY,GAAG,eAAe;AAAA,IAC9B,UAAU,GAAG,aAAa;AAAA,IAC1B,gBAAgB,GAAG,kBAAkB;AAAA,IACrC,MAAM,GAAG,QAAQ,CAAC;AAAA,EACpB;AACF;AAiBO,IAAM,SAAN,MAAa;AAAA,EAKlB,YAAY,UAAyB,CAAC,GAAG;AACvC,UAAM,MAAM,QAAQ,UAAU,UAAU;AACxC,QAAI,CAAC,KAAK;AACR,YAAM,IAAI;AAAA,QACR;AAAA,MACF;AAAA,IACF;AACA,SAAK,SAAS;AACd,SAAK,WAAW,QAAQ,WAAW,kBAAkB,QAAQ,QAAQ,EAAE;AACvE,SAAK,UAAU,QAAQ,WAAW;AAAA,EACpC;AAAA,EAEA,MAAc,QAAW,QAAgB,MAAc,OAAwB,CAAC,GAAe;AAC7F,UAAM,MAAM,IAAI,IAAI,KAAK,UAAU,IAAI;AACvC,QAAI,KAAK,OAAO;AACd,iBAAW,CAAC,GAAG,CAAC,KAAK,OAAO,QAAQ,KAAK,KAAK,GAAG;AAC/C,YAAI,MAAM,UAAa,MAAM,KAAM,KAAI,aAAa,IAAI,GAAG,OAAO,CAAC,CAAC;AAAA,MACtE;AAAA,IACF;AAEA,UAAM,aAAa,IAAI,gBAAgB;AACvC,UAAM,QAAQ,WAAW,MAAM,WAAW,MAAM,GAAG,KAAK,OAAO;AAE/D,QAAI;AACJ,QAAI;AACF,YAAM,MAAM,MAAM,IAAI,SAAS,GAAG;AAAA,QAChC;AAAA,QACA,SAAS;AAAA,UACP,gBAAgB;AAAA,UAChB,eAAe,UAAU,KAAK,MAAM;AAAA,UACpC,mBAAmB,aAAa,OAAO;AAAA,QACzC;AAAA,QACA,MAAM,KAAK,SAAS,SAAY,KAAK,UAAU,KAAK,IAAI,IAAI;AAAA,QAC5D,QAAQ,WAAW;AAAA,MACrB,CAAC;AAAA,IACH,SAAS,KAAU;AACjB,mBAAa,KAAK;AAClB,UAAI,KAAK,SAAS,aAAc,OAAM,IAAI,YAAY,oBAAoB;AAC1E,YAAM,IAAI,YAAY,kBAAkB,KAAK,WAAW,OAAO,GAAG,CAAC,EAAE;AAAA,IACvE;AACA,iBAAa,KAAK;AAClB,WAAO,KAAK,OAAU,GAAG;AAAA,EAC3B;AAAA,EAEA,MAAc,OAAU,KAA2B;AACjD,QAAI,OAAY;AAChB,UAAM,OAAO,MAAM,IAAI,KAAK;AAC5B,QAAI,MAAM;AACR,UAAI;AACF,eAAO,KAAK,MAAM,IAAI;AAAA,MACxB,QAAQ;AACN,eAAO;AAAA,MACT;AAAA,IACF;AAEA,QAAI,IAAI,GAAI,QAAO;AAEnB,UAAM,SAAkB,SAAS,KAAK,UAAU,KAAK,UAAW,IAAI,cAAc;AAClF,QAAI,IAAI,WAAW,IAAK,OAAM,IAAI,oBAAoB,QAAQ,GAAG;AACjE,QAAI,IAAI,WAAW,IAAK,OAAM,IAAI,cAAc,QAAQ,GAAG;AAC3D,QAAI,IAAI,WAAW,IAAK,OAAM,IAAI,eAAe,QAAQ,GAAG;AAC5D,QAAI,IAAI,UAAU,IAAK,OAAM,IAAI,YAAY,QAAQ,IAAI,MAAM;AAC/D,UAAM,IAAI,YAAY,cAAc,IAAI,MAAM,MAAM,MAAM,IAAI,IAAI,MAAM;AAAA,EAC1E;AAAA;AAAA,EAGA,MAAM,SAAS,QAAgB,MAAc,OAAwB,CAAC,GAAyB;AAC7F,UAAM,OAAO,MAAM,KAAK,QAA4B,QAAQ,oBAAoB;AAAA,MAC9E,MAAM;AAAA,QACJ,SAAS;AAAA,QACT;AAAA,QACA,QAAQ,KAAK,UAAU;AAAA,QACvB,UAAU,KAAK,YAAY,CAAC;AAAA,QAC5B,WAAW,KAAK,aAAa,KAAK,IAAI,IAAI;AAAA,MAC5C;AAAA,IACF,CAAC;AACD,WAAO,EAAE,OAAO,KAAK,OAAO;AAAA,EAC9B;AAAA;AAAA,EAGA,MAAM,OAAO,QAAgB,OAAe,OAAsB,CAAC,GAAsB;AACvF,UAAM,OAAO,MAAM,KAAK,QAA6B,QAAQ,kBAAkB;AAAA,MAC7E,MAAM,EAAE,SAAS,QAAQ,OAAO,OAAO,KAAK,QAAQ,GAAG,WAAW,KAAK,aAAa,KAAK;AAAA,IAC3F,CAAC;AACD,YAAQ,KAAK,YAAY,CAAC,GAAG,IAAI,QAAQ;AAAA,EAC3C;AAAA;AAAA,EAGA,MAAM,QAAQ,QAAgB,OAAe,OAAuB,CAAC,GAA6B;AAChG,UAAM,OAAO,MAAM,KAAK,QAA4B,QAAQ,mBAAmB;AAAA,MAC7E,MAAM,EAAE,SAAS,QAAQ,OAAO,OAAO,KAAK,QAAQ,EAAE;AAAA,IACxD,CAAC;AACD,YAAQ,KAAK,WAAW,CAAC,GAAG,IAAI,CAAC,OAAY;AAAA,MAC3C,QAAQ,SAAS,CAAC;AAAA,MAClB,aAAa,GAAG,eAAe;AAAA,MAC/B,gBAAgB;AAAA,QACd,YAAY,GAAG,iBAAiB;AAAA,QAChC,WAAW,GAAG,iBAAiB;AAAA,QAC/B,aAAa,GAAG,iBAAiB;AAAA,QACjC,YAAY,GAAG,iBAAiB;AAAA,QAChC,gBAAgB,GAAG,iBAAiB;AAAA,QACpC,UAAU,GAAG,iBAAiB;AAAA,MAChC;AAAA,IACF,EAAE;AAAA,EACJ;AAAA;AAAA,EAGA,MAAM,OAAO,QAAgB,OAAsC;AACjE,UAAM,OAAO,MAAM,KAAK,QAA8B,UAAU,kBAAkB;AAAA,MAChF,MAAM,EAAE,SAAS,QAAQ,QAAQ,MAAM;AAAA,IACzC,CAAC;AACD,WAAO,EAAE,SAAS,KAAK,WAAW,OAAO,MAAM;AAAA,EACjD;AAAA;AAAA,EAGA,MAAM,MAAM,QAAiC;AAC3C,UAAM,OAAO,MAAM,KAAK,QAA6B,UAAU,iBAAiB;AAAA,MAC9E,MAAM,EAAE,SAAS,OAAO;AAAA,IAC1B,CAAC;AACD,WAAO,KAAK,WAAW;AAAA,EACzB;AAAA;AAAA,EAGA,MAAM,OAAO,QAAuC;AAClD,UAAM,OAAO,MAAM,KAAK,QAAa,OAAO,kBAAkB,EAAE,OAAO,EAAE,SAAS,OAAO,EAAE,CAAC;AAC5F,WAAO;AAAA,MACL,QAAQ,MAAM,WAAW;AAAA,MACzB,OAAO,MAAM,UAAU,MAAM,UAAU,UAAU;AAAA,MACjD,WAAW,MAAM,YAAY,CAAC,GAAG,IAAI,QAAQ;AAAA,IAC/C;AAAA,EACF;AAAA;AAAA,EAGA,MAAM,OAAO,QAAkC;AAC7C,UAAM,OAAO,MAAM,KAAK,QAA6B,QAAQ,kBAAkB;AAAA,MAC7E,MAAM,EAAE,SAAS,OAAO;AAAA,IAC1B,CAAC;AACD,WAAO,KAAK,UAAU;AAAA,EACxB;AAAA;AAAA,EAGA,MAAM,MAAM,QAAiC;AAC3C,WAAO,KAAK,QAAe,OAAO,iBAAiB;AAAA,MACjD,OAAO,SAAS,EAAE,SAAS,OAAO,IAAI;AAAA,IACxC,CAAC;AAAA,EACH;AACF;","names":[]}

package/package.json

@@ -0,0 +1,42 @@
+{
+  "name": "@quorex/sdk",
+  "version": "0.1.0",
+  "description": "Official JavaScript/TypeScript SDK for Quorex — the memory layer for AI agents.",
+  "type": "module",
+  "main": "./dist/index.cjs",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "require": "./dist/index.cjs"
+    }
+  },
+  "files": ["dist", "README.md"],
+  "sideEffects": false,
+  "engines": { "node": ">=18" },
+  "scripts": {
+    "build": "tsup",
+    "typecheck": "tsc --noEmit",
+    "test": "vitest run",
+    "test:watch": "vitest",
+    "prepublishOnly": "npm run build"
+  },
+  "keywords": ["quorex", "memory", "ai", "llm", "agents", "sdk", "vector", "rag", "context"],
+  "homepage": "https://quorex.fr",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/quorex-ai/quorex-js.git"
+  },
+  "bugs": { "url": "https://github.com/quorex-ai/quorex-js/issues" },
+  "author": "Quorex",
+  "license": "MIT",
+  "publishConfig": { "access": "public" },
+  "devDependencies": {
+    "@types/node": "^20.0.0",
+    "tsup": "^8.0.0",
+    "typescript": "^5.4.0",
+    "vitest": "^2.0.0"
+  }
+}