@symbiote-native/background-fetch 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 A. Prokopenko
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,161 @@
+# @symbiote-native/background-fetch
+
+A wrapper package for [SymbioteNative](../../README.md) that makes
+[`expo-background-fetch`](https://github.com/expo/expo/tree/main/packages/expo-background-fetch)
+usable from **every** adapter — React, Vue, Svelte, Solid, and Angular. Like
+[`@symbiote-native/task-manager`](../task-manager), every export is a plain async function, so
+there is no hook/composable/service to wrap: the React, Vue, Svelte, Solid, and Angular entry
+points are plain re-exports of the same `core`.
+
+**Upstream deprecated this API in favor of `expo-background-task`** — Apple and Google are both
+moving away from periodic-fetch-style scheduling toward task-scheduling APIs
+(`BGTaskScheduler` / `WorkManager`). It is ported here anyway, alongside
+[`@symbiote-native/background-task`](../background-task), because Expo still ships both
+simultaneously as of sdk-57 and an app already built against the old API needs a path to run on
+SymbioteNative too. Prefer `@symbiote-native/background-task` for new code.
+
+This package registers a task with native so it fires **periodically in the background** — it
+does not define what the task does. Define the task first via
+[`@symbiote-native/task-manager`](../task-manager)'s `defineTask`, then register it for periodic
+execution via this package's `registerTaskAsync`.
+
+## Install
+
+**New app:**
+
+```bash
+npx @symbiote-native/cli new my-app --background-fetch
+```
+
+**Existing SymbioteNative app:**
+
+```bash
+npx @symbiote-native/cli add --background-fetch
+```
+
+Either way: installs `@symbiote-native/background-fetch` + `@symbiote-native/task-manager` and
+wires the native autolinking automatically — see [`@symbiote-native/cli`](../cli).
+
+<details>
+<summary>Manual install (no CLI — installing and wiring native autolinking by hand)</summary>
+
+```bash
+npm install @symbiote-native/background-fetch @symbiote-native/task-manager
+```
+
+`expo-background-fetch` and `expo-modules-core` come along as regular dependencies, pinned to
+exact versions — never install them yourself, and never add the `expo` meta-package to your
+project.
+
+## Required one-time step: native autolinking wiring
+
+Same one-time step as every other `expo-modules-core` package this project ships — see
+[`@symbiote-native/local-auth`'s README](../local-auth/README.md#required-one-time-step-native-autolinking-wiring)
+and the `symbiote-expo-native-module` project skill.
+
+iOS also needs `UIBackgroundModes: fetch` in the app's Info.plist —
+`native-link.json`'s `ios.infoPlistArrayKeys` covers this ARRAY-valued case (see
+`@symbiote-native/expo-modules-link`), so it's wired automatically by the same postinstall step,
+no manual edit needed. Android needs no manual step — `RECEIVE_BOOT_COMPLETED` and `WAKE_LOCK`
+ship in `expo-background-fetch`'s own `AndroidManifest.xml` and merge automatically once the
+package is installed.
+
+</details>
+
+## Shape
+
+```
+src/core/     getStatusAsync / setMinimumIntervalAsync / registerTaskAsync / unregisterTaskAsync,
+              plus BackgroundFetchResult / BackgroundFetchStatus / IBackgroundFetchOptions.
+              native-module.ts resolves the native module via expo-modules-core's
+              requireNativeModule.
+src/angular/  @symbiote-native/background-fetch/angular — export * from '../core'
+```
+
+`./react`, `./vue`, `./svelte`, and `./solid` are `exports`-map aliases straight onto
+`src/core/`. `./angular` stays a physical file/subpath since Angular ships through a separate
+`ngc`/AOT build (`build-ngc/`).
+
+## Use it
+
+```ts
+// index.ts, alongside AppRegistry.registerComponent — identical on every adapter
+import { defineTask } from '@symbiote-native/task-manager';
+import {
+  registerTaskAsync,
+  BackgroundFetchResult,
+} from '@symbiote-native/background-fetch';
+
+const SYNC_TASK = 'background-sync';
+
+defineTask(SYNC_TASK, async ({ data, error }) => {
+  if (error) {
+    console.error('background-sync failed:', error);
+    return BackgroundFetchResult.Failed;
+  }
+  const receivedNewData = await runSync(data);
+  return receivedNewData
+    ? BackgroundFetchResult.NewData
+    : BackgroundFetchResult.NoData;
+});
+
+// Somewhere after the task is defined (a settings screen, app bootstrap, …):
+await registerTaskAsync(SYNC_TASK, { minimumInterval: 900 });
+```
+
+`@symbiote-native/task-manager` is the primitive both this package and
+[`@symbiote-native/background-task`](../background-task) build on — `defineTask` lives there,
+`registerTaskAsync`/`unregisterTaskAsync` live here. `defineTask` must run at the top of the JS
+bundle, outside any component, for the same reason documented in task-manager's own README: the
+app can be launched headlessly to run a background task, with no views mounted.
+
+```ts
+import {
+  getStatusAsync,
+  unregisterTaskAsync,
+} from '@symbiote-native/background-fetch';
+
+const status = await getStatusAsync();
+await unregisterTaskAsync(SYNC_TASK); // stop receiving background-fetch callbacks for it
+```
+
+Identical import surface on every adapter — `@symbiote-native/background-fetch/react`,
+`/vue`, `/svelte`, `/solid`, `/angular` all re-export the same functions.
+
+## API
+
+```ts
+getStatusAsync(): Promise<BackgroundFetchStatus | null>
+setMinimumIntervalAsync(minimumInterval: number): Promise<void>
+registerTaskAsync(taskName: string, options?: IBackgroundFetchOptions): Promise<void>
+unregisterTaskAsync(taskName: string): Promise<void>
+```
+
+Plus `BackgroundFetchResult`, `BackgroundFetchStatus`, `IBackgroundFetchOptions` — ported from
+upstream's `BackgroundFetch.types.ts`, the options type renamed with this repo's `I`-prefix
+convention for exported types (`ts-js-best-practices`).
+
+## Notes
+
+- **Every function warns once, on first call, that this API is deprecated** — matching upstream's
+  own `showDeprecationWarning`. It still works; the warning is a nudge toward
+  `@symbiote-native/background-task`, not a functional restriction.
+- **`registerTaskAsync` requires the task to already be defined.** It throws if
+  `@symbiote-native/task-manager`'s `isTaskDefined(taskName)` is `false` — call `defineTask`
+  first.
+- **`getStatusAsync` shortcuts to `Available` on Android without calling native at all** —
+  matches upstream, which has no Android-side status concept (the native call exists only on
+  iOS).
+- **`setMinimumIntervalAsync` silently no-ops when native lacks the method** (Android has no
+  equivalent call) rather than throwing — matches upstream.
+- **Expo Go is out of scope.** Upstream also warns when running inside Expo Go
+  (`isRunningInExpoGo`, imported from the `expo` meta-package). This project never installs
+  `expo` — every app here is a bare/dev-client build, never Expo Go — so that check has no
+  equivalent here and is intentionally not ported.
+
+## Test it
+
+No Fabric/Descriptor angle at all — every function here is a pure async-function surface, never a
+view or per-instance state. Tests inject a fake native-module object in place of the real
+`requireNativeModule` resolution and a fake `@symbiote-native/task-manager` module
+(`src/core/background-fetch.test.ts`) — no `installFabric()`, no ViewConfig.

package/build/angular/index.d.ts

@@ -0,0 +1 @@
+export * from '../core';

package/build/angular/index.js

@@ -0,0 +1,4 @@
+// @symbiote-native/background-fetch/angular: the Angular entry over the framework-agnostic core.
+// Same reasoning as the React/Vue entries — no per-instance state or event stream to wrap in a
+// service, so this is a plain re-export.
+export * from '../core/index.js';

package/build/core/background-fetch.d.ts

@@ -0,0 +1,18 @@
+import { BackgroundFetchStatus } from './types';
+import type { IBackgroundFetchOptions } from './types';
+/** Gets the current background-fetch status, or `null` if the native module is unreachable. */
+export declare function getStatusAsync(): Promise<BackgroundFetchStatus | null>;
+/**
+ * Sets the minimum number of seconds that must elapse before another background fetch can be
+ * initiated. Advisory only — iOS treats it as a floor, not an exact schedule. No effect on
+ * Android.
+ */
+export declare function setMinimumIntervalAsync(minimumInterval: number): Promise<void>;
+/**
+ * Registers a background-fetch task with the given name. The task must already be defined via
+ * `@symbiote-native/task-manager`'s `defineTask` — registration is driven by this package, but
+ * execution dispatch is task-manager's job.
+ */
+export declare function registerTaskAsync(taskName: string, options?: IBackgroundFetchOptions): Promise<void>;
+/** Unregisters a background-fetch task, so the app stops receiving fetch callbacks for it. */
+export declare function unregisterTaskAsync(taskName: string): Promise<void>;

package/build/core/background-fetch.js

@@ -0,0 +1,70 @@
+import { Platform, UnavailabilityError } from 'expo-modules-core';
+import { isTaskDefined } from '@symbiote-native/task-manager';
+import { expoBackgroundFetch } from './native-module.js';
+import { BackgroundFetchStatus } from './types.js';
+const NATIVE_MODULE_NAME = 'BackgroundFetch';
+// expo-background-fetch is upstream-deprecated in favor of expo-background-task (still shipped
+// in sdk-57 alongside it, same as this project's file-system legacy+modern split) — carry the
+// same one-time console warning upstream shows, so an app that adopted the old API notices.
+let didShowDeprecationWarning = false;
+function warnDeprecated() {
+    if (didShowDeprecationWarning)
+        return;
+    didShowDeprecationWarning = true;
+    console.warn('@symbiote-native/background-fetch: this API is deprecated. Use @symbiote-native/background-task instead.');
+}
+function assertValidTaskName(taskName) {
+    if (!taskName || typeof taskName !== 'string') {
+        throw new TypeError('`taskName` must be a non-empty string.');
+    }
+}
+// Upstream also warns when running inside Expo Go (`isRunningInExpoGo`, imported from the `expo`
+// meta-package). This project never installs `expo` — every app here is a bare/dev-client build,
+// never Expo Go — so that check has no equivalent and is intentionally not ported.
+/** Gets the current background-fetch status, or `null` if the native module is unreachable. */
+export async function getStatusAsync() {
+    warnDeprecated();
+    if (Platform.OS === 'android') {
+        return BackgroundFetchStatus.Available;
+    }
+    if (!expoBackgroundFetch.getStatusAsync) {
+        throw new UnavailabilityError(NATIVE_MODULE_NAME, 'getStatusAsync');
+    }
+    return expoBackgroundFetch.getStatusAsync();
+}
+/**
+ * Sets the minimum number of seconds that must elapse before another background fetch can be
+ * initiated. Advisory only — iOS treats it as a floor, not an exact schedule. No effect on
+ * Android.
+ */
+export async function setMinimumIntervalAsync(minimumInterval) {
+    warnDeprecated();
+    if (!expoBackgroundFetch.setMinimumIntervalAsync)
+        return;
+    await expoBackgroundFetch.setMinimumIntervalAsync(minimumInterval);
+}
+/**
+ * Registers a background-fetch task with the given name. The task must already be defined via
+ * `@symbiote-native/task-manager`'s `defineTask` — registration is driven by this package, but
+ * execution dispatch is task-manager's job.
+ */
+export async function registerTaskAsync(taskName, options = {}) {
+    warnDeprecated();
+    if (!expoBackgroundFetch.registerTaskAsync) {
+        throw new UnavailabilityError(NATIVE_MODULE_NAME, 'registerTaskAsync');
+    }
+    if (!isTaskDefined(taskName)) {
+        throw new Error(`Task '${taskName}' is not defined. You must define a task using defineTask (from @symbiote-native/task-manager) before registering.`);
+    }
+    assertValidTaskName(taskName);
+    await expoBackgroundFetch.registerTaskAsync(taskName, options);
+}
+/** Unregisters a background-fetch task, so the app stops receiving fetch callbacks for it. */
+export async function unregisterTaskAsync(taskName) {
+    warnDeprecated();
+    if (!expoBackgroundFetch.unregisterTaskAsync) {
+        throw new UnavailabilityError(NATIVE_MODULE_NAME, 'unregisterTaskAsync');
+    }
+    assertValidTaskName(taskName);
+    await expoBackgroundFetch.unregisterTaskAsync(taskName);
+}

package/build/core/index.d.ts

@@ -0,0 +1,3 @@
+export { getStatusAsync, setMinimumIntervalAsync, registerTaskAsync, unregisterTaskAsync, } from './background-fetch';
+export { BackgroundFetchResult, BackgroundFetchStatus } from './types';
+export type { IBackgroundFetchOptions } from './types';

package/build/core/index.js

@@ -0,0 +1,2 @@
+export { getStatusAsync, setMinimumIntervalAsync, registerTaskAsync, unregisterTaskAsync, } from './background-fetch.js';
+export { BackgroundFetchResult, BackgroundFetchStatus } from './types.js';

package/build/core/native-module.d.ts

@@ -0,0 +1,8 @@
+export type INativeBackgroundFetchModule = {
+    getStatusAsync?(): Promise<number>;
+    /** iOS only — Android has no equivalent native call. */
+    setMinimumIntervalAsync?(minimumInterval: number): Promise<void>;
+    registerTaskAsync?(taskName: string, options: Record<string, unknown>): Promise<void>;
+    unregisterTaskAsync?(taskName: string): Promise<void>;
+};
+export declare const expoBackgroundFetch: INativeBackgroundFetchModule;

package/build/core/native-module.js

@@ -0,0 +1,3 @@
+import { requireNativeModule } from 'expo-modules-core';
+const EXPO_BACKGROUND_FETCH_MODULE_NAME = 'ExpoBackgroundFetch';
+export const expoBackgroundFetch = requireNativeModule(EXPO_BACKGROUND_FETCH_MODULE_NAME);

package/build/core/types.d.ts

@@ -0,0 +1,47 @@
+/**
+ * What iOS does with the return value of a background-fetch task executor — lets the platform
+ * schedule future fetches more intelligently. Android ignores it (it has no equivalent concept).
+ */
+export declare enum BackgroundFetchResult {
+    /** There was no new data to download. */
+    NoData = 1,
+    /** New data was successfully downloaded. */
+    NewData = 2,
+    /** An attempt to download data was made but that attempt failed. */
+    Failed = 3
+}
+/** Whether the app can currently receive background-fetch callbacks. */
+export declare enum BackgroundFetchStatus {
+    /** The user explicitly disabled background behavior for this app or for the whole system. */
+    Denied = 1,
+    /**
+     * Background updates are unavailable and the user cannot enable them again — e.g. parental
+     * controls are in effect for the current user.
+     */
+    Restricted = 2,
+    /** Background updates are available for the app. */
+    Available = 3
+}
+/** Options accepted by {@link registerTaskAsync}. */
+export type IBackgroundFetchOptions = {
+    /**
+     * Inexact interval in seconds between subsequent repeats of the background fetch alarm. The
+     * final interval may differ from the specified one to minimize wakeups and battery usage.
+     * - Android defaults to 10 minutes.
+     * - iOS calls `setMinimumIntervalAsync` behind the scenes; the platform default is the
+     *   smallest fetch interval it supports (10-15 minutes).
+     */
+    minimumInterval?: number;
+    /**
+     * Whether to stop receiving background fetch events after the user terminates the app.
+     * @default true
+     * @platform android
+     */
+    stopOnTerminate?: boolean;
+    /**
+     * Whether to restart background fetch events when the device has finished booting.
+     * @default false
+     * @platform android
+     */
+    startOnBoot?: boolean;
+};

package/build/core/types.js

@@ -0,0 +1,26 @@
+/**
+ * What iOS does with the return value of a background-fetch task executor — lets the platform
+ * schedule future fetches more intelligently. Android ignores it (it has no equivalent concept).
+ */
+export var BackgroundFetchResult;
+(function (BackgroundFetchResult) {
+    /** There was no new data to download. */
+    BackgroundFetchResult[BackgroundFetchResult["NoData"] = 1] = "NoData";
+    /** New data was successfully downloaded. */
+    BackgroundFetchResult[BackgroundFetchResult["NewData"] = 2] = "NewData";
+    /** An attempt to download data was made but that attempt failed. */
+    BackgroundFetchResult[BackgroundFetchResult["Failed"] = 3] = "Failed";
+})(BackgroundFetchResult || (BackgroundFetchResult = {}));
+/** Whether the app can currently receive background-fetch callbacks. */
+export var BackgroundFetchStatus;
+(function (BackgroundFetchStatus) {
+    /** The user explicitly disabled background behavior for this app or for the whole system. */
+    BackgroundFetchStatus[BackgroundFetchStatus["Denied"] = 1] = "Denied";
+    /**
+     * Background updates are unavailable and the user cannot enable them again — e.g. parental
+     * controls are in effect for the current user.
+     */
+    BackgroundFetchStatus[BackgroundFetchStatus["Restricted"] = 2] = "Restricted";
+    /** Background updates are available for the app. */
+    BackgroundFetchStatus[BackgroundFetchStatus["Available"] = 3] = "Available";
+})(BackgroundFetchStatus || (BackgroundFetchStatus = {}));

package/build-ngc/angular/index.d.ts

@@ -0,0 +1 @@
+export * from '../core';

package/build-ngc/angular/index.js

@@ -0,0 +1,5 @@
+// @symbiote-native/background-fetch/angular: the Angular entry over the framework-agnostic core.
+// Same reasoning as the React/Vue entries — no per-instance state or event stream to wrap in a
+// service, so this is a plain re-export.
+export * from '../core';
+//# sourceMappingURL=index.js.map

package/build-ngc/angular/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/angular/index.ts"],"names":[],"mappings":"AAAA,iGAAiG;AACjG,+FAA+F;AAC/F,yCAAyC;AACzC,cAAc,SAAS,CAAC"}

package/build-ngc/core/background-fetch.d.ts

@@ -0,0 +1,18 @@
+import { BackgroundFetchStatus } from './types';
+import type { IBackgroundFetchOptions } from './types';
+/** Gets the current background-fetch status, or `null` if the native module is unreachable. */
+export declare function getStatusAsync(): Promise<BackgroundFetchStatus | null>;
+/**
+ * Sets the minimum number of seconds that must elapse before another background fetch can be
+ * initiated. Advisory only — iOS treats it as a floor, not an exact schedule. No effect on
+ * Android.
+ */
+export declare function setMinimumIntervalAsync(minimumInterval: number): Promise<void>;
+/**
+ * Registers a background-fetch task with the given name. The task must already be defined via
+ * `@symbiote-native/task-manager`'s `defineTask` — registration is driven by this package, but
+ * execution dispatch is task-manager's job.
+ */
+export declare function registerTaskAsync(taskName: string, options?: IBackgroundFetchOptions): Promise<void>;
+/** Unregisters a background-fetch task, so the app stops receiving fetch callbacks for it. */
+export declare function unregisterTaskAsync(taskName: string): Promise<void>;

package/build-ngc/core/background-fetch.js

@@ -0,0 +1,71 @@
+import { Platform, UnavailabilityError } from 'expo-modules-core';
+import { isTaskDefined } from '@symbiote-native/task-manager';
+import { expoBackgroundFetch } from './native-module';
+import { BackgroundFetchStatus } from './types';
+const NATIVE_MODULE_NAME = 'BackgroundFetch';
+// expo-background-fetch is upstream-deprecated in favor of expo-background-task (still shipped
+// in sdk-57 alongside it, same as this project's file-system legacy+modern split) — carry the
+// same one-time console warning upstream shows, so an app that adopted the old API notices.
+let didShowDeprecationWarning = false;
+function warnDeprecated() {
+    if (didShowDeprecationWarning)
+        return;
+    didShowDeprecationWarning = true;
+    console.warn('@symbiote-native/background-fetch: this API is deprecated. Use @symbiote-native/background-task instead.');
+}
+function assertValidTaskName(taskName) {
+    if (!taskName || typeof taskName !== 'string') {
+        throw new TypeError('`taskName` must be a non-empty string.');
+    }
+}
+// Upstream also warns when running inside Expo Go (`isRunningInExpoGo`, imported from the `expo`
+// meta-package). This project never installs `expo` — every app here is a bare/dev-client build,
+// never Expo Go — so that check has no equivalent and is intentionally not ported.
+/** Gets the current background-fetch status, or `null` if the native module is unreachable. */
+export async function getStatusAsync() {
+    warnDeprecated();
+    if (Platform.OS === 'android') {
+        return BackgroundFetchStatus.Available;
+    }
+    if (!expoBackgroundFetch.getStatusAsync) {
+        throw new UnavailabilityError(NATIVE_MODULE_NAME, 'getStatusAsync');
+    }
+    return expoBackgroundFetch.getStatusAsync();
+}
+/**
+ * Sets the minimum number of seconds that must elapse before another background fetch can be
+ * initiated. Advisory only — iOS treats it as a floor, not an exact schedule. No effect on
+ * Android.
+ */
+export async function setMinimumIntervalAsync(minimumInterval) {
+    warnDeprecated();
+    if (!expoBackgroundFetch.setMinimumIntervalAsync)
+        return;
+    await expoBackgroundFetch.setMinimumIntervalAsync(minimumInterval);
+}
+/**
+ * Registers a background-fetch task with the given name. The task must already be defined via
+ * `@symbiote-native/task-manager`'s `defineTask` — registration is driven by this package, but
+ * execution dispatch is task-manager's job.
+ */
+export async function registerTaskAsync(taskName, options = {}) {
+    warnDeprecated();
+    if (!expoBackgroundFetch.registerTaskAsync) {
+        throw new UnavailabilityError(NATIVE_MODULE_NAME, 'registerTaskAsync');
+    }
+    if (!isTaskDefined(taskName)) {
+        throw new Error(`Task '${taskName}' is not defined. You must define a task using defineTask (from @symbiote-native/task-manager) before registering.`);
+    }
+    assertValidTaskName(taskName);
+    await expoBackgroundFetch.registerTaskAsync(taskName, options);
+}
+/** Unregisters a background-fetch task, so the app stops receiving fetch callbacks for it. */
+export async function unregisterTaskAsync(taskName) {
+    warnDeprecated();
+    if (!expoBackgroundFetch.unregisterTaskAsync) {
+        throw new UnavailabilityError(NATIVE_MODULE_NAME, 'unregisterTaskAsync');
+    }
+    assertValidTaskName(taskName);
+    await expoBackgroundFetch.unregisterTaskAsync(taskName);
+}
+//# sourceMappingURL=background-fetch.js.map

package/build-ngc/core/background-fetch.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"background-fetch.js","sourceRoot":"","sources":["../../src/core/background-fetch.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,QAAQ,EAAE,mBAAmB,EAAE,MAAM,mBAAmB,CAAC;AAClE,OAAO,EAAE,aAAa,EAAE,MAAM,+BAA+B,CAAC;AAC9D,OAAO,EAAE,mBAAmB,EAAE,MAAM,iBAAiB,CAAC;AACtD,OAAO,EAAE,qBAAqB,EAAE,MAAM,SAAS,CAAC;AAGhD,MAAM,kBAAkB,GAAG,iBAAiB,CAAC;AAE7C,+FAA+F;AAC/F,8FAA8F;AAC9F,4FAA4F;AAC5F,IAAI,yBAAyB,GAAG,KAAK,CAAC;AACtC,SAAS,cAAc;IACrB,IAAI,yBAAyB;QAAE,OAAO;IACtC,yBAAyB,GAAG,IAAI,CAAC;IACjC,OAAO,CAAC,IAAI,CACV,0GAA0G,CAC3G,CAAC;AACJ,CAAC;AAED,SAAS,mBAAmB,CAAC,QAAiB;IAC5C,IAAI,CAAC,QAAQ,IAAI,OAAO,QAAQ,KAAK,QAAQ,EAAE,CAAC;QAC9C,MAAM,IAAI,SAAS,CAAC,wCAAwC,CAAC,CAAC;IAChE,CAAC;AACH,CAAC;AAED,iGAAiG;AACjG,iGAAiG;AACjG,mFAAmF;AAEnF,+FAA+F;AAC/F,MAAM,CAAC,KAAK,UAAU,cAAc;IAClC,cAAc,EAAE,CAAC;IACjB,IAAI,QAAQ,CAAC,EAAE,KAAK,SAAS,EAAE,CAAC;QAC9B,OAAO,qBAAqB,CAAC,SAAS,CAAC;IACzC,CAAC;IACD,IAAI,CAAC,mBAAmB,CAAC,cAAc,EAAE,CAAC;QACxC,MAAM,IAAI,mBAAmB,CAAC,kBAAkB,EAAE,gBAAgB,CAAC,CAAC;IACtE,CAAC;IACD,OAAO,mBAAmB,CAAC,cAAc,EAAoC,CAAC;AAChF,CAAC;AAED;;;;GAIG;AACH,MAAM,CAAC,KAAK,UAAU,uBAAuB,CAC3C,eAAuB;IAEvB,cAAc,EAAE,CAAC;IACjB,IAAI,CAAC,mBAAmB,CAAC,uBAAuB;QAAE,OAAO;IACzD,MAAM,mBAAmB,CAAC,uBAAuB,CAAC,eAAe,CAAC,CAAC;AACrE,CAAC;AAED;;;;GAIG;AACH,MAAM,CAAC,KAAK,UAAU,iBAAiB,CACrC,QAAgB,EAChB,UAAmC,EAAE;IAErC,cAAc,EAAE,CAAC;IACjB,IAAI,CAAC,mBAAmB,CAAC,iBAAiB,EAAE,CAAC;QAC3C,MAAM,IAAI,mBAAmB,CAAC,kBAAkB,EAAE,mBAAmB,CAAC,CAAC;IACzE,CAAC;IACD,IAAI,CAAC,aAAa,CAAC,QAAQ,CAAC,EAAE,CAAC;QAC7B,MAAM,IAAI,KAAK,CACb,SAAS,QAAQ,oHAAoH,CACtI,CAAC;IACJ,CAAC;IACD,mBAAmB,CAAC,QAAQ,CAAC,CAAC;IAC9B,MAAM,mBAAmB,CAAC,iBAAiB,CAAC,QAAQ,EAAE,OAAO,CAAC,CAAC;AACjE,CAAC;AAED,8FAA8F;AAC9F,MAAM,CAAC,KAAK,UAAU,mBAAmB,CAAC,QAAgB;IACxD,cAAc,EAAE,CAAC;IACjB,IAAI,CAAC,mBAAmB,CAAC,mBAAmB,EAAE,CAAC;QAC7C,MAAM,IAAI,mBAAmB,CAAC,kBAAkB,EAAE,qBAAqB,CAAC,CAAC;IAC3E,CAAC;IACD,mBAAmB,CAAC,QAAQ,CAAC,CAAC;IAC9B,MAAM,mBAAmB,CAAC,mBAAmB,CAAC,QAAQ,CAAC,CAAC;AAC1D,CAAC"}

package/build-ngc/core/index.d.ts

@@ -0,0 +1,3 @@
+export { getStatusAsync, setMinimumIntervalAsync, registerTaskAsync, unregisterTaskAsync, } from './background-fetch';
+export { BackgroundFetchResult, BackgroundFetchStatus } from './types';
+export type { IBackgroundFetchOptions } from './types';

package/build-ngc/core/index.js

@@ -0,0 +1,3 @@
+export { getStatusAsync, setMinimumIntervalAsync, registerTaskAsync, unregisterTaskAsync, } from './background-fetch';
+export { BackgroundFetchResult, BackgroundFetchStatus } from './types';
+//# sourceMappingURL=index.js.map

package/build-ngc/core/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/core/index.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,cAAc,EACd,uBAAuB,EACvB,iBAAiB,EACjB,mBAAmB,GACpB,MAAM,oBAAoB,CAAC;AAC5B,OAAO,EAAE,qBAAqB,EAAE,qBAAqB,EAAE,MAAM,SAAS,CAAC"}

package/build-ngc/core/native-module.d.ts

@@ -0,0 +1,8 @@
+export type INativeBackgroundFetchModule = {
+    getStatusAsync?(): Promise<number>;
+    /** iOS only — Android has no equivalent native call. */
+    setMinimumIntervalAsync?(minimumInterval: number): Promise<void>;
+    registerTaskAsync?(taskName: string, options: Record<string, unknown>): Promise<void>;
+    unregisterTaskAsync?(taskName: string): Promise<void>;
+};
+export declare const expoBackgroundFetch: INativeBackgroundFetchModule;

package/build-ngc/core/native-module.js

@@ -0,0 +1,4 @@
+import { requireNativeModule } from 'expo-modules-core';
+const EXPO_BACKGROUND_FETCH_MODULE_NAME = 'ExpoBackgroundFetch';
+export const expoBackgroundFetch = requireNativeModule(EXPO_BACKGROUND_FETCH_MODULE_NAME);
+//# sourceMappingURL=native-module.js.map

package/build-ngc/core/native-module.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"native-module.js","sourceRoot":"","sources":["../../src/core/native-module.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,mBAAmB,EAAE,MAAM,mBAAmB,CAAC;AAExD,MAAM,iCAAiC,GAAG,qBAAqB,CAAC;AAgBhE,MAAM,CAAC,MAAM,mBAAmB,GAC9B,mBAAmB,CACjB,iCAAiC,CAClC,CAAC"}

package/build-ngc/core/types.d.ts

@@ -0,0 +1,47 @@
+/**
+ * What iOS does with the return value of a background-fetch task executor — lets the platform
+ * schedule future fetches more intelligently. Android ignores it (it has no equivalent concept).
+ */
+export declare enum BackgroundFetchResult {
+    /** There was no new data to download. */
+    NoData = 1,
+    /** New data was successfully downloaded. */
+    NewData = 2,
+    /** An attempt to download data was made but that attempt failed. */
+    Failed = 3
+}
+/** Whether the app can currently receive background-fetch callbacks. */
+export declare enum BackgroundFetchStatus {
+    /** The user explicitly disabled background behavior for this app or for the whole system. */
+    Denied = 1,
+    /**
+     * Background updates are unavailable and the user cannot enable them again — e.g. parental
+     * controls are in effect for the current user.
+     */
+    Restricted = 2,
+    /** Background updates are available for the app. */
+    Available = 3
+}
+/** Options accepted by {@link registerTaskAsync}. */
+export type IBackgroundFetchOptions = {
+    /**
+     * Inexact interval in seconds between subsequent repeats of the background fetch alarm. The
+     * final interval may differ from the specified one to minimize wakeups and battery usage.
+     * - Android defaults to 10 minutes.
+     * - iOS calls `setMinimumIntervalAsync` behind the scenes; the platform default is the
+     *   smallest fetch interval it supports (10-15 minutes).
+     */
+    minimumInterval?: number;
+    /**
+     * Whether to stop receiving background fetch events after the user terminates the app.
+     * @default true
+     * @platform android
+     */
+    stopOnTerminate?: boolean;
+    /**
+     * Whether to restart background fetch events when the device has finished booting.
+     * @default false
+     * @platform android
+     */
+    startOnBoot?: boolean;
+};

package/build-ngc/core/types.js

@@ -0,0 +1,27 @@
+/**
+ * What iOS does with the return value of a background-fetch task executor — lets the platform
+ * schedule future fetches more intelligently. Android ignores it (it has no equivalent concept).
+ */
+export var BackgroundFetchResult;
+(function (BackgroundFetchResult) {
+    /** There was no new data to download. */
+    BackgroundFetchResult[BackgroundFetchResult["NoData"] = 1] = "NoData";
+    /** New data was successfully downloaded. */
+    BackgroundFetchResult[BackgroundFetchResult["NewData"] = 2] = "NewData";
+    /** An attempt to download data was made but that attempt failed. */
+    BackgroundFetchResult[BackgroundFetchResult["Failed"] = 3] = "Failed";
+})(BackgroundFetchResult || (BackgroundFetchResult = {}));
+/** Whether the app can currently receive background-fetch callbacks. */
+export var BackgroundFetchStatus;
+(function (BackgroundFetchStatus) {
+    /** The user explicitly disabled background behavior for this app or for the whole system. */
+    BackgroundFetchStatus[BackgroundFetchStatus["Denied"] = 1] = "Denied";
+    /**
+     * Background updates are unavailable and the user cannot enable them again — e.g. parental
+     * controls are in effect for the current user.
+     */
+    BackgroundFetchStatus[BackgroundFetchStatus["Restricted"] = 2] = "Restricted";
+    /** Background updates are available for the app. */
+    BackgroundFetchStatus[BackgroundFetchStatus["Available"] = 3] = "Available";
+})(BackgroundFetchStatus || (BackgroundFetchStatus = {}));
+//# sourceMappingURL=types.js.map

package/build-ngc/core/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../src/core/types.ts"],"names":[],"mappings":"AAAA;;;GAGG;AACH,MAAM,CAAN,IAAY,qBAOX;AAPD,WAAY,qBAAqB;IAC/B,yCAAyC;IACzC,qEAAU,CAAA;IACV,4CAA4C;IAC5C,uEAAW,CAAA;IACX,oEAAoE;IACpE,qEAAU,CAAA;AACZ,CAAC,EAPW,qBAAqB,KAArB,qBAAqB,QAOhC;AAED,wEAAwE;AACxE,MAAM,CAAN,IAAY,qBAUX;AAVD,WAAY,qBAAqB;IAC/B,6FAA6F;IAC7F,qEAAU,CAAA;IACV;;;OAGG;IACH,6EAAc,CAAA;IACd,oDAAoD;IACpD,2EAAa,CAAA;AACf,CAAC,EAVW,qBAAqB,KAArB,qBAAqB,QAUhC"}

package/native-link.json

@@ -0,0 +1,15 @@
+{
+  "android": {
+    "gradleProjectName": "expo-background-fetch",
+    "modules": [
+      {
+        "importPath": "expo.modules.backgroundfetch.BackgroundFetchModule",
+        "className": "BackgroundFetchModule",
+        "nativeName": "ExpoBackgroundFetch"
+      }
+    ]
+  },
+  "ios": {
+    "infoPlistArrayKeys": { "UIBackgroundModes": ["fetch"] }
+  }
+}

package/package.json

@@ -0,0 +1,151 @@
+{
+  "name": "@symbiote-native/background-fetch",
+  "version": "0.1.0",
+  "description": "expo-background-fetch wrapped for SymbioteNative — one framework-agnostic core, built once and reachable from the React, Vue, Svelte, Solid, and Angular adapters. Periodic background fetch, registered through @symbiote-native/task-manager. Deprecated upstream in favor of expo-background-task; ported for parity with what Expo still ships.",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/OneEyed1366/symbiote-native.git",
+    "directory": "packages/background-fetch"
+  },
+  "homepage": "https://github.com/OneEyed1366/symbiote-native/tree/master/packages/background-fetch#readme",
+  "bugs": {
+    "url": "https://github.com/OneEyed1366/symbiote-native/issues"
+  },
+  "author": "Andrey Prokopenko <psevdoproger@gmail.com>",
+  "keywords": [
+    "react-native",
+    "symbiote-native",
+    "expo-background-fetch",
+    "react",
+    "vue",
+    "svelte",
+    "solid",
+    "angular",
+    "background",
+    "fetch"
+  ],
+  "type": "module",
+  "main": "./build/core/index.js",
+  "module": "./build/core/index.js",
+  "types": "./build/core/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./build/core/index.d.ts",
+      "default": "./build/core/index.js"
+    },
+    "./vue": {
+      "types": "./build/core/index.d.ts",
+      "default": "./build/core/index.js"
+    },
+    "./react": {
+      "types": "./build/core/index.d.ts",
+      "default": "./build/core/index.js"
+    },
+    "./svelte": {
+      "types": "./build/core/index.d.ts",
+      "default": "./build/core/index.js"
+    },
+    "./solid": {
+      "types": "./build/core/index.d.ts",
+      "default": "./build/core/index.js"
+    },
+    "./angular": {
+      "types": "./build-ngc/angular/index.d.ts",
+      "react-native": "./build-ngc/angular/index.js",
+      "default": "./src/angular/index.ts"
+    }
+  },
+  "files": [
+    "src",
+    "build",
+    "build-ngc",
+    "native-link.json",
+    "!src/**/*.test.*",
+    "!src/**/*.spec.*",
+    "!src/**/*.detox.*"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "dependencies": {
+    "expo-background-fetch": "57.0.15",
+    "expo-modules-core": "57.0.5",
+    "@symbiote-native/task-manager": "0.1.0"
+  },
+  "peerDependencies": {
+    "@angular/core": ">=20",
+    "@vue/runtime-core": "^3.5.13",
+    "react": ">=19.0.0",
+    "react-native": ">=0.86",
+    "solid-js": ">=1.9.0",
+    "svelte": ">=5.56.0",
+    "vue": ">=3.5.0",
+    "@symbiote-native/engine": "^1.3.0",
+    "@symbiote-native/angular": "^3.1.0",
+    "@symbiote-native/react": "^3.0.2",
+    "@symbiote-native/svelte": "^3.0.2",
+    "@symbiote-native/vue": "^3.0.2",
+    "@symbiote-native/solid": "^3.0.2"
+  },
+  "peerDependenciesMeta": {
+    "@symbiote-native/angular": {
+      "optional": true
+    },
+    "@symbiote-native/react": {
+      "optional": true
+    },
+    "@symbiote-native/solid": {
+      "optional": true
+    },
+    "@symbiote-native/svelte": {
+      "optional": true
+    },
+    "@symbiote-native/vue": {
+      "optional": true
+    },
+    "@angular/core": {
+      "optional": true
+    },
+    "@vue/runtime-core": {
+      "optional": true
+    },
+    "react": {
+      "optional": true
+    },
+    "solid-js": {
+      "optional": true
+    },
+    "svelte": {
+      "optional": true
+    },
+    "vue": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
+    "@angular/compiler": "~22.0.8",
+    "@angular/compiler-cli": "~22.0.8",
+    "@angular/core": "~22.0.8",
+    "@types/node": "^26.0.0",
+    "@types/react": "^19.2.0",
+    "@vue/runtime-core": "^3.5.13",
+    "react": "19.2.3",
+    "solid-js": "^1.9.14",
+    "svelte": "^5.56.0",
+    "typescript": "~6.0.0",
+    "@symbiote-native/engine": "1.3.0",
+    "@symbiote-native/svelte": "3.0.2",
+    "@symbiote-native/angular": "3.1.0",
+    "@symbiote-native/vue": "3.0.2",
+    "@symbiote-native/react": "3.0.2",
+    "@symbiote-native/solid": "3.0.2",
+    "@symbiote-native/test-utils": "0.4.2"
+  },
+  "scripts": {
+    "typecheck": "tsc --build",
+    "clean": "rm -rf build-ngc",
+    "ng:build": "pnpm run clean && ngc -p tsconfig.angular.json",
+    "format": "prettier --write \"src/**/*.{ts,tsx}\""
+  }
+}

