@absolutejs/devices-capacitor
Capacitor implementations for the provider-neutral @absolutejs/devices
contracts. AbsoluteJS installs this adapter in the generated mobile shell;
application code continues to import from @absolutejs/devices.
The release-candidate adapter covers:
- app metadata and native platform identity;
- app state, native resume, and Android restored-operation delivery;
- launch URLs, inbound links, and audited HTTP(S) external browser opening;
- native network status and change events;
- Android hardware-back events with an explicit capability check; and
- namespaced ordinary preferences that never clear another package's keys; and
- an Absolute-owned native credential vault backed by iOS Keychain and Android Keystore AES-256-GCM encryption; plus
- opt-in Clipboard, Share, Haptics, Camera, and scoped photo-picker provider slices; and
- opt-in foreground Geolocation with approximate/precise permission reporting, one-shot reads, watched updates, and deterministic cleanup.
- opt-in Documents selection, native share/save export, and native preview with bounded cache staging and deterministic cleanup.
- opt-in Local Notifications with explicit permission, best-effort one-time scheduling, cancellation, pending inspection, and receipt/tap events.
- opt-in Push Notifications through Capacitor 8.1.2, with provider tokens confined to the generated authenticated registration bridge.
- opt-in Keyboard 8.0.5 visibility/height events and dismissal, plus the Capacitor 8 core SystemBars API for modern edge-to-edge status/navigation UI.
Preferences is never used for credentials. On a native build the adapter
selects AbsoluteSecureStorage automatically when Capacitor has registered the
bundled plugin. Browser previews remain unavailable/fail-closed. Advanced hosts
can still pass a different audited provider through secureStorage.
import { installCapacitorDeviceAdapterIfNative } from "@absolutejs/devices-capacitor";
const remove = installCapacitorDeviceAdapterIfNative();
The conditional helper returns null in a browser preview, preserving the core
web adapter. AbsoluteJS owns this bootstrap call; application code normally does
not invoke it.
Optional capabilities are intentionally separate exports:
import { createCapacitorClipboardCapability } from "@absolutejs/devices-capacitor/clipboard";
import {
createCapacitorCameraCapability,
createCapacitorPhotosCapability,
} from "@absolutejs/devices-capacitor/camera";
import { createCapacitorHapticsCapability } from "@absolutejs/devices-capacitor/haptics";
import { createCapacitorKeyboardCapability } from "@absolutejs/devices-capacitor/keyboard";
import { createCapacitorLocationCapability } from "@absolutejs/devices-capacitor/location";
import { createCapacitorLocalNotificationsCapability } from "@absolutejs/devices-capacitor/local-notifications";
import { createCapacitorPushNotificationsCapability } from "@absolutejs/devices-capacitor/push-notifications";
import { createCapacitorDocumentsCapability } from "@absolutejs/devices-capacitor/documents";
import { createCapacitorShareCapability } from "@absolutejs/devices-capacitor/share";
import { createCapacitorSystemBarsCapability } from "@absolutejs/devices-capacitor/system-bars";
The absolutejs.devices field in this package's package.json declares the
factory, exact tested Capacitor dependency, and native permission purposes for
each slice. The AbsoluteJS CLI consumes that metadata, generates imports and iOS
usage descriptions, and leaves Android free of unnecessary camera/storage
permissions. Foreground location adds only coarse/fine Android permissions and
the provider-required iOS usage strings. Users keep importing the
provider-neutral facade only. The base
entry does not import these plugins.
System bars use Capacitor 8's core edge-to-edge API rather than the legacy
Status Bar plugin. Public light/dark values name foreground icon/text color,
avoiding the provider enum's background-oriented wording. Browser appearance is
best-effort through color-scheme; browser chrome visibility fails explicitly.
Documents use the WebView's system-backed file input for scoped selection, so
selected content remains Blob-backed and path-free. Export and preview stage a
bounded file only in Capacitor's cache directory, call the official Share or
File Viewer plugin, and then erase the staged file. AbsoluteJS generates and
targets the Filesystem plugin's required Apple privacy manifest entry
(NSPrivacyAccessedAPICategoryFileTimestamp, reason C617.1) from package
metadata; users do not edit Xcode or PrivacyInfo.xcprivacy.
Camera permission is never prompted implicitly: portable application code calls
camera.requestPermission() from an intentional user action before
camera.takePhoto(). photos.pick() opens the selected-item system picker and
does not request broad photo-library access. Captures are not saved to the
gallery and EXIF metadata is not returned by this first slice.
Location permission is also explicit. The adapter does not start a watch during bootstrap, never claims background delivery, preserves approximate versus precise access, and maps disabled services, policy restriction, timeout, and provider failures into the shared device error vocabulary. Every successful watch returns an idempotent cleanup function that clears the native provider watch.
Local Notifications uses the complete official Capacitor 8.2.1 release. The
adapter checks permission before every schedule and never lets the provider
prompt implicitly. AbsoluteJS installs the plugin only when application code
imports localNotifications; Android's display permission is projected from
provider metadata. This first contract intentionally uses inexact best-effort
schedules, so it does not request exact-alarm permissions or imply critical
delivery. Notification content and data must never contain secrets.
Push Notifications uses the official Capacitor 8.1.2 plugin. AbsoluteJS
projects the Android 13 display permission, validates and copies the Firebase
google-services.json for the configured application ID, adds the iOS APNs
entitlement, and installs Capacitor's AppDelegate registration forwarding. Raw
APNs/FCM tokens are accepted only by the adapter's internal registration sink;
@absolutejs/devices application code cannot read them. The server returns an
opaque installation identity that the shell retains in Keychain/Keystore for
rotation and authenticated removal.
The JavaScript contract and native sources are tested in CI; release acceptance still requires the real iOS/Android simulator checklist because native Keychain and Keystore behavior cannot be proven by a browser test runner.