highseat 0.5.0 → 0.7.0

package/README.md

@@ -13,10 +13,11 @@ npm install highseat
 | Import | Contents | Needs |
 | --- | --- | --- |
 | `highseat` | `track()`, `identify()`, `getAttributionId()`, `inject()` and `setBeforeSend()` | Nothing |
-| `highseat/react` | `<Highseat />`, `useIdentify()` and `useBeforeSend()` | React |
-| `highseat/next` | `<Highseat />`, `useIdentify()`, `useBeforeSend()`, `createProxy()` and `withHighseat()` for Next.js | Next.js |
+| `highseat/react` | `<Highseat />`, `<Embed />`, `useIdentify()` and `useBeforeSend()` | React |
+| `highseat/next` | `<Highseat />`, `<Embed />`, `useIdentify()`, `useBeforeSend()`, `createProxy()` and `withHighseat()` for Next.js | Next.js |
 | `highseat/proxy` | `createProxy()`, a first-party proxy for any runtime with `fetch` | Nothing |
 | `highseat/server` | `track()`, `flush()`, `close()` and `createTracker()`, for events sent from your backend | Nothing |
+| `highseat/mcp` | `trackToolCalls()` and `mcpLink()`, for the tool calls AI assistants make to your MCP server | The MCP TypeScript SDK v2 |
 
 Each entry point loads on its own and imports no framework it does not name, so `highseat/proxy` and `highseat/server` run in a Cloudflare Worker without React installed.
 
@@ -95,6 +96,47 @@ A site without a bundler, or a website builder such as Webflow or Shopify, needs
 <script defer src="https://cdn.highseat.com/script.js" data-site="site_…"></script>
 ```
 
+## Embeds
+
+`<Embed />` shows a share link or a widget on your page. Its `token` is the last part of the `/share/` address in the embed code, and `title` names the frame for screen readers. It needs no script tag: the component fits the frame to the embed and follows it as it resizes.
+
+Pass your page's theme when the page has its own switch, so the frame's colours match the page:
+
+```tsx
+"use client"
+
+import { Embed } from "highseat/react"
+import { useTheme } from "next-themes"
+
+export function VisitorsChart() {
+  const { resolvedTheme } = useTheme()
+
+  return (
+    <Embed
+      token="YOUR_WIDGET_TOKEN"
+      title="Visitors in the last 30 days"
+      widget="chart"
+      theme={resolvedTheme === "dark" ? "dark" : "light"}
+    />
+  )
+}
+```
+
+The server renders an empty box at the frame's height, and the frame replaces it after mount. So a theme known only in the browser needs no mounted check of your own and causes no hydration mismatch. If the theme is still unknown after mount, pass `theme={null}`: the box stays empty until you pass a theme, and the frame loads once. Leave `theme` out to follow the reader's own light or dark setting.
+
+| Prop | Default | Does |
+| --- | --- | --- |
+| `token` | Required | The share link or widget to show |
+| `title` | Required | The frame's accessible name |
+| `theme` | `"system"` | `"system"`, `"light"`, `"dark"`, or `null` while your page's theme is unknown |
+| `widget` | None, for a whole board | `"chart"` or `"figure"`, which sets the height held before the frame loads: 360px, 80px, or 1600px for a board |
+| `background` | `"transparent"` for a widget, otherwise `"default"` | `"transparent"` lets your page's background show through |
+| `height` | Set by `widget` | The height in pixels to hold until the embed reports its own |
+| `credit` | `true` | Shows the "Analytics by Highseat" link under the frame |
+| `creditClassName` | None | A class for the credit link, which replaces its default spacing and size |
+
+`className` and `style` go to the box around the frame and the credit link. Other attributes, such as `id` or `loading`, go to the frame. The credit link is a plain, followed link in the server's HTML, and it is yours to remove: pass `credit={false}`.
+
 ## Debugging
 
 In development, the package logs every `track()` and `identify()` call to the console, with its properties or id, and says whether the call went to the tracker or waits in the queue for it to load. It also warns once per page when nothing can reach Highseat: the page has no tracker script, or the script failed to load, as one an ad blocker stopped does.
@@ -328,6 +370,48 @@ Each event takes `request` or `headers`, then `ip`, `userAgent`, `userId`, `host
 
 Any language can send the same request. `POST https://cdn.highseat.com/api/event` with `x-site-id` and `x-hs-secret` headers and a JSON array of up to 25 events. Each event names `event_name`, `hostname` (or a `page_url`), and optionally `event_id`, `user_id`, `ip`, `user_agent`, `page_url`, `referrer`, `properties` (string values) and `revenue`. The answer lists each refused event in `rejections` and each event it did not store in `dropped`, by its index in the batch.
 
+## MCP tool calls
+
+`highseat/mcp` records each call an AI assistant (Claude, ChatGPT, Cursor and others) makes to a tool on your MCP server, built with the MCP TypeScript SDK v2. It sends through `highseat/server`, so set `HIGHSEAT_SITE` and `HIGHSEAT_SECRET` on the server as above. Call `trackToolCalls()` once, after creating the server and before registering any tool:
+
+```ts
+import { McpServer } from "@modelcontextprotocol/server"
+import { mcpLink, trackToolCalls } from "highseat/mcp"
+import { z } from "zod"
+
+const server = new McpServer({ name: "Acme", version: "1.0.0" })
+trackToolCalls(server, { hostname: "acme.com" })
+
+server.registerTool(
+  "get_product",
+  {
+    description: "One product, by its slug.",
+    inputSchema: z.object({ slug: z.string() }),
+    annotations: { readOnlyHint: true },
+  },
+  async ({ slug }, context) => ({
+    content: [{ type: "text", text: mcpLink(`https://acme.com/products/${slug}`, context) }],
+  }),
+)
+```
+
+Each call sends one `mcp_tool_call` event with these properties:
+
+| Property | |
+| --- | --- |
+| `tool` | The tool's name. |
+| `server` | The `server` option, a label such as `public` or `admin` for a site with more than one MCP server. |
+| `client` | The name the client declares in `clientInfo`, else the product name its User-Agent starts with, such as `Claude-User`, else `unknown`. |
+| `client_version` | The version the client declares, when it declares one. |
+| `client_source` | `client_info`, `user_agent` or `none`: how `client` was found. |
+| `status` | `ok`, or the error code the client saw: the `code` of a thrown error, the `CODE:` an error result's text starts with, else `TOOL_ERROR` or `INTERNAL_SERVER_ERROR`. |
+| `results` | How many items a read-only tool returned, when its result is a list, or an object holding exactly one list. |
+| `duration_ms` | How long the call took, in whole milliseconds. |
+
+It never sends the tool's arguments, its result, the caller's IP or its user agent, and it never reads ChatGPT's user or conversation ids. Assistant directories forbid collecting conversation data, and every call comes from the assistant's servers rather than from a person, so a tool call counts as an event, never as a visitor. Highseat accepts `mcp_tool_call` only from a server holding the site secret.
+
+`mcpLink(url, context)` tags a link a tool returns with `utm_source` set to the client and `utm_medium=mcp`, so a visit it brings reads as that assistant in the AI channel. A link that already names a `utm_source` is returned as it is. Pass `waitUntil` to `trackToolCalls()` in a serverless function, and `tracker` to send with a tracker from `createTracker()`.
+
 ## First-party proxy
 
 The proxy serves the tracker and forwards its events from your own domain, on the site's own path, so a filter list that blocks Highseat's host does not block your site. A `GET` on the path serves the script and a `POST` forwards events. The proxy sends the visitor's IP under your site secret, which a rewrite or a redirect rule cannot do: without it, every visitor would get your server's country.
@@ -357,7 +441,7 @@ To rotate the path, rotate it in Installation settings, update `HIGHSEAT_PATH` a
 | --- | --- | --- |
 | `clientIp` | Required | Where the visitor's IP comes from: `"vercel"`, `"cloudflare"`, `"netlify"`, `"nginx"` (the `X-Real-IP` header your nginx sets), or a function `(request) => string`. The outermost proxy that sets the header decides the preset: behind a proxied Cloudflare record, use `"cloudflare"` on any origin (Next.js, TanStack Start, a Node server, with or without Traefik or nginx in between), whose `X-Real-IP` holds a Cloudflare edge address. A visitor can write any header the host does not overwrite, so there is no default and no fallback to `X-Forwarded-For`. |
 | `path` | `HIGHSEAT_PATH` | The proxy path. Any other path answers 404, or goes to `fallback`. Leave it unset where your router already sends only the proxy path to the handler. |
-| `secret` | `HIGHSEAT_SECRET` | The site secret. An older secret that starts `hs_proxy_` or `ana_proxy_` works too. A value with neither prefix throws. |
+| `secret` | `HIGHSEAT_SECRET` | The site secret. A value that does not start with `hs_secret_` throws. |
 | `upstream` | `https://cdn.highseat.com` | The Highseat ingest origin. |
 | `fallback` | None | Answers every other path, for a handler that sees every request on the site. Needs `path`. |
 

package/embed.d.ts

@@ -0,0 +1,15 @@
+//#region src/embed.d.ts
+/**
+ * What `<Embed />` knows about a Highseat embed frame: its URL, its message and the credit link.
+ * The dashboard's own copy lives in the monorepo, which this package cannot import because it
+ * builds alone in the public mirror. `scripts/embed-mirror.test.ts` at the monorepo's root fails
+ * when the two differ.
+ */
+/** The theme of an embed: `system` follows the reader's own light or dark setting. */
+export type EmbedTheme = "system" | "light" | "dark";
+/** The background of an embed: `transparent` lets the host page's own show through. */
+export type EmbedBackground = "default" | "transparent";
+/** The kind of widget a token shows. */
+export type EmbedWidget = "chart" | "figure";
+//#endregion
+//# sourceMappingURL=embed.d.ts.map

package/embed.js