package/src/angular/index.ts

@@ -0,0 +1,4 @@
+// @symbiote-native/background-fetch/angular: the Angular entry over the framework-agnostic core.
+// Same reasoning as the React/Vue entries — no per-instance state or event stream to wrap in a
+// service, so this is a plain re-export.
+export * from '../core';

package/src/core/background-fetch.ts

@@ -0,0 +1,86 @@
+import { Platform, UnavailabilityError } from 'expo-modules-core';
+import { isTaskDefined } from '@symbiote-native/task-manager';
+import { expoBackgroundFetch } from './native-module';
+import { BackgroundFetchStatus } from './types';
+import type { IBackgroundFetchOptions } from './types';
+
+const NATIVE_MODULE_NAME = 'BackgroundFetch';
+
+// expo-background-fetch is upstream-deprecated in favor of expo-background-task (still shipped
+// in sdk-57 alongside it, same as this project's file-system legacy+modern split) — carry the
+// same one-time console warning upstream shows, so an app that adopted the old API notices.
+let didShowDeprecationWarning = false;
+function warnDeprecated(): void {
+  if (didShowDeprecationWarning) return;
+  didShowDeprecationWarning = true;
+  console.warn(
+    '@symbiote-native/background-fetch: this API is deprecated. Use @symbiote-native/background-task instead.',
+  );
+}
+
+function assertValidTaskName(taskName: unknown): asserts taskName is string {
+  if (!taskName || typeof taskName !== 'string') {
+    throw new TypeError('`taskName` must be a non-empty string.');
+  }
+}
+
+// Upstream also warns when running inside Expo Go (`isRunningInExpoGo`, imported from the `expo`
+// meta-package). This project never installs `expo` — every app here is a bare/dev-client build,
+// never Expo Go — so that check has no equivalent and is intentionally not ported.
+
+/** Gets the current background-fetch status, or `null` if the native module is unreachable. */
+export async function getStatusAsync(): Promise<BackgroundFetchStatus | null> {
+  warnDeprecated();
+  if (Platform.OS === 'android') {
+    return BackgroundFetchStatus.Available;
+  }
+  if (!expoBackgroundFetch.getStatusAsync) {
+    throw new UnavailabilityError(NATIVE_MODULE_NAME, 'getStatusAsync');
+  }
+  return expoBackgroundFetch.getStatusAsync() as Promise<BackgroundFetchStatus>;
+}
+
+/**
+ * Sets the minimum number of seconds that must elapse before another background fetch can be
+ * initiated. Advisory only — iOS treats it as a floor, not an exact schedule. No effect on
+ * Android.
+ */
+export async function setMinimumIntervalAsync(
+  minimumInterval: number,
+): Promise<void> {
+  warnDeprecated();
+  if (!expoBackgroundFetch.setMinimumIntervalAsync) return;
+  await expoBackgroundFetch.setMinimumIntervalAsync(minimumInterval);
+}
+
+/**
+ * Registers a background-fetch task with the given name. The task must already be defined via
+ * `@symbiote-native/task-manager`'s `defineTask` — registration is driven by this package, but
+ * execution dispatch is task-manager's job.
+ */
+export async function registerTaskAsync(
+  taskName: string,
+  options: IBackgroundFetchOptions = {},
+): Promise<void> {
+  warnDeprecated();
+  if (!expoBackgroundFetch.registerTaskAsync) {
+    throw new UnavailabilityError(NATIVE_MODULE_NAME, 'registerTaskAsync');
+  }
+  if (!isTaskDefined(taskName)) {
+    throw new Error(
+      `Task '${taskName}' is not defined. You must define a task using defineTask (from @symbiote-native/task-manager) before registering.`,
+    );
+  }
+  assertValidTaskName(taskName);
+  await expoBackgroundFetch.registerTaskAsync(taskName, options);
+}
+
+/** Unregisters a background-fetch task, so the app stops receiving fetch callbacks for it. */
+export async function unregisterTaskAsync(taskName: string): Promise<void> {
+  warnDeprecated();
+  if (!expoBackgroundFetch.unregisterTaskAsync) {
+    throw new UnavailabilityError(NATIVE_MODULE_NAME, 'unregisterTaskAsync');
+  }
+  assertValidTaskName(taskName);
+  await expoBackgroundFetch.unregisterTaskAsync(taskName);
+}

