@useparallel/agent-identification 0.8.2 → 0.9.0

package/README.md

@@ -29,37 +29,29 @@ current browser.
 
 ## Report agents from your server
 
-Install the package and add these calls where your server handles requests. They
-skip ordinary requests without a network call, and none of them throws or slows the
-response. Keep the site's secret in `AGENT_ID_SITE_SECRET` on the server only.
+Install the package and add one call where your server handles requests. It skips
+ordinary requests without a network call, and never throws or slows the response. Keep
+the site's secret in `AGENT_ID_SITE_SECRET` on the server only.
 
 ```ts
-import {
-  reportLink,
-  reportRequestSignals,
-  reportSignedRequest,
-  serverTiming,
-} from "@useparallel/agent-identification/server";
+import { agentIdentification } from "@useparallel/agent-identification/server";
 
-const agentId = {
-  apiUrl: "https://YOUR-COLLECTOR",
-  siteId: "your-public-site-id",
-  secret: process.env.AGENT_ID_SITE_SECRET!,
-};
+// Express. Reads your server secret from AGENT_ID_SITE_SECRET; the hosted collector is the
+// default. Behind a proxy, set "trust proxy" so req.ip is the visitor's address.
+app.use(agentIdentification({ siteId: "your-public-site-id" }).express());
 
-// Express:
-app.use((req, res, next) => {
-  // Only for a request it reports, so the page script can join the reports to its visit.
-  const link = reportLink(req);
-  if (link) res.append("Server-Timing", serverTiming(link));
-  void reportSignedRequest(req, { ...agentId, link });
-  // req.ip lets the collector check a named agent against its operator's published addresses.
-  // Behind a proxy or load balancer, set Express's "trust proxy" so req.ip is the visitor's.
-  void reportRequestSignals(req, { ...agentId, link, clientIp: req.ip });
-  next();
-});
+// Next.js proxy.ts:
+// const agentId = agentIdentification({ siteId: "your-public-site-id" });
+// export function proxy(request, event) {
+//   return agentId.next(request, event, NextResponse.next());
+// }
 ```
 
+It reports signed requests, agents that name themselves (including Claude Code and Codex),
+and command-line clients such as curl, each with the page requested, and checks Anthropic's
+and OpenAI's agents against their published addresses. Report actions with
+`agentId.action({ action, outcome, sessionBinding })`.
+
 The page script reads the link from its own page's `Server-Timing` header and claims
 it, so a signed request joins that visit. Only that browser has the link, and no
 cookie is set. Keep pages that carry a link out of shared caches.
@@ -75,7 +67,7 @@ Add one tag to every page. It draws nothing, sets no cookies and needs no secret
 ```html
 <script
   defer
-  src="https://YOUR-COLLECTOR/sdk/v0.8.2/agent-id-track.js"
+  src="https://YOUR-COLLECTOR/sdk/v0.9.0/agent-id-track.js"
   data-site="YOUR-SITE-ID"
 ></script>
 ```
@@ -101,7 +93,7 @@ on servers.
 <div id="visitor-choice"></div>
 <script
   defer
-  src="https://YOUR-COLLECTOR/sdk/v0.8.2/agent-id.js"
+  src="https://YOUR-COLLECTOR/sdk/v0.9.0/agent-id.js"
   data-site="YOUR-SITE-ID"
   data-target="#visitor-choice"
   data-mode="optional"
@@ -122,7 +114,7 @@ To require a choice before using a section of the page:
 <form id="checkout"><!-- Your existing form --></form>
 <script
   defer
-  src="https://YOUR-COLLECTOR/sdk/v0.8.2/agent-id.js"
+  src="https://YOUR-COLLECTOR/sdk/v0.9.0/agent-id.js"
   data-site="YOUR-SITE-ID"
   data-target="#visitor-choice"
   data-mode="required"
@@ -256,7 +248,7 @@ For a restrictive Content Security Policy, allow the collector in `script-src`,
 `style-src` and `connect-src`. Use external integration scripts or your existing
 nonce policy. The widget uses an external stylesheet and requires no inline
 script/style exceptions. Its `styleUrl` can point to your own copy of the CSS.
-Versioned asset hashes are at `/sdk/v0.8.2/integrity.json`.
+Versioned asset hashes are at `/sdk/v0.9.0/integrity.json`.
 
 ## What's collected
 

package/dist/agent-id-track.js

