@useparallel/agent-identification 0.0.0-stage → 0.9.0

package/dist/react/index.js

@@ -0,0 +1,646 @@
+"use client";
+
+// src/react/index.tsx
+import { useEffect, useRef } from "react";
+
+// src/protocol.ts
+var VERSION = "0.9.0";
+var CHOICES = ["ai_assistant", "person", "prefer_not_to_say"];
+function isChoice(value) {
+  return typeof value === "string" && CHOICES.includes(value);
+}
+var MAX_PATH = 512;
+var ID_SEGMENTS = [
+  /^\d+$/,
+  /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i,
+  /^[0-9a-f]{12,}$/i,
+  /@/,
+  // Letters mixed with three or more digits, as in most generated IDs and tokens.
+  /^(?=(?:[^\d]*\d){3})(?=.*[a-z])[a-z0-9_-]{8,}$/i
+];
+function routePath(path) {
+  const bare = path.replace(/[?#][\s\S]*$/, "");
+  const masked = bare.split("/").map((segment) => {
+    let text = segment;
+    try {
+      text = decodeURIComponent(segment);
+    } catch {
+    }
+    return ID_SEGMENTS.some((pattern) => pattern.test(text)) ? ":id" : segment;
+  }).join("/");
+  return (masked.startsWith("/") ? masked : `/${masked}`).slice(0, MAX_PATH);
+}
+function isRoutePattern(value) {
+  return typeof value === "string" && /^\/[A-Za-z0-9_.~:/{}*-]{0,255}$/.test(value);
+}
+
+// src/browser/shared.ts
+var memorySessions = /* @__PURE__ */ new Map();
+var requestTimeoutMs = 15e3;
+var HttpError = class extends Error {
+  constructor(status) {
+    super(`Identification service returned HTTP ${status}.`);
+    this.status = status;
+    this.name = "HttpError";
+  }
+  status;
+};
+function endpoint(value, name) {
+  let url;
+  try {
+    url = new URL(value, window.location.href);
+  } catch {
+    throw new Error(`${name} must be a valid URL.`);
+  }
+  const local = ["localhost", "127.0.0.1", "[::1]"].includes(url.hostname);
+  if (url.protocol !== "https:" && !(url.protocol === "http:" && local) || url.username || url.password || url.search || url.hash) {
+    throw new Error(
+      `${name} must use HTTPS (or localhost HTTP), without credentials, query or fragment.`
+    );
+  }
+  return url.href.replace(/\/$/, "");
+}
+function siteId(value) {
+  if (!/^[a-zA-Z0-9_-]{1,100}$/.test(value)) {
+    throw new Error("siteId must contain 1\u2013100 letters, numbers, underscores or hyphens.");
+  }
+  return value;
+}
+function pageOrigin() {
+  if (window.location.origin === "null") {
+    throw new Error("Serve this website over HTTPS (or localhost HTTP) to use identification.");
+  }
+  return window.location.origin;
+}
+function record(value) {
+  return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function opaque(value, min = 1, max = 512) {
+  return typeof value === "string" && value.length >= min && value.length <= max && /^[A-Za-z0-9._~-]+$/.test(value);
+}
+function uuid(value) {
+  return typeof value === "string" && /^[0-9a-f]{8}-[0-9a-f]{4}-[1-8][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i.test(value);
+}
+function sessionToken(value) {
+  return typeof value === "string" && /^[A-Za-z0-9_-]{32,512}$/.test(value);
+}
+function futureDate(value) {
+  return typeof value === "string" && /^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}\.\d{3}Z$/.test(value) && Number.isFinite(Date.parse(value)) && Date.parse(value) > Date.now();
+}
+function readStored(value) {
+  if (!record(value) || !sessionToken(value.token) || !uuid(value.sessionId) || !futureDate(value.expiresAt)) {
+    return null;
+  }
+  return { token: value.token, sessionId: value.sessionId, expiresAt: value.expiresAt };
+}
+async function storageKey(target, context) {
+  const scope = JSON.stringify([target.apiUrl, target.siteId, target.origin, context ?? null]);
+  const digest = await crypto.subtle.digest("SHA-256", new TextEncoder().encode(scope));
+  return `parallel-agent-id:v1:${Array.from(new Uint8Array(digest), (byte) => byte.toString(16).padStart(2, "0")).join("")}`;
+}
+function loadSession(key, storage) {
+  let found = memorySessions.get(key) ?? null;
+  if (storage === "session") {
+    try {
+      const serialized = sessionStorage.getItem(key);
+      found = serialized ? readStored(JSON.parse(serialized)) : found;
+      if (serialized && !found) sessionStorage.removeItem(key);
+    } catch {
+    }
+  }
+  return readStored(found);
+}
+function persistSession(key, storage, value) {
+  for (const [stored, session] of memorySessions) {
+    if (!futureDate(session.expiresAt)) memorySessions.delete(stored);
+  }
+  if (value) memorySessions.set(key, { ...value });
+  else memorySessions.delete(key);
+  if (storage === "session") {
+    try {
+      if (value) sessionStorage.setItem(key, JSON.stringify(value));
+      else sessionStorage.removeItem(key);
+    } catch {
+    }
+  }
+}
+function asError(value) {
+  return value instanceof Error ? value : new Error("Identification request failed.");
+}
+async function send(target, operation, path, method, body, token) {
+  const request = new AbortController();
+  const abort = () => request.abort();
+  operation.addEventListener("abort", abort, { once: true });
+  if (operation.aborted) request.abort();
+  const timeout = setTimeout(() => request.abort(), requestTimeoutMs);
+  try {
+    const response = await fetch(`${target.apiUrl}${path}`, {
+      method,
+      headers: {
+        ...body === void 0 ? {} : { "Content-Type": "application/json" },
+        ...token ? { Authorization: `Bearer ${token}`, "X-Agent-Site": target.siteId } : {}
+      },
+      ...body === void 0 ? {} : { body: JSON.stringify(body) },
+      credentials: "omit",
+      cache: "no-store",
+      mode: "cors",
+      referrerPolicy: "no-referrer",
+      signal: request.signal
+    });
+    if (!response.ok) throw new HttpError(response.status);
+    if (method === "DELETE") {
+      if (response.status !== 204) throw new Error("Session revocation was not confirmed.");
+      return null;
+    }
+    if (!response.headers.get("content-type")?.toLowerCase().includes("application/json")) {
+      throw new Error("Identification service did not return JSON.");
+    }
+    return await response.json();
+  } catch (error) {
+    if (request.signal.aborted && !operation.aborted)
+      throw new Error("Identification service timed out. Please retry.", { cause: error });
+    throw error;
+  } finally {
+    clearTimeout(timeout);
+    operation.removeEventListener("abort", abort);
+  }
+}
+function confirmed(body, id) {
+  return record(body) && Array.isArray(body.results) && body.results.some(
+    (result) => record(result) && result.id === id && (result.status === "recorded" || result.status === "duplicate")
+  );
+}
+function automationSignals() {
+  const found = [];
+  if (navigator.webdriver === true)
+    found.push({ signal: "webdriver", detail: "navigator.webdriver" });
+  if (/HeadlessChrome\//.test(navigator.userAgent)) {
+    found.push({ signal: "headless_browser", detail: "HeadlessChrome" });
+  }
+  return found;
+}
+
+// src/browser/index.ts
+var instances = /* @__PURE__ */ new WeakMap();
+var gates = /* @__PURE__ */ new WeakMap();
+var labels = {
+  ai_assistant: "AI assistant",
+  person: "Person",
+  prefer_not_to_say: "Prefer not to say"
+};
+function element(value, name) {
+  const found = typeof value === "string" ? document.querySelector(value) : value;
+  if (!(found instanceof HTMLElement)) {
+    throw new Error(`${name} must identify an existing HTML element.`);
+  }
+  return found;
+}
+function configure(options) {
+  const container = element(options.container, "container");
+  const gate = options.gate === void 0 ? void 0 : element(options.gate, "gate");
+  const apiUrl = endpoint(options.apiUrl, "apiUrl");
+  const mode = options.mode ?? "optional";
+  const storage = options.storage ?? "session";
+  if (mode !== "optional" && mode !== "required") throw new Error("Invalid identification mode.");
+  if (storage !== "session" && storage !== "memory") throw new Error("Invalid storage option.");
+  if (gate && (gate === container || gate.contains(container))) {
+    throw new Error("The gate must not contain the identification widget.");
+  }
+  const origin = pageOrigin();
+  if (options.route !== void 0 && !isRoutePattern(options.route)) {
+    throw new Error("route must be a path pattern such as /tickets/:id.");
+  }
+  return {
+    container,
+    gate,
+    apiUrl,
+    siteId: siteId(options.siteId),
+    origin,
+    mode,
+    storage,
+    styleUrl: endpoint(options.styleUrl ?? `${apiUrl}/sdk/v${VERSION}/agent-id.css`, "styleUrl"),
+    bindingContext: options.bindingContext,
+    onRecorded: options.onRecorded,
+    onError: options.onError,
+    pageViews: options.pageViews ?? true,
+    route: options.route,
+    automationSignals: options.automationSignals ?? false
+  };
+}
+function sameConfiguration(left, right) {
+  return Object.keys(left).every((key) => {
+    if ((key === "onRecorded" || key === "onError") && right[key] === void 0) return true;
+    return left[key] === right[key];
+  });
+}
+function validateStatus(value, config, expectedId, expectedChoice) {
+  if (!record(value) || !uuid(value.sessionId) || expectedId !== void 0 && value.sessionId !== expectedId || value.siteId !== config.siteId || value.origin !== config.origin || !futureDate(value.expiresAt) || value.evidence !== "self_reported") {
+    throw new Error("Identification service returned an invalid or mismatched session.");
+  }
+  const unanswered = value.choice === null && value.receipt === null && value.eventId === null;
+  const answered = isChoice(value.choice) && opaque(value.receipt, 1, 8192) && uuid(value.eventId);
+  if (!unanswered && !answered || expectedChoice !== void 0 && value.choice !== expectedChoice) {
+    throw new Error("Identification service returned an invalid or mismatched response.");
+  }
+  return {
+    sessionId: value.sessionId,
+    siteId: config.siteId,
+    origin: config.origin,
+    expiresAt: value.expiresAt,
+    choice: value.choice,
+    receipt: value.receipt,
+    eventId: value.eventId,
+    evidence: "self_reported"
+  };
+}
+var Controller = class {
+  constructor(config) {
+    this.config = config;
+    this.originalInert = config.gate?.inert ?? false;
+    this.build();
+    this.lock();
+    this.ready = this.start(this.version);
+    void this.ready.catch(() => {
+    });
+  }
+  config;
+  ready;
+  host = document.createElement("div");
+  root = this.host.attachShadow({ mode: "open" });
+  status = document.createElement("p");
+  retry = document.createElement("button");
+  buttons = [];
+  originalInert;
+  version = 0;
+  controller = new AbortController();
+  destroyed = false;
+  state = null;
+  session = null;
+  key = null;
+  pending = null;
+  retryAction = null;
+  expiry;
+  /** The session this page load has recorded its automatic page view in. */
+  viewed = null;
+  /** The session this page load has reported its automation signals in. */
+  signalled = null;
+  build() {
+    this.host.dataset.agentIdentification = VERSION;
+    const stylesheet = document.createElement("link");
+    stylesheet.rel = "stylesheet";
+    stylesheet.href = this.config.styleUrl;
+    const panel = document.createElement("section");
+    panel.className = "agent-identification";
+    panel.setAttribute("aria-label", "Visitor identification");
+    const title = document.createElement("h2");
+    title.textContent = this.config.mode === "required" ? "Before continuing" : "How are you visiting?";
+    const description = document.createElement("p");
+    description.textContent = "Choose one option. Your answer is self-reported.";
+    const actions = document.createElement("div");
+    actions.className = "choices";
+    for (const choice of Object.keys(labels)) {
+      const button = document.createElement("button");
+      button.type = "button";
+      button.textContent = labels[choice];
+      button.disabled = true;
+      button.addEventListener("click", () => {
+        this.pending = { choice, requestId: crypto.randomUUID() };
+        void this.submit(this.version).catch(() => {
+        });
+      });
+      this.buttons.push(button);
+      actions.append(button);
+    }
+    this.status.className = "status";
+    this.status.setAttribute("role", "status");
+    this.status.setAttribute("aria-live", "polite");
+    this.status.setAttribute("aria-atomic", "true");
+    this.retry.type = "button";
+    this.retry.textContent = "Retry";
+    this.retry.hidden = true;
+    this.retry.addEventListener("click", () => {
+      const action = this.retryAction;
+      if (action) void action().catch(() => {
+      });
+    });
+    panel.append(title, description, actions, this.status, this.retry);
+    this.root.append(stylesheet, panel);
+    this.config.container.append(this.host);
+  }
+  active(version) {
+    if (this.destroyed || version !== this.version)
+      throw new DOMException("Widget operation was superseded.", "AbortError");
+  }
+  lock() {
+    if (this.config.mode === "required" && this.config.gate) this.config.gate.inert = true;
+  }
+  busy(message) {
+    this.status.textContent = message;
+    this.retry.hidden = true;
+    this.retryAction = null;
+    for (const button of this.buttons) button.disabled = true;
+  }
+  fail(error, version, action, prefix) {
+    if (this.destroyed || version !== this.version) return;
+    const failure = asError(error);
+    this.status.textContent = `${prefix} ${failure.message}`;
+    this.retry.hidden = false;
+    this.retryAction = action;
+    this.notifyError(failure);
+  }
+  notifyError(error) {
+    try {
+      this.config.onError?.(error);
+    } catch {
+    }
+  }
+  accepted(status) {
+    this.state = status;
+    clearTimeout(this.expiry);
+    this.expiry = setTimeout(
+      () => {
+        if (this.destroyed || this.state?.sessionId !== status.sessionId) return;
+        this.state = null;
+        this.lock();
+        this.busy("Your identification session expired.");
+        this.retry.hidden = false;
+        this.retryAction = () => this.restart();
+      },
+      Math.min(Date.parse(status.expiresAt) - Date.now(), 2147483647)
+    );
+    this.retry.hidden = true;
+    this.retryAction = null;
+    if (status.choice !== null) {
+      this.status.textContent = `Response recorded: ${labels[status.choice]}.`;
+      if (this.config.mode === "required" && this.config.gate)
+        this.config.gate.inert = this.originalInert;
+      try {
+        this.config.onRecorded?.({ ...status });
+      } catch {
+        this.notifyError(
+          new Error("Your onRecorded callback failed after the response was recorded.")
+        );
+      }
+    } else {
+      this.status.textContent = this.config.mode === "required" ? "Select any option to continue." : "You can choose an option or continue without answering.";
+    }
+    for (const button of this.buttons) button.disabled = status.choice !== null;
+    return { ...status };
+  }
+  load() {
+    return this.key ? loadSession(this.key, this.config.storage) : null;
+  }
+  persist(value) {
+    if (this.key) persistSession(this.key, this.config.storage, value);
+  }
+  request(path, method, body, token) {
+    return send(this.config, this.controller.signal, path, method, body, token);
+  }
+  async start(version) {
+    this.busy("Loading identification\u2026");
+    this.lock();
+    try {
+      const context = typeof this.config.bindingContext === "function" ? await this.config.bindingContext() : this.config.bindingContext;
+      this.active(version);
+      if (context !== void 0 && (typeof context !== "string" || context.length === 0 || context.length > 8192)) {
+        throw new Error("bindingContext must be a nonempty signed context.");
+      }
+      const key = await storageKey(this.config, context);
+      this.active(version);
+      this.key = key;
+      this.session = this.load();
+      if (this.session) {
+        try {
+          const body2 = await this.request(
+            "/v1/sessions/current",
+            "GET",
+            void 0,
+            this.session.token
+          );
+          this.active(version);
+          const status2 = validateStatus(body2, this.config, this.session.sessionId);
+          this.session.expiresAt = status2.expiresAt;
+          this.persist(this.session);
+          return this.view(this.accepted(status2));
+        } catch (error) {
+          this.active(version);
+          if (!(error instanceof HttpError) || ![401, 404, 410].includes(error.status)) throw error;
+          this.persist(null);
+          this.session = null;
+        }
+      }
+      const body = await this.request("/v1/sessions", "POST", {
+        siteId: this.config.siteId,
+        ...context === void 0 ? {} : { bindingContext: context }
+      });
+      this.active(version);
+      const status = validateStatus(body, this.config);
+      if (!record(body) || !sessionToken(body.sessionToken) || status.choice !== null) {
+        throw new Error("Identification service returned an invalid new session.");
+      }
+      this.session = {
+        token: body.sessionToken,
+        sessionId: status.sessionId,
+        expiresAt: status.expiresAt
+      };
+      this.persist(this.session);
+      return this.view(this.accepted(status));
+    } catch (error) {
+      this.fail(error, version, () => this.restart(), "Could not load identification.");
+      throw error;
+    }
+  }
+  async submit(version) {
+    if (!this.pending || !this.session) throw new Error("Identification session is not ready.");
+    const pending = this.pending;
+    const session = this.session;
+    this.busy("Recording your response\u2026");
+    try {
+      const body = await this.request("/v1/declarations", "POST", pending, session.token);
+      this.active(version);
+      const status = validateStatus(body, this.config, session.sessionId, pending.choice);
+      session.expiresAt = status.expiresAt;
+      this.persist(session);
+      this.pending = null;
+      return this.accepted(status);
+    } catch (error) {
+      this.fail(error, version, () => this.submit(this.version), "Could not record your response.");
+      throw error;
+    }
+  }
+  /** Records this page load's automatic view once per session; failures reach onError. */
+  view(status) {
+    if (this.config.pageViews && this.viewed !== status.sessionId) {
+      this.viewed = status.sessionId;
+      void this.pageView({ route: this.config.route }).catch(() => {
+      });
+    }
+    if (this.config.automationSignals && this.signalled !== status.sessionId) {
+      this.signalled = status.sessionId;
+      void this.reportSignals().catch(() => {
+      });
+    }
+    return status;
+  }
+  async pageView(options = {}) {
+    this.active(this.version);
+    if (options.route !== void 0 && !isRoutePattern(options.route)) {
+      throw new Error("route must be a path pattern such as /tickets/:id.");
+    }
+    const view = {
+      // The same ID on every attempt, so a retry is recorded once.
+      id: crypto.randomUUID(),
+      path: routePath(window.location.pathname),
+      ...options.route ? { route: options.route } : {},
+      occurredAt: (/* @__PURE__ */ new Date()).toISOString()
+    };
+    await this.deliver("/v1/page-views", { views: [view] }, view.id, "page view");
+  }
+  /**
+   * Sends one event and waits for the collector to confirm that exact ID. It retries with the same
+   * ID, so a retry is recorded once, and reports to onError before rejecting.
+   */
+  async deliver(path, payload, id, what) {
+    const operation = this.controller.signal;
+    for (let attempt = 0; ; attempt++) {
+      const session = this.session;
+      try {
+        if (!session) throw new Error("Identification session is not ready.");
+        const body = await this.request(path, "POST", payload, session.token);
+        if (!confirmed(body, id))
+          throw new Error(`Identification service did not confirm the ${what}.`);
+        return;
+      } catch (error) {
+        if (operation.aborted || this.destroyed) throw error;
+        const retryable = session !== null && (!(error instanceof HttpError) || error.status === 429 || error.status >= 500);
+        if (!retryable || attempt >= 2) {
+          const failure = asError(error);
+          this.notifyError(failure);
+          throw failure;
+        }
+        await new Promise((resolve) => setTimeout(resolve, 300 * 3 ** attempt));
+        if (operation.aborted || this.destroyed) throw error;
+      }
+    }
+  }
+  /** Opt-in: what this browser shows of automation, as evidence and never as identity. */
+  async reportSignals() {
+    for (const signal of automationSignals()) {
+      const event = { id: crypto.randomUUID(), ...signal, occurredAt: (/* @__PURE__ */ new Date()).toISOString() };
+      await this.deliver("/v1/browser-signals", { signals: [event] }, event.id, "signal");
+    }
+  }
+  restart() {
+    this.active(this.version);
+    this.controller.abort();
+    clearTimeout(this.expiry);
+    this.controller = new AbortController();
+    this.version += 1;
+    return this.start(this.version);
+  }
+  getState() {
+    return this.state ? { ...this.state } : null;
+  }
+  async reset() {
+    this.active(this.version);
+    this.controller.abort();
+    clearTimeout(this.expiry);
+    this.controller = new AbortController();
+    const version = ++this.version;
+    this.busy("Resetting identification\u2026");
+    this.state = null;
+    this.pending = null;
+    this.lock();
+    try {
+      if (this.session) {
+        await this.request("/v1/sessions/current", "DELETE", void 0, this.session.token);
+        this.active(version);
+      }
+      this.persist(null);
+      this.session = null;
+    } catch (error) {
+      this.fail(error, version, () => this.reset(), "Could not reset identification.");
+      throw error;
+    }
+    return this.start(version);
+  }
+  destroy() {
+    if (this.destroyed) return;
+    this.destroyed = true;
+    this.version += 1;
+    this.controller.abort();
+    clearTimeout(this.expiry);
+    this.host.remove();
+    if (this.config.mode === "required" && this.config.gate) {
+      this.config.gate.inert = this.originalInert;
+      gates.delete(this.config.gate);
+    }
+    instances.delete(this.config.container);
+    this.retryAction = null;
+  }
+};
+function init(options) {
+  const config = configure(options);
+  const existing = instances.get(config.container);
+  if (existing) {
+    if (!sameConfiguration(existing.config, config))
+      throw new Error(
+        "This container already has an identification widget with different options."
+      );
+    return existing;
+  }
+  if (config.mode === "required" && config.gate && gates.has(config.gate)) {
+    throw new Error("This gate is already controlled by another identification widget.");
+  }
+  const controller = new Controller(config);
+  instances.set(config.container, controller);
+  if (config.mode === "required" && config.gate) gates.set(config.gate, controller);
+  return controller;
+}
+
+// src/react/index.tsx
+import { jsx } from "react/jsx-runtime";
+function AgentIdentification({
+  className,
+  id,
+  onRecorded,
+  onError,
+  ...options
+}) {
+  const container = useRef(null);
+  const callbacks = useRef({ onRecorded, onError });
+  callbacks.current = { onRecorded, onError };
+  useEffect(() => {
+    if (!container.current) return;
+    let widget;
+    try {
+      widget = init({
+        ...options,
+        container: container.current,
+        onRecorded: (response) => callbacks.current.onRecorded?.(response),
+        onError: (error) => callbacks.current.onError?.(error)
+      });
+    } catch (error) {
+      const failure = error instanceof Error ? error : new Error("Identification could not initialize.");
+      const notice = document.createElement("p");
+      notice.setAttribute("role", "alert");
+      notice.textContent = `Visitor identification unavailable. ${failure.message}`;
+      container.current.append(notice);
+      callbacks.current.onError?.(failure);
+      return () => notice.remove();
+    }
+    return () => widget.destroy();
+  }, [
+    options.apiUrl,
+    options.siteId,
+    options.mode,
+    options.gate,
+    options.styleUrl,
+    options.bindingContext,
+    options.storage
+  ]);
+  return /* @__PURE__ */ jsx("div", { ref: container, className, id });
+}
+export {
+  AgentIdentification
+};