@logbrew/react-native 0.1.10 → 0.1.12

package/LogBrewReactNative.podspec

@@ -12,11 +12,33 @@ Pod::Spec.new do |spec|
   spec.platforms = { :ios => "13.0" }
   spec.source = {
     :git => "https://github.com/LogBrewCo/sdk.git",
-    :tag => "react-native-v#{spec.version}"
+    :tag => "js/logbrew-react-native/v#{spec.version}"
   }
-  spec.source_files = "ios/**/*.{h,m,mm}"
-  spec.exclude_files = "ios/Tests/**/*"
+  spec.default_subspecs = "Core"
+  spec.swift_versions = ["5.0"]
   spec.dependency "React-Core"
 
+  spec.subspec "Core" do |core|
+    core.source_files = "ios/**/*.{h,m,mm}"
+    core.exclude_files = [
+      "ios/AppleDiagnostics/**/*",
+      "ios/Tests/**/*"
+    ]
+  end
+
+  spec.subspec "AppleNativeDiagnostics" do |diagnostics|
+    diagnostics.ios.deployment_target = "15.0"
+    diagnostics.source_files = [
+      "ios/AppleDiagnostics/**/*.{h,m,mm,swift}",
+      "ios/GeneratedAppleDiagnostics/**/*.swift"
+    ]
+    diagnostics.dependency "#{spec.name}/Core"
+    diagnostics.dependency "KSCrash/Recording", "2.5.1"
+    diagnostics.pod_target_xcconfig = {
+      "DEFINES_MODULE" => "YES",
+      "SWIFT_VERSION" => "5.0"
+    }
+  end
+
   install_modules_dependencies(spec) if respond_to?(:install_modules_dependencies, true)
 end

package/README.md

@@ -6,7 +6,7 @@
 
 React Native helpers for the public LogBrew JavaScript SDK.
 
-This package is intentionally thin. It keeps all event validation, retry, flush, and shutdown behavior in `@logbrew/sdk`, while adding mobile-friendly helpers for screen views, app-state changes, product actions, API milestones, handled JavaScript errors, opt-in Hermes Promise rejection tracking, app-owned Promise rejection callbacks, provider/hook usage, active W3C trace correlation, explicit W3C trace propagation, opt-in lifecycle spans, opt-in resource fetch spans, opt-in reversible global fetch spans, app-owned native bridge scope sync, and reversible instrumentation setup.
+This package keeps event validation, retry, flush, and shutdown behavior in `@logbrew/sdk`. It adds mobile helpers for screen views, app-state changes, product actions, API milestones, bounded issue breadcrumbs, typed handled and unhandled JavaScript errors, Promise rejection tracking, provider and hook usage, W3C trace correlation and propagation, lifecycle spans, resource spans, reversible instrumentation, and opt-in Apple native crash and app-hang diagnostics.
 
 ## Install
 
@@ -118,6 +118,73 @@ client key before creating a new client. A `429` preserves the queue and
 reports `pausedReason: "rate_limit"` plus the bounded retry signal exposed by
 the failed flush.
 
+## Offline And Restart Delivery
+
+The React Native entry uses an app-private native queue by default when the
+current app binary contains the linked LogBrew module. Each accepted event is
+written before it enters memory. After a JavaScript runtime or app restart,
+the client loads pending events oldest first with their original IDs. A
+successful intake response commits which records were accepted before removing
+them, so an interrupted removal can cause a duplicate but cannot silently lose
+an unaccepted event. Replayed events keep their stable IDs. Delivery is at
+least once, so apps must tolerate duplicates, including when retries regroup
+events into different batches.
+
+Inspect the delivery health snapshot to observe the active behavior:
+
+```js
+const health = client.deliveryHealth();
+if (health.storage !== "persistent") {
+  // The app is running without the linked native queue.
+}
+```
+
+The default `persistentQueue: "auto"` mode uses memory when the native module
+is absent, including Expo Go and an older app binary after a JavaScript-only
+update. For a production build that must not start without restart recovery,
+set `persistentQueue: "required"`. Use `persistentQueue: "disabled"` only
+when the app intentionally accepts a memory-only queue.
+
+```js
+const client = createLogBrewReactNativeClient({
+  clientKey,
+  persistentQueue: "required",
+  transport: createReactNativeFetchTransport()
+});
+```
+
+The native queue stores one compact event per atomic record, is limited to
+1,000 events and 4 MiB of compact event data, and uses the same smaller limits
+when you configure them on the client. Both platforms use app-private storage.
+The client key is not written to disk; its SHA-256 digest separates queues
+after key rotation. The queue does not provide mathematically exactly-once
+delivery.
+
+A successful `shutdown()` drains and closes the queue. A failed flush or
+shutdown leaves the exact remainder available to the same client and the next
+app start. Call `client.purgePendingEvents()` only when no flush or shutdown is
+active. To retire an active key without sending its remainder, purge that
+client first and then close it:
+
+```js
+client.purgePendingEvents();
+await client.shutdown();
+```
+
+When no client owns the key, remove any remaining records explicitly with:
+
+```js
+import { purgeLogBrewReactNativePersistentQueue } from "@logbrew/react-native";
+
+purgeLogBrewReactNativePersistentQueue({ clientKey: previousClientKey });
+```
+
+Use only one active persistent client for a given key across an app process.
+The SDK rejects duplicates within one JavaScript runtime; apps with multiple
+React Native runtimes or platform processes must coordinate that ownership.
+Different client keys use separate native queues. The Node ESM and CommonJS
+entries remain platform-neutral and never load React Native.
+
 ## Product Actions And API Milestones
 
 Use explicit action and network helpers for important mobile funnel steps your app already understands. These events are designed for timelines and agent analysis without enabling broad automatic replay:
