@katrinalaszlo/track 0.5.0 → 0.6.0

package/README.md

@@ -31,7 +31,7 @@ app.use(agentTraffic({ accountIdOf: (req, res) => req.user?.id }));
 
 Register it right after creating the app, before auth and routes. `accountIdOf` returns your customer's id (hashed before it leaves your server), or undefined. Optional `errorOf(req, res)` returns error text for failed responses (400 and above, up to 200 characters), so two errors with the same status show separately. Keys come from `AGENT_TRAFFIC_KEY`, `AGENT_TRAFFIC_PROJECT_ID` and `AGENT_TRAFFIC_ACCOUNT_SALT` in the environment or `.env`; get them with the signup in [SKILL.md](skills/agent-traffic/SKILL.md).
 
-Per request it sends the route pattern, method, status code, the `User-Agent`, `Signature-Agent` and `Accept-Language` headers, the time, the hashed customer id, the journey key if the request carried one (see below), and the text `errorOf` returns if you set it. When an agent signed its request (Web Bot Auth, `Signature` and `Signature-Input` headers present) it also sends those two headers, the request's full URL, and the other headers the signature covers, so the signature can be checked; never `Authorization` or `Cookie`, whatever the signer covered. Otherwise no bodies, no other headers, no IPs. To see which agents lead to signups and payments, call `traffic.recordOutcome({ accountId, name: "paid", value: 1999, currency: "USD", idempotencyKey: paymentEvent.id })` from your payment webhook (and `name: "signup"` from your signup handler): the outcome joins the agent session of the same customer. Events go out in batches once a second (at once on Vercel, Lambda and Netlify), and it never blocks or fails a request. No dependencies; TypeScript types included.
+Per request it sends the route pattern, the path (see below), method, status code, the `User-Agent`, `Signature-Agent` and `Accept-Language` headers, the time, the hashed customer id, the journey key if the request carried one (see below), and the text `errorOf` returns if you set it. When an agent signed its request (Web Bot Auth, `Signature` and `Signature-Input` headers present) it also sends those two headers, the request's full URL, and the other headers the signature covers, so the signature can be checked; never `Authorization` or `Cookie`, whatever the signer covered. Otherwise no bodies, no other headers, no IPs. To see which agents lead to signups and payments, call `traffic.recordOutcome({ accountId, name: "paid", value: 1999, currency: "USD", idempotencyKey: paymentEvent.id })` from your payment webhook (and `name: "signup"` from your signup handler): the outcome joins the agent session of the same customer. Events go out in batches once a second (at once on Vercel, Lambda and Netlify), and it never blocks or fails a request. No dependencies; TypeScript types included.
 
 ### Journey keys
 
@@ -47,6 +47,12 @@ Then every response carries the visitor's key: the one the request sent, or a ne
 
 Event names use the matched route's pattern and exclude router mount prefixes, which can contain raw IDs. A router mounted at `/customers/:customerId` with route `/orders/:orderId` records `orders_orderid` for every customer. Routes with the same pattern under different mounts share an event name.
 
+### Path
+
+Each event also carries `path`, which Track's Paths and Attribution reports use: the path the app received, router mount prefix included, cut at the first `?` or `#`. `GET https://api.example.com/v1/users?api_key=123` is sent as `/v1/users`: never the domain, and never the query or fragment, so an API key or a `track_j` value in the query is neither sent nor logged. Segments are sent as they are, not percent-decoded, so an id in the path is sent: `/v1/users/123` arrives as `/v1/users/123`. Event names stay route patterns (`users_id`), so reports grouped by event name do not split by id; there is no option yet to leave `path` out of the event. A path that does not start with `/` or is longer than 2048 characters is left out of the event.
+
+For a signed request (Web Bot Auth), the signature material still carries the full URL with its query, because the signature covers it and cannot be checked without it. It goes to Track ingest only, never to a log.
+
 What each event contains, and the raw HTTP API for other stacks: [alg.katrinalaszlo.com/docs](https://alg.katrinalaszlo.com/docs).
 
 ## Tests

package/index.d.ts

@@ -53,6 +53,11 @@ export interface AgentTrafficMiddleware {
   recordOutcome(outcome: OutcomeInput): Promise<void>;
 }
 
+/**
+ * Each event the middleware records carries `path`: the request path as the app received it (router mount prefix
+ * included, not percent-decoded), cut at the first "?" or "#", so never the domain or the query. Left out when it does
+ * not start with "/" or is longer than 2048 characters. Ids in path segments (/v1/users/123) are sent as they are.
+ */
 export function agentTraffic(options?: AgentTrafficOptions): AgentTrafficMiddleware;
 
 /** The event name for a request: its route pattern without router mount prefixes, version and "api" segments dropped, the method added for anything but GET. */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@katrinalaszlo/track",
-  "version": "0.5.0",
+  "version": "0.6.0",
   "description": "Express middleware that shows which AI agents call your API, how their sessions go, and which errors end them.",
   "license": "MIT",
   "type": "module",

package/skills/agent-traffic/agent-traffic.cjs

@@ -36,6 +36,7 @@ const OUTCOME_NAMES = ["signup", "key_created", "activation", "paid", "custom"];
 const FLUSH_MS = 1000;
 const RETRIES_MAX = 3;
 const ERROR_MAX = 200;
+const PATH_MAX = 2048;
 // On serverless hosts the process can freeze as soon as the response is sent, so a queued batch might never go out.
 // There each event is sent at once, and on Vercel the send is handed to waitUntil so the function stays up until it
 // is done (the request context @vercel/functions reads, without depending on it).
@@ -116,13 +117,25 @@ function signatureMaterial(req) {
   };
 }
 
