@_nazmiforreal/flutter-ota 0.1.0 → 0.1.1

package/dart-src/plugins/cloudflare/lib/src/d1_build_where.dart

@@ -0,0 +1,93 @@
+import 'dart:convert' show jsonEncode;
+
+import 'package:flutter_patcher_plugin_core/flutter_patcher_plugin_core.dart'
+    show DatabaseBundleQueryWhere;
+
+/// Result of building a WHERE clause: SQL fragment plus positional params.
+class _BuildWhereResult {
+  const _BuildWhereResult(this.sql, this.params);
+
+  final String sql;
+  final List<dynamic> params;
+}
+
+/// Build a SQLite WHERE clause with positional `?` params, mirroring
+/// `buildWhereClause` from hot-updater's `d1Database.ts`.
+_BuildWhereResult buildWhereClause(DatabaseBundleQueryWhere conditions) {
+  final clauses = <String>[];
+  final params = <dynamic>[];
+
+  String jsonEachIn(String columnName, List<String> values) {
+    if (values.isEmpty) return '1 = 0';
+    params.add(jsonEncode(values));
+    return '$columnName IN (SELECT value FROM json_each(?))';
+  }
+
+  if (conditions.channel != null) {
+    clauses.add('channel = ?');
+    params.add(conditions.channel);
+  }
+
+  if (conditions.platform != null) {
+    clauses.add('platform = ?');
+    params.add(conditions.platform!.value);
+  }
+
+  if (conditions.enabled != null) {
+    clauses.add('enabled = ?');
+    params.add(conditions.enabled! ? 1 : 0);
+  }
+
+  if (conditions.id?.ins != null) {
+    clauses.add(jsonEachIn('id', conditions.id!.ins!));
+  }
+
+  if (conditions.id?.eq != null) {
+    clauses.add('id = ?');
+    params.add(conditions.id!.eq);
+  }
+
+  if (conditions.id?.gt != null) {
+    clauses.add('id > ?');
+    params.add(conditions.id!.gt);
+  }
+
+  if (conditions.id?.gte != null) {
+    clauses.add('id >= ?');
+    params.add(conditions.id!.gte);
+  }
+
+  if (conditions.id?.lt != null) {
+    clauses.add('id < ?');
+    params.add(conditions.id!.lt);
+  }
+
+  if (conditions.id?.lte != null) {
+    clauses.add('id <= ?');
+    params.add(conditions.id!.lte);
+  }
+
+  if (conditions.targetAppVersionNotNull == true) {
+    clauses.add('target_app_version IS NOT NULL');
+  }
+
+  if (conditions.targetAppVersion != null) {
+    clauses.add('target_app_version = ?');
+    params.add(conditions.targetAppVersion);
+  }
+
+  if (conditions.targetAppVersionIn != null) {
+    clauses.add(
+      jsonEachIn('target_app_version', conditions.targetAppVersionIn!),
+    );
+  }
+
+  if (conditions.fingerprintHash != null) {
+    clauses.add('fingerprint_hash = ?');
+    params.add(conditions.fingerprintHash);
+  }
+
+  final whereClause =
+      clauses.isNotEmpty ? ' WHERE ${clauses.join(' AND ')}' : '';
+  return _BuildWhereResult(whereClause, params);
+}

package/dart-src/plugins/cloudflare/lib/src/d1_bundle_mapper.dart

