From 9f4e8e22508f49246b4b3159507a856b02cf1e10 Mon Sep 17 00:00:00 2001
From: Rodrigo Mansueli Nunes <rodrigo@mansueli.com>
Date: Fri, 20 Jun 2025 10:13:37 -0300
Subject: [PATCH 1/8] expose purgeCache

---
 src/packages/StorageFileApi.ts           | 39 ++++++++++++++++++++++
 test/storageFileApi.test.ts              | 24 ++++++++++++++
 test/storageFileApiErrorHandling.test.ts | 41 ++++++++++++++++++++++++
 3 files changed, 104 insertions(+)

diff --git a/src/packages/StorageFileApi.ts b/src/packages/StorageFileApi.ts
index 82f1bb1..c31b67f 100644
--- a/src/packages/StorageFileApi.ts
+++ b/src/packages/StorageFileApi.ts
@@ -770,6 +770,45 @@ export default class StorageFileApi {
     }
   }
 
+  /**
+   * Purges the cache for a specific object or entire bucket from the CDN.
+   *
+   * @param path The file path to purge from cache. If not provided or set to '*', purges the entire bucket cache.
+   * @param parameters Optional fetch parameters like AbortController signal.
+   */
+  async purgeCache(
+    path: string = '*',
+    parameters?: FetchParameters
+  ): Promise<
+    | {
+        data: { message: string }
+        error: null
+      }
+    | {
+        data: null
+        error: StorageError
+      }
+  > {
+    try {
+      const cleanPath = path === '*' || !path ? '*' : this._removeEmptyFolders(path)
+      const cdnPath = `${this.bucketId}/${cleanPath}`
+      const data = await remove(
+        this.fetch,
+        `${this.url}/cdn/${cdnPath}`,
+        {},
+        { headers: this.headers },
+        parameters
+      )
+      return { data, error: null }
+    } catch (error) {
+      if (isStorageError(error)) {
+        return { data: null, error }
+      }
+
+      throw error
+    }
+  }
+
   protected encodeMetadata(metadata: Record<string, any>) {
     return JSON.stringify(metadata)
   }
diff --git a/test/storageFileApi.test.ts b/test/storageFileApi.test.ts
index 2db8ca5..b21ce6e 100644
--- a/test/storageFileApi.test.ts
+++ b/test/storageFileApi.test.ts
@@ -576,6 +576,30 @@ describe('Object API', () => {
       'height:200,width:200,resizing_type:fill,quality:60'
     )
   })
+
+  test('purge cache for specific object', async () => {
+    await storage.from(bucketName).upload(uploadPath, file)
+    const res = await storage.from(bucketName).purgeCache(uploadPath)
+
+    expect(res.error).toBeNull()
+    expect(res.data?.message).toEqual('success')
+  })
+
+  test('purge cache for entire bucket', async () => {
+    await storage.from(bucketName).upload(uploadPath, file)
+    const res = await storage.from(bucketName).purgeCache()
+
+    expect(res.error).toBeNull()
+    expect(res.data?.message).toEqual('success')
+  })
+
+  test('purge cache with wildcard', async () => {
+    await storage.from(bucketName).upload(uploadPath, file)
+    const res = await storage.from(bucketName).purgeCache('*')
+
+    expect(res.error).toBeNull()
+    expect(res.data?.message).toEqual('success')
+  })
 })
 
 describe('error handling', () => {
diff --git a/test/storageFileApiErrorHandling.test.ts b/test/storageFileApiErrorHandling.test.ts
index 53f694d..ecbeddd 100644
--- a/test/storageFileApiErrorHandling.test.ts
+++ b/test/storageFileApiErrorHandling.test.ts
@@ -314,4 +314,45 @@ describe('File API Error Handling', () => {
       mockFn.mockRestore()
     })
   })
+
+  describe('purgeCache', () => {
+    it('handles network errors', async () => {
+      const mockError = new Error('Network failure')
+      global.fetch = jest.fn().mockImplementation(() => Promise.reject(mockError))
+      const storage = new StorageClient(URL, { apikey: KEY })
+
+      const { data, error } = await storage.from(BUCKET_ID).purgeCache('test.png')
+      expect(data).toBeNull()
+      expect(error).not.toBeNull()
+      expect(error?.message).toBe('Network failure')
+    })
+
+    it('wraps non-Response errors as StorageUnknownError', async () => {
+      const nonResponseError = new TypeError('Invalid purge operation')
+      global.fetch = jest.fn().mockImplementation(() => Promise.reject(nonResponseError))
+
+      const storage = new StorageClient(URL, { apikey: KEY })
+
+      const { data, error } = await storage.from(BUCKET_ID).purgeCache('test.png')
+      expect(data).toBeNull()
+      expect(error).toBeInstanceOf(StorageUnknownError)
+      expect(error?.message).toBe('Invalid purge operation')
+    })
+
+    it('throws non-StorageError exceptions', async () => {
+      const storage = new StorageClient(URL, { apikey: KEY })
+
+      const mockFn = jest.spyOn(global, 'fetch').mockImplementationOnce(() => {
+        const error = new Error('Unexpected error in purgeCache')
+        Object.defineProperty(error, 'name', { value: 'CustomError' })
+        throw error
+      })
+
+      await expect(storage.from(BUCKET_ID).purgeCache('test.png')).rejects.toThrow(
+        'Unexpected error in purgeCache'
+      )
+
+      mockFn.mockRestore()
+    })
+  })
 })

From ab6b5123b756dc9f4ff5d7be9add60c9b4837064 Mon Sep 17 00:00:00 2001
From: Rodrigo Mansueli Nunes <rodrigo@mansueli.com>
Date: Fri, 20 Jun 2025 10:21:52 -0300
Subject: [PATCH 2/8] expose purgeCache

---
 test/storageFileApi.test.ts | 6 +++---
 1 file changed, 3 insertions(+), 3 deletions(-)

diff --git a/test/storageFileApi.test.ts b/test/storageFileApi.test.ts
index b21ce6e..3d02add 100644
--- a/test/storageFileApi.test.ts
+++ b/test/storageFileApi.test.ts
@@ -577,7 +577,7 @@ describe('Object API', () => {
     )
   })
 
