@agenthoney/analytics 0.0.0-stage → 0.14.0

package/dist/serve/source.d.ts

@@ -0,0 +1,48 @@
+import type { ResolvedConfig } from "../core/config.js";
+import { type Twin, type TwinOptions } from "./twin.js";
+/**
+ * Where a twin comes from — and, more importantly, **what a caller is allowed
+ * to wait for.**
+ *
+ * ── ⚠️ Why this exists at all ────────────────────────────────────────────────
+ * Three adapters each called `twin.resolve(path)` and each had to know, without
+ * anything in the type saying so, whether the call they were making was allowed
+ * to touch the network. They did not know. `./express` called it on **every
+ * passing GET** to decide whether to advertise, and deferred `next()` until it
+ * settled; `./web` awaited it after the customer's handler had already built
+ * the response. With a corpus-backed resolver on a cold process, both of those
+ * were a visitor waiting on OUR ingest before their page rendered — which is
+ * the one thing this package is built not to do.
+ *
+ * So the rule is expressed as two methods instead of a comment:
+ *
+ *   - **`lookup` is synchronous and never does I/O.** Anything running on a
+ *     request that did not ask for markdown uses it. A cold process answers
+ *     `undefined`, advertises nothing, and is correct.
+ *   - **`resolve` may await, and only on a request that asked** — a `.md` path
+ *     or `Accept: text/markdown`. Bounded, and falling through to the
+ *     customer's own handler on a miss, a throw or the deadline.
+ *
+ * ⚠️ A caller cannot get this wrong by forgetting a comment any more; it gets
+ * it wrong by calling the wrong method, which is visible in a diff.
+ */
+export interface TwinSource {
+    lookup: (path: string) => Twin | undefined;
+    resolve: (path: string) => Twin | null | undefined | Promise<Twin | null | undefined>;
+    /**
+     * Load the corpus in the background. **Never awaited on a request path.**
+     *
+     * ⚠️ Handed to whatever channel the adapter already has — `after` on Next,
+     * `waitUntil` on a Worker, fire-and-forget on a long-lived Node process. It
+     * is a clock comparison in the common case, so calling it per request is
+     * cheap and calling it never is the bug: `resolve` refreshes only while the
+     * process is cold, so a corpus that is never refreshed is **frozen at its
+     * first load** — new twins never appear and withdrawals never take effect.
+     */
+    warm: () => Promise<void>;
+}
+/**
+ * ⚠️ Built ONCE per middleware, not per request. The corpus is the point: a
+ * source rebuilt per request holds nothing and refetches everything.
+ */
+export declare function twinSourceFor(twin: TwinOptions, config: ResolvedConfig): TwinSource;

package/dist/serve/tag-asset.generated.d.ts

