@supabase/storage-js 2.91.1 → 2.91.2

package/src/packages/StorageFileApi.ts

@@ -1,6 +1,7 @@
-import { isStorageError, StorageError, StorageUnknownError } from '../lib/errors'
-import { Fetch, get, head, post, put, remove } from '../lib/fetch'
-import { recursiveToCamel, resolveFetch } from '../lib/helpers'
+import { StorageError, StorageUnknownError, isStorageError } from '../lib/common/errors'
+import { get, head, post, put, remove, Fetch } from '../lib/common/fetch'
+import { recursiveToCamel } from '../lib/common/helpers'
+import BaseApiClient from '../lib/common/BaseApiClient'
 import {
   FileObject,
   FileOptions,
@@ -42,12 +43,8 @@ type FileBody =
   | URLSearchParams
   | string
 
-export default class StorageFileApi {
-  protected url: string
-  protected headers: { [key: string]: string }
+export default class StorageFileApi extends BaseApiClient<StorageError> {
   protected bucketId?: string
-  protected fetch: Fetch
-  protected shouldThrowOnError = false
 
   constructor(
     url: string,
@@ -55,20 +52,8 @@ export default class StorageFileApi {
     bucketId?: string,
     fetch?: Fetch
   ) {
-    this.url = url
-    this.headers = headers
+    super(url, headers, fetch, 'storage')
     this.bucketId = bucketId
-    this.fetch = resolveFetch(fetch)
-  }
-
-  /**
-   * Enable throwing errors instead of returning them.
-   *
-   * @category File Buckets
-   */
-  public throwOnError(): this {
-    this.shouldThrowOnError = true
-    return this
   }
 
   /**
@@ -93,7 +78,7 @@ export default class StorageFileApi {
         error: StorageError
       }
   > {
-    try {
+    return this.handleOperation(async () => {
       let body
       const options = { ...DEFAULT_FILE_OPTIONS, ...fileOptions }
       let headers: Record<string, string> = {
@@ -152,20 +137,8 @@ export default class StorageFileApi {
         { headers, ...(options?.duplex ? { duplex: options.duplex } : {}) }
       )
 
-      return {
-        data: { path: cleanPath, id: data.Id, fullPath: data.Key },
-        error: null,
-      }
-    } catch (error) {
-      if (this.shouldThrowOnError) {
-        throw error
-      }
-      if (isStorageError(error)) {
-        return { data: null, error }
-      }
-
-      throw error
-    }
+      return { path: cleanPath, id: data.Id, fullPath: data.Key }
+    })
   }
 
   /**
@@ -272,7 +245,7 @@ export default class StorageFileApi {
     const url = new URL(this.url + `/object/upload/sign/${_path}`)
     url.searchParams.set('token', token)
 
-    try {
+    return this.handleOperation(async () => {
       let body
       const options = { upsert: DEFAULT_FILE_OPTIONS.upsert, ...fileOptions }
       const headers: Record<string, string> = {
@@ -295,20 +268,8 @@ export default class StorageFileApi {
 
       const data = await put(this.fetch, url.toString(), body as object, { headers })
 
-      return {
-        data: { path: cleanPath, fullPath: data.Key },
-        error: null,
-      }
-    } catch (error) {
-      if (this.shouldThrowOnError) {
-        throw error
-      }
-      if (isStorageError(error)) {
-        return { data: null, error }
-      }
-
-      throw error
-    }
+      return { path: cleanPath, fullPath: data.Key }
+    })
   }
 
   /**
@@ -354,7 +315,7 @@ export default class StorageFileApi {
         error: StorageError
       }
   > {
-    try {
+    return this.handleOperation(async () => {
       let _path = this._getFinalPath(path)
 
       const headers = { ...this.headers }
@@ -378,17 +339,8 @@ export default class StorageFileApi {
         throw new StorageError('No token returned by API')
       }
 
-      return { data: { signedUrl: url.toString(), path, token }, error: null }
-    } catch (error) {
-      if (this.shouldThrowOnError) {
-        throw error
-      }
-      if (isStorageError(error)) {
-        return { data: null, error }
-      }
-
-      throw error
-    }
+      return { signedUrl: url.toString(), path, token }
+    })
   }
 
   /**
@@ -503,8 +455,8 @@ export default class StorageFileApi {
         error: StorageError
       }
   > {
-    try {
-      const data = await post(
+    return this.handleOperation(async () => {
+      return await post(
         this.fetch,
         `${this.url}/object/move`,
         {
@@ -515,17 +467,7 @@ export default class StorageFileApi {
         },
         { headers: this.headers }
       )
-      return { data, error: null }
-    } catch (error) {
-      if (this.shouldThrowOnError) {
-        throw error
-      }
-      if (isStorageError(error)) {
-        return { data: null, error }
-      }
-
-      throw error
-    }
+    })
   }
 
   /**
@@ -569,7 +511,7 @@ export default class StorageFileApi {
         error: StorageError
       }
   > {
-    try {
+    return this.handleOperation(async () => {
       const data = await post(
         this.fetch,
         `${this.url}/object/copy`,
@@ -581,17 +523,8 @@ export default class StorageFileApi {
         },
         { headers: this.headers }
       )
-      return { data: { path: data.Key }, error: null }
-    } catch (error) {
-      if (this.shouldThrowOnError) {
-        throw error
-      }
-      if (isStorageError(error)) {
-        return { data: null, error }
-      }
-
-      throw error
-    }
+      return { path: data.Key }
+    })
   }
 
   /**
@@ -659,7 +592,7 @@ export default class StorageFileApi {
         error: StorageError
       }
   > {
-    try {
+    return this.handleOperation(async () => {
       let _path = this._getFinalPath(path)
 
       let data = await post(
@@ -672,18 +605,8 @@ export default class StorageFileApi {
         ? `&download=${options.download === true ? '' : options.download}`
         : ''
       const signedUrl = encodeURI(`${this.url}${data.signedURL}${downloadQueryParam}`)
-      data = { signedUrl }
-      return { data, error: null }
-    } catch (error) {
-      if (this.shouldThrowOnError) {
-        throw error
-      }
-      if (isStorageError(error)) {
-        return { data: null, error }
-      }
-
-      throw error
-    }
+      return { signedUrl }
+    })
   }
 
   /**
@@ -738,7 +661,7 @@ export default class StorageFileApi {
         error: StorageError
       }
   > {
-    try {
+    return this.handleOperation(async () => {
       const data = await post(
         this.fetch,
         `${this.url}/object/sign/${this.bucketId}`,
@@ -749,25 +672,13 @@ export default class StorageFileApi {
       const downloadQueryParam = options?.download
         ? `&download=${options.download === true ? '' : options.download}`
         : ''
-      return {
-        data: data.map((datum: { signedURL: string }) => ({
-          ...datum,
-          signedUrl: datum.signedURL
-            ? encodeURI(`${this.url}${datum.signedURL}${downloadQueryParam}`)
-            : null,
-        })),
-        error: null,
-      }
-    } catch (error) {
-      if (this.shouldThrowOnError) {
-        throw error
-      }
-      if (isStorageError(error)) {
-        return { data: null, error }
-      }
-
-      throw error
-    }
+      return data.map((datum: { signedURL: string }) => ({
+        ...datum,
+        signedUrl: datum.signedURL
+          ? encodeURI(`${this.url}${datum.signedURL}${downloadQueryParam}`)
+          : null,
+      }))
+    })
   }
 
   /**
@@ -852,22 +763,13 @@ export default class StorageFileApi {
   > {
     const _path = this._getFinalPath(path)
 
-    try {
+    return this.handleOperation(async () => {
       const data = await get(this.fetch, `${this.url}/object/info/${_path}`, {
         headers: this.headers,
       })
 
-      return { data: recursiveToCamel(data) as Camelize<FileObjectV2>, error: null }
-    } catch (error) {
-      if (this.shouldThrowOnError) {
-        throw error
-      }
-      if (isStorageError(error)) {
-        return { data: null, error }
-      }
-
-      throw error
-    }
+      return recursiveToCamel(data) as Camelize<FileObjectV2>
+    })
   }
 
   /**
@@ -1035,24 +937,14 @@ export default class StorageFileApi {
         error: StorageError
       }
   > {
-    try {
-      const data = await remove(
+    return this.handleOperation(async () => {
+      return await remove(
         this.fetch,
         `${this.url}/object/${this.bucketId}`,
         { prefixes: paths },
         { headers: this.headers }
       )
-      return { data, error: null }
-    } catch (error) {
-      if (this.shouldThrowOnError) {
-        throw error
-      }
-      if (isStorageError(error)) {
-        return { data: null, error }
-      }
-
-      throw error
-    }
+    })
   }
 
   /**
@@ -1191,26 +1083,16 @@ export default class StorageFileApi {
         error: StorageError
       }
   > {
-    try {
+    return this.handleOperation(async () => {
       const body = { ...DEFAULT_SEARCH_OPTIONS, ...options, prefix: path || '' }
-      const data = await post(
+      return await post(
         this.fetch,
         `${this.url}/object/list/${this.bucketId}`,
         body,
         { headers: this.headers },
         parameters
       )
-      return { data, error: null }
-    } catch (error) {
-      if (this.shouldThrowOnError) {
-        throw error
-      }
-      if (isStorageError(error)) {
-        return { data: null, error }
-      }
-
-      throw error
-    }
+    })
   }
 
   /**
@@ -1233,26 +1115,16 @@ export default class StorageFileApi {
         error: StorageError
       }
   > {
-    try {
+    return this.handleOperation(async () => {
       const body = { ...options }
-      const data = await post(
+      return await post(
         this.fetch,
         `${this.url}/object/list-v2/${this.bucketId}`,
         body,
         { headers: this.headers },
         parameters
       )
-      return { data, error: null }
-    } catch (error) {
-      if (this.shouldThrowOnError) {
-        throw error
-      }
-      if (isStorageError(error)) {
-        return { data: null, error }
-      }
-
-      throw error
-    }
+    })
   }
 
   protected encodeMetadata(metadata: Record<string, any>) {

package/src/{lib/vectors → packages}/StorageVectorsClient.ts

@@ -1,6 +1,6 @@
 import VectorIndexApi, { CreateIndexOptions } from './VectorIndexApi'
 import VectorDataApi from './VectorDataApi'
-import { Fetch } from './fetch'
+import { Fetch } from '../lib/common/fetch'
 import VectorBucketApi from './VectorBucketApi'
 import {
   ApiResponse,
@@ -13,7 +13,7 @@ import {
   PutVectorsOptions,
   QueryVectorsOptions,
   VectorBucket,
-} from './types'
+} from '../lib/types'
 
 /**
  *

package/src/packages/StreamDownloadBuilder.ts

@@ -1,4 +1,4 @@
-import { isStorageError } from '../lib/errors'
+import { isStorageError } from '../lib/common/errors'
 import { DownloadResult } from '../lib/types'
 
 export default class StreamDownloadBuilder implements PromiseLike<DownloadResult<ReadableStream>> {

package/src/packages/VectorBucketApi.ts

@@ -0,0 +1,73 @@
+import { DEFAULT_HEADERS } from '../lib/constants'
+import { StorageError } from '../lib/common/errors'
+import { Fetch, post } from '../lib/common/fetch'
+import BaseApiClient from '../lib/common/BaseApiClient'
+import {
+  ApiResponse,
+  VectorBucket,
+  ListVectorBucketsOptions,
+  ListVectorBucketsResponse,
+} from '../lib/types'
+
+/**
+ * @hidden
+ * Base implementation for vector bucket operations.
+ * Use {@link StorageVectorsClient} via `supabase.storage.vectors` instead.
+ */
+export default class VectorBucketApi extends BaseApiClient<StorageError> {
+  /** Creates a new VectorBucketApi instance */
+  constructor(url: string, headers: { [key: string]: string } = {}, fetch?: Fetch) {
+    const finalUrl = url.replace(/\/$/, '')
+    const finalHeaders = { ...DEFAULT_HEADERS, 'Content-Type': 'application/json', ...headers }
+    super(finalUrl, finalHeaders, fetch, 'vectors')
+  }
+
+  /** Creates a new vector bucket */
+  async createBucket(vectorBucketName: string): Promise<ApiResponse<undefined>> {
+    return this.handleOperation(async () => {
+      const data = await post(
+        this.fetch,
+        `${this.url}/CreateVectorBucket`,
+        { vectorBucketName },
+        { headers: this.headers }
+      )
+      return data || {}
+    })
+  }
+
+  /** Retrieves metadata for a specific vector bucket */
+  async getBucket(vectorBucketName: string): Promise<ApiResponse<{ vectorBucket: VectorBucket }>> {
+    return this.handleOperation(async () => {
+      return await post(
+        this.fetch,
+        `${this.url}/GetVectorBucket`,
+        { vectorBucketName },
+        { headers: this.headers }
+      )
+    })
+  }
+
+  /** Lists vector buckets with optional filtering and pagination */
+  async listBuckets(
+    options: ListVectorBucketsOptions = {}
+  ): Promise<ApiResponse<ListVectorBucketsResponse>> {
+    return this.handleOperation(async () => {
+      return await post(this.fetch, `${this.url}/ListVectorBuckets`, options, {
+        headers: this.headers,
+      })
+    })
+  }
+
+  /** Deletes a vector bucket (must be empty first) */
+  async deleteBucket(vectorBucketName: string): Promise<ApiResponse<undefined>> {
+    return this.handleOperation(async () => {
+      const data = await post(
+        this.fetch,
+        `${this.url}/DeleteVectorBucket`,
+        { vectorBucketName },
+        { headers: this.headers }
+      )
+      return data || {}
+    })
+  }
+}

package/src/packages/VectorDataApi.ts

@@ -0,0 +1,98 @@
+import { DEFAULT_HEADERS } from '../lib/constants'
+import { StorageError } from '../lib/common/errors'
+import { Fetch, post } from '../lib/common/fetch'
+import BaseApiClient from '../lib/common/BaseApiClient'
+import {
+  ApiResponse,
+  PutVectorsOptions,
+  GetVectorsOptions,
+  GetVectorsResponse,
+  DeleteVectorsOptions,
+  ListVectorsOptions,
+  ListVectorsResponse,
+  QueryVectorsOptions,
+  QueryVectorsResponse,
+} from '../lib/types'
+
+/**
+ * @hidden
+ * Base implementation for vector data operations.
+ * Use {@link VectorIndexScope} via `supabase.storage.vectors.from('bucket').index('idx')` instead.
+ */
+export default class VectorDataApi extends BaseApiClient<StorageError> {
+  /** Creates a new VectorDataApi instance */
+  constructor(url: string, headers: { [key: string]: string } = {}, fetch?: Fetch) {
+    const finalUrl = url.replace(/\/$/, '')
+    const finalHeaders = { ...DEFAULT_HEADERS, 'Content-Type': 'application/json', ...headers }
+    super(finalUrl, finalHeaders, fetch, 'vectors')
+  }
+
+  /** Inserts or updates vectors in batch (1-500 per request) */
+  async putVectors(options: PutVectorsOptions): Promise<ApiResponse<undefined>> {
+    // 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')
+    }
+
+    return this.handleOperation(async () => {
+      const data = await post(this.fetch, `${this.url}/PutVectors`, options, {
+        headers: this.headers,
+      })
+      return data || {}
+    })
+  }
+
+  /** Retrieves vectors by their keys in batch */
+  async getVectors(options: GetVectorsOptions): Promise<ApiResponse<GetVectorsResponse>> {
+    return this.handleOperation(async () => {
+      return await post(this.fetch, `${this.url}/GetVectors`, options, {
+        headers: this.headers,
+      })
+    })
+  }
+
+  /** Lists vectors in an index with pagination */
+  async listVectors(options: ListVectorsOptions): Promise<ApiResponse<ListVectorsResponse>> {
+    // 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}`)
+        }
+      }
+    }
+
+    return this.handleOperation(async () => {
+      return await post(this.fetch, `${this.url}/ListVectors`, options, {
+        headers: this.headers,
+      })
+    })
+  }
+
+  /** Queries for similar vectors using approximate nearest neighbor search */
+  async queryVectors(options: QueryVectorsOptions): Promise<ApiResponse<QueryVectorsResponse>> {
+    return this.handleOperation(async () => {
+      return await post(this.fetch, `${this.url}/QueryVectors`, options, {
+        headers: this.headers,
+      })
+    })
+  }
+
+  /** Deletes vectors by their keys in batch (1-500 per request) */
+  async deleteVectors(options: DeleteVectorsOptions): Promise<ApiResponse<undefined>> {
+    // 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')
+    }
+
+    return this.handleOperation(async () => {
+      const data = await post(this.fetch, `${this.url}/DeleteVectors`, options, {
+        headers: this.headers,
+      })
+      return data || {}
+    })
+  }
+}