@simplr-ai/react-native 1.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Simplr
+
+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,258 @@
+# @simplr-ai/react-native
+
+React Native client SDK for the **Simplr** fraud & identity platform — the mobile counterpart to the browser SDK (`@simplr-ai/js`) and the Flutter SDK (`simplr_fraud`). One package gives you:
+
+- 📱 **Device fingerprinting** — a stable device signature + persistent device ID (no DOM/canvas; built from React Native APIs)
+- 👆 **Behavioral biometrics** — touch/gesture dynamics (tap intervals, pressure, swipe velocity) to tell humans from bots
+- 🛒 **Order fraud scoring** — score transactions via `POST /v1/orders`
+- 🧪 **Fraud checks** — `POST /v1/check` with device + behavior signals
+- 🚩 **Feature flags** — local, deterministic evaluation (rollouts, targeting, rules), bucketing identical to every other SDK
+- ⚛️ **React hooks** — `useSimplr`, `useDeviceSignals`, `useFeatureFlag`, `useTouchBiometrics`
+
+Use a **public key** (`pk_live_…` / `pk_test_…`) on the client. Keep secret keys on your backend.
+
+Full docs: https://docs.simplr.so/docs/sdks/ (see the React Native page).
+
+## Install
+
+```bash
+npm install @simplr-ai/react-native
+# or: yarn add @simplr-ai/react-native
+```
+
+`react` and `react-native` are peer dependencies (already present in any RN app).
+
+### Optional: persistent device IDs
+
+For a device ID that survives app restarts, install AsyncStorage:
+
+```bash
+npm install @react-native-async-storage/async-storage
+```
+
+It is **optional** and lazily detected — the SDK never hard-depends on it. Without it, the device ID is stable for the current app session (in-memory fallback).
+
+### Expo
+
+Fully Expo-compatible. The core uses only `Platform`, `Dimensions`, `PixelRatio` and `Intl` — no custom native modules and no config plugin required. AsyncStorage works in Expo too (`npx expo install @react-native-async-storage/async-storage`).
+
+## Quick start
+
+```ts
+import { SimplrFraud } from "@simplr-ai/react-native";
+
+const simplr = new SimplrFraud({ apiKey: "pk_live_xxx" });
+
+// Run a fraud check — device + behavior signals are auto-collected.
+const result = await simplr.check({ email: "user@example.com" });
+console.log(result.risk_score, result.risk_level);
+```
+
+## Device signals
+
+```ts
+const signals = await simplr.getDeviceSignals();
+// {
+//   fingerprint, device_id, device_id_created_at,
+//   platform: "ios" | "android", os, os_version, model, brand,
+//   screen_resolution, device_pixel_ratio, font_scale,
+//   timezone, timezone_offset, language, languages, is_emulator
+// }
+```
+
+The fingerprint is a stable hash built from OS + version, model/brand (when available), screen geometry + pixel ratio + font scale, timezone and locale.
+
+## check()
+
+```ts
+const result = await simplr.check({
+  email: "user@example.com",
+  phone: "+15551234567",
+  event_type: "signup",
+  metadata: { plan: "growth" },
+});
+```
+
+Device and behavior signals are merged automatically (override by passing your own `device` / `behavior`).
+
+## Order scoring
+
+```ts
+const order = await simplr.submitOrder({
+  order_id: "ord_123",
+  amount: 4999,
+  currency: "USD",
+});
+console.log(order.risk_score, order.risk_level);
+```
+
+A `fingerprint_hash` is attached automatically when you don't provide one.
+
+## Feature flags
+
+Flags are fetched once on `initialize()`, refreshed on an interval, then evaluated **locally** — no network call per check. Bucketing uses the same MurmurHash3 as the server/browser/Node/Flutter SDKs, so a user lands in the same bucket everywhere.
+
+```ts
+import { SimplrFlags } from "@simplr-ai/react-native";
+
+const flags = new SimplrFlags();
+await flags.initialize({ apiKey: "pk_live_xxx", environment: "live" });
+flags.setUser("user_123"); // optional; falls back to "anonymous"
+
+if (flags.isEnabled("new-checkout")) {
+  // …
+}
+
+// Per-call context for rules / targeting:
+flags.isEnabled("new-checkout", { userId: "user_123", attributes: { plan: "growth" } });
+```
+
+## Profiles (`simplr.profiles`)
+
+Anonymous user profiles + order fraud monitoring. The device fingerprint is auto-attached from the client's own device-signal collector.
+
+```ts
+import { SimplrFraud } from "@simplr-ai/react-native";
+
+const simplr = new SimplrFraud({ apiKey: "pk_live_xxx" });
+
+// Create/update an anonymous profile and link this device.
+const { profile, is_new } = await simplr.profiles.identify("user-123", { profileType: "customer" });
+
+// Score an order (fingerprint auto-attached).
+const result = await simplr.profiles.submitOrder({
+  order_id: "order-1",
+  external_id: "user-123",
+  amount: 4999,
+  currency: "USD",
+});
+
+// Read a user's risk profile, and report confirmed outcomes back.
+const risk = await simplr.profiles.getProfileRisk("user-123");
+await simplr.profiles.reportOutcome("user-123", "fraud"); // or "legitimate"
+```
+
+You can also use `SimplrProfiles` standalone with `new SimplrProfiles({ apiKey })`.
+
+## RUM (`simplr.rum`)
+
+Real User Monitoring. Events are batched and flushed to `/v1/rum/events` on a timer (`setInterval`). There are no native dependencies — report screen views via `trackView()` (or the `useTrackView` hook) from your navigation listener.
+
+```ts
+simplr.rum.initialize({ apiKey: "pk_live_xxx", applicationId: "my-app", environment: "production" });
+
+simplr.rum.setUser("user-123", { plan: "pro" });
+simplr.rum.addAttribute("buildNumber", "1.4.0");
+
+simplr.rum.trackView("CheckoutScreen");
+simplr.rum.trackAction("PressBuy", { sku: "abc" });
+simplr.rum.log("info", "checkout opened");
+
+try {
+  // …
+} catch (err) {
+  simplr.rum.trackError(err as Error);
+}
+
+await simplr.rum.flush();        // force a flush
+await simplr.rum.stopSession();  // emit session_end, flush, stop timer
+```
+
+`SimplrRUM` is also available standalone (and as the shared `simplrRUM` singleton used by the hooks below).
+
+## AI delegation (`simplr.ai`)
+
+OAuth-like AI authentication — mint, validate, and revoke delegation tokens an end user shares with their AI agent.
+
+```ts
+const delegation = await simplr.ai.createDelegation({
+  userId: "user-123",
+  binding: "verified_device",
+  fingerprintHash: (await simplr.getDeviceSignals()).fingerprint,
+});
+
+await simplr.ai.validate(token, { aiProvider: "anthropic", action: "read_orders" });
+await simplr.ai.list("user-123");
+await simplr.ai.get(delegation.delegationId);
+await simplr.ai.stats();
+await simplr.ai.revoke(delegation.delegationId, "user revoked");
+await simplr.ai.revokeAllForUser("user-123", "logout"); // returns count
+```
+
+> The browser SDK's interactive `connect()` popup flow relies on `window.open`/`postMessage` and is browser-only; it is intentionally omitted from the React Native SDK. Use `createDelegation()` to mint tokens directly.
+
+## Behavioral biometrics
+
+A pure-JS touch-dynamics tracker fed by handlers you attach to a `View`:
+
+```ts
+import { createTouchTracker } from "@simplr-ai/react-native";
+
+const tracker = createTouchTracker();
+tracker.start();
+const h = tracker.getEventHandlers();
+
+<View onTouchStart={h.onTouchStart} onTouchMove={h.onTouchMove} onTouchEnd={h.onTouchEnd}>
+  {/* … */}
+</View>;
+
+const metrics = tracker.getMetrics();
+// { avgPressure, avgSwipeVelocity, avgTapInterval, avgTouchDuration, multiTouchCount, … }
+```
+
+The SDK's own tracker (used by `check()`) is available via `simplr.getTouchTracker()`.
+
+## Hooks (`@simplr-ai/react-native/hooks`)
+
+```tsx
+import {
+  useSimplr,
+  useDeviceSignals,
+  useFeatureFlag,
+  useTouchBiometrics,
+  useRum,
+  useTrackView,
+  useTrackAction,
+  useTrackError,
+} from "@simplr-ai/react-native/hooks";
+
+function Checkout() {
+  const simplr = useSimplr({ apiKey: "pk_live_xxx" });
+  const { signals, loading } = useDeviceSignals(simplr);
+  const showNewFlow = useFeatureFlag("new-checkout", { userId: "user_123" });
+  const { handlers } = useTouchBiometrics(simplr);
+
+  // RUM
+  useRum({ apiKey: "pk_live_xxx", applicationId: "my-app" }); // initialize once
+  useTrackView("CheckoutScreen");                              // tracks on mount
+  const trackAction = useTrackAction();
+  const trackError = useTrackError();
+
+  return (
+    <View {...handlers}>
+      <Button title="Buy" onPress={() => trackAction("PressBuy", { sku: "abc" })} />
+    </View>
+  );
+}
+```
+
+| Hook | Returns |
+| --- | --- |
+| `useSimplr(config?)` | the configured `SimplrFraud` client |
+| `useDeviceSignals(client?)` | `{ signals, loading, error, refresh }` |
+| `useFeatureFlag(key, ctx?, flags?)` | `boolean` (re-evaluates as flags load) |
+| `useTouchBiometrics(client?)` | `{ tracker, handlers, getMetrics }` |
+| `useRum(config?)` | the shared `SimplrRUM` client (initializes it once) |
+| `useTrackView(name, attrs?)` | `void` — tracks a screen view on mount |
+| `useTrackAction()` | `(name, attrs?) => void` |
+| `useTrackError()` | `(error, attrs?) => void` |
+
+All hooks guard their effects so they never crash during SSR or tests.
+
+## Configuration
+
+`new SimplrFraud({ apiKey, baseUrl?, timeoutMs?, autoStart?, fetchImpl? })`. Every module accepts an optional `baseUrl` (defaults to `https://api.simplr.sh`, trailing slashes stripped) so you can point at any environment. Requests time out after 15s by default and raise a `SimplrError`.
+
+## License
+
+MIT — see [LICENSE](./LICENSE).