@supabase/storage-js 2.75.1 → 2.75.2-canary.1

package/src/lib/vectors/VectorDataApi.ts

@@ -0,0 +1,341 @@
+import { DEFAULT_HEADERS } from './constants'
+import { isStorageVectorsError } from './errors'
+import { Fetch, post } from './fetch'
+import { resolveFetch } from './helpers'
+import {
+  ApiResponse,
+  PutVectorsOptions,
+  GetVectorsOptions,
+  GetVectorsResponse,
+  DeleteVectorsOptions,
+  ListVectorsOptions,
+  ListVectorsResponse,
+  QueryVectorsOptions,
+  QueryVectorsResponse,
+} from './types'
+
+/**
+ * API class for managing Vector Data within Vector Indexes
+ * Provides methods for inserting, querying, listing, and deleting vector embeddings
+ */
+export default class VectorDataApi {
+  protected url: string
+  protected headers: { [key: string]: string }
+  protected fetch: Fetch
+  protected shouldThrowOnError = false
+
+  constructor(url: string, headers: { [key: string]: string } = {}, fetch?: Fetch) {
+    this.url = url.replace(/\/$/, '')
+    this.headers = { ...DEFAULT_HEADERS, ...headers }
+    this.fetch = resolveFetch(fetch)
+  }
+
+  /**
+   * Enable throwing errors instead of returning them in the response
+   * When enabled, failed operations will throw instead of returning { data: null, error }
+   *
+   * @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
+   * ```
+   */
+  public throwOnError(): this {
+    this.shouldThrowOnError = true
+    return this
+  }
+
+  /**
+   * Inserts or updates vectors in batch (upsert operation)
+   * Accepts 1-500 vectors per request. Larger batches should be split
+   *
+   * @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 }
+   *     }
+   *   ]
+   * })
+   * ```
+   */
+  async putVectors(options: PutVectorsOptions): Promise<ApiResponse<undefined>> {
+    try {
+      // Validate batch size
+      if (options.vectors.length < 1 || options.vectors.length > 500) {
+        throw new Error('Vector batch size must be between 1 and 500 items')
+      }
+
+      const data = await post(this.fetch, `${this.url}/PutVectors`, options, {
+        headers: this.headers,
+      })
+      return { data: data || {}, error: null }
+    } catch (error) {
+      if (this.shouldThrowOnError) {
+        throw error
+      }
+      if (isStorageVectorsError(error)) {
+        return { data: null, error }
+      }
+      throw error
+    }
+  }
+
+  /**
+   * Retrieves vectors by their keys in batch
+   * Optionally includes vector data and/or metadata in response
+   * Additional permissions required when returning data or metadata
+   *
+   * @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))
+   * }
+   * ```
+   */
+  async getVectors(options: GetVectorsOptions): Promise<ApiResponse<GetVectorsResponse>> {
+    try {
+      const data = await post(this.fetch, `${this.url}/GetVectors`, options, {
+        headers: this.headers,
+      })
+      return { data, error: null }
+    } catch (error) {
+      if (this.shouldThrowOnError) {
+        throw error
+      }
+      if (isStorageVectorsError(error)) {
+        return { data: null, error }
+      }
+      throw error
+    }
+  }
+
+  /**
+   * 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
+   *
+   * @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)
+   * ```
+   */
+  async listVectors(options: ListVectorsOptions): Promise<ApiResponse<ListVectorsResponse>> {
+    try {
+      // Validate segment configuration
+      if (options.segmentCount !== undefined) {
+        if (options.segmentCount < 1 || options.segmentCount > 16) {
+          throw new Error('segmentCount must be between 1 and 16')
+        }
+        if (options.segmentIndex !== undefined) {
+          if (options.segmentIndex < 0 || options.segmentIndex >= options.segmentCount) {
+            throw new Error(`segmentIndex must be between 0 and ${options.segmentCount - 1}`)
+          }
+        }
+      }
+
+      const data = await post(this.fetch, `${this.url}/ListVectors`, options, {
+        headers: this.headers,
+      })
+      return { data, error: null }
+    } catch (error) {
+      if (this.shouldThrowOnError) {
+        throw error
+      }
+      if (isStorageVectorsError(error)) {
+        return { data: null, error }
+      }
+      throw error
+    }
+  }
+
+  /**
+   * 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)
+   *
+   * @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)
+   *   })
+   * }
+   * ```
+   */
+  async queryVectors(options: QueryVectorsOptions): Promise<ApiResponse<QueryVectorsResponse>> {
+    try {
+      const data = await post(this.fetch, `${this.url}/QueryVectors`, options, {
+        headers: this.headers,
+      })
+      return { data, error: null }
+    } catch (error) {
+      if (this.shouldThrowOnError) {
+        throw error
+      }
+      if (isStorageVectorsError(error)) {
+        return { data: null, error }
+      }
+      throw error
+    }
+  }
+
+  /**
+   * Deletes vectors by their keys in batch
+   * Accepts 1-500 keys per request
+   *
+   * @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')
+   * }
+   * ```
+   */
+  async deleteVectors(options: DeleteVectorsOptions): Promise<ApiResponse<undefined>> {
+    try {
+      // Validate batch size
+      if (options.keys.length < 1 || options.keys.length > 500) {
+        throw new Error('Keys batch size must be between 1 and 500 items')
+      }
+
+      const data = await post(this.fetch, `${this.url}/DeleteVectors`, options, {
+        headers: this.headers,
+      })
+      return { data: data || {}, error: null }
+    } catch (error) {
+      if (this.shouldThrowOnError) {
+        throw error
+      }
+      if (isStorageVectorsError(error)) {
+        return { data: null, error }
+      }
+      throw error
+    }
+  }
+}