package/src/core/index.ts

@@ -0,0 +1,8 @@
+export {
+  getStatusAsync,
+  setMinimumIntervalAsync,
+  registerTaskAsync,
+  unregisterTaskAsync,
+} from './background-fetch';
+export { BackgroundFetchResult, BackgroundFetchStatus } from './types';
+export type { IBackgroundFetchOptions } from './types';

package/src/core/native-module.ts

@@ -0,0 +1,22 @@
+import { requireNativeModule } from 'expo-modules-core';
+
+const EXPO_BACKGROUND_FETCH_MODULE_NAME = 'ExpoBackgroundFetch';
+
+// Every method is optional — each call site checks for its presence before calling through and
+// throws an UnavailabilityError itself, matching upstream's own per-platform capability checks
+// (same pattern as packages/task-manager/src/core/native-module.ts's INativeTaskManagerModule).
+export type INativeBackgroundFetchModule = {
+  getStatusAsync?(): Promise<number>;
+  /** iOS only — Android has no equivalent native call. */
+  setMinimumIntervalAsync?(minimumInterval: number): Promise<void>;
+  registerTaskAsync?(
+    taskName: string,
+    options: Record<string, unknown>,
+  ): Promise<void>;
+  unregisterTaskAsync?(taskName: string): Promise<void>;
+};
+
+export const expoBackgroundFetch =
+  requireNativeModule<INativeBackgroundFetchModule>(
+    EXPO_BACKGROUND_FETCH_MODULE_NAME,
+  );

