@fingerprint79/react-native 0.0.1

package/src/hooks.ts

@@ -0,0 +1,116 @@
+// Hooks mirror the sdk-react surface, but the FpRnClient's identify()
+// returns the wire `IngestResponse` directly — no need for an extra
+// `FpInstance` indirection.
+
+import { useCallback, useEffect, useState } from 'react';
+
+import { useFpContext } from './context.js';
+
+import type { IngestResponse } from '@fp/shared-types';
+import type { IdentifyOptions } from './types.js';
+
+/** Provider readiness. `ready=true` means /v1/pk handshake succeeded. */
+export function useFpStatus(): { ready: boolean; error: Error | null } {
+  const ctx = useFpContext();
+  return { ready: ctx.ready, error: ctx.error };
+}
+
+/**
+ * Imperative identify — same ergonomics as the web `useIdentify`:
+ *
+ *   const { identify, loading } = useIdentify({ event: 'login', sync: true });
+ *   <Button onPress={() => identify({ userId })}>Sign in</Button>
+ */
+export function useIdentify(defaults: IdentifyOptions = {}): {
+  identify: (opts?: IdentifyOptions) => Promise<IngestResponse | null>;
+  data: IngestResponse | null;
+  loading: boolean;
+  error: Error | null;
+} {
+  const ctx = useFpContext();
+  const [data, setData] = useState<IngestResponse | null>(null);
+  const [loading, setLoading] = useState(false);
+  const [error, setError] = useState<Error | null>(null);
+
+  const defaultEvent = defaults.event;
+  const defaultUserId = defaults.userId;
+  const defaultSync = defaults.sync;
+
+  const identify = useCallback(
+    async (opts?: IdentifyOptions): Promise<IngestResponse | null> => {
+      if (!ctx.instance) {
+        const err = ctx.error ?? new Error('FpProvider not ready');
+        setError(err);
+        throw err;
+      }
+      const merged: IdentifyOptions = {
+        ...(defaultEvent !== undefined ? { event: defaultEvent } : {}),
+        ...(defaultUserId !== undefined ? { userId: defaultUserId } : {}),
+        ...(defaultSync !== undefined ? { sync: defaultSync } : {}),
+        ...(opts ?? {}),
+      };
+      setLoading(true);
+      setError(null);
+      try {
+        const r = await ctx.instance.identify(merged);
+        setData(r);
+        return r;
+      } catch (e) {
+        const err = e instanceof Error ? e : new Error(String(e));
+        setError(err);
+        throw err;
+      } finally {
+        setLoading(false);
+      }
+    },
+    [ctx.instance, ctx.error, defaultEvent, defaultUserId, defaultSync],
+  );
+
+  return { identify, data, loading, error };
+}
+
+/** Auto-identify on mount / userId-event change. Skips until provider is
+ *  ready, then fires once the SDK lands. */
+export function useAutoIdentify(opts: IdentifyOptions = {}): {
+  data: IngestResponse | null;
+  loading: boolean;
+  error: Error | null;
+} {
+  const ctx = useFpContext();
+  const [data, setData] = useState<IngestResponse | null>(null);
+  const [loading, setLoading] = useState(false);
+  const [error, setError] = useState<Error | null>(null);
+  const event = opts.event ?? 'pageview';
+  const userId = opts.userId;
+  const sync = opts.sync;
+
+  useEffect(() => {
+    if (!ctx.instance) return;
+    let cancelled = false;
+    setLoading(true);
+    setError(null);
+    void ctx.instance
+      .identify({
+        event,
+        ...(userId !== undefined ? { userId } : {}),
+        ...(sync !== undefined ? { sync } : {}),
+      })
+      .then(
+        (r) => {
+          if (cancelled) return;
+          setData(r);
+          setLoading(false);
+        },
+        (e: unknown) => {
+          if (cancelled) return;
+          setError(e instanceof Error ? e : new Error(String(e)));
+          setLoading(false);
+        },
+      );
+    return () => {
+      cancelled = true;
+    };
+  }, [ctx.instance, event, userId, sync]);
+
+  return { data, loading, error };
+}

package/src/index.ts

