@shieldlabs-ai/vue 1.0.0

package/dist/index.d.ts

@@ -0,0 +1,166 @@
+import { ShieldLabsError, IdentifyOptions, IdentifyResult, ShieldLabsAgent, LoadOptions } from '@shieldlabs-ai/js';
+export { IdentifyOptions, IdentifyResult, InteractionIdentifier, LoadOptions, ShieldLabsAgent, ShieldLabsError, ShieldLabsErrorCode } from '@shieldlabs-ai/js';
+import { Ref, App, MaybeRefOrGetter, InjectionKey } from 'vue';
+
+/**
+ * State of the agent for this app:
+ *
+ * - `loading`: not ready yet. Always the value during server-side rendering and in the first render
+ *   of every component, so that hydration matches the server HTML. With `autoLoad: false` it stays
+ *   `loading` until `load()` is called.
+ * - `ready`: the agent is loaded; identifications start right away.
+ * - `error`: the last load failed. `error` says why; the next `identify()`, `check()`, `getAgent()`
+ *   or `load()` tries again.
+ */
+type ShieldLabsStatus = 'loading' | 'ready' | 'error';
+/**
+ * `checkOnLoad` plugin option. `true` runs one anonymous `check()` when the agent is ready,
+ * `{ userId }` runs it for a User HID. Default `false`.
+ */
+type CheckOnLoadOption = boolean | {
+    userId?: string | null;
+};
+/** Options of `createShieldLabs()`: the `@shieldlabs-ai/js` load options plus the plugin options. */
+interface ShieldLabsOptions extends LoadOptions {
+    /**
+     * Runs `check()` once when the agent becomes ready, for passive monitoring of the visit. The agent
+     * limits it to one per visit every five minutes. Skipped when an `identify()` or `check()` for the
+     * same User HID is already in flight at that moment: that call identifies the visit, and the agent
+     * runs one identification at a time for a User HID. Default `false`.
+     */
+    checkOnLoad?: CheckOnLoadOption;
+    /**
+     * Loads the agent right after the app is mounted (default `true`). With `false` nothing loads until
+     * `load()` from `useShieldLabs()` is called, for example once the visitor has given consent. Until
+     * then `status` stays `loading` and `getAgent()` waits, while `identify()` and `check()` fail fast
+     * instead of waiting: `identify()` rejects with `not_initialized`, `check()` resolves `null`, and
+     * the `identify()` of `useIdentify()` resolves `null` with a `not_initialized` error.
+     */
+    autoLoad?: boolean;
+}
+/** The Vue plugin returned by {@link createShieldLabs}. Pass it to `app.use()`. */
+interface ShieldLabsPlugin {
+    install: (app: App) => void;
+}
+/** What `useShieldLabs()` returns, and what the plugin provides under `shieldLabsKey`. */
+interface ShieldLabsContext {
+    /** `loading`, `ready` or `error`. */
+    readonly status: Readonly<Ref<ShieldLabsStatus>>;
+    /** Why the last load failed, otherwise `null`. */
+    readonly error: Readonly<Ref<ShieldLabsError | null>>;
+    /**
+     * Fresh identification with a new request ID. Waits for the agent; `timeout` covers the wait and
+     * the agent's answer together. Rejects with a `ShieldLabsError` when there is no identification,
+     * and with `not_initialized` right away while `autoLoad: false` waits for `load()`.
+     */
+    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 right away while `autoLoad: false` waits for `load()`. Waits for
+     * the agent like `identify()`.
+     */
+    check: (options?: IdentifyOptions) => Promise<IdentifyResult | null>;
+    /**
+     * Starts loading the agent now, unless it is loaded or loading. With `autoLoad: false` nothing
+     * loads before this call. After a failed load it loads again. The outcome shows in `status` and
+     * `error`. Does nothing during server-side rendering.
+     */
+    load: () => void;
+    /**
+     * The agent of `@shieldlabs-ai/js` once it has loaded, for example to identify on the first
+     * interaction with a form: `getAgent().then((agent) => agent.identifyOnInteraction(form))`.
+     * Loads the agent when needed; with `autoLoad: false` it waits until `load()` is called, with no
+     * timeout of its own. Rejects with the `ShieldLabsError` of a failed load, and with
+     * `unsupported_environment` during server-side rendering.
+     */
+    getAgent: () => Promise<ShieldLabsAgent>;
+}
+/** Return value of `useShieldLabs()`. */
+type UseShieldLabsReturn = ShieldLabsContext;
+/** Options of `useIdentify()`. */
+interface UseIdentifyOptions {
+    /**
+     * User HID computed on your server, read when `identify()` runs. A string, a ref or a getter;
+     * `undefined` or `null` for anonymous identifications.
+     */
+    userId?: MaybeRefOrGetter<string | null | undefined>;
+    /**
+     * Calls `identify()` once when the component is mounted (after the agent is ready). Each call is
+     * a billable identification: use it sparingly. With `autoLoad: false` that identification ends
+     * right away with a `not_initialized` error unless `load()` was called before the component
+     * mounted, and a later `load()` does not start it again. Default `false`.
+     */
+    runOnMount?: boolean;
+}
+/** Return value of `useIdentify()`. */
+interface UseIdentifyReturn {
+    /**
+     * Runs a fresh identification. Resolves with the result, or `null` when there is no
+     * identification (the reason is in `error`); it never rejects. Options override the composable's
+     * `userId` for this call, and `timeout` covers the wait for the agent and its answer together.
+     * While a call of this helper with the same `userId` and `timeout` is in flight (a double submit),
+     * it returns that call instead of starting another identification. A call without `timeout`
+     * counts as one with the plugin's `timeout` (10 seconds by default).
+     */
+    identify: (options?: IdentifyOptions) => Promise<IdentifyResult | null>;
+    /** The result of the latest `identify()`, `null` before it resolves or when it failed. */
+    readonly result: Readonly<Ref<IdentifyResult | null>>;
+    /** `true` while the latest `identify()` runs. */
+    readonly isLoading: Readonly<Ref<boolean>>;
+    /** Why the latest `identify()` returned `null`, otherwise `null`. */
+    readonly error: Readonly<Ref<ShieldLabsError | null>>;
+    /**
+     * Clears `result`, `error` and `isLoading`. A call still in flight no longer updates them, unless
+     * `identify()` is called again with the same `userId` and `timeout` while it runs: that call
+     * returns it.
+     */
+    reset: () => void;
+}
+
+/**
+ * Creates the ShieldLabs plugin for `app.use()`. The plugin loads the agent once per app, after the
+ * app is mounted in the browser (with `autoLoad: false`, when `load()` from `useShieldLabs()` is
+ * called): never during server-side rendering and never before hydration.
+ * The load options (`publicKey`, `environment`, `scriptUrl`, `timeout`) are checked by
+ * `@shieldlabs-ai/js` when the agent loads; a problem shows up in `status` and `error`.
+ *
+ * @example
+ * createApp(App)
+ *   .use(createShieldLabs({ publicKey: import.meta.env.VITE_SHIELDLABS_PUBLIC_KEY }))
+ *   .mount('#app');
+ */
+declare function createShieldLabs(options: ShieldLabsOptions): ShieldLabsPlugin;
+
+/**
+ * The agent state of the app (`status`, `error`), its `identify()` and `check()`, `load()` to start
+ * loading (with `autoLoad: false`, for example after consent) and `getAgent()` for the agent itself.
+ *
+ * Inside a component, `status` is `loading` and `error` is `null` until the component is mounted,
+ * as during server-side rendering, so hydration always matches the server HTML. Nothing loads or
+ * identifies during server-side rendering.
+ */
+declare function useShieldLabs(): UseShieldLabsReturn;
+/**
+ * An identify helper with `result`, `isLoading` and `error` refs. `identify()` never rejects: it
+ * resolves `null` when there is no identification, so the protected action can go ahead as
+ * unverified. `userId` is read when `identify()` runs; changing it never starts an identification.
+ *
+ * @example
+ * const { identify, isLoading } = useIdentify({ userId: () => user.value?.hid });
+ * async function onSubmit() {
+ *   const result = await identify();
+ *   await fetch('/api/signup', { method: 'POST', body: JSON.stringify({ requestId: result?.requestId ?? null }) });
+ * }
+ */
+declare function useIdentify(options?: UseIdentifyOptions): UseIdentifyReturn;
+
+/**
+ * Injection key under which the plugin provides the {@link ShieldLabsContext} of an app. Use it
+ * with `provide()` to give components a stand-in context in tests.
+ */
+declare const shieldLabsKey: InjectionKey<ShieldLabsContext>;
+
+/** Version of `@shieldlabs-ai/vue`. A test keeps it equal to `package.json`. */
+declare const VERSION = "1.0.0";
+
+export { type CheckOnLoadOption, type ShieldLabsContext, type ShieldLabsOptions, type ShieldLabsPlugin, type ShieldLabsStatus, type UseIdentifyOptions, type UseIdentifyReturn, type UseShieldLabsReturn, VERSION, createShieldLabs, shieldLabsKey, useIdentify, useShieldLabs };

