@_nazmiforreal/flutter-ota 0.1.11 → 0.1.13

package/dart-src/plugins/pocketbase/lib/src/pocketbase_client.dart

@@ -0,0 +1,349 @@
+/// Minimal PocketBase HTTP client (REST API).
+///
+/// PocketBase is a single-binary Go backend that exposes a REST API at
+/// `/api/`. The official `pocketbase` Dart package exists but pulls in
+/// `dart:io`/`dart:html` polyfills that conflict with Flutter Web, so we
+/// implement just the subset we need on top of `package:http`.
+///
+/// See: https://pocketbase.io/docs/api-records/
+library;
+
+import 'dart:async';
+import 'dart:convert';
+
+import 'package:http/http.dart' as http;
+
+/// Factory for creating [PocketBaseClient] instances. Allows tests to inject
+/// a fake client without spinning up a real PB server.
+typedef PocketBaseClientFactory = PocketBaseClient Function(
+  String baseUrl,
+  String adminEmail,
+  String adminPassword,
+);
+
+/// A thin REST client for PocketBase admin operations.
+///
+/// Authenticates with the admin collection to obtain a long-lived auth token,
+/// then exposes typed helpers for CRUD on collections and file storage.
+class PocketBaseClient {
+  PocketBaseClient._(this._baseUrl, this._token, this._http);
+
+  /// Build a client (unauthenticated). Call [adminCredentials] and
+  /// [authenticate] before use, or rely on lazy auth.
+  factory PocketBaseClient(String baseUrl, {http.Client? httpClient}) =>
+      PocketBaseClient._(
+        _normalizeUrl(baseUrl),
+        '',
+        httpClient ?? http.Client(),
+      );
+
+  final String _baseUrl;
+  String _token;
+  final http.Client _http;
+
+  static String _normalizeUrl(String url) {
+    var u = url.trim();
+    if (u.endsWith('/')) u = u.substring(0, u.length - 1);
+    return u;
+  }
+
+  /// Provide admin credentials for lazy authentication.
+  void adminCredentials(String email, String password) {
+    _adminEmail = email;
+    _adminPassword = password;
+  }
+
+  /// Authenticate as [adminEmail] / [adminPassword]. Idempotent — calling
+  /// twice refreshes the token.
+  Future<PocketBaseClient> authenticate(
+    String adminEmail,
+    String adminPassword,
+  ) async {
+    final res = await _http.post(
+      Uri.parse('$_baseUrl/api/admins/auth-with-password'),
+      headers: {'content-type': 'application/json'},
+      body: jsonEncode({'identity': adminEmail, 'password': adminPassword}),
+    );
+    if (res.statusCode != 200) {
+      throw PocketBaseException(
+        'PocketBase admin auth failed: HTTP ${res.statusCode} ${res.body}',
+      );
+    }
+    final body = jsonDecode(res.body) as Map<String, dynamic>;
+    _token = body['token'] as String? ?? '';
+    if (_token.isEmpty) {
+      throw PocketBaseException(
+        'PocketBase admin auth returned no token. Is the admins collection '
+        'set up? Run `flutter_ota_kit serve` once to install the schema.',
+      );
+    }
+    return this;
+  }
+
+  String? _adminEmail;
+  String? _adminPassword;
+  Future<void>? _authInFlight;
+
+  Map<String, String> get _authHeaders => {
+    'content-type': 'application/json',
+    'authorization': _token,
+  };
+
+  Future<void> _ensureAuth() {
+    if (_token.isNotEmpty) return Future.value();
+    if (_adminEmail == null || _adminPassword == null) {
+      throw PocketBaseException(
+        'PocketBase client has no credentials. Call adminCredentials() first.',
+      );
+    }
+    _authInFlight ??= authenticate(_adminEmail!, _adminPassword!);
+    return _authInFlight!;
+  }
+
+  Future<http.Response> _get(Uri uri) async {
+    await _ensureAuth();
+    return _http.get(uri, headers: _authHeaders);
+  }
+
+  Future<http.Response> _post(Uri uri, {Object? body}) async {
+    await _ensureAuth();
+    return _http.post(
+      uri,
+      headers: _authHeaders,
+      body: body == null ? null : jsonEncode(body),
+    );
+  }
+
+  Future<http.Response> _patch(Uri uri, {Object? body}) async {
+    await _ensureAuth();
+    return _http.patch(
+      uri,
+      headers: _authHeaders,
+      body: body == null ? null : jsonEncode(body),
+    );
+  }
+
+  Future<http.Response> _delete(Uri uri) async {
+    await _ensureAuth();
+    return _http.delete(uri, headers: _authHeaders);
+  }
+
+  // ----- Records -----
+
+  /// List records from a collection with optional filter, sort, and page.
+  Future<PocketBaseList<T>> listRecords<T>(
+    String collection,
+    T Function(Map<String, dynamic>) fromJson, {
+    String? filter,
+    String? sort,
+    int page = 1,
+    int perPage = 50,
+  }) async {
+    final qp = <String, String>{
+      'page': page.toString(),
+      'perPage': perPage.toString(),
+    };
+    if (filter != null && filter.isNotEmpty) qp['filter'] = filter;
+    if (sort != null && sort.isNotEmpty) qp['sort'] = sort;
+    final uri = Uri.parse('$_baseUrl/api/collections/$collection/records')
+        .replace(queryParameters: qp);
+    final res = await _get(uri);
+    if (res.statusCode != 200) {
+      throw PocketBaseException(
+        'listRecords($collection) failed: HTTP ${res.statusCode} ${res.body}',
+      );
+    }
+    final body = jsonDecode(res.body) as Map<String, dynamic>;
+    final items = (body['items'] as List? ?? [])
+        .cast<Map<String, dynamic>>()
+        .map(fromJson)
+        .toList();
+    return PocketBaseList<T>(
+      items: items,
+      page: (body['page'] as num?)?.toInt() ?? page,
+      perPage: (body['perPage'] as num?)?.toInt() ?? perPage,
+      totalItems: (body['totalItems'] as num?)?.toInt() ?? items.length,
+      totalPages: (body['totalPages'] as num?)?.toInt() ?? 1,
+    );
+  }
+
+  /// Get a single record by ID.
+  Future<T?> getRecord<T>(
+    String collection,
+    String id,
+    T Function(Map<String, dynamic>) fromJson,
+  ) async {
+    final res = await _get(
+      Uri.parse('$_baseUrl/api/collections/$collection/records/$id'),
+    );
+    if (res.statusCode == 404) return null;
+    if (res.statusCode != 200) {
+      throw PocketBaseException(
+        'getRecord($collection/$id) failed: HTTP ${res.statusCode} ${res.body}',
+      );
+    }
+    return fromJson(jsonDecode(res.body) as Map<String, dynamic>);
+  }
+
+  /// Create a new record.
+  Future<T> createRecord<T>(
+    String collection,
+    Map<String, dynamic> body,
+    T Function(Map<String, dynamic>) fromJson,
+  ) async {
+    final res = await _post(
+      Uri.parse('$_baseUrl/api/collections/$collection/records'),
+      body: body,
+    );
+    if (res.statusCode != 200 && res.statusCode != 201) {
+      throw PocketBaseException(
+        'createRecord($collection) failed: HTTP ${res.statusCode} ${res.body}',
+      );
+    }
+    return fromJson(jsonDecode(res.body) as Map<String, dynamic>);
+  }
+
+  /// Update an existing record.
+  Future<T> updateRecord<T>(
+    String collection,
+    String id,
+    Map<String, dynamic> body,
+    T Function(Map<String, dynamic>) fromJson,
+  ) async {
+    final res = await _patch(
+      Uri.parse('$_baseUrl/api/collections/$collection/records/$id'),
+      body: body,
+    );
+    if (res.statusCode != 200) {
+      throw PocketBaseException(
+        'updateRecord($collection/$id) failed: HTTP ${res.statusCode} ${res.body}',
+      );
+    }
+    return fromJson(jsonDecode(res.body) as Map<String, dynamic>);
+  }
+
+  /// Delete a record.
+  Future<void> deleteRecord(String collection, String id) async {
+    final res = await _delete(
+      Uri.parse('$_baseUrl/api/collections/$collection/records/$id'),
+    );
+    if (res.statusCode != 204) {
+      throw PocketBaseException(
+        'deleteRecord($collection/$id) failed: HTTP ${res.statusCode} ${res.body}',
+      );
+    }
+  }
+
+  // ----- Files -----
+
+  /// Upload a file to a record's file field (multipart/form-data).
+  Future<T> uploadFile<T>(
+    String collection,
+    String recordId,
+    String fieldName,
+    String filename,
+    List<int> bytes, {
+    Map<String, String>? extraFields,
+    required T Function(Map<String, dynamic>) fromJson,
+  }) async {
+    await _ensureAuth();
+    final req = http.MultipartRequest(
+      'PATCH',
+      Uri.parse(
+        '$_baseUrl/api/collections/$collection/records/$recordId/$fieldName',
+      ),
+    );
+    req.headers['authorization'] = _token;
+    if (extraFields != null) req.fields.addAll(extraFields);
+    req.files.add(
+      http.MultipartFile.fromBytes(fieldName, bytes, filename: filename),
+    );
+    final streamed = await req.send();
+    final res = await http.Response.fromStream(streamed);
+    if (res.statusCode != 200) {
+      throw PocketBaseException(
+        'uploadFile($collection/$recordId) failed: HTTP ${res.statusCode} ${res.body}',
+      );
+    }
+    return fromJson(jsonDecode(res.body) as Map<String, dynamic>);
+  }
+
+  /// Get a download token for a record's file field.
+  Future<String> getFileToken(String recordId, String filename) async {
+    final res = await _post(Uri.parse('$_baseUrl/api/files/token'));
+    if (res.statusCode != 200) {
+      throw PocketBaseException(
+        'getFileToken failed: HTTP ${res.statusCode} ${res.body}',
+      );
+    }
+    final body = jsonDecode(res.body) as Map<String, dynamic>;
+    return body['token'] as String? ?? '';
+  }
+
+  /// Build a public download URL for a record's file field.
+  String fileUrl(
+    String collection,
+    String recordId,
+    String filename, [
+    String? token,
+  ]) {
+    final t = token == null ? '' : '?token=$token';
+    return '$_baseUrl/api/files/$collection/$recordId/$filename$t';
+  }
+
+  /// Download a file by URL (returns bytes).
+  Future<List<int>> downloadFile(String url) async {
+    final res = await _http.get(Uri.parse(url));
+    if (res.statusCode != 200) {
+      throw PocketBaseException(
+        'downloadFile($url) failed: HTTP ${res.statusCode}',
+      );
+    }
+    return res.bodyBytes;
+  }
+
+  /// Check if a record exists in a collection.
+  Future<bool> recordExists(String collection, String id) async {
+    final res = await _get(
+      Uri.parse('$_baseUrl/api/collections/$collection/records/$id'),
+    );
+    return res.statusCode == 200;
+  }
+
+  /// Health check (PB exposes /api/health).
+  Future<bool> health() async {
+    try {
+      final res = await _http.get(Uri.parse('$_baseUrl/api/health'));
+      return res.statusCode == 200;
+    } catch (_) {
+      return false;
+    }
+  }
+
+  void close() => _http.close();
+}
+
+/// Paginated list response from PocketBase.
+class PocketBaseList<T> {
+  const PocketBaseList({
+    required this.items,
+    required this.page,
+    required this.perPage,
+    required this.totalItems,
+    required this.totalPages,
+  });
+
+  final List<T> items;
+  final int page;
+  final int perPage;
+  final int totalItems;
+  final int totalPages;
+}
+
+/// Exception thrown by [PocketBaseClient] for any non-2xx response.
+class PocketBaseException implements Exception {
+  const PocketBaseException(this.message);
+  final String message;
+  @override
+  String toString() => 'PocketBaseException: $message';
+}