package/src/lib/vectors/VectorIndexApi.ts

@@ -0,0 +1,245 @@
+import { DEFAULT_HEADERS } from './constants'
+import { isStorageVectorsError } from './errors'
+import { Fetch, post } from './fetch'
+import { resolveFetch } from './helpers'
+import {
+  ApiResponse,
+  VectorIndex,
+  ListIndexesOptions,
+  ListIndexesResponse,
+  VectorDataType,
+  DistanceMetric,
+  MetadataConfiguration,
+} from './types'
+
+/**
+ * Options for creating a vector index
+ */
+export interface CreateIndexOptions {
+  vectorBucketName: string
+  indexName: string
+  dataType: VectorDataType
+  dimension: number
+  distanceMetric: DistanceMetric
+  metadataConfiguration?: MetadataConfiguration
+}
+
+/**
+ * API class for managing Vector Indexes within Vector Buckets
+ * Provides methods for creating, reading, listing, and deleting vector indexes
+ */
+export default class VectorIndexApi {
+  protected url: string
+  protected headers: { [key: string]: string }
+  protected fetch: Fetch
+  protected shouldThrowOnError = false
+
+  constructor(url: string, headers: { [key: string]: string } = {}, fetch?: Fetch) {
+    this.url = url.replace(/\/$/, '')
+    this.headers = { ...DEFAULT_HEADERS, ...headers }
+    this.fetch = resolveFetch(fetch)
+  }
+
+  /**
+   * Enable throwing errors instead of returning them in the response
+   * When enabled, failed operations will throw instead of returning { data: null, error }
+   *
+   * @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
+   * ```
+   */
+  public throwOnError(): this {
+    this.shouldThrowOnError = true
+    return this
+  }
+
+  /**
+   * Creates a new vector index within a bucket
+   * Defines the schema for vectors including dimensionality, distance metric, and metadata config
+   *
+   * @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']
+   *   }
+   * })
+   * ```
+   */
+  async createIndex(options: CreateIndexOptions): Promise<ApiResponse<undefined>> {
+    try {
+      const data = await post(this.fetch, `${this.url}/CreateIndex`, options, {
+        headers: this.headers,
+      })
+      return { data: data || {}, error: null }
+    } catch (error) {
+      if (this.shouldThrowOnError) {
+        throw error
+      }
+      if (isStorageVectorsError(error)) {
+        return { data: null, error }
+      }
+      throw error
+    }
+  }
+
+  /**
+   * Retrieves metadata for a specific vector index
+   * Returns index configuration including dimension, distance metric, and metadata settings
+   *
+   * @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)
+   * }
+   * ```
+   */
+  async getIndex(
+    vectorBucketName: string,
+    indexName: string
+  ): Promise<ApiResponse<{ index: VectorIndex }>> {
+    try {
+      const data = await post(
+        this.fetch,
+        `${this.url}/GetIndex`,
+        { vectorBucketName, indexName },
+        { headers: this.headers }
+      )
+      return { data, error: null }
+    } catch (error) {
+      if (this.shouldThrowOnError) {
+        throw error
+      }
+      if (isStorageVectorsError(error)) {
+        return { data: null, error }
+      }
+      throw error
+    }
+  }
+
+  /**
+   * Lists vector indexes within a bucket with optional filtering and pagination
+   * Supports prefix-based filtering and paginated results
+   *
+   * @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
+   *     })
+   *   }
+   * }
+   * ```
+   */
+  async listIndexes(options: ListIndexesOptions): Promise<ApiResponse<ListIndexesResponse>> {
+    try {
+      const data = await post(this.fetch, `${this.url}/ListIndexes`, options, {
+        headers: this.headers,
+      })
+      return { data, error: null }
+    } catch (error) {
+      if (this.shouldThrowOnError) {
+        throw error
+      }
+      if (isStorageVectorsError(error)) {
+        return { data: null, error }
+      }
+      throw error
+    }
+  }
+
+  /**
+   * Deletes a vector index and all its data
+   * This operation removes the index schema and all vectors stored in the index
+   *
+   * @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')
+   * }
+   * ```
+   */
+  async deleteIndex(vectorBucketName: string, indexName: string): Promise<ApiResponse<undefined>> {
+    try {
+      const data = await post(
+        this.fetch,
+        `${this.url}/DeleteIndex`,
+        { vectorBucketName, indexName },
+        { headers: this.headers }
+      )
+      return { data: data || {}, error: null }
+    } catch (error) {
+      if (this.shouldThrowOnError) {
+        throw error
+      }
+      if (isStorageVectorsError(error)) {
+        return { data: null, error }
+      }
+      throw error
+    }
+  }
+}

