feat(storage): expose purgeCache for buckets and single objects

[mandarini]

Description

Adds storage.from(bucket).purgeCache(path) mapping to the Storage API's DELETE /cdn/{bucket}/{path} endpoint. Calling it issues a CDN invalidation for the named object.

What changed?

• New method purgeCache(path, parameters?) on StorageFileApi. Returns { data: { message }, error: null } on success or { data: null, error } on failure. Threads parameters through to the underlying fetch (e.g. AbortController signal), matching the shape used by download().
• Uses the existing handleOperation + _getFinalPath + remove helper plumbing. No new error types, no new dependencies, no new imports.
• Three mock-based tests covering: happy path (DELETE on /cdn/{bucket}/{path} returns { message }), server 404 surfacing as StorageApiError, and signal forwarding through parameters.

Why was this change needed?

Cache purging has been a long-standing ask. This supersedes #1742 (originally proposed by @mansueli in supabase/storage-js#229).

What this PR deliberately leaves out vs #1742:

• No purgeCacheByPrefix. The Storage server has no native prefix-purge endpoint. A client-side list() + N individual DELETEs loop is silently non-recursive (the storage list endpoint is not recursive), unpaginated past 1000 objects, and sequential per object even with a batchSize knob. If users need bulk invalidation, that should be solved server-side.
• No client-side wildcard or empty-path validation. The server's error responses are the source of truth.

Two operational gotchas:

1. The endpoint enforces service_role JWT (enforceJwtRoles: [dbServiceRole] in storage/src/http/routes/cdn/index.ts). Anon or user JWT calls will be rejected.
2. The endpoint is gated behind the purgeCache tenant feature, and self-hosted deployments need CDN_PURGE_ENDPOINT_URL configured.

Supersedes #1742.

Screenshots/Examples

// purge entire bucket cache
const { data, error } = await storage.purgeBucketCache('bucket-name')

// purge individual object cache
const { data, error } = await supabase.storage
  .from('avatars')
  .purgeCache('folder/avatar1.png' )

// purge only transformations:
await supabase.storage
  .from('avatars')
  .purgeCache('folder/avatar1.png', { transformations: true })

// Cancellation:
const controller = new AbortController()
await supabase.storage
  .from('avatars')
  .purgeCache('folder/avatar1.png', undefined, { signal: controller.signal })

Breaking changes

• This PR contains no breaking changes

Additive: a new public method, no changes to any existing API.

Checklist

• I have read the Contributing Guidelines
• My PR title follows the conventional commit format: <type>(<scope>): <description>
• I have run pnpm nx format to ensure consistent code formatting
• I have added tests for new functionality (if applicable)
• I have updated documentation (if applicable)

Additional notes

Server-side cross-reference for reviewers:

• Route: src/http/routes/cdn/purgeCache.ts in supabase/storage. The route is fastify.delete('/:bucketName/*') mounted under /cdn.
• Auth gate: src/http/routes/cdn/index.ts registers the route with enforceJwtRoles: [dbServiceRole] and requireTenantFeature('purgeCache').
• CDN delegation: src/storage/cdn/cdn-cache-manager.ts forwards to CDN_PURGE_ENDPOINT_URL (or errors out if unset).

No integration test against the local Docker storage stack is included. The CDN purge endpoint requires CDN_PURGE_ENDPOINT_URL plus the purgeCache tenant feature, neither of which are configured in the local compose, so an integration test would either skip or fail spuriously. A manual smoke test against a hosted project with the service_role key is recommended before promoting the canary to stable.

[pkg-pr-new]

Open in StackBlitz

@supabase/auth-js

npm i https://pkg.pr.new/@supabase/auth-js@2429

@supabase/functions-js

npm i https://pkg.pr.new/@supabase/functions-js@2429

@supabase/postgrest-js

npm i https://pkg.pr.new/@supabase/postgrest-js@2429

@supabase/realtime-js

npm i https://pkg.pr.new/@supabase/realtime-js@2429

@supabase/storage-js

npm i https://pkg.pr.new/@supabase/storage-js@2429

@supabase/supabase-js

npm i https://pkg.pr.new/@supabase/supabase-js@2429

commit: 21a31f9

[mandarini]

do not merge until @itslenny works on this

[ferhatelmas]

const controller = new AbortController()
await supabase.storage
  .from('avatars')
  .purgeCache({ object: 'folder/avatar1.png' }, { signal: controller.signal })

This example from PR description needs an update as well, it might be from a previous iteration