docs(storage): enhance storage docs (#1865)

Author: mandarini

packages/core/storage-js/README.md

@@ -209,7 +209,17 @@ await storageClient.analytics.deleteBucket('analytics-data')
 - Retrieve the details of all Storage buckets within an existing project:
 
   ```js
+  // List all buckets
   const { data, error } = await storageClient.listBuckets()
+
+  // List buckets with options (pagination, sorting, search)
+  const { data, error } = await storageClient.listBuckets({
+    limit: 10,
+    offset: 0,
+    sortColumn: 'created_at',
+    sortOrder: 'desc',
+    search: 'prod',
+  })
   ```
 
 #### Handling Files

packages/core/storage-js/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

packages/core/storage-js/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
    *