@@ -0,0 +1,49 @@
+//#region src/embed.ts
+/** The origin that serves every embed page, and so the only one a resize message can come from. */
+const EMBED_ORIGIN = "https://app.highseat.com";
+/** The `type` of the message an embed posts to its parent whenever its height changes. */
+const EMBED_RESIZE_MESSAGE = "highseat:embed-resize";
+/** The height of a whole board's frame before the board reports its own. */
+const EMBED_FALLBACK_HEIGHT = 1600;
+/** The height of a widget's frame before the widget reports its own, close to its usual one. */
+const WIDGET_FALLBACK_HEIGHTS = {
+	figure: 80,
+	chart: 360
+};
+/** Where the link under an embed goes, tagged so the visits it sends are attributed. */
+const EMBED_CREDIT_URL = "https://highseat.com/?ref=embed";
+/** The text of the link under an embed. */
+const EMBED_CREDIT_TEXT = "Analytics by Highseat";
+/** An embeddable page's URL with the keys that frame it: `embed=1` and the chosen look. */
+function formatEmbedUrl(pageUrl, { theme, background }) {
+	const params = new URLSearchParams({ embed: "1" });
+	if (theme !== "system") params.set("theme", theme);
+	if (background !== "default") params.set("background", background);
+	return `${pageUrl}?${params}`;
+}
+/** The URL of the embed page a token opens. */
+function formatEmbedSrc(token, look) {
+	return formatEmbedUrl(`${EMBED_ORIGIN}/share/${encodeURIComponent(token)}`, look);
+}
+/**
+* The colour scheme a see-through frame declares. A browser paints an opaque backdrop behind a
+* frame whose scheme differs from the frame element's, so the element takes the page's scheme.
+*/
+function getFrameColorScheme(theme) {
+	return theme === "system" ? "light dark" : theme;
+}
+/**
+* The height a message asks `frameWindow` to take, rounded up. Any page or frame can post to the
+* host page, so a message counts only from the embed origin and from that exact frame. Without
+* the source check, a second embed on the page would resize this one.
+*/
+function findEmbedHeight({ data, origin, source }, frameWindow) {
+	if (origin !== "https://app.highseat.com" || !frameWindow || source !== frameWindow) return;
+	if (data?.type !== "highseat:embed-resize") return;
+	if (!Number.isFinite(data.height) || data.height <= 0) return;
+	return Math.ceil(data.height);
+}
+//#endregion
+export { EMBED_CREDIT_TEXT, EMBED_CREDIT_URL, EMBED_FALLBACK_HEIGHT, EMBED_ORIGIN, EMBED_RESIZE_MESSAGE, WIDGET_FALLBACK_HEIGHTS, findEmbedHeight, formatEmbedSrc, formatEmbedUrl, getFrameColorScheme };
+
+//# sourceMappingURL=embed.js.map

package/embed.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"embed.js","names":[],"sources":["../src/embed.ts"],"sourcesContent":["/**\n * What `<Embed />` knows about a Highseat embed frame: its URL, its message and the credit link.\n * The dashboard's own copy lives in the monorepo, which this package cannot import because it\n * builds alone in the public mirror. `scripts/embed-mirror.test.ts` at the monorepo's root fails\n * when the two differ.\n */\n\n/** The theme of an embed: `system` follows the reader's own light or dark setting. */\nexport type EmbedTheme = \"system\" | \"light\" | \"dark\"\n\n/** The background of an embed: `transparent` lets the host page's own show through. */\nexport type EmbedBackground = \"default\" | \"transparent\"\n\n/** The kind of widget a token shows. */\nexport type EmbedWidget = \"chart\" | \"figure\"\n\ninterface EmbedLook {\n  theme: EmbedTheme\n  background: EmbedBackground\n}\n\n/** The part of a `MessageEvent` a resize message is judged on. */\ntype FrameMessage = Pick<MessageEvent, \"data\" | \"origin\" | \"source\">\n\n/** The origin that serves every embed page, and so the only one a resize message can come from. */\nexport const EMBED_ORIGIN = \"https://app.highseat.com\"\n\n/** The `type` of the message an embed posts to its parent whenever its height changes. */\nexport const EMBED_RESIZE_MESSAGE = \"highseat:embed-resize\"\n\n/** The height of a whole board's frame before the board reports its own. */\nexport const EMBED_FALLBACK_HEIGHT = 1600\n\n/** The height of a widget's frame before the widget reports its own, close to its usual one. */\nexport const WIDGET_FALLBACK_HEIGHTS: Record<EmbedWidget, number> = {\n  figure: 80,\n  chart: 360,\n}\n\n/** Where the link under an embed goes, tagged so the visits it sends are attributed. */\nexport const EMBED_CREDIT_URL = \"https://highseat.com/?ref=embed\"\n\n/** The text of the link under an embed. */\nexport const EMBED_CREDIT_TEXT = \"Analytics by Highseat\"\n\n/** An embeddable page's URL with the keys that frame it: `embed=1` and the chosen look. */\nexport function formatEmbedUrl(pageUrl: string, { theme, background }: EmbedLook): string {\n  const params = new URLSearchParams({ embed: \"1\" })\n  if (theme !== \"system\") params.set(\"theme\", theme)\n  if (background !== \"default\") params.set(\"background\", background)\n  return `${pageUrl}?${params}`\n}\n\n/** The URL of the embed page a token opens. */\nexport function formatEmbedSrc(token: string, look: EmbedLook): string {\n  return formatEmbedUrl(`${EMBED_ORIGIN}/share/${encodeURIComponent(token)}`, look)\n}\n\n/**\n * The colour scheme a see-through frame declares. A browser paints an opaque backdrop behind a\n * frame whose scheme differs from the frame element's, so the element takes the page's scheme.\n */\nexport function getFrameColorScheme(theme: EmbedTheme): string {\n  return theme === \"system\" ? \"light dark\" : theme\n}\n\n/**\n * The height a message asks `frameWindow` to take, rounded up. Any page or frame can post to the\n * host page, so a message counts only from the embed origin and from that exact frame. Without\n * the source check, a second embed on the page would resize this one.\n */\nexport function findEmbedHeight(\n  { data, origin, source }: FrameMessage,\n  frameWindow: Window | null | undefined,\n): number | undefined {\n  if (origin !== EMBED_ORIGIN || !frameWindow || source !== frameWindow) return\n  if (data?.type !== EMBED_RESIZE_MESSAGE) return\n  if (!Number.isFinite(data.height) || data.height <= 0) return\n  return Math.ceil(data.height)\n}\n"],"mappings":";;AAyBA,MAAa,eAAe;;AAG5B,MAAa,uBAAuB;;AAGpC,MAAa,wBAAwB;;AAGrC,MAAa,0BAAuD;CAClE,QAAQ;CACR,OAAO;AACT;;AAGA,MAAa,mBAAmB;;AAGhC,MAAa,oBAAoB;;AAGjC,SAAgB,eAAe,SAAiB,EAAE,OAAO,cAAiC;CACxF,MAAM,SAAS,IAAI,gBAAgB,EAAE,OAAO,IAAI,CAAC;CACjD,IAAI,UAAU,UAAU,OAAO,IAAI,SAAS,KAAK;CACjD,IAAI,eAAe,WAAW,OAAO,IAAI,cAAc,UAAU;CACjE,OAAO,GAAG,QAAQ,GAAG;AACvB;;AAGA,SAAgB,eAAe,OAAe,MAAyB;CACrE,OAAO,eAAe,GAAG,aAAa,SAAS,mBAAmB,KAAK,KAAK,IAAI;AAClF;;;;;AAMA,SAAgB,oBAAoB,OAA2B;CAC7D,OAAO,UAAU,WAAW,eAAe;AAC7C;;;;;;AAOA,SAAgB,gBACd,EAAE,MAAM,QAAQ,UAChB,aACoB;CACpB,IAAI,WAAA,8BAA2B,CAAC,eAAe,WAAW,aAAa;CACvE,IAAI,MAAM,SAAA,yBAA+B;CACzC,IAAI,CAAC,OAAO,SAAS,KAAK,MAAM,KAAK,KAAK,UAAU,GAAG;CACvD,OAAO,KAAK,KAAK,KAAK,MAAM;AAC9B"}

package/index.d.ts

@@ -81,23 +81,33 @@ type CheckedProperties<Shape> = [keyof Shape] extends [never] ? Record<string, n
 type RegisteredEvents = Register extends {
   events: infer Registered;
 } ? { [Name in keyof Registered]: CheckedProperties<Registered[Name]>; } : {};
-type KnownEvents = Omit<BuiltInEvents, keyof RegisteredEvents> & RegisteredEvents;
+type KnownEvents<BuiltIns> = Omit<BuiltIns, keyof RegisteredEvents> & RegisteredEvents;
+/**
+ * The event names a `track` with the given built-in events knows, built-in or registered.
+ * `highseat/server` passes its server-only events on top of {@link BuiltInEvents}.
+ */
+export type KnownEventName<BuiltIns> = Extract<keyof KnownEvents<BuiltIns>, string>;
 /** Every event name `track` knows, built-in or registered. */
-export type EventName = Extract<keyof KnownEvents, string>;
+export type EventName = KnownEventName<BuiltInEvents>;
 /**
- * The names `track` accepts: known names, and any other string unless the site is strict.
- * `string & {}` keeps the known names in the editor's suggestions, which a plain `string` in the
- * union would absorb.
+ * The names a `track` with the given built-in events accepts: known names, and any other string
+ * unless the site is strict. `string & {}` keeps the known names in the editor's suggestions,
+ * which a plain `string` in the union would absorb.
  */
-export type TrackName = Register extends {
+export type TrackNameOf<BuiltIns> = Register extends {
   strict: true;
-} ? EventName : EventName | (string & {});
+} ? KnownEventName<BuiltIns> : KnownEventName<BuiltIns> | (string & {});
+/** The names `track` accepts: known names, and any other string unless the site is strict. */
+export type TrackName = TrackNameOf<BuiltInEvents>;
 /**
- * The arguments after an event's name. A known name takes its declared properties, required
- * when any of them is; any other name takes {@link Properties}. Wrapped in tuples so a union of
- * names is checked as a whole rather than name by name.
+ * The arguments after an event's name, for a `track` with the given built-in events. A known
+ * name takes its declared properties, required when any of them is; any other name takes
+ * {@link Properties}. Wrapped in tuples so a union of names is checked as a whole rather than
+ * name by name.
  */
