feat(storage): add purgeCache to invalidate CDN cache for a single object (#1607)

## Summary

Adds `StorageFileApi.purgeCache(path, {transformations})` to invalidate
the CDN cache for a single object in a bucket. Issues `DELETE
/cdn/{bucket}/{path}` 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
object intact; otherwise the object cache is purged.

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

**Outcome:** implemented

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

## Compliance matrix

- `storage.file_buckets.purge_cache` → `implemented` (symbol
`StorageFileApi.purgeCache`)

## Tests

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

SDK-1331

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/lib/src/storage_file_api.dart

@@ -695,6 +695,37 @@ class StorageFileApi {
     return fileObjects;
   }
 
+  /// Purges the CDN cache for a single object.
+  ///
+  /// Invalidates the CDN cache for the object at [path] (relative to the
+  /// bucket). There is no wildcard or recursion; pass the exact path of the
+  /// object to invalidate. For example: `purgeCache('folder/avatar.png')`.
+  ///
+  /// When [transformations] is `true`, only the resized/formatted variants are
+  /// purged, leaving the original cached file intact. When omitted the object
+  /// cache is purged.
+  ///
+  /// Requires the service-role key and the tenant `purgeCache` feature to be
+  /// enabled on the storage server.
+  Future<String> purgeCache(
+    String path, {
+    bool transformations = false,
+  }) async {
+    final finalPath = _getFinalPath(path);
+    var requestUrl = Uri.parse('$url/cdn/$finalPath');
+    if (transformations) {
+      requestUrl = requestUrl.replace(
+        queryParameters: {'transformations': 'true'},
+      );
+    }
+    final response = await _storageFetch.delete(
+      requestUrl.toString(),
+      {},
+      options: _fetchOptions,
+    );
+    return (response as Map<String, dynamic>)['message'] as String;
+  }
+
   /// Lists all the files within a bucket.
   ///
   /// [path] The folder path.

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;
 
@@ -248,6 +277,37 @@ void main() {
       expect(response, 'Move');
     });
 
+    test('should purgeCache issuing DELETE to /cdn/{bucket}/{path}', () async {
+      customHttpClient.response = {'message': 'success'};
+
+      final response = await client.from('public').purgeCache('folder/a.txt');
+
+      final request = customHttpClient.receivedRequests.last;
+      expect(request.method, 'DELETE');
+      expect(
+        request.url.toString(),
+        endsWith('/storage/v1/cdn/public/folder/a.txt'),
+      );
+      expect(request.url.query, isEmpty);
+      expect(response, 'success');
+    });
+
+    test('should purgeCache with transformations query param', () async {
+      customHttpClient.response = {'message': 'success'};
+
+      final response = await client
+          .from('public')
+          .purgeCache('folder/a.txt', transformations: true);
+
+      final request = customHttpClient.receivedRequests.last;
+      expect(request.method, 'DELETE');
+      expect(
+        request.url.queryParameters['transformations'],
+        'true',
+      );
+      expect(response, 'success');
+    });
+
     test('should createSignedUrl file', () async {
       customHttpClient.response = {'signedURL': '/signed/url'};
 

sdk-compliance.yaml

@@ -438,6 +438,14 @@ features:
   storage.file_buckets.copy: implemented
   storage.file_buckets.copy_cross_bucket: implemented
   storage.file_buckets.remove: implemented
+  storage.file_buckets.purge_cache:
+    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: