@kesha-antonov/react-native-background-downloader 4.5.4 → 4.5.6

package/lib/types.d.ts

@@ -0,0 +1,249 @@
+export type UnsafeObject = {
+    [key: string]: string;
+};
+export type Headers = Record<string, string | null>;
+export type LogCallback = (tag: string, message: string, ...args: unknown[]) => void;
+/**
+ * Configuration for notification text with pluralization support.
+ * Use {count} placeholder for the number of downloads.
+ */
+export interface NotificationTexts {
+    /** Title for individual download notification (default: "Download") */
+    downloadTitle?: string;
+    /** Text shown when download is starting (default: "Starting download...") */
+    downloadStarting?: string;
+    /** Text pattern for download progress. Use {progress} for percentage (default: "Downloading... {progress}%") */
+    downloadProgress?: string;
+    /** Text shown when download is paused (default: "Paused") */
+    downloadPaused?: string;
+    /** Text shown when download is finished (default: "Download complete") */
+    downloadFinished?: string;
+    /** Title for group summary notification (default: "Downloads") */
+    groupTitle?: string;
+    /** Text pattern for group summary. Use {count} for number of downloads.
+     * Can be a string or function for pluralization (default: "{count} download(s) in progress") */
+    groupText?: string | ((count: number) => string);
+}
+/**
+ * Mode for notification display when grouping is enabled.
+ * - 'individual': Show all notifications (default, current behavior)
+ * - 'summaryOnly': Show only summary notification, minimize individual ones
+ */
+export type NotificationGroupingMode = 'individual' | 'summaryOnly';
+/**
+ * Configuration for notifications grouping.
+ */
+export interface NotificationsGroupingConfig {
+    /** Enable notification grouping (default: false) */
+    enabled: boolean;
+    /** Mode for notification display (default: 'individual') */
+    mode?: NotificationGroupingMode;
+    /** Custom notification texts with optional pluralization */
+    texts?: NotificationTexts;
+}
+/**
+ * iOS Data Protection level applied to the downloaded file (iOS only, ignored on Android).
+ *
+ * On iOS, files protected with `complete` become unreadable/unwritable while the device
+ * is locked, which can make a background download fail to save when it finishes on a
+ * locked device. The default `completeUntilFirstUserAuthentication` lets the file be
+ * written while locked (after the first unlock since boot), which is what you almost
+ * always want for background downloads.
+ *
+ * Maps to the NSFileProtection* constants.
+ */
+export type IosDataProtection = 'complete' | 'completeUnlessOpen' | 'completeUntilFirstUserAuthentication' | 'none';
+export interface Config {
+    headers?: Headers;
+    progressInterval?: number;
+    progressMinBytes?: number;
+    isLogsEnabled?: boolean;
+    logCallback?: LogCallback;
+    maxParallelDownloads?: number;
+    allowsCellularAccess?: boolean;
+    /** Show download notifications (Android only, default: false). When false, creates minimal silent notifications (UIDT requires a notification) */
+    showNotificationsEnabled?: boolean;
+    /** Configuration for notifications grouping on Android */
+    notificationsGrouping?: NotificationsGroupingConfig;
+    /**
+     * Default iOS Data Protection level for downloaded files (iOS only).
+     * Default: 'completeUntilFirstUserAuthentication'. Can be overridden per task.
+     */
+    iosDataProtection?: IosDataProtection;
+}
+export type SetConfig = (config: Partial<Config>) => void;
+export type BeginHandlerParams = {
+    expectedBytes: number;
+    headers: Headers;
+};
+export type BeginHandler = (params: BeginHandlerParams) => void;
+export type ProgressHandlerParams = {
+    bytesDownloaded: number;
+    bytesTotal: number;
+};
+export type ProgressHandler = (params: ProgressHandlerParams) => void;
+export type DoneHandlerParams = {
+    location: string;
+    bytesDownloaded: number;
+    bytesTotal: number;
+};
+export type DoneHandler = (params: DoneHandlerParams) => void;
+export interface ErrorHandlerParams {
+    error: string;
+    errorCode: number;
+}
+export type ErrorHandler = (params: ErrorHandlerParams) => void;
+export type Metadata = Record<string, unknown>;
+export interface TaskInfoNative {
+    id: string;
+    metadata: Metadata;
+    bytesDownloaded: number;
+    bytesTotal: number;
+    errorCode: number;
+    state: number;
+    destination?: string | null;
+}
+export interface TaskInfo {
+    id: string;
+    metadata?: object;
+}
+export type DownloadTaskState = 'PENDING' | 'DOWNLOADING' | 'PAUSED' | 'DONE' | 'FAILED' | 'STOPPED';
+export type DownloadParams = {
+    url: string;
+    destination: string;
+    headers?: Headers;
+    isAllowedOverRoaming?: boolean;
+    isAllowedOverMetered?: boolean;
+    maxRedirects?: number;
+    /** Group ID for notification grouping (only used when grouping is enabled) */
+    groupId?: string;
+    /** Group name displayed in notification (only used when grouping is enabled) */
+    groupName?: string;
+    /**
+     * iOS Data Protection level for this download's file (iOS only).
+     * Overrides the global `iosDataProtection` from setConfig.
+     */
+    iosDataProtection?: IosDataProtection;
+};
+export interface DownloadTask {
+    id: string;
+    state: DownloadTaskState;
+    metadata: Metadata;
+    errorCode: number;
+    bytesDownloaded: number;
+    bytesTotal: number;
+    downloadParams?: DownloadParams;
+    begin: (handler: BeginHandler) => DownloadTask;
+    progress: (handler: ProgressHandler) => DownloadTask;
+    done: (handler: DoneHandler) => DownloadTask;
+    error: (handler: ErrorHandler) => DownloadTask;
+    beginHandler?: BeginHandler;
+    progressHandler?: ProgressHandler;
+    doneHandler?: DoneHandler;
+    errorHandler?: ErrorHandler;
+    setDownloadParams: (params: DownloadParams) => void;
+    start: () => void;
+    pause: () => Promise<void>;
+    resume: () => Promise<void>;
+    stop: () => Promise<void>;
+    tryParseJson: (metadata?: string | Metadata) => Metadata | null;
+}
+export type getExistingDownloadTasks = () => Promise<DownloadTask[]>;
+export interface DownloadOption {
+    id: string;
+    url: string;
+    destination: string;
+    headers?: Headers | undefined;
+    metadata?: object;
+    isAllowedOverRoaming?: boolean;
+    isAllowedOverMetered?: boolean;
+}
+export type Download = (options: DownloadOption) => DownloadTask;
+export type CompleteHandler = (id: string) => void;
+export interface Directories {
+    documents: string;
+}
+export type UploadBeginHandlerParams = {
+    expectedBytes: number;
+};
+export type UploadBeginHandler = (params: UploadBeginHandlerParams) => void;
+export type UploadProgressHandlerParams = {
+    bytesUploaded: number;
+    bytesTotal: number;
+};
+export type UploadProgressHandler = (params: UploadProgressHandlerParams) => void;
+export type UploadDoneHandlerParams = {
+    responseCode: number;
+    responseBody: string;
+    bytesUploaded: number;
+    bytesTotal: number;
+};
+export type UploadDoneHandler = (params: UploadDoneHandlerParams) => void;
+export interface UploadErrorHandlerParams {
+    error: string;
+    errorCode: number;
+}
+export type UploadErrorHandler = (params: UploadErrorHandlerParams) => void;
+export type UploadTaskState = 'PENDING' | 'UPLOADING' | 'PAUSED' | 'DONE' | 'FAILED' | 'STOPPED';
+export interface UploadTaskInfoNative {
+    id: string;
+    metadata: Metadata;
+    bytesUploaded: number;
+    bytesTotal: number;
+    errorCode: number;
+    state: number;
+}
+export interface UploadTaskInfo {
+    id: string;
+    metadata?: object;
+}
+export type UploadParams = {
+    url: string;
+    source: string;
+    method?: 'POST' | 'PUT' | 'PATCH';
+    headers?: Headers;
+    fieldName?: string;
+    mimeType?: string;
+    parameters?: Record<string, string>;
+    isAllowedOverRoaming?: boolean;
+    isAllowedOverMetered?: boolean;
+};
+export interface UploadTask {
+    id: string;
+    state: UploadTaskState;
+    metadata: Metadata;
+    errorCode: number;
+    bytesUploaded: number;
+    bytesTotal: number;
+    uploadParams?: UploadParams;
+    begin: (handler: UploadBeginHandler) => UploadTask;
+    progress: (handler: UploadProgressHandler) => UploadTask;
+    done: (handler: UploadDoneHandler) => UploadTask;
+    error: (handler: UploadErrorHandler) => UploadTask;
+    beginHandler?: UploadBeginHandler;
+    progressHandler?: UploadProgressHandler;
+    doneHandler?: UploadDoneHandler;
+    errorHandler?: UploadErrorHandler;
+    setUploadParams: (params: UploadParams) => void;
+    start: () => void;
+    pause: () => Promise<void>;
+    resume: () => Promise<void>;
+    stop: () => Promise<void>;
+    tryParseJson: (metadata?: string | Metadata) => Metadata | null;
+}
+export type getExistingUploadTasks = () => Promise<UploadTask[]>;
+export interface UploadOption {
+    id: string;
+    url: string;
+    source: string;
+    method?: 'POST' | 'PUT' | 'PATCH';
+    headers?: Headers | undefined;
+    metadata?: object;
+    fieldName?: string;
+    mimeType?: string;
+    parameters?: Record<string, string>;
+    isAllowedOverRoaming?: boolean;
+    isAllowedOverMetered?: boolean;
+}
+export type Upload = (options: UploadOption) => UploadTask;
+export type CompleteUploadHandler = (id: string) => void;