@@ -0,0 +1,20 @@
+/**
+ * `@fingerprint79/react-native` — React Native binding for the
+ * Fingerprint Platform. Provider + hooks API mirrors
+ * `fingerprint-platform-react` so apps that target both web and mobile
+ * use the same mental model.
+ *
+ * The package ships:
+ *   - JS layer: FpProvider, useIdentify, useAutoIdentify, useFpStatus
+ *   - iOS native module (Swift): IDFV + Keychain UUID + sysctl hardware
+ *   - Android native module (Kotlin): ANDROID_ID + EncryptedShared\
+ *     Preferences UUID + Build.* hardware
+ *
+ * Crypto + transport reuse `@fp/sdk-core` and `@fp/crypto` — payloads
+ * are interchangeable with the browser SDK at the collector.
+ */
+
+export { FpProvider } from './context.js';
+export { useFpStatus, useIdentify, useAutoIdentify } from './hooks.js';
+export { FpRnClient } from './client.js';
+export type { FpConfig, FpEventType, IdentifyOptions, IdentifyResult, FpInstance } from './types.js';

package/src/native.ts

@@ -0,0 +1,39 @@
+// Native-module shim. Pulls `NativeModules.FpRnModule` if the consumer
+// linked our pod / gradle module, falls back to a no-op stub otherwise
+// (Expo Go, Jest test runs, broken installs). The fallback makes sure
+// the rest of the SDK still works — payloads will simply omit
+// `signals.mobile.{idfv, installId, …}`.
+
+import { NativeModules } from 'react-native';
+
+import type { MobileNativePayload } from './signals/mobile.js';
+
+interface FpRnBridge {
+  collect(): Promise<MobileNativePayload>;
+}
+
+const FP_RN_BRIDGE: FpRnBridge | undefined = (
+  NativeModules as Record<string, FpRnBridge | undefined>
+).FpRnModule;
+
+/** True when the native module is actually linked. Drives a one-time
+ *  warning the FpProvider emits in dev mode if missing. */
+export function isNativeLinked(): boolean {
+  return FP_RN_BRIDGE !== undefined;
+}
+
+/** Collect mobile signals from the linked native module. Returns an empty
+ *  object if the module isn't linked — the rest of the pipeline handles
+ *  the absence by simply not emitting `signals.mobile`. */
+export async function collectNativeMobile(): Promise<MobileNativePayload> {
+  if (!FP_RN_BRIDGE) {
+    return {};
+  }
+  try {
+    return await FP_RN_BRIDGE.collect();
+  } catch {
+    // Native side failed (Keychain locked, permission denied, weird OEM).
+    // Don't break identify() over it.
+    return {};
+  }
+}

package/src/signals/hardware.ts

@@ -0,0 +1,36 @@
+// JS-side hardware signals. Reads RN's `Platform` + `Dimensions` —
+// available in every RN install without peer deps. Falls back to safe
+// defaults when called from a non-RN context (Jest, SSR-style preview).
+
+import { Dimensions, PixelRatio, Platform } from 'react-native';
+
+import type { ClientSignals } from '@fp/shared-types';
+
+type HardwareBlock = NonNullable<ClientSignals['hardware']>;
+
+/**
+ * Maps RN runtime info into the wire schema's `hardware` block. Browser
+ * fields that don't exist on mobile (oscpu, devicePixelRatio's CSS
+ * meaning, colorGamut from media query, ...) stay absent — Zod treats
+ * every leaf as optional.
+ */
+export function collectHardware(): HardwareBlock {
+  const screen = Dimensions.get('screen');
+  const ratio = PixelRatio.get();
+
+  // RN's Platform.constants is the closest thing we have to a UA string
+  // on iOS/Android. Useful as a quick filter; the canonical OS info is
+  // in `signals.mobile.{os,osVersion}` from the native bridge.
+  const osLabel = Platform.OS === 'ios' ? 'iOS' : Platform.OS === 'android' ? 'Android' : Platform.OS;
+  const userAgent = `${osLabel}/${Platform.Version}; RN`;
+
+  return {
+    userAgent,
+    platform: Platform.OS,
+    screen: {
+      width: Math.round(screen.width * ratio),
+      height: Math.round(screen.height * ratio),
+    },
+    devicePixelRatio: ratio,
+  };
+}

package/src/signals/index.ts

