@lucida-analytics/react-native 0.0.0-stage → 0.1.0

package/LICENSE

@@ -0,0 +1,202 @@
+                                 Apache License
+                           Version 2.0, January 2004
+                        http://www.apache.org/licenses/
+
+   TERMS AND CONDITIONS FOR USE, REPRODUCTION, AND DISTRIBUTION
+
+   1. Definitions.
+
+      "License" shall mean the terms and conditions for use, reproduction,
+      and distribution as defined by Sections 1 through 9 of this document.
+
+      "Licensor" shall mean the copyright owner or entity authorized by
+      the copyright owner that is granting the License.
+
+      "Legal Entity" shall mean the union of the acting entity and all
+      other entities that control, are controlled by, or are under common
+      control with that entity. For the purposes of this definition,
+      "control" means (i) the power, direct or indirect, to cause the
+      direction or management of such entity, whether by contract or
+      otherwise, or (ii) ownership of fifty percent (50%) or more of the
+      outstanding shares, or (iii) beneficial ownership of such entity.
+
+      "You" (or "Your") shall mean an individual or Legal Entity
+      exercising permissions granted by this License.
+
+      "Source" form shall mean the preferred form for making modifications,
+      including but not limited to software source code, documentation
+      source, and configuration files.
+
+      "Object" form shall mean any form resulting from mechanical
+      transformation or translation of a Source form, including but
+      not limited to compiled object code, generated documentation,
+      and conversions to other media types.
+
+      "Work" shall mean the work of authorship, whether in Source or
+      Object form, made available under the License, as indicated by a
+      copyright notice that is included in or attached to the work
+      (an example is provided in the Appendix below).
+
+      "Derivative Works" shall mean any work, whether in Source or Object
+      form, that is based on (or derived from) the Work and for which the
+      editorial revisions, annotations, elaborations, or other modifications
+      represent, as a whole, an original work of authorship. For the purposes
+      of this License, Derivative Works shall not include works that remain
+      separable from, or merely link (or bind by name) to the interfaces of,
+      the Work and Derivative Works thereof.
+
+      "Contribution" shall mean any work of authorship, including
+      the original version of the Work and any modifications or additions
+      to that Work or Derivative Works thereof, that is intentionally
+      submitted to Licensor for inclusion in the Work by the copyright owner
+      or by an individual or Legal Entity authorized to submit on behalf of
+      the copyright owner. For the purposes of this definition, "submitted"
+      means any form of electronic, verbal, or written communication sent
+      to the Licensor or its representatives, including but not limited to
+      communication on electronic mailing lists, source code control systems,
+      and issue tracking systems that are managed by, or on behalf of, the
+      Licensor for the purpose of discussing and improving the Work, but
+      excluding communication that is conspicuously marked or otherwise
+      designated in writing by the copyright owner as "Not a Contribution."
+
+      "Contributor" shall mean Licensor and any individual or Legal Entity
+      on behalf of whom a Contribution has been received by Licensor and
+      subsequently incorporated within the Work.
+
+   2. Grant of Copyright License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      copyright license to reproduce, prepare Derivative Works of,
+      publicly display, publicly perform, sublicense, and distribute the
+      Work and such Derivative Works in Source or Object form.
+
+   3. Grant of Patent License. Subject to the terms and conditions of
+      this License, each Contributor hereby grants to You a perpetual,
+      worldwide, non-exclusive, no-charge, royalty-free, irrevocable
+      (except as stated in this section) patent license to make, have made,
+      use, offer to sell, sell, import, and otherwise transfer the Work,
+      where such license applies only to those patent claims licensable
+      by such Contributor that are necessarily infringed by their
+      Contribution(s) alone or by combination of their Contribution(s)
+      with the Work to which such Contribution(s) was submitted. If You
+      institute patent litigation against any entity (including a
+      cross-claim or counterclaim in a lawsuit) alleging that the Work
+      or a Contribution incorporated within the Work constitutes direct
+      or contributory patent infringement, then any patent licenses
+      granted to You under this License for that Work shall terminate
+      as of the date such litigation is filed.
+
+   4. Redistribution. You may reproduce and distribute copies of the
+      Work or Derivative Works thereof in any medium, with or without
+      modifications, and in Source or Object form, provided that You
+      meet the following conditions:
+
+      (a) You must give any other recipients of the Work or
+          Derivative Works a copy of this License; and
+
+      (b) You must cause any modified files to carry prominent notices
+          stating that You changed the files; and
+
+      (c) You must retain, in the Source form of any Derivative Works
+          that You distribute, all copyright, patent, trademark, and
+          attribution notices from the Source form of the Work,
+          excluding those notices that do not pertain to any part of
+          the Derivative Works; and
+
+      (d) If the Work includes a "NOTICE" text file as part of its
+          distribution, then any Derivative Works that You distribute must
+          include a readable copy of the attribution notices contained
+          within such NOTICE file, excluding those notices that do not
+          pertain to any part of the Derivative Works, in at least one
+          of the following places: within a NOTICE text file distributed
+          as part of the Derivative Works; within the Source form or
+          documentation, if provided along with the Derivative Works; or,
+          within a display generated by the Derivative Works, if and
+          wherever such third-party notices normally appear. The contents
+          of the NOTICE file are for informational purposes only and
+          do not modify the License. You may add Your own attribution
+          notices within Derivative Works that You distribute, alongside
+          or as an addendum to the NOTICE text from the Work, provided
+          that such additional attribution notices cannot be construed
+          as modifying the License.
+
+      You may add Your own copyright statement to Your modifications and
+      may provide additional or different license terms and conditions
+      for use, reproduction, or distribution of Your modifications, or
+      for any such Derivative Works as a whole, provided Your use,
+      reproduction, and distribution of the Work otherwise complies with
+      the conditions stated in this License.
+
+   5. Submission of Contributions. Unless You explicitly state otherwise,
+      any Contribution intentionally submitted for inclusion in the Work
+      by You to the Licensor shall be under the terms and conditions of
+      this License, without any additional terms or conditions.
+      Notwithstanding the above, nothing herein shall supersede or modify
+      the terms of any separate license agreement you may have executed
+      with Licensor regarding such Contributions.
+
+   6. Trademarks. This License does not grant permission to use the trade
+      names, trademarks, service marks, or product names of the Licensor,
+      except as required for reasonable and customary use in describing the
+      origin of the Work and reproducing the content of the NOTICE file.
+
+   7. Disclaimer of Warranty. Unless required by applicable law or
+      agreed to in writing, Licensor provides the Work (and each
+      Contributor provides its Contributions) on an "AS IS" BASIS,
+      WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or
+      implied, including, without limitation, any warranties or conditions
+      of TITLE, NON-INFRINGEMENT, MERCHANTABILITY, or FITNESS FOR A
+      PARTICULAR PURPOSE. You are solely responsible for determining the
+      appropriateness of using or redistributing the Work and assume any
+      risks associated with Your exercise of permissions under this License.
+
+   8. Limitation of Liability. In no event and under no legal theory,
+      whether in tort (including negligence), contract, or otherwise,
+      unless required by applicable law (such as deliberate and grossly
+      negligent acts) or agreed to in writing, shall any Contributor be
+      liable to You for damages, including any direct, indirect, special,
+      incidental, or consequential damages of any character arising as a
+      result of this License or out of the use or inability to use the
+      Work (including but not limited to damages for loss of goodwill,
+      work stoppage, computer failure or malfunction, or any and all
+      other commercial damages or losses), even if such Contributor
+      has been advised of the possibility of such damages.
+
+   9. Accepting Warranty or Additional Liability. While redistributing
+      the Work or Derivative Works thereof, You may choose to offer,
+      and charge a fee for, acceptance of support, warranty, indemnity,
+      or other liability obligations and/or rights consistent with this
+      License. However, in accepting such obligations, You may act only
+      on Your own behalf and on Your sole responsibility, not on behalf
+      of any other Contributor, and only if You agree to indemnify,
+      defend, and hold each Contributor harmless for any liability
+      incurred by, or claims asserted against, such Contributor by reason
+      of your accepting any such warranty or additional liability.
+
+   END OF TERMS AND CONDITIONS
+
+   APPENDIX: How to apply the Apache License to your work.
+
+      To apply the Apache License to your work, attach the following
+      boilerplate notice, with the fields enclosed by brackets "[]"
+      replaced with your own identifying information. (Don't include
+      the brackets!)  The text should be enclosed in the appropriate
+      comment syntax for the file format. We also recommend that a
+      file or class name and description of purpose be included on the
+      same "printed page" as the copyright notice for easier
+      identification within third-party archives.
+
+   Copyright [yyyy] [name of copyright owner]
+
+   Licensed under the Apache License, Version 2.0 (the "License");
+   you may not use this file except in compliance with the License.
+   You may obtain a copy of the License at
+
+       http://www.apache.org/licenses/LICENSE-2.0
+
+   Unless required by applicable law or agreed to in writing, software
+   distributed under the License is distributed on an "AS IS" BASIS,
+   WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+   See the License for the specific language governing permissions and
+   limitations under the License.
+