package/lib/types.js

@@ -0,0 +1,2 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kesha-antonov/react-native-background-downloader",
-  "version": "4.5.4",
+  "version": "4.5.6",
   "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",
@@ -23,9 +23,9 @@
       "name": "Kesha Antonov, Elad Gil"
     }
   ],
-  "main": "src/index.ts",
+  "main": "lib/index.js",
   "react-native": "src/index.ts",
-  "types": "src/index.d.ts",
+  "types": "lib/index.d.ts",
   "expo": {
     "plugin": "./app.plugin.js"
   },
@@ -44,6 +44,7 @@
     "package.json",
     "app.plugin.js",
     "src/",
+    "lib/",
     "ios/",
     "android/build.gradle",
     "android/src/",
@@ -53,9 +54,11 @@
     "bump": "npm version patch",
     "lint": "eslint .",
     "typecheck": "tsc src/*.ts --noEmit --strict --skipLibCheck",
-    "prepublishOnly": "npm run build-plugin && npm run typecheck && jest && npm run lint",
+    "build": "rm -rf lib && tsc -p tsconfig.build.json",
+    "prepare": "npm run build && npm run build-plugin",
+    "prepublishOnly": "npm run build-plugin && npm run build && npm run typecheck && jest && npm run lint",
     "build-plugin": "tsc plugin/src/index.ts --outDir plugin/build --target ES2018 --module commonjs --declaration --esModuleInterop --strict --skipLibCheck",
