fix(storage): add custom endpoints for analytics buckets

fenos · fenos · commit a667ec56fa83 · 2025-10-16T16:46:18.000+02:00
diff --git a/packages/core/storage-js/src/StorageClient.ts b/packages/core/storage-js/src/StorageClient.ts
@@ -1,5 +1,6 @@
 import StorageFileApi from './packages/StorageFileApi'
 import StorageBucketApi from './packages/StorageBucketApi'
+import StorageAnalyticsApi from './packages/StorageAnalyticsApi'
 import { Fetch } from './lib/fetch'
 import { StorageVectorsClient } from '@supabase/storage-vectors-js'
 
@@ -31,10 +32,33 @@ export class StorageClient extends StorageBucketApi {
    *
    * @returns A StorageVectorsClient instance configured with the current storage settings.
    */
-  vectors(): StorageVectorsClient {
+  get vectors(): StorageVectorsClient {
     return new StorageVectorsClient(this.url + '/vector', {
       headers: this.headers,
       fetch: this.fetch,
     })
   }
+
+  /**
+   * Access analytics storage operations using Iceberg tables.
+   *
+   * @returns A StorageAnalyticsApi instance configured with the current storage settings.
+   * @example
+   * ```typescript
+   * const client = createClient(url, key)
+   * const analytics = client.storage.analytics
+   *
+   * // Create an analytics bucket
+   * await analytics.createBucket('my-analytics-bucket', { public: false })
+   *
+   * // List all analytics buckets
+   * const { data: buckets } = await analytics.listBuckets()
+   *
+   * // Delete an analytics bucket
+   * await analytics.deleteBucket('old-analytics-bucket')
+   * ```
+   */
+  get analytics(): StorageAnalyticsApi {
+    return new StorageAnalyticsApi(this.url + '/iceberg', this.headers, this.fetch)
+  }
 }
diff --git a/packages/core/storage-js/src/index.ts b/packages/core/storage-js/src/index.ts
@@ -1,5 +1,6 @@
 export { StorageClient } from './StorageClient'
 export type { StorageClientOptions } from './StorageClient'
+export { default as StorageAnalyticsApi } from './packages/StorageAnalyticsApi'
 export * from './lib/types'
 export * from './lib/errors'
 export * from '@supabase/storage-vectors-js'
diff --git a/packages/core/storage-js/src/lib/types.ts b/packages/core/storage-js/src/lib/types.ts
@@ -14,6 +14,14 @@ export interface Bucket {
   public: boolean
 }
 
+export interface AnalyticBucket {
+  id: string
+  type: "ANALYTICS"
+  format: string
+  created_at: string
+  updated_at: string
+}
+
 export interface FileObject {
   name: string
   bucket_id: string
diff --git a/packages/core/storage-js/src/packages/StorageAnalyticsApi.ts b/packages/core/storage-js/src/packages/StorageAnalyticsApi.ts
@@ -0,0 +1,203 @@
+import { DEFAULT_HEADERS } from '../lib/constants'
+import { isStorageError, StorageError } from '../lib/errors'
+import { Fetch, get, post, remove } from '../lib/fetch'
+import { resolveFetch } from '../lib/helpers'
+import { AnalyticBucket, Bucket } from '../lib/types'
+
+/**
+ * API class for managing Analytics Buckets using Iceberg tables
+ * Provides methods for creating, listing, and deleting analytics buckets
+ */
+export default class StorageAnalyticsApi {
+  protected url: string
+  protected headers: { [key: string]: string }
+  protected fetch: Fetch
+  protected shouldThrowOnError = false
+
+  constructor(url: string, headers: { [key: string]: string } = {}, fetch?: Fetch) {
+    this.url = url.replace(/\/$/, '')
+    this.headers = { ...DEFAULT_HEADERS, ...headers }
+    this.fetch = resolveFetch(fetch)
+  }
+
+  /**
+   * Enable throwing errors instead of returning them in the response
+   * When enabled, failed operations will throw instead of returning { data: null, error }
+   *
+   * @returns This instance for method chaining
+   */
+  public throwOnError(): this {
+    this.shouldThrowOnError = true
+    return this
+  }
+
+  /**
+   * Creates a new analytics bucket using Iceberg tables
+   * Analytics buckets are optimized for analytical queries and data processing
+   *
+   * @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)
+   * }
+   * ```
+   */
+  async createBucket(
+    name: string
+  ): Promise<
+    | {
+        data: AnalyticBucket,
+        error: null
+      }
+    | {
+        data: null
+        error: StorageError
+      }
+  > {
+    try {
+      const data = await post(
+        this.fetch,
+        `${this.url}/bucket`,
+        { name },
+        { headers: this.headers }
+      )
+      return { data, error: null }
+    } catch (error) {
+      if (this.shouldThrowOnError) {
+        throw error
+      }
+      if (isStorageError(error)) {
+        return { data: null, error }
+      }
+
+      throw error
+    }
+  }
+
+  /**
+   * Retrieves the details of all Analytics Storage buckets within an existing project
+   * Only returns buckets of type 'ANALYTICS'
+   *
+   * @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 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}`))
+   * }
+   * ```
+   */
+  async listBuckets(options?: {
+    limit?: number
+    offset?: number
+    sortColumn?: 'id' | 'name' | 'created_at' | 'updated_at'
+    sortOrder?: 'asc' | 'desc'
+    search?: string
+  }): Promise<
+    | {
+        data: AnalyticBucket[]
+        error: null
+      }
+    | {
+        data: null
+        error: StorageError
+      }
+  > {
+    try {
+      // Build query string from options
+      const queryParams = new URLSearchParams()
+      if (options?.limit !== undefined) queryParams.set('limit', options.limit.toString())
+      if (options?.offset !== undefined) queryParams.set('offset', options.offset.toString())
+      if (options?.sortColumn) queryParams.set('sortColumn', options.sortColumn)
+      if (options?.sortOrder) queryParams.set('sortOrder', options.sortOrder)
+      if (options?.search) queryParams.set('search', options.search)
+
+      const queryString = queryParams.toString()
+      const url = queryString ? `${this.url}/bucket?${queryString}` : `${this.url}/bucket`
+
+      const data = await get(this.fetch, url, { headers: this.headers })
+      // Filter to only return analytics buckets
+      const analyticsBuckets = Array.isArray(data)
+        ? data.filter((bucket: Bucket) => bucket.type === 'ANALYTICS')
+        : []
+      return { data: analyticsBuckets, error: null }
+    } catch (error) {
+      if (this.shouldThrowOnError) {
+        throw error
+      }
+      if (isStorageError(error)) {
+        return { data: null, error }
+      }
+
+      throw error
+    }
+  }
+
+  /**
+   * Deletes an existing analytics bucket
+   * A bucket can't be deleted with existing objects inside it
+   * You must first empty the bucket before deletion
+   *
+   * @param bucketId 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)
+   * }
+   * ```
+   */
+  async deleteBucket(bucketId: string): Promise<
+    | {
+        data: { message: string }
+        error: null
+      }
+    | {
+        data: null
+        error: StorageError
+      }
+  > {
+    try {
+      const data = await remove(
+        this.fetch,
+        `${this.url}/bucket/${bucketId}`,
+        {},
+        { headers: this.headers }
+      )
+      return { data, error: null }
+    } catch (error) {
+      if (this.shouldThrowOnError) {
+        throw error
+      }
+      if (isStorageError(error)) {
+        return { data: null, error }
+      }
+
+      throw error
+    }
+  }
+}
