react-native-audio-browser 0.0.1 → 0.1.0-next.1

package/nitrogen/generated/shared/c++/TransformableRequestConfig.hpp

@@ -0,0 +1,124 @@
+///
+/// TransformableRequestConfig.hpp
+/// This file was generated by nitrogen. DO NOT MODIFY THIS FILE.
+/// https://github.com/mrousavy/nitro
+/// Copyright © Marc Rousavy @ Margelo
+///
+
+#pragma once
+
+#if __has_include(<NitroModules/JSIConverter.hpp>)
+#include <NitroModules/JSIConverter.hpp>
+#else
+#error NitroModules cannot be found! Are you sure you installed NitroModules properly?
+#endif
+#if __has_include(<NitroModules/NitroDefines.hpp>)
+#include <NitroModules/NitroDefines.hpp>
+#else
+#error NitroModules cannot be found! Are you sure you installed NitroModules properly?
+#endif
+#if __has_include(<NitroModules/JSIHelpers.hpp>)
+#include <NitroModules/JSIHelpers.hpp>
+#else
+#error NitroModules cannot be found! Are you sure you installed NitroModules properly?
+#endif
+#if __has_include(<NitroModules/PropNameIDCache.hpp>)
+#include <NitroModules/PropNameIDCache.hpp>
+#else
+#error NitroModules cannot be found! Are you sure you installed NitroModules properly?
+#endif
+
+// Forward declaration of `RequestConfig` to properly resolve imports.
+namespace margelo::nitro::audiobrowser { struct RequestConfig; }
+// Forward declaration of `HttpMethod` to properly resolve imports.
+namespace margelo::nitro::audiobrowser { enum class HttpMethod; }
+
+#include "RequestConfig.hpp"
+#include <NitroModules/Promise.hpp>
+#include <string>
+#include <unordered_map>
+#include <optional>
+#include <functional>
+#include "HttpMethod.hpp"
+
+namespace margelo::nitro::audiobrowser {
+
+  /**
+   * A struct which can be represented as a JavaScript object (TransformableRequestConfig).
+   */
+  struct TransformableRequestConfig final {
+  public:
+    std::optional<std::function<std::shared_ptr<Promise<std::shared_ptr<Promise<RequestConfig>>>>(const RequestConfig& /* request */, const std::optional<std::unordered_map<std::string, std::string>>& /* routeParams */)>> transform     SWIFT_PRIVATE;
+    std::optional<HttpMethod> method     SWIFT_PRIVATE;
+    std::optional<std::string> path     SWIFT_PRIVATE;
+    std::optional<std::string> baseUrl     SWIFT_PRIVATE;
+    std::optional<std::unordered_map<std::string, std::string>> headers     SWIFT_PRIVATE;
+    std::optional<std::unordered_map<std::string, std::string>> query     SWIFT_PRIVATE;
+    std::optional<std::string> body     SWIFT_PRIVATE;
+    std::optional<std::string> contentType     SWIFT_PRIVATE;
+    std::optional<std::string> userAgent     SWIFT_PRIVATE;
+
+  public:
+    TransformableRequestConfig() = default;
+    explicit TransformableRequestConfig(std::optional<std::function<std::shared_ptr<Promise<std::shared_ptr<Promise<RequestConfig>>>>(const RequestConfig& /* request */, const std::optional<std::unordered_map<std::string, std::string>>& /* routeParams */)>> transform, std::optional<HttpMethod> method, std::optional<std::string> path, std::optional<std::string> baseUrl, std::optional<std::unordered_map<std::string, std::string>> headers, std::optional<std::unordered_map<std::string, std::string>> query, std::optional<std::string> body, std::optional<std::string> contentType, std::optional<std::string> userAgent): transform(transform), method(method), path(path), baseUrl(baseUrl), headers(headers), query(query), body(body), contentType(contentType), userAgent(userAgent) {}
+
+  public:
+    // TransformableRequestConfig is not equatable because these properties are not equatable: transform
+  };
+
+} // namespace margelo::nitro::audiobrowser
+
+namespace margelo::nitro {
+
+  // C++ TransformableRequestConfig <> JS TransformableRequestConfig (object)
+  template <>
+  struct JSIConverter<margelo::nitro::audiobrowser::TransformableRequestConfig> final {
+    static inline margelo::nitro::audiobrowser::TransformableRequestConfig fromJSI(jsi::Runtime& runtime, const jsi::Value& arg) {
+      jsi::Object obj = arg.asObject(runtime);
+      return margelo::nitro::audiobrowser::TransformableRequestConfig(
+        JSIConverter<std::optional<std::function<std::shared_ptr<Promise<std::shared_ptr<Promise<margelo::nitro::audiobrowser::RequestConfig>>>>(const margelo::nitro::audiobrowser::RequestConfig&, const std::optional<std::unordered_map<std::string, std::string>>&)>>>::fromJSI(runtime, obj.getProperty(runtime, PropNameIDCache::get(runtime, "transform"))),
+        JSIConverter<std::optional<margelo::nitro::audiobrowser::HttpMethod>>::fromJSI(runtime, obj.getProperty(runtime, PropNameIDCache::get(runtime, "method"))),
+        JSIConverter<std::optional<std::string>>::fromJSI(runtime, obj.getProperty(runtime, PropNameIDCache::get(runtime, "path"))),
+        JSIConverter<std::optional<std::string>>::fromJSI(runtime, obj.getProperty(runtime, PropNameIDCache::get(runtime, "baseUrl"))),
+        JSIConverter<std::optional<std::unordered_map<std::string, std::string>>>::fromJSI(runtime, obj.getProperty(runtime, PropNameIDCache::get(runtime, "headers"))),
+        JSIConverter<std::optional<std::unordered_map<std::string, std::string>>>::fromJSI(runtime, obj.getProperty(runtime, PropNameIDCache::get(runtime, "query"))),
+        JSIConverter<std::optional<std::string>>::fromJSI(runtime, obj.getProperty(runtime, PropNameIDCache::get(runtime, "body"))),
+        JSIConverter<std::optional<std::string>>::fromJSI(runtime, obj.getProperty(runtime, PropNameIDCache::get(runtime, "contentType"))),
+        JSIConverter<std::optional<std::string>>::fromJSI(runtime, obj.getProperty(runtime, PropNameIDCache::get(runtime, "userAgent")))
+      );
+    }
+    static inline jsi::Value toJSI(jsi::Runtime& runtime, const margelo::nitro::audiobrowser::TransformableRequestConfig& arg) {
+      jsi::Object obj(runtime);
+      obj.setProperty(runtime, PropNameIDCache::get(runtime, "transform"), JSIConverter<std::optional<std::function<std::shared_ptr<Promise<std::shared_ptr<Promise<margelo::nitro::audiobrowser::RequestConfig>>>>(const margelo::nitro::audiobrowser::RequestConfig&, const std::optional<std::unordered_map<std::string, std::string>>&)>>>::toJSI(runtime, arg.transform));
+      obj.setProperty(runtime, PropNameIDCache::get(runtime, "method"), JSIConverter<std::optional<margelo::nitro::audiobrowser::HttpMethod>>::toJSI(runtime, arg.method));
+      obj.setProperty(runtime, PropNameIDCache::get(runtime, "path"), JSIConverter<std::optional<std::string>>::toJSI(runtime, arg.path));
+      obj.setProperty(runtime, PropNameIDCache::get(runtime, "baseUrl"), JSIConverter<std::optional<std::string>>::toJSI(runtime, arg.baseUrl));
+      obj.setProperty(runtime, PropNameIDCache::get(runtime, "headers"), JSIConverter<std::optional<std::unordered_map<std::string, std::string>>>::toJSI(runtime, arg.headers));
+      obj.setProperty(runtime, PropNameIDCache::get(runtime, "query"), JSIConverter<std::optional<std::unordered_map<std::string, std::string>>>::toJSI(runtime, arg.query));
+      obj.setProperty(runtime, PropNameIDCache::get(runtime, "body"), JSIConverter<std::optional<std::string>>::toJSI(runtime, arg.body));
+      obj.setProperty(runtime, PropNameIDCache::get(runtime, "contentType"), JSIConverter<std::optional<std::string>>::toJSI(runtime, arg.contentType));
+      obj.setProperty(runtime, PropNameIDCache::get(runtime, "userAgent"), JSIConverter<std::optional<std::string>>::toJSI(runtime, arg.userAgent));
+      return obj;
+    }
+    static inline bool canConvert(jsi::Runtime& runtime, const jsi::Value& value) {
+      if (!value.isObject()) {
+        return false;
+      }
+      jsi::Object obj = value.getObject(runtime);
+      if (!nitro::isPlainObject(runtime, obj)) {
+        return false;
+      }
+      if (!JSIConverter<std::optional<std::function<std::shared_ptr<Promise<std::shared_ptr<Promise<margelo::nitro::audiobrowser::RequestConfig>>>>(const margelo::nitro::audiobrowser::RequestConfig&, const std::optional<std::unordered_map<std::string, std::string>>&)>>>::canConvert(runtime, obj.getProperty(runtime, PropNameIDCache::get(runtime, "transform")))) return false;
+      if (!JSIConverter<std::optional<margelo::nitro::audiobrowser::HttpMethod>>::canConvert(runtime, obj.getProperty(runtime, PropNameIDCache::get(runtime, "method")))) return false;
+      if (!JSIConverter<std::optional<std::string>>::canConvert(runtime, obj.getProperty(runtime, PropNameIDCache::get(runtime, "path")))) return false;
+      if (!JSIConverter<std::optional<std::string>>::canConvert(runtime, obj.getProperty(runtime, PropNameIDCache::get(runtime, "baseUrl")))) return false;
+      if (!JSIConverter<std::optional<std::unordered_map<std::string, std::string>>>::canConvert(runtime, obj.getProperty(runtime, PropNameIDCache::get(runtime, "headers")))) return false;
+      if (!JSIConverter<std::optional<std::unordered_map<std::string, std::string>>>::canConvert(runtime, obj.getProperty(runtime, PropNameIDCache::get(runtime, "query")))) return false;
+      if (!JSIConverter<std::optional<std::string>>::canConvert(runtime, obj.getProperty(runtime, PropNameIDCache::get(runtime, "body")))) return false;
+      if (!JSIConverter<std::optional<std::string>>::canConvert(runtime, obj.getProperty(runtime, PropNameIDCache::get(runtime, "contentType")))) return false;
+      if (!JSIConverter<std::optional<std::string>>::canConvert(runtime, obj.getProperty(runtime, PropNameIDCache::get(runtime, "userAgent")))) return false;
+      return true;
+    }
+  };
+
+} // namespace margelo::nitro

