@magield/react 0.0.0-stage → 0.7.1

package/LICENSE

@@ -0,0 +1,27 @@
+Copyright (c) 2026 MagicShield. All rights reserved.
+
+MAGIC SHIELD SDK LICENCE
+
+This package is published to a public registry so that licensed customers can
+install it with ordinary tooling. Being able to download it does not grant any
+right to use it.
+
+You may install, use and redistribute this package, unmodified and only as part
+of your own application, solely to integrate that application with a Magic
+Shield deployment that you are licensed to use under a written agreement with
+MagicShield ("your Agreement"), and only for the term of your Agreement.
+
+Except as your Agreement expressly allows, you may not:
+
+  - use this package for any other purpose, including to build, benchmark or
+    assist a competing product;
+  - modify it, or reverse engineer, decompile, deobfuscate or disassemble it,
+    except to the extent this restriction is unenforceable under applicable law;
+  - remove or alter this notice or any copyright or attribution in it.
+
+THE PACKAGE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXCEPT AS YOUR
+AGREEMENT PROVIDES. IN NO EVENT SHALL MAGICSHIELD BE LIABLE FOR ANY CLAIM,
+DAMAGES OR OTHER LIABILITY ARISING FROM THE PACKAGE OR ITS USE, EXCEPT AS YOUR
+AGREEMENT PROVIDES.
+
+Your Agreement governs if it conflicts with this notice.

package/dist/context.d.ts

@@ -0,0 +1,11 @@
+import { type Shield, type ShieldConfig } from '@magield/web';
+export declare const ShieldContext: import("react").Context<Shield | undefined>;
+/**
+ * One Shield instance per provider.
+ *
+ * Instance identity matters: warmed signals and the resolved device id live on
+ * it, so recreating it on every render would discard the work that makes
+ * `collect()` fast and re-resolve storage each time.
+ */
+export declare function createInstance(config: ShieldConfig): Shield;
+export declare function useShieldInstance(): Shield;

package/dist/context.js

@@ -0,0 +1,20 @@
+import { createShield } from '@magield/web';
+import { createContext, useContext } from 'react';
+export const ShieldContext = createContext(undefined);
+/**
+ * One Shield instance per provider.
+ *
+ * Instance identity matters: warmed signals and the resolved device id live on
+ * it, so recreating it on every render would discard the work that makes
+ * `collect()` fast and re-resolve storage each time.
+ */
+export function createInstance(config) {
+    return createShield(config);
+}
+export function useShieldInstance() {
+    const shield = useContext(ShieldContext);
+    if (shield === undefined) {
+        throw new Error('useShield must be used inside <ShieldProvider>. Wrap your app once, at the root.');
+    }
+    return shield;
+}

package/dist/index.d.ts

@@ -0,0 +1,4 @@
+export { ShieldProvider, type ShieldProviderProps } from './provider.js';
+export { useShield, useShieldToken, type UseShieldResult } from './use-shield.js';
+export { ShieldContext } from './context.js';
+export type { CollectOptions, CollectResult, ShieldConfig } from '@magield/web';

package/dist/index.js

@@ -0,0 +1,3 @@
+export { ShieldProvider } from './provider.js';
+export { useShield, useShieldToken } from './use-shield.js';
+export { ShieldContext } from './context.js';

package/dist/provider.d.ts

@@ -0,0 +1,13 @@
+import type { ShieldConfig } from '@magield/web';
+import { type ReactNode } from 'react';
+export interface ShieldProviderProps {
+    readonly config: ShieldConfig;
+    /**
+     * Collect the expensive signals on mount, so that by the time a user submits
+     * a form the work is already done. On by default: it is the difference
+     * between collection costing nothing and costing 60ms at the worst moment.
+     */
+    readonly warmup?: boolean;
+    readonly children: ReactNode;
+}
+export declare function ShieldProvider({ config, warmup, children }: ShieldProviderProps): ReactNode;

package/dist/provider.js

@@ -0,0 +1,17 @@
+import { jsx as _jsx } from "react/jsx-runtime";
+import { useEffect, useMemo } from 'react';
+import { createInstance, ShieldContext } from './context.js';
+export function ShieldProvider({ config, warmup = true, children }) {
+    // Keyed on the site key rather than the config object, because an inline
+    // object literal is a new reference on every render and would otherwise
+    // rebuild the instance continuously.
+    const shield = useMemo(() => createInstance(config), [config.siteKey]);
+    useEffect(() => {
+        if (!warmup)
+            return;
+        // Deliberately not awaited and never surfaced: warmup is an optimisation,
+        // and a failed one must not reach the integrator's error boundary.
+        void shield.warmup();
+    }, [shield, warmup]);
+    return _jsx(ShieldContext.Provider, { value: shield, children: children });
+}