package/dart-src/plugins/pocketbase/lib/src/pocketbase_config.dart

@@ -0,0 +1,61 @@
+/// Configuration for the PocketBase backend plugin.
+library;
+
+import 'pocketbase_client.dart';
+
+/// Configuration for the PocketBase database plugin.
+///
+/// This is a standalone config (does not import flutter_ota_kit_cli) so the
+/// plugin can be reused in any Dart application. The CLI's `resolvePocketBaseConfig`
+/// helper in `cli-tools` converts a `FlutterPatcherConfig` + env vars into this.
+class PocketBaseConfig {
+  const PocketBaseConfig({
+    required this.url,
+    required this.adminEmail,
+    required this.adminPassword,
+    this.bundlesCollection = 'bundles',
+    this.channelsCollection = 'channels',
+    this.bundlesBucket = 'bundles',
+    this.clientFactory,
+  });
+
+  /// Base URL of the PocketBase instance, e.g. `http://localhost:8090`.
+  final String url;
+
+  /// Admin email (used to mint auth tokens for backend operations).
+  final String adminEmail;
+
+  /// Admin password.
+  final String adminPassword;
+
+  /// Name of the PB collection that stores bundle records.
+  final String bundlesCollection;
+
+  /// Name of the PB collection that stores channels.
+  final String channelsCollection;
+
+  /// Name of the PB file storage bucket for bundle artifacts.
+  final String bundlesBucket;
+
+  /// Optional test seam: a factory that builds the [PocketBaseClient] used by
+  /// the plugin. When omitted, a default HTTP-backed client is created.
+  final PocketBaseClientFactory? clientFactory;
+
+  PocketBaseConfig copyWith({
+    String? url,
+    String? adminEmail,
+    String? adminPassword,
+    String? bundlesCollection,
+    String? channelsCollection,
+    String? bundlesBucket,
+    PocketBaseClientFactory? clientFactory,
+  }) => PocketBaseConfig(
+    url: url ?? this.url,
+    adminEmail: adminEmail ?? this.adminEmail,
+    adminPassword: adminPassword ?? this.adminPassword,
+    bundlesCollection: bundlesCollection ?? this.bundlesCollection,
+    channelsCollection: channelsCollection ?? this.channelsCollection,
+    bundlesBucket: bundlesBucket ?? this.bundlesBucket,
+    clientFactory: clientFactory ?? this.clientFactory,
+  );
+}