@@ -0,0 +1,131 @@
+import 'dart:convert' show jsonDecode;
+
+import 'package:flutter_patcher_core/flutter_patcher_core.dart'
+    show Bundle, BundleMetadata, BundlePatchArtifact, Platform, getBundlePatches;
+
+/// Default rollout cohort count — full rollout in the Dart port's per-mille
+/// scale (matches core's `defaultRolloutCohortCount` = `numericCohortSize`).
+const int defaultRolloutCohortCount = 1000;
+
+/// Compound patch id `${bundleId}:${baseBundleId}` (matches D1 schema).
+String buildBundlePatchId(String bundleId, String baseBundleId) =>
+    '$bundleId:$baseBundleId';
+
+/// Parse `target_cohorts` which is stored as a JSON string (or already a list).
+List<String>? parseTargetCohorts(dynamic value) {
+  if (value == null) return null;
+  if (value is List) {
+    return [
+      for (final v in value)
+        if (v is String) v,
+    ];
+  }
+  if (value is String) {
+    try {
+      final parsed = jsonDecode(value);
+      if (parsed is List) {
+        return [
+          for (final v in parsed)
+            if (v is String) v,
+        ];
+      }
+    } catch (_) {
+      return null;
+    }
+  }
+  return null;
+}
+
+/// Parse `metadata` which may be a JSON string or an already-decoded object.
+Map<String, Object?>? parseMetadata(dynamic value) {
+  if (value == null) return null;
+  if (value is String) {
+    try {
+      return parseMetadata(jsonDecode(value));
+    } catch (_) {
+      return null;
+    }
+  }
+  if (value is Map) {
+    return value.cast<String, Object?>();
+  }
+  return null;
+}
+
+/// Convert a [Bundle] into the rows inserted into `bundle_patches`.
+List<Map<String, dynamic>> bundleToPatchRows(Bundle bundle) =>
+    getBundlePatches(bundle).asMap().entries.map((entry) {
+      final patch = entry.value;
+      return {
+        'id': buildBundlePatchId(bundle.id, patch.baseBundleId),
+        'bundle_id': bundle.id,
+        'base_bundle_id': patch.baseBundleId,
+        'base_file_hash': patch.baseFileHash,
+        'patch_file_hash': patch.patchFileHash,
+        'patch_storage_uri': patch.patchStorageUri,
+        'order_index': entry.key,
+      };
+    }).toList();
+
+/// Rebuild a [Bundle] from a D1 `bundles` row plus its `bundle_patches` rows.
+Bundle transformRowToBundle(
+  Map<String, dynamic> row, [
+  List<Map<String, dynamic>> patchRows = const [],
+]) {
+  final rawMetadata = parseMetadata(row['metadata']);
+  final metadata = rawMetadata == null
+      ? null
+      : BundleMetadata.fromJson(rawMetadata.cast<String, dynamic>());
+  final patches = patchRows
+      .toList()
+    ..sort(
+      (left, right) =>
+          (left['order_index'] as num? ?? 0)
+              .compareTo(right['order_index'] as num? ?? 0) +
+          (left['base_bundle_id'] as String? ?? '')
+              .compareTo(right['base_bundle_id'] as String? ?? ''),
+    );
+
+  final bundlePatches = patches.map((patch) {
+    return BundlePatchArtifact(
+      baseBundleId: patch['base_bundle_id'] as String,
+      baseFileHash: patch['base_file_hash'] as String,
+      patchFileHash: patch['patch_file_hash'] as String,
+      patchStorageUri: patch['patch_storage_uri'] as String,
+    );
+  }).toList();
+
+  final primaryPatch = bundlePatches.isNotEmpty ? bundlePatches.first : null;
+
+  final enabled = row['enabled'];
+  final shouldForceUpdate = row['should_force_update'];
+
+  return Bundle(
+    id: row['id'] as String,
+    channel: row['channel'] as String,
+    enabled: enabled is bool ? enabled : (enabled as num? ?? 0) != 0,
+    shouldForceUpdate: shouldForceUpdate is bool
+        ? shouldForceUpdate
+        : (shouldForceUpdate as num? ?? 0) != 0,
+    fileHash: row['file_hash'] as String,
+    gitCommitHash: row['git_commit_hash'] as String?,
+    message: row['message'] as String?,
+    platform: Platform.fromValue(row['platform'] as String),
+    targetAppVersion: row['target_app_version'] as String?,
+    storageUri: row['storage_uri'] as String,
+    fingerprintHash: row['fingerprint_hash'] as String?,
+    metadata: metadata,
+    manifestStorageUri: row['manifest_storage_uri'] as String?,
+    manifestFileHash: row['manifest_file_hash'] as String?,
+    assetBaseStorageUri: row['asset_base_storage_uri'] as String?,
+    patches: bundlePatches,
+    patchBaseBundleId: primaryPatch?.baseBundleId,
+    patchBaseFileHash: primaryPatch?.baseFileHash,
+    patchFileHash: primaryPatch?.patchFileHash,
+    patchStorageUri: primaryPatch?.patchStorageUri,
+    rolloutCohortCount:
+        (row['rollout_cohort_count'] as num? ?? defaultRolloutCohortCount)
+            .toInt(),
+    targetCohorts: parseTargetCohorts(row['target_cohorts']),
+  );
+}

package/dart-src/plugins/cloudflare/lib/src/d1_client.dart