package/dist/use-shield.d.ts

@@ -0,0 +1,25 @@
+import type { CollectOptions, CollectResult } from '@magield/web';
+export interface UseShieldResult {
+    /**
+     * Collects and returns a token. Nothing is sent anywhere — where the token
+     * travels is your decision.
+     */
+    collect(options: CollectOptions): Promise<CollectResult>;
+    /** True once warmup has finished. Collection works before this; it is slower. */
+    readonly ready: boolean;
+    readonly deviceId: string | null;
+    /** True while a collect() is in flight, for disabling a submit button. */
+    readonly collecting: boolean;
+}
+export declare function useShield(): UseShieldResult;
+/**
+ * Collects once for a fixed action and keeps the result.
+ *
+ * For pages where the action is known ahead of time and the token is wanted
+ * before the user acts. Tokens are short-lived and single-use, so this
+ * re-collects when the action changes rather than caching indefinitely.
+ */
+export declare function useShieldToken(action: string): {
+    token: string | null;
+    refresh: () => Promise<void>;
+};

package/dist/use-shield.js

@@ -0,0 +1,61 @@
+import { useCallback, useEffect, useRef, useState } from 'react';
+import { useShieldInstance } from './context.js';
+export function useShield() {
+    const shield = useShieldInstance();
+    const [ready, setReady] = useState(false);
+    const [deviceId, setDeviceId] = useState(null);
+    const [collecting, setCollecting] = useState(false);
+    const mounted = useRef(true);
+    useEffect(() => {
+        mounted.current = true;
+        return () => {
+            mounted.current = false;
+        };
+    }, []);
+    useEffect(() => {
+        let cancelled = false;
+        void (async () => {
+            await shield.warmup();
+            const id = await shield.getDeviceId();
+            // Guarded, because a form can be unmounted while warmup is in flight and
+            // setting state afterwards is a warning the integrator would see, not us.
+            if (!cancelled && mounted.current) {
+                setDeviceId(id);
+                setReady(true);
+            }
+        })();
+        return () => {
+            cancelled = true;
+        };
+    }, [shield]);
+    const collect = useCallback(async (options) => {
+        setCollecting(true);
+        try {
+            return await shield.collect(options);
+        }
+        finally {
+            if (mounted.current)
+                setCollecting(false);
+        }
+    }, [shield]);
+    return { collect, ready, deviceId, collecting };
+}
+/**
+ * Collects once for a fixed action and keeps the result.
+ *
+ * For pages where the action is known ahead of time and the token is wanted
+ * before the user acts. Tokens are short-lived and single-use, so this
+ * re-collects when the action changes rather than caching indefinitely.
+ */
+export function useShieldToken(action) {
+    const { collect } = useShield();
+    const [token, setToken] = useState(null);
+    const refresh = useCallback(async () => {
+        const result = await collect({ action });
+        setToken(result.token === '' ? null : result.token);
+    }, [collect, action]);
+    useEffect(() => {
+        void refresh();
+    }, [refresh]);
+    return { token, refresh };
+}

package/package.json

@@ -1,6 +1,45 @@
 {
   "name": "@magield/react",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
+  "version": "0.7.1",
+  "description": "React bindings for the Magic Shield web SDK",
+  "license": "SEE LICENSE IN LICENSE",
+  "files": [
+    "dist",
+    "!**/*.map",
+    "LICENSE"
+  ],
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org/"
+  },
+  "type": "module",
+  "exports": {
+    ".": "./dist/index.js"
+  },
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "sideEffects": false,
+  "peerDependencies": {
+    "react": ">=18"
+  },
+  "dependencies": {
+    "@magield/web": "0.7.1"
+  },
+  "devDependencies": {
+    "@testing-library/react": "^16.1.0",
+    "@types/node": "^22.10.2",
+    "@types/react": "^19.0.2",
+    "happy-dom": "^15.11.7",
+    "react": "^19.0.0",
+    "react-dom": "^19.0.0",
+    "typescript": "^5.7.2",
+    "vitest": "^2.1.8"
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.json",
+    "typecheck": "tsc -p tsconfig.json --noEmit",
+    "typecheck:tests": "tsc -p tsconfig.test.json",
+    "test": "vitest run",
+    "clean": "rm -rf dist .turbo"
+  }
 }

package/README.md

@@ -1,3 +0,0 @@
-# Temporary Holding Version
-
-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.