@z3rno/sdk 0.8.1 → 0.23.0

package/dist/index.cjs

@@ -1,1310 +0,0 @@
-'use strict';
-
-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";
-    this.statusCode = statusCode;
-  }
-};
-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";
-    this.retryAfter = retryAfter;
-  }
-};
-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",
-  "semantic",
-  "procedural"
-]);
-var RelationshipType = zod.z.enum([
-  "derived_from",
-  "contradicts",
-  "supports",
-  "supersedes",
-  "related_to",
-  "caused_by"
-]);
-var RetrievalStrategy = zod.z.enum([
-  "AUTO",
-  "VECTOR",
-  "LEXICAL",
-  "GRAPH",
-  "TRIPLET",
-  "TRACE",
-  "TEMPORAL",
-  "ASK",
-  "CYPHER"
-]);
-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),
-  /**
-   * Phase C retrieval strategy. `AUTO` (default) lets the server's
-   * LLM router pick the best fit. See {@link RetrievalStrategy}.
-   */
-  strategy: RetrievalStrategy.default("AUTO"),
-  /**
-   * Phase C cross-encoder re-ranking. When `true`, the server
-   * re-ranks the top results via a cross-encoder. Requires the
-   * `sentence-transformers` extra on the server.
-   */
-  rerank: 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({}),
-  /**
-   * Phase C per-source signals — e.g. `{ vector: 0.83, lexical: 0.61 }`.
-   * Optional so older servers (v0.7.x) keep parsing.
-   */
-  score_components: zod.z.record(zod.z.number()).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(),
-  /** Phase C: strategy that actually ran (after AUTO routing + re-rank). */
-  strategy_used: zod.z.string().default("VECTOR"),
-  /** Phase C: AUTO's candidate list (e.g. `["AUTO->GRAPH"]`). */
-  strategies_considered: zod.z.array(zod.z.string()).default([]),
-  /** Phase C: whether the cross-encoder re-rank ran. */
-  reranked: zod.z.boolean().default(false),
-  /** Phase C: end-to-end recall latency on the server (ms). */
-  elapsed_ms: zod.z.number().default(0)
-});
-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()
-}).transform((data) => ({
-  ...data,
-  /** Alias for `created_at`. Added in v0.8.1 for cross-SDK naming parity. */
-  timestamp: data.created_at
-}));
-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()
-}).transform((data) => ({
-  ...data,
-  /** Alias for `total`. Added in v0.8.1 for cross-SDK naming parity. */
-  total_count: data.total
-}));
-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()
-});
-var IngestJobResponse = zod.z.object({
-  job_id: zod.z.string(),
-  kind: zod.z.string(),
-  status: zod.z.string(),
-  dataset_id: zod.z.string().nullable().optional(),
-  enqueued_at: zod.z.string()
-});
-var IngestJobStatusResponse = zod.z.object({
-  job_id: zod.z.string(),
-  agent_id: zod.z.string(),
-  dataset_id: zod.z.string().nullable().optional(),
-  kind: zod.z.string(),
-  status: zod.z.string(),
-  source_uri: zod.z.string().nullable().optional(),
-  content_type: zod.z.string().nullable().optional(),
-  filename: zod.z.string().nullable().optional(),
-  file_size: zod.z.number().nullable().optional(),
-  memory_ids: zod.z.array(zod.z.string()).default([]),
-  memos_written: zod.z.number().default(0),
-  distill_job_id: zod.z.string().nullable().optional(),
-  codegraph_memos_written: zod.z.number().default(0),
-  codegraph_edges_written: zod.z.number().default(0),
-  error: zod.z.string().nullable().optional(),
-  warnings: zod.z.array(zod.z.record(zod.z.unknown())).default([]),
-  started_at: zod.z.string().nullable().optional(),
-  completed_at: zod.z.string().nullable().optional(),
-  created_at: zod.z.string().nullable().optional(),
-  updated_at: zod.z.string().nullable().optional()
-});
-var DistillJobResponse = zod.z.object({
-  job_id: zod.z.string(),
-  status: zod.z.string(),
-  memory_ids: zod.z.array(zod.z.string()),
-  enqueued_at: zod.z.string()
-});
-var DistillJobStatusResponse = zod.z.object({
-  job_id: zod.z.string(),
-  agent_id: zod.z.string(),
-  status: zod.z.string(),
-  model: zod.z.string(),
-  memory_ids: zod.z.array(zod.z.string()),
-  chunk_size: zod.z.number(),
-  chunk_overlap: zod.z.number(),
-  max_concurrency: zod.z.number(),
-  chunks_total: zod.z.number(),
-  chunks_failed: zod.z.number(),
-  entities_extracted: zod.z.number(),
-  relationships_extracted: zod.z.number(),
-  memos_written: zod.z.number(),
-  error: zod.z.string().nullable().optional(),
-  started_at: zod.z.string().nullable().optional(),
-  completed_at: zod.z.string().nullable().optional(),
-  created_at: zod.z.string().nullable().optional(),
-  updated_at: zod.z.string().nullable().optional()
-});
-var RefineJobResponse = zod.z.object({
-  job_id: zod.z.string(),
-  status: zod.z.string(),
-  dataset_id: zod.z.string().nullable().optional(),
-  enqueued_at: zod.z.string()
-});
-var RefineJobStatusResponse = zod.z.object({
-  job_id: zod.z.string(),
-  status: zod.z.string(),
-  dataset_id: zod.z.string().nullable().optional(),
-  trigger: zod.z.string(),
-  memos_scanned: zod.z.number().default(0),
-  memos_deduped: zod.z.number().default(0),
-  edges_reweighted: zod.z.number().default(0),
-  edges_pruned: zod.z.number().default(0),
-  feedback_drained: zod.z.number().default(0),
-  job_metadata: zod.z.record(zod.z.unknown()).default({}),
-  error: zod.z.string().nullable().optional(),
-  started_at: zod.z.string().nullable().optional(),
-  completed_at: zod.z.string().nullable().optional(),
-  created_at: zod.z.string().nullable().optional(),
-  updated_at: zod.z.string().nullable().optional()
-});
-var ConversationResponse = zod.z.object({
-  id: zod.z.string(),
-  agent_id: zod.z.string(),
-  user_id: zod.z.string().nullable().optional(),
-  title: zod.z.string().nullable().optional(),
-  summary_cadence: zod.z.number(),
-  turn_count: zod.z.number(),
-  last_summary_turn: zod.z.number(),
-  metadata: zod.z.record(zod.z.unknown()).default({}),
-  created_at: zod.z.string(),
-  updated_at: zod.z.string()
-});
-var TurnAddResponse = zod.z.object({
-  turn_index: zod.z.number(),
-  needs_summary: zod.z.boolean()
-});
-var TurnResponse = zod.z.object({
-  memory_id: zod.z.string(),
-  turn_index: zod.z.number(),
-  turn_role: zod.z.string(),
-  content: zod.z.string(),
-  created_at: zod.z.string()
-});
-var TurnListResponse = zod.z.object({
-  turns: zod.z.array(TurnResponse),
-  total: zod.z.number(),
-  conversation_id: zod.z.string()
-});
-var TenantBudgets = zod.z.object({
-  daily_tokens: zod.z.number(),
-  daily_llm_calls: zod.z.number(),
-  daily_embeddings: zod.z.number(),
-  monthly_tokens: zod.z.number(),
-  monthly_llm_calls: zod.z.number(),
-  monthly_embeddings: zod.z.number()
-});
-var TenantBudgetsView = zod.z.object({
-  overrides: TenantBudgets,
-  effective: TenantBudgets
-});
-
-// src/client.ts
-var Z3rnoClient = class {
-  baseUrl;
-  apiKey;
-  timeout;
-  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,
-      content: request.content,
-      memory_type: request.memoryType,
-      user_id: request.userId,
-      metadata: request.metadata,
-      relationships: request.relationships?.map((r) => ({
-        target_memory_id: r.targetMemoryId,
-        relationship_type: r.relationshipType,
-        weight: r.weight,
-        metadata: r.metadata
-      })),
-      ttl_seconds: request.ttlSeconds,
-      importance: request.importance
-    };
-    const resp = await this.request("POST", "/v1/memories", body);
-    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) {
-    let metadataFilter = params.metadataFilter;
-    if (params.filters !== void 0 && metadataFilter === void 0) {
-      if (typeof console !== "undefined" && console.warn) {
-        console.warn(
-          "Z3rnoClient.recall({filters}) is deprecated; use {metadataFilter} instead."
-        );
-      }
-      metadataFilter = params.filters;
-    }
-    const body = {
-      agent_id: params.agentId,
-      query: params.query,
-      memory_type: params.memoryType,
-      metadata_filter: metadataFilter,
-      top_k: params.topK ?? 10,
-      similarity_threshold: params.similarityThreshold ?? 0,
-      // Always send strategy + rerank. Older servers silently ignore
-      // unknown body fields.
-      strategy: params.strategy ?? "AUTO",
-      rerank: params.rerank ?? false
-    };
-    if (params.userId) {
-      body.user_id = params.userId;
-    }
-    if (params.conversationId) {
-      body.conversation_id = params.conversationId;
-    }
-    const resp = await this.request("POST", "/v1/memories/recall", body);
-    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,
-      memory_id: params.memoryId,
-      memory_ids: params.memoryIds,
-      hard_delete: params.hardDelete ?? false,
-      cascade: params.cascade ?? false,
-      reason: params.reason
-    };
-    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);
-    if (params?.page) searchParams.set("page", String(params.page));
-    if (params?.pageSize)
-      searchParams.set("page_size", String(params.pageSize));
-    const query = searchParams.toString();
-    const path = query ? `/v1/audit?${query}` : "/v1/audit";
-    const resp = await this.request("GET", path);
-    return AuditPageResponse.parse(resp);
-  }
-  // --- Forge: ingest / distill / refine -------------------------------
-  //
-  // Wrap the server's POST /v1/ingest, /v1/distill, /v1/refine plus the
-  // matching GET status endpoints. The server gates each verb behind an
-  // operator flag (INGEST_ENABLED / DISTILL_ENABLED / REFINE_ENABLED);
-  // when off, these methods throw NotFoundError.
-  async ingestText(params) {
-    const body = {
-      kind: "text",
-      agent_id: params.agentId,
-      text: params.text
-    };
-    if (params.datasetId) body.dataset_id = params.datasetId;
-    const resp = await this.request("POST", "/v1/ingest", body);
-    return IngestJobResponse.parse(resp);
-  }
-  async ingestUrl(params) {
-    const body = {
-      kind: "url",
-      agent_id: params.agentId,
-      url: params.url
-    };
-    if (params.datasetId) body.dataset_id = params.datasetId;
-    const resp = await this.request("POST", "/v1/ingest", body);
-    return IngestJobResponse.parse(resp);
-  }
-  async getIngestStatus(jobId) {
-    const resp = await this.request("GET", `/v1/ingest/${jobId}`);
-    return IngestJobStatusResponse.parse(resp);
-  }
-  async distill(params) {
-    const body = {
-      agent_id: params.agentId,
-      memory_ids: params.memoryIds,
-      include_summary: params.includeSummary ?? true
-    };
-    if (params.chunkSize !== void 0) body.chunk_size = params.chunkSize;
-    if (params.chunkOverlap !== void 0)
-      body.chunk_overlap = params.chunkOverlap;
-    if (params.maxConcurrency !== void 0)
-      body.max_concurrency = params.maxConcurrency;
-    if (params.summaryStyle !== void 0)
-      body.summary_style = params.summaryStyle;
-    const resp = await this.request("POST", "/v1/distill", body);
-    return DistillJobResponse.parse(resp);
-  }
-  async getDistillStatus(jobId) {
-    const resp = await this.request("GET", `/v1/distill/${jobId}`);
-    return DistillJobStatusResponse.parse(resp);
-  }
-  async refine(params) {
-    const body = {};
-    if (params?.datasetId) body.dataset_id = params.datasetId;
-    const resp = await this.request("POST", "/v1/refine", body);
-    return RefineJobResponse.parse(resp);
-  }
-  async getRefineStatus(jobId) {
-    const resp = await this.request("GET", `/v1/refine/${jobId}`);
-    return RefineJobStatusResponse.parse(resp);
-  }
-  // --- Conversations (Phase G slice 2) ---
-  /**
-   * Open a new conversation. Returns the conversation row including
-   * the assigned `id`, which subsequent `recall`s and `addTurn`s
-   * reference. The `summaryCadence` controls how often the server
-   * flags the conversation for summarization.
-   */
-  async createConversation(params) {
-    const body = {
-      agent_id: params.agentId,
-      summary_cadence: params.summaryCadence ?? 10
-    };
-    if (params.userId) body.user_id = params.userId;
-    if (params.title) body.title = params.title;
-    if (params.metadata) body.metadata = params.metadata;
-    const resp = await this.request("POST", "/v1/conversations", body);
-    return ConversationResponse.parse(resp);
-  }
-  async getConversation(conversationId) {
-    const resp = await this.request("GET", `/v1/conversations/${conversationId}`);
-    return ConversationResponse.parse(resp);
-  }
-  /**
-   * Stamp an existing Memo as the next turn of the conversation.
-   * Returns the assigned `turn_index` plus `needs_summary` — when
-   * `true`, the conversation has crossed its cadence threshold.
-   */
-  async addTurn(conversationId, params) {
-    const resp = await this.request(
-      "POST",
-      `/v1/conversations/${conversationId}/turns`,
-      { memory_id: params.memoryId, turn_role: params.turnRole }
-    );
-    return TurnAddResponse.parse(resp);
-  }
-  /**
-   * v0.19.3 — soft-delete a conversation. Existing turn Memos stay
-   * queryable through standard recall; the conversation itself stops
-   * accepting turns and its endpoints 404. Idempotent.
-   */
-  async deleteConversation(conversationId) {
-    await this.request("DELETE", `/v1/conversations/${conversationId}`);
-  }
-  async listTurns(conversationId, params) {
-    const query = new URLSearchParams();
-    if (params?.afterTurn !== void 0)
-      query.set("after_turn", String(params.afterTurn));
-    query.set("limit", String(params?.limit ?? 50));
-    const path = `/v1/conversations/${conversationId}/turns?${query.toString()}`;
-    const resp = await this.request("GET", path);
-    return TurnListResponse.parse(resp);
-  }
-  // --- Tenant budgets (v0.20.3) ---
-  /**
-   * Read this org's stored budget overrides + resolved effective caps.
-   * Auth: any admin/write/read member of the calling org.
-   */
-  async getMyBudgets() {
-    const resp = await this.request("GET", "/v1/tenants/me/budgets");
-    return TenantBudgetsView.parse(resp);
-  }
-  /**
-   * Replace this org's budget overrides. Zero / missing fields
-   * inherit the server default. Auth: admin/write only.
-   */
-  async setMyBudgets(budgets) {
-    const body = {
-      daily_tokens: budgets.daily_tokens ?? 0,
-      daily_llm_calls: budgets.daily_llm_calls ?? 0,
-      daily_embeddings: budgets.daily_embeddings ?? 0,
-      monthly_tokens: budgets.monthly_tokens ?? 0,
-      monthly_llm_calls: budgets.monthly_llm_calls ?? 0,
-      monthly_embeddings: budgets.monthly_embeddings ?? 0
-    };
-    const resp = await this.request("PUT", "/v1/tenants/me/budgets", body);
-    return TenantBudgetsView.parse(resp);
-  }
-  // --- HTTP layer ---
-  async request(method, path, body) {
-    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) {
-      if (resp.status === 204) {
-        return void 0;
-      }
-      return resp.json();
-    }
-    let detail = resp.statusText;
-    try {
-      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) {
-      case 401:
-        throw new AuthenticationError(`Authentication failed: ${detail}`);
-      case 404:
-        throw new NotFoundError(`Not found: ${detail}`);
-      case 429: {
-        const retryAfter = parseInt(
-          resp.headers.get("Retry-After") ?? "60",
-          10
-        );
-        throw new RateLimitError(`Rate limit exceeded: ${detail}`, retryAfter);
-      }
-      case 400:
-      case 422:
-        throw new ValidationError(detail, resp.status);
-      default:
-        if (resp.status >= 500) {
-          throw new ServerError(`Server error: ${detail}`, resp.status);
-        }
-        throw new Z3rnoError(
-          `Unexpected error (${resp.status}): ${detail}`,
-          resp.status
-        );
-    }
-  }
-};
-
-// src/integrations/vercel-ai.ts
-var Z3rnoVercelMemory = class {
-  client;
-  agentId;
-  conversationId;
-  topK;
-  constructor(options) {
-    this.client = options.client;
-    this.agentId = options.agentId;
-    this.conversationId = options.conversationId;
-    this.topK = options.topK ?? 50;
-  }
-  async messages() {
-    if (this.conversationId) {
-      const page = await this.client.listTurns(this.conversationId, {
-        limit: this.topK
-      });
-      return page.turns.map((t) => ({
-        role: this.normaliseRole(t.turn_role),
-        content: t.content
-      }));
-    }
-    const resp = await this.client.recall({
-      agentId: this.agentId,
-      topK: this.topK,
-      memoryType: "episodic"
-    });
-    const reversed = [...resp.results].reverse();
-    return reversed.map((r) => ({
-      role: this.normaliseRole(
-        (r.metadata ?? {})["role"]
-      ),
-      content: r.content
-    }));
-  }
-  async appendUserMessage(content) {
-    await this.append(content, "user");
-  }
-  async appendAssistantMessage(content) {
-    await this.append(content, "assistant");
-  }
-  async appendToolMessage(content) {
-    await this.append(content, "tool");
-  }
-  async append(content, role) {
-    const memory = await this.client.store({
-      agentId: this.agentId,
-      content,
-      memoryType: "episodic",
-      metadata: { role },
-      relationships: []
-    });
-    if (this.conversationId) {
-      await this.client.addTurn(this.conversationId, {
-        memoryId: memory.id,
-        turnRole: role
-      });
-    }
-  }
-  normaliseRole(raw) {
-    switch (raw) {
-      case "assistant":
-      case "ai":
-        return "assistant";
-      case "system":
-        return "system";
-      case "tool":
-        return "tool";
-      default:
-        return "user";
-    }
-  }
-};
-
-// src/integrations/mastra.ts
-var Z3rnoMastraMemory = class {
-  client;
-  agentId;
-  conversationId;
-  topK;
-  constructor(options) {
-    this.client = options.client;
-    this.agentId = options.agentId;
-    this.conversationId = options.conversationId;
-    this.topK = options.topK ?? 50;
-  }
-  /** Mastra contract: return ordered prior messages for the thread. */
-  async getMessages(_args) {
-    const limit = _args?.limit ?? this.topK;
-    if (this.conversationId) {
-      const page = await this.client.listTurns(this.conversationId, { limit });
-      return page.turns.map((t) => ({
-        role: this.normaliseRole(t.turn_role),
-        content: t.content,
-        threadId: this.conversationId
-      }));
-    }
-    const resp = await this.client.recall({
-      agentId: this.agentId,
-      topK: limit,
-      memoryType: "episodic"
-    });
-    const reversed = [...resp.results].reverse();
-    return reversed.map((r) => ({
-      role: this.normaliseRole(
-        (r.metadata ?? {})["role"]
-      ),
-      content: r.content
-    }));
-  }
-  /** Mastra contract: persist one message. */
-  async addMessage(message) {
-    const memory = await this.client.store({
-      agentId: this.agentId,
-      content: message.content,
-      memoryType: "episodic",
-      metadata: { role: message.role },
-      relationships: []
-    });
-    if (this.conversationId) {
-      await this.client.addTurn(this.conversationId, {
-        memoryId: memory.id,
-        turnRole: message.role
-      });
-    }
-  }
-  /**
-   * Mastra `clear()` — deliberate no-op. Z3rno keeps the source of
-   * truth and recall is already scoped per conversation; flushing
-   * the thread would risk losing audit-relevant history.
-   */
-  async clear() {
-    return;
-  }
-  normaliseRole(raw) {
-    switch (raw) {
-      case "assistant":
-      case "ai":
-        return "assistant";
-      case "system":
-        return "system";
-      case "tool":
-        return "tool";
-      default:
-        return "user";
-    }
-  }
-};
-
-exports.AuditEntry = AuditEntry;
-exports.AuditPageResponse = AuditPageResponse;
-exports.AuthenticationError = AuthenticationError;
-exports.BatchStoreResponse = BatchStoreResponse;
-exports.ConversationResponse = ConversationResponse;
-exports.DistillJobResponse = DistillJobResponse;
-exports.DistillJobStatusResponse = DistillJobStatusResponse;
-exports.EndSessionResponse = EndSessionResponse;
-exports.ForgetResponse = ForgetResponse;
-exports.IngestJobResponse = IngestJobResponse;
-exports.IngestJobStatusResponse = IngestJobStatusResponse;
-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.RefineJobResponse = RefineJobResponse;
-exports.RefineJobStatusResponse = RefineJobStatusResponse;
-exports.RelationshipType = RelationshipType;
-exports.RetrievalStrategy = RetrievalStrategy;
-exports.ServerError = ServerError;
-exports.SessionResponse = SessionResponse;
-exports.TenantBudgets = TenantBudgets;
-exports.TenantBudgetsView = TenantBudgetsView;
-exports.TurnAddResponse = TurnAddResponse;
-exports.TurnListResponse = TurnListResponse;
-exports.TurnResponse = TurnResponse;
-exports.ValidationError = ValidationError;
-exports.Z3rnoClient = Z3rnoClient;
-exports.Z3rnoConnectionError = Z3rnoConnectionError;
-exports.Z3rnoError = Z3rnoError;
-exports.Z3rnoMastraMemory = Z3rnoMastraMemory;
-exports.Z3rnoTimeoutError = Z3rnoTimeoutError;
-exports.Z3rnoVercelMemory = Z3rnoVercelMemory;
-//# sourceMappingURL=index.cjs.map
-//# sourceMappingURL=index.cjs.map