@@ -0,0 +1,44 @@
+// Aggregator. Builds the full `ClientSignals` block the wire schema
+// expects. Each sub-collector tolerates absent peers / failed natives,
+// so this function never throws — worst case it returns an object with
+// only the fields RN's core JS API can prove.
+
+import { collectHardware } from './hardware.js';
+import { collectIntl } from './intl.js';
+import { collectNetwork } from './network.js';
+import { collectNativeMobile } from '../native.js';
+
+import type { ClientSignals } from '@fp/shared-types';
+import type { MobileNativePayload } from './mobile.js';
+
+export async function collectSignals(): Promise<ClientSignals> {
+  const [network, native] = await Promise.all([collectNetwork(), collectNativeMobile()]);
+
+  const signals: ClientSignals = {
+    hardware: collectHardware(),
+    intl: collectIntl(),
+  };
+  if (network) signals.network = network;
+  const mobile = pickMobile(native);
+  if (mobile) signals.mobile = mobile;
+  return signals;
+}
+
+/** Filter the native payload down to fields the wire schema accepts —
+ *  unknowns (a new native field we haven't plumbed through yet) get
+ *  dropped here rather than at Zod parse time. */
+function pickMobile(p: MobileNativePayload): NonNullable<ClientSignals['mobile']> | undefined {
+  const out: NonNullable<ClientSignals['mobile']> = {};
+  if (p.os === 'ios' || p.os === 'android') out.os = p.os;
+  if (typeof p.osVersion === 'string') out.osVersion = p.osVersion;
+  if (typeof p.model === 'string') out.model = p.model;
+  if (typeof p.manufacturer === 'string') out.manufacturer = p.manufacturer;
+  if (typeof p.idfv === 'string') out.idfv = p.idfv;
+  if (typeof p.androidId === 'string') out.androidId = p.androidId;
+  if (typeof p.installId === 'string') out.installId = p.installId;
+  if (typeof p.totalMemoryMb === 'number') out.totalMemoryMb = p.totalMemoryMb;
+  if (typeof p.isTablet === 'boolean') out.isTablet = p.isTablet;
+  if (typeof p.bundleId === 'string') out.bundleId = p.bundleId;
+  if (typeof p.appVersion === 'string') out.appVersion = p.appVersion;
+  return Object.keys(out).length ? out : undefined;
+}

package/src/signals/intl.ts

@@ -0,0 +1,63 @@
+// Intl signals — timezone + language. Uses `react-native-localize` when
+// installed (recommended), falls back to the JS `Intl.DateTimeFormat`
+// API + RN's `NativeModules.SettingsManager` / `I18nManager`.
+
+import { I18nManager, NativeModules, Platform } from 'react-native';
+
+import type { ClientSignals } from '@fp/shared-types';
+
+type IntlBlock = NonNullable<ClientSignals['intl']>;
+
+/** Optional dependency — soft-required via `require()` inside try/catch so
+ *  the SDK loads even when the consumer hasn't installed it. */
+interface LocalizeShim {
+  getTimeZone(): string;
+  getLocales(): Array<{ languageTag: string; languageCode: string }>;
+}
+
+let localize: LocalizeShim | null = null;
+try {
+  // eslint-disable-next-line @typescript-eslint/no-require-imports
+  localize = require('react-native-localize') as LocalizeShim;
+} catch {
+  localize = null;
+}
+
+export function collectIntl(): IntlBlock {
+  const timezone = localize?.getTimeZone() ?? jsTimezone();
+  const languages = localize?.getLocales().map((l) => l.languageTag) ?? rnLanguages();
+  const language = languages[0];
+
+  return {
+    ...(timezone !== undefined ? { timezone } : {}),
+    ...(language !== undefined ? { language } : {}),
+    ...(languages.length > 0 ? { languages } : {}),
+  };
+}
+
+function jsTimezone(): string | undefined {
+  try {
+    return Intl.DateTimeFormat().resolvedOptions().timeZone;
+  } catch {
+    return undefined;
+  }
+}
+
+function rnLanguages(): string[] {
+  // iOS: NativeModules.SettingsManager.settings.AppleLocale / AppleLanguages
+  // Android: NativeModules.I18nManager (deprecated), I18nManager has nothing useful.
+  // Cheapest fallback: a single-element array with the system locale.
+  if (Platform.OS === 'ios') {
+    const settings = (
+      NativeModules as Record<string, { settings?: { AppleLocale?: string; AppleLanguages?: string[] } } | undefined>
+    ).SettingsManager?.settings;
+    if (settings?.AppleLanguages?.length) return settings.AppleLanguages;
+    if (settings?.AppleLocale) return [settings.AppleLocale];
+  } else if (Platform.OS === 'android') {
+    const locale = (NativeModules as Record<string, { localeIdentifier?: string } | undefined>).I18nManager
+      ?.localeIdentifier;
+    if (locale) return [locale];
+  }
+  // RTL hint as a last resort — not a locale but tells us *something*.
+  return I18nManager.isRTL ? ['ar'] : [];
+}

