@fingerprintchecker/react 0.0.0-stage → 0.1.0

package/README.md

@@ -1,3 +1,89 @@
-# Temporary Holding Version
+# @fingerprintchecker/react
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+React provider and hook for [FingerPrintChecker](https://fpchecker.com). Built on `@fingerprintchecker/agent`. Requires React 18 or newer.
+
+```bash
+npm install @fingerprintchecker/react
+```
+
+```tsx
+import { FpCheckerProvider, useFpChecker } from '@fingerprintchecker/react';
+
+<FpCheckerProvider publishableKey="pk_live_...">
+  <App />
+</FpCheckerProvider>
+```
+
+The provider accepts the same options as `load()` from `@fingerprintchecker/agent`: `publishableKey`, optional `endpoint`, optional `scriptUrl`. The agent loads in the browser after mount; nothing loads during server rendering.
+
+```tsx
+const { identify, data, error, isLoading } = useFpChecker();
+const result = await identify({ intentToken, linkedId, cache: { ttlSeconds: 60, storage: 'session' } });
+```
+
+- `identify(opts)` passes through to the agent, updates `data`, `error`, `isLoading`, returns the result and rethrows on failure.
+- If several calls overlap, the most recently started call decides `data`.
+- A failure to load the agent shows up as `error`.
+- `useFpChecker()` outside the provider throws an error naming `FpCheckerProvider`.
+
+## Next.js App Router
+
+The package files start with `'use client'`, so they can be imported from client components.
+
+```tsx
+// app/fp-provider.tsx
+'use client';
+import { FpCheckerProvider } from '@fingerprintchecker/react';
+
+export function Providers({ children }: { children: React.ReactNode }) {
+  return <FpCheckerProvider publishableKey={process.env.NEXT_PUBLIC_FPCHECKER_KEY!}>{children}</FpCheckerProvider>;
+}
+```
+
+```tsx
+// app/layout.tsx  (server component)
+import { Providers } from './fp-provider';
+
+export default function RootLayout({ children }: { children: React.ReactNode }) {
+  return (
+    <html lang="en">
+      <body>
+        <Providers>{children}</Providers>
+      </body>
+    </html>
+  );
+}
+```
+
+```tsx
+// app/signup/signup-button.tsx
+'use client';
+import { useFpChecker } from '@fingerprintchecker/react';
+
+export function SignupButton({ intentToken }: { intentToken: string }) {
+  const { identify, isLoading, error } = useFpChecker();
+
+  async function onClick() {
+    const result = await identify({ intentToken });
+    // Send the result to YOUR backend, which verifies it with the server SDK.
+    await fetch('/api/signup', {
+      method: 'POST',
+      headers: { 'content-type': 'application/json' },
+      body: JSON.stringify({ eventId: result.eventId, sealedResult: result.sealedResult }),
+    });
+  }
+
+  return (
+    <>
+      <button onClick={onClick} disabled={isLoading}>Sign up</button>
+      {error && <p role="alert">{error.message}</p>}
+    </>
+  );
+}
+```
+
+Call `identify` from a handler, not during render.
+
+## License
+
+Apache-2.0

package/dist/index.d.ts

@@ -0,0 +1,14 @@
+import type { IdentifyOptions, IdentifyResult, LoadOptions } from '@fingerprintchecker/agent';
+import { type ReactNode } from 'react';
+export type { IdentifyOptions, IdentifyResult, LoadOptions } from '@fingerprintchecker/agent';
+export interface FpCheckerState {
+    identify(opts: IdentifyOptions): Promise<IdentifyResult>;
+    data?: IdentifyResult;
+    error?: Error;
+    isLoading: boolean;
+}
+export type FpCheckerProviderProps = LoadOptions & {
+    children?: ReactNode;
+};
+export declare function FpCheckerProvider(props: FpCheckerProviderProps): import("react").JSX.Element;
+export declare function useFpChecker(): FpCheckerState;

package/dist/index.js

@@ -0,0 +1,103 @@
+'use client';
+import { jsx as _jsx } from "react/jsx-runtime";
+import { FpCheckerAgentError, load } from '@fingerprintchecker/agent';
+import { createContext, useCallback, useContext, useEffect, useMemo, useRef, useState, } from 'react';
+const FpCheckerContext = createContext(null);
+function toError(e) {
+    return e instanceof Error ? e : new Error(String(e));
+}
+export function FpCheckerProvider(props) {
+    const { publishableKey, endpoint, scriptUrl, children } = props;
+    const [data, setData] = useState(undefined);
+    const [error, setError] = useState(undefined);
+    const [isLoading, setIsLoading] = useState(false);
+    const mounted = useRef(true);
+    const callId = useRef(0);
+    const agentRef = useRef(null);
+    const prevKey = useRef(null);
+    const optionsKey = JSON.stringify([publishableKey, endpoint ?? null, scriptUrl ?? null]);
+    useEffect(() => {
+        mounted.current = true;
+        return () => {
+            mounted.current = false;
+        };
+    }, []);
+    const getAgent = useCallback(() => {
+        if (agentRef.current?.key !== optionsKey) {
+            const opts = {
+                publishableKey,
+                ...(endpoint !== undefined ? { endpoint } : {}),
+                ...(scriptUrl !== undefined ? { scriptUrl } : {}),
+            };
+            const promise = load(opts);
+            agentRef.current = { key: optionsKey, promise };
+            // Do not cache a failed load: the next identify retries.
+            promise.catch(() => {
+                if (agentRef.current?.promise === promise)
+                    agentRef.current = null;
+            });
+        }
+        return agentRef.current.promise;
+    }, [optionsKey, publishableKey, endpoint, scriptUrl]);
+    // Client only: effects never run during server rendering.
+    // A change of options starts a new generation: old calls become stale and state resets.
+    useEffect(() => {
+        let active = true;
+        // Only a real change resets: on first mount (and the StrictMode re-run) children's
+        // mount-time identify calls have already started and must stay current.
+        if (prevKey.current !== null && prevKey.current !== optionsKey) {
+            callId.current += 1;
+            setData(undefined);
+            setError(undefined);
+            setIsLoading(false);
+        }
+        prevKey.current = optionsKey;
+        getAgent().catch((e) => {
+            if (active)
+                setError(toError(e));
+        });
+        return () => {
+            active = false;
+        };
+    }, [getAgent, optionsKey]);
+    const identify = useCallback(async (opts) => {
+        if (typeof window === 'undefined') {
+            throw new FpCheckerAgentError('ssr', 'identify() can only run in the browser; call it from an event handler or effect.');
+        }
+        const id = ++callId.current;
+        const isLatest = () => mounted.current && callId.current === id;
+        setIsLoading(true);
+        try {
+            const agent = await getAgent();
+            const result = await agent.identify(opts);
+            if (isLatest()) {
+                setData(result);
+                setError(undefined);
+            }
+            return result;
+        }
+        catch (e) {
+            if (isLatest())
+                setError(toError(e));
+            throw e;
+        }
+        finally {
+            if (isLatest())
+                setIsLoading(false);
+        }
+    }, [getAgent]);
+    const value = useMemo(() => ({
+        identify,
+        isLoading,
+        ...(data !== undefined ? { data } : {}),
+        ...(error !== undefined ? { error } : {}),
+    }), [identify, data, error, isLoading]);
+    return _jsx(FpCheckerContext.Provider, { value: value, children: children });
+}
+export function useFpChecker() {
+    const ctx = useContext(FpCheckerContext);
+    if (!ctx) {
+        throw new Error('useFpChecker must be used inside <FpCheckerProvider>. Wrap your app (or layout) with it.');
+    }
+    return ctx;
+}

package/package.json

@@ -1,6 +1,33 @@
 {
   "name": "@fingerprintchecker/react",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.0",
+  "description": "React provider and hook for FingerPrintChecker.",
+  "license": "Apache-2.0",
+  "type": "module",
+  "main": "./dist/index.js",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": { "types": "./dist/index.d.ts", "default": "./dist/index.js" },
+    "./package.json": "./package.json"
+  },
+  "files": ["dist", "README.md"],
+  "sideEffects": false,
+  "scripts": {
+    "build": "rm -rf dist && tsc -p tsconfig.json",
+    "test": "vitest run",
+    "prepack": "npm run build"
+  },
+  "dependencies": { "@fingerprintchecker/agent": "^0.1.0" },
+  "peerDependencies": { "react": ">=18" },
+  "devDependencies": {
+    "@testing-library/react": "^16.0.0",
+    "@types/react": "^18.3.0",
+    "@types/react-dom": "^18.3.0",
+    "happy-dom": "^15.11.0",
+    "react": "^18.3.1",
+    "react-dom": "^18.3.1",
+    "typescript": "^5.5.0",
+    "vitest": "^2.1.0"
+  }
+}