@shieldlabs-ai/react 1.0.0

package/dist/index.cjs

@@ -0,0 +1,380 @@
+"use client";
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/index.ts
+var src_exports = {};
+__export(src_exports, {
+  ShieldLabsError: () => import_js4.ShieldLabsError,
+  ShieldLabsProvider: () => ShieldLabsProvider,
+  useIdentify: () => useIdentify,
+  useShieldLabs: () => useShieldLabs
+});
+module.exports = __toCommonJS(src_exports);
+
+// src/provider.ts
+var import_react = require("react");
+var import_js3 = require("@shieldlabs-ai/js");
+
+// src/internal.ts
+var import_js = require("@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 import_js.ShieldLabsError ? error : new import_js.ShieldLabsError(code, message, error);
+}
+function withTimeout(promise, ms, message) {
+  return new Promise((resolve, reject) => {
+    const timer = setTimeout(() => {
+      reject(new import_js.ShieldLabsError("timeout", message));
+    }, ms);
+    const clear = () => {
+      clearTimeout(timer);
+    };
+    promise.then(clear, clear);
+    promise.then(resolve, reject);
+  });
+}
+function ignore() {
+}
+
+// src/loader.ts
+var import_js2 = require("@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((0, import_js2.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 import_js2.ShieldLabsError("not_initialized", NOT_LOADED)),
+    check: (callOptions) => allowed ? track(callOptions, withAgent(callOptions, (agent, agentOptions) => agent.check(agentOptions))) : Promise.resolve(null)
+  };
+}
+
+// src/provider.ts
+var ShieldLabsContext = (0, import_react.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 import_js3.ShieldLabsError && 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] = (0, import_react.useState)(
+    () => createAgentLoader(loadOptionsOf(publicKey, environment, scriptUrl, timeout), loadsByItself)
+  );
+  const [loadState, setLoadState] = (0, import_react.useState)(() => ({ key, status: "loading", error: null }));
+  const checkedRef = (0, import_react.useRef)(false);
+  (0, import_react.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;
+  (0, import_react.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 = (0, import_react.useMemo)(
+    () => ({
+      status,
+      error,
+      identify: loader.identify,
+      check: loader.check,
+      load: loader.load,
+      getAgent: loader.getAgent
+    }),
+    [loader, status, error]
+  );
+  const value = (0, import_react.useMemo)(
+    () => ({ shieldLabs, defaultTimeout: loader.defaultTimeout }),
+    [loader, shieldLabs]
+  );
+  return (0, import_react.createElement)(ShieldLabsContext.Provider, { value }, children);
+}
+function useShieldLabsContext(hook) {
+  const value = (0, import_react.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
+var import_react2 = require("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] = (0, import_react2.useState)(runOnMount ? LOADING : IDLE);
+  const connectedRef = (0, import_react2.useRef)(false);
+  const queuedRef = (0, import_react2.useRef)(null);
+  const latestRef = (0, import_react2.useRef)({});
+  const runningRef = (0, import_react2.useRef)([]);
+  const mountRunRef = (0, import_react2.useRef)(runOnMount);
+  const apply = (0, import_react2.useCallback)((next) => {
+    if (connectedRef.current) setState(next);
+    else queuedRef.current = next;
+  }, []);
+  (0, import_react2.useEffect)(() => {
+    connectedRef.current = true;
+    const queued = queuedRef.current;
+    queuedRef.current = null;
+    if (queued) apply(queued);
+    return () => {
+      connectedRef.current = false;
+    };
+  }, [apply]);
+  const identify = (0, import_react2.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 = (0, import_react2.useCallback)(() => {
+    latestRef.current = {};
+    runningRef.current = [];
+    apply(IDLE);
+  }, [apply]);
+  (0, import_react2.useEffect)(() => {
+    if (!mountRunRef.current) return;
+    mountRunRef.current = false;
+    void identify();
+  }, [identify]);
+  return (0, import_react2.useMemo)(
+    () => ({ identify, result: state.result, isLoading: state.isLoading, error: state.error, reset }),
+    [identify, state, reset]
+  );
+}
+
+// src/index.ts
+var import_js4 = require("@shieldlabs-ai/js");
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  ShieldLabsError,
+  ShieldLabsProvider,
+  useIdentify,
+  useShieldLabs
+});

package/dist/index.d.cts

@@ -0,0 +1,118 @@
+import { ReactNode, ReactElement } from 'react';
+import { LoadOptions, ShieldLabsError, IdentifyOptions, IdentifyResult, ShieldLabsAgent } from '@shieldlabs-ai/js';
+export { IdentifyOptions, IdentifyResult, InteractionIdentifier, LoadOptions, ShieldLabsAgent, ShieldLabsError, ShieldLabsErrorCode } from '@shieldlabs-ai/js';
+
+/** Where the agent is: `'loading'`, `'ready'`, or `'error'` when it could not be loaded. */
+type ShieldLabsStatus = 'loading' | 'ready' | 'error';
+
+/**
+ * Props of {@link ShieldLabsProvider}: the `load()` options of `@shieldlabs-ai/js` plus `autoLoad` and
+ * `checkOnLoad`.
+ */
+interface ShieldLabsProviderProps extends LoadOptions {
+    /**
+     * Loads the agent after the first render in the browser. With `false`, nothing loads until `load()`
+     * from `useShieldLabs()` is called or `autoLoad` becomes `true`, for example once the user has given
+     * consent. Default `true`.
+     */
+    autoLoad?: boolean;
+    /**
+     * Runs `check()` once per provider mount when the agent is ready, for passive monitoring of the
+     * visit, unless an `identify()` or `check()` for the same User HID is running at that moment. `true`
+     * checks anonymously, `{ userId }` passes a User HID. Default `false`.
+     */
+    checkOnLoad?: boolean | {
+        userId?: string;
+    };
+    children?: ReactNode;
+}
+/** What {@link useShieldLabs} returns. */
+interface UseShieldLabsResult {
+    /** `'loading'` until the agent has loaded, then `'ready'`, or `'error'` when loading failed. */
+    status: ShieldLabsStatus;
+    /** Why loading failed while `status` is `'error'`, otherwise `null`. */
+    error: ShieldLabsError | null;
+    /**
+     * Runs a fresh identification: a new request ID on every call. Waits for the agent while it is
+     * loading; the call's timeout covers that wait and the agent's answer. Rejects with a
+     * `ShieldLabsError` when there is no identification, with `not_initialized` at once while
+     * `autoLoad={false}` and `load()` has not been called. For protected actions, `useIdentify()` adds
+     * state and never rejects.
+     */
+    identify: (options?: IdentifyOptions) => Promise<IdentifyResult>;
+    /**
+     * Background check, limited by the agent to one per visit every five minutes. Resolves `null` when
+     * the agent skipped it, and at once while `autoLoad={false}` and `load()` has not been called. Waits
+     * for the agent while it is loading, within the call's timeout.
+     */
+    check: (options?: IdentifyOptions) => Promise<IdentifyResult | null>;
+    /**
+     * Starts loading the agent: needed only with `autoLoad={false}`, for example once the user has given
+     * consent. Also loads again after a failed load. Safe to call more than once. Call it from an event
+     * handler or an effect, never during render.
+     */
+    load: () => void;
+    /**
+     * The loaded agent of `@shieldlabs-ai/js`, for example for `agent.identifyOnInteraction(form)`. Waits
+     * while the agent loads, and with `autoLoad={false}` until loading starts, with no timeout of its
+     * own. Rejects with the load error when the agent cannot load; the next call loads again when that
+     * can help.
+     */
+    getAgent: () => Promise<ShieldLabsAgent>;
+}
+/**
+ * Loads the ShieldLabs agent once, after the first render in the browser (or once `load()` is called
+ * with `autoLoad={false}`), and gives the components below it `useShieldLabs()` and `useIdentify()`.
+ * Renders only its children. Nothing runs during server-side rendering.
+ */
+declare function ShieldLabsProvider(props: ShieldLabsProviderProps): ReactElement;
+/**
+ * The status of the ShieldLabs agent in the closest {@link ShieldLabsProvider}, its `identify()` and
+ * `check()`, `load()` for deferred loading and `getAgent()`.
+ * Throws when there is no provider above the component.
+ */
+declare function useShieldLabs(): UseShieldLabsResult;
+
+/** Options of {@link useIdentify}. */
+interface UseIdentifyOptions {
+    /**
+     * User HID for every identification of this hook: a hashed or pseudonymous account ID computed on
+     * your server. Omit it for anonymous visitors. Options of `identify()` with a `userId` key override
+     * it, also when the value is `undefined` or `null`, which both identify anonymously.
+     */
+    userId?: string;
+    /**
+     * Runs `identify()` once when the component mounts, as soon as the agent is ready. With
+     * `autoLoad={false}`, a mount before `load()` ends at once with a `not_initialized` error and does
+     * not run again after `load()`. Every run is a billable identification, so use it sparingly.
+     * Default `false`.
+     */
+    runOnMount?: boolean;
+}
+/** What {@link useIdentify} returns. */
+interface UseIdentifyResult {
+    /**
+     * Runs a fresh identification (a new request ID on every call) and resolves its result, or `null`
+     * when there is no identification: the reason is then in `error`. Never rejects. While a call of
+     * this hook with the same User HID and `timeout` is running (a double submit), returns that call
+     * instead of starting another identification. The User HID of a call is its own `userId` when the
+     * options have that key (`undefined` and `null` both mean anonymous), else the hook's. A call
+     * without `timeout` counts as one with the provider `timeout` (10000 ms by default).
+     */
+    identify: (options?: IdentifyOptions) => Promise<IdentifyResult | null>;
+    /** The result of the latest identification, `null` before it resolves, when it failed or after `reset()`. */
+    result: IdentifyResult | null;
+    /** `true` while the latest identification is running. */
+    isLoading: boolean;
+    /** Why the latest identification failed, otherwise `null`. */
+    error: ShieldLabsError | null;
+    /** Clears `result` and `error`. A running identification no longer updates the state. */
+    reset: () => void;
+}
+/**
+ * Identification with loading and error state, for protected actions such as signup, login or
+ * checkout. Must be called inside a {@link ShieldLabsProvider}.
+ */
+declare function useIdentify(options?: UseIdentifyOptions): UseIdentifyResult;
+
+export { ShieldLabsProvider, type ShieldLabsProviderProps, type ShieldLabsStatus, type UseIdentifyOptions, type UseIdentifyResult, type UseShieldLabsResult, useIdentify, useShieldLabs };

package/dist/index.d.ts

@@ -0,0 +1,118 @@
+import { ReactNode, ReactElement } from 'react';
+import { LoadOptions, ShieldLabsError, IdentifyOptions, IdentifyResult, ShieldLabsAgent } from '@shieldlabs-ai/js';
+export { IdentifyOptions, IdentifyResult, InteractionIdentifier, LoadOptions, ShieldLabsAgent, ShieldLabsError, ShieldLabsErrorCode } from '@shieldlabs-ai/js';
+
+/** Where the agent is: `'loading'`, `'ready'`, or `'error'` when it could not be loaded. */
+type ShieldLabsStatus = 'loading' | 'ready' | 'error';
+
+/**
+ * Props of {@link ShieldLabsProvider}: the `load()` options of `@shieldlabs-ai/js` plus `autoLoad` and
+ * `checkOnLoad`.
+ */
+interface ShieldLabsProviderProps extends LoadOptions {
+    /**
+     * Loads the agent after the first render in the browser. With `false`, nothing loads until `load()`
+     * from `useShieldLabs()` is called or `autoLoad` becomes `true`, for example once the user has given
+     * consent. Default `true`.
+     */
+    autoLoad?: boolean;
+    /**
+     * Runs `check()` once per provider mount when the agent is ready, for passive monitoring of the
+     * visit, unless an `identify()` or `check()` for the same User HID is running at that moment. `true`
+     * checks anonymously, `{ userId }` passes a User HID. Default `false`.
+     */
+    checkOnLoad?: boolean | {
+        userId?: string;
+    };
+    children?: ReactNode;
+}
+/** What {@link useShieldLabs} returns. */
+interface UseShieldLabsResult {
+    /** `'loading'` until the agent has loaded, then `'ready'`, or `'error'` when loading failed. */
+    status: ShieldLabsStatus;
+    /** Why loading failed while `status` is `'error'`, otherwise `null`. */
+    error: ShieldLabsError | null;
+    /**
+     * Runs a fresh identification: a new request ID on every call. Waits for the agent while it is
+     * loading; the call's timeout covers that wait and the agent's answer. Rejects with a
+     * `ShieldLabsError` when there is no identification, with `not_initialized` at once while
+     * `autoLoad={false}` and `load()` has not been called. For protected actions, `useIdentify()` adds
+     * state and never rejects.
+     */
+    identify: (options?: IdentifyOptions) => Promise<IdentifyResult>;
+    /**
+     * Background check, limited by the agent to one per visit every five minutes. Resolves `null` when
+     * the agent skipped it, and at once while `autoLoad={false}` and `load()` has not been called. Waits
+     * for the agent while it is loading, within the call's timeout.
+     */
+    check: (options?: IdentifyOptions) => Promise<IdentifyResult | null>;
+    /**
+     * Starts loading the agent: needed only with `autoLoad={false}`, for example once the user has given
+     * consent. Also loads again after a failed load. Safe to call more than once. Call it from an event
+     * handler or an effect, never during render.
+     */
+    load: () => void;
+    /**
+     * The loaded agent of `@shieldlabs-ai/js`, for example for `agent.identifyOnInteraction(form)`. Waits
+     * while the agent loads, and with `autoLoad={false}` until loading starts, with no timeout of its
+     * own. Rejects with the load error when the agent cannot load; the next call loads again when that
+     * can help.
+     */
+    getAgent: () => Promise<ShieldLabsAgent>;
+}
+/**
+ * Loads the ShieldLabs agent once, after the first render in the browser (or once `load()` is called
+ * with `autoLoad={false}`), and gives the components below it `useShieldLabs()` and `useIdentify()`.
+ * Renders only its children. Nothing runs during server-side rendering.
+ */
+declare function ShieldLabsProvider(props: ShieldLabsProviderProps): ReactElement;
+/**
+ * The status of the ShieldLabs agent in the closest {@link ShieldLabsProvider}, its `identify()` and
+ * `check()`, `load()` for deferred loading and `getAgent()`.
+ * Throws when there is no provider above the component.
+ */
+declare function useShieldLabs(): UseShieldLabsResult;
+
+/** Options of {@link useIdentify}. */
+interface UseIdentifyOptions {
+    /**
+     * User HID for every identification of this hook: a hashed or pseudonymous account ID computed on
+     * your server. Omit it for anonymous visitors. Options of `identify()` with a `userId` key override
+     * it, also when the value is `undefined` or `null`, which both identify anonymously.
+     */
+    userId?: string;
+    /**
+     * Runs `identify()` once when the component mounts, as soon as the agent is ready. With
+     * `autoLoad={false}`, a mount before `load()` ends at once with a `not_initialized` error and does
+     * not run again after `load()`. Every run is a billable identification, so use it sparingly.
+     * Default `false`.
+     */
+    runOnMount?: boolean;
+}
+/** What {@link useIdentify} returns. */
+interface UseIdentifyResult {
+    /**
+     * Runs a fresh identification (a new request ID on every call) and resolves its result, or `null`
+     * when there is no identification: the reason is then in `error`. Never rejects. While a call of
+     * this hook with the same User HID and `timeout` is running (a double submit), returns that call
+     * instead of starting another identification. The User HID of a call is its own `userId` when the
+     * options have that key (`undefined` and `null` both mean anonymous), else the hook's. A call
+     * without `timeout` counts as one with the provider `timeout` (10000 ms by default).
+     */
+    identify: (options?: IdentifyOptions) => Promise<IdentifyResult | null>;
+    /** The result of the latest identification, `null` before it resolves, when it failed or after `reset()`. */
+    result: IdentifyResult | null;
+    /** `true` while the latest identification is running. */
+    isLoading: boolean;
+    /** Why the latest identification failed, otherwise `null`. */
+    error: ShieldLabsError | null;
+    /** Clears `result` and `error`. A running identification no longer updates the state. */
+    reset: () => void;
+}
+/**
+ * Identification with loading and error state, for protected actions such as signup, login or
+ * checkout. Must be called inside a {@link ShieldLabsProvider}.
+ */
+declare function useIdentify(options?: UseIdentifyOptions): UseIdentifyResult;
+
+export { ShieldLabsProvider, type ShieldLabsProviderProps, type ShieldLabsStatus, type UseIdentifyOptions, type UseIdentifyResult, type UseShieldLabsResult, useIdentify, useShieldLabs };