@_nazmiforreal/flutter-ota 0.1.12 → 0.1.14

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

@@ -0,0 +1,255 @@
+/// PocketBase-backed [StoragePlugin] implementation.
+///
+/// Uses PocketBase's built-in file storage (per-collection buckets) for
+/// bundle artifacts. Each bundle record carries a single `artifact` file
+/// field that stores the patch zip; the storage URI is a `pb://` URL that
+/// the runtime resolves to a signed download URL on the client.
+library;
+
+import 'dart:io';
+
+import 'package:flutter_ota_kit_plugin_core/flutter_ota_kit_plugin_core.dart';
+
+import 'pocketbase_client.dart';
+
+/// Configuration for the PocketBase storage plugin.
+class PocketBaseStorageConfig {
+  const PocketBaseStorageConfig({
+    required this.url,
+    required this.adminEmail,
+    required this.adminPassword,
+    required this.bundlesCollection,
+    this.bundlesBucket = 'bundles',
+    this.basePath,
+    this.clientFactory,
+  });
+
+  final String url;
+  final String adminEmail;
+  final String adminPassword;
+  final String bundlesCollection;
+  final String bundlesBucket;
+  final String? basePath;
+  final PocketBaseClientFactory? clientFactory;
+}
+
+/// Parse a `pb://bundles/{recordId}/{filename}` URI back into its parts.
+({String recordId, String filename, String? bucket})? parsePocketBaseStorageUri(
+  String storageUri,
+) {
+  // Accepts both `pb://{bucket}/{id}/{file}` and `pb:///{id}/{file}` (no
+  // bucket). The leading double-slash with an optional bucket prefix is
+  // matched explicitly.
+  final match = RegExp(r'^pb://(?:([^/]*)/)?([^/]+)/(.+)$')
+      .firstMatch(storageUri);
+  if (match == null) return null;
+  final bucket = match.group(1);
+  return (
+    recordId: match.group(2)!,
+    filename: match.group(3)!,
+    bucket: (bucket == null || bucket.isEmpty) ? null : bucket,
+  );
+}
+
+/// Stringify a PocketBase file storage URI.
+String buildPocketBaseStorageUri(
+  String recordId,
+  String filename, [
+  String? bucket,
+]) => 'pb://${bucket ?? ''}/${recordId}/$filename';
+
+/// PocketBase-backed [StoragePlugin].
+class _PocketBaseStorage implements StoragePlugin {
+  _PocketBaseStorage(this.config, this.client);
+
+  final PocketBaseStorageConfig config;
+  final PocketBaseClient client;
+
+  @override
+  String get name => 'pocketbaseStorage';
+
+  @override
+  String get supportedProtocol => 'pb:';
+
+  @override
+  StoragePluginProfiles get profiles => StoragePluginProfiles(
+    node: _PocketBaseNodeStorage(this),
+    runtime: _PocketBaseRuntimeStorage(this),
+  );
+}
+
+/// Runtime profile: URL-oriented operations used by the device SDK
+/// (resolve a signed download URL for a `pb://...` storage URI).
+class _PocketBaseRuntimeStorage implements RuntimeStorageProfile {
+  _PocketBaseRuntimeStorage(this.parent);
+
+  final _PocketBaseStorage parent;
+
+  PocketBaseClient get _client => parent.client;
+  PocketBaseStorageConfig get _config => parent.config;
+
+  @override
+  Future<Map<String, String>> getDownloadUrl(String storageUri) async {
+    final parsed = parsePocketBaseStorageUri(storageUri);
+    if (parsed == null) {
+      throw FormatException('Not a pb:// URI: $storageUri');
+    }
+    // PocketBase file downloads require a short-lived token when the
+    // collection's file rules restrict public reads. The server can mint one
+    // via `POST /api/files/token` with admin auth.
+    final token = await _client.getFileToken(parsed.recordId, parsed.filename);
+    final url = _client.fileUrl(
+      _config.bundlesCollection,
+      parsed.recordId,
+      parsed.filename,
+      token.isEmpty ? null : token,
+    );
+    return {'fileUrl': url, 'storageUri': storageUri};
+  }
+
+  @override
+  Future<String?> readText(String storageUri) async {
+    // PB serves binary files only; text reads aren't supported.
+    return null;
+  }
+}
+
+/// Node profile: filesystem-aware operations.
+class _PocketBaseNodeStorage implements NodeStorageProfile {
+  _PocketBaseNodeStorage(this.parent);
+
+  final _PocketBaseStorage parent;
+
+  PocketBaseClient get _client => parent.client;
+  PocketBaseStorageConfig get _config => parent.config;
+
+  String _keyToFilename(String key) =>
+      key.replaceAll('/', '_').replaceAll('\\', '_');
+
+  String _baseKey() {
+    final bp = _config.basePath;
+    return (bp == null || bp.isEmpty) ? '' : '$bp/';
+  }
+
+  String _fullKey(String key) => '${_baseKey()}$key';
+
+  @override
+  Future<Map<String, String>> upload(String key, String filePath) async {
+    final file = File(filePath);
+    if (!await file.exists()) {
+      throw FileSystemException('Artifact not found', filePath);
+    }
+    final bytes = await file.readAsBytes();
+    final filename = _keyToFilename(_fullKey(key));
+    // PocketBase file storage attaches files to records; use the storage key
+    // itself as the record id so callers can pass the bundle id (which the
+    // CLI already does) and find the file back via `exists()`.
+    final recordId = key;
+    final existing = await _client.recordExists(
+      _config.bundlesCollection,
+      recordId,
+    );
+    if (!existing) {
+      await _client.createRecord<dynamic>(_config.bundlesCollection, {
+        'id': recordId,
+        'channel': 'pending',
+        'platform': 'android',
+        'enabled': false,
+        'should_force_update': false,
+        'file_hash': '',
+        'storage_uri': '',
+        'rollout_cohort_count': 1000,
+      }, (j) => j);
+    }
+    await _client.uploadFile<dynamic>(
+      _config.bundlesCollection,
+      recordId,
+      'artifact',
+      filename,
+      bytes,
+      fromJson: (j) => j,
+    );
+    final uri = buildPocketBaseStorageUri(recordId, filename);
+    return {'key': _fullKey(key), 'storageUri': uri};
+  }
+
+  @override
+  Future<bool> exists(String storageUri) async {
+    final parsed = parsePocketBaseStorageUri(storageUri);
+    if (parsed == null) return false;
+    return _client.recordExists(_config.bundlesCollection, parsed.recordId);
+  }
+
+  @override
+  Future<void> delete(String storageUri) async {
+    final parsed = parsePocketBaseStorageUri(storageUri);
+    if (parsed == null) return;
+    await _client.deleteRecord(_config.bundlesCollection, parsed.recordId);
+  }
+
+  @override
+  Future<void> downloadFile(String storageUri, String filePath) async {
+    final parsed = parsePocketBaseStorageUri(storageUri);
+    if (parsed == null) {
+      throw FormatException('Not a pb:// URI: $storageUri');
+    }
+    final token = await _client.getFileToken(parsed.recordId, parsed.filename);
+    final url = _client.fileUrl(
+      _config.bundlesCollection,
+      parsed.recordId,
+      parsed.filename,
+      token.isEmpty ? null : token,
+    );
+    final bytes = await _client.downloadFile(url);
+    final out = File(filePath);
+    await out.parent.create(recursive: true);
+    await out.writeAsBytes(bytes);
+  }
+
+  @override
+  Future<List<StorageObject>> listObjects([String? prefix]) async {
+    final res = await _client.listRecords<dynamic>(
+      _config.bundlesCollection,
+      (j) => j,
+      perPage: 500,
+    );
+    final all = res.items.cast<Map>();
+    return all
+        .map((j) {
+          final id = j['id']?.toString() ?? '';
+          final filename = j['artifact']?.toString() ?? '';
+          if (filename.isEmpty) return null;
+          final key = filename.replaceFirst(_baseKey(), '');
+          if (prefix != null && prefix.isNotEmpty && !key.startsWith(prefix)) {
+            return null;
+          }
+          return StorageObject(
+            key: key,
+            storageUri: buildPocketBaseStorageUri(id, filename),
+            size: 0,
+          );
+        })
+        .whereType<StorageObject>()
+        .toList();
+  }
+
+  @override
+  Future<void> deleteObjects(List<String> keys) async {
+    for (final key in keys) {
+      await _client.deleteRecord(_config.bundlesCollection, key);
+    }
+  }
+}
+
+/// Build a `pocketbaseStorage` plugin.
+StoragePlugin pocketbaseStorage(PocketBaseStorageConfig config) {
+  final client = config.clientFactory != null
+      ? config.clientFactory!(
+          config.url,
+          config.adminEmail,
+          config.adminPassword,
+        )
+      : PocketBaseClient(config.url);
+  client.adminCredentials(config.adminEmail, config.adminPassword);
+  return _PocketBaseStorage(config, client);
+}

