@aglyn/aglyn 1.0.0-beta.143

package/src/lib/app-utils/agent-openapi.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../../../../../libs/aglyn/src/lib/app-utils/agent-openapi.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\n/**\n * `/openapi.json` for a tenant site (AGL-2716) — the machine-readable\n * description of what a site serves, per host.\n *\n * ## Why this is generated and not a checked-in file\n *\n * The document is a function of the SITE: its name, its origin, the content\n * collections it publishes. A static file would describe one site, and every\n * other host on the platform would publish a spec naming somebody else's\n * domain in `servers[]` — which is worse than no spec, because a client that\n * trusts it makes requests to the wrong origin.\n *\n * ## Read-only, deliberately\n *\n * Only GET operations are described. The tenant does serve writes — form\n * submissions, membership, consent — and each is reachable, rate-limited and\n * public, so listing them would be truthful. It would also be an invitation:\n * a spec is a list of things to call, an agent that reads one calls them, and\n * \"submit this form\" is not an operation a site owner asked to publish to\n * every crawler on the internet. Writes stay discoverable the way they always\n * were, from the page that carries the form.\n *\n * That decision belongs in the document, not just in this comment, so the\n * `description` says so — a reader who needs a write endpoint is told where to\n * look rather than left assuming none exists.\n *\n * ## Shaped for function calling\n *\n * Every operation carries a unique `operationId`, a `summary`, a `description`\n * and typed parameters, and every response names a schema. That is exactly the\n * subset an LLM tool-calling bridge reads when it turns a spec into callable\n * functions — a missing `operationId` becomes a generated name nobody can\n * predict, and a missing parameter type becomes a string the model guesses at.\n *\n * OpenAPI **3.1.0** rather than 3.0: 3.1 aligns its schema dialect with JSON\n * Schema 2020-12, which is the dialect the function-calling formats already\n * speak, so a bridge converts without a lossy pass.\n */\n\n/** A content collection the site publishes, as the feed operation names it. */\nexport interface AgentOpenApiCollection {\n  slug: string\n  name?: string\n}\n\nexport interface AgentOpenApiOptions {\n  /** The site's name, for `info.title`. */\n  siteName: string\n  /** Absolute origin, no trailing slash — the single `servers[]` entry. */\n  origin: string\n  /** The site's own description, for `info.description`. */\n  description?: string\n  /** Published content collections, for the feed operation's enum. */\n  collections?: readonly AgentOpenApiCollection[]\n  /** Whether the site serves `/search`. */\n  hasSearch?: boolean\n  /** Platform version, so a consumer can tell two documents apart. */\n  version?: string\n  /** Contact email published in `info.contact`, when the site has one. */\n  contactEmail?: string\n  /** Absolute URL of the site's terms, when it publishes any. */\n  termsOfServiceUrl?: string\n}\n\nimport { API_CATALOG_MEDIA_TYPE } from './agent-api-catalog'\n\n/** A JSON-Schema-shaped object; loose on purpose — this is a document, not a type. */\ntype Schema = Record<string, unknown>\n\n/** `text/markdown`, per RFC 7763. */\nconst MARKDOWN = 'text/markdown'\n\n/**\n * The header that carries the API version, in both directions (AGL-2722).\n *\n * A header and not a URL segment, because most of this surface sits at a\n * location some other specification fixed — `/openapi.json`, `/robots.txt`,\n * `/llms.txt`, `/sitemap.xml`, `/manifest.webmanifest`. `/v1/robots.txt` is\n * not a robots.txt: the crawler that needs it looks at the root and nowhere\n * else. Versioning only the `/api/*` half would leave one surface running two\n * rules, which is worse than either rule alone.\n */\nexport const API_VERSION_HEADER = 'Aglyn-API-Version'\n\n/**\n * The version this description and these responses are.\n *\n * ⚠️ Independent of the platform's release version, and deliberately so. The\n * platform ships several times a day; this shape is a promise to strangers and\n * moves only when the promise does. Bump it when a field is removed or\n * renamed, or when an operation narrows what it accepts — never for an\n * addition, which is why a consumer is told to parse leniently.\n */\nexport const API_VERSION = '1.0.0'\n\n/**\n * The RFC 9331 headers, and the 429, for the two operations that actually\n * meter (AGL-2722).\n *\n * Declared on those two only, never blanket-applied. `/api/health` is an\n * uptime probe answering from several regions on a schedule — metering it\n * would turn a bookkeeping limit into a false outage — and the static files\n * are served from the edge cache without ever reaching a counter. A header\n * describing a limit that is not enforced is worse than no header, because a\n * caller paces against it.\n */\nconst RATE_LIMIT_HEADERS: Schema = {\n  'RateLimit-Limit': { $ref: '#/components/headers/RateLimitLimit' },\n  'RateLimit-Remaining': { $ref: '#/components/headers/RateLimitRemaining' },\n  'RateLimit-Reset': { $ref: '#/components/headers/RateLimitReset' },\n}\n\nconst TOO_MANY_REQUESTS: Schema = {\n  description:\n    'The address exceeded its per-minute budget. `Retry-After` names the ' +\n    'seconds to wait. Reaching this from ordinary reading would be ' +\n    'surprising — the budget is set well above what reading a whole site ' +\n    'costs.',\n  headers: {\n    ...RATE_LIMIT_HEADERS,\n    'Retry-After': { $ref: '#/components/headers/RetryAfter' },\n  },\n  content: {\n    'application/json': { schema: { $ref: '#/components/schemas/Error' } },\n  },\n}\n\n/**\n * The `Accept` parameter, declared once and referenced by every page\n * operation.\n *\n * A header parameter rather than prose, because it is the ONLY way a client\n * discovers the Markdown representation from the document alone — and a\n * function-calling bridge that reads this turns it into an argument the model\n * can set, which is the whole point of publishing it.\n */\nconst ACCEPT_PARAMETER: Schema = {\n  name: 'Accept',\n  in: 'header',\n  required: false,\n  description:\n    'Content negotiation, per RFC 9110. `text/markdown` returns a clean ' +\n    'Markdown rendering of the page with the navigation, styling and scripts ' +\n    'removed; anything else returns HTML. Quality values are honored, and a ' +\n    'request that accepts neither representation is answered `406`. ' +\n    'Responses carry `Vary: Accept`.',\n  schema: {\n    type: 'string',\n    enum: ['text/html', MARKDOWN],\n    default: 'text/html',\n  },\n}\n\n/** Error envelope shared by the JSON operations. */\nconst ERROR_SCHEMA: Schema = {\n  type: 'object',\n  description: 'The error envelope every JSON endpoint on this site returns.',\n  properties: {\n    status: { type: 'string', enum: ['error'], description: 'Always `error`.' },\n    statusMessage: { type: 'string', description: 'Human-readable reason.' },\n    errorCode: { type: 'string', description: 'Stable machine-readable code.' },\n  },\n  required: ['status'],\n}\n\n/** The `seo` block both the site and page schemas carry. */\nconst SEO_SCHEMA: Schema = {\n  type: 'object',\n  description: 'Search and social metadata.',\n  properties: {\n    title: { type: 'string', description: 'Title used in the page head.' },\n    description: { type: 'string', description: 'Meta description.' },\n    image: { type: 'string', description: 'Social card image reference.' },\n    imageWidth: { type: 'integer', description: 'Social card width in pixels.' },\n    imageHeight: { type: 'integer', description: 'Social card height in pixels.' },\n    imageAlt: {\n      type: 'string',\n      description: 'Alternative text for the social card image.',\n    },\n  },\n}\n\n/** Build the OpenAPI 3.1 document for one site. */\nexport function buildAgentOpenApi(options: AgentOpenApiOptions): Schema {\n  const origin = options.origin.replace(/\\/+$/, '')\n  const collections = options.collections ?? []\n  const collectionSlugs = collections.map((collection) => collection.slug)\n\n  const paths: Schema = {\n    '/openapi.json': {\n      get: {\n        operationId: 'getOpenApiDocument',\n        summary: 'This document',\n        description:\n          'The OpenAPI 3.1 description of everything this site serves. ' +\n          'Generated per site, so `servers[0].url` always names this origin.',\n        tags: ['Discovery'],\n        responses: {\n          '200': {\n            description: 'The OpenAPI document.',\n            content: {\n              'application/json': {\n                schema: { $ref: '#/components/schemas/OpenApiDocument' },\n              },\n            },\n          },\n        },\n      },\n    },\n    '/.well-known/api-catalog': {\n      get: {\n        operationId: 'getApiCatalog',\n        summary: 'API catalog',\n        description:\n          'Every API that answers for this site, as an RFC 9727 catalog in ' +\n          'RFC 9264 linkset form. Two of them exist and they are not ' +\n          'interchangeable: this site’s own API, described by the document ' +\n          'you are reading, is anonymous and read-only; the platform API it ' +\n          'names is keyed, typed and writes. Each entry carries the API’s ' +\n          '`service-desc` (its OpenAPI description), `service-doc` and, where ' +\n          'there is one, `status`.',\n        tags: ['Discovery'],\n        responses: {\n          '200': {\n            description: 'The catalog.',\n            content: {\n              [API_CATALOG_MEDIA_TYPE]: {\n                schema: { $ref: '#/components/schemas/ApiCatalog' },\n              },\n            },\n          },\n        },\n      },\n    },\n    '/llms.txt': {\n      get: {\n        operationId: 'getAgentGuidance',\n        summary: 'Agent guidance (llms.txt)',\n        description:\n          'What this site is for, when an agent should reach for it, and the ' +\n          'entry points that lead to everything else. Follows the ' +\n          'llmstxt.org format: an H1 name, a summary blockquote, and ' +\n          'H2-delimited link lists.',\n        tags: ['Discovery'],\n        responses: {\n          '200': {\n            description: 'The guidance file.',\n            content: { [MARKDOWN]: { schema: { type: 'string' } } },\n          },\n        },\n      },\n    },\n    '/robots.txt': {\n      get: {\n        operationId: 'getRobotsTxt',\n        summary: 'Crawler policy',\n        description:\n          'The exclusion rules this site asks crawlers to honor, and the ' +\n          'address of its sitemap index.',\n        tags: ['Discovery'],\n        responses: {\n          '200': {\n            description: 'The robots policy.',\n            content: { 'text/plain': { schema: { type: 'string' } } },\n          },\n        },\n      },\n    },\n    '/sitemap.xml': {\n      get: {\n        operationId: 'getSitemapIndex',\n        summary: 'Sitemap index',\n        description:\n          'A sitemap INDEX — it names child sitemaps rather than URLs. Each ' +\n          'child lists up to 5,000 URLs with their last-modified dates.',\n        tags: ['Discovery'],\n        responses: {\n          '200': {\n            description: 'A `<sitemapindex>` document.',\n            content: { 'application/xml': { schema: { type: 'string' } } },\n          },\n        },\n      },\n    },\n    '/manifest.webmanifest': {\n      get: {\n        operationId: 'getWebAppManifest',\n        summary: 'Web app manifest',\n        description: \"The site's installable web app manifest.\",\n        tags: ['Discovery'],\n        responses: {\n          '200': {\n            description: 'The manifest.',\n            content: {\n              'application/manifest+json': {\n                schema: { $ref: '#/components/schemas/WebAppManifest' },\n              },\n            },\n          },\n        },\n      },\n    },\n    '/{path}': {\n      get: {\n        operationId: 'getPage',\n        summary: 'Fetch one page',\n        description:\n          'Any page on this site, in HTML or Markdown. `path` is the page ' +\n          'path without a leading slash — use an empty string for the home ' +\n          'page — and MAY contain `/` for a nested page. Two ways to ask for ' +\n          'Markdown: send `Accept: text/markdown`, or append `.md` to the ' +\n          'path. Enumerate the available paths with `listPublishedPages` or ' +\n          'from the sitemap index.',\n        tags: ['Content'],\n        parameters: [\n          {\n            name: 'path',\n            in: 'path',\n            required: true,\n            description:\n              'Page path without a leading slash, e.g. `pricing` or ' +\n              '`blog/hello-world`. May end in `.md` to request Markdown ' +\n              'without a content-negotiation header.',\n            schema: { type: 'string' },\n            example: 'pricing',\n          },\n          ACCEPT_PARAMETER,\n        ],\n        responses: {\n          '200': {\n            description: 'The page.',\n            headers: {\n              Vary: {\n                description:\n                  'Includes `Accept`, so a cache cannot serve one ' +\n                  'representation in answer to a request for the other.',\n                schema: { type: 'string' },\n              },\n            },\n            content: {\n              'text/html': { schema: { type: 'string' } },\n              [MARKDOWN]: {\n                schema: {\n                  type: 'string',\n                  description:\n                    'The page as Markdown: an H1 title, a blockquote ' +\n                    'summary, the content region, and a `Source:` line ' +\n                    'carrying the canonical URL. Navigation and footer are ' +\n                    'omitted.',\n                },\n              },\n            },\n          },\n          '404': { description: 'No page answers at that path.' },\n          '406': {\n            description:\n              'The request accepts neither `text/html` nor `text/markdown`. ' +\n              'The body lists the representations that are available.',\n            content: { 'text/plain': { schema: { type: 'string' } } },\n          },\n        },\n      },\n    },\n    '/api/host': {\n      get: {\n        operationId: 'getSiteIdentity',\n        summary: 'Who publishes this site',\n        description:\n          \"The site's public identity: display name, logo, locales and the \" +\n          'search/social metadata it defaults to. Anonymous, cacheable, and ' +\n          'an allow-listed projection — never the underlying document.',\n        tags: ['Site'],\n        parameters: [\n          {\n            name: 'host',\n            in: 'query',\n            required: false,\n            description:\n              // NO PLATFORM APEX HERE. This string is published in the\n              // OpenAPI document of EVERY site, including a self-hosted\n              // operator's — naming Aglyn's own apex would tell their callers\n              // to address a domain that is not theirs (the self-host ratchet\n              // in `selfhost-hardcoded-hosts.spec.ts` is what caught it).\n              'Which site to describe: its custom domain, its platform ' +\n              'subdomain address, or its bare subdomain. ' +\n              'Defaults to the domain the request was sent to, so an agent ' +\n              'talking to one site never needs it.',\n            schema: { type: 'string' },\n          },\n        ],\n        responses: {\n          '200': {\n            description: 'The site identity.',\n            content: {\n              'application/json': {\n                schema: {\n                  type: 'object',\n                  properties: {\n                    status: { type: 'string', enum: ['success'] },\n                    data: {\n                      type: 'object',\n                      properties: {\n                        host: { $ref: '#/components/schemas/SiteIdentity' },\n                      },\n                    },\n                  },\n                  required: ['status'],\n                },\n              },\n            },\n          },\n          '400': {\n            description: 'The site could not be resolved.',\n            content: {\n              'application/json': { schema: { $ref: '#/components/schemas/Error' } },\n            },\n          },\n        },\n      },\n    },\n    '/api/screen': {\n      get: {\n        operationId: 'listPublishedPages',\n        summary: 'List published pages',\n        description:\n          'Every published, indexable page on this site, with its title, ' +\n          'description and dates. Gated pages — private, password-protected, ' +\n          'members-only and unlisted — are omitted, so this listing never ' +\n          'advertises an address a visitor cannot open. Paginate by passing ' +\n          'the previous response’s `cursor`; an empty cursor means the last ' +\n          'page.',\n        tags: ['Content'],\n        parameters: [\n          {\n            name: 'host',\n            in: 'query',\n            required: false,\n            description:\n              'Which site to list. Defaults to the domain the request was ' +\n              'sent to.',\n            schema: { type: 'string' },\n          },\n          {\n            name: 'cursor',\n            in: 'query',\n            required: false,\n            description:\n              'Cursor from the previous response. Omit for the first page.',\n            schema: { type: 'string' },\n          },\n          {\n            name: 'limit',\n            in: 'query',\n            required: false,\n            description: 'Pages per response.',\n            schema: { type: 'integer', minimum: 1, maximum: 100, default: 50 },\n          },\n        ],\n        responses: {\n          '200': {\n            description: 'One page of the listing.',\n            content: {\n              'application/json': {\n                schema: {\n                  type: 'object',\n                  properties: {\n                    status: { type: 'string', enum: ['success'] },\n                    data: {\n                      type: 'object',\n                      properties: {\n                        screens: {\n                          type: 'array',\n                          items: { $ref: '#/components/schemas/PublishedPage' },\n                        },\n                        cursor: {\n                          type: 'string',\n                          description:\n                            'Cursor for the next request; empty on the last page.',\n                        },\n                      },\n                      required: ['screens', 'cursor'],\n                    },\n                  },\n                  required: ['status'],\n                },\n              },\n            },\n          },\n          '400': {\n            description: 'The site could not be resolved.',\n            content: {\n              'application/json': { schema: { $ref: '#/components/schemas/Error' } },\n            },\n          },\n        },\n      },\n    },\n    '/api/health': {\n      get: {\n        operationId: 'getSiteHealth',\n        summary: 'Service health',\n        description:\n          'Whether the site runtime and its datastore are answering. `200` ' +\n          'when healthy, `503` when not; the body names which check failed.',\n        tags: ['Site'],\n        responses: {\n          '200': {\n            description: 'Healthy.',\n            content: {\n              'application/json': { schema: { $ref: '#/components/schemas/Health' } },\n            },\n          },\n          '503': {\n            description: 'A dependency is unavailable.',\n            content: {\n              'application/json': { schema: { $ref: '#/components/schemas/Health' } },\n            },\n          },\n        },\n      },\n    },\n  }\n\n  /*\n    The feed operation exists only where a feed does. A site with no content\n    collection has no `/{slug}/rss.xml` to serve, and publishing the operation\n    anyway would put an endpoint in the document that answers 404 — the one\n    defect that makes a client distrust the rest of the spec.\n  */\n  if (collectionSlugs.length > 0) {\n    paths['/{collectionSlug}/rss.xml'] = {\n      get: {\n        operationId: 'getCollectionFeed',\n        summary: 'Collection feed',\n        description:\n          \"A content collection's newest entries as RSS 2.0, newest first.\",\n        tags: ['Content'],\n        parameters: [\n          {\n            name: 'collectionSlug',\n            in: 'path',\n            required: true,\n            description: 'Which collection to read.',\n            // An enum rather than a bare string: this site's collections are\n            // known here, and a function-calling bridge turns an enum into a\n            // constrained argument the model cannot get wrong.\n            schema: { type: 'string', enum: collectionSlugs },\n            example: collectionSlugs[0],\n          },\n        ],\n        responses: {\n          '200': {\n            description: 'An RSS 2.0 document.',\n            content: { 'application/rss+xml': { schema: { type: 'string' } } },\n          },\n          '404': { description: 'No collection answers at that slug.' },\n        },\n      },\n    }\n  }\n\n  if (options.hasSearch) {\n    paths['/search'] = {\n      get: {\n        operationId: 'searchSite',\n        summary: 'Search this site',\n        description:\n          \"Full-text search across this site's published pages and content \" +\n          'entries. HTML only — unlike every other page here, the results are ' +\n          'computed in the browser, so a Markdown variant would be a heading ' +\n          'with no results under it. To read the matches as Markdown, follow ' +\n          'the result links and fetch each page with `Accept: text/markdown`.',\n        tags: ['Content'],\n        parameters: [\n          {\n            name: 'q',\n            in: 'query',\n            required: true,\n            description: 'The query.',\n            schema: { type: 'string', minLength: 1 },\n          },\n        ],\n        responses: {\n          '200': {\n            description: 'The results page.',\n            content: { 'text/html': { schema: { type: 'string' } } },\n          },\n        },\n      },\n    }\n  }\n\n  const info: Schema = {\n    title: `${options.siteName} — public API`,\n    /*\n      The CONTRACT version, not the build. `info.version` carrying the platform\n      release meant it changed several times a day, so a consumer reading it as\n      \"the shape I was built against\" was tracking deploy noise and had nothing\n      to pin. The build identifier keeps its purpose — telling two documents\n      apart — under its own key.\n    */\n    version: API_VERSION,\n    ...(options.version ? { 'x-aglyn-platform-version': options.version } : {}),\n    summary: `Everything ${options.siteName} publishes for machine consumption.`,\n    description:\n      `The read-only surface of ${options.siteName}. Every operation is ` +\n      'anonymous — no key, no session — and every page can be fetched as ' +\n      'Markdown instead of HTML by sending `Accept: text/markdown` or by ' +\n      'appending `.md` to its path.\\n\\n' +\n      'Write endpoints are deliberately not described here. This site does ' +\n      'accept form submissions and account actions, but those belong to the ' +\n      'page that carries them rather than to a spec published to every ' +\n      'crawler; follow the form on the relevant page.\\n\\n' +\n      `Start at [/llms.txt](${origin}/llms.txt) for what this site is for, ` +\n      `or [/sitemap.xml](${origin}/sitemap.xml) for every indexable URL.\\n\\n` +\n      '## Versioning and deprecation\\n\\n' +\n      'This surface is versioned by HEADER, not by URL. Send ' +\n      `\\`${API_VERSION_HEADER}: ${API_VERSION}\\` to pin the shape you were ` +\n      'built against; omit it and you get the current version. Every ' +\n      `response names the version that served it in the same header.\\n\\n` +\n      'A path version was the alternative and it does not fit this surface: ' +\n      'most of what is described here lives at a location some other ' +\n      'specification fixed — `/openapi.json`, `/robots.txt`, `/llms.txt`, ' +\n      '`/sitemap.xml`, `/manifest.webmanifest`. Moving those under `/v1/` ' +\n      'would break the specs that define them, and versioning only the ' +\n      '`/api/*` half would leave one surface with two rules.\\n\\n' +\n      'Additive changes — a new operation, a new optional field — ship ' +\n      'without a version bump, so parse leniently and ignore what you do ' +\n      'not recognise. Anything that removes or renames a field, or narrows ' +\n      'what an operation accepts, does bump it.\\n\\n' +\n      'Removal is announced on the responses themselves, not only in a ' +\n      'changelog. A deprecated operation answers with `Deprecation` (RFC ' +\n      '9745) from the moment it is deprecated, and `Sunset` (RFC 8594) ' +\n      'naming the date it stops answering. Both are HTTP dates. An ' +\n      'operation that has never carried either is not scheduled for ' +\n      'removal.',\n    ...(options.contactEmail\n      ? { contact: { name: options.siteName, email: options.contactEmail } }\n      : {}),\n    ...(options.termsOfServiceUrl ? { termsOfService: options.termsOfServiceUrl } : {}),\n  }\n\n  /*\n    Every response names the version that served it and declares the two\n    headers a removal is announced on; every operation accepts the version\n    request header. Attached by a walk rather than written into each operation\n    by hand — a policy stated in `info` and then missing from an operation is\n    not a policy, and eleven hand-copied blocks is exactly how that happens.\n  */\n  const versionedHeaders: Schema = {\n    [API_VERSION_HEADER]: { $ref: '#/components/headers/ApiVersion' },\n    Deprecation: { $ref: '#/components/headers/Deprecation' },\n    Sunset: { $ref: '#/components/headers/Sunset' },\n  }\n  /** The paths `publicReadApiGate` actually meters. Kept in step by AGL-2722's spec. */\n  const METERED = new Set(['/api/host', '/api/screen'])\n  for (const [pathName, pathItem] of Object.entries(paths as Record<string, Schema>)) {\n    const metered = METERED.has(pathName)\n    for (const operation of Object.values(pathItem)) {\n      if (!operation || typeof operation !== 'object') continue\n      const verb = operation as Schema\n      const responses = verb.responses as Record<string, Schema> | undefined\n      if (!responses) continue\n      if (metered && !responses['429']) responses['429'] = { ...TOO_MANY_REQUESTS }\n      for (const response of Object.values(responses)) {\n        // The operation's own headers win: a walk that overwrote them would\n        // silently drop something an operation deliberately said.\n        response.headers = {\n          ...versionedHeaders,\n          ...(metered ? RATE_LIMIT_HEADERS : {}),\n          ...((response.headers as Schema) ?? {}),\n        }\n      }\n      verb.parameters = [\n        ...((verb.parameters as unknown[]) ?? []),\n        { $ref: '#/components/parameters/ApiVersionRequest' },\n      ]\n    }\n  }\n\n  return {\n    openapi: '3.1.0',\n    // The dialect, stated rather than assumed. It is what tells a consumer the\n    // schemas below are JSON Schema 2020-12 and not OpenAPI 3.0's dialect.\n    jsonSchemaDialect: 'https://json-schema.org/draft/2020-12/schema',\n    info,\n    servers: [{ url: origin, description: options.siteName }],\n    tags: [\n      {\n        name: 'Discovery',\n        description: 'Files that describe the site to a machine.',\n      },\n      { name: 'Content', description: 'The pages and entries the site publishes.' },\n      { name: 'Site', description: 'Identity and operational status.' },\n    ],\n    paths,\n    components: {\n      schemas: {\n        Error: ERROR_SCHEMA,\n        ApiCatalog: {\n          type: 'object',\n          description:\n            'An RFC 9264 linkset. Each member of `linkset` is a link ' +\n            'CONTEXT keyed by its `anchor`: the first is anchored at the ' +\n            'catalog and lists its members under `item`, and each one after ' +\n            'it is anchored at a single API and carries that API’s links.',\n          required: ['linkset'],\n          properties: {\n            linkset: {\n              type: 'array',\n              items: {\n                type: 'object',\n                required: ['anchor'],\n                properties: {\n                  anchor: {\n                    type: 'string',\n                    format: 'uri',\n                    description:\n                      'What every link in this object is a link FROM.',\n                  },\n                  item: {\n                    type: 'array',\n                    description: 'Catalog membership — the APIs listed.',\n                    items: { $ref: '#/components/schemas/CatalogLink' },\n                  },\n                  'service-desc': {\n                    type: 'array',\n                    description:\n                      'Machine-readable description of the anchored API.',\n                    items: { $ref: '#/components/schemas/CatalogLink' },\n                  },\n                  'service-doc': {\n                    type: 'array',\n                    description: 'Documentation written for a person.',\n                    items: { $ref: '#/components/schemas/CatalogLink' },\n                  },\n                  status: {\n                    type: 'array',\n                    description: 'Where the anchored API reports its health.',\n                    items: { $ref: '#/components/schemas/CatalogLink' },\n                  },\n                },\n              },\n            },\n          },\n        },\n        CatalogLink: {\n          type: 'object',\n          description: 'One link in a linkset.',\n          required: ['href'],\n          properties: {\n            href: { type: 'string', format: 'uri' },\n            type: {\n              type: 'string',\n              description: 'Media type of the target, when it is known.',\n            },\n            title: { type: 'string', description: 'Human label.' },\n          },\n        },\n        OpenApiDocument: {\n          type: 'object',\n          description:\n            'An OpenAPI 3.1 description — this document. Described rather ' +\n            'than left as a bare object so a consumer knows which dialect ' +\n            'the schemas inside it use before it fetches them.',\n          required: ['openapi', 'info', 'paths'],\n          properties: {\n            openapi: {\n              type: 'string',\n              description: 'OpenAPI specification version, e.g. `3.1.0`.',\n            },\n            jsonSchemaDialect: {\n              type: 'string',\n              description: 'The JSON Schema dialect the schemas below use.',\n            },\n            info: {\n              type: 'object',\n              description: 'Title, version, summary and description.',\n            },\n            servers: {\n              type: 'array',\n              description: 'Origins this description applies to.',\n              items: { type: 'object' },\n            },\n            tags: {\n              type: 'array',\n              description: 'Operation groupings.',\n              items: { type: 'object' },\n            },\n            paths: {\n              type: 'object',\n              description: 'Every path, keyed by template, each with its verbs.',\n            },\n            components: {\n              type: 'object',\n              description: 'Reusable schemas, parameters and headers.',\n            },\n          },\n        },\n        WebAppManifest: {\n          type: 'object',\n          description:\n            'A W3C web app manifest. Only the members this site actually ' +\n            'emits are described; the specification allows more.',\n          properties: {\n            name: { type: 'string', description: 'Full name of the site.' },\n            short_name: {\n              type: 'string',\n              description: 'Name used where space is tight.',\n            },\n            description: { type: 'string', description: 'What the site is.' },\n            start_url: {\n              type: 'string',\n              description: 'Where an installed instance opens.',\n            },\n            scope: { type: 'string', description: 'URLs the install covers.' },\n            display: {\n              type: 'string',\n              description: 'Preferred display mode, e.g. `standalone`.',\n            },\n            theme_color: {\n              type: 'string',\n              description: 'CSS color for the surrounding UI.',\n            },\n            background_color: {\n              type: 'string',\n              description: 'CSS color painted before the site renders.',\n            },\n            icons: {\n              type: 'array',\n              description: 'Installable icons.',\n              items: {\n                type: 'object',\n                properties: {\n                  src: { type: 'string' },\n                  sizes: { type: 'string' },\n                  type: { type: 'string' },\n                  purpose: { type: 'string' },\n                },\n              },\n            },\n          },\n        },\n        SiteIdentity: {\n          type: 'object',\n          description: \"A site's public identity.\",\n          properties: {\n            $id: { type: 'string', description: 'Stable site identifier.' },\n            displayName: { type: 'string', description: 'Human-readable name.' },\n            logoUrl: { type: 'string', description: \"The site's logo.\" },\n            subdomain: {\n              type: 'string',\n              description: 'Platform subdomain, without the apex.',\n            },\n            cname: { type: 'string', description: 'Custom domain, when set.' },\n            locales: {\n              type: 'array',\n              items: { type: 'string' },\n              description: 'BCP-47 locales this site publishes.',\n            },\n            defaultLocale: { type: 'string', description: 'The default locale.' },\n            seo: SEO_SCHEMA,\n          },\n        },\n        PublishedPage: {\n          type: 'object',\n          description: 'One published, indexable page.',\n          properties: {\n            $id: { type: 'string', description: 'Stable page identifier.' },\n            slug: { type: 'string', description: 'The page’s own path segment.' },\n            parentId: {\n              type: 'string',\n              description: 'Parent page, for a nested page.',\n            },\n            order: { type: 'integer', description: 'Sort order among siblings.' },\n            displayName: { type: 'string', description: 'The page’s name.' },\n            description: { type: 'string', description: 'Author’s summary.' },\n            locale: { type: 'string', description: 'BCP-47 locale.' },\n            publishedAt: {\n              type: 'string',\n              format: 'date-time',\n              description: 'When this page was last published.',\n            },\n            updatedAt: {\n              type: 'string',\n              format: 'date-time',\n              description: 'When this page was last saved.',\n            },\n            seo: SEO_SCHEMA,\n          },\n          required: ['$id'],\n        },\n        Health: {\n          type: 'object',\n          description: 'Service health.',\n          properties: {\n            status: {\n              type: 'string',\n              enum: ['ok', 'degraded', 'down'],\n              description: 'Overall verdict.',\n            },\n            service: { type: 'string', description: 'Which service answered.' },\n            version: { type: 'string', description: 'Platform version.' },\n            environment: { type: 'string', description: 'Deployment environment.' },\n            checks: {\n              type: 'object',\n              description: 'Per-dependency results.',\n              additionalProperties: { type: 'object' },\n            },\n          },\n          required: ['status'],\n        },\n      },\n      headers: {\n        ApiVersion: {\n          description:\n            'The API version that produced this response. Compare it with ' +\n            'the version you were built against; they differ only when ' +\n            'something was removed, renamed, or narrowed.',\n          schema: { type: 'string', examples: [API_VERSION] },\n        },\n        Deprecation: {\n          description:\n            'Present only on a deprecated operation, per RFC 9745: the HTTP ' +\n            'date the deprecation took effect. Its absence is meaningful — ' +\n            'an operation that has never carried this is not scheduled for ' +\n            'removal.',\n          schema: { type: 'string' },\n        },\n        Sunset: {\n          description:\n            'Present only once a removal date is set, per RFC 8594: the ' +\n            'HTTP date after which this operation stops answering. Always ' +\n            'accompanied by `Deprecation`.',\n          schema: { type: 'string' },\n        },\n        RateLimitLimit: {\n          description:\n            'Requests this address may make per window, per RFC 9331.',\n          schema: { type: 'integer' },\n        },\n        RateLimitRemaining: {\n          description:\n            'Requests left in the current window.\\n\\n' +\n            '⚠️ Counted PER SERVING INSTANCE, not across the deployment. ' +\n            'The limit is a backstop set far above ordinary reading, and an ' +\n            'exact global counter would cost every request two round trips ' +\n            'to enforce a number nobody should reach. Pace against it as a ' +\n            'courtesy signal, not as an exact budget.',\n          schema: { type: 'integer' },\n        },\n        RateLimitReset: {\n          description:\n            'Seconds until the current window resets — a duration, not a ' +\n            'timestamp, so a caller uses its own clock rather than trusting ' +\n            'ours.',\n          schema: { type: 'integer' },\n        },\n        RetryAfter: {\n          description:\n            'Seconds to wait before retrying. Sent only with a 429.',\n          schema: { type: 'integer' },\n        },\n      },\n      parameters: {\n        ApiVersionRequest: {\n          name: API_VERSION_HEADER,\n          in: 'header',\n          required: false,\n          description:\n            'Pin the response shape to a version you were built against. ' +\n            'Omit it to get the current version, which is what most callers ' +\n            'want — additive changes never bump it.',\n          schema: { type: 'string', examples: [API_VERSION] },\n        },\n      },\n    },\n  }\n}\n"],"names":["API_CATALOG_MEDIA_TYPE","MARKDOWN","API_VERSION_HEADER","API_VERSION","RATE_LIMIT_HEADERS","$ref","TOO_MANY_REQUESTS","description","headers","content","schema","ACCEPT_PARAMETER","name","in","required","type","enum","default","ERROR_SCHEMA","properties","status","statusMessage","errorCode","SEO_SCHEMA","title","image","imageWidth","imageHeight","imageAlt","buildAgentOpenApi","options","origin","replace","collections","collectionSlugs","map","collection","slug","paths","get","operationId","summary","tags","responses","parameters","example","Vary","data","host","minimum","maximum","screens","items","cursor","length","hasSearch","minLength","info","siteName","version","contactEmail","contact","email","termsOfServiceUrl","termsOfService","versionedHeaders","Deprecation","Sunset","METERED","Set","pathName","pathItem","Object","entries","metered","has","operation","values","verb","response","openapi","jsonSchemaDialect","servers","url","components","schemas","Error","ApiCatalog","linkset","anchor","format","item","CatalogLink","href","OpenApiDocument","WebAppManifest","short_name","start_url","scope","display","theme_color","background_color","icons","src","sizes","purpose","SiteIdentity","$id","displayName","logoUrl","subdomain","cname","locales","defaultLocale","seo","PublishedPage","parentId","order","locale","publishedAt","updatedAt","Health","service","environment","checks","additionalProperties","ApiVersion","examples","RateLimitLimit","RateLimitRemaining","RateLimitReset","RetryAfter","ApiVersionRequest"],"mappings":"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"}

package/src/lib/app-utils/analytics-beacon.d.ts

@@ -0,0 +1,154 @@
+/**
+ * @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 gate every FIRST-PARTY analytics beacon passes through, and the one
+ * function that sends one.
+ *
+ * ## Why this exists beside the Google Analytics gate rather than inside it
+ *
+ * `analyticsMayEmit` (AGL-2067) decides whether a build may load a Google tag.
+ * It was applied to the GA4 mount, the GTM mount, the advertising tags and
+ * Firebase Analytics — every tag that costs nothing — and not to
+ * `/api/analytics/collect`, which is the one that bills.
+ *
+ * That endpoint increments `hosts/{hostId}/analytics/{day}.total`, which rolls
+ * up into `orgs/{orgId}/usage/{month}.pageViews` and from there into the
+ * Stripe meter, the free plan's bandwidth band (`bandwidthCapShouldEngage`)
+ * and the abuse ceiling (`checkBandwidthAbuseCeiling`). Both Next apps map
+ * `VERCEL_ENV` into the client bundle and both point at the production
+ * Firebase project, so before this gate a `next dev` on `localhost:4500` and
+ * every preview deployment of `apps/tenant` wrote real page views into a
+ * customer's invoice and against their cap.
+ *
+ * ## The two halves of the decision
+ *
+ * 1. **The build.** A production surface, and ONLY a production surface. Note
+ *    what this deliberately does not honor: `NEXT_PUBLIC_ANALYTICS_ALLOW_NONPROD`.
+ *    That hatch exists so someone can exercise the GA taxonomy against
+ *    DebugView from a dev build, and it is paired with
+ *    `analyticsEnvironmentForcesInternal` precisely so the hits it produces
+ *    are all marked ours. A hit marked ours must not be billed to anyone, so
+ *    the hatch buys a GA session and never a counter increment.
+ *
+ *    `analyticsMayEmit(env) && !analyticsEnvironmentForcesInternal(env)`
+ *    reduces to `isProductionSurface(env)`, which is not exported. Composing
+ *    the two published predicates keeps this gate and the GA gate reading the
+ *    same environment through the same code, so a change to what counts as
+ *    production cannot move one and leave the other.
+ *
+ * 2. **The browser.** `readInternalTrafficOverride` — the same per-origin
+ *    opt-in (`?aglyn_internal=1`) that stamps `traffic_type: 'internal'` for
+ *    GA4. GA stamps and lets a data filter discard; here there is nothing to
+ *    filter after the fact, because a counter is a running total and a page
+ *    view already added to an invoice cannot be taken back out. So the beacon
+ *    is not sent at all.
+ *
+ * A loopback self-host install (`{subdomain}.localhost:4500` from the compose
+ * file) counts nothing, by the same rule that already silences its GA tag. An
+ * operator serving from a real name is a production surface and counts
+ * normally — theirs is the deployment an unknown `deployEnv` is for.
+ *
+ * ## Bias
+ *
+ * Opt-in only, never inferred, and every ambiguous case resolves to NOT
+ * internal — a browser with `localStorage` disabled, a sandboxed iframe, a
+ * server render. Wrongly flagging a real visitor under-counts a customer's
+ * own dashboard as well as their bill, which is the quieter of the two
+ * failures but still theirs.
+ */
+import { type AnalyticsEnvironment } from './analytics-environment';
+import { type InternalTrafficOverrideSource } from './internal-traffic';
+/**
+ * The collector. One definition, because four call sites across three
+ * packages send to it and a path that drifts by one character is a counter
+ * that silently stops.
+ */
+export declare const ANALYTICS_BEACON_ENDPOINT = "/api/analytics/collect";
+/** The browser and build facts the gate reads, so a spec can supply them. */
+export interface AnalyticsBeaconContext {
+    /** Defaults to this build's own environment. */
+    env?: AnalyticsEnvironment;
+    /** Defaults to `window.location.search` and `window.localStorage`. */
+    override?: InternalTrafficOverrideSource;
+}
+/**
+ * Whether a beacon from HERE, in THIS browser, should be counted.
+ *
+ * ⚠️ Reading the override also APPLIES it: `?aglyn_internal=1` persists on the
+ * call that observes it, so the visit carrying the parameter is itself
+ * suppressed rather than counted and excluded from the next one. That is the
+ * whole reason one round trip through the URL is enough.
+ */
+export declare function analyticsBeaconMaySend(context?: AnalyticsBeaconContext): boolean;
+/**
+ * Send one beacon, or don't.
+ *
+ * Returns whether the browser accepted it, so a caller that has its own
+ * once-per-pageview bookkeeping can tell "refused" from "queued" — though
+ * every caller today treats analytics as fire-and-forget and ignores it.
+ *
+ * Never throws. `sendBeacon` itself throws on some payloads and in some
+ * sandboxes, and analytics does not get to break a customer's page.
+ */
+export declare function sendAnalyticsBeacon(payload: Record<string, unknown>, context?: AnalyticsBeaconContext): boolean;
+/**
+ * The playback events `/api/analytics/collect` counts (AGL-2746).
+ *
+ * A closed vocabulary, exported so the player and the route cannot drift: an
+ * event the route does not recognize is silently discarded with a 204, which
+ * is the correct behavior for an unauthenticated collector and a terrible
+ * way to find out a player is sending `'started'`.
+ *
+ * Quartiles rather than a position. A percentage would be a continuous,
+ * visitor-supplied value arriving on a Firestore map key, and four buckets
+ * answer the only question anyone asks of a watch curve — where people stop.
+ */
+export type VideoAnalyticsEvent = 'play' | 'progress25' | 'progress50' | 'progress75' | 'complete';
+/**
+ * The quartile event a playhead has just crossed, or undefined.
+ *
+ * `previousFraction` is what the player last reported, so a seek backwards
+ * re-fires nothing and a normal watch fires each quartile exactly once. The
+ * caller keeps that one number; this keeps the thresholds, so a player does
+ * not carry its own copy of 0.25/0.5/0.75 — which is the shape of duplication
+ * that made `analyticsPathKey` a shared function.
+ *
+ * `complete` is NOT produced here. It belongs to the `ended` event, which is
+ * the only signal that distinguishes watching to the end from seeking to it.
+ */
+export declare function videoQuartileEvent(fraction: number, previousFraction: number): VideoAnalyticsEvent | undefined;
+/**
+ * Report one playback event for one DAM asset.
+ *
+ * Rides {@link sendAnalyticsBeacon}, so it inherits both halves of that gate
+ * — production surfaces only, and never a browser carrying the internal-traffic
+ * opt-in. Inheriting them matters even though these counters never reach an
+ * invoice: a preview deployment and a developer's `next dev` both point at the
+ * production Firebase project, so without the gate every local page load of a
+ * page carrying a video would add plays to a customer's dashboard.
+ *
+ * Returns whether the browser accepted the beacon. Every caller today treats
+ * it as fire-and-forget.
+ */
+export declare function sendVideoAnalyticsBeacon(options: {
+    hostId: string;
+    /** The DAM media id, not a URL. */
+    mediaId: string;
+    event: VideoAnalyticsEvent;
+    /** Page path, for parity with every other beacon. Optional. */
+    path?: string;
+}, context?: AnalyticsBeaconContext): boolean;

package/src/lib/app-utils/analytics-beacon.js

@@ -0,0 +1,152 @@
+import { _ as _extends } from "@swc/helpers/_/_extends";
+/**
+ * @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 gate every FIRST-PARTY analytics beacon passes through, and the one
+ * function that sends one.
+ *
+ * ## Why this exists beside the Google Analytics gate rather than inside it
+ *
+ * `analyticsMayEmit` (AGL-2067) decides whether a build may load a Google tag.
+ * It was applied to the GA4 mount, the GTM mount, the advertising tags and
+ * Firebase Analytics — every tag that costs nothing — and not to
+ * `/api/analytics/collect`, which is the one that bills.
+ *
+ * That endpoint increments `hosts/{hostId}/analytics/{day}.total`, which rolls
+ * up into `orgs/{orgId}/usage/{month}.pageViews` and from there into the
+ * Stripe meter, the free plan's bandwidth band (`bandwidthCapShouldEngage`)
+ * and the abuse ceiling (`checkBandwidthAbuseCeiling`). Both Next apps map
+ * `VERCEL_ENV` into the client bundle and both point at the production
+ * Firebase project, so before this gate a `next dev` on `localhost:4500` and
+ * every preview deployment of `apps/tenant` wrote real page views into a
+ * customer's invoice and against their cap.
+ *
+ * ## The two halves of the decision
+ *
+ * 1. **The build.** A production surface, and ONLY a production surface. Note
+ *    what this deliberately does not honor: `NEXT_PUBLIC_ANALYTICS_ALLOW_NONPROD`.
+ *    That hatch exists so someone can exercise the GA taxonomy against
+ *    DebugView from a dev build, and it is paired with
+ *    `analyticsEnvironmentForcesInternal` precisely so the hits it produces
+ *    are all marked ours. A hit marked ours must not be billed to anyone, so
+ *    the hatch buys a GA session and never a counter increment.
+ *
+ *    `analyticsMayEmit(env) && !analyticsEnvironmentForcesInternal(env)`
+ *    reduces to `isProductionSurface(env)`, which is not exported. Composing
+ *    the two published predicates keeps this gate and the GA gate reading the
+ *    same environment through the same code, so a change to what counts as
+ *    production cannot move one and leave the other.
+ *
+ * 2. **The browser.** `readInternalTrafficOverride` — the same per-origin
+ *    opt-in (`?aglyn_internal=1`) that stamps `traffic_type: 'internal'` for
+ *    GA4. GA stamps and lets a data filter discard; here there is nothing to
+ *    filter after the fact, because a counter is a running total and a page
+ *    view already added to an invoice cannot be taken back out. So the beacon
+ *    is not sent at all.
+ *
+ * A loopback self-host install (`{subdomain}.localhost:4500` from the compose
+ * file) counts nothing, by the same rule that already silences its GA tag. An
+ * operator serving from a real name is a production surface and counts
+ * normally — theirs is the deployment an unknown `deployEnv` is for.
+ *
+ * ## Bias
+ *
+ * Opt-in only, never inferred, and every ambiguous case resolves to NOT
+ * internal — a browser with `localStorage` disabled, a sandboxed iframe, a
+ * server render. Wrongly flagging a real visitor under-counts a customer's
+ * own dashboard as well as their bill, which is the quieter of the two
+ * failures but still theirs.
+ */ import { analyticsEnvironmentForcesInternal, analyticsMayEmit, readAnalyticsEnvironment } from "./analytics-environment.js";
+import { readInternalTrafficOverride } from "./internal-traffic.js";
+/**
+ * The collector. One definition, because four call sites across three
+ * packages send to it and a path that drifts by one character is a counter
+ * that silently stops.
+ */ export const ANALYTICS_BEACON_ENDPOINT = '/api/analytics/collect';
+/**
+ * Whether a beacon from HERE, in THIS browser, should be counted.
+ *
+ * ⚠️ Reading the override also APPLIES it: `?aglyn_internal=1` persists on the
+ * call that observes it, so the visit carrying the parameter is itself
+ * suppressed rather than counted and excluded from the next one. That is the
+ * whole reason one round trip through the URL is enough.
+ */ export function analyticsBeaconMaySend(context = {}) {
+    var _context_env;
+    const env = (_context_env = context.env) != null ? _context_env : readAnalyticsEnvironment();
+    if (!analyticsMayEmit(env)) return false;
+    if (analyticsEnvironmentForcesInternal(env)) return false;
+    return !readInternalTrafficOverride(context.override);
+}
+/**
+ * Send one beacon, or don't.
+ *
+ * Returns whether the browser accepted it, so a caller that has its own
+ * once-per-pageview bookkeeping can tell "refused" from "queued" — though
+ * every caller today treats analytics as fire-and-forget and ignores it.
+ *
+ * Never throws. `sendBeacon` itself throws on some payloads and in some
+ * sandboxes, and analytics does not get to break a customer's page.
+ */ export function sendAnalyticsBeacon(payload, context = {}) {
+    if (typeof navigator === 'undefined') return false;
+    if (!analyticsBeaconMaySend(context)) return false;
+    try {
+        return navigator.sendBeacon(ANALYTICS_BEACON_ENDPOINT, JSON.stringify(payload));
+    } catch (unused) {
+        return false;
+    }
+}
+/**
+ * The quartile event a playhead has just crossed, or undefined.
+ *
+ * `previousFraction` is what the player last reported, so a seek backwards
+ * re-fires nothing and a normal watch fires each quartile exactly once. The
+ * caller keeps that one number; this keeps the thresholds, so a player does
+ * not carry its own copy of 0.25/0.5/0.75 — which is the shape of duplication
+ * that made `analyticsPathKey` a shared function.
+ *
+ * `complete` is NOT produced here. It belongs to the `ended` event, which is
+ * the only signal that distinguishes watching to the end from seeking to it.
+ */ export function videoQuartileEvent(fraction, previousFraction) {
+    const crossed = (threshold)=>fraction >= threshold && previousFraction < threshold;
+    if (crossed(0.75)) return 'progress75';
+    if (crossed(0.5)) return 'progress50';
+    if (crossed(0.25)) return 'progress25';
+    return undefined;
+}
+/**
+ * Report one playback event for one DAM asset.
+ *
+ * Rides {@link sendAnalyticsBeacon}, so it inherits both halves of that gate
+ * — production surfaces only, and never a browser carrying the internal-traffic
+ * opt-in. Inheriting them matters even though these counters never reach an
+ * invoice: a preview deployment and a developer's `next dev` both point at the
+ * production Firebase project, so without the gate every local page load of a
+ * page carrying a video would add plays to a customer's dashboard.
+ *
+ * Returns whether the browser accepted the beacon. Every caller today treats
+ * it as fire-and-forget.
+ */ export function sendVideoAnalyticsBeacon(options, context = {}) {
+    if (!options.hostId || !options.mediaId) return false;
+    return sendAnalyticsBeacon(_extends({
+        hostId: options.hostId,
+        mediaId: options.mediaId,
+        video: options.event
+    }, options.path ? {
+        path: options.path
+    } : {}), context);
+}
+
+//# sourceMappingURL=analytics-beacon.js.map

package/src/lib/app-utils/analytics-beacon.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../../../../../libs/aglyn/src/lib/app-utils/analytics-beacon.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\n/**\n * The gate every FIRST-PARTY analytics beacon passes through, and the one\n * function that sends one.\n *\n * ## Why this exists beside the Google Analytics gate rather than inside it\n *\n * `analyticsMayEmit` (AGL-2067) decides whether a build may load a Google tag.\n * It was applied to the GA4 mount, the GTM mount, the advertising tags and\n * Firebase Analytics — every tag that costs nothing — and not to\n * `/api/analytics/collect`, which is the one that bills.\n *\n * That endpoint increments `hosts/{hostId}/analytics/{day}.total`, which rolls\n * up into `orgs/{orgId}/usage/{month}.pageViews` and from there into the\n * Stripe meter, the free plan's bandwidth band (`bandwidthCapShouldEngage`)\n * and the abuse ceiling (`checkBandwidthAbuseCeiling`). Both Next apps map\n * `VERCEL_ENV` into the client bundle and both point at the production\n * Firebase project, so before this gate a `next dev` on `localhost:4500` and\n * every preview deployment of `apps/tenant` wrote real page views into a\n * customer's invoice and against their cap.\n *\n * ## The two halves of the decision\n *\n * 1. **The build.** A production surface, and ONLY a production surface. Note\n *    what this deliberately does not honor: `NEXT_PUBLIC_ANALYTICS_ALLOW_NONPROD`.\n *    That hatch exists so someone can exercise the GA taxonomy against\n *    DebugView from a dev build, and it is paired with\n *    `analyticsEnvironmentForcesInternal` precisely so the hits it produces\n *    are all marked ours. A hit marked ours must not be billed to anyone, so\n *    the hatch buys a GA session and never a counter increment.\n *\n *    `analyticsMayEmit(env) && !analyticsEnvironmentForcesInternal(env)`\n *    reduces to `isProductionSurface(env)`, which is not exported. Composing\n *    the two published predicates keeps this gate and the GA gate reading the\n *    same environment through the same code, so a change to what counts as\n *    production cannot move one and leave the other.\n *\n * 2. **The browser.** `readInternalTrafficOverride` — the same per-origin\n *    opt-in (`?aglyn_internal=1`) that stamps `traffic_type: 'internal'` for\n *    GA4. GA stamps and lets a data filter discard; here there is nothing to\n *    filter after the fact, because a counter is a running total and a page\n *    view already added to an invoice cannot be taken back out. So the beacon\n *    is not sent at all.\n *\n * A loopback self-host install (`{subdomain}.localhost:4500` from the compose\n * file) counts nothing, by the same rule that already silences its GA tag. An\n * operator serving from a real name is a production surface and counts\n * normally — theirs is the deployment an unknown `deployEnv` is for.\n *\n * ## Bias\n *\n * Opt-in only, never inferred, and every ambiguous case resolves to NOT\n * internal — a browser with `localStorage` disabled, a sandboxed iframe, a\n * server render. Wrongly flagging a real visitor under-counts a customer's\n * own dashboard as well as their bill, which is the quieter of the two\n * failures but still theirs.\n */\n\nimport {\n  type AnalyticsEnvironment,\n  analyticsEnvironmentForcesInternal,\n  analyticsMayEmit,\n  readAnalyticsEnvironment,\n} from './analytics-environment'\nimport {\n  type InternalTrafficOverrideSource,\n  readInternalTrafficOverride,\n} from './internal-traffic'\n\n/**\n * The collector. One definition, because four call sites across three\n * packages send to it and a path that drifts by one character is a counter\n * that silently stops.\n */\nexport const ANALYTICS_BEACON_ENDPOINT = '/api/analytics/collect'\n\n/** The browser and build facts the gate reads, so a spec can supply them. */\nexport interface AnalyticsBeaconContext {\n  /** Defaults to this build's own environment. */\n  env?: AnalyticsEnvironment\n  /** Defaults to `window.location.search` and `window.localStorage`. */\n  override?: InternalTrafficOverrideSource\n}\n\n/**\n * Whether a beacon from HERE, in THIS browser, should be counted.\n *\n * ⚠️ Reading the override also APPLIES it: `?aglyn_internal=1` persists on the\n * call that observes it, so the visit carrying the parameter is itself\n * suppressed rather than counted and excluded from the next one. That is the\n * whole reason one round trip through the URL is enough.\n */\nexport function analyticsBeaconMaySend(\n  context: AnalyticsBeaconContext = {},\n): boolean {\n  const env = context.env ?? readAnalyticsEnvironment()\n  if (!analyticsMayEmit(env)) return false\n  if (analyticsEnvironmentForcesInternal(env)) return false\n  return !readInternalTrafficOverride(context.override)\n}\n\n/**\n * Send one beacon, or don't.\n *\n * Returns whether the browser accepted it, so a caller that has its own\n * once-per-pageview bookkeeping can tell \"refused\" from \"queued\" — though\n * every caller today treats analytics as fire-and-forget and ignores it.\n *\n * Never throws. `sendBeacon` itself throws on some payloads and in some\n * sandboxes, and analytics does not get to break a customer's page.\n */\nexport function sendAnalyticsBeacon(\n  payload: Record<string, unknown>,\n  context: AnalyticsBeaconContext = {},\n): boolean {\n  if (typeof navigator === 'undefined') return false\n  if (!analyticsBeaconMaySend(context)) return false\n  try {\n    return navigator.sendBeacon(\n      ANALYTICS_BEACON_ENDPOINT,\n      JSON.stringify(payload),\n    )\n  } catch {\n    return false\n  }\n}\n\n/**\n * The playback events `/api/analytics/collect` counts (AGL-2746).\n *\n * A closed vocabulary, exported so the player and the route cannot drift: an\n * event the route does not recognize is silently discarded with a 204, which\n * is the correct behavior for an unauthenticated collector and a terrible\n * way to find out a player is sending `'started'`.\n *\n * Quartiles rather than a position. A percentage would be a continuous,\n * visitor-supplied value arriving on a Firestore map key, and four buckets\n * answer the only question anyone asks of a watch curve — where people stop.\n */\nexport type VideoAnalyticsEvent =\n  | 'play'\n  | 'progress25'\n  | 'progress50'\n  | 'progress75'\n  | 'complete'\n\n/**\n * The quartile event a playhead has just crossed, or undefined.\n *\n * `previousFraction` is what the player last reported, so a seek backwards\n * re-fires nothing and a normal watch fires each quartile exactly once. The\n * caller keeps that one number; this keeps the thresholds, so a player does\n * not carry its own copy of 0.25/0.5/0.75 — which is the shape of duplication\n * that made `analyticsPathKey` a shared function.\n *\n * `complete` is NOT produced here. It belongs to the `ended` event, which is\n * the only signal that distinguishes watching to the end from seeking to it.\n */\nexport function videoQuartileEvent(\n  fraction: number,\n  previousFraction: number,\n): VideoAnalyticsEvent | undefined {\n  const crossed = (threshold: number) =>\n    fraction >= threshold && previousFraction < threshold\n  if (crossed(0.75)) return 'progress75'\n  if (crossed(0.5)) return 'progress50'\n  if (crossed(0.25)) return 'progress25'\n  return undefined\n}\n\n/**\n * Report one playback event for one DAM asset.\n *\n * Rides {@link sendAnalyticsBeacon}, so it inherits both halves of that gate\n * — production surfaces only, and never a browser carrying the internal-traffic\n * opt-in. Inheriting them matters even though these counters never reach an\n * invoice: a preview deployment and a developer's `next dev` both point at the\n * production Firebase project, so without the gate every local page load of a\n * page carrying a video would add plays to a customer's dashboard.\n *\n * Returns whether the browser accepted the beacon. Every caller today treats\n * it as fire-and-forget.\n */\nexport function sendVideoAnalyticsBeacon(\n  options: {\n    hostId: string\n    /** The DAM media id, not a URL. */\n    mediaId: string\n    event: VideoAnalyticsEvent\n    /** Page path, for parity with every other beacon. Optional. */\n    path?: string\n  },\n  context: AnalyticsBeaconContext = {},\n): boolean {\n  if (!options.hostId || !options.mediaId) return false\n  return sendAnalyticsBeacon(\n    {\n      hostId: options.hostId,\n      mediaId: options.mediaId,\n      video: options.event,\n      ...(options.path ? { path: options.path } : {}),\n    },\n    context,\n  )\n}\n"],"names":["analyticsEnvironmentForcesInternal","analyticsMayEmit","readAnalyticsEnvironment","readInternalTrafficOverride","ANALYTICS_BEACON_ENDPOINT","analyticsBeaconMaySend","context","env","override","sendAnalyticsBeacon","payload","navigator","sendBeacon","JSON","stringify","videoQuartileEvent","fraction","previousFraction","crossed","threshold","undefined","sendVideoAnalyticsBeacon","options","hostId","mediaId","video","event","path"],"mappings":";AAAA;;;;;;;;;;;;;;;CAeC,GAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;CAuDC,GAED,SAEEA,kCAAkC,EAClCC,gBAAgB,EAChBC,wBAAwB,QACnB,6BAAyB;AAChC,SAEEC,2BAA2B,QACtB,wBAAoB;AAE3B;;;;CAIC,GACD,OAAO,MAAMC,4BAA4B,yBAAwB;AAUjE;;;;;;;CAOC,GACD,OAAO,SAASC,uBACdC,UAAkC,CAAC,CAAC;QAExBA;IAAZ,MAAMC,OAAMD,eAAAA,QAAQC,GAAG,YAAXD,eAAeJ;IAC3B,IAAI,CAACD,iBAAiBM,MAAM,OAAO;IACnC,IAAIP,mCAAmCO,MAAM,OAAO;IACpD,OAAO,CAACJ,4BAA4BG,QAAQE,QAAQ;AACtD;AAEA;;;;;;;;;CASC,GACD,OAAO,SAASC,oBACdC,OAAgC,EAChCJ,UAAkC,CAAC,CAAC;IAEpC,IAAI,OAAOK,cAAc,aAAa,OAAO;IAC7C,IAAI,CAACN,uBAAuBC,UAAU,OAAO;IAC7C,IAAI;QACF,OAAOK,UAAUC,UAAU,CACzBR,2BACAS,KAAKC,SAAS,CAACJ;IAEnB,EAAE,eAAM;QACN,OAAO;IACT;AACF;AAqBA;;;;;;;;;;;CAWC,GACD,OAAO,SAASK,mBACdC,QAAgB,EAChBC,gBAAwB;IAExB,MAAMC,UAAU,CAACC,YACfH,YAAYG,aAAaF,mBAAmBE;IAC9C,IAAID,QAAQ,OAAO,OAAO;IAC1B,IAAIA,QAAQ,MAAM,OAAO;IACzB,IAAIA,QAAQ,OAAO,OAAO;IAC1B,OAAOE;AACT;AAEA;;;;;;;;;;;;CAYC,GACD,OAAO,SAASC,yBACdC,OAOC,EACDhB,UAAkC,CAAC,CAAC;IAEpC,IAAI,CAACgB,QAAQC,MAAM,IAAI,CAACD,QAAQE,OAAO,EAAE,OAAO;IAChD,OAAOf,oBACL;QACEc,QAAQD,QAAQC,MAAM;QACtBC,SAASF,QAAQE,OAAO;QACxBC,OAAOH,QAAQI,KAAK;OAChBJ,QAAQK,IAAI,GAAG;QAAEA,MAAML,QAAQK,IAAI;IAAC,IAAI,CAAC,IAE/CrB;AAEJ"}

package/src/lib/app-utils/analytics-environment.d.ts

@@ -0,0 +1,133 @@
+/**
+ * @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.
+ */
+/**
+ * Whether THIS BUILD is allowed to report to Google Analytics at all
+ * (AGL-2067).
+ *
+ * ## The hole this closes
+ *
+ * Neither app gated GA on the deployment environment. The console called
+ * `initializeAnalytics` unconditionally and `apps/console/.env.development.local`
+ * points at the PRODUCTION measurement id, so every `next dev` session produced
+ * real `session_start` / `first_visit` / `page_view` hits in the live property;
+ * the tenant runtime mounted its tag wherever the resolved host carried an id,
+ * which on a preview deploy of `aglyn.com` is our own.
+ *
+ * That is not hypothetical. `docs/ANALYTICS.md` records the archived Marketing
+ * property's entire year-to-date history as 30 views / 6 users, ~24 of them
+ * `/signin` on Vercel PREVIEW urls of the console. Preview traffic reaching a
+ * production property is most of what that property ever recorded.
+ *
+ * `apps/docs` already got this right — the Docusaurus gtag plugin returns null
+ * unless `NODE_ENV === 'production'` — so this is the same rule, made
+ * available to the two apps that lacked it.
+ *
+ * ## Why this is better than the stamp for the dev case
+ *
+ * `traffic_type: 'internal'` only helps once a matching GA4 data filter exists
+ * in the property, and a filter is not retroactive: a hit that ships today is
+ * counted today. Not emitting at all needs no console configuration and cannot
+ * be got wrong later.
+ *
+ * ## The three signals, and why the default leans LOUD
+ *
+ * - `NODE_ENV !== 'production'` — every `next dev`, every jest run, every
+ *   local e2e. Never emits.
+ * - `deployEnv` is `preview` or `development` — a Vercel preview build has
+ *   `NODE_ENV === 'production'` (it is a production build), so nothing else
+ *   catches it. `VERCEL_ENV` is server-only, so each app maps it into the
+ *   client bundle through its `next.config` `env` block; assuming Vercel's
+ *   "automatically expose system environment variables" setting is on would
+ *   be a gate that silently is not there.
+ * - `deployEnv` unknown with `NODE_ENV === 'production'` — **emits.** That is
+ *   the self-host case (Docker + bring-your-own-Firebase), which points at the
+ *   operator's own Firebase project and their own GA property. Defaulting
+ *   those to silence would break a customer's analytics to protect ours, which
+ *   is the worse failure; our own builds are the ones that carry the marker.
+ * - **The document is served from a loopback host — never emits**, whatever
+ *   the other three say. The signals above are all build-time, and a build is
+ *   not a deployment: `next start`, `docker compose up` from a clone, and a
+ *   production container run locally all carry `NODE_ENV === 'production'`
+ *   with no `VERCEL_ENV`, which is byte-for-byte the self-host case the rule
+ *   above deliberately lets through. Run against
+ *   `apps/console/.env.development.local`, whose measurement id is the live
+ *   `G-YW5PG16YTM`, that path reports a developer's laptop as production
+ *   traffic — and it is not theoretical: `localhost` was 145 sessions of a
+ *   609-session month, arriving as `localhost:4200 / referral`, which also
+ *   overwrites the acquisition source of every session it touches.
+ *
+ *   The host is the one signal that separates the two cases, because a real
+ *   self-hosted deployment is reached at a real name. It is read from
+ *   `location` at call time and is therefore absent server-side, where it
+ *   changes nothing — the check can only ever tighten the client decision,
+ *   which is where the tag actually boots.
+ *
+ * ## The escape hatch
+ *
+ * `NEXT_PUBLIC_ANALYTICS_ALLOW_NONPROD=1` re-enables emission where the rules
+ * above would silence it, for the times someone genuinely needs to exercise
+ * the taxonomy against GA DebugView. It is deliberately paired with
+ * `analyticsEnvironmentForcesInternal`, so a build using it stamps
+ * `traffic_type: 'internal'` on everything unconditionally — the hatch cannot
+ * become the leak it exists beside.
+ */
+/** The env var that re-enables analytics where this module would silence it. */
+export declare const ANALYTICS_ALLOW_NONPROD_ENV = "NEXT_PUBLIC_ANALYTICS_ALLOW_NONPROD";
+export interface AnalyticsEnvironment {
+    /** `process.env.NODE_ENV`. */
+    nodeEnv?: string | null;
+    /** `VERCEL_ENV`, mapped into the client bundle by each app's next.config. */
+    deployEnv?: string | null;
+    /** The escape hatch's raw value. */
+    allowNonProduction?: string | null;
+    /**
+     * The host this document is served from, absent server-side.
+     *
+     * Undefined is NOT loopback: a server render has no location and must keep
+     * the build-time answer, or the tenant's `<Script>` would stop rendering on
+     * every real deployment.
+     */
+    hostname?: string | null;
+}
+/**
+ * The build's own environment.
+ *
+ * Read through `process.env` at CALL time rather than captured at module load,
+ * so a spec can drive every branch — the alternative is a module constant that
+ * can only ever be observed in one state, which is the shape of a check that
+ * cannot fail.
+ */
+export declare function readAnalyticsEnvironment(): AnalyticsEnvironment;
+/**
+ * Whether this build may load a Google Analytics tag and send hits at all.
+ *
+ * The one question both apps ask. `false` means the tag is never created —
+ * not created and then suppressed — because a resident tag re-creates `_ga`
+ * and reports on its own (the AGL-1608 lesson), and because "no tag" is the
+ * only state that needs no filter to be true.
+ */
+export declare function analyticsMayEmit(env?: AnalyticsEnvironment): boolean;
+/**
+ * Whether every hit from this build must carry `traffic_type: 'internal'`
+ * regardless of who is signed in or what the browser opted into.
+ *
+ * True only for a non-production build running with the escape hatch on —
+ * i.e. exactly the builds that emit *because someone asked them to*, which are
+ * by definition ours. Keeps the hatch from reopening the hole.
+ */
+export declare function analyticsEnvironmentForcesInternal(env?: AnalyticsEnvironment): boolean;
+export default analyticsMayEmit;