@aglyn/shared-util-first-touch 1.0.0-beta.186

package/src/lib/first-touch-page.d.ts

@@ -0,0 +1,43 @@
+/**
+ * @license
+ * Copyright 2026 Aglyn LLC
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *   http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+import type { FirstTouchRuntime } from './first-touch';
+/**
+ * The bridge between a SERVED capture script and the page's own code.
+ *
+ * A surface that includes the capture as a script tag has no import to call
+ * it through, and its consent code — which decides whether the record may be
+ * written to the device — runs in a bundle that never loaded the capture. So
+ * the served script leaves its runtime on `window`, and this module is the
+ * one place that knows where. It imports nothing but a type, which is the
+ * point: a page pays for these few lines, not for the capture.
+ *
+ * Consent can be decided before the script has booted (the script is loaded
+ * `async`), so a decision is also left where the script reads it at boot.
+ */
+/** Where a served script leaves its runtime. */
+export declare const FIRST_TOUCH_PAGE_GLOBAL = "aglynFirstTouch";
+/** Where a storage decision made before the script booted waits for it. */
+export declare const FIRST_TOUCH_PAGE_STORAGE_GLOBAL = "__aglynFirstTouchStorage";
+/** The runtime a served script booted on this page, or null. */
+export declare function pageFirstTouchRuntime(): FirstTouchRuntime | null;
+/**
+ * Tell the page's capture whether it may keep the record on the device:
+ * `true` to grant, `false` to refuse (and erase what it kept), `null` while
+ * the visitor's consent is unresolved. Reaches a runtime that is already
+ * running and waits for one that has not booted yet.
+ */
+export declare function setPageFirstTouchStorage(allowed: boolean | null): void;

package/src/lib/first-touch-page.js

@@ -0,0 +1,52 @@
+/**
+ * @license
+ * Copyright 2026 Aglyn LLC
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *   http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */ /**
+ * The bridge between a SERVED capture script and the page's own code.
+ *
+ * A surface that includes the capture as a script tag has no import to call
+ * it through, and its consent code — which decides whether the record may be
+ * written to the device — runs in a bundle that never loaded the capture. So
+ * the served script leaves its runtime on `window`, and this module is the
+ * one place that knows where. It imports nothing but a type, which is the
+ * point: a page pays for these few lines, not for the capture.
+ *
+ * Consent can be decided before the script has booted (the script is loaded
+ * `async`), so a decision is also left where the script reads it at boot.
+ */ /** Where a served script leaves its runtime. */ export const FIRST_TOUCH_PAGE_GLOBAL = 'aglynFirstTouch';
+/** Where a storage decision made before the script booted waits for it. */ export const FIRST_TOUCH_PAGE_STORAGE_GLOBAL = '__aglynFirstTouchStorage';
+function pageWindow() {
+    return typeof window === 'undefined' ? null : window;
+}
+/** The runtime a served script booted on this page, or null. */ export function pageFirstTouchRuntime() {
+    var _pageWindow;
+    const runtime = (_pageWindow = pageWindow()) == null ? void 0 : _pageWindow[FIRST_TOUCH_PAGE_GLOBAL];
+    return runtime && typeof runtime.read === 'function' && typeof runtime.setStorage === 'function' ? runtime : null;
+}
+/**
+ * Tell the page's capture whether it may keep the record on the device:
+ * `true` to grant, `false` to refuse (and erase what it kept), `null` while
+ * the visitor's consent is unresolved. Reaches a runtime that is already
+ * running and waits for one that has not booted yet.
+ */ export function setPageFirstTouchStorage(allowed) {
+    var _pageFirstTouchRuntime;
+    const page = pageWindow();
+    if (!page) return;
+    const value = allowed === true ? true : allowed === false ? false : null;
+    page[FIRST_TOUCH_PAGE_STORAGE_GLOBAL] = value;
+    (_pageFirstTouchRuntime = pageFirstTouchRuntime()) == null ? void 0 : _pageFirstTouchRuntime.setStorage(value);
+}
+
+//# sourceMappingURL=first-touch-page.js.map