package/dart-src/plugins/pocketbase/pubspec.yaml

@@ -0,0 +1,26 @@
+name: flutter_ota_kit_pocketbase
+description: PocketBase plugin for flutter_ota_kit — local-first self-hostable backend with admin UI, auth, file storage, and realtime.
+version: 0.1.0
+homepage: https://github.com/HYPER12755/flutter-ota-kit
+repository: https://github.com/HYPER12755/flutter-ota-kit
+issue_tracker: https://github.com/HYPER12755/flutter-ota-kit/issues
+documentation: https://github.com/HYPER12755/flutter-ota-kit#readme
+license: MIT
+
+environment:
+  sdk: ">=3.13.2 <4.0.0"
+
+dependencies:
+  flutter_ota_kit_core: ^0.1.2
+  flutter_ota_kit_plugin_core: ^0.0.4
+  http: ^1.2.0
+
+dev_dependencies:
+  test: ^1.25.0
+  lints: ^4.0.0
+
+dependency_overrides:
+  flutter_ota_kit_core:
+    path: ../../packages/core
+  flutter_ota_kit_plugin_core:
+    path: ../plugin-core

package/dart-src/plugins/pocketbase/test/pb_uri_test.dart

@@ -0,0 +1,12 @@
+import 'package:flutter_ota_kit_pocketbase/flutter_ota_kit_pocketbase.dart';
+import 'package:test/test.dart';
+
+void main() {
+  test('buildPocketBaseStorageUri with no bucket parses back', () {
+    final uri = buildPocketBaseStorageUri('abc', 'file.zip');
+    final parsed = parsePocketBaseStorageUri(uri);
+    expect(parsed, isNotNull);
+    expect(parsed!.recordId, 'abc');
+    expect(parsed.filename, 'file.zip');
+  });
+}

