Complete Push Notifications Integration Guide

# Add under dependencies: in pubspec.yaml
  firebase_messaging: ^15.0.0
  http: ^1.2.0
  web_socket_channel: ^2.4.0
  flutter_local_notifications: ^17.0.0
  shared_preferences: ^2.2.0

/// DNZ Notifications — Flutter SDK
/// ----------------------------------------
/// مكتبة Flutter لربط تطبيقك بمنصة DNZ:
///   * تسجيل الجهاز مع connectionId فريد
///   * فتح WebSocket في الخلفية لاستقبال الإشعارات حتى عند إغلاق التطبيق
///   * عرض إشعارات النظام محلياً عند وصول رسالة
///   * heartbeat تلقائي كل 30 ثانية
///
/// المتطلبات (في pubspec.yaml):
///   http, web_socket_channel, flutter_local_notifications,
///   flutter_background_service, shared_preferences
///
/// استخدام أساسي في main.dart:
///   await DNZNotifications.instance.initialize(
///     apiKey: 'dnz_live_...',
///     apiBase: 'https://dnzteam.online/notifications-api',
///   );
///   await DNZNotifications.instance.registerDevice(recipientId: userId);
///   await DNZNotifications.instance.startBackground();
///
/// المصدر الكامل مضمّن في الدليل:
///   https://dnzteam.online/push-notifications/docs/complete-guide (القسم 4)
library dnz_notifications;

import 'dart:async';
import 'dart:convert';
import 'dart:io' show Platform;
import 'dart:math';

import 'package:flutter_local_notifications/flutter_local_notifications.dart';
import 'package:http/http.dart' as http;
import 'package:shared_preferences/shared_preferences.dart';
import 'package:web_socket_channel/web_socket_channel.dart';

typedef DNZMessageHandler = void Function(Map<String, dynamic> message);

class DNZException implements Exception {
  final String message;
  final int? statusCode;
  DNZException(this.message, [this.statusCode]);
  @override
  String toString() => 'DNZException($statusCode): $message';
}

class DNZNotifications {
  DNZNotifications._();
  static final DNZNotifications instance = DNZNotifications._();

  late String _apiKey;
  late String _apiBase;
  String? _connectionId;
  WebSocketChannel? _channel;
  StreamSubscription? _wsSub;
  Timer? _heartbeat;
  bool _shouldReconnect = true;
  final List<DNZMessageHandler> _handlers = [];
  final FlutterLocalNotificationsPlugin _local = FlutterLocalNotificationsPlugin();

  bool _initialized = false;

  static const String _androidChannelId = 'dnz_channel_v3';
  // صوت إشعار النظام الافتراضي على أندرويد
  static const UriAndroidNotificationSound _defaultAndroidSound =
      UriAndroidNotificationSound('content://settings/system/notification_sound');

  Future<void> initialize({
    required String apiKey,
    required String apiBase,
  }) async {
    if (_initialized) return;
    if (apiKey.isEmpty) throw ArgumentError('apiKey مطلوب');
    _apiKey = apiKey;
    _apiBase = apiBase.endsWith('/')
        ? apiBase.substring(0, apiBase.length - 1)
        : apiBase;

    const androidInit = AndroidInitializationSettings('@mipmap/ic_launcher');
    const iosInit = DarwinInitializationSettings(
      requestAlertPermission: true,
      requestBadgePermission: true,
      requestSoundPermission: true,
    );
    await _local.initialize(
      const InitializationSettings(android: androidInit, iOS: iosInit),
    );

    final androidPlugin = _local.resolvePlatformSpecificImplementation<
        AndroidFlutterLocalNotificationsPlugin>();
    await androidPlugin?.createNotificationChannel(
      const AndroidNotificationChannel(
        _androidChannelId,
        'DNZ Notifications',
        description: 'إشعارات DNZ بصوت النظام الافتراضي',
        importance: Importance.high,
        playSound: true,
        enableVibration: true,
        sound: _defaultAndroidSound,
      ),
    );

    final prefs = await SharedPreferences.getInstance();
    _connectionId = prefs.getString('dnz_connection_id') ?? _generateConnectionId();
    await prefs.setString('dnz_connection_id', _connectionId!);
    _initialized = true;
  }

