blodemd 0.0.13 → 0.0.14

package/docs/lib/docs-collection.ts

@@ -1,22 +1,7 @@
-import type { SiteConfig } from "@repo/models";
-
-export const getDocsCollection = (
-  config: SiteConfig
-): SiteConfig["collections"][number] | undefined =>
-  config.collections.find((collection) => collection.type === "docs");
-
-export const getDocsNavigation = (config: SiteConfig) =>
-  getDocsCollection(config)?.navigation ?? config.navigation;
-
-export const getDocsCollectionWithNavigation = (
-  config: SiteConfig
-): SiteConfig["collections"][number] | undefined => {
-  const docsCollection = getDocsCollection(config);
-  const docsNavigation = getDocsNavigation(config);
-
-  return docsCollection &&
-    docsNavigation &&
-    docsCollection.navigation !== docsNavigation
-    ? { ...docsCollection, navigation: docsNavigation }
-    : docsCollection;
-};
+// These helpers live in @repo/previewing; re-exported here so existing docs
+// imports keep working against the single shared implementation.
+export {
+  getDocsCollection,
+  getDocsCollectionWithNavigation,
+  getDocsNavigation,
+} from "@repo/previewing";

package/docs/lib/docs-runtime.tsx

@@ -5,7 +5,6 @@ import {
   buildPageMetadataMap,
   buildSearchIndex,
   buildUtilityIndex,
-  loadContentSource,
   loadPrebuiltContentIndex,
   loadPrebuiltSearchIndex,
   loadPrebuiltTocIndex,
@@ -282,6 +281,36 @@ const getTenantArtifacts = async (tenantSlug: string) => {
   });
 };
 