package/src/lib/first-touch-page.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../../../../../../libs/shared/util/first-touch/src/lib/first-touch-page.ts"],"sourcesContent":["/**\n * @license\n * Copyright 2026 Aglyn LLC\n *\n * Licensed under the Apache License, Version 2.0 (the \"License\");\n * you may not use this file except in compliance with the License.\n * You may obtain a copy of the License at\n *\n *   http://www.apache.org/licenses/LICENSE-2.0\n *\n * Unless required by applicable law or agreed to in writing, software\n * distributed under the License is distributed on an \"AS IS\" BASIS,\n * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n * See the License for the specific language governing permissions and\n * limitations under the License.\n */\n\nimport type { FirstTouchRuntime } from './first-touch'\n\n/**\n * The bridge between a SERVED capture script and the page's own code.\n *\n * A surface that includes the capture as a script tag has no import to call\n * it through, and its consent code — which decides whether the record may be\n * written to the device — runs in a bundle that never loaded the capture. So\n * the served script leaves its runtime on `window`, and this module is the\n * one place that knows where. It imports nothing but a type, which is the\n * point: a page pays for these few lines, not for the capture.\n *\n * Consent can be decided before the script has booted (the script is loaded\n * `async`), so a decision is also left where the script reads it at boot.\n */\n\n/** Where a served script leaves its runtime. */\nexport const FIRST_TOUCH_PAGE_GLOBAL = 'aglynFirstTouch'\n\n/** Where a storage decision made before the script booted waits for it. */\nexport const FIRST_TOUCH_PAGE_STORAGE_GLOBAL = '__aglynFirstTouchStorage'\n\nfunction pageWindow(): Record<string, unknown> | null {\n  return typeof window === 'undefined'\n    ? null\n    : (window as unknown as Record<string, unknown>)\n}\n\n/** The runtime a served script booted on this page, or null. */\nexport function pageFirstTouchRuntime(): FirstTouchRuntime | null {\n  const runtime = pageWindow()?.[FIRST_TOUCH_PAGE_GLOBAL] as\n    | Partial<FirstTouchRuntime>\n    | undefined\n  return runtime &&\n    typeof runtime.read === 'function' &&\n    typeof runtime.setStorage === 'function'\n    ? (runtime as FirstTouchRuntime)\n    : null\n}\n\n/**\n * Tell the page's capture whether it may keep the record on the device:\n * `true` to grant, `false` to refuse (and erase what it kept), `null` while\n * the visitor's consent is unresolved. Reaches a runtime that is already\n * running and waits for one that has not booted yet.\n */\nexport function setPageFirstTouchStorage(allowed: boolean | null): void {\n  const page = pageWindow()\n  if (!page) return\n  const value = allowed === true ? true : allowed === false ? false : null\n  page[FIRST_TOUCH_PAGE_STORAGE_GLOBAL] = value\n  pageFirstTouchRuntime()?.setStorage(value)\n}\n"],"names":["FIRST_TOUCH_PAGE_GLOBAL","FIRST_TOUCH_PAGE_STORAGE_GLOBAL","pageWindow","window","pageFirstTouchRuntime","runtime","read","setStorage","setPageFirstTouchStorage","allowed","page","value"],"mappings":"AAAA;;;;;;;;;;;;;;;CAeC,GAID;;;;;;;;;;;;CAYC,GAED,8CAA8C,GAC9C,OAAO,MAAMA,0BAA0B,kBAAiB;AAExD,yEAAyE,GACzE,OAAO,MAAMC,kCAAkC,2BAA0B;AAEzE,SAASC;IACP,OAAO,OAAOC,WAAW,cACrB,OACCA;AACP;AAEA,8DAA8D,GAC9D,OAAO,SAASC;QACEF;IAAhB,MAAMG,WAAUH,cAAAA,iCAAAA,WAAc,CAACF,wBAAwB;IAGvD,OAAOK,WACL,OAAOA,QAAQC,IAAI,KAAK,cACxB,OAAOD,QAAQE,UAAU,KAAK,aAC3BF,UACD;AACN;AAEA;;;;;CAKC,GACD,OAAO,SAASG,yBAAyBC,OAAuB;QAK9DL;IAJA,MAAMM,OAAOR;IACb,IAAI,CAACQ,MAAM;IACX,MAAMC,QAAQF,YAAY,OAAO,OAAOA,YAAY,QAAQ,QAAQ;IACpEC,IAAI,CAACT,gCAAgC,GAAGU;KACxCP,yBAAAA,4CAAAA,uBAAyBG,UAAU,CAACI;AACtC"}

