diff --git a/packages/core/storage-js/src/StorageClient.ts b/packages/core/storage-js/src/StorageClient.ts index 8c1c46567..c7df75bec 100644 --- a/packages/core/storage-js/src/StorageClient.ts +++ b/packages/core/storage-js/src/StorageClient.ts @@ -40,7 +40,7 @@ export class StorageClient extends StorageBucketApi { * * @example * ```typescript - * const avatars = storage.from('avatars') + * const avatars = supabase.storage.from('avatars') * ``` */ from(id: string): StorageFileApi { @@ -75,20 +75,6 @@ export class StorageClient extends StorageBucketApi { * * @category Analytics Buckets * @returns A StorageAnalyticsClient instance configured with the current storage settings. - * @example - * ```typescript - * const client = createClient(url, key) - * const analytics = client.storage.analytics - * - * // Create an analytics bucket - * await analytics.createBucket('my-analytics-bucket') - * - * // List all analytics buckets - * const { data: buckets } = await analytics.listBuckets() - * - * // Delete an analytics bucket - * await analytics.deleteBucket('old-analytics-bucket') - * ``` */ get analytics(): StorageAnalyticsClient { return new StorageAnalyticsClient(this.url + '/iceberg', this.headers, this.fetch) diff --git a/packages/core/storage-js/src/lib/vectors/StorageVectorsClient.ts b/packages/core/storage-js/src/lib/vectors/StorageVectorsClient.ts index f8210a2b9..51bba8fa5 100644 --- a/packages/core/storage-js/src/lib/vectors/StorageVectorsClient.ts +++ b/packages/core/storage-js/src/lib/vectors/StorageVectorsClient.ts @@ -42,32 +42,14 @@ export interface StorageVectorsClientOptions { * * **Usage Patterns:** * - * 1. **Via StorageClient (recommended for most use cases):** * ```typescript - * import { StorageClient } from '@supabase/storage-js' - * - * const storageClient = new StorageClient(url, headers) - * const vectors = storageClient.vectors - * - * // Use vector operations - * await vectors.createBucket('embeddings-prod') - * const bucket = vectors.from('embeddings-prod') - * await bucket.createIndex({ ... }) - * ``` - * - * 2. **Standalone (for vector-only applications):** - * ```typescript - * import { StorageVectorsClient } from '@supabase/storage-js' - * - * const vectorsClient = new StorageVectorsClient('https://api.example.com', { - * headers: { 'Authorization': 'Bearer token' } - * }) - * - * // Access bucket operations - * await vectorsClient.createBucket('embeddings-prod') + * const { data, error } = await supabase + * .storage + * .vectors + * .createBucket('embeddings-prod') * * // Access index operations via buckets - * const bucket = vectorsClient.from('embeddings-prod') + * const bucket = supabase.storage.vectors.from('embeddings-prod') * await bucket.createIndex({ * indexName: 'documents', * dataType: 'float32', @@ -128,18 +110,7 @@ export class StorageVectorsClient extends VectorBucketApi { * * @example * ```typescript - * const bucket = client.bucket('embeddings-prod') - * - * // Create an index in this bucket - * await bucket.createIndex({ - * indexName: 'documents-openai', - * dataType: 'float32', - * dimension: 1536, - * distanceMetric: 'cosine' - * }) - * - * // List indexes in this bucket - * const { data } = await bucket.listIndexes() + * const bucket = supabase.storage.vectors.from('embeddings-prod') * ``` */ from(vectorBucketName: string): VectorBucketScope { @@ -169,7 +140,7 @@ export class VectorBucketScope extends VectorIndexApi { * @category Vector Buckets * @example * ```typescript - * const bucket = client.bucket('embeddings-prod') + * const bucket = supabase.storage.vectors.from('embeddings-prod') * ``` */ constructor( @@ -197,7 +168,7 @@ export class VectorBucketScope extends VectorIndexApi { * * @example * ```typescript - * const bucket = client.bucket('embeddings-prod') + * const bucket = supabase.storage.vectors.from('embeddings-prod') * await bucket.createIndex({ * indexName: 'documents-openai', * dataType: 'float32', @@ -231,7 +202,7 @@ export class VectorBucketScope extends VectorIndexApi { * * @example * ```typescript - * const bucket = client.bucket('embeddings-prod') + * const bucket = supabase.storage.vectors.from('embeddings-prod') * const { data } = await bucket.listIndexes({ prefix: 'documents-' }) * ``` */ @@ -257,7 +228,7 @@ export class VectorBucketScope extends VectorIndexApi { * * @example * ```typescript - * const bucket = client.bucket('embeddings-prod') + * const bucket = supabase.storage.vectors.from('embeddings-prod') * const { data } = await bucket.getIndex('documents-openai') * console.log('Dimension:', data?.index.dimension) * ``` @@ -281,7 +252,7 @@ export class VectorBucketScope extends VectorIndexApi { * * @example * ```typescript - * const bucket = client.bucket('embeddings-prod') + * const bucket = supabase.storage.vectors.from('embeddings-prod') * await bucket.deleteIndex('old-index') * ``` */ @@ -304,7 +275,7 @@ export class VectorBucketScope extends VectorIndexApi { * * @example * ```typescript - * const index = client.bucket('embeddings-prod').index('documents-openai') + * const index = supabase.storage.vectors.from('embeddings-prod').index('documents-openai') * * // Insert vectors * await index.putVectors({ @@ -355,7 +326,7 @@ export class VectorIndexScope extends VectorDataApi { * @category Vector Buckets * @example * ```typescript - * const index = client.bucket('embeddings-prod').index('documents-openai') + * const index = supabase.storage.vectors.from('embeddings-prod').index('documents-openai') * ``` */ constructor( @@ -385,7 +356,7 @@ export class VectorIndexScope extends VectorDataApi { * * @example * ```typescript - * const index = client.bucket('embeddings-prod').index('documents-openai') + * const index = supabase.storage.vectors.from('embeddings-prod').index('documents-openai') * await index.putVectors({ * vectors: [ * { @@ -420,7 +391,7 @@ export class VectorIndexScope extends VectorDataApi { * * @example * ```typescript - * const index = client.bucket('embeddings-prod').index('documents-openai') + * const index = supabase.storage.vectors.from('embeddings-prod').index('documents-openai') * const { data } = await index.getVectors({ * keys: ['doc-1', 'doc-2'], * returnMetadata: true @@ -450,7 +421,7 @@ export class VectorIndexScope extends VectorDataApi { * * @example * ```typescript - * const index = client.bucket('embeddings-prod').index('documents-openai') + * const index = supabase.storage.vectors.from('embeddings-prod').index('documents-openai') * const { data } = await index.listVectors({ * maxResults: 500, * returnMetadata: true @@ -482,7 +453,7 @@ export class VectorIndexScope extends VectorDataApi { * * @example * ```typescript - * const index = client.bucket('embeddings-prod').index('documents-openai') + * const index = supabase.storage.vectors.from('embeddings-prod').index('documents-openai') * const { data } = await index.queryVectors({ * queryVector: { float32: [0.1, 0.2, ...] }, * topK: 5, @@ -517,7 +488,7 @@ export class VectorIndexScope extends VectorDataApi { * * @example * ```typescript - * const index = client.bucket('embeddings-prod').index('documents-openai') + * const index = supabase.storage.vectors.from('embeddings-prod').index('documents-openai') * await index.deleteVectors({ * keys: ['doc-1', 'doc-2', 'doc-3'] * }) diff --git a/packages/core/storage-js/src/lib/vectors/VectorBucketApi.ts b/packages/core/storage-js/src/lib/vectors/VectorBucketApi.ts index 701f2c149..d3d8851d3 100644 --- a/packages/core/storage-js/src/lib/vectors/VectorBucketApi.ts +++ b/packages/core/storage-js/src/lib/vectors/VectorBucketApi.ts @@ -10,13 +10,9 @@ import { } from './types' /** - * - * @alpha - * - * API class for managing Vector Buckets - * Provides methods for creating, reading, listing, and deleting vector buckets - * - * **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 bucket operations. + * Use {@link StorageVectorsClient} via `supabase.storage.vectors` instead. */ export default class VectorBucketApi { protected url: string @@ -24,79 +20,20 @@ export default class VectorBucketApi { protected fetch: Fetch protected shouldThrowOnError = false - /** - * - * @alpha - * - * Creates a new VectorBucketApi instance - * - * **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 - The base URL for the storage vectors API - * @param headers - HTTP headers to include in requests - * @param fetch - Optional custom fetch implementation - * - * @example - * ```typescript - * const client = new VectorBucketApi(url, headers) - * ``` - */ + /** Creates a new VectorBucketApi 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 VectorBucketApi(url, headers) - * client.throwOnError() - * const { data } = await client.createBucket('my-bucket') // 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 bucket - * Vector buckets are containers for vector indexes and their data - * - * **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 - Unique name for the vector bucket - * @returns Promise with empty response on success or error - * - * @throws {StorageVectorsApiError} With code: - * - `S3VectorConflictException` if bucket already exists (HTTP 409) - * - `S3VectorMaxBucketsExceeded` if quota exceeded (HTTP 400) - * - `InternalError` for server errors (HTTP 500) - * - * @example - * ```typescript - * const { data, error } = await client.createBucket('embeddings-prod') - * if (error) { - * console.error('Failed to create bucket:', error.message) - * } - * ``` - */ + /** Creates a new vector bucket */ async createBucket(vectorBucketName: string): Promise> { try { const data = await post( @@ -117,31 +54,7 @@ export default class VectorBucketApi { } } - /** - * - * @alpha - * - * Retrieves metadata for a specific vector bucket - * Returns bucket configuration including encryption settings and creation time - * - * **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 vector bucket to retrieve - * @returns Promise with bucket metadata or error - * - * @throws {StorageVectorsApiError} With code: - * - `S3VectorNotFoundException` if bucket doesn't exist (HTTP 404) - * - `InternalError` for server errors (HTTP 500) - * - * @example - * ```typescript - * const { data, error } = await client.getBucket('embeddings-prod') - * if (data) { - * console.log('Bucket created at:', new Date(data.vectorBucket.creationTime! * 1000)) - * } - * ``` - */ + /** Retrieves metadata for a specific vector bucket */ async getBucket(vectorBucketName: string): Promise> { try { const data = await post( @@ -162,38 +75,7 @@ export default class VectorBucketApi { } } - /** - * - * @alpha - * - * Lists vector buckets 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.prefix - Filter buckets 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 buckets and pagination token - * - * @throws {StorageVectorsApiError} With code: - * - `InternalError` for server errors (HTTP 500) - * - * @example - * ```typescript - * // List all buckets with prefix 'prod-' - * const { data, error } = await client.listBuckets({ prefix: 'prod-' }) - * if (data) { - * console.log('Found buckets:', data.buckets.length) - * // Fetch next page if available - * if (data.nextToken) { - * const next = await client.listBuckets({ nextToken: data.nextToken }) - * } - * } - * ``` - */ + /** Lists vector buckets with optional filtering and pagination */ async listBuckets( options: ListVectorBucketsOptions = {} ): Promise> { @@ -213,33 +95,7 @@ export default class VectorBucketApi { } } - /** - * - * @alpha - * - * Deletes a vector bucket - * Bucket must be empty before deletion (all indexes must be removed first) - * - * **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 vector bucket to delete - * @returns Promise with empty response on success or error - * - * @throws {StorageVectorsApiError} With code: - * - `S3VectorBucketNotEmpty` if bucket contains indexes (HTTP 400) - * - `S3VectorNotFoundException` if bucket doesn't exist (HTTP 404) - * - `InternalError` for server errors (HTTP 500) - * - * @example - * ```typescript - * // Delete all indexes first, then delete bucket - * const { error } = await client.deleteBucket('old-bucket') - * if (error?.statusCode === 'S3VectorBucketNotEmpty') { - * console.error('Must delete all indexes first') - * } - * ``` - */ + /** Deletes a vector bucket (must be empty first) */ async deleteBucket(vectorBucketName: string): Promise> { try { const data = await post( diff --git a/packages/core/storage-js/src/lib/vectors/VectorDataApi.ts b/packages/core/storage-js/src/lib/vectors/VectorDataApi.ts index 3cd12d68b..da02b1740 100644 --- a/packages/core/storage-js/src/lib/vectors/VectorDataApi.ts +++ b/packages/core/storage-js/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> { 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> { 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> { 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> { 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> { try { // Validate batch size diff --git a/packages/core/storage-js/src/lib/vectors/VectorIndexApi.ts b/packages/core/storage-js/src/lib/vectors/VectorIndexApi.ts index 68f36840a..be107e1d8 100644 --- a/packages/core/storage-js/src/lib/vectors/VectorIndexApi.ts +++ b/packages/core/storage-js/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> { 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> { 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> { try { const data = await post( diff --git a/packages/core/storage-js/src/packages/StorageAnalyticsClient.ts b/packages/core/storage-js/src/packages/StorageAnalyticsClient.ts index 5737e4da1..2120e21a5 100644 --- a/packages/core/storage-js/src/packages/StorageAnalyticsClient.ts +++ b/packages/core/storage-js/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" * }