@shieldlabs-ai/react 1.0.0

package/dist/index.js

@@ -0,0 +1,364 @@
+"use client";
+
+// src/provider.ts
+import {
+  createContext,
+  createElement,
+  useContext,
+  useEffect,
+  useMemo,
+  useRef,
+  useState
+} from "react";
+import {
+  ShieldLabsError as ShieldLabsError3
+} from "@shieldlabs-ai/js";
+
+// src/internal.ts
+import { ShieldLabsError } from "@shieldlabs-ai/js";
+var DEFAULT_TIMEOUT = 1e4;
+var MAX_TIMEOUT = 2147483647;
+function isObject(value) {
+  return typeof value === "object" && value !== null;
+}
+function isValidTimeout(value) {
+  return typeof value === "number" && value > 0 && value <= MAX_TIMEOUT;
+}
+function asShieldLabsError(error, code, message) {
+  return error instanceof ShieldLabsError ? error : new ShieldLabsError(code, message, error);
+}
+function withTimeout(promise, ms, message) {
+  return new Promise((resolve, reject) => {
+    const timer = setTimeout(() => {
+      reject(new ShieldLabsError("timeout", message));
+    }, ms);
+    const clear = () => {
+      clearTimeout(timer);
+    };
+    promise.then(clear, clear);
+    promise.then(resolve, reject);
+  });
+}
+function ignore() {
+}
+
+// src/loader.ts
+import {
+  load,
+  ShieldLabsError as ShieldLabsError2
+} from "@shieldlabs-ai/js";
+var LOAD_FAILED = "Could not load the ShieldLabs agent.";
+var NOT_LOADED = "The ShieldLabs agent is not loaded: ShieldLabsProvider has autoLoad={false} and load() from useShieldLabs() has not been called.";
+function keyOf(options) {
+  return [options.publicKey, options.environment, options.scriptUrl, options.timeout].map((value) => typeof value + ":" + String(value)).join("|");
+}
+function userIdOf(options) {
+  return isObject(options) && typeof options.userId === "string" ? options.userId : null;
+}
+function startLoad(options) {
+  return new Promise((resolve) => {
+    resolve(load(options));
+  }).catch((error) => {
+    throw asShieldLabsError(error, "load_failed", LOAD_FAILED);
+  });
+}
+function canRetry(slot) {
+  var _a;
+  const code = (_a = slot.error) == null ? void 0 : _a.code;
+  return code === "load_failed" || code === "timeout";
+}
+function warnSetupProblem(error) {
+  if (error.code === "invalid_options" || error.code === "unsupported_environment") {
+    console.warn("[ShieldLabs] ShieldLabsProvider could not load the agent: " + error.message);
+  }
+}
+function callTimeout(callOptions, loadOptions) {
+  const perCall = callOptions == null ? void 0 : callOptions.timeout;
+  if (isValidTimeout(perCall)) return perCall;
+  if (isValidTimeout(loadOptions.timeout)) return loadOptions.timeout;
+  return DEFAULT_TIMEOUT;
+}
+function withTimeLeft(callOptions, total, startedAt) {
+  const raw = callOptions;
+  if (raw != null && !isObject(raw)) return callOptions;
+  if ((callOptions == null ? void 0 : callOptions.timeout) !== void 0 && !isValidTimeout(callOptions.timeout)) return callOptions;
+  const left = total - (Date.now() - startedAt);
+  return { ...callOptions, timeout: Math.min(total, Math.max(1, left)) };
+}
+function createAgentLoader(initialOptions, autoLoad) {
+  let options = initialOptions;
+  let slot = null;
+  let listener = null;
+  let latest = null;
+  let allowed = autoLoad;
+  let allowedPromise = null;
+  let resolveAllowed = null;
+  const running = /* @__PURE__ */ new Map();
+  const currentSlot = () => {
+    const key = keyOf(options);
+    const previous = slot;
+    if ((previous == null ? void 0 : previous.key) === key && !canRetry(previous)) return previous;
+    const next = { key, promise: startLoad(options), agent: null, error: null };
+    slot = next;
+    latest = null;
+    const publish = (state) => {
+      if (slot !== next) return;
+      latest = state;
+      if (listener) listener(state);
+    };
+    if ((previous == null ? void 0 : previous.key) === key) publish({ key, status: "loading", error: null });
+    next.promise.then(
+      (agent) => {
+        next.agent = agent;
+        publish({ key, status: "ready", error: null });
+      },
+      (error) => {
+        next.error = asShieldLabsError(error, "load_failed", LOAD_FAILED);
+        if (slot === next) warnSetupProblem(next.error);
+        publish({ key, status: "error", error: next.error });
+      }
+    );
+    return next;
+  };
+  const allow = () => {
+    if (allowed) return;
+    allowed = true;
+    if (resolveAllowed) resolveAllowed();
+    allowedPromise = null;
+    resolveAllowed = null;
+  };
+  const whenAllowed = () => allowedPromise != null ? allowedPromise : allowedPromise = new Promise((resolve) => {
+    resolveAllowed = resolve;
+  });
+  const withAgent = (callOptions, call) => {
+    const current = currentSlot();
+    if (current.agent) return Promise.resolve(current.agent).then((agent) => call(agent, callOptions));
+    const ms = callTimeout(callOptions, options);
+    const startedAt = Date.now();
+    return withTimeout(current.promise, ms, "The ShieldLabs agent did not load within " + String(ms) + " ms.").then(
+      (agent) => call(agent, withTimeLeft(callOptions, ms, startedAt))
+    );
+  };
+  const track = (callOptions, promise) => {
+    var _a;
+    const userId = userIdOf(callOptions);
+    running.set(userId, ((_a = running.get(userId)) != null ? _a : 0) + 1);
+    return promise.finally(() => {
+      var _a2;
+      const left = ((_a2 = running.get(userId)) != null ? _a2 : 1) - 1;
+      if (left > 0) running.set(userId, left);
+      else running.delete(userId);
+    });
+  };
+  return {
+    update(nextOptions, nextAutoLoad) {
+      options = nextOptions;
+      if (nextAutoLoad) allow();
+      if (allowed) currentSlot();
+    },
+    subscribe(nextListener) {
+      listener = nextListener;
+      if (latest) nextListener(latest);
+      return () => {
+        if (listener === nextListener) listener = null;
+      };
+    },
+    isRunning(userId) {
+      return running.has(userId);
+    },
+    defaultTimeout: () => callTimeout(void 0, options),
+    load: () => {
+      allow();
+      currentSlot();
+    },
+    getAgent: () => allowed ? currentSlot().promise : whenAllowed().then(() => currentSlot().promise),
+    identify: (callOptions) => allowed ? track(callOptions, withAgent(callOptions, (agent, agentOptions) => agent.identify(agentOptions))) : Promise.reject(new ShieldLabsError2("not_initialized", NOT_LOADED)),
+    check: (callOptions) => allowed ? track(callOptions, withAgent(callOptions, (agent, agentOptions) => agent.check(agentOptions))) : Promise.resolve(null)
+  };
+}
+
+// src/provider.ts
+var ShieldLabsContext = createContext(null);
+ShieldLabsContext.displayName = "ShieldLabsContext";
+function loadOptionsOf(publicKey, environment, scriptUrl, timeout) {
+  const options = { publicKey };
+  if (environment !== void 0) options.environment = environment;
+  if (scriptUrl !== void 0) options.scriptUrl = scriptUrl;
+  if (timeout !== void 0) options.timeout = timeout;
+  return options;
+}
+function warnCheckOnLoad(error) {
+  if (error instanceof ShieldLabsError3 && error.code === "invalid_options") {
+    console.warn("[ShieldLabs] checkOnLoad: " + error.message);
+  }
+}
+function ShieldLabsProvider(props) {
+  const { publicKey, environment, scriptUrl, timeout, autoLoad, checkOnLoad = false, children } = props;
+  const loadsByItself = autoLoad !== false;
+  const key = keyOf(loadOptionsOf(publicKey, environment, scriptUrl, timeout));
+  const [loader] = useState(
+    () => createAgentLoader(loadOptionsOf(publicKey, environment, scriptUrl, timeout), loadsByItself)
+  );
+  const [loadState, setLoadState] = useState(() => ({ key, status: "loading", error: null }));
+  const checkedRef = useRef(false);
+  useEffect(() => {
+    const unsubscribe = loader.subscribe(setLoadState);
+    loader.update(loadOptionsOf(publicKey, environment, scriptUrl, timeout), loadsByItself);
+    return unsubscribe;
+  }, [loader, publicKey, environment, scriptUrl, timeout, loadsByItself]);
+  const current = loadState.key === key ? loadState : null;
+  const status = current ? current.status : "loading";
+  const error = current ? current.error : null;
+  const checkEnabled = checkOnLoad === true || isObject(checkOnLoad);
+  const checkUserId = isObject(checkOnLoad) ? checkOnLoad.userId : void 0;
+  useEffect(() => {
+    if (status !== "ready" || !checkEnabled || checkedRef.current) return;
+    checkedRef.current = true;
+    const checkOptions = checkUserId === void 0 ? {} : { userId: checkUserId };
+    if (loader.isRunning(userIdOf(checkOptions))) return;
+    loader.check(checkOptions).then(ignore, warnCheckOnLoad);
+  }, [loader, status, checkEnabled, checkUserId]);
+  const shieldLabs = useMemo(
+    () => ({
+      status,
+      error,
+      identify: loader.identify,
+      check: loader.check,
+      load: loader.load,
+      getAgent: loader.getAgent
+    }),
+    [loader, status, error]
+  );
+  const value = useMemo(
+    () => ({ shieldLabs, defaultTimeout: loader.defaultTimeout }),
+    [loader, shieldLabs]
+  );
+  return createElement(ShieldLabsContext.Provider, { value }, children);
+}
+function useShieldLabsContext(hook) {
+  const value = useContext(ShieldLabsContext);
+  if (value === null) {
+    throw new Error(
+      "[ShieldLabs] " + hook + '() must be called inside <ShieldLabsProvider>. Render <ShieldLabsProvider publicKey="..."> above the component that calls it.'
+    );
+  }
+  return value;
+}
+function useShieldLabs() {
+  return useShieldLabsContext("useShieldLabs").shieldLabs;
+}
+
+// src/use-identify.ts
+import { useCallback, useEffect as useEffect2, useMemo as useMemo2, useRef as useRef2, useState as useState2 } from "react";
+function agentOptionsOf(callOptions, userId) {
+  const raw = callOptions;
+  if (raw != null && !isObject(raw)) return callOptions;
+  const { userId: ownUserId, ...rest } = callOptions != null ? callOptions : {};
+  const effectiveUserId = callOptions != null && "userId" in callOptions ? ownUserId : userId;
+  return effectiveUserId == null ? rest : { ...rest, userId: effectiveUserId };
+}
+function timeoutOf(options, defaultTimeout) {
+  const timeout = options == null ? void 0 : options.timeout;
+  return timeout === void 0 ? defaultTimeout : timeout;
+}
+function isSameCall(running, options, timeout) {
+  const raw = options;
+  return isObject(raw) && running.userId === (options == null ? void 0 : options.userId) && running.timeout === timeout;
+}
+var IDLE = { result: null, isLoading: false, error: null };
+var LOADING = { result: null, isLoading: true, error: null };
+function useIdentify(options = {}) {
+  const { shieldLabs, defaultTimeout } = useShieldLabsContext("useIdentify");
+  const identifyWithAgent = shieldLabs.identify;
+  const { userId, runOnMount = false } = options;
+  const [state, setState] = useState2(runOnMount ? LOADING : IDLE);
+  const connectedRef = useRef2(false);
+  const queuedRef = useRef2(null);
+  const latestRef = useRef2({});
+  const runningRef = useRef2([]);
+  const mountRunRef = useRef2(runOnMount);
+  const apply = useCallback((next) => {
+    if (connectedRef.current) setState(next);
+    else queuedRef.current = next;
+  }, []);
+  useEffect2(() => {
+    connectedRef.current = true;
+    const queued = queuedRef.current;
+    queuedRef.current = null;
+    if (queued) apply(queued);
+    return () => {
+      connectedRef.current = false;
+    };
+  }, [apply]);
+  const identify = useCallback(
+    (callOptions) => {
+      const agentOptions = agentOptionsOf(callOptions, userId);
+      const timeout = timeoutOf(agentOptions, defaultTimeout());
+      const shared = runningRef.current.find((running) => isSameCall(running, agentOptions, timeout));
+      if (shared) {
+        if (latestRef.current !== shared.token) {
+          latestRef.current = shared.token;
+          apply(LOADING);
+        }
+        return shared.promise;
+      }
+      const token = {};
+      latestRef.current = token;
+      const publish = (next) => {
+        if (latestRef.current === token) apply(next);
+      };
+      let entry = null;
+      const settle = (next) => {
+        runningRef.current = runningRef.current.filter((running) => running !== entry);
+        publish(next);
+      };
+      publish(LOADING);
+      const promise = new Promise((resolve) => {
+        resolve(identifyWithAgent(agentOptions));
+      }).then(
+        (result) => {
+          settle({ result, isLoading: false, error: null });
+          return result;
+        },
+        (error) => {
+          settle({
+            result: null,
+            isLoading: false,
+            error: asShieldLabsError(error, "not_initialized", "The identification did not complete.")
+          });
+          return null;
+        }
+      );
+      const raw = agentOptions;
+      if (isObject(raw)) {
+        entry = { userId: agentOptions == null ? void 0 : agentOptions.userId, timeout, promise, token };
+        runningRef.current = [...runningRef.current, entry];
+      }
+      return promise;
+    },
+    [identifyWithAgent, defaultTimeout, userId, apply]
+  );
+  const reset = useCallback(() => {
+    latestRef.current = {};
+    runningRef.current = [];
+    apply(IDLE);
+  }, [apply]);
+  useEffect2(() => {
+    if (!mountRunRef.current) return;
+    mountRunRef.current = false;
+    void identify();
+  }, [identify]);
+  return useMemo2(
+    () => ({ identify, result: state.result, isLoading: state.isLoading, error: state.error, reset }),
+    [identify, state, reset]
+  );
+}
+
+// src/index.ts
+import { ShieldLabsError as ShieldLabsError4 } from "@shieldlabs-ai/js";
+export {
+  ShieldLabsError4 as ShieldLabsError,
+  ShieldLabsProvider,
+  useIdentify,
+  useShieldLabs
+};