-export type TrackArgs<Name extends string> = [Name] extends [EventName] ? {} extends KnownEvents[Name] ? [properties?: KnownEvents[Name]] : [properties: KnownEvents[Name]] : [properties?: Properties];
+export type TrackArgsOf<BuiltIns, Name extends string> = [Name] extends [KnownEventName<BuiltIns>] ? {} extends KnownEvents<BuiltIns>[Name] ? [properties?: KnownEvents<BuiltIns>[Name]] : [properties: KnownEvents<BuiltIns>[Name]] : [properties?: Properties];
+/** The arguments after an event's name: its properties. See {@link TrackArgsOf}. */
+export type TrackArgs<Name extends string> = TrackArgsOf<BuiltInEvents, Name>;
 /**
  * A user id from your own system, as {@link identify} takes it. A string or a number identifies
  * the visitor, `null` clears the id, and `undefined` or an empty string changes nothing. Pass your
@@ -182,8 +192,6 @@ declare global {
     highseat?: HighseatGlobal;
   }
 }
-/** Where the tracker loads from when the site has no proxy path. */
-export declare const SCRIPT_URL = "https://cdn.highseat.com/script.js";
 /**
  * Records an event. A known name autocompletes and checks its properties; any other name is a
  * custom event, unless {@link Register} sets `strict`. Names are stored exactly as written, so

package/index.js

@@ -177,6 +177,6 @@ function inject(options) {
 	document.head.append(script);
 }
 //#endregion
-export { SCRIPT_URL, getAttributionId, identify, inject, setBeforeSend, track };
+export { getAttributionId, identify, inject, setBeforeSend, track };
 
 //# sourceMappingURL=index.js.map

package/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","names":[],"sources":["../src/index.ts"],"sourcesContent":["import { isDevelopment } from \"./env\"\n\n/**\n * The browser client. Every call goes to the hosted tracker on `window.highseat`; before the\n * tracker has loaded, calls wait in a queue the tracker drains on startup. Nothing here throws:\n * on a server, with the tracker blocked, or with tracking off, a call does nothing.\n */\n\n/** A value an event property can hold. A `null` or `undefined` value is left out of the event. */\nexport type PropertyValue = string | number | boolean | null | undefined\n\n/**\n * Money attached to an event. `amount` is an integer in the currency's smallest unit, so\n * `{ amount: 4999, currency: \"USD\" }` is $49.99 and `{ amount: 5000, currency: \"JPY\" }` is ¥5000.\n */\nexport interface Revenue {\n  /** An integer in minor units: 4999 for $49.99. An amount with decimals is rejected. */\n  amount: number\n  /** An ISO 4217 code, such as `USD` or `EUR`. */\n  currency: string\n}\n\n/** The properties of an event with no declared shape: any string keys, plus optional revenue. */\nexport interface Properties {\n  /** Money the event brought in. */\n  revenue?: Revenue\n  [key: string]: PropertyValue | Revenue\n}\n\n/**\n * The events Highseat knows by name. A site extends it, or overrides an entry, through\n * {@link Register}. Type-only: it adds nothing to the bundle.\n */\nexport interface BuiltInEvents {\n  /** A visitor created an account. */\n  signup: Properties\n  /** A visitor signed in. */\n  login: Properties\n  /**\n   * A sale. With a payment provider connected, leave `revenue` out: the provider's webhook\n   * records the money, and revenue sent here as well would count the sale twice. Send `revenue`\n   * only for a checkout no provider reports, and then with an `order_id`, so a provider sale\n   * added later for the same order is not counted again.\n   */\n  purchase: Properties\n  /** A paid subscription began. */\n  subscription_started: Properties\n  /** A free trial began. */\n  trial_started: Properties\n  /** A file download. The tracker records links to files on its own. */\n  file_download: { url: string }\n  /** A click on a link to another site. The tracker records these on its own. */\n  outbound_link_click: { url: string }\n  /** A visit to a missing page. Call it from a single-page app's not-found route. */\n  \"404\": Properties\n}\n\n/**\n * Declares a site's own events. Augment it from any file the compiler sees:\n *\n * ```ts\n * declare module \"highseat\" {\n *   interface Register {\n *     events: {\n *       signup: { plan: \"free\" | \"pro\" }\n *     }\n *     strict: true\n *   }\n * }\n * ```\n *\n * `events` adds names, or replaces a built-in one's properties. `strict: true` makes `track`\n * accept only built-in and registered names, so a misspelt name is a type error.\n */\nexport interface Register {}\n\n/**\n * A registered event's properties as `track` accepts them. A shape with no properties takes none,\n * and a property whose type an event cannot carry becomes `never`, so a call passing it fails\n * instead of sending `\"[object Object]\"`. The shape is not rejected at registration, where a\n * failed check would silently drop every registered event at once.\n */\ntype CheckedProperties<Shape> = [keyof Shape] extends [never]\n  ? Record<string, never>\n  : { [Key in keyof Shape]: Shape[Key] extends PropertyValue | Revenue ? Shape[Key] : never }\n\ntype RegisteredEvents = Register extends { events: infer Registered }\n  ? { [Name in keyof Registered]: CheckedProperties<Registered[Name]> }\n  : {}\n\ntype KnownEvents = Omit<BuiltInEvents, keyof RegisteredEvents> & RegisteredEvents\n\n/** Every event name `track` knows, built-in or registered. */\nexport type EventName = Extract<keyof KnownEvents, string>\n\n/**\n * The names `track` accepts: known names, and any other string unless the site is strict.\n * `string & {}` keeps the known names in the editor's suggestions, which a plain `string` in the\n * union would absorb.\n */\nexport type TrackName = Register extends { strict: true } ? EventName : EventName | (string & {})\n\n/**\n * The arguments after an event's name. A known name takes its declared properties, required\n * when any of them is; any other name takes {@link Properties}. Wrapped in tuples so a union of\n * names is checked as a whole rather than name by name.\n */\nexport type TrackArgs<Name extends string> = [Name] extends [EventName]\n  ? {} extends KnownEvents[Name]\n    ? [properties?: KnownEvents[Name]]\n    : [properties: KnownEvents[Name]]\n  : [properties?: Properties]\n\n/**\n * A user id from your own system, as {@link identify} takes it. A string or a number identifies\n * the visitor, `null` clears the id, and `undefined` or an empty string changes nothing. Pass your\n * own database id, never an email or other personal data.\n */\nexport type UserId = string | number | null | undefined\n\n/**\n * The part of an event {@link BeforeSend} sees and may change. The site, the visitor's user id\n * and the attribution id are out of reach, so a hook cannot change who an event belongs to.\n */\nexport interface BeforeSendEvent {\n  /** The event's name: `pageview`, `engagement`, or a name passed to `track`. Read-only. */\n  readonly name: string\n  /** The page's full URL. The page path is read off the URL you return. */\n  url: string\n  /** The page the visitor came from, or the page left on a client-side navigation. */\n  referrer?: string\n  /** The event's properties, each value a string. */\n  properties?: Record<string, string>\n}\n\n/**\n * Runs in the browser on every event before the tracker sends it, page views from client-side\n * navigation included. Return the event, changed or not, or `null` to drop it. Any other falsy\n * answer drops it too, and so does a hook that throws: a hook that keeps a secret out of the\n * data must not leak it when it fails. The error still reaches the console.\n *\n * ```ts\n * function beforeSend(event: BeforeSendEvent) {\n *   const url = new URL(event.url)\n *   if (url.pathname.startsWith(\"/admin/\")) return null\n *   url.searchParams.delete(\"email\")\n *   return { ...event, url: url.href }\n * }\n * ```\n */\nexport type BeforeSend = (event: BeforeSendEvent) => BeforeSendEvent | null\n\n/** The tracker's API on `window.highseat`, or the queue that stands in for it until it loads. */\nexport interface HighseatGlobal {\n  /** Records an event. */\n  track?: (name: string, properties?: Properties) => void\n  /** Sets or clears the visitor's user id. */\n  identify?: (id: UserId) => void\n  /** The id that joins a payment to this tab's visit. */\n  getAttributionId?: () => string | undefined\n  /** Calls made before the tracker loaded, drained in order when it starts. */\n  q?: [string, unknown[]][]\n  /** The site's {@link BeforeSend} hook, read on every event. */\n  beforeSend?: BeforeSend\n}\n\n/** How long {@link getAttributionId} waits for the tracker. */\nexport interface AttributionOptions {\n  /** Milliseconds to wait for the tracker to load. Defaults to 3000. */\n  timeout?: number\n}\n\n/** How the tracker is loaded. Each option maps to an attribute on its script tag. */\nexport interface InjectOptions {\n  /** The site id, `site_…`, from the site's Installation settings. */\n  site: string\n  /**\n   * Where the script loads from: the site's proxy path (`/3f9a0c1e2b`) for first-party\n   * delivery, or a full URL. Defaults to Highseat's own host. The tracker posts its events back\n   * to the same place.\n   */\n  src?: string\n  /** Records clicks on links to other sites as `outbound_link_click`. Defaults to `true`. */\n  outbound?: boolean\n  /** Records clicks on links to files as `file_download`. Defaults to `true`. */\n  downloads?: boolean\n  /** Counts a change of `#/route` as a page view, for an app that routes by hash. */\n  hashRouting?: boolean\n  /** Changes or drops each event before it leaves the browser. See {@link BeforeSend}. */\n  beforeSend?: BeforeSend\n  /**\n   * Logs every `track()` and `identify()` call to the console, and warns once when no tracker\n   * script is on the page or the script failed to load. Defaults to `true` when\n   * `process.env.NODE_ENV` is `development`, so a production build logs nothing.\n   */\n  debug?: boolean\n}\n\ndeclare global {\n  interface Window {\n    highseat?: HighseatGlobal\n  }\n}\n\n/** Where the tracker loads from when the site has no proxy path. */\nexport const SCRIPT_URL = \"https://cdn.highseat.com/script.js\"\n\n// The tracker marks its own API with this symbol. A site's own stub can define methods too, so\n// only the symbol proves the tracker is running.\nconst LIVE = Symbol.for(\"highseat\")\n\nconst SCRIPT_HOST = new URL(SCRIPT_URL).host\n// A site's proxy path: `/` and ten hex characters.\nconst PROXY_PATH = /^\\/[0-9a-f]{10}$/\n\nconst TRACKER_TIMEOUT = 3000\nconst TRACKER_POLL_INTERVAL = 50\n\nconst MISSING_SCRIPT_WARNING = [\n  \"highseat: no tracker script on this page, so no event reaches Highseat.\",\n  \"Render <Highseat />, call inject({ site }), or add the script tag from the site's Installation settings.\",\n].join(\" \")\nconst FAILED_SCRIPT_WARNING = [\n  \"highseat: the tracker script failed to load, so no event reaches Highseat.\",\n  \"An ad blocker may have stopped it: load the tracker from the site's proxy path instead.\",\n].join(\" \")\nconst SLOW_SCRIPT_WARNING = [\n  `highseat: the tracker script has not loaded after ${TRACKER_TIMEOUT / 1000} seconds,`,\n  \"so every call waits in the queue. Check the network panel for a blocked or failed request.\",\n].join(\" \")\n\n// The script tags `inject` added, and every tracker script whose request failed, such as one an\n// ad blocker stopped. A browser keeps no record of a failed script, so a failure is only known\n// to a listener attached before it happened.\nconst injectedScripts = new WeakSet<HTMLScriptElement>()\nconst failedScripts = new WeakSet<HTMLScriptElement>()\n\n// The `debug` option of the last `inject` call. Unset falls back to the build's environment.\nlet debugOption: boolean | undefined\n// The windows whose tracker is being watched, so a page warns about its script once.\nconst watchedWindows = new WeakSet<Window>()\n\nfunction findGlobal(): HighseatGlobal | undefined {\n  if (typeof window === \"undefined\") return\n  return (window.highseat ??= {})\n}\n\nfunction isLive(api: HighseatGlobal | undefined): api is HighseatGlobal {\n  return !!api && (api as Record<symbol, unknown>)[LIVE] === true\n}\n\n// One function for every script, so attaching it on each poll adds no second listener.\nfunction markFailed(event: Event) {\n  failedScripts.add(event.currentTarget as HTMLScriptElement)\n}\n\n/**\n * Whether a script tag loads the tracker, judged as the tracker judges itself. Fathom's snippet\n * carries a `data-site` too, so a tag is matched by a `site_` id, or by a `src` on a proxy path\n * or on Highseat's host: an older site's id is a UUID, which any tool could use.\n */\nfunction isTrackerScript(script: HTMLScriptElement) {\n  const { site } = script.dataset\n  if (injectedScripts.has(script) || site?.startsWith(\"site_\")) return true\n  if (site === undefined) return false\n\n  try {\n    // A browser hands back `src` resolved; the base only matters to a relative one.\n    const url = new URL(script.src, \"http://localhost\")\n    return url.host === SCRIPT_HOST || PROXY_PATH.test(url.pathname)\n  } catch {\n    return false\n  }\n}\n\n/** The page's tracker scripts, each one listened to from now on for a failed load. */\nfunction getTrackerScripts() {\n  const scripts = Array.from(document.scripts).filter(isTrackerScript)\n  for (const script of scripts) script.addEventListener(\"error\", markFailed)\n  return scripts\n}\n\nfunction isDebug() {\n  return debugOption ?? isDevelopment()\n}\n\n/**\n * Warns once per page when the tracker cannot arrive: no tracker script, or only failed ones. A\n * missing script is judged at the timeout, because `<Highseat />` adds its tag in an effect that\n * runs after the effects of the components inside it.\n */\nfunction watchTracker() {\n  if (typeof window === \"undefined\" || typeof document === \"undefined\") return\n  if (watchedWindows.has(window)) return\n  watchedWindows.add(window)\n\n  const page = window\n  const deadline = Date.now() + TRACKER_TIMEOUT\n\n  function check() {\n    // A replaced global window, as a test sets up for each case, is another page.\n    if (window !== page || isLive(page.highseat)) return\n\n    const scripts = getTrackerScripts()\n\n    if (scripts.length > 0 && scripts.every(script => failedScripts.has(script))) {\n      console.warn(FAILED_SCRIPT_WARNING)\n      return\n    }\n    if (Date.now() < deadline) {\n      setTimeout(check, TRACKER_POLL_INTERVAL)\n      return\n    }\n    console.warn(scripts.length === 0 ? MISSING_SCRIPT_WARNING : SLOW_SCRIPT_WARNING)\n  }\n\n  setTimeout(check, TRACKER_POLL_INTERVAL)\n}\n\n/**\n * Logs a call when debugging is on. The check waits a microtask, so a `debug` option that\n * `<Highseat />` passes in its effect applies to the calls its children make in theirs.\n */\nfunction logCall(method: \"track\" | \"identify\", args: unknown[], isQueued: boolean) {\n  queueMicrotask(() => {\n    if (!isDebug()) return\n\n    const status = isQueued ? \"queued until the tracker loads\" : \"sent to the tracker\"\n    const [value, properties] = args\n    // `JSON.stringify` quotes a name or a string id, and returns `undefined` for an unset id.\n    const message = `highseat: ${method} ${String(JSON.stringify(value))}, ${status}`\n\n    if (properties === undefined) console.info(message)\n    else console.info(message, properties)\n    watchTracker()\n  })\n}\n\nfunction call(method: \"track\" | \"identify\", args: unknown[]) {\n  const api = findGlobal()\n  if (!api) return\n\n  const handler = api[method] as ((...values: unknown[]) => void) | undefined\n  if (typeof handler !== \"function\") {\n    api.q ??= []\n    api.q.push([method, args])\n    logCall(method, args, true)\n    return\n  }\n\n  logCall(method, args, false)\n  try {\n    handler(...args)\n  } catch {}\n}\n\n/**\n * Records an event. A known name autocompletes and checks its properties; any other name is a\n * custom event, unless {@link Register} sets `strict`. Names are stored exactly as written, so\n * `Purchase` and `purchase` are two events.\n */\nexport function track<Name extends TrackName>(name: Name, ...args: TrackArgs<Name>): void {\n  const [properties] = args\n  call(\"track\", properties === undefined ? [name] : [name, properties])\n}\n\n/**\n * Links the visitor to a user id from your own system, on this event and every later one, across\n * visits. `null` clears it at sign-out. An empty or `undefined` id is ignored, so\n * `identify(user?.id)` before a session loads does not sign the visitor out.\n */\nexport function identify(id: UserId): void {\n  call(\"identify\", [id])\n}\n\n/**\n * The id that joins a payment to this tab's visit. Pass it to the checkout as metadata\n * (`attribution_id`), and the payment provider's webhook credits the sale to the visit's source.\n * Resolves to `undefined`, so a checkout that awaits it never hangs: at once when the page has\n * no tracker script or its script fails to load (an ad blocker stopping it), after the timeout\n * when the script is still loading, and on a server or with tracking off.\n */\nexport async function getAttributionId(\n  options: AttributionOptions = {},\n): Promise<string | undefined> {\n  if (typeof window === \"undefined\" || typeof document === \"undefined\") return\n\n  const deadline = Date.now() + (options.timeout ?? TRACKER_TIMEOUT)\n  let api = window.highseat\n\n  while (!isLive(api)) {\n    if (Date.now() >= deadline) return\n\n    const scripts = getTrackerScripts()\n    // No tracker script at all, or only failed ones: the tracker cannot arrive.\n    if (scripts.every(script => failedScripts.has(script))) return\n\n    await new Promise(resolve => setTimeout(resolve, TRACKER_POLL_INTERVAL))\n    api = window.highseat\n  }\n\n  try {\n    return api.getAttributionId?.()\n  } catch {\n    return\n  }\n}\n\n/**\n * Sets the {@link BeforeSend} hook, or clears it with `undefined`. Works before the tracker has\n * loaded, which picks the hook up when it starts, and applies from the next event once it runs.\n * Does nothing on a server.\n */\nexport function setBeforeSend(beforeSend: BeforeSend | undefined): void {\n  const api = findGlobal()\n  if (api) api.beforeSend = beforeSend\n}\n\n/**\n * Adds the tracker's script tag to the page, once. A second call for the same site, such as a\n * component mounting again, finds the tag and adds nothing, but its `debug` option still applies.\n * Does nothing on a server.\n */\nexport function inject(options: InjectOptions): void {\n  if (typeof document === \"undefined\") return\n\n  const { site, src = SCRIPT_URL, outbound, downloads, hashRouting, beforeSend, debug } = options\n  debugOption = debug\n  // Set before the script tag is added, so the first page view already passes through it.\n  if (beforeSend) setBeforeSend(beforeSend)\n  if (isDebug()) watchTracker()\n  if (Array.from(document.scripts).some(script => script.dataset.site === site)) return\n\n  const script = document.createElement(\"script\")\n  script.addEventListener(\"error\", markFailed)\n  injectedScripts.add(script)\n  script.src = src\n  script.dataset.site = site\n  if (outbound === false) script.dataset.outbound = \"false\"\n  if (downloads === false) script.dataset.downloads = \"false\"\n  if (hashRouting) script.dataset.hashRouting = \"\"\n  document.head.append(script)\n}\n"],"mappings":";;;AA6MA,MAAa,aAAa;AAI1B,MAAM,OAAO,OAAO,IAAI,UAAU;AAElC,MAAM,cAAc,IAAI,IAAI,UAAU,CAAC,CAAC;AAExC,MAAM,aAAa;AAEnB,MAAM,kBAAkB;AACxB,MAAM,wBAAwB;AAE9B,MAAM,yBAAyB,CAC7B,2EACA,0GACF,CAAC,CAAC,KAAK,GAAG;AACV,MAAM,wBAAwB,CAC5B,8EACA,yFACF,CAAC,CAAC,KAAK,GAAG;AACV,MAAM,sBAAsB,CAC1B,qDAAqD,kBAAkB,IAAK,YAC5E,4FACF,CAAC,CAAC,KAAK,GAAG;AAKV,MAAM,kCAAkB,IAAI,QAA2B;AACvD,MAAM,gCAAgB,IAAI,QAA2B;AAGrD,IAAI;AAEJ,MAAM,iCAAiB,IAAI,QAAgB;AAE3C,SAAS,aAAyC;CAChD,IAAI,OAAO,WAAW,aAAa;CACnC,OAAQ,OAAO,aAAa,CAAC;AAC/B;AAEA,SAAS,OAAO,KAAwD;CACtE,OAAO,CAAC,CAAC,OAAQ,IAAgC,UAAU;AAC7D;AAGA,SAAS,WAAW,OAAc;CAChC,cAAc,IAAI,MAAM,aAAkC;AAC5D;;;;;;AAOA,SAAS,gBAAgB,QAA2B;CAClD,MAAM,EAAE,SAAS,OAAO;CACxB,IAAI,gBAAgB,IAAI,MAAM,KAAK,MAAM,WAAW,OAAO,GAAG,OAAO;CACrE,IAAI,SAAS,KAAA,GAAW,OAAO;CAE/B,IAAI;EAEF,MAAM,MAAM,IAAI,IAAI,OAAO,KAAK,kBAAkB;EAClD,OAAO,IAAI,SAAS,eAAe,WAAW,KAAK,IAAI,QAAQ;CACjE,QAAQ;EACN,OAAO;CACT;AACF;;AAGA,SAAS,oBAAoB;CAC3B,MAAM,UAAU,MAAM,KAAK,SAAS,OAAO,CAAC,CAAC,OAAO,eAAe;CACnE,KAAK,MAAM,UAAU,SAAS,OAAO,iBAAiB,SAAS,UAAU;CACzE,OAAO;AACT;AAEA,SAAS,UAAU;CACjB,OAAO,eAAe,cAAc;AACtC;;;;;;AAOA,SAAS,eAAe;CACtB,IAAI,OAAO,WAAW,eAAe,OAAO,aAAa,aAAa;CACtE,IAAI,eAAe,IAAI,MAAM,GAAG;CAChC,eAAe,IAAI,MAAM;CAEzB,MAAM,OAAO;CACb,MAAM,WAAW,KAAK,IAAI,IAAI;CAE9B,SAAS,QAAQ;EAEf,IAAI,WAAW,QAAQ,OAAO,KAAK,QAAQ,GAAG;EAE9C,MAAM,UAAU,kBAAkB;EAElC,IAAI,QAAQ,SAAS,KAAK,QAAQ,OAAM,WAAU,cAAc,IAAI,MAAM,CAAC,GAAG;GAC5E,QAAQ,KAAK,qBAAqB;GAClC;EACF;EACA,IAAI,KAAK,IAAI,IAAI,UAAU;GACzB,WAAW,OAAO,qBAAqB;GACvC;EACF;EACA,QAAQ,KAAK,QAAQ,WAAW,IAAI,yBAAyB,mBAAmB;CAClF;CAEA,WAAW,OAAO,qBAAqB;AACzC;;;;;AAMA,SAAS,QAAQ,QAA8B,MAAiB,UAAmB;CACjF,qBAAqB;EACnB,IAAI,CAAC,QAAQ,GAAG;EAEhB,MAAM,SAAS,WAAW,mCAAmC;EAC7D,MAAM,CAAC,OAAO,cAAc;EAE5B,MAAM,UAAU,aAAa,OAAO,GAAG,OAAO,KAAK,UAAU,KAAK,CAAC,EAAE,IAAI;EAEzE,IAAI,eAAe,KAAA,GAAW,QAAQ,KAAK,OAAO;OAC7C,QAAQ,KAAK,SAAS,UAAU;EACrC,aAAa;CACf,CAAC;AACH;AAEA,SAAS,KAAK,QAA8B,MAAiB;CAC3D,MAAM,MAAM,WAAW;CACvB,IAAI,CAAC,KAAK;CAEV,MAAM,UAAU,IAAI;CACpB,IAAI,OAAO,YAAY,YAAY;EACjC,IAAI,MAAM,CAAC;EACX,IAAI,EAAE,KAAK,CAAC,QAAQ,IAAI,CAAC;EACzB,QAAQ,QAAQ,MAAM,IAAI;EAC1B;CACF;CAEA,QAAQ,QAAQ,MAAM,KAAK;CAC3B,IAAI;EACF,QAAQ,GAAG,IAAI;CACjB,QAAQ,CAAC;AACX;;;;;;AAOA,SAAgB,MAA8B,MAAY,GAAG,MAA6B;CACxF,MAAM,CAAC,cAAc;CACrB,KAAK,SAAS,eAAe,KAAA,IAAY,CAAC,IAAI,IAAI,CAAC,MAAM,UAAU,CAAC;AACtE;;;;;;AAOA,SAAgB,SAAS,IAAkB;CACzC,KAAK,YAAY,CAAC,EAAE,CAAC;AACvB;;;;;;;;AASA,eAAsB,iBACpB,UAA8B,CAAC,GACF;CAC7B,IAAI,OAAO,WAAW,eAAe,OAAO,aAAa,aAAa;CAEtE,MAAM,WAAW,KAAK,IAAI,KAAK,QAAQ,WAAW;CAClD,IAAI,MAAM,OAAO;CAEjB,OAAO,CAAC,OAAO,GAAG,GAAG;EACnB,IAAI,KAAK,IAAI,KAAK,UAAU;EAI5B,IAFgB,kBAEN,CAAC,CAAC,OAAM,WAAU,cAAc,IAAI,MAAM,CAAC,GAAG;EAExD,MAAM,IAAI,SAAQ,YAAW,WAAW,SAAS,qBAAqB,CAAC;EACvE,MAAM,OAAO;CACf;CAEA,IAAI;EACF,OAAO,IAAI,mBAAmB;CAChC,QAAQ;EACN;CACF;AACF;;;;;;AAOA,SAAgB,cAAc,YAA0C;CACtE,MAAM,MAAM,WAAW;CACvB,IAAI,KAAK,IAAI,aAAa;AAC5B;;;;;;AAOA,SAAgB,OAAO,SAA8B;CACnD,IAAI,OAAO,aAAa,aAAa;CAErC,MAAM,EAAE,MAAM,MAAM,YAAY,UAAU,WAAW,aAAa,YAAY,UAAU;CACxF,cAAc;CAEd,IAAI,YAAY,cAAc,UAAU;CACxC,IAAI,QAAQ,GAAG,aAAa;CAC5B,IAAI,MAAM,KAAK,SAAS,OAAO,CAAC,CAAC,MAAK,WAAU,OAAO,QAAQ,SAAS,IAAI,GAAG;CAE/E,MAAM,SAAS,SAAS,cAAc,QAAQ;CAC9C,OAAO,iBAAiB,SAAS,UAAU;CAC3C,gBAAgB,IAAI,MAAM;CAC1B,OAAO,MAAM;CACb,OAAO,QAAQ,OAAO;CACtB,IAAI,aAAa,OAAO,OAAO,QAAQ,WAAW;CAClD,IAAI,cAAc,OAAO,OAAO,QAAQ,YAAY;CACpD,IAAI,aAAa,OAAO,QAAQ,cAAc;CAC9C,SAAS,KAAK,OAAO,MAAM;AAC7B"}
+{"version":3,"file":"index.js","names":[],"sources":["../src/index.ts"],"sourcesContent":["import { isDevelopment } from \"./env\"\n\n/**\n * The browser client. Every call goes to the hosted tracker on `window.highseat`; before the\n * tracker has loaded, calls wait in a queue the tracker drains on startup. Nothing here throws:\n * on a server, with the tracker blocked, or with tracking off, a call does nothing.\n */\n\n/** A value an event property can hold. A `null` or `undefined` value is left out of the event. */\nexport type PropertyValue = string | number | boolean | null | undefined\n\n/**\n * Money attached to an event. `amount` is an integer in the currency's smallest unit, so\n * `{ amount: 4999, currency: \"USD\" }` is $49.99 and `{ amount: 5000, currency: \"JPY\" }` is ¥5000.\n */\nexport interface Revenue {\n  /** An integer in minor units: 4999 for $49.99. An amount with decimals is rejected. */\n  amount: number\n  /** An ISO 4217 code, such as `USD` or `EUR`. */\n  currency: string\n}\n\n/** The properties of an event with no declared shape: any string keys, plus optional revenue. */\nexport interface Properties {\n  /** Money the event brought in. */\n  revenue?: Revenue\n  [key: string]: PropertyValue | Revenue\n}\n\n/**\n * The events Highseat knows by name. A site extends it, or overrides an entry, through\n * {@link Register}. Type-only: it adds nothing to the bundle.\n */\nexport interface BuiltInEvents {\n  /** A visitor created an account. */\n  signup: Properties\n  /** A visitor signed in. */\n  login: Properties\n  /**\n   * A sale. With a payment provider connected, leave `revenue` out: the provider's webhook\n   * records the money, and revenue sent here as well would count the sale twice. Send `revenue`\n   * only for a checkout no provider reports, and then with an `order_id`, so a provider sale\n   * added later for the same order is not counted again.\n   */\n  purchase: Properties\n  /** A paid subscription began. */\n  subscription_started: Properties\n  /** A free trial began. */\n  trial_started: Properties\n  /** A file download. The tracker records links to files on its own. */\n  file_download: { url: string }\n  /** A click on a link to another site. The tracker records these on its own. */\n  outbound_link_click: { url: string }\n  /** A visit to a missing page. Call it from a single-page app's not-found route. */\n  \"404\": Properties\n}\n\n/**\n * Declares a site's own events. Augment it from any file the compiler sees:\n *\n * ```ts\n * declare module \"highseat\" {\n *   interface Register {\n *     events: {\n *       signup: { plan: \"free\" | \"pro\" }\n *     }\n *     strict: true\n *   }\n * }\n * ```\n *\n * `events` adds names, or replaces a built-in one's properties. `strict: true` makes `track`\n * accept only built-in and registered names, so a misspelt name is a type error.\n */\nexport interface Register {}\n\n/**\n * A registered event's properties as `track` accepts them. A shape with no properties takes none,\n * and a property whose type an event cannot carry becomes `never`, so a call passing it fails\n * instead of sending `\"[object Object]\"`. The shape is not rejected at registration, where a\n * failed check would silently drop every registered event at once.\n */\ntype CheckedProperties<Shape> = [keyof Shape] extends [never]\n  ? Record<string, never>\n  : { [Key in keyof Shape]: Shape[Key] extends PropertyValue | Revenue ? Shape[Key] : never }\n\ntype RegisteredEvents = Register extends { events: infer Registered }\n  ? { [Name in keyof Registered]: CheckedProperties<Registered[Name]> }\n  : {}\n\n// A registered event replaces a built-in one of the same name.\ntype KnownEvents<BuiltIns> = Omit<BuiltIns, keyof RegisteredEvents> & RegisteredEvents\n\n/**\n * The event names a `track` with the given built-in events knows, built-in or registered.\n * `highseat/server` passes its server-only events on top of {@link BuiltInEvents}.\n */\nexport type KnownEventName<BuiltIns> = Extract<keyof KnownEvents<BuiltIns>, string>\n\n/** Every event name `track` knows, built-in or registered. */\nexport type EventName = KnownEventName<BuiltInEvents>\n\n/**\n * The names a `track` with the given built-in events accepts: known names, and any other string\n * unless the site is strict. `string & {}` keeps the known names in the editor's suggestions,\n * which a plain `string` in the union would absorb.\n */\nexport type TrackNameOf<BuiltIns> = Register extends { strict: true }\n  ? KnownEventName<BuiltIns>\n  : KnownEventName<BuiltIns> | (string & {})\n\n/** The names `track` accepts: known names, and any other string unless the site is strict. */\nexport type TrackName = TrackNameOf<BuiltInEvents>\n\n/**\n * The arguments after an event's name, for a `track` with the given built-in events. A known\n * name takes its declared properties, required when any of them is; any other name takes\n * {@link Properties}. Wrapped in tuples so a union of names is checked as a whole rather than\n * name by name.\n */\nexport type TrackArgsOf<BuiltIns, Name extends string> = [Name] extends [KnownEventName<BuiltIns>]\n  ? {} extends KnownEvents<BuiltIns>[Name]\n    ? [properties?: KnownEvents<BuiltIns>[Name]]\n    : [properties: KnownEvents<BuiltIns>[Name]]\n  : [properties?: Properties]\n\n/** The arguments after an event's name: its properties. See {@link TrackArgsOf}. */\nexport type TrackArgs<Name extends string> = TrackArgsOf<BuiltInEvents, Name>\n\n/**\n * A user id from your own system, as {@link identify} takes it. A string or a number identifies\n * the visitor, `null` clears the id, and `undefined` or an empty string changes nothing. Pass your\n * own database id, never an email or other personal data.\n */\nexport type UserId = string | number | null | undefined\n\n/**\n * The part of an event {@link BeforeSend} sees and may change. The site, the visitor's user id\n * and the attribution id are out of reach, so a hook cannot change who an event belongs to.\n */\nexport interface BeforeSendEvent {\n  /** The event's name: `pageview`, `engagement`, or a name passed to `track`. Read-only. */\n  readonly name: string\n  /** The page's full URL. The page path is read off the URL you return. */\n  url: string\n  /** The page the visitor came from, or the page left on a client-side navigation. */\n  referrer?: string\n  /** The event's properties, each value a string. */\n  properties?: Record<string, string>\n}\n\n/**\n * Runs in the browser on every event before the tracker sends it, page views from client-side\n * navigation included. Return the event, changed or not, or `null` to drop it. Any other falsy\n * answer drops it too, and so does a hook that throws: a hook that keeps a secret out of the\n * data must not leak it when it fails. The error still reaches the console.\n *\n * ```ts\n * function beforeSend(event: BeforeSendEvent) {\n *   const url = new URL(event.url)\n *   if (url.pathname.startsWith(\"/admin/\")) return null\n *   url.searchParams.delete(\"email\")\n *   return { ...event, url: url.href }\n * }\n * ```\n */\nexport type BeforeSend = (event: BeforeSendEvent) => BeforeSendEvent | null\n\n/** The tracker's API on `window.highseat`, or the queue that stands in for it until it loads. */\nexport interface HighseatGlobal {\n  /** Records an event. */\n  track?: (name: string, properties?: Properties) => void\n  /** Sets or clears the visitor's user id. */\n  identify?: (id: UserId) => void\n  /** The id that joins a payment to this tab's visit. */\n  getAttributionId?: () => string | undefined\n  /** Calls made before the tracker loaded, drained in order when it starts. */\n  q?: [string, unknown[]][]\n  /** The site's {@link BeforeSend} hook, read on every event. */\n  beforeSend?: BeforeSend\n}\n\n/** How long {@link getAttributionId} waits for the tracker. */\nexport interface AttributionOptions {\n  /** Milliseconds to wait for the tracker to load. Defaults to 3000. */\n  timeout?: number\n}\n\n/** How the tracker is loaded. Each option maps to an attribute on its script tag. */\nexport interface InjectOptions {\n  /** The site id, `site_…`, from the site's Installation settings. */\n  site: string\n  /**\n   * Where the script loads from: the site's proxy path (`/3f9a0c1e2b`) for first-party\n   * delivery, or a full URL. Defaults to Highseat's own host. The tracker posts its events back\n   * to the same place.\n   */\n  src?: string\n  /** Records clicks on links to other sites as `outbound_link_click`. Defaults to `true`. */\n  outbound?: boolean\n  /** Records clicks on links to files as `file_download`. Defaults to `true`. */\n  downloads?: boolean\n  /** Counts a change of `#/route` as a page view, for an app that routes by hash. */\n  hashRouting?: boolean\n  /** Changes or drops each event before it leaves the browser. See {@link BeforeSend}. */\n  beforeSend?: BeforeSend\n  /**\n   * Logs every `track()` and `identify()` call to the console, and warns once when no tracker\n   * script is on the page or the script failed to load. Defaults to `true` when\n   * `process.env.NODE_ENV` is `development`, so a production build logs nothing.\n   */\n  debug?: boolean\n}\n\ndeclare global {\n  interface Window {\n    highseat?: HighseatGlobal\n  }\n}\n\n/** Where the tracker loads from when the site has no proxy path. */\nconst SCRIPT_URL = \"https://cdn.highseat.com/script.js\"\n\n// The tracker marks its own API with this symbol. A site's own stub can define methods too, so\n// only the symbol proves the tracker is running.\nconst LIVE = Symbol.for(\"highseat\")\n\nconst SCRIPT_HOST = new URL(SCRIPT_URL).host\n// A site's proxy path: `/` and ten hex characters.\nconst PROXY_PATH = /^\\/[0-9a-f]{10}$/\n\nconst TRACKER_TIMEOUT = 3000\nconst TRACKER_POLL_INTERVAL = 50\n\nconst MISSING_SCRIPT_WARNING = [\n  \"highseat: no tracker script on this page, so no event reaches Highseat.\",\n  \"Render <Highseat />, call inject({ site }), or add the script tag from the site's Installation settings.\",\n].join(\" \")\nconst FAILED_SCRIPT_WARNING = [\n  \"highseat: the tracker script failed to load, so no event reaches Highseat.\",\n  \"An ad blocker may have stopped it: load the tracker from the site's proxy path instead.\",\n].join(\" \")\nconst SLOW_SCRIPT_WARNING = [\n  `highseat: the tracker script has not loaded after ${TRACKER_TIMEOUT / 1000} seconds,`,\n  \"so every call waits in the queue. Check the network panel for a blocked or failed request.\",\n].join(\" \")\n\n// The script tags `inject` added, and every tracker script whose request failed, such as one an\n// ad blocker stopped. A browser keeps no record of a failed script, so a failure is only known\n// to a listener attached before it happened.\nconst injectedScripts = new WeakSet<HTMLScriptElement>()\nconst failedScripts = new WeakSet<HTMLScriptElement>()\n\n// The `debug` option of the last `inject` call. Unset falls back to the build's environment.\nlet debugOption: boolean | undefined\n// The windows whose tracker is being watched, so a page warns about its script once.\nconst watchedWindows = new WeakSet<Window>()\n\nfunction findGlobal(): HighseatGlobal | undefined {\n  if (typeof window === \"undefined\") return\n  return (window.highseat ??= {})\n}\n\nfunction isLive(api: HighseatGlobal | undefined): api is HighseatGlobal {\n  return !!api && (api as Record<symbol, unknown>)[LIVE] === true\n}\n\n// One function for every script, so attaching it on each poll adds no second listener.\nfunction markFailed(event: Event) {\n  failedScripts.add(event.currentTarget as HTMLScriptElement)\n}\n\n/**\n * Whether a script tag loads the tracker, judged as the tracker judges itself. Fathom's snippet\n * carries a `data-site` too, so a tag is matched by a `site_` id, or by a `src` on a proxy path\n * or on Highseat's host: an older site's id is a UUID, which any tool could use.\n */\nfunction isTrackerScript(script: HTMLScriptElement) {\n  const { site } = script.dataset\n  if (injectedScripts.has(script) || site?.startsWith(\"site_\")) return true\n  if (site === undefined) return false\n\n  try {\n    // A browser hands back `src` resolved; the base only matters to a relative one.\n    const url = new URL(script.src, \"http://localhost\")\n    return url.host === SCRIPT_HOST || PROXY_PATH.test(url.pathname)\n  } catch {\n    return false\n  }\n}\n\n/** The page's tracker scripts, each one listened to from now on for a failed load. */\nfunction getTrackerScripts() {\n  const scripts = Array.from(document.scripts).filter(isTrackerScript)\n  for (const script of scripts) script.addEventListener(\"error\", markFailed)\n  return scripts\n}\n\nfunction isDebug() {\n  return debugOption ?? isDevelopment()\n}\n\n/**\n * Warns once per page when the tracker cannot arrive: no tracker script, or only failed ones. A\n * missing script is judged at the timeout, because `<Highseat />` adds its tag in an effect that\n * runs after the effects of the components inside it.\n */\nfunction watchTracker() {\n  if (typeof window === \"undefined\" || typeof document === \"undefined\") return\n  if (watchedWindows.has(window)) return\n  watchedWindows.add(window)\n\n  const page = window\n  const deadline = Date.now() + TRACKER_TIMEOUT\n\n  function check() {\n    // A replaced global window, as a test sets up for each case, is another page.\n    if (window !== page || isLive(page.highseat)) return\n\n    const scripts = getTrackerScripts()\n\n    if (scripts.length > 0 && scripts.every(script => failedScripts.has(script))) {\n      console.warn(FAILED_SCRIPT_WARNING)\n      return\n    }\n    if (Date.now() < deadline) {\n      setTimeout(check, TRACKER_POLL_INTERVAL)\n      return\n    }\n    console.warn(scripts.length === 0 ? MISSING_SCRIPT_WARNING : SLOW_SCRIPT_WARNING)\n  }\n\n  setTimeout(check, TRACKER_POLL_INTERVAL)\n}\n\n/**\n * Logs a call when debugging is on. The check waits a microtask, so a `debug` option that\n * `<Highseat />` passes in its effect applies to the calls its children make in theirs.\n */\nfunction logCall(method: \"track\" | \"identify\", args: unknown[], isQueued: boolean) {\n  queueMicrotask(() => {\n    if (!isDebug()) return\n\n    const status = isQueued ? \"queued until the tracker loads\" : \"sent to the tracker\"\n    const [value, properties] = args\n    // `JSON.stringify` quotes a name or a string id, and returns `undefined` for an unset id.\n    const message = `highseat: ${method} ${String(JSON.stringify(value))}, ${status}`\n\n    if (properties === undefined) console.info(message)\n    else console.info(message, properties)\n    watchTracker()\n  })\n}\n\nfunction call(method: \"track\" | \"identify\", args: unknown[]) {\n  const api = findGlobal()\n  if (!api) return\n\n  const handler = api[method] as ((...values: unknown[]) => void) | undefined\n  if (typeof handler !== \"function\") {\n    api.q ??= []\n    api.q.push([method, args])\n    logCall(method, args, true)\n    return\n  }\n\n  logCall(method, args, false)\n  try {\n    handler(...args)\n  } catch {}\n}\n\n/**\n * Records an event. A known name autocompletes and checks its properties; any other name is a\n * custom event, unless {@link Register} sets `strict`. Names are stored exactly as written, so\n * `Purchase` and `purchase` are two events.\n */\nexport function track<Name extends TrackName>(name: Name, ...args: TrackArgs<Name>): void {\n  const [properties] = args\n  call(\"track\", properties === undefined ? [name] : [name, properties])\n}\n\n/**\n * Links the visitor to a user id from your own system, on this event and every later one, across\n * visits. `null` clears it at sign-out. An empty or `undefined` id is ignored, so\n * `identify(user?.id)` before a session loads does not sign the visitor out.\n */\nexport function identify(id: UserId): void {\n  call(\"identify\", [id])\n}\n\n/**\n * The id that joins a payment to this tab's visit. Pass it to the checkout as metadata\n * (`attribution_id`), and the payment provider's webhook credits the sale to the visit's source.\n * Resolves to `undefined`, so a checkout that awaits it never hangs: at once when the page has\n * no tracker script or its script fails to load (an ad blocker stopping it), after the timeout\n * when the script is still loading, and on a server or with tracking off.\n */\nexport async function getAttributionId(\n  options: AttributionOptions = {},\n): Promise<string | undefined> {\n  if (typeof window === \"undefined\" || typeof document === \"undefined\") return\n\n  const deadline = Date.now() + (options.timeout ?? TRACKER_TIMEOUT)\n  let api = window.highseat\n\n  while (!isLive(api)) {\n    if (Date.now() >= deadline) return\n\n    const scripts = getTrackerScripts()\n    // No tracker script at all, or only failed ones: the tracker cannot arrive.\n    if (scripts.every(script => failedScripts.has(script))) return\n\n    await new Promise(resolve => setTimeout(resolve, TRACKER_POLL_INTERVAL))\n    api = window.highseat\n  }\n\n  try {\n    return api.getAttributionId?.()\n  } catch {\n    return\n  }\n}\n\n/**\n * Sets the {@link BeforeSend} hook, or clears it with `undefined`. Works before the tracker has\n * loaded, which picks the hook up when it starts, and applies from the next event once it runs.\n * Does nothing on a server.\n */\nexport function setBeforeSend(beforeSend: BeforeSend | undefined): void {\n  const api = findGlobal()\n  if (api) api.beforeSend = beforeSend\n}\n\n/**\n * Adds the tracker's script tag to the page, once. A second call for the same site, such as a\n * component mounting again, finds the tag and adds nothing, but its `debug` option still applies.\n * Does nothing on a server.\n */\nexport function inject(options: InjectOptions): void {\n  if (typeof document === \"undefined\") return\n\n  const { site, src = SCRIPT_URL, outbound, downloads, hashRouting, beforeSend, debug } = options\n  debugOption = debug\n  // Set before the script tag is added, so the first page view already passes through it.\n  if (beforeSend) setBeforeSend(beforeSend)\n  if (isDebug()) watchTracker()\n  if (Array.from(document.scripts).some(script => script.dataset.site === site)) return\n\n  const script = document.createElement(\"script\")\n  script.addEventListener(\"error\", markFailed)\n  injectedScripts.add(script)\n  script.src = src\n  script.dataset.site = site\n  if (outbound === false) script.dataset.outbound = \"false\"\n  if (downloads === false) script.dataset.downloads = \"false\"\n  if (hashRouting) script.dataset.hashRouting = \"\"\n  document.head.append(script)\n}\n"],"mappings":"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"}