+// The path the app received, mount prefix included, cut at the first ? or #: never the domain or the query, which
+// can hold an API key or a journey key. Not percent-decoded. Anything that does not start with / or is longer than
+// ingest accepts is left out rather than cut.
+function requestPath(req) {
+  const url = req.originalUrl ?? req.url;
+  if (typeof url !== "string") return undefined;
+  const path = url.split(/[?#]/)[0];
+  if (!path.startsWith("/") || path.length > PATH_MAX) return undefined;
+  return path;
+}
+
 // A journey key ties requests from one visitor together across sessions: the journey header, else ?track_j= in the URL,
 // else the track_j cookie. The first value that fits the ingest rule wins; one that does not is ignored, never sent.
 function journeyKeyOf(req) {
   const header = req.headers[JOURNEY_HEADER.toLowerCase()];
   if (typeof header === "string" && JOURNEY_KEY.test(header)) return { journey_id: header, journey_source: "header" };
 
-  const url = req.originalUrl ?? req.url ?? "";
+  const rawUrl = req.originalUrl ?? req.url;
+  const url = typeof rawUrl === "string" ? rawUrl : "";
   const queryStart = url.indexOf("?");
   if (queryStart !== -1) {
     const fromQuery = new URLSearchParams(url.slice(queryStart + 1)).getAll(JOURNEY_PARAM).find((value) => JOURNEY_KEY.test(value));
@@ -190,7 +203,7 @@ function agentTraffic({ accountIdOf, errorOf, key, projectId, salt, endpoint, is
           byReason.set(label, (byReason.get(label) ?? 0) + 1);
         }
         for (const [label, n] of byReason) {
-          const hint = label.startsWith("unknown_field") ? ". The agent traffic host does not know this field yet: it is older than this package (0.5.0). Upgrade the host, or pin @katrinalaszlo/track to 0.4.x. https://alg.katrinalaszlo.com/docs#event-fields" : "";
+          const hint = label.startsWith("unknown_field") ? ". The agent traffic host does not know this field yet: it is older than this package (0.6.0). Upgrade the host, or pin @katrinalaszlo/track to 0.5.x. https://alg.katrinalaszlo.com/docs#event-fields" : "";
           console.error(`agent-traffic: ${n} of ${batch.length} events rejected: ${label}${hint}`);
         }
         return;
@@ -263,8 +276,8 @@ function agentTraffic({ accountIdOf, errorOf, key, projectId, salt, endpoint, is
       try {
         event = eventOf(req, res, occurredAt, journey);
       } catch (err) {
-        // The path only: the query string can hold a journey key, which never goes in a log.
-        console.error(`agent-traffic: event not recorded for ${req.method} ${(req.originalUrl ?? req.url ?? "").split("?")[0]}: ${err.stack}`);
+        // The path only: the query string can hold an API key or a journey key, which never go in a log.
+        console.error(`agent-traffic: event not recorded for ${req.method} ${requestPath(req) ?? "(no path)"}: ${err.stack}`);
         return;
       }
       if (SERVERLESS || vercel?.waitUntil) {
@@ -289,6 +302,7 @@ function agentTraffic({ accountIdOf, errorOf, key, projectId, salt, endpoint, is
     return {
       idempotency_key: randomUUID(),
       name: eventName(req),
+      path: requestPath(req),
       occurred_at: occurredAt,
       source: "sdk",
       account_id: accountId ? hashAccountId(accountId) : undefined,