@supabase/storage-js 2.79.1-canary.1 → 2.80.0

package/src/StorageClient.ts

@@ -1,6 +1,8 @@
 import StorageFileApi from './packages/StorageFileApi'
 import StorageBucketApi from './packages/StorageBucketApi'
+import StorageAnalyticsApi from './packages/StorageAnalyticsApi'
 import { Fetch } from './lib/fetch'
+import { StorageVectorsClient } from './lib/vectors'
 
 export interface StorageClientOptions {
   useNewHostname?: boolean
@@ -24,4 +26,39 @@ export class StorageClient extends StorageBucketApi {
   from(id: string): StorageFileApi {
     return new StorageFileApi(this.url, this.headers, id, this.fetch)
   }
+
+  /**
+   * Access vector storage operations.
+   *
+   * @returns A StorageVectorsClient instance configured with the current storage settings.
+   */
+  get vectors(): StorageVectorsClient {
+    return new StorageVectorsClient(this.url + '/vector', {
+      headers: this.headers,
+      fetch: this.fetch,
+    })
+  }
+
+  /**
+   * Access analytics storage operations using Iceberg tables.
+   *
+   * @returns A StorageAnalyticsApi 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(): StorageAnalyticsApi {
+    return new StorageAnalyticsApi(this.url + '/iceberg', this.headers, this.fetch)
+  }
 }

package/src/index.ts

@@ -1,4 +1,6 @@
 export { StorageClient } from './StorageClient'
 export type { StorageClientOptions } from './StorageClient'
+export { default as StorageAnalyticsApi } from './packages/StorageAnalyticsApi'
 export * from './lib/types'
 export * from './lib/errors'
+export * from './lib/vectors'

package/src/lib/constants.ts

@@ -1,2 +1,4 @@
 import { version } from './version'
-export const DEFAULT_HEADERS = { 'X-Client-Info': `storage-js/${version}` }
+export const DEFAULT_HEADERS = {
+  'X-Client-Info': `storage-js/${version}`,
+}

package/src/lib/fetch.ts

@@ -15,7 +15,11 @@ export interface FetchOptions {
 export type RequestMethodType = 'GET' | 'POST' | 'PUT' | 'DELETE' | 'HEAD'
 
 const _getErrorMessage = (err: any): string =>
-  err.msg || err.message || err.error_description || err.error || JSON.stringify(err)
+  err.msg ||
+  err.message ||
+  err.error_description ||
+  (typeof err.error === 'string' ? err.error : err.error?.message) ||
+  JSON.stringify(err)
 
 const handleError = async (
   error: unknown,

package/src/lib/helpers.ts

@@ -1,24 +1,13 @@
 type Fetch = typeof fetch
 
 export const resolveFetch = (customFetch?: Fetch): Fetch => {
-  let _fetch: Fetch
   if (customFetch) {
-    _fetch = customFetch
-  } else if (typeof fetch === 'undefined') {
-    _fetch = (...args) =>
-      import('@supabase/node-fetch' as any).then(({ default: fetch }) => fetch(...args))
-  } else {
-    _fetch = fetch
+    return (...args) => customFetch(...args)
   }
-  return (...args) => _fetch(...args)
+  return (...args) => fetch(...args)
 }
 
-export const resolveResponse = async (): Promise<typeof Response> => {
-  if (typeof Response === 'undefined') {
-    // @ts-ignore
-    return (await import('@supabase/node-fetch' as any)).Response
-  }
-
+export const resolveResponse = (): typeof Response => {
   return Response
 }
 

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,31 @@ export interface Bucket {
   public: boolean
 }
 
+export interface ListBucketOptions {
+  limit?: number
+  offset?: number
+  sortColumn?: 'id' | 'name' | 'created_at' | 'updated_at'
+  sortOrder?: 'asc' | 'desc'
+  search?: string
+}
+
+/**
+ * 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
@@ -21,6 +51,7 @@ export interface FileObject {
   id: string
   updated_at: string
   created_at: string
+  /** @deprecated */
   last_accessed_at: string
   metadata: Record<string, any>
   buckets: Bucket
@@ -33,6 +64,7 @@ export interface FileObjectV2 {
   bucket_id: string
   updated_at: string
   created_at: string
+  /** @deprecated */
   last_accessed_at: string
   size?: number
   cache_control?: string
@@ -103,17 +135,66 @@ export interface SearchOptions {
   search?: string
 }
 
+export interface SortByV2 {
+  column: 'name' | 'updated_at' | 'created_at'
+  order?: 'asc' | 'desc'
+}
+
 export interface SearchV2Options {
+  /**
+   * The number of files you want to be returned.
+   * @default 1000
+   */
   limit?: number
+
+  /**
+   * The prefix search string to filter files by.
+   */
   prefix?: string
+
+  /**
+   * The cursor used for pagination. Pass the value received from nextCursor of the previous request.
+   */
   cursor?: string
+
+  /**
+   * Whether to emulate a hierarchical listing of objects using delimiters.
+   *
+   * - When `false` (default), all objects are listed as flat key/value pairs.
+   * - When `true`, the response groups objects by delimiter, making it appear
+   *   like a file/folder hierarchy.
+   *
+   * @default false
+   */
   with_delimiter?: boolean
+
+  /**
+   * The column and order to sort by
+   * @default 'name asc'
+   */
+  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
 }
 
 export interface FetchParameters {

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,
+    })
+  }
+}