package/dart-src/plugins/postgres/CHANGELOG.md

@@ -1,3 +1,19 @@
+## 0.1.3
+
+- Add dartdoc on internal API surfaces (10/10 pana dartdoc coverage).
+
+## 0.1.2
+
+- Add `PostgresBundleRow` + `mapRowToBundle` exports for writing custom server
+  tooling on top of `flutter_ota_kit_postgres`.
+- Repository moved to `https://github.com/HYPER12755/flutter-ota-kit`.
+
+## 0.1.1
+
+- Throw a clear `StateError` from `getDownloadUrl` when no `servingBaseUrl`
+  is configured (previously the URL silently failed).
+- Remove dead `IS NULL` filter paths in `_buildWhere`.
+
 ## 0.1.0
 
 - Initial release of `flutter_ota_kit_postgres` as part of the flutter_ota_kit OTA toolkit.

package/dart-src/plugins/postgres/example/lib/main.dart

@@ -0,0 +1,67 @@
+// flutter_ota_kit_postgres example
+//
+// `flutter_ota_kit_postgres` is a Postgres backend for `flutter_ota_kit`.
+// It provides a `postgresDatabase` factory and a `postgresStorage`
+// factory that talk to a vanilla Postgres database (no Supabase, no
+// Cloudflare — just `pg`).
+//
+// Most apps don't import this package directly; they wire it through
+// `flutter_ota_kit.configurePostgres(...)` in their app boot path. This
+// file shows the low-level config types in case you're writing a custom
+// server, a migration script, or a CLI extension.
+//
+// Run: `dart run example/main.dart`
+
+import 'package:flutter_ota_kit_postgres/flutter_ota_kit_postgres.dart';
+import 'package:flutter_ota_kit_core/flutter_ota_kit_core.dart';
+
+void main() {
+  // ── 1. Database config (vanilla Postgres connection). ─────────────
+  // `PostgresConfig` is a thin wrapper around the `postgres` package
+  // connection parameters. The `host`/`port`/`database` triple is the
+  // canonical form; username/password are required for non-trust auth.
+  const dbConfig = PostgresConfig(
+    host: 'db.example.com',
+    port: 5432,
+    database: 'ota',
+    username: 'ota',
+    password: 'secret',
+  );
+  print('Postgres: ${dbConfig.host}:${dbConfig.port}/${dbConfig.database}');
+
+  // ── 2. Storage config (for storing patch blobs). ──────────────────
+  // The `servingBaseUrl` is the public-facing URL that the device SDK
+  // can use to download patches. Omit it only if you proxy the
+  // download through your own update-check endpoint.
+  const storageConfig = PostgresStorageConfig(
+    db: dbConfig,
+    servingBaseUrl: 'https://cdn.example.com/flutter-ota',
+  );
+  print('Serving base URL: ${storageConfig.servingBaseUrl}');
+
+  // ── 3. Row-to-Bundle mapping (server-side helper). ────────────────
+  // Use this when reading bundles from a custom query and passing them
+  // to the SDK's `PatchInfo.fromJson`. The mapper handles both
+  // camelCase and snake_case column names.
+  const row = PostgresBundleRow(
+    id: '01a059a6-7d3c-4f3e-8a2c-9c2e3a4b5d6e',
+    channel: 'production',
+    enabled: true,
+    shouldForceUpdate: false,
+    fileHash: '7c4a8d09ca3762af61e59520943dc26494f8941b',
+    platform: Platform.android,
+    storageUri:
+        'postgres-blob://flutter-ota-bundles/'
+        '01a059a6/patch.zip',
+    targetAppVersion: '1.0.0',
+    rolloutCohortCount: 100,
+  );
+  final bundle = mapRowToBundle(row);
+  print('Mapped bundle: ${bundle.id} (${bundle.storageUri})');
+
+  // ── 4. Bundle → SQL values (for inserts/updates). ────────────────
+  // Returns snake_case column→value maps ready to feed to a `pg` query.
+  final values = bundleToRowValues(bundle);
+  print('SQL column count: ${values.length}');
+  print('  file_hash = ${values['file_hash']}');
+}