@@ -160,7 +227,7 @@ withLogBrewTrace(trace, () => {
 
 ## Error Capture
 
-Use `captureReactNativeError()` in app-owned error boundaries, route handlers, async catch blocks, or global handlers. It records handled JavaScript errors as LogBrew issue events with React Native context and omits stack text by default:
+Use `captureReactNativeError()` in app-owned error boundaries, route handlers, async catch blocks, or global handlers. It records a typed exception with `react-native.error`, `handled: true`, prior screen/app-state/action/network breadcrumbs, and React Native context. Global errors and Promise rejections use their own mechanism with `handled: false`. Raw stack text stays omitted by default:
 
 ```js
 import { captureReactNativeError } from "@logbrew/react-native";
@@ -202,7 +269,101 @@ Installation is idempotent for the active React Native `ErrorUtils` object. The
 
 The React Native conditional export obtains LogBrew's synchronous native fatal store through the supported TurboModule or `NativeModules` seam. Before chaining a fatal report, it writes one bounded record to app-private storage that is excluded from operating-system archives. On a later installation it performs stable-ID at-least-once replay, and acknowledgement happens only after local queue admission is observable through the SDK queue counters. Filtered, dropped, unknown-admission, persistence-failed, and acknowledgement-failed records are retained. A failed acknowledgement is retried without admitting the same ID twice in one JavaScript runtime. Use `fatalHealth()` for frozen bounded counters and status, or `discardPendingFatalRecord()` for an explicit rollback discard. The Node ESM and CommonJS entries never import React Native; non-React-Native callers must inject `fatalStore` explicitly.
 
-Automatic events exclude the original error message, raw stack, arbitrary metadata, full URLs, hosts, query strings, local absolute paths, payloads, and native error text. `onDiagnostic` receives only a fixed code. This integration does not claim mathematically exactly-once delivery, backend-visible deduplication, native crash capture, ANR or hang detection, general offline queueing, or symbolication.
+Automatic events exclude the original error message, raw stack, arbitrary metadata, full URLs, hosts, query strings, local absolute paths, payloads, and native error text. `onDiagnostic` receives only a fixed code. This error-handler integration does not claim mathematically exactly-once delivery, native crash capture, ANR or hang detection, general offline queueing by the fatal-record slot, or symbolication. The client-level persistent queue above owns normal event restart delivery.
+
+### Apple native crash and app-hang diagnostics
+
+Apple native diagnostics are an iOS-only, opt-in build feature. They capture a
+fatal native process crash and replay one privacy-bounded issue after the next
+launch. Set `hangThresholdSeconds` to also capture recovered or ongoing UIKit
+main-thread hangs. Android native crash and ANR capture are not included.
+
+For Expo prebuild or development builds, add the config plugin:
+
+```json
+{
+  "expo": {
+    "plugins": ["@logbrew/react-native/expo"]
+  }
+}
+```
+
+Then run your normal Expo prebuild or EAS build. Expo Go cannot load this native
+module. For a bare React Native app, add the optional subspec inside the app
+target in `ios/Podfile`, then run `pod install`:
+
+```ruby
+logbrew_react_native_path = File.dirname(`node --print "require.resolve('@logbrew/react-native')"`)
+pod 'LogBrewReactNative/AppleNativeDiagnostics', :path => logbrew_react_native_path
+```
+
+The default `LogBrewReactNative/Core` subspec remains unchanged and supports
+iOS 13. `AppleNativeDiagnostics` requires iOS 15. Install it on the main thread
+before root registration, then start replay:
+
+```js
+import {
+  installLogBrewAppleNativeDiagnostics,
+  replayLogBrewAppleNativeDiagnostics
+} from "@logbrew/react-native/apple-native-diagnostics";
+
+const nativeStatus = installLogBrewAppleNativeDiagnostics({
+  clientKey: process.env.EXPO_PUBLIC_LOGBREW_CLIENT_KEY,
+  projectId: "550e8400-e29b-41d4-a716-446655440000",
+  release: "com.example.app@1.2.3+45",
+  environment: "production",
+  service: "ios-app",
+  fatalHandlerOwnership: "logbrew",
+  hangThresholdSeconds: 2
+});
+
+void replayLogBrewAppleNativeDiagnostics().catch((error) => {
+  console.warn(error?.code ?? "native_diagnostics_failed");
+});
+```
+
+`fatalHandlerOwnership: "logbrew"` is an explicit process-lifetime ownership
+claim. Do not install these diagnostics while Sentry or another integration
+owns the native fatal signal or Mach exception handlers. Linking both SDKs is
+allowed, but only one integration may install native fatal capture in a given
+process. LogBrew cannot transfer or remove that ownership before process
+restart.
+
+Installation creates app-private, data-protected storage that iOS excludes from
+device data archives. Pending reports are partitioned by project, so changing
+the configured project does not replay an earlier project's records with the
+new project's key. The raw local KSCrash report can still contain sensitive
+process details, so apply the app's consent and retention policy to it. Hosted
+replay uploads only the bounded crash or hang issue described by the Swift
+`LogBrewCrash` contract. Status and error results expose fixed codes and bounded
+counters, not keys, paths, raw reports, or native error text. A custom endpoint
+must be a plain HTTPS path without embedded authentication, a query, or a fragment.
+
+Use the same project, release, environment, and service values for the runtime
+and its Apple dSYM. After signing in with `logbrew login`, upload and inspect
+the exact debug object with the released CLI:
+
+```bash
+logbrew debug-artifacts upload ios/build/MyApp.app.dSYM \
+  --project 550e8400-e29b-41d4-a716-446655440000 \
+  --release com.example.app@1.2.3+45 \
+  --environment production \
+  --service ios-app \
+  --json
+
+logbrew debug-artifacts lookup \
+  --project 550e8400-e29b-41d4-a716-446655440000 \
+  --release com.example.app@1.2.3+45 \
+  --environment production \
+  --service ios-app \
+  --image-uuid <mach_o_uuid> \
+  --architecture arm64 \
+  --json
+```
+
+The SDK does not upload debug objects during a build or at runtime. Hosted
+symbolication begins only after the exact Mach-O UUID and architecture lookup
+succeeds.
 
 ### Opt-in Hermes Promise rejection tracking
 
@@ -387,6 +548,8 @@ export function App({ client }) {
 }
 ```
 
+Screen views carry the versioned `screen_view` analytics classification, and explicit product actions carry `interaction`. The SDK uses the app-owned screen name as a bounded surface and does not inspect view hierarchies, selectors, or input values. Caller metadata cannot replace the reserved classification. See the repository [product analytics capture contract](../../docs/product-analytics-contract.md).
+
 The package ships a `react-native` entry that imports `AppState` and `Platform` for Metro, while the default Node entry accepts those dependencies explicitly. That keeps mobile setup explicit instead of pretending a Node process is a native runtime.
 
 ## Trace Propagation
@@ -714,7 +877,14 @@ uploadLogBrewReactNativeReleaseArtifacts({
 
 The helper requires explicit `release`, `environment`, `service`, and `platform` metadata. Hosted uploads also require a UUID `projectId`; local preparation and loopback upload remain valid without it. It defaults minified bundle URLs to `app:///react-native/<platform>/...`, removes query strings and hashes from manifest URLs, and strips source paths under `root` or `stripSourcePrefix`. Hosted endpoints must use HTTPS and must not include embedded auth values, query strings, or fragments. The helper never uses normal SDK ingest keys or account/session API auth values. When `sourcemap` points at a final Hermes-composed map, the helper makes the bundle's `sourceMappingURL` point at that explicit map, so stale packager-map comments do not block manifest generation. The explicit Metro wrapper changes only app-owned serialization and one bounded runtime Debug-ID registry; neither helper patches Gradle, Xcode, global fetch/XHR, request payloads, or transport behavior.
 
-React Native native symbols are handled as release artifacts, not runtime telemetry. For local dry-run validation, use the repo release-artifact tooling against app-owned build outputs such as `ios/build/.../*.dSYM`, `android/app/build/outputs/mapping/release/mapping.txt`, and `android/app/build/intermediates/merged_native_libs/.../*.so`. The current public SDK validates metadata and privacy boundaries only; backend upload, storage, lookup, and native symbolication are still backend-owned future support, so do not rely on normal runtime error capture for native crash symbolication yet.
+React Native native symbols are release artifacts, not runtime telemetry. Use
+the repository release-artifact tooling for local dry-run checks of app-owned
+outputs such as `ios/build/.../*.dSYM`, Android mapping files, and native shared
+objects. Apple dSYM upload, storage, exact UUID and architecture lookup, and
+hosted symbolication are available through `logbrew debug-artifacts`. The SDK
+does not upload those artifacts automatically. Normal JavaScript error capture
+does not produce native crash symbolication; use the opt-in Apple diagnostics
+flow above with an exact uploaded dSYM.
 
 ## Example Source