@katrinalaszlo/track 0.5.0 → 0.7.0

package/README.md

@@ -29,9 +29,9 @@ const { agentTraffic } = require("@katrinalaszlo/track"); // or: import { agentT
 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).
+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. It needs one variable, `AGENT_TRAFFIC_KEY`, in the environment or `.env`: the key belongs to one project, and events go there. Get it with `npx agent-led-growth connect`, which opens your browser to sign in and writes the key to `.env` for you, or with the signup in [SKILL.md](skills/agent-traffic/SKILL.md). `AGENT_TRAFFIC_ACCOUNT_SALT` is needed when you set `accountIdOf` or call `recordOutcome`. `AGENT_TRAFFIC_PROJECT_ID` is optional: set, it is sent with each batch as before.
 
-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 fails a request. The one request it holds up is a person opening a handoff link (below), for at most 2 seconds. No dependencies; TypeScript types included.
 
 ### Journey keys
 
@@ -45,8 +45,32 @@ app.use(agentTraffic({ accountIdOf: (req, res) => req.user?.id, issueJourneyKeys
 
 Then every response carries the visitor's key: the one the request sent, or a new one (`j_` plus 32 hex characters) when it sent none. It goes out as the `Track-Journey` response header and as `Set-Cookie: track_j=<key>; Path=/; Max-Age=1209600; SameSite=Lax; Secure`, with `Cache-Control: private` so a shared cache never serves one visitor's key to another. It is off by default because it sets a cookie on your responses and changes their caching: that can need a line in your cookie policy or consent banner, and a CDN will stop caching those responses. Both are set before your routes run, so a route that sets its own `Cache-Control` replaces `private` (keep it private on any response that carries a key), and a raw `res.setHeader("Set-Cookie", ...)` replaces the `track_j` cookie (Express's `res.cookie` and express-session add to it instead). The request that receives a new key is sent with that key as `journey_id` and `journey_source: "issued"`, so it is the first step of the journey.
 
+### Handoff links
+
+When an agent cannot finish on its own (a person has to approve a payment or verify an email) and your server sends that person a link, add a handoff token to the link so the person's actions count toward the agent's journey. Their checkout is then credited to the agent that brought them.
+
+```js
+const traffic = agentTraffic({ accountIdOf: (req, res) => req.user?.id, issueJourneyKeys: true });
+app.use(traffic);
+
+app.post("/v1/checkout-links", async (req, res) => {
+  const link = await traffic.handoffUrl("https://example.com/checkout?plan=pro", { req });
+  res.json({ approve_at: link });   // https://example.com/checkout?plan=pro&track_h=h_...
+});
+```
+
+`handoffUrl(link, { req })` asks Track for a one-time token for the journey of `req` (the agent's request, which must carry a journey key, or have one issued) and resolves with `link` plus `?track_h=<token>`. Pass `{ journeyId }` instead when you have the key without the request. It throws at once when `link` is not an absolute URL or there is no journey key. If Track cannot mint a token, it logs why and resolves with `link` unchanged, so the person still gets a working link that just does not count toward the journey.
+
+When the person opens the link, the middleware sees `?track_h=` and, before your routes run, sends a `handoff_opened` event carrying the token and waits up to 2 seconds for Track's answer. If Track linked it, the request's own event goes on the agent's journey (`journey_source: "issued"`), and with `issueJourneyKeys` on the response sets the person's `track_j` cookie to the agent's journey, so their sign-in and checkout land on it too. With `issueJourneyKeys` off no cookie is set: read `traffic.journeyIdOf(req)` and set the `track_j` cookie (or send the `Track-Journey` header) yourself. A token links once and for 24 hours; a used, expired or unknown token, or Track not answering in time, leaves the person on their own journey and logs one line. A token is never written to a log, and `?track_h=` never reaches `path`. Needs a Track host that takes `handoff_token` (an older one logs that it does not).
+
 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

@@ -7,7 +7,7 @@ export interface AgentTrafficOptions {
   errorOf?: (req: any, res: any) => string | null | undefined;
   /** Defaults to AGENT_TRAFFIC_KEY from the environment or .env. */
   key?: string;
-  /** Defaults to AGENT_TRAFFIC_PROJECT_ID from the environment or .env. */
+  /** Defaults to AGENT_TRAFFIC_PROJECT_ID from the environment or .env. Optional: without it, events go to the key's own project. */
   projectId?: string;
   /** Defaults to AGENT_TRAFFIC_ACCOUNT_SALT from the environment or .env. Required when accountIdOf is set. */
   salt?: string;
@@ -29,10 +29,20 @@ export const JOURNEY_HEADER: string;
 export interface JourneyFields {
   /** 8 to 128 characters of A-Z, a-z, 0-9, _ and -. */
   journey_id: string;
-  /** "issued" when issueJourneyKeys minted the key on this request's response. */
+  /** "issued" when issueJourneyKeys minted the key on this request's response, or a handoff link gave the request the agent's journey. */
   journey_source: "header" | "query" | "cookie" | "issued";
 }
 
+/** The query parameter a handoff link carries: "track_h". */
+export const HANDOFF_PARAM: string;
+
+export interface HandoffOptions {
+  /** A request the middleware saw: its journey key (after any handoff) is the agent's journey to hand off. */
+  req?: any;
+  /** The agent's journey key, when you have it without a request. Wins over req. */
+  journeyId?: string;
+}
+
 export interface OutcomeInput {
   /** The same customer id accountIdOf returns for this customer's requests. Hashed with the salt before it is sent. */
   accountId: string | number;
@@ -51,8 +61,22 @@ export interface AgentTrafficMiddleware {
   (req: any, res: any, next: (err?: unknown) => void): void;
   /** Sends one outcome at once. Throws synchronously on bad input; the returned promise settles when the send finished. */
   recordOutcome(outcome: OutcomeInput): Promise<void>;
+  /**
+   * Resolves with `link` plus `?track_h=<token>`, a one-time token (24 hours) that puts the person who opens the link
+   * on the agent's journey. Throws synchronously when link is not absolute or there is no valid journey key. When Track
+   * cannot mint a token, logs it and resolves with `link` unchanged.
+   */
+  handoffUrl(link: string, options: HandoffOptions): Promise<string>;
+  /** The journey key the middleware recorded this request with (the agent's, when a handoff link linked it), or undefined. */
+  journeyIdOf(req: any): string | undefined;
 }
 
+/**
+ * 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.
+ * A request with a well-formed ?track_h= waits up to 2 seconds for Track to link it, before your routes run.
+ */
 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.7.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

@@ -11,14 +11,21 @@
 // accountIdOf returns your customer's id for the request (called with req and res after the response, so values your
 // auth set on either, such as req.user or res.locals.user, are there), or undefined. errorOf, optional, returns the
 // error text for a failed response (status 400 and above), such as an error code your handler put in res.locals, so
-// two errors with the same status show as different rows in Fix next. AGENT_TRAFFIC_KEY,
-// AGENT_TRAFFIC_PROJECT_ID and AGENT_TRAFFIC_ACCOUNT_SALT come from the environment, or from a .env in the working
-// directory, this file's folder or any folder above it, when the environment lacks them; only AGENT_TRAFFIC_ lines are
-// read, nothing else in .env is touched. issueJourneyKeys, optional and off by default, gives each visitor a journey key
+// two errors with the same status show as different rows in Fix next. AGENT_TRAFFIC_KEY (required),
+// AGENT_TRAFFIC_ACCOUNT_SALT and AGENT_TRAFFIC_PROJECT_ID (optional: without it the key's own project is used) come from
+// the environment, or from a .env in the working directory, this file's folder or any folder above it, when the
+// environment lacks them; only AGENT_TRAFFIC_ lines are read, nothing else in .env is touched. issueJourneyKeys, optional and off by default, gives each visitor a journey key
 // on the response (a header and a track_j cookie) so its later requests join one journey.
 //
-// Register it right after creating the app, before auth and routes. It never blocks or fails a request: events are
-// queued, sent in batches of up to 25 once a second, and a failed batch is logged and retried with the same keys.
+// Handoffs: when an agent sends a person a link to finish (approve a payment, verify an email), add a one-time token so
+// the person's actions count toward the agent's journey:
+//   const link = await traffic.handoffUrl("https://example.com/checkout?plan=pro", { req });   // adds ?track_h=<token>
+// A request that arrives with ?track_h= waits up to 2 seconds for Track to link it to the agent's journey, records a
+// handoff_opened event, and, with issueJourneyKeys on, sets the person's track_j cookie to the agent's journey.
+//
+// Register it right after creating the app, before auth and routes. It never fails a request, and blocks none but a
+// request carrying ?track_h=: events are queued, sent in batches of up to 25 once a second, and a failed batch is logged
+// and retried with the same keys.
 const { createHmac, randomBytes, randomUUID } = require("node:crypto");
 const { existsSync, readFileSync } = require("node:fs");
 const { dirname, join } = require("node:path");
@@ -30,12 +37,19 @@ const JOURNEY_PARAM = "track_j";
 const JOURNEY_KEY = /^[A-Za-z0-9_-]{8,128}$/;
 // 14 days. Secure so the key never travels over plain http; Lax so it comes along when a person follows a link in.
 const JOURNEY_COOKIE_ATTRIBUTES = "Path=/; Max-Age=1209600; SameSite=Lax; Secure";
+// The query parameter a handoff link carries, and the token shape Track mints. A token is a secret in transit: it goes
+// to Track only, never into a log or an error message.
+const HANDOFF_PARAM = "track_h";
+const HANDOFF_TOKEN = /^h_[A-Za-z0-9_-]{32,64}$/;
+// How long a request with ?track_h= waits for Track before it carries on unlinked.
+const HANDOFF_WAIT_MS = 2000;
 
 const BATCH_MAX = 25;
 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 +130,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));
@@ -141,6 +167,15 @@ function journeyKeyOf(req) {
   return undefined;
 }
 
+// The ?track_h= value when it has the token shape, else undefined.
+function handoffTokenOf(req) {
+  const rawUrl = req.originalUrl ?? req.url;
+  const url = typeof rawUrl === "string" ? rawUrl : "";
+  const queryStart = url.indexOf("?");
+  if (queryStart === -1) return undefined;
+  return new URLSearchParams(url.slice(queryStart + 1)).getAll(HANDOFF_PARAM).find((value) => HANDOFF_TOKEN.test(value));
+}
+
 // Cache-Control: private so a shared cache never hands one visitor's key to another. A Set-Cookie an earlier
 // middleware added is kept.
 function setJourneyKey(res, journeyId) {
@@ -157,9 +192,13 @@ function agentTraffic({ accountIdOf, errorOf, key, projectId, salt, endpoint, is
   projectId ??= env.AGENT_TRAFFIC_PROJECT_ID;
   salt ??= env.AGENT_TRAFFIC_ACCOUNT_SALT;
   endpoint ??= env.AGENT_TRAFFIC_ENDPOINT ?? "https://alg.katrinalaszlo.com";
-  if (!key || !projectId) throw new Error("agentTraffic needs AGENT_TRAFFIC_KEY and AGENT_TRAFFIC_PROJECT_ID, in the environment or in .env.");
+  if (!key) throw new Error("agentTraffic needs AGENT_TRAFFIC_KEY, in the environment or in .env. Run `npx agent-led-growth connect` to get one.");
   if (accountIdOf && !salt) throw new Error("agentTraffic needs AGENT_TRAFFIC_ACCOUNT_SALT, in the environment or in .env, to hash what accountIdOf returns.");
-  const url = `${endpoint}/v1/events?project_id=${encodeURIComponent(projectId)}`;
+  const projectQuery = projectId ? `?project_id=${encodeURIComponent(projectId)}` : "";
+  const url = `${endpoint}/v1/events${projectQuery}`;
+  const handoffsUrl = `${endpoint}/v1/handoffs${projectQuery}`;
+  // The journey key each request was recorded with, after a handoff link changed it; read by journeyIdOf and handoffUrl.
+  const journeys = new WeakMap();
   let queue = [];
   let timer = null;
   const warned = new Set();
@@ -190,7 +229,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.7.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;
@@ -249,36 +288,116 @@ function agentTraffic({ accountIdOf, errorOf, key, projectId, salt, endpoint, is
     return sending;
   }
 
+  // The journey key the middleware recorded req with (the agent's journey when a handoff link linked it), or undefined.
+  function journeyIdOf(req) {
+    return journeys.get(req)?.journey_id;
+  }
+
+  // Resolves with link plus ?track_h=<token> for the agent's journey: journeyId, else the journey of req. Bad input
+  // throws synchronously. When Track cannot mint a token the failure is logged and the promise resolves with link
+  // unchanged, so the person still gets a working link; it just will not count toward the agent's journey.
+  function handoffUrl(link, { req, journeyId } = {}) {
+    let target;
+    try {
+      target = new URL(link);
+    } catch {
+      throw new TypeError("handoffUrl: link must be an absolute URL, such as https://example.com/checkout, because it is sent to a person.");
+    }
+    const journey = journeyId ?? (req ? journeyIdOf(req) ?? journeyKeyOf(req)?.journey_id : undefined);
+    if (typeof journey !== "string" || !JOURNEY_KEY.test(journey)) throw new TypeError("handoffUrl: no journey to hand off. Pass { req } for a request that carried a journey key (Track-Journey header, ?track_j= or the track_j cookie, or issueJourneyKeys on), or { journeyId }. docs: https://alg.katrinalaszlo.com/docs#handing-off-to-a-person");
+    return (async () => {
+      try {
+        const res = await fetch(handoffsUrl, {
+          method: "POST",
+          headers: { authorization: `Bearer ${key}`, "content-type": "application/json" },
+          body: JSON.stringify({ journey_id: journey }),
+        });
+        const body = await res.json();
+        if (res.status !== 201) {
+          console.error(`agent-traffic: handoff link sent without a token: ${res.status} ${body.error}: ${body.message}`);
+          return link;
+        }
+        target.searchParams.set(HANDOFF_PARAM, body.token);
+        return target.toString();
+      } catch (err) {
+        console.error(`agent-traffic: handoff link sent without a token: ${err.message}`);
+        return link;
+      }
+    })();
+  }
+
+  // Sends the event of a request that arrived with a handoff token, at once, and resolves with the agent's journey key
+  // when Track linked it, else null. Never rejects: a failure is logged (without the token) and the request carries on.
+  async function linkHandoff(event) {
+    try {
+      const res = await fetch(url, {
+        method: "POST",
+        headers: { authorization: `Bearer ${key}`, "content-type": "application/json" },
+        body: JSON.stringify([event]),
+        signal: AbortSignal.timeout(HANDOFF_WAIT_MS),
+      });
+      const body = await res.json();
+      if (res.status !== 202) {
+        console.error(`agent-traffic: handoff not linked: ${res.status} ${body.error}: ${body.message}`);
+        return null;
+      }
+      for (const entry of body.rejected) {
+        const hint = entry.reason === "unknown_field" ? ". The agent traffic host is older than this package (0.7.0) and does not take handoff tokens yet." : "";
+        console.error(`agent-traffic: handoff not linked: event rejected: ${entry.reason}${hint}`);
+      }
+      for (const warning of body.event_warnings ?? []) console.error(`agent-traffic: handoff not linked: ${warning.message}`);
+      return body.journeys?.[0]?.journey_id ?? null;
+    } catch (err) {
+      console.error(`agent-traffic: handoff not linked: ${err.message}`);
+      return null;
+    }
+  }
+
   function agentTrafficMiddleware(req, res, next) {
     const occurredAt = new Date().toISOString();
     // Read while the request is current: the context is per request.
     const vercel = globalThis[VERCEL_CONTEXT]?.get?.();
     let journey = journeyKeyOf(req);
     if (issueJourneyKeys && !journey) journey = { journey_id: `j_${randomBytes(16).toString("hex")}`, journey_source: "issued" };
-    if (issueJourneyKeys) setJourneyKey(res, journey.journey_id);
-    res.on("finish", () => {
-      // An exception here would be thrown outside the request, so it is logged instead: the event is lost, the
-      // server is not.
-      let event;
-      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}`);
-        return;
-      }
-      if (SERVERLESS || vercel?.waitUntil) {
-        const sending = send([event], 1);
-        vercel?.waitUntil?.(sending);
-        return;
-      }
-      queue.push(event);
-      if (queue.length >= BATCH_MAX) flush();
-      else if (!timer) timer = setTimeout(flush, FLUSH_MS).unref();
-    });
-    next();
+    const handoffToken = handoffTokenOf(req);
+    if (!handoffToken) return record(journey);
+    // A handoff link: Track has to answer before the response, so the person's cookie can carry the agent's journey.
+    // The request's own event is still sent after the response, on the agent's journey with journey_source "issued":
+    // the key was given on this request, not read from it. Ingest takes "handoff" from no caller.
+    linkHandoff(handoffEventOf(req, occurredAt, journey, handoffToken)).then((agentJourney) => {
+      if (agentJourney) journey = { journey_id: agentJourney, journey_source: "issued" };
+      record(journey);
+    }).catch(next);
+
+    function record(journey) {
+      journeys.set(req, journey);
+      if (issueJourneyKeys) setJourneyKey(res, journey.journey_id);
+      res.on("finish", () => {
+        // An exception here would be thrown outside the request, so it is logged instead: the event is lost, the
+        // server is not.
+        let event;
+        try {
+          event = eventOf(req, res, occurredAt, journey);
+        } catch (err) {
+          // The path only: the query string can hold an API key, a journey key or a handoff token, 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) {
+          const sending = send([event], 1);
+          vercel?.waitUntil?.(sending);
+          return;
+        }
+        queue.push(event);
+        if (queue.length >= BATCH_MAX) flush();
+        else if (!timer) timer = setTimeout(flush, FLUSH_MS).unref();
+      });
+      next();
+    }
   }
   agentTrafficMiddleware.recordOutcome = recordOutcome;
+  agentTrafficMiddleware.handoffUrl = handoffUrl;
+  agentTrafficMiddleware.journeyIdOf = journeyIdOf;
   return agentTrafficMiddleware;
 
   function eventOf(req, res, occurredAt, journey) {
@@ -289,6 +408,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,
@@ -300,6 +420,24 @@ function agentTraffic({ accountIdOf, errorOf, key, projectId, salt, endpoint, is
       properties: { status_code: res.statusCode, method: req.method, ...(typeof error === "string" && error !== "" ? { error: error.slice(0, ERROR_MAX) } : {}) },
     };
   }
+
+  // The event that carries a handoff token, sent before the response, so it has no status code and no account yet:
+  // the person's sign-in comes on their later requests.
+  function handoffEventOf(req, occurredAt, journey, handoffToken) {
+    return {
+      idempotency_key: randomUUID(),
+      name: "handoff_opened",
+      path: requestPath(req),
+      occurred_at: occurredAt,
+      source: "sdk",
+      user_agent: req.headers["user-agent"],
+      accept_language: req.headers["accept-language"],
+      signature_agent: req.headers["signature-agent"],
+      ...journey,
+      handoff_token: handoffToken,
+      properties: { method: req.method },
+    };
+  }
 }
 
-module.exports = { eventName, agentTraffic, signatureMaterial, JOURNEY_HEADER };
+module.exports = { eventName, agentTraffic, signatureMaterial, JOURNEY_HEADER, HANDOFF_PARAM };