package/package.json

@@ -0,0 +1,86 @@
+{
+  "name": "@shieldlabs-ai/react",
+  "version": "1.0.0",
+  "description": "React bindings for ShieldLabs device intelligence: a provider that loads the agent once and hooks that return a request ID for every identification.",
+  "keywords": [
+    "shieldlabs",
+    "react",
+    "react-hooks",
+    "device-intelligence",
+    "fraud-detection",
+    "risk-score",
+    "identification"
+  ],
+  "homepage": "https://docs.shieldlabs.ai",
+  "bugs": {
+    "url": "https://github.com/ShieldLabs-ai/shieldlabs-react/issues",
+    "email": "contact@shieldlabs.ai"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/ShieldLabs-ai/shieldlabs-react.git"
+  },
+  "license": "MIT",
+  "author": "ShieldLabs Inc. <contact@shieldlabs.ai>",
+  "type": "module",
+  "sideEffects": false,
+  "main": "./dist/index.cjs",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "import": {
+        "types": "./dist/index.d.ts",
+        "default": "./dist/index.js"
+      },
+      "require": {
+        "types": "./dist/index.d.cts",
+        "default": "./dist/index.cjs"
+      }
+    },
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "dist",
+    "CHANGELOG.md"
+  ],
+  "engines": {
+    "node": ">=18"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "scripts": {
+    "prebuild": "node scripts/check-core.mjs",
+    "build": "tsup",
+    "pretypecheck": "node scripts/check-core.mjs",
+    "typecheck": "tsc --noEmit && tsc --noEmit -p tsconfig.build.json",
+    "prelint": "node scripts/check-core.mjs",
+    "lint": "eslint .",
+    "pretest": "npm run build",
+    "test": "vitest run",
+    "prepublishOnly": "npm run build"
+  },
+  "peerDependencies": {
+    "@shieldlabs-ai/js": "^1.0.0",
+    "react": "^18.0.0 || ^19.0.0"
+  },
+  "devDependencies": {
+    "@eslint/js": "~9.39.5",
+    "@testing-library/dom": "^10.4.2",
+    "@testing-library/react": "^16.3.3",
+    "@types/node": "^22.0.0",
+    "@types/react": "^19.3.0",
+    "@types/react-dom": "^19.3.0",
+    "@vitest/coverage-v8": "~3.2.7",
+    "eslint": "~9.39.5",
+    "eslint-plugin-react-hooks": "^7.1.1",
+    "happy-dom": "^20.14.5",
+    "react": "^19.3.0",
+    "react-dom": "^19.3.0",
+    "tsup": "^8.5.1",
+    "typescript": "~5.9.3",
+    "typescript-eslint": "^8.71.0",
+    "vitest": "~3.2.7"
+  }
+}