  String get connectionId => _connectionId ?? '';

  void onMessage(DNZMessageHandler handler) => _handlers.add(handler);

  String _generateConnectionId() {
    final rand = Random.secure();
    final bytes = List<int>.generate(16, (_) => rand.nextInt(256));
    return bytes.map((b) => b.toRadixString(16).padLeft(2, '0')).join();
  }

  /// [fcmToken] من FirebaseMessaging (أندرويد) — [apnsToken] من FirebaseMessaging أو APNs (آيفون).
  /// الموجّه الهجين يستخدمها عند إغلاق التطبيق بدون استهلاك بطارية إضافية.
  Future<Map<String, dynamic>> registerDevice({
    required String recipientId,
    String? fcmToken,
    String? apnsToken,
  }) async {
    _ensureInit();
    final platform = Platform.isIOS ? 'ios' : 'android';
    final body = <String, dynamic>{
      'recipientId': recipientId,
      'platform': platform,
      'deviceTransport': 'mobile_background',
      'connectionId': _connectionId,
    };
    if (fcmToken != null && fcmToken.isNotEmpty) body['nativeFcmToken'] = fcmToken;
    if (apnsToken != null && apnsToken.isNotEmpty) body['nativeApnsToken'] = apnsToken;
    final res = await http.post(
      Uri.parse('$_apiBase/v1/subscribers/register'),
      headers: _headers(),
      body: jsonEncode(body),
    );
    return _decode(res);
  }

  Future<void> startBackground() async {
    _ensureInit();
    _shouldReconnect = true;
    await _connectWs();
    _heartbeat?.cancel();
    _heartbeat = Timer.periodic(const Duration(seconds: 30), (_) => _sendHeartbeat());
  }

  Future<void> stopBackground() async {
    _shouldReconnect = false;
    _heartbeat?.cancel();
    _heartbeat = null;
    await _wsSub?.cancel();
    _wsSub = null;
    await _channel?.sink.close();
    _channel = null;
  }

  final Set<String> _seenMessageIds = {};

  Future<void> _connectWs() async {
    await _wsSub?.cancel();
    _wsSub = null;
    try {
      await _channel?.sink.close();
    } catch (_) {}
    _channel = null;

    final wsBase = _apiBase
        .replaceFirst('https://', 'wss://')
        .replaceFirst('http://', 'ws://');
    final url = Uri.parse(
      '$wsBase/v1/ws/background'
      '?connectionId=$_connectionId&apiKey=$_apiKey',
    );
    try {
      _channel = WebSocketChannel.connect(url);
      _wsSub = _channel!.stream.listen(
        _onWsData,
        onError: (_) => _scheduleReconnect(),
        onDone: _scheduleReconnect,
        cancelOnError: true,
      );
    } catch (_) {
      _scheduleReconnect();
    }
  }

  void _onWsData(dynamic data) {
    if (data is! String) return;
    try {
      final msg = jsonDecode(data) as Map<String, dynamic>;
      final msgId = msg['id']?.toString();
      if (msgId != null && msgId.isNotEmpty) {
        if (_seenMessageIds.contains(msgId)) return;
        _seenMessageIds.add(msgId);
        if (_seenMessageIds.length > 200) {
          _seenMessageIds.remove(_seenMessageIds.first);
        }
      }
      _showLocal(msg);
      for (final h in _handlers) {
        try { h(msg); } catch (_) {}
      }
    } catch (_) {}
  }

  void _scheduleReconnect() {
    _wsSub = null;
    _channel = null;
    if (!_shouldReconnect) return;
    Future.delayed(const Duration(seconds: 3), _connectWs);
  }

  Future<void> _sendHeartbeat() async {
    try {
      await http.post(
        Uri.parse('$_apiBase/v1/devices/heartbeat'),
        headers: _headers(),
        body: jsonEncode({'connectionId': _connectionId}),
      );
    } catch (_) {}
  }

