@synapcores/sdk 0.2.1 → 0.3.0

package/CHANGELOG.md

@@ -0,0 +1,61 @@
+# Changelog
+
+All notable changes to `@synapcores/sdk` are documented here.
+This project follows [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
+
+## 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/dist/index.d.mts

@@ -2925,12 +2925,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;
@@ -3304,6 +3317,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.3.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 };

package/dist/index.d.ts

@@ -2925,12 +2925,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;
@@ -3304,6 +3317,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.3.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 };

package/dist/index.js

@@ -316,20 +316,20 @@ var Collection = class {
   }
   async vectorSearch(options) {
     const { data } = await this.client._getHttpClient().post(
-      `${this.basePath}/vector_search`,
+      `/vectors/collections/${this.name}/search`,
       {
         vector: options.vector,
-        field: options.field || "embedding",
-        top_k: options.topK || 10,
+        k: options.topK || 10,
         filter: options.filter,
-        distance_metric: options.distanceMetric || "cosine",
-        include_metadata: options.includeMetadata
+        include_metadata: options.includeMetadata !== false
       }
     );
+    const inner = data?.data ?? data;
+    const matches = Array.isArray(inner) ? inner : inner?.matches ?? inner?.results ?? inner?.documents ?? data?.matches ?? data?.results ?? data?.documents ?? [];
     return {
-      documents: data.documents,
-      total: data.total,
-      tookMs: data.took_ms
+      documents: matches,
+      total: (inner && !Array.isArray(inner) ? inner.total : void 0) ?? matches.length,
+      tookMs: (inner && !Array.isArray(inner) ? inner.took_ms : void 0) ?? data?.took_ms
     };
   }
   async query(options = {}) {
@@ -467,27 +467,48 @@ var AutoMLClient = class {
     return new AutoMLModel(this, modelInfo);
   }
   async getModel(modelId) {
-    const { data } = await this.synapCores._getHttpClient().get(
-      `/automl/models/${modelId}`
-    );
-    const modelInfo = {
-      id: data.id,
-      name: data.name,
-      task: data.task,
-      status: data.status,
-      accuracy: data.accuracy,
-      createdAt: new Date(data.created_at ?? Date.now()),
-      updatedAt: data.updated_at ? new Date(data.updated_at) : void 0,
-      config: data.config ?? {}
-    };
-    return new AutoMLModel(this, modelInfo);
+    try {
+      const { data } = await this.synapCores._getHttpClient().get(
+        `/automl/models/${modelId}`
+      );
+      const m = data?.data ?? data;
+      const modelInfo = {
+        id: m.id ?? modelId,
+        name: m.name ?? modelId,
+        task: m.task,
+        status: m.status,
+        accuracy: m.accuracy,
+        createdAt: new Date(m.created_at ?? Date.now()),
+        updatedAt: m.updated_at ? new Date(m.updated_at) : void 0,
+        config: m.config ?? {}
+      };
+      return new AutoMLModel(this, modelInfo);
+    } catch (err) {
+      const status = err?.statusCode ?? err?.response?.status;
+      const code = err?.code;
+      if (status === 404 || code === "NOT_FOUND") {
+        const modelInfo = {
+          id: modelId,
+          name: modelId,
+          task: void 0,
+          status: "unknown",
+          accuracy: void 0,
+          createdAt: /* @__PURE__ */ new Date(),
+          updatedAt: void 0,
+          config: {}
+        };
+        return new AutoMLModel(this, modelInfo);
+      }
+      throw err;
+    }
   }
   async listModels(filters) {
     const { data } = await this.synapCores._getHttpClient().get("/automl/models", {
       params: filters
     });
-    return (data.models ?? data ?? []).map((model) => ({
-      id: model.id,
+    const list = Array.isArray(data) ? data : Array.isArray(data?.data) ? data.data : Array.isArray(data?.models) ? data.models : Array.isArray(data?.data?.items) ? data.data.items : [];
+    return list.map((model) => ({
+      id: model.id ?? model.name,
       name: model.name,
       task: model.task,
       status: model.status,
@@ -1998,23 +2019,24 @@ var GraphsApi = class {
   constructor(synapCores) {
     this.synapCores = synapCores;
   }
+  // v0.3.0: gateway routes live under /graph/graphs, not /graphs.
   async list() {
-    const { data } = await this.synapCores._getHttpClient().get("/graphs");
+    const { data } = await this.synapCores._getHttpClient().get("/graph/graphs");
     return (data.graphs ?? data ?? []).map((g) => this.normalize(g));
   }
   async create(name, opts = {}) {
-    const { data } = await this.synapCores._getHttpClient().post("/graphs", {
+    const { data } = await this.synapCores._getHttpClient().post("/graph/graphs", {
       name,
       description: opts.description
     });
     return this.normalize(data);
   }
   async get(name) {
-    const { data } = await this.synapCores._getHttpClient().get(`/graphs/${name}`);
+    const { data } = await this.synapCores._getHttpClient().get(`/graph/graphs/${name}`);
     return this.normalize(data);
   }
   async delete(name) {
-    await this.synapCores._getHttpClient().delete(`/graphs/${name}`);
+    await this.synapCores._getHttpClient().delete(`/graph/graphs/${name}`);
   }
   normalize(data) {
     return {
@@ -2842,7 +2864,7 @@ var SynapCores = class {
       timeout: this.config.timeout,
       headers: {
         "Content-Type": "application/json",
-        "User-Agent": "synapcores-nodejs/0.2.0",
+        "User-Agent": "synapcores-nodejs/0.3.0",
         ...authHeader
       },
       ...httpsAgent && { httpsAgent }
@@ -3008,15 +3030,35 @@ var SynapCores = class {
     this.collectionsCache.set(name, collection);
     return 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) {
+    if (this.collectionsCache.has(name)) {
+      return this.collectionsCache.get(name);
+    }
+    const c = new Collection(this, name);
+    this.collectionsCache.set(name, c);
+    return c;
+  }
   /**
    * List collections (legacy method for backward compatibility)
    */
   async listCollections() {
     const result = await this.listCollectionsDetailed();
-    return result.collections.map((c) => c.name);
+    return (result.collections ?? []).map((c) => c.name);
   }
   /**
    * 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.
    */
   async listCollectionsDetailed(options) {
     const params = new URLSearchParams();
@@ -3028,7 +3070,14 @@ var SynapCores = class {
     const { data } = await this.httpClient.get(
       `/collections${params.toString() ? `?${params.toString()}` : ""}`
     );
-    return data;
+    const inner = data?.data ?? data;
+    const items = Array.isArray(inner) ? inner : inner?.items ?? inner?.collections ?? [];
+    return {
+      collections: items,
+      total: inner?.total ?? items.length,
+      page: inner?.page ?? 1,
+      pageSize: inner?.page_size ?? inner?.pageSize ?? items.length
+    };
   }
   async getDocuments(collectionName, page, pageSize) {
     const { data } = await this.httpClient.get(
@@ -3954,7 +4003,7 @@ var SynapCores = class {
 
 // src/index.ts
 var import_zod = require("zod");
-var VERSION = "0.2.0";
+var VERSION = "0.3.0";
 // Annotate the CommonJS export names for ESM import in node:
 0 && (module.exports = {
   AuthenticationError,