hebbrix 2.2.1 → 2.3.0

package/dist/index.js

@@ -25,7 +25,9 @@ __export(index_exports, {
   CollectionsResource: () => CollectionsResource,
   ConsolidationResource: () => ConsolidationResource,
   CorrectionsResource: () => CorrectionsResource,
+  EntitlementError: () => EntitlementError,
   HebbrixError: () => HebbrixError,
+  IndexingTimeoutError: () => IndexingTimeoutError,
   MemoriesResource: () => MemoriesResource,
   MemoryClient: () => MemoryClient,
   MemoryJobsResource: () => MemoryJobsResource,
@@ -40,7 +42,6 @@ __export(index_exports, {
   TemporalResource: () => TemporalResource,
   ValidationError: () => ValidationError,
   WorkingMemoryResource: () => WorkingMemoryResource,
-  WorldModelResource: () => WorldModelResource,
   enforceSearchSafety: () => enforceSearchSafety
 });
 module.exports = __toCommonJS(index_exports);
@@ -99,6 +100,72 @@ function enforceSearchSafety(response, rowsKey = "results") {
   return data;
 }
 
+// src/errors.ts
+var HebbrixError = class _HebbrixError extends Error {
+  constructor(message, statusCode, options = {}) {
+    super(message);
+    this.name = "HebbrixError";
+    this.statusCode = statusCode;
+    this.code = options.code;
+    this.requestId = options.requestId;
+    this.details = options.details;
+    Object.setPrototypeOf(this, _HebbrixError.prototype);
+  }
+};
+var EntitlementError = class _EntitlementError extends HebbrixError {
+  constructor(message, statusCode, options = {}) {
+    super(message, statusCode, options);
+    this.name = "EntitlementError";
+    Object.setPrototypeOf(this, _EntitlementError.prototype);
+  }
+};
+var IndexingTimeoutError = class _IndexingTimeoutError extends Error {
+  constructor(message, receipt) {
+    super(message);
+    this.name = "IndexingTimeoutError";
+    this.receipt = { ...receipt };
+    this.memoryIds = [...receipt.memory_ids || []];
+    this.statusUrl = receipt.status_url;
+    Object.setPrototypeOf(this, _IndexingTimeoutError.prototype);
+  }
+};
+var AuthenticationError = class _AuthenticationError extends HebbrixError {
+  constructor(message = "Authentication failed", options = {}) {
+    super(message, 401, options);
+    this.name = "AuthenticationError";
+    Object.setPrototypeOf(this, _AuthenticationError.prototype);
+  }
+};
+var ValidationError = class _ValidationError extends HebbrixError {
+  constructor(message, errors, options = {}) {
+    super(message, 422, options);
+    this.name = "ValidationError";
+    this.errors = errors;
+    Object.setPrototypeOf(this, _ValidationError.prototype);
+  }
+};
+var NotFoundError = class _NotFoundError extends HebbrixError {
+  constructor(message = "Resource not found", options = {}) {
+    super(message, 404, options);
+    this.name = "NotFoundError";
+    Object.setPrototypeOf(this, _NotFoundError.prototype);
+  }
+};
+var RateLimitError = class _RateLimitError extends HebbrixError {
+  constructor(message = "Rate limit exceeded", options = {}) {
+    super(message, 429, options);
+    this.name = "RateLimitError";
+    Object.setPrototypeOf(this, _RateLimitError.prototype);
+  }
+};
+var ServerError = class _ServerError extends HebbrixError {
+  constructor(message = "Internal server error", options = {}) {
+    super(message, 500, options);
+    this.name = "ServerError";
+    Object.setPrototypeOf(this, _ServerError.prototype);
+  }
+};
+
 // src/resources.ts
 var BaseResource = class {
   constructor(client) {
@@ -195,9 +262,9 @@ var MemoriesResource = class extends BaseResource {
   }
   /**
    * Create up to 100 memories with one unambiguous readiness contract.
-   * `wait_for_index=true` resolves only for a fully searchable batch; a server
-   * deadline or indexing failure rejects the request instead of returning a
-   * successful processing receipt.
+   * `wait_for_index=true` resolves only for a fully searchable batch. A durable
+   * server-side 202 is polled to the caller's deadline; expiry raises a typed
+   * `IndexingTimeoutError` carrying the original durable receipt.
    */
   async createBatch(params) {
     if (!params.memories?.length || params.memories.length > 100) {
@@ -206,7 +273,13 @@ var MemoriesResource = class extends BaseResource {
     if (params.memories.some((item) => !item.content?.trim())) {
       throw new TypeError("every batch memory must contain non-empty content");
     }
-    const { idempotency_key, signal, ...body } = params;
+    const {
+      idempotency_key,
+      signal,
+      index_timeout_ms,
+      index_poll_interval_ms,
+      ...body
+    } = params;
     const receipt = await this.client.request(
       "POST",
       "/v1/memories/batch",
@@ -216,10 +289,12 @@ var MemoriesResource = class extends BaseResource {
         signal
       }
     );
-    if (params.wait_for_index && !(receipt.searchable === true && receipt.processing_status === "completed")) {
-      throw new Error(
-        "wait_for_index batch response was not fully searchable; retry with the same Idempotency-Key"
-      );
+    if (params.wait_for_index && !receipt.searchable) {
+      return this.waitForBatchSearchable(receipt, {
+        timeoutMs: index_timeout_ms,
+        pollIntervalMs: index_poll_interval_ms,
+        signal
+      });
     }
     return receipt;
   }
@@ -260,7 +335,10 @@ var MemoriesResource = class extends BaseResource {
         };
       }
       if (Date.now() >= deadline) {
-        throw new Error(`batch was not searchable within ${timeoutMs}ms`);
+        throw new IndexingTimeoutError(
+          `batch was not searchable within ${timeoutMs}ms; the write is durable`,
+          receipt
+        );
       }
       await new Promise((resolve) => setTimeout(resolve, pollIntervalMs));
     }
@@ -454,8 +532,7 @@ var RLResource = class extends BaseResource {
    * Train the Memory Manager agent using RL
    */
   async trainMemoryManager(params) {
-    return this.client.post("/rl/train/memory-manager", {
-      collection_id: params.collection_id,
+    return this.client.post("/v1/rl/train/memory-manager", {
       num_episodes: params.num_episodes || 100,
       ...params
     });
@@ -464,8 +541,7 @@ var RLResource = class extends BaseResource {
    * Train the Answer Agent using RL
    */
   async trainAnswerAgent(params) {
-    return this.client.post("/rl/train/answer-agent", {
-      collection_id: params.collection_id,
+    return this.client.post("/v1/rl/train/answer-agent", {
       num_episodes: params.num_episodes || 100,
       ...params
     });
@@ -474,13 +550,13 @@ var RLResource = class extends BaseResource {
    * Get RL training metrics
    */
   async getMetrics() {
-    return this.client.get("/rl/metrics");
+    return this.client.get("/v1/rl/metrics");
   }
   /**
    * Evaluate a trained RL agent
    */
   async evaluate(agentType, collectionId) {
-    return this.client.post("/rl/evaluate", {
+    return this.client.post("/v1/rl/evaluate", {
       agent_type: agentType,
       collection_id: collectionId
     });
@@ -566,12 +642,15 @@ var TemporalResource = class extends BaseResource {
    * Add a temporal fact to the knowledge graph
    */
   async addFact(params) {
-    return this.client.post("/temporal/facts", {
+    return this.client.post("/v1/temporal/facts", {
       subject: params.subject,
+      subject_type: params.subject_type || "ENTITY",
       predicate: params.predicate,
       object: params.object,
+      object_type: params.object_type || "ENTITY",
       valid_from: params.valid_from,
       valid_until: params.valid_until,
+      observed_at: params.observed_at,
       confidence: params.confidence || 1,
       source_memory_id: params.source_memory_id,
       metadata: params.metadata || {}
@@ -581,33 +660,79 @@ var TemporalResource = class extends BaseResource {
    * Query temporal facts
    */
   async queryFacts(params) {
-    return this.client.get("/temporal/facts", {
-      subject: params?.subject,
-      predicate: params?.predicate,
-      object: params?.object,
-      at_time: params?.at_time
+    if (!params.subject) {
+      throw new TypeError("subject is required by the temporal query contract");
+    }
+    let rows;
+    if (params.at_time) {
+      const response = await this.queryAtTime({
+        subject: params.subject,
+        predicate: params.predicate,
+        timestamp: params.at_time
+      });
+      rows = response.facts || [];
+    } else if (params.predicate) {
+      const response = await this.history(
+        params.subject,
+        params.predicate
+      );
+      rows = response.history || [];
+    } else {
+      throw new TypeError("predicate or at_time is required");
+    }
+    return params.object === void 0 ? rows : rows.filter((row) => row.object === params.object);
+  }
+  async queryAtTime(params) {
+    return this.client.post("/v1/temporal/facts/query-at-time", params);
+  }
+  async history(subject, predicate, limit = 50) {
+    return this.client.get("/v1/temporal/facts/history", {
+      subject,
+      predicate,
+      limit
+    });
+  }
+  async conflicts(subject, predicate) {
+    return this.client.get("/v1/temporal/facts/conflicts", {
+      subject,
+      predicate
+    });
+  }
+  async invalidate(subject, predicate, object) {
+    return this.client.post("/v1/temporal/facts/invalidate", {
+      subject,
+      predicate,
+      object
     });
   }
   /**
    * Query knowledge state at a specific point in time
    */
   async pointInTime(timestamp, entity) {
-    return this.client.post("/temporal/point-in-time", {
+    if (!entity) {
+      throw new TypeError("entity is required and maps to the canonical subject");
+    }
+    return this.queryAtTime({
       timestamp,
-      entity
+      subject: entity
     });
   }
   /** Permanently delete a tenant-scoped temporal fact by stable ID. */
   async deleteFact(factId) {
-    return this.client.delete(`/temporal/facts/${factId}`);
+    return this.client.delete(`/v1/temporal/facts/${factId}`);
   }
 };
 var WorkingMemoryResource = class extends BaseResource {
+  constructor(client) {
+    super(client);
+    this.sessionId = `sdk-${Date.now().toString(36)}-${Math.random().toString(36).slice(2)}`;
+  }
   /**
    * Add item to working memory buffer
    */
   async add(params) {
-    return this.client.post("/working-memory", {
+    return this.client.post("/v1/working-memory/add", {
+      session_id: params.session_id || this.sessionId,
       role: params.role,
       content: params.content,
       metadata: params.metadata || {}
@@ -616,48 +741,40 @@ var WorkingMemoryResource = class extends BaseResource {
   /**
    * Get current working memory context
    */
-  async getContext() {
-    return this.client.get("/working-memory/context");
+  async getContext(sessionId = this.sessionId, includeCompressed = false) {
+    return this.client.get(`/v1/working-memory/context/${sessionId}`, {
+      include_compressed: includeCompressed
+    });
   }
   /**
    * Compress working memory buffer
    */
-  async compress() {
-    return this.client.post("/working-memory/compress");
+  async compress(sessionId = this.sessionId) {
+    return this.client.post(`/v1/working-memory/compress/${sessionId}`);
   }
   /**
    * Clear working memory buffer
    */
-  async clear() {
-    return this.client.delete("/working-memory");
+  async clear(sessionId = this.sessionId) {
+    return this.client.delete(`/v1/working-memory/clear/${sessionId}`);
   }
 };
 var ConsolidationResource = class extends BaseResource {
   /**
    * Trigger memory consolidation
    */
-  async consolidate(collectionId, threshold = 100) {
-    return this.client.post("/consolidation/consolidate", {
+  async consolidate(collectionId, lookbackDays = 7, utilityThreshold = 0.3) {
+    return this.client.post("/v1/consolidation/consolidate", {
       collection_id: collectionId,
-      threshold
+      lookback_days: lookbackDays,
+      utility_threshold: utilityThreshold
     });
   }
   /**
    * Get consolidation statistics
    */
   async getStats(collectionId) {
-    return this.client.get("/consolidation/stats", {
-      collection_id: collectionId
-    });
-  }
-  /**
-   * Archive old memories
-   */
-  async archive(collectionId, beforeDate) {
-    return this.client.post("/consolidation/archive", {
-      collection_id: collectionId,
-      before_date: beforeDate
-    });
+    return this.client.get(`/v1/consolidation/stats/${collectionId}`);
   }
 };
 var MemoryToolsResource = class extends BaseResource {
@@ -665,100 +782,38 @@ var MemoryToolsResource = class extends BaseResource {
    * Replace memory content
    */
   async replace(params) {
-    return this.client.post("/memory-tools/replace", {
+    return this.client.post("/v1/memory-tools/replace", {
       memory_id: params.memory_id,
+      old_content: params.old_content,
       new_content: params.new_content,
-      reason: params.reason
+      collection_id: params.collection_id
     });
   }
   /**
    * Insert new memory at position
    */
   async insert(params) {
-    return this.client.post("/memory-tools/insert", {
+    const metadata = { ...params.metadata || {} };
+    if (params.position !== void 0) metadata.requested_position = params.position;
+    if (params.reason !== void 0) metadata.reason = params.reason;
+    return this.client.post("/v1/memory-tools/insert", {
       collection_id: params.collection_id,
       content: params.content,
-      position: params.position,
-      reason: params.reason
+      importance: params.importance ?? 0.5,
+      metadata
     });
   }
   /**
    * Re-evaluate memory in light of new information
    */
-  async rethink(memoryId, query) {
-    return this.client.post("/memory-tools/rethink", {
+  async rethink(memoryId, collectionId) {
+    return this.client.post("/v1/memory-tools/rethink", {
       memory_id: memoryId,
-      query
-    });
-  }
-};
-var WorldModelResource = class extends BaseResource {
-  /**
-   * Simulate retrieval without actually retrieving
-   */
-  async imagineRetrieval(query, collectionId) {
-    return this.client.post("/world-model/imagine-retrieval", {
-      query,
-      collection_id: collectionId
-    });
-  }
-  /**
-   * Plan memory operations to achieve goal
-   */
-  async plan(goal, collectionId) {
-    return this.client.post("/world-model/plan", {
-      goal,
       collection_id: collectionId
     });
   }
 };
 
-// src/errors.ts
-var HebbrixError = class _HebbrixError extends Error {
-  constructor(message, statusCode) {
-    super(message);
-    this.name = "HebbrixError";
-    this.statusCode = statusCode;
-    Object.setPrototypeOf(this, _HebbrixError.prototype);
-  }
-};
-var AuthenticationError = class _AuthenticationError extends HebbrixError {
-  constructor(message = "Authentication failed") {
-    super(message, 401);
-    this.name = "AuthenticationError";
-    Object.setPrototypeOf(this, _AuthenticationError.prototype);
-  }
-};
-var ValidationError = class _ValidationError extends HebbrixError {
-  constructor(message, errors) {
-    super(message, 422);
-    this.name = "ValidationError";
-    this.errors = errors;
-    Object.setPrototypeOf(this, _ValidationError.prototype);
-  }
-};
-var NotFoundError = class _NotFoundError extends HebbrixError {
-  constructor(message = "Resource not found") {
-    super(message, 404);
-    this.name = "NotFoundError";
-    Object.setPrototypeOf(this, _NotFoundError.prototype);
-  }
-};
-var RateLimitError = class _RateLimitError extends HebbrixError {
-  constructor(message = "Rate limit exceeded") {
-    super(message, 429);
-    this.name = "RateLimitError";
-    Object.setPrototypeOf(this, _RateLimitError.prototype);
-  }
-};
-var ServerError = class _ServerError extends HebbrixError {
-  constructor(message = "Internal server error") {
-    super(message, 500);
-    this.name = "ServerError";
-    Object.setPrototypeOf(this, _ServerError.prototype);
-  }
-};
-
 // src/client.ts
 var MemoryClient = class {
   constructor(config = {}) {
@@ -778,13 +833,12 @@ var MemoryClient = class {
     this.workingMemory = new WorkingMemoryResource(this);
     this.consolidation = new ConsolidationResource(this);
     this.memoryTools = new MemoryToolsResource(this);
-    this.worldModel = new WorldModelResource(this);
     this.proofloop = new ProofLoopResource(this);
   }
   getHeaders() {
     const headers = {
       "Content-Type": "application/json",
-      "User-Agent": "hebbrix-typescript/2.2.1"
+      "User-Agent": "hebbrix-typescript/2.3.0"
     };
     if (this.apiKey) {
       headers["Authorization"] = `Bearer ${this.apiKey}`;
@@ -793,21 +847,31 @@ var MemoryClient = class {
   }
   handleError(response, data) {
     const statusCode = response.status;
-    const detail = data?.detail;
-    const message = data?.error?.message || (typeof detail === "string" ? detail : detail?.message) || response.statusText;
+    const envelope = data?.error || data?.detail || {};
+    const nested = envelope?.message;
+    const details = nested && typeof nested === "object" ? nested : envelope;
+    const message = details?.message || (typeof nested === "string" ? nested : void 0) || response.statusText;
+    const code = details?.code || envelope?.code;
+    const requestId = details?.request_id || envelope?.request_id || response.headers.get("X-Request-ID") || void 0;
     if (statusCode === 401) {
-      throw new AuthenticationError(message);
+      throw new AuthenticationError(message, { code, requestId, details });
     } else if (statusCode === 404) {
-      throw new NotFoundError(message);
+      throw new NotFoundError(message, { code, requestId, details });
     } else if (statusCode === 422) {
       const errors = data?.error?.details || [];
-      throw new ValidationError(message, errors);
+      throw new ValidationError(message, errors, { code, requestId, details });
     } else if (statusCode === 429) {
-      throw new RateLimitError(message);
+      throw new RateLimitError(message, { code, requestId, details });
     } else if (statusCode >= 500) {
-      throw new ServerError(message);
+      throw new ServerError(message, { code, requestId, details });
+    } else if ((statusCode === 402 || statusCode === 403) && (String(code || "").includes("ENTITLEMENT") || ["feature_not_available", "tier_upgrade_required"].includes(details?.error))) {
+      throw new EntitlementError(message, statusCode, {
+        code,
+        requestId,
+        details
+      });
     } else {
-      throw new HebbrixError(message, statusCode);
+      throw new HebbrixError(message, statusCode, { code, requestId, details });
     }
   }
   async request(method, path, options = {}) {
@@ -889,7 +953,9 @@ var MemoryClient = class {
   CollectionsResource,
   ConsolidationResource,
   CorrectionsResource,
+  EntitlementError,
   HebbrixError,
+  IndexingTimeoutError,
   MemoriesResource,
   MemoryClient,
   MemoryJobsResource,
@@ -904,6 +970,5 @@ var MemoryClient = class {
   TemporalResource,
   ValidationError,
   WorkingMemoryResource,
-  WorldModelResource,
   enforceSearchSafety
 });