@katrinalaszlo/track 0.6.0 → 0.7.1

package/README.md

@@ -1,13 +1,13 @@
-# Agent traffic: install skill
+# Track: install skill
 
-[Agent traffic](https://alg.katrinalaszlo.com) shows which AI agents call your API, how their sessions go, and which errors end them. This repo is everything that runs on your side: an agent skill that installs it, the Express middleware it adds, and the script that checks the install.
+[Track](https://alg.katrinalaszlo.com) shows which AI agents call your API, how their sessions go, and which errors end them. This repo is everything that runs on your side: an agent skill that installs it, the Express middleware it adds, and the script that checks the install.
 
 ## Install with a coding agent
 
 Give your agent (Claude Code, Cursor, Codex) this prompt:
 
 ```
-Add agent traffic to this API: read https://alg.katrinalaszlo.com/SKILL.md and follow it.
+Add Track to this API: read https://alg.katrinalaszlo.com/SKILL.md and follow it.
 ```
 
 Or add the skill to your agent first:
@@ -29,9 +29,18 @@ 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. No account yet? This creates a free workspace and appends its key to `.env` without printing it (the first line adds a final newline to a `.env` that lacks one):
 
-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.
+```sh
+if [ -s .env ] && [ -n "$(tail -c 1 .env)" ]; then echo >> .env; fi
+curl -fsS -X POST "https://alg.katrinalaszlo.com/v1/signup?format=env" -H "Content-Type: application/json" -d '{"label":"my api","scopes":["read","write"]}' >> .env
+```
+
+Already have an account? Create a key on the Install page of your dashboard, or run `npx agent-led-growth connect`, which opens your browser to sign in and writes the key to `.env` for you. The full install steps are in [SKILL.md](https://github.com/katrinalaszlo/track-skill/blob/main/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, 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,6 +54,24 @@ 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
@@ -57,6 +84,8 @@ What each event contains, and the raw HTTP API for other stacks: [alg.katrinalas
 
 ## Tests
 
+From a clone of [katrinalaszlo/track-skill](https://github.com/katrinalaszlo/track-skill) (the npm package ships only the middleware and its types):
+
 ```sh
 npm test
 ```

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,12 +61,21 @@ 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;
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@katrinalaszlo/track",
-  "version": "0.6.0",
+  "version": "0.7.1",
   "description": "Express middleware that shows which AI agents call your API, how their sessions go, and which errors end them.",
   "license": "MIT",
   "type": "module",
@@ -8,7 +8,10 @@
     "type": "git",
     "url": "git+https://github.com/katrinalaszlo/track-skill.git"
   },
-  "homepage": "https://traffic.katrinalaszlo.com/docs",
+  "homepage": "https://alg.katrinalaszlo.com/docs",
+  "bugs": {
+    "url": "https://github.com/katrinalaszlo/track-skill/issues"
+  },
   "keywords": [
     "ai-agents",
     "express",

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,6 +37,12 @@ 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"];
@@ -154,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) {
@@ -170,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();
@@ -203,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.6.0). Upgrade the host, or pin @katrinalaszlo/track to 0.5.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;
@@ -262,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 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) {
-        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) {
@@ -314,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 };