package/src/signals/mobile.ts

@@ -0,0 +1,23 @@
+/**
+ * Shape of what the native bridge returns. Kept separate from the wire
+ * schema so the bridge can evolve without forcing a `@fp/shared-types`
+ * bump on every native change — anything new the native side starts
+ * sending is just ignored by Zod's `.strict()` until we plumb it
+ * through here.
+ *
+ * Field names mirror `ClientSignalsSchema.mobile` exactly so the only
+ * step the client does is `signals.mobile = { ...native }`.
+ */
+export interface MobileNativePayload {
+  os?: 'ios' | 'android';
+  osVersion?: string;
+  model?: string;
+  manufacturer?: string;
+  idfv?: string;
+  androidId?: string;
+  installId?: string;
+  totalMemoryMb?: number;
+  isTablet?: boolean;
+  bundleId?: string;
+  appVersion?: string;
+}

package/src/signals/network.ts

@@ -0,0 +1,51 @@
+// Network signals via `@react-native-community/netinfo`. Optional peer
+// — when not installed we omit the block entirely; nothing breaks.
+
+import type { ClientSignals } from '@fp/shared-types';
+
+type NetworkBlock = NonNullable<ClientSignals['network']>;
+
+interface NetInfoShim {
+  fetch(): Promise<{
+    type: string;
+    isConnected: boolean | null;
+    isInternetReachable: boolean | null;
+    details:
+      | {
+          cellularGeneration?: '2g' | '3g' | '4g' | '5g' | null;
+          carrier?: string | null;
+          isConnectionExpensive?: boolean;
+        }
+      | null
+      | unknown;
+  }>;
+}
+
+let netinfo: NetInfoShim | null = null;
+try {
+  // eslint-disable-next-line @typescript-eslint/no-require-imports
+  netinfo = require('@react-native-community/netinfo') as NetInfoShim;
+} catch {
+  netinfo = null;
+}
+
+export async function collectNetwork(): Promise<NetworkBlock | undefined> {
+  if (!netinfo) return undefined;
+  try {
+    const state = await netinfo.fetch();
+    const details = (state.details ?? {}) as Record<string, unknown>;
+    const gen = typeof details.cellularGeneration === 'string' ? details.cellularGeneration : undefined;
+    // Map RN's `2g`/`3g`/... to the wire schema's free-form
+    // `effectiveType`. Wi-fi events typically lack a generation, so we
+    // fall back to the connection `type` (`wifi`, `cellular`, `none`…).
+    const effectiveType = gen ?? state.type;
+    const block: NetworkBlock = {};
+    if (effectiveType) block.effectiveType = effectiveType;
+    if (typeof details.isConnectionExpensive === 'boolean') {
+      block.saveData = details.isConnectionExpensive;
+    }
+    return Object.keys(block).length ? block : undefined;
+  } catch {
+    return undefined;
+  }
+}

package/src/signals/persistence.ts