package/src/lib/first-touch-script.d.ts

@@ -0,0 +1,39 @@
+/**
+ * @license
+ * Copyright 2026 Aglyn LLC
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *   http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+import { type FirstTouchConfig } from './first-touch';
+/**
+ * The capture as a script a page runs with no bundler: the kit's own source
+ * text, called with this surface's configuration.
+ *
+ * Served by the platform at one URL so that including the capture on a new
+ * surface is one tag — `<script src="…/api/first-touch" async>` — and the
+ * host registry, the hand-off endpoint and the storage decision arrive with
+ * it rather than being configured on each surface.
+ *
+ * Two page-side overrides, both read at boot:
+ *
+ * - `data-consent="pending"` on the tag holds the record in memory until the
+ *   page's consent code grants storage — for a surface whose own consent tool
+ *   decides after load;
+ * - a decision the page's code already left through
+ *   `setPageFirstTouchStorage` before the script arrived wins over both the
+ *   attribute and the served default, because it is the newest answer.
+ *
+ * Everything runs inside a `try`: a capture that throws must never cost the
+ * page it runs on.
+ */
+export declare function firstTouchScript(config: FirstTouchConfig): string;

package/src/lib/first-touch-script.js

@@ -0,0 +1,52 @@
+/**
+ * @license
+ * Copyright 2026 Aglyn LLC
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *   http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */ import { createFirstTouchKit } from "./first-touch.js";
+import { FIRST_TOUCH_PAGE_GLOBAL, FIRST_TOUCH_PAGE_STORAGE_GLOBAL } from "./first-touch-page.js";
+/**
+ * The capture as a script a page runs with no bundler: the kit's own source
+ * text, called with this surface's configuration.
+ *
+ * Served by the platform at one URL so that including the capture on a new
+ * surface is one tag — `<script src="…/api/first-touch" async>` — and the
+ * host registry, the hand-off endpoint and the storage decision arrive with
+ * it rather than being configured on each surface.
+ *
+ * Two page-side overrides, both read at boot:
+ *
+ * - `data-consent="pending"` on the tag holds the record in memory until the
+ *   page's consent code grants storage — for a surface whose own consent tool
+ *   decides after load;
+ * - a decision the page's code already left through
+ *   `setPageFirstTouchStorage` before the script arrived wins over both the
+ *   attribute and the served default, because it is the newest answer.
+ *
+ * Everything runs inside a `try`: a capture that throws must never cost the
+ * page it runs on.
+ */ export function firstTouchScript(config) {
+    var _config_hosts, _config_handoffUrl;
+    const served = JSON.stringify({
+        hosts: [
+            ...(_config_hosts = config.hosts) != null ? _config_hosts : []
+        ],
+        storage: config.storage === undefined ? true : config.storage,
+        handoffUrl: (_config_handoffUrl = config.handoffUrl) != null ? _config_handoffUrl : null
+    })// Inline in a `<script>` element as well as served, so nothing in the
+    // configuration may close the element or break a pre-2019 parser.
+    .replace(/</g, '\\u003c').replace(/\u2028/g, '\\u2028').replace(/\u2029/g, '\\u2029');
+    return '(function(){try{' + `var c=${served};` + 'var w=window;var s=document.currentScript;' + "if(s&&s.getAttribute('data-consent')==='pending')c.storage=null;" + `var q=w[${JSON.stringify(FIRST_TOUCH_PAGE_STORAGE_GLOBAL)}];` + 'if(q===true||q===false||q===null)c.storage=q;' + `w[${JSON.stringify(FIRST_TOUCH_PAGE_GLOBAL)}]=(${createFirstTouchKit.toString()})().boot(c);` + '}catch(e){}})();';
+}
+
+//# sourceMappingURL=first-touch-script.js.map