package/dist/index.js

@@ -0,0 +1,361 @@
+import { ShieldLabsError, load } from '@shieldlabs-ai/js';
+export { ShieldLabsError } from '@shieldlabs-ai/js';
+import { getCurrentInstance, shallowRef, onMounted, computed, shallowReadonly, toValue, hasInjectionContext, inject } from 'vue';
+
+// src/plugin.ts
+var shieldLabsKey = /* @__PURE__ */ Symbol("shieldlabs");
+var DEFAULT_TIMEOUT = 1e4;
+var MAX_TIMEOUT = 2147483647;
+var internals = /* @__PURE__ */ new WeakMap();
+var serverContext;
+function isBrowser() {
+  return typeof window !== "undefined" && typeof document !== "undefined";
+}
+function toShieldLabsError(reason, code, message) {
+  return reason instanceof ShieldLabsError ? reason : new ShieldLabsError(code, message, reason);
+}
+function isObject(value) {
+  return typeof value === "object" && value !== null;
+}
+function isTimeout(value) {
+  return typeof value === "number" && value > 0 && value <= MAX_TIMEOUT;
+}
+function ignore() {
+}
+function userOf(options) {
+  return isObject(options) && typeof options.userId === "string" ? options.userId : void 0;
+}
+function withTimeLeft(options, left, total) {
+  const raw = options;
+  if (left >= total) return options;
+  if (raw === void 0 || raw === null) return { timeout: left };
+  if (!isObject(raw) || raw.timeout !== void 0 && !isTimeout(raw.timeout)) return options;
+  return { ...options, timeout: left };
+}
+function createContext(loadOptions, checkOnLoad, autoLoad) {
+  const status = shallowRef("loading");
+  const error = shallowRef(null);
+  let loading;
+  let agent;
+  let loadAllowed = autoLoad;
+  let started = false;
+  let checked = false;
+  const inFlight = [];
+  let allow = ignore;
+  const allowed = new Promise((resolve) => {
+    allow = resolve;
+  });
+  allowed.catch(ignore);
+  const defaultTimeout = isTimeout(loadOptions.timeout) ? loadOptions.timeout : DEFAULT_TIMEOUT;
+  const runCheckOnLoad = (ready) => {
+    var _a;
+    if (checkOnLoad === false || checked) return;
+    checked = true;
+    const userId = checkOnLoad === true ? void 0 : (_a = checkOnLoad.userId) != null ? _a : void 0;
+    if (inFlight.includes(userId)) return;
+    const options = userId === void 0 ? void 0 : { userId };
+    new Promise((resolve) => {
+      resolve(ready.check(options));
+    }).catch((reason) => {
+      if (reason instanceof ShieldLabsError && reason.code === "invalid_options") {
+        console.warn("[ShieldLabs] checkOnLoad: " + reason.message);
+      }
+    });
+  };
+  const startLoad = () => {
+    if (loading) return loading;
+    started = true;
+    const next = new Promise((resolve) => {
+      resolve(load(loadOptions));
+    }).catch((reason) => {
+      throw toShieldLabsError(reason, "load_failed", "Could not load the ShieldLabs agent.");
+    });
+    loading = next;
+    status.value = "loading";
+    error.value = null;
+    next.then(
+      (ready) => {
+        agent = ready;
+        status.value = "ready";
+        runCheckOnLoad(ready);
+      },
+      (reason) => {
+        loading = void 0;
+        const failure = toShieldLabsError(reason, "load_failed", "Could not load the ShieldLabs agent.");
+        if (failure.code === "invalid_options") console.warn("[ShieldLabs] " + failure.message);
+        error.value = failure;
+        status.value = "error";
+      }
+    );
+    return next;
+  };
+  const getAgent = () => {
+    if (!isBrowser()) return load(loadOptions);
+    return loadAllowed ? startLoad() : allowed;
+  };
+  const loadNow = () => {
+    if (!isBrowser()) return;
+    const first = !loadAllowed;
+    loadAllowed = true;
+    const next = startLoad();
+    if (first) allow(next);
+  };
+  const beforeLoad = () => !loadAllowed && isBrowser();
+  const notLoaded = () => new ShieldLabsError("not_initialized", "The ShieldLabs agent is not loaded. With autoLoad: false it loads once load() is called.");
+  const timedOut = (total) => new ShieldLabsError("timeout", "The ShieldLabs agent did not load within " + String(total) + " ms.");
+  const withAgent = (options, call) => {
+    const user = userOf(options);
+    inFlight.push(user);
+    const outcome = new Promise((resolve, reject) => {
+      if (agent) {
+        resolve(call(agent, options));
+        return;
+      }
+      const raw = options;
+      const own = isObject(raw) ? raw.timeout : void 0;
+      const total = isTimeout(own) ? own : defaultTimeout;
+      const startedAt = Date.now();
+      let settled = false;
+      const timer = setTimeout(() => {
+        settled = true;
+        reject(timedOut(total));
+      }, total);
+      getAgent().then(
+        (ready) => {
+          if (settled) return;
+          settled = true;
+          clearTimeout(timer);
+          const left = total - (Date.now() - startedAt);
+          if (left < 1) reject(timedOut(total));
+          else resolve(call(ready, withTimeLeft(options, left, total)));
+        },
+        (reason) => {
+          if (settled) return;
+          settled = true;
+          clearTimeout(timer);
+          reject(toShieldLabsError(reason, "load_failed", "Could not load the ShieldLabs agent."));
+        }
+      );
+    });
+    const finish = () => {
+      inFlight.splice(inFlight.indexOf(user), 1);
+    };
+    outcome.then(finish, finish);
+    return outcome;
+  };
+  const context = {
+    status: shallowReadonly(status),
+    error: shallowReadonly(error),
+    // Like the agent: identify() rejects with not_initialized, check() resolves null.
+    identify: (options) => beforeLoad() ? Promise.reject(notLoaded()) : withAgent(options, (ready, agentOptions) => ready.identify(agentOptions)),
+    check: (options) => beforeLoad() ? Promise.resolve(null) : withAgent(options, (ready, agentOptions) => ready.check(agentOptions)),
+    load: loadNow,
+    getAgent
+  };
+  internals.set(context, {
+    // With autoLoad the plugin starts loading once the app is mounted, unless a load has already
+    // started. After a failed load only identify(), check(), getAgent() and load() load again.
+    start: () => {
+      if (started || !autoLoad || !isBrowser()) return;
+      void startLoad();
+    },
+    defaultTimeout
+  });
+  return context;
+}
+function startContext(context) {
+  var _a;
+  (_a = internals.get(context)) == null ? void 0 : _a.start();
+}
+function defaultTimeoutOf(context) {
+  var _a, _b;
+  return (_b = (_a = internals.get(context)) == null ? void 0 : _a.defaultTimeout) != null ? _b : DEFAULT_TIMEOUT;
+}
+function createServerContext() {
+  const unsupported = () => Promise.reject(
+    new ShieldLabsError("unsupported_environment", "ShieldLabs identifies in the browser, not during server-side rendering.")
+  );
+  return {
+    status: shallowReadonly(shallowRef("loading")),
+    error: shallowReadonly(shallowRef(null)),
+    identify: unsupported,
+    check: unsupported,
+    load: ignore,
+    getAgent: unsupported
+  };
+}
+function injectContext(caller) {
+  const inContext = hasInjectionContext();
+  const context = inContext ? inject(shieldLabsKey, null) : null;
+  if (context) return context;
+  if (!isBrowser()) return serverContext != null ? serverContext : serverContext = createServerContext();
+  if (!inContext) {
+    throw new Error("[ShieldLabs] " + caller + "() must be called inside setup() of a component or in app.runWithContext().");
+  }
+  throw new Error(
+    "[ShieldLabs] " + caller + "() found no ShieldLabs plugin. Install it before mounting the app: app.use(createShieldLabs({ publicKey })). In Nuxt, add the client plugin plugins/shieldlabs.client.ts."
+  );
+}
+
+// src/plugin.ts
+var installedApps = /* @__PURE__ */ new WeakSet();
+function invalidOptions(message) {
+  return new ShieldLabsError("invalid_options", message);
+}
+function checkCheckOnLoad(value) {
+  if (value === void 0 || value === false) return false;
+  if (value === true) return true;
+  if (typeof value === "object" && value !== null) {
+    const userId = value.userId;
+    if (userId === void 0 || userId === null) return {};
+    if (typeof userId === "string") return { userId };
+  }
+  throw invalidOptions("checkOnLoad must be true, false or { userId }.");
+}
+function createShieldLabs(options) {
+  var _a;
+  const candidate = options;
+  if (typeof candidate !== "object" || candidate === null) {
+    throw invalidOptions("createShieldLabs() needs an options object with the Public Key of your domain: createShieldLabs({ publicKey }).");
+  }
+  const checkOnLoad = checkCheckOnLoad(options.checkOnLoad);
+  const autoLoad = (_a = options.autoLoad) != null ? _a : true;
+  if (typeof autoLoad !== "boolean") throw invalidOptions("autoLoad must be true or false.");
+  const loadOptions = { publicKey: options.publicKey };
+  if (options.environment !== void 0) loadOptions.environment = options.environment;
+  if (options.scriptUrl !== void 0) loadOptions.scriptUrl = options.scriptUrl;
+  if (options.timeout !== void 0) loadOptions.timeout = options.timeout;
+  return {
+    install(app) {
+      if (installedApps.has(app)) {
+        console.warn("[ShieldLabs] This app already has a ShieldLabs plugin; the second one is ignored.");
+        return;
+      }
+      installedApps.add(app);
+      const context = createContext(loadOptions, checkOnLoad, autoLoad);
+      app.provide(shieldLabsKey, context);
+      const mount = app.mount.bind(app);
+      app.mount = (...args) => {
+        const root = mount(...args);
+        startContext(context);
+        return root;
+      };
+    }
+  };
+}
+function useShieldLabs() {
+  const context = injectContext("useShieldLabs");
+  if (!getCurrentInstance()) return context;
+  const mounted = shallowRef(false);
+  onMounted(() => {
+    mounted.value = true;
+    startContext(context);
+  });
+  return {
+    status: computed(() => mounted.value ? context.status.value : "loading"),
+    error: computed(() => mounted.value ? context.error.value : null),
+    identify: context.identify,
+    check: context.check,
+    load: context.load,
+    getAgent: context.getAgent
+  };
+}
+function orUndefined(value) {
+  return value != null ? value : void 0;
+}
+function boundOf(timeout, fallback) {
+  return timeout === void 0 ? fallback : timeout;
+}
+function useIdentify(options = {}) {
+  const context = injectContext("useIdentify");
+  const defaultTimeout = defaultTimeoutOf(context);
+  const result = shallowRef(null);
+  const isLoading = shallowRef(false);
+  const error = shallowRef(null);
+  const running = /* @__PURE__ */ new Set();
+  let lastId = 0;
+  let owner = 0;
+  const own = (id) => {
+    owner = id;
+    result.value = null;
+    error.value = null;
+    isLoading.value = true;
+  };
+  const identify = (overrides) => {
+    const given = overrides != null ? overrides : {};
+    let callOptions = given;
+    let key;
+    if (typeof given === "object" && given !== null) {
+      const picked = given;
+      const userId = "userId" in picked ? orUndefined(picked.userId) : orUndefined(toValue(options.userId));
+      const timeout = picked.timeout;
+      const bound = boundOf(timeout, defaultTimeout);
+      for (const call of running) {
+        if (call.userId === userId && Object.is(call.timeout, bound)) {
+          if (owner !== call.id) own(call.id);
+          return call.promise;
+        }
+      }
+      key = { userId, timeout: bound };
+      const built = {};
+      if (userId !== void 0) built.userId = userId;
+      if (timeout !== void 0) built.timeout = timeout;
+      callOptions = built;
+    }
+    const id = ++lastId;
+    own(id);
+    const promise = new Promise((resolve) => {
+      resolve(context.identify(callOptions));
+    }).then(
+      (value) => {
+        if (owner === id) {
+          result.value = value;
+          isLoading.value = false;
+        }
+        return value;
+      },
+      (reason) => {
+        const failure = toShieldLabsError(reason, "not_initialized", "The identification did not start.");
+        if (owner === id) {
+          error.value = failure;
+          isLoading.value = false;
+        }
+        return null;
+      }
+    );
+    if (key !== void 0) {
+      const entry = { id, ...key, promise };
+      running.add(entry);
+      void promise.then(() => {
+        running.delete(entry);
+      });
+    }
+    return promise;
+  };
+  const reset = () => {
+    owner = 0;
+    result.value = null;
+    error.value = null;
+    isLoading.value = false;
+  };
+  if (getCurrentInstance()) {
+    onMounted(() => {
+      startContext(context);
+      if (options.runOnMount === true) void identify();
+    });
+  } else if (options.runOnMount === true && isBrowser()) {
+    void identify();
+  }
+  return {
+    identify,
+    result: shallowReadonly(result),
+    isLoading: shallowReadonly(isLoading),
+    error: shallowReadonly(error),
+    reset
+  };
+}
+
+// src/version.ts
+var VERSION = "1.0.0";
+
+export { VERSION, createShieldLabs, shieldLabsKey, useIdentify, useShieldLabs };