-    "publish": "npm publish",
+    "release": "npm publish",
     "test": "jest"
   },
   "lint-staged": {

package/plugin/package.json

@@ -0,0 +1,6 @@
+{
+  "name": "@kesha-antonov/react-native-background-downloader-expo-plugin",
+  "version": "1.0.0",
+  "main": "build/index.js",
+  "types": "build/index.d.ts"
+}

package/react-native-background-downloader.podspec

@@ -20,8 +20,14 @@ Pod::Spec.new do |s|
   install_modules_dependencies(s)
 
   # MMKV is used for persistent download state storage on iOS
-  # Using MMKV (Objective-C wrapper) which depends on MMKVCore
-  s.dependency 'MMKV'
+  # Using MMKV (Objective-C wrapper) which depends on MMKVCore.
+  # We only use MMKV's basic key/value APIs (initializeMMKV:, mmkvWithID:,
+  # getDataForKey:/setData:forKey:, typed getters/setters) which have been stable
+  # since MMKV 1.x, so we require only that minimum. CocoaPods is still free to
+  # resolve a newer MMKV when another pod (e.g. react-native-mmkv, which pins an
+  # exact MMKVCore) requires one - we just don't impose our own higher floor.
+  # See https://github.com/kesha-antonov/react-native-background-downloader/issues/162
+  s.dependency 'MMKV', '>= 1.2.0'
 
   # Enable codegen for new architecture
   if ENV['RCT_NEW_ARCH_ENABLED'] == '1'

package/src/DownloadTask.ts

@@ -192,6 +192,8 @@ export class DownloadTask {
       headers: this.headersToUnsafeObject(this.downloadParams.headers),
       isAllowedOverRoaming: this.downloadParams.isAllowedOverRoaming ?? false,
       isAllowedOverMetered: this.downloadParams.isAllowedOverMetered ?? false,
+      // iOS-only; ignored on Android. Falls back to the global setConfig default.
+      iosDataProtection: this.downloadParams.iosDataProtection ?? config.iosDataProtection,
     })
   }
 