@@ -1 +1 @@
-"use strict";(()=>{var B=512;var M=[/^\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,/@/,/^(?=(?:[^\d]*\d){3})(?=.*[a-z])[a-z0-9_-]{8,}$/i];function I(e){let t=e.replace(/[?#][\s\S]*$/,"").split("/").map(n=>{let i=n;try{i=decodeURIComponent(n)}catch{}return M.some(d=>d.test(i))?":id":n}).join("/");return(t.startsWith("/")?t:`/${t}`).slice(0,B)}function y(e){return typeof e=="string"&&/^\/[A-Za-z0-9_.~:/{}*-]{0,255}$/.test(e)}var T="agent-id";function b(e){return typeof e=="string"&&/^[A-Za-z0-9_-]{22}$/.test(e)}var f=new Map,z=15e3,p=class extends Error{constructor(t){super(`Identification service returned HTTP ${t}.`);this.status=t;this.name="HttpError"}status};function C(e,r){let t;try{t=new URL(e,window.location.href)}catch{throw new Error(`${r} must be a valid URL.`)}let n=["localhost","127.0.0.1","[::1]"].includes(t.hostname);if(t.protocol!=="https:"&&!(t.protocol==="http:"&&n)||t.username||t.password||t.search||t.hash)throw new Error(`${r} must use HTTPS (or localhost HTTP), without credentials, query or fragment.`);return t.href.replace(/\/$/,"")}function P(e){if(!/^[a-zA-Z0-9_-]{1,100}$/.test(e))throw new Error("siteId must contain 1\u2013100 letters, numbers, underscores or hyphens.");return e}function O(){if(window.location.origin==="null")throw new Error("Serve this website over HTTPS (or localhost HTTP) to use identification.");return window.location.origin}function g(e){return typeof e=="object"&&e!==null&&!Array.isArray(e)}function S(e){return typeof e=="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(e)}function m(e){return typeof e=="string"&&/^[A-Za-z0-9_-]{32,512}$/.test(e)}function h(e){return typeof e=="string"&&/^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}\.\d{3}Z$/.test(e)&&Number.isFinite(Date.parse(e))&&Date.parse(e)>Date.now()}function _(e){return!g(e)||!m(e.token)||!S(e.sessionId)||!h(e.expiresAt)?null:{token:e.token,sessionId:e.sessionId,expiresAt:e.expiresAt}}async function U(e,r){let t=JSON.stringify([e.apiUrl,e.siteId,e.origin,r??null]),n=await crypto.subtle.digest("SHA-256",new TextEncoder().encode(t));return`parallel-agent-id:v1:${Array.from(new Uint8Array(n),i=>i.toString(16).padStart(2,"0")).join("")}`}function v(e,r){let t=f.get(e)??null;if(r==="session")try{let n=sessionStorage.getItem(e);t=n?_(JSON.parse(n)):t,n&&!t&&sessionStorage.removeItem(e)}catch{}return _(t)}function E(e,r,t){for(let[n,i]of f)h(i.expiresAt)||f.delete(n);if(t?f.set(e,{...t}):f.delete(e),r==="session")try{t?sessionStorage.setItem(e,JSON.stringify(t)):sessionStorage.removeItem(e)}catch{}}function R(e){return e instanceof Error?e:new Error("Identification request failed.")}async function x(e,r,t,n,i,d){let s=new AbortController,o=()=>s.abort();r.addEventListener("abort",o,{once:!0}),r.aborted&&s.abort();let a=setTimeout(()=>s.abort(),z);try{let c=await fetch(`${e.apiUrl}${t}`,{method:n,headers:{...i===void 0?{}:{"Content-Type":"application/json"},...d?{Authorization:`Bearer ${d}`,"X-Agent-Site":e.siteId}:{}},...i===void 0?{}:{body:JSON.stringify(i)},credentials:"omit",cache:"no-store",mode:"cors",referrerPolicy:"no-referrer",signal:s.signal});if(!c.ok)throw new p(c.status);if(n==="DELETE"){if(c.status!==204)throw new Error("Session revocation was not confirmed.");return null}if(!c.headers.get("content-type")?.toLowerCase().includes("application/json"))throw new Error("Identification service did not return JSON.");return await c.json()}catch(c){throw s.signal.aborted&&!r.aborted?new Error("Identification service timed out. Please retry.",{cause:c}):c}finally{clearTimeout(a),r.removeEventListener("abort",o)}}function $(e,r){return g(e)&&Array.isArray(e.results)&&e.results.some(t=>g(t)&&t.id===r&&(t.status==="recorded"||t.status==="duplicate"))}function N(){let e=[];return navigator.webdriver===!0&&e.push({signal:"webdriver",detail:"navigator.webdriver"}),/HeadlessChrome\//.test(navigator.userAgent)&&e.push({signal:"headless_browser",detail:"HeadlessChrome"}),e}var w=new Map;function j(){try{let[e]=performance.getEntriesByType("navigation"),r=(e?.serverTiming??[]).filter(t=>t.name===T&&b(t.description)).map(t=>t.description);return[...new Set(r)].slice(0,5)}catch{return[]}}var L=new Set,H=new WeakMap;function G(e){let{history:r}=window,t=H.get(r);if(!t){let n=()=>{for(let i of[...t])i()};t=new Set,H.set(r,t);for(let i of["pushState","replaceState"]){let d=r[i];r[i]=function(...s){let o=d.apply(this,s);return n(),o}}window.addEventListener("popstate",n)}return t.add(e),()=>t.delete(e)}function V(e){let r=e.storage??"session";if(r!=="session"&&r!=="memory")throw new Error("Invalid storage option.");if(e.route!==void 0&&!y(e.route))throw new Error("route must be a path pattern such as /tickets/:id.");return{apiUrl:C(e.apiUrl,"apiUrl"),siteId:P(e.siteId),origin:O(),storage:r,navigation:e.navigation??!0,automationSignals:e.automationSignals??!0,onError:e.onError}}function Z(e,r){return Object.keys(e).every(t=>t==="onError"&&r[t]===void 0||e[t]===r[t])}var k=class{constructor(r,t){this.config=r;this.key=U(r,void 0),this.stopWatching=r.navigation?G(()=>this.navigated()):()=>{},this.ready=this.pageView({route:t}),this.ready.then(()=>this.claimLinks()).catch(()=>{})}config;ready;controller=new AbortController;key;stopWatching;session=null;starting=null;destroyed=!1;path=window.location.pathname;async claimLinks(){let r=j();r.length&&await this.deliver("/v1/links",{links:r},r[0],"links",t=>r.every(n=>g(t)&&Array.isArray(t.results)&&t.results.some(i=>g(i)&&i.id===n)))}navigated(){this.destroyed||window.location.pathname===this.path||this.pageView().catch(()=>{})}async pageView(r={}){if(this.destroyed)throw new Error("This tracker was destroyed.");if(r.route!==void 0&&!y(r.route))throw new Error("route must be a path pattern such as /tickets/:id.");this.path=window.location.pathname;let t={id:crypto.randomUUID(),path:I(this.path),...r.route?{route:r.route}:{},occurredAt:new Date().toISOString()},n=await this.deliver("/v1/page-views",{views:[t]},t.id,"page view");this.config.automationSignals&&await this.firstSignals(n.sessionId)&&this.reportSignals().catch(()=>{})}async firstSignals(r){let t=`${await this.key}:signals`;if(L.has(r))return!1;if(L.add(r),this.config.storage==="memory")return!0;try{if(sessionStorage.getItem(t)===r)return!1;sessionStorage.setItem(t,r)}catch{}return!0}async reportSignals(){for(let r of N()){let t={id:crypto.randomUUID(),...r,occurredAt:new Date().toISOString()};await this.deliver("/v1/browser-signals",{signals:[t]},t.id,"signal")}}async current(){let r=await this.key;return this.session??=v(r,this.config.storage),this.session&&h(this.session.expiresAt)?this.session:(this.starting??=this.start(r).finally(()=>this.starting=null),this.starting)}async start(r){let t=await x(this.config,this.controller.signal,"/v1/sessions","POST",{siteId:this.config.siteId});if(!g(t)||!S(t.sessionId)||t.siteId!==this.config.siteId||t.origin!==this.config.origin||!h(t.expiresAt)||!m(t.sessionToken))throw new Error("Identification service returned an invalid new session.");return this.session={token:t.sessionToken,sessionId:t.sessionId,expiresAt:t.expiresAt},E(r,this.config.storage,this.session),this.session}async deliver(r,t,n,i,d=s=>$(s,n)){for(let s=0;;s++){let o=null;try{o=await this.current();let a=await x(this.config,this.controller.signal,r,"POST",t,o.token);if(!d(a))throw new Error(`Identification service did not confirm the ${i}.`);return o}catch(a){if(this.destroyed)throw a;let c=o!==null&&a instanceof p&&[401,404,410].includes(a.status);if(c&&o&&this.session===o){this.session=null;let l=await this.key;v(l,this.config.storage)?.token===o.token&&E(l,this.config.storage,null)}if(!(c||!(a instanceof p)||a.status===429||a.status>=500)||s>=2){let l=R(a);try{this.config.onError?.(l)}catch{}throw l}if(c||await new Promise(l=>setTimeout(l,300*3**s)),this.destroyed)throw a}}}destroy(){this.destroyed||(this.destroyed=!0,this.stopWatching(),this.controller.abort(),w.get(this.config.apiUrl+" "+this.config.siteId)===this&&w.delete(this.config.apiUrl+" "+this.config.siteId))}};function A(e){let r=V(e),t=r.apiUrl+" "+r.siteId,n=w.get(t);if(n){if(!Z(n.config,r))throw new Error("This site is already tracked on this page with different options.");return n}let i=new k(r,e.route);return w.set(t,i),i}window.AgentIdentificationTracker=Object.freeze({track:A});var u=document.currentScript;function D(e){document.dispatchEvent(new CustomEvent("agent-identification:error",{detail:{message:e}}))}if(u?.dataset.site)try{A({siteId:u.dataset.site,apiUrl:u.dataset.api??new URL(u.src).origin,storage:u.dataset.storage,route:u.dataset.route,navigation:u.dataset.navigation!=="off",automationSignals:u.dataset.automationSignals!=="off",onError:e=>D(e.message)})}catch(e){D(e instanceof Error?e.message:"Agent Identification could not start.")}})();
+"use strict";(()=>{var M=512;var j=[/^\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,/@/,/^(?=(?:[^\d]*\d){3})(?=.*[a-z])[a-z0-9_-]{8,}$/i];function T(t){let e=t.replace(/[?#][\s\S]*$/,"").split("/").map(r=>{let i=r;try{i=decodeURIComponent(r)}catch{}return j.some(d=>d.test(i))?":id":r}).join("/");return(e.startsWith("/")?e:`/${e}`).slice(0,M)}function m(t){return typeof t=="string"&&/^\/[A-Za-z0-9_.~:/{}*-]{0,255}$/.test(t)}var A="agent-id";function C(t){return typeof t=="string"&&/^[A-Za-z0-9_-]{22}$/.test(t)}var f=new Map,z=15e3,p=class extends Error{constructor(e){super(`Identification service returned HTTP ${e}.`);this.status=e;this.name="HttpError"}status};function P(t,n){let e;try{e=new URL(t,window.location.href)}catch{throw new Error(`${n} must be a valid URL.`)}let r=["localhost","127.0.0.1","[::1]"].includes(e.hostname);if(e.protocol!=="https:"&&!(e.protocol==="http:"&&r)||e.username||e.password||e.search||e.hash)throw new Error(`${n} must use HTTPS (or localhost HTTP), without credentials, query or fragment.`);return e.href.replace(/\/$/,"")}function O(t){if(!/^[a-zA-Z0-9_-]{1,100}$/.test(t))throw new Error("siteId must contain 1\u2013100 letters, numbers, underscores or hyphens.");return t}function U(){if(window.location.origin==="null")throw new Error("Serve this website over HTTPS (or localhost HTTP) to use identification.");return window.location.origin}function g(t){return typeof t=="object"&&t!==null&&!Array.isArray(t)}function S(t){return typeof t=="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(t)}function v(t){return typeof t=="string"&&/^[A-Za-z0-9_-]{32,512}$/.test(t)}function h(t){return typeof t=="string"&&/^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}\.\d{3}Z$/.test(t)&&Number.isFinite(Date.parse(t))&&Date.parse(t)>Date.now()}function _(t){return!g(t)||!v(t.token)||!S(t.sessionId)||!h(t.expiresAt)?null:{token:t.token,sessionId:t.sessionId,expiresAt:t.expiresAt}}async function L(t,n){let e=JSON.stringify([t.apiUrl,t.siteId,t.origin,n??null]),r=await crypto.subtle.digest("SHA-256",new TextEncoder().encode(e));return`parallel-agent-id:v1:${Array.from(new Uint8Array(r),i=>i.toString(16).padStart(2,"0")).join("")}`}function x(t,n){let e=f.get(t)??null;if(n==="session")try{let r=sessionStorage.getItem(t);e=r?_(JSON.parse(r)):e,r&&!e&&sessionStorage.removeItem(t)}catch{}return _(e)}function E(t,n,e){for(let[r,i]of f)h(i.expiresAt)||f.delete(r);if(e?f.set(t,{...e}):f.delete(t),n==="session")try{e?sessionStorage.setItem(t,JSON.stringify(e)):sessionStorage.removeItem(t)}catch{}}function R(t){return t instanceof Error?t:new Error("Identification request failed.")}async function k(t,n,e,r,i,d){let o=new AbortController,s=()=>o.abort();n.addEventListener("abort",s,{once:!0}),n.aborted&&o.abort();let a=setTimeout(()=>o.abort(),z);try{let c=await fetch(`${t.apiUrl}${e}`,{method:r,headers:{...i===void 0?{}:{"Content-Type":"application/json"},...d?{Authorization:`Bearer ${d}`,"X-Agent-Site":t.siteId}:{}},...i===void 0?{}:{body:JSON.stringify(i)},credentials:"omit",cache:"no-store",mode:"cors",referrerPolicy:"no-referrer",signal:o.signal});if(!c.ok)throw new p(c.status);if(r==="DELETE"){if(c.status!==204)throw new Error("Session revocation was not confirmed.");return null}if(!c.headers.get("content-type")?.toLowerCase().includes("application/json"))throw new Error("Identification service did not return JSON.");return await c.json()}catch(c){throw o.signal.aborted&&!n.aborted?new Error("Identification service timed out. Please retry.",{cause:c}):c}finally{clearTimeout(a),n.removeEventListener("abort",s)}}function N(t,n){return g(t)&&Array.isArray(t.results)&&t.results.some(e=>g(e)&&e.id===n&&(e.status==="recorded"||e.status==="duplicate"))}function $(){let t=[];return navigator.webdriver===!0&&t.push({signal:"webdriver",detail:"navigator.webdriver"}),/HeadlessChrome\//.test(navigator.userAgent)&&t.push({signal:"headless_browser",detail:"HeadlessChrome"}),t}var w=new Map;function W(){try{let[t]=performance.getEntriesByType("navigation"),n=(t?.serverTiming??[]).filter(e=>e.name===A&&C(e.description)).map(e=>e.description);return[...new Set(n)].slice(0,5)}catch{return[]}}var H=new Set,D=new Set,B=new WeakMap;function K(t){let{history:n}=window,e=B.get(n);if(!e){let r=()=>{for(let i of[...e])i()};e=new Set,B.set(n,e);for(let i of["pushState","replaceState"]){let d=n[i];n[i]=function(...o){let s=d.apply(this,o);return r(),s}}window.addEventListener("popstate",r)}return e.add(t),()=>e.delete(t)}function V(t){if(!(t==null||t==="")){if(typeof t!="string"||t.length>4096)throw new Error("bindingContext must be the signed context your server created.");return t}}function q(t){let n=0,e=!1,r=()=>performance.now()-n<=1e3,i=()=>{n=performance.now()},d=()=>{e=r()},o=c=>{if(!c.isTrusted||r())return;let y=c.inputType;(y==="insertText"||y==="insertCompositionText"&&!e)&&(a(),t("typing"))},s={capture:!0,passive:!0};window.addEventListener("keydown",i,s),window.addEventListener("compositionstart",d,s),window.addEventListener("input",o,s);function a(){window.removeEventListener("keydown",i,s),window.removeEventListener("compositionstart",d,s),window.removeEventListener("input",o,s)}return a}function Z(t){let n=t.storage??"session";if(n!=="session"&&n!=="memory")throw new Error("Invalid storage option.");if(t.route!==void 0&&!m(t.route))throw new Error("route must be a path pattern such as /tickets/:id.");return{apiUrl:P(t.apiUrl,"apiUrl"),siteId:O(t.siteId),origin:U(),storage:n,navigation:t.navigation??!0,automationSignals:t.automationSignals??!0,bindingContext:V(t.bindingContext),onError:t.onError}}function J(t,n){return Object.keys(t).every(e=>e==="onError"&&n[e]===void 0||t[e]===n[e])}var b=class{constructor(n,e){this.config=n;this.key=L(n,n.bindingContext),this.stopInput=n.automationSignals?q(r=>{this.reportInput(r).catch(()=>{})}):()=>{},this.stopWatching=n.navigation?K(()=>this.navigated()):()=>{},this.ready=this.pageView({route:e}),this.ready.then(()=>this.claimLinks()).catch(()=>{})}config;ready;controller=new AbortController;key;stopWatching;stopInput;session=null;starting=null;destroyed=!1;path=window.location.pathname;async claimLinks(){let n=W();n.length&&await this.deliver("/v1/links",{links:n},n[0],"links",e=>n.every(r=>g(e)&&Array.isArray(e.results)&&e.results.some(i=>g(i)&&i.id===r)))}navigated(){this.destroyed||window.location.pathname===this.path||this.pageView().catch(()=>{})}async pageView(n={}){if(this.destroyed)throw new Error("This tracker was destroyed.");if(n.route!==void 0&&!m(n.route))throw new Error("route must be a path pattern such as /tickets/:id.");this.path=window.location.pathname;let e={id:crypto.randomUUID(),path:T(this.path),...n.route?{route:n.route}:{},occurredAt:new Date().toISOString()},r=await this.deliver("/v1/page-views",{views:[e]},e.id,"page view");this.config.automationSignals&&await this.firstSignals(r.sessionId)&&this.reportSignals().catch(()=>{})}async firstSignals(n){let e=`${await this.key}:signals`;if(H.has(n))return!1;if(H.add(n),this.config.storage==="memory")return!0;try{if(sessionStorage.getItem(e)===n)return!1;sessionStorage.setItem(e,n)}catch{}return!0}async reportInput(n){let e=await this.current(),r=`${await this.key}:input`;if(D.has(e.sessionId))return;D.add(e.sessionId);try{if(this.config.storage==="session"){if(sessionStorage.getItem(r)===e.sessionId)return;sessionStorage.setItem(r,e.sessionId)}}catch{}let i={id:crypto.randomUUID(),signal:"synthetic_input",detail:n,occurredAt:new Date().toISOString()};await this.deliver("/v1/browser-signals",{signals:[i]},i.id,"signal")}async reportSignals(){for(let n of $()){let e={id:crypto.randomUUID(),...n,occurredAt:new Date().toISOString()};await this.deliver("/v1/browser-signals",{signals:[e]},e.id,"signal")}}async current(){let n=await this.key;return this.session??=x(n,this.config.storage),this.session&&h(this.session.expiresAt)?this.session:(this.starting??=this.start(n).finally(()=>this.starting=null),this.starting)}async start(n){let e=await k(this.config,this.controller.signal,"/v1/sessions","POST",{siteId:this.config.siteId,...this.config.bindingContext?{bindingContext:this.config.bindingContext}:{}});if(!g(e)||!S(e.sessionId)||e.siteId!==this.config.siteId||e.origin!==this.config.origin||!h(e.expiresAt)||!v(e.sessionToken))throw new Error("Identification service returned an invalid new session.");return this.session={token:e.sessionToken,sessionId:e.sessionId,expiresAt:e.expiresAt},E(n,this.config.storage,this.session),this.session}async deliver(n,e,r,i,d=o=>N(o,r)){for(let o=0;;o++){let s=null;try{s=await this.current();let a=await k(this.config,this.controller.signal,n,"POST",e,s.token);if(!d(a))throw new Error(`Identification service did not confirm the ${i}.`);return s}catch(a){if(this.destroyed)throw a;let c=s!==null&&a instanceof p&&[401,404,410].includes(a.status);if(c&&s&&this.session===s){this.session=null;let l=await this.key;x(l,this.config.storage)?.token===s.token&&E(l,this.config.storage,null)}if(!(c||!(a instanceof p)||a.status===429||a.status>=500)||o>=2){let l=R(a);try{this.config.onError?.(l)}catch{}throw l}if(c||await new Promise(l=>setTimeout(l,300*3**o)),this.destroyed)throw a}}}destroy(){this.destroyed||(this.destroyed=!0,this.stopWatching(),this.stopInput(),this.controller.abort(),w.get(this.config.apiUrl+" "+this.config.siteId)===this&&w.delete(this.config.apiUrl+" "+this.config.siteId))}};function I(t){let n=Z(t),e=n.apiUrl+" "+n.siteId,r=w.get(e);if(r){if(!J(r.config,n))throw new Error("This site is already tracked on this page with different options.");return r}let i=new b(n,t.route);return w.set(e,i),i}window.AgentIdentificationTracker=Object.freeze({track:I});var u=document.currentScript;function G(t){document.dispatchEvent(new CustomEvent("agent-identification:error",{detail:{message:t}}))}if(u?.dataset.site)try{I({siteId:u.dataset.site,apiUrl:u.dataset.api??new URL(u.src).origin,storage:u.dataset.storage,route:u.dataset.route,navigation:u.dataset.navigation!=="off",automationSignals:u.dataset.automationSignals!=="off",...u.dataset.binding?{bindingContext:u.dataset.binding}:{},onError:t=>G(t.message)})}catch(t){G(t instanceof Error?t.message:"Agent Identification could not start.")}})();

package/dist/agent-id.js

@@ -1 +1 @@
-"use strict";(()=>{var E="0.8.2",W=["ai_assistant","person","prefer_not_to_say"];function D(t){return typeof t=="string"&&W.includes(t)}var V=512;var j=[/^\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,/@/,/^(?=(?:[^\d]*\d){3})(?=.*[a-z])[a-z0-9_-]{8,}$/i];function b(t){let i=t.replace(/[?#][\s\S]*$/,"").split("/").map(n=>{let r=n;try{r=decodeURIComponent(n)}catch{}return j.some(s=>s.test(r))?":id":n}).join("/");return(i.startsWith("/")?i:`/${i}`).slice(0,V)}function m(t){return typeof t=="string"&&/^\/[A-Za-z0-9_.~:/{}*-]{0,255}$/.test(t)}var h=new Map,B=15e3,u=class extends Error{constructor(i){super(`Identification service returned HTTP ${i}.`);this.status=i;this.name="HttpError"}status};function w(t,e){let i;try{i=new URL(t,window.location.href)}catch{throw new Error(`${e} must be a valid URL.`)}let n=["localhost","127.0.0.1","[::1]"].includes(i.hostname);if(i.protocol!=="https:"&&!(i.protocol==="http:"&&n)||i.username||i.password||i.search||i.hash)throw new Error(`${e} must use HTTPS (or localhost HTTP), without credentials, query or fragment.`);return i.href.replace(/\/$/,"")}function x(t){if(!/^[a-zA-Z0-9_-]{1,100}$/.test(t))throw new Error("siteId must contain 1\u2013100 letters, numbers, underscores or hyphens.");return t}function I(){if(window.location.origin==="null")throw new Error("Serve this website over HTTPS (or localhost HTTP) to use identification.");return window.location.origin}function g(t){return typeof t=="object"&&t!==null&&!Array.isArray(t)}function N(t,e=1,i=512){return typeof t=="string"&&t.length>=e&&t.length<=i&&/^[A-Za-z0-9._~-]+$/.test(t)}function p(t){return typeof t=="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(t)}function v(t){return typeof t=="string"&&/^[A-Za-z0-9_-]{32,512}$/.test(t)}function f(t){return typeof t=="string"&&/^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}\.\d{3}Z$/.test(t)&&Number.isFinite(Date.parse(t))&&Date.parse(t)>Date.now()}function H(t){return!g(t)||!v(t.token)||!p(t.sessionId)||!f(t.expiresAt)?null:{token:t.token,sessionId:t.sessionId,expiresAt:t.expiresAt}}async function k(t,e){let i=JSON.stringify([t.apiUrl,t.siteId,t.origin,e??null]),n=await crypto.subtle.digest("SHA-256",new TextEncoder().encode(i));return`parallel-agent-id:v1:${Array.from(new Uint8Array(n),r=>r.toString(16).padStart(2,"0")).join("")}`}function A(t,e){let i=h.get(t)??null;if(e==="session")try{let n=sessionStorage.getItem(t);i=n?H(JSON.parse(n)):i,n&&!i&&sessionStorage.removeItem(t)}catch{}return H(i)}function C(t,e,i){for(let[n,r]of h)f(r.expiresAt)||h.delete(n);if(i?h.set(t,{...i}):h.delete(t),e==="session")try{i?sessionStorage.setItem(t,JSON.stringify(i)):sessionStorage.removeItem(t)}catch{}}function S(t){return t instanceof Error?t:new Error("Identification request failed.")}async function T(t,e,i,n,r,s){let o=new AbortController,a=()=>o.abort();e.addEventListener("abort",a,{once:!0}),e.aborted&&o.abort();let d=setTimeout(()=>o.abort(),B);try{let l=await fetch(`${t.apiUrl}${i}`,{method:n,headers:{...r===void 0?{}:{"Content-Type":"application/json"},...s?{Authorization:`Bearer ${s}`,"X-Agent-Site":t.siteId}:{}},...r===void 0?{}:{body:JSON.stringify(r)},credentials:"omit",cache:"no-store",mode:"cors",referrerPolicy:"no-referrer",signal:o.signal});if(!l.ok)throw new u(l.status);if(n==="DELETE"){if(l.status!==204)throw new Error("Session revocation was not confirmed.");return null}if(!l.headers.get("content-type")?.toLowerCase().includes("application/json"))throw new Error("Identification service did not return JSON.");return await l.json()}catch(l){throw o.signal.aborted&&!e.aborted?new Error("Identification service timed out. Please retry.",{cause:l}):l}finally{clearTimeout(d),e.removeEventListener("abort",a)}}function _(t,e){return g(t)&&Array.isArray(t.results)&&t.results.some(i=>g(i)&&i.id===e&&(i.status==="recorded"||i.status==="duplicate"))}function P(){let t=[];return navigator.webdriver===!0&&t.push({signal:"webdriver",detail:"navigator.webdriver"}),/HeadlessChrome\//.test(navigator.userAgent)&&t.push({signal:"headless_browser",detail:"HeadlessChrome"}),t}var R=new WeakMap,L=new WeakMap,O={ai_assistant:"AI assistant",person:"Person",prefer_not_to_say:"Prefer not to say"};function q(t,e){let i=typeof t=="string"?document.querySelector(t):t;if(!(i instanceof HTMLElement))throw new Error(`${e} must identify an existing HTML element.`);return i}function z(t){let e=q(t.container,"container"),i=t.gate===void 0?void 0:q(t.gate,"gate"),n=w(t.apiUrl,"apiUrl"),r=t.mode??"optional",s=t.storage??"session";if(r!=="optional"&&r!=="required")throw new Error("Invalid identification mode.");if(s!=="session"&&s!=="memory")throw new Error("Invalid storage option.");if(i&&(i===e||i.contains(e)))throw new Error("The gate must not contain the identification widget.");let o=I();if(t.route!==void 0&&!m(t.route))throw new Error("route must be a path pattern such as /tickets/:id.");return{container:e,gate:i,apiUrl:n,siteId:x(t.siteId),origin:o,mode:r,storage:s,styleUrl:w(t.styleUrl??`${n}/sdk/v${E}/agent-id.css`,"styleUrl"),bindingContext:t.bindingContext,onRecorded:t.onRecorded,onError:t.onError,pageViews:t.pageViews??!0,route:t.route,automationSignals:t.automationSignals??!1}}function G(t,e){return Object.keys(t).every(i=>(i==="onRecorded"||i==="onError")&&e[i]===void 0?!0:t[i]===e[i])}function U(t,e,i,n){if(!g(t)||!p(t.sessionId)||i!==void 0&&t.sessionId!==i||t.siteId!==e.siteId||t.origin!==e.origin||!f(t.expiresAt)||t.evidence!=="self_reported")throw new Error("Identification service returned an invalid or mismatched session.");let r=t.choice===null&&t.receipt===null&&t.eventId===null,s=D(t.choice)&&N(t.receipt,1,8192)&&p(t.eventId);if(!r&&!s||n!==void 0&&t.choice!==n)throw new Error("Identification service returned an invalid or mismatched response.");return{sessionId:t.sessionId,siteId:e.siteId,origin:e.origin,expiresAt:t.expiresAt,choice:t.choice,receipt:t.receipt,eventId:t.eventId,evidence:"self_reported"}}var M=class{constructor(e){this.config=e;this.originalInert=e.gate?.inert??!1,this.build(),this.lock(),this.ready=this.start(this.version),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=!1;state=null;session=null;key=null;pending=null;retryAction=null;expiry;viewed=null;signalled=null;build(){this.host.dataset.agentIdentification=E;let e=document.createElement("link");e.rel="stylesheet",e.href=this.config.styleUrl;let i=document.createElement("section");i.className="agent-identification",i.setAttribute("aria-label","Visitor identification");let n=document.createElement("h2");n.textContent=this.config.mode==="required"?"Before continuing":"How are you visiting?";let r=document.createElement("p");r.textContent="Choose one option. Your answer is self-reported.";let s=document.createElement("div");s.className="choices";for(let o of Object.keys(O)){let a=document.createElement("button");a.type="button",a.textContent=O[o],a.disabled=!0,a.addEventListener("click",()=>{this.pending={choice:o,requestId:crypto.randomUUID()},this.submit(this.version).catch(()=>{})}),this.buttons.push(a),s.append(a)}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=!0,this.retry.addEventListener("click",()=>{let o=this.retryAction;o&&o().catch(()=>{})}),i.append(n,r,s,this.status,this.retry),this.root.append(e,i),this.config.container.append(this.host)}active(e){if(this.destroyed||e!==this.version)throw new DOMException("Widget operation was superseded.","AbortError")}lock(){this.config.mode==="required"&&this.config.gate&&(this.config.gate.inert=!0)}busy(e){this.status.textContent=e,this.retry.hidden=!0,this.retryAction=null;for(let i of this.buttons)i.disabled=!0}fail(e,i,n,r){if(this.destroyed||i!==this.version)return;let s=S(e);this.status.textContent=`${r} ${s.message}`,this.retry.hidden=!1,this.retryAction=n,this.notifyError(s)}notifyError(e){try{this.config.onError?.(e)}catch{}}accepted(e){if(this.state=e,clearTimeout(this.expiry),this.expiry=setTimeout(()=>{this.destroyed||this.state?.sessionId!==e.sessionId||(this.state=null,this.lock(),this.busy("Your identification session expired."),this.retry.hidden=!1,this.retryAction=()=>this.restart())},Math.min(Date.parse(e.expiresAt)-Date.now(),2147483647)),this.retry.hidden=!0,this.retryAction=null,e.choice!==null){this.status.textContent=`Response recorded: ${O[e.choice]}.`,this.config.mode==="required"&&this.config.gate&&(this.config.gate.inert=this.originalInert);try{this.config.onRecorded?.({...e})}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(let i of this.buttons)i.disabled=e.choice!==null;return{...e}}load(){return this.key?A(this.key,this.config.storage):null}persist(e){this.key&&C(this.key,this.config.storage,e)}request(e,i,n,r){return T(this.config,this.controller.signal,e,i,n,r)}async start(e){this.busy("Loading identification\u2026"),this.lock();try{let i=typeof this.config.bindingContext=="function"?await this.config.bindingContext():this.config.bindingContext;if(this.active(e),i!==void 0&&(typeof i!="string"||i.length===0||i.length>8192))throw new Error("bindingContext must be a nonempty signed context.");let n=await k(this.config,i);if(this.active(e),this.key=n,this.session=this.load(),this.session)try{let o=await this.request("/v1/sessions/current","GET",void 0,this.session.token);this.active(e);let a=U(o,this.config,this.session.sessionId);return this.session.expiresAt=a.expiresAt,this.persist(this.session),this.view(this.accepted(a))}catch(o){if(this.active(e),!(o instanceof u)||![401,404,410].includes(o.status))throw o;this.persist(null),this.session=null}let r=await this.request("/v1/sessions","POST",{siteId:this.config.siteId,...i===void 0?{}:{bindingContext:i}});this.active(e);let s=U(r,this.config);if(!g(r)||!v(r.sessionToken)||s.choice!==null)throw new Error("Identification service returned an invalid new session.");return this.session={token:r.sessionToken,sessionId:s.sessionId,expiresAt:s.expiresAt},this.persist(this.session),this.view(this.accepted(s))}catch(i){throw this.fail(i,e,()=>this.restart(),"Could not load identification."),i}}async submit(e){if(!this.pending||!this.session)throw new Error("Identification session is not ready.");let i=this.pending,n=this.session;this.busy("Recording your response\u2026");try{let r=await this.request("/v1/declarations","POST",i,n.token);this.active(e);let s=U(r,this.config,n.sessionId,i.choice);return n.expiresAt=s.expiresAt,this.persist(n),this.pending=null,this.accepted(s)}catch(r){throw this.fail(r,e,()=>this.submit(this.version),"Could not record your response."),r}}view(e){return this.config.pageViews&&this.viewed!==e.sessionId&&(this.viewed=e.sessionId,this.pageView({route:this.config.route}).catch(()=>{})),this.config.automationSignals&&this.signalled!==e.sessionId&&(this.signalled=e.sessionId,this.reportSignals().catch(()=>{})),e}async pageView(e={}){if(this.active(this.version),e.route!==void 0&&!m(e.route))throw new Error("route must be a path pattern such as /tickets/:id.");let i={id:crypto.randomUUID(),path:b(window.location.pathname),...e.route?{route:e.route}:{},occurredAt:new Date().toISOString()};await this.deliver("/v1/page-views",{views:[i]},i.id,"page view")}async deliver(e,i,n,r){let s=this.controller.signal;for(let o=0;;o++){let a=this.session;try{if(!a)throw new Error("Identification session is not ready.");let d=await this.request(e,"POST",i,a.token);if(!_(d,n))throw new Error(`Identification service did not confirm the ${r}.`);return}catch(d){if(s.aborted||this.destroyed)throw d;if(!(a!==null&&(!(d instanceof u)||d.status===429||d.status>=500))||o>=2){let y=S(d);throw this.notifyError(y),y}if(await new Promise(y=>setTimeout(y,300*3**o)),s.aborted||this.destroyed)throw d}}}async reportSignals(){for(let e of P()){let i={id:crypto.randomUUID(),...e,occurredAt:new Date().toISOString()};await this.deliver("/v1/browser-signals",{signals:[i]},i.id,"signal")}}restart(){return this.active(this.version),this.controller.abort(),clearTimeout(this.expiry),this.controller=new AbortController,this.version+=1,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;let e=++this.version;this.busy("Resetting identification\u2026"),this.state=null,this.pending=null,this.lock();try{this.session&&(await this.request("/v1/sessions/current","DELETE",void 0,this.session.token),this.active(e)),this.persist(null),this.session=null}catch(i){throw this.fail(i,e,()=>this.reset(),"Could not reset identification."),i}return this.start(e)}destroy(){this.destroyed||(this.destroyed=!0,this.version+=1,this.controller.abort(),clearTimeout(this.expiry),this.host.remove(),this.config.mode==="required"&&this.config.gate&&(this.config.gate.inert=this.originalInert,L.delete(this.config.gate)),R.delete(this.config.container),this.retryAction=null)}};function $(t){let e=z(t),i=R.get(e.container);if(i){if(!G(i.config,e))throw new Error("This container already has an identification widget with different options.");return i}if(e.mode==="required"&&e.gate&&L.has(e.gate))throw new Error("This gate is already controlled by another identification widget.");let n=new M(e);return R.set(e.container,n),e.mode==="required"&&e.gate&&L.set(e.gate,n),n}window.AgentIdentification=Object.freeze({init:$});var c=document.currentScript;if(c?.dataset.site){let t=()=>{try{let e;c.dataset.target?e=c.dataset.target:(e=document.createElement("div"),e.dataset.agentIdentificationContainer="",document.body.append(e));let i={container:e,siteId:c.dataset.site,apiUrl:c.dataset.api??new URL(c.src).origin,mode:c.dataset.mode,gate:c.dataset.gate,storage:c.dataset.storage,styleUrl:c.dataset.style,pageViews:c.dataset.pageViews!=="off",route:c.dataset.route,automationSignals:c.dataset.automationSignals==="on",onRecorded:n=>{(typeof e=="string"?document.querySelector(e):e).dispatchEvent(new CustomEvent("agent-identification:recorded",{detail:n,bubbles:!0}))},onError:n=>{document.dispatchEvent(new CustomEvent("agent-identification:error",{detail:{message:n.message}}))}};$(i)}catch(e){let i=e instanceof Error?e.message:"Identification widget could not initialize.",n=document.createElement("p");n.setAttribute("role","alert"),n.textContent=`Visitor identification unavailable. ${i}`,c.insertAdjacentElement("afterend",n),document.dispatchEvent(new CustomEvent("agent-identification:error",{detail:{message:i}}))}};document.readyState==="loading"?document.addEventListener("DOMContentLoaded",t,{once:!0}):t()}})();
+"use strict";(()=>{var E="0.9.0",W=["ai_assistant","person","prefer_not_to_say"];function $(t){return typeof t=="string"&&W.includes(t)}var V=512;var B=[/^\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,/@/,/^(?=(?:[^\d]*\d){3})(?=.*[a-z])[a-z0-9_-]{8,}$/i];function b(t){let i=t.replace(/[?#][\s\S]*$/,"").split("/").map(n=>{let r=n;try{r=decodeURIComponent(n)}catch{}return B.some(s=>s.test(r))?":id":n}).join("/");return(i.startsWith("/")?i:`/${i}`).slice(0,V)}function m(t){return typeof t=="string"&&/^\/[A-Za-z0-9_.~:/{}*-]{0,255}$/.test(t)}var h=new Map,j=15e3,l=class extends Error{constructor(i){super(`Identification service returned HTTP ${i}.`);this.status=i;this.name="HttpError"}status};function w(t,e){let i;try{i=new URL(t,window.location.href)}catch{throw new Error(`${e} must be a valid URL.`)}let n=["localhost","127.0.0.1","[::1]"].includes(i.hostname);if(i.protocol!=="https:"&&!(i.protocol==="http:"&&n)||i.username||i.password||i.search||i.hash)throw new Error(`${e} must use HTTPS (or localhost HTTP), without credentials, query or fragment.`);return i.href.replace(/\/$/,"")}function x(t){if(!/^[a-zA-Z0-9_-]{1,100}$/.test(t))throw new Error("siteId must contain 1\u2013100 letters, numbers, underscores or hyphens.");return t}function I(){if(window.location.origin==="null")throw new Error("Serve this website over HTTPS (or localhost HTTP) to use identification.");return window.location.origin}function g(t){return typeof t=="object"&&t!==null&&!Array.isArray(t)}function N(t,e=1,i=512){return typeof t=="string"&&t.length>=e&&t.length<=i&&/^[A-Za-z0-9._~-]+$/.test(t)}function p(t){return typeof t=="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(t)}function v(t){return typeof t=="string"&&/^[A-Za-z0-9_-]{32,512}$/.test(t)}function f(t){return typeof t=="string"&&/^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}\.\d{3}Z$/.test(t)&&Number.isFinite(Date.parse(t))&&Date.parse(t)>Date.now()}function M(t){return!g(t)||!v(t.token)||!p(t.sessionId)||!f(t.expiresAt)?null:{token:t.token,sessionId:t.sessionId,expiresAt:t.expiresAt}}async function k(t,e){let i=JSON.stringify([t.apiUrl,t.siteId,t.origin,e??null]),n=await crypto.subtle.digest("SHA-256",new TextEncoder().encode(i));return`parallel-agent-id:v1:${Array.from(new Uint8Array(n),r=>r.toString(16).padStart(2,"0")).join("")}`}function C(t,e){let i=h.get(t)??null;if(e==="session")try{let n=sessionStorage.getItem(t);i=n?M(JSON.parse(n)):i,n&&!i&&sessionStorage.removeItem(t)}catch{}return M(i)}function T(t,e,i){for(let[n,r]of h)f(r.expiresAt)||h.delete(n);if(i?h.set(t,{...i}):h.delete(t),e==="session")try{i?sessionStorage.setItem(t,JSON.stringify(i)):sessionStorage.removeItem(t)}catch{}}function S(t){return t instanceof Error?t:new Error("Identification request failed.")}async function A(t,e,i,n,r,s){let o=new AbortController,a=()=>o.abort();e.addEventListener("abort",a,{once:!0}),e.aborted&&o.abort();let c=setTimeout(()=>o.abort(),j);try{let u=await fetch(`${t.apiUrl}${i}`,{method:n,headers:{...r===void 0?{}:{"Content-Type":"application/json"},...s?{Authorization:`Bearer ${s}`,"X-Agent-Site":t.siteId}:{}},...r===void 0?{}:{body:JSON.stringify(r)},credentials:"omit",cache:"no-store",mode:"cors",referrerPolicy:"no-referrer",signal:o.signal});if(!u.ok)throw new l(u.status);if(n==="DELETE"){if(u.status!==204)throw new Error("Session revocation was not confirmed.");return null}if(!u.headers.get("content-type")?.toLowerCase().includes("application/json"))throw new Error("Identification service did not return JSON.");return await u.json()}catch(u){throw o.signal.aborted&&!e.aborted?new Error("Identification service timed out. Please retry.",{cause:u}):u}finally{clearTimeout(c),e.removeEventListener("abort",a)}}function P(t,e){return g(t)&&Array.isArray(t.results)&&t.results.some(i=>g(i)&&i.id===e&&(i.status==="recorded"||i.status==="duplicate"))}function _(){let t=[];return navigator.webdriver===!0&&t.push({signal:"webdriver",detail:"navigator.webdriver"}),/HeadlessChrome\//.test(navigator.userAgent)&&t.push({signal:"headless_browser",detail:"HeadlessChrome"}),t}var R=new WeakMap,L=new WeakMap,O={ai_assistant:"AI assistant",person:"Person",prefer_not_to_say:"Prefer not to say"};function q(t,e){let i=typeof t=="string"?document.querySelector(t):t;if(!(i instanceof HTMLElement))throw new Error(`${e} must identify an existing HTML element.`);return i}function G(t){let e=q(t.container,"container"),i=t.gate===void 0?void 0:q(t.gate,"gate"),n=w(t.apiUrl,"apiUrl"),r=t.mode??"optional",s=t.storage??"session";if(r!=="optional"&&r!=="required")throw new Error("Invalid identification mode.");if(s!=="session"&&s!=="memory")throw new Error("Invalid storage option.");if(i&&(i===e||i.contains(e)))throw new Error("The gate must not contain the identification widget.");let o=I();if(t.route!==void 0&&!m(t.route))throw new Error("route must be a path pattern such as /tickets/:id.");return{container:e,gate:i,apiUrl:n,siteId:x(t.siteId),origin:o,mode:r,storage:s,styleUrl:w(t.styleUrl??`${n}/sdk/v${E}/agent-id.css`,"styleUrl"),bindingContext:t.bindingContext,onRecorded:t.onRecorded,onError:t.onError,pageViews:t.pageViews??!0,route:t.route,automationSignals:t.automationSignals??!1}}function z(t,e){return Object.keys(t).every(i=>(i==="onRecorded"||i==="onError")&&e[i]===void 0?!0:t[i]===e[i])}function U(t,e,i,n){if(!g(t)||!p(t.sessionId)||i!==void 0&&t.sessionId!==i||t.siteId!==e.siteId||t.origin!==e.origin||!f(t.expiresAt)||t.evidence!=="self_reported")throw new Error("Identification service returned an invalid or mismatched session.");let r=t.choice===null&&t.receipt===null&&t.eventId===null,s=$(t.choice)&&N(t.receipt,1,8192)&&p(t.eventId);if(!r&&!s||n!==void 0&&t.choice!==n)throw new Error("Identification service returned an invalid or mismatched response.");return{sessionId:t.sessionId,siteId:e.siteId,origin:e.origin,expiresAt:t.expiresAt,choice:t.choice,receipt:t.receipt,eventId:t.eventId,evidence:"self_reported"}}var D=class{constructor(e){this.config=e;this.originalInert=e.gate?.inert??!1,this.build(),this.lock(),this.ready=this.start(this.version),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=!1;state=null;session=null;key=null;pending=null;retryAction=null;expiry;viewed=null;signalled=null;build(){this.host.dataset.agentIdentification=E;let e=document.createElement("link");e.rel="stylesheet",e.href=this.config.styleUrl;let i=document.createElement("section");i.className="agent-identification",i.setAttribute("aria-label","Visitor identification");let n=document.createElement("h2");n.textContent=this.config.mode==="required"?"Before continuing":"How are you visiting?";let r=document.createElement("p");r.textContent="Choose one option. Your answer is self-reported.";let s=document.createElement("div");s.className="choices";for(let o of Object.keys(O)){let a=document.createElement("button");a.type="button",a.textContent=O[o],a.disabled=!0,a.addEventListener("click",()=>{this.pending={choice:o,requestId:crypto.randomUUID()},this.submit(this.version).catch(()=>{})}),this.buttons.push(a),s.append(a)}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=!0,this.retry.addEventListener("click",()=>{let o=this.retryAction;o&&o().catch(()=>{})}),i.append(n,r,s,this.status,this.retry),this.root.append(e,i),this.config.container.append(this.host)}active(e){if(this.destroyed||e!==this.version)throw new DOMException("Widget operation was superseded.","AbortError")}lock(){this.config.mode==="required"&&this.config.gate&&(this.config.gate.inert=!0)}busy(e){this.status.textContent=e,this.retry.hidden=!0,this.retryAction=null;for(let i of this.buttons)i.disabled=!0}fail(e,i,n,r){if(this.destroyed||i!==this.version)return;let s=S(e);this.status.textContent=`${r} ${s.message}`,this.retry.hidden=!1,this.retryAction=n,this.notifyError(s)}notifyError(e){try{this.config.onError?.(e)}catch{}}accepted(e){if(this.state=e,clearTimeout(this.expiry),this.expiry=setTimeout(()=>{this.destroyed||this.state?.sessionId!==e.sessionId||(this.state=null,this.lock(),this.busy("Your identification session expired."),this.retry.hidden=!1,this.retryAction=()=>this.restart())},Math.min(Date.parse(e.expiresAt)-Date.now(),2147483647)),this.retry.hidden=!0,this.retryAction=null,e.choice!==null){this.status.textContent=`Response recorded: ${O[e.choice]}.`,this.config.mode==="required"&&this.config.gate&&(this.config.gate.inert=this.originalInert);try{this.config.onRecorded?.({...e})}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(let i of this.buttons)i.disabled=e.choice!==null;return{...e}}load(){return this.key?C(this.key,this.config.storage):null}persist(e){this.key&&T(this.key,this.config.storage,e)}request(e,i,n,r){return A(this.config,this.controller.signal,e,i,n,r)}async start(e){this.busy("Loading identification\u2026"),this.lock();try{let i=typeof this.config.bindingContext=="function"?await this.config.bindingContext():this.config.bindingContext;if(this.active(e),i!==void 0&&(typeof i!="string"||i.length===0||i.length>8192))throw new Error("bindingContext must be a nonempty signed context.");let n=await k(this.config,i);if(this.active(e),this.key=n,this.session=this.load(),this.session)try{let o=await this.request("/v1/sessions/current","GET",void 0,this.session.token);this.active(e);let a=U(o,this.config,this.session.sessionId);return this.session.expiresAt=a.expiresAt,this.persist(this.session),this.view(this.accepted(a))}catch(o){if(this.active(e),!(o instanceof l)||![401,404,410].includes(o.status))throw o;this.persist(null),this.session=null}let r=await this.request("/v1/sessions","POST",{siteId:this.config.siteId,...i===void 0?{}:{bindingContext:i}});this.active(e);let s=U(r,this.config);if(!g(r)||!v(r.sessionToken)||s.choice!==null)throw new Error("Identification service returned an invalid new session.");return this.session={token:r.sessionToken,sessionId:s.sessionId,expiresAt:s.expiresAt},this.persist(this.session),this.view(this.accepted(s))}catch(i){throw this.fail(i,e,()=>this.restart(),"Could not load identification."),i}}async submit(e){if(!this.pending||!this.session)throw new Error("Identification session is not ready.");let i=this.pending,n=this.session;this.busy("Recording your response\u2026");try{let r=await this.request("/v1/declarations","POST",i,n.token);this.active(e);let s=U(r,this.config,n.sessionId,i.choice);return n.expiresAt=s.expiresAt,this.persist(n),this.pending=null,this.accepted(s)}catch(r){throw this.fail(r,e,()=>this.submit(this.version),"Could not record your response."),r}}view(e){return this.config.pageViews&&this.viewed!==e.sessionId&&(this.viewed=e.sessionId,this.pageView({route:this.config.route}).catch(()=>{})),this.config.automationSignals&&this.signalled!==e.sessionId&&(this.signalled=e.sessionId,this.reportSignals().catch(()=>{})),e}async pageView(e={}){if(this.active(this.version),e.route!==void 0&&!m(e.route))throw new Error("route must be a path pattern such as /tickets/:id.");let i={id:crypto.randomUUID(),path:b(window.location.pathname),...e.route?{route:e.route}:{},occurredAt:new Date().toISOString()};await this.deliver("/v1/page-views",{views:[i]},i.id,"page view")}async deliver(e,i,n,r){let s=this.controller.signal;for(let o=0;;o++){let a=this.session;try{if(!a)throw new Error("Identification session is not ready.");let c=await this.request(e,"POST",i,a.token);if(!P(c,n))throw new Error(`Identification service did not confirm the ${r}.`);return}catch(c){if(s.aborted||this.destroyed)throw c;if(!(a!==null&&(!(c instanceof l)||c.status===429||c.status>=500))||o>=2){let y=S(c);throw this.notifyError(y),y}if(await new Promise(y=>setTimeout(y,300*3**o)),s.aborted||this.destroyed)throw c}}}async reportSignals(){for(let e of _()){let i={id:crypto.randomUUID(),...e,occurredAt:new Date().toISOString()};await this.deliver("/v1/browser-signals",{signals:[i]},i.id,"signal")}}restart(){return this.active(this.version),this.controller.abort(),clearTimeout(this.expiry),this.controller=new AbortController,this.version+=1,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;let e=++this.version;this.busy("Resetting identification\u2026"),this.state=null,this.pending=null,this.lock();try{this.session&&(await this.request("/v1/sessions/current","DELETE",void 0,this.session.token),this.active(e)),this.persist(null),this.session=null}catch(i){throw this.fail(i,e,()=>this.reset(),"Could not reset identification."),i}return this.start(e)}destroy(){this.destroyed||(this.destroyed=!0,this.version+=1,this.controller.abort(),clearTimeout(this.expiry),this.host.remove(),this.config.mode==="required"&&this.config.gate&&(this.config.gate.inert=this.originalInert,L.delete(this.config.gate)),R.delete(this.config.container),this.retryAction=null)}};function H(t){let e=G(t),i=R.get(e.container);if(i){if(!z(i.config,e))throw new Error("This container already has an identification widget with different options.");return i}if(e.mode==="required"&&e.gate&&L.has(e.gate))throw new Error("This gate is already controlled by another identification widget.");let n=new D(e);return R.set(e.container,n),e.mode==="required"&&e.gate&&L.set(e.gate,n),n}window.AgentIdentification=Object.freeze({init:H});var d=document.currentScript;if(d?.dataset.site){let t=()=>{try{let e;d.dataset.target?e=d.dataset.target:(e=document.createElement("div"),e.dataset.agentIdentificationContainer="",document.body.append(e));let i={container:e,siteId:d.dataset.site,apiUrl:d.dataset.api??new URL(d.src).origin,mode:d.dataset.mode,gate:d.dataset.gate,storage:d.dataset.storage,styleUrl:d.dataset.style,pageViews:d.dataset.pageViews!=="off",route:d.dataset.route,automationSignals:d.dataset.automationSignals==="on",onRecorded:n=>{(typeof e=="string"?document.querySelector(e):e).dispatchEvent(new CustomEvent("agent-identification:recorded",{detail:n,bubbles:!0}))},onError:n=>{document.dispatchEvent(new CustomEvent("agent-identification:error",{detail:{message:n.message}}))}};H(i)}catch(e){let i=e instanceof Error?e.message:"Identification widget could not initialize.",n=document.createElement("p");n.setAttribute("role","alert"),n.textContent=`Visitor identification unavailable. ${i}`,d.insertAdjacentElement("afterend",n),document.dispatchEvent(new CustomEvent("agent-identification:error",{detail:{message:i}}))}};document.readyState==="loading"?document.addEventListener("DOMContentLoaded",t,{once:!0}):t()}})();

package/dist/browser/index.js

@@ -1,5 +1,5 @@
 // src/protocol.ts
-var VERSION = "0.8.2";
+var VERSION = "0.9.0";
 var CHOICES = ["ai_assistant", "person", "prefer_not_to_say"];
 function isChoice(value) {
   return typeof value === "string" && CHOICES.includes(value);
@@ -191,6 +191,7 @@ function pageLinks() {
   }
 }
 var signalledSessions = /* @__PURE__ */ new Set();
+var inputSessions = /* @__PURE__ */ new Set();
 var navigationListeners = /* @__PURE__ */ new WeakMap();
 function watchNavigation(listener) {
   const { history } = window;
@@ -214,6 +215,42 @@ function watchNavigation(listener) {
   listeners.add(listener);
   return () => listeners.delete(listener);
 }
+function bindingContext(value) {
+  if (value === void 0 || value === null || value === "") return void 0;
+  if (typeof value !== "string" || value.length > 4096) {
+    throw new Error("bindingContext must be the signed context your server created.");
+  }
+  return value;
+}
+function watchInput(found) {
+  let lastKey = 0;
+  let composedByKey = false;
+  const keyPressed = () => performance.now() - lastKey <= 1e3;
+  const keydown = () => {
+    lastKey = performance.now();
+  };
+  const compositionstart = () => {
+    composedByKey = keyPressed();
+  };
+  const input = (event) => {
+    if (!event.isTrusted || keyPressed()) return;
+    const inputType = event.inputType;
+    if (inputType === "insertText" || inputType === "insertCompositionText" && !composedByKey) {
+      stop();
+      found("typing");
+    }
+  };
+  const options = { capture: true, passive: true };
+  window.addEventListener("keydown", keydown, options);
+  window.addEventListener("compositionstart", compositionstart, options);
+  window.addEventListener("input", input, options);
+  function stop() {
+    window.removeEventListener("keydown", keydown, options);
+    window.removeEventListener("compositionstart", compositionstart, options);
+    window.removeEventListener("input", input, options);
+  }
+  return stop;
+}
 function configure(options) {
   const storage = options.storage ?? "session";
   if (storage !== "session" && storage !== "memory") throw new Error("Invalid storage option.");
@@ -227,6 +264,7 @@ function configure(options) {
     storage,
     navigation: options.navigation ?? true,
     automationSignals: options.automationSignals ?? true,
+    bindingContext: bindingContext(options.bindingContext),
     onError: options.onError
   };
 }
@@ -238,7 +276,10 @@ function sameConfiguration(left, right) {
 var Controller = class {
   constructor(config, route) {
     this.config = config;
-    this.key = storageKey(config, void 0);
+    this.key = storageKey(config, config.bindingContext);
+    this.stopInput = config.automationSignals ? watchInput((detail) => void this.reportInput(detail).catch(() => {
+    })) : () => {
+    };
     this.stopWatching = config.navigation ? watchNavigation(() => this.navigated()) : () => {
     };
     this.ready = this.pageView({ route });
@@ -250,6 +291,7 @@ var Controller = class {
   controller = new AbortController();
   key;
   stopWatching;
+  stopInput;
   session = null;
   starting = null;
   destroyed = false;
@@ -309,6 +351,27 @@ var Controller = class {
     }
     return true;
   }
+  /** Reports injected input once per session, kept with the session like the other signals. */
+  async reportInput(detail) {
+    const session = await this.current();
+    const key = `${await this.key}:input`;
+    if (inputSessions.has(session.sessionId)) return;
+    inputSessions.add(session.sessionId);
+    try {
+      if (this.config.storage === "session") {
+        if (sessionStorage.getItem(key) === session.sessionId) return;
+        sessionStorage.setItem(key, session.sessionId);
+      }
+    } catch {
+    }
+    const event = {
+      id: crypto.randomUUID(),
+      signal: "synthetic_input",
+      detail,
+      occurredAt: (/* @__PURE__ */ new Date()).toISOString()
+    };
+    await this.deliver("/v1/browser-signals", { signals: [event] }, event.id, "signal");
+  }
   async reportSignals() {
     for (const signal of automationSignals()) {
       const event = { id: crypto.randomUUID(), ...signal, occurredAt: (/* @__PURE__ */ new Date()).toISOString() };
@@ -325,7 +388,8 @@ var Controller = class {
   }
   async start(key) {
     const body = await send(this.config, this.controller.signal, "/v1/sessions", "POST", {
-      siteId: this.config.siteId
+      siteId: this.config.siteId,
+      ...this.config.bindingContext ? { bindingContext: this.config.bindingContext } : {}
     });
     if (!record(body) || !uuid(body.sessionId) || body.siteId !== this.config.siteId || body.origin !== this.config.origin || !futureDate(body.expiresAt) || !sessionToken(body.sessionToken)) {
       throw new Error("Identification service returned an invalid new session.");
@@ -386,6 +450,7 @@ var Controller = class {
     if (this.destroyed) return;
     this.destroyed = true;
     this.stopWatching();
+    this.stopInput();
     this.controller.abort();
     if (trackers.get(this.config.apiUrl + " " + this.config.siteId) === this) {
       trackers.delete(this.config.apiUrl + " " + this.config.siteId);

package/dist/react/index.js

@@ -4,7 +4,7 @@
 import { useEffect, useRef } from "react";
 
 // src/protocol.ts
-var VERSION = "0.8.2";
+var VERSION = "0.9.0";
 var CHOICES = ["ai_assistant", "person", "prefer_not_to_say"];
 function isChoice(value) {
   return typeof value === "string" && CHOICES.includes(value);

package/dist/server/index.js

@@ -51,12 +51,37 @@ var AGENT_USER_AGENT_TOKENS = [
   "MistralAI-User",
   "DuckAssistBot"
 ];
+var CODING_AGENT_PRODUCTS = [
+  [/\bclaude-code\/\d/i, "Claude Code"],
+  [/\bcodex_cli_rs\/\d/i, "Codex"]
+];
+var HTTP_CLIENTS = [
+  [/^curl\//i, "curl"],
+  [/^Wget\//i, "Wget"],
+  [/^python-requests\//i, "Python requests"],
+  [/^python-httpx\//i, "Python httpx"],
+  [/^Python-urllib\//i, "Python urllib"],
+  [/^aiohttp\//i, "Python aiohttp"],
+  [/^axios\//i, "axios"],
+  [/^node-fetch\b/i, "node-fetch"],
+  [/^(node|undici)$/i, "Node.js fetch"],
+  [/^Go-http-client\//i, "Go HTTP client"],
+  [/^okhttp\//i, "OkHttp"],
+  [/^Java-http-client\//i, "Java HTTP client"],
+  [/^libwww-perl\//i, "Perl LWP"],
+  [/^HTTPie\//i, "HTTPie"],
+  [/^Deno\//i, "Deno"],
+  [/^Bun\//i, "Bun"]
+];
 function userAgentSignals(userAgent) {
   const found = [];
-  const token = AGENT_USER_AGENT_TOKENS.find(
+  const product = CODING_AGENT_PRODUCTS.find(([pattern]) => pattern.test(userAgent))?.[1];
+  const token = product ?? 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 });
+  const client = HTTP_CLIENTS.find(([pattern]) => pattern.test(userAgent.trim()))?.[1];
+  if (client && !token) found.push({ signal: "http_client", detail: client });
   if (/HeadlessChrome\//.test(userAgent))
     found.push({ signal: "headless_browser", detail: "HeadlessChrome" });
   return found;
@@ -398,9 +423,15 @@ async function reportRequestSignals(request, options) {
   try {
     const headers = headerMap(request);
     const found = userAgentSignals(headers["user-agent"] ?? "");
-    if (!found.length || isAssetRequest(requestUrl(request, headers), headers)) {
+    const url = options.url ?? requestUrl(request, headers);
+    if (!found.length || isAssetRequest(url, headers)) {
       return { status: "skipped" };
     }
+    let path = null;
+    try {
+      path = routePath(new URL(url, "http://localhost").pathname);
+    } catch {
+    }
     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"));
@@ -413,6 +444,7 @@ async function reportRequestSignals(request, options) {
       id: crypto.randomUUID(),
       ...item,
       ...address && item.signal === "agent_user_agent" ? { ip: address } : {},
+      ...path ? { path } : {},
       occurredAt,
       ...options.sessionBinding ? { sessionBinding: options.sessionBinding } : {},
       ...options.link ? { link: options.link } : {}
@@ -475,9 +507,88 @@ function reportLink(request, options = {}) {
 function serverTiming(link) {
   return `${LINK_TIMING};desc="${link}"`;
 }
+
+// src/server/setup.ts
+var DEFAULT_COLLECTOR = "https://parallel-agent-identification.vercel.app";
+var warned = /* @__PURE__ */ new Set();
+function agentIdentification(options = {}) {
+  const environment = typeof process === "undefined" ? {} : process.env;
+  const config = {
+    apiUrl: options.apiUrl ?? environment.AGENT_ID_API_URL ?? DEFAULT_COLLECTOR,
+    siteId: options.siteId ?? environment.AGENT_ID_SITE_ID ?? "",
+    secret: options.secret ?? environment.AGENT_ID_SITE_SECRET ?? "",
+    ...options.onError ? { onError: options.onError } : {},
+    ...options.fetch ? { fetch: options.fetch } : {}
+  };
+  const ready = () => {
+    if (config.siteId && config.secret) return true;
+    const missing = [!config.siteId && "AGENT_ID_SITE_ID", !config.secret && "AGENT_ID_SITE_SECRET"].filter(Boolean).join(" and ");
+    if (!warned.has(missing)) {
+      warned.add(missing);
+      const error = new Error(`Agent identification is off: set ${missing}.`);
+      (options.onError ?? ((failure) => console.warn(failure.message)))(error);
+    }
+    return false;
+  };
+  const report = (request, requestOptions = {}) => {
+    if (!ready()) return null;
+    const link = reportLink(request, requestOptions.url ? { url: requestOptions.url } : {});
+    const shared = {
+      ...config,
+      link,
+      ...requestOptions.url ? { url: requestOptions.url } : {}
+    };
+    const work = Promise.all([
+      reportSignedRequest(request, shared),
+      reportRequestSignals(request, {
+        ...shared,
+        clientIp: requestOptions.clientIp ?? null,
+        ...requestOptions.sessionBinding ? { sessionBinding: requestOptions.sessionBinding } : {}
+      })
+    ]);
+    if (requestOptions.waitUntil) requestOptions.waitUntil(work);
+    else void work;
+    return link ? serverTiming(link) : null;
+  };
+  return {
+    report,
+    express() {
+      return (request, response, next) => {
+        const timing = report(request, { clientIp: request.ip ?? null });
+        if (timing) response.append("Server-Timing", timing);
+        next();
+      };
+    },
+    next(request, event, response, extra = {}) {
+      const url = new URL(request.url);
+      url.host = request.headers.get("host") ?? url.host;
+      const clientIp = extra.clientIp !== void 0 ? extra.clientIp : environment.VERCEL ? request.headers.get("x-real-ip") : null;
+      const timing = report(request, {
+        url: url.href,
+        clientIp,
+        ...extra.sessionBinding ? { sessionBinding: extra.sessionBinding } : {},
+        waitUntil: (work) => event.waitUntil(work)
+      });
+      if (timing) response.headers.append("Server-Timing", timing);
+      return response;
+    },
+    action(input) {
+      if (!ready()) {
+        return Promise.resolve({
+          status: "failed",
+          id: input.id ?? "",
+          error: new Error("Agent identification is off: set its site ID and secret.")
+        });
+      }
+      return reportAction(input, config);
+    }
+  };
+}
 export {
   AGENT_USER_AGENT_TOKENS,
+  DEFAULT_COLLECTOR,
   LINK_TIMING,
+  agentIdentification,
   createBindingContext,
   isLink,
   reportAction,

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

@@ -15,6 +15,11 @@ export interface TrackerOptions {
      * session, as heuristic evidence that never labels a visitor an AI agent. Defaults to true.
      */
     automationSignals?: boolean;
+    /**
+     * 0.9.0: a binding context your server signed with createBindingContext() for this visitor's
+     * own session. Actions your server reports with the same sessionBinding then join this visit.
+     */
+    bindingContext?: string;
     onError?: (error: Error) => void;
 }
 export interface Tracker {

package/dist/types/protocol.d.ts

@@ -1,5 +1,5 @@
 /** Shared wire protocol. Classifications are always self-reported. */
-export declare const VERSION = "0.8.2";
+export declare const VERSION = "0.9.0";
 export declare const CHOICES: readonly ["ai_assistant", "person", "prefer_not_to_say"];
 export type Choice = (typeof CHOICES)[number];
 export type Mode = "optional" | "required";
@@ -120,7 +120,7 @@ export interface SignatureEvent extends EventBase {
  * Heuristic automation signals. Each is evidence, never identity: an automated browser isn't
  * necessarily an AI agent, and a user agent that names one is only a claim anyone can make.
  */
-export declare const SIGNALS: readonly ["webdriver", "headless_browser", "agent_user_agent"];
+export declare const SIGNALS: readonly ["webdriver", "headless_browser", "agent_user_agent", "http_client", "synthetic_input"];
 export type Signal = (typeof SIGNALS)[number];
 /** The signals a page can observe itself. */
 export declare const BROWSER_SIGNALS: readonly Signal[];
@@ -137,6 +137,8 @@ export interface SignalEvent extends EventBase {
     signal: Signal;
     /** What triggered it, such as the user agent's ChatGPT-User token. */
     detail: string | null;
+    /** 0.9.0: for a server's report, the masked path of the page requested. Null from a page. */
+    path: string | null;
     /**
      * For a server-reported agent user agent sent with the visitor's address, whether that address
      * is on the agent's operator's published list. Null when it wasn't checked.
@@ -162,6 +164,12 @@ export declare function isSignal(value: unknown): value is Signal;
  * request claims to be that agent, which anyone can do, so it's a signal, never verification.
  */
 export declare const AGENT_USER_AGENT_TOKENS: readonly ["Claude-Agent", "ChatGPT-User", "OAI-SearchBot", "GPTBot", "Claude-User", "Claude-SearchBot", "ClaudeBot", "Perplexity-User", "PerplexityBot", "MistralAI-User", "DuckAssistBot"];
+/**
+ * Coding agents that fetch pages from the developer's own machine, named by a product token in
+ * their user agent. Claude Code sends "Claude-User (claude-code/2.1.317; …)" from wherever it
+ * runs, so it's named on its own rather than checked against Anthropic's server addresses.
+ */
+export declare const CODING_AGENT_PRODUCTS: readonly [RegExp, string][];
 /** The signals a user agent string carries on its own. */
 export declare function userAgentSignals(userAgent: string): {
     signal: Signal;

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

@@ -7,6 +7,8 @@ export type { ActionReport, ActionReportOptions, ReportedAction } from "./activi
 export { reportSignedRequest } from "./web-bot-auth.js";
 export { reportRequestSignals } from "./signals.js";
 export { reportLink, serverTiming } from "./links.js";
+export { agentIdentification, DEFAULT_COLLECTOR } from "./setup.js";
+export type { AgentIdentification, AgentIdentificationOptions, RequestReportOptions, } from "./setup.js";
 export type { SignalReport, SignalReportOptions } from "./signals.js";
 export type { ReportableRequest, SignatureReport, SignatureReportOptions } from "./web-bot-auth.js";
 export { routePath, userAgentSignals, isLink, AGENT_USER_AGENT_TOKENS, LINK_TIMING, } from "../protocol.js";

package/dist/types/server/setup.d.ts

@@ -0,0 +1,60 @@
+import { type ActionReport, type ReportedAction } from "./activity.js";
+import { type ReportableRequest } from "./web-bot-auth.js";
+/** The hosted collector, used unless you pass apiUrl or set AGENT_ID_API_URL. */
+export declare const DEFAULT_COLLECTOR = "https://parallel-agent-identification.vercel.app";
+export interface AgentIdentificationOptions {
+    /** Your public site ID. Defaults to the AGENT_ID_SITE_ID environment variable. */
+    siteId?: string;
+    /** Your server secret. Defaults to AGENT_ID_SITE_SECRET. Never put it in browser code. */
+    secret?: string;
+    /** The collector. Defaults to AGENT_ID_API_URL, then the hosted collector. */
+    apiUrl?: string;
+    /** Called when a report fails. Defaults to a console warning without any secret. */
+    onError?: (error: Error) => void;
+    fetch?: typeof globalThis.fetch;
+}
+export interface RequestReportOptions {
+    /** The URL the visitor asked for, if your framework rewrites the request's own. */
+    url?: string;
+    /**
+     * The visitor's IP address as your platform gives it, never from a header visitors can set.
+     * It's sent only with a request that names an agent, to check it against the agent's
+     * operator's published addresses, and the collector keeps only the result.
+     */
+    clientIp?: string | null;
+    /** Your server's own session binding, as in the page script's binding context. */
+    sessionBinding?: string;
+    /** Keeps the reports running after the response, such as Next.js's event.waitUntil. */
+    waitUntil?: (work: Promise<unknown>) => void;
+}
+export interface AgentIdentification {
+    /**
+     * Reports one request: a signed agent's signature, and an agent or automation its user agent
+     * names. Ordinary requests and assets are skipped without a network call. Returns the
+     * Server-Timing value to add to this page's response, or null, so the page script can join the
+     * reports to its visit. It never throws and never waits for the collector.
+     */
+    report(request: ReportableRequest, options?: RequestReportOptions): string | null;
+    /** Express or Connect middleware that reports every request. */
+    express(): (request: ReportableRequest & {
+        ip?: string;
+    }, response: {
+        append(name: string, value: string): unknown;
+    }, next: () => void) => void;
+    /**
+     * For a Next.js proxy: reports the request and adds the link to your response. On Vercel it
+     * passes the visitor's address from x-real-ip, which Vercel sets; elsewhere pass clientIp.
+     */
+    next<T extends {
+        headers: Headers;
+    }>(request: Request, event: {
+        waitUntil(work: Promise<unknown>): void;
+    }, response: T, options?: Pick<RequestReportOptions, "clientIp" | "sessionBinding">): T;
+    /** Reports an action your server handled, such as an order placed. Never throws. */
+    action(input: ReportedAction): Promise<ActionReport>;
+}
+/**
+ * Sets up agent identification in one call, from AGENT_ID_SITE_ID and AGENT_ID_SITE_SECRET unless
+ * you pass them. Use .express() as middleware, or .next() in a Next.js proxy.
+ */
+export declare function agentIdentification(options?: AgentIdentificationOptions): AgentIdentification;

package/dist/types/server/signals.d.ts

@@ -17,6 +17,11 @@ export interface SignalReportOptions {
      * address.
      */
     clientIp?: string | null;
+    /**
+     * The URL the visitor asked for, when your framework changes the request's own (Next.js uses
+     * localhost). Its masked path goes with the report, so you can see which pages agents fetched.
+     */
+    url?: string;
     /** Called when a report fails. Defaults to a console warning without any secret. */
     onError?: (error: Error) => void;
     fetch?: typeof globalThis.fetch;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@useparallel/agent-identification",
-  "version": "0.8.2",
+  "version": "0.9.0",
   "description": "See which AI agents use your website: report agents from your server, record visits with a page script that draws nothing, and verify signed agents and operators' published addresses.",
   "type": "module",
   "license": "MIT",