@z3rno/sdk 0.0.1 → 0.1.0

package/dist/index.cjs

@@ -4,7 +4,12 @@ var zod = require('zod');
 
 // src/errors.ts
 var Z3rnoError = class extends Error {
+  /** HTTP status code returned by the server, if applicable. */
   statusCode;
+  /**
+   * @param message - Human-readable description of the error.
+   * @param statusCode - HTTP status code associated with the error, if any.
+   */
   constructor(message, statusCode) {
     super(message);
     this.name = "Z3rnoError";
@@ -12,13 +17,21 @@ var Z3rnoError = class extends Error {
   }
 };
 var AuthenticationError = class extends Z3rnoError {
+  /**
+   * @param message - Description of the authentication failure.
+   */
   constructor(message) {
     super(message, 401);
     this.name = "AuthenticationError";
   }
 };
 var RateLimitError = class extends Z3rnoError {
+  /** Number of seconds to wait before retrying, per the Retry-After header. */
   retryAfter;
+  /**
+   * @param message - Description of the rate-limit error.
+   * @param retryAfter - Seconds to wait before retrying (defaults to 60).
+   */
   constructor(message, retryAfter = 60) {
     super(message, 429);
     this.name = "RateLimitError";
@@ -26,23 +39,56 @@ var RateLimitError = class extends Z3rnoError {
   }
 };
 var ValidationError = class extends Z3rnoError {
+  /**
+   * @param message - Description of the validation failure.
+   * @param statusCode - HTTP status code (400 or 422, defaults to 400).
+   */
   constructor(message, statusCode = 400) {
     super(message, statusCode);
     this.name = "ValidationError";
   }
 };
 var NotFoundError = class extends Z3rnoError {
+  /**
+   * @param message - Description of what was not found.
+   */
   constructor(message) {
     super(message, 404);
     this.name = "NotFoundError";
   }
 };
 var ServerError = class extends Z3rnoError {
+  /**
+   * @param message - Description of the server error.
+   * @param statusCode - HTTP status code (defaults to 500).
+   */
   constructor(message, statusCode = 500) {
     super(message, statusCode);
     this.name = "ServerError";
   }
 };
+var Z3rnoTimeoutError = class extends Z3rnoError {
+  /** The timeout duration in milliseconds that was exceeded. */
+  timeout;
+  /**
+   * @param message - Description of the timeout.
+   * @param timeout - The configured timeout value in milliseconds.
+   */
+  constructor(message, timeout) {
+    super(message, void 0);
+    this.name = "Z3rnoTimeoutError";
+    this.timeout = timeout;
+  }
+};
+var Z3rnoConnectionError = class extends Z3rnoError {
+  /**
+   * @param message - Description of the connection failure.
+   */
+  constructor(message) {
+    super(message, void 0);
+    this.name = "Z3rnoConnectionError";
+  }
+};
 var MemoryType = zod.z.enum([
   "working",
   "episodic",
@@ -58,104 +104,283 @@ var RelationshipType = zod.z.enum([
   "caused_by"
 ]);
 zod.z.object({
+  /** UUID of the agent that owns this memory. */
   agentId: zod.z.string().uuid(),
+  /** The text content to store (1 to 100,000 characters). */
   content: zod.z.string().min(1).max(1e5),
+  /** Category of memory. Defaults to `"episodic"`. */
   memoryType: MemoryType.default("episodic"),
+  /** Optional UUID of the user associated with this memory. */
   userId: zod.z.string().uuid().optional(),
+  /** Arbitrary key-value metadata attached to the memory. */
   metadata: zod.z.record(zod.z.unknown()).default({}),
+  /** Relationships to other memories in the knowledge graph. */
   relationships: zod.z.array(
     zod.z.object({
+      /** UUID of the target memory. */
       targetMemoryId: zod.z.string().uuid(),
+      /** Type of relationship to the target memory. */
       relationshipType: RelationshipType,
+      /** Relationship strength from 0 to 1. Defaults to 1.0. */
       weight: zod.z.number().min(0).max(1).default(1),
+      /** Arbitrary metadata for the relationship edge. */
       metadata: zod.z.record(zod.z.unknown()).default({})
     })
   ).default([]),
+  /** Time-to-live in seconds. Memory auto-deletes after this duration. */
   ttlSeconds: zod.z.number().int().positive().optional(),
+  /** Importance score from 0 to 1. Influences recall ranking. */
   importance: zod.z.number().min(0).max(1).optional()
 });
 zod.z.object({
+  /** UUID of the agent whose memories to search. */
   agentId: zod.z.string().uuid(),
+  /** Natural-language query for semantic similarity search. */
   query: zod.z.string().optional(),
+  /** Filter results to a specific memory type. */
   memoryType: zod.z.string().optional(),
+  /** Additional metadata filters. */
   filters: zod.z.record(zod.z.unknown()).optional(),
+  /** Maximum number of results to return (1-100, default 10). */
   topK: zod.z.number().int().min(1).max(100).default(10),
+  /** Minimum similarity score threshold (0-1, default 0). */
   similarityThreshold: zod.z.number().min(0).max(1).default(0),
+  /** ISO 8601 timestamp for temporal queries (point-in-time recall). */
   asOf: zod.z.string().datetime().optional(),
+  /** Whether to include soft-deleted memories. */
   includeDeleted: zod.z.boolean().default(false)
 });
 zod.z.object({
+  /** UUID of the agent that owns the memories. */
   agentId: zod.z.string().uuid(),
+  /** UUID of a single memory to delete. */
   memoryId: zod.z.string().uuid().optional(),
+  /** UUIDs of multiple memories to delete in one call. */
   memoryIds: zod.z.array(zod.z.string().uuid()).optional(),
+  /** If true, permanently deletes (vs. soft-delete). Defaults to false. */
   hardDelete: zod.z.boolean().default(false),
+  /** If true, also deletes related memories. Defaults to false. */
   cascade: zod.z.boolean().default(false),
+  /** Optional reason for the deletion (stored in audit log). */
   reason: zod.z.string().optional()
 });
 var MemoryResponse = zod.z.object({
+  /** Unique identifier for this memory. */
   id: zod.z.string(),
+  /** UUID of the owning agent. */
   agent_id: zod.z.string(),
+  /** Text content of the memory. */
   content: zod.z.string(),
+  /** Category of the memory. */
   memory_type: zod.z.string(),
+  /** Server-computed importance score (0-1). */
   importance_score: zod.z.number(),
+  /** Number of times this memory has been recalled. */
   recall_count: zod.z.number(),
+  /** Name of the embedding model used, if any. */
   embedding_model: zod.z.string().nullable().optional(),
+  /** ISO 8601 creation timestamp. */
   created_at: zod.z.string(),
+  /** Arbitrary metadata attached to the memory. */
   metadata: zod.z.record(zod.z.unknown()).default({})
 });
 var RecallResultItem = zod.z.object({
+  /** Unique identifier of the recalled memory. */
   memory_id: zod.z.string(),
+  /** Text content of the memory. */
   content: zod.z.string(),
+  /** Optional server-generated summary. */
   summary: zod.z.string().nullable().optional(),
+  /** Category of the memory. */
   memory_type: zod.z.string(),
+  /** Cosine similarity to the query (0-1). */
   similarity_score: zod.z.number(),
+  /** Server-computed importance score (0-1). */
   importance_score: zod.z.number(),
+  /** Combined relevance score used for ranking (0-1). */
   relevance_score: zod.z.number(),
+  /** Number of times this memory has been recalled. */
   recall_count: zod.z.number(),
+  /** ISO 8601 creation timestamp. */
   created_at: zod.z.string(),
+  /** Arbitrary metadata attached to the memory. */
   metadata: zod.z.record(zod.z.unknown()).default({})
 });
 var RecallResponse = zod.z.object({
+  /** Ranked list of matching memories. */
   results: zod.z.array(RecallResultItem),
+  /** Total number of matches (may exceed `topK`). */
   total: zod.z.number(),
+  /** The query that was searched, if any. */
   query: zod.z.string().nullable().optional()
 });
 var ForgetResponse = zod.z.object({
+  /** Number of memories deleted. */
   deleted_count: zod.z.number(),
+  /** Whether a hard delete was performed. */
   hard_deleted: zod.z.boolean(),
+  /** Number of related memories deleted via cascade. */
   cascade_count: zod.z.number(),
+  /** IDs of all deleted memories. */
   memory_ids: zod.z.array(zod.z.string())
 });
 var AuditEntry = zod.z.object({
+  /** Auto-incrementing audit entry ID. */
   id: zod.z.number(),
+  /** UUID of the agent, if applicable. */
   agent_id: zod.z.string().nullable().optional(),
+  /** UUID of the user, if applicable. */
   user_id: zod.z.string().nullable().optional(),
+  /** Operation type (e.g., `"store"`, `"recall"`, `"forget"`). */
   operation: zod.z.string(),
+  /** UUID of the affected memory, if applicable. */
   memory_id: zod.z.string().nullable().optional(),
+  /** Memory type of the affected memory, if applicable. */
   memory_type: zod.z.string().nullable().optional(),
+  /** Additional details about the operation. */
   details: zod.z.record(zod.z.unknown()).default({}),
+  /** IP address of the caller, if available. */
   ip_address: zod.z.string().nullable().optional(),
+  /** ISO 8601 timestamp of the operation. */
   created_at: zod.z.string()
 });
 var AuditPageResponse = zod.z.object({
+  /** Audit entries on this page. */
   entries: zod.z.array(AuditEntry),
+  /** Total number of matching audit entries. */
   total: zod.z.number(),
+  /** Current page number (1-indexed). */
   page: zod.z.number(),
+  /** Number of entries per page. */
   page_size: zod.z.number(),
+  /** Whether more pages are available. */
   has_next: zod.z.boolean()
 });
+var BatchStoreResponse = zod.z.object({
+  /** Array of stored memory objects. */
+  results: zod.z.array(MemoryResponse),
+  /** Number of memories successfully stored. */
+  stored_count: zod.z.number()
+});
+var MemoryVersion = zod.z.object({
+  /** Version identifier. */
+  id: zod.z.string(),
+  /** Text content at this version. */
+  content: zod.z.string(),
+  /** Memory type at this version. */
+  memory_type: zod.z.string(),
+  /** Importance score at this version. */
+  importance_score: zod.z.number(),
+  /** ISO 8601 timestamp when this version became active. */
+  valid_from: zod.z.string(),
+  /** ISO 8601 timestamp when this version was superseded, or null if current. */
+  valid_to: zod.z.string().nullable().optional(),
+  /** Metadata at this version. */
+  metadata: zod.z.record(zod.z.unknown()).default({})
+});
+var MemoryHistoryResponse = zod.z.object({
+  /** UUID of the memory. */
+  memory_id: zod.z.string(),
+  /** Chronologically ordered list of versions. */
+  versions: zod.z.array(MemoryVersion),
+  /** Total number of versions. */
+  total: zod.z.number()
+});
+var SessionResponse = zod.z.object({
+  /** Unique session identifier. */
+  session_id: zod.z.string(),
+  /** UUID of the agent this session belongs to. */
+  agent_id: zod.z.string(),
+  /** Type of session (e.g., `"conversation"`). */
+  session_type: zod.z.string(),
+  /** ISO 8601 timestamp when the session started. */
+  started_at: zod.z.string(),
+  /** Arbitrary session metadata. */
+  metadata: zod.z.record(zod.z.unknown()).default({})
+});
+var EndSessionResponse = zod.z.object({
+  /** The session that was ended. */
+  session_id: zod.z.string(),
+  /** ISO 8601 timestamp when the session ended. */
+  ended_at: zod.z.string(),
+  /** Total duration of the session in seconds. */
+  duration_seconds: zod.z.number(),
+  /** Number of memories created during the session. */
+  memory_count: zod.z.number()
+});
 
 // src/client.ts
 var Z3rnoClient = class {
   baseUrl;
   apiKey;
   timeout;
-  constructor(config) {
-    this.baseUrl = config.baseUrl.replace(/\/$/, "");
-    this.apiKey = config.apiKey;
+  maxRetries;
+  fetchImpl;
+  onRequest;
+  onResponse;
+  /**
+   * Creates a new Z3rno client instance.
+   *
+   * @param config - Client configuration options. All fields are optional.
+   *
+   * @example
+   * ```ts
+   * // Explicit configuration
+   * const client = new Z3rnoClient({
+   *   baseUrl: "http://localhost:8000",
+   *   apiKey: "z3rno_sk_test_...",
+   *   timeout: 10000,
+   *   maxRetries: 2,
+   * });
+   *
+   * // Or rely on environment variables (Z3RNO_BASE_URL, Z3RNO_API_KEY)
+   * const client = new Z3rnoClient();
+   * ```
+   */
+  constructor(config = {}) {
+    let resolvedUrl = config.baseUrl ?? "";
+    if (!resolvedUrl && typeof process !== "undefined" && process.env) {
+      resolvedUrl = process.env.Z3RNO_BASE_URL ?? "";
+    }
+    if (!resolvedUrl) {
+      resolvedUrl = "https://api.z3rno.dev";
+    }
+    this.baseUrl = resolvedUrl.replace(/\/$/, "");
+    let resolvedKey = config.apiKey ?? "";
+    if (!resolvedKey && typeof process !== "undefined" && process.env) {
+      resolvedKey = process.env.Z3RNO_API_KEY ?? "";
+    }
+    this.apiKey = resolvedKey;
     this.timeout = config.timeout ?? 3e4;
+    this.maxRetries = config.maxRetries ?? 3;
+    this.fetchImpl = config.fetch ?? globalThis.fetch;
+    this.onRequest = config.onRequest;
+    this.onResponse = config.onResponse;
   }
   // --- Store ---
+  /**
+   * Stores a new memory for an agent.
+   *
+   * The server generates an embedding for the content and stores it in
+   * the vector database. The memory is immediately available for recall.
+   *
+   * @param request - The memory to store.
+   * @returns The stored memory, including the server-generated ID and scores.
+   * @throws {@link AuthenticationError} If the API key is invalid.
+   * @throws {@link ValidationError} If the request body is invalid.
+   * @throws {@link Z3rnoTimeoutError} If the request times out.
+   *
+   * @example
+   * ```ts
+   * const memory = await client.store({
+   *   agentId: "550e8400-e29b-41d4-a716-446655440000",
+   *   content: "User prefers dark mode",
+   *   memoryType: "semantic",
+   *   metadata: { source: "settings-page" },
+   * });
+   * console.log(memory.id); // "mem-abc123"
+   * ```
+   */
   async store(request) {
     const body = {
       agent_id: request.agentId,
@@ -176,6 +401,36 @@ var Z3rnoClient = class {
     return MemoryResponse.parse(resp);
   }
   // --- Recall ---
+  /**
+   * Recalls memories by semantic similarity to a query.
+   *
+   * Returns a ranked list of memories sorted by a combined relevance score
+   * that factors in similarity, importance, and recency.
+   *
+   * @param params - Recall parameters including the query and filters.
+   * @param params.agentId - UUID of the agent whose memories to search.
+   * @param params.query - Natural-language query for semantic search.
+   * @param params.memoryType - Filter by memory type.
+   * @param params.filters - Additional metadata filters.
+   * @param params.topK - Maximum results to return (default 10).
+   * @param params.similarityThreshold - Minimum similarity score (default 0).
+   * @returns Ranked recall results with similarity scores.
+   * @throws {@link AuthenticationError} If the API key is invalid.
+   * @throws {@link Z3rnoTimeoutError} If the request times out.
+   *
+   * @example
+   * ```ts
+   * const results = await client.recall({
+   *   agentId: "550e8400-e29b-41d4-a716-446655440000",
+   *   query: "user preferences",
+   *   topK: 5,
+   *   similarityThreshold: 0.7,
+   * });
+   * for (const item of results.results) {
+   *   console.log(`${item.content} (score: ${item.relevance_score})`);
+   * }
+   * ```
+   */
   async recall(params) {
     const body = {
       agent_id: params.agentId,
@@ -189,6 +444,35 @@ var Z3rnoClient = class {
     return RecallResponse.parse(resp);
   }
   // --- Forget ---
+  /**
+   * Forgets (deletes) one or more memories.
+   *
+   * By default, performs a soft delete (marks as deleted but retains data).
+   * Set `hardDelete: true` for permanent removal. Use `cascade: true` to
+   * also delete related memories in the knowledge graph.
+   *
+   * @param params - Forget parameters.
+   * @param params.agentId - UUID of the agent that owns the memories.
+   * @param params.memoryId - UUID of a single memory to delete.
+   * @param params.memoryIds - UUIDs of multiple memories to delete.
+   * @param params.hardDelete - Permanently delete (default false).
+   * @param params.cascade - Delete related memories too (default false).
+   * @param params.reason - Reason for deletion (stored in audit log).
+   * @returns Summary of the deletion operation.
+   * @throws {@link AuthenticationError} If the API key is invalid.
+   * @throws {@link NotFoundError} If the specified memory does not exist.
+   *
+   * @example
+   * ```ts
+   * const result = await client.forget({
+   *   agentId: "550e8400-e29b-41d4-a716-446655440000",
+   *   memoryId: "mem-abc123",
+   *   hardDelete: true,
+   *   reason: "User requested data deletion",
+   * });
+   * console.log(`Deleted ${result.deleted_count} memories`);
+   * ```
+   */
   async forget(params) {
     const body = {
       agent_id: params.agentId,
@@ -201,7 +485,193 @@ var Z3rnoClient = class {
     const resp = await this.request("POST", "/v1/memories/forget", body);
     return ForgetResponse.parse(resp);
   }
+  // --- Get Memory ---
+  /**
+   * Retrieves a single memory by its ID.
+   *
+   * @param memoryId - The unique identifier of the memory to retrieve.
+   * @returns The full memory object.
+   * @throws {@link NotFoundError} If no memory exists with the given ID.
+   * @throws {@link AuthenticationError} If the API key is invalid.
+   *
+   * @example
+   * ```ts
+   * const memory = await client.getMemory("mem-abc123");
+   * console.log(memory.content);
+   * console.log(memory.importance_score);
+   * ```
+   */
+  async getMemory(memoryId) {
+    const resp = await this.request("GET", `/v1/memories/${memoryId}`);
+    return MemoryResponse.parse(resp);
+  }
+  // --- Store Batch ---
+  /**
+   * Stores multiple memories in a single API call.
+   *
+   * More efficient than calling {@link store} in a loop. All memories are
+   * processed atomically on the server.
+   *
+   * @param memories - Array of memories to store.
+   * @returns The stored memories and a count of how many were created.
+   * @throws {@link ValidationError} If any memory in the batch is invalid.
+   * @throws {@link AuthenticationError} If the API key is invalid.
+   *
+   * @example
+   * ```ts
+   * const result = await client.storeBatch([
+   *   { agentId: "agent-1", content: "Fact one" },
+   *   { agentId: "agent-1", content: "Fact two", memoryType: "semantic" },
+   * ]);
+   * console.log(`Stored ${result.stored_count} memories`);
+   * ```
+   */
+  async storeBatch(memories) {
+    const body = {
+      memories: memories.map((m) => ({
+        agent_id: m.agentId,
+        content: m.content,
+        memory_type: m.memoryType,
+        metadata: m.metadata,
+        importance: m.importance
+      }))
+    };
+    const resp = await this.request("POST", "/v1/memories/batch", body);
+    return BatchStoreResponse.parse(resp);
+  }
+  // --- Memory History ---
+  /**
+   * Retrieves the full version history of a memory.
+   *
+   * Z3rno uses temporal versioning — every update creates a new version
+   * rather than overwriting. This method returns all versions ordered
+   * chronologically.
+   *
+   * @param memoryId - The unique identifier of the memory.
+   * @returns All versions of the memory with validity timestamps.
+   * @throws {@link NotFoundError} If no memory exists with the given ID.
+   * @throws {@link AuthenticationError} If the API key is invalid.
+   *
+   * @example
+   * ```ts
+   * const history = await client.getMemoryHistory("mem-abc123");
+   * for (const version of history.versions) {
+   *   console.log(`${version.valid_from}: ${version.content}`);
+   * }
+   * ```
+   */
+  async getMemoryHistory(memoryId) {
+    const resp = await this.request("GET", `/v1/memories/${memoryId}/history`);
+    return MemoryHistoryResponse.parse(resp);
+  }
+  // --- Update Memory ---
+  /**
+   * Updates an existing memory's content, metadata, or importance.
+   *
+   * Creates a new temporal version of the memory. The previous version
+   * remains accessible via {@link getMemoryHistory}.
+   *
+   * @param memoryId - The unique identifier of the memory to update.
+   * @param updates - Fields to update (only provided fields are changed).
+   * @param updates.content - New text content.
+   * @param updates.metadata - New metadata (replaces existing metadata).
+   * @param updates.importance - New importance score (0-1).
+   * @returns The updated memory object.
+   * @throws {@link NotFoundError} If no memory exists with the given ID.
+   * @throws {@link ValidationError} If the update values are invalid.
+   * @throws {@link AuthenticationError} If the API key is invalid.
+   *
+   * @example
+   * ```ts
+   * const updated = await client.updateMemory("mem-abc123", {
+   *   content: "User now prefers light mode",
+   *   importance: 0.9,
+   * });
+   * ```
+   */
+  async updateMemory(memoryId, updates) {
+    const body = {};
+    if (updates.content !== void 0) body.content = updates.content;
+    if (updates.metadata !== void 0) body.metadata = updates.metadata;
+    if (updates.importance !== void 0) body.importance = updates.importance;
+    const resp = await this.request("PATCH", `/v1/memories/${memoryId}`, body);
+    return MemoryResponse.parse(resp);
+  }
+  // --- Sessions ---
+  /**
+   * Starts a new session for grouping related memory operations.
+   *
+   * Sessions are useful for tracking conversation turns or task boundaries.
+   * Memories created during a session are automatically associated with it.
+   *
+   * @param params - Session parameters.
+   * @param params.agentId - UUID of the agent to start the session for.
+   * @param params.sessionType - Type of session (default `"conversation"`).
+   * @returns The created session with its ID and start time.
+   * @throws {@link AuthenticationError} If the API key is invalid.
+   *
+   * @example
+   * ```ts
+   * const session = await client.startSession({ agentId: "agent-1" });
+   * console.log(`Session started: ${session.session_id}`);
+   * // ... perform operations ...
+   * await client.endSession(session.session_id);
+   * ```
+   */
+  async startSession(params) {
+    const body = {
+      agent_id: params.agentId,
+      session_type: params.sessionType ?? "conversation"
+    };
+    const resp = await this.request("POST", "/v1/sessions", body);
+    return SessionResponse.parse(resp);
+  }
+  /**
+   * Ends an active session.
+   *
+   * Returns summary statistics including the session duration and the
+   * number of memories created during the session.
+   *
+   * @param sessionId - The unique identifier of the session to end.
+   * @returns Session summary with duration and memory count.
+   * @throws {@link NotFoundError} If no active session exists with the given ID.
+   * @throws {@link AuthenticationError} If the API key is invalid.
+   *
+   * @example
+   * ```ts
+   * const summary = await client.endSession("sess-abc123");
+   * console.log(`Session lasted ${summary.duration_seconds}s, ${summary.memory_count} memories`);
+   * ```
+   */
+  async endSession(sessionId) {
+    const resp = await this.request("POST", `/v1/sessions/${sessionId}/end`);
+    return EndSessionResponse.parse(resp);
+  }
   // --- Audit ---
+  /**
+   * Retrieves a paginated audit log of memory operations.
+   *
+   * The audit log records every store, recall, forget, and update operation
+   * performed by any agent. Useful for compliance, debugging, and analytics.
+   *
+   * @param params - Optional pagination and filter parameters.
+   * @param params.agentId - Filter by agent UUID.
+   * @param params.page - Page number (1-indexed).
+   * @param params.pageSize - Number of entries per page.
+   * @returns A page of audit log entries with pagination metadata.
+   * @throws {@link AuthenticationError} If the API key is invalid.
+   *
+   * @example
+   * ```ts
+   * const page = await client.audit({ agentId: "agent-1", page: 1, pageSize: 20 });
+   * for (const entry of page.entries) {
+   *   console.log(`${entry.created_at}: ${entry.operation} on ${entry.memory_id}`);
+   * }
+   * if (page.has_next) {
+   *   const nextPage = await client.audit({ agentId: "agent-1", page: 2 });
+   * }
+   * ```
+   */
   async audit(params) {
     const searchParams = new URLSearchParams();
     if (params?.agentId) searchParams.set("agent_id", params.agentId);
@@ -215,26 +685,75 @@ var Z3rnoClient = class {
   }
   // --- HTTP layer ---
   async request(method, path, body) {
-    const controller = new AbortController();
-    const timeoutId = setTimeout(() => controller.abort(), this.timeout);
-    try {
-      const response = await fetch(`${this.baseUrl}${path}`, {
-        method,
-        headers: {
-          Authorization: `Bearer ${this.apiKey}`,
-          "Content-Type": "application/json",
-          "User-Agent": "@z3rno/sdk/0.0.1"
-        },
-        body: body ? JSON.stringify(body) : void 0,
-        signal: controller.signal
-      });
-      clearTimeout(timeoutId);
-      return this.handleResponse(response);
-    } catch (error) {
-      clearTimeout(timeoutId);
-      if (error instanceof Z3rnoError) throw error;
-      throw new Z3rnoError(`Request failed: ${String(error)}`);
+    let lastError;
+    for (let attempt = 0; attempt <= this.maxRetries; attempt++) {
+      const controller = new AbortController();
+      const timeoutId = setTimeout(() => controller.abort(), this.timeout);
+      try {
+        const url = `${this.baseUrl}${path}`;
+        let init = {
+          method,
+          headers: {
+            Authorization: `Bearer ${this.apiKey}`,
+            "Content-Type": "application/json",
+            "User-Agent": "@z3rno/sdk/0.0.1"
+          },
+          body: body ? JSON.stringify(body) : void 0,
+          signal: controller.signal
+        };
+        if (this.onRequest) {
+          init = this.onRequest(url, init);
+        }
+        let response = await this.fetchImpl(url, init);
+        if (this.onResponse) {
+          response = this.onResponse(response);
+        }
+        clearTimeout(timeoutId);
+        if (response.status === 429 && attempt < this.maxRetries) {
+          const retryAfter = parseInt(
+            response.headers.get("Retry-After") ?? "1",
+            10
+          );
+          await this.sleep(retryAfter * 1e3);
+          continue;
+        }
+        if (response.status >= 500 && attempt < this.maxRetries) {
+          const delay = Math.pow(2, attempt) * 1e3;
+          await this.sleep(delay);
+          continue;
+        }
+        return this.handleResponse(response);
+      } catch (error) {
+        clearTimeout(timeoutId);
+        if (error instanceof Z3rnoError) throw error;
+        if (error instanceof DOMException && error.name === "AbortError") {
+          lastError = new Z3rnoTimeoutError(
+            `Request timed out after ${this.timeout}ms`,
+            this.timeout
+          );
+        } else if (error instanceof TypeError) {
+          lastError = new Z3rnoConnectionError(
+            `Connection failed: ${error.message}`
+          );
+        } else {
+          lastError = error instanceof Error ? error : new Error(String(error));
+        }
+        if (attempt < this.maxRetries) {
+          const delay = Math.pow(2, attempt) * 1e3;
+          await this.sleep(delay);
+          continue;
+        }
+      }
+    }
+    if (lastError instanceof Z3rnoError) {
+      throw lastError;
     }
+    throw new Z3rnoError(
+      `Request failed after ${this.maxRetries + 1} attempts: ${String(lastError)}`
+    );
+  }
+  sleep(ms) {
+    return new Promise((resolve) => setTimeout(resolve, ms));
   }
   async handleResponse(resp) {
     if (resp.ok) {
@@ -242,8 +761,16 @@ var Z3rnoClient = class {
     }
     let detail = resp.statusText;
     try {
-      const body = await resp.json();
-      detail = String(body.detail ?? body.error ?? resp.statusText);
+      const text = await resp.text();
+      try {
+        const body = JSON.parse(text);
+        detail = String(body.detail ?? body.error ?? resp.statusText);
+      } catch {
+        if (text.length > 0) {
+          const preview = text.length > 200 ? text.slice(0, 200) + "..." : text;
+          detail = `${resp.statusText} \u2014 ${preview}`;
+        }
+      }
     } catch {
     }
     switch (resp.status) {
@@ -276,17 +803,24 @@ var Z3rnoClient = class {
 exports.AuditEntry = AuditEntry;
 exports.AuditPageResponse = AuditPageResponse;
 exports.AuthenticationError = AuthenticationError;
+exports.BatchStoreResponse = BatchStoreResponse;
+exports.EndSessionResponse = EndSessionResponse;
 exports.ForgetResponse = ForgetResponse;
+exports.MemoryHistoryResponse = MemoryHistoryResponse;
 exports.MemoryResponse = MemoryResponse;
 exports.MemoryType = MemoryType;
+exports.MemoryVersion = MemoryVersion;
 exports.NotFoundError = NotFoundError;
 exports.RateLimitError = RateLimitError;
 exports.RecallResponse = RecallResponse;
 exports.RecallResultItem = RecallResultItem;
 exports.RelationshipType = RelationshipType;
 exports.ServerError = ServerError;
+exports.SessionResponse = SessionResponse;
 exports.ValidationError = ValidationError;
 exports.Z3rnoClient = Z3rnoClient;
+exports.Z3rnoConnectionError = Z3rnoConnectionError;
 exports.Z3rnoError = Z3rnoError;
+exports.Z3rnoTimeoutError = Z3rnoTimeoutError;
 //# sourceMappingURL=index.cjs.map
 //# sourceMappingURL=index.cjs.map