@useparallel/agent-identification 0.0.0-stage → 0.8.2

package/dist/server/index.js

@@ -0,0 +1,492 @@
+// src/server/tokens.ts
+import { createHash, createHmac, timingSafeEqual } from "node:crypto";
+
+// src/protocol.ts
+var CHOICES = ["ai_assistant", "person", "prefer_not_to_say"];
+function isChoice(value) {
+  return typeof value === "string" && CHOICES.includes(value);
+}
+var OUTCOMES = ["attempted", "rejected", "confirmed"];
+var ADDRESS_CHECKS = ["operator", "elsewhere"];
+function isAddressCheck(value) {
+  return typeof value === "string" && ADDRESS_CHECKS.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 isReference(value) {
+  return typeof value === "string" && /^[A-Za-z0-9_.:-]{1,128}$/.test(value);
+}
+function isActionName(value) {
+  return typeof value === "string" && /^[a-z][a-z0-9_.:-]{0,63}$/.test(value);
+}
+var AGENT_USER_AGENT_TOKENS = [
+  "Claude-Agent",
+  "ChatGPT-User",
+  "OAI-SearchBot",
+  "GPTBot",
+  "Claude-User",
+  "Claude-SearchBot",
+  "ClaudeBot",
+  "Perplexity-User",
+  "PerplexityBot",
+  "MistralAI-User",
+  "DuckAssistBot"
+];
+function userAgentSignals(userAgent) {
+  const found = [];
+  const token = AGENT_USER_AGENT_TOKENS.find(
+    (name) => new RegExp(`(^|[^A-Za-z-])${name}(/|;|\\s|$)`).test(userAgent)
+  );
+  if (token) found.push({ signal: "agent_user_agent", detail: token });
+  if (/HeadlessChrome\//.test(userAgent))
+    found.push({ signal: "headless_browser", detail: "HeadlessChrome" });
+  return found;
+}
+function isOutcome(value) {
+  return typeof value === "string" && OUTCOMES.includes(value);
+}
+var LINK_TIMING = "agent-id";
+function isLink(value) {
+  return typeof value === "string" && /^[A-Za-z0-9_-]{22}$/.test(value);
+}
+
+// src/server/tokens.ts
+var HEADER = Buffer.from(JSON.stringify({ alg: "HS256", typ: "AID", v: 1 })).toString(
+  "base64url"
+);
+var HASH = /^[a-f0-9]{64}$/;
+var ID = /^[a-zA-Z0-9_-]{1,100}$/;
+var UUID = /^[0-9a-f]{8}-[0-9a-f]{4}-[1-8][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i;
+function isUuid(value) {
+  return typeof value === "string" && UUID.test(value);
+}
+function isSiteId(value) {
+  return typeof value === "string" && ID.test(value);
+}
+function isAllowedOrigin(value) {
+  if (typeof value !== "string") return false;
+  try {
+    const url = new URL(value);
+    return url.origin === value && !url.username && !url.password && (url.protocol === "https:" || url.protocol === "http:" && ["localhost", "127.0.0.1", "[::1]"].includes(url.hostname));
+  } catch {
+    return false;
+  }
+}
+function hashToken(token) {
+  return createHash("sha256").update(token).digest("hex");
+}
+function hashBinding(siteId, binding) {
+  if (typeof binding !== "string" || !binding || binding.length > 2048) {
+    throw new Error("sessionBinding must be an opaque, nonempty value");
+  }
+  return hashToken(JSON.stringify(["agent-identification-binding-v1", siteId, binding]));
+}
+function secretEquals(actual, expected) {
+  return timingSafeEqual(
+    Buffer.from(hashToken(actual), "hex"),
+    Buffer.from(hashToken(expected), "hex")
+  );
+}
+function seconds(now) {
+  if (!Number.isFinite(now.getTime())) throw new Error("Invalid current time");
+  return Math.floor(now.getTime() / 1e3);
+}
+function assertSecret(secret) {
+  if (typeof secret !== "string" || secret.length < 32 || secret.length > 1024) {
+    throw new Error("A server-only site secret of at least 32 characters is required");
+  }
+}
+function sign(claims, secret) {
+  assertSecret(secret);
+  const payload = Buffer.from(JSON.stringify(claims)).toString("base64url");
+  const signed = `${HEADER}.${payload}`;
+  const signature = createHmac("sha256", secret).update(signed).digest("base64url");
+  return `${signed}.${signature}`;
+}
+function verify(token, expected) {
+  assertSecret(expected.secret);
+  if (!isSiteId(expected.siteId) || !isAllowedOrigin(expected.origin)) {
+    throw new Error("Invalid expected site or origin");
+  }
+  if (typeof token !== "string" || token.length > 4096) {
+    throw new Error("Invalid signed token");
+  }
+  const parts = token.split(".");
+  if (parts.length !== 3 || parts[0] !== HEADER || !/^[A-Za-z0-9_-]+$/.test(parts[1]) || !/^[A-Za-z0-9_-]{43}$/.test(parts[2])) {
+    throw new Error("Invalid signed token");
+  }
+  const signature = createHmac("sha256", expected.secret).update(`${parts[0]}.${parts[1]}`).digest("base64url");
+  if (!secretEquals(signature, parts[2])) throw new Error("Invalid signed token");
+  let claims;
+  try {
+    claims = JSON.parse(Buffer.from(parts[1], "base64url").toString("utf8"));
+  } catch {
+    throw new Error("Invalid signed token");
+  }
+  const now = seconds(expected.now ?? /* @__PURE__ */ new Date());
+  if (!claims || Array.isArray(claims) || claims.v !== 1 || claims.siteId !== expected.siteId || claims.origin !== expected.origin || !Number.isSafeInteger(claims.iat) || !Number.isSafeInteger(claims.exp) || claims.iat > now || claims.exp <= now || claims.exp <= claims.iat) {
+    throw new Error("Signed token is invalid or expired");
+  }
+  return claims;
+}
+function exactKeys(value, keys) {
+  return Object.keys(value).sort().join(",") === keys.sort().join(",");
+}
+function createBindingContext(options) {
+  const ttl = options.expiresInSeconds ?? 300;
+  if (!Number.isInteger(ttl) || ttl < 1 || ttl > 900) {
+    throw new Error("Binding context lifetime must be 1\u2013900 seconds");
+  }
+  if (!isSiteId(options.siteId) || !isAllowedOrigin(options.origin)) {
+    throw new Error("Invalid site or origin");
+  }
+  const iat = seconds(options.now ?? /* @__PURE__ */ new Date());
+  return sign(
+    {
+      v: 1,
+      purpose: "binding_context",
+      siteId: options.siteId,
+      origin: options.origin,
+      bindingHash: hashBinding(options.siteId, options.sessionBinding),
+      iat,
+      exp: iat + ttl
+    },
+    options.secret
+  );
+}
+function verifyDeclaration(receipt, expected) {
+  const c = verify(receipt, expected);
+  const expectedHash = hashBinding(expected.siteId, expected.sessionBinding);
+  if (c.purpose !== "declaration" || c.evidence !== "self_reported" || !isUuid(c.sessionId) || !isUuid(c.eventId) || !isChoice(c.choice) || typeof c.bindingHash !== "string" || !HASH.test(c.bindingHash) || !secretEquals(c.bindingHash, expectedHash) || c.exp - c.iat > 1800 || !exactKeys(c, [
+    "v",
+    "purpose",
+    "siteId",
+    "origin",
+    "bindingHash",
+    "iat",
+    "exp",
+    "sessionId",
+    "eventId",
+    "choice",
+    "evidence"
+  ])) {
+    throw new Error("Declaration does not match the active session");
+  }
+  return c;
+}
+
+// src/server/online.ts
+async function verifyDeclarationOnline(receipt, options) {
+  const claims = verifyDeclaration(receipt, options);
+  const url = new URL(options.apiUrl);
+  if (!isAllowedOrigin(url.origin) || url.username || url.password || url.search || url.hash)
+    throw new Error("Invalid collector API URL");
+  url.pathname = `${url.pathname.replace(/\/$/, "")}/v1/verify`;
+  const response = await (options.fetch ?? globalThis.fetch)(url, {
+    method: "POST",
+    headers: {
+      authorization: `Bearer ${options.secret}`,
+      "content-type": "application/json"
+    },
+    credentials: "omit",
+    cache: "no-store",
+    redirect: "error",
+    signal: AbortSignal.timeout(1e4),
+    body: JSON.stringify({
+      siteId: options.siteId,
+      origin: options.origin,
+      sessionBinding: options.sessionBinding,
+      receipt
+    })
+  });
+  if (!response.ok) throw new Error("Declaration is not active or verification is unavailable");
+  const result = await response.json();
+  if (!result || typeof result !== "object" || !("valid" in result) || result.valid !== true || !("sessionId" in result) || result.sessionId !== claims.sessionId || !("eventId" in result) || result.eventId !== claims.eventId || !("choice" in result) || result.choice !== claims.choice || !("evidence" in result) || result.evidence !== "self_reported")
+    throw new Error("Invalid declaration verification response");
+  return claims;
+}
+
+// src/server/activity.ts
+async function reportAction(input, options) {
+  const id = input.id ?? crypto.randomUUID();
+  const fail = (error) => {
+    (options.onError ?? ((e) => console.warn(`Action report failed: ${e.message}`)))(error);
+    return { status: "failed", id, error };
+  };
+  if (!isActionName(input.action)) return fail(new Error("Invalid action name"));
+  if (!isOutcome(input.outcome)) return fail(new Error("Invalid outcome"));
+  for (const field of ["resourceRef", "accountRef"]) {
+    if (input[field] !== void 0 && !isReference(input[field])) {
+      return fail(new Error(`${field} must be an opaque ID`));
+    }
+  }
+  let api;
+  try {
+    api = new URL(options.apiUrl);
+  } catch {
+    return fail(new Error("Invalid collector API URL"));
+  }
+  if (!isAllowedOrigin(api.origin) || api.username || api.password || api.search || api.hash) {
+    return fail(new Error("Invalid collector API URL"));
+  }
+  api.pathname = `${api.pathname.replace(/\/$/, "")}/v1/actions`;
+  const body = JSON.stringify({
+    siteId: options.siteId,
+    actions: [
+      {
+        id,
+        action: input.action,
+        outcome: input.outcome,
+        occurredAt: (input.occurredAt ?? /* @__PURE__ */ new Date()).toISOString(),
+        ...input.resourceRef ? { resourceRef: input.resourceRef } : {},
+        ...input.accountRef ? { accountRef: input.accountRef } : {},
+        ...input.sessionBinding ? { sessionBinding: input.sessionBinding } : {}
+      }
+    ]
+  });
+  for (let attempt = 0; ; attempt++) {
+    let retryable = true;
+    try {
+      const response = await (options.fetch ?? globalThis.fetch)(api, {
+        method: "POST",
+        headers: {
+          authorization: `Bearer ${options.secret}`,
+          "content-type": "application/json"
+        },
+        credentials: "omit",
+        cache: "no-store",
+        redirect: "error",
+        signal: AbortSignal.timeout(5e3),
+        body
+      });
+      if (!response.ok) {
+        retryable = response.status === 429 || response.status >= 500;
+        throw new Error(`The collector answered ${response.status}`);
+      }
+      const result = await response.json();
+      const match = result?.results?.find((item) => item.id === id);
+      if (!match || match.status !== "recorded" && match.status !== "duplicate") {
+        retryable = false;
+        throw new Error(
+          match?.status === "conflict" ? "This ID was already used for a different action" : "Invalid response from the collector"
+        );
+      }
+      return {
+        status: "recorded",
+        id,
+        sessionId: typeof match.sessionId === "string" ? match.sessionId : null,
+        duplicate: match.status === "duplicate"
+      };
+    } catch (error) {
+      const failure = error instanceof Error ? error : new Error("Action report failed");
+      if (!retryable || attempt >= 2) return fail(failure);
+      await new Promise((resolve) => setTimeout(resolve, 300 * 3 ** attempt));
+    }
+  }
+}
+
+// src/server/web-bot-auth.ts
+var ASSET = /\.(?:m?js|css|map|png|jpe?g|gif|svg|webp|avif|ico|woff2?|ttf|otf|mp4|webm)$/i;
+function isAssetRequest(url, headers) {
+  const destination = headers["sec-fetch-dest"];
+  return destination !== void 0 && !["document", "iframe", "frame"].includes(destination) || ASSET.test(new URL(url, "https://placeholder.invalid").pathname);
+}
+function headerMap(request) {
+  const headers = {};
+  if (typeof Headers !== "undefined" && request.headers instanceof Headers) {
+    request.headers.forEach((value, name) => {
+      headers[name.toLowerCase()] = value;
+    });
+    return headers;
+  }
+  for (const [name, value] of Object.entries(
+    request.headers
+  )) {
+    if (value !== void 0) {
+      headers[name.toLowerCase()] = Array.isArray(value) ? value.join(", ") : value;
+    }
+  }
+  return headers;
+}
+function requestUrl(request, headers) {
+  if (typeof Request !== "undefined" && request instanceof Request) return request.url;
+  const node = request;
+  const path = node.originalUrl ?? node.url ?? "/";
+  return `${node.protocol ?? "https"}://${headers.host ?? ""}${path}`;
+}
+async function reportSignedRequest(request, options) {
+  const fail = (error) => {
+    (options.onError ?? ((e) => console.warn(`Web Bot Auth report failed: ${e.message}`)))(error);
+    return { status: "failed", error };
+  };
+  try {
+    const headers = headerMap(request);
+    const input = headers["signature-input"];
+    if (!input || !headers.signature) return { status: "skipped" };
+    const url = options.url ?? requestUrl(request, headers);
+    if (!options.includeAssets && isAssetRequest(url, headers)) return { status: "skipped" };
+    const covered = /* @__PURE__ */ new Set(["signature", "signature-input", "signature-agent"]);
+    for (const match of input.matchAll(/"([a-z0-9-]+)"/g)) covered.add(match[1]);
+    const forwarded = Object.fromEntries(
+      [...covered].filter((name) => headers[name] !== void 0).map((name) => [name, headers[name]])
+    );
+    const api = new URL(options.apiUrl);
+    if (!isAllowedOrigin(api.origin) || api.username || api.password || api.search || api.hash) {
+      return fail(new Error("Invalid collector API URL"));
+    }
+    api.pathname = `${api.pathname.replace(/\/$/, "")}/v1/signatures`;
+    const response = await (options.fetch ?? globalThis.fetch)(api, {
+      method: "POST",
+      headers: {
+        authorization: `Bearer ${options.secret}`,
+        "content-type": "application/json"
+      },
+      credentials: "omit",
+      cache: "no-store",
+      redirect: "error",
+      signal: AbortSignal.timeout(5e3),
+      body: JSON.stringify({
+        siteId: options.siteId,
+        request: {
+          method: (request.method ?? "GET").toUpperCase(),
+          url,
+          headers: forwarded
+        },
+        ...options.sessionId ? { sessionId: options.sessionId } : {},
+        ...options.accountRef ? { accountRef: options.accountRef } : {},
+        ...options.link ? { link: options.link } : {}
+      })
+    });
+    if (!response.ok) return fail(new Error(`The collector answered ${response.status}`));
+    const result = await response.json();
+    const event = result?.event;
+    if (!event || event.type !== "signature" || typeof event.id !== "string") {
+      return fail(new Error("Invalid response from the collector"));
+    }
+    return { status: "recorded", event };
+  } catch (error) {
+    return fail(error instanceof Error ? error : new Error("Web Bot Auth report failed"));
+  }
+}
+
+// src/server/signals.ts
+import { isIP } from "node:net";
+async function reportRequestSignals(request, options) {
+  const fail = (error) => {
+    (options.onError ?? ((e) => console.warn(`Signal report failed: ${e.message}`)))(error);
+    return { status: "failed", error };
+  };
+  try {
+    const headers = headerMap(request);
+    const found = userAgentSignals(headers["user-agent"] ?? "");
+    if (!found.length || isAssetRequest(requestUrl(request, headers), headers)) {
+      return { status: "skipped" };
+    }
+    const api = new URL(options.apiUrl);
+    if (!isAllowedOrigin(api.origin) || api.username || api.password || api.search || api.hash) {
+      return fail(new Error("Invalid collector API URL"));
+    }
+    api.pathname = `${api.pathname.replace(/\/$/, "")}/v1/signals`;
+    const occurredAt = (/* @__PURE__ */ new Date()).toISOString();
+    const ip = typeof options.clientIp === "string" ? options.clientIp.trim() : "";
+    const address = ip && isIP(ip.replace(/^\[|\]$/g, "").replace(/%.*$/, "")) ? ip : null;
+    const signals = found.map((item) => ({
+      id: crypto.randomUUID(),
+      ...item,
+      ...address && item.signal === "agent_user_agent" ? { ip: address } : {},
+      occurredAt,
+      ...options.sessionBinding ? { sessionBinding: options.sessionBinding } : {},
+      ...options.link ? { link: options.link } : {}
+    }));
+    for (let attempt = 0; ; attempt++) {
+      let retryable = true;
+      try {
+        const response = await (options.fetch ?? globalThis.fetch)(api, {
+          method: "POST",
+          headers: {
+            authorization: `Bearer ${options.secret}`,
+            "content-type": "application/json"
+          },
+          credentials: "omit",
+          cache: "no-store",
+          redirect: "error",
+          signal: AbortSignal.timeout(5e3),
+          body: JSON.stringify({ siteId: options.siteId, signals })
+        });
+        if (!response.ok) {
+          retryable = response.status === 429 || response.status >= 500;
+          throw new Error(`The collector answered ${response.status}`);
+        }
+        const result = await response.json();
+        const confirmed = signals.every(
+          (signal) => result?.results?.some(
+            (item) => item.id === signal.id && (item.status === "recorded" || item.status === "duplicate")
+          )
+        );
+        if (!confirmed) {
+          retryable = false;
+          throw new Error("Invalid response from the collector");
+        }
+        return {
+          status: "recorded",
+          signals: found.map((item, index) => {
+            const answer = result.results.find((entry) => entry.id === signals[index].id);
+            return { ...item, address: isAddressCheck(answer?.address) ? answer.address : null };
+          })
+        };
+      } catch (error) {
+        const failure = error instanceof Error ? error : new Error("Signal report failed");
+        if (!retryable || attempt >= 2) return fail(failure);
+        await new Promise((resolve) => setTimeout(resolve, 300 * 3 ** attempt));
+      }
+    }
+  } catch (error) {
+    return fail(error instanceof Error ? error : new Error("Signal report failed"));
+  }
+}
+
+// src/server/links.ts
+function reportLink(request, options = {}) {
+  const headers = headerMap(request);
+  const signed = Boolean(headers["signature-input"] && headers.signature);
+  if (!signed && !userAgentSignals(headers["user-agent"] ?? "").length) return null;
+  if (isAssetRequest(options.url ?? requestUrl(request, headers), headers)) return null;
+  return Buffer.from(crypto.getRandomValues(new Uint8Array(16))).toString("base64url");
+}
+function serverTiming(link) {
+  return `${LINK_TIMING};desc="${link}"`;
+}
+export {
+  AGENT_USER_AGENT_TOKENS,
+  LINK_TIMING,
+  createBindingContext,
+  isLink,
+  reportAction,
+  reportLink,
+  reportRequestSignals,
+  reportSignedRequest,
+  routePath,
+  serverTiming,
+  userAgentSignals,
+  verifyDeclaration,
+  verifyDeclarationOnline
+};

package/dist/types/browser/index.d.ts

@@ -0,0 +1,40 @@
+import { type Choice, type Mode, type RecordedDeclaration, type SessionStatus } from "../protocol.js";
+export type { Choice, Mode, RecordedDeclaration, SessionStatus };
+export { track, type Tracker, type TrackerOptions } from "./track.js";
+export interface WidgetOptions {
+    container: HTMLElement | string;
+    siteId: string;
+    apiUrl: string;
+    mode?: Mode;
+    gate?: HTMLElement | string;
+    styleUrl?: string;
+    bindingContext?: string | (() => Promise<string>);
+    storage?: "session" | "memory";
+    onRecorded?: (declaration: RecordedDeclaration) => void;
+    onError?: (error: Error) => void;
+    /**
+     * Records a page view once the session is ready, and again after reset. Only the path is
+     * sent, without its query or fragment and with parts that look like IDs masked. Defaults to
+     * true.
+     */
+    pageViews?: boolean;
+    /** Your route pattern for this page, such as /tickets/:id, for parts masking can't catch. */
+    route?: string;
+    /**
+     * Reports whether this browser is automated (navigator.webdriver) or headless, as heuristic
+     * evidence that never labels a visitor an AI agent. Off by default.
+     */
+    automationSignals?: boolean;
+}
+export interface Widget {
+    readonly ready: Promise<SessionStatus>;
+    getState(): SessionStatus | null;
+    reset(): Promise<SessionStatus>;
+    /** Records a page view, for apps that change pages without reloading. */
+    pageView(options?: {
+        route?: string;
+    }): Promise<void>;
+    destroy(): void;
+}
+/** Mount a self-reported visitor choice. Required mode controls only the supplied UI gate. */
+export declare function init(options: WidgetOptions): Widget;

package/dist/types/browser/script.d.ts

@@ -0,0 +1,8 @@
+import { init } from "./index.js";
+declare global {
+    interface Window {
+        AgentIdentification: {
+            init: typeof init;
+        };
+    }
+}

package/dist/types/browser/shared.d.ts

@@ -0,0 +1,38 @@
+/** Session and request code shared by the declaration widget and the page tracker. */
+import type { Signal } from "../protocol.js";
+export interface StoredSession {
+    token: string;
+    sessionId: string;
+    expiresAt: string;
+}
+export interface Target {
+    apiUrl: string;
+    siteId: string;
+    origin: string;
+}
+export declare class HttpError extends Error {
+    readonly status: number;
+    constructor(status: number);
+}
+export declare function endpoint(value: string, name: string): string;
+export declare function siteId(value: string): string;
+export declare function pageOrigin(): string;
+export declare function record(value: unknown): value is Record<string, unknown>;
+export declare function opaque(value: unknown, min?: number, max?: number): value is string;
+export declare function uuid(value: unknown): value is string;
+export declare function sessionToken(value: unknown): value is string;
+export declare function futureDate(value: unknown): value is string;
+export declare function readStored(value: unknown): StoredSession | null;
+export declare function storageKey(target: Target, context: string | undefined): Promise<string>;
+export declare function loadSession(key: string, storage: "session" | "memory"): StoredSession | null;
+export declare function persistSession(key: string, storage: "session" | "memory", value: StoredSession | null): void;
+export declare function asError(value: unknown): Error;
+/** One collector request. Anything but a successful, well-formed response throws. */
+export declare function send(target: Target, operation: AbortSignal, path: string, method: string, body?: unknown, token?: string): Promise<unknown>;
+/** Whether the collector confirmed that exact event ID as recorded, now or before. */
+export declare function confirmed(body: unknown, id: string): boolean;
+/** What this browser shows of automation: evidence, never identity. */
+export declare function automationSignals(): {
+    signal: Signal;
+    detail: string;
+}[];

package/dist/types/browser/track-script.d.ts

@@ -0,0 +1,8 @@
+import { track } from "./track.js";
+declare global {
+    interface Window {
+        AgentIdentificationTracker: {
+            track: typeof track;
+        };
+    }
+}

package/dist/types/browser/track.d.ts

@@ -0,0 +1,34 @@
+export interface TrackerOptions {
+    siteId: string;
+    apiUrl: string;
+    /** Where the tab's session is kept: sessionStorage (the default) or memory only. */
+    storage?: "session" | "memory";
+    /** Your route pattern for this page, such as /tickets/:id, for parts masking can't catch. */
+    route?: string;
+    /**
+     * Records a page view whenever the path changes without a reload, through the History API or
+     * the back and forward buttons. Defaults to true; turn it off if you call pageView() yourself.
+     */
+    navigation?: boolean;
+    /**
+     * Reports whether this browser is automated (navigator.webdriver) or headless, once per
+     * session, as heuristic evidence that never labels a visitor an AI agent. Defaults to true.
+     */
+    automationSignals?: boolean;
+    onError?: (error: Error) => void;
+}
+export interface Tracker {
+    /** Resolves once this page load's page view is confirmed, and rejects if it couldn't be. */
+    readonly ready: Promise<void>;
+    /** Records a page view, for apps that change pages without the History API. */
+    pageView(options?: {
+        route?: string;
+    }): Promise<void>;
+    /** Stops recording. It never ends the session or removes anything already recorded. */
+    destroy(): void;
+}
+/**
+ * Records this page's views and automation signals for one site, without drawing anything.
+ * Calling it again for the same site returns the same tracker.
+ */
+export declare function track(options: TrackerOptions): Tracker;