@wiscale/velesdb-sdk 1.18.0 → 2.0.0

package/dist/index.d.ts

@@ -12,8 +12,15 @@ type StorageMode = 'full' | 'sq8' | 'binary' | 'pq' | 'rabitq';
 type SearchQuality = 'fast' | 'balanced' | 'accurate' | 'perfect' | 'autotune' | `custom:${number}` | `adaptive:${number}:${number}`;
 /** Backend type for VelesDB connection */
 type BackendType = 'wasm' | 'rest';
-/** Numeric point ID required by velesdb-server REST API (`u64`). */
-type RestPointId = number;
+/**
+ * Point ID accepted by the velesdb-server REST API (`u64`).
+ *
+ * Ids within the JS safe-integer range are numbers; decimal-string ids above
+ * `Number.MAX_SAFE_INTEGER` (2^53-1) stay verbatim strings so the full u64
+ * range survives the JavaScript boundary without precision loss (the server
+ * deserialises both forms since #1004).
+ */
+type RestPointId = number | string;
 /** Configuration options for VelesDB client */
 interface VelesDBConfig {
     /** Backend type: 'wasm' for browser/Node.js, 'rest' for server */
@@ -563,6 +570,42 @@ interface DegreeResponse {
     /** Number of outgoing edges */
     outDegree: number;
 }
+/** Request body for POST /collections/{name}/relations */
+interface RelateRequest {
+    /** Source point ID */
+    source: GraphNodeId;
+    /** Target point ID */
+    target: GraphNodeId;
+    /** Relationship type label (e.g. "KNOWS", "RELATED_TO") */
+    relType: string;
+    /** Optional edge properties */
+    properties?: Record<string, unknown>;
+}
+/** Response from POST /collections/{name}/relations */
+interface RelateResponse {
+    /** Allocated edge ID */
+    edgeId: GraphNodeId;
+}
+/** A single outgoing relation edge */
+interface RelationEdge {
+    /** Edge ID */
+    id: GraphNodeId;
+    /** Source point ID */
+    source: GraphNodeId;
+    /** Target point ID */
+    target: GraphNodeId;
+    /** Relationship type label */
+    relType: string;
+    /** Edge properties */
+    properties?: Record<string, unknown>;
+}
+/** Response from GET /collections/{name}/points/{id}/relations */
+interface RelationsResponse {
+    /** Outgoing relation edges */
+    edges: RelationEdge[];
+    /** Total count */
+    count: number;
+}
 /** Schema mode for graph collections */
 type GraphSchemaMode = 'schemaless' | 'strict';
 /** Graph collection configuration */
@@ -583,8 +626,15 @@ interface GraphCollectionConfig {
  */
 /** Semantic memory entry */
 interface SemanticEntry {
-    /** Unique fact ID */
-    id: number;
+    /**
+     * Unique fact ID.
+     *
+     * `string | number` is accepted as a convenience (a string must be a decimal
+     * integer). Ids must be non-negative integers within the JS safe-integer
+     * range (0..2^53-1): the REST wire transmits point ids as JSON numbers, so
+     * out-of-range ids are rejected (not silently truncated).
+     */
+    id: string | number;
     /** Fact text content */
     text: string;
     /** Embedding vector */
@@ -594,8 +644,24 @@ interface SemanticEntry {
 }
 /** Episodic memory event */
 interface EpisodicEvent {
+    /**
+     * Optional caller-provided event ID. When omitted, a monotonic id is
+     * generated. `string | number` is accepted as a convenience; ids must be
+     * non-negative integers within the JS safe-integer range (0..2^53-1) because
+     * the REST wire transmits them as JSON numbers, and out-of-range ids are
+     * rejected (not silently truncated).
+     */
+    id?: string | number;
     /** Event type identifier */
     eventType: string;
+    /**
+     * Event timestamp as a NUMERIC unix time in **seconds**.
+     *
+     * Mirrors the core episodic store, which persists a numeric `timestamp`
+     * that feeds `recent(since)` / `older_than(before)`. When omitted it
+     * defaults to the current unix-seconds value (`floor(Date.now() / 1000)`).
+     */
+    timestamp?: number;
     /** Event data */
     data: Record<string, unknown>;
     /** Embedding vector */
@@ -605,6 +671,14 @@ interface EpisodicEvent {
 }
 /** Procedural memory pattern */
 interface ProceduralPattern {
+    /**
+     * Optional caller-provided pattern ID. When omitted, a monotonic id is
+     * generated. `string | number` is accepted as a convenience; ids must be
+     * non-negative integers within the JS safe-integer range (0..2^53-1) because
+     * the REST wire transmits them as JSON numbers, and out-of-range ids are
+     * rejected (not silently truncated).
+     */
+    id?: string | number;
     /** Procedure name */
     name: string;
     /** Ordered steps */
@@ -620,6 +694,15 @@ interface ProceduralPattern {
     /** Optional metadata */
     metadata?: Record<string, unknown>;
 }
+/** A single episodic event recalled by timestamp. */
+interface EpisodicRecord {
+    /** Point id as a string (u64 precision preserved). */
+    id: string;
+    /** Numeric unix-seconds timestamp. */
+    timestamp: number;
+    /** Full point payload (includes `event_type`, caller data/metadata). */
+    payload: Record<string, unknown>;
+}
 /** Agent memory configuration */
 interface AgentMemoryConfig {
     /** Embedding dimension (default: 384) */
@@ -939,11 +1022,17 @@ declare const REST_CAPABILITIES: Readonly<CapabilityMap>;
  * Capability map for the WASM backend.
  *
  * The WASM build ships a focused subset: the dense / text / hybrid /
- * multi-query search paths plus VelesQL execution. Everything that
- * relies on persistent on-disk structures (secondary indexes, graph,
- * streaming, PQ training, agent memory, introspection, sparse
- * inverted index) is explicitly `false`. See `backends/wasm-stubs.ts`
- * for the exact set of `wasmNotSupported()` throw sites.
+ * multi-query search paths. Everything that relies on persistent
+ * on-disk structures (secondary indexes, graph, streaming, PQ
+ * training, agent memory, introspection, sparse inverted index) is
+ * explicitly `false`. See `backends/wasm-stubs.ts` for the exact set
+ * of `wasmNotSupported()` throw sites.
+ *
+ * `velesqlQuery` is `false`: `query()` only executes pure top-k NEAR
+ * statements (`SELECT * FROM <collection> WHERE vector NEAR $param
+ * [LIMIT n]`) and throws `NOT_SUPPORTED` for any other VelesQL clause
+ * (WHERE predicates, JOIN, GROUP BY, MATCH, set operations, FUSION),
+ * so full VelesQL is not advertised.
  */
 declare const WASM_CAPABILITIES: Readonly<CapabilityMap>;
 
@@ -1104,13 +1193,6 @@ interface StreamUpsertResponse {
     networkErrors: number;
 }
 
-/**
- * VelesDB TypeScript SDK - Backend Interface
- *
- * The `IVelesDBBackend` interface that all backends must implement.
- * @packageDocumentation
- */
-
 /** Backend interface that all backends must implement */
 interface IVelesDBBackend {
     /** Initialize the backend */
@@ -1239,12 +1321,28 @@ interface IVelesDBBackend {
     storeSemanticFact(collection: string, entry: SemanticEntry): Promise<void>;
     /** Search semantic memory */
     searchSemanticMemory(collection: string, embedding: number[], k?: number): Promise<SearchResult[]>;
-    /** Record an episodic event. Returns the generated point ID. */
-    recordEpisodicEvent(collection: string, event: EpisodicEvent): Promise<number>;
-    /** Recall episodic events */
+    /**
+     * Record an episodic event. Returns the point ID as a string (u64
+     * precision preserved).
+     */
+    recordEpisodicEvent(collection: string, event: EpisodicEvent): Promise<string>;
+    /** Recall episodic events by vector similarity. */
     recallEpisodicEvents(collection: string, embedding: number[], k?: number): Promise<SearchResult[]>;
-    /** Store a procedural pattern. Returns the generated point ID. */
-    storeProceduralPattern(collection: string, pattern: ProceduralPattern): Promise<number>;
+    /**
+     * Recall episodic events most-recent-first, optionally bounded below by
+     * `since` (inclusive unix-seconds). Mirrors core `episodic.recent(since)`.
+     */
+    recallRecentEvents(collection: string, since?: number): Promise<EpisodicRecord[]>;
+    /**
+     * Recall episodic events strictly older than `before` (unix-seconds),
+     * most-recent-first. Mirrors core `episodic.older_than(before)`.
+     */
+    recallOlderThanEvents(collection: string, before: number): Promise<EpisodicRecord[]>;
+    /**
+     * Store a procedural pattern. Returns the point ID as a string (u64
+     * precision preserved).
+     */
+    storeProceduralPattern(collection: string, pattern: ProceduralPattern): Promise<string>;
     /** Match procedural patterns */
     matchProceduralPatterns(collection: string, embedding: number[], k?: number): Promise<SearchResult[]>;
     /** Rebuild a collection's HNSW index (compacts tombstones). */
@@ -1271,6 +1369,14 @@ interface IVelesDBBackend {
     upsertNodePayload(collection: string, nodeId: number, payload: Record<string, unknown>): Promise<void>;
     /** Vector similarity search scoped to graph nodes only. */
     graphSearch(collection: string, request: GraphSearchRequest): Promise<GraphSearchResponse>;
+    /** Create a typed relation edge between two points. Returns the allocated edge ID. */
+    relate(collection: string, req: RelateRequest): Promise<RelateResponse>;
+    /** Remove a relation edge by ID. Returns `true` if removed. */
+    unrelate(collection: string, edgeId: GraphNodeId): Promise<boolean>;
+    /** List outgoing relation edges for a point. */
+    getRelations(collection: string, pointId: GraphNodeId): Promise<RelationsResponse>;
+    /** Durably set (or refresh) the TTL of a point. */
+    setTtlDurable(collection: string, pointId: GraphNodeId, ttlSeconds: number): Promise<void>;
 }
 
 /**
@@ -1328,16 +1434,31 @@ declare class AgentMemoryClient {
     storeFact(collection: string, entry: SemanticEntry): Promise<void>;
     /** Search semantic memory */
     searchFacts(collection: string, embedding: number[], k?: number): Promise<SearchResult[]>;
-    /** Record an episodic event. Returns the generated point ID. */
-    recordEvent(collection: string, event: EpisodicEvent): Promise<number>;
-    /** Recall episodic events */
+    /** Record an episodic event. Returns the point ID (string, u64-safe). */
+    recordEvent(collection: string, event: EpisodicEvent): Promise<string>;
+    /** Recall episodic events by vector similarity. */
     recallEvents(collection: string, embedding: number[], k?: number): Promise<SearchResult[]>;
-    /** Store a procedural pattern. Returns the generated point ID. */
-    learnProcedure(collection: string, pattern: ProceduralPattern): Promise<number>;
+    /**
+     * Recall episodic events most-recent-first, optionally bounded below by
+     * `since` (inclusive unix-seconds). Mirrors core `episodic.recent(since)`.
+     */
+    recallRecent(collection: string, since?: number): Promise<EpisodicRecord[]>;
+    /**
+     * Recall episodic events strictly older than `before` (unix-seconds),
+     * most-recent-first. Mirrors core `episodic.older_than(before)`.
+     */
+    recallOlderThan(collection: string, before: number): Promise<EpisodicRecord[]>;
+    /** Store a procedural pattern. Returns the point ID (string, u64-safe). */
+    learnProcedure(collection: string, pattern: ProceduralPattern): Promise<string>;
     /** Match procedural patterns */
     recallProcedures(collection: string, embedding: number[], k?: number): Promise<SearchResult[]>;
-    /** Delete a memory entry (fact, event, or procedure) by its point ID. */
-    deleteMemory(collection: string, id: number): Promise<boolean>;
+    /**
+     * Delete a memory entry (fact, event, or procedure) by its point ID.
+     *
+     * Accepts the `string` ids returned by `recordEvent` / `learnProcedure`
+     * (u64-safe decimal strings) as well as numeric ids.
+     */
+    deleteMemory(collection: string, id: string | number): Promise<boolean>;
 }
 
 /**
@@ -1436,6 +1557,10 @@ declare class VelesDB {
     getNodePayload(collection: string, nodeId: number): Promise<NodePayloadResponse>;
     upsertNodePayload(collection: string, nodeId: number, payload: Record<string, unknown>): Promise<void>;
     graphSearch(collection: string, request: GraphSearchRequest): Promise<GraphSearchResponse>;
+    relate(collection: string, req: RelateRequest): Promise<RelateResponse>;
+    unrelate(collection: string, edgeId: GraphNodeId): Promise<boolean>;
+    getRelations(collection: string, pointId: GraphNodeId): Promise<RelationsResponse>;
+    setTtlDurable(collection: string, pointId: GraphNodeId, ttlSeconds: number): Promise<void>;
     capabilities(): Readonly<CapabilityMap>;
     get backendType(): string;
     agentMemory(config?: AgentMemoryConfig): AgentMemoryClient;
@@ -1514,9 +1639,11 @@ declare class WasmBackend implements IVelesDBBackend {
     }>>;
     storeSemanticFact(c: string, e: SemanticEntry): Promise<void>;
     searchSemanticMemory(c: string, e: number[], k?: number): Promise<SearchResult[]>;
-    recordEpisodicEvent(c: string, e: EpisodicEvent): Promise<number>;
+    recordEpisodicEvent(c: string, e: EpisodicEvent): Promise<string>;
     recallEpisodicEvents(c: string, e: number[], k?: number): Promise<SearchResult[]>;
-    storeProceduralPattern(c: string, p: ProceduralPattern): Promise<number>;
+    recallRecentEvents(c: string, since?: number): Promise<EpisodicRecord[]>;
+    recallOlderThanEvents(c: string, before: number): Promise<EpisodicRecord[]>;
+    storeProceduralPattern(c: string, p: ProceduralPattern): Promise<string>;
     matchProceduralPatterns(c: string, e: number[], k?: number): Promise<SearchResult[]>;
     rebuildIndex(c: string): Promise<RebuildIndexResponse>;
     getGuardrails(): Promise<GuardRailsConfigResponse>;
@@ -1531,6 +1658,10 @@ declare class WasmBackend implements IVelesDBBackend {
     upsertNodePayload(c: string, id: number, p: Record<string, unknown>): Promise<void>;
     graphSearch(c: string, r: GraphSearchRequest): Promise<GraphSearchResponse>;
     sparseSearchNamed(c: string, q: SparseVector, idx: string, o?: SparseSearchNamedOptions): Promise<SearchResult[]>;
+    relate(c: string, req: RelateRequest): Promise<RelateResponse>;
+    unrelate(c: string, edgeId: GraphNodeId): Promise<boolean>;
+    getRelations(c: string, pointId: GraphNodeId): Promise<RelationsResponse>;
+    setTtlDurable(c: string, pointId: GraphNodeId, ttlSeconds: number): Promise<void>;
 }
 
 /**
@@ -1569,6 +1700,10 @@ declare class RestBackend implements IVelesDBBackend {
     getNodePayload(c: string, id: number): Promise<NodePayloadResponse>;
     upsertNodePayload(c: string, id: number, p: Record<string, unknown>): Promise<void>;
     graphSearch(c: string, r: GraphSearchRequest): Promise<GraphSearchResponse>;
+    relate(c: string, req: RelateRequest): Promise<RelateResponse>;
+    unrelate(c: string, edgeId: GraphNodeId): Promise<boolean>;
+    getRelations(c: string, pointId: GraphNodeId): Promise<RelationsResponse>;
+    setTtlDurable(c: string, pointId: GraphNodeId, ttlSeconds: number): Promise<void>;
     search(c: string, q: number[] | Float32Array, o?: SearchOptions): Promise<SearchResult[]>;
     searchBatch(c: string, s: Array<{
         vector: number[] | Float32Array;
@@ -1615,9 +1750,11 @@ declare class RestBackend implements IVelesDBBackend {
     streamUpsertPoints(c: string, d: VectorDocument[]): Promise<StreamUpsertResponse>;
     storeSemanticFact(c: string, e: SemanticEntry): Promise<void>;
     searchSemanticMemory(c: string, e: number[], k?: number): Promise<SearchResult[]>;
-    recordEpisodicEvent(c: string, e: EpisodicEvent): Promise<number>;
+    recordEpisodicEvent(c: string, e: EpisodicEvent): Promise<string>;
     recallEpisodicEvents(c: string, e: number[], k?: number): Promise<SearchResult[]>;
-    storeProceduralPattern(c: string, p: ProceduralPattern): Promise<number>;
+    recallRecentEvents(c: string, since?: number): Promise<EpisodicRecord[]>;
+    recallOlderThanEvents(c: string, before: number): Promise<EpisodicRecord[]>;
+    storeProceduralPattern(c: string, p: ProceduralPattern): Promise<string>;
     matchProceduralPatterns(c: string, e: number[], k?: number): Promise<SearchResult[]>;
 }
 
@@ -2109,4 +2246,4 @@ declare class OpenAIEmbedder implements Embedder {
     embed(texts: string[]): Promise<number[][]>;
 }
 
-export { type ActualStats, type AddEdgeRequest, AgentMemoryClient, type AgentMemoryConfig, type AggregateQueryOptions, type AggregateResponse, type AggregationQueryResponse, AllocationFailedError, type AsyncIndexBuilderOptions, type BackendType, BackpressureError, type CapabilityMap, type Collection, type CollectionConfig, type CollectionConfigResponse, CollectionExistsError, CollectionNotFoundError, type CollectionSanityChecks, type CollectionSanityDiagnostics, type CollectionSanityResponse, type CollectionStatsResponse, type CollectionType, type ColumnStatsDetail, ColumnStoreError, type CompareOp, type Condition, ConfigError, ConnectionError, type CreateIndexOptions, DatabaseLockedError, type DeferredIndexerOptions, type DegreeResponse, DimensionMismatchError, type DistanceMetric, EdgeExistsError, EdgeNotFoundError, type EdgesResponse, type Embedder, type EpisodicEvent, EpochMismatchError, type ExplainCost, type ExplainFeatures, type ExplainPlanStep, type ExplainResponse, type Filter, type FilterInput, type FusionOptions, type FusionStrategy, type GetEdgesOptions, type GetNodeEdgesOptions, GpuError, type GraphCollectionConfig, type GraphEdge, type GraphNodeId, GraphNotSupportedError, type GraphSchemaMode, type GraphSearchRequest, type GraphSearchResponse, type GraphSearchResultItem, GuardRailError, type GuardRailsConfigResponse, type GuardRailsUpdateRequest, type HnswParams, type IVelesDBBackend, IncompatibleSchemaVersionError, IndexCorruptedError, IndexError, type IndexInfo, type IndexType, InternalError, InvalidCollectionNameError, InvalidDimensionError, InvalidEdgeLabelError, InvalidQuantizerConfigError, InvalidVectorError, IoError, type JsonValue, type ListNodesResponse, type MatchQueryOptions, type MatchQueryResponse, type MatchQueryResultItem, type MultiQuerySearchOptions, type NearVectorOptions, NodeNotFoundError, type NodePayloadResponse, type NodeStats, NotFoundError, OpenAIEmbedder, type OpenAIEmbedderOptions, OverflowError, PointNotFoundError, type PqTrainOptions, type ProceduralPattern, type QueryApiResponse, QueryError, type QueryOptions, type QueryResponse, type QueryResult, type QueryStats, REST_CAPABILITIES, type RebuildIndexResponse, type RelDirection, type RelOptions, RestBackend, type RestPointId, SchemaValidationError, type ScrollRequest, type ScrollResponse, SearchNotSupportedError, type SearchOptions, type SearchQuality, type SearchQualityWire, type SearchResult, type SemanticEntry, SerializationError, SnapshotBuildFailedError, SparseIndexError, type SparseSearchNamedOptions, type SparseVector, StorageError, type StorageMode, type StreamUpsertResponse, TrainingFailedError, type TraversalResultItem, type TraversalStats, type TraverseParallelRequest, type TraverseRequest, type TraverseResponse, VELES_ERROR_CODES, ValidationError, type VectorDocument, VectorNotAllowedError, VectorRequiredError, VelesDB, type VelesDBConfig, VelesDBError, VelesError, type VelesErrorCode, VelesQLBuilder, WASM_CAPABILITIES, WasmBackend, f, isTypedFilter, normalizeFilter, parseVelesError, searchQualityToMode, velesql };
+export { type ActualStats, type AddEdgeRequest, AgentMemoryClient, type AgentMemoryConfig, type AggregateQueryOptions, type AggregateResponse, type AggregationQueryResponse, AllocationFailedError, type AsyncIndexBuilderOptions, type BackendType, BackpressureError, type CapabilityMap, type Collection, type CollectionConfig, type CollectionConfigResponse, CollectionExistsError, CollectionNotFoundError, type CollectionSanityChecks, type CollectionSanityDiagnostics, type CollectionSanityResponse, type CollectionStatsResponse, type CollectionType, type ColumnStatsDetail, ColumnStoreError, type CompareOp, type Condition, ConfigError, ConnectionError, type CreateIndexOptions, DatabaseLockedError, type DeferredIndexerOptions, type DegreeResponse, DimensionMismatchError, type DistanceMetric, EdgeExistsError, EdgeNotFoundError, type EdgesResponse, type Embedder, type EpisodicEvent, type EpisodicRecord, EpochMismatchError, type ExplainCost, type ExplainFeatures, type ExplainPlanStep, type ExplainResponse, type Filter, type FilterInput, type FusionOptions, type FusionStrategy, type GetEdgesOptions, type GetNodeEdgesOptions, GpuError, type GraphCollectionConfig, type GraphEdge, type GraphNodeId, GraphNotSupportedError, type GraphSchemaMode, type GraphSearchRequest, type GraphSearchResponse, type GraphSearchResultItem, GuardRailError, type GuardRailsConfigResponse, type GuardRailsUpdateRequest, type HnswParams, type IVelesDBBackend, IncompatibleSchemaVersionError, IndexCorruptedError, IndexError, type IndexInfo, type IndexType, InternalError, InvalidCollectionNameError, InvalidDimensionError, InvalidEdgeLabelError, InvalidQuantizerConfigError, InvalidVectorError, IoError, type JsonValue, type ListNodesResponse, type MatchQueryOptions, type MatchQueryResponse, type MatchQueryResultItem, type MultiQuerySearchOptions, type NearVectorOptions, NodeNotFoundError, type NodePayloadResponse, type NodeStats, NotFoundError, OpenAIEmbedder, type OpenAIEmbedderOptions, OverflowError, PointNotFoundError, type PqTrainOptions, type ProceduralPattern, type QueryApiResponse, QueryError, type QueryOptions, type QueryResponse, type QueryResult, type QueryStats, REST_CAPABILITIES, type RebuildIndexResponse, type RelDirection, type RelOptions, type RelateRequest, type RelateResponse, type RelationEdge, type RelationsResponse, RestBackend, type RestPointId, SchemaValidationError, type ScrollRequest, type ScrollResponse, SearchNotSupportedError, type SearchOptions, type SearchQuality, type SearchQualityWire, type SearchResult, type SemanticEntry, SerializationError, SnapshotBuildFailedError, SparseIndexError, type SparseSearchNamedOptions, type SparseVector, StorageError, type StorageMode, type StreamUpsertResponse, TrainingFailedError, type TraversalResultItem, type TraversalStats, type TraverseParallelRequest, type TraverseRequest, type TraverseResponse, VELES_ERROR_CODES, ValidationError, type VectorDocument, VectorNotAllowedError, VectorRequiredError, VelesDB, type VelesDBConfig, VelesDBError, VelesError, type VelesErrorCode, VelesQLBuilder, WASM_CAPABILITIES, WasmBackend, f, isTypedFilter, normalizeFilter, parseVelesError, searchQualityToMode, velesql };