@farming-labs/docs 0.2.120 → 0.2.122

package/dist/sitemap.mjs

@@ -0,0 +1,254 @@
+import { resolveDocsDiscoveryApiRoute } from "./standards-discovery.mjs";
+
+//#region src/sitemap.ts
+const DEFAULT_SITEMAP_XML_ROUTE = "/sitemap.xml";
+const DEFAULT_SITEMAP_MD_ROUTE = "/sitemap.md";
+const DEFAULT_SITEMAP_MD_DOCS_ROUTE = "/docs/sitemap.md";
+const DEFAULT_SITEMAP_MD_WELL_KNOWN_ROUTE = "/.well-known/sitemap.md";
+const DEFAULT_SITEMAP_MANIFEST_PATH = ".farming-labs/sitemap-manifest.json";
+function normalizeUrlPath(value) {
+	const normalized = value.replace(/\/+/g, "/");
+	if (normalized === "/") return normalized;
+	return normalized.replace(/\/+$/, "");
+}
+function normalizeRoutePrefix(value) {
+	if (!value) return "";
+	const normalized = normalizeUrlPath(`/${value.replace(/^\/+|\/+$/g, "")}`);
+	return normalized === "/" ? "" : normalized;
+}
+function joinRoute(prefix, route) {
+	return normalizeUrlPath(`${prefix}/${route.replace(/^\/+/, "")}`);
+}
+function normalizeDateOnly(value) {
+	if (!value) return void 0;
+	const trimmed = value.trim();
+	if (!trimmed) return void 0;
+	const dateOnly = trimmed.match(/^(\d{4}-\d{2}-\d{2})/);
+	if (dateOnly) return dateOnly[1];
+	const parsed = new Date(trimmed);
+	if (Number.isNaN(parsed.getTime())) return void 0;
+	return parsed.toISOString().slice(0, 10);
+}
+function normalizeBaseUrl(value) {
+	if (!value) return void 0;
+	return value.trim().replace(/\/+$/, "") || void 0;
+}
+function isEnabledObject(config) {
+	if (config === false) return false;
+	if (config === void 0) return true;
+	if (config === true) return true;
+	return config.enabled !== false;
+}
+function resolveDocsSitemapConfig(sitemap, defaults = {}) {
+	const objectConfig = sitemap && typeof sitemap === "object" ? sitemap : {};
+	const routePrefix = normalizeRoutePrefix(objectConfig.routePrefix);
+	const xmlConfig = objectConfig.xml;
+	const markdownConfig = objectConfig.markdown;
+	const xmlEnabled = xmlConfig === false ? false : typeof xmlConfig === "object" ? xmlConfig.enabled ?? true : true;
+	const markdownEnabled = markdownConfig === false ? false : typeof markdownConfig === "object" ? markdownConfig.enabled ?? true : true;
+	return {
+		enabled: isEnabledObject(sitemap),
+		routePrefix,
+		baseUrl: normalizeBaseUrl(objectConfig.baseUrl ?? defaults.baseUrl),
+		manifestPath: objectConfig.manifestPath ?? DEFAULT_SITEMAP_MANIFEST_PATH,
+		xml: {
+			enabled: xmlEnabled,
+			includeLastmod: typeof xmlConfig === "object" ? xmlConfig.includeLastmod ?? true : true,
+			route: joinRoute(routePrefix, DEFAULT_SITEMAP_XML_ROUTE)
+		},
+		markdown: {
+			enabled: markdownEnabled,
+			includeDescriptions: typeof markdownConfig === "object" ? markdownConfig.includeDescriptions ?? true : true,
+			includeLastmod: typeof markdownConfig === "object" ? markdownConfig.includeLastmod ?? true : true,
+			linkTarget: typeof markdownConfig === "object" ? markdownConfig.linkTarget ?? "both" : "both",
+			route: joinRoute(routePrefix, DEFAULT_SITEMAP_MD_ROUTE),
+			docsRoute: routePrefix ? void 0 : DEFAULT_SITEMAP_MD_DOCS_ROUTE,
+			wellKnownRoute: joinRoute(routePrefix, DEFAULT_SITEMAP_MD_WELL_KNOWN_ROUTE)
+		}
+	};
+}
+function resolveDocsSitemapRequest(url, sitemap, options = {}) {
+	const pathname = normalizeUrlPath(url.pathname);
+	const format = url.searchParams.get("format")?.trim();
+	if (pathname === resolveDocsDiscoveryApiRoute(options.apiRoute)) {
+		if (format === "sitemap-xml") return "xml";
+		if (format === "sitemap-md" || format === "sitemap-markdown") return "markdown";
+	}
+	const resolved = resolveDocsSitemapConfig(sitemap);
+	if (!resolved.enabled) return null;
+	if (resolved.xml.enabled && pathname === resolved.xml.route) return "xml";
+	if (resolved.markdown.enabled && (pathname === resolved.markdown.route || pathname === resolved.markdown.docsRoute || pathname === resolved.markdown.wellKnownRoute)) return "markdown";
+	return null;
+}
+function toDocsSitemapMarkdownUrl(url) {
+	const normalized = normalizeUrlPath(url);
+	return normalized.endsWith(".md") ? normalized : `${normalized}.md`;
+}
+function absolutizeUrl(baseUrl, url) {
+	if (/^https?:\/\//i.test(url)) return url;
+	const base = normalizeBaseUrl(baseUrl);
+	return base ? `${base}${url.startsWith("/") ? url : `/${url}`}` : url;
+}
+function escapeXml(value) {
+	return value.replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;").replace(/"/g, "&quot;").replace(/'/g, "&apos;");
+}
+function hashString(value) {
+	let hash = 14695981039346656037n;
+	const bytes = new TextEncoder().encode(value);
+	for (const byte of bytes) {
+		hash ^= BigInt(byte);
+		hash = BigInt.asUintN(64, hash * 1099511628211n);
+	}
+	return `"fnv1a64-${hash.toString(16).padStart(16, "0")}"`;
+}
+function newestLastmod(pages) {
+	let newest;
+	for (const page of pages) {
+		const date = normalizeDateOnly(page.lastmod);
+		if (!date) continue;
+		if (!newest || date > newest) newest = date;
+	}
+	return newest;
+}
+function titleize(value) {
+	return value.replace(/-/g, " ").replace(/\b\w/g, (char) => char.toUpperCase());
+}
+function sitemapSectionName(entry, pageUrl) {
+	const normalizedEntry = `/${entry.replace(/^\/+|\/+$/g, "") || "docs"}`;
+	const normalizedUrl = normalizeUrlPath(pageUrl);
+	if (normalizedUrl === normalizedEntry) return "Overview";
+	const firstSegment = (normalizedUrl.startsWith(`${normalizedEntry}/`) ? normalizedUrl.slice(normalizedEntry.length + 1) : normalizedUrl.replace(/^\/+/, "")).split("/").filter(Boolean)[0];
+	return firstSegment ? titleize(firstSegment) : "Pages";
+}
+function buildDocsSitemapManifest(options) {
+	const baseUrl = normalizeBaseUrl(options.baseUrl);
+	const seen = /* @__PURE__ */ new Set();
+	const pages = [];
+	for (const page of options.pages) {
+		const url = normalizeUrlPath(page.url);
+		if (seen.has(url)) continue;
+		seen.add(url);
+		const resolvedLastmod = options.resolveLastmod?.(page);
+		const fallbackLastmod = normalizeDateOnly(page.lastmod ?? page.lastModified);
+		const lastmod = normalizeDateOnly(resolvedLastmod?.lastmod) ?? fallbackLastmod;
+		pages.push({
+			url,
+			absoluteUrl: absolutizeUrl(baseUrl, url),
+			markdownUrl: page.markdownUrl ?? toDocsSitemapMarkdownUrl(url),
+			title: page.title,
+			description: page.description,
+			sourcePath: page.sourcePath,
+			lastmod,
+			lastmodSource: resolvedLastmod?.lastmodSource ?? (lastmod ? "unknown" : void 0),
+			related: page.related?.map((link) => link.href)
+		});
+	}
+	pages.sort((left, right) => left.url.localeCompare(right.url));
+	return {
+		version: 1,
+		generatedAt: options.generatedAt ?? (/* @__PURE__ */ new Date()).toISOString(),
+		baseUrl,
+		entry: options.entry ?? "docs",
+		siteTitle: options.siteTitle,
+		pages
+	};
+}
+function renderDocsSitemapXml(manifest, options = {}) {
+	const baseUrl = normalizeBaseUrl(options.baseUrl ?? manifest.baseUrl);
+	const includeLastmod = options.includeLastmod ?? true;
+	const lines = ["<?xml version=\"1.0\" encoding=\"UTF-8\"?>", "<urlset xmlns=\"http://www.sitemaps.org/schemas/sitemap/0.9\">"];
+	for (const page of manifest.pages) {
+		lines.push("  <url>");
+		lines.push(`    <loc>${escapeXml(page.absoluteUrl ?? absolutizeUrl(baseUrl, page.url))}</loc>`);
+		const lastmod = normalizeDateOnly(page.lastmod);
+		if (includeLastmod && lastmod) lines.push(`    <lastmod>${lastmod}</lastmod>`);
+		lines.push("  </url>");
+	}
+	lines.push("</urlset>");
+	return `${lines.join("\n")}\n`;
+}
+function renderDocsSitemapMarkdown(manifest, options = {}) {
+	const siteTitle = manifest.siteTitle ?? "Documentation";
+	const includeDescriptions = options.includeDescriptions ?? true;
+	const includeLastmod = options.includeLastmod ?? true;
+	const linkTarget = options.linkTarget ?? "both";
+	const lines = [`# ${siteTitle} Sitemap`, ""];
+	const baseUrl = normalizeBaseUrl(options.baseUrl ?? manifest.baseUrl);
+	if (baseUrl) lines.push(`Base URL: ${baseUrl}`);
+	lines.push(`Docs entry: /${manifest.entry.replace(/^\/+|\/+$/g, "") || "docs"}`);
+	lines.push(`Generated: ${normalizeDateOnly(manifest.generatedAt) ?? manifest.generatedAt}`, "");
+	const groups = /* @__PURE__ */ new Map();
+	for (const page of manifest.pages) {
+		const sectionName = sitemapSectionName(manifest.entry, page.url);
+		groups.set(sectionName, [...groups.get(sectionName) ?? [], page]);
+	}
+	for (const [sectionName, pages] of groups) {
+		lines.push(`## ${sectionName}`, "");
+		for (const page of pages) {
+			const primaryHref = linkTarget === "markdown" ? page.markdownUrl : page.url;
+			lines.push(`- [${page.title}](${primaryHref})`);
+			if (linkTarget === "both" || linkTarget === "markdown") lines.push(`  Markdown: ${page.markdownUrl}`);
+			if (includeDescriptions && page.description) lines.push(`  Description: ${page.description}`);
+			const lastmod = normalizeDateOnly(page.lastmod);
+			if (includeLastmod && lastmod) lines.push(`  Last updated: ${lastmod}`);
+			if (page.related && page.related.length > 0) lines.push(`  Related: ${page.related.join(", ")}`);
+			lines.push("");
+		}
+	}
+	return lines.join("\n").replace(/\n{3,}/g, "\n\n");
+}
+function readDocsSitemapManifestFromContentMap(contentMap) {
+	if (!contentMap) return null;
+	const raw = contentMap[`/${DEFAULT_SITEMAP_MANIFEST_PATH}`] ?? contentMap[DEFAULT_SITEMAP_MANIFEST_PATH];
+	if (!raw) return null;
+	try {
+		return JSON.parse(raw);
+	} catch {
+		return null;
+	}
+}
+function resolveDocsSitemapPageLastmod(manifest, url) {
+	if (!manifest) return void 0;
+	const normalizedUrl = normalizeUrlPath(url);
+	return normalizeDateOnly(manifest.pages.find((entry) => normalizeUrlPath(entry.url) === normalizedUrl)?.lastmod);
+}
+function createDocsSitemapResponse({ request, apiRoute, sitemap, entry = "docs", siteTitle, baseUrl, pages, manifest }) {
+	const url = new URL(request.url);
+	const format = resolveDocsSitemapRequest(url, sitemap, { apiRoute });
+	if (!format) return null;
+	const resolved = resolveDocsSitemapConfig(sitemap, { baseUrl });
+	if (!resolved.enabled) return null;
+	if (format === "xml" && !resolved.xml.enabled) return null;
+	if (format === "markdown" && !resolved.markdown.enabled) return null;
+	const nextManifest = manifest ?? buildDocsSitemapManifest({
+		pages,
+		entry,
+		siteTitle,
+		baseUrl: resolved.baseUrl ?? url.origin
+	});
+	const responseBaseUrl = resolved.baseUrl ?? nextManifest.baseUrl ?? url.origin;
+	const body = format === "xml" ? renderDocsSitemapXml(nextManifest, {
+		baseUrl: responseBaseUrl,
+		includeLastmod: resolved.xml.includeLastmod
+	}) : renderDocsSitemapMarkdown(nextManifest, {
+		baseUrl: responseBaseUrl,
+		includeDescriptions: resolved.markdown.includeDescriptions,
+		includeLastmod: resolved.markdown.includeLastmod,
+		linkTarget: resolved.markdown.linkTarget
+	});
+	const headers = new Headers({
+		"Content-Type": format === "xml" ? "application/xml; charset=utf-8" : "text/markdown; charset=utf-8",
+		"Cache-Control": "public, max-age=0, s-maxage=3600, stale-while-revalidate=86400",
+		ETag: hashString(body)
+	});
+	const lastModified = newestLastmod(nextManifest.pages);
+	if (lastModified) headers.set("Last-Modified", (/* @__PURE__ */ new Date(`${lastModified}T00:00:00.000Z`)).toUTCString());
+	if (request.headers.get("if-none-match") === headers.get("ETag")) return new Response(null, {
+		status: 304,
+		headers
+	});
+	return new Response(body, { headers });
+}
+
+//#endregion
+export { DEFAULT_SITEMAP_MANIFEST_PATH, DEFAULT_SITEMAP_MD_DOCS_ROUTE, DEFAULT_SITEMAP_MD_ROUTE, DEFAULT_SITEMAP_MD_WELL_KNOWN_ROUTE, DEFAULT_SITEMAP_XML_ROUTE, buildDocsSitemapManifest, createDocsSitemapResponse, readDocsSitemapManifestFromContentMap, renderDocsSitemapMarkdown, renderDocsSitemapXml, resolveDocsSitemapConfig, resolveDocsSitemapPageLastmod, resolveDocsSitemapRequest, toDocsSitemapMarkdownUrl };

package/dist/{standards-discovery-BHPc7YIX.d.mts → standards-discovery.d.mts}

@@ -1,4 +1,4 @@
-import { F as DocsAgentA2ASecurityScheme, L as DocsAgentA2ASkill, N as DocsAgentA2AProtocolBinding, P as DocsAgentA2ASecurityRequirement, b as DocsAgentA2AConfig, y as DocsAgentA2ACapabilities } from "./types-BJFeMXWZ.mjs";
+import { DocsAgentA2ACapabilities, DocsAgentA2AConfig, DocsAgentA2AProtocolBinding, DocsAgentA2ASecurityRequirement, DocsAgentA2ASecurityScheme, DocsAgentA2ASkill } from "./types.mjs";
 
 //#region src/standards-discovery.d.ts
 declare const DEFAULT_API_CATALOG_ROUTE = "/.well-known/api-catalog";
@@ -248,4 +248,4 @@ declare function createDocsStandardsResponse({
   lastModified
 }: CreateDocsStandardsResponseOptions): Promise<Response | null>;
 //#endregion
-export { resolveDocsDiscoveryApiRoute as $, DocsAgentSkillIndexEntry as A, DocsPublishedAgentSkillFile as B, DOCS_AGENT_MANIFEST_FORMAT as C, DocsA2AAgentCard as D, DOCS_AGENT_MANIFEST_VERSION as E, DocsApiCatalogLinkTarget as F, buildDocsA2AAgentCard as G, DocsStandardsDiscoveryRequest as H, DocsApiCatalogOpenApiDefinition as I, buildDocsLegacySkillsIndex as J, buildDocsAgentSkillsIndex as K, DocsApiCatalogOptions as L, DocsApiCatalog as M, DocsApiCatalogApiTarget as N, DocsA2AAgentCardOptions as O, DocsApiCatalogLinkContext as P, isDocsStandardsDiscoveryRequest as Q, DocsDiscoveryApiRouteOptions as R, DEFAULT_LEGACY_SKILLS_ROUTE_PREFIX as S, DOCS_AGENT_MANIFEST_SCHEMA_URI as T, DocsStandardsDiscoveryRouteOptions as U, DocsPublishedAgentSkillOptions as V, appendDocsDiscoveryLinkHeader as W, getDocsAgentManifestLinkHeader as X, createDocsStandardsResponse as Y, getDocsDiscoveryLinkHeader as Z, DEFAULT_AGENT_SKILL_RESOURCE_FORMAT as _, DEFAULT_A2A_AGENT_CARD_FORMAT as a, DEFAULT_LEGACY_SKILLS_INDEX_FORMAT as b, DEFAULT_A2A_PROTOCOL_VERSION as c, DEFAULT_AGENT_SKILLS_INDEX_ROUTE as d, resolveDocsPublishedAgentSkill as et, DEFAULT_AGENT_SKILLS_ROUTE_PATTERN as f, DEFAULT_AGENT_SKILL_FORMAT as g, DEFAULT_AGENT_SKILL_FILE_FORMAT as h, CreateDocsStandardsResponseOptions as i, DocsAgentSkillsIndex as j, DocsA2AAgentInterface as k, DEFAULT_AGENT_SKILLS_ARCHIVE_ROUTE_PATTERN as l, DEFAULT_AGENT_SKILL_ARCHIVE_FORMAT as m, API_CATALOG_MEDIA_TYPE as n, sha256DocsDiscoveryContent as nt, DEFAULT_A2A_AGENT_CARD_ROUTE as o, DEFAULT_AGENT_SKILLS_ROUTE_PREFIX as p, buildDocsApiCatalog as q, API_CATALOG_PROFILE_URI as r, DEFAULT_A2A_PROTOCOL_BINDING as s, AGENT_SKILLS_DISCOVERY_SCHEMA_URI as t, resolveDocsStandardsDiscoveryRequest as tt, DEFAULT_AGENT_SKILLS_INDEX_FORMAT as u, DEFAULT_API_CATALOG_FORMAT as v, DOCS_AGENT_MANIFEST_SCHEMA_MEDIA_TYPE as w, DEFAULT_LEGACY_SKILLS_INDEX_ROUTE as x, DEFAULT_API_CATALOG_ROUTE as y, DocsPublishedAgentSkill as z };
+export { AGENT_SKILLS_DISCOVERY_SCHEMA_URI, API_CATALOG_MEDIA_TYPE, API_CATALOG_PROFILE_URI, CreateDocsStandardsResponseOptions, DEFAULT_A2A_AGENT_CARD_FORMAT, DEFAULT_A2A_AGENT_CARD_ROUTE, DEFAULT_A2A_PROTOCOL_BINDING, DEFAULT_A2A_PROTOCOL_VERSION, DEFAULT_AGENT_SKILLS_ARCHIVE_ROUTE_PATTERN, DEFAULT_AGENT_SKILLS_INDEX_FORMAT, DEFAULT_AGENT_SKILLS_INDEX_ROUTE, DEFAULT_AGENT_SKILLS_ROUTE_PATTERN, DEFAULT_AGENT_SKILLS_ROUTE_PREFIX, DEFAULT_AGENT_SKILL_ARCHIVE_FORMAT, DEFAULT_AGENT_SKILL_FILE_FORMAT, DEFAULT_AGENT_SKILL_FORMAT, DEFAULT_AGENT_SKILL_RESOURCE_FORMAT, DEFAULT_API_CATALOG_FORMAT, DEFAULT_API_CATALOG_ROUTE, DEFAULT_LEGACY_SKILLS_INDEX_FORMAT, DEFAULT_LEGACY_SKILLS_INDEX_ROUTE, DEFAULT_LEGACY_SKILLS_ROUTE_PREFIX, DOCS_AGENT_MANIFEST_FORMAT, DOCS_AGENT_MANIFEST_SCHEMA_MEDIA_TYPE, DOCS_AGENT_MANIFEST_SCHEMA_URI, DOCS_AGENT_MANIFEST_VERSION, DocsA2AAgentCard, DocsA2AAgentCardOptions, DocsA2AAgentInterface, DocsAgentSkillIndexEntry, DocsAgentSkillsIndex, DocsApiCatalog, DocsApiCatalogApiTarget, DocsApiCatalogLinkContext, DocsApiCatalogLinkTarget, DocsApiCatalogOpenApiDefinition, DocsApiCatalogOptions, DocsDiscoveryApiRouteOptions, DocsLegacySkillsIndex, DocsPublishedAgentSkill, DocsPublishedAgentSkillFile, DocsPublishedAgentSkillOptions, DocsStandardsDiscoveryRequest, DocsStandardsDiscoveryRouteOptions, appendDocsDiscoveryLinkHeader, buildDocsA2AAgentCard, buildDocsAgentSkillsIndex, buildDocsApiCatalog, buildDocsLegacySkillsIndex, createDocsStandardsResponse, getDocsAgentManifestLinkHeader, getDocsDiscoveryLinkHeader, isDocsStandardsDiscoveryRequest, resolveDocsDiscoveryApiRoute, resolveDocsPublishedAgentSkill, resolveDocsStandardsDiscoveryRequest, sha256DocsDiscoveryContent };

package/dist/{standards-discovery-sSEojU80.mjs → standards-discovery.mjs}

@@ -1,143 +1,7 @@
-import { i as sha256DocsContent } from "./retrieval-digest-CT-eIEcp.mjs";
+import { sha256DocsContent } from "./retrieval-digest.mjs";
+import { createDocsCacheableResponse } from "./http-cache.mjs";
 import { parseDocsAgentSkillFrontmatter, validateDocsAgentSkillFrontmatter } from "./agent-skills-spec.mjs";
 
-//#region src/http-cache.ts
-const BASE64_ALPHABET = "ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789+/";
-const MAX_CACHED_TEXT_REPRESENTATIONS = 64;
-const MAX_CACHED_TEXT_CHARACTERS = 8 * 1024 * 1024;
-const textValidatorCache = /* @__PURE__ */ new Map();
-let cachedTextCharacters = 0;
-function encodeBase64(bytes) {
-	let encoded = "";
-	for (let offset = 0; offset < bytes.length; offset += 3) {
-		const first = bytes[offset];
-		const second = bytes[offset + 1];
-		const third = bytes[offset + 2];
-		const value = first << 16 | (second ?? 0) << 8 | (third ?? 0);
-		encoded += BASE64_ALPHABET[value >>> 18 & 63];
-		encoded += BASE64_ALPHABET[value >>> 12 & 63];
-		encoded += second === void 0 ? "=" : BASE64_ALPHABET[value >>> 6 & 63];
-		encoded += third === void 0 ? "=" : BASE64_ALPHABET[value & 63];
-	}
-	return encoded;
-}
-function sha256HexBytes(sha256) {
-	if (!/^[a-f\d]{64}$/iu.test(sha256)) throw new Error("A SHA-256 digest must contain exactly 64 hexadecimal characters.");
-	const bytes = new Uint8Array(32);
-	for (let index = 0; index < bytes.length; index += 1) bytes[index] = Number.parseInt(sha256.slice(index * 2, index * 2 + 2), 16);
-	return bytes;
-}
-/** Format an RFC 9530 Content-Digest field from a SHA-256 hex digest. */
-function formatDocsContentDigest(sha256) {
-	return `sha-256=:${encodeBase64(sha256HexBytes(sha256))}:`;
-}
-function resolveDocsContentValidators(content, suppliedSha256) {
-	if (suppliedSha256) return {
-		sha256: suppliedSha256,
-		contentDigest: formatDocsContentDigest(suppliedSha256)
-	};
-	const cached = typeof content === "string" ? textValidatorCache.get(content) : void 0;
-	if (cached) {
-		if (typeof content === "string") {
-			textValidatorCache.delete(content);
-			textValidatorCache.set(content, cached);
-		}
-		return cached;
-	}
-	const sha256 = sha256DocsContent(content);
-	const validators = {
-		sha256,
-		contentDigest: formatDocsContentDigest(sha256)
-	};
-	if (typeof content !== "string") return validators;
-	if (content.length <= MAX_CACHED_TEXT_CHARACTERS) {
-		textValidatorCache.set(content, validators);
-		cachedTextCharacters += content.length;
-		while (textValidatorCache.size > MAX_CACHED_TEXT_REPRESENTATIONS || cachedTextCharacters > MAX_CACHED_TEXT_CHARACTERS) {
-			const oldest = textValidatorCache.keys().next().value;
-			if (oldest === void 0) break;
-			textValidatorCache.delete(oldest);
-			cachedTextCharacters -= oldest.length;
-		}
-	}
-	return validators;
-}
-/** Normalize an exact source timestamp for Last-Modified. */
-function resolveDocsHttpDate(value) {
-	if (!value) return void 0;
-	if (typeof value === "string" && !/(?:T|\s)\d{2}:\d{2}(?::\d{2}(?:\.\d+)?)?/.test(value.trim())) return;
-	const date = value instanceof Date ? value : new Date(value);
-	if (Number.isNaN(date.getTime())) return void 0;
-	return date.toUTCString();
-}
-function normalizeEtag(value) {
-	return value.trim().replace(/^W\//iu, "");
-}
-/** Match strong or weak If-None-Match validators for a GET/HEAD representation. */
-function requestMatchesDocsEtag(request, etag) {
-	const header = request.headers.get("if-none-match");
-	if (!header) return false;
-	if (header.trim() === "*") return true;
-	const expected = normalizeEtag(etag);
-	return header.split(",").some((candidate) => normalizeEtag(candidate) === expected);
-}
-/** Apply If-Modified-Since only when the stronger If-None-Match validator is absent. */
-function requestHasFreshDocsDate(request, lastModified) {
-	const method = request.method.toUpperCase();
-	if (method !== "GET" && method !== "HEAD") return false;
-	if (!lastModified || request.headers.has("if-none-match")) return false;
-	const ifModifiedSince = request.headers.get("if-modified-since");
-	if (!ifModifiedSince) return false;
-	const resourceTime = Date.parse(lastModified);
-	const requestTime = Date.parse(ifModifiedSince);
-	return Number.isFinite(resourceTime) && Number.isFinite(requestTime) && Math.floor(resourceTime / 1e3) <= Math.floor(requestTime / 1e3);
-}
-function exposeValidatorHeaders(headers) {
-	if (!headers.has("Access-Control-Allow-Origin")) return;
-	const exposed = new Set((headers.get("Access-Control-Expose-Headers") ?? "").split(",").map((value) => value.trim()).filter(Boolean));
-	exposed.add("Content-Digest");
-	exposed.add("ETag");
-	if (headers.has("Last-Modified")) exposed.add("Last-Modified");
-	headers.set("Access-Control-Expose-Headers", [...exposed].join(", "));
-}
-/**
-* Build a byte-stable GET/HEAD response with HTTP validators and RFC 9530 integrity metadata.
-*/
-function createDocsCacheableResponse(options) {
-	const method = options.request.method.toUpperCase();
-	const isSafeRetrieval = method === "GET" || method === "HEAD";
-	const status = options.status ?? 200;
-	const canApplyConditionalRequest = status === 200;
-	const { sha256, contentDigest } = resolveDocsContentValidators(options.content, options.sha256);
-	const etag = `"${sha256}"`;
-	const lastModified = resolveDocsHttpDate(options.lastModified);
-	const headers = new Headers(options.headers);
-	headers.set("Content-Digest", contentDigest);
-	headers.set("ETag", etag);
-	if (lastModified) headers.set("Last-Modified", lastModified);
-	exposeValidatorHeaders(headers);
-	if (canApplyConditionalRequest && requestMatchesDocsEtag(options.request, etag)) {
-		headers.delete("Content-Type");
-		return new Response(null, {
-			status: isSafeRetrieval ? 304 : 412,
-			headers
-		});
-	}
-	if (canApplyConditionalRequest && isSafeRetrieval && requestHasFreshDocsDate(options.request, lastModified)) {
-		headers.delete("Content-Type");
-		return new Response(null, {
-			status: 304,
-			headers
-		});
-	}
-	const body = method === "HEAD" ? null : typeof options.content === "string" ? options.content : options.content;
-	return new Response(body, {
-		status,
-		headers
-	});
-}
-
-//#endregion
 //#region src/standards-discovery.ts
 const DEFAULT_API_CATALOG_ROUTE = "/.well-known/api-catalog";
 const DEFAULT_API_CATALOG_FORMAT = "api-catalog";
@@ -940,4 +804,4 @@ async function createDocsStandardsResponse({ request, apiCatalog, apiCatalogEnab
 }
 
 //#endregion
-export { buildDocsLegacySkillsIndex as A, createDocsCacheableResponse as B, DOCS_AGENT_MANIFEST_SCHEMA_MEDIA_TYPE as C, buildDocsA2AAgentCard as D, appendDocsDiscoveryLinkHeader as E, isDocsStandardsDiscoveryRequest as F, requestHasFreshDocsDate as H, resolveDocsDiscoveryApiRoute as I, resolveDocsPublishedAgentSkill as L, createDocsStandardsResponse as M, getDocsAgentManifestLinkHeader as N, buildDocsAgentSkillsIndex as O, getDocsDiscoveryLinkHeader as P, resolveDocsStandardsDiscoveryRequest as R, DOCS_AGENT_MANIFEST_FORMAT as S, DOCS_AGENT_MANIFEST_VERSION as T, requestMatchesDocsEtag as U, formatDocsContentDigest as V, resolveDocsHttpDate as W, DEFAULT_API_CATALOG_FORMAT as _, DEFAULT_A2A_AGENT_CARD_ROUTE as a, DEFAULT_LEGACY_SKILLS_INDEX_ROUTE as b, DEFAULT_AGENT_SKILLS_ARCHIVE_ROUTE_PATTERN as c, DEFAULT_AGENT_SKILLS_ROUTE_PATTERN as d, DEFAULT_AGENT_SKILLS_ROUTE_PREFIX as f, DEFAULT_AGENT_SKILL_RESOURCE_FORMAT as g, DEFAULT_AGENT_SKILL_FORMAT as h, DEFAULT_A2A_AGENT_CARD_FORMAT as i, buildDocsPublishedAgentSkill as j, buildDocsApiCatalog as k, DEFAULT_AGENT_SKILLS_INDEX_FORMAT as l, DEFAULT_AGENT_SKILL_FILE_FORMAT as m, API_CATALOG_MEDIA_TYPE as n, DEFAULT_A2A_PROTOCOL_BINDING as o, DEFAULT_AGENT_SKILL_ARCHIVE_FORMAT as p, API_CATALOG_PROFILE_URI as r, DEFAULT_A2A_PROTOCOL_VERSION as s, AGENT_SKILLS_DISCOVERY_SCHEMA_URI as t, DEFAULT_AGENT_SKILLS_INDEX_ROUTE as u, DEFAULT_API_CATALOG_ROUTE as v, DOCS_AGENT_MANIFEST_SCHEMA_URI as w, DEFAULT_LEGACY_SKILLS_ROUTE_PREFIX as x, DEFAULT_LEGACY_SKILLS_INDEX_FORMAT as y, sha256DocsDiscoveryContent as z };
+export { AGENT_SKILLS_DISCOVERY_SCHEMA_URI, API_CATALOG_MEDIA_TYPE, API_CATALOG_PROFILE_URI, DEFAULT_A2A_AGENT_CARD_FORMAT, DEFAULT_A2A_AGENT_CARD_ROUTE, DEFAULT_A2A_PROTOCOL_BINDING, DEFAULT_A2A_PROTOCOL_VERSION, DEFAULT_AGENT_SKILLS_ARCHIVE_ROUTE_PATTERN, DEFAULT_AGENT_SKILLS_INDEX_FORMAT, DEFAULT_AGENT_SKILLS_INDEX_ROUTE, DEFAULT_AGENT_SKILLS_ROUTE_PATTERN, DEFAULT_AGENT_SKILLS_ROUTE_PREFIX, DEFAULT_AGENT_SKILL_ARCHIVE_FORMAT, DEFAULT_AGENT_SKILL_FILE_FORMAT, DEFAULT_AGENT_SKILL_FORMAT, DEFAULT_AGENT_SKILL_RESOURCE_FORMAT, DEFAULT_API_CATALOG_FORMAT, DEFAULT_API_CATALOG_ROUTE, DEFAULT_LEGACY_SKILLS_INDEX_FORMAT, DEFAULT_LEGACY_SKILLS_INDEX_ROUTE, DEFAULT_LEGACY_SKILLS_ROUTE_PREFIX, DOCS_AGENT_MANIFEST_FORMAT, DOCS_AGENT_MANIFEST_SCHEMA_MEDIA_TYPE, DOCS_AGENT_MANIFEST_SCHEMA_URI, DOCS_AGENT_MANIFEST_VERSION, appendDocsDiscoveryLinkHeader, buildDocsA2AAgentCard, buildDocsAgentSkillsIndex, buildDocsApiCatalog, buildDocsLegacySkillsIndex, buildDocsPublishedAgentSkill, createDocsStandardsResponse, getDocsAgentManifestLinkHeader, getDocsDiscoveryLinkHeader, isDocsStandardsDiscoveryRequest, resolveDocsDiscoveryApiRoute, resolveDocsPublishedAgentSkill, resolveDocsStandardsDiscoveryRequest, sha256DocsDiscoveryContent };

package/dist/telemetry-runtime.d.mts

@@ -0,0 +1,42 @@
+import { DocsConfig, DocsTelemetryAgentSurface, DocsTelemetryConfig, DocsTelemetryEvent, DocsTelemetryFramework } from "./types.mjs";
+
+//#region src/telemetry-runtime.d.ts
+interface ResolvedDocsTelemetryConfig {
+  enabled: boolean;
+  endpoint?: string;
+}
+interface DocsTelemetryContext {
+  framework?: DocsTelemetryFramework;
+  request?: Request;
+  siteOrigin?: string;
+  properties?: Record<string, unknown>;
+}
+interface DocsTelemetryAgentSurfaceContext extends DocsTelemetryContext {
+  surface: DocsTelemetryAgentSurface;
+}
+interface DocsTelemetryPageViewContext {
+  framework?: DocsTelemetryFramework;
+  siteOrigin?: string;
+  path?: string;
+  locale?: string;
+}
+interface DocsTelemetryAgentSurfaceRequestOptions {
+  entry: string;
+  llmsTxt?: DocsConfig["llmsTxt"];
+  feedback?: DocsConfig["feedback"];
+}
+declare function resolveDocsTelemetryConfig(telemetry?: boolean | DocsTelemetryConfig): ResolvedDocsTelemetryConfig;
+/** Normalize an HTTP(S) telemetry site value to its origin. */
+declare function normalizeDocsTelemetryOrigin(candidate: string | undefined): string | undefined;
+/** Return whether a telemetry origin points at a local development server. */
+declare function isLocalDocsTelemetryOrigin(candidate: string | undefined): boolean;
+declare function emitDocsTelemetryEvent(telemetry: boolean | DocsTelemetryConfig | undefined, event: DocsTelemetryEvent): Promise<void>;
+/**
+ * Emit a privacy-preserving browser page view for the maintainer telemetry dashboard.
+ *
+ * Page views include only the public site origin, pathname, locale, framework, and package
+ * metadata. They never include a query string, referrer, visitor id, IP address, or user agent.
+ */
+declare function emitDocsTelemetryPageViewEvent(telemetry: boolean | DocsTelemetryConfig | undefined, context?: DocsTelemetryPageViewContext): void;
+//#endregion
+export { DocsTelemetryAgentSurfaceContext, DocsTelemetryAgentSurfaceRequestOptions, DocsTelemetryContext, DocsTelemetryPageViewContext, ResolvedDocsTelemetryConfig, emitDocsTelemetryEvent, emitDocsTelemetryPageViewEvent, isLocalDocsTelemetryOrigin, normalizeDocsTelemetryOrigin, resolveDocsTelemetryConfig };