@dakera-ai/dakera 0.6.1 → 0.7.0

package/dist/index.d.mts

@@ -226,16 +226,33 @@ interface BatchQuerySpec {
     /** Staleness configuration for bounded staleness reads */
     stalenessConfig?: StalenessConfig;
 }
+/** Exponential backoff configuration for retries */
+interface RetryConfig {
+    /** Maximum number of retry attempts (default: 3) */
+    maxRetries?: number;
+    /** Base delay in milliseconds before the first retry (default: 100) */
+    baseDelay?: number;
+    /** Maximum delay in milliseconds between retries (default: 60000) */
+    maxDelay?: number;
+    /** Whether to add random jitter to backoff delay (default: true) */
+    jitter?: boolean;
+}
 /** Client configuration options */
 interface ClientOptions {
     /** Base URL of the Dakera server */
     baseUrl: string;
     /** API key for authentication */
     apiKey?: string;
-    /** Request timeout in milliseconds */
+    /** Per-request timeout in milliseconds (default: 30000) */
     timeout?: number;
-    /** Maximum number of retries */
+    /** Connection establishment timeout in milliseconds. Defaults to `timeout`. */
+    connectTimeout?: number;
+    /** Maximum number of retries for transient errors (default: 3).
+     *  Ignored when `retryBackoff` is provided. */
     maxRetries?: number;
+    /** Fine-grained retry and backoff configuration.
+     *  When provided, `maxRetries` is ignored in favour of `retryBackoff.maxRetries`. */
+    retryBackoff?: RetryConfig;
     /** Additional headers */
     headers?: Record<string, string>;
 }
