@kesha-antonov/react-native-background-downloader 4.0.0-alpha.0 → 4.0.2

package/CHANGELOG.md

@@ -0,0 +1,50 @@
+# Changelog
+
+## v4.0.0
+
+> 📖 **Upgrading from v3.x?** See the [Migration Guide](./MIGRATION.md) for detailed instructions.
+
+### ⚠️ Breaking Changes
+
+- **API Renamed:** `checkForExistingDownloads()` → `getExistingDownloadTasks()` - Now returns a Promise with better naming
+- **API Renamed:** `download()` → `createDownloadTask()` - Downloads now require explicit `.start()` call
+- **Download Tasks Start Explicitly:** Tasks created with `createDownloadTask()` are now in `PENDING` state and must call `.start()` to begin downloading
+- **New Config Option:** Added `progressMinBytes` to `setConfig()` - controls minimum bytes change before progress callback fires (default: 1MB)
+- **Source Structure Changed:** Code moved from `lib/` to `src/` directory with proper TypeScript types
+
+### ✨ New Features
+
+- **React Native New Architecture Support:** Full TurboModules support for both iOS and Android
+- **Expo Config Plugin:** Added automatic iOS native code integration for Expo projects via `app.plugin.js`
+- **Android Kotlin Migration:** All Java code converted to Kotlin
+- **`maxRedirects` Option:** Configure maximum redirects for Android downloads (resolves #15)
+- **`progressMinBytes` Option:** Hybrid progress reporting - callbacks fire based on time interval OR bytes downloaded
+- **Android 15+ Support:** Added support for 16KB memory page sizes
+- **Architecture Fallback:** Comprehensive x86/ARMv7 support with SharedPreferences fallback
+
+### 🐛 Bug Fixes
+
+- **iOS Pause/Resume:** Fixed pause and resume functionality on iOS
+- **RN 0.78+ Compatibility:** Fixed bridge checks with safe emitter checks
+- **New Architecture Events:** Fixed `downloadBegin` and `downloadProgress` events emission
+- **Android Background Downloads:** Fixed completed files not moving to destination
+- **Progress Callback Unknown Total:** Fixed progress callback not firing when total bytes unknown
+- **Android 12 MMKV Crash:** Added robust error handling
+- **`checkForExistingDownloads` TypeError:** Fixed TypeError on Android with architecture fallback
+- **Firebase Performance Compatibility:** Fixed `completeHandler` method compatibility on Android
+- **Slow Connection Handling:** Better handling of slow-responding URLs with timeouts
+- **Android OldArch Export:** Fixed module method export issue (#79)
+- **MMKV Compatibility:** Support for react-native-mmkv 4+ with mmkv-shared dependency
+
+### 📦 Dependencies & Infrastructure
+
+- **React Native:** Updated example app to RN 0.81.4
+- **TypeScript:** Full TypeScript types in `src/types.ts`
+- **iOS Native:** Converted from `.m` to `.mm` (Objective-C++)
+- **Package Manager:** Switched to yarn as preferred package manager
+
+### 📚 Documentation
+
+- Added documentation for `progressMinBytes` option
+- Updated README for React Native 0.77+ instructions
+- Improved Expo config plugin examples

package/README.md

@@ -1,16 +1,29 @@
-![react-native-background-downloader banner](https://d1w2zhnqcy4l8f.cloudfront.net/content/falcon/production/projects/V5EEOX_fast/RNBD-190702083358.png)
+
+<p align="center">
+  <img width="300" src="https://github.com/user-attachments/assets/25e89808-9eb7-42b2-8031-b48d8c24796c" />
+</p>
 
 [![npm version](https://badge.fury.io/js/@kesha-antonov%2Freact-native-background-downloader.svg)](https://badge.fury.io/js/@kesha-antonov%2Freact-native-background-downloader)
 
-## 🚧👷 Important notice
+## 🎉 Version 4.0.0 Released!
+
+**v4.0.0** is now available with full **React Native New Architecture (TurboModules)** support!
 
-There's currently WIP going on to make the library support New Architecture. If you have any issues, please report them. If you want to contribute, please do so.
+### What's New
+- ✅ Full TurboModules support for iOS and Android
+- ✅ Expo Config Plugin for automatic iOS setup
+- ✅ Android code converted to Kotlin
+- ✅ Full TypeScript support
+- ✅ New `progressMinBytes` option for hybrid progress reporting
+- ✅ `maxRedirects` option for Android
 
-The most stable version is `3.2.6`. If you want to use the latest version, please be aware that it's a work in progress.
+### Upgrading from v3.x?
+📖 See the [Migration Guide](./MIGRATION.md) for detailed upgrade instructions and breaking changes.
 
-Readme for that version: [3.2.6 readme](https://github.com/kesha-antonov/react-native-background-downloader/blob/8f4b8a844a2d7f00d1558f6ea65bac94c8dd6fc9/README.md)
+📋 See the [Changelog](./CHANGELOG.md) for the full list of changes.
 
-I'm working on making the library compatible with the New Architecture while keeping backward compatibility with the old one. I plan to use Nitro Modules so apps on the old architecture can also benefit from the performance improvements.
+### Looking for v3.2.6?
+If you need the previous stable version: [3.2.6 readme](https://github.com/kesha-antonov/react-native-background-downloader/blob/8f4b8a844a2d7f00d1558f6ea65bac94c8dd6fc9/README.md)
 
 # @kesha-antonov/react-native-background-downloader
 
@@ -51,15 +64,6 @@ Then:
 cd ios && pod install
 ```
 
-### New Architecture Support
-
-This library supports React Native's New Architecture (Fabric + TurboModules) starting from React Native 0.70+.
-
-#### Automatic Detection
-The library automatically detects whether the New Architecture is enabled in your app and uses the appropriate implementation:
-- **New Architecture**: Uses TurboModules for optimal performance
-- **Legacy Architecture**: Uses the traditional bridge implementation
-
 #### Manual Setup (Advanced)
 If you need to manually configure the package for New Architecture:
 

package/ios/RNBackgroundDownloader.mm

@@ -43,6 +43,8 @@ static CompletionHandler storedCompletionHandler;
     NSMutableDictionary<NSString *, NSDictionary *> *progressReports;
     NSMutableDictionary<NSString *, NSNumber *> *idToLastBytesMap;
     NSMutableSet<NSString *> *idsToPauseSet;
+    // Tracks tasks that have already been retried once after a decode error (-1015)
+    NSMutableSet<NSString *> *decodeErrorRetriedIds;
     float progressInterval;
     int64_t progressMinBytes;
     NSDate *lastProgressReportedAt;
@@ -56,16 +58,16 @@ RCT_EXPORT_MODULE();
 // Enable interop layer so NativeModules.RNBackgroundDownloader is available
 // This is required for NativeEventEmitter to work with TurboModules
 + (BOOL)requiresMainQueueSetup {
-    return YES;
+    return NO;
 }
 
 #pragma mark - Helper methods
 
 - (BOOL)canSendEvents {
-    // Always return YES - let RCTEventEmitter handle listener management
-    // The warning "Sending X with no listeners registered" is harmless
-    // and events will be properly received once JS listeners are set up
-    return YES;
+    // Only send events if JavaScript has fully loaded
+    // This prevents "Invariant Violation: Failed to call into JavaScript module method"
+    // errors that occur when native code tries to send events before the JS bridge is ready
+    return isJavascriptLoaded;
 }
 
 - (RNBGDTaskConfig *)configForTask:(NSURLSessionTask *)task {
@@ -124,6 +126,11 @@ RCT_EXPORT_MODULE();
     self = [super initWithDisabledObservation];
 #endif
     if (self) {
+#ifdef RCT_NEW_ARCH_ENABLED
+        // TurboModules are lazily initialized when JS first accesses them,
+        // so JavaScript is ready when init is called
+        isJavascriptLoaded = YES;
+#endif
         [MMKV initializeMMKV:nil];
         mmkv = [MMKV mmkvWithID:@"RNBackgroundDownloader"];
 
@@ -160,6 +167,7 @@ RCT_EXPORT_MODULE();
         int64_t progressMinBytesScope = [mmkv getInt64ForKey:PROGRESS_MIN_BYTES_KEY];
         progressMinBytes = progressMinBytesScope > 0 ? progressMinBytesScope : 0;
         lastProgressReportedAt = [[NSDate alloc] init];
+        decodeErrorRetriedIds = [[NSMutableSet alloc] init];
 
         [self registerBridgeListener];
     }
@@ -365,7 +373,7 @@ RCT_EXPORT_METHOD(download: (NSDictionary *) options) {
     }
 }
 
-- (void)pauseTask:(NSString *)identifier {
+- (void)pauseTaskInternal:(NSString *)identifier {
     DLog(identifier, @"[RNBackgroundDownloader] - [pauseTask]");
     @synchronized (sharedLock) {
         NSURLSessionDownloadTask *task = self->idToTaskMap[identifier];
@@ -389,13 +397,17 @@ RCT_EXPORT_METHOD(download: (NSDictionary *) options) {
     }
 }
 
-#ifndef RCT_NEW_ARCH_ENABLED
+#ifdef RCT_NEW_ARCH_ENABLED
+- (void)pauseTask:(NSString *)identifier {
+    [self pauseTaskInternal:identifier];
+}
+#else
 RCT_EXPORT_METHOD(pauseTask: (NSString *)id) {
-    [self pauseTask:id];
+    [self pauseTaskInternal:id];
 }
 #endif
 
-- (void)resumeTask:(NSString *)identifier {
+- (void)resumeTaskInternal:(NSString *)identifier {
     DLog(identifier, @"[RNBackgroundDownloader] - [resumeTask]");
     @synchronized (sharedLock) {
         [self lazyRegisterSession];
@@ -446,13 +458,17 @@ RCT_EXPORT_METHOD(pauseTask: (NSString *)id) {
     }
 }
 
-#ifndef RCT_NEW_ARCH_ENABLED
+#ifdef RCT_NEW_ARCH_ENABLED
+- (void)resumeTask:(NSString *)identifier {
+    [self resumeTaskInternal:identifier];
+}
+#else
 RCT_EXPORT_METHOD(resumeTask: (NSString *)id) {
-    [self resumeTask:id];
+    [self resumeTaskInternal:id];
 }
 #endif
 
-- (void)stopTask:(NSString *)identifier {
+- (void)stopTaskInternal:(NSString *)identifier {
     DLog(identifier, @"[RNBackgroundDownloader] - [stopTask]");
     @synchronized (sharedLock) {
         NSURLSessionDownloadTask *task = self->idToTaskMap[identifier];
@@ -465,9 +481,13 @@ RCT_EXPORT_METHOD(resumeTask: (NSString *)id) {
     }
 }
 
-#ifndef RCT_NEW_ARCH_ENABLED
+#ifdef RCT_NEW_ARCH_ENABLED
+- (void)stopTask:(NSString *)identifier {
+    [self stopTaskInternal:identifier];
+}
+#else
 RCT_EXPORT_METHOD(stopTask: (NSString *)id) {
-    [self stopTask:id];
+    [self stopTaskInternal:id];
 }
 #endif
 
@@ -818,6 +838,46 @@ RCT_EXPORT_METHOD(getExistingDownloadTasks: (RCTPromiseResolveBlock)resolve reje
             return;
         }
 
+        // Fallback: certain servers return -1015 (NSURLErrorCannotDecodeRawData) on resumed tasks.
+        // Instead of failing permanently, attempt ONE fresh retry without resume data.
+        if (error.code == NSURLErrorCannotDecodeRawData && ![decodeErrorRetriedIds containsObject:taskConfig.id]) {
+            [decodeErrorRetriedIds addObject:taskConfig.id];
+            DLog(taskConfig.id, @"[RNBackgroundDownloader] - [didCompleteWithError] attempting fresh retry after decode error");
+
+            // Build a fresh request replicating original headers
+            NSMutableURLRequest *request = [[NSMutableURLRequest alloc] initWithURL:[NSURL URLWithString:taskConfig.url]];
+            // Reapply original request headers if available (including our internal identifier header)
+            NSDictionary *originalHeaders = task.originalRequest.allHTTPHeaderFields;
+            if (originalHeaders != nil) {
+                for (NSString *headerKey in originalHeaders) {
+                    [request setValue:[originalHeaders valueForKey:headerKey] forHTTPHeaderField:headerKey];
+                }
+            }
+            [request setValue:taskConfig.id forHTTPHeaderField:@"configId"]; // ensure config id header
+
+            // Remove old mapping keyed by previous task identifier
+            [taskToConfigMap removeObjectForKey:@(task.taskIdentifier)];
+
+            NSURLSessionDownloadTask *newTask = [urlSession downloadTaskWithRequest:request];
+            if (newTask != nil) {
+                // Reset task state for fresh attempt
+                taskConfig.state = NSURLSessionTaskStateRunning;
+                taskConfig.errorCode = 0;
+                taskConfig.bytesDownloaded = 0;
+                taskConfig.bytesTotal = 0;
+                taskToConfigMap[@(newTask.taskIdentifier)] = taskConfig;
+                [mmkv setData:[self serialize: taskToConfigMap] forKey:ID_TO_CONFIG_MAP_KEY];
+                idToTaskMap[taskConfig.id] = newTask;
+                idToPercentMap[taskConfig.id] = @0.0;
+                idToLastBytesMap[taskConfig.id] = @0;
+                [newTask resume];
+                DLog(taskConfig.id, @"[RNBackgroundDownloader] - [didCompleteWithError] fresh retry started");
+                return; // Do not emit failure yet
+            } else {
+                DLog(taskConfig.id, @"[RNBackgroundDownloader] - [didCompleteWithError] fresh retry creation failed");
+            }
+        }
+
         // Handle failure
         if ([self canSendEvents]) {
 #ifdef RCT_NEW_ARCH_ENABLED

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kesha-antonov/react-native-background-downloader",
-  "version": "4.0.0-alpha.0",
+  "version": "4.0.2",
   "description": "A library for React-Native to help you download large files on iOS and Android both in the foreground and most importantly in the background.",
   "keywords": [
     "react-native",
@@ -83,9 +83,9 @@
     "@babel/preset-typescript": "^7.28.5",
     "@babel/runtime": "^7.28.4",
     "@expo/config-plugins": "^54.0.2",
-    "@react-native/babel-preset": "^0.81.4",
-    "@react-native/eslint-config": "^0.81.4",
-    "@react-native/metro-config": "^0.81.4",
+    "@react-native/babel-preset": "^0.81.5",
+    "@react-native/eslint-config": "^0.81.5",
+    "@react-native/metro-config": "^0.81.5",
     "@typescript-eslint/eslint-plugin": "^8.46.1",
     "@typescript-eslint/parser": "^8.46.1",
     "babel-jest": "^29.7.0",
@@ -105,7 +105,7 @@
     "lint-staged": ">=16",
     "metro-react-native-babel-preset": "^0.77.0",
     "react": "19.1.0",
-    "react-native": "0.81.4",
+    "react-native": "0.81.5",
     "react-native-fs": "^2.20.0",
     "react-native-vector-icons": "^10.3.0",
     "react-test-renderer": "19.2.0",

package/src/DownloadTask.ts

@@ -15,7 +15,7 @@ import {
   DownloadTaskState,
   Metadata,
 } from './types'
-import { config, log } from '.'
+import { config, log } from './config'
 import type { Spec } from './NativeRNBackgroundDownloader'
 
 // Try to get the native module using TurboModuleRegistry first (new architecture),

package/src/config.ts

@@ -0,0 +1,23 @@
+import { Headers } from './types'
+
+export const DEFAULT_PROGRESS_INTERVAL = 1000
+export const DEFAULT_PROGRESS_MIN_BYTES = 1024 * 1024 // 1MB
+
+interface ConfigState {
+  headers: Headers
+  progressInterval: number
+  progressMinBytes: number
+  isLogsEnabled: boolean
+}
+
+export const config: ConfigState = {
+  headers: {},
+  progressInterval: DEFAULT_PROGRESS_INTERVAL,
+  progressMinBytes: DEFAULT_PROGRESS_MIN_BYTES,
+  isLogsEnabled: false,
+}
+
+export const log = (...args: unknown[]): void => {
+  if (config.isLogsEnabled)
+    console.log('[RNBackgroundDownloader]', ...args)
+}

package/src/index.ts

@@ -1,9 +1,10 @@
-import { NativeModules, Platform, TurboModuleRegistry, DeviceEventEmitter } from 'react-native'
+import { NativeModules, Platform, TurboModuleRegistry, NativeEventEmitter, NativeModule } from 'react-native'
 import DownloadTask from './DownloadTask'
 import { Config, DownloadParams, Headers, TaskInfo, TaskInfoNative } from './types'
+import { config, log, DEFAULT_PROGRESS_INTERVAL, DEFAULT_PROGRESS_MIN_BYTES } from './config'
 import type { Spec } from './NativeRNBackgroundDownloader'
 
-type NativeModule = Spec & {
+type RNBackgroundDownloaderModule = Spec & {
   TaskRunning: number
   TaskSuspended: number
   TaskCanceling: number
@@ -11,61 +12,61 @@ type NativeModule = Spec & {
   documents: string
 }
 
-// Try to get the native module using TurboModuleRegistry first (new architecture),
-// then fall back to NativeModules (old architecture)
-let RNBackgroundDownloader: NativeModule
-
-// Try TurboModules first
-const turboModule = TurboModuleRegistry.get<Spec>('RNBackgroundDownloader')
-const isNewArchitecture = turboModule != null
-
-if (turboModule) {
-  // TurboModules use getConstants() method
-  const constants = turboModule.getConstants()
-  RNBackgroundDownloader = Object.assign(turboModule, constants) as NativeModule
-} else {
-  // Fall back to old architecture
-  RNBackgroundDownloader = NativeModules.RNBackgroundDownloader
-
-  // For old architecture, constants may need to be fetched via getConstants() as well
-  if (RNBackgroundDownloader && !RNBackgroundDownloader.documents && typeof RNBackgroundDownloader.getConstants === 'function') {
-    const constants = RNBackgroundDownloader.getConstants()
-    if (constants)
-      Object.assign(RNBackgroundDownloader, constants)
+// Lazy initialization state
+let RNBackgroundDownloader: RNBackgroundDownloaderModule & NativeModule
+let turboModule: Spec | null = null
+let isNewArchitecture = false
+let isInitialized = false
+
+/**
+ * Lazily initialize the native module.
+ * This is called on first actual use of the module, not at import time.
+ * This prevents issues with module loading before React Native's bridge is ready.
+ */
+function ensureNativeModuleInitialized (): RNBackgroundDownloaderModule & NativeModule {
+  if (isInitialized && RNBackgroundDownloader)
+    return RNBackgroundDownloader
+
+  // Try TurboModules first
+  turboModule = TurboModuleRegistry.get<Spec>('RNBackgroundDownloader')
+  // Check if the new architecture event emitters are available
+  // TurboModuleRegistry.get() can return a module even with old arch, but event emitters won't exist
+  isNewArchitecture = turboModule != null && typeof turboModule.onDownloadBegin === 'function'
+
+  if (isNewArchitecture && turboModule) {
+    // New architecture: TurboModules use getConstants() method
+    const constants = turboModule.getConstants()
+    RNBackgroundDownloader = Object.assign(turboModule, constants) as RNBackgroundDownloaderModule & NativeModule
+  } else {
+    // Fall back to old architecture - must use NativeModules for proper event emission
+    RNBackgroundDownloader = NativeModules.RNBackgroundDownloader
+
+    // For old architecture, constants may need to be fetched via getConstants() as well
+    if (RNBackgroundDownloader && !RNBackgroundDownloader.documents && typeof RNBackgroundDownloader.getConstants === 'function') {
+      const constants = RNBackgroundDownloader.getConstants()
+      if (constants)
+        Object.assign(RNBackgroundDownloader, constants)
+    }
   }
-}
 
-if (!RNBackgroundDownloader)
-  throw new Error(
-    'The package \'@kesha-antonov/react-native-background-downloader\' doesn\'t seem to be linked. Make sure: \n\n' +
-    Platform.select({ ios: '- You have run \'pod install\'\n', default: '' }) +
-    '- You rebuilt the app after installing the package\n' +
-    '- You are not using Expo Go\n'
-  )
+  if (!RNBackgroundDownloader)
+    throw new Error(
+      'The package \'@kesha-antonov/react-native-background-downloader\' doesn\'t seem to be linked. Make sure: \n\n' +
+      Platform.select({ ios: '- You have run \'pod install\'\n', default: '' }) +
+      '- You rebuilt the app after installing the package\n' +
+      '- You are not using Expo Go\n'
+    )
 
-const MIN_PROGRESS_INTERVAL = 250
-const DEFAULT_PROGRESS_INTERVAL = 1000
-const DEFAULT_PROGRESS_MIN_BYTES = 1024 * 1024 // 1MB
-const tasksMap = new Map<string, DownloadTask>()
+  isInitialized = true
 
-interface ConfigState {
-  headers: Headers
-  progressInterval: number
-  progressMinBytes: number
-  isLogsEnabled: boolean
-}
+  // Initialize event listeners after native module is ready
+  initializeEventListeners()
 
-export const config: ConfigState = {
-  headers: {},
-  progressInterval: DEFAULT_PROGRESS_INTERVAL,
-  progressMinBytes: DEFAULT_PROGRESS_MIN_BYTES,
-  isLogsEnabled: false,
+  return RNBackgroundDownloader
 }
 
-export const log = (...args: unknown[]): void => {
-  if (config.isLogsEnabled)
-    console.log('[RNBackgroundDownloader]', ...args)
-}
+const MIN_PROGRESS_INTERVAL = 250
+const tasksMap = new Map<string, DownloadTask>()
 
 interface DownloadBeginEvent {
   id: string
@@ -92,74 +93,89 @@ interface DownloadFailedEvent {
 }
 
 // Set up event listeners based on architecture
-if (isNewArchitecture && turboModule) {
-  // New architecture: use EventEmitter from TurboModule spec
-  turboModule.onDownloadBegin((data: DownloadBeginEvent) => {
-    const { id, ...rest } = data
-    log('downloadBegin', id, rest)
-    const task = tasksMap.get(id)
-    task?.onBegin(rest)
-  })
-
-  turboModule.onDownloadProgress((events: DownloadProgressEvent[]) => {
-    log('downloadProgress', events)
-    for (const event of events) {
-      const { id, ...rest } = event
+// For old architecture, we need to defer NativeEventEmitter creation
+// to avoid issues during module initialization
+let eventListenersInitialized = false
+
+function initializeEventListeners () {
+  if (eventListenersInitialized) return
+  eventListenersInitialized = true
+
+  if (isNewArchitecture && turboModule) {
+    // New architecture: use EventEmitter from TurboModule spec
+    turboModule.onDownloadBegin((data: DownloadBeginEvent) => {
+      const { id, ...rest } = data
+      log('downloadBegin', id, rest)
       const task = tasksMap.get(id)
-      task?.onProgress(rest)
-    }
-  })
-
-  turboModule.onDownloadComplete((data: DownloadCompleteEvent) => {
-    const { id, ...rest } = data
-    log('downloadComplete', id, rest)
-    const task = tasksMap.get(id)
-    task?.onDone(rest)
-    tasksMap.delete(id)
-  })
+      task?.onBegin(rest)
+    })
+
+    turboModule.onDownloadProgress((events: DownloadProgressEvent[]) => {
+      log('downloadProgress', events)
+      for (const event of events) {
+        const { id, ...rest } = event
+        const task = tasksMap.get(id)
+        task?.onProgress(rest)
+      }
+    })
 
-  turboModule.onDownloadFailed((data: DownloadFailedEvent) => {
-    const { id, ...rest } = data
-    log('downloadFailed', id, rest)
-    const task = tasksMap.get(id)
-    task?.onError(rest)
-    tasksMap.delete(id)
-  })
-} else {
-  // Old architecture: use DeviceEventEmitter
-  DeviceEventEmitter.addListener('downloadBegin', (data: DownloadBeginEvent) => {
-    const { id, ...rest } = data
-    log('downloadBegin', id, rest)
-    const task = tasksMap.get(id)
-    task?.onBegin(rest)
-  })
+    turboModule.onDownloadComplete((data: DownloadCompleteEvent) => {
+      const { id, ...rest } = data
+      log('downloadComplete', id, rest)
+      const task = tasksMap.get(id)
+      task?.onDone(rest)
+      tasksMap.delete(id)
+    })
 
-  DeviceEventEmitter.addListener('downloadProgress', (events: DownloadProgressEvent[]) => {
-    log('downloadProgress', events)
-    for (const event of events) {
-      const { id, ...rest } = event
+    turboModule.onDownloadFailed((data: DownloadFailedEvent) => {
+      const { id, ...rest } = data
+      log('downloadFailed', id, rest)
       const task = tasksMap.get(id)
-      task?.onProgress(rest)
-    }
-  })
+      task?.onError(rest)
+      tasksMap.delete(id)
+    })
+  } else {
+    // Old architecture: use NativeEventEmitter with the native module
+    // RCTEventEmitter on native side requires NativeEventEmitter on JS side
+    const eventEmitter = new NativeEventEmitter(RNBackgroundDownloader)
+
+    eventEmitter.addListener('downloadBegin', (data: DownloadBeginEvent) => {
+      const { id, ...rest } = data
+      log('downloadBegin', id, rest)
+      const task = tasksMap.get(id)
+      task?.onBegin(rest)
+    })
+
+    eventEmitter.addListener('downloadProgress', (events: DownloadProgressEvent[]) => {
+      log('downloadProgress', events)
+      for (const event of events) {
+        const { id, ...rest } = event
+        const task = tasksMap.get(id)
+        task?.onProgress(rest)
+      }
+    })
 
-  DeviceEventEmitter.addListener('downloadComplete', (data: DownloadCompleteEvent) => {
-    const { id, ...rest } = data
-    log('downloadComplete', id, rest)
-    const task = tasksMap.get(id)
-    task?.onDone(rest)
-    tasksMap.delete(id)
-  })
+    eventEmitter.addListener('downloadComplete', (data: DownloadCompleteEvent) => {
+      const { id, ...rest } = data
+      log('downloadComplete', id, rest)
+      const task = tasksMap.get(id)
+      task?.onDone(rest)
+      tasksMap.delete(id)
+    })
 
-  DeviceEventEmitter.addListener('downloadFailed', (data: DownloadFailedEvent) => {
-    const { id, ...rest } = data
-    log('downloadFailed', id, rest)
-    const task = tasksMap.get(id)
-    task?.onError(rest)
-    tasksMap.delete(id)
-  })
+    eventEmitter.addListener('downloadFailed', (data: DownloadFailedEvent) => {
+      const { id, ...rest } = data
+      log('downloadFailed', id, rest)
+      const task = tasksMap.get(id)
+      task?.onError(rest)
+      tasksMap.delete(id)
+    })
+  }
 }
 
+// Event listeners are now initialized lazily when ensureNativeModuleInitialized() is called
+// This ensures the bridge is ready before any native module access
+
 export function setConfig ({
   headers = {},
   progressInterval = DEFAULT_PROGRESS_INTERVAL,
@@ -182,7 +198,8 @@ export function setConfig ({
 }
 
 export const getExistingDownloadTasks = async (): Promise<DownloadTask[]> => {
-  const downloads = await RNBackgroundDownloader.getExistingDownloadTasks()
+  const nativeModule = ensureNativeModuleInitialized()
+  const downloads = await nativeModule.getExistingDownloadTasks()
   const downloadTasks: DownloadTask[] = downloads.map(downloadInfo => {
     // Parse metadata from JSON string to object
     let metadata = {}
@@ -202,15 +219,15 @@ export const getExistingDownloadTasks = async (): Promise<DownloadTask[]> => {
     const task = new DownloadTask(taskInfo, tasksMap.get(taskInfo.id))
 
     switch (taskInfo.state) {
-      case RNBackgroundDownloader.TaskRunning: {
+      case nativeModule.TaskRunning: {
         task.state = 'DOWNLOADING'
         break
       }
-      case RNBackgroundDownloader.TaskSuspended: {
+      case nativeModule.TaskSuspended: {
         task.state = 'PAUSED'
         break
       }
-      case RNBackgroundDownloader.TaskCanceling: {
+      case nativeModule.TaskCanceling: {
         // On iOS, paused tasks (via cancelByProducingResumeData) are in Canceling state with errorCode -999
         if (taskInfo.errorCode === -999) {
           task.state = 'PAUSED'
@@ -220,7 +237,7 @@ export const getExistingDownloadTasks = async (): Promise<DownloadTask[]> => {
         }
         break
       }
-      case RNBackgroundDownloader.TaskCompleted: {
+      case nativeModule.TaskCompleted: {
         if (taskInfo.bytesDownloaded === taskInfo.bytesTotal)
           task.state = 'DONE'
         else
@@ -254,7 +271,8 @@ export const completeHandler = (jobId: string) => {
     return
   }
 
-  return RNBackgroundDownloader.completeHandler(jobId)
+  const nativeModule = ensureNativeModuleInitialized()
+  return nativeModule.completeHandler(jobId)
 }
 
 export function createDownloadTask ({
@@ -263,6 +281,9 @@ export function createDownloadTask ({
   isNotificationVisible = false,
   ...rest
 }: TaskInfo & DownloadParams) {
+  // Ensure native module and event listeners are initialized before creating tasks
+  ensureNativeModuleInitialized()
+
   if (!rest.id || !rest.url || !rest.destination)
     throw new Error('[RNBackgroundDownloader] id, url and destination are required')
 
@@ -287,8 +308,11 @@ export function createDownloadTask ({
   return task
 }
 
+// Use getter to lazily initialize native module when directories are accessed
 export const directories = {
-  documents: RNBackgroundDownloader.documents,
+  get documents () {
+    return ensureNativeModuleInitialized().documents
+  },
 }
 
 export default {