package/nitrogen/generated/shared/c++/UpdateOptions.hpp

@@ -0,0 +1,111 @@
+///
+/// UpdateOptions.hpp
+/// This file was generated by nitrogen. DO NOT MODIFY THIS FILE.
+/// https://github.com/mrousavy/nitro
+/// Copyright © Marc Rousavy @ Margelo
+///
+
+#pragma once
+
+#if __has_include(<NitroModules/JSIConverter.hpp>)
+#include <NitroModules/JSIConverter.hpp>
+#else
+#error NitroModules cannot be found! Are you sure you installed NitroModules properly?
+#endif
+#if __has_include(<NitroModules/NitroDefines.hpp>)
+#include <NitroModules/NitroDefines.hpp>
+#else
+#error NitroModules cannot be found! Are you sure you installed NitroModules properly?
+#endif
+#if __has_include(<NitroModules/JSIHelpers.hpp>)
+#include <NitroModules/JSIHelpers.hpp>
+#else
+#error NitroModules cannot be found! Are you sure you installed NitroModules properly?
+#endif
+#if __has_include(<NitroModules/PropNameIDCache.hpp>)
+#include <NitroModules/PropNameIDCache.hpp>
+#else
+#error NitroModules cannot be found! Are you sure you installed NitroModules properly?
+#endif
+
+// Forward declaration of `AndroidUpdateOptions` to properly resolve imports.
+namespace margelo::nitro::audiobrowser { struct AndroidUpdateOptions; }
+// Forward declaration of `PlayerCapabilities` to properly resolve imports.
+namespace margelo::nitro::audiobrowser { struct PlayerCapabilities; }
+
+#include "AndroidUpdateOptions.hpp"
+#include <optional>
+#include <NitroModules/Null.hpp>
+#include <variant>
+#include "PlayerCapabilities.hpp"
+#include <vector>
+
+namespace margelo::nitro::audiobrowser {
+
+  /**
+   * A struct which can be represented as a JavaScript object (UpdateOptions).
+   */
+  struct UpdateOptions final {
+  public:
+    std::optional<AndroidUpdateOptions> android     SWIFT_PRIVATE;
+    std::optional<double> forwardJumpInterval     SWIFT_PRIVATE;
+    std::optional<double> backwardJumpInterval     SWIFT_PRIVATE;
+    std::optional<std::variant<nitro::NullType, double>> progressUpdateEventInterval     SWIFT_PRIVATE;
+    std::optional<PlayerCapabilities> capabilities     SWIFT_PRIVATE;
+    std::optional<std::vector<double>> iosPlaybackRates     SWIFT_PRIVATE;
+
+  public:
+    UpdateOptions() = default;
+    explicit UpdateOptions(std::optional<AndroidUpdateOptions> android, std::optional<double> forwardJumpInterval, std::optional<double> backwardJumpInterval, std::optional<std::variant<nitro::NullType, double>> progressUpdateEventInterval, std::optional<PlayerCapabilities> capabilities, std::optional<std::vector<double>> iosPlaybackRates): android(android), forwardJumpInterval(forwardJumpInterval), backwardJumpInterval(backwardJumpInterval), progressUpdateEventInterval(progressUpdateEventInterval), capabilities(capabilities), iosPlaybackRates(iosPlaybackRates) {}
+
+  public:
+    friend bool operator==(const UpdateOptions& lhs, const UpdateOptions& rhs) = default;
+  };
+
+} // namespace margelo::nitro::audiobrowser
+
+namespace margelo::nitro {
+
+  // C++ UpdateOptions <> JS UpdateOptions (object)
+  template <>
+  struct JSIConverter<margelo::nitro::audiobrowser::UpdateOptions> final {
+    static inline margelo::nitro::audiobrowser::UpdateOptions fromJSI(jsi::Runtime& runtime, const jsi::Value& arg) {
+      jsi::Object obj = arg.asObject(runtime);
+      return margelo::nitro::audiobrowser::UpdateOptions(
+        JSIConverter<std::optional<margelo::nitro::audiobrowser::AndroidUpdateOptions>>::fromJSI(runtime, obj.getProperty(runtime, PropNameIDCache::get(runtime, "android"))),
+        JSIConverter<std::optional<double>>::fromJSI(runtime, obj.getProperty(runtime, PropNameIDCache::get(runtime, "forwardJumpInterval"))),
+        JSIConverter<std::optional<double>>::fromJSI(runtime, obj.getProperty(runtime, PropNameIDCache::get(runtime, "backwardJumpInterval"))),
+        JSIConverter<std::optional<std::variant<nitro::NullType, double>>>::fromJSI(runtime, obj.getProperty(runtime, PropNameIDCache::get(runtime, "progressUpdateEventInterval"))),
+        JSIConverter<std::optional<margelo::nitro::audiobrowser::PlayerCapabilities>>::fromJSI(runtime, obj.getProperty(runtime, PropNameIDCache::get(runtime, "capabilities"))),
+        JSIConverter<std::optional<std::vector<double>>>::fromJSI(runtime, obj.getProperty(runtime, PropNameIDCache::get(runtime, "iosPlaybackRates")))
+      );
+    }
+    static inline jsi::Value toJSI(jsi::Runtime& runtime, const margelo::nitro::audiobrowser::UpdateOptions& arg) {
+      jsi::Object obj(runtime);
+      obj.setProperty(runtime, PropNameIDCache::get(runtime, "android"), JSIConverter<std::optional<margelo::nitro::audiobrowser::AndroidUpdateOptions>>::toJSI(runtime, arg.android));
+      obj.setProperty(runtime, PropNameIDCache::get(runtime, "forwardJumpInterval"), JSIConverter<std::optional<double>>::toJSI(runtime, arg.forwardJumpInterval));
+      obj.setProperty(runtime, PropNameIDCache::get(runtime, "backwardJumpInterval"), JSIConverter<std::optional<double>>::toJSI(runtime, arg.backwardJumpInterval));
+      obj.setProperty(runtime, PropNameIDCache::get(runtime, "progressUpdateEventInterval"), JSIConverter<std::optional<std::variant<nitro::NullType, double>>>::toJSI(runtime, arg.progressUpdateEventInterval));
+      obj.setProperty(runtime, PropNameIDCache::get(runtime, "capabilities"), JSIConverter<std::optional<margelo::nitro::audiobrowser::PlayerCapabilities>>::toJSI(runtime, arg.capabilities));
+      obj.setProperty(runtime, PropNameIDCache::get(runtime, "iosPlaybackRates"), JSIConverter<std::optional<std::vector<double>>>::toJSI(runtime, arg.iosPlaybackRates));
+      return obj;
+    }
+    static inline bool canConvert(jsi::Runtime& runtime, const jsi::Value& value) {
+      if (!value.isObject()) {
+        return false;
+      }
+      jsi::Object obj = value.getObject(runtime);
+      if (!nitro::isPlainObject(runtime, obj)) {
+        return false;
+      }
+      if (!JSIConverter<std::optional<margelo::nitro::audiobrowser::AndroidUpdateOptions>>::canConvert(runtime, obj.getProperty(runtime, PropNameIDCache::get(runtime, "android")))) return false;
+      if (!JSIConverter<std::optional<double>>::canConvert(runtime, obj.getProperty(runtime, PropNameIDCache::get(runtime, "forwardJumpInterval")))) return false;
+      if (!JSIConverter<std::optional<double>>::canConvert(runtime, obj.getProperty(runtime, PropNameIDCache::get(runtime, "backwardJumpInterval")))) return false;
+      if (!JSIConverter<std::optional<std::variant<nitro::NullType, double>>>::canConvert(runtime, obj.getProperty(runtime, PropNameIDCache::get(runtime, "progressUpdateEventInterval")))) return false;
+      if (!JSIConverter<std::optional<margelo::nitro::audiobrowser::PlayerCapabilities>>::canConvert(runtime, obj.getProperty(runtime, PropNameIDCache::get(runtime, "capabilities")))) return false;
+      if (!JSIConverter<std::optional<std::vector<double>>>::canConvert(runtime, obj.getProperty(runtime, PropNameIDCache::get(runtime, "iosPlaybackRates")))) return false;
+      return true;
+    }
+  };
+
+} // namespace margelo::nitro