+export interface TenantSidebarData {
+  anchors: { label: string; href: string }[];
+  entries: NavEntry[];
+}
+
+export const getTenantSidebarData = cache(
+  async (
+    tenantSlug: string,
+    activeTabIndex: number
+  ): Promise<TenantSidebarData | null> => {
+    const artifacts = await getTenantArtifacts(tenantSlug);
+    if (
+      !artifacts ||
+      isConfigErrorResult(artifacts) ||
+      isUnpublishedTenantResult(artifacts)
+    ) {
+      return null;
+    }
+
+    const tabEntries = artifacts.tabs
+      ? getVisibleNavigation(artifacts.tabs[activeTabIndex]?.entries ?? [])
+      : null;
+
+    return {
+      anchors: artifacts.anchors,
+      entries: tabEntries ?? artifacts.visibleNav,
+    };
+  }
+);
+
 export const getTenantSearchItems = cache(async (tenantSlug: string) => {
   const artifacts = await getTenantArtifacts(tenantSlug);
   if (
@@ -324,6 +353,7 @@ export const getTenantSearchItems = cache(async (tenantSlug: string) => {
 
 const getRenderedPageData = async ({
   artifacts,
+  basePath,
   currentPath,
   relativePath,
   rawContent: preloadedRawContent,
@@ -331,13 +361,14 @@ const getRenderedPageData = async ({
   useToc,
 }: {
   artifacts: TenantArtifacts;
+  basePath?: string;
   currentPath: string;
   relativePath: string;
   rawContent?: string;
   toc?: TocItem[];
   useToc: boolean;
 }) => {
-  const cacheKey = `${getTenantArtifactsCacheKey(artifacts.tenant)}:${currentPath}`;
+  const cacheKey = `${getTenantArtifactsCacheKey(artifacts.tenant)}:${basePath ?? ""}:${currentPath}`;
 
   return await renderedPageCache.getOrCreate(cacheKey, async () => {
     const compiled =
@@ -346,10 +377,14 @@ const getRenderedPageData = async ({
       preloadedRawContent ??
       (compiled
         ? undefined
-        : await loadContentSource(artifacts.contentSource, relativePath));
+        : await artifacts.contentSource.readFile(relativePath));
     const rendered = compiled
-      ? await renderFromCompiled(compiled.compiledSource)
-      : await renderMdx(rawContent ?? "");
+      ? await renderFromCompiled(
+          compiled.compiledSource,
+          basePath,
+          relativePath
+        )
+      : await renderMdx(rawContent ?? "", basePath, relativePath);
 
     return {
       content: rendered.content,
@@ -389,6 +424,103 @@ const computePrevNext = (
   };
 };
 
+const META_DESCRIPTION_MIN = 120;
+const META_DESCRIPTION_MAX = 160;
+const META_FRONTMATTER_RE = /^---\s*\n[\s\S]*?\n---\s*\n?/;
+
+/**
+ * Reduce raw MDX/Markdown to a single line of readable prose so it can seed a
+ * meta description when a page has no (or a too-short) frontmatter description.
+ */
+const markdownToPlainText = (markdown: string): string =>
+  markdown
+    .replace(META_FRONTMATTER_RE, "")
+    .replaceAll(/```[\s\S]*?```/g, " ")
+    .replaceAll(/~~~[\s\S]*?~~~/g, " ")
+    .replaceAll(/`[^`]*`/g, " ")
+    .replaceAll(/!\[[^\]]*\]\([^)]*\)/g, " ")
+    .replaceAll(/\[([^\]]+)\]\([^)]*\)/g, "$1")
+    .replaceAll(/<[^>]+>/g, " ")
+    .replaceAll(/^\s{0,3}#{1,6}\s+/gm, "")
+    .replaceAll(/^\s{0,3}>\s?/gm, "")
+    .replaceAll(/^\s{0,3}(?:[-*+]|\d+\.)\s+/gm, "")
+    .replaceAll(/[*_~]+/g, "")
+    .replaceAll("|", " ")
+    .replaceAll(/\s+/g, " ")
+    .trim();
+
+const normalizeMetaText = (value?: string) =>
+  value ? value.replaceAll(/\s+/g, " ").trim() : "";
+
+const truncateMetaDescription = (text: string, max: number): string => {
+  if (text.length <= max) {
+    return text;
+  }
+  const slice = text.slice(0, max - 1);
+  const lastSpace = slice.lastIndexOf(" ");
+  const trimmed = (lastSpace > max * 0.6 ? slice.slice(0, lastSpace) : slice)
+    .replace(/[\s.,;:–—-]+$/, "")
+    .trim();
+  return `${trimmed}…`;
+};
+
+/**
+ * Build a 120-160 character meta description from (in order of preference) the
+ * frontmatter description, the page body, and a site-level fallback. Keeps the
+ * visible page subtitle untouched while giving crawlers a complete description.
+ */
+const deriveMetaDescription = ({
+  description,
+  rawText,
+  fallback,
+}: {
+  description?: string;
+  rawText?: string;
+  fallback?: string;
+}): string | undefined => {
+  const frontmatter = normalizeMetaText(description);
+  if (frontmatter.length >= META_DESCRIPTION_MIN) {
+    return truncateMetaDescription(frontmatter, META_DESCRIPTION_MAX);
+  }
+
+  let combined = frontmatter;
+  const excerpt = rawText ? markdownToPlainText(rawText) : "";
+  if (excerpt) {
+    if (
+      !frontmatter ||
+      excerpt.toLowerCase().startsWith(frontmatter.toLowerCase())
+    ) {
+      combined = excerpt;
+    } else if (combined.length < META_DESCRIPTION_MIN) {
+      combined = `${frontmatter} ${excerpt}`;
+    }
+  }
+
+  const fallbackText = normalizeMetaText(fallback);
+  if (
+    fallbackText &&
+    normalizeMetaText(combined).length < META_DESCRIPTION_MIN
+  ) {
+    combined = combined ? `${combined} ${fallbackText}` : fallbackText;
+  }
+
+  combined = normalizeMetaText(combined);
+  return combined
+    ? truncateMetaDescription(combined, META_DESCRIPTION_MAX)
+    : undefined;
+};
+
+const buildMetaDescriptionFallback = (
+  config: { name?: string; description?: string } | undefined,
+  title: string | undefined
+): string => {
+  const name = config?.name ?? "Docs";
+  const lead = title
+    ? `${title} — ${name} documentation.`
+    : `${name} documentation.`;
+  return config?.description ? `${lead} ${config.description}` : lead;
+};
+
 /**
  * Returns shell data (config, nav, title, breadcrumbs) from cached artifacts
  * without compiling MDX. Used by the page component to render the shell
@@ -434,6 +566,13 @@ export const getDocShellData = cache(
         hidden: isHidden,
         hideFooterPagination: false,
         kind: "openapi" as const,
+        metaDescription: deriveMetaDescription({
+          description: openApiEntry.operation.description,
+          fallback: buildMetaDescriptionFallback(
+            artifacts.config,
+            openApiEntry.operation.summary ?? openApiEntry.identifier
+          ),
+        }),
         mode: undefined as PageMode | undefined,
         nav: activeTabNav ?? artifacts.visibleNav,
         nextPage: computePrevNext(effectiveFlatNav, currentPath).nextPage,
@@ -481,6 +620,10 @@ export const getDocShellData = cache(
         hidden: false,
         hideFooterPagination: false,
         kind: "index" as const,
+        metaDescription: deriveMetaDescription({
+          description: entry.description,
+          fallback: buildMetaDescriptionFallback(artifacts.config, entry.title),
+        }),
         mode: undefined as PageMode | undefined,
         nav: showDocsNav ? (activeTabNav ?? artifacts.visibleNav) : [],
         nextPage: computePrevNext(effectiveFlatNav, currentPath).nextPage,
@@ -513,14 +656,14 @@ export const getDocShellData = cache(
       ? contextualOptionsRequirePageContent(artifacts.config.contextual.options)
       : false;
 
+    // Load the body when we need a TOC, contextual content, or a body excerpt
+    // to flesh out a short/missing frontmatter description for SEO.
+    const needsExcerpt = (entry.description ?? "").trim().length < 120;
     let rawContent: string | undefined;
     let toc: ReturnType<typeof extractToc> = prebuiltToc ?? [];
-    if ((!prebuiltToc && useToc) || needsRawContent) {
+    if ((!prebuiltToc && useToc) || needsRawContent || needsExcerpt) {
       try {
-        rawContent = await loadContentSource(
-          artifacts.contentSource,
-          entry.relativePath
-        );
+        rawContent = await artifacts.contentSource.readFile(entry.relativePath);
         if (!prebuiltToc && useToc) {
           toc = extractToc(rawContent);
         }
@@ -539,6 +682,11 @@ export const getDocShellData = cache(
       hidden: isHiddenByNav || entry.hidden === true,
       hideFooterPagination: pageMeta?.hideFooterPagination ?? false,
       kind: "page" as const,
+      metaDescription: deriveMetaDescription({
+        description: entry.description,
+        fallback: buildMetaDescriptionFallback(artifacts.config, entry.title),
+        rawText: rawContent,
+      }),
       mode: pageMeta?.mode,
       nav: showDocsNav ? (activeTabNav ?? artifacts.visibleNav) : [],
       nextPage,
@@ -562,6 +710,7 @@ export const getDocPageContent = cache(
   async (
     tenantSlug: string,
     slugKey: string,
+    basePath = "",
     rawContent?: string,
     toc?: TocItem[]
   ) => {
@@ -585,6 +734,7 @@ export const getDocPageContent = cache(
 
     return await getRenderedPageData({
       artifacts,
+      basePath,
       currentPath,
       rawContent,
       relativePath: entry.relativePath,

package/docs/lib/llms-full.ts

@@ -0,0 +1,82 @@
+export const LLMS_FULL_CHAR_LIMIT = 80_000;
+
+const FENCE_LINE_REGEX = /^ {0,3}(`{3,}|~{3,})/;
+
+const getTruncationFooter = (indexUrl: string) =>
+  [
+    "",
+    "---",
+    "",
+    "Content truncated to keep this response under crawler size limits.",
+    `Use ${indexUrl} for the full page index and fetch individual .md pages for uncapped content.`,
+  ].join("\n");
+
+const findOpenFence = (source: string) => {
+  let openFence: string | null = null;
+
+  for (const line of source.split(/\r?\n/)) {
+    const marker = FENCE_LINE_REGEX.exec(line)?.[1];
+    if (!marker) {
+      continue;
+    }
+
+    if (!openFence) {
+      openFence = marker;
+      continue;
+    }
+
+    if (marker[0] === openFence[0] && marker.length >= openFence.length) {
+      openFence = null;
+    }
+  }
+
+  return openFence;
+};
+
+const closeOpenFence = (source: string) => {
+  const openFence = findOpenFence(source);
+  return openFence ? `${source}\n${openFence}` : source;
+};
+
+const findTruncationBoundary = (source: string, minimum: number) => {
+  const sectionBoundary = source.lastIndexOf("\n# ");
+  if (sectionBoundary > minimum) {
+    return sectionBoundary;
+  }
+
+  const paragraphBoundary = source.lastIndexOf("\n\n");
+  if (paragraphBoundary > minimum) {
+    return paragraphBoundary;
+  }
+
+  const lineBoundary = source.lastIndexOf("\n");
+  return lineBoundary > 0 ? lineBoundary : source.length;
+};
+
+export const capLlmsFullContent = (
+  content: string,
+  indexUrl: string,
+  limit = LLMS_FULL_CHAR_LIMIT
+) => {
+  const trimmed = content.trim();
+  if (trimmed.length <= limit) {
+    return trimmed;
+  }
+
+  const footer = getTruncationFooter(indexUrl);
+  let room = limit - footer.length - 16;
+  while (room > 0) {
+    const draft = trimmed.slice(0, room);
+    const boundary = findTruncationBoundary(draft, Math.floor(room / 2));
+    const capped = closeOpenFence(draft.slice(0, boundary).trimEnd());
+    const result = `${capped}${footer}`;
+
+    if (result.length <= limit) {
+      return result;
+    }
+
+    room -= result.length - limit + 16;
+  }
+
+  return footer.trim().slice(0, limit);
+};

package/docs/lib/marketing-markdown.ts

@@ -0,0 +1,79 @@
+const MARKETING_MARKDOWN: Record<string, string> = {
+  "/": `# Blode.md
+
+Docs your users love. And their AI understands.
+
+Write MDX, commit, push. blode.md ships a fast, beautiful docs site in one git push, wired up for the LLMs your users ask too.
+
+## How it works
+
+1. Install the GitHub app at github.com/apps/blodemd
+2. Pick a repo and a docs folder
+3. Push to \`main\`, deployed to \`acme.blode.md\`
+
+Or use the CLI:
+
+\`\`\`
+npm i -g blodemd
+blodemd login
+blodemd new docs
+blodemd push docs
+\`\`\`
+
+## What you get
+
+- **GitHub auto-deploy** — Install once. Every push to your branch deploys in seconds.
+- **Custom domains** — Point a domain, get SSL. Or proxy docs at yourdomain.com/docs.
+- **MDX components** — 30+ components out of the box: callouts, tabs, code groups, API refs.
+- **Search** — Full-text search across every page. No plugin, no config.
+- **Content types** — Docs, blogs, changelogs, and courses in one project, one domain.
+- **API reference** — Point at an OpenAPI spec, ship an interactive API reference.
+
+## Links
+
+- [About](https://blode.md/about)
+- [Blog](https://blode.md/blog)
+- [Changelog](https://blode.md/changelog)
+- [Privacy](https://blode.md/privacy)
+- [Terms](https://blode.md/terms)
+- [Security](https://blode.md/security)
+- [Docs](https://blode.md/docs)
+- [GitHub](https://github.com/mblode/blodemd)
+`,
+  "/about": `# About Blode.md
+
+blode.md is a docs platform that lives in your git repo. Write MDX, push to main, ship docs.
+`,
+  "/blog": `# Blog
+
+Notes from the team building blode.md.
+`,
+  "/changelog": `# Changelog
+
+Latest updates to the blode.md platform.
+`,
+  "/pricing": `# Pricing
+
+Blode.md is currently free for hosted projects and MIT licensed for self-hosting.
+`,
+  "/privacy": `# Privacy Policy
+
+How blode.md collects, uses, and protects your information.
+`,
+  "/security": `# Security
+
+Security practices at blode.md.
+`,
+  "/terms": `# Terms of Service
+
+Terms governing your use of blode.md.
+`,
+};
+
+export const getMarketingMarkdown = (pathname: string): string | null => {
+  const normalized = pathname.replace(/\/+$/, "") || "/";
+  return MARKETING_MARKDOWN[normalized] ?? null;
+};
+
+export const hasMarketingMarkdown = (pathname: string): boolean =>
+  getMarketingMarkdown(pathname) !== null;

package/docs/lib/marketing-site.ts

@@ -0,0 +1,31 @@
+import { platformRootDomain } from "./env";
+
+export const MARKETING_ORIGIN = `https://${platformRootDomain}`;
+
+export const MARKETING_CANONICAL_PATHS = [
+  "/",
+  "/about",
+  "/blog",
+  "/changelog",
+  "/pricing",
+  "/privacy",
+  "/security",
+  "/terms",
+] as const;
+
+export const MARKETING_API_CATALOG_PATH = "/.well-known/api-catalog";
+export const MARKETING_SKILLS_INDEX_PATH =
+  "/.well-known/agent-skills/index.json";
+export const MARKETING_MCP_SERVER_CARD_PATH =
+  "/.well-known/mcp/server-card.json";
+export const MARKETING_OAUTH_AUTHORIZATION_SERVER_PATH =
+  "/.well-known/oauth-authorization-server";
+export const MARKETING_OAUTH_PROTECTED_RESOURCE_PATH =
+  "/.well-known/oauth-protected-resource";
+export const MARKETING_OPENID_CONFIGURATION_PATH =
+  "/.well-known/openid-configuration";
+export const MARKETING_API_DOCS_PATH = "/docs/api/overview";
+export const MARKETING_API_STATUS_PATH = "/api/health";
+export const MARKETING_API_SERVICE_DESC_PATH = "/api/openapi.json";
+
+export const marketingUrl = (path: string) => `${MARKETING_ORIGIN}${path}`;

package/docs/lib/mdx.ts

@@ -8,7 +8,7 @@ import rehypeAutolinkHeadings from "rehype-autolink-headings";
 import rehypeSlug from "rehype-slug";
 import remarkGfm from "remark-gfm";
 
-import { mdxComponents } from "@/components/mdx";
+import { createMdxComponents } from "@/components/mdx";
 
 import { getHighlighter, SHIKI_THEME_PAIR } from "./shiki";
 
@@ -25,17 +25,22 @@ const stripFrontmatter = (source: string) => ({
  * `outputFormat: 'function-body'`. This is the fast path — no parsing,
  * no plugin execution, no Shiki. Sub-millisecond execution.
  */
-export const renderFromCompiled = async (compiledSource: string) => {
+export const renderFromCompiled = async (
+  compiledSource: string,
+  basePath = "",
+  currentPath = ""
+) => {
+  const components = createMdxComponents(basePath, currentPath);
   const mdxModule = await run(compiledSource, {
     ...jsxRuntime,
     baseUrl: import.meta.url,
   });
   const Content = mdxModule.default as ComponentType<{
-    components?: typeof mdxComponents;
+    components?: ReturnType<typeof createMdxComponents>;
   }>;
 
   return {
-    content: createElement(Content, { components: mdxComponents }),
+    content: createElement(Content, { components }),
     frontmatter: {} as Record<string, unknown>,
   };
 };
@@ -44,17 +49,23 @@ export const renderFromCompiled = async (compiledSource: string) => {
  * Full MDX compilation + rendering. Used as fallback for local development
  * (FsContentSource) and any content that wasn't pre-compiled at deploy time.
  */
-export const renderMdx = async (source: string) => {
+export const renderMdx = async (
+  source: string,
+  basePath = "",
+  currentPath = ""
+) => {
   const { body, frontmatter } = stripFrontmatter(source);
+  const components = createMdxComponents(basePath, currentPath);
   const highlighter = await getHighlighter();
   const shikiTransformer = rehypeShikiFromHighlighter(highlighter, {
     defaultColor: false,
+    fallbackLanguage: "text",
     themes: SHIKI_THEME_PAIR,
   });
   const shikiPlugin = () => shikiTransformer;
 
   const result = await compileMDX({
-    components: mdxComponents,
+    components,
     options: {
       blockDangerousJS: false,
       blockJS: false,

package/docs/lib/routes.ts

@@ -57,7 +57,19 @@ export const getMarkdownExportSlug = (pathname: string, basePath = "") => {
 export const isExternalHref = (href: string) =>
   ABSOLUTE_URL_REGEX.test(href) || href.startsWith("//");
 
-export const resolveHref = (href: string, basePath = "") => {
+const isDotRelativeHref = (href: string) =>
+  href.startsWith("./") || href.startsWith("../");
+
+const resolveDotRelativePath = (pathPart: string, currentPath: string) => {
+  const cleanCurrentPath = normalizePath(currentPath);
+  const currentDirectory = cleanCurrentPath.includes("/")
+    ? cleanCurrentPath.slice(0, cleanCurrentPath.lastIndexOf("/") + 1)
+    : "";
+  const resolved = new URL(pathPart, `https://docs.local/${currentDirectory}`);
+  return normalizePath(resolved.pathname) || "index";
+};
+
+export const resolveHref = (href: string, basePath = "", currentPath = "") => {
   if (
     !href ||
     href.startsWith("#") ||
@@ -70,10 +82,14 @@ export const resolveHref = (href: string, basePath = "") => {
   const suffixIndex = href.search(/[?#]/);
   const pathPart = suffixIndex === -1 ? href : href.slice(0, suffixIndex);
   const suffix = suffixIndex === -1 ? "" : href.slice(suffixIndex);
+  const resolvedPath =
+    currentPath && isDotRelativeHref(pathPart)
+      ? resolveDotRelativePath(pathPart, currentPath)
+      : pathPart;
   const normalizedBase = basePath
     ? withLeadingSlash(basePath).replaceAll(/\/+$/g, "")
     : "";
-  const normalizedPath = withLeadingSlash(pathPart || "/");
+  const normalizedPath = withLeadingSlash(resolvedPath || "/");
 
   if (
     normalizedBase &&
@@ -83,5 +99,5 @@ export const resolveHref = (href: string, basePath = "") => {
     return `${normalizedPath}${suffix}`;
   }
 
-  return `${toDocHref(pathPart || "index", basePath)}${suffix}`;
+  return `${toDocHref(resolvedPath || "index", basePath)}${suffix}`;
 };

package/docs/lib/shiki.ts

@@ -12,9 +12,13 @@ const COMMON_LANGS = [
   "jsx",
   "markdown",
   "mdx",
+  "nginx",
   "python",
   "rust",
+  "sh",
+  "shell",
   "sql",
+  "text",
   "tsx",
   "typescript",
   "yaml",

package/docs/lib/tenancy.ts

@@ -21,6 +21,7 @@ const DEFAULT_RESERVED_PATHS = [
   "/favicon.ico",
   "/llms.txt",
   "/logos",
+  "/mcp",
   "/oauth",
   "/robots.txt",
   "/sitemap.xml",
@@ -64,11 +65,23 @@ const BACKSLASH_TO_SLASH_REGEX = /\\/g;
 const DEFAULT_DOCS_BASE_PATH = "/docs";
 const TENANT_RESOLUTION_REVALIDATE_SECONDS = 300;
 const ROOT_TENANT_UTILITY_PATHS = new Set([
+  "/.well-known/llms-full.txt",
+  "/.well-known/llms.txt",
   "/llms-full.txt",
   "/llms.txt",
   "/robots.txt",
   "/sitemap.xml",
 ]);
+const WELL_KNOWN_SKILLS_SEGMENT = "/.well-known/skills/";
+const LLMS_SEGMENT_SEGMENT = "/llms/";
+
+export const isTenantUtilityPath = (pathname: string) =>
+  ROOT_TENANT_UTILITY_PATHS.has(pathname) ||
+  pathname.startsWith(WELL_KNOWN_SKILLS_SEGMENT) ||
+  (pathname.startsWith(LLMS_SEGMENT_SEGMENT) && pathname.endsWith(".txt"));
+
+const isPathMatch = (pathname: string, prefix: string) =>
+  pathname === prefix || pathname.startsWith(`${prefix}/`);
 
 const slugifyPath = (value: string) => {
   const trimmed = value
@@ -134,7 +147,7 @@ export const isReservedPath = (pathname: string) => {
   if (isRootStaticAsset(pathname)) {
     return true;
   }
-  return DEFAULT_RESERVED_PATHS.some((prefix) => pathname.startsWith(prefix));
+  return DEFAULT_RESERVED_PATHS.some((prefix) => isPathMatch(pathname, prefix));
 };
 
 const resolveSubdomainBasePath = (pathname: string): string => {
@@ -157,7 +170,7 @@ const buildTenantPathResolution = (
   pathname: string,
   basePath: string
 ) => {
-  if (ROOT_TENANT_UTILITY_PATHS.has(pathname)) {
+  if (isTenantUtilityPath(pathname)) {
     return {
       basePath,
       host,

package/docs/lib/tenant-headers.ts

@@ -1,4 +1,7 @@
+import type { ProjectAnalytics } from "@repo/contracts";
+
 export const TENANT_HEADERS = {
+  ANALYTICS: "x-tenant-analytics",
   BASE_PATH: "x-tenant-base-path",
   CUSTOM_DOMAINS: "x-tenant-custom-domains",
   DEPLOYMENT_ID: "x-tenant-deployment-id",
@@ -12,3 +15,29 @@ export const TENANT_HEADERS = {
   STRATEGY: "x-tenant-strategy",
   SUBDOMAIN: "x-tenant-subdomain",
 } as const;
+
+const hasAnyProvider = (value: ProjectAnalytics): boolean =>
+  Boolean(value.ga4?.measurementId || value.posthog?.projectKey);
+
+export const encodeTenantAnalyticsHeader = (
+  analytics: ProjectAnalytics | undefined
+): string | null => {
+  if (!analytics || !hasAnyProvider(analytics)) {
+    return null;
+  }
+  return encodeURIComponent(JSON.stringify(analytics));
+};
+
+export const decodeTenantAnalyticsHeader = (
+  encoded: string | null | undefined
+): ProjectAnalytics | null => {
+  if (!encoded) {
+    return null;
+  }
+  try {
+    const parsed = JSON.parse(decodeURIComponent(encoded)) as ProjectAnalytics;
+    return hasAnyProvider(parsed) ? parsed : null;
+  } catch {
+    return null;
+  }
+};