package/src/NativeRNBackgroundDownloader.ts

@@ -78,6 +78,8 @@ export interface Spec extends TurboModule {
     isAllowedOverRoaming: boolean
     isAllowedOverMetered: boolean
     maxRedirects?: number
+    /** iOS only: NSFileProtection level for the saved file. Ignored on Android. */
+    iosDataProtection?: string
   }): void
 
   pauseTask(id: string): Promise<void>

package/src/config.ts

@@ -1,9 +1,12 @@
-import { Headers, NotificationGroupingMode, NotificationsGroupingConfig, NotificationTexts } from './types'
+import { Headers, IosDataProtection, NotificationGroupingMode, NotificationsGroupingConfig, NotificationTexts } from './types'
 
 export const DEFAULT_PROGRESS_INTERVAL = 1000
 export const DEFAULT_PROGRESS_MIN_BYTES = 1024 * 1024 // 1MB
 export const DEFAULT_MAX_PARALLEL_DOWNLOADS = 4
 export const DEFAULT_ALLOWS_CELLULAR_ACCESS = true
+// Lets a background download save its file even while the device is locked
+// (after the first unlock since boot). See the iOS background-download notes in the README.
+export const DEFAULT_IOS_DATA_PROTECTION: IosDataProtection = 'completeUntilFirstUserAuthentication'
 
 // Default notification texts
 export const DEFAULT_NOTIFICATION_TEXTS: Required<NotificationTexts> = {
@@ -29,6 +32,7 @@ interface ConfigState {
   allowsCellularAccess: boolean
   showNotificationsEnabled: boolean
   notificationsGrouping: NotificationsGroupingConfig & { mode: NotificationGroupingMode }
+  iosDataProtection: IosDataProtection
 }
 
 export const config: ConfigState = {
@@ -40,6 +44,7 @@ export const config: ConfigState = {
   maxParallelDownloads: DEFAULT_MAX_PARALLEL_DOWNLOADS,
   allowsCellularAccess: DEFAULT_ALLOWS_CELLULAR_ACCESS,
   showNotificationsEnabled: false,
+  iosDataProtection: DEFAULT_IOS_DATA_PROTECTION,
   notificationsGrouping: {
     enabled: false,
     mode: 'individual',

package/src/index.ts

@@ -372,9 +372,13 @@ export function setConfig ({
   allowsCellularAccess,
   showNotificationsEnabled,
   notificationsGrouping,
+  iosDataProtection,
 }: Config) {
   config.headers = headers
 
+  if (iosDataProtection !== undefined)
+    config.iosDataProtection = iosDataProtection
+
   if (progressInterval >= MIN_PROGRESS_INTERVAL)
     config.progressInterval = progressInterval
   else

package/src/types.ts

@@ -47,6 +47,23 @@ export interface NotificationsGroupingConfig {
   texts?: NotificationTexts
 }
 
+/**
+ * iOS Data Protection level applied to the downloaded file (iOS only, ignored on Android).
+ *
+ * On iOS, files protected with `complete` become unreadable/unwritable while the device
+ * is locked, which can make a background download fail to save when it finishes on a
+ * locked device. The default `completeUntilFirstUserAuthentication` lets the file be
+ * written while locked (after the first unlock since boot), which is what you almost
+ * always want for background downloads.
+ *
+ * Maps to the NSFileProtection* constants.
+ */
+export type IosDataProtection =
+  | 'complete'
+  | 'completeUnlessOpen'
+  | 'completeUntilFirstUserAuthentication'
+  | 'none'
+
 export interface Config {
   headers?: Headers
   progressInterval?: number
@@ -59,6 +76,11 @@ export interface Config {
   showNotificationsEnabled?: boolean
   /** Configuration for notifications grouping on Android */
   notificationsGrouping?: NotificationsGroupingConfig
+  /**
+   * Default iOS Data Protection level for downloaded files (iOS only).
+   * Default: 'completeUntilFirstUserAuthentication'. Can be overridden per task.
+   */
+  iosDataProtection?: IosDataProtection
 }
 
 export type SetConfig = (config: Partial<Config>) => void
@@ -129,6 +151,11 @@ export type DownloadParams = {
   groupId?: string
   /** Group name displayed in notification (only used when grouping is enabled) */
   groupName?: string
+  /**
+   * iOS Data Protection level for this download's file (iOS only).
+   * Overrides the global `iosDataProtection` from setConfig.
+   */
+  iosDataProtection?: IosDataProtection
 }
 
 export interface DownloadTask {