@synapcores/sdk 0.2.1 → 0.4.0

package/CHANGELOG.md

@@ -0,0 +1,108 @@
+# Changelog
+
+All notable changes to `@synapcores/sdk` are documented here.
+This project follows [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## 0.4.0 — 2026-05-18 — vector-subsystem + auth alignment with v1.6.5.2-ce gateway
+
+Closes three wire-format gaps surfaced during the OpenClaw v0.1.0 integration.
+Validation against `validate-nodejs-sdk-v04.ts` goes from **8/9** under 0.3.0
+to **11/12** under 0.4.0 (#5 — Cypher `$param` — remains the documented
+gateway-side blocker).
+
+### Fixed
+
+- **Auth: `apiKey` now sends `Authorization: Bearer <key>` instead of
+  `X-API-Key`.** Gateway v1.6.5.2-ce only honours the `Authorization`
+  header for both JWTs and AIDB-issued API keys (`aidb_*` / `ak_*`);
+  the legacy `X-API-Key` shim was rejected with HTTP 401
+  `missing_authorization`, forcing callers to manually promote API keys
+  into `jwtToken`. The SDK now sends `Bearer` for every credential
+  type — `apiKey: 'aidb_...'` Just Works.
+- **`Collection.vectorSearch` no longer crosses subsystems** (regression
+  guard for callers that relied on the 0.3.0 `client.collection(name)`
+  accessor with a vector collection: the search still hits the right
+  endpoint regardless of which accessor produced the handle).
+
+### Added
+
+- **`client.createVectorCollection({name, dimensions, distance_metric})`** —
+  posts to `POST /v1/vectors/collections` with the gateway's expected
+  body shape. The legacy `createCollection({name, vector_size, ...})`
+  silently dropped `vector_size` and posted to the document-store
+  subsystem, leaving the collection invisible to vector search.
+- **`client.vectorCollection(name)`** — synchronous typed handle for an
+  existing vector collection. Returns a `VectorCollection` wired to
+  `/v1/vectors/collections/{name}/...`, distinct from the document-store
+  `client.collection(name)` accessor.
+- **`VectorCollection` class** (`src/vector_collection.ts`) — explicit
+  vector-subsystem API surface: `insert(records)`, `search({vector, k,
+  filter?, includeMetadata?})`, `get(id)`, `delete(id|ids)`, `count()`,
+  `info()`. Wire paths target `/v1/vectors/collections/{name}/vectors`
+  and `/search`; envelope unwrapping matches the rest of the 0.3.0 SDK.
+- **`client.listVectorCollections()`** and
+  **`client.deleteVectorCollection(name)`** — sibling helpers for the
+  vector subsystem.
+- **`tests/live-smoke-v04.test.ts`** — gated on `AIDB_LIVE_TEST=1`,
+  runs the 12-test v0.4.0 validation suite against a live gateway.
+
+### Documentation
+
+- README now lists v1.6.5.2-ce as the verified-against gateway version.
+
+## 0.3.0 — 2026-05-18
+
+Wire-alignment release for the v1.6.5.1-ce gateway. Brings the SDK back into sync
+with the gateway response shapes and route prefixes that shipped in v1.6.x.
+
+### Fixed
+
+- `client.listCollections()` / `listCollectionsDetailed()` now correctly parse the
+  v1.6.x envelope `{ data: { items, total, page, page_size }, meta }`. Previously
+  the SDK looked for `data.collections` and threw
+  `Cannot read properties of undefined (reading 'map')`.
+- `client.graph.graphs.{list,create,get,delete}()` now hit `/v1/graph/graphs`
+  (the actual mount point); the old `/v1/graphs` paths 404'd against the v1.6.x
+  gateway.
+- `client.automl.listModels()` now tolerates the v1.6.x `{ data: [...], meta }`
+  envelope (was throwing `(data.models ?? data ?? []).map is not a function`
+  because `data` is an object, not an array).
+- `client.automl.getModel(id)` no longer hard-fails when the gateway's model
+  registry returns 404 for an id whose `/predict` endpoint still works (the
+  registry and the predict path can be out of sync after a recipe-loaded model
+  is hot-swapped). It now returns a stub `AutoMLModel` so `.predict()` /
+  `.evaluate()` still flow through.
+- `collection(name).vectorSearch({ vector, topK, filter? })` now posts to
+  `POST /v1/vectors/collections/{name}/search` with the gateway's `k` field
+  (was using the removed `/collections/{name}/vector_search` route with
+  `top_k`).
+
+### Added
+
+- `client.collection(name)` — synchronous accessor returning a `Collection`
+  handle without round-tripping to the gateway. Enables one-liner
+  `client.collection('docs').vectorSearch({...})`.
+- `tests/live-smoke.test.ts` — gated on `AIDB_LIVE_TEST=1`, runs the 9-test
+  validation suite against a live gateway so regressions in wire shapes are
+  caught in CI rather than at customer-install time.
+
+### Process
+
+- This is the first release where the public `SynapCores/nodejs-sdk` repository
+  reflects the code actually shipped to npm. Releases 0.1.0 / 0.2.0 / 0.2.1
+  were published directly from an internal workspace and the public repo
+  diverged by months. Going forward, all releases must be cut from this repo.
+
+## 0.2.1 — 2026-05-13
+
+- Internal release published from the workspace (not from this repo).
+
+## 0.2.0 — 2026-05-07
+
+- Internal release published from the workspace (not from this repo).
+- Migrated `/ai/*` routes to `/automl/*`, added Graph / NL2SQL / Filesystem /
+  Chat / Multimodal / System / Transactions / MCP sub-clients.
+
+## 0.1.0 — 2025-10-31
+
+- Initial release.

package/README.md

@@ -2,6 +2,16 @@
 
 Official Node.js/TypeScript SDK for SynapCores AI-Native Database Management System - A SQL 2026-compliant database with native tenant isolation, AI/ML functions, and multimedia support.
 
+> **0.4.0 — vector-subsystem + auth alignment with gateway v1.6.5.2-ce.**
+> Closes three wire-format gaps the OpenClaw v0.1.0 integration hit:
+> (a) `apiKey: 'aidb_...'` now sends `Authorization: Bearer` instead of the
+> rejected `X-API-Key` header; (b) `client.createVectorCollection({name,
+> dimensions, distance_metric})` provisions on the **vector subsystem**
+> (not the document-store one); (c) the new
+> `client.vectorCollection(name).insert(...)` / `.search(...)` round-trip
+> hits `/v1/vectors/collections/{name}/...` end-to-end. See CHANGELOG.md.
+> Verified against gateway v1.6.5.2-ce. Validation: 11/12 PASS.
+
 > **0.2.0 — gateway v1.5.0-ce alignment.** This release rewires every
 > module against the v1.5.0-ce route surface: AutoML moved from `/ai/*`
 > to `/automl/*`, vector ops collapsed onto `/vector-algebra/operation`,

package/dist/index.d.mts

@@ -151,6 +151,124 @@ declare class Collection {
     subscribe(options?: SubscriptionOptions): Promise<Subscription>;
 }
 
+/**
+ * VectorCollection — thin wrapper around the gateway's
+ * `/v1/vectors/collections/{name}/...` API.
+ *
+ * v0.4.0: introduced so users have an explicit, typed handle for the
+ * **vector subsystem** (separate from `/v1/collections/{name}`, the
+ * document-store world that `Collection` wraps). Mirror of the Python
+ * SDK's `synapcores.vector_collection.VectorCollection`.
+ *
+ * Get one via `client.vectorCollection(name)` for an existing collection,
+ * or `client.createVectorCollection({name, dimensions, distance_metric})`
+ * to provision a new one.
+ */
+
+type VectorDistanceMetric = 'cosine' | 'l2' | 'dot' | 'euclidean' | 'dot_product';
+/** Wire shape of a single vector going into the gateway. */
+interface VectorRecord {
+    id: string;
+    /** Embedding values. Length must match the collection's `dimensions`. */
+    values: number[];
+    /** Optional per-vector metadata returned on search hits. */
+    metadata?: Record<string, any>;
+}
+/** Options for `VectorCollection.search()`. */
+interface VectorCollectionSearchOptions {
+    vector: number[];
+    /** Number of nearest neighbours. */
+    k?: number;
+    /** Alias for `k` (parity with the document-store API). */
+    topK?: number;
+    /** Optional metadata filter forwarded as `filter` on the wire. */
+    filter?: Record<string, any>;
+    /** Whether the gateway should include metadata in each hit (default: true). */
+    includeMetadata?: boolean;
+}
+/** One match returned from `VectorCollection.search()`. */
+interface VectorHit {
+    id: string;
+    /** Cosine distance (lower = closer) for cosine metric; raw distance otherwise. */
+    score?: number;
+    distance?: number;
+    values?: number[];
+    metadata?: Record<string, any>;
+    [key: string]: any;
+}
+/** Shape returned by `VectorCollection.info()`. */
+interface VectorCollectionInfo {
+    name: string;
+    dimensions: number;
+    vector_count?: number;
+    distance_metric?: string;
+    index_type?: string;
+    [key: string]: any;
+}
+/** Shape returned by `client.createVectorCollection()`. */
+interface CreateVectorCollectionOptions {
+    name: string;
+    dimensions: number;
+    /** Distance metric. `cosine` is the gateway default. */
+    distance_metric?: VectorDistanceMetric;
+}
+declare class VectorCollection {
+    private readonly client;
+    readonly name: string;
+    constructor(client: SynapCores, name: string);
+    private get basePath();
+    /**
+     * Insert one or more vectors.
+     *
+     * Wire: `POST /v1/vectors/collections/{name}/vectors` with
+     * `{ vectors: [{ id, values, metadata }] }`.
+     *
+     * Accepts either a single record or an array — the SDK always sends
+     * the wrapped `{ vectors: [...] }` envelope the gateway expects.
+     */
+    insert(records: VectorRecord | VectorRecord[]): Promise<any>;
+    /**
+     * k-NN search over the vector collection.
+     *
+     * Wire: `POST /v1/vectors/collections/{name}/search` with
+     * `{ vector, k, include_metadata, filter? }`.
+     *
+     * Returns the bare array of hits — gateway envelope (`{data: [...]}`) is
+     * unwrapped automatically for parity with `Collection.vectorSearch`.
+     */
+    search(options: VectorCollectionSearchOptions): Promise<VectorHit[]>;
+    /**
+     * Fetch a single vector by id.
+     *
+     * Wire: `GET /v1/vectors/collections/{name}/vectors/{id}`. Returns the
+     * gateway payload `{ id, values, metadata }` (envelope unwrapped) or
+     * `null` on 404.
+     */
+    get(id: string): Promise<VectorHit | null>;
+    /**
+     * Delete one or more vectors by id.
+     *
+     * Single-id wire: `DELETE /v1/vectors/collections/{name}/vectors/{id}`.
+     * Bulk wire: `DELETE /v1/vectors/collections/{name}/vectors` with
+     * `{ ids: [...] }` body.
+     */
+    delete(ids: string | string[]): Promise<any>;
+    /**
+     * Vector count.
+     *
+     * Wire: `GET /v1/vectors/collections/{name}/count` if the gateway
+     * exposes it, otherwise falls back to `info().vector_count`.
+     */
+    count(): Promise<number>;
+    /**
+     * Collection metadata.
+     *
+     * Wire: `GET /v1/vectors/collections/{name}` returning
+     * `{ name, dimensions, vector_count, distance_metric, index_type }`.
+     */
+    info(): Promise<VectorCollectionInfo>;
+}
+
 /**
  * Type definitions for AutoML
  */
@@ -2925,12 +3043,25 @@ declare class SynapCores {
      */
     createCollectionWithSchema(request: CreateCollectionRequest): Promise<Collection>;
     getCollection(name: string): Promise<Collection>;
+    /**
+     * Synchronous accessor that returns a Collection handle without round-tripping
+     * to the gateway. Use this when you already know the collection exists and just
+     * want to issue a vectorSearch / search / insert against it.
+     *
+     * v0.3.0: added so `client.collection(name).vectorSearch(...)` works without
+     * a preceding await on getCollection().
+     */
+    collection(name: string): Collection;
     /**
      * List collections (legacy method for backward compatibility)
      */
     listCollections(): Promise<string[]>;
     /**
      * List collections with detailed information matching the database integration guide format
+     *
+     * v0.3.0: gateway returns an envelope { data: { items, total, page, page_size, ... }, meta }.
+     * We normalise that into the SDK's { collections, total, page, pageSize } shape and also
+     * accept legacy { collections: [...] } / bare arrays for forward-compat.
      */
     listCollectionsDetailed(options?: {
         page?: number;
@@ -2941,6 +3072,45 @@ declare class SynapCores {
     }): Promise<ListCollectionsResponse>;
     getDocuments(collectionName: string, page: number, pageSize: number): Promise<Document[]>;
     deleteCollection(name: string): Promise<void>;
+    private readonly vectorCollectionsCache;
+    /**
+     * Create a vector collection.
+     *
+     * Wire: `POST /v1/vectors/collections` with
+     * `{ name, dimensions, distance_metric }`. Distinct from
+     * `createCollection`, which targets the document-store subsystem.
+     *
+     * @example
+     *   const coll = await client.createVectorCollection({
+     *     name: 'memory_v1', dimensions: 1536, distance_metric: 'cosine',
+     *   });
+     *   await coll.insert({ id: 'v1', values: [...], metadata: { ... } });
+     */
+    createVectorCollection(options: CreateVectorCollectionOptions): Promise<VectorCollection>;
+    /**
+     * Synchronous accessor for an existing vector collection. Does not
+     * round-trip to the gateway — use `createVectorCollection` if you
+     * need to provision the collection first, or `listVectorCollections`
+     * to confirm existence.
+     *
+     * v0.4.0 split: this targets the **vector subsystem**
+     * (`/v1/vectors/collections/{name}`). `client.collection(name)` still
+     * returns a document-store `Collection` for the legacy subsystem.
+     */
+    vectorCollection(name: string): VectorCollection;
+    /**
+     * List vector collections.
+     *
+     * Wire: `GET /v1/vectors/collections`. Returns the bare array of
+     * collection-info objects (envelope unwrapped).
+     */
+    listVectorCollections(): Promise<VectorCollectionInfo[]>;
+    /**
+     * Delete a vector collection.
+     *
+     * Wire: `DELETE /v1/vectors/collections/{name}`.
+     */
+    deleteVectorCollection(name: string): Promise<void>;
     /**
      * Execute SQL query (legacy method for backward compatibility)
      * @deprecated Use executeQuery for new code
@@ -3304,6 +3474,6 @@ declare class BatchOperationError extends SynapCoresError {
  * Official SDK for SynapCores AI-Native Database Management System.
  */
 
-declare const VERSION = "0.2.0";
+declare const VERSION = "0.4.0";
 
-export { type APIKeyInfo, type APIKeyStats, type AlterTableOptions, type AnalyzeOptions, type AsyncTrainOptions, type AuthConfig, AuthenticationError, AutoMLClient, AutoMLModel, type Backup, BackupClient, type BackupMetrics, type BackupOptions, type BackupSchedule, type BackupStatus, type BackupVerificationResult, type BatchDeleteOptions, type BatchInsertOptions, BatchOperationError, type BatchQueryRequest, type BatchQueryResponse, type BatchQueryResult, type BatchResult, type BatchUpdateOptions, type BeginTransactionOptions, type BulkImportOptions, type BulkImportResult, type CTEDefinition, type ChangeOperation, type ChatCacheStats, ChatClient, type ChatMessage, type ChatModelInfo, type ChatSession, type ChatStreamChunk, type ChatSuggestion, type ChatSuggestionsOptions, type ChatSystemPrompt, type ChatTool, Collection, type CollectionFieldDefinition, type CollectionIndexDefinition, type CollectionInfo, type CollectionSchema, type CollectionSchemaDefinition, type CollectionStats, type ColumnConstraint, type ColumnDefinition, type ColumnInfo, ConnectionError, type ConnectionPool, type ConstraintInfo, type CreateAPIKeyRequest, type CreateAPIKeyResponse, type CreateChatSessionOptions, type CreateCollectionRequest, type CreateCollectionResponse, type CreateFsCollectionOptions, type CreateIntegrationOptions, type CreateRecipeOptions, type CreateScheduleOptions, type CreateTableOptions, type CreateWebhookOptions, type CypherProfileResult, type CypherResult, type DataValidationOptions, type DataValidationResult, type Document, type EmbedOptions, type Entity, type EvaluationResult, type ExecuteIntegrationOptions, type ExecuteQueryRequest, type ExecuteRecipeOptions, type ExportJobStatus, type ExportOptions, type ExportResult, FilesystemCollectionsClient, type ForeignKeyReference, type FsCollection, type FsDocument, type FsProgressEvent, type GenerateRecipeOptions, type GeneratedRecipe, type GraphAlgorithmName, type GraphAlgorithmRequest, type GraphAlgorithmResult, GraphClient, type GraphEdge, type GraphExtractRequest, type GraphExtractResult, type GraphNode, type GraphSummary, type HybridSearchOptions, type ImportError, ImportExportClient, type ImportJobStatus, type ImportOptions, type ImportResult, type ValidationError$1 as ImportValidationError, type ValidationWarning as ImportValidationWarning, type IndexDefinition, type IndexInfo, type InsertResult, type Integration, IntegrationClient, type IntegrationConfig, type IntegrationEvent, type IntegrationExecutionResult, type IntegrationLog, type IntegrationStats, type IntegrationWebhook, type KNNSearchOptions, type ListAPIKeysResponse, type ListBackupsOptions, type ListCollectionsResponse, type ListIntegrationsOptions, type ListMultimediaResponse, type ListRecipesOptions, type ListTrainingJobsOptions, type LoginRequest, type LoginResponse, McpClient, type McpInfo, type McpRequest, type McpResponse, type ModelInfo, type MultimediaInfo, MultimodalClient, type MultimodalEmbedResult, type MultimodalInput, type MultimodalJoinOptions, type MultimodalJoinResult, type MultimodalSearchHit, type MultimodalSearchOptions, type MultimodalSimilarityOptions, type MultimodalSimilarityResult, NL2SqlClient, type NLPAnalysis, NLPClient, type Nl2SqlAskOptions, type Nl2SqlAskResult, type Nl2SqlHistoryEntry, type Nl2SqlSchemaContext, type Nl2SqlValidateResult, NotFoundError, type OAuth2Config, type PredictResult, type PreparedStatement, type PreparedStatementOptions, type QueryColumn, type QueryOptions, type QueryPerformance, type QueryResult, type RangeSearchOptions, RateLimitError, type Recipe, RecipeClient, type RecipeExecutionResult, type RecipeInfo, type RecipeParameter, type RefreshResponse, type RegisterRequest, type RegisterResponse, type RelationshipInfo, type RestoreOptions, type RestoreResult, type RestoreStatus, type RetryConfig, SQLError, SchemaClient, type SchemaStatistics, type ValidationError$2 as SchemaValidationError, type SearchOptions, type SearchResult, type SendChatOptions, type SendChatResult, type Sentiment, ServerError, type StorageConfig, Subscription, type SubscriptionEvent, type SubscriptionOptions, type SummarizeOptions, SynapCores, type SynapCoresConfig, SynapCoresError, SystemClient, type TableConstraint, type TableInfo, type TableSchema, type TestIntegrationOptions, type TestIntegrationResult, TimeoutError, type TrainOptions, type TrainingJob, type TrainingMetrics, type TransactionContext, TransactionError, type TransactionOptions, TransactionsClient, Tx, type TxHistoryEntry, type TxQueryResult, type UpdateOptions, type UploadMultimediaRequest, VERSION, ValidationError, type ValidationResult, type ValidationWarning$1 as ValidationWarning, type Vector, type VectorArithmeticResult, VectorError, type VectorSearchOptions, type VectorSearchResult, type VectorSimilarityResult, type VisionConfig, type VisionTestResult, type WindowFunctionOptions };
+export { type APIKeyInfo, type APIKeyStats, type AlterTableOptions, type AnalyzeOptions, type AsyncTrainOptions, type AuthConfig, AuthenticationError, AutoMLClient, AutoMLModel, type Backup, BackupClient, type BackupMetrics, type BackupOptions, type BackupSchedule, type BackupStatus, type BackupVerificationResult, type BatchDeleteOptions, type BatchInsertOptions, BatchOperationError, type BatchQueryRequest, type BatchQueryResponse, type BatchQueryResult, type BatchResult, type BatchUpdateOptions, type BeginTransactionOptions, type BulkImportOptions, type BulkImportResult, type CTEDefinition, type ChangeOperation, type ChatCacheStats, ChatClient, type ChatMessage, type ChatModelInfo, type ChatSession, type ChatStreamChunk, type ChatSuggestion, type ChatSuggestionsOptions, type ChatSystemPrompt, type ChatTool, Collection, type CollectionFieldDefinition, type CollectionIndexDefinition, type CollectionInfo, type CollectionSchema, type CollectionSchemaDefinition, type CollectionStats, type ColumnConstraint, type ColumnDefinition, type ColumnInfo, ConnectionError, type ConnectionPool, type ConstraintInfo, type CreateAPIKeyRequest, type CreateAPIKeyResponse, type CreateChatSessionOptions, type CreateCollectionRequest, type CreateCollectionResponse, type CreateFsCollectionOptions, type CreateIntegrationOptions, type CreateRecipeOptions, type CreateScheduleOptions, type CreateTableOptions, type CreateVectorCollectionOptions, type CreateWebhookOptions, type CypherProfileResult, type CypherResult, type DataValidationOptions, type DataValidationResult, type Document, type EmbedOptions, type Entity, type EvaluationResult, type ExecuteIntegrationOptions, type ExecuteQueryRequest, type ExecuteRecipeOptions, type ExportJobStatus, type ExportOptions, type ExportResult, FilesystemCollectionsClient, type ForeignKeyReference, type FsCollection, type FsDocument, type FsProgressEvent, type GenerateRecipeOptions, type GeneratedRecipe, type GraphAlgorithmName, type GraphAlgorithmRequest, type GraphAlgorithmResult, GraphClient, type GraphEdge, type GraphExtractRequest, type GraphExtractResult, type GraphNode, type GraphSummary, type HybridSearchOptions, type ImportError, ImportExportClient, type ImportJobStatus, type ImportOptions, type ImportResult, type ValidationError$1 as ImportValidationError, type ValidationWarning as ImportValidationWarning, type IndexDefinition, type IndexInfo, type InsertResult, type Integration, IntegrationClient, type IntegrationConfig, type IntegrationEvent, type IntegrationExecutionResult, type IntegrationLog, type IntegrationStats, type IntegrationWebhook, type KNNSearchOptions, type ListAPIKeysResponse, type ListBackupsOptions, type ListCollectionsResponse, type ListIntegrationsOptions, type ListMultimediaResponse, type ListRecipesOptions, type ListTrainingJobsOptions, type LoginRequest, type LoginResponse, McpClient, type McpInfo, type McpRequest, type McpResponse, type ModelInfo, type MultimediaInfo, MultimodalClient, type MultimodalEmbedResult, type MultimodalInput, type MultimodalJoinOptions, type MultimodalJoinResult, type MultimodalSearchHit, type MultimodalSearchOptions, type MultimodalSimilarityOptions, type MultimodalSimilarityResult, NL2SqlClient, type NLPAnalysis, NLPClient, type Nl2SqlAskOptions, type Nl2SqlAskResult, type Nl2SqlHistoryEntry, type Nl2SqlSchemaContext, type Nl2SqlValidateResult, NotFoundError, type OAuth2Config, type PredictResult, type PreparedStatement, type PreparedStatementOptions, type QueryColumn, type QueryOptions, type QueryPerformance, type QueryResult, type RangeSearchOptions, RateLimitError, type Recipe, RecipeClient, type RecipeExecutionResult, type RecipeInfo, type RecipeParameter, type RefreshResponse, type RegisterRequest, type RegisterResponse, type RelationshipInfo, type RestoreOptions, type RestoreResult, type RestoreStatus, type RetryConfig, SQLError, SchemaClient, type SchemaStatistics, type ValidationError$2 as SchemaValidationError, type SearchOptions, type SearchResult, type SendChatOptions, type SendChatResult, type Sentiment, ServerError, type StorageConfig, Subscription, type SubscriptionEvent, type SubscriptionOptions, type SummarizeOptions, SynapCores, type SynapCoresConfig, SynapCoresError, SystemClient, type TableConstraint, type TableInfo, type TableSchema, type TestIntegrationOptions, type TestIntegrationResult, TimeoutError, type TrainOptions, type TrainingJob, type TrainingMetrics, type TransactionContext, TransactionError, type TransactionOptions, TransactionsClient, Tx, type TxHistoryEntry, type TxQueryResult, type UpdateOptions, type UploadMultimediaRequest, VERSION, ValidationError, type ValidationResult, type ValidationWarning$1 as ValidationWarning, type Vector, type VectorArithmeticResult, VectorCollection, type VectorCollectionInfo, type VectorCollectionSearchOptions, type VectorDistanceMetric, VectorError, type VectorHit, type VectorRecord, type VectorSearchOptions, type VectorSearchResult, type VectorSimilarityResult, type VisionConfig, type VisionTestResult, type WindowFunctionOptions };

package/dist/index.d.ts

@@ -151,6 +151,124 @@ declare class Collection {
     subscribe(options?: SubscriptionOptions): Promise<Subscription>;
 }
 
+/**
+ * VectorCollection — thin wrapper around the gateway's
+ * `/v1/vectors/collections/{name}/...` API.
+ *
+ * v0.4.0: introduced so users have an explicit, typed handle for the
+ * **vector subsystem** (separate from `/v1/collections/{name}`, the
+ * document-store world that `Collection` wraps). Mirror of the Python
+ * SDK's `synapcores.vector_collection.VectorCollection`.
+ *
+ * Get one via `client.vectorCollection(name)` for an existing collection,
+ * or `client.createVectorCollection({name, dimensions, distance_metric})`
+ * to provision a new one.
+ */
+
+type VectorDistanceMetric = 'cosine' | 'l2' | 'dot' | 'euclidean' | 'dot_product';
+/** Wire shape of a single vector going into the gateway. */
+interface VectorRecord {
+    id: string;
+    /** Embedding values. Length must match the collection's `dimensions`. */
+    values: number[];
+    /** Optional per-vector metadata returned on search hits. */
+    metadata?: Record<string, any>;
+}
+/** Options for `VectorCollection.search()`. */
+interface VectorCollectionSearchOptions {
+    vector: number[];
+    /** Number of nearest neighbours. */
+    k?: number;
+    /** Alias for `k` (parity with the document-store API). */
+    topK?: number;
+    /** Optional metadata filter forwarded as `filter` on the wire. */
+    filter?: Record<string, any>;
+    /** Whether the gateway should include metadata in each hit (default: true). */
+    includeMetadata?: boolean;
+}
+/** One match returned from `VectorCollection.search()`. */
+interface VectorHit {
+    id: string;
+    /** Cosine distance (lower = closer) for cosine metric; raw distance otherwise. */
+    score?: number;
+    distance?: number;
+    values?: number[];
+    metadata?: Record<string, any>;
+    [key: string]: any;
+}
+/** Shape returned by `VectorCollection.info()`. */
+interface VectorCollectionInfo {
+    name: string;
+    dimensions: number;
+    vector_count?: number;
+    distance_metric?: string;
+    index_type?: string;
+    [key: string]: any;
+}
+/** Shape returned by `client.createVectorCollection()`. */
+interface CreateVectorCollectionOptions {
+    name: string;
+    dimensions: number;
+    /** Distance metric. `cosine` is the gateway default. */
+    distance_metric?: VectorDistanceMetric;
+}
+declare class VectorCollection {
+    private readonly client;
+    readonly name: string;
+    constructor(client: SynapCores, name: string);
+    private get basePath();
+    /**
+     * Insert one or more vectors.
+     *
+     * Wire: `POST /v1/vectors/collections/{name}/vectors` with
+     * `{ vectors: [{ id, values, metadata }] }`.
+     *
+     * Accepts either a single record or an array — the SDK always sends
+     * the wrapped `{ vectors: [...] }` envelope the gateway expects.
+     */
+    insert(records: VectorRecord | VectorRecord[]): Promise<any>;
+    /**
+     * k-NN search over the vector collection.
+     *
+     * Wire: `POST /v1/vectors/collections/{name}/search` with
+     * `{ vector, k, include_metadata, filter? }`.
+     *
+     * Returns the bare array of hits — gateway envelope (`{data: [...]}`) is
+     * unwrapped automatically for parity with `Collection.vectorSearch`.
+     */
+    search(options: VectorCollectionSearchOptions): Promise<VectorHit[]>;
+    /**
+     * Fetch a single vector by id.
+     *
+     * Wire: `GET /v1/vectors/collections/{name}/vectors/{id}`. Returns the
+     * gateway payload `{ id, values, metadata }` (envelope unwrapped) or
+     * `null` on 404.
+     */
+    get(id: string): Promise<VectorHit | null>;
+    /**
+     * Delete one or more vectors by id.
+     *
+     * Single-id wire: `DELETE /v1/vectors/collections/{name}/vectors/{id}`.
+     * Bulk wire: `DELETE /v1/vectors/collections/{name}/vectors` with
+     * `{ ids: [...] }` body.
+     */
+    delete(ids: string | string[]): Promise<any>;
+    /**
+     * Vector count.
+     *
+     * Wire: `GET /v1/vectors/collections/{name}/count` if the gateway
+     * exposes it, otherwise falls back to `info().vector_count`.
+     */
+    count(): Promise<number>;
+    /**
+     * Collection metadata.
+     *
+     * Wire: `GET /v1/vectors/collections/{name}` returning
+     * `{ name, dimensions, vector_count, distance_metric, index_type }`.
+     */
+    info(): Promise<VectorCollectionInfo>;
+}
+
 /**
  * Type definitions for AutoML
  */
@@ -2925,12 +3043,25 @@ declare class SynapCores {
      */
     createCollectionWithSchema(request: CreateCollectionRequest): Promise<Collection>;
     getCollection(name: string): Promise<Collection>;
+    /**
+     * Synchronous accessor that returns a Collection handle without round-tripping
+     * to the gateway. Use this when you already know the collection exists and just
+     * want to issue a vectorSearch / search / insert against it.
+     *
+     * v0.3.0: added so `client.collection(name).vectorSearch(...)` works without
+     * a preceding await on getCollection().
+     */
+    collection(name: string): Collection;
     /**
      * List collections (legacy method for backward compatibility)
      */
     listCollections(): Promise<string[]>;
     /**
      * List collections with detailed information matching the database integration guide format
+     *
+     * v0.3.0: gateway returns an envelope { data: { items, total, page, page_size, ... }, meta }.
+     * We normalise that into the SDK's { collections, total, page, pageSize } shape and also
+     * accept legacy { collections: [...] } / bare arrays for forward-compat.
      */
     listCollectionsDetailed(options?: {
         page?: number;
@@ -2941,6 +3072,45 @@ declare class SynapCores {
     }): Promise<ListCollectionsResponse>;
     getDocuments(collectionName: string, page: number, pageSize: number): Promise<Document[]>;
     deleteCollection(name: string): Promise<void>;
+    private readonly vectorCollectionsCache;
+    /**
+     * Create a vector collection.
+     *
+     * Wire: `POST /v1/vectors/collections` with
+     * `{ name, dimensions, distance_metric }`. Distinct from
+     * `createCollection`, which targets the document-store subsystem.
+     *
+     * @example
+     *   const coll = await client.createVectorCollection({
+     *     name: 'memory_v1', dimensions: 1536, distance_metric: 'cosine',
+     *   });
+     *   await coll.insert({ id: 'v1', values: [...], metadata: { ... } });
+     */
+    createVectorCollection(options: CreateVectorCollectionOptions): Promise<VectorCollection>;
+    /**
+     * Synchronous accessor for an existing vector collection. Does not
+     * round-trip to the gateway — use `createVectorCollection` if you
+     * need to provision the collection first, or `listVectorCollections`
+     * to confirm existence.
+     *
+     * v0.4.0 split: this targets the **vector subsystem**
+     * (`/v1/vectors/collections/{name}`). `client.collection(name)` still
+     * returns a document-store `Collection` for the legacy subsystem.
+     */
+    vectorCollection(name: string): VectorCollection;
+    /**
+     * List vector collections.
+     *
+     * Wire: `GET /v1/vectors/collections`. Returns the bare array of
+     * collection-info objects (envelope unwrapped).
+     */
+    listVectorCollections(): Promise<VectorCollectionInfo[]>;
+    /**
+     * Delete a vector collection.
+     *
+     * Wire: `DELETE /v1/vectors/collections/{name}`.
+     */
+    deleteVectorCollection(name: string): Promise<void>;
     /**
      * Execute SQL query (legacy method for backward compatibility)
      * @deprecated Use executeQuery for new code
@@ -3304,6 +3474,6 @@ declare class BatchOperationError extends SynapCoresError {
  * Official SDK for SynapCores AI-Native Database Management System.
  */
 
-declare const VERSION = "0.2.0";
+declare const VERSION = "0.4.0";
 
-export { type APIKeyInfo, type APIKeyStats, type AlterTableOptions, type AnalyzeOptions, type AsyncTrainOptions, type AuthConfig, AuthenticationError, AutoMLClient, AutoMLModel, type Backup, BackupClient, type BackupMetrics, type BackupOptions, type BackupSchedule, type BackupStatus, type BackupVerificationResult, type BatchDeleteOptions, type BatchInsertOptions, BatchOperationError, type BatchQueryRequest, type BatchQueryResponse, type BatchQueryResult, type BatchResult, type BatchUpdateOptions, type BeginTransactionOptions, type BulkImportOptions, type BulkImportResult, type CTEDefinition, type ChangeOperation, type ChatCacheStats, ChatClient, type ChatMessage, type ChatModelInfo, type ChatSession, type ChatStreamChunk, type ChatSuggestion, type ChatSuggestionsOptions, type ChatSystemPrompt, type ChatTool, Collection, type CollectionFieldDefinition, type CollectionIndexDefinition, type CollectionInfo, type CollectionSchema, type CollectionSchemaDefinition, type CollectionStats, type ColumnConstraint, type ColumnDefinition, type ColumnInfo, ConnectionError, type ConnectionPool, type ConstraintInfo, type CreateAPIKeyRequest, type CreateAPIKeyResponse, type CreateChatSessionOptions, type CreateCollectionRequest, type CreateCollectionResponse, type CreateFsCollectionOptions, type CreateIntegrationOptions, type CreateRecipeOptions, type CreateScheduleOptions, type CreateTableOptions, type CreateWebhookOptions, type CypherProfileResult, type CypherResult, type DataValidationOptions, type DataValidationResult, type Document, type EmbedOptions, type Entity, type EvaluationResult, type ExecuteIntegrationOptions, type ExecuteQueryRequest, type ExecuteRecipeOptions, type ExportJobStatus, type ExportOptions, type ExportResult, FilesystemCollectionsClient, type ForeignKeyReference, type FsCollection, type FsDocument, type FsProgressEvent, type GenerateRecipeOptions, type GeneratedRecipe, type GraphAlgorithmName, type GraphAlgorithmRequest, type GraphAlgorithmResult, GraphClient, type GraphEdge, type GraphExtractRequest, type GraphExtractResult, type GraphNode, type GraphSummary, type HybridSearchOptions, type ImportError, ImportExportClient, type ImportJobStatus, type ImportOptions, type ImportResult, type ValidationError$1 as ImportValidationError, type ValidationWarning as ImportValidationWarning, type IndexDefinition, type IndexInfo, type InsertResult, type Integration, IntegrationClient, type IntegrationConfig, type IntegrationEvent, type IntegrationExecutionResult, type IntegrationLog, type IntegrationStats, type IntegrationWebhook, type KNNSearchOptions, type ListAPIKeysResponse, type ListBackupsOptions, type ListCollectionsResponse, type ListIntegrationsOptions, type ListMultimediaResponse, type ListRecipesOptions, type ListTrainingJobsOptions, type LoginRequest, type LoginResponse, McpClient, type McpInfo, type McpRequest, type McpResponse, type ModelInfo, type MultimediaInfo, MultimodalClient, type MultimodalEmbedResult, type MultimodalInput, type MultimodalJoinOptions, type MultimodalJoinResult, type MultimodalSearchHit, type MultimodalSearchOptions, type MultimodalSimilarityOptions, type MultimodalSimilarityResult, NL2SqlClient, type NLPAnalysis, NLPClient, type Nl2SqlAskOptions, type Nl2SqlAskResult, type Nl2SqlHistoryEntry, type Nl2SqlSchemaContext, type Nl2SqlValidateResult, NotFoundError, type OAuth2Config, type PredictResult, type PreparedStatement, type PreparedStatementOptions, type QueryColumn, type QueryOptions, type QueryPerformance, type QueryResult, type RangeSearchOptions, RateLimitError, type Recipe, RecipeClient, type RecipeExecutionResult, type RecipeInfo, type RecipeParameter, type RefreshResponse, type RegisterRequest, type RegisterResponse, type RelationshipInfo, type RestoreOptions, type RestoreResult, type RestoreStatus, type RetryConfig, SQLError, SchemaClient, type SchemaStatistics, type ValidationError$2 as SchemaValidationError, type SearchOptions, type SearchResult, type SendChatOptions, type SendChatResult, type Sentiment, ServerError, type StorageConfig, Subscription, type SubscriptionEvent, type SubscriptionOptions, type SummarizeOptions, SynapCores, type SynapCoresConfig, SynapCoresError, SystemClient, type TableConstraint, type TableInfo, type TableSchema, type TestIntegrationOptions, type TestIntegrationResult, TimeoutError, type TrainOptions, type TrainingJob, type TrainingMetrics, type TransactionContext, TransactionError, type TransactionOptions, TransactionsClient, Tx, type TxHistoryEntry, type TxQueryResult, type UpdateOptions, type UploadMultimediaRequest, VERSION, ValidationError, type ValidationResult, type ValidationWarning$1 as ValidationWarning, type Vector, type VectorArithmeticResult, VectorError, type VectorSearchOptions, type VectorSearchResult, type VectorSimilarityResult, type VisionConfig, type VisionTestResult, type WindowFunctionOptions };
+export { type APIKeyInfo, type APIKeyStats, type AlterTableOptions, type AnalyzeOptions, type AsyncTrainOptions, type AuthConfig, AuthenticationError, AutoMLClient, AutoMLModel, type Backup, BackupClient, type BackupMetrics, type BackupOptions, type BackupSchedule, type BackupStatus, type BackupVerificationResult, type BatchDeleteOptions, type BatchInsertOptions, BatchOperationError, type BatchQueryRequest, type BatchQueryResponse, type BatchQueryResult, type BatchResult, type BatchUpdateOptions, type BeginTransactionOptions, type BulkImportOptions, type BulkImportResult, type CTEDefinition, type ChangeOperation, type ChatCacheStats, ChatClient, type ChatMessage, type ChatModelInfo, type ChatSession, type ChatStreamChunk, type ChatSuggestion, type ChatSuggestionsOptions, type ChatSystemPrompt, type ChatTool, Collection, type CollectionFieldDefinition, type CollectionIndexDefinition, type CollectionInfo, type CollectionSchema, type CollectionSchemaDefinition, type CollectionStats, type ColumnConstraint, type ColumnDefinition, type ColumnInfo, ConnectionError, type ConnectionPool, type ConstraintInfo, type CreateAPIKeyRequest, type CreateAPIKeyResponse, type CreateChatSessionOptions, type CreateCollectionRequest, type CreateCollectionResponse, type CreateFsCollectionOptions, type CreateIntegrationOptions, type CreateRecipeOptions, type CreateScheduleOptions, type CreateTableOptions, type CreateVectorCollectionOptions, type CreateWebhookOptions, type CypherProfileResult, type CypherResult, type DataValidationOptions, type DataValidationResult, type Document, type EmbedOptions, type Entity, type EvaluationResult, type ExecuteIntegrationOptions, type ExecuteQueryRequest, type ExecuteRecipeOptions, type ExportJobStatus, type ExportOptions, type ExportResult, FilesystemCollectionsClient, type ForeignKeyReference, type FsCollection, type FsDocument, type FsProgressEvent, type GenerateRecipeOptions, type GeneratedRecipe, type GraphAlgorithmName, type GraphAlgorithmRequest, type GraphAlgorithmResult, GraphClient, type GraphEdge, type GraphExtractRequest, type GraphExtractResult, type GraphNode, type GraphSummary, type HybridSearchOptions, type ImportError, ImportExportClient, type ImportJobStatus, type ImportOptions, type ImportResult, type ValidationError$1 as ImportValidationError, type ValidationWarning as ImportValidationWarning, type IndexDefinition, type IndexInfo, type InsertResult, type Integration, IntegrationClient, type IntegrationConfig, type IntegrationEvent, type IntegrationExecutionResult, type IntegrationLog, type IntegrationStats, type IntegrationWebhook, type KNNSearchOptions, type ListAPIKeysResponse, type ListBackupsOptions, type ListCollectionsResponse, type ListIntegrationsOptions, type ListMultimediaResponse, type ListRecipesOptions, type ListTrainingJobsOptions, type LoginRequest, type LoginResponse, McpClient, type McpInfo, type McpRequest, type McpResponse, type ModelInfo, type MultimediaInfo, MultimodalClient, type MultimodalEmbedResult, type MultimodalInput, type MultimodalJoinOptions, type MultimodalJoinResult, type MultimodalSearchHit, type MultimodalSearchOptions, type MultimodalSimilarityOptions, type MultimodalSimilarityResult, NL2SqlClient, type NLPAnalysis, NLPClient, type Nl2SqlAskOptions, type Nl2SqlAskResult, type Nl2SqlHistoryEntry, type Nl2SqlSchemaContext, type Nl2SqlValidateResult, NotFoundError, type OAuth2Config, type PredictResult, type PreparedStatement, type PreparedStatementOptions, type QueryColumn, type QueryOptions, type QueryPerformance, type QueryResult, type RangeSearchOptions, RateLimitError, type Recipe, RecipeClient, type RecipeExecutionResult, type RecipeInfo, type RecipeParameter, type RefreshResponse, type RegisterRequest, type RegisterResponse, type RelationshipInfo, type RestoreOptions, type RestoreResult, type RestoreStatus, type RetryConfig, SQLError, SchemaClient, type SchemaStatistics, type ValidationError$2 as SchemaValidationError, type SearchOptions, type SearchResult, type SendChatOptions, type SendChatResult, type Sentiment, ServerError, type StorageConfig, Subscription, type SubscriptionEvent, type SubscriptionOptions, type SummarizeOptions, SynapCores, type SynapCoresConfig, SynapCoresError, SystemClient, type TableConstraint, type TableInfo, type TableSchema, type TestIntegrationOptions, type TestIntegrationResult, TimeoutError, type TrainOptions, type TrainingJob, type TrainingMetrics, type TransactionContext, TransactionError, type TransactionOptions, TransactionsClient, Tx, type TxHistoryEntry, type TxQueryResult, type UpdateOptions, type UploadMultimediaRequest, VERSION, ValidationError, type ValidationResult, type ValidationWarning$1 as ValidationWarning, type Vector, type VectorArithmeticResult, VectorCollection, type VectorCollectionInfo, type VectorCollectionSearchOptions, type VectorDistanceMetric, VectorError, type VectorHit, type VectorRecord, type VectorSearchOptions, type VectorSearchResult, type VectorSimilarityResult, type VisionConfig, type VisionTestResult, type WindowFunctionOptions };