@@ -0,0 +1,14 @@
+/**
+ * ⚠️ GENERATED by `scripts/build-tag-asset.ts` from `packages/tag/dist/t.js`.
+ * Do not edit by hand -- `tag-asset.test.ts` regenerates this and fails if the
+ * two disagree.
+ *
+ * The SDK holds the page tag as a STRING, never as an import:
+ * `@agenthoney/tag` is private and unpublished, so a surviving import would
+ * make the published SDK uninstallable and `check-sdk-artifact.mjs` refuses
+ * one anyway.
+ */
+/** The built tag, with its configuration placeholder still in place. */
+export declare const TAG_SOURCE = "\"use strict\";(()=>{var y=\"__AGENTHONEY_TAG_CONFIG__\";function l(){try{let e=JSON.parse(y);return!e||typeof e!=\"object\"||typeof e.key!=\"string\"||!e.key||typeof e.endpoint!=\"string\"||!e.endpoint||e.deny!==void 0&&!Array.isArray(e.deny)?null:e}catch{return null}}function d(e,t){if(!t||!t.length)return!1;for(let n=0;n<t.length;n+=1){let r=t[n];if(typeof r!=\"string\")continue;let i=r.trim();if(i===\"/\")return!0;let o=i.replace(/\\/+$/,\"\");if(!(!o||o.charAt(0)!==\"/\")&&(e===o||e.indexOf(`${o}/`)===0))return!0}return!1}function u(e){try{return e()}catch{return}}var T=new Set([\"SCRIPT\",\"STYLE\",\"NOSCRIPT\",\"TEMPLATE\",\"SVG\",\"CANVAS\",\"IFRAME\",\"OBJECT\",\"EMBED\",\"VIDEO\",\"AUDIO\",\"INPUT\",\"TEXTAREA\",\"SELECT\",\"OPTION\",\"BUTTON\"]),b=[\"main\",\"article\",\"[role=main]\",\"#main\",\"#content\"],v=[[/[^\\s@<>()[\\]]+@[^\\s@<>()[\\]]+\\.[a-z]{2,}/gi,\"[redacted]\"],[/\\b(?:\\d[ -]?){13,19}\\b/g,\"[redacted]\"],[/\\b\\d{9,}\\b/g,\"[redacted]\"]];function C(e){return!!(e.getAttribute(\"aria-hidden\")===\"true\"||e.hasAttribute(\"hidden\")||e.hasAttribute(\"data-agenthoney-private\"))}function E(e){var r;let t=e.cloneNode(!0),n=t.querySelectorAll(\"*\");for(let i=0;i<n.length;i+=1){let o=n[i];if(!o)continue;if(T.has(o.tagName)||C(o)){o.remove();continue}let a=o.attributes;for(let s=a.length-1;s>=0;s-=1){let c=(r=a[s])==null?void 0:r.name;c&&c!==\"href\"&&c!==\"src\"&&c!==\"alt\"&&c!==\"title\"&&o.removeAttribute(c)}}return t}function f(e){let t=e;for(let[n,r]of v)t=t.replace(n,r);return t}function g(e){return u(()=>{var i,o;let t=null;for(let a of b)if(t=e.querySelector(a),t)break;if(t||(t=e.body),!t)return;let n=E(t),r=f((i=n.textContent)!=null?i:\"\").replace(/\\s+/g,\" \").trim();if(!(r.length<200))return{html:f(n.innerHTML),title:f((o=e.title)!=null?o:\"\").slice(0,300),textLength:r.length}})}async function m(e){var t,n;try{let r=(t=globalThis.crypto)==null?void 0:t.subtle;if(!r)return;let i=new TextEncoder().encode(e),o=await r.digest(\"SHA-256\",i),a=new Uint8Array(o),s=\"\";for(let c=0;c<a.length;c+=1)s+=((n=a[c])!=null?n:0).toString(16).padStart(2,\"0\");return s}catch{return}}var A=512*1024;function w(e){try{return new URL(e).origin}catch{return}}async function h(e){try{let t=w(e.config.endpoint);if(!t)return\"failed\";let n=g(e.doc);if(!n)return\"no_content\";let r=await m(n.html);if(!r)return\"no_hash\";let i=`?k=${encodeURIComponent(e.config.key)}&p=${encodeURIComponent(e.path)}&h=${r}`,o=await e.fetchImpl(`${t}/v1/twin-state${i}`,{method:\"GET\",credentials:\"omit\",mode:\"cors\",cache:\"no-store\"});if(!o.ok)return\"failed\";let a=await o.json();if((a==null?void 0:a.want)!==!0)return\"not_wanted\";if(n.html.length>A)return\"too_large\";let s=JSON.stringify({k:e.config.key,path:e.path,contentHash:r,title:n.title,textLength:n.textLength,html:n.html});return(await e.fetchImpl(`${t}/v1/twin-content`,{method:\"POST\",credentials:\"omit\",mode:\"cors\",headers:{\"content-type\":\"text/plain;charset=UTF-8\"},body:s})).ok?\"uploaded\":\"failed\"}catch{return\"failed\"}}var p=\"0.3.0\";function x(e){let t=e.slice(),n=((...r)=>{u(()=>{t.length<128&&t.push(r)})});return n.q=t,Object.defineProperty(n,\"version\",{value:p,enumerable:!0}),Object.defineProperty(n,\"config\",{value:l(),enumerable:!0}),n}u(()=>{var n;if(typeof window==\"undefined\")return;let e=window.agenthoney,t=(n=u(()=>Array.isArray(e==null?void 0:e.q)?e.q:[]))!=null?n:[];e&&e.version===p||(window.agenthoney=x(t),S())});function S(){u(()=>{var a,s,c;let e=l();if(!e||e.harvest!==!0)return;let t=(s=(a=document.querySelector('meta[name=\"robots\"]'))==null?void 0:a.getAttribute(\"content\"))!=null?s:\"\";if(/noindex|none/i.test(t)||d(location.pathname,e.deny)||((c=navigator.connection)==null?void 0:c.saveData)===!0||typeof navigator.hardwareConcurrency==\"number\"&&navigator.hardwareConcurrency<=2)return;let r=()=>{u(()=>{h({doc:document,config:e,fetchImpl:fetch.bind(globalThis),path:location.pathname})})},i=globalThis.requestIdleCallback,o=()=>{i?i(r):setTimeout(r,2e3)};document.readyState===\"complete\"?o():window.addEventListener(\"load\",o,{once:!0,passive:!0})})}})();\n";
+/** Of the UNSUBSTITUTED source, so it identifies the build and not the site. */
+export declare const TAG_SHA256 = "0421439eca918bb309b6fdd572e7db685466fb2ae25a7a93337c52811502e7e6";

