fix(storage): improve docs and tests

Author: itslenny

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

@@ -393,8 +393,8 @@ 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' }`.
+   * Maps to `DELETE /cdn/{bucket}` on the Storage API. The server
+   * issues a CDN invalidation for the bucket 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
@@ -404,12 +404,9 @@ export default class StorageBucketApi extends BaseApiClient<StorageError> {
    * 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 id The unique identifier of the bucket you would like to purge from cache.
    * @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.
    *

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

@@ -569,22 +569,24 @@ describe('Bucket API Error Handling', () => {
     })
 
     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' } }
-          )
+      const fetchMock = jest.fn().mockResolvedValue(
+        new Response(
+          JSON.stringify({
+            statusCode: '403',
+            error: 'Forbidden',
+            message: 'Feature not enabled',
+          }),
+          { status: 403, 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')
+      expect(error?.message).toBe('Feature not enabled')
     })
 
     it('forwards the AbortController signal to fetch', async () => {

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

@@ -1058,8 +1058,8 @@ describe('purgeCache', () => {
       .fn()
       .mockResolvedValue(
         new Response(
-          JSON.stringify({ statusCode: '404', error: 'Not Found', message: 'Object not found' }),
-          { status: 404, headers: { 'Content-Type': 'application/json' } }
+          JSON.stringify({ statusCode: '403', error: 'Forbidden', message: 'Feature not enabled' }),
+          { status: 403, headers: { 'Content-Type': 'application/json' } }
         )
       )
     global.fetch = fetchMock
@@ -1069,7 +1069,7 @@ describe('purgeCache', () => {
 
     expect(data).toBeNull()
     expect(error).toBeInstanceOf(StorageApiError)
-    expect(error?.message).toBe('Object not found')
+    expect(error?.message).toBe('Feature not enabled')
   })
 
   it('forwards the AbortController signal to fetch', async () => {