package/src/lib/vectors/constants.ts

@@ -0,0 +1,5 @@
+import { version } from '../version'
+export const DEFAULT_HEADERS = {
+  'X-Client-Info': `storage-js/${version}`,
+  'Content-Type': 'application/json',
+}

package/src/lib/vectors/errors.ts

@@ -0,0 +1,78 @@
+/**
+ * Base error class for all Storage Vectors errors
+ */
+export class StorageVectorsError extends Error {
+  protected __isStorageVectorsError = true
+
+  constructor(message: string) {
+    super(message)
+    this.name = 'StorageVectorsError'
+  }
+}
+
+/**
+ * Type guard to check if an error is a StorageVectorsError
+ * @param error - The error to check
+ * @returns True if the error is a StorageVectorsError
+ */
+export function isStorageVectorsError(error: unknown): error is StorageVectorsError {
+  return typeof error === 'object' && error !== null && '__isStorageVectorsError' in error
+}
+
+/**
+ * API error returned from S3 Vectors service
+ * Includes HTTP status code and service-specific error code
+ */
+export class StorageVectorsApiError extends StorageVectorsError {
+  status: number
+  statusCode: string
+
+  constructor(message: string, status: number, statusCode: string) {
+    super(message)
+    this.name = 'StorageVectorsApiError'
+    this.status = status
+    this.statusCode = statusCode
+  }
+
+  toJSON() {
+    return {
+      name: this.name,
+      message: this.message,
+      status: this.status,
+      statusCode: this.statusCode,
+    }
+  }
+}
+
+/**
+ * Unknown error that doesn't match expected error patterns
+ * Wraps the original error for debugging
+ */
+export class StorageVectorsUnknownError extends StorageVectorsError {
+  originalError: unknown
+
+  constructor(message: string, originalError: unknown) {
+    super(message)
+    this.name = 'StorageVectorsUnknownError'
+    this.originalError = originalError
+  }
+}
+
+/**
+ * Error codes specific to S3 Vectors API
+ * Maps AWS service errors to application-friendly error codes
+ */
+export enum StorageVectorsErrorCode {
+  /** Internal server fault (HTTP 500) */
+  InternalError = 'InternalError',
+  /** Resource already exists / conflict (HTTP 409) */
+  S3VectorConflictException = 'S3VectorConflictException',
+  /** Resource not found (HTTP 404) */
+  S3VectorNotFoundException = 'S3VectorNotFoundException',
+  /** Delete bucket while not empty (HTTP 400) */
+  S3VectorBucketNotEmpty = 'S3VectorBucketNotEmpty',
+  /** Exceeds bucket quota/limit (HTTP 400) */
+  S3VectorMaxBucketsExceeded = 'S3VectorMaxBucketsExceeded',
+  /** Exceeds index quota/limit (HTTP 400) */
+  S3VectorMaxIndexesExceeded = 'S3VectorMaxIndexesExceeded',
+}