package/ingest.d.ts

@@ -1,7 +1,7 @@
 //#region src/ingest.d.ts
 /**
  * What `highseat/proxy` and `highseat/server` share about reaching ingest: its host, the site
- * secret's prefixes and where the visitor's IP is read.
+ * secret's prefix and where the visitor's IP is read.
  */
 /** A host whose own header carries the visitor's IP. */
 export type ClientIpPreset = "vercel" | "cloudflare" | "netlify" | "nginx";

package/ingest.js

@@ -2,11 +2,7 @@ import { findSecret } from "./env.js";
 //#region src/ingest.ts
 /** The ingest origin both handlers send to unless told otherwise. */
 const DEFAULT_UPSTREAM = "https://cdn.highseat.com";
-const SECRET_PREFIXES = [
-	"hs_secret_",
-	"hs_proxy_",
-	"ana_proxy_"
-];
+const SECRET_PREFIX = "hs_secret_";
 const CLIENT_IP_HEADERS = {
 	vercel: "x-real-ip",
 	cloudflare: "cf-connecting-ip",
@@ -19,8 +15,8 @@ const CLIENT_IP_HEADERS = {
 */
 function findValidSecret(option, entry) {
 	const secret = option ?? findSecret();
-	if (!secret || SECRET_PREFIXES.some((prefix) => secret.startsWith(prefix))) return secret;
-	throw new Error(`${entry}: not a site secret. Copy it from the site's Installation settings; it starts with "${SECRET_PREFIXES[0]}".`);
+	if (!secret || secret.startsWith(SECRET_PREFIX)) return secret;
+	throw new Error(`${entry}: not a site secret. Copy it from the site's Installation settings; it starts with "${SECRET_PREFIX}".`);
 }
 function getClientIpReader(clientIp, entry) {
 	if (typeof clientIp === "function") return {

package/ingest.js.map

@@ -1 +1 @@
-{"version":3,"file":"ingest.js","names":[],"sources":["../src/ingest.ts"],"sourcesContent":["import { findSecret } from \"./env\"\n\n/**\n * What `highseat/proxy` and `highseat/server` share about reaching ingest: its host, the site\n * secret's prefixes and where the visitor's IP is read.\n */\n\n/** A host whose own header carries the visitor's IP. */\nexport type ClientIpPreset = \"vercel\" | \"cloudflare\" | \"netlify\" | \"nginx\"\n\n/**\n * Where the visitor's IP is read: a host preset, or a function for any other setup. A function\n * returns the IP, or nothing when the request carries none.\n */\nexport type ClientIp = ClientIpPreset | ((request: Request) => string | null | undefined)\n\n/** The ingest origin both handlers send to unless told otherwise. */\nexport const DEFAULT_UPSTREAM = \"https://cdn.highseat.com\"\n\n// The current prefix first. Ingest still accepts the secrets minted under the older two, so a\n// site keeps its secret when it moves to this package.\nconst SECRET_PREFIXES = [\"hs_secret_\", \"hs_proxy_\", \"ana_proxy_\"]\n\nconst CLIENT_IP_HEADERS: Record<ClientIpPreset, string> = {\n  vercel: \"x-real-ip\",\n  // Read from the inbound request: Cloudflare overwrites it on the Worker's own subrequest.\n  cloudflare: \"cf-connecting-ip\",\n  netlify: \"x-nf-client-connection-ip\",\n  nginx: \"x-real-ip\",\n}\n\ninterface ClientIpReader {\n  read: (request: Request) => string\n  /** Where `read` looks, for the warning about an empty IP. */\n  source: string\n}\n\n/**\n * The site secret, `option` or else `HIGHSEAT_SECRET`, or `undefined` when neither is set. Throws\n * on a value that is not one, naming the entry point that read it: that is a copying mistake.\n */\nexport function findValidSecret(option: string | undefined, entry: string): string | undefined {\n  const secret = option ?? findSecret()\n  if (!secret || SECRET_PREFIXES.some(prefix => secret.startsWith(prefix))) return secret\n\n  throw new Error(\n    `${entry}: not a site secret. Copy it from the site's Installation settings; it starts with \"${SECRET_PREFIXES[0]}\".`,\n  )\n}\n\nexport function getClientIpReader(clientIp: ClientIp, entry: string): ClientIpReader {\n  if (typeof clientIp === \"function\") {\n    return { read: request => clientIp(request)?.trim() ?? \"\", source: \"the clientIp function\" }\n  }\n\n  const header = CLIENT_IP_HEADERS[clientIp]\n  if (!header) throw new Error(`${entry}: unknown clientIp preset \"${String(clientIp)}\".`)\n  return {\n    read: request => request.headers.get(header)?.trim() ?? \"\",\n    source: `the \"${clientIp}\" preset's ${header} header`,\n  }\n}\n"],"mappings":";;;AAiBA,MAAa,mBAAmB;AAIhC,MAAM,kBAAkB;CAAC;CAAc;CAAa;AAAY;AAEhE,MAAM,oBAAoD;CACxD,QAAQ;CAER,YAAY;CACZ,SAAS;CACT,OAAO;AACT;;;;;AAYA,SAAgB,gBAAgB,QAA4B,OAAmC;CAC7F,MAAM,SAAS,UAAU,WAAW;CACpC,IAAI,CAAC,UAAU,gBAAgB,MAAK,WAAU,OAAO,WAAW,MAAM,CAAC,GAAG,OAAO;CAEjF,MAAM,IAAI,MACR,GAAG,MAAM,sFAAsF,gBAAgB,GAAG,GACpH;AACF;AAEA,SAAgB,kBAAkB,UAAoB,OAA+B;CACnF,IAAI,OAAO,aAAa,YACtB,OAAO;EAAE,OAAM,YAAW,SAAS,OAAO,CAAC,EAAE,KAAK,KAAK;EAAI,QAAQ;CAAwB;CAG7F,MAAM,SAAS,kBAAkB;CACjC,IAAI,CAAC,QAAQ,MAAM,IAAI,MAAM,GAAG,MAAM,6BAA6B,OAAO,QAAQ,EAAE,GAAG;CACvF,OAAO;EACL,OAAM,YAAW,QAAQ,QAAQ,IAAI,MAAM,CAAC,EAAE,KAAK,KAAK;EACxD,QAAQ,QAAQ,SAAS,aAAa,OAAO;CAC/C;AACF"}
+{"version":3,"file":"ingest.js","names":[],"sources":["../src/ingest.ts"],"sourcesContent":["import { findSecret } from \"./env\"\n\n/**\n * What `highseat/proxy` and `highseat/server` share about reaching ingest: its host, the site\n * secret's prefix and where the visitor's IP is read.\n */\n\n/** A host whose own header carries the visitor's IP. */\nexport type ClientIpPreset = \"vercel\" | \"cloudflare\" | \"netlify\" | \"nginx\"\n\n/**\n * Where the visitor's IP is read: a host preset, or a function for any other setup. A function\n * returns the IP, or nothing when the request carries none.\n */\nexport type ClientIp = ClientIpPreset | ((request: Request) => string | null | undefined)\n\n/** The ingest origin both handlers send to unless told otherwise. */\nexport const DEFAULT_UPSTREAM = \"https://cdn.highseat.com\"\n\nconst SECRET_PREFIX = \"hs_secret_\"\n\nconst CLIENT_IP_HEADERS: Record<ClientIpPreset, string> = {\n  vercel: \"x-real-ip\",\n  // Read from the inbound request: Cloudflare overwrites it on the Worker's own subrequest.\n  cloudflare: \"cf-connecting-ip\",\n  netlify: \"x-nf-client-connection-ip\",\n  nginx: \"x-real-ip\",\n}\n\ninterface ClientIpReader {\n  read: (request: Request) => string\n  /** Where `read` looks, for the warning about an empty IP. */\n  source: string\n}\n\n/**\n * The site secret, `option` or else `HIGHSEAT_SECRET`, or `undefined` when neither is set. Throws\n * on a value that is not one, naming the entry point that read it: that is a copying mistake.\n */\nexport function findValidSecret(option: string | undefined, entry: string): string | undefined {\n  const secret = option ?? findSecret()\n  if (!secret || secret.startsWith(SECRET_PREFIX)) return secret\n\n  throw new Error(\n    `${entry}: not a site secret. Copy it from the site's Installation settings; it starts with \"${SECRET_PREFIX}\".`,\n  )\n}\n\nexport function getClientIpReader(clientIp: ClientIp, entry: string): ClientIpReader {\n  if (typeof clientIp === \"function\") {\n    return { read: request => clientIp(request)?.trim() ?? \"\", source: \"the clientIp function\" }\n  }\n\n  const header = CLIENT_IP_HEADERS[clientIp]\n  if (!header) throw new Error(`${entry}: unknown clientIp preset \"${String(clientIp)}\".`)\n  return {\n    read: request => request.headers.get(header)?.trim() ?? \"\",\n    source: `the \"${clientIp}\" preset's ${header} header`,\n  }\n}\n"],"mappings":";;;AAiBA,MAAa,mBAAmB;AAEhC,MAAM,gBAAgB;AAEtB,MAAM,oBAAoD;CACxD,QAAQ;CAER,YAAY;CACZ,SAAS;CACT,OAAO;AACT;;;;;AAYA,SAAgB,gBAAgB,QAA4B,OAAmC;CAC7F,MAAM,SAAS,UAAU,WAAW;CACpC,IAAI,CAAC,UAAU,OAAO,WAAW,aAAa,GAAG,OAAO;CAExD,MAAM,IAAI,MACR,GAAG,MAAM,sFAAsF,cAAc,GAC/G;AACF;AAEA,SAAgB,kBAAkB,UAAoB,OAA+B;CACnF,IAAI,OAAO,aAAa,YACtB,OAAO;EAAE,OAAM,YAAW,SAAS,OAAO,CAAC,EAAE,KAAK,KAAK;EAAI,QAAQ;CAAwB;CAG7F,MAAM,SAAS,kBAAkB;CACjC,IAAI,CAAC,QAAQ,MAAM,IAAI,MAAM,GAAG,MAAM,6BAA6B,OAAO,QAAQ,EAAE,GAAG;CACvF,OAAO;EACL,OAAM,YAAW,QAAQ,QAAQ,IAAI,MAAM,CAAC,EAAE,KAAK,KAAK;EACxD,QAAQ,QAAQ,SAAS,aAAa,OAAO;CAC/C;AACF"}

package/mcp.d.ts

@@ -0,0 +1,61 @@
+import { ServerBuiltInEvents, ServerEventOptions, WaitUntil } from "./server.js";
+import { McpServer, ServerContext } from "@modelcontextprotocol/server";
+//#region src/mcp.d.ts
+/**
+ * MCP tool calls, recorded from your own MCP server built on the MCP TypeScript SDK v2: one
+ * `mcp_tool_call` event per call, with the tool, the client, the outcome and the time it took.
+ * The tool's arguments, the caller's IP and its user agent are never sent: assistant directories
+ * forbid collecting conversation data, and the caller is the assistant's server, not a person.
+ */
+type ToolCall = ServerBuiltInEvents["mcp_tool_call"];
+/** What tool calls are sent with: a tracker from `createTracker()`, or any `track()` like its. */
+export interface ToolCallTracker {
+  track: (name: "mcp_tool_call", properties: ToolCall, options?: ServerEventOptions) => void;
+}
+export interface TrackToolCallsOptions {
+  /** The tracker events are sent with. Defaults to the one `track()` from `highseat/server` uses. */
+  tracker?: ToolCallTracker;
+  /** A label for this MCP server, such as `public` or `admin`, when the site runs more than one. */
+  server?: string;
+  /** The site hostname every call is filed under. Defaults to the tracker's `hostname`. */
+  hostname?: string;
+  /**
+   * Keeps a serverless function alive until each event is sent: `after` from `next/server`, or
+   * `ctx.waitUntil` in a Cloudflare Worker, bound to its object.
+   */
+  waitUntil?: WaitUntil;
+}
+/**
+ * Records every tool call on an MCP server built with the MCP TypeScript SDK v2. Call it once,
+ * right after creating the server and before registering any tool: it wraps `registerTool`, so a
+ * tool registered earlier would go unrecorded, and it throws when the server already has tools.
+ *
+ * ```ts
+ * const server = new McpServer({ name: "Acme", version: "1.0.0" })
+ * trackToolCalls(server, { server: "public" })
+ * server.registerTool("search", config, handler)
+ * ```
+ *
+ * Each call sends `mcp_tool_call` with the tool, the client, the status, the time it took and,
+ * for a read-only tool whose result is a list, how many items it returned. The tool's arguments,
+ * the caller's IP and its user agent are never sent. A call still waiting for input from the
+ * client is recorded once it ends. Failures to send never reach the tool: they go to the
+ * tracker's `onError`.
+ */
+export declare function trackToolCalls(server: McpServer, options?: TrackToolCallsOptions): void;
+/**
+ * Tags a link a tool returns, so the visit it brings reads as the assistant that showed it:
+ * `utm_source` names the client and `utm_medium` is `mcp`, which Highseat reads as the AI
+ * channel. A link that already has a `utm_source` is returned as it is. Pass the tool handler's
+ * context.
+ *
+ * ```ts
+ * server.registerTool("get_product", config, async ({ slug }, context) => ({
+ *   content: [{ type: "text", text: mcpLink(`https://acme.com/products/${slug}`, context) }],
+ * }))
+ * ```
+ */
+export declare function mcpLink(url: string, context: ServerContext): string;
+//#endregion
+export {};
+//# sourceMappingURL=mcp.d.ts.map