package/README.md

@@ -1,3 +1,170 @@
-# Temporary Holding Version
+# @lucida-analytics/react-native
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+React Native SDK on top of `@lucida-analytics/sdk-core` (queue, batching, retry, identity, sessions, consent,
+local flag evaluation). Native modules are injected, never imported, so the package has no native
+dependency and tests run without React Native.
+
+```tsx
+import AsyncStorage from "@react-native-async-storage/async-storage";
+import { AppState } from "react-native";
+import { LucidaProvider, useFeatureFlag, useCapture } from "@lucida-analytics/react-native";
+
+<LucidaProvider apiKey="lc_pk_..." options={{
+  apiHost: "https://ingest.example.com",
+  asyncStorage: AsyncStorage, appState: AppState,
+  appVersion: "1.4.0", platform: "ios",
+}}>
+  <App />
+</LucidaProvider>
+```
+
+Or imperatively: `const client = await createClient(key, config)` (storage hydrates first, hence async).
+
+## Features
+
+- **Capture**: `POST /v1/batch`, 20 events / 5 s, retry with backoff, offline batches persisted to
+  AsyncStorage (`offlineTransport`). No gzip (React Native has no `CompressionStream`).
+- **Lifecycle** (`appState` adapter): `$app_opened`, `$app_backgrounded` (flushes),
+  `$app_installed`, `$app_updated` (needs `appVersion`).
+- **Identity/consent**: `identify`, `alias`, `reset`, `register*`, `group`, `optIn`/`optOut`. With
+  `consent: { mode: "opt_in" }` nothing is written to AsyncStorage or sent before consent.
+- **Flags**: `localFlags` evaluated on device (same evaluator and vectors as the web SDK), the rest via
+  `POST /v1/flags`. Hooks: `useFeatureFlag`, `useFeatureFlagVariant`, `useFeatureFlagPayload`,
+  `useActiveFeatureFlags`, `FeatureGate`.
+- **Screens**: `useScreen("Home")`, or react-navigation (optional peer):
+
+```tsx
+const ref = useNavigationContainerRef();
+const { onReady, onStateChange } = screenTracker(client, ref);
+<NavigationContainer ref={ref} onReady={onReady} onStateChange={onStateChange} />
+```
+
+Route params are not sent unless `includeParams: true` (they often contain PII).
+
+## Install attribution
+
+Pass `installInfo: () => NativeModules.LucidaReplay.installInfo()` to `createClient` and the first-open
+`$app_installed` carries: Android Play Install Referrer (`$install_store=google_play`, `$install_referrer`,
+`$install_referrer_click_ts`, `$install_begin_ts`, parsed `$utm_*`, click ids `$gclid`/`$gbraid`/`$wbraid`/`$fbclid`/
+`$ttclid`/`$msclkid`) or iOS Apple Search Ads via AdServices (`$install_store=app_store`, `$install_adservices_attribution`,
+`$utm_*`, `$asa_*`; the token is POSTed as text/plain with a 10 s timeout, 404 retried). Any failure still sends the
+event with `$install_store` only. Disable with `installAttribution: false`. The Android module needs
+`com.android.installreferrer:installreferrer` (Apache-2.0) in the app's Gradle dependencies. Pure parsers are exported:
+`installReferrerProps`, `appStoreInstallProps`.
+
+## Hooks, person profiles, flags, privacy, autocapture
+
+- `beforeSend: [hook, ...]`: ordered `(event) => event | null`; return a changed event to amend, `null` to drop. A hook that throws is
+  logged (when `debug`) and skipped: the event continues as it was before that hook. `sampleHook(0.1)` keeps ~10% and adds `$sample_rate`.
+  Hooks run as events enter the queue (a wrapper on the queue's `enqueue`, since `@lucida-analytics/sdk-core` is shared with the web SDK).
+- `personProfiles`: `"always"` (default), `"identified_only"` (events carry `$process_person_profile: false` until identify, alias, group or
+  a person-property write; persisted, cleared by `reset()`), `"never"` (identify/alias/setPersonProperties are no-ops with a debug warning, `$set` is stripped).
+- Flags: `flagOptions: { bootstrap: { distinctId, isIdentified, flags, payloads }, sendFeatureFlagEvent, preload, evaluationContexts }`,
+  `disableRemoteFeatureFlags: true` (never calls `/v1/flags`) with `client.updateFlags(flags, payloads, { merge })` for flags your own backend
+  evaluated, `onFlags`, `setPersonPropertiesForFlags(props, reload?)`, `setGroupPropertiesForFlags`, reset variants.
+- Interventions: `client.onIntervention((i) => ...)` receives in-session interventions fired for this person (`{id, name, event, payload, fired_at}`);
+  polls `GET /v1/interventions` every 15 s while a listener is set, after analytics consent. See `docs/guides/interventions.md`.
+- Queue/network: `flushAt`, `flushIntervalMs`, `maxQueueSize`, `maxBatchSize`, `maxRetries`, `retryDelayMs`, `requestTimeoutMs`,
+  `dataMode: "wifi"` + `network: { isWifi() }` (inject NetInfo), `sessionIdleMs` / `sessionMaxMs`, `disableGeoip`, `disabled`, `client.debug(true)`.
+- Person helpers: `setPersonProperties`, `capture(event, props, { set, setOnce })`, `getAnonymousId`, `reuseAnonymousId`, `isOptedOut`, `openURL(url, referrer)` (`$deep_link_opened`).
+- Tracing headers: `tracingHeaders: ["api.example.com", ".corp.io"]`, then call your backend through `client.fetch` to add
+  `X-Lucida-Distinct-Id` / `X-Lucida-Session-Id` (never to the Lucida host; analytics consent required).
+- Autocapture: `autocapture: { enabled: true, ignoreLabels, maxElements, propsAllowList, customLabelProp, noCaptureProp, rageTap }`, then
+  `<View onTouchEnd={touchHandler(client.autocapture)}>` at the root. Elements are the touched fiber's ancestors that carry an
+  `accessibilityLabel` / `testID`; `<View lucidaNoCapture>` excludes a subtree. It reads React internals (`_targetInst`), so treat it as best effort.
+  Text-field values are never read. `$rageclick` fires after repeated taps.
+- Replay privacy: `replay: { maskText, maskAllTextInputs, maskAllImages, maskSandboxedViews, sampleRate, throttleMs }` (the native modules receive the mask flags),
+  `client.replay.start()/stop()/isRecording()`.
+
+Not built: push registration (needs a scope decision).
+
+## Session replay (wireframe)
+
+Off by default. The native view hierarchy is encoded natively by the Lucida iOS / Android SDK wireframe
+encoder (inputs and secure fields never carry text; other text is starred unless `maskText: false`); this package
+owns consent (analytics **and** replay), session/window ids, `seq` (resets when the session rotates), structure
+dedupe and delivery to `POST /v1/replay`.
+
+```tsx
+import { NativeModules } from "react-native";
+createClient("lc_pk_...", { replay: { enabled: true, module: NativeModules.LucidaReplay, snapshotIntervalMs: 5000 } });
+```
+
+Screenshot mode: `replay: { mode: "screenshot", screenshotQuality: 0.4 }`. The native module draws the window into a
+bitmap, paints inputs, secure fields, `<LucidaMask>` views, images and (unless `maskText: false`) text over, and only then
+encodes JPEG (the same `ScreenshotCapture` / `UIKitScreenshot` code the native SDKs use); at most one frame a second.
+
+Native contract (`NativeReplayModule` in `src/replay.ts`): `captureWireframe({ screen, maskText, maskAllTextInputs, maskAllImages, maskSandboxedViews }): Promise<string>` (plus `mode: "screenshot", screenshotQuality` in screenshot mode)
+resolves JSON text `{"width","height","events":[meta (type 4), fullSnapshot (type 2)]}`, or `""` when nothing can
+be captured. Reference implementations, linked as ordinary React Native native modules:
+
+- iOS: `ios/LucidaReplay.swift` + `.m`, calling `ReplayBridge.capture` from the `Lucida` Swift package (add it as a pod/SPM dependency).
+- Android: `android/src/main/kotlin/com/lucida/reactnative/LucidaReplayModule.kt`, calling `WireframeCapture.capture`
+  from `lucida-android`; register the module in a `ReactPackage` of your app.
+
+These two files are not compiled in this repository (no React Native toolchain); everything they call is covered
+by `swift test` (ReplayBridgeTests) and `make sdk-android` (ReplayBridgeTest). Verify them in a real app before shipping.
+
+### Session replay: privacy additions
+
+Every remote value below arrives in `GET /v1/config` and only ever adds masking to what the app configured.
+
+- **Masked screens** (P-M17): `replay: { maskScreens: ["Checkout", "Pay*"] }` plus the project's `replay_mask_screens`
+  (case-insensitive, `*` = any run of characters, whole screen name as passed to `client.screen`). On a matching screen the
+  native encoder masks every text, input value and image whatever `maskText` or `<LucidaUnmask>` say (`maskScreen: true` in
+  the capture options); screenshots paint them all over.
+- **Text patterns** (P-M46): `replay: { maskTextPatterns: ["\\d{4,}"] }` plus `replay_mask_text_patterns` (regular
+  expressions; one that does not compile is ignored). The native encoder stars matches in shown text and paints matching views
+  in screenshots (`maskTextPatterns` in the capture options); JS stars them again in the returned wireframe.
+- **`$dead_swipe`** (P-M46, `captureDeadSwipes`, default true, fed by `<LucidaTouchCapture>` or
+  `client.replay.swipeBegan()` / `swipeEnded(dx, dy)`): a swipe of 48 pt or more after which the starred wireframe is unchanged
+  ~700 ms later. Properties: `$screen_name`, `$swipe_direction` (`left|right|up|down`), `$swipe_distance`. Never text or
+  view content; at most one per 2 s.
+- **Controlled exposure** (P-L12): when the project sends `replay_exposure_fields` and `replay_exposure_key`,
+  `client.captureSensitive("card_number", value)` (field = your `testID`) encrypts the value natively with RSA-OAEP-SHA256
+  (`encryptSensitive(pkcs1, n, e, plain)`, a blocking synchronous method of the LucidaReplay module) and sends
+  `$sensitive_capture` (`$exposure_field`, `$exposure_kid`, `$exposure_ciphertext`, `$screen_name`, `$exposure_truncated`
+  when cut to 190 bytes). Only an audited reveal on the server can read it. Never pass a secure field; identical values are
+  sent once per session; nothing is persisted; a missing or failing native method sends nothing.
+
+### Encrypting the offline queue at rest
+
+The same native module exposes two blocking synchronous methods, `encryptQueue` / `decryptQueue`: AES-256-GCM with a key the
+platform keeps (iOS Keychain via the iOS SDK's `KeychainQueueCipher`, Android Keystore via `KeystoreQueueCipher`), generated on
+first use. Wire it with `nativeQueueCipher`:
+
+```ts
+createClient("lc_pk_...", { asyncStorage, queueCipher: nativeQueueCipher(NativeModules.LucidaReplay) });
+```
+
+Only the offline queue (`lc_offline`) is encrypted. A lost or rotated key reads as an empty queue, and a native failure on
+encrypt stores an empty value, never plaintext. Blocking sync methods need JSI, so they do not work under the remote JS debugger.
+Covered by `test/native-cipher.test.ts` (native module mocked with real AES-GCM); the native halves are verified in step 5 below.
+
+### Verifying the native modules in a real app (G35)
+
+Not done in this repository (no RN toolchain, no Xcode/Gradle builds on the dev disk). Exact steps:
+
+1. `npx @react-native-community/cli init LucidaProbe` (RN >= 0.74), then `pnpm add file:<repo>/sdks/react-native` (or `pnpm pack` it).
+2. iOS: add the `Lucida` Swift package (`sdks/ios`) via SPM, copy `ios/LucidaReplay.swift` and `LucidaReplay.m` into the app target
+   (create a bridging header if Xcode asks), `cd ios && pod install`, build for a simulator. Expect: it compiles; `NativeModules.LucidaReplay.captureWireframe({screen:"Home",maskText:true})` resolves JSON starting `{"width"`.
+3. Android: add `include ':lucida-android'` / `project(':lucida-android').projectDir = new File('<repo>/sdks/android/lucida-android')` and the `lucida-core` module,
+   copy `android/src/main/kotlin/com/lucida/reactnative/*.kt`, register the package in `MainApplication`, `./gradlew :app:assembleDebug`. Expect the same JSON.
+4. In JS: `createClient("lc_pk_...", { replay: { enabled: true, module: NativeModules.LucidaReplay }, flagStream: true })`, grant consent, open a screen, and confirm
+   `POST /v1/replay` chunks arrive and `GET /v1/flags/stream` connects (RN's `fetch` usually cannot stream response bodies; then the SDK silently polls every `pollMs`).
+5. Queue cipher: with `queueCipher: nativeQueueCipher(NativeModules.LucidaReplay)` go offline, capture an event, and confirm the `lc_offline` AsyncStorage value is
+   opaque base64 (no event name in it) and that the event is delivered after reconnecting and an app restart.
+6. Native unit coverage that exists today: `swift test` (sdks/ios, ReplayBridgeTests) and `make sdk-android` (ReplayBridgeTest).
+
+## In-app guides
+
+Kinds `modal`, `banner`, `announcement`, `slideout`, `tour`, `carousel` (Back / Next with a slide pager) and, with an
+anchoring presenter, `tooltip` / `hotspot`. A step's `native_id` anchors it to a native view: wrap it in `<GuideAnchor testID="checkout">` (React Native cannot look views up by testID from JS) and mount `<LucidaGuides />` as the last child of the app root: the bubble is drawn next
+to the view and follows it on scroll and relayout; a hotspot is a pulsing dot that opens the step. When the view does not
+appear within `wait_ms` (default 3 s, max 15 s) the SDK sends `$guide_target_missing {step_id, selector}` and shows the step
+unanchored; a view gone for 2 s closes the step. The resolved `appearance` tokens (background, text, accent, radius,
+font) apply, with `appearance.dark.tokens` when `theme_mode` is dark, or auto and the device is dark.
+
+## Out of scope
+
+Push registration and attribution.

package/android/src/main/kotlin/com/lucida/reactnative/LucidaReplayModule.kt

@@ -0,0 +1,96 @@
+package com.lucida.reactnative
+
+import com.facebook.react.bridge.Arguments
+import com.facebook.react.bridge.Promise
+import com.facebook.react.bridge.ReactApplicationContext
+import com.facebook.react.bridge.ReactContextBaseJavaModule
+import com.facebook.react.bridge.ReactMethod
+import com.facebook.react.bridge.ReadableMap
+import com.facebook.react.bridge.UiThreadUtil
+import com.lucida.android.KeystoreQueueCipher
+import com.lucida.android.WireframeCapture
+import com.lucida.core.ExposureKey
+import com.lucida.core.SensitiveCapture
+
+/**
+ * React Native module `NativeModules.LucidaReplay`. Contract: see src/replay.ts (NativeReplayModule).
+ * Not compiled in this repository's CI (needs the React Native toolchain); the logic it calls
+ * (WireframeCapture -> ViewHierarchy -> ReplayBridge -> Wireframe, KeystoreQueueCipher) is covered by `make sdk-android`.
+ */
+class LucidaReplayModule(ctx: ReactApplicationContext) : ReactContextBaseJavaModule(ctx) {
+    override fun getName() = "LucidaReplay"
+
+    // Android Keystore AES-256-GCM key, created on first use; same ciphertext format as the Android SDK's queue cipher.
+    private val cipher by lazy { KeystoreQueueCipher() }
+
+    /** Blocking on purpose: the JS queue storage is synchronous (see src/native-cipher.ts). Fails closed with "". */
+    @ReactMethod(isBlockingSynchronousMethod = true)
+    fun encryptQueue(plain: String): String = runCatching { cipher.encrypt(plain) }.getOrDefault("")
+
+    /** null when the value cannot be decrypted (key lost or rotated); the queue then starts empty. */
+    @ReactMethod(isBlockingSynchronousMethod = true)
+    fun decryptQueue(value: String): String? = runCatching { cipher.decrypt(value) }.getOrNull()
+
+    /** Blocking synchronous (P-L12, src/sensitive.ts): RSA-OAEP with SHA-256 and MGF1-SHA-256 over (n, e); "" on failure. */
+    @ReactMethod(isBlockingSynchronousMethod = true)
+    fun encryptSensitive(pkcs1: String, n: String, e: String, plain: String): String =
+        SensitiveCapture.encrypt(plain.toByteArray(Charsets.UTF_8), ExposureKey("", n, e, pkcs1)) ?: ""
+
+    /**
+     * Install attribution (src/install.ts): resolves `{platform: "android", referrer, clickTs, beginTs}` from the Play Install
+     * Referrer, or null when the library is absent or the service is unavailable. Needs `com.android.installreferrer:installreferrer`.
+     */
+    @ReactMethod
+    fun installInfo(promise: Promise) {
+        try {
+            val client = com.android.installreferrer.api.InstallReferrerClient.newBuilder(reactApplicationContext).build()
+            client.startConnection(object : com.android.installreferrer.api.InstallReferrerStateListener {
+                override fun onInstallReferrerSetupFinished(code: Int) {
+                    try {
+                        val m = Arguments.createMap()
+                        m.putString("platform", "android")
+                        if (code == com.android.installreferrer.api.InstallReferrerClient.InstallReferrerResponse.OK) {
+                            val r = client.installReferrer
+                            m.putString("referrer", r.installReferrer)
+                            m.putDouble("clickTs", r.referrerClickTimestampSeconds.toDouble())
+                            m.putDouble("beginTs", r.installBeginTimestampSeconds.toDouble())
+                        }
+                        promise.resolve(m)
+                    } catch (_: Throwable) {
+                        promise.resolve(null)
+                    }
+                    try { client.endConnection() } catch (_: Throwable) {}
+                }
+
+                override fun onInstallReferrerServiceDisconnected() = Unit
+            })
+        } catch (_: Throwable) { // includes NoClassDefFoundError
+            promise.resolve(null)
+        }
+    }
+
+    /** Resolves the JSON text of one wireframe (or masked screenshot) capture, or "" when there is no resumed Activity. */
+    @ReactMethod
+    fun captureWireframe(options: ReadableMap, promise: Promise) {
+        val screen = if (options.hasKey("screen")) options.getString("screen") ?: "Unknown" else "Unknown"
+        val maskText = if (options.hasKey("maskText")) options.getBoolean("maskText") else true
+        fun flag(k: String) = if (options.hasKey(k)) options.getBoolean(k) else true
+        val maskInputs = flag("maskAllTextInputs")
+        val maskImages = flag("maskAllImages")
+        val maskSandboxed = flag("maskSandboxedViews")
+        // Screenshot mode: JPEG quality 0..100; masks are painted on the bitmap before it is encoded (ScreenshotCapture).
+        val shots = options.hasKey("mode") && options.getString("mode") == "screenshot"
+        val quality = if (!shots) null else Math.round(100 * (if (options.hasKey("screenshotQuality")) options.getDouble("screenshotQuality") else 0.4)).toInt()
+        val maskScreen = options.hasKey("maskScreen") && options.getBoolean("maskScreen")  // P-M17
+        val patterns = if (options.hasKey("maskTextPatterns")) options.getArray("maskTextPatterns")?.toArrayList()?.filterIsInstance<String>() ?: emptyList() else emptyList()  // P-M46
+        val activity = currentActivity
+        if (activity == null) {
+            promise.resolve("")
+            return
+        }
+        // View access must happen on the main thread.
+        UiThreadUtil.runOnUiThread {
+            promise.resolve(runCatching { WireframeCapture.capture(activity, screen, maskText, maskInputs, maskImages, maskSandboxed, quality, maskScreen, patterns) }.getOrDefault(""))
+        }
+    }
+}