package/dart-src/plugins/postgres/lib/flutter_ota_kit_postgres.dart

@@ -3,15 +3,12 @@
 /// Faithful port of hot-updater `plugins/postgres`.
 library;
 
-export 'src/postgres_config.dart'
-    show PostgresConfig, PostgresClientFactory;
-export 'src/postgres_client.dart'
-    show PostgresClientLike, PostgresClient;
+export 'src/postgres_config.dart' show PostgresConfig, PostgresClientFactory;
+export 'src/postgres_client.dart' show PostgresClientLike, PostgresClient;
 export 'src/postgres_database.dart' show postgresDatabase;
 export 'src/postgres_storage.dart'
     show postgresStorage, PostgresStorageConfig, resolvePostgresStorageClient;
 export 'src/postgres_get_update_info.dart' show getUpdateInfo;
-export 'src/postgres_types.dart'
-    show PostgresBundleRow, PostgresBundlePatchRow;
+export 'src/postgres_types.dart' show PostgresBundleRow, PostgresBundlePatchRow;
 export 'src/postgres_bundle_mapper.dart'
     show mapRowToBundle, bundleToRowValues, bundleToPatchRows;

package/dart-src/plugins/postgres/lib/src/postgres_bundle_mapper.dart

@@ -2,8 +2,6 @@
 /// (the `mapRowToBundle` / `bundleToRowValues` / `bundleToPatchRows` helpers).
 library;
 
-import 'dart:convert';
-
 import 'package:flutter_ota_kit_core/flutter_ota_kit_core.dart'
     show
         Bundle,
@@ -16,36 +14,17 @@ import 'package:flutter_ota_kit_core/flutter_ota_kit_core.dart'
         getManifestStorageUri,
         stripBundleArtifactMetadata;
 