package/dist/serve/tag.d.ts

@@ -0,0 +1,131 @@
+import { TAG_SHA256 } from "./tag-asset.generated.js";
+/**
+ * Serving the page tag from the customer's own origin.
+ *
+ * ── ⚠️ Served, never injected ────────────────────────────────────────────────
+ * The obvious design is to insert a `<script>` into the HTML on the way past.
+ * It is prohibited, for three independent reasons:
+ *
+ *   1. It is **body rewriting**. `res` is a single-read stream; monkey-patching
+ *      `write`/`end` to splice a tag in adds latency, adds memory, and can
+ *      corrupt what the customer sends. This middleware has no body path at all
+ *      today and must not grow one.
+ *   2. An **inline script breaks a nonce-based CSP**. That is not hypothetical
+ *      -- **R6** is written down about Cloudflare's Scrape Shield doing exactly
+ *      this. An external SAME-ORIGIN script satisfies `script-src 'self'` with
+ *      no nonce at all.
+ *   3. Injection would make the tag impossible to remove without removing the
+ *      middleware, which is the wrong kill switch for the half that runs in
+ *      somebody else's browser.
+ *
+ * So: the adapter serves the file, and the customer writes one `<script async>`
+ * themselves. Serving it ourselves is what lets the configuration be baked into
+ * the bytes, so their HTML has nothing in it that can be pasted wrong -- which
+ * matters more here than it would elsewhere, because this product's real
+ * install path is an AI coding agent reading `/install.md`.
+ *
+ * ── ⚠️ First-party, so no third-party origin is involved ─────────────────────
+ * Same-origin means no extra DNS, no extra TLS, no `*.agenthoney.ai` in the
+ * customer's `script-src`, and nothing for a tracker blocker to match on the
+ * script itself.
+ */
+/** ⚠️ Must match `RAW` in `packages/tag/src/config.ts`. */
+declare const TAG_CONFIG_PLACEHOLDER = "__AGENTHONEY_TAG_CONFIG__";
+/** Where the adapters serve it. Underscored so it cannot collide with a route. */
+export declare const TAG_PATH = "/_agenthoney/t.js";
+export interface TagOptions {
+    /**
+     * The site's PUBLIC key, `ep_live_public_…`.
+     *
+     * ⚠️ Not a secret, and cannot be made one -- it is served inside this file to
+     * anyone who asks. What makes that safe is the class: `authenticate()` in
+     * ingest requires `server` on `/v1/events`, so a public key cannot write
+     * events. Never put `AGENTHONEY_SERVER_KEY` here; the SDK's own
+     * `check-browser-safety.mjs` exists to stop that value reaching a browser.
+     */
+    publicKey: string;
+    /**
+     * Where the tag will post. An ORIGIN; the tag appends its own paths.
+     * Defaults to the origin of the SDK's configured ingest URL.
+     */
+    endpoint?: string;
+    /**
+     * Let the tag read this site's rendered pages and offer them as twins.
+     *
+     * ⚠️ **Site-level, and off by default.** The plan for this phase said the
+     * middleware would refuse harvesting per request -- when the request carried
+     * a session cookie or an `Authorization` header -- and that is **not
+     * implementable**: this file is one shared artifact, cached, served to every
+     * visitor. A flag baked into it cannot describe the request that will later
+     * load a page. Discovering that late is exactly why it is written here.
+     *
+     * What actually protects a signed-in visitor's page is the consensus gate:
+     * nothing is published until several DISTINCT anonymous visitors
+     * independently produced the same content, so personalised and authenticated
+     * pages never converge. The tag additionally skips any page the site itself
+     * marks `noindex`, which is the owner saying "not for machines" in the one
+     * place they already say it.
+     */
+    harvest?: boolean;
+    /**
+     * Path prefixes the tag must never read on this site.
+     *
+     * ⚠️ **A deny list, not an allow list, and the difference is whether anybody
+     * will fill it in.** An allow list asks a client-rendered site's operator
+     * for a complete route inventory -- which is the hand-authoring burden the
+     * tag exists to remove -- while this asks only for the prefixes a signed-in
+     * user lands on, which an operator knows without looking anything up.
+     *
+     * ⚠️ Enforced again at ingest from the SITE's own record, because this file
+     * is cached for five minutes and by whatever CDN fronts it. What is baked in
+     * here saves the browser the work; what is on the server is the control.
+     */
+    harvestDeny?: readonly string[];
+    /**
+     * ⚠️ Short on purpose. A revoked public key must stop being handed out, and a
+     * long cache on the file that CONTAINS it would make revocation meaningless.
+     * Five minutes is long enough to matter for a busy site and short enough that
+     * a rotation takes effect while somebody is still watching.
+     */
+    cacheControl?: string;
+}
+/**
+ * Where the tag will post, derived from the SDK's own ingest URL.
+ *
+ * ⚠️ Derived rather than defaulted to a constant, so a customer pointed at a
+ * staging ingest does not have their browser traffic silently going to
+ * production.
+ *
+ * ⚠️ **An ORIGIN, and it used to be a route that does not exist.** This
+ * returned `<origin>/v1/signals` until Phase 35, and the install guide told
+ * every customer to construct that path by hand. Ingest has never served it.
+ * Nothing broke, because the tag takes `new URL(endpoint).origin` and appends
+ * its own paths -- so the wrong half was silently discarded on every page load,
+ * and the guide taught a URL that 404s if anyone ever fetched it. That is the
+ * same silent-misconfiguration shape the bare-origin `ingestUrl` bug had in
+ * Phase 32, and it is corrected the same way: emit the thing that is true.
+ *
+ * Returns `""` when there is nothing to derive from, and the caller treats that
+ * as "do not serve the tag" -- a tag with no endpoint is a file that runs in
+ * somebody's browser for no reason.
+ */
+export declare function tagEndpointFor(ingestUrl: string): string;
+export interface RenderedTag {
+    body: string;
+    headers: Record<string, string>;
+}
+/**
+ * ⚠️ Throws on a placeholder count that is not exactly one, rather than serving
+ * a best-effort file.
+ *
+ * Zero would mean a build that eliminated the placeholder, and every visitor
+ * would run an inert tag that reports nothing -- a silent, total failure that
+ * looks exactly like "no traffic". More than one would mean substituting
+ * something that was not meant to be substituted. Both are bugs in OUR build,
+ * caught here at wiring time; the caller wraps this so a throw can never reach
+ * the customer's response.
+ */
+export declare function renderTag(options: TagOptions & {
+    endpoint: string;
+}): RenderedTag;
+export { TAG_CONFIG_PLACEHOLDER, TAG_SHA256 };