package/src/lib/first-touch-script.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../../../../../../libs/shared/util/first-touch/src/lib/first-touch-script.ts"],"sourcesContent":["/**\n * @license\n * Copyright 2026 Aglyn LLC\n *\n * Licensed under the Apache License, Version 2.0 (the \"License\");\n * you may not use this file except in compliance with the License.\n * You may obtain a copy of the License at\n *\n *   http://www.apache.org/licenses/LICENSE-2.0\n *\n * Unless required by applicable law or agreed to in writing, software\n * distributed under the License is distributed on an \"AS IS\" BASIS,\n * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.\n * See the License for the specific language governing permissions and\n * limitations under the License.\n */\n\nimport { createFirstTouchKit, type FirstTouchConfig } from './first-touch'\nimport {\n  FIRST_TOUCH_PAGE_GLOBAL,\n  FIRST_TOUCH_PAGE_STORAGE_GLOBAL,\n} from './first-touch-page'\n\n/**\n * The capture as a script a page runs with no bundler: the kit's own source\n * text, called with this surface's configuration.\n *\n * Served by the platform at one URL so that including the capture on a new\n * surface is one tag — `<script src=\"…/api/first-touch\" async>` — and the\n * host registry, the hand-off endpoint and the storage decision arrive with\n * it rather than being configured on each surface.\n *\n * Two page-side overrides, both read at boot:\n *\n * - `data-consent=\"pending\"` on the tag holds the record in memory until the\n *   page's consent code grants storage — for a surface whose own consent tool\n *   decides after load;\n * - a decision the page's code already left through\n *   `setPageFirstTouchStorage` before the script arrived wins over both the\n *   attribute and the served default, because it is the newest answer.\n *\n * Everything runs inside a `try`: a capture that throws must never cost the\n * page it runs on.\n */\nexport function firstTouchScript(config: FirstTouchConfig): string {\n  const served = JSON.stringify({\n    hosts: [...(config.hosts ?? [])],\n    storage: config.storage === undefined ? true : config.storage,\n    handoffUrl: config.handoffUrl ?? null,\n  })\n    // Inline in a `<script>` element as well as served, so nothing in the\n    // configuration may close the element or break a pre-2019 parser.\n    .replace(/</g, '\\\\u003c')\n    .replace(/\\u2028/g, '\\\\u2028')\n    .replace(/\\u2029/g, '\\\\u2029')\n  return (\n    '(function(){try{' +\n    `var c=${served};` +\n    'var w=window;var s=document.currentScript;' +\n    \"if(s&&s.getAttribute('data-consent')==='pending')c.storage=null;\" +\n    `var q=w[${JSON.stringify(FIRST_TOUCH_PAGE_STORAGE_GLOBAL)}];` +\n    'if(q===true||q===false||q===null)c.storage=q;' +\n    `w[${JSON.stringify(FIRST_TOUCH_PAGE_GLOBAL)}]=(${createFirstTouchKit.toString()})().boot(c);` +\n    '}catch(e){}})();'\n  )\n}\n"],"names":["createFirstTouchKit","FIRST_TOUCH_PAGE_GLOBAL","FIRST_TOUCH_PAGE_STORAGE_GLOBAL","firstTouchScript","config","served","JSON","stringify","hosts","storage","undefined","handoffUrl","replace","toString"],"mappings":"AAAA;;;;;;;;;;;;;;;CAeC,GAED,SAASA,mBAAmB,QAA+B,mBAAe;AAC1E,SACEC,uBAAuB,EACvBC,+BAA+B,QAC1B,wBAAoB;AAE3B;;;;;;;;;;;;;;;;;;;;CAoBC,GACD,OAAO,SAASC,iBAAiBC,MAAwB;QAEzCA,eAEAA;IAHd,MAAMC,SAASC,KAAKC,SAAS,CAAC;QAC5BC,OAAO;gBAAKJ,gBAAAA,OAAOI,KAAK,YAAZJ,gBAAgB,EAAE;SAAE;QAChCK,SAASL,OAAOK,OAAO,KAAKC,YAAY,OAAON,OAAOK,OAAO;QAC7DE,UAAU,GAAEP,qBAAAA,OAAOO,UAAU,YAAjBP,qBAAqB;IACnC,EACE,sEAAsE;IACtE,kEAAkE;KACjEQ,OAAO,CAAC,MAAM,WACdA,OAAO,CAAC,WAAW,WACnBA,OAAO,CAAC,WAAW;IACtB,OACE,qBACA,CAAC,MAAM,EAAEP,OAAO,CAAC,CAAC,GAClB,+CACA,qEACA,CAAC,QAAQ,EAAEC,KAAKC,SAAS,CAACL,iCAAiC,EAAE,CAAC,GAC9D,kDACA,CAAC,EAAE,EAAEI,KAAKC,SAAS,CAACN,yBAAyB,GAAG,EAAED,oBAAoBa,QAAQ,GAAG,YAAY,CAAC,GAC9F;AAEJ"}

package/src/lib/first-touch.d.ts

@@ -0,0 +1,212 @@
+/**
+ * @license
+ * Copyright 2026 Aglyn LLC
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *   http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+/**
+ * First-touch capture: where a visitor first arrived from, kept on their
+ * device until an account is created and the platform writes it down.
+ *
+ * ## The one rule everything else follows from
+ *
+ * A visitor rarely signs up on the page they landed on, and the page they
+ * landed on is not always the marketing site. They find a guide on the docs
+ * host through a search engine, read the pricing page, then sign up on the
+ * console. Three hosts, and only the first one saw where they came from.
+ *
+ * So every surface the platform serves includes this capture, and every one
+ * of them agrees on which referrers are its own. **An internal referrer is
+ * never a first touch.** Only an external referrer, or a landing with no
+ * referrer at all, starts the record; a hop between two of our own hosts
+ * carries the record forward and never replaces it. "docs → pricing →
+ * signup" therefore still reports the search engine that started it.
+ *
+ * ## Where the record lives
+ *
+ * - **A cookie on the registrable domain** of the surface (`.example.com`),
+ *   found by asking the browser rather than by carrying a public-suffix list:
+ *   the broadest domain that accepts a cookie is the registrable one. Every
+ *   subdomain, and so every console door under it, reads the same value.
+ * - **`sessionStorage`**, when the browser refuses the cookie. It dies with
+ *   the tab and does not cross subdomains, which is the price of a browser
+ *   that refuses storage.
+ * - **Memory**, while the visitor's consent is unresolved or has been refused
+ *   for this surface. Nothing is written to the device. A link to another of
+ *   our hosts can still carry the record, sealed, in its URL (below).
+ *
+ * The cookie is re-written on every load with a fresh lifetime, because some
+ * browsers cap the life of a script-written cookie at a week of inactivity;
+ * the VALUE never changes once set.
+ *
+ * ## Crossing to a host the cookie cannot reach
+ *
+ * A surface on a different registrable domain, or any hop made while the
+ * record is held in memory, cannot read the cookie. For those links the
+ * capture asks the platform to SEAL the record (an HMAC over it and an
+ * expiry, signed with a secret no page holds) and appends the sealed token as
+ * `_ft` at the moment the link is followed. The receiving surface strips the
+ * parameter from its address bar at once, asks the platform to OPEN it, and
+ * adopts what comes back. Adoption is a merge, and the merge keeps the
+ * earlier record, so replaying a token can never move a first touch later.
+ *
+ * What the seal proves is narrow and worth stating exactly: that this install
+ * produced the record, recently, and nobody edited it on the way. It does not
+ * prove the record is TRUE — a visitor can put any `utm_*` they like on a URL
+ * and always could. Attribution is a label, and it grants nothing.
+ *
+ * ## What is never recorded
+ *
+ * No identifier. The record says how a visit began, and two visitors who
+ * arrived the same way carry the same record give or take a timestamp. Click
+ * ids are kept as PRESENCE only — "this arrived from a paid click" — and their
+ * values never leave the URL they came on. Referrers are kept as a HOST, never
+ * a path, because a referring path can carry a search query or an account
+ * page. `utm_*` values are trimmed, refused when shaped like an email
+ * address, and capped, the same scrub the signup campaign parser applies.
+ *
+ * ## Why the whole runtime is one function
+ *
+ * The same code must run as a module a Next app imports and as a script tag
+ * on a page no bundler touches (a hosted forum, a status page). So the
+ * runtime is ONE self-contained function, {@link createFirstTouchKit}, that
+ * references nothing outside itself: the served script is that function's own
+ * source text followed by a call to it. The constraint that keeps it working
+ * is the same one `next-themes` lives under — no imports, no module-level
+ * values, and no syntax a compiler would lower into a shared helper (object
+ * spread, classes, `async`). `first-touch-script.spec.ts` runs the
+ * stringified function in a bare context to hold that.
+ */
+/** Click identifiers whose PRESENCE the record keeps; their values never leave the URL. */
+export declare const FIRST_TOUCH_CLICK_IDS: readonly ["gclid", "fbclid", "msclkid"];
+export type FirstTouchClickId = (typeof FIRST_TOUCH_CLICK_IDS)[number];
+/** The `utm_*` parameters the record keeps, named without their prefix. */
+export declare const FIRST_TOUCH_UTM_KEYS: readonly ["source", "medium", "campaign", "content", "term"];
+export type FirstTouchUtmKey = (typeof FIRST_TOUCH_UTM_KEYS)[number];
+export type FirstTouchUtm = Partial<Record<FirstTouchUtmKey, string>>;
+/** The cookie the record is kept in, on the surface's registrable domain. */
+export declare const FIRST_TOUCH_COOKIE = "aglyn_ft";
+/** The query parameter a sealed hand-off rides on. */
+export declare const FIRST_TOUCH_HANDOFF_PARAM = "_ft";
+/** How a visit began, as the capture records it. */
+export interface FirstTouch {
+    /** Record format. A reader refuses any other value rather than guess. */
+    v: 1;
+    /** When the visitor landed, epoch milliseconds. */
+    at: number;
+    /** The host of the first page they landed on. */
+    host: string;
+    /** That page's path, without its query string or fragment. */
+    path: string;
+    /** The EXTERNAL host that sent them, or null when nothing external did. */
+    ref: string | null;
+    /**
+     * One of our own hosts they arrived from before any surface had recorded
+     * them — the tell of a surface that does not include the capture yet.
+     */
+    via?: string;
+    /** The `utm_*` parameters the landing URL carried. */
+    utm?: FirstTouchUtm;
+    /** Which click identifiers the landing URL carried. */
+    click?: FirstTouchClickId[];
+}
+/** What {@link FirstTouchKit.buildFirstTouch} reads a landing from. */
+export interface FirstTouchLanding {
+    /** The URL the visitor landed on. */
+    href: string;
+    /** `document.referrer` at that moment; empty when there was none. */
+    referrer?: string | null;
+    /** The hosts this install serves itself — see {@link FirstTouchConfig.hosts}. */
+    hosts: readonly string[];
+    /** The time to stamp, epoch milliseconds. */
+    now: number;
+}
+/** How a surface configures the capture. */
+export interface FirstTouchConfig {
+    /**
+     * The hosts this install serves itself. An entry is an exact host
+     * (`example.com`) or a wildcard for every subdomain of one at any depth
+     * (`*.example.com`, which does not match `example.com` itself). A leading
+     * `!` EXCLUDES what the rest of the entry names, whatever else matches it:
+     * `!*.sites.example.com` keeps customer sites served under the operator's
+     * own domain external. A referrer on an included host is internal, and the
+     * capture runs only on a page whose host is included.
+     */
+    hosts: readonly string[];
+    /**
+     * Whether this surface may keep the record on the device. `null` means the
+     * visitor's consent is not resolved yet: the record is held in memory and
+     * written the moment {@link FirstTouchRuntime.setStorage} grants it.
+     * Omitted means true, the posture of a surface with no consent gate.
+     */
+    storage?: boolean | null;
+    /**
+     * The platform endpoint that seals and opens hand-off tokens: absolute, or
+     * a path on the current origin. Without it no link is decorated and no
+     * token is adopted, and the cookie alone carries the record.
+     */
+    handoffUrl?: string | null;
+}
+/** Where the record currently lives on this page. */
+export type FirstTouchTier = 'cookie' | 'session' | 'memory';
+/** The handle a booted capture returns. */
+export interface FirstTouchRuntime {
+    /** The first touch as this page knows it, or null. */
+    read(): FirstTouch | null;
+    /** Grant, refuse or un-resolve device storage for this surface. */
+    setStorage(allowed: boolean | null): void;
+    /** Where the record lives right now, or null when there is none. */
+    tier(): FirstTouchTier | null;
+}
+/** Everything the capture does, as one closure — see the file comment for why. */
+export interface FirstTouchKit {
+    /** A bare lowercase host, or '' when the value is not one. */
+    normalizeHost(value: unknown): string;
+    /** Whether `host` is one of `hosts` — see {@link FirstTouchConfig.hosts}. */
+    isFirstPartyHost(host: unknown, hosts: readonly string[]): boolean;
+    /** The touch a landing describes, or null when the URL is not a web page. */
+    buildFirstTouch(landing: FirstTouchLanding): FirstTouch | null;
+    /**
+     * Rebuild a record from an untrusted value, keeping only known fields, each
+     * re-scrubbed; null when it is not a record. `now`, when given, refuses a
+     * record stamped more than a day into the future.
+     */
+    sanitizeFirstTouch(value: unknown, now?: number): FirstTouch | null;
+    /** The first of two records: the earlier `at` wins, and a tie keeps `a`. */
+    mergeFirstTouch(a: FirstTouch | null | undefined, b: FirstTouch | null | undefined): FirstTouch | null;
+    /** The cookie-safe text form of a record. */
+    encodeFirstTouch(touch: FirstTouch): string;
+    /** A record from its cookie text, sanitized; null for anything else. */
+    decodeFirstTouch(value: unknown): FirstTouch | null;
+    /** The record a `Cookie` header carries, for a server that receives one. */
+    readFirstTouchCookie(cookieHeader: string | null | undefined): FirstTouch | null;
+    /** Start capturing on this page. Idempotent; a second call updates the config. */
+    boot(config: FirstTouchConfig): FirstTouchRuntime;
+    /** The booted runtime's record, or whatever the device holds when none booted. */
+    read(): FirstTouch | null;
+}
+/**
+ * Build the capture. Self-contained by construction: nothing in the body may
+ * reference a value declared outside it (types are erased and do not count).
+ */
+export declare function createFirstTouchKit(): FirstTouchKit;
+export declare const normalizeFirstTouchHost: (value: unknown) => string;
+export declare const isFirstPartyHost: (host: unknown, hosts: readonly string[]) => boolean;
+export declare const buildFirstTouch: (landing: FirstTouchLanding) => FirstTouch | null;
+export declare const sanitizeFirstTouch: (value: unknown, now?: number) => FirstTouch | null;
+export declare const mergeFirstTouch: (a: FirstTouch | null | undefined, b: FirstTouch | null | undefined) => FirstTouch | null;
+export declare const encodeFirstTouch: (touch: FirstTouch) => string;
+export declare const decodeFirstTouch: (value: unknown) => FirstTouch | null;
+export declare const readFirstTouchCookie: (cookieHeader: string | null | undefined) => FirstTouch | null;
+export declare const bootFirstTouch: (config: FirstTouchConfig) => FirstTouchRuntime;
+export declare const readFirstTouch: () => FirstTouch | null;