@supabase/storage-js 2.81.2-canary.3 → 2.82.0

package/src/StorageClient.ts

@@ -12,6 +12,7 @@ export class StorageClient extends StorageBucketApi {
   /**
    * Creates a client for Storage buckets, files, analytics, and vectors.
    *
+   * @category File Buckets
    * @example
    * ```ts
    * import { StorageClient } from '@supabase/storage-js'
@@ -34,17 +35,27 @@ export class StorageClient extends StorageBucketApi {
   /**
    * Perform file operation in a bucket.
    *
+   * @category File Buckets
    * @param id The bucket id to operate on.
+   *
+   * @example
+   * ```typescript
+   * const avatars = storage.from('avatars')
+   * ```
    */
   from(id: string): StorageFileApi {
     return new StorageFileApi(this.url, this.headers, id, this.fetch)
   }
 
   /**
+   *
+   * @alpha
+   *
    * Access vector storage operations.
    *
-   * **Private alpha:** This API is part of a private alpha release and may change or be removed without notice.
+   * **Public alpha:** This API is part of a public alpha release and may not be available to your account type.
    *
+   * @category Vector Buckets
    * @returns A StorageVectorsClient instance configured with the current storage settings.
    */
   get vectors(): StorageVectorsClient {
@@ -57,6 +68,9 @@ export class StorageClient extends StorageBucketApi {
   /**
    * Access analytics storage operations using Iceberg tables.
    *
+   * **Public alpha:** This API is part of a public alpha release and may not be available to your account type.
+   *
+   * @category Analytics Buckets
    * @returns A StorageAnalyticsApi instance configured with the current storage settings.
    * @example
    * ```typescript

package/src/lib/vectors/StorageVectorsClient.ts

@@ -12,9 +12,12 @@ import {
 } from './types'
 
 /**
+ *
+ * @alpha
+ *
  * Configuration options for the Storage Vectors client
  *
- * **Private alpha:** Vector storage APIs are currently in private alpha and may not be accessible.
+ * **Public alpha:** This API is part of a public alpha release and may not be available to your account type.
  */
 export interface StorageVectorsClientOptions {
   /**
@@ -29,10 +32,13 @@ export interface StorageVectorsClientOptions {
 }
 
 /**
+ *
+ * @alpha
+ *
  * Main client for interacting with S3 Vectors API
  * Provides access to bucket, index, and vector data operations
  *
- * **Private alpha:** Vector storage APIs are currently in private alpha and may not be accessible.
+ * **Public alpha:** This API is part of a public alpha release and may not be available to your account type.
  *
  * **Usage Patterns:**
  *
@@ -87,24 +93,36 @@ export interface StorageVectorsClientOptions {
  */
 export class StorageVectorsClient extends VectorBucketApi {
   /**
+   * @alpha
+   *
    * Creates a StorageVectorsClient that can manage buckets, indexes, and vectors.
    *
-   * **Private alpha:** Vector storage APIs are currently in private alpha and may not be accessible.
+   * **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 of the Storage Vectors REST API.
    * @param options.headers - Optional headers (for example `Authorization`) applied to every request.
    * @param options.fetch - Optional custom `fetch` implementation for non-browser runtimes.
+   *
+   * @example
+   * ```typescript
+   * const client = new StorageVectorsClient(url, options)
+   * ```
    */
   constructor(url: string, options: StorageVectorsClientOptions = {}) {
     super(url, options.headers || {}, options.fetch)
   }
 
   /**
+   *
+   * @alpha
+   *
    * Access operations for a specific vector bucket
    * Returns a scoped client for index and vector operations within the bucket
    *
-   * **Private alpha:** Vector storage APIs are currently in private alpha and may not be accessible.
+   * **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
    * @returns Bucket-scoped client with index and vector operations
    *
@@ -130,18 +148,29 @@ export class StorageVectorsClient extends VectorBucketApi {
 }
 
 /**
+ *
+ * @alpha
+ *
  * Scoped client for operations within a specific vector bucket
  * Provides index management and access to vector operations
  *
- * **Private alpha:** Vector storage APIs are currently in private alpha and may not be accessible.
+ * **Public alpha:** This API is part of a public alpha release and may not be available to your account type.
  */
 export class VectorBucketScope extends VectorIndexApi {
   private vectorBucketName: string
 
   /**
+   * @alpha
+   *
    * Creates a helper that automatically scopes all index operations to the provided bucket.
    *
-   * **Private alpha:** Vector storage APIs are currently in private alpha and may not be accessible.
+   * **Public alpha:** This API is part of a public alpha release and may not be available to your account type.
+   *
+   * @category Vector Buckets
+   * @example
+   * ```typescript
+   * const bucket = client.bucket('embeddings-prod')
+   * ```
    */
   constructor(
     url: string,
@@ -154,11 +183,15 @@ export class VectorBucketScope extends VectorIndexApi {
   }
 
   /**
+   *
+   * @alpha
+   *
    * Creates a new vector index in this bucket
    * Convenience method that automatically includes the bucket name
    *
-   * **Private alpha:** Vector storage APIs are currently in private alpha and may not be accessible.
+   * **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 (vectorBucketName is automatically set)
    * @returns Promise with empty response on success or error
    *
@@ -184,11 +217,15 @@ export class VectorBucketScope extends VectorIndexApi {
   }
 
   /**
+   *
+   * @alpha
+   *
    * Lists indexes in this bucket
    * Convenience method that automatically includes the bucket name
    *
-   * **Private alpha:** Vector storage APIs are currently in private alpha and may not be accessible.
+   * **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 (vectorBucketName is automatically set)
    * @returns Promise with list of indexes or error
    *
@@ -206,11 +243,15 @@ export class VectorBucketScope extends VectorIndexApi {
   }
 
   /**
+   *
+   * @alpha
+   *
    * Retrieves metadata for a specific index in this bucket
    * Convenience method that automatically includes the bucket name
    *
-   * **Private alpha:** Vector storage APIs are currently in private alpha and may not be accessible.
+   * **Public alpha:** This API is part of a public alpha release and may not be available to your account type.
    *
+   * @category Vector Buckets
    * @param indexName - Name of the index to retrieve
    * @returns Promise with index metadata or error
    *
@@ -226,11 +267,15 @@ export class VectorBucketScope extends VectorIndexApi {
   }
 
   /**
+   *
+   * @alpha
+   *
    * Deletes an index from this bucket
    * Convenience method that automatically includes the bucket name
    *
-   * **Private alpha:** Vector storage APIs are currently in private alpha and may not be accessible.
+   * **Public alpha:** This API is part of a public alpha release and may not be available to your account type.
    *
+   * @category Vector Buckets
    * @param indexName - Name of the index to delete
    * @returns Promise with empty response on success or error
    *
@@ -245,11 +290,15 @@ export class VectorBucketScope extends VectorIndexApi {
   }
 
   /**
+   *
+   * @alpha
+   *
    * Access operations for a specific index within this bucket
    * Returns a scoped client for vector data operations
    *
-   * **Private alpha:** Vector storage APIs are currently in private alpha and may not be accessible.
+   * **Public alpha:** This API is part of a public alpha release and may not be available to your account type.
    *
+   * @category Vector Buckets
    * @param indexName - Name of the index
    * @returns Index-scoped client with vector data operations
    *
@@ -283,19 +332,31 @@ export class VectorBucketScope extends VectorIndexApi {
 }
 
 /**
+ *
+ * @alpha
+ *
  * Scoped client for operations within a specific vector index
  * Provides vector data operations (put, get, list, query, delete)
  *
- * **Private alpha:** Vector storage APIs are currently in private alpha and may not be accessible.
+ * **Public alpha:** This API is part of a public alpha release and may not be available to your account type.
  */
 export class VectorIndexScope extends VectorDataApi {
   private vectorBucketName: string
   private indexName: string
 
   /**
+   *
+   * @alpha
+   *
    * Creates a helper that automatically scopes all vector operations to the provided bucket/index names.
    *
-   * **Private alpha:** Vector storage APIs are currently in private alpha and may not be accessible.
+   * **Public alpha:** This API is part of a public alpha release and may not be available to your account type.
+   *
+   * @category Vector Buckets
+   * @example
+   * ```typescript
+   * const index = client.bucket('embeddings-prod').index('documents-openai')
+   * ```
    */
   constructor(
     url: string,
@@ -310,11 +371,15 @@ export class VectorIndexScope extends VectorDataApi {
   }
 
   /**
+   *
+   * @alpha
+   *
    * Inserts or updates vectors in this index
    * Convenience method that automatically includes bucket and index names
    *
-   * **Private alpha:** Vector storage APIs are currently in private alpha and may not be accessible.
+   * **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 (bucket and index names automatically set)
    * @returns Promise with empty response on success or error
    *
@@ -341,11 +406,15 @@ export class VectorIndexScope extends VectorDataApi {
   }
 
   /**
+   *
+   * @alpha
+   *
    * Retrieves vectors by keys from this index
    * Convenience method that automatically includes bucket and index names
    *
-   * **Private alpha:** Vector storage APIs are currently in private alpha and may not be accessible.
+   * **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 (bucket and index names automatically set)
    * @returns Promise with array of vectors or error
    *
@@ -367,11 +436,15 @@ export class VectorIndexScope extends VectorDataApi {
   }
 
   /**
+   *
+   * @alpha
+   *
    * Lists vectors in this index with pagination
    * Convenience method that automatically includes bucket and index names
    *
-   * **Private alpha:** Vector storage APIs are currently in private alpha and may not be accessible.
+   * **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 (bucket and index names automatically set)
    * @returns Promise with array of vectors and pagination token
    *
@@ -395,11 +468,15 @@ export class VectorIndexScope extends VectorDataApi {
   }
 
   /**
+   *
+   * @alpha
+   *
    * Queries for similar vectors in this index
    * Convenience method that automatically includes bucket and index names
    *
-   * **Private alpha:** Vector storage APIs are currently in private alpha and may not be accessible.
+   * **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 (bucket and index names automatically set)
    * @returns Promise with array of similar vectors ordered by distance
    *
@@ -426,11 +503,15 @@ export class VectorIndexScope extends VectorDataApi {
   }
 
   /**
+   *
+   * @alpha
+   *
    * Deletes vectors by keys from this index
    * Convenience method that automatically includes bucket and index names
    *
-   * **Private alpha:** Vector storage APIs are currently in private alpha and may not be accessible.
+   * **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 - Deletion options (bucket and index names automatically set)
    * @returns Promise with empty response on success or error
    *

package/src/lib/vectors/VectorBucketApi.ts

@@ -10,10 +10,13 @@ import {
 } from './types'
 
 /**
+ *
+ * @alpha
+ *
  * API class for managing Vector Buckets
  * Provides methods for creating, reading, listing, and deleting vector buckets
  *
- * **Private alpha:** Vector storage APIs are currently in private alpha and may not be accessible.
+ * **Public alpha:** This API is part of a public alpha release and may not be available to your account type.
  */
 export default class VectorBucketApi {
   protected url: string
@@ -22,9 +25,14 @@ export default class VectorBucketApi {
   protected shouldThrowOnError = false
 
   /**
+   *
+   * @alpha
+   *
    * Creates a new VectorBucketApi instance
    *
-   * **Private alpha:** Vector storage APIs are currently in private alpha and may not be accessible.
+   * **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
@@ -41,11 +49,15 @@ export default class VectorBucketApi {
   }
 
   /**
+   *
+   * @alpha
+   *
    * Enable throwing errors instead of returning them in the response
    * When enabled, failed operations will throw instead of returning { data: null, error }
    *
-   * **Private alpha:** Vector storage APIs are currently in private alpha and may not be accessible.
+   * **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
@@ -60,11 +72,15 @@ export default class VectorBucketApi {
   }
 
   /**
+   *
+   * @alpha
+   *
    * Creates a new vector bucket
    * Vector buckets are containers for vector indexes and their data
    *
-   * **Private alpha:** Vector storage APIs are currently in private alpha and may not be accessible.
+   * **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
    *
@@ -102,11 +118,15 @@ export default class VectorBucketApi {
   }
 
   /**
+   *
+   * @alpha
+   *
    * Retrieves metadata for a specific vector bucket
    * Returns bucket configuration including encryption settings and creation time
    *
-   * **Private alpha:** Vector storage APIs are currently in private alpha and may not be accessible.
+   * **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
    *
@@ -143,11 +163,15 @@ export default class VectorBucketApi {
   }
 
   /**
+   *
+   * @alpha
+   *
    * Lists vector buckets with optional filtering and pagination
    * Supports prefix-based filtering and paginated results
    *
-   * **Private alpha:** Vector storage APIs are currently in private alpha and may not be accessible.
+   * **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)
@@ -190,11 +214,15 @@ export default class VectorBucketApi {
   }
 
   /**
+   *
+   * @alpha
+   *
    * Deletes a vector bucket
    * Bucket must be empty before deletion (all indexes must be removed first)
    *
-   * **Private alpha:** Vector storage APIs are currently in private alpha and may not be accessible.
+   * **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
    *

package/src/lib/vectors/VectorDataApi.ts

@@ -15,10 +15,13 @@ import {
 } from './types'
 
 /**
+ *
+ * @alpha
+ *
  * API class for managing Vector Data within Vector Indexes
  * Provides methods for inserting, querying, listing, and deleting vector embeddings
  *
- * **Private alpha:** Vector storage APIs are currently in private alpha and may not be accessible.
+ * **Public alpha:** This API is part of a public alpha release and may not be available to your account type.
  */
 export default class VectorDataApi {
   protected url: string
@@ -27,13 +30,22 @@ export default class VectorDataApi {
   protected shouldThrowOnError = false
 
   /**
+   *
+   * @alpha
+   *
    * Creates a VectorDataApi bound to a Storage Vectors deployment.
    *
-   * **Private alpha:** Vector storage APIs are currently in private alpha and may not be accessible.
+   * **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)
+   * ```
    */
   constructor(url: string, headers: { [key: string]: string } = {}, fetch?: Fetch) {
     this.url = url.replace(/\/$/, '')
@@ -42,11 +54,15 @@ export default class VectorDataApi {
   }
 
   /**
+   *
+   * @alpha
+   *
    * Enable throwing errors instead of returning them in the response
    * When enabled, failed operations will throw instead of returning { data: null, error }
    *
-   * **Private alpha:** Vector storage APIs are currently in private alpha and may not be accessible.
+   * **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
@@ -61,11 +77,15 @@ export default class VectorDataApi {
   }
 
   /**
+   *
+   * @alpha
+   *
    * Inserts or updates vectors in batch (upsert operation)
    * Accepts 1-500 vectors per request. Larger batches should be split
    *
-   * **Private alpha:** Vector storage APIs are currently in private alpha and may not be accessible.
+   * **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
@@ -120,12 +140,16 @@ 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
    *
-   * **Private alpha:** Vector storage APIs are currently in private alpha and may not be accessible.
+   * **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
@@ -170,12 +194,16 @@ 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
    *
-   * **Private alpha:** Vector storage APIs are currently in private alpha and may not be accessible.
+   * **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
@@ -252,12 +280,16 @@ 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)
    *
-   * **Private alpha:** Vector storage APIs are currently in private alpha and may not be accessible.
+   * **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
@@ -313,11 +345,15 @@ export default class VectorDataApi {
   }
 
   /**
+   *
+   * @alpha
+   *
    * Deletes vectors by their keys in batch
    * Accepts 1-500 keys per request
    *
-   * **Private alpha:** Vector storage APIs are currently in private alpha and may not be accessible.
+   * **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