package/dart-src/plugins/pocketbase/lib/src/pocketbase_database.dart

@@ -0,0 +1,278 @@
+/// PocketBase-backed [DatabasePlugin] implementation.
+library;
+
+import 'package:flutter_ota_kit_core/flutter_ota_kit_core.dart';
+import 'package:flutter_ota_kit_plugin_core/flutter_ota_kit_plugin_core.dart';
+
+import 'pocketbase_bundle_mapper.dart';
+import 'pocketbase_client.dart';
+import 'pocketbase_config.dart';
+
+/// Configuration for the PocketBase database plugin.
+typedef PocketBaseDatabaseConfig = PocketBaseConfig;
+
+/// PocketBase-backed [AbstractDatabasePlugin] implementation.
+class _PocketBaseDatabase implements AbstractDatabasePlugin {
+  _PocketBaseDatabase(this.config, this.client);
+
+  final PocketBaseConfig config;
+  final PocketBaseClient client;
+
+  static _PocketBaseDatabase build(PocketBaseConfig config) {
+    final client = config.clientFactory != null
+        ? config.clientFactory!(
+            config.url,
+            config.adminEmail,
+            config.adminPassword,
+          )
+        : PocketBaseClient(config.url);
+    client.adminCredentials(config.adminEmail, config.adminPassword);
+    return _PocketBaseDatabase(config, client);
+  }
+
+  @override
+  bool get supportsCursorPagination => false;
+
+  // ----- Channels -----
+
+  @override
+  Future<List<String>> getChannels() async {
+    final res = await client.listRecords<dynamic>(
+      config.channelsCollection,
+      (j) => j,
+      perPage: 200,
+      sort: 'name',
+    );
+    return res.items
+        .map((j) => (j as Map)['name'] as String? ?? '')
+        .where((s) => s.isNotEmpty)
+        .toList();
+  }
+
+  // ----- Single bundle -----
+
+  @override
+  Future<Bundle?> getBundleById(String bundleId) async {
+    final row = await client.getRecord<PocketBaseBundleRow>(
+      config.bundlesCollection,
+      bundleId,
+      PocketBaseBundleRow.fromJson,
+    );
+    return row == null ? null : mapRowToBundle(row);
+  }
+
+  @override
+  Future<UpdateInfo?> getUpdateInfo(GetBundlesArgs args) async {
+    final filter = _buildFilter(
+      channel: args.channel,
+      platform: args.platform,
+      enabled: true,
+    );
+    final list = await client.listRecords<PocketBaseBundleRow>(
+      config.bundlesCollection,
+      PocketBaseBundleRow.fromJson,
+      filter: filter.isEmpty ? null : filter,
+      sort: '-created',
+      perPage: 1,
+    );
+    if (list.items.isEmpty) return null;
+    final bundle = mapRowToBundle(list.items.first);
+    return UpdateInfo(
+      id: bundle.id,
+      shouldForceUpdate: bundle.shouldForceUpdate,
+      message: bundle.message,
+      status: UpdateStatus.update,
+      storageUri: bundle.storageUri,
+      fileHash: bundle.fileHash,
+    );
+  }
+
+  // ----- Query bundles -----
+
+  @override
+  Future<Paginated<List<Bundle>>> getBundles(
+    DatabaseBundleQueryOptions options,
+  ) async {
+    final where = options.where;
+    final filter = _buildFilter(
+      channel: where?.channel,
+      platform: where?.platform,
+      enabled: where?.enabled,
+      idEq: where?.id?.eq,
+      idGt: where?.id?.gt,
+      idLt: where?.id?.lt,
+      targetAppVersion: where?.targetAppVersion,
+      fingerprintHash: where?.fingerprintHash,
+    );
+    final orderField = options.orderBy?.field ?? 'id';
+    final desc = options.orderBy?.direction != 'asc';
+    // PB sort syntax: `field` for asc, `-field` for desc.
+    final sort = (desc ? '-' : '') + orderField;
+    final limit = options.limit == 0 ? 50 : options.limit;
+    final page = (options.offset ?? 0) ~/ limit + 1;
+    final list = await client.listRecords<PocketBaseBundleRow>(
+      config.bundlesCollection,
+      PocketBaseBundleRow.fromJson,
+      filter: filter.isEmpty ? null : filter,
+      sort: sort,
+      page: page,
+      perPage: limit,
+    );
+    final total = list.totalItems;
+    final totalPages = list.totalPages == 0 ? 1 : list.totalPages;
+    final currentPage = list.page;
+    final hasNextPage = currentPage < totalPages;
+    final hasPreviousPage = currentPage > 1;
+    return Paginated(
+      data: list.items.map(mapRowToBundle).toList(),
+      pagination: PaginationInfo(
+        total: total,
+        hasNextPage: hasNextPage,
+        hasPreviousPage: hasPreviousPage,
+        currentPage: currentPage,
+        totalPages: totalPages,
+        nextCursor: list.items.isNotEmpty && hasNextPage
+            ? list.items.last.id
+            : null,
+        previousCursor: list.items.isNotEmpty && hasPreviousPage
+            ? list.items.first.id
+            : null,
+      ),
+    );
+  }
+
+  // ----- Mutations (UnitOfWork) -----
+
+  @override
+  Future<void> commitBundle({required List<BundleChange> changedSets}) async {
+    for (final change in changedSets) {
+      switch (change.operation) {
+        case BundleChangeOperation.insert:
+          final row = _rowFromBundle(change.data);
+          final exists = await client.recordExists(
+            config.bundlesCollection,
+            change.data.id,
+          );
+          if (exists) {
+            // The storage plugin may have pre-created the record (to host
+            // the artifact file). Update the metadata fields rather than
+            // failing on a duplicate id.
+            await client.updateRecord<dynamic>(
+              config.bundlesCollection,
+              change.data.id,
+              row.toCreateJson(),
+              (j) => j,
+            );
+          } else {
+            await client.createRecord<dynamic>(
+              config.bundlesCollection,
+              row.toCreateJson(),
+              (j) => j,
+            );
+          }
+          break;
+        case BundleChangeOperation.update:
+          final patch = _buildUpdatePatch(change.data);
+          if (patch.isEmpty) continue;
+          await client.updateRecord<dynamic>(
+            config.bundlesCollection,
+            change.data.id,
+            patch,
+            (j) => j,
+          );
+          break;
+        case BundleChangeOperation.delete:
+          await client.deleteRecord(config.bundlesCollection, change.data.id);
+          break;
+      }
+    }
+  }
+
+  @override
+  Future<void> onUnmount() async {
+    client.close();
+  }
+
+  // ----- Helpers -----
+
+  PocketBaseBundleRow _rowFromBundle(Bundle v) => PocketBaseBundleRow(
+    id: v.id,
+    channel: v.channel,
+    enabled: v.enabled,
+    platform: v.platform.value,
+    shouldForceUpdate: v.shouldForceUpdate,
+    fileHash: v.fileHash,
+    storageUri: v.storageUri,
+    rolloutCohortCount: v.rolloutCohortCount ?? 1000,
+    gitCommitHash: v.gitCommitHash,
+    message: v.message,
+    fingerprintHash: v.fingerprintHash,
+    targetAppVersion: v.targetAppVersion,
+    manifestStorageUri: v.manifestStorageUri,
+    manifestFileHash: v.manifestFileHash,
+    assetBaseStorageUri: v.assetBaseStorageUri,
+    targetCohorts: v.targetCohorts,
+    metadata: v.metadata?.toJson(),
+  );
+
+  String _buildFilter({
+    String? channel,
+    Platform? platform,
+    bool? enabled,
+    String? idEq,
+    String? idGt,
+    String? idLt,
+    String? targetAppVersion,
+    String? fingerprintHash,
+  }) {
+    final clauses = <String>[];
+    if (channel != null && channel.isNotEmpty) {
+      clauses.add('channel = "${_escape(channel)}"');
+    }
+    if (platform != null) {
+      clauses.add('platform = "${_escape(platform.value)}"');
+    }
+    if (enabled != null) {
+      clauses.add('enabled = ${enabled ? 'true' : 'false'}');
+    }
+    if (idEq != null) clauses.add('id = "${_escape(idEq)}"');
+    if (idGt != null) clauses.add('id > "${_escape(idGt)}"');
+    if (idLt != null) clauses.add('id < "${_escape(idLt)}"');
+    if (targetAppVersion != null) {
+      clauses.add('target_app_version = "${_escape(targetAppVersion)}"');
+    }
+    if (fingerprintHash != null) {
+      clauses.add('fingerprint_hash = "${_escape(fingerprintHash)}"');
+    }
+    return clauses.join(' && ');
+  }
+
+  String _escape(String s) => s.replaceAll(r'\', r'\\').replaceAll('"', r'\"');
+
+  Map<String, dynamic> _buildUpdatePatch(Bundle v) => {
+    if (v.channel.isNotEmpty) 'channel': v.channel,
+    'enabled': v.enabled,
+    'platform': v.platform.value,
+    'should_force_update': v.shouldForceUpdate,
+    'rollout_cohort_count': v.rolloutCohortCount ?? 1000,
+    'file_hash': v.fileHash,
+    'storage_uri': v.storageUri,
+    if (v.gitCommitHash != null) 'git_commit_hash': v.gitCommitHash,
+    if (v.message != null) 'message': v.message,
+    if (v.fingerprintHash != null) 'fingerprint_hash': v.fingerprintHash,
+    if (v.targetAppVersion != null) 'target_app_version': v.targetAppVersion,
+    if (v.manifestStorageUri != null)
+      'manifest_storage_uri': v.manifestStorageUri,
+    if (v.manifestFileHash != null) 'manifest_file_hash': v.manifestFileHash,
+    if (v.assetBaseStorageUri != null)
+      'asset_base_storage_uri': v.assetBaseStorageUri,
+    if (v.targetCohorts != null) 'target_cohorts': v.targetCohorts,
+    if (v.metadata != null) 'metadata': v.metadata!.toJson(),
+  };
+}
+
+/// Build a `pocketbaseDatabase` plugin factory.
+final pocketbaseDatabase = createDatabasePlugin<PocketBaseConfig>(
+  name: 'pocketbaseDatabase',
+  factory: _PocketBaseDatabase.build,
+);