@@ -0,0 +1,66 @@
+import 'dart:convert' show jsonDecode, jsonEncode;
+
+import 'package:http/http.dart' show Client;
+
+import 'd1_config.dart' show D1DatabaseConfig;
+
+/// A thin client over a Cloudflare D1 database.
+///
+/// Mirrors the `cf.d1.database.query(databaseId, { account_id, sql, params })`
+/// call from hot-updater's cloudflare plugin: each call issues a single SQL
+/// statement with positional `?` parameters and returns the flattened result
+/// rows as JSON maps.
+abstract class D1ClientLike {
+  const D1ClientLike();
+
+  Future<List<Map<String, dynamic>>> query(
+    String sql, [
+    List<dynamic> params = const [],
+  ]);
+}
+
+/// Real D1 client backed by the Cloudflare REST API.
+class D1Client implements D1ClientLike {
+  D1Client(this.config, {Client? http}) : _http = http ?? Client();
+
+  final D1DatabaseConfig config;
+  final Client _http;
+
+  @override
+  Future<List<Map<String, dynamic>>> query(
+    String sql, [
+    List<dynamic> params = const [],
+  ]) async {
+    final uri = Uri.https(
+      'api.cloudflare.com',
+      '/client/v4/accounts/${config.accountId}/d1/database/${config.databaseId}/query',
+    );
+
+    final response = await _http.post(
+      uri,
+      headers: {
+        'Authorization': 'Bearer ${config.cloudflareApiToken}',
+        'Content-Type': 'application/json',
+      },
+      body: jsonEncode({'sql': sql, 'params': params}),
+    );
+
+    if (response.statusCode < 200 || response.statusCode >= 300) {
+      throw Exception(
+        'Cloudflare D1 query failed (${response.statusCode}): ${response.body}',
+      );
+    }
+
+    final decoded = jsonDecode(response.body) as Map<String, dynamic>;
+    final result = (decoded['result'] as List?) ?? const <dynamic>[];
+
+    final rows = <Map<String, dynamic>>[];
+    for (final page in result.cast<Map<String, dynamic>>()) {
+      final pageResults = (page['results'] as List?) ?? const <dynamic>[];
+      for (final row in pageResults) {
+        rows.add((row as Map).cast<String, dynamic>());
+      }
+    }
+    return rows;
+  }
+}

package/dart-src/plugins/cloudflare/lib/src/d1_config.dart

@@ -0,0 +1,30 @@
+import 'd1_client.dart' show D1Client, D1ClientLike;
+
+/// Configuration for the Cloudflare D1 database plugin.
+class D1DatabaseConfig {
+  const D1DatabaseConfig({
+    required this.databaseId,
+    required this.accountId,
+    required this.cloudflareApiToken,
+    this.clientFactory,
+  });
+
+  /// Cloudflare D1 database ID.
+  final String databaseId;
+
+  /// Cloudflare account ID.
+  final String accountId;
+
+  /// Cloudflare API token with D1 read/write permissions.
+  final String cloudflareApiToken;
+
+  /// Optional factory used to inject a [D1ClientLike] in tests.
+  final D1ClientFactory? clientFactory;
+}
+
+/// Builds a [D1ClientLike] for the given [D1DatabaseConfig].
+typedef D1ClientFactory = D1ClientLike Function(D1DatabaseConfig config);
+
+/// Resolves the client for a config, using the injected factory when present.
+D1ClientLike resolveD1Client(D1DatabaseConfig config) =>
+    config.clientFactory?.call(config) ?? D1Client(config);

package/dart-src/plugins/cloudflare/lib/src/d1_database.dart

@@ -0,0 +1,16 @@
+import 'package:flutter_patcher_plugin_core/flutter_patcher_plugin_core.dart'
+    show createDatabasePlugin;
+
+import 'd1_config.dart' show D1DatabaseConfig, resolveD1Client;
+import 'd1_database_plugin.dart' show D1DatabasePlugin;
+
+/// Cloudflare D1 database plugin over the REST API (faithful port of
+/// hot-updater's `d1Database`).
+///
+/// Issues raw SQLite statements against Cloudflare D1 over the REST API and
+/// resolves update information in-process via [resolveUpdateInfoFromBundles]
+/// (no SQL stored procedures, unlike the Supabase/Postgres backends).
+final d1Database = createDatabasePlugin<D1DatabaseConfig>(
+  name: 'd1Database',
+  factory: (config) => D1DatabasePlugin(resolveD1Client(config)),
+);