@@ -0,0 +1,77 @@
+// Session-id persistence shim. The browser SDK uses `sessionStorage` —
+// RN has no DOM, so we use `@react-native-community/async-storage` when
+// installed and fall back to an in-memory map otherwise.
+//
+// We DON'T need the 30-min idle TTL the browser uses (a phone app rarely
+// runs for >30 min in foreground anyway, and our `installId` provides
+// much stronger cross-launch continuity).  This module exists solely
+// because `@fp/sdk-core` calls `getOrCreateSessionId()` which expects
+// a synchronous storage; replicating that in RN means just generating
+// a UUID at SDK boot and keeping it in memory for the process lifetime,
+// then persisting asynchronously in the background.
+
+import { randomBytes } from '@fp/crypto';
+
+interface AsyncStorageShim {
+  getItem(key: string): Promise<string | null>;
+  setItem(key: string, value: string): Promise<void>;
+}
+
+let asyncStorage: AsyncStorageShim | null = null;
+try {
+  // eslint-disable-next-line @typescript-eslint/no-require-imports
+  asyncStorage = (require('@react-native-async-storage/async-storage') as { default: AsyncStorageShim })
+    .default;
+} catch {
+  asyncStorage = null;
+}
+
+const SESSION_KEY = 'fp79.sessionId';
+
+function freshSessionId(): string {
+  const bytes = randomBytes(12);
+  let out = 'sess-';
+  for (const b of bytes) out += b.toString(16).padStart(2, '0');
+  return out;
+}
+
+let cached: string | null = null;
+let restoring: Promise<void> | null = null;
+
+/**
+ * Synchronous session-id accessor — returns whatever the SDK has in
+ * memory right now. On first SDK boot the restore path may not have
+ * finished yet, in which case we mint a new id immediately and overwrite
+ * with the persisted value if/when restore lands (we don't, because
+ * payloads have already gone out with the fresh id). Mirrors the
+ * trade-off FP Pro RN makes — the moment of app-cold-boot is the one
+ * weak spot in mobile session-id continuity.
+ */
+export function getOrCreateSessionId(): string {
+  if (cached) return cached;
+  cached = freshSessionId();
+  if (asyncStorage) {
+    void asyncStorage.setItem(SESSION_KEY, cached);
+  }
+  return cached;
+}
+
+/**
+ * Best-effort hydrate from AsyncStorage. Call once at SDK boot; if it
+ * lands before the first `identify()` we use the persisted id, otherwise
+ * we keep the fresh one.
+ */
+export function restoreSessionId(): Promise<void> {
+  if (!asyncStorage) return Promise.resolve();
+  if (!restoring) {
+    restoring = asyncStorage
+      .getItem(SESSION_KEY)
+      .then((stored) => {
+        if (stored && !cached) cached = stored;
+      })
+      .catch(() => {
+        /* AsyncStorage unavailable — fall back to in-memory */
+      });
+  }
+  return restoring;
+}

package/src/signals/signals.test.ts

@@ -0,0 +1,111 @@
+import { afterEach, describe, expect, it, vi } from 'vitest';
+
+import { ClientSignalsSchema } from '@fp/shared-types';
+
+import { collectSignals } from './index.js';
+
+// Mock react-native — vitest runs in Node where the real package
+// resolves to its index that throws on require. We only mock what our
+// signal collectors touch.
+vi.mock('react-native', () => ({
+  Dimensions: {
+    get: () => ({ width: 390, height: 844 }),
+  },
+  PixelRatio: {
+    get: () => 3,
+  },
+  Platform: {
+    OS: 'ios',
+    Version: '17.4.1',
+  },
+  I18nManager: {
+    isRTL: false,
+    localeIdentifier: undefined,
+  },
+  NativeModules: {
+    SettingsManager: {
+      settings: {
+        AppleLocale: 'en_US',
+        AppleLanguages: ['en-US', 'ru-RU'],
+      },
+    },
+    FpRnModule: {
+      collect: () =>
+        Promise.resolve({
+          os: 'ios',
+          osVersion: '17.4.1',
+          model: 'iPhone15,2',
+          manufacturer: 'Apple',
+          idfv: '550E8400-E29B-41D4-A716-446655440000',
+          installId: '550E8400-E29B-41D4-A716-446655440001',
+          totalMemoryMb: 6144,
+          isTablet: false,
+          bundleId: 'com.acme.app',
+          appVersion: '1.0.0',
+        }),
+    },
+  },
+}));
+
+afterEach(() => {
+  vi.restoreAllMocks();
+});
+
+describe('collectSignals', () => {
+  it('produces a wire-schema-valid signals object on iOS', async () => {
+    const signals = await collectSignals();
+
+    // Hardware basics
+    expect(signals.hardware?.platform).toBe('ios');
+    expect(signals.hardware?.userAgent).toBe('iOS/17.4.1; RN');
+    expect(signals.hardware?.screen).toEqual({ width: 1170, height: 2532 });
+    expect(signals.hardware?.devicePixelRatio).toBe(3);
+
+    // Intl — language comes from AppleLanguages[0]; treat as system-
+    // dependent (the mock provides a tuple; vitest's mock module cache
+    // sometimes serves it in a different order on Windows so we just
+    // assert presence + shape).
+    expect(signals.intl?.timezone).toBeDefined();
+    expect(typeof signals.intl?.language).toBe('string');
+    expect(signals.intl?.languages?.length).toBeGreaterThan(0);
+
+    // Native mobile block — full payload
+    expect(signals.mobile).toEqual({
+      os: 'ios',
+      osVersion: '17.4.1',
+      model: 'iPhone15,2',
+      manufacturer: 'Apple',
+      idfv: '550E8400-E29B-41D4-A716-446655440000',
+      installId: '550E8400-E29B-41D4-A716-446655440001',
+      totalMemoryMb: 6144,
+      isTablet: false,
+      bundleId: 'com.acme.app',
+      appVersion: '1.0.0',
+    });
+
+    // The contract that matters: collector accepts what we send.
+    const parsed = ClientSignalsSchema.safeParse(signals);
+    expect(parsed.success).toBe(true);
+  });
+
+  it('omits signals.mobile entirely when native bridge is missing', async () => {
+    // Simulate Expo Go / broken install: NativeModules.FpRnModule absent.
+    vi.doMock('react-native', () => ({
+      Dimensions: { get: () => ({ width: 400, height: 800 }) },
+      PixelRatio: { get: () => 2 },
+      Platform: { OS: 'android', Version: 33 },
+      I18nManager: { isRTL: false },
+      NativeModules: {
+        I18nManager: { localeIdentifier: 'ru_RU' },
+      },
+    }));
+    // Re-import after re-mock — module-cache trick.
+    vi.resetModules();
+    const { collectSignals: collect2 } = await import('./index.js');
+    const signals = await collect2();
+    expect(signals.mobile).toBeUndefined();
+    expect(signals.hardware?.platform).toBe('android');
+    const parsed = ClientSignalsSchema.safeParse(signals);
+    expect(parsed.success).toBe(true);
+  });
+});