-import 'postgres_types.dart';
-
-/// Normalize metadata from various shapes to a plain map.
-Map<String, Object?>? _normalizeMetadata(Object? value) {
-  if (value == null) return null;
-
-  if (value is String) {
-    try {
-      final parsed = jsonDecode(value);
-      return _normalizeMetadata(parsed);
-    } catch (_) {
-      return null;
-    }
-  }
+import 'package:flutter_ota_kit_plugin_core/flutter_ota_kit_plugin_core.dart'
+    show buildBundlePatchId, normalizeMetadata;
 
-  if (value is Map) return value.cast<String, Object?>();
-
-  return null;
-}
-
-/// Build the compound primary key for a patch row.
-String _buildBundlePatchId(String bundleId, String baseBundleId) =>
-    '$bundleId:$baseBundleId';
+import 'postgres_types.dart';
 
 /// Map a Postgres bundle row + optional patch rows to a [Bundle].
 Bundle mapRowToBundle(
   PostgresBundleRow data, [
   List<PostgresBundlePatchRow> patchRows = const [],
 ]) {
-  final rawMetadata = _normalizeMetadata(data.metadata);
+  final rawMetadata = normalizeMetadata(data.metadata);
   final patches = patchRows.toList()
     ..sort((a, b) {
       final cmp = a.orderIndex.compareTo(b.orderIndex);
@@ -54,12 +33,14 @@ Bundle mapRowToBundle(
     });
 
   final patchArtifacts = patches
-      .map((p) => BundlePatchArtifact(
-            baseBundleId: p.baseBundleId,
-            baseFileHash: p.baseFileHash,
-            patchFileHash: p.patchFileHash,
-            patchStorageUri: p.patchStorageUri,
-          ))
+      .map(
+        (p) => BundlePatchArtifact(
+          baseBundleId: p.baseBundleId,
+          baseFileHash: p.baseFileHash,
+          patchFileHash: p.patchFileHash,
+          patchStorageUri: p.patchStorageUri,
+        ),
+      )
       .toList();
 
   final primaryPatch = patchArtifacts.isNotEmpty ? patchArtifacts.first : null;
@@ -76,8 +57,7 @@ Bundle mapRowToBundle(
     targetAppVersion: data.targetAppVersion,
     fingerprintHash: data.fingerprintHash,
     storageUri: data.storageUri,
-    metadata:
-        rawMetadata != null ? BundleMetadata.fromJson(rawMetadata) : null,
+    metadata: rawMetadata != null ? BundleMetadata.fromJson(rawMetadata) : null,
     manifestStorageUri: data.manifestStorageUri,
     manifestFileHash: data.manifestFileHash,
     assetBaseStorageUri: data.assetBaseStorageUri,
@@ -93,24 +73,24 @@ Bundle mapRowToBundle(
 
 /// Map a [Bundle] to a `bundles` row for insert/update (snake_case columns).
 Map<String, dynamic> bundleToRowValues(Bundle bundle) => {
-      'id': bundle.id,
-      'enabled': bundle.enabled,
-      'should_force_update': bundle.shouldForceUpdate,
-      'file_hash': bundle.fileHash,
-      'git_commit_hash': bundle.gitCommitHash,
-      'message': bundle.message,
-      'platform': bundle.platform.value,
-      'target_app_version': bundle.targetAppVersion,
-      'channel': bundle.channel,
-      'storage_uri': bundle.storageUri,
-      'fingerprint_hash': bundle.fingerprintHash,
-      'metadata': stripBundleArtifactMetadata(bundle.metadata?.toJson()) ?? {},
-      'manifest_storage_uri': getManifestStorageUri(bundle),
-      'manifest_file_hash': getManifestFileHash(bundle),
-      'asset_base_storage_uri': getAssetBaseStorageUri(bundle),
-      'rollout_cohort_count': bundle.rolloutCohortCount,
-      'target_cohorts': bundle.targetCohorts,
-    };
+  'id': bundle.id,
+  'enabled': bundle.enabled,
+  'should_force_update': bundle.shouldForceUpdate,
+  'file_hash': bundle.fileHash,
+  'git_commit_hash': bundle.gitCommitHash,
+  'message': bundle.message,
+  'platform': bundle.platform.value,
+  'target_app_version': bundle.targetAppVersion,
+  'channel': bundle.channel,
+  'storage_uri': bundle.storageUri,
+  'fingerprint_hash': bundle.fingerprintHash,
+  'metadata': stripBundleArtifactMetadata(bundle.metadata?.toJson()) ?? {},
+  'manifest_storage_uri': getManifestStorageUri(bundle),
+  'manifest_file_hash': getManifestFileHash(bundle),
+  'asset_base_storage_uri': getAssetBaseStorageUri(bundle),
+  'rollout_cohort_count': bundle.rolloutCohortCount,
+  'target_cohorts': bundle.targetCohorts,
+};
 
 /// Map a [Bundle] to its `bundle_patches` rows for insert.
 List<Map<String, dynamic>> bundleToPatchRows(Bundle bundle) {
@@ -118,7 +98,7 @@ List<Map<String, dynamic>> bundleToPatchRows(Bundle bundle) {
   return [
     for (var i = 0; i < patchArtifacts.length; i++)
       PostgresBundlePatchRow(
-        id: _buildBundlePatchId(bundle.id, patchArtifacts[i].baseBundleId),
+        id: buildBundlePatchId(bundle.id, patchArtifacts[i].baseBundleId),
         bundleId: bundle.id,
         baseBundleId: patchArtifacts[i].baseBundleId,
         baseFileHash: patchArtifacts[i].baseFileHash,

package/dart-src/plugins/postgres/lib/src/postgres_config.dart

@@ -32,4 +32,6 @@ class PostgresConfig {
 }
 
 /// Builds a [PostgresClientLike] from a [PostgresConfig].
-typedef PostgresClientFactory = PostgresClientLike Function(PostgresConfig config);
+typedef PostgresClientFactory = PostgresClientLike Function(
+  PostgresConfig config,
+);