package/dart-src/plugins/cloudflare/lib/src/d1_database_plugin.dart

@@ -0,0 +1,314 @@
+import 'dart:convert' show jsonEncode;
+
+import 'package:flutter_patcher_core/flutter_patcher_core.dart'
+    show
+        AppVersionGetBundlesArgs,
+        Bundle,
+        FingerprintGetBundlesArgs,
+        GetBundlesArgs,
+        UpdateInfo,
+        UpdateStrategy;
+import 'package:flutter_patcher_plugin_core/flutter_patcher_plugin_core.dart'
+    show
+        AbstractDatabasePlugin,
+        BundleChange,
+        BundleChangeOperation,
+        DatabaseBundleIdFilter,
+        DatabaseBundleQueryOptions,
+        DatabaseBundleQueryOrder,
+        DatabaseBundleQueryWhere,
+        Paginated,
+        calculatePagination,
+        filterCompatibleAppVersions,
+        resolveUpdateInfoFromBundles,
+        ResolveUpdateInfoFromBundlesOptions;
+
+import 'd1_bundle_mapper.dart'
+    show
+        bundleToPatchRows,
+        defaultRolloutCohortCount,
+        transformRowToBundle;
+import 'd1_build_where.dart' show buildWhereClause;
+import 'd1_client.dart' show D1ClientLike;
+
+/// Shared D1 database plugin logic used by both [d1Database] (REST API client)
+/// and [cloudflareWorkerDatabase] (in-process D1 binding).
+///
+/// Issues raw SQLite statements and resolves update information in-process via
+/// [resolveUpdateInfoFromBundles] (no SQL stored procedures, unlike the
+/// Supabase/Postgres backends).
+class D1DatabasePlugin implements AbstractDatabasePlugin {
+  D1DatabasePlugin(this._client);
+
+  final D1ClientLike _client;
+
+  Future<Map<String, List<Map<String, dynamic>>>> _getPatchMap(
+    List<String> bundleIds,
+  ) async {
+    final patchMap = <String, List<Map<String, dynamic>>>{};
+    if (bundleIds.isEmpty) return patchMap;
+
+    final rows = await _client.query(
+      'SELECT * FROM bundle_patches '
+      'WHERE bundle_id IN (SELECT value FROM json_each(?)) '
+      'ORDER BY order_index ASC, base_bundle_id ASC',
+      [jsonEncode(bundleIds)],
+    );
+
+    for (final row in rows) {
+      (patchMap[row['bundle_id'] as String] ??= []).add(row);
+    }
+    return patchMap;
+  }
+
+  Future<int> _getTotalCount(DatabaseBundleQueryWhere conditions) async {
+    final where = buildWhereClause(conditions);
+    final rows = await _client.query(
+      'SELECT COUNT(*) as total FROM bundles${where.sql}',
+      where.params,
+    );
+    return (rows.firstOrNull?['total'] as num?)?.toInt() ?? 0;
+  }
+
+  Future<List<Bundle>> _getPaginatedBundles(
+    DatabaseBundleQueryWhere conditions,
+    int limit,
+    int offset,
+    DatabaseBundleQueryOrder? orderBy,
+  ) async {
+    final where = buildWhereClause(conditions);
+    final orderBySql =
+        orderBy?.direction == 'asc' ? 'ORDER BY id ASC' : 'ORDER BY id DESC';
+
+    final rows = await _client.query(
+      'SELECT * FROM bundles ${where.sql} $orderBySql LIMIT ? OFFSET ?',
+      [...where.params, limit, offset],
+    );
+
+    final patchMap = await _getPatchMap(
+      rows.map((row) => row['id'] as String).toList(),
+    );
+    return rows
+        .map((row) => transformRowToBundle(row, patchMap[row['id']] ?? const []))
+        .toList();
+  }
+
+  Future<List<Bundle>> _queryBundlesForUpdateInfo(
+    DatabaseBundleQueryWhere conditions,
+  ) async {
+    final where = buildWhereClause(conditions);
+    final rows = await _client.query(
+      'SELECT * FROM bundles${where.sql}',
+      where.params,
+    );
+    final patchMap = await _getPatchMap(
+      rows.map((row) => row['id'] as String).toList(),
+    );
+    return rows
+        .map((row) => transformRowToBundle(row, patchMap[row['id']] ?? const []))
+        .toList();
+  }
+
+  Future<List<String>> _getTargetAppVersionsForUpdateInfo({
+    required String channel,
+    required String platform,
+    required String minBundleId,
+  }) async {
+    final rows = await _client.query(
+      'SELECT target_app_version FROM bundles '
+      'WHERE channel = ? AND platform = ? AND enabled = 1 '
+      'AND id >= ? AND target_app_version IS NOT NULL '
+      'GROUP BY target_app_version',
+      [channel, platform, minBundleId],
+    );
+    return rows
+        .map((row) => row['target_app_version'] as String)
+        .toList();
+  }
+
+  @override
+  Future<UpdateInfo?> getUpdateInfo(GetBundlesArgs args) async {
+    final channel = args.channel;
+    final minBundleId = args.minBundleId;
+    final platform = args.platform.value;
+
+    if (args.updateStrategy == UpdateStrategy.appVersion) {
+      final appVersion = (args as AppVersionGetBundlesArgs).appVersion;
+      final targetAppVersions = await _getTargetAppVersionsForUpdateInfo(
+        channel: channel,
+        platform: platform,
+        minBundleId: minBundleId,
+      );
+      final compatibleAppVersions = filterCompatibleAppVersions(
+        targetAppVersions,
+        appVersion,
+      );
+      final bundles = compatibleAppVersions.isNotEmpty
+          ? await _queryBundlesForUpdateInfo(
+              DatabaseBundleQueryWhere(
+                enabled: true,
+                platform: args.platform,
+                channel: channel,
+                id: DatabaseBundleIdFilter(gte: minBundleId),
+                targetAppVersionIn: compatibleAppVersions,
+              ),
+            )
+          : const <Bundle>[];
+
+      return resolveUpdateInfoFromBundles(
+        ResolveUpdateInfoFromBundlesOptions(args: args, bundles: bundles),
+      );
+    }
+
+    final fingerprintHash = args is FingerprintGetBundlesArgs
+        ? args.fingerprintHash
+        : null;
+
+    final bundles = await _queryBundlesForUpdateInfo(
+      DatabaseBundleQueryWhere(
+        enabled: true,
+        platform: args.platform,
+        channel: channel,
+        id: DatabaseBundleIdFilter(gte: minBundleId),
+        fingerprintHash: fingerprintHash,
+      ),
+    );
+
+    return resolveUpdateInfoFromBundles(
+      ResolveUpdateInfoFromBundlesOptions(args: args, bundles: bundles),
+    );
+  }
+
+  @override
+  Future<Bundle?> getBundleById(String bundleId) async {
+    final rows = await _client.query(
+      'SELECT * FROM bundles WHERE id = ? LIMIT 1',
+      [bundleId],
+    );
+    if (rows.isEmpty) return null;
+
+    final patchMap = await _getPatchMap([bundleId]);
+    return transformRowToBundle(rows.first, patchMap[bundleId] ?? const []);
+  }
+
+  @override
+  Future<Paginated<List<Bundle>>> getBundles(
+    DatabaseBundleQueryOptions options,
+  ) async {
+    final where = options.where ?? const DatabaseBundleQueryWhere();
+    final limit = options.limit;
+    final offset = options.offset ??
+        (options.page != null ? (options.page! - 1) * limit : 0);
+
+    final totalCount = await _getTotalCount(where);
+    final bundles = await _getPaginatedBundles(
+      where,
+      limit,
+      offset,
+      options.orderBy,
+    );
+
+    final pagination = calculatePagination(
+      totalCount,
+      limit: limit,
+      offset: offset,
+    );
+
+    return Paginated<List<Bundle>>(data: bundles, pagination: pagination);
+  }
+
+  @override
+  Future<List<String>> getChannels() async {
+    final rows = await _client.query(
+      'SELECT channel FROM bundles GROUP BY channel',
+    );
+    return rows.map((row) => row['channel'] as String).toList();
+  }
+
+  @override
+  bool get supportsCursorPagination => false;
+
+  @override
+  Future<void> onUnmount() async {}
+
+  @override
+  Future<void> commitBundle({
+    required List<BundleChange> changedSets,
+  }) async {
+    if (changedSets.isEmpty) return;
+
+    for (final op in changedSets) {
+      if (op.operation == BundleChangeOperation.delete) {
+        await _client.query(
+          'DELETE FROM bundle_patches WHERE bundle_id = ?',
+          [op.data.id],
+        );
+        await _client.query(
+          'DELETE FROM bundle_patches WHERE base_bundle_id = ?',
+          [op.data.id],
+        );
+        await _client.query(
+          'DELETE FROM bundles WHERE id = ?',
+          [op.data.id],
+        );
+      } else {
+        final bundle = op.data;
+        await _client.query(
+          'INSERT OR REPLACE INTO bundles ('
+          'id, channel, enabled, should_force_update, file_hash, '
+          'git_commit_hash, message, platform, target_app_version, '
+          'storage_uri, fingerprint_hash, metadata, manifest_storage_uri, '
+          'manifest_file_hash, asset_base_storage_uri, rollout_cohort_count, '
+          'target_cohorts) VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)',
+          [
+            bundle.id,
+            bundle.channel,
+            bundle.enabled ? 1 : 0,
+            bundle.shouldForceUpdate ? 1 : 0,
+            bundle.fileHash,
+            bundle.gitCommitHash,
+            bundle.message,
+            bundle.platform.value,
+            bundle.targetAppVersion,
+            bundle.storageUri,
+            bundle.fingerprintHash,
+            jsonEncode(
+              bundle.metadata?.toJson() ?? <String, dynamic>{},
+            ),
+            bundle.manifestStorageUri,
+            bundle.manifestFileHash,
+            bundle.assetBaseStorageUri,
+            bundle.rolloutCohortCount ?? defaultRolloutCohortCount,
+            bundle.targetCohorts != null
+                ? jsonEncode(bundle.targetCohorts)
+                : null,
+          ],
+        );
+
+        await _client.query(
+          'DELETE FROM bundle_patches WHERE bundle_id = ?',
+          [bundle.id],
+        );
+
+        final patchRows = bundleToPatchRows(bundle);
+        for (final patchRow in patchRows) {
+          await _client.query(
+            'INSERT OR REPLACE INTO bundle_patches ('
+            'id, bundle_id, base_bundle_id, base_file_hash, '
+            'patch_file_hash, patch_storage_uri, order_index) '
+            'VALUES (?, ?, ?, ?, ?, ?, ?)',
+            [
+              patchRow['id'],
+              patchRow['bundle_id'],
+              patchRow['base_bundle_id'],
+              patchRow['base_file_hash'],
+              patchRow['patch_file_hash'],
+              patchRow['patch_storage_uri'],
+              patchRow['order_index'],
+            ],
+          );
+        }
+      }
+    }
+  }
+}