@@ -966,6 +983,8 @@ interface CrossAgentNetworkResponse {
     nodes: AgentNetworkNode[];
     edges: AgentNetworkEdge[];
     stats: AgentNetworkStats;
+    /** Total number of memory nodes in the network (added in server v0.6.2). */
+    node_count: number;
 }
 /** Request body for POST /v1/knowledge/network/cross-agent */
 interface CrossAgentNetworkRequest {
@@ -1044,6 +1063,74 @@ interface KeyUsage {
     last_used?: string;
     requests_by_endpoint?: Record<string, number>;
 }
+/**
+ * Rate-limit and quota headers present on every API response (OPS-1).
+ *
+ * Fields are `undefined` when the server does not include the header
+ * (e.g. non-namespaced endpoints where quota does not apply).
+ */
+interface RateLimitHeaders {
+    /** `X-RateLimit-Limit` — max requests allowed in the current window. */
+    limit?: number;
+    /** `X-RateLimit-Remaining` — requests left in the current window. */
+    remaining?: number;
+    /** `X-RateLimit-Reset` — Unix timestamp (seconds) when the window resets. */
+    reset?: number;
+    /** `X-Quota-Used` — namespace vectors / storage consumed. */
+    quotaUsed?: number;
+    /** `X-Quota-Limit` — namespace quota ceiling. */
+    quotaLimit?: number;
+}
+/**
+ * Filter predicates for batch memory operations (CE-2).
+ *
+ * All fields are optional.  For `batchForget` at least one must be set
+ * (server-side safety guard).
+ */
+interface BatchMemoryFilter {
+    /** Restrict to memories that carry **all** listed tags. */
+    tags?: string[];
+    /** Minimum importance (inclusive). */
+    min_importance?: number;
+    /** Maximum importance (inclusive). */
+    max_importance?: number;
+    /** Only memories created at or after this Unix timestamp (seconds). */
+    created_after?: number;
+    /** Only memories created before or at this Unix timestamp (seconds). */
+    created_before?: number;
+    /** Restrict to a specific memory type. */
+    memory_type?: MemoryType;
+    /** Restrict to memories from a specific session. */
+    session_id?: string;
+}
+/** Request body for `POST /v1/memories/recall/batch`. */
+interface BatchRecallRequest {
+    /** Agent whose memory namespace to search. */
+    agent_id: string;
+    /** Filter predicates to apply.  An empty object returns all memories up to `limit`. */
+    filter?: BatchMemoryFilter;
+    /** Maximum number of results to return (default: 100). */
+    limit?: number;
+}
+/** Response from `POST /v1/memories/recall/batch`. */
+interface BatchRecallResponse {
+    memories: Memory[];
+    /** Total memories in the agent namespace. */
+    total: number;
+    /** Number of memories that passed the filter. */
+    filtered: number;
+}
+/** Request body for `DELETE /v1/memories/forget/batch`. */
+interface BatchForgetRequest {
+    /** Agent whose memory namespace to purge from. */
+    agent_id: string;
+    /** Filter predicates — **at least one must be set** (server safety guard). */
+    filter: BatchMemoryFilter;
+}
+/** Response from `DELETE /v1/memories/forget/batch`. */
+interface BatchForgetResponse {
+    deleted_count: number;
+}
 
 /**
  * Dakera Client
@@ -1072,17 +1159,28 @@ declare class DakeraClient {
     private readonly baseUrl;
     private readonly apiKey?;
     private readonly timeout;
-    private readonly maxRetries;
+    private readonly connectTimeout;
+    private readonly retryConfig;
     private readonly headers;
+    /** OPS-1: rate-limit headers from the most recent API response. */
+    private _lastRateLimitHeaders;
     constructor(options: ClientOptions | string);
     /**
-     * Make an HTTP request with retry logic.
+     * Rate-limit headers from the most recent API response (OPS-1).
+     *
+     * Returns `null` until the first successful request has been made.
+     */
+    get lastRateLimitHeaders(): RateLimitHeaders | null;
+    private computeBackoff;
+    /**
+     * Make an HTTP request with retry logic and exponential backoff.
      */
     private request;
     /**
      * Handle HTTP response and throw appropriate errors.
      */
     private handleResponse;
+    private _parseHeaderInt;
     private sleep;
     /**
      * Upsert vectors into a namespace.
@@ -1555,6 +1653,38 @@ declare class DakeraClient {
     forget(agentId: string, memoryId: string): Promise<{
         status: string;
     }>;
+    /**
+     * Bulk-recall memories using filter predicates (CE-2).
+     *
+     * Uses `POST /v1/memories/recall/batch` — no embedding required.
+     *
+     * @example
+     * ```typescript
+     * const resp = await client.batchRecall({
+     *   agent_id: 'agent-1',
+     *   filter: { tags: ['preferences'], min_importance: 0.7 },
+     *   limit: 50,
+     * });
+     * console.log(`Found ${resp.filtered} memories`);
+     * ```
+     */
+    batchRecall(request: BatchRecallRequest): Promise<BatchRecallResponse>;
+    /**
+     * Bulk-delete memories using filter predicates (CE-2).
+     *
+     * Uses `DELETE /v1/memories/forget/batch`.  At least one filter predicate
+     * must be set (server safety guard).
+     *
+     * @example
+     * ```typescript
+     * const resp = await client.batchForget({
+     *   agent_id: 'agent-1',
+     *   filter: { created_before: Math.floor(Date.now() / 1000) - 86400 },
+     * });
+     * console.log(`Deleted ${resp.deleted_count} memories`);
+     * ```
+     */
+    batchForget(request: BatchForgetRequest): Promise<BatchForgetResponse>;
     /** Search memories for an agent */
     searchMemories(agentId: string, query: string, options?: {
         top_k?: number;
@@ -1744,6 +1874,16 @@ declare class DakeraClient {
      * ```
      */
     streamMemoryEvents(): AsyncGenerator<MemoryEvent>;
+    /**
+     * Return a URL with `?api_key=<key>` appended for use with browser-native
+     * `EventSource`, which cannot send custom request headers.
+     *
+     * @example
+     * ```ts
+     * const src = new EventSource(client.sseUrl('/v1/namespaces/my-ns/events'));
+     * ```
+     */
+    sseUrl(path: string): string;
     /** Low-level SSE streaming helper — parses the SSE wire format. */
     private _streamSse;
     /** Parse a single SSE event block into a {@link DakeraEvent}. */
@@ -1822,4 +1962,4 @@ declare class TimeoutError extends DakeraError {
     constructor(message: string);
 }
 
-export { type AccessPatternHint, type AgentId, type AgentNetworkEdge, type AgentNetworkInfo, type AgentNetworkNode, type AgentNetworkStats, type AgentStats, type AgentSummary, type AggregationGroup, type AggregationRequest, type AggregationResponse, type AnalyticsOptions, type AnalyticsOverview, type ApiKey, AuthenticationError, AuthorizationError, type BackupInfo, type BatchQuerySpec, type BatchTextQueryOptions, type BatchTextQueryResponse, type Branded, type CacheStats, type ClientOptions, type ClusterNode, type ClusterStatus, type ColumnUpsertRequest, type ConfigureNamespaceRequest, type ConfigureNamespaceResponse, ConnectionError, type ConsolidateRequest, type ConsolidateResponse, type CreateKeyRequest, type CrossAgentNetworkRequest, type CrossAgentNetworkResponse, DakeraClient, DakeraError, type DakeraEvent, type DeduplicateRequest, type DeduplicateResponse, type DeleteOptions, type DeleteResponse, type DistanceMetric, type Document, type DocumentInput, type EmbeddingModel, ErrorCode, type ExportRequest, type ExportResponse, type ExportedVector, type FilterExpression, type FilterOperators, type FullKnowledgeGraphRequest, type FullTextSearchResult, type HealthResponse, type HybridSearchResult, type IndexStats, type JobProgressEvent, type KeyUsage, type KnowledgeEdge, type KnowledgeGraphRequest, type KnowledgeGraphResponse, type KnowledgeNode, type LatencyAnalytics, type ListSessionsOptions, type Memory, type MemoryEvent, type MemoryFeedbackRequest, type MemoryFeedbackResponse, type MemoryId, type MemoryType, type MultiVectorSearchRequest, type MultiVectorSearchResponse, type MultiVectorSearchResult, type NamespaceCreatedEvent, type NamespaceDeletedEvent, type NamespaceInfo, NotFoundError, type OpStatus, type OperationProgressEvent, type QueryExplainRequest, type QueryExplainResponse, type QueryOptions, type QueryResult, RateLimitError, type ReadConsistency, type RecallRequest, type RecalledMemory, type SearchResult, ServerError, type Session, type SessionId, type SlowQuery, type StalenessConfig, type StartSessionRequest, type StorageAnalytics, type StoreMemoryRequest, type StoreMemoryResponse, type StreamLaggedEvent, type SummarizeRequest, type SummarizeResponse, type TextDocument, type TextQueryOptions, type TextQueryResponse, type TextSearchResult, type TextUpsertOptions, type TextUpsertResponse, type ThroughputAnalytics, TimeoutError, type TtlConfig, type UnifiedQueryRequest, type UnifiedQueryResponse, type UnifiedSearchResult, type UpdateImportanceRequest, type UpdateMemoryRequest, type UpsertOptions, type UpsertResponse, ValidationError, type Vector, type VectorId, type VectorInput, type VectorMutationOp, type VectorsMutatedEvent, type WarmCacheRequest, type WarmCacheResponse, type WarmingPriority, type WarmingTargetTier, agentId, memoryId, sessionId, vectorId };
+export { type AccessPatternHint, type AgentId, type AgentNetworkEdge, type AgentNetworkInfo, type AgentNetworkNode, type AgentNetworkStats, type AgentStats, type AgentSummary, type AggregationGroup, type AggregationRequest, type AggregationResponse, type AnalyticsOptions, type AnalyticsOverview, type ApiKey, AuthenticationError, AuthorizationError, type BackupInfo, type BatchForgetRequest, type BatchForgetResponse, type BatchMemoryFilter, type BatchQuerySpec, type BatchRecallRequest, type BatchRecallResponse, type BatchTextQueryOptions, type BatchTextQueryResponse, type Branded, type CacheStats, type ClientOptions, type ClusterNode, type ClusterStatus, type ColumnUpsertRequest, type ConfigureNamespaceRequest, type ConfigureNamespaceResponse, ConnectionError, type ConsolidateRequest, type ConsolidateResponse, type CreateKeyRequest, type CrossAgentNetworkRequest, type CrossAgentNetworkResponse, DakeraClient, DakeraError, type DakeraEvent, type DeduplicateRequest, type DeduplicateResponse, type DeleteOptions, type DeleteResponse, type DistanceMetric, type Document, type DocumentInput, type EmbeddingModel, ErrorCode, type ExportRequest, type ExportResponse, type ExportedVector, type FilterExpression, type FilterOperators, type FullKnowledgeGraphRequest, type FullTextSearchResult, type HealthResponse, type HybridSearchResult, type IndexStats, type JobProgressEvent, type KeyUsage, type KnowledgeEdge, type KnowledgeGraphRequest, type KnowledgeGraphResponse, type KnowledgeNode, type LatencyAnalytics, type ListSessionsOptions, type Memory, type MemoryEvent, type MemoryFeedbackRequest, type MemoryFeedbackResponse, type MemoryId, type MemoryType, type MultiVectorSearchRequest, type MultiVectorSearchResponse, type MultiVectorSearchResult, type NamespaceCreatedEvent, type NamespaceDeletedEvent, type NamespaceInfo, NotFoundError, type OpStatus, type OperationProgressEvent, type QueryExplainRequest, type QueryExplainResponse, type QueryOptions, type QueryResult, RateLimitError, type RateLimitHeaders, type ReadConsistency, type RecallRequest, type RecalledMemory, type RetryConfig, type SearchResult, ServerError, type Session, type SessionId, type SlowQuery, type StalenessConfig, type StartSessionRequest, type StorageAnalytics, type StoreMemoryRequest, type StoreMemoryResponse, type StreamLaggedEvent, type SummarizeRequest, type SummarizeResponse, type TextDocument, type TextQueryOptions, type TextQueryResponse, type TextSearchResult, type TextUpsertOptions, type TextUpsertResponse, type ThroughputAnalytics, TimeoutError, type TtlConfig, type UnifiedQueryRequest, type UnifiedQueryResponse, type UnifiedSearchResult, type UpdateImportanceRequest, type UpdateMemoryRequest, type UpsertOptions, type UpsertResponse, ValidationError, type Vector, type VectorId, type VectorInput, type VectorMutationOp, type VectorsMutatedEvent, type WarmCacheRequest, type WarmCacheResponse, type WarmingPriority, type WarmingTargetTier, agentId, memoryId, sessionId, vectorId };

package/dist/index.d.ts

@@ -226,16 +226,33 @@ interface BatchQuerySpec {
     /** Staleness configuration for bounded staleness reads */
     stalenessConfig?: StalenessConfig;
 }
+/** Exponential backoff configuration for retries */
+interface RetryConfig {
+    /** Maximum number of retry attempts (default: 3) */
+    maxRetries?: number;
+    /** Base delay in milliseconds before the first retry (default: 100) */
+    baseDelay?: number;
+    /** Maximum delay in milliseconds between retries (default: 60000) */
+    maxDelay?: number;
+    /** Whether to add random jitter to backoff delay (default: true) */
+    jitter?: boolean;
+}
 /** Client configuration options */
 interface ClientOptions {
     /** Base URL of the Dakera server */
     baseUrl: string;
     /** API key for authentication */
     apiKey?: string;
-    /** Request timeout in milliseconds */
+    /** Per-request timeout in milliseconds (default: 30000) */
     timeout?: number;
-    /** Maximum number of retries */
+    /** Connection establishment timeout in milliseconds. Defaults to `timeout`. */
+    connectTimeout?: number;
+    /** Maximum number of retries for transient errors (default: 3).
+     *  Ignored when `retryBackoff` is provided. */
     maxRetries?: number;
+    /** Fine-grained retry and backoff configuration.
+     *  When provided, `maxRetries` is ignored in favour of `retryBackoff.maxRetries`. */
+    retryBackoff?: RetryConfig;
     /** Additional headers */
     headers?: Record<string, string>;
 }
@@ -966,6 +983,8 @@ interface CrossAgentNetworkResponse {
     nodes: AgentNetworkNode[];
     edges: AgentNetworkEdge[];
     stats: AgentNetworkStats;
+    /** Total number of memory nodes in the network (added in server v0.6.2). */
+    node_count: number;
 }
 /** Request body for POST /v1/knowledge/network/cross-agent */
 interface CrossAgentNetworkRequest {
@@ -1044,6 +1063,74 @@ interface KeyUsage {
     last_used?: string;
     requests_by_endpoint?: Record<string, number>;
 }
+/**
+ * Rate-limit and quota headers present on every API response (OPS-1).
+ *
+ * Fields are `undefined` when the server does not include the header
+ * (e.g. non-namespaced endpoints where quota does not apply).
+ */
+interface RateLimitHeaders {
+    /** `X-RateLimit-Limit` — max requests allowed in the current window. */
+    limit?: number;
+    /** `X-RateLimit-Remaining` — requests left in the current window. */
+    remaining?: number;
+    /** `X-RateLimit-Reset` — Unix timestamp (seconds) when the window resets. */
+    reset?: number;
+    /** `X-Quota-Used` — namespace vectors / storage consumed. */
+    quotaUsed?: number;
+    /** `X-Quota-Limit` — namespace quota ceiling. */
+    quotaLimit?: number;
+}
+/**
+ * Filter predicates for batch memory operations (CE-2).
+ *
+ * All fields are optional.  For `batchForget` at least one must be set
+ * (server-side safety guard).
+ */
+interface BatchMemoryFilter {
+    /** Restrict to memories that carry **all** listed tags. */
+    tags?: string[];
+    /** Minimum importance (inclusive). */
+    min_importance?: number;
+    /** Maximum importance (inclusive). */
+    max_importance?: number;
+    /** Only memories created at or after this Unix timestamp (seconds). */
+    created_after?: number;
+    /** Only memories created before or at this Unix timestamp (seconds). */
+    created_before?: number;
+    /** Restrict to a specific memory type. */
+    memory_type?: MemoryType;
+    /** Restrict to memories from a specific session. */
+    session_id?: string;
+}
+/** Request body for `POST /v1/memories/recall/batch`. */
+interface BatchRecallRequest {
+    /** Agent whose memory namespace to search. */
+    agent_id: string;
+    /** Filter predicates to apply.  An empty object returns all memories up to `limit`. */
+    filter?: BatchMemoryFilter;
+    /** Maximum number of results to return (default: 100). */
+    limit?: number;
+}
+/** Response from `POST /v1/memories/recall/batch`. */
+interface BatchRecallResponse {
+    memories: Memory[];
+    /** Total memories in the agent namespace. */
+    total: number;
+    /** Number of memories that passed the filter. */
+    filtered: number;
+}
+/** Request body for `DELETE /v1/memories/forget/batch`. */
+interface BatchForgetRequest {
+    /** Agent whose memory namespace to purge from. */
+    agent_id: string;
+    /** Filter predicates — **at least one must be set** (server safety guard). */
+    filter: BatchMemoryFilter;
+}
+/** Response from `DELETE /v1/memories/forget/batch`. */
+interface BatchForgetResponse {
+    deleted_count: number;
+}
 
 /**
  * Dakera Client
@@ -1072,17 +1159,28 @@ declare class DakeraClient {
     private readonly baseUrl;
     private readonly apiKey?;
     private readonly timeout;
-    private readonly maxRetries;
+    private readonly connectTimeout;
+    private readonly retryConfig;
     private readonly headers;
+    /** OPS-1: rate-limit headers from the most recent API response. */
+    private _lastRateLimitHeaders;
     constructor(options: ClientOptions | string);
     /**
-     * Make an HTTP request with retry logic.
+     * Rate-limit headers from the most recent API response (OPS-1).
+     *
+     * Returns `null` until the first successful request has been made.
+     */
+    get lastRateLimitHeaders(): RateLimitHeaders | null;
+    private computeBackoff;
+    /**
+     * Make an HTTP request with retry logic and exponential backoff.
      */
     private request;
     /**
      * Handle HTTP response and throw appropriate errors.
      */
     private handleResponse;
+    private _parseHeaderInt;
     private sleep;
     /**
      * Upsert vectors into a namespace.
@@ -1555,6 +1653,38 @@ declare class DakeraClient {
     forget(agentId: string, memoryId: string): Promise<{
         status: string;
     }>;
+    /**
+     * Bulk-recall memories using filter predicates (CE-2).
+     *
+     * Uses `POST /v1/memories/recall/batch` — no embedding required.
+     *
+     * @example
+     * ```typescript
+     * const resp = await client.batchRecall({
+     *   agent_id: 'agent-1',
+     *   filter: { tags: ['preferences'], min_importance: 0.7 },
+     *   limit: 50,
+     * });
+     * console.log(`Found ${resp.filtered} memories`);
+     * ```
+     */
+    batchRecall(request: BatchRecallRequest): Promise<BatchRecallResponse>;
+    /**
+     * Bulk-delete memories using filter predicates (CE-2).
+     *
+     * Uses `DELETE /v1/memories/forget/batch`.  At least one filter predicate
+     * must be set (server safety guard).
+     *
+     * @example
+     * ```typescript
+     * const resp = await client.batchForget({
+     *   agent_id: 'agent-1',
+     *   filter: { created_before: Math.floor(Date.now() / 1000) - 86400 },
+     * });
+     * console.log(`Deleted ${resp.deleted_count} memories`);
+     * ```
+     */
+    batchForget(request: BatchForgetRequest): Promise<BatchForgetResponse>;
     /** Search memories for an agent */
     searchMemories(agentId: string, query: string, options?: {
         top_k?: number;
@@ -1744,6 +1874,16 @@ declare class DakeraClient {
      * ```
      */
     streamMemoryEvents(): AsyncGenerator<MemoryEvent>;
+    /**
+     * Return a URL with `?api_key=<key>` appended for use with browser-native
+     * `EventSource`, which cannot send custom request headers.
+     *
+     * @example
+     * ```ts
+     * const src = new EventSource(client.sseUrl('/v1/namespaces/my-ns/events'));
+     * ```
+     */
+    sseUrl(path: string): string;
     /** Low-level SSE streaming helper — parses the SSE wire format. */
     private _streamSse;
     /** Parse a single SSE event block into a {@link DakeraEvent}. */
@@ -1822,4 +1962,4 @@ declare class TimeoutError extends DakeraError {
     constructor(message: string);
 }
 
-export { type AccessPatternHint, type AgentId, type AgentNetworkEdge, type AgentNetworkInfo, type AgentNetworkNode, type AgentNetworkStats, type AgentStats, type AgentSummary, type AggregationGroup, type AggregationRequest, type AggregationResponse, type AnalyticsOptions, type AnalyticsOverview, type ApiKey, AuthenticationError, AuthorizationError, type BackupInfo, type BatchQuerySpec, type BatchTextQueryOptions, type BatchTextQueryResponse, type Branded, type CacheStats, type ClientOptions, type ClusterNode, type ClusterStatus, type ColumnUpsertRequest, type ConfigureNamespaceRequest, type ConfigureNamespaceResponse, ConnectionError, type ConsolidateRequest, type ConsolidateResponse, type CreateKeyRequest, type CrossAgentNetworkRequest, type CrossAgentNetworkResponse, DakeraClient, DakeraError, type DakeraEvent, type DeduplicateRequest, type DeduplicateResponse, type DeleteOptions, type DeleteResponse, type DistanceMetric, type Document, type DocumentInput, type EmbeddingModel, ErrorCode, type ExportRequest, type ExportResponse, type ExportedVector, type FilterExpression, type FilterOperators, type FullKnowledgeGraphRequest, type FullTextSearchResult, type HealthResponse, type HybridSearchResult, type IndexStats, type JobProgressEvent, type KeyUsage, type KnowledgeEdge, type KnowledgeGraphRequest, type KnowledgeGraphResponse, type KnowledgeNode, type LatencyAnalytics, type ListSessionsOptions, type Memory, type MemoryEvent, type MemoryFeedbackRequest, type MemoryFeedbackResponse, type MemoryId, type MemoryType, type MultiVectorSearchRequest, type MultiVectorSearchResponse, type MultiVectorSearchResult, type NamespaceCreatedEvent, type NamespaceDeletedEvent, type NamespaceInfo, NotFoundError, type OpStatus, type OperationProgressEvent, type QueryExplainRequest, type QueryExplainResponse, type QueryOptions, type QueryResult, RateLimitError, type ReadConsistency, type RecallRequest, type RecalledMemory, type SearchResult, ServerError, type Session, type SessionId, type SlowQuery, type StalenessConfig, type StartSessionRequest, type StorageAnalytics, type StoreMemoryRequest, type StoreMemoryResponse, type StreamLaggedEvent, type SummarizeRequest, type SummarizeResponse, type TextDocument, type TextQueryOptions, type TextQueryResponse, type TextSearchResult, type TextUpsertOptions, type TextUpsertResponse, type ThroughputAnalytics, TimeoutError, type TtlConfig, type UnifiedQueryRequest, type UnifiedQueryResponse, type UnifiedSearchResult, type UpdateImportanceRequest, type UpdateMemoryRequest, type UpsertOptions, type UpsertResponse, ValidationError, type Vector, type VectorId, type VectorInput, type VectorMutationOp, type VectorsMutatedEvent, type WarmCacheRequest, type WarmCacheResponse, type WarmingPriority, type WarmingTargetTier, agentId, memoryId, sessionId, vectorId };
+export { type AccessPatternHint, type AgentId, type AgentNetworkEdge, type AgentNetworkInfo, type AgentNetworkNode, type AgentNetworkStats, type AgentStats, type AgentSummary, type AggregationGroup, type AggregationRequest, type AggregationResponse, type AnalyticsOptions, type AnalyticsOverview, type ApiKey, AuthenticationError, AuthorizationError, type BackupInfo, type BatchForgetRequest, type BatchForgetResponse, type BatchMemoryFilter, type BatchQuerySpec, type BatchRecallRequest, type BatchRecallResponse, type BatchTextQueryOptions, type BatchTextQueryResponse, type Branded, type CacheStats, type ClientOptions, type ClusterNode, type ClusterStatus, type ColumnUpsertRequest, type ConfigureNamespaceRequest, type ConfigureNamespaceResponse, ConnectionError, type ConsolidateRequest, type ConsolidateResponse, type CreateKeyRequest, type CrossAgentNetworkRequest, type CrossAgentNetworkResponse, DakeraClient, DakeraError, type DakeraEvent, type DeduplicateRequest, type DeduplicateResponse, type DeleteOptions, type DeleteResponse, type DistanceMetric, type Document, type DocumentInput, type EmbeddingModel, ErrorCode, type ExportRequest, type ExportResponse, type ExportedVector, type FilterExpression, type FilterOperators, type FullKnowledgeGraphRequest, type FullTextSearchResult, type HealthResponse, type HybridSearchResult, type IndexStats, type JobProgressEvent, type KeyUsage, type KnowledgeEdge, type KnowledgeGraphRequest, type KnowledgeGraphResponse, type KnowledgeNode, type LatencyAnalytics, type ListSessionsOptions, type Memory, type MemoryEvent, type MemoryFeedbackRequest, type MemoryFeedbackResponse, type MemoryId, type MemoryType, type MultiVectorSearchRequest, type MultiVectorSearchResponse, type MultiVectorSearchResult, type NamespaceCreatedEvent, type NamespaceDeletedEvent, type NamespaceInfo, NotFoundError, type OpStatus, type OperationProgressEvent, type QueryExplainRequest, type QueryExplainResponse, type QueryOptions, type QueryResult, RateLimitError, type RateLimitHeaders, type ReadConsistency, type RecallRequest, type RecalledMemory, type RetryConfig, type SearchResult, ServerError, type Session, type SessionId, type SlowQuery, type StalenessConfig, type StartSessionRequest, type StorageAnalytics, type StoreMemoryRequest, type StoreMemoryResponse, type StreamLaggedEvent, type SummarizeRequest, type SummarizeResponse, type TextDocument, type TextQueryOptions, type TextQueryResponse, type TextSearchResult, type TextUpsertOptions, type TextUpsertResponse, type ThroughputAnalytics, TimeoutError, type TtlConfig, type UnifiedQueryRequest, type UnifiedQueryResponse, type UnifiedSearchResult, type UpdateImportanceRequest, type UpdateMemoryRequest, type UpsertOptions, type UpsertResponse, ValidationError, type Vector, type VectorId, type VectorInput, type VectorMutationOp, type VectorsMutatedEvent, type WarmCacheRequest, type WarmCacheResponse, type WarmingPriority, type WarmingTargetTier, agentId, memoryId, sessionId, vectorId };

package/dist/index.js

@@ -136,25 +136,34 @@ function parseErrorCode(raw) {
   }
   return "UNKNOWN" /* UNKNOWN */;
 }
-var DEFAULT_OPTIONS = {
-  baseUrl: "http://localhost:3000",
-  timeout: 3e4,
-  maxRetries: 3
-};
+var DEFAULT_TIMEOUT = 3e4;
+var DEFAULT_MAX_RETRIES = 3;
+var DEFAULT_BASE_DELAY = 100;
+var DEFAULT_MAX_DELAY = 6e4;
 var DakeraClient = class {
   baseUrl;
   apiKey;
   timeout;
-  maxRetries;
+  connectTimeout;
+  retryConfig;
   headers;
+  /** OPS-1: rate-limit headers from the most recent API response. */
+  _lastRateLimitHeaders = null;
   constructor(options) {
     if (typeof options === "string") {
       options = { baseUrl: options };
     }
     this.baseUrl = options.baseUrl.replace(/\/$/, "");
     this.apiKey = options.apiKey;
-    this.timeout = options.timeout ?? DEFAULT_OPTIONS.timeout;
-    this.maxRetries = options.maxRetries ?? DEFAULT_OPTIONS.maxRetries;
+    this.timeout = options.timeout ?? DEFAULT_TIMEOUT;
+    this.connectTimeout = options.connectTimeout ?? this.timeout;
+    const rb = options.retryBackoff ?? {};
+    this.retryConfig = {
+      maxRetries: rb.maxRetries ?? options.maxRetries ?? DEFAULT_MAX_RETRIES,
+      baseDelay: rb.baseDelay ?? DEFAULT_BASE_DELAY,
+      maxDelay: rb.maxDelay ?? DEFAULT_MAX_DELAY,
+      jitter: rb.jitter ?? true
+    };
     this.headers = {
       "Content-Type": "application/json",
       ...options.headers
@@ -164,41 +173,73 @@ var DakeraClient = class {
     }
   }
   /**
-   * Make an HTTP request with retry logic.
+   * Rate-limit headers from the most recent API response (OPS-1).
+   *
+   * Returns `null` until the first successful request has been made.
+   */
+  get lastRateLimitHeaders() {
+    return this._lastRateLimitHeaders;
+  }
+  computeBackoff(attempt) {
+    const { baseDelay, maxDelay, jitter } = this.retryConfig;
+    let delay = Math.min(maxDelay, baseDelay * Math.pow(2, attempt));
+    if (jitter) {
+      delay *= 0.5 + Math.random();
+    }
+    return delay;
+  }
+  /**
+   * Make an HTTP request with retry logic and exponential backoff.
    */
   async request(method, path, body) {
     const url = `${this.baseUrl}${path}`;
+    const { maxRetries } = this.retryConfig;
+    const connectMs = Math.min(this.connectTimeout, this.timeout);
     let lastError;
-    for (let attempt = 0; attempt < this.maxRetries; attempt++) {
+    for (let attempt = 0; attempt < maxRetries; attempt++) {
       try {
         const controller = new AbortController();
-        const timeoutId = setTimeout(() => controller.abort(), this.timeout);
+        const timerId = setTimeout(() => controller.abort(), connectMs);
         const response = await fetch(url, {
           method,
           headers: this.headers,
           body: body ? JSON.stringify(body) : void 0,
           signal: controller.signal
         });
-        clearTimeout(timeoutId);
+        clearTimeout(timerId);
         return await this.handleResponse(response);
       } catch (error) {
+        if (error instanceof RateLimitError) {
+          if (attempt === maxRetries - 1) throw error;
+          const wait = error.retryAfter != null ? error.retryAfter * 1e3 : this.computeBackoff(attempt);
+          await this.sleep(wait);
+          continue;
+        }
         if (error instanceof DakeraError) {
-          if (error.statusCode && error.statusCode >= 400 && error.statusCode < 500 && !(error instanceof RateLimitError)) {
+          if (error.statusCode && error.statusCode >= 400 && error.statusCode < 500) {
+            throw error;
+          }
+          if (attempt === maxRetries - 1) throw error;
+          lastError = error;
+        } else if (error instanceof Error) {
+          if (attempt === maxRetries - 1) {
+            if (error.name === "AbortError") {
+              throw new TimeoutError(`Request timed out after ${connectMs}ms`);
+            }
+            if (error.message.includes("fetch")) {
+              throw new ConnectionError(`Failed to connect to ${url}: ${error.message}`);
+            }
             throw error;
           }
-        }
-        if (error instanceof Error) {
           if (error.name === "AbortError") {
-            lastError = new TimeoutError(`Request timed out after ${this.timeout}ms`);
+            lastError = new TimeoutError(`Request timed out after ${connectMs}ms`);
           } else if (error.message.includes("fetch")) {
             lastError = new ConnectionError(`Failed to connect to ${url}: ${error.message}`);
           } else {
             lastError = error;
           }
         }
-        if (attempt < this.maxRetries - 1) {
-          await this.sleep(Math.pow(2, attempt) * 100);
-        }
+        await this.sleep(this.computeBackoff(attempt));
       }
     }
     throw lastError ?? new DakeraError("Request failed after retries");
@@ -207,6 +248,13 @@ var DakeraClient = class {
    * Handle HTTP response and throw appropriate errors.
    */
   async handleResponse(response) {
+    this._lastRateLimitHeaders = {
+      limit: this._parseHeaderInt(response.headers.get("X-RateLimit-Limit")),
+      remaining: this._parseHeaderInt(response.headers.get("X-RateLimit-Remaining")),
+      reset: this._parseHeaderInt(response.headers.get("X-RateLimit-Reset")),
+      quotaUsed: this._parseHeaderInt(response.headers.get("X-Quota-Used")),
+      quotaLimit: this._parseHeaderInt(response.headers.get("X-Quota-Limit"))
+    };
     let body;
     const contentType = response.headers.get("content-type");
     if (contentType?.includes("application/json")) {
@@ -247,6 +295,11 @@ var DakeraClient = class {
         throw new DakeraError(errorMessage, response.status, body, code);
     }
   }
+  _parseHeaderInt(value) {
+    if (value === null) return void 0;
+    const n = parseInt(value, 10);
+    return isNaN(n) ? void 0 : n;
+  }
   sleep(ms) {
     return new Promise((resolve) => setTimeout(resolve, ms));
   }
@@ -1017,6 +1070,42 @@ var DakeraClient = class {
   async forget(agentId2, memoryId2) {
     return this.request("DELETE", `/v1/agents/${agentId2}/memories/${memoryId2}`);
   }
+  /**
+   * Bulk-recall memories using filter predicates (CE-2).
+   *
+   * Uses `POST /v1/memories/recall/batch` — no embedding required.
+   *
+   * @example
+   * ```typescript
+   * const resp = await client.batchRecall({
+   *   agent_id: 'agent-1',
+   *   filter: { tags: ['preferences'], min_importance: 0.7 },
+   *   limit: 50,
+   * });
+   * console.log(`Found ${resp.filtered} memories`);
+   * ```
+   */
+  async batchRecall(request) {
+    return this.request("POST", "/v1/memories/recall/batch", request);
+  }
+  /**
+   * Bulk-delete memories using filter predicates (CE-2).
+   *
+   * Uses `DELETE /v1/memories/forget/batch`.  At least one filter predicate
+   * must be set (server safety guard).
+   *
+   * @example
+   * ```typescript
+   * const resp = await client.batchForget({
+   *   agent_id: 'agent-1',
+   *   filter: { created_before: Math.floor(Date.now() / 1000) - 86400 },
+   * });
+   * console.log(`Deleted ${resp.deleted_count} memories`);
+   * ```
+   */
+  async batchForget(request) {
+    return this.request("DELETE", "/v1/memories/forget/batch", request);
+  }
   /** Search memories for an agent */
   async searchMemories(agentId2, query, options) {
     const body = { query, ...options };
@@ -1341,15 +1430,29 @@ var DakeraClient = class {
     const url = `${this.baseUrl}/v1/events/stream`;
     yield* this._streamSseMemory(url);
   }
+  /**
+   * Return a URL with `?api_key=<key>` appended for use with browser-native
+   * `EventSource`, which cannot send custom request headers.
+   *
+   * @example
+   * ```ts
+   * const src = new EventSource(client.sseUrl('/v1/namespaces/my-ns/events'));
+   * ```
+   */
+  sseUrl(path) {
+    const base = `${this.baseUrl}${path}`;
+    if (!this.apiKey) return base;
+    const sep = base.includes("?") ? "&" : "?";
+    return `${base}${sep}api_key=${encodeURIComponent(this.apiKey)}`;
+  }
   /** Low-level SSE streaming helper — parses the SSE wire format. */
   async *_streamSse(url) {
+    const sseUrl = this.apiKey ? `${url}${url.includes("?") ? "&" : "?"}api_key=${encodeURIComponent(this.apiKey)}` : url;
     const headers = {
-      ...this.headers,
-      // includes Authorization and any custom headers
       Accept: "text/event-stream",
       "Cache-Control": "no-cache"
     };
-    const response = await fetch(url, { headers });
+    const response = await fetch(sseUrl, { headers });
     if (!response.ok || !response.body) {
       throw new Error(`SSE connection failed: ${response.status} ${response.statusText}`);
     }
@@ -1395,12 +1498,12 @@ var DakeraClient = class {
    * so callers receive a fully-populated {@link MemoryEvent}.
    */
   async *_streamSseMemory(url) {
+    const sseUrl = this.apiKey ? `${url}${url.includes("?") ? "&" : "?"}api_key=${encodeURIComponent(this.apiKey)}` : url;
     const headers = {
-      ...this.headers,
       Accept: "text/event-stream",
       "Cache-Control": "no-cache"
     };
-    const response = await fetch(url, { headers });
+    const response = await fetch(sseUrl, { headers });
     if (!response.ok || !response.body) {
       throw new Error(`SSE connection failed: ${response.status} ${response.statusText}`);
     }

package/dist/index.mjs

@@ -96,25 +96,34 @@ function parseErrorCode(raw) {
   }
   return "UNKNOWN" /* UNKNOWN */;
 }
-var DEFAULT_OPTIONS = {
-  baseUrl: "http://localhost:3000",
-  timeout: 3e4,
-  maxRetries: 3
-};
+var DEFAULT_TIMEOUT = 3e4;
+var DEFAULT_MAX_RETRIES = 3;
+var DEFAULT_BASE_DELAY = 100;
+var DEFAULT_MAX_DELAY = 6e4;
 var DakeraClient = class {
   baseUrl;
   apiKey;
   timeout;
-  maxRetries;
+  connectTimeout;
+  retryConfig;
   headers;
+  /** OPS-1: rate-limit headers from the most recent API response. */
+  _lastRateLimitHeaders = null;
   constructor(options) {
     if (typeof options === "string") {
       options = { baseUrl: options };
     }
     this.baseUrl = options.baseUrl.replace(/\/$/, "");
     this.apiKey = options.apiKey;
-    this.timeout = options.timeout ?? DEFAULT_OPTIONS.timeout;
-    this.maxRetries = options.maxRetries ?? DEFAULT_OPTIONS.maxRetries;
+    this.timeout = options.timeout ?? DEFAULT_TIMEOUT;
+    this.connectTimeout = options.connectTimeout ?? this.timeout;
+    const rb = options.retryBackoff ?? {};
+    this.retryConfig = {
+      maxRetries: rb.maxRetries ?? options.maxRetries ?? DEFAULT_MAX_RETRIES,
+      baseDelay: rb.baseDelay ?? DEFAULT_BASE_DELAY,
+      maxDelay: rb.maxDelay ?? DEFAULT_MAX_DELAY,
+      jitter: rb.jitter ?? true
+    };
     this.headers = {
       "Content-Type": "application/json",
       ...options.headers
@@ -124,41 +133,73 @@ var DakeraClient = class {
     }
   }
   /**
-   * Make an HTTP request with retry logic.
+   * Rate-limit headers from the most recent API response (OPS-1).
+   *
+   * Returns `null` until the first successful request has been made.
+   */
+  get lastRateLimitHeaders() {
+    return this._lastRateLimitHeaders;
+  }
+  computeBackoff(attempt) {
+    const { baseDelay, maxDelay, jitter } = this.retryConfig;
+    let delay = Math.min(maxDelay, baseDelay * Math.pow(2, attempt));
+    if (jitter) {
+      delay *= 0.5 + Math.random();
+    }
+    return delay;
+  }
+  /**
+   * Make an HTTP request with retry logic and exponential backoff.
    */
   async request(method, path, body) {
     const url = `${this.baseUrl}${path}`;
+    const { maxRetries } = this.retryConfig;
+    const connectMs = Math.min(this.connectTimeout, this.timeout);
     let lastError;
-    for (let attempt = 0; attempt < this.maxRetries; attempt++) {
+    for (let attempt = 0; attempt < maxRetries; attempt++) {
       try {
         const controller = new AbortController();
-        const timeoutId = setTimeout(() => controller.abort(), this.timeout);
+        const timerId = setTimeout(() => controller.abort(), connectMs);
         const response = await fetch(url, {
           method,
           headers: this.headers,
           body: body ? JSON.stringify(body) : void 0,
           signal: controller.signal
         });
-        clearTimeout(timeoutId);
+        clearTimeout(timerId);
         return await this.handleResponse(response);
       } catch (error) {
+        if (error instanceof RateLimitError) {
+          if (attempt === maxRetries - 1) throw error;
+          const wait = error.retryAfter != null ? error.retryAfter * 1e3 : this.computeBackoff(attempt);
+          await this.sleep(wait);
+          continue;
+        }
         if (error instanceof DakeraError) {
-          if (error.statusCode && error.statusCode >= 400 && error.statusCode < 500 && !(error instanceof RateLimitError)) {
+          if (error.statusCode && error.statusCode >= 400 && error.statusCode < 500) {
+            throw error;
+          }
+          if (attempt === maxRetries - 1) throw error;
+          lastError = error;
+        } else if (error instanceof Error) {
+          if (attempt === maxRetries - 1) {
+            if (error.name === "AbortError") {
+              throw new TimeoutError(`Request timed out after ${connectMs}ms`);
+            }
+            if (error.message.includes("fetch")) {
+              throw new ConnectionError(`Failed to connect to ${url}: ${error.message}`);
+            }
             throw error;
           }
-        }
-        if (error instanceof Error) {
           if (error.name === "AbortError") {
-            lastError = new TimeoutError(`Request timed out after ${this.timeout}ms`);
+            lastError = new TimeoutError(`Request timed out after ${connectMs}ms`);
           } else if (error.message.includes("fetch")) {
             lastError = new ConnectionError(`Failed to connect to ${url}: ${error.message}`);
           } else {
             lastError = error;
           }
         }
-        if (attempt < this.maxRetries - 1) {
-          await this.sleep(Math.pow(2, attempt) * 100);
-        }
+        await this.sleep(this.computeBackoff(attempt));
       }
     }
     throw lastError ?? new DakeraError("Request failed after retries");
@@ -167,6 +208,13 @@ var DakeraClient = class {
    * Handle HTTP response and throw appropriate errors.
    */
   async handleResponse(response) {
+    this._lastRateLimitHeaders = {
+      limit: this._parseHeaderInt(response.headers.get("X-RateLimit-Limit")),
+      remaining: this._parseHeaderInt(response.headers.get("X-RateLimit-Remaining")),
+      reset: this._parseHeaderInt(response.headers.get("X-RateLimit-Reset")),
+      quotaUsed: this._parseHeaderInt(response.headers.get("X-Quota-Used")),
+      quotaLimit: this._parseHeaderInt(response.headers.get("X-Quota-Limit"))
+    };
     let body;
     const contentType = response.headers.get("content-type");
     if (contentType?.includes("application/json")) {
@@ -207,6 +255,11 @@ var DakeraClient = class {
         throw new DakeraError(errorMessage, response.status, body, code);
     }
   }
+  _parseHeaderInt(value) {
+    if (value === null) return void 0;
+    const n = parseInt(value, 10);
+    return isNaN(n) ? void 0 : n;
+  }
   sleep(ms) {
     return new Promise((resolve) => setTimeout(resolve, ms));
   }
@@ -977,6 +1030,42 @@ var DakeraClient = class {
   async forget(agentId2, memoryId2) {
     return this.request("DELETE", `/v1/agents/${agentId2}/memories/${memoryId2}`);
   }
+  /**
+   * Bulk-recall memories using filter predicates (CE-2).
+   *
+   * Uses `POST /v1/memories/recall/batch` — no embedding required.
+   *
+   * @example
+   * ```typescript
+   * const resp = await client.batchRecall({
+   *   agent_id: 'agent-1',
+   *   filter: { tags: ['preferences'], min_importance: 0.7 },
+   *   limit: 50,
+   * });
+   * console.log(`Found ${resp.filtered} memories`);
+   * ```
+   */
+  async batchRecall(request) {
+    return this.request("POST", "/v1/memories/recall/batch", request);
+  }
+  /**
+   * Bulk-delete memories using filter predicates (CE-2).
+   *
+   * Uses `DELETE /v1/memories/forget/batch`.  At least one filter predicate
+   * must be set (server safety guard).
+   *
+   * @example
+   * ```typescript
+   * const resp = await client.batchForget({
+   *   agent_id: 'agent-1',
+   *   filter: { created_before: Math.floor(Date.now() / 1000) - 86400 },
+   * });
+   * console.log(`Deleted ${resp.deleted_count} memories`);
+   * ```
+   */
+  async batchForget(request) {
+    return this.request("DELETE", "/v1/memories/forget/batch", request);
+  }
   /** Search memories for an agent */
   async searchMemories(agentId2, query, options) {
     const body = { query, ...options };
@@ -1301,15 +1390,29 @@ var DakeraClient = class {
     const url = `${this.baseUrl}/v1/events/stream`;
     yield* this._streamSseMemory(url);
   }
+  /**
+   * Return a URL with `?api_key=<key>` appended for use with browser-native
+   * `EventSource`, which cannot send custom request headers.
+   *
+   * @example
+   * ```ts
+   * const src = new EventSource(client.sseUrl('/v1/namespaces/my-ns/events'));
+   * ```
+   */
+  sseUrl(path) {
+    const base = `${this.baseUrl}${path}`;
+    if (!this.apiKey) return base;
+    const sep = base.includes("?") ? "&" : "?";
+    return `${base}${sep}api_key=${encodeURIComponent(this.apiKey)}`;
+  }
   /** Low-level SSE streaming helper — parses the SSE wire format. */
   async *_streamSse(url) {
+    const sseUrl = this.apiKey ? `${url}${url.includes("?") ? "&" : "?"}api_key=${encodeURIComponent(this.apiKey)}` : url;
     const headers = {
-      ...this.headers,
-      // includes Authorization and any custom headers
       Accept: "text/event-stream",
       "Cache-Control": "no-cache"
     };
-    const response = await fetch(url, { headers });
+    const response = await fetch(sseUrl, { headers });
     if (!response.ok || !response.body) {
       throw new Error(`SSE connection failed: ${response.status} ${response.statusText}`);
     }
@@ -1355,12 +1458,12 @@ var DakeraClient = class {
    * so callers receive a fully-populated {@link MemoryEvent}.
    */
   async *_streamSseMemory(url) {
+    const sseUrl = this.apiKey ? `${url}${url.includes("?") ? "&" : "?"}api_key=${encodeURIComponent(this.apiKey)}` : url;
     const headers = {
-      ...this.headers,
       Accept: "text/event-stream",
       "Cache-Control": "no-cache"
     };
-    const response = await fetch(url, { headers });
+    const response = await fetch(sseUrl, { headers });
     if (!response.ok || !response.body) {
       throw new Error(`SSE connection failed: ${response.status} ${response.statusText}`);
     }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dakera-ai/dakera",
-  "version": "0.6.1",
+  "version": "0.7.0",
   "description": "TypeScript/JavaScript SDK for Dakera AI memory platform",
   "main": "dist/index.js",
   "module": "dist/index.mjs",
@@ -57,3 +57,4 @@
     "vitest": "^4.1.0"
   }
 }
+