feat(storage): expose purge cache for entire bucket

Author: itslenny

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

@@ -2,7 +2,7 @@ import { DEFAULT_HEADERS } from '../lib/constants'
 import { StorageError } from '../lib/common/errors'
 import { Fetch, get, post, put, remove } from '../lib/common/fetch'
 import BaseApiClient from '../lib/common/BaseApiClient'
-import { Bucket, BucketType, ListBucketOptions } from '../lib/types'
+import { Bucket, BucketType, FetchParameters, ListBucketOptions } from '../lib/types'
 import { StorageClientOptions } from '../StorageClient'
 
 export default class StorageBucketApi extends BaseApiClient<StorageError> {
@@ -390,6 +390,60 @@ export default class StorageBucketApi extends BaseApiClient<StorageError> {
     })
   }
 
+  /**
+   * Purges the CDN cache for an entire bucket.
+   *
+   * Maps to `DELETE /cdn/{bucket}/{path}` on the Storage API. The server
+   * issues a CDN invalidation for the object and returns `{ message: 'success' }`.
+   *
+   * **Requires the `service_role` key.** The underlying endpoint enforces
+   * `service_role` JWT — calls made with the anon key or a user JWT will be
+   * rejected by the server.
+   *
+   * **Hosted CDN feature.** On self-hosted Supabase, the Storage service must
+   * have `CDN_PURGE_ENDPOINT_URL` configured and the `purgeCache` tenant
+   * feature enabled, otherwise the server returns an error.
+   *
+   * Operates on a single object path. There is no wildcard or recursion: pass
+   * the exact path of the object you want invalidated.
+   *
+   * @category Storage
+   * @subcategory File Buckets
+   * @param path The path (relative to the bucket) of the object to purge, e.g. `folder/avatar.png`.
+   * @param parameters Optional fetch parameters such as an `AbortController` signal.
+   * @returns Promise with `{ data: { message }, error: null }` on success or `{ data: null, error }` on failure.
+   *
+   * @example Purge cache for an entire bucket
+   * ```js
+   * const { data, error } = await supabase
+   *   .storage
+   *   .purgeBucketCache('avatars')
+   * ```
+   */
+  async purgeBucketCache(
+    id: string,
+    parameters?: FetchParameters
+  ): Promise<
+    | {
+        data: { message: string }
+        error: null
+      }
+    | {
+        data: null
+        error: StorageError
+      }
+  > {
+    return this.handleOperation(async () => {
+      return await remove(
+        this.fetch,
+        `${this.url}/cdn/${id}`,
+        {},
+        { headers: this.headers },
+        parameters
+      )
+    })
+  }
+
   private listBucketOptionsToQueryString(options?: ListBucketOptions): string {
     const params: Record<string, string> = {}
     if (options) {

packages/core/storage-js/test/storageBucketApi.test.ts

@@ -1,5 +1,5 @@
 import { StorageClient } from '../src/index'
-import { StorageUnknownError } from '../src/lib/common/errors'
+import { StorageApiError, StorageUnknownError } from '../src/lib/common/errors'
 
 // Create a simple Response implementation for testing
 class MockResponse {
@@ -539,4 +539,72 @@ describe('Bucket API Error Handling', () => {
       mockFn.mockRestore()
     })
   })
+
+  describe('purgeBucketCache', () => {
+    const PURGE_URL = 'http://localhost:8000/storage/v1'
+    const BUCKET = 'avatars'
+
+    afterEach(() => {
+      jest.restoreAllMocks()
+    })
+
+    it('issues DELETE to /cdn/{bucket} and returns the server message', async () => {
+      const fetchMock = jest.fn().mockResolvedValue(
+        new Response(JSON.stringify({ message: 'success' }), {
+          status: 200,
+          headers: { 'Content-Type': 'application/json' },
+        })
+      )
+      global.fetch = fetchMock
+
+      const client = new StorageClient(PURGE_URL, { apikey: 'service-role-token' })
+      const { data, error } = await client.purgeBucketCache(BUCKET)
+
+      expect(error).toBeNull()
+      expect(data?.message).toBe('success')
+      expect(fetchMock).toHaveBeenCalledWith(
+        `${PURGE_URL}/cdn/${BUCKET}`,
+        expect.objectContaining({ method: 'DELETE' })
+      )
+    })
+
+    it('surfaces server errors via StorageApiError', async () => {
+      const fetchMock = jest
+        .fn()
+        .mockResolvedValue(
+          new Response(
+            JSON.stringify({ statusCode: '404', error: 'Not Found', message: 'Object not found' }),
+            { status: 404, headers: { 'Content-Type': 'application/json' } }
+          )
+        )
+      global.fetch = fetchMock
+
+      const client = new StorageClient(PURGE_URL, { apikey: 'service-role-token' })
+      const { data, error } = await client.purgeBucketCache(BUCKET)
+
+      expect(data).toBeNull()
+      expect(error).toBeInstanceOf(StorageApiError)
+      expect(error?.message).toBe('Object not found')
+    })
+
+    it('forwards the AbortController signal to fetch', async () => {
+      const fetchMock = jest.fn().mockResolvedValue(
+        new Response(JSON.stringify({ message: 'success' }), {
+          status: 200,
+          headers: { 'Content-Type': 'application/json' },
+        })
+      )
+      global.fetch = fetchMock
+
+      const client = new StorageClient(PURGE_URL, { apikey: 'service-role-token' })
+      const controller = new AbortController()
+      const { error } = await client.purgeBucketCache(BUCKET, { signal: controller.signal })
+
+      expect(error).toBeNull()
+      expect(fetchMock).toHaveBeenCalledWith(
+        `${PURGE_URL}/cdn/${BUCKET}`,
+        expect.objectContaining({ method: 'DELETE', signal: controller.signal })
+      )
+    })
+  })
 })