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

package/src/lib/vectors/VectorIndexApi.ts

@@ -13,9 +13,12 @@ import {
 } from './types'
 
 /**
+ *
+ * @alpha
+ *
  * Options for creating a vector index
  *
- * **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 CreateIndexOptions {
   vectorBucketName: string
@@ -27,10 +30,13 @@ export interface CreateIndexOptions {
 }
 
 /**
+ *
+ * @alpha
+ *
  * API class for managing Vector Indexes within Vector Buckets
  * Provides methods for creating, reading, listing, and deleting vector indexes
  *
- * **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 VectorIndexApi {
   protected url: string
@@ -39,13 +45,22 @@ export default class VectorIndexApi {
   protected shouldThrowOnError = false
 
   /**
+   *
+   * @alpha
+   *
    * Creates an API client for managing vector indexes.
    *
-   * **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 sent with each request.
    * @param fetch - Optional custom `fetch` implementation for non-browser runtimes.
+   *
+   * @example
+   * ```typescript
+   * const client = new VectorIndexApi(url, headers)
+   * ```
    */
   constructor(url: string, headers: { [key: string]: string } = {}, fetch?: Fetch) {
     this.url = url.replace(/\/$/, '')
@@ -54,11 +69,15 @@ export default class VectorIndexApi {
   }
 
   /**
+   *
+   * @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
@@ -73,11 +92,15 @@ export default class VectorIndexApi {
   }
 
   /**
+   *
+   * @alpha
+   *
    * Creates a new vector index within a bucket
    * Defines the schema for vectors including dimensionality, distance metric, and metadata config
    *
-   * **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
    * @param options.vectorBucketName - Name of the parent vector bucket
    * @param options.indexName - Unique name for the index within the bucket
@@ -125,11 +148,15 @@ export default class VectorIndexApi {
   }
 
   /**
+   *
+   * @alpha
+   *
    * Retrieves metadata for a specific vector index
    * Returns index configuration including dimension, distance metric, and metadata settings
    *
-   * **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 parent vector bucket
    * @param indexName - Name of the index to retrieve
    * @returns Promise with index metadata or error
@@ -171,11 +198,15 @@ export default class VectorIndexApi {
   }
 
   /**
+   *
+   * @alpha
+   *
    * Lists vector indexes within a bucket 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.vectorBucketName - Name of the parent vector bucket
    * @param options.prefix - Filter indexes by name prefix
@@ -224,11 +255,15 @@ export default class VectorIndexApi {
   }
 
   /**
+   *
+   * @alpha
+   *
    * Deletes a vector index and all its data
    * This operation removes the index schema and all vectors stored in the index
    *
-   * **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 parent vector bucket
    * @param indexName - Name of the index to delete
    * @returns Promise with empty response on success or error

package/src/lib/version.ts

@@ -4,4 +4,4 @@
 // - Debugging and support (identifying which version is running)
 // - Telemetry and logging (version reporting in errors/analytics)
 // - Ensuring build artifacts match the published package version
-export const version = '2.81.2-canary.3'
+export const version = '2.82.0'

package/src/packages/StorageAnalyticsApi.ts

@@ -16,9 +16,18 @@ export default class StorageAnalyticsApi {
 
   /**
    * Creates a new StorageAnalyticsApi instance
+   *
+   * **Public alpha:** This API is part of a public alpha release and may not be available to your account type.
+   *
+   * @category Analytics Buckets
    * @param url - The base URL for the storage API
    * @param headers - HTTP headers to include in requests
    * @param fetch - Optional custom fetch implementation
+   *
+   * @example
+   * ```typescript
+   * const client = new StorageAnalyticsApi(url, headers)
+   * ```
    */
   constructor(url: string, headers: { [key: string]: string } = {}, fetch?: Fetch) {
     this.url = url.replace(/\/$/, '')
@@ -30,6 +39,9 @@ export default class StorageAnalyticsApi {
    * Enable throwing errors instead of returning them in the response
    * When enabled, failed operations will throw instead of returning { data: null, error }
    *
+   * **Public alpha:** This API is part of a public alpha release and may not be available to your account type.
+   *
+   * @category Analytics Buckets
    * @returns This instance for method chaining
    */
   public throwOnError(): this {
@@ -41,16 +53,27 @@ export default class StorageAnalyticsApi {
    * Creates a new analytics bucket using Iceberg tables
    * Analytics buckets are optimized for analytical queries and data processing
    *
+   * **Public alpha:** This API is part of a public alpha release and may not be available to your account type.
+   *
+   * @category Analytics Buckets
    * @param name A unique name for the bucket you are creating
    * @returns Promise with newly created bucket name or error
    *
-   * @example
-   * ```typescript
-   * const { data, error } = await storage.analytics.createBucket('analytics-data')
-   * if (error) {
-   *   console.error('Failed to create analytics bucket:', error.message)
-   * } else {
-   *   console.log('Created bucket:', data.name)
+   * @example Create analytics bucket
+   * ```js
+   * const { data, error } = await supabase
+   *   .storage
+   *   .analytics
+   *   .createBucket('analytics-data')
+   * ```
+   *
+   * Response:
+   * ```json
+   * {
+   *   "data": {
+   *     "name": "analytics-data"
+   *   },
+   *   "error": null
    * }
    * ```
    */
@@ -83,6 +106,9 @@ export default class StorageAnalyticsApi {
    * Retrieves the details of all Analytics Storage buckets within an existing project
    * Only returns buckets of type 'ANALYTICS'
    *
+   * **Public alpha:** This API is part of a public alpha release and may not be available to your account type.
+   *
+   * @category Analytics Buckets
    * @param options Query parameters for listing buckets
    * @param options.limit Maximum number of buckets to return
    * @param options.offset Number of buckets to skip
@@ -91,18 +117,32 @@ export default class StorageAnalyticsApi {
    * @param options.search Search term to filter bucket names
    * @returns Promise with list of analytics buckets or error
    *
-   * @example
-   * ```typescript
-   * const { data, error } = await storage.analytics.listBuckets({
-   *   limit: 10,
-   *   offset: 0,
-   *   sortColumn: 'created_at',
-   *   sortOrder: 'desc',
-   *   search: 'analytics'
-   * })
-   * if (data) {
-   *   console.log('Found analytics buckets:', data.length)
-   *   data.forEach(bucket => console.log(`- ${bucket.name}`))
+   * @example List analytics buckets
+   * ```js
+   * const { data, error } = await supabase
+   *   .storage
+   *   .analytics
+   *   .listBuckets({
+   *     limit: 10,
+   *     offset: 0,
+   *     sortColumn: 'created_at',
+   *     sortOrder: 'desc'
+   *   })
+   * ```
+   *
+   * Response:
+   * ```json
+   * {
+   *   "data": [
+   *     {
+   *       "id": "analytics-data",
+   *       "name": "analytics-data",
+   *       "type": "ANALYTICS",
+   *       "created_at": "2024-05-22T22:26:05.100Z",
+   *       "updated_at": "2024-05-22T22:26:05.100Z"
+   *     }
+   *   ],
+   *   "error": null
    * }
    * ```
    */
@@ -154,16 +194,27 @@ export default class StorageAnalyticsApi {
    * A bucket can't be deleted with existing objects inside it
    * You must first empty the bucket before deletion
    *
+   * **Public alpha:** This API is part of a public alpha release and may not be available to your account type.
+   *
+   * @category Analytics Buckets
    * @param bucketName The unique identifier of the bucket you would like to delete
    * @returns Promise with success message or error
    *
-   * @example
-   * ```typescript
-   * const { data, error } = await analyticsApi.deleteBucket('old-analytics-bucket')
-   * if (error) {
-   *   console.error('Failed to delete bucket:', error.message)
-   * } else {
-   *   console.log('Bucket deleted successfully:', data.message)
+   * @example Delete analytics bucket
+   * ```js
+   * const { data, error } = await supabase
+   *   .storage
+   *   .analytics
+   *   .deleteBucket('analytics-data')
+   * ```
+   *
+   * Response:
+   * ```json
+   * {
+   *   "data": {
+   *     "message": "Successfully deleted"
+   *   },
+   *   "error": null
    * }
    * ```
    */

package/src/packages/StorageBucketApi.ts

@@ -35,6 +35,8 @@ export default class StorageBucketApi {
 
   /**
    * Enable throwing errors instead of returning them.
+   *
+   * @category File Buckets
    */
   public throwOnError(): this {
     this.shouldThrowOnError = true
@@ -43,6 +45,35 @@ export default class StorageBucketApi {
 
   /**
    * Retrieves the details of all Storage buckets within an existing project.
+   *
+   * @category File Buckets
+   * @param options Query parameters for listing buckets
+   * @param options.limit Maximum number of buckets to return
+   * @param options.offset Number of buckets to skip
+   * @param options.sortColumn Column to sort by ('id', 'name', 'created_at', 'updated_at')
+   * @param options.sortOrder Sort order ('asc' or 'desc')
+   * @param options.search Search term to filter bucket names
+   * @returns Promise with list of buckets or error
+   *
+   * @example List buckets
+   * ```js
+   * const { data, error } = await supabase
+   *   .storage
+   *   .listBuckets()
+   * ```
+   *
+   * @example List buckets with options
+   * ```js
+   * const { data, error } = await supabase
+   *   .storage
+   *   .listBuckets({
+   *     limit: 10,
+   *     offset: 0,
+   *     sortColumn: 'created_at',
+   *     sortOrder: 'desc',
+   *     search: 'prod'
+   *   })
+   * ```
    */
   async listBuckets(options?: ListBucketOptions): Promise<
     | {
@@ -75,7 +106,35 @@ export default class StorageBucketApi {
   /**
    * Retrieves the details of an existing Storage bucket.
    *
+   * @category File Buckets
    * @param id The unique identifier of the bucket you would like to retrieve.
+   * @returns Promise with bucket details or error
+   *
+   * @example Get bucket
+   * ```js
+   * const { data, error } = await supabase
+   *   .storage
+   *   .getBucket('avatars')
+   * ```
+   *
+   * Response:
+   * ```json
+   * {
+   *   "data": {
+   *     "id": "avatars",
+   *     "name": "avatars",
+   *     "owner": "",
+   *     "public": false,
+   *     "file_size_limit": 1024,
+   *     "allowed_mime_types": [
+   *       "image/png"
+   *     ],
+   *     "created_at": "2024-05-22T22:26:05.100Z",
+   *     "updated_at": "2024-05-22T22:26:05.100Z"
+   *   },
+   *   "error": null
+   * }
+   * ```
    */
   async getBucket(id: string): Promise<
     | {
@@ -105,6 +164,7 @@ export default class StorageBucketApi {
   /**
    * Creates a new Storage bucket
    *
+   * @category File Buckets
    * @param id A unique identifier for the bucket you are creating.
    * @param options.public The visibility of the bucket. Public buckets don't require an authorization token to download objects, but still require a valid token for all other operations. By default, buckets are private.
    * @param options.fileSizeLimit specifies the max file size in bytes that can be uploaded to this bucket.
@@ -113,9 +173,30 @@ export default class StorageBucketApi {
    * @param options.allowedMimeTypes specifies the allowed mime types that this bucket can accept during upload.
    * The default value is null, which allows files with all mime types to be uploaded.
    * Each mime type specified can be a wildcard, e.g. image/*, or a specific mime type, e.g. image/png.
-   * @returns newly created bucket id
    * @param options.type (private-beta) specifies the bucket type. see `BucketType` for more details.
    *   - default bucket type is `STANDARD`
+   * @returns Promise with newly created bucket id or error
+   *
+   * @example Create bucket
+   * ```js
+   * const { data, error } = await supabase
+   *   .storage
+   *   .createBucket('avatars', {
+   *     public: false,
+   *     allowedMimeTypes: ['image/png'],
+   *     fileSizeLimit: 1024
+   *   })
+   * ```
+   *
+   * Response:
+   * ```json
+   * {
+   *   "data": {
+   *     "name": "avatars"
+   *   },
+   *   "error": null
+   * }
+   * ```
    */
   async createBucket(
     id: string,
@@ -167,6 +248,7 @@ export default class StorageBucketApi {
   /**
    * Updates a Storage bucket
    *
+   * @category File Buckets
    * @param id A unique identifier for the bucket you are updating.
    * @param options.public The visibility of the bucket. Public buckets don't require an authorization token to download objects, but still require a valid token for all other operations.
    * @param options.fileSizeLimit specifies the max file size in bytes that can be uploaded to this bucket.
@@ -175,6 +257,28 @@ export default class StorageBucketApi {
    * @param options.allowedMimeTypes specifies the allowed mime types that this bucket can accept during upload.
    * The default value is null, which allows files with all mime types to be uploaded.
    * Each mime type specified can be a wildcard, e.g. image/*, or a specific mime type, e.g. image/png.
+   * @returns Promise with success message or error
+   *
+   * @example Update bucket
+   * ```js
+   * const { data, error } = await supabase
+   *   .storage
+   *   .updateBucket('avatars', {
+   *     public: false,
+   *     allowedMimeTypes: ['image/png'],
+   *     fileSizeLimit: 1024
+   *   })
+   * ```
+   *
+   * Response:
+   * ```json
+   * {
+   *   "data": {
+   *     "message": "Successfully updated"
+   *   },
+   *   "error": null
+   * }
+   * ```
    */
   async updateBucket(
     id: string,
@@ -222,7 +326,26 @@ export default class StorageBucketApi {
   /**
    * Removes all objects inside a single bucket.
    *
+   * @category File Buckets
    * @param id The unique identifier of the bucket you would like to empty.
+   * @returns Promise with success message or error
+   *
+   * @example Empty bucket
+   * ```js
+   * const { data, error } = await supabase
+   *   .storage
+   *   .emptyBucket('avatars')
+   * ```
+   *
+   * Response:
+   * ```json
+   * {
+   *   "data": {
+   *     "message": "Successfully emptied"
+   *   },
+   *   "error": null
+   * }
+   * ```
    */
   async emptyBucket(id: string): Promise<
     | {
@@ -258,7 +381,26 @@ export default class StorageBucketApi {
    * Deletes an existing bucket. A bucket can't be deleted with existing objects inside it.
    * You must first `empty()` the bucket.
    *
+   * @category File Buckets
    * @param id The unique identifier of the bucket you would like to delete.
+   * @returns Promise with success message or error
+   *
+   * @example Delete bucket
+   * ```js
+   * const { data, error } = await supabase
+   *   .storage
+   *   .deleteBucket('avatars')
+   * ```
+   *
+   * Response:
+   * ```json
+   * {
+   *   "data": {
+   *     "message": "Successfully deleted"
+   *   },
+   *   "error": null
+   * }
+   * ```
    */
   async deleteBucket(id: string): Promise<
     | {