@koderlabs/tasks-sdk-rn-native 0.1.0 → 0.1.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (2) hide show
  1. package/README.md +104 -5
  2. package/package.json +5 -5
package/README.md CHANGED
@@ -1,9 +1,108 @@
1
- # Proprietary Software
1
+ # @koderlabs/tasks-sdk-rn-native
2
2
 
3
- KoderLabs proprietary. All rights reserved.
3
+ > Runtime: React Native on iOS / Android via an Expo prebuild (EAS Build or `expo prebuild`). Will not work in Expo Go (managed runtime cannot load native code). Not a JS-only package. Companion to `@koderlabs/tasks-sdk-rn`.
4
4
 
5
- See the bundled `LICENSE` for terms. No grant of any rights, express or
6
- implied, is conferred by access to or possession of this package. A
7
- separate signed written licence from KoderLabs is required for any use.
5
+ Captures **native crashes** that escape the JS runtime — segfaults, ObjC `NSException`s, Android `Throwable`s — plus an opt-in Android ANR watchdog. Reports are written to disk by the native side and drained on next launch by `@koderlabs/tasks-sdk-rn` (`captureNativeCrash: true`).
6
+
7
+ ## What it captures
8
+
9
+ **iOS (PLCrashReporter bundled as a Pod):**
10
+
11
+ - Mach exceptions
12
+ - BSD signals (`SIGSEGV`, `SIGBUS`, `SIGABRT`, `SIGFPE`, `SIGILL`, `SIGPIPE`, `SIGTRAP`)
13
+ - ObjC `NSException`s
14
+
15
+ **Android (JNI signal handler — `libtasks_native_crash.so`):**
16
+
17
+ - `SIGSEGV`, `SIGBUS`, `SIGABRT`, `SIGFPE`, `SIGILL` with backtrace addresses
18
+ - Optional ANR watchdog thread (opt-in; OS-level ANR detection is usually enough)
19
+
20
+ ## Install
21
+
22
+ ```bash
23
+ pnpm add @koderlabs/tasks-sdk @koderlabs/tasks-sdk-rn @koderlabs/tasks-sdk-rn-native
24
+ ```
25
+
26
+ Then register the Expo config plugin in `app.json` / `app.config.ts`:
27
+
28
+ ```jsonc
29
+ {
30
+ "expo": {
31
+ "plugins": ["@koderlabs/tasks-sdk-rn-native"]
32
+ }
33
+ }
34
+ ```
35
+
36
+ Prebuild:
37
+
38
+ ```bash
39
+ npx expo prebuild --clean
40
+ # or: eas build
41
+ ```
42
+
43
+ ## Usage
44
+
45
+ ```ts
46
+ // App.tsx — early bootstrap, before any user interaction
47
+ import { init } from '@koderlabs/tasks-sdk-rn';
48
+ import { enableNativeCapture } from '@koderlabs/tasks-sdk-rn-native';
49
+
50
+ init({
51
+ projectId: 'IT-MOBILE',
52
+ accessKey: 'sk_live_…',
53
+ captureNativeCrash: true, // sdk-rn drains the report on next launch
54
+ onNativeCrashError: console.warn,
55
+ });
56
+
57
+ await enableNativeCapture({
58
+ enableAnrWatchdog: false, // default off
59
+ anrThresholdMs: 5000,
60
+ onError: (err) => console.warn('[IT native]', err.stage, err.message),
61
+ });
62
+ ```
63
+
64
+ That's it — register early, then the package operates passively. When a native crash happens, the report is written to disk; on the next launch `sdk-rn` reads, ships, and purges it.
65
+
66
+ ## API
67
+
68
+ | Export | Purpose |
69
+ |---|---|
70
+ | `enableNativeCapture(opts?)` | Install signal handlers + optional ANR watchdog. Idempotent. Resolves `true` on success, `false` when the native module isn't loaded. |
71
+ | `getPendingNativeCrash(onError?)` | Read the on-disk report from the previous launch. Returns `null` if none or on error. Usually called by `sdk-rn`. |
72
+ | `purgePendingNativeCrash(onError?)` | Delete the on-disk report. Safe to call when nothing's there. |
73
+ | `generateTestNativeReport(onError?)` | Write a fake report without crashing. For dev/CI verification. |
74
+ | Types: `EnableOptions`, `NativeError`, `NativeErrorHandler`, `NativeCrashReport`. |
75
+
76
+ ### `EnableOptions`
77
+
78
+ | Option | Type | Default | Notes |
79
+ |---|---|---|---|
80
+ | `enableAnrWatchdog` | `boolean` | `false` | Android only. Soft watchdogs are noisy on slow devices — the OS does its own ANR detection. |
81
+ | `anrThresholdMs` | `number` | `5000` | Matches OS-level Activity ANR. |
82
+ | `onError` | `(NativeError) => void` | — | Surface load/runtime failures. Without it, "no crash" and "decode failed" look identical. |
83
+
84
+ ### `NativeError.stage`
85
+
86
+ `'require-core' | 'require-native' | 'enable' | 'get-report' | 'purge' | 'test-report'` — lets callers distinguish "native module not installed" from a genuine runtime failure that silenced crash reporting.
87
+
88
+ ## Caveats
89
+
90
+ - **Expo Go cannot load native code.** Use `expo prebuild` or EAS Build. The JS layer falls back to sdk-rn-only behaviour when the native module isn't present — no crash, but no native capture either.
91
+ - Symbol resolution for `.so` backtraces requires a CLI source-map upload step (planned follow-up — not in v1).
92
+ - **Crashpad/Breakpad is not bundled.** A future package may replace the custom signal handler with richer stack walks; out of scope for v1.
93
+ - Re-entrant crashes inside the signal handler are not detected.
94
+ - ANR watchdog is opt-in for a reason — slow devices, debugger pauses, and intentionally long-running JS work all trigger false positives.
95
+ - iOS uses PLCrashReporter (BSD/MIT). Make sure your `Podfile.lock` matches CI to avoid surprise version bumps.
96
+ - `enableNativeCapture()` is safe to call before authentication is established.
97
+
98
+ ---
99
+
100
+ ## Suite overview
101
+
102
+ Full SDK suite map + platform availability matrix: [docs/sdk/overview.md](https://github.com/jawaidgadiwala/instant-tasks/blob/main/docs/sdk/overview.md).
103
+
104
+ ## License
105
+
106
+ KoderLabs proprietary. See [`LICENSE`](./LICENSE) for terms. Use of this package requires a separate signed written agreement with KoderLabs; access alone confers no rights.
8
107
 
9
108
  Licensing inquiries: jawaidgadiwala@gmail.com
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@koderlabs/tasks-sdk-rn-native",
3
- "version": "0.1.0",
3
+ "version": "0.1.1",
4
4
  "description": "Native crash + ANR capture for @koderlabs/tasks-sdk-rn (Expo module — PLCrashReporter iOS, NDK signal handler + ANR watchdog Android).",
5
5
  "keywords": [
6
6
  "instanttasks",
@@ -45,13 +45,13 @@
45
45
  ],
46
46
  "sideEffects": false,
47
47
  "dependencies": {
48
- "@koderlabs/tasks-sdk": "0.1.0"
48
+ "@koderlabs/tasks-sdk": "0.1.1"
49
49
  },
50
50
  "peerDependencies": {
51
51
  "expo": ">=50.0.0",
52
52
  "expo-modules-core": ">=1.0.0",
53
53
  "react-native": ">=0.72.0",
54
- "@koderlabs/tasks-sdk-rn": "0.1.0"
54
+ "@koderlabs/tasks-sdk-rn": "0.1.1"
55
55
  },
56
56
  "peerDependenciesMeta": {
57
57
  "expo": {
@@ -69,13 +69,13 @@
69
69
  "tsup": "^8.3.0",
70
70
  "typescript": "^5.5.0",
71
71
  "vitest": "^2.1.0",
72
- "@koderlabs/tasks-sdk-rn": "0.1.0"
72
+ "@koderlabs/tasks-sdk-rn": "0.1.1"
73
73
  },
74
74
  "engines": {
75
75
  "node": ">=20"
76
76
  },
77
77
  "publishConfig": {
78
- "access": "restricted"
78
+ "access": "public"
79
79
  },
80
80
  "scripts": {
81
81
  "build": "tsup",