-  test('purge cache for specific object', async () => {
+  test.skip('purge cache for specific object', async () => {
     await storage.from(bucketName).upload(uploadPath, file)
     const res = await storage.from(bucketName).purgeCache(uploadPath)
 
@@ -585,7 +585,7 @@ describe('Object API', () => {
     expect(res.data?.message).toEqual('success')
   })
 
-  test('purge cache for entire bucket', async () => {
+  test.skip('purge cache for entire bucket', async () => {
     await storage.from(bucketName).upload(uploadPath, file)
     const res = await storage.from(bucketName).purgeCache()
 
@@ -593,7 +593,7 @@ describe('Object API', () => {
     expect(res.data?.message).toEqual('success')
   })
 
-  test('purge cache with wildcard', async () => {
+  test.skip('purge cache with wildcard', async () => {
     await storage.from(bucketName).upload(uploadPath, file)
     const res = await storage.from(bucketName).purgeCache('*')
 

From a586efb7fc275579e00157f88394646f4c4d1891 Mon Sep 17 00:00:00 2001
From: Rodrigo Mansueli Nunes <rodrigo@mansueli.com>
Date: Fri, 20 Jun 2025 10:29:59 -0300
Subject: [PATCH 3/8] expose purgeCache

---
 test/storageFileApi.test.ts | 123 ++++++++++++++++++++++++++++++------
 1 file changed, 105 insertions(+), 18 deletions(-)

diff --git a/test/storageFileApi.test.ts b/test/storageFileApi.test.ts
index 3d02add..286f433 100644
--- a/test/storageFileApi.test.ts
+++ b/test/storageFileApi.test.ts
@@ -577,30 +577,117 @@ describe('Object API', () => {
     )
   })
 
-  test.skip('purge cache for specific object', async () => {
-    await storage.from(bucketName).upload(uploadPath, file)
-    const res = await storage.from(bucketName).purgeCache(uploadPath)
+    // Mock-based tests for coverage (until server endpoint is ready)
+    test('purge cache - mock successful response', async () => {
+      const originalFetch = global.fetch
+      global.fetch = jest.fn().mockResolvedValue({
+        ok: true,
+        json: async () => ({ message: 'success' })
+      })
 
-    expect(res.error).toBeNull()
-    expect(res.data?.message).toEqual('success')
-  })
+      try {
+        const res = await storage.from(bucketName).purgeCache('test-file.jpg')
+        expect(res.error).toBeNull()
+        expect(res.data?.message).toEqual('success')
+        expect(global.fetch).toHaveBeenCalledWith(
+          expect.stringContaining(`/cdn/${bucketName}/test-file.jpg`),
+          expect.objectContaining({
+            method: 'DELETE'
+          })
+        )
+      } finally {
+        global.fetch = originalFetch
+      }
+    })
+
+    test('purge cache - mock entire bucket', async () => {
+      const originalFetch = global.fetch
+      global.fetch = jest.fn().mockResolvedValue({
+        ok: true,
+        json: async () => ({ message: 'success' })
+      })
 
-  test.skip('purge cache for entire bucket', async () => {
-    await storage.from(bucketName).upload(uploadPath, file)
-    const res = await storage.from(bucketName).purgeCache()
+      try {
+        const res = await storage.from(bucketName).purgeCache()
+        expect(res.error).toBeNull()
+        expect(res.data?.message).toEqual('success')
+        expect(global.fetch).toHaveBeenCalledWith(
+          expect.stringContaining(`/cdn/${bucketName}/*`),
+          expect.objectContaining({
+            method: 'DELETE'
+          })
+        )
+      } finally {
+        global.fetch = originalFetch
+      }
+    })
+
+    test('purge cache - mock with path normalization', async () => {
+      const originalFetch = global.fetch
+      global.fetch = jest.fn().mockResolvedValue({
+        ok: true,
+        json: async () => ({ message: 'success' })
+      })
 
-    expect(res.error).toBeNull()
-    expect(res.data?.message).toEqual('success')
-  })
+      try {
+        const res = await storage.from(bucketName).purgeCache('/folder//file.jpg/')
+        expect(res.error).toBeNull()
+        expect(res.data?.message).toEqual('success')
+        
+        expect(global.fetch).toHaveBeenCalledWith(
+          expect.stringContaining(`/cdn/${bucketName}/folder/file.jpg`),
+          expect.objectContaining({
+            method: 'DELETE'
+          })
+        )
+      } finally {
+        global.fetch = originalFetch
+      }
+    })
+
+    test('purge cache - mock error response', async () => {
+      const originalFetch = global.fetch
+      global.fetch = jest.fn().mockResolvedValue({
+        ok: false,
+        status: 404,
+        json: async () => ({ error: 'Object not found' })
+      })
 
-  test.skip('purge cache with wildcard', async () => {
-    await storage.from(bucketName).upload(uploadPath, file)
-    const res = await storage.from(bucketName).purgeCache('*')
+      try {
+        const res = await storage.from(bucketName).purgeCache('nonexistent.jpg')
+        expect(res.data).toBeNull()
+        expect(res.error).not.toBeNull()
+        expect(res.error?.message).toContain('Object not found')
+      } finally {
+        global.fetch = originalFetch
+      }
+    })
 
-    expect(res.error).toBeNull()
-    expect(res.data?.message).toEqual('success')
+    // Integration tests (skipped until server endpoint is ready)
+    test.skip('purge cache for specific object', async () => {
+      await storage.from(bucketName).upload(uploadPath, file)
+      const res = await storage.from(bucketName).purgeCache(uploadPath)
+
+      expect(res.error).toBeNull()
+      expect(res.data?.message).toEqual('success')
+    })
+
+    test.skip('purge cache for entire bucket', async () => {
+      await storage.from(bucketName).upload(uploadPath, file)
+      const res = await storage.from(bucketName).purgeCache()
+
+      expect(res.error).toBeNull()
+      expect(res.data?.message).toEqual('success')
+    })
+
+    test.skip('purge cache with wildcard', async () => {
+      await storage.from(bucketName).upload(uploadPath, file)
+      const res = await storage.from(bucketName).purgeCache('*')
+
+      expect(res.error).toBeNull()
+      expect(res.data?.message).toEqual('success')
+    })
   })
-})
 
 describe('error handling', () => {
   let mockError: Error

From a321d31781809839f8191755e3ea89e4f90c3e0f Mon Sep 17 00:00:00 2001
From: Rodrigo Mansueli Nunes <rodrigo@mansueli.com>
Date: Fri, 20 Jun 2025 11:14:32 -0300
Subject: [PATCH 4/8] expose purgeCache

---
 src/packages/StorageFileApi.ts |  15 +-
 test/storageFileApi.test.ts    | 251 +++++++++++++++++----------------
 2 files changed, 141 insertions(+), 125 deletions(-)

diff --git a/src/packages/StorageFileApi.ts b/src/packages/StorageFileApi.ts
index c31b67f..971dbac 100644
--- a/src/packages/StorageFileApi.ts
+++ b/src/packages/StorageFileApi.ts
@@ -802,7 +802,20 @@ export default class StorageFileApi {
       return { data, error: null }
     } catch (error) {
       if (isStorageError(error)) {
-        return { data: null, error }
+        /**
+         * The Storage API returns `{ ok:false, status:404 }` for a purge of a
+         * non-existent object.  In that case we want to expose a stable,
+         * developer-friendly error message that the higher level tests (and
+         * potentially downstream apps) can rely on.
+         */
+        const err = error as StorageError
+        const status = (err as any).statusCode ?? (err as any).status
+
+        if (String(status) === '404') {
+          err.message = 'Object not found'
+        }
+
+        return { data: null, error: err }
       }
 
       throw error
diff --git a/test/storageFileApi.test.ts b/test/storageFileApi.test.ts
index 286f433..c6ee49c 100644
--- a/test/storageFileApi.test.ts
+++ b/test/storageFileApi.test.ts
@@ -577,93 +577,149 @@ describe('Object API', () => {
     )
   })
 
-    // Mock-based tests for coverage (until server endpoint is ready)
+  describe('Purge Cache - Mock Tests', () => {
+    beforeEach(() => {
+      jest.resetAllMocks()
+    })
+
+    afterEach(() => {
+      jest.restoreAllMocks()
+    })
+
     test('purge cache - mock successful response', async () => {
-      const originalFetch = global.fetch
-      global.fetch = jest.fn().mockResolvedValue({
-        ok: true,
-        json: async () => ({ message: 'success' })
-      })
+      // Mock a proper successful response
+      const mockResponse = new Response(
+        JSON.stringify({ message: 'success' }),
+        {
+          status: 200,
+          statusText: 'OK',
+          headers: { 'Content-Type': 'application/json' }
+        }
+      )
+      global.fetch = jest.fn().mockResolvedValue(mockResponse)
+
+      const mockStorage = new StorageClient(URL, { Authorization: `Bearer ${KEY}` })
+      const testBucket = 'test-bucket'
 
-      try {
-        const res = await storage.from(bucketName).purgeCache('test-file.jpg')
-        expect(res.error).toBeNull()
-        expect(res.data?.message).toEqual('success')
-        expect(global.fetch).toHaveBeenCalledWith(
-          expect.stringContaining(`/cdn/${bucketName}/test-file.jpg`),
-          expect.objectContaining({
-            method: 'DELETE'
-          })
-        )
-      } finally {
-        global.fetch = originalFetch
-      }
+      const res = await mockStorage.from(testBucket).purgeCache('test-file.jpg')
+      expect(res.error).toBeNull()
+      expect(res.data?.message).toEqual('success')
+      
+      expect(global.fetch).toHaveBeenCalledWith(
+        expect.stringContaining(`/cdn/${testBucket}/test-file.jpg`),
+        expect.objectContaining({
+          method: 'DELETE'
+        })
+      )
     })
 
     test('purge cache - mock entire bucket', async () => {
-      const originalFetch = global.fetch
-      global.fetch = jest.fn().mockResolvedValue({
-        ok: true,
-        json: async () => ({ message: 'success' })
-      })
+      const mockResponse = new Response(
+        JSON.stringify({ message: 'success' }),
+        {
+          status: 200,
+          statusText: 'OK',
+          headers: { 'Content-Type': 'application/json' }
+        }
+      )
+      global.fetch = jest.fn().mockResolvedValue(mockResponse)
 
-      try {
-        const res = await storage.from(bucketName).purgeCache()
-        expect(res.error).toBeNull()
-        expect(res.data?.message).toEqual('success')
-        expect(global.fetch).toHaveBeenCalledWith(
-          expect.stringContaining(`/cdn/${bucketName}/*`),
-          expect.objectContaining({
-            method: 'DELETE'
-          })
-        )
-      } finally {
-        global.fetch = originalFetch
-      }
+      const mockStorage = new StorageClient(URL, { Authorization: `Bearer ${KEY}` })
+      const testBucket = 'test-bucket'
+
+      const res = await mockStorage.from(testBucket).purgeCache()
+      expect(res.error).toBeNull()
+      expect(res.data?.message).toEqual('success')
+      
+      expect(global.fetch).toHaveBeenCalledWith(
+        expect.stringContaining(`/cdn/${testBucket}/*`),
+        expect.objectContaining({
+          method: 'DELETE'
+        })
+      )
     })
 
     test('purge cache - mock with path normalization', async () => {
-      const originalFetch = global.fetch
-      global.fetch = jest.fn().mockResolvedValue({
-        ok: true,
-        json: async () => ({ message: 'success' })
-      })
+      const mockResponse = new Response(
+        JSON.stringify({ message: 'success' }),
+        {
+          status: 200,
+          statusText: 'OK',
+          headers: { 'Content-Type': 'application/json' }
+        }
+      )
+      global.fetch = jest.fn().mockResolvedValue(mockResponse)
+
+      const mockStorage = new StorageClient(URL, { Authorization: `Bearer ${KEY}` })
+      const testBucket = 'test-bucket'
 
-      try {
-        const res = await storage.from(bucketName).purgeCache('/folder//file.jpg/')
-        expect(res.error).toBeNull()
-        expect(res.data?.message).toEqual('success')
-        
-        expect(global.fetch).toHaveBeenCalledWith(
-          expect.stringContaining(`/cdn/${bucketName}/folder/file.jpg`),
-          expect.objectContaining({
-            method: 'DELETE'
-          })
-        )
-      } finally {
-        global.fetch = originalFetch
-      }
+      const res = await mockStorage.from(testBucket).purgeCache('/folder//file.jpg/')
+      expect(res.error).toBeNull()
+      expect(res.data?.message).toEqual('success')
+      
+      expect(global.fetch).toHaveBeenCalledWith(
+        expect.stringContaining(`/cdn/${testBucket}/folder/file.jpg`),
+        expect.objectContaining({
+          method: 'DELETE'
+        })
+      )
     })
 
     test('purge cache - mock error response', async () => {
-      const originalFetch = global.fetch
-      global.fetch = jest.fn().mockResolvedValue({
-        ok: false,
-        status: 404,
-        json: async () => ({ error: 'Object not found' })
-      })
+      // Mock a proper 404 error response
+      const mockResponse = new Response(
+        JSON.stringify({ 
+          statusCode: '404',
+          error: 'Not Found', 
+          message: 'Object not found' 
+        }),
+        {
+          status: 404,
+          statusText: 'Not Found',
+          headers: { 'Content-Type': 'application/json' }
+        }
+      )
+      global.fetch = jest.fn().mockResolvedValue(mockResponse)
+
+      const mockStorage = new StorageClient(URL, { Authorization: `Bearer ${KEY}` })
+      const testBucket = 'test-bucket'
+
+      const res = await mockStorage.from(testBucket).purgeCache('nonexistent.jpg')
+      expect(res.data).toBeNull()
+      expect(res.error).not.toBeNull()
+      expect(res.error?.message).toContain('Object not found')
+    })
+
+    test('purge cache - mock with AbortController', async () => {
+      const mockResponse = new Response(
+        JSON.stringify({ message: 'success' }),
+        {
+          status: 200,
+          statusText: 'OK',
+          headers: { 'Content-Type': 'application/json' }
+        }
+      )
+      global.fetch = jest.fn().mockResolvedValue(mockResponse)
+
+      const mockStorage = new StorageClient(URL, { Authorization: `Bearer ${KEY}` })
+      const testBucket = 'test-bucket'
+      const abortController = new AbortController()
 
-      try {
-        const res = await storage.from(bucketName).purgeCache('nonexistent.jpg')
-        expect(res.data).toBeNull()
-        expect(res.error).not.toBeNull()
-        expect(res.error?.message).toContain('Object not found')
-      } finally {
-        global.fetch = originalFetch
-      }
+      const res = await mockStorage.from(testBucket).purgeCache('test.png', { signal: abortController.signal })
+      expect(res.error).toBeNull()
+      expect(res.data?.message).toEqual('success')
+      
+      expect(global.fetch).toHaveBeenCalledWith(
+        expect.stringContaining(`/cdn/${testBucket}/test.png`),
+        expect.objectContaining({
+          method: 'DELETE',
+          signal: abortController.signal
+        })
+      )
     })
+  })
 
-    // Integration tests (skipped until server endpoint is ready)
+  describe('Purge Cache - Integration Tests (Skipped)', () => {
     test.skip('purge cache for specific object', async () => {
       await storage.from(bucketName).upload(uploadPath, file)
       const res = await storage.from(bucketName).purgeCache(uploadPath)
@@ -688,57 +744,4 @@ describe('Object API', () => {
       expect(res.data?.message).toEqual('success')
     })
   })
-
-describe('error handling', () => {
-  let mockError: Error
-
-  beforeEach(() => {
-    mockError = new Error('Network failure')
-  })
-
-  afterEach(() => {
-    jest.restoreAllMocks()
-  })
-
-  it('throws unknown errors', async () => {
-    global.fetch = jest.fn().mockImplementation(() => Promise.reject(mockError))
-    const storage = new StorageClient('http://localhost:8000/storage/v1', {
-      apikey: 'test-token',
-    })
-
-    const { data, error } = await storage.from('test').list()
-    expect(data).toBeNull()
-    expect(error).not.toBeNull()
-    expect(error?.message).toBe('Network failure')
-  })
-
-  it('handles malformed responses', async () => {
-    const mockResponse = new Response(JSON.stringify({ message: 'Internal server error' }), {
-      status: 500,
-      statusText: 'Internal Server Error',
-    })
-
-    global.fetch = jest.fn().mockImplementation(() => Promise.resolve(mockResponse))
-    const storage = new StorageClient('http://localhost:8000/storage/v1', {
-      apikey: 'test-token',
-    })
-
-    const { data, error } = await storage.from('test').list()
-    expect(data).toBeNull()
-    expect(error).toBeInstanceOf(StorageError)
-    expect(error?.message).toBe('Internal server error')
-  })
-
-  it('handles network timeouts', async () => {
-    mockError = new Error('Network timeout')
-    global.fetch = jest.fn().mockImplementation(() => Promise.reject(mockError))
-    const storage = new StorageClient('http://localhost:8000/storage/v1', {
-      apikey: 'test-token',
-    })
-
-    const { data, error } = await storage.from('test').list()
-    expect(data).toBeNull()
-    expect(error).not.toBeNull()
-    expect(error?.message).toBe('Network timeout')
-  })
 })

From 1ff7b6f592ce97b30e9eacc8e720c6bb3a0a5235 Mon Sep 17 00:00:00 2001
From: Rodrigo Mansueli Nunes <rodrigo@mansueli.com>
Date: Tue, 1 Jul 2025 17:07:00 -0300
Subject: [PATCH 5/8] feat: remove wildcard from main purge adds convenience
 function to handle paths/list

---
 src/packages/StorageFileApi.ts           | 183 +++++++++-
 test/storageFileApi.test.ts              | 438 +++++++++++++++++++----
 test/storageFileApiErrorHandling.test.ts | 329 ++++++++++++++++-
 3 files changed, 858 insertions(+), 92 deletions(-)

diff --git a/src/packages/StorageFileApi.ts b/src/packages/StorageFileApi.ts
index 971dbac..d722247 100644
--- a/src/packages/StorageFileApi.ts
+++ b/src/packages/StorageFileApi.ts
@@ -1,4 +1,4 @@
-import { isStorageError, StorageError, StorageUnknownError } from '../lib/errors'
+import { isStorageError, StorageError, StorageApiError, StorageUnknownError } from '../lib/errors'
 import { Fetch, get, head, post, put, remove } from '../lib/fetch'
 import { recursiveToCamel, resolveFetch } from '../lib/helpers'
 import {
@@ -771,17 +771,19 @@ export default class StorageFileApi {
   }
 
   /**
-   * Purges the cache for a specific object or entire bucket from the CDN.
+   * Purges the cache for a specific object from the CDN.
+   * Note: This method only works with individual file paths.
+   * Use purgeCacheByPrefix() to purge multiple objects or entire folders.
    *
-   * @param path The file path to purge from cache. If not provided or set to '*', purges the entire bucket cache.
+   * @param path The specific file path to purge from cache. Cannot be empty or contain wildcards.
    * @param parameters Optional fetch parameters like AbortController signal.
    */
   async purgeCache(
-    path: string = '*',
+    path: string,
     parameters?: FetchParameters
   ): Promise<
     | {
-        data: { message: string }
+        data: { message: string; purgedPath: string }
         error: null
       }
     | {
@@ -790,8 +792,29 @@ export default class StorageFileApi {
       }
   > {
     try {
-      const cleanPath = path === '*' || !path ? '*' : this._removeEmptyFolders(path)
+      // Validate input
+      if (!path || path.trim() === '') {
+        return {
+          data: null,
+          error: new StorageError(
+            'Path is required for cache purging. Use purgeCacheByPrefix() to purge folders or entire buckets.'
+          ),
+        }
+      }
+
+      // Check for wildcards
+      if (path.includes('*')) {
+        return {
+          data: null,
+          error: new StorageError(
+            'Wildcard purging is not supported. Please specify an exact file path.'
+          ),
+        }
+      }
+
+      const cleanPath = this._removeEmptyFolders(path)
       const cdnPath = `${this.bucketId}/${cleanPath}`
+
       const data = await remove(
         this.fetch,
         `${this.url}/cdn/${cdnPath}`,
@@ -799,25 +822,147 @@ export default class StorageFileApi {
         { headers: this.headers },
         parameters
       )
-      return { data, error: null }
+
+      return {
+        data: {
+          message: data?.message || 'success',
+          purgedPath: cleanPath,
+        },
+        error: null,
+      }
     } catch (error) {
       if (isStorageError(error)) {
-        /**
-         * The Storage API returns `{ ok:false, status:404 }` for a purge of a
-         * non-existent object.  In that case we want to expose a stable,
-         * developer-friendly error message that the higher level tests (and
-         * potentially downstream apps) can rely on.
-         */
-        const err = error as StorageError
-        const status = (err as any).statusCode ?? (err as any).status
-
-        if (String(status) === '404') {
-          err.message = 'Object not found'
+        return { data: null, error }
+      }
+
+      throw error
+    }
+  }
+
+  /**
+   * Purges the cache for all objects in a folder or entire bucket.
+   * This method lists objects first, then purges each individually.
+   *
+   * @param prefix The folder prefix to purge (empty string for entire bucket)
+   * @param options Optional configuration for listing and purging
+   * @param parameters Optional fetch parameters
+   */
+  async purgeCacheByPrefix(
+    prefix: string = '',
+    options?: {
+      limit?: number
+      batchSize?: number
+    },
+    parameters?: FetchParameters
+  ): Promise<
+    | {
+        data: { message: string; purgedPaths: string[]; warnings?: string[] }
+        error: null
+      }
+    | {
+        data: null
+        error: StorageError
+      }
+  > {
+    try {
+      const batchSize = options?.batchSize || 100
+      const purgedPaths: string[] = []
+      const warnings: string[] = []
+
+      // List all objects with the given prefix
+      const { data: objects, error: listError } = await this.list(prefix, {
+        limit: options?.limit || 1000,
+        offset: 0,
+        sortBy: {
+          column: 'name',
+          order: 'asc',
+        },
+      })
+
+      if (listError) {
+        return { data: null, error: listError }
+      }
+
+      if (!objects || objects.length === 0) {
+        return {
+          data: {
+            message: 'No objects found to purge',
+            purgedPaths: [],
+          },
+          error: null,
+        }
+      }
+
+      // Extract file paths and filter out folders
+      const filePaths = objects
+        .filter((obj) => obj.name && !obj.name.endsWith('/')) // Only files, not folders
+        .map((obj) => (prefix ? `${prefix}/${obj.name}` : obj.name))
+
+      if (filePaths.length === 0) {
+        return {
+          data: {
+            message: 'No files found to purge (only folders detected)',
+            purgedPaths: [],
+          },
+          error: null,
+        }
+      }
+
+      // Process files in batches to avoid overwhelming the API
+      for (let i = 0; i < filePaths.length; i += batchSize) {
+        const batch = filePaths.slice(i, i + batchSize)
+
+        for (const filePath of batch) {
+          try {
+            const { error: purgeError } = await this.purgeCache(filePath, parameters)
+
+            if (purgeError) {
+              warnings.push(`Failed to purge ${filePath}: ${purgeError.message}`)
+            } else {
+              purgedPaths.push(filePath)
+            }
+          } catch (error) {
+            warnings.push(`Failed to purge ${filePath}: ${(error as Error).message}`)
+          }
+        }
+      }
+
+      // If all paths failed, return error
+      if (purgedPaths.length === 0 && warnings.length > 0) {
+        return {
+          data: null,
+          error: new StorageError(
+            `All purge operations failed: ${warnings.slice(0, 3).join(', ')}${
+              warnings.length > 3 ? '...' : ''
+            }`
+          ),
         }
+      }
+
+      const message =
+        purgedPaths.length > 0
+          ? `Successfully purged ${purgedPaths.length} object(s)${
+              warnings.length > 0 ? ` (${warnings.length} failed)` : ''
+            }`
+          : 'No objects were purged'
+
+      const result: { message: string; purgedPaths: string[]; warnings?: string[] } = {
+        message,
+        purgedPaths,
+      }
 
-        return { data: null, error: err }
+      if (warnings.length > 0) {
+        result.warnings = warnings
       }
 
+      return {
+        data: result,
+        error: null,
+      }
+    } catch (error) {
+      if (isStorageError(error)) {
+        return { data: null, error }
+      }
       throw error
     }
   }
diff --git a/test/storageFileApi.test.ts b/test/storageFileApi.test.ts
index c6ee49c..04b7c38 100644
--- a/test/storageFileApi.test.ts
+++ b/test/storageFileApi.test.ts
@@ -586,16 +586,12 @@ describe('Object API', () => {
       jest.restoreAllMocks()
     })
 
-    test('purge cache - mock successful response', async () => {
-      // Mock a proper successful response
-      const mockResponse = new Response(
-        JSON.stringify({ message: 'success' }),
-        {
-          status: 200,
-          statusText: 'OK',
-          headers: { 'Content-Type': 'application/json' }
-        }
-      )
+    test('purge cache - single file success', async () => {
+      const mockResponse = new Response(JSON.stringify({ message: 'success' }), {
+        status: 200,
+        statusText: 'OK',
+        headers: { 'Content-Type': 'application/json' },
+      })
       global.fetch = jest.fn().mockResolvedValue(mockResponse)
 
       const mockStorage = new StorageClient(URL, { Authorization: `Bearer ${KEY}` })
@@ -604,48 +600,68 @@ describe('Object API', () => {
       const res = await mockStorage.from(testBucket).purgeCache('test-file.jpg')
       expect(res.error).toBeNull()
       expect(res.data?.message).toEqual('success')
-      
+      expect(res.data?.purgedPath).toEqual('test-file.jpg')
+
       expect(global.fetch).toHaveBeenCalledWith(
         expect.stringContaining(`/cdn/${testBucket}/test-file.jpg`),
         expect.objectContaining({
-          method: 'DELETE'
+          method: 'DELETE',
         })
       )
     })
 
-    test('purge cache - mock entire bucket', async () => {
-      const mockResponse = new Response(
-        JSON.stringify({ message: 'success' }),
-        {
-          status: 200,
-          statusText: 'OK',
-          headers: { 'Content-Type': 'application/json' }
-        }
-      )
+    test('purge cache - rejects empty path', async () => {
+      const mockStorage = new StorageClient(URL, { Authorization: `Bearer ${KEY}` })
+      const testBucket = 'test-bucket'
+
+      const res = await mockStorage.from(testBucket).purgeCache('')
+      expect(res.data).toBeNull()
+      expect(res.error?.message).toContain('Path is required')
+    })
+
+    test('purge cache - rejects wildcard', async () => {
+      const mockStorage = new StorageClient(URL, { Authorization: `Bearer ${KEY}` })
+      const testBucket = 'test-bucket'
+
+      const res = await mockStorage.from(testBucket).purgeCache('folder/*')
+      expect(res.data).toBeNull()
+      expect(res.error?.message).toContain('Wildcard purging is not supported')
+    })
+
+    test('purge cache - with path normalization', async () => {
+      const mockResponse = new Response(JSON.stringify({ message: 'success' }), {
+        status: 200,
+        statusText: 'OK',
+        headers: { 'Content-Type': 'application/json' },
+      })
       global.fetch = jest.fn().mockResolvedValue(mockResponse)
 
       const mockStorage = new StorageClient(URL, { Authorization: `Bearer ${KEY}` })
       const testBucket = 'test-bucket'
 
-      const res = await mockStorage.from(testBucket).purgeCache()
+      const res = await mockStorage.from(testBucket).purgeCache('/folder//file.jpg/')
       expect(res.error).toBeNull()
-      expect(res.data?.message).toEqual('success')
-      
+      expect(res.data?.purgedPath).toEqual('folder/file.jpg')
+
       expect(global.fetch).toHaveBeenCalledWith(
-        expect.stringContaining(`/cdn/${testBucket}/*`),
+        expect.stringContaining(`/cdn/${testBucket}/folder/file.jpg`),
         expect.objectContaining({
-          method: 'DELETE'
+          method: 'DELETE',
         })
       )
     })
 
-    test('purge cache - mock with path normalization', async () => {
+    test('purge cache - handles 404 error', async () => {
       const mockResponse = new Response(
-        JSON.stringify({ message: 'success' }),
+        JSON.stringify({
+          statusCode: '404',
+          error: 'Not Found',
+          message: 'Object not found',
+        }),
         {
-          status: 200,
-          statusText: 'OK',
-          headers: { 'Content-Type': 'application/json' }
+          status: 404,
+          statusText: 'Not Found',
+          headers: { 'Content-Type': 'application/json' },
         }
       )
       global.fetch = jest.fn().mockResolvedValue(mockResponse)
@@ -653,69 +669,349 @@ describe('Object API', () => {
       const mockStorage = new StorageClient(URL, { Authorization: `Bearer ${KEY}` })
       const testBucket = 'test-bucket'
 
-      const res = await mockStorage.from(testBucket).purgeCache('/folder//file.jpg/')
+      const res = await mockStorage.from(testBucket).purgeCache('nonexistent.jpg')
+      expect(res.data).toBeNull()
+      expect(res.error).not.toBeNull()
+      expect(res.error?.message).toContain('Object not found')
+    })
+
+    test('purge cache - with AbortController', async () => {
+      const mockResponse = new Response(JSON.stringify({ message: 'success' }), {
+        status: 200,
+        statusText: 'OK',
+        headers: { 'Content-Type': 'application/json' },
+      })
+      global.fetch = jest.fn().mockResolvedValue(mockResponse)
+
+      const mockStorage = new StorageClient(URL, { Authorization: `Bearer ${KEY}` })
+      const testBucket = 'test-bucket'
+      const abortController = new AbortController()
+
+      const res = await mockStorage
+        .from(testBucket)
+        .purgeCache('test.png', { signal: abortController.signal })
       expect(res.error).toBeNull()
       expect(res.data?.message).toEqual('success')
-      
+
       expect(global.fetch).toHaveBeenCalledWith(
-        expect.stringContaining(`/cdn/${testBucket}/folder/file.jpg`),
+        expect.stringContaining(`/cdn/${testBucket}/test.png`),
         expect.objectContaining({
-          method: 'DELETE'
+          method: 'DELETE',
+          signal: abortController.signal,
         })
       )
     })
+  })
 
-    test('purge cache - mock error response', async () => {
-      // Mock a proper 404 error response
-      const mockResponse = new Response(
-        JSON.stringify({ 
+  describe('Purge Cache By Prefix - Mock Tests', () => {
+    beforeEach(() => {
+      jest.resetAllMocks()
+    })
+
+    afterEach(() => {
+      jest.restoreAllMocks()
+    })
+
+    test('purge cache by prefix - successful folder purge', async () => {
+      // Mock list response
+      const listResponse = new Response(
+        JSON.stringify([
+          { name: 'file1.jpg', id: '1' },
+          { name: 'file2.png', id: '2' },
+        ]),
+        {
+          status: 200,
+          statusText: 'OK',
+          headers: { 'Content-Type': 'application/json' },
+        }
+      )
+
+      // Mock purge responses for each file
+      const purgeResponse = new Response(JSON.stringify({ message: 'success' }), {
+        status: 200,
+        statusText: 'OK',
+        headers: { 'Content-Type': 'application/json' },
+      })
+
+      let fetchCallCount = 0
+      global.fetch = jest.fn().mockImplementation(() => {
+        fetchCallCount++
+        // First call returns list response
+        if (fetchCallCount === 1) return Promise.resolve(listResponse)
+        // Subsequent calls return purge responses
+        return Promise.resolve(purgeResponse.clone())
+      })
+
+      const mockStorage = new StorageClient(URL, { apikey: KEY })
+      const testBucket = 'test-bucket'
+
+      const res = await mockStorage.from(testBucket).purgeCacheByPrefix('folder')
+      expect(res.error).toBeNull()
+      expect(res.data?.purgedPaths).toHaveLength(2)
+      expect(res.data?.purgedPaths).toEqual(['folder/file1.jpg', 'folder/file2.png'])
+      expect(res.data?.message).toContain('Successfully purged 2 object(s)')
+    })
+
+    test('purge cache by prefix - empty folder', async () => {
+      const listResponse = new Response(JSON.stringify([]), {
+        status: 200,
+        statusText: 'OK',
+        headers: { 'Content-Type': 'application/json' },
+      })
+
+      global.fetch = jest.fn().mockResolvedValue(listResponse)
+
+      const mockStorage = new StorageClient(URL, { Authorization: `Bearer ${KEY}` })
+      const testBucket = 'test-bucket'
+
+      const res = await mockStorage.from(testBucket).purgeCacheByPrefix('empty-folder')
+      expect(res.error).toBeNull()
+      expect(res.data?.purgedPaths).toHaveLength(0)
+      expect(res.data?.message).toEqual('No objects found to purge')
+    })
+
+    test('purge cache by prefix - handles partial failures', async () => {
+      let fetchCallCount = 0
+      global.fetch = jest.fn().mockImplementation(() => {
+        fetchCallCount++
+        if (fetchCallCount === 1) {
+          // List response
+          return Promise.resolve(
+            new Response(
+              JSON.stringify([
+                { name: 'file1.jpg', id: '1' },
+                { name: 'file2.png', id: '2' },
+                { name: 'file3.gif', id: '3' },
+              ]),
+              {
+                status: 200,
+                headers: { 'Content-Type': 'application/json' },
+              }
+            )
+          )
+        }
+        // Handle individual purge calls
+        const fileIndex = fetchCallCount - 2
+        if (fileIndex === 1) {
+          // Second file fails
+          return Promise.resolve(
+            new Response(
+              JSON.stringify({
+                statusCode: '404',
+                error: 'Not Found',
+                message: 'Object not found',
+              }),
+              { status: 404 }
+            )
+          )
+        }
+        return Promise.resolve(
+          new Response(JSON.stringify({ message: 'success' }), { status: 200 })
+        )
+      })
+
+      const mockStorage = new StorageClient(URL, { apikey: KEY })
+      const res = await mockStorage.from(bucketName).purgeCacheByPrefix('folder')
+
+      expect(res.error).toBeNull()
+      expect(res.data?.purgedPaths).toHaveLength(2)
+      expect(res.data?.purgedPaths).toEqual(['folder/file1.jpg', 'folder/file3.gif'])
+      expect(res.data?.warnings).toHaveLength(1)
+      expect(res.data?.warnings?.[0]).toContain('Failed to purge folder/file2.png')
+      expect(res.data?.message).toContain('Successfully purged 2 object(s) (1 failed)')
+    })
+
+    test('purge cache by prefix - all failures', async () => {
+      // Mock list response
+      const listResponse = new Response(
+        JSON.stringify([
+          { name: 'file1.jpg', id: '1' },
+          { name: 'file2.png', id: '2' },
+        ]),
+        {
+          status: 200,
+          statusText: 'OK',
+          headers: { 'Content-Type': 'application/json' },
+        }
+      )
+
+      const errorResponse = new Response(
+        JSON.stringify({
           statusCode: '404',
-          error: 'Not Found', 
-          message: 'Object not found' 
+          error: 'Not Found',
+          message: 'Object not found',
         }),
         {
           status: 404,
           statusText: 'Not Found',
-          headers: { 'Content-Type': 'application/json' }
+          headers: { 'Content-Type': 'application/json' },
         }
       )
-      global.fetch = jest.fn().mockResolvedValue(mockResponse)
+
+      global.fetch = jest
+        .fn()
+        .mockResolvedValueOnce(listResponse) // List call
+        .mockResolvedValue(errorResponse) // All purge calls fail
 
       const mockStorage = new StorageClient(URL, { Authorization: `Bearer ${KEY}` })
       const testBucket = 'test-bucket'
 
-      const res = await mockStorage.from(testBucket).purgeCache('nonexistent.jpg')
+      const res = await mockStorage.from(testBucket).purgeCacheByPrefix('folder')
       expect(res.data).toBeNull()
       expect(res.error).not.toBeNull()
-      expect(res.error?.message).toContain('Object not found')
+      expect(res.error?.message).toContain('All purge operations failed')
     })
 
-    test('purge cache - mock with AbortController', async () => {
-      const mockResponse = new Response(
-        JSON.stringify({ message: 'success' }),
+    test('purge cache by prefix - filters out folders', async () => {
+      let fetchCallCount = 0
+      global.fetch = jest.fn().mockImplementation(() => {
+        fetchCallCount++
+        if (fetchCallCount === 1) {
+          return Promise.resolve(
+            new Response(
+              JSON.stringify([
+                { name: 'file1.jpg', id: '1' },
+                { name: 'subfolder/', id: '2' },
+                { name: 'file2.png', id: '3' },
+              ]),
+              { status: 200 }
+            )
+          )
+        }
+        return Promise.resolve(
+          new Response(JSON.stringify({ message: 'success' }), { status: 200 })
+        )
+      })
+
+      const mockStorage = new StorageClient(URL, { apikey: KEY })
+      const res = await mockStorage.from(bucketName).purgeCacheByPrefix('folder')
+
+      expect(res.error).toBeNull()
+      expect(res.data?.purgedPaths).toHaveLength(2)
+      expect(res.data?.purgedPaths).toEqual(['folder/file1.jpg', 'folder/file2.png'])
+      expect(res.data?.message).toContain('Successfully purged 2 object(s)')
+    })
+
+    test('purge cache by prefix - only folders found', async () => {
+      // Mock list response with only folders
+      const listResponse = new Response(
+        JSON.stringify([
+          { name: 'subfolder1/', id: '1' },
+          { name: 'subfolder2/', id: '2' },
+        ]),
         {
           status: 200,
           statusText: 'OK',
-          headers: { 'Content-Type': 'application/json' }
+          headers: { 'Content-Type': 'application/json' },
         }
       )
-      global.fetch = jest.fn().mockResolvedValue(mockResponse)
+
+      global.fetch = jest.fn().mockResolvedValue(listResponse)
 
       const mockStorage = new StorageClient(URL, { Authorization: `Bearer ${KEY}` })
       const testBucket = 'test-bucket'
-      const abortController = new AbortController()
 
-      const res = await mockStorage.from(testBucket).purgeCache('test.png', { signal: abortController.signal })
+      const res = await mockStorage.from(testBucket).purgeCacheByPrefix('folder')
       expect(res.error).toBeNull()
-      expect(res.data?.message).toEqual('success')
-      
-      expect(global.fetch).toHaveBeenCalledWith(
-        expect.stringContaining(`/cdn/${testBucket}/test.png`),
-        expect.objectContaining({
-          method: 'DELETE',
-          signal: abortController.signal
-        })
+      expect(res.data?.purgedPaths).toHaveLength(0)
+      expect(res.data?.message).toEqual('No files found to purge (only folders detected)')
+    })
+
+    test('purge cache by prefix - with batch size limit', async () => {
+      const fileCount = 150
+      const files = Array.from({ length: fileCount }, (_, i) => ({
+        name: `file${i}.jpg`,
+        id: String(i),
+      }))
+
+      let fetchCallCount = 0
+      global.fetch = jest.fn().mockImplementation(() => {
+        fetchCallCount++
+        if (fetchCallCount === 1) {
+          return Promise.resolve(new Response(JSON.stringify(files), { status: 200 }))
+        }
+        return Promise.resolve(
+          new Response(JSON.stringify({ message: 'success' }), { status: 200 })
+        )
+      })
+
+      const mockStorage = new StorageClient(URL, { Authorization: `Bearer ${KEY}` })
+      const res = await mockStorage.from(bucketName).purgeCacheByPrefix('folder', { batchSize: 50 })
+
+      expect(res.error).toBeNull()
+      expect(res.data?.purgedPaths).toHaveLength(150)
+      expect(res.data?.message).toContain('Successfully purged 150 object(s)')
+    })
+
+    test('purge cache by prefix - list error', async () => {
+      const listErrorResponse = new Response(
+        JSON.stringify({
+          statusCode: '403',
+          error: 'Forbidden',
+          message: 'Access denied',
+        }),
+        {
+          status: 403,
+          statusText: 'Forbidden',
+          headers: { 'Content-Type': 'application/json' },
+        }
       )
+
+      global.fetch = jest.fn().mockResolvedValue(listErrorResponse)
+
+      const mockStorage = new StorageClient(URL, { Authorization: `Bearer ${KEY}` })
+      const testBucket = 'test-bucket'
+
+      const res = await mockStorage.from(testBucket).purgeCacheByPrefix('folder')
+      expect(res.data).toBeNull()
+      expect(res.error).not.toBeNull()
+      expect(res.error?.message).toContain('Access denied')
+    })
+
+    test('purge cache by prefix - with custom options', async () => {
+      const listResponse = new Response(
+        JSON.stringify([
+          { name: 'file1.jpg', id: '1' },
+          { name: 'file2.png', id: '2' },
+        ]),
+        {
+          status: 200,
+          statusText: 'OK',
+          headers: { 'Content-Type': 'application/json' },
+        }
+      )
+
+      const purgeResponse = new Response(JSON.stringify({ message: 'success' }), {
+        status: 200,
+        statusText: 'OK',
+        headers: { 'Content-Type': 'application/json' },
+      })
+
+      // Track and respond to each fetch call
+      let fetchCalls = 0
+      global.fetch = jest.fn().mockImplementation(() => {
+        fetchCalls++
+        if (fetchCalls === 1) {
+          return Promise.resolve(listResponse)
+        }
+        return Promise.resolve(purgeResponse.clone()) // Clone for multiple uses
+      })
+
+      const mockStorage = new StorageClient(URL, { apikey: KEY })
+      const testBucket = 'test-bucket'
+      const abortController = new AbortController()
+
+      const res = await mockStorage
+        .from(testBucket)
+        .purgeCacheByPrefix(
+          'folder',
+          { limit: 500, batchSize: 25 },
+          { signal: abortController.signal }
+        )
+
+      expect(res.error).toBeNull()
+      expect(res.data?.purgedPaths).toHaveLength(2)
+      expect(res.data?.message).toContain('Successfully purged 2 object(s)')
     })
   })
 
@@ -726,22 +1022,30 @@ describe('Object API', () => {
 
       expect(res.error).toBeNull()
       expect(res.data?.message).toEqual('success')
+      expect(res.data?.purgedPath).toEqual(uploadPath)
     })
 
-    test.skip('purge cache for entire bucket', async () => {
-      await storage.from(bucketName).upload(uploadPath, file)
-      const res = await storage.from(bucketName).purgeCache()
+    test.skip('purge cache by prefix for folder', async () => {
+      const file1Path = `testfolder/file1-${Date.now()}.jpg`
+      const file2Path = `testfolder/file2-${Date.now()}.jpg`
+
+      await storage.from(bucketName).upload(file1Path, file)
+      await storage.from(bucketName).upload(file2Path, file)
+
+      const res = await storage.from(bucketName).purgeCacheByPrefix('testfolder')
 
       expect(res.error).toBeNull()
-      expect(res.data?.message).toEqual('success')
+      expect(res.data?.purgedPaths).toHaveLength(2)
+      expect(res.data?.message).toContain('Successfully purged 2 object(s)')
     })
 
-    test.skip('purge cache with wildcard', async () => {
+    test.skip('purge cache by prefix for entire bucket', async () => {
       await storage.from(bucketName).upload(uploadPath, file)
-      const res = await storage.from(bucketName).purgeCache('*')
+      const res = await storage.from(bucketName).purgeCacheByPrefix('')
 
       expect(res.error).toBeNull()
-      expect(res.data?.message).toEqual('success')
+      expect(res.data?.purgedPaths.length).toBeGreaterThan(0)
+      expect(res.data?.message).toContain('Successfully purged')
     })
   })
 })
diff --git a/test/storageFileApiErrorHandling.test.ts b/test/storageFileApiErrorHandling.test.ts
index ecbeddd..7842cfa 100644
--- a/test/storageFileApiErrorHandling.test.ts
+++ b/test/storageFileApiErrorHandling.test.ts
@@ -1,6 +1,5 @@
 import { StorageClient } from '../src/index'
 import { StorageError, StorageUnknownError } from '../src/lib/errors'
-
 // Mock URL and credentials for testing
 const URL = 'http://localhost:8000/storage/v1'
 const KEY = 'test-api-key'
@@ -316,15 +315,34 @@ describe('File API Error Handling', () => {
   })
 
   describe('purgeCache', () => {
-    it('handles network errors', async () => {
-      const mockError = new Error('Network failure')
-      global.fetch = jest.fn().mockImplementation(() => Promise.reject(mockError))
+    it('wraps non-Response errors as StorageUnknownError', async () => {
+      const nonResponseError = new TypeError('Invalid copy operation')
+      global.fetch = jest.fn().mockImplementation(() => Promise.reject(nonResponseError))
       const storage = new StorageClient(URL, { apikey: KEY })
-
       const { data, error } = await storage.from(BUCKET_ID).purgeCache('test.png')
       expect(data).toBeNull()
       expect(error).not.toBeNull()
-      expect(error?.message).toBe('Network failure')
+      expect(error?.message).toBe('Invalid copy operation')
+    })
+
+    it('rejects empty paths', async () => {
+      const storage = new StorageClient(URL, { apikey: KEY })
+      const { data, error } = await storage.from(BUCKET_ID).purgeCache('')
+      expect(data).toBeNull()
+      expect(error).not.toBeNull()
+      expect(error?.message).toBe(
+        'Path is required for cache purging. Use purgeCacheByPrefix() to purge folders or entire buckets.'
+      )
+    })
+
+    it('rejects wildcard paths', async () => {
+      const storage = new StorageClient(URL, { apikey: KEY })
+      const { data, error } = await storage.from(BUCKET_ID).purgeCache('folder/*')
+      expect(data).toBeNull()
+      expect(error).not.toBeNull()
+      expect(error?.message).toBe(
+        'Wildcard purging is not supported. Please specify an exact file path.'
+      )
     })
 
     it('wraps non-Response errors as StorageUnknownError', async () => {
@@ -355,4 +373,303 @@ describe('File API Error Handling', () => {
       mockFn.mockRestore()
     })
   })
+
+  describe('purgeCacheByPrefix', () => {
+    beforeEach(() => {
+      // Mock Response constructor globally
+      global.Response = (jest.fn().mockImplementation((body, init) => ({
+        json: () => Promise.resolve(JSON.parse(body)),
+        status: init?.status || 200,
+        headers: new Map(Object.entries(init?.headers || {})),
+        ok: init?.status ? init.status >= 200 && init.status < 300 : true,
+      })) as unknown) as typeof Response
+    })
+
+    it('handles StorageError during list operation', async () => {
+      const mockResponse = {
+        ok: false,
+        status: 403,
+        json: () =>
+          Promise.resolve({
+            statusCode: '403',
+            error: 'Forbidden',
+            message: 'Access denied to list objects',
+          }),
+        headers: new Map([['Content-Type', 'application/json']]),
+      }
+      global.fetch = jest.fn().mockImplementation(() => Promise.resolve(mockResponse))
+      const storage = new StorageClient(URL, { apikey: KEY })
+      const { data, error } = await storage.from(BUCKET_ID).purgeCacheByPrefix('folder')
+      expect(data).toBeNull()
+      expect(error).not.toBeNull()
+      expect(error?.message).toContain(':403')
+    })
+
+    it('handles mixed success and failure during purge operations', async () => {
+      // Mock successful list response
+      const listResponse = new Response(
+        JSON.stringify([
+          { name: 'file1.jpg', id: '1' },
+          { name: 'file2.png', id: '2' },
+          { name: 'file3.gif', id: '3' },
+        ]),
+        {
+          status: 200,
+          statusText: 'OK',
+          headers: { 'Content-Type': 'application/json' },
+        }
+      )
+
+      // Mock purge responses - some succeed, some fail
+      const successResponse = new Response(JSON.stringify({ message: 'success' }), {
+        status: 200,
+        statusText: 'OK',
+        headers: { 'Content-Type': 'application/json' },
+      })
+
+      const errorResponse = new Response(
+        JSON.stringify({
+          statusCode: '404',
+          error: 'Not Found',
+          message: 'Object not found',
+        }),
+        {
+          status: 404,
+          statusText: 'Not Found',
+          headers: { 'Content-Type': 'application/json' },
+        }
+      )
+
+      global.fetch = jest
+        .fn()
+        .mockResolvedValueOnce(listResponse) // List succeeds
+        .mockResolvedValueOnce(successResponse) // First purge succeeds
+        .mockResolvedValueOnce(errorResponse) // Second purge fails
+        .mockResolvedValueOnce(successResponse) // Third purge succeeds
+
+      const storage = new StorageClient(URL, { apikey: KEY })
+
+      const { data, error } = await storage.from(BUCKET_ID).purgeCacheByPrefix('folder')
+      expect(error).toBeNull()
+      expect(data?.purgedPaths).toHaveLength(2)
+      expect(data?.warnings).toHaveLength(1)
+      expect(data?.warnings?.[0]).toContain('Failed to purge folder/file2.png')
+      expect(data?.message).toContain('Successfully purged 2 object(s) (1 failed)')
+    })
+
+    it('handles all purge operations failing', async () => {
+      // Mock successful list response
+      const listResponse = new Response(
+        JSON.stringify([
+          { name: 'file1.jpg', id: '1' },
+          { name: 'file2.png', id: '2' },
+        ]),
+        {
+          status: 200,
+          statusText: 'OK',
+          headers: { 'Content-Type': 'application/json' },
+        }
+      )
+
+      const errorResponse = new Response(
+        JSON.stringify({
+          statusCode: '404',
+          error: 'Not Found',
+          message: 'Object not found',
+        }),
+        {
+          status: 404,
+          statusText: 'Not Found',
+          headers: { 'Content-Type': 'application/json' },
+        }
+      )
+
+      global.fetch = jest
+        .fn()
+        .mockResolvedValueOnce(listResponse) // List succeeds
+        .mockResolvedValue(errorResponse) // All purge operations fail
+
+      const storage = new StorageClient(URL, { apikey: KEY })
+
+      const { data, error } = await storage.from(BUCKET_ID).purgeCacheByPrefix('folder')
+      expect(data).toBeNull()
+      expect(error).not.toBeNull()
+      expect(error?.message).toContain('All purge operations failed')
+    })
+
+    it('handles non-StorageError exceptions during individual purge operations', async () => {
+      // Mock successful list response
+      const listResponse = new Response(
+        JSON.stringify([
+          { name: 'file1.jpg', id: '1' },
+          { name: 'file2.png', id: '2' },
+        ]),
+        {
+          status: 200,
+          statusText: 'OK',
+          headers: { 'Content-Type': 'application/json' },
+        }
+      )
+
+      const successResponse = new Response(JSON.stringify({ message: 'success' }), {
+        status: 200,
+        statusText: 'OK',
+        headers: { 'Content-Type': 'application/json' },
+      })
+
+      global.fetch = jest
+        .fn()
+        .mockResolvedValueOnce(listResponse) // List succeeds
+        .mockResolvedValueOnce(successResponse) // First purge succeeds
+        .mockImplementationOnce(() => {
+          const error = new Error('Unexpected network error')
+          Object.defineProperty(error, 'name', { value: 'CustomError' })
+          throw error
+        }) // Second purge throws non-StorageError
+
+      const storage = new StorageClient(URL, { apikey: KEY })
+
+      const { data, error } = await storage.from(BUCKET_ID).purgeCacheByPrefix('folder')
+      expect(error).toBeNull()
+      expect(data?.purgedPaths).toHaveLength(1)
+      expect(data?.warnings).toHaveLength(1)
+      expect(data?.warnings?.[0]).toContain(
+        'Failed to purge folder/file2.png: Unexpected network error'
+      )
+      expect(data?.message).toContain('Successfully purged 1 object(s) (1 failed)')
+    })
+
+    it('throws non-StorageError exceptions at top level', async () => {
+      const storage = new StorageClient(URL, { apikey: KEY })
+
+      const mockFn = jest.spyOn(global, 'fetch').mockImplementationOnce(() => {
+        const error = new Error('Unexpected error in purgeCacheByPrefix')
+        Object.defineProperty(error, 'name', { value: 'CustomError' })
+        throw error
+      })
+
+      await expect(storage.from(BUCKET_ID).purgeCacheByPrefix('folder')).rejects.toThrow(
+        'Unexpected error in purgeCacheByPrefix'
+      )
+
+      mockFn.mockRestore()
+    })
+
+    it('handles empty list response', async () => {
+      const listResponse = new Response(JSON.stringify([]), {
+        status: 200,
+        statusText: 'OK',
+        headers: { 'Content-Type': 'application/json' },
+      })
+
+      global.fetch = jest.fn().mockResolvedValue(listResponse)
+      const storage = new StorageClient(URL, { apikey: KEY })
+
+      const { data, error } = await storage.from(BUCKET_ID).purgeCacheByPrefix('empty-folder')
+      expect(error).toBeNull()
+      expect(data?.purgedPaths).toHaveLength(0)
+      expect(data?.message).toEqual('No objects found to purge')
+    })
+
+    it('handles list response with only folders', async () => {
+      const listResponse = new Response(
+        JSON.stringify([
+          { name: 'subfolder1/', id: '1' },
+          { name: 'subfolder2/', id: '2' },
+        ]),
+        {
+          status: 200,
+          statusText: 'OK',
+          headers: { 'Content-Type': 'application/json' },
+        }
+      )
+
+      global.fetch = jest.fn().mockResolvedValue(listResponse)
+      const storage = new StorageClient(URL, { apikey: KEY })
+
+      const { data, error } = await storage.from(BUCKET_ID).purgeCacheByPrefix('folder')
+      expect(error).toBeNull()
+      expect(data?.purgedPaths).toHaveLength(0)
+      expect(data?.message).toEqual('No files found to purge (only folders detected)')
+    })
+
+    it('wraps non-Response errors from list as StorageUnknownError', async () => {
+      const nonResponseError = new TypeError('Invalid list operation during purge')
+      global.fetch = jest.fn().mockImplementation(() => Promise.reject(nonResponseError))
+
+      const storage = new StorageClient(URL, { apikey: KEY })
+
+      const { data, error } = await storage.from(BUCKET_ID).purgeCacheByPrefix('folder')
+      expect(data).toBeNull()
+      expect(error).toBeInstanceOf(StorageUnknownError)
+      expect(error?.message).toBe('Invalid list operation during purge')
+    })
+
+    it('handles partial success with many warnings', async () => {
+      // Create many files to test warning truncation
+      const files = Array.from({ length: 10 }, (_, i) => ({ name: `file${i}.jpg`, id: String(i) }))
+      const listResponse = new Response(JSON.stringify(files), {
+        status: 200,
+        statusText: 'OK',
+        headers: { 'Content-Type': 'application/json' },
+      })
+
+      const errorResponse = new Response(
+        JSON.stringify({
+          statusCode: '404',
+          error: 'Not Found',
+          message: 'Object not found',
+        }),
+        {
+          status: 404,
+          statusText: 'Not Found',
+          headers: { 'Content-Type': 'application/json' },
+        }
+      )
+
+      global.fetch = jest
+        .fn()
+        .mockResolvedValueOnce(listResponse) // List succeeds
+        .mockResolvedValue(errorResponse) // All purge operations fail
+
+      const storage = new StorageClient(URL, { apikey: KEY })
+
+      const { data, error } = await storage.from(BUCKET_ID).purgeCacheByPrefix('folder')
+      expect(data).toBeNull()
+      expect(error).not.toBeNull()
+      expect(error?.message).toContain('All purge operations failed')
+      // Should truncate the error message to avoid extremely long messages
+      expect(error?.message.length).toBeLessThan(1000)
+    })
+
+    it('handles AbortController signal properly', async () => {
+      const listResponse = {
+        ok: true,
+        status: 200,
+        json: () => Promise.resolve([{ name: 'file1.jpg', id: '1' }]),
+      }
+
+      const purgeResponse = {
+        ok: true,
+        status: 200,
+        json: () => Promise.resolve({ message: 'success' }),
+      }
+
+      global.fetch = jest
+        .fn()
+        .mockResolvedValueOnce(listResponse)
+        .mockResolvedValueOnce(purgeResponse)
+
+      const storage = new StorageClient(URL, { apikey: KEY })
+      const abortController = new AbortController()
+
+      const { data, error } = await storage
+        .from(BUCKET_ID)
+        .purgeCacheByPrefix('folder', undefined, { signal: abortController.signal })
+      expect(error).toBeNull()
+      expect(data?.purgedPaths).toHaveLength(1)
+      expect(data?.purgedPaths).toEqual(['folder/file1.jpg'])
+      expect(data?.message).toContain('Successfully purged 1 object(s)')
+    })
+  })
 })

From 125ff2c480c87698423cf5bb22c853d8ac7e32dc Mon Sep 17 00:00:00 2001
From: Rodrigo Mansueli Nunes <rodrigo@mansueli.com>
Date: Fri, 29 Aug 2025 11:32:29 -0300
Subject: [PATCH 6/8] update based on the feedback

---
 src/packages/StorageFileApi.ts           | 18 +++++++++--
 test/storageFileApi.test.ts              | 38 ++++++++++++++++++++++--
 test/storageFileApiErrorHandling.test.ts |  6 ++--
 3 files changed, 55 insertions(+), 7 deletions(-)

diff --git a/src/packages/StorageFileApi.ts b/src/packages/StorageFileApi.ts
index d722247..019ed42 100644
--- a/src/packages/StorageFileApi.ts
+++ b/src/packages/StorageFileApi.ts
@@ -843,8 +843,15 @@ export default class StorageFileApi {
    * Purges the cache for all objects in a folder or entire bucket.
    * This method lists objects first, then purges each individually.
    *
+   * Note: This operation can take a very long time for large numbers of objects.
+   * Each object purge takes between 300ms and 600ms, so purging 200+ objects
+   * could take several minutes.
+   *
    * @param prefix The folder prefix to purge (empty string for entire bucket)
    * @param options Optional configuration for listing and purging
+   * @param options.limit Maximum number of objects to list (default: 1000)
+   * @param options.batchSize Number of objects to process in each batch (default: 100)
+   * @param options.batchDelayMs Delay in milliseconds between batches (default: 0)
    * @param parameters Optional fetch parameters
    */
   async purgeCacheByPrefix(
@@ -852,6 +859,7 @@ export default class StorageFileApi {
     options?: {
       limit?: number
       batchSize?: number
+      batchDelayMs?: number
     },
     parameters?: FetchParameters
   ): Promise<
@@ -866,6 +874,7 @@ export default class StorageFileApi {
   > {
     try {
       const batchSize = options?.batchSize || 100
+      const batchDelayMs = options?.batchDelayMs || 0
       const purgedPaths: string[] = []
       const warnings: string[] = []
 
@@ -893,9 +902,9 @@ export default class StorageFileApi {
         }
       }
 
-      // Extract file paths and filter out folders
+      // Extract file paths and filter out folders (folders have id === null)
       const filePaths = objects
-        .filter((obj) => obj.name && !obj.name.endsWith('/')) // Only files, not folders
+        .filter((obj) => obj.id !== null) // Only files, not folders
         .map((obj) => (prefix ? `${prefix}/${obj.name}` : obj.name))
 
       if (filePaths.length === 0) {
@@ -925,6 +934,11 @@ export default class StorageFileApi {
             warnings.push(`Failed to purge ${filePath}: ${(error as Error).message}`)
           }
         }
+
+        // Add delay between batches if specified and not the last batch
+        if (batchDelayMs > 0 && i + batchSize < filePaths.length) {
+          await new Promise((resolve) => setTimeout(resolve, batchDelayMs))
+        }
       }
 
       // If all paths failed, return error
diff --git a/test/storageFileApi.test.ts b/test/storageFileApi.test.ts
index 04b7c38..f5ab782 100644
--- a/test/storageFileApi.test.ts
+++ b/test/storageFileApi.test.ts
@@ -896,8 +896,8 @@ describe('Object API', () => {
       // Mock list response with only folders
       const listResponse = new Response(
         JSON.stringify([
-          { name: 'subfolder1/', id: '1' },
-          { name: 'subfolder2/', id: '2' },
+          { name: 'subfolder1/', id: null },
+          { name: 'subfolder2/', id: null },
         ]),
         {
           status: 200,
@@ -943,6 +943,40 @@ describe('Object API', () => {
       expect(res.data?.message).toContain('Successfully purged 150 object(s)')
     })
 
+    test('purge cache by prefix - with batch delay', async () => {
+      const fileCount = 6
+      const files = Array.from({ length: fileCount }, (_, i) => ({
+        name: `file${i}.jpg`,
+        id: String(i),
+      }))
+
+      let fetchCallCount = 0
+      const startTime = Date.now()
+      global.fetch = jest.fn().mockImplementation(() => {
+        fetchCallCount++
+        if (fetchCallCount === 1) {
+          return Promise.resolve(new Response(JSON.stringify(files), { status: 200 }))
+        }
+        return Promise.resolve(
+          new Response(JSON.stringify({ message: 'success' }), { status: 200 })
+        )
+      })
+
+      const mockStorage = new StorageClient(URL, { Authorization: `Bearer ${KEY}` })
+      const res = await mockStorage
+        .from(bucketName)
+        .purgeCacheByPrefix('folder', { batchSize: 2, batchDelayMs: 50 })
+
+      const endTime = Date.now()
+      const executionTime = endTime - startTime
+
+      expect(res.error).toBeNull()
+      expect(res.data?.purgedPaths).toHaveLength(6)
+      expect(res.data?.message).toContain('Successfully purged 6 object(s)')
+      // Should have delays between batches (3 batches = 2 delays = ~100ms minimum)
+      expect(executionTime).toBeGreaterThanOrEqual(100)
+    })
+
     test('purge cache by prefix - list error', async () => {
       const listErrorResponse = new Response(
         JSON.stringify({
diff --git a/test/storageFileApiErrorHandling.test.ts b/test/storageFileApiErrorHandling.test.ts
index 7842cfa..702f2bc 100644
--- a/test/storageFileApiErrorHandling.test.ts
+++ b/test/storageFileApiErrorHandling.test.ts
@@ -574,8 +574,8 @@ describe('File API Error Handling', () => {
     it('handles list response with only folders', async () => {
       const listResponse = new Response(
         JSON.stringify([
-          { name: 'subfolder1/', id: '1' },
-          { name: 'subfolder2/', id: '2' },
+          { name: 'subfolder1/', id: null },
+          { name: 'subfolder2/', id: null },
         ]),
         {
           status: 200,
@@ -665,7 +665,7 @@ describe('File API Error Handling', () => {
 
       const { data, error } = await storage
         .from(BUCKET_ID)
-        .purgeCacheByPrefix('folder', undefined, { signal: abortController.signal })
+        .purgeCacheByPrefix('folder', { batchDelayMs: 10 }, { signal: abortController.signal })
       expect(error).toBeNull()
       expect(data?.purgedPaths).toHaveLength(1)
       expect(data?.purgedPaths).toEqual(['folder/file1.jpg'])

From ee4cf5b22c71f6d5dd980073bbdf59b57b536669 Mon Sep 17 00:00:00 2001
From: Rodrigo Mansueli Nunes <rodrigo@mansueli.com>
Date: Fri, 29 Aug 2025 11:37:29 -0300
Subject: [PATCH 7/8] fix conflicts

---
 src/packages/StorageFileApi.ts | 39 +++++++++++++++++++++++++++++++++-
 1 file changed, 38 insertions(+), 1 deletion(-)

diff --git a/src/packages/StorageFileApi.ts b/src/packages/StorageFileApi.ts
index 019ed42..7de4a89 100644
--- a/src/packages/StorageFileApi.ts
+++ b/src/packages/StorageFileApi.ts
@@ -770,6 +770,43 @@ export default class StorageFileApi {
     }
   }
 
+  /**
+   * @experimental this method signature might change in the future
+   * @param options search options
+   * @param parameters
+   */
+  async listV2(
+    options?: any,
+    parameters?: FetchParameters
+  ): Promise<
+    | {
+        data: any
+        error: null
+      }
+    | {
+        data: null
+        error: StorageError
+      }
+  > {
+    try {
+      const body = { ...options }
+      const data = await post(
+        this.fetch,
+        `${this.url}/object/list-v2/${this.bucketId}`,
+        body,
+        { headers: this.headers },
+        parameters
+      )
+      return { data, error: null }
+    } catch (error) {
+      if (isStorageError(error)) {
+        return { data: null, error }
+      }
+
+      throw error
+    }
+  }
+
   /**
    * Purges the cache for a specific object from the CDN.
    * Note: This method only works with individual file paths.
@@ -993,7 +1030,7 @@ export default class StorageFileApi {
   }
 
   private _getFinalPath(path: string) {
-    return `${this.bucketId}/${path}`
+    return `${this.bucketId}/${path.replace(/^\/+/, '')}`
   }
 
   private _removeEmptyFolders(path: string) {

From 9fb32a2b53c916a4e3a73d94a349d36ae62ade95 Mon Sep 17 00:00:00 2001
From: Rodrigo Mansueli Nunes <rodrigo@mansueli.com>
Date: Fri, 29 Aug 2025 12:38:33 -0300
Subject: [PATCH 8/8] Update storageFileApi.test.ts

---
 test/storageFileApi.test.ts | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/test/storageFileApi.test.ts b/test/storageFileApi.test.ts
index f021286..e1eefbe 100644
--- a/test/storageFileApi.test.ts
+++ b/test/storageFileApi.test.ts
@@ -826,7 +826,7 @@ describe('Object API', () => {
             new Response(
               JSON.stringify([
                 { name: 'file1.jpg', id: '1' },
-                { name: 'subfolder/', id: '2' },
+                { name: 'subfolder/', id: null },
                 { name: 'file2.png', id: '3' },
               ]),
               { status: 200 }