@supabase/storage-js 2.84.0 → 2.84.1-canary.0

package/src/lib/vectors/VectorDataApi.ts

@@ -15,13 +15,9 @@ import {
 } from './types'
 
 /**
- *
- * @alpha
- *
- * API class for managing Vector Data within Vector Indexes
- * Provides methods for inserting, querying, listing, and deleting vector embeddings
- *
- * **Public alpha:** This API is part of a public alpha release and may not be available to your account type.
+ * @hidden
+ * Base implementation for vector data operations.
+ * Use {@link VectorIndexScope} via `supabase.storage.vectors.from('bucket').index('idx')` instead.
  */
 export default class VectorDataApi {
   protected url: string
@@ -29,94 +25,20 @@ export default class VectorDataApi {
   protected fetch: Fetch
   protected shouldThrowOnError = false
 
-  /**
-   *
-   * @alpha
-   *
-   * Creates a VectorDataApi bound to a Storage Vectors deployment.
-   *
-   * **Public alpha:** This API is part of a public alpha release and may not be available to your account type.
-   *
-   * @category Vector Buckets
-   * @param url - Base URL for the Storage Vectors API.
-   * @param headers - Default headers (for example authentication tokens).
-   * @param fetch - Optional custom `fetch` implementation for non-browser runtimes.
-   *
-   * @example
-   * ```typescript
-   * const client = new VectorDataApi(url, headers)
-   * ```
-   */
+  /** Creates a new VectorDataApi instance */
   constructor(url: string, headers: { [key: string]: string } = {}, fetch?: Fetch) {
     this.url = url.replace(/\/$/, '')
     this.headers = { ...DEFAULT_HEADERS, ...headers }
     this.fetch = resolveFetch(fetch)
   }
 
-  /**
-   *
-   * @alpha
-   *
-   * Enable throwing errors instead of returning them in the response
-   * When enabled, failed operations will throw instead of returning { data: null, error }
-   *
-   * **Public alpha:** This API is part of a public alpha release and may not be available to your account type.
-   *
-   * @category Vector Buckets
-   * @returns This instance for method chaining
-   * @example
-   * ```typescript
-   * const client = new VectorDataApi(url, headers)
-   * client.throwOnError()
-   * const { data } = await client.putVectors(options) // throws on error
-   * ```
-   */
+  /** Enable throwing errors instead of returning them in the response */
   public throwOnError(): this {
     this.shouldThrowOnError = true
     return this
   }
 
-  /**
-   *
-   * @alpha
-   *
-   * Inserts or updates vectors in batch (upsert operation)
-   * Accepts 1-500 vectors per request. Larger batches should be split
-   *
-   * **Public alpha:** This API is part of a public alpha release and may not be available to your account type.
-   *
-   * @category Vector Buckets
-   * @param options - Vector insertion options
-   * @param options.vectorBucketName - Name of the parent vector bucket
-   * @param options.indexName - Name of the target index
-   * @param options.vectors - Array of vectors to insert/update (1-500 items)
-   * @returns Promise with empty response on success or error
-   *
-   * @throws {StorageVectorsApiError} With code:
-   * - `S3VectorConflictException` if duplicate key conflict occurs (HTTP 409)
-   * - `S3VectorNotFoundException` if bucket or index doesn't exist (HTTP 404)
-   * - `InternalError` for server errors (HTTP 500)
-   *
-   * @example
-   * ```typescript
-   * const { data, error } = await client.putVectors({
-   *   vectorBucketName: 'embeddings-prod',
-   *   indexName: 'documents-openai-small',
-   *   vectors: [
-   *     {
-   *       key: 'doc-1',
-   *       data: { float32: [0.1, 0.2, 0.3, ...] }, // 1536 dimensions
-   *       metadata: { title: 'Introduction', page: 1 }
-   *     },
-   *     {
-   *       key: 'doc-2',
-   *       data: { float32: [0.4, 0.5, 0.6, ...] },
-   *       metadata: { title: 'Conclusion', page: 42 }
-   *     }
-   *   ]
-   * })
-   * ```
-   */
+  /** Inserts or updates vectors in batch (1-500 per request) */
   async putVectors(options: PutVectorsOptions): Promise<ApiResponse<undefined>> {
     try {
       // Validate batch size
@@ -139,43 +61,7 @@ export default class VectorDataApi {
     }
   }
 
-  /**
-   *
-   * @alpha
-   *
-   * Retrieves vectors by their keys in batch
-   * Optionally includes vector data and/or metadata in response
-   * Additional permissions required when returning data or metadata
-   *
-   * **Public alpha:** This API is part of a public alpha release and may not be available to your account type.
-   *
-   * @category Vector Buckets
-   * @param options - Vector retrieval options
-   * @param options.vectorBucketName - Name of the parent vector bucket
-   * @param options.indexName - Name of the index
-   * @param options.keys - Array of vector keys to retrieve
-   * @param options.returnData - Whether to include vector embeddings (requires permission)
-   * @param options.returnMetadata - Whether to include metadata (requires permission)
-   * @returns Promise with array of vectors or error
-   *
-   * @throws {StorageVectorsApiError} With code:
-   * - `S3VectorNotFoundException` if bucket or index doesn't exist (HTTP 404)
-   * - `InternalError` for server errors (HTTP 500)
-   *
-   * @example
-   * ```typescript
-   * const { data, error } = await client.getVectors({
-   *   vectorBucketName: 'embeddings-prod',
-   *   indexName: 'documents-openai-small',
-   *   keys: ['doc-1', 'doc-2', 'doc-3'],
-   *   returnData: false,     // Don't return embeddings
-   *   returnMetadata: true   // Return metadata only
-   * })
-   * if (data) {
-   *   data.vectors.forEach(v => console.log(v.key, v.metadata))
-   * }
-   * ```
-   */
+  /** Retrieves vectors by their keys in batch */
   async getVectors(options: GetVectorsOptions): Promise<ApiResponse<GetVectorsResponse>> {
     try {
       const data = await post(this.fetch, `${this.url}/GetVectors`, options, {
@@ -193,63 +79,7 @@ export default class VectorDataApi {
     }
   }
 
-  /**
-   *
-   * @alpha
-   *
-   * Lists/scans vectors in an index with pagination
-   * Supports parallel scanning via segment configuration for high-throughput scenarios
-   * Additional permissions required when returning data or metadata
-   *
-   * **Public alpha:** This API is part of a public alpha release and may not be available to your account type.
-   *
-   * @category Vector Buckets
-   * @param options - Vector listing options
-   * @param options.vectorBucketName - Name of the parent vector bucket
-   * @param options.indexName - Name of the index
-   * @param options.maxResults - Maximum results per page (default: 500, max: 1000)
-   * @param options.nextToken - Pagination token from previous response
-   * @param options.returnData - Whether to include vector embeddings (requires permission)
-   * @param options.returnMetadata - Whether to include metadata (requires permission)
-   * @param options.segmentCount - Total parallel segments (1-16) for distributed scanning
-   * @param options.segmentIndex - Zero-based segment index (0 to segmentCount-1)
-   * @returns Promise with array of vectors, pagination token, or error
-   *
-   * @throws {StorageVectorsApiError} With code:
-   * - `S3VectorNotFoundException` if bucket or index doesn't exist (HTTP 404)
-   * - `InternalError` for server errors (HTTP 500)
-   *
-   * @example
-   * ```typescript
-   * // Simple pagination
-   * let nextToken: string | undefined
-   * do {
-   *   const { data, error } = await client.listVectors({
-   *     vectorBucketName: 'embeddings-prod',
-   *     indexName: 'documents-openai-small',
-   *     maxResults: 500,
-   *     nextToken,
-   *     returnMetadata: true
-   *   })
-   *   if (error) break
-   *   console.log('Batch:', data.vectors.length)
-   *   nextToken = data.nextToken
-   * } while (nextToken)
-   *
-   * // Parallel scanning (4 concurrent workers)
-   * const workers = [0, 1, 2, 3].map(async (segmentIndex) => {
-   *   const { data } = await client.listVectors({
-   *     vectorBucketName: 'embeddings-prod',
-   *     indexName: 'documents-openai-small',
-   *     segmentCount: 4,
-   *     segmentIndex,
-   *     returnMetadata: true
-   *   })
-   *   return data?.vectors || []
-   * })
-   * const results = await Promise.all(workers)
-   * ```
-   */
+  /** Lists vectors in an index with pagination */
   async listVectors(options: ListVectorsOptions): Promise<ApiResponse<ListVectorsResponse>> {
     try {
       // Validate segment configuration
@@ -279,54 +109,7 @@ export default class VectorDataApi {
     }
   }
 
-  /**
-   *
-   * @alpha
-   *
-   * Queries for similar vectors using approximate nearest neighbor (ANN) search
-   * Returns top-K most similar vectors based on the configured distance metric
-   * Supports optional metadata filtering (requires GetVectors permission)
-   *
-   * **Public alpha:** This API is part of a public alpha release and may not be available to your account type.
-   *
-   * @category Vector Buckets
-   * @param options - Query options
-   * @param options.vectorBucketName - Name of the parent vector bucket
-   * @param options.indexName - Name of the index
-   * @param options.queryVector - Query embedding to find similar vectors
-   * @param options.topK - Number of nearest neighbors to return (default: 10)
-   * @param options.filter - Optional JSON filter for metadata (requires GetVectors permission)
-   * @param options.returnDistance - Whether to include similarity distances
-   * @param options.returnMetadata - Whether to include metadata (requires GetVectors permission)
-   * @returns Promise with array of similar vectors ordered by distance
-   *
-   * @throws {StorageVectorsApiError} With code:
-   * - `S3VectorNotFoundException` if bucket or index doesn't exist (HTTP 404)
-   * - `InternalError` for server errors (HTTP 500)
-   *
-   * @example
-   * ```typescript
-   * // Semantic search with filtering
-   * const { data, error } = await client.queryVectors({
-   *   vectorBucketName: 'embeddings-prod',
-   *   indexName: 'documents-openai-small',
-   *   queryVector: { float32: [0.1, 0.2, 0.3, ...] }, // 1536 dimensions
-   *   topK: 5,
-   *   filter: {
-   *     category: 'technical',
-   *     published: true
-   *   },
-   *   returnDistance: true,
-   *   returnMetadata: true
-   * })
-   * if (data) {
-   *   data.matches.forEach(match => {
-   *     console.log(`${match.key}: distance=${match.distance}`)
-   *     console.log('Metadata:', match.metadata)
-   *   })
-   * }
-   * ```
-   */
+  /** Queries for similar vectors using approximate nearest neighbor search */
   async queryVectors(options: QueryVectorsOptions): Promise<ApiResponse<QueryVectorsResponse>> {
     try {
       const data = await post(this.fetch, `${this.url}/QueryVectors`, options, {
@@ -344,38 +127,7 @@ export default class VectorDataApi {
     }
   }
 
-  /**
-   *
-   * @alpha
-   *
-   * Deletes vectors by their keys in batch
-   * Accepts 1-500 keys per request
-   *
-   * **Public alpha:** This API is part of a public alpha release and may not be available to your account type.
-   *
-   * @category Vector Buckets
-   * @param options - Vector deletion options
-   * @param options.vectorBucketName - Name of the parent vector bucket
-   * @param options.indexName - Name of the index
-   * @param options.keys - Array of vector keys to delete (1-500 items)
-   * @returns Promise with empty response on success or error
-   *
-   * @throws {StorageVectorsApiError} With code:
-   * - `S3VectorNotFoundException` if bucket or index doesn't exist (HTTP 404)
-   * - `InternalError` for server errors (HTTP 500)
-   *
-   * @example
-   * ```typescript
-   * const { error } = await client.deleteVectors({
-   *   vectorBucketName: 'embeddings-prod',
-   *   indexName: 'documents-openai-small',
-   *   keys: ['doc-1', 'doc-2', 'doc-3']
-   * })
-   * if (!error) {
-   *   console.log('Vectors deleted successfully')
-   * }
-   * ```
-   */
+  /** Deletes vectors by their keys in batch (1-500 per request) */
   async deleteVectors(options: DeleteVectorsOptions): Promise<ApiResponse<undefined>> {
     try {
       // Validate batch size

package/src/lib/vectors/VectorIndexApi.ts

@@ -13,7 +13,6 @@ import {
 } from './types'
 
 /**
- *
  * @alpha
  *
  * Options for creating a vector index
@@ -30,13 +29,9 @@ export interface CreateIndexOptions {
 }
 
 /**
- *
- * @alpha
- *
- * API class for managing Vector Indexes within Vector Buckets
- * Provides methods for creating, reading, listing, and deleting vector indexes
- *
- * **Public alpha:** This API is part of a public alpha release and may not be available to your account type.
+ * @hidden
+ * Base implementation for vector index operations.
+ * Use {@link VectorBucketScope} via `supabase.storage.vectors.from('bucket')` instead.
  */
 export default class VectorIndexApi {
   protected url: string
@@ -44,92 +39,20 @@ export default class VectorIndexApi {
   protected fetch: Fetch
   protected shouldThrowOnError = false
 
-  /**
-   *
-   * @alpha
-   *
-   * Creates an API client for managing vector indexes.
-   *
-   * **Public alpha:** This API is part of a public alpha release and may not be available to your account type.
-   *
-   * @category Vector Buckets
-   * @param url - Base URL for the Storage Vectors API.
-   * @param headers - Default headers sent with each request.
-   * @param fetch - Optional custom `fetch` implementation for non-browser runtimes.
-   *
-   * @example
-   * ```typescript
-   * const client = new VectorIndexApi(url, headers)
-   * ```
-   */
+  /** Creates a new VectorIndexApi instance */
   constructor(url: string, headers: { [key: string]: string } = {}, fetch?: Fetch) {
     this.url = url.replace(/\/$/, '')
     this.headers = { ...DEFAULT_HEADERS, ...headers }
     this.fetch = resolveFetch(fetch)
   }
 
-  /**
-   *
-   * @alpha
-   *
-   * Enable throwing errors instead of returning them in the response
-   * When enabled, failed operations will throw instead of returning { data: null, error }
-   *
-   * **Public alpha:** This API is part of a public alpha release and may not be available to your account type.
-   *
-   * @category Vector Buckets
-   * @returns This instance for method chaining
-   * @example
-   * ```typescript
-   * const client = new VectorIndexApi(url, headers)
-   * client.throwOnError()
-   * const { data } = await client.createIndex(options) // throws on error
-   * ```
-   */
+  /** Enable throwing errors instead of returning them in the response */
   public throwOnError(): this {
     this.shouldThrowOnError = true
     return this
   }
 
-  /**
-   *
-   * @alpha
-   *
-   * Creates a new vector index within a bucket
-   * Defines the schema for vectors including dimensionality, distance metric, and metadata config
-   *
-   * **Public alpha:** This API is part of a public alpha release and may not be available to your account type.
-   *
-   * @category Vector Buckets
-   * @param options - Index configuration
-   * @param options.vectorBucketName - Name of the parent vector bucket
-   * @param options.indexName - Unique name for the index within the bucket
-   * @param options.dataType - Data type for vector components (currently only 'float32')
-   * @param options.dimension - Dimensionality of vectors (e.g., 384, 768, 1536)
-   * @param options.distanceMetric - Similarity metric ('cosine', 'euclidean', 'dotproduct')
-   * @param options.metadataConfiguration - Optional config for non-filterable metadata keys
-   * @returns Promise with empty response on success or error
-   *
-   * @throws {StorageVectorsApiError} With code:
-   * - `S3VectorConflictException` if index already exists (HTTP 409)
-   * - `S3VectorMaxIndexesExceeded` if quota exceeded (HTTP 400)
-   * - `S3VectorNotFoundException` if bucket doesn't exist (HTTP 404)
-   * - `InternalError` for server errors (HTTP 500)
-   *
-   * @example
-   * ```typescript
-   * const { data, error } = await client.createIndex({
-   *   vectorBucketName: 'embeddings-prod',
-   *   indexName: 'documents-openai-small',
-   *   dataType: 'float32',
-   *   dimension: 1536,
-   *   distanceMetric: 'cosine',
-   *   metadataConfiguration: {
-   *     nonFilterableMetadataKeys: ['raw_text', 'internal_id']
-   *   }
-   * })
-   * ```
-   */
+  /** Creates a new vector index within a bucket */
   async createIndex(options: CreateIndexOptions): Promise<ApiResponse<undefined>> {
     try {
       const data = await post(this.fetch, `${this.url}/CreateIndex`, options, {
@@ -147,33 +70,7 @@ export default class VectorIndexApi {
     }
   }
 
-  /**
-   *
-   * @alpha
-   *
-   * Retrieves metadata for a specific vector index
-   * Returns index configuration including dimension, distance metric, and metadata settings
-   *
-   * **Public alpha:** This API is part of a public alpha release and may not be available to your account type.
-   *
-   * @category Vector Buckets
-   * @param vectorBucketName - Name of the parent vector bucket
-   * @param indexName - Name of the index to retrieve
-   * @returns Promise with index metadata or error
-   *
-   * @throws {StorageVectorsApiError} With code:
-   * - `S3VectorNotFoundException` if index or bucket doesn't exist (HTTP 404)
-   * - `InternalError` for server errors (HTTP 500)
-   *
-   * @example
-   * ```typescript
-   * const { data, error } = await client.getIndex('embeddings-prod', 'documents-openai-small')
-   * if (data) {
-   *   console.log('Index dimension:', data.index.dimension)
-   *   console.log('Distance metric:', data.index.distanceMetric)
-   * }
-   * ```
-   */
+  /** Retrieves metadata for a specific vector index */
   async getIndex(
     vectorBucketName: string,
     indexName: string
@@ -197,46 +94,7 @@ export default class VectorIndexApi {
     }
   }
 
-  /**
-   *
-   * @alpha
-   *
-   * Lists vector indexes within a bucket with optional filtering and pagination
-   * Supports prefix-based filtering and paginated results
-   *
-   * **Public alpha:** This API is part of a public alpha release and may not be available to your account type.
-   *
-   * @category Vector Buckets
-   * @param options - Listing options
-   * @param options.vectorBucketName - Name of the parent vector bucket
-   * @param options.prefix - Filter indexes by name prefix
-   * @param options.maxResults - Maximum results per page (default: 100)
-   * @param options.nextToken - Pagination token from previous response
-   * @returns Promise with list of indexes and pagination token
-   *
-   * @throws {StorageVectorsApiError} With code:
-   * - `S3VectorNotFoundException` if bucket doesn't exist (HTTP 404)
-   * - `InternalError` for server errors (HTTP 500)
-   *
-   * @example
-   * ```typescript
-   * // List all indexes in a bucket
-   * const { data, error } = await client.listIndexes({
-   *   vectorBucketName: 'embeddings-prod',
-   *   prefix: 'documents-'
-   * })
-   * if (data) {
-   *   console.log('Found indexes:', data.indexes.map(i => i.indexName))
-   *   // Fetch next page if available
-   *   if (data.nextToken) {
-   *     const next = await client.listIndexes({
-   *       vectorBucketName: 'embeddings-prod',
-   *       nextToken: data.nextToken
-   *     })
-   *   }
-   * }
-   * ```
-   */
+  /** Lists vector indexes within a bucket with optional filtering and pagination */
   async listIndexes(options: ListIndexesOptions): Promise<ApiResponse<ListIndexesResponse>> {
     try {
       const data = await post(this.fetch, `${this.url}/ListIndexes`, options, {
@@ -254,33 +112,7 @@ export default class VectorIndexApi {
     }
   }
 
-  /**
-   *
-   * @alpha
-   *
-   * Deletes a vector index and all its data
-   * This operation removes the index schema and all vectors stored in the index
-   *
-   * **Public alpha:** This API is part of a public alpha release and may not be available to your account type.
-   *
-   * @category Vector Buckets
-   * @param vectorBucketName - Name of the parent vector bucket
-   * @param indexName - Name of the index to delete
-   * @returns Promise with empty response on success or error
-   *
-   * @throws {StorageVectorsApiError} With code:
-   * - `S3VectorNotFoundException` if index or bucket doesn't exist (HTTP 404)
-   * - `InternalError` for server errors (HTTP 500)
-   *
-   * @example
-   * ```typescript
-   * // Delete an index and all its vectors
-   * const { error } = await client.deleteIndex('embeddings-prod', 'old-index')
-   * if (!error) {
-   *   console.log('Index deleted successfully')
-   * }
-   * ```
-   */
+  /** Deletes a vector index and all its data */
   async deleteIndex(vectorBucketName: string, indexName: string): Promise<ApiResponse<undefined>> {
     try {
       const data = await post(

package/src/lib/version.ts

@@ -4,4 +4,4 @@
 // - Debugging and support (identifying which version is running)
 // - Telemetry and logging (version reporting in errors/analytics)
 // - Ensuring build artifacts match the published package version
-export const version = '2.84.0'
+export const version = '2.84.1-canary.0'

package/src/packages/StorageAnalyticsClient.ts

@@ -77,7 +77,11 @@ export default class StorageAnalyticsClient {
    * ```json
    * {
    *   "data": {
-   *     "name": "analytics-data"
+   *     "name": "analytics-data",
+   *     "type": "ANALYTICS",
+   *     "format": "iceberg",
+   *     "created_at": "2024-05-22T22:26:05.100Z",
+   *     "updated_at": "2024-05-22T22:26:05.100Z"
    *   },
    *   "error": null
    * }
@@ -143,9 +147,9 @@ export default class StorageAnalyticsClient {
    * {
    *   "data": [
    *     {
-   *       "id": "analytics-data",
    *       "name": "analytics-data",
    *       "type": "ANALYTICS",
+   *       "format": "iceberg",
    *       "created_at": "2024-05-22T22:26:05.100Z",
    *       "updated_at": "2024-05-22T22:26:05.100Z"
    *     }