package/package.json

@@ -0,0 +1,79 @@
+{
+  "name": "@shieldlabs-ai/vue",
+  "version": "1.0.0",
+  "description": "Vue 3 and Nuxt bindings for ShieldLabs device intelligence: a plugin that loads the agent once and composables that return a request ID with loading and error state.",
+  "keywords": [
+    "shieldlabs",
+    "vue",
+    "nuxt",
+    "device-intelligence",
+    "fraud-detection",
+    "risk-score",
+    "identification"
+  ],
+  "homepage": "https://docs.shieldlabs.ai",
+  "bugs": {
+    "url": "https://github.com/ShieldLabs-ai/shieldlabs-vue/issues",
+    "email": "contact@shieldlabs.ai"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/ShieldLabs-ai/shieldlabs-vue.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": {
+    "build": "tsup",
+    "typecheck": "tsc --noEmit && tsc --noEmit -p tsconfig.build.json",
+    "lint": "eslint .",
+    "pretest": "npm run build",
+    "test": "vitest run",
+    "prepublishOnly": "npm run build"
+  },
+  "peerDependencies": {
+    "@shieldlabs-ai/js": "^1.0.0",
+    "vue": "^3.3.0"
+  },
+  "devDependencies": {
+    "@eslint/js": "~9.39.5",
+    "@types/node": "^22.0.0",
+    "@vitest/coverage-v8": "~3.2.7",
+    "@vue/test-utils": "^2.4.6",
+    "eslint": "~9.39.5",
+    "happy-dom": "^20.14.5",
+    "tsup": "^8.5.1",
+    "typescript": "~5.9.3",
+    "typescript-eslint": "^8.71.0",
+    "vite": "~6.4.3",
+    "vitest": "~3.2.7",
+    "vue": "~3.5.22"
+  }
+}