package/package.json

@@ -1,9 +1,120 @@
 {
   "name": "react-native-audio-browser",
-  "version": "0.0.1",
-  "description": "React Native audio module with browsable navigation trees and native Android Auto/CarPlay integration.",
-  "main": "index.js",
-  "repository": "https://github.com/radio-garden/react-native-audio-browser",
-  "author": "Radio Garden <jonathan@radio.garden>",
-  "license": "MIT"
+  "version": "0.1.0-next.1",
+  "description": "react-native-audio-browser is a react native package built with Nitro",
+  "keywords": [
+    "react-native",
+    "react-native-audio-browser"
+  ],
+  "homepage": "https://github.com/radio-garden/react-native-audio-browser#readme",
+  "bugs": "https://github.com/radio-garden/react-native-audio-browser/issues",
+  "license": "MIT",
+  "author": "puckey",
+  "repository": "https://github.com/radio-garden/react-native-audio-browser.git",
+  "source": "src/index",
+  "workspaces": [
+    "apps/*",
+    "docs"
+  ],
+  "files": [
+    "src",
+    "react-native.config.js",
+    "lib",
+    "nitrogen",
+    "cpp",
+    "nitro.json",
+    "android/build.gradle",
+    "android/fix-prefab.gradle",
+    "android/gradle.properties",
+    "android/CMakeLists.txt",
+    "android/src",
+    "ios/**/*.h",
+    "ios/**/*.m",
+    "ios/**/*.mm",
+    "ios/**/*.cpp",
+    "ios/**/*.swift",
+    "app.plugin.js",
+    "*.podspec",
+    "README.md"
+  ],
+  "type": "module",
+  "main": "./lib/commonjs/index.js",
+  "module": "./lib/module/index.js",
+  "types": "./lib/typescript/src/index.d.ts",
+  "react-native": "src/index",
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org/"
+  },
+  "scripts": {
+    "android:format": "yarn workspace example-native android:format",
+    "android:ide": "yarn workspace example-native android:ide",
+    "android:logs": "react-native log-android",
+    "android:test": "yarn workspace example-native android:test",
+    "build": "yarn prepare",
+    "clean": "del-cli android/build example/android/build example/android/app/build example/ios/build lib",
+    "codegen": "node codegen/index.js --logLevel=\"debug\" && node post-script.cjs && yarn build",
+    "prepare": "bob build",
+    "example": "yarn workspace example-native",
+    "ci:format": "prettier --check src",
+    "ci:lint": "oxlint src",
+    "format": "oxfmt --write",
+    "ios:format": "swiftformat ios",
+    "ios:ide": "yarn workspace example-native ios:ide",
+    "ios:rebuild": "yarn workspace example-native ios:rebuild",
+    "ios:test": "swift test",
+    "lint": "oxlint --fix",
+    "release": "semantic-release",
+    "test": "vitest run",
+    "types": "tsc --noEmit"
+  },
+  "devDependencies": {
+    "@react-native-community/cli": "15.0.0-alpha.2",
+    "@semantic-release/changelog": "^6.0.3",
+    "@semantic-release/git": "^10.0.1",
+    "@types/react": "19.1.1",
+    "conventional-changelog-conventionalcommits": "^9.3.0",
+    "del-cli": "^5.1.0",
+    "nitrogen": "0.35.0",
+    "oxfmt": "^0.27.0",
+    "oxlint": "^1.42.0",
+    "oxlint-tsgolint": "^0.11.2",
+    "prettier": "^3.0.3",
+    "react": "19.1.1",
+    "react-native": "0.83.0",
+    "react-native-builder-bob": "^0.37.0",
+    "react-native-monorepo-config": "^0.3.1",
+    "react-native-nitro-modules": "0.35.0",
+    "semantic-release": "^25.0.3",
+    "shaka-player": "^4.15.4",
+    "typescript": "^5.8.3",
+    "typescript-eslint": "^8.46.0",
+    "vitest": "^4.0.18"
+  },
+  "peerDependencies": {
+    "react": "*",
+    "react-native": "*",
+    "react-native-nitro-modules": "*",
+    "shaka-player": "^4.7.9"
+  },
+  "peerDependenciesMeta": {
+    "shaka-player": {
+      "optional": true
+    }
+  },
+  "packageManager": "yarn@4.12.0",
+  "react-native-builder-bob": {
+    "source": "src",
+    "output": "lib",
+    "targets": [
+      "commonjs",
+      "module",
+      [
+        "typescript",
+        {
+          "project": "tsconfig.json"
+        }
+      ]
+    ]
+  }
 }

