docs(storage): overrides and rendering issues

packages/core/storage-js/README.md

@@ -67,7 +67,8 @@ If you're already using `@supabase/supabase-js`, access storage through the clie
 ```js
 import { createClient } from '@supabase/supabase-js'
 
-const supabase = createClient('https://<project_ref>.supabase.co', '<your-anon-key>')
+// Use publishable/anon key for frontend applications
+const supabase = createClient('https://<project_ref>.supabase.co', '<your-publishable-key>')
 
 // Access storage
 const storage = supabase.storage
@@ -80,13 +81,13 @@ const analyticsBucket = storage.analytics // Analytics API
 
 #### Option 2: Standalone StorageClient
 
-For applications that only need storage functionality:
+For backend applications or when you need to bypass Row Level Security:
 
 ```js
 import { StorageClient } from '@supabase/storage-js'
 
 const STORAGE_URL = 'https://<project_ref>.supabase.co/storage/v1'
-const SERVICE_KEY = '<service_role>' //! service key, not anon key
+const SERVICE_KEY = '<your-secret-key>' // Use secret key for backend operations
 
 const storageClient = new StorageClient(STORAGE_URL, {
   apikey: SERVICE_KEY,
@@ -101,8 +102,10 @@ const analyticsBucket = storageClient.analytics // Analytics API
 
 > **When to use each approach:**
 >
-> - Use `supabase.storage` when working with other Supabase features (auth, database, etc.)
-> - Use `new StorageClient()` for storage-only applications or when you need fine-grained control
+> - Use `supabase.storage` when working with other Supabase features (auth, database, etc.) in frontend applications
+> - Use `new StorageClient()` for backend applications, Edge Functions, or when you need to bypass RLS policies
+
+> **Note:** Refer to the [Storage Access Control guide](https://supabase.com/docs/guides/storage/access-control) for detailed information on creating RLS policies.
 
 ### Understanding Bucket Types
 
@@ -340,7 +343,7 @@ You can access analytics functionality through the `analytics` property on your
 ```typescript
 import { createClient } from '@supabase/supabase-js'
 
-const supabase = createClient('https://your-project.supabase.co', 'your-anon-key')
+const supabase = createClient('https://your-project.supabase.co', 'your-publishable-key')
 
 // Access analytics operations
 const analytics = supabase.storage.analytics
@@ -646,7 +649,7 @@ If you're using the full Supabase client:
 ```typescript
 import { createClient } from '@supabase/supabase-js'
 
-const supabase = createClient('https://your-project.supabase.co', 'your-anon-key')
+const supabase = createClient('https://your-project.supabase.co', 'your-publishable-key')
 
 // Access vector operations through storage
 const vectors = supabase.storage.vectors

packages/core/storage-js/src/lib/vectors/StorageVectorsClient.ts

@@ -3,12 +3,16 @@ import VectorDataApi from './VectorDataApi'
 import { Fetch } from './fetch'
 import VectorBucketApi from './VectorBucketApi'
 import {
+  ApiResponse,
   DeleteVectorsOptions,
   GetVectorsOptions,
   ListIndexesOptions,
   ListVectorsOptions,
+  ListVectorBucketsOptions,
+  ListVectorBucketsResponse,
   PutVectorsOptions,
   QueryVectorsOptions,
+  VectorBucket,
 } from './types'
 
 /**
@@ -116,6 +120,112 @@ export class StorageVectorsClient extends VectorBucketApi {
   from(vectorBucketName: string): VectorBucketScope {
     return new VectorBucketScope(this.url, this.headers, vectorBucketName, this.fetch)
   }
+
+  /**
+   *
+   * @alpha
+   *
+   * Creates a new vector bucket
+   * Vector buckets are containers for vector indexes and their data
+   *
+   * **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
+   *
+   * @example
+   * ```typescript
+   * const { data, error } = await supabase
+   *   .storage
+   *   .vectors
+   *   .createBucket('embeddings-prod')
+   * ```
+   */
+  async createBucket(vectorBucketName: string): Promise<ApiResponse<undefined>> {
+    return super.createBucket(vectorBucketName)
+  }
+
+  /**
+   *
+   * @alpha
+   *
+   * Retrieves metadata for a specific vector bucket
+   *
+   * **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 Promise with bucket metadata or error
+   *
+   * @example
+   * ```typescript
+   * const { data, error } = await supabase
+   *   .storage
+   *   .vectors
+   *   .getBucket('embeddings-prod')
+   *
+   * console.log('Bucket created:', data?.vectorBucket.creationTime)
+   * ```
+   */
+  async getBucket(vectorBucketName: string): Promise<ApiResponse<{ vectorBucket: VectorBucket }>> {
+    return super.getBucket(vectorBucketName)
+  }
+
+  /**
+   *
+   * @alpha
+   *
+   * Lists all vector buckets with optional filtering and pagination
+   *
+   * **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 - Optional filters (prefix, maxResults, nextToken)
+   * @returns Promise with list of buckets or error
+   *
+   * @example
+   * ```typescript
+   * const { data, error } = await supabase
+   *   .storage
+   *   .vectors
+   *   .listBuckets({ prefix: 'embeddings-' })
+   *
+   * data?.vectorBuckets.forEach(bucket => {
+   *   console.log(bucket.vectorBucketName)
+   * })
+   * ```
+   */
+  async listBuckets(
+    options: ListVectorBucketsOptions = {}
+  ): Promise<ApiResponse<ListVectorBucketsResponse>> {
+    return super.listBuckets(options)
+  }
+
+  /**
+   *
+   * @alpha
+   *
+   * Deletes a vector bucket (bucket must be empty)
+   * All indexes must be deleted before deleting the bucket
+   *
+   * **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
+   *
+   * @example
+   * ```typescript
+   * const { data, error } = await supabase
+   *   .storage
+   *   .vectors
+   *   .deleteBucket('embeddings-old')
+   * ```
+   */
+  async deleteBucket(vectorBucketName: string): Promise<ApiResponse<undefined>> {
+    return super.deleteBucket(vectorBucketName)
+  }
 }
 
 /**
@@ -198,7 +308,7 @@ export class VectorBucketScope extends VectorIndexApi {
    *
    * @category Vector Buckets
    * @param options - Listing options (vectorBucketName is automatically set)
-   * @returns Promise with list of indexes or error
+   * @returns Promise with response containing indexes array and pagination token or error
    *
    * @example
    * ```typescript
@@ -387,7 +497,7 @@ export class VectorIndexScope extends VectorDataApi {
    *
    * @category Vector Buckets
    * @param options - Vector retrieval options (bucket and index names automatically set)
-   * @returns Promise with array of vectors or error
+   * @returns Promise with response containing vectors array or error
    *
    * @example
    * ```typescript
@@ -417,7 +527,7 @@ export class VectorIndexScope extends VectorDataApi {
    *
    * @category Vector Buckets
    * @param options - Listing options (bucket and index names automatically set)
-   * @returns Promise with array of vectors and pagination token
+   * @returns Promise with response containing vectors array and pagination token or error
    *
    * @example
    * ```typescript
@@ -449,7 +559,7 @@ export class VectorIndexScope extends VectorDataApi {
    *
    * @category Vector Buckets
    * @param options - Query options (bucket and index names automatically set)
-   * @returns Promise with array of similar vectors ordered by distance
+   * @returns Promise with response containing matches array of similar vectors ordered by distance or error
    *
    * @example
    * ```typescript

packages/core/storage-js/src/packages/StorageAnalyticsClient.ts

@@ -63,7 +63,7 @@ export default class StorageAnalyticsClient {
    *
    * @category Analytics Buckets
    * @param name A unique name for the bucket you are creating
-   * @returns Promise with newly created bucket name or error
+   * @returns Promise with response containing newly created analytics bucket or error
    *
    * @example Create analytics bucket
    * ```js
@@ -124,10 +124,10 @@ export default class StorageAnalyticsClient {
    * @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.sortColumn Column to sort by ('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 analytics buckets or error
+   * @returns Promise with response containing array of analytics buckets or error
    *
    * @example List analytics buckets
    * ```js
@@ -161,7 +161,7 @@ export default class StorageAnalyticsClient {
   async listBuckets(options?: {
     limit?: number
     offset?: number
-    sortColumn?: 'id' | 'name' | 'created_at' | 'updated_at'
+    sortColumn?: 'name' | 'created_at' | 'updated_at'
     sortOrder?: 'asc' | 'desc'
     search?: string
   }): Promise<
@@ -212,7 +212,7 @@ export default class StorageAnalyticsClient {
    *
    * @category Analytics Buckets
    * @param bucketName The unique identifier of the bucket you would like to delete
-   * @returns Promise with success message or error
+   * @returns Promise with response containing success message or error
    *
    * @example Delete analytics bucket
    * ```js

packages/core/storage-js/src/packages/StorageBucketApi.ts

@@ -53,7 +53,7 @@ export default class StorageBucketApi {
    * @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
+   * @returns Promise with response containing array of buckets or error
    *
    * @example List buckets
    * ```js
@@ -108,7 +108,7 @@ export default class StorageBucketApi {
    *
    * @category File Buckets
    * @param id The unique identifier of the bucket you would like to retrieve.
-   * @returns Promise with bucket details or error
+   * @returns Promise with response containing bucket details or error
    *
    * @example Get bucket
    * ```js
@@ -175,7 +175,7 @@ export default class StorageBucketApi {
    * Each mime type specified can be a wildcard, e.g. image/*, or a specific mime type, e.g. image/png.
    * @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
+   * @returns Promise with response containing newly created bucket name or error
    *
    * @example Create bucket
    * ```js
@@ -257,7 +257,7 @@ 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
+   * @returns Promise with response containing success message or error
    *
    * @example Update bucket
    * ```js