@allstak/react-native 0.1.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2024 AllStak
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,75 @@
+# @allstak-io/react-native
+
+AllStak React Native SDK — `ErrorUtils` + Hermes rejection tracking + Platform device tags.  
+Includes native Android (Kotlin) and iOS (Swift) crash capture modules under `./native/`.
+
+## Install
+
+> **Auth required:** GitHub Packages requires a token with `read:packages` scope.
+
+### 1. Configure `.npmrc`
+
+```ini
+@allstak-io:registry=https://npm.pkg.github.com
+//npm.pkg.github.com/:_authToken=YOUR_GITHUB_PAT
+```
+
+### 2. Install
+
+```bash
+npm install @allstak-io/react-native@0.1.1 @allstak-io/core@0.1.1
+# react-native >=0.70 is an optional peer dep
+```
+
+## Usage
+
+```ts
+import { AllStak } from '@allstak-io/core';
+import { installReactNative } from '@allstak-io/react-native';
+
+// Initialize the base SDK
+AllStak.init({
+  apiKey: process.env.ALLSTAK_API_KEY!,
+  environment: 'production',
+  release: 'v1.0.0',
+  // ingest: 'https://api.allstak.sa'  ← default
+});
+
+// Install RN-specific instrumentation
+installReactNative({
+  // Hooks ErrorUtils for uncaught JS errors
+  // Installs Hermes rejection tracking
+  // Tags every event with Platform.OS and Platform.Version
+});
+```
+
+## What's captured automatically after `installReactNative()`
+
+| Capability | Notes |
+|-----------|-------|
+| Uncaught JS errors | Via `ErrorUtils.setGlobalHandler` |
+| Unhandled promise rejections | Via Hermes rejection tracking |
+| `Platform.OS` / `Platform.Version` tags | Attached to every event |
+
+## Native crash capture (Android/iOS)
+
+Native modules for Java/Kotlin (Android) and Obj-C/Swift (iOS) crash capture are in `./native/`. See [`native/README.md`](./native/README.md) for platform-specific setup.
+
+## API
+
+| Export | Description |
+|--------|-------------|
+| `AllStak` | Re-exported from `@allstak-io/core` |
+| `installReactNative(opts?)` | Hooks ErrorUtils + Hermes + device tags |
+| `ReactNativeInstallOptions` | Options type for `installReactNative` |
+
+## GitHub Packages
+
+- **Package:** `@allstak-io/react-native`
+- **Registry:** `https://npm.pkg.github.com`
+- **Repo:** [github.com/allstak-io/allstak-react-native](https://github.com/allstak-io/allstak-react-native)
+- **Releases:** [github.com/allstak-io/allstak-react-native/releases](https://github.com/allstak-io/allstak-react-native/releases)
+
+## Versioning
+
+Tags must match `package.json` version exactly (e.g. `v0.1.1`). The release workflow fails if there's a mismatch.

package/dist/index.d.mts

@@ -0,0 +1 @@
+export { AllStak, ReactNativeInstallOptions, installReactNative } from 'allstak-js/react-native';

package/dist/index.d.ts

@@ -0,0 +1 @@
+export { AllStak, ReactNativeInstallOptions, installReactNative } from 'allstak-js/react-native';

package/dist/index.js

@@ -0,0 +1,28 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/index.ts
+var index_exports = {};
+__export(index_exports, {
+  AllStak: () => import_react_native.AllStak,
+  installReactNative: () => import_react_native.installReactNative
+});
+module.exports = __toCommonJS(index_exports);
+var import_react_native = require("allstak-js/react-native");
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/index.ts"],"sourcesContent":["/**\n * @allstak/react-native — React Native public API.\n *\n * Re-exports the RN integration from allstak-js/react-native:\n *   - installReactNative({...}) — hooks ErrorUtils + Hermes rejection tracking\n *     + Platform.OS tags\n *\n * Native-layer crash capture (Java/Kotlin on Android, Obj-C/Swift on iOS)\n * lives under the `native/` directory inside this package. See README.\n */\nexport { installReactNative, type ReactNativeInstallOptions, AllStak } from 'allstak-js/react-native';\n"],"mappings":";;;;;;;;;;;;;;;;;;;;AAAA;AAAA;AAAA;AAAA;AAAA;AAAA;AAUA,0BAA4E;","names":[]}

package/dist/index.mjs

@@ -0,0 +1,7 @@
+// src/index.ts
+import { installReactNative, AllStak } from "allstak-js/react-native";
+export {
+  AllStak,
+  installReactNative
+};
+//# sourceMappingURL=index.mjs.map

package/dist/index.mjs.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/index.ts"],"sourcesContent":["/**\n * @allstak/react-native — React Native public API.\n *\n * Re-exports the RN integration from allstak-js/react-native:\n *   - installReactNative({...}) — hooks ErrorUtils + Hermes rejection tracking\n *     + Platform.OS tags\n *\n * Native-layer crash capture (Java/Kotlin on Android, Obj-C/Swift on iOS)\n * lives under the `native/` directory inside this package. See README.\n */\nexport { installReactNative, type ReactNativeInstallOptions, AllStak } from 'allstak-js/react-native';\n"],"mappings":";AAUA,SAAS,oBAAoD,eAAe;","names":[]}

package/native/README.md

@@ -0,0 +1,73 @@
+# @allstak/react-native — native crash capture
+
+**Status: SCAFFOLDED, requires real device/emulator verification.**
+
+This directory contains the Android (Java) and iOS (Obj-C) native modules
+that intercept uncaught platform-level crashes — the ones that can't be
+caught from the JS layer via `ErrorUtils`.
+
+## Files
+
+| File | Purpose |
+|---|---|
+| `android/src/main/java/io/allstak/rn/AllStakCrashHandler.java` | Installs `Thread.setDefaultUncaughtExceptionHandler`, serialises the crash to `SharedPreferences`, survives process death. |
+| `android/src/main/java/io/allstak/rn/AllStakRNModule.java` | `ReactContextBaseJavaModule` exposing `install(release)` + `drainPendingCrash()` to JS. |
+| `ios/AllStakCrashHandler.{h,m}` | `NSSetUncaughtExceptionHandler` → `NSUserDefaults`. |
+| `ios/AllStakRNModule.m` | `RCTBridgeModule` exposing the same API. |
+
+## JS-side drain
+
+The `@allstak/react-native` package exports `drainPendingNativeCrashes(release?)`
+which calls `NativeModules.AllStakNative.drainPendingCrash()`, parses the JSON
+payload (already DTO-compatible with `/ingest/v1/errors`), and re-submits it via
+`AllStak.captureException` so the crash appears as a regular error group tagged
+`native.crash=true` + `device.os=android|ios` + `fatal=true`.
+
+Call it once early in your app init (inside a `try/catch`), *after* `AllStak.init()`:
+
+```ts
+import { AllStak, installReactNative, drainPendingNativeCrashes } from '@allstak/react-native';
+
+AllStak.init({ apiKey: '...', release: 'my-app@1.2.3' });
+installReactNative();
+drainPendingNativeCrashes('my-app@1.2.3');
+```
+
+## How to finish the integration (per-app, one-time)
+
+### Bare React Native — Android
+
+1. Copy `native/android/src/main/java/io/allstak/rn/*.java` into your app's
+   `android/app/src/main/java/...` (or a local autolinked module).
+2. Create a `ReactPackage` that registers `AllStakRNModule` — add to
+   `getPackages()` in `MainApplication.java`.
+3. In `MainApplication.onCreate`, call
+   `AllStakCrashHandler.install(this, BuildConfig.VERSION_NAME)` BEFORE
+   `SoLoader.init(...)` so the handler is armed before any RN code runs.
+
+### Bare React Native — iOS
+
+1. Drag `native/ios/AllStakCrashHandler.{h,m}` + `AllStakRNModule.m` into the
+   Xcode project.
+2. Add `#import "AllStakCrashHandler.h"` to `AppDelegate.m` and call
+   `[AllStakCrashHandler installWithRelease:@"<release>"]` at the top of
+   `application:didFinishLaunchingWithOptions:` (before RCTBridge is built).
+3. CocoaPods autolinking will wire the `RCTBridgeModule` automatically.
+
+### Expo
+
+Bare workflow only for now — Expo Go cannot load custom native modules.
+Config-plugin wrapper is a planned follow-up.
+
+## Verification checklist (device/emulator required)
+
+- [ ] Android Java crash (throw from MainActivity.onResume) → app dies →
+      relaunch → dashboard shows error group with
+      `exceptionClass=RuntimeException`, `device.os=android`, `fatal=true`,
+      `stackTrace` visible.
+- [ ] iOS Obj-C exception (`@throw [NSException exceptionWithName:...]`) →
+      same flow, `device.os=ios`.
+
+None of the above can be verified from a browser Chrome MCP session.
+Flag this in the report as *scaffolded, verification blocked on physical
+build env*.

package/native/android/src/main/java/io/allstak/rn/AllStakCrashHandler.java

@@ -0,0 +1,93 @@
+package io.allstak.rn;
+
+import android.content.Context;
+import android.content.SharedPreferences;
+import android.os.Build;
+import android.util.Log;
+
+import org.json.JSONArray;
+import org.json.JSONObject;
+
+import java.io.PrintWriter;
+import java.io.StringWriter;
+
+/**
+ * Installs a {@link Thread.UncaughtExceptionHandler} that serialises the
+ * crash to SharedPreferences so it survives process death. On next app
+ * launch, {@link #drainPendingCrash(Context)} returns the stashed payload
+ * for the JS layer to ship to AllStak.
+ *
+ * The crash payload is DTO-compatible with /ingest/v1/errors:
+ *   { exceptionClass, message, stackTrace: List<String>,
+ *     metadata: { platform, device.os, device.osVersion, device.model,
+ *                 fatal, source, release }, ... }
+ *
+ * This class is platform-level: it does NOT depend on React Native so the
+ * handler continues to work even if the RN bridge is already torn down.
+ *
+ * SCAFFOLDED — requires real device/emulator run to fully verify.
+ */
+public final class AllStakCrashHandler {
+    private static final String TAG = "AllStakCrashHandler";
+    private static final String PREFS_NAME = "allstak_crashes";
+    private static final String PREFS_KEY = "pending_crash";
+
+    private AllStakCrashHandler() {}
+
+    public static void install(final Context appContext, final String release) {
+        final Context ctx = appContext.getApplicationContext();
+        final Thread.UncaughtExceptionHandler previous = Thread.getDefaultUncaughtExceptionHandler();
+        Thread.setDefaultUncaughtExceptionHandler(new Thread.UncaughtExceptionHandler() {
+            @Override
+            public void uncaughtException(Thread thread, Throwable throwable) {
+                try {
+                    JSONObject payload = buildPayload(throwable, release);
+                    SharedPreferences prefs = ctx.getSharedPreferences(PREFS_NAME, Context.MODE_PRIVATE);
+                    prefs.edit().putString(PREFS_KEY, payload.toString()).commit();
+                } catch (Throwable t) {
+                    Log.e(TAG, "failed to stash crash", t);
+                }
+                if (previous != null) {
+                    previous.uncaughtException(thread, throwable);
+                }
+            }
+        });
+    }
+
+    /** Returns the stashed crash JSON (or null) and clears it. */
+    public static String drainPendingCrash(Context context) {
+        SharedPreferences prefs = context.getSharedPreferences(PREFS_NAME, Context.MODE_PRIVATE);
+        String json = prefs.getString(PREFS_KEY, null);
+        prefs.edit().remove(PREFS_KEY).commit();
+        return json;
+    }
+
+    private static JSONObject buildPayload(Throwable t, String release) throws Exception {
+        StringWriter sw = new StringWriter();
+        t.printStackTrace(new PrintWriter(sw));
+        String full = sw.toString();
+        JSONArray stack = new JSONArray();
+        for (String line : full.split("\n")) {
+            String trimmed = line.trim();
+            if (!trimmed.isEmpty()) stack.put(trimmed);
+        }
+
+        JSONObject metadata = new JSONObject();
+        metadata.put("platform", "react-native");
+        metadata.put("device.os", "android");
+        metadata.put("device.osVersion", String.valueOf(Build.VERSION.SDK_INT));
+        metadata.put("device.model", Build.MODEL == null ? "" : Build.MODEL);
+        metadata.put("device.manufacturer", Build.MANUFACTURER == null ? "" : Build.MANUFACTURER);
+        metadata.put("fatal", "true");
+        metadata.put("source", "android-UncaughtExceptionHandler");
+
+        JSONObject payload = new JSONObject();
+        payload.put("exceptionClass", t.getClass().getSimpleName());
+        payload.put("message", t.getMessage() == null ? t.toString() : t.getMessage());
+        payload.put("stackTrace", stack);
+        payload.put("level", "fatal");
+        if (release != null) payload.put("release", release);
+        payload.put("metadata", metadata);
+        return payload;
+    }
+}

package/native/android/src/main/java/io/allstak/rn/AllStakRNModule.java

@@ -0,0 +1,45 @@
+package io.allstak.rn;
+
+import androidx.annotation.NonNull;
+
+import com.facebook.react.bridge.ReactApplicationContext;
+import com.facebook.react.bridge.ReactContextBaseJavaModule;
+import com.facebook.react.bridge.ReactMethod;
+import com.facebook.react.bridge.Promise;
+
+/**
+ * React Native module bridging {@link AllStakCrashHandler}.
+ *
+ *  JS side:
+ *     NativeModules.AllStakNative.drainPendingCrash().then(json => ...)
+ *
+ * SCAFFOLDED — compiles against React Native; requires a bare RN app with
+ * autolinking to verify end-to-end.
+ */
+public class AllStakRNModule extends ReactContextBaseJavaModule {
+    public AllStakRNModule(ReactApplicationContext ctx) { super(ctx); }
+
+    @NonNull
+    @Override
+    public String getName() { return "AllStakNative"; }
+
+    @ReactMethod
+    public void install(String release, Promise promise) {
+        try {
+            AllStakCrashHandler.install(getReactApplicationContext(), release);
+            promise.resolve(true);
+        } catch (Throwable t) {
+            promise.reject("install-failed", t);
+        }
+    }
+
+    @ReactMethod
+    public void drainPendingCrash(Promise promise) {
+        try {
+            String json = AllStakCrashHandler.drainPendingCrash(getReactApplicationContext());
+            promise.resolve(json);
+        } catch (Throwable t) {
+            promise.reject("drain-failed", t);
+        }
+    }
+}

package/native/ios/AllStakCrashHandler.h

@@ -0,0 +1,21 @@
+// AllStakCrashHandler — iOS native crash capture for React Native.
+//
+// SCAFFOLDED: compiles against UIKit; requires an Xcode project + real
+// device/simulator to verify end-to-end.
+
+#import <Foundation/Foundation.h>
+
+NS_ASSUME_NONNULL_BEGIN
+
+@interface AllStakCrashHandler : NSObject
+
+/// Install the NSUncaughtExceptionHandler. Idempotent.
++ (void)installWithRelease:(nullable NSString *)release;
+
+/// Returns the JSON payload stashed by the previous crash (or nil), and
+/// clears it from NSUserDefaults.
++ (nullable NSString *)drainPendingCrash;
+
+@end
+
+NS_ASSUME_NONNULL_END

package/native/ios/AllStakCrashHandler.m

@@ -0,0 +1,76 @@
+// AllStakCrashHandler.m — iOS uncaught exception capture.
+//
+// SCAFFOLDED: requires Xcode compile + real iOS simulator/device for
+// end-to-end verification. Obj-C / UIKit imports are standard; no
+// third-party dependencies.
+
+#import "AllStakCrashHandler.h"
+#import <UIKit/UIKit.h>
+
+static NSString * const kAllStakPendingCrashKey = @"io.allstak.rn.pending_crash";
+static NSString *gAllStakRelease = nil;
+static NSUncaughtExceptionHandler *gAllStakPreviousHandler = NULL;
+
+static void AllStakHandleUncaughtException(NSException *exception) {
+    @try {
+        NSMutableArray<NSString *> *stack = [NSMutableArray array];
+        for (NSString *line in [exception callStackSymbols]) {
+            NSString *trimmed = [line stringByTrimmingCharactersInSet:[NSCharacterSet whitespaceCharacterSet]];
+            if (trimmed.length > 0) [stack addObject:trimmed];
+        }
+
+        UIDevice *dev = [UIDevice currentDevice];
+        NSDictionary *metadata = @{
+            @"platform": @"react-native",
+            @"device.os": @"ios",
+            @"device.osVersion": dev.systemVersion ?: @"",
+            @"device.model": dev.model ?: @"",
+            @"device.name": dev.name ?: @"",
+            @"fatal": @"true",
+            @"source": @"ios-NSUncaughtExceptionHandler"
+        };
+
+        NSMutableDictionary *payload = [@{
+            @"exceptionClass": exception.name ?: @"NSException",
+            @"message": exception.reason ?: @"(no reason)",
+            @"stackTrace": stack,
+            @"level": @"fatal",
+            @"metadata": metadata,
+        } mutableCopy];
+        if (gAllStakRelease) payload[@"release"] = gAllStakRelease;
+
+        NSError *err = nil;
+        NSData *json = [NSJSONSerialization dataWithJSONObject:payload options:0 error:&err];
+        if (json && !err) {
+            NSString *str = [[NSString alloc] initWithData:json encoding:NSUTF8StringEncoding];
+            [[NSUserDefaults standardUserDefaults] setObject:str forKey:kAllStakPendingCrashKey];
+            [[NSUserDefaults standardUserDefaults] synchronize];
+        }
+    } @catch (NSException *ignored) {
+        // never re-raise from within the crash handler
+    }
+
+    if (gAllStakPreviousHandler) {
+        gAllStakPreviousHandler(exception);
+    }
+}
+
+@implementation AllStakCrashHandler
+
++ (void)installWithRelease:(NSString *)release {
+    @synchronized(self) {
+        if (release) gAllStakRelease = [release copy];
+        gAllStakPreviousHandler = NSGetUncaughtExceptionHandler();
+        NSSetUncaughtExceptionHandler(&AllStakHandleUncaughtException);
+    }
+}
+
++ (NSString *)drainPendingCrash {
+    NSUserDefaults *defaults = [NSUserDefaults standardUserDefaults];
+    NSString *json = [defaults stringForKey:kAllStakPendingCrashKey];
+    [defaults removeObjectForKey:kAllStakPendingCrashKey];
+    [defaults synchronize];
+    return json;
+}
+
+@end

package/native/ios/AllStakRNModule.m

@@ -0,0 +1,29 @@
+// RCTBridgeModule bridging AllStakCrashHandler to JS.
+//
+// SCAFFOLDED: requires React Native iOS project with CocoaPods autolinking
+// to verify end-to-end.
+
+#import <React/RCTBridgeModule.h>
+#import "AllStakCrashHandler.h"
+
+@interface AllStakRNModule : NSObject <RCTBridgeModule>
+@end
+
+@implementation AllStakRNModule
+
+RCT_EXPORT_MODULE(AllStakNative);
+
+RCT_EXPORT_METHOD(install:(NSString *)release
+                  resolver:(RCTPromiseResolveBlock)resolve
+                  rejecter:(RCTPromiseRejectBlock)reject) {
+    [AllStakCrashHandler installWithRelease:release];
+    resolve(@YES);
+}
+
+RCT_EXPORT_METHOD(drainPendingCrash:(RCTPromiseResolveBlock)resolve
+                  rejecter:(RCTPromiseRejectBlock)reject) {
+    NSString *json = [AllStakCrashHandler drainPendingCrash];
+    resolve(json ?: [NSNull null]);
+}
+
+@end

package/package.json

@@ -0,0 +1,61 @@
+{
+  "name": "@allstak/react-native",
+  "version": "0.1.1",
+  "description": "AllStak React Native SDK — ErrorUtils + Hermes rejection tracking + device tags. Depends on @allstak-io/core. Native Android/iOS crash capture modules in ./native.",
+  "main": "./dist/index.js",
+  "module": "./dist/index.mjs",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.mjs",
+      "require": "./dist/index.js"
+    }
+  },
+  "files": [
+    "dist",
+    "native",
+    "README.md",
+    "LICENSE"
+  ],
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/allstak-io/allstak-react-native.git"
+  },
+  "homepage": "https://allstak.sa",
+  "bugs": {
+    "url": "https://github.com/allstak-io/allstak-react-native/issues"
+  },
+  "keywords": [
+    "allstak",
+    "observability",
+    "react-native",
+    "mobile",
+    "error-tracking"
+  ],
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org/"
+  },
+  "scripts": {
+    "build": "tsup src/index.ts --format esm,cjs --dts --clean --sourcemap --platform browser --external react-native",
+    "typecheck": "tsc --noEmit"
+  },
+  "peerDependencies": {
+    "react-native": ">=0.70"
+  },
+  "peerDependenciesMeta": {
+    "react-native": {
+      "optional": true
+    }
+  },
+  "dependencies": {
+    "@allstak/core": "^0.1.1",
+    "@allstak/js": "^0.1.1"
+  },
+  "devDependencies": {
+    "tsup": "^8.0.0",
+    "typescript": "^5.3.0"
+  }
+}