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

package/src/lib/index.ts

@@ -2,3 +2,4 @@ export * from '../packages/StorageBucketApi'
 export * from '../packages/StorageFileApi'
 export * from './types'
 export * from './constants'
+export * from './vectors'

package/src/lib/types.ts

@@ -1,5 +1,10 @@
 import { StorageError } from './errors'
 
+/**
+ * Type of storage bucket
+ * - STANDARD: Regular file storage buckets
+ * - ANALYTICS: Iceberg table-based buckets for analytical workloads
+ */
 export type BucketType = 'STANDARD' | 'ANALYTICS'
 
 export interface Bucket {
@@ -14,6 +19,23 @@ export interface Bucket {
   public: boolean
 }
 
+/**
+ * Represents an Analytics Bucket using Apache Iceberg table format.
+ * Analytics buckets are optimized for analytical queries and data processing.
+ */
+export interface AnalyticBucket {
+  /** Unique identifier for the bucket */
+  id: string
+  /** Bucket type - always 'ANALYTICS' for analytics buckets */
+  type: 'ANALYTICS'
+  /** Storage format used (e.g., 'iceberg') */
+  format: string
+  /** ISO 8601 timestamp of bucket creation */
+  created_at: string
+  /** ISO 8601 timestamp of last update */
+  updated_at: string
+}
+
 export interface FileObject {
   name: string
   bucket_id: string
@@ -143,10 +165,25 @@ export interface SearchV2Options {
   sortBy?: SortByV2
 }
 
+export interface SearchV2Object {
+  id: string
+  key: string
+  name: string
+  updated_at: string
+  created_at: string
+  metadata: Record<string, any>
+  /**
+   * @deprecated
+   */
+  last_accessed_at: string
+}
+
+export type SearchV2Folder = Omit<SearchV2Object, 'id' | 'metadata' | 'last_accessed_at'>
+
 export interface SearchV2Result {
   hasNext: boolean
-  folders: { name: string }[]
-  objects: FileObject[]
+  folders: SearchV2Folder[]
+  objects: SearchV2Object[]
   nextCursor?: string
 }
 

package/src/lib/vectors/StorageVectorsClient.ts

@@ -0,0 +1,405 @@
+import VectorIndexApi, { CreateIndexOptions } from './VectorIndexApi'
+import VectorDataApi from './VectorDataApi'
+import { Fetch } from './fetch'
+import VectorBucketApi from './VectorBucketApi'
+import {
+  DeleteVectorsOptions,
+  GetVectorsOptions,
+  ListIndexesOptions,
+  ListVectorsOptions,
+  PutVectorsOptions,
+  QueryVectorsOptions,
+} from './types'
+
+/**
+ * Configuration options for the Storage Vectors client
+ */
+export interface StorageVectorsClientOptions {
+  /**
+   * Custom headers to include in all requests
+   */
+  headers?: { [key: string]: string }
+  /**
+   * Custom fetch implementation (optional)
+   * Useful for testing or custom request handling
+   */
+  fetch?: Fetch
+}
+
+/**
+ * Main client for interacting with S3 Vectors API
+ * Provides access to bucket, index, and vector data operations
+ *
+ * **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')
+ *
+ * // Access index operations via buckets
+ * const bucket = vectorsClient.from('embeddings-prod')
+ * await bucket.createIndex({
+ *   indexName: 'documents',
+ *   dataType: 'float32',
+ *   dimension: 1536,
+ *   distanceMetric: 'cosine'
+ * })
+ *
+ * // Access vector operations via index
+ * const index = bucket.index('documents')
+ * await index.putVectors({
+ *   vectors: [
+ *     { key: 'doc-1', data: { float32: [...] }, metadata: { title: 'Intro' } }
+ *   ]
+ * })
+ *
+ * // Query similar vectors
+ * const { data } = await index.queryVectors({
+ *   queryVector: { float32: [...] },
+ *   topK: 5,
+ *   returnDistance: true
+ * })
+ * ```
+ */
+export class StorageVectorsClient extends VectorBucketApi {
+  constructor(url: string, options: StorageVectorsClientOptions = {}) {
+    super(url, options.headers || {}, options.fetch)
+  }
+
+  /**
+   * Access operations for a specific vector bucket
+   * Returns a scoped client for index and vector operations within the bucket
+   *
+   * @param vectorBucketName - Name of the vector bucket
+   * @returns Bucket-scoped client with index and vector operations
+   *
+   * @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()
+   * ```
+   */
+  from(vectorBucketName: string): VectorBucketScope {
+    return new VectorBucketScope(this.url, this.headers, vectorBucketName, this.fetch)
+  }
+}
+
+/**
+ * Scoped client for operations within a specific vector bucket
+ * Provides index management and access to vector operations
+ */
+export class VectorBucketScope extends VectorIndexApi {
+  private vectorBucketName: string
+
+  constructor(
+    url: string,
+    headers: { [key: string]: string },
+    vectorBucketName: string,
+    fetch?: Fetch
+  ) {
+    super(url, headers, fetch)
+    this.vectorBucketName = vectorBucketName
+  }
+
+  /**
+   * Creates a new vector index in this bucket
+   * Convenience method that automatically includes the bucket name
+   *
+   * @param options - Index configuration (vectorBucketName is automatically set)
+   * @returns Promise with empty response on success or error
+   *
+   * @example
+   * ```typescript
+   * const bucket = client.bucket('embeddings-prod')
+   * await bucket.createIndex({
+   *   indexName: 'documents-openai',
+   *   dataType: 'float32',
+   *   dimension: 1536,
+   *   distanceMetric: 'cosine',
+   *   metadataConfiguration: {
+   *     nonFilterableMetadataKeys: ['raw_text']
+   *   }
+   * })
+   * ```
+   */
+  override async createIndex(options: Omit<CreateIndexOptions, 'vectorBucketName'>) {
+    return super.createIndex({
+      ...options,
+      vectorBucketName: this.vectorBucketName,
+    })
+  }
+
+  /**
+   * Lists indexes in this bucket
+   * Convenience method that automatically includes the bucket name
+   *
+   * @param options - Listing options (vectorBucketName is automatically set)
+   * @returns Promise with list of indexes or error
+   *
+   * @example
+   * ```typescript
+   * const bucket = client.bucket('embeddings-prod')
+   * const { data } = await bucket.listIndexes({ prefix: 'documents-' })
+   * ```
+   */
+  override async listIndexes(options: Omit<ListIndexesOptions, 'vectorBucketName'> = {}) {
+    return super.listIndexes({
+      ...options,
+      vectorBucketName: this.vectorBucketName,
+    })
+  }
+
+  /**
+   * Retrieves metadata for a specific index in this bucket
+   * Convenience method that automatically includes the bucket name
+   *
+   * @param indexName - Name of the index to retrieve
+   * @returns Promise with index metadata or error
+   *
+   * @example
+   * ```typescript
+   * const bucket = client.bucket('embeddings-prod')
+   * const { data } = await bucket.getIndex('documents-openai')
+   * console.log('Dimension:', data?.index.dimension)
+   * ```
+   */
+  override async getIndex(indexName: string) {
+    return super.getIndex(this.vectorBucketName, indexName)
+  }
+
+  /**
+   * Deletes an index from this bucket
+   * Convenience method that automatically includes the bucket name
+   *
+   * @param indexName - Name of the index to delete
+   * @returns Promise with empty response on success or error
+   *
+   * @example
+   * ```typescript
+   * const bucket = client.bucket('embeddings-prod')
+   * await bucket.deleteIndex('old-index')
+   * ```
+   */
+  override async deleteIndex(indexName: string) {
+    return super.deleteIndex(this.vectorBucketName, indexName)
+  }
+
+  /**
+   * Access operations for a specific index within this bucket
+   * Returns a scoped client for vector data operations
+   *
+   * @param indexName - Name of the index
+   * @returns Index-scoped client with vector data operations
+   *
+   * @example
+   * ```typescript
+   * const index = client.bucket('embeddings-prod').index('documents-openai')
+   *
+   * // Insert vectors
+   * await index.putVectors({
+   *   vectors: [
+   *     { key: 'doc-1', data: { float32: [...] }, metadata: { title: 'Intro' } }
+   *   ]
+   * })
+   *
+   * // Query similar vectors
+   * const { data } = await index.queryVectors({
+   *   queryVector: { float32: [...] },
+   *   topK: 5
+   * })
+   * ```
+   */
+  index(indexName: string): VectorIndexScope {
+    return new VectorIndexScope(
+      this.url,
+      this.headers,
+      this.vectorBucketName,
+      indexName,
+      this.fetch
+    )
+  }
+}
+
+/**
+ * Scoped client for operations within a specific vector index
+ * Provides vector data operations (put, get, list, query, delete)
+ */
+export class VectorIndexScope extends VectorDataApi {
+  private vectorBucketName: string
+  private indexName: string
+
+  constructor(
+    url: string,
+    headers: { [key: string]: string },
+    vectorBucketName: string,
+    indexName: string,
+    fetch?: Fetch
+  ) {
+    super(url, headers, fetch)
+    this.vectorBucketName = vectorBucketName
+    this.indexName = indexName
+  }
+
+  /**
+   * Inserts or updates vectors in this index
+   * Convenience method that automatically includes bucket and index names
+   *
+   * @param options - Vector insertion options (bucket and index names automatically set)
+   * @returns Promise with empty response on success or error
+   *
+   * @example
+   * ```typescript
+   * const index = client.bucket('embeddings-prod').index('documents-openai')
+   * await index.putVectors({
+   *   vectors: [
+   *     {
+   *       key: 'doc-1',
+   *       data: { float32: [0.1, 0.2, ...] },
+   *       metadata: { title: 'Introduction', page: 1 }
+   *     }
+   *   ]
+   * })
+   * ```
+   */
+  override async putVectors(options: Omit<PutVectorsOptions, 'vectorBucketName' | 'indexName'>) {
+    return super.putVectors({
+      ...options,
+      vectorBucketName: this.vectorBucketName,
+      indexName: this.indexName,
+    })
+  }
+
+  /**
+   * Retrieves vectors by keys from this index
+   * Convenience method that automatically includes bucket and index names
+   *
+   * @param options - Vector retrieval options (bucket and index names automatically set)
+   * @returns Promise with array of vectors or error
+   *
+   * @example
+   * ```typescript
+   * const index = client.bucket('embeddings-prod').index('documents-openai')
+   * const { data } = await index.getVectors({
+   *   keys: ['doc-1', 'doc-2'],
+   *   returnMetadata: true
+   * })
+   * ```
+   */
+  override async getVectors(options: Omit<GetVectorsOptions, 'vectorBucketName' | 'indexName'>) {
+    return super.getVectors({
+      ...options,
+      vectorBucketName: this.vectorBucketName,
+      indexName: this.indexName,
+    })
+  }
+
+  /**
+   * Lists vectors in this index with pagination
+   * Convenience method that automatically includes bucket and index names
+   *
+   * @param options - Listing options (bucket and index names automatically set)
+   * @returns Promise with array of vectors and pagination token
+   *
+   * @example
+   * ```typescript
+   * const index = client.bucket('embeddings-prod').index('documents-openai')
+   * const { data } = await index.listVectors({
+   *   maxResults: 500,
+   *   returnMetadata: true
+   * })
+   * ```
+   */
+  override async listVectors(
+    options: Omit<ListVectorsOptions, 'vectorBucketName' | 'indexName'> = {}
+  ) {
+    return super.listVectors({
+      ...options,
+      vectorBucketName: this.vectorBucketName,
+      indexName: this.indexName,
+    })
+  }
+
+  /**
+   * Queries for similar vectors in this index
+   * Convenience method that automatically includes bucket and index names
+   *
+   * @param options - Query options (bucket and index names automatically set)
+   * @returns Promise with array of similar vectors ordered by distance
+   *
+   * @example
+   * ```typescript
+   * const index = client.bucket('embeddings-prod').index('documents-openai')
+   * const { data } = await index.queryVectors({
+   *   queryVector: { float32: [0.1, 0.2, ...] },
+   *   topK: 5,
+   *   filter: { category: 'technical' },
+   *   returnDistance: true,
+   *   returnMetadata: true
+   * })
+   * ```
+   */
+  override async queryVectors(
+    options: Omit<QueryVectorsOptions, 'vectorBucketName' | 'indexName'>
+  ) {
+    return super.queryVectors({
+      ...options,
+      vectorBucketName: this.vectorBucketName,
+      indexName: this.indexName,
+    })
+  }
+
+  /**
+   * Deletes vectors by keys from this index
+   * Convenience method that automatically includes bucket and index names
+   *
+   * @param options - Deletion options (bucket and index names automatically set)
+   * @returns Promise with empty response on success or error
+   *
+   * @example
+   * ```typescript
+   * const index = client.bucket('embeddings-prod').index('documents-openai')
+   * await index.deleteVectors({
+   *   keys: ['doc-1', 'doc-2', 'doc-3']
+   * })
+   * ```
+   */
+  override async deleteVectors(
+    options: Omit<DeleteVectorsOptions, 'vectorBucketName' | 'indexName'>
+  ) {
+    return super.deleteVectors({
+      ...options,
+      vectorBucketName: this.vectorBucketName,
+      indexName: this.indexName,
+    })
+  }
+}

package/src/lib/vectors/VectorBucketApi.ts

@@ -0,0 +1,217 @@
+import { DEFAULT_HEADERS } from './constants'
+import { isStorageVectorsError } from './errors'
+import { Fetch, post } from './fetch'
+import { resolveFetch } from './helpers'
+import {
+  ApiResponse,
+  VectorBucket,
+  ListVectorBucketsOptions,
+  ListVectorBucketsResponse,
+} from './types'
+
+/**
+ * API class for managing Vector Buckets
+ * Provides methods for creating, reading, listing, and deleting vector buckets
+ */
+export default class VectorBucketApi {
+  protected url: string
+  protected headers: { [key: string]: string }
+  protected fetch: Fetch
+  protected shouldThrowOnError = false
+
+  /**
+   * Creates a new VectorBucketApi instance
+   * @param url - The base URL for the storage vectors API
+   * @param headers - HTTP headers to include in requests
+   * @param fetch - Optional custom fetch implementation
+   */
+  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 VectorBucketApi(url, headers)
+   * client.throwOnError()
+   * const { data } = await client.createBucket('my-bucket') // throws on error
+   * ```
+   */
+  public throwOnError(): this {
+    this.shouldThrowOnError = true
+    return this
+  }
+
+  /**
+   * Creates a new vector bucket
+   * Vector buckets are containers for vector indexes and their data
+   *
+   * @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)
+   * }
+   * ```
+   */
+  async createBucket(vectorBucketName: string): Promise<ApiResponse<undefined>> {
+    try {
+      const data = await post(
+        this.fetch,
+        `${this.url}/CreateVectorBucket`,
+        { vectorBucketName },
+        { 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 bucket
+   * Returns bucket configuration including encryption settings and creation time
+   *
+   * @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))
+   * }
+   * ```
+   */
+  async getBucket(
+    vectorBucketName: string
+  ): Promise<ApiResponse<{ vectorBucket: VectorBucket }>> {
+    try {
+      const data = await post(
+        this.fetch,
+        `${this.url}/GetVectorBucket`,
+        { vectorBucketName },
+        { 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 buckets with optional filtering and pagination
+   * Supports prefix-based filtering and paginated results
+   *
+   * @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 })
+   *   }
+   * }
+   * ```
+   */
+  async listBuckets(
+    options: ListVectorBucketsOptions = {}
+  ): Promise<ApiResponse<ListVectorBucketsResponse>> {
+    try {
+      const data = await post(this.fetch, `${this.url}/ListVectorBuckets`, 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 bucket
+   * Bucket must be empty before deletion (all indexes must be removed first)
+   *
+   * @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')
+   * }
+   * ```
+   */
+  async deleteBucket(vectorBucketName: string): Promise<ApiResponse<undefined>> {
+    try {
+      const data = await post(
+        this.fetch,
+        `${this.url}/DeleteVectorBucket`,
+        { vectorBucketName },
+        { headers: this.headers }
+      )
+      return { data: data || {}, error: null }
+    } catch (error) {
+      if (this.shouldThrowOnError) {
+        throw error
+      }
+      if (isStorageVectorsError(error)) {
+        return { data: null, error }
+      }
+      throw error
+    }
+  }
+}