package/src/core/types.ts

@@ -0,0 +1,49 @@
+/**
+ * What iOS does with the return value of a background-fetch task executor — lets the platform
+ * schedule future fetches more intelligently. Android ignores it (it has no equivalent concept).
+ */
+export enum BackgroundFetchResult {
+  /** There was no new data to download. */
+  NoData = 1,
+  /** New data was successfully downloaded. */
+  NewData = 2,
+  /** An attempt to download data was made but that attempt failed. */
+  Failed = 3,
+}
+
+/** Whether the app can currently receive background-fetch callbacks. */
+export enum BackgroundFetchStatus {
+  /** The user explicitly disabled background behavior for this app or for the whole system. */
+  Denied = 1,
+  /**
+   * Background updates are unavailable and the user cannot enable them again — e.g. parental
+   * controls are in effect for the current user.
+   */
+  Restricted = 2,
+  /** Background updates are available for the app. */
+  Available = 3,
+}
+
+/** Options accepted by {@link registerTaskAsync}. */
+export type IBackgroundFetchOptions = {
+  /**
+   * Inexact interval in seconds between subsequent repeats of the background fetch alarm. The
+   * final interval may differ from the specified one to minimize wakeups and battery usage.
+   * - Android defaults to 10 minutes.
+   * - iOS calls `setMinimumIntervalAsync` behind the scenes; the platform default is the
+   *   smallest fetch interval it supports (10-15 minutes).
+   */
+  minimumInterval?: number;
+  /**
+   * Whether to stop receiving background fetch events after the user terminates the app.
+   * @default true
+   * @platform android
+   */
+  stopOnTerminate?: boolean;
+  /**
+   * Whether to restart background fetch events when the device has finished booting.
+   * @default false
+   * @platform android
+   */
+  startOnBoot?: boolean;
+};