feat(storage): add purgeBucketCache to invalidate CDN cache for a whole bucket (#1608)

## Summary

Adds `StorageBucketApi.purgeBucketCache(id, {transformations})` to
invalidate the CDN cache for every object in a bucket. Issues `DELETE
/cdn/{bucket}` against the storage base URL and returns the server's
success message. When `transformations` is `true`, only the
resized/formatted variants are purged, leaving the original cached
objects intact; otherwise the bucket cache is purged.

Requires the service-role key and the tenant `purgeCache` feature
enabled on the storage server.

> Stacked on top of #1607 (`SDK-1331`, object-level purge). Base this PR
against `main` once #1607 merges.

**Outcome:** implemented

**Reference:** supabase-js PR
[#2429](supabase/supabase-js#2429)
(`storage.file_buckets.purge_bucket_cache`)

## Compliance matrix

- `storage.file_buckets.purge_bucket_cache` → `implemented` (symbol
`StorageBucketApi.purgeBucketCache`)

## Tests

Added unit tests in `packages/storage_client/test/basic_test.dart`
covering the DELETE endpoint/URL and the `transformations` query
parameter.

SDK-1332

Author: spydon

packages/storage_client/lib/src/storage_bucket_api.dart

@@ -134,6 +134,35 @@ class StorageBucketApi {
     return (response as Map<String, dynamic>)['message'] as String;
   }
 
+  /// Purges the CDN cache for an entire bucket.
+  ///
+  /// Invalidates the CDN cache for every object in the bucket [id]. Maps to
+  /// `DELETE /cdn/{bucket}` on the storage server.
+  ///
+  /// When [transformations] is `true`, only the resized/formatted variants are
+  /// purged, leaving the original cached files intact. When omitted the bucket
+  /// cache is purged.
+  ///
+  /// Requires the service-role key and the tenant `purgeCache` feature to be
+  /// enabled on the storage server.
+  Future<String> purgeBucketCache(
+    String id, {
+    bool transformations = false,
+  }) async {
+    var requestUrl = Uri.parse('$url/cdn/$id');
+    if (transformations) {
+      requestUrl = requestUrl.replace(
+        queryParameters: {'transformations': 'true'},
+      );
+    }
+    final response = await storageFetch.delete(
+      requestUrl.toString(),
+      {},
+      options: FetchOptions(headers),
+    );
+    return (response as Map<String, dynamic>)['message'] as String;
+  }
+
   /// Creates a new analytics bucket backed by the Apache Iceberg table format.
   ///
   /// [id] is the unique identifier for the bucket you are creating.

packages/storage_client/test/basic_test.dart

@@ -154,6 +154,35 @@ void main() {
       expect(response, 'Deleted');
     });
 
+    test('should purgeBucketCache issuing DELETE to /cdn/{bucket}', () async {
+      customHttpClient.response = {'message': 'success'};
+
+      final response = await client.purgeBucketCache('test_bucket');
+
+      final request = customHttpClient.receivedRequests.last;
+      expect(request.method, 'DELETE');
+      expect(
+        request.url.toString(),
+        endsWith('/storage/v1/cdn/test_bucket'),
+      );
+      expect(request.url.query, isEmpty);
+      expect(response, 'success');
+    });
+
+    test('should purgeBucketCache with transformations query param', () async {
+      customHttpClient.response = {'message': 'success'};
+
+      final response = await client.purgeBucketCache(
+        'test_bucket',
+        transformations: true,
+      );
+
+      final request = customHttpClient.receivedRequests.last;
+      expect(request.method, 'DELETE');
+      expect(request.url.queryParameters['transformations'], 'true');
+      expect(response, 'success');
+    });
+
     test('should create analytics bucket', () async {
       customHttpClient.response = testAnalyticsBucketJson;
 

sdk-compliance.yaml

@@ -442,6 +442,10 @@ features:
     status: implemented
     symbols:
       - StorageFileApi.purgeCache
+  storage.file_buckets.purge_bucket_cache:
+    status: implemented
+    symbols:
+      - StorageBucketApi.purgeBucketCache
   storage.file_buckets.create_signed_url:
     status: implemented
     symbols: