Extract registration logic and improve API naming (#13)

Extract shared registration logic and rename methods for clarity

Author: mlaucis

README.md

@@ -153,38 +153,38 @@ MaterialApp(
 )
 ```
 
-### 3. Advanced: Delayed Permission Flow
+### 3. Advanced: Delayed Registration Flow
 
 For apps that need to ask for permission at a specific time (e.g., after user onboarding):
 
 ```dart
 void main() async {
   WidgetsFlutterBinding.ensureInitialized();
 
-  // Initialize without requesting permission
+  // Initialize without registering device
   await PntaFlutter.initialize(
     'prj_XXXXXXXXX',
-    requestPermission: false,  // Skip permission request
+    registerDevice: false,  // Skip device registration
   );
 
   runApp(MyApp());
 }
 
-// Later in your app, when ready to ask for permission:
+// Later in your app, when ready to register:
 Future<void> setupNotifications() async {
-  await PntaFlutter.requestPermission(
+  await PntaFlutter.registerDevice(
     metadata: {
       'user_id': '123',
       'user_email': 'user@example.com',
     },
   );
 
   // Optional: Get the device token if you need it for your backend
-  // final deviceToken = await PntaFlutter.requestPermission(...);
+  // final deviceToken = await PntaFlutter.registerDevice(...);
   // if (deviceToken != null) {
-  //   print('Permission granted and device registered!');
+  //   print('Device registered successfully!');
   // } else {
-  //   print('Permission denied or registration failed');
+  //   print('Registration failed');
   // }
 }
 ```
@@ -229,25 +229,25 @@ PntaFlutter.onNotificationTap.listen((payload) {
 
 ### Core Methods
 
-#### `PntaFlutter.initialize(String projectId, {Map<String, dynamic>? metadata, bool requestPermission, bool autoHandleLinks, bool showSystemUI})`
+#### `PntaFlutter.initialize(String projectId, {Map<String, dynamic>? metadata, bool registerDevice, bool autoHandleLinks, bool showSystemUI})`
 
 Main initialization method that handles everything for most apps:
 
 -   `projectId`: Your PNTA project ID (format: `prj_XXXXXXXXX`) from [app.pnta.io](https://app.pnta.io)
 -   `metadata`: Optional device metadata to include during registration
--   `requestPermission`: Whether to request permission and register device immediately (default: `true`)
+-   `registerDevice`: Whether to register device immediately (default: `true`)
 -   `autoHandleLinks`: Automatically handle `link_to` URLs when notifications are tapped (default: `true`)
 -   `showSystemUI`: Show system notification banner/sound when app is in foreground (default: `false`)
 
-Returns `Future<String?>` - the device token if permission was granted and device registered, null otherwise.
+Returns `Future<String?>` - the device token if device was registered, null otherwise.
 
-#### `PntaFlutter.requestPermission({Map<String, dynamic>? metadata})`
+#### `PntaFlutter.registerDevice({Map<String, dynamic>? metadata})`
 
-For delayed permission scenarios. Must be called after `initialize()` with `requestPermission: false`.
+For delayed registration scenarios. Requests notification permission and registers device. Must be called after `initialize()` with `registerDevice: false`.
 
--   `metadata`: Optional device metadata to include during registration (merged with metadata from initialize)
+-   `metadata`: Optional device metadata to include during registration
 
-Returns `Future<String?>` - the device token if permission was granted and device registered, null otherwise. **Note: You can ignore the return value if you don't need the token.**
+Returns `Future<String?>` - the device token if permission was granted and device registered successfully, null otherwise. **Note: You can ignore the return value if you don't need the token.**
 
 #### `PntaFlutter.updateMetadata(Map<String, dynamic> metadata)`
 

example/integration_test/plugin_integration_test.dart

@@ -20,7 +20,7 @@ void main() {
     try {
       await PntaFlutter.initialize(
         'prj_test123',
-        requestPermission: false, // Don't request permission in test
+        registerDevice: false, // Don't register device in test
         metadata: {'test': 'true'},
       );
       // If we get here without exception, initialization succeeded

lib/pnta_flutter.dart

@@ -2,33 +2,34 @@ import 'package:flutter/material.dart';
 import 'src/link_handler.dart';
 import 'pnta_flutter_platform_interface.dart';
 
-class PntaFlutterConfig {
+class _PntaFlutterConfig {
   final String projectId;
   final bool autoHandleLinks;
   final bool showSystemUI;
-  final bool requestPermission;
-  final Map<String, dynamic>? metadata;
+  final bool registerDevice;
+  Map<String, dynamic>? metadata;
 
-  PntaFlutterConfig({
+  _PntaFlutterConfig({
     required this.projectId,
     required this.autoHandleLinks,
     required this.showSystemUI,
-    required this.requestPermission,
+    required this.registerDevice,
     this.metadata,
   });
 }
 
 class PntaFlutter {
-  static PntaFlutterConfig? _config;
+  static _PntaFlutterConfig? _config;
   static String? _deviceToken;
   static final GlobalKey<NavigatorState> navigatorKey =
       GlobalKey<NavigatorState>();
 
+  // Setup
   /// Main initialization - handles everything for most apps
   static Future<String?> initialize(
     String projectId, {
     Map<String, dynamic>? metadata,
-    bool requestPermission = true,
+    bool registerDevice = true,
     bool autoHandleLinks = true,
     bool showSystemUI = false,
   }) async {
@@ -42,35 +43,20 @@ class PntaFlutter {
         debugPrint('PNTA: Invalid project ID. Must start with "prj_".');
         return null;
       }
-      _config = PntaFlutterConfig(
+      _config = _PntaFlutterConfig(
         projectId: projectId,
         autoHandleLinks: autoHandleLinks,
         showSystemUI: showSystemUI,
-        requestPermission: requestPermission,
+        registerDevice: registerDevice,
         metadata: metadata,
       );
       LinkHandler.initialize(autoHandleLinks: autoHandleLinks);
       await PntaFlutterPlatform.instance
           .setForegroundPresentationOptions(showSystemUI: showSystemUI);
-      if (requestPermission) {
-        final granted =
-            await PntaFlutterPlatform.instance.requestNotificationPermission();
-        if (!granted) {
-          debugPrint('PNTA: Notification permission denied.');
-          return null;
-        }
-        // Pure device registration with SDK version
-        _deviceToken = await PntaFlutterPlatform.instance.identify(projectId);
-
-        // Separately update metadata if provided
-        if (metadata != null && metadata.isNotEmpty) {
-          await PntaFlutterPlatform.instance
-              .updateMetadata(projectId, metadata);
-        }
-
-        return _deviceToken;
+      if (registerDevice) {
+        return await _performRegistration(metadata: metadata);
       } else {
-        // Delayed permission scenario
+        // Delayed registration scenario
         return null;
       }
     } catch (e, st) {
@@ -79,37 +65,18 @@ class PntaFlutter {
     }
   }
 
-  /// For delayed permission scenarios: requests permission, gets token, and registers device
-  static Future<String?> requestPermission(
+  // Registration
+  /// For delayed registration scenarios
+  static Future<String?> registerDevice(
       {Map<String, dynamic>? metadata}) async {
     if (_config == null) {
-      debugPrint('PNTA: Must call initialize() before requesting permission.');
-      return null;
-    }
-    try {
-      final granted =
-          await PntaFlutterPlatform.instance.requestNotificationPermission();
-      if (!granted) {
-        debugPrint('PNTA: Notification permission denied.');
-        return null;
-      }
-      // Pure device registration (SDK version is sent internally by identify)
-      _deviceToken =
-          await PntaFlutterPlatform.instance.identify(_config!.projectId);
-
-      // Update metadata if provided
-      if (metadata != null && metadata.isNotEmpty) {
-        await PntaFlutterPlatform.instance
-            .updateMetadata(_config!.projectId, metadata);
-      }
-      return _deviceToken;
-    } catch (e, st) {
-      debugPrint('PNTA: requestPermission error: $e\n$st');
+      debugPrint('PNTA: Must call initialize() before registering device.');
       return null;
     }
+    return await _performRegistration(metadata: metadata);
   }
 
-  /// Non-critical metadata updates
+  /// Update device metadata
   static Future<void> updateMetadata(Map<String, dynamic> metadata) async {
     if (_config == null) {
       debugPrint('PNTA: Must call initialize() before updating metadata.');
@@ -118,15 +85,18 @@ class PntaFlutter {
     try {
       await PntaFlutterPlatform.instance
           .updateMetadata(_config!.projectId, metadata);
+      _config!.metadata = metadata;
     } catch (e, st) {
       debugPrint('PNTA: updateMetadata error: $e\n$st');
     }
   }
 
-  /// Notification streams
+  // Notifications
+  /// Stream of notifications received while app is in foreground
   static Stream<Map<String, dynamic>> get foregroundNotifications =>
       PntaFlutterPlatform.instance.foregroundNotifications;
 
+  /// Stream of notification taps
   static Stream<Map<String, dynamic>> get onNotificationTap =>
       PntaFlutterPlatform.instance.onNotificationTap.asyncMap((payload) async {
         if (_config?.autoHandleLinks == true) {
@@ -135,15 +105,45 @@ class PntaFlutter {
         return payload;
       });
 
-  /// Manual link handling
+  // Utilities
+  /// Manually handle a deep link
   static Future<bool> handleLink(String? link) async {
     return await LinkHandler.handleLink(link);
   }
 
-  /// Configuration access
+  // Getters
   static String? get projectId => _config?.projectId;
   static bool get autoHandleLinks => _config?.autoHandleLinks ?? false;
   static bool get showSystemUI => _config?.showSystemUI ?? false;
   static Map<String, dynamic>? get currentMetadata => _config?.metadata;
   static String? get deviceToken => _deviceToken;
+
+  // Private
+  static Future<String?> _performRegistration(
+      {Map<String, dynamic>? metadata}) async {
+    try {
+      final granted =
+          await PntaFlutterPlatform.instance.requestNotificationPermission();
+      if (!granted) {
+        debugPrint('PNTA: Notification permission denied.');
+        return null;
+      }
+
+      // Pure device registration with SDK version
+      _deviceToken =
+          await PntaFlutterPlatform.instance.identify(_config!.projectId);
+
+      // Update metadata if provided
+      if (metadata != null && metadata.isNotEmpty) {
+        await PntaFlutterPlatform.instance
+            .updateMetadata(_config!.projectId, metadata);
+        _config!.metadata = metadata;
+      }
+
+      return _deviceToken;
+    } catch (e, st) {
+      debugPrint('PNTA: Registration error: $e\n$st');
+      return null;
+    }
+  }
 }