package/dist/serve/twin.d.ts

@@ -0,0 +1,162 @@
+/**
+ * The markdown twin: the decision, as a pure function.
+ *
+ * ── Why the decision is separated from the serving ───────────────────────────
+ * Two adapters have to make the identical choice, and the choice is the part
+ * with consequences -- serve the wrong thing and a human gets a text file
+ * instead of a website. One function, one set of tests, two thin call sites.
+ */
+export interface Twin {
+    body: string;
+    /** Defaults to `text/markdown; charset=utf-8`. */
+    contentType?: string;
+    etag?: string;
+    lastModified?: string;
+}
+export type TwinResolver = (path: string) => Twin | null | undefined | Promise<Twin | null | undefined>;
+/**
+ * Serve twins from the corpus this site's own visitors wrote.
+ *
+ * ⚠️ **`true` is the whole configuration.** The server key and ingest URL are
+ * already in `AgentHoneyConfig` for the observe half, so a corpus-backed
+ * install is one word rather than the lazy singleton, the `waitUntil` and the
+ * hand-wired resolver that `apps/www` had to assemble -- which, until Phase 49,
+ * was the only place anyone had ever done it, because `hostedTwins` appeared in
+ * exactly zero customer-facing documents.
+ *
+ * ⚠️ **It stays OPT-IN even though we know the key.** Turning it on changes
+ * what a visitor receives under the customer's own domain, and doing that
+ * because somebody took a patch upgrade is not a thing this package does.
+ */
+export type HostedTwinOptions = true | {
+    /** Defaults to the SDK's configured server key. */
+    serverKey?: string;
+    /** Defaults to the SDK's configured ingest URL. */
+    ingestUrl?: string;
+    /** How stale the in-memory set may get. Default five minutes. */
+    refreshMs?: number;
+    /** The ceiling on the one await a COLD process is allowed. */
+    coldTimeoutMs?: number;
+    /** How long a failed refresh holds off the next. Default thirty seconds. */
+    failureBackoffMs?: number;
+    /** The ceiling on a single refresh's network call. Default five seconds. */
+    refreshTimeoutMs?: number;
+    /** Injected for tests. */
+    fetchImpl?: typeof fetch;
+};
+interface TwinOptionsBase {
+    /** `Cache-Control` for a served twin. Edge-cacheable by default. */
+    cacheControl?: string;
+    /** Advertise an available twin on the HTML response. Default true. */
+    advertise?: boolean;
+    /**
+     * Serve `/llms.txt`, `/llms-full.txt` and `/install.md` from the same
+     * manifest that serves the twins.
+     *
+     * ⚠️ Derived, not written: a hand-maintained index is wrong the first time a
+     * page is added, and an index listing pages that no longer exist is worse
+     * than none -- an agent spends its budget on 404s and concludes the site is
+     * broken.
+     */
+    discovery?: import("./discovery.js").DiscoveryOptions;
+}
+/**
+ * ⚠️ **A union, so each half is sufficient alone and neither loses its type.**
+ *
+ * `resolve` is for a site that already HAS markdown; `hosted` is for one whose
+ * twins were written by its own visitors. Supplying both is allowed and
+ * `resolve` wins -- authored markdown beats harvested markdown, every time,
+ * because the customer wrote one of them on purpose.
+ *
+ * ⚠️ This widens a published surface rather than retyping one: every existing
+ * caller passes `resolve` and keeps working, which is what the append-only rule
+ * requires.
+ */
+export type TwinOptions = TwinOptionsBase & ({
+    /**
+     * Find the twin for a normalised path, or return null.
+     *
+     * ⚠️ **Registered, not derived.** Returning a twin for any path that
+     * "looks like" it should have one produces a site where every URL
+     * answers, including the typos -- caprail.dev returns a plain 404 for
+     * an unregistered `.md`, and that is the behaviour to match.
+     */
+    resolve: TwinResolver;
+    hosted?: HostedTwinOptions;
+} | {
+    resolve?: TwinResolver;
+    hosted: HostedTwinOptions;
+});
+/** Paths the discovery block answers, when it is configured. */
+export declare const DISCOVERY_PATHS: readonly ["/llms.txt", "/llms-full.txt", "/install.md"];
+export declare const DEFAULT_TWIN_CONTENT_TYPE = "text/markdown; charset=utf-8";
+export declare const DEFAULT_TWIN_CACHE_CONTROL = "public, max-age=3600, s-maxage=86400";
+export type TwinDecision = 
+/** Serve the twin for `lookupPath`. */
+{
+    action: "serve";
+    lookupPath: string;
+    reason: "md_path" | "accept_header";
+}
+/** Not ours to answer, but a twin may exist worth advertising. */
+ | {
+    action: "pass";
+    reason: "not_get" | "no_signal";
+};
+/**
+ * Map a request onto a decision. Nothing here touches I/O.
+ *
+ * Two gates, and only two:
+ *   1. the path ends in `.md`  -- a distinct resource, no negotiation at all;
+ *   2. `Accept` explicitly prefers markdown -- content negotiation, which owes
+ *      a `Vary: Accept`.
+ *
+ * ⚠️ Never the User-Agent. See `accept.ts`.
+ */
+export declare function decideTwin(input: {
+    method: string;
+    path: string;
+    accept: string | null | undefined;
+}): TwinDecision;
+/**
+ * `/docs/intro.md` -> `/docs/intro`, and `/index.md` -> `/`.
+ *
+ * The root is the case worth naming: a site's home page has no slug, so its
+ * twin is `/index.md` by convention -- the same convention caprail.dev uses.
+ */
+export declare function stripMdSuffix(path: string): string;
+/** `/docs/intro` -> `/docs/intro.md`, and `/` -> `/index.md`. */
+export declare function twinPathFor(path: string): string;
+export interface TwinResponse {
+    status: number;
+    headers: Record<string, string>;
+    body: string;
+}
+export declare function buildTwinResponse(twin: Twin, decision: Extract<TwinDecision, {
+    action: "serve";
+}>, options: TwinOptions): TwinResponse;
+/**
+ * The advertisement for an available twin, as a `Link` header.
+ *
+ * ⚠️ **A header, not a tag injected into the HTML.** Caprail puts
+ * `<link rel="alternate">` in its own document head, which it can do because it
+ * owns the template. A middleware cannot: injecting into the body means
+ * buffering and rewriting somebody else's response, which is precisely what
+ * this package refuses to do. RFC 8288 makes the header the equivalent, it
+ * costs nothing, and it works for JSON and plain text as well as HTML.
+ *
+ * A customer who also wants the tag can add it to their own template, and
+ * should -- some crawlers read one and not the other.
+ */
+/**
+ * Is a resolver's answer a promise?
+ *
+ * ⚠️ **Asked so that the ADVERTISE path can decline to wait.** `resolve` may
+ * return a value or a promise, and the difference decides whether a caller is
+ * allowed to use the answer: a request that has not asked for markdown must
+ * never be delayed for one. Duck-typed rather than `instanceof Promise`,
+ * because a customer's resolver may return a thenable from any library.
+ */
+export declare function isThenable<T>(value: T | Promise<T>): value is Promise<T>;
+export declare function advertiseHeader(path: string): string;
+export {};