package/dart-src/plugins/cloudflare/lib/src/r2_config.dart

@@ -0,0 +1,50 @@
+import 'r2_s3_client.dart' show R2S3Client, R2S3ClientLike;
+
+/// Configuration for the Cloudflare R2 S3-compatible storage plugin.
+///
+/// Mirrors hot-updater's `R2S3StorageConfig` (a thin wrapper over the AWS S3
+/// client config). Credentials are passed directly (access/secret keys) and
+/// the client signs requests with AWS Signature V4 against the R2 endpoint.
+class R2S3StorageConfig {
+  const R2S3StorageConfig({
+    required this.accountId,
+    required this.bucketName,
+    required this.accessKeyId,
+    required this.secretAccessKey,
+    this.basePath,
+    this.region = 'auto',
+    this.endpoint,
+    this.clientFactory,
+  });
+
+  /// Cloudflare account ID (used to build the R2 endpoint host).
+  final String accountId;
+
+  /// Target R2 bucket name.
+  final String bucketName;
+
+  /// S3 access key ID.
+  final String accessKeyId;
+
+  /// S3 secret access key.
+  final String secretAccessKey;
+
+  /// Optional base path prepended to all object keys.
+  final String? basePath;
+
+  /// R2 region (defaults to "auto").
+  final String region;
+
+  /// Override endpoint (defaults to `https://<accountId>.r2.cloudflarestorage.com`).
+  final String? endpoint;
+
+  /// Optional factory used to inject an [R2S3ClientLike] in tests.
+  final R2S3ClientFactory? clientFactory;
+}
+
+/// Builds an [R2S3ClientLike] for the given [R2S3StorageConfig].
+typedef R2S3ClientFactory = R2S3ClientLike Function(R2S3StorageConfig config);
+
+/// Resolves the client for a config, using the injected factory when present.
+R2S3ClientLike resolveR2Client(R2S3StorageConfig config) =>
+    config.clientFactory?.call(config) ?? R2S3Client(config);