package/src/AudioBrowser.ts

@@ -0,0 +1,4 @@
+export * from './features'
+export * from './native'
+export * from './types'
+export * from './utils/useDebug'

package/src/features/battery.ts

@@ -0,0 +1,176 @@
+/**
+ * Battery optimization status and warning handling for Android 12+ foreground service restrictions.
+ *
+ * When an external controller (Bluetooth, car head unit) tries to resume playback while the app
+ * is killed and battery restrictions are in place, Android 12+ blocks the foreground service start.
+ * This module exposes APIs to detect this condition and guide users to fix their settings.
+ */
+
+import { nativeBrowser } from '../native'
+import { NativeUpdatedValue } from '../utils/NativeUpdatedValue'
+import { useNativeUpdatedValue } from '../utils/useNativeUpdatedValue'
+
+// MARK: - Types
+
+/**
+ * Battery optimization status.
+ *
+ * - `unrestricted`: App can run freely in background. User explicitly allowed it.
+ * - `optimized`: System may limit background work (Doze, App Standby). Default state.
+ * - `restricted`: User or system severely limited background. Services blocked.
+ */
+export type BatteryOptimizationStatus =
+  | 'unrestricted'
+  | 'optimized'
+  | 'restricted'
+
+/**
+ * Event fired when battery warning pending state changes.
+ */
+export type BatteryWarningPendingChangedEvent = {
+  pending: boolean
+}
+
+/**
+ * Event fired when battery optimization status changes.
+ */
+export type BatteryOptimizationStatusChangedEvent = {
+  status: BatteryOptimizationStatus
+}
+
+// MARK: - Getters
+
+/**
+ * Check if a battery warning is pending (Android only).
+ * Returns true if a foreground service start was blocked and the user hasn't dismissed
+ * the warning or fixed their battery settings.
+ * Auto-clears when battery status becomes unrestricted.
+ * @returns true if warning is pending, always false on iOS
+ */
+export function getBatteryWarningPending(): boolean {
+  return nativeBrowser.getBatteryWarningPending()
+}
+
+/**
+ * Get the current battery optimization status (Android only).
+ * Also fires onBatteryOptimizationStatusChanged if status changed since last call.
+ * @returns Current status, always 'unrestricted' on iOS
+ */
+export function getBatteryOptimizationStatus(): BatteryOptimizationStatus {
+  return nativeBrowser.getBatteryOptimizationStatus()
+}
+
+// MARK: - Actions
+
+/**
+ * Dismiss the battery warning without fixing settings (Android only).
+ * Call this when the user chooses to ignore the warning.
+ * No-op on iOS.
+ */
+export function dismissBatteryWarning(): void {
+  nativeBrowser.dismissBatteryWarning()
+}
+
+/**
+ * Open the system battery settings for this app (Android only).
+ * No-op on iOS.
+ */
+export function openBatterySettings(): void {
+  nativeBrowser.openBatterySettings()
+}
+
+// MARK: - Event Callbacks
+
+/**
+ * Subscribes to battery warning pending state changes (Android only).
+ * Fires when: failure occurs (true), dismissBatteryWarning() called (false),
+ * or status becomes unrestricted (false).
+ * Never fires on iOS.
+ */
+export const onBatteryWarningPendingChanged =
+  NativeUpdatedValue.emitterize<BatteryWarningPendingChangedEvent>(
+    (cb) => (nativeBrowser.onBatteryWarningPendingChanged = cb)
+  )
+
+/**
+ * Subscribes to battery optimization status changes (Android only).
+ * Fires when user returns from settings with a different status.
+ * Never fires on iOS.
+ */
+export const onBatteryOptimizationStatusChanged =
+  NativeUpdatedValue.emitterize<BatteryOptimizationStatusChangedEvent>(
+    (cb) => (nativeBrowser.onBatteryOptimizationStatusChanged = cb)
+  )
+
+// MARK: - Hooks
+
+/**
+ * Hook that returns whether a battery warning is pending and updates when it changes (Android only).
+ * @returns true if warning is pending, always false on iOS
+ */
+export function useBatteryWarningPending(): boolean {
+  return useNativeUpdatedValue(
+    getBatteryWarningPending,
+    onBatteryWarningPendingChanged,
+    'pending'
+  )
+}
+
+/**
+ * Hook that returns the current battery optimization status and updates when it changes (Android only).
+ * @returns Current status, always 'unrestricted' on iOS
+ */
+export function useBatteryOptimizationStatus(): BatteryOptimizationStatus {
+  return useNativeUpdatedValue(
+    getBatteryOptimizationStatus,
+    onBatteryOptimizationStatusChanged,
+    'status'
+  )
+}
+
+/**
+ * Return type for useBatteryWarning hook.
+ */
+export interface BatteryWarning {
+  /** Whether a battery warning is pending */
+  pending: boolean
+  /** Current battery optimization status */
+  status: BatteryOptimizationStatus
+  /** Dismiss the warning without changing settings */
+  dismiss: () => void
+  /** Open system battery settings for this app */
+  openSettings: () => void
+}
+
+/**
+ * Meta hook that bundles all battery warning state and actions (Android only).
+ * Use this for a complete battery warning UI implementation.
+ *
+ * @example
+ * ```tsx
+ * function BatteryWarningBanner() {
+ *   const { pending, status, dismiss, openSettings } = useBatteryWarning()
+ *
+ *   if (!pending) return null
+ *
+ *   return (
+ *     <View>
+ *       <Text>Battery status: {status}</Text>
+ *       <Button onPress={openSettings} title="Fix" />
+ *       <Button onPress={dismiss} title="Dismiss" />
+ *     </View>
+ *   )
+ * }
+ * ```
+ */
+export function useBatteryWarning(): BatteryWarning {
+  const pending = useBatteryWarningPending()
+  const status = useBatteryOptimizationStatus()
+
+  return {
+    pending,
+    status,
+    dismiss: dismissBatteryWarning,
+    openSettings: openBatterySettings
+  }
+}