  Future<void> _showLocal(Map<String, dynamic> msg) async {
    const channel = AndroidNotificationDetails(
      _androidChannelId,
      'DNZ Notifications',
      channelDescription: 'إشعارات DNZ بصوت النظام الافتراضي',
      importance: Importance.high,
      priority: Priority.high,
      playSound: true,
      enableVibration: true,
      sound: _defaultAndroidSound,
    );
    const ios = DarwinNotificationDetails(
      presentAlert: true,
      presentBadge: true,
      presentSound: true,
    );
    await _local.show(
      DateTime.now().millisecondsSinceEpoch.remainder(1 << 31),
      msg['title']?.toString() ?? 'DNZ',
      msg['body']?.toString() ?? '',
      const NotificationDetails(android: channel, iOS: ios),
      payload: jsonEncode(msg['data'] ?? {}),
    );
  }

  Map<String, String> _headers() => {
        'Content-Type': 'application/json',
        'X-API-Key': _apiKey,
      };

  Future<Map<String, dynamic>> _decode(http.Response res) async {
    Map<String, dynamic> body = {};
    try { body = jsonDecode(res.body) as Map<String, dynamic>; } catch (_) {}
    if (res.statusCode >= 400) {
      throw DNZException(body['detail']?.toString() ?? 'HTTP ${res.statusCode}', res.statusCode);
    }
    return body;
  }

  void _ensureInit() {
    if (!_initialized) {
      throw StateError('DNZNotifications: استدعِ initialize() أولاً');
    }
  }
}

<!-- android/app/src/main/AndroidManifest.xml (before <application>) -->
<uses-permission android:name="android.permission.INTERNET" />
<uses-permission android:name="android.permission.WAKE_LOCK" />
<uses-permission android:name="android.permission.POST_NOTIFICATIONS" />

POST https://dnzteam.online/notifications-api/v1/subscribers/register
Headers:
  Content-Type: application/json
  X-API-Key: dnz_live_YOUR_KEY

Body:
{
  "recipientId": "user_12345",
  "platform": "android",
  "deviceTransport": "mobile_background",
  "connectionId": "unique-device-id-abc",
  "nativeFcmToken": "fcm-token-from-firebase-on-device"
}

POST https://dnzteam.online/notifications-api/v1/subscribers/register
Headers:
  Content-Type: application/json
  X-API-Key: dnz_live_YOUR_KEY

Body:
{
  "recipientId": "user_12345",
  "platform": "android",
  "deviceTransport": "mobile_background",
  "connectionId": "unique-device-id-abc",
  "nativeFcmToken": "fcm-token-from-firebase-on-device"
}

POST https://dnzteam.online/notifications-api/v1/subscribers/register
Headers:
  Content-Type: application/json
  X-API-Key: dnz_live_YOUR_KEY

Body:
{
  "recipientId": "user_12345",
  "platform": "ios",
  "deviceTransport": "mobile_background",
  "connectionId": "unique-device-id-abc",
  "nativeApnsToken": "apns-token-from-device"
}

POST https://dnzteam.online/notifications-api/v1/subscribers/register
Headers:
  Content-Type: application/json
  X-API-Key: dnz_live_YOUR_KEY

Body:
{
  "recipientId": "user_12345",
  "platform": "web",
  "deviceTransport": "web_push",
  "webPush": {
    "endpoint": "https://fcm.googleapis.com/fcm/send/...",
    "keys": {
      "p256dh": "BASE64_PUBLIC_KEY",
      "auth": "BASE64_AUTH_SECRET"
    }
  }
}

POST https://dnzteam.online/notifications-api/v1/send
Headers:
  Content-Type: application/json
  X-API-Key: dnz_live_YOUR_KEY

Body:
{
  "recipientId": "user_12345",
  "channel": "push",
  "title": "Hello",
  "body": "Your notification text",
  "androidChannelId": "vcenter_push_v1",
  "androidSound": "vcenter_notify",
  "data": {
    "orderId": "123"
  }
}