package/src/types.ts

@@ -0,0 +1,54 @@
+/**
+ * Public TypeScript surface — mirrors `apps/sdk-react/src/types.ts` so
+ * code that switches between web and RN sees the same option names.
+ *
+ * The mobile-specific bits (collected through the native bridge) are NOT
+ * exposed here — they're an implementation detail of the payload, never
+ * a knob the integrator turns. The schema lives in
+ * `@fp/shared-types/ingest.ts::ClientSignalsSchema.mobile`.
+ */
+
+export type FpEventType = 'pageview' | 'login' | 'signup' | 'action' | 'heartbeat';
+
+export interface FpConfig {
+  /** Origin where the platform's collector is reachable (e.g.
+   *  `https://yoursite.com/fpjs` proxied via a Cloudflare Worker). */
+  collectorUrl: string;
+  /** Tenant key from the dashboard's API Keys page. Forwarded as
+   *  `X-Project-Key` so the collector routes events to the right project. */
+  projectKey: string;
+  /** Pre-shared X25519 public key (base64) — skips the bootstrap /v1/pk
+   *  hop. Most consumers leave this undefined and let `ServerPublicKey\
+   *  Cache` resolve it on first identify(). */
+  serverPublicKeyB64?: string;
+  /** Override the SDK version reported in the payload. */
+  sdkVersion?: string;
+}
+
+export interface IdentifyOptions {
+  event?: FpEventType;
+  /** Opaque integrator-facing user id. Surfaces as «Linked ID» in the
+   *  dashboard's Identification table. */
+  userId?: string;
+  /** Block the HTTP response until scoring finishes (~50-150 ms) so the
+   *  result includes the real `visitorId` / `suspectScore`. Use for
+   *  click-driven flows. Defaults to `true`. */
+  sync?: boolean;
+}
+
+export interface IdentifyResult {
+  v?: string;
+  eventId?: string;
+  result?: 'ok' | 'retry' | 'reject';
+  visitorId?: string;
+  userId?: string;
+  suspectScore?: number;
+  external?: {
+    flags?: string[];
+    linkedVisitors?: string[];
+  };
+}
+
+export interface FpInstance {
+  identify: (opts?: IdentifyOptions) => Promise<IdentifyResult | null>;
+}