busabase-cms-sdk 0.1.3

package/dist/fumadocs.d.ts

@@ -0,0 +1,24 @@
+import { o as PageVO } from "./types-QKFW2jvT.js";
+import { MarkdownProps } from "fumadocs-core/content/md";
+import { ReactNode } from "react";
+import { TOCItemType } from "fumadocs-core/toc";
+//#region src/fumadocs.d.ts
+interface SafeMarkdownProps {
+  children: string;
+  components?: MarkdownProps["components"];
+}
+/** Render stored Markdown without MDX execution or raw HTML passthrough. */
+declare const SafeMarkdown: ({ children, components }: SafeMarkdownProps) => Promise<ReactNode>;
+declare const getSafeMarkdownToc: (markdown: string) => Promise<TOCItemType[]>;
+/** Sanitize stored Landing Page HTML before passing it to `dangerouslySetInnerHTML`. */
+declare const sanitizeLandingPageHtml: (html: string) => string;
+/**
+ * Sanitize a CMS Page's stored body for injection. Lives here, next to the sanitizer it wraps,
+ * rather than in `busabase-cms-sdk/integration`: `sanitizeLandingPageHtml` drags in remark, rehype
+ * and sanitize-html, and only the component that actually injects the HTML should pay for that.
+ *
+ * Call this immediately before injecting — the sanitize step must never move up to the caller.
+ */
+declare const getSanitizedCmsPageBody: (page: Pick<PageVO, "body">) => string;
+//#endregion
+export { SafeMarkdown, SafeMarkdownProps, getSafeMarkdownToc, getSanitizedCmsPageBody, sanitizeLandingPageHtml };

package/dist/fumadocs.js

@@ -0,0 +1,188 @@
+import { createMarkdownRenderer } from "fumadocs-core/content/md";
+import { getTableOfContents } from "fumadocs-core/content/toc";
+import { remarkHeading } from "fumadocs-core/mdx-plugins/remark-heading";
+import rehypeSanitize from "rehype-sanitize";
+import remarkGfm from "remark-gfm";
+import sanitizeHtml from "sanitize-html";
+//#region src/fumadocs.ts
+const safeMarkdownRenderer = createMarkdownRenderer({
+	remarkPlugins: [remarkGfm, remarkHeading],
+	rehypePlugins: [rehypeSanitize]
+});
+/** Render stored Markdown without MDX execution or raw HTML passthrough. */
+const SafeMarkdown = async ({ children, components }) => safeMarkdownRenderer.MarkdownServer({
+	children,
+	components
+});
+const getSafeMarkdownToc = async (markdown) => getTableOfContents(markdown, [remarkGfm]);
+const safeCssValue = /^(?!.*(?:url|expression|@import|javascript))[-a-zA-Z0-9#(),.%\s/]+$/i;
+const safeLength = /^(?!.*(?:url|expression|@import|javascript))(?:0|auto|none|(?:min|max|clamp|calc)\([^;{}]+\)|[0-9.]+(?:px|rem|em|%|vh|vw|ch))$/i;
+/** Sanitize stored Landing Page HTML before passing it to `dangerouslySetInnerHTML`. */
+const sanitizeLandingPageHtml = (html) => sanitizeHtml(html, {
+	allowedTags: [
+		"article",
+		"section",
+		"div",
+		"span",
+		"p",
+		"h1",
+		"h2",
+		"h3",
+		"h4",
+		"h5",
+		"h6",
+		"a",
+		"strong",
+		"em",
+		"b",
+		"i",
+		"s",
+		"blockquote",
+		"code",
+		"pre",
+		"ul",
+		"ol",
+		"li",
+		"dl",
+		"dt",
+		"dd",
+		"table",
+		"thead",
+		"tbody",
+		"tfoot",
+		"tr",
+		"th",
+		"td",
+		"figure",
+		"figcaption",
+		"picture",
+		"source",
+		"img",
+		"details",
+		"summary",
+		"hr",
+		"br"
+	],
+	allowedAttributes: {
+		"*": [
+			"id",
+			"style",
+			"role",
+			"aria-label",
+			"aria-labelledby",
+			"aria-describedby"
+		],
+		a: [
+			"href",
+			"name",
+			"target",
+			"rel",
+			"title"
+		],
+		img: [
+			"src",
+			"alt",
+			"title",
+			"width",
+			"height",
+			"loading",
+			"decoding"
+		],
+		source: [
+			"src",
+			"srcset",
+			"media",
+			"type",
+			"width",
+			"height"
+		],
+		td: ["colspan", "rowspan"],
+		th: [
+			"colspan",
+			"rowspan",
+			"scope"
+		]
+	},
+	allowedSchemes: [
+		"http",
+		"https",
+		"mailto"
+	],
+	allowedSchemesByTag: {
+		img: ["http", "https"],
+		source: ["http", "https"]
+	},
+	allowProtocolRelative: false,
+	enforceHtmlBoundary: true,
+	allowedStyles: { "*": {
+		display: [/^(?:block|inline|inline-block|flex|inline-flex|grid|none)$/],
+		"flex-direction": [/^(?:row|row-reverse|column|column-reverse)$/],
+		"flex-wrap": [/^(?:nowrap|wrap|wrap-reverse)$/],
+		"align-items": [/^(?:normal|stretch|center|start|end|flex-start|flex-end|baseline)$/],
+		"justify-content": [/^(?:normal|stretch|center|start|end|flex-start|flex-end|space-between|space-around|space-evenly)$/],
+		"grid-template-columns": [safeCssValue],
+		"grid-template-rows": [safeCssValue],
+		"grid-column": [safeCssValue],
+		"grid-row": [safeCssValue],
+		gap: [safeLength],
+		"column-gap": [safeLength],
+		"row-gap": [safeLength],
+		width: [safeLength],
+		"min-width": [safeLength],
+		"max-width": [safeLength],
+		height: [safeLength],
+		"min-height": [safeLength],
+		"max-height": [safeLength],
+		margin: [safeCssValue],
+		"margin-top": [safeLength],
+		"margin-right": [safeLength],
+		"margin-bottom": [safeLength],
+		"margin-left": [safeLength],
+		padding: [safeCssValue],
+		"padding-top": [safeLength],
+		"padding-right": [safeLength],
+		"padding-bottom": [safeLength],
+		"padding-left": [safeLength],
+		color: [safeCssValue],
+		background: [safeCssValue],
+		"background-color": [safeCssValue],
+		border: [safeCssValue],
+		"border-bottom": [safeCssValue],
+		"border-left": [safeCssValue],
+		"border-right": [safeCssValue],
+		"border-top": [safeCssValue],
+		"border-color": [safeCssValue],
+		"border-width": [safeLength],
+		"border-style": [/^(?:none|solid|dashed|dotted)$/],
+		"border-radius": [safeLength],
+		"font-size": [safeLength],
+		"font-family": [safeCssValue],
+		"font-weight": [/^(?:normal|bold|[1-9]00)$/],
+		"line-height": [safeCssValue],
+		"text-align": [/^(?:start|end|left|right|center|justify)$/],
+		"text-decoration": [safeCssValue],
+		"text-transform": [/^(?:none|capitalize|uppercase|lowercase)$/],
+		"object-fit": [/^(?:contain|cover|fill|none|scale-down)$/],
+		overflow: [/^(?:visible|hidden|clip|scroll|auto)$/],
+		"overflow-x": [/^(?:visible|hidden|clip|scroll|auto)$/],
+		"overflow-y": [/^(?:visible|hidden|clip|scroll|auto)$/],
+		opacity: [/^(?:0(?:\.\d+)?|1(?:\.0+)?)$/]
+	} },
+	transformTags: { a: (tagName, attribs) => ({
+		tagName,
+		attribs: attribs.target === "_blank" ? {
+			...attribs,
+			rel: "noopener noreferrer"
+		} : attribs
+	}) }
+});
+/**
+* Sanitize a CMS Page's stored body for injection. Lives here, next to the sanitizer it wraps,
+* rather than in `busabase-cms-sdk/integration`: `sanitizeLandingPageHtml` drags in remark, rehype
+* and sanitize-html, and only the component that actually injects the HTML should pay for that.
+*
+* Call this immediately before injecting — the sanitize step must never move up to the caller.
+*/
+const getSanitizedCmsPageBody = (page) => sanitizeLandingPageHtml(page.body);
+//#endregion
+export { SafeMarkdown, getSafeMarkdownToc, getSanitizedCmsPageBody, sanitizeLandingPageHtml };

package/dist/index.d.ts

@@ -0,0 +1,33 @@
+import { C as taxonomyFieldsDTOSchema, S as tagVOSchema, _ as pageVOSchema, a as PageFieldsDTO, b as relationFieldsDTOSchema, c as PostVO, d as TagVO, f as attachmentFieldsDTOSchema, g as pageFieldsDTOSchema, h as categoryVOSchema, i as CategoryVO, l as RelationFieldsDTO, m as categoryFieldsDTOSchema, n as AttachmentVO, o as PageVO, p as attachmentVOSchema, r as CategoryFieldsDTO, s as PostFieldsDTO, t as AttachmentFieldsDTO, u as TagFieldsDTO, v as postFieldsDTOSchema, x as tagFieldsDTOSchema, y as postVOSchema } from "./types-QKFW2jvT.js";
+import { $ as BusabaseCmsSetupError, A as BUSABASE_CMS_SCHEMA_PROFILES, B as i18nName, C as createBusabaseCms, D as mapPublishedPostRecord, E as mapPublishedPageRecord, F as BusabaseCmsFieldDefinition, G as BusabaseCmsFieldOptions, H as BusabaseCmsBase, I as BusabaseCmsFieldsOverride, J as BusabaseCmsSource, K as BusabaseCmsNode, L as BusabaseCmsFolderMetadata, M as BusabaseCmsBaseDefinition, N as BusabaseCmsBaseIds, O as BUSABASE_CMS_METADATA_KEY, P as BusabaseCmsBaseRole, Q as BusabaseCmsSchemaDriftError, R as BusabaseCmsSchemaProfile, S as InvalidCmsRecordIssue, T as mapActiveTagRecord, U as BusabaseCmsClient, V as replaceField, W as BusabaseCmsField, X as createBusabaseCmsSourceFromConfig, Y as createBusabaseCmsSource, Z as BusabaseCmsError, _ as CmsRecordKind, a as buildCmsCanonicalPath, b as DEFAULT_POSTS_BASE_SLUG, c as filterCmsPostsByTaxonomy, d as normalizeCmsPath, f as parseCmsCanonicalPath, g as BusabaseCmsTaxonomyCollection, h as BusabaseCmsPathCollection, i as CmsTaxonomyKind, j as BUSABASE_CMS_SCHEMA_VERSION, k as BUSABASE_CMS_ROLES, l as isCmsBlogPostPath, m as BusabaseCmsOptions, n as CmsCanonicalPathOptions, o as buildCmsTaxonomyArchivePath, p as BusabaseCms, q as BusabaseCmsRecord, r as CmsPathHelpers, s as createCmsPathHelpers, t as CmsCanonicalPath, u as isCmsContentForLocale, v as DEFAULT_CATEGORIES_BASE_SLUG, w as mapActiveCategoryRecord, x as DEFAULT_TAGS_BASE_SLUG, y as DEFAULT_PAGES_BASE_SLUG, z as getBusabaseCmsBaseDefinition } from "./routing-VU56uuJ0.js";
+//#region src/fallback.d.ts
+/**
+ * The "read from Busabase, fall back to bundled content on any failure" wrapper — every app
+ * consuming busabase-cms re-implemented this same try/catch/console.warn a couple of times
+ * (once for list-shaped reads, once for single-record reads). One generic version, one place
+ * to change the log format.
+ */
+declare const readCmsOrFallback: <T>(operation: (() => Promise<T>) | null | undefined, fallback: T, label: string) => Promise<T>;
+//#endregion
+//#region src/links.d.ts
+/** Keep rendered CMS attachments on protocols browsers can navigate safely. */
+declare const getSafeCmsExternalUrl: (value: string) => string | null;
+//#endregion
+//#region src/provision.d.ts
+/**
+ * `profile` is a caller-chosen label persisted in Folder metadata and used only for
+ * mismatch detection (see `assertMetadataProfile`) — the SDK never branches on its value.
+ * A caller using a profile other than `"standard"` must supply `fieldsOverride` to describe
+ * that profile's actual field shape, and may list `legacyOptionalFields` to grandfather in a
+ * field that predates a later required-field tightening.
+ */
+interface BusabaseCmsSchemaConfig {
+  profile: BusabaseCmsSchemaProfile;
+  fieldsOverride?: BusabaseCmsFieldsOverride;
+  legacyOptionalFields?: Array<{
+    role: BusabaseCmsBaseRole;
+    slug: string;
+  }>;
+}
+//#endregion
+export { AttachmentFieldsDTO, AttachmentVO, BUSABASE_CMS_METADATA_KEY, BUSABASE_CMS_ROLES, BUSABASE_CMS_SCHEMA_PROFILES, BUSABASE_CMS_SCHEMA_VERSION, type BusabaseCms, type BusabaseCmsBase, type BusabaseCmsBaseDefinition, type BusabaseCmsBaseIds, type BusabaseCmsBaseRole, type BusabaseCmsClient, BusabaseCmsError, type BusabaseCmsField, type BusabaseCmsFieldDefinition, type BusabaseCmsFieldOptions, type BusabaseCmsFieldsOverride, type BusabaseCmsFolderMetadata, type BusabaseCmsNode, type BusabaseCmsOptions, type BusabaseCmsPathCollection, type BusabaseCmsRecord, type BusabaseCmsSchemaConfig, BusabaseCmsSchemaDriftError, type BusabaseCmsSchemaProfile, BusabaseCmsSetupError, type BusabaseCmsSource, type BusabaseCmsTaxonomyCollection, CategoryFieldsDTO, CategoryVO, CmsCanonicalPath, CmsCanonicalPathOptions, CmsPathHelpers, type CmsRecordKind, CmsTaxonomyKind, DEFAULT_CATEGORIES_BASE_SLUG, DEFAULT_PAGES_BASE_SLUG, DEFAULT_POSTS_BASE_SLUG, DEFAULT_TAGS_BASE_SLUG, type InvalidCmsRecordIssue, PageFieldsDTO, PageVO, PostFieldsDTO, PostVO, RelationFieldsDTO, TagFieldsDTO, TagVO, attachmentFieldsDTOSchema, attachmentVOSchema, buildCmsCanonicalPath, buildCmsTaxonomyArchivePath, i18nName as busabaseCmsFieldI18nName, categoryFieldsDTOSchema, categoryVOSchema, createBusabaseCms, createBusabaseCmsSource, createBusabaseCmsSourceFromConfig, createCmsPathHelpers, filterCmsPostsByTaxonomy, getBusabaseCmsBaseDefinition, getSafeCmsExternalUrl, isCmsBlogPostPath, isCmsContentForLocale, mapActiveCategoryRecord, mapActiveTagRecord, mapPublishedPageRecord, mapPublishedPostRecord, normalizeCmsPath, pageFieldsDTOSchema, pageVOSchema, parseCmsCanonicalPath, postFieldsDTOSchema, postVOSchema, readCmsOrFallback, relationFieldsDTOSchema, replaceField, tagFieldsDTOSchema, tagVOSchema, taxonomyFieldsDTOSchema };

package/dist/index.js

@@ -0,0 +1,14 @@
+import { A as replaceField, C as createBusabaseCmsSourceFromConfig, D as BUSABASE_CMS_SCHEMA_VERSION, E as BUSABASE_CMS_SCHEMA_PROFILES, M as BusabaseCmsSchemaDriftError, N as BusabaseCmsSetupError, O as getBusabaseCmsBaseDefinition, S as createBusabaseCmsSource, T as BUSABASE_CMS_ROLES, _ as postVOSchema, a as createBusabaseCms, b as tagVOSchema, c as mapPublishedPageRecord, d as attachmentVOSchema, f as categoryFieldsDTOSchema, g as postFieldsDTOSchema, h as pageVOSchema, i as DEFAULT_TAGS_BASE_SLUG, j as BusabaseCmsError, k as i18nName, l as mapPublishedPostRecord, m as pageFieldsDTOSchema, n as DEFAULT_PAGES_BASE_SLUG, o as mapActiveCategoryRecord, p as categoryVOSchema, r as DEFAULT_POSTS_BASE_SLUG, s as mapActiveTagRecord, t as DEFAULT_CATEGORIES_BASE_SLUG, u as attachmentFieldsDTOSchema, v as relationFieldsDTOSchema, w as BUSABASE_CMS_METADATA_KEY, x as taxonomyFieldsDTOSchema, y as tagFieldsDTOSchema } from "./content-BXgsWQjQ.js";
+import { a as isCmsBlogPostPath, c as parseCmsCanonicalPath, i as filterCmsPostsByTaxonomy, l as readCmsOrFallback, n as buildCmsTaxonomyArchivePath, o as isCmsContentForLocale, r as createCmsPathHelpers, s as normalizeCmsPath, t as buildCmsCanonicalPath } from "./routing-C3lkVAZ8.js";
+//#region src/links.ts
+/** Keep rendered CMS attachments on protocols browsers can navigate safely. */
+const getSafeCmsExternalUrl = (value) => {
+	try {
+		const url = new URL(value);
+		return url.protocol === "http:" || url.protocol === "https:" ? url.toString() : null;
+	} catch {
+		return null;
+	}
+};
+//#endregion
+export { BUSABASE_CMS_METADATA_KEY, BUSABASE_CMS_ROLES, BUSABASE_CMS_SCHEMA_PROFILES, BUSABASE_CMS_SCHEMA_VERSION, BusabaseCmsError, BusabaseCmsSchemaDriftError, BusabaseCmsSetupError, DEFAULT_CATEGORIES_BASE_SLUG, DEFAULT_PAGES_BASE_SLUG, DEFAULT_POSTS_BASE_SLUG, DEFAULT_TAGS_BASE_SLUG, attachmentFieldsDTOSchema, attachmentVOSchema, buildCmsCanonicalPath, buildCmsTaxonomyArchivePath, i18nName as busabaseCmsFieldI18nName, categoryFieldsDTOSchema, categoryVOSchema, createBusabaseCms, createBusabaseCmsSource, createBusabaseCmsSourceFromConfig, createCmsPathHelpers, filterCmsPostsByTaxonomy, getBusabaseCmsBaseDefinition, getSafeCmsExternalUrl, isCmsBlogPostPath, isCmsContentForLocale, mapActiveCategoryRecord, mapActiveTagRecord, mapPublishedPageRecord, mapPublishedPostRecord, normalizeCmsPath, pageFieldsDTOSchema, pageVOSchema, parseCmsCanonicalPath, postFieldsDTOSchema, postVOSchema, readCmsOrFallback, relationFieldsDTOSchema, replaceField, tagFieldsDTOSchema, tagVOSchema, taxonomyFieldsDTOSchema };

package/dist/integration/index.d.ts

@@ -0,0 +1,251 @@
+import { c as PostVO, d as TagVO, i as CategoryVO, o as PageVO } from "../types-QKFW2jvT.js";
+import { S as InvalidCmsRecordIssue, i as CmsTaxonomyKind, p as BusabaseCms, r as CmsPathHelpers, t as CmsCanonicalPath } from "../routing-VU56uuJ0.js";
+import "server-only";
+//#region src/integration/config.d.ts
+/** Next data-cache `revalidate` used when an app does not override it. */
+declare const DEFAULT_CMS_REVALIDATE_SECONDS = 300;
+/**
+ * The four Base slugs used ONLY when `BUSABASE_CMS_FOLDER_ID` is unset. Without a Folder id,
+ * `createBusabaseCms` otherwise falls back to the SDK's own generic, SHARED default Base slugs
+ * (busabase-cms-posts / -pages / -categories / -tags), which would silently mix content with
+ * any other app pointed at the same Busabase space without a Folder id configured — so an app
+ * that wants its own Bases MUST pass its own app-prefixed slugs here.
+ *
+ * Each slug can still be overridden at deploy time by `BUSABASE_CMS_{POSTS,PAGES,CATEGORIES,
+ * TAGS}_BASE_SLUG`; what is configured here is only the default.
+ */
+interface CmsIntegrationBaseSlugs {
+  posts: string;
+  pages: string;
+  categories: string;
+  tags: string;
+}
+interface CmsIntegrationCacheTags {
+  posts?: string[];
+  pages?: string[];
+  categories?: string[];
+  tags?: string[];
+}
+interface CmsIntegrationCacheConfig {
+  /** Seconds; `false` disables time-based revalidation. Defaults to 300. */
+  revalidate?: number | false;
+  /**
+   * `revalidateTag` targets per collection. Defaults to
+   * `["<cacheNamespace>:cms-<collection>"]`.
+   */
+  tags?: CmsIntegrationCacheTags;
+}
+interface CmsIntegrationConfig {
+  /** Human-readable app name, used only in degrade-safe warning log labels (e.g. "ProductReady"). */
+  appLabel: string;
+  /**
+   * Stable, unique-per-app slug (e.g. "productready", "sandock-cloud", "busabase-cloud").
+   *
+   * This is the first discriminator in the Next data-cache key prefix and the default
+   * `revalidateTag` namespace. It exists so that two apps deployed against the SAME Busabase
+   * host + space can never read each other's cached CMS entries, no matter how their Folder id
+   * or Base slugs are (mis)configured.
+   */
+  cacheNamespace: string;
+  supportedLocales: readonly string[];
+  defaultLocale: string;
+  /**
+   * Caller-owned profile label (see src/schema.ts) — MUST be unique per app so a shared
+   * Busabase Folder never mismatches the apps' provisioned field shapes.
+   */
+  schemaProfile: string;
+  /** Default Base slugs, used without a Folder id and overridable per deploy (see above). */
+  baseSlugs: CmsIntegrationBaseSlugs;
+  cache?: CmsIntegrationCacheConfig;
+  /** Passed straight through to `createBusabaseCms`. Leave unset for the SDK default. */
+  invalidRecords?: "skip" | "throw";
+  onInvalidRecord?: (issue: InvalidCmsRecordIssue) => void;
+}
+/** The fully-resolved, env-derived CMS target. `null` when the integration is off. */
+interface ResolvedCmsConfig {
+  baseUrl: string;
+  apiKey: string;
+  spaceId: string;
+  folderId: string | null;
+  baseSlugs: CmsIntegrationBaseSlugs;
+}
+/**
+ * Pure `BUSABASE_CMS_*` env-var gate. All three of host/key/space are required: you genuinely
+ * cannot talk to a Busabase space without an API key, so a partial configuration is treated as
+ * "off" rather than as a guaranteed-failing read on every request.
+ *
+ * Re-reads the environment on every call — deliberately never memoized, unlike the client.
+ */
+declare const readCmsEnvConfig: (defaultBaseSlugs: CmsIntegrationBaseSlugs, env?: Record<string, string | undefined>) => ResolvedCmsConfig | null;
+//#endregion
+//#region src/integration/client.d.ts
+/**
+ * Explicit Next data-cache key prefix. Two reasons it is never left to the SDK's default:
+ *
+ * 1. App identity — the SDK's own default prefix (see `resolveBusabaseCmsCacheKeyPrefix`) is
+ *    derived purely from the CMS target (host / space / folder / profile / Base slugs) and
+ *    carries no app identity at all. `cacheNamespace` (unique per app) is the first element
+ *    here, so no two apps can ever share an entry even when they read the very same Bases.
+ * 2. Re-pointing safety — folder id, schema profile and all four Base slugs are part of the
+ *    key, so changing any of them at deploy time starts from a cold cache instead of serving
+ *    content read out of a different Base.
+ *
+ * The API key is deliberately NOT part of the key (it is a secret, and it does not change
+ * which records are addressed).
+ */
+declare const buildCmsCacheKeyPrefix: (config: Pick<CmsIntegrationConfig, "cacheNamespace" | "schemaProfile">, resolved: ResolvedCmsConfig) => string[];
+/** `revalidateTag` targets per collection, defaulting to `<cacheNamespace>:cms-<collection>`. */
+declare const resolveCmsCacheTags: (config: Pick<CmsIntegrationConfig, "cacheNamespace" | "cache">) => Required<CmsIntegrationCacheTags>;
+interface CmsClientProvider {
+  /** `null` when the integration is unconfigured — callers degrade to bundled content. */
+  getCms: () => BusabaseCms | null;
+  /** Throws when the integration is unconfigured. Prefer `getCms` + `readCmsOrFallback`. */
+  requireCms: () => BusabaseCms;
+  getCmsConfig: () => ResolvedCmsConfig | null;
+  isBusabaseCmsEnabled: () => boolean;
+}
+declare const createCmsClientProvider: (config: CmsIntegrationConfig) => CmsClientProvider;
+//#endregion
+//#region src/integration/pages.d.ts
+interface CmsPageReads {
+  /** Raw reads — throw when the integration is unconfigured. Prefer the `*OrFallback` variants. */
+  listBusabaseLandingPages: () => Promise<PageVO[]>;
+  getBusabaseLandingPageByPath: (path: string) => Promise<PageVO | null>;
+  listBusabaseLandingPagesOrFallback: () => Promise<PageVO[]>;
+  getBusabaseLandingPageByPathOrFallback: (path: string) => Promise<PageVO | null>;
+}
+declare const createCmsPageReads: ({ getCms, requireCms }: CmsClientProvider, appLabel: string) => CmsPageReads;
+/** The argument object an app's own `generatePageMetadata` helper accepts. */
+interface CmsPageMetadataOptions {
+  title: string;
+  description: string;
+  path: string;
+  lang: string;
+  type: "website" | "article";
+}
+/** The slice of a `CmsIntegration` the Page helpers depend on. */
+interface CmsPageHelpersIntegration {
+  buildCmsPath: (locale: string, path: string | readonly string[]) => string | null;
+  parseCmsPath: (path: string) => CmsCanonicalPath | null;
+  isCmsContentForLocale: (item: {
+    locale: string;
+    path: string;
+  }, locale: string) => boolean;
+  getBusabaseLandingPageByPathOrFallback: (path: string) => Promise<PageVO | null>;
+}
+interface CmsPageHelpersOptions<TMetadata> {
+  integration: CmsPageHelpersIntegration;
+  /**
+   * The app's own metadata helper. Injected and typed structurally so the SDK does not depend
+   * on any app's site config.
+   */
+  generatePageMetadata: (options: CmsPageMetadataOptions) => TMetadata;
+}
+interface CmsPageHelpers<TMetadata> {
+  getCmsPageForRequest: (lang: string, path: string | readonly string[]) => Promise<PageVO | null>;
+  generateCmsPageMetadata: (page: PageVO, lang: string) => TMetadata | Record<string, never>;
+}
+declare const createCmsPageHelpers: <TMetadata>({ integration, generatePageMetadata }: CmsPageHelpersOptions<TMetadata>) => CmsPageHelpers<TMetadata>;
+//#endregion
+//#region src/integration/posts.d.ts
+interface CmsPostReads {
+  /** Raw reads — throw when the integration is unconfigured. Prefer the `*OrFallback` variants. */
+  listBusabaseBlogPosts: () => Promise<PostVO[]>;
+  getBusabaseBlogPostByPath: (path: string) => Promise<PostVO | null>;
+  listBusabaseBlogPostsOrFallback: () => Promise<PostVO[]>;
+  getBusabaseBlogPostByPathOrFallback: (path: string) => Promise<PostVO | null>;
+}
+declare const createCmsPostReads: ({ getCms, requireCms }: CmsClientProvider, appLabel: string) => CmsPostReads;
+interface BlogCardContent {
+  url: string;
+  title: string;
+  description?: string;
+  date?: string | Date;
+  author?: string;
+  image?: string;
+}
+/**
+ * Merge Post card sources in priority order, using canonical paths as identity — the earliest
+ * source to claim a path wins. Lets an app render CMS Posts and bundled MDX posts in one grid
+ * without a CMS post and its local original showing up twice.
+ */
+declare const mergeBlogCardsByPath: (...sources: readonly BlogCardContent[][]) => BlogCardContent[];
+/**
+ * Structural shape of the fumadocs `loader()` result the resolver needs. Typed structurally
+ * (rather than importing an app's `~/lib/source`) so the SDK stays free of app internals;
+ * `TPage` flows the app's own local-MDX page type through untouched.
+ */
+interface LocalPostSourceLike<TPage> {
+  getPage: (slugs: string[], locale: string) => TPage | undefined;
+}
+interface ResolvedCmsPostPageBase {
+  requestedLocale: string;
+  contentLocale: string;
+  isLocaleFallback: boolean;
+  canonicalPath: string;
+}
+type ResolvedCmsPostPage<TPage> = (ResolvedCmsPostPageBase & {
+  source: "busabase";
+  content: PostVO;
+}) | (ResolvedCmsPostPageBase & {
+  source: "local";
+  content: TPage;
+});
+interface CmsPostResolverDependencies<TPage> {
+  getCmsPost: (locale: string, slugs: string[]) => Promise<PostVO | null>;
+  getLocalPost: (locale: string, slugs: string[]) => TPage | undefined;
+}
+/** The slice of a `CmsIntegration` the Post resolver depends on. */
+interface CmsPostResolverIntegration {
+  buildCmsPath: (locale: string, path: string | readonly string[]) => string | null;
+  parseCmsPath: (path: string) => CmsCanonicalPath | null;
+  isCmsContentForLocale: (item: {
+    locale: string;
+    path: string;
+  }, locale: string) => boolean;
+  getBusabaseBlogPostByPathOrFallback: (path: string) => Promise<PostVO | null>;
+}
+interface CmsPostResolverOptions<TPage> {
+  integration: CmsPostResolverIntegration;
+  localSource: LocalPostSourceLike<TPage>;
+}
+interface CmsPostResolver<TPage> {
+  resolvePostPage: (requestedLocale: string, slugPath: string) => Promise<ResolvedCmsPostPage<TPage> | null>;
+  resolvePostPageWithDependencies: (requestedLocale: string, slugPath: string, dependencies: CmsPostResolverDependencies<TPage>) => Promise<ResolvedCmsPostPage<TPage> | null>;
+}
+declare const createCmsPostResolver: <TPage>({ integration, localSource }: CmsPostResolverOptions<TPage>) => CmsPostResolver<TPage>;
+//#endregion
+//#region src/integration/taxonomy.d.ts
+interface CmsTaxonomyReads {
+  /** Raw reads — throw when the integration is unconfigured. Prefer the `*OrFallback` variants. */
+  listBusabaseCategories: () => Promise<CategoryVO[]>;
+  listBusabaseCategoriesOrFallback: () => Promise<CategoryVO[]>;
+  listBusabaseTags: () => Promise<TagVO[]>;
+  listBusabaseTagsOrFallback: () => Promise<TagVO[]>;
+}
+declare const createCmsTaxonomyReads: ({ getCms, requireCms }: CmsClientProvider, appLabel: string) => CmsTaxonomyReads;
+//#endregion
+//#region src/integration/index.d.ts
+/**
+ * The whole per-app Busabase CMS surface, bound once to one app's locale / schema / Base
+ * config: canonical-path helpers, the env gate, and the Post / Page / taxonomy reads.
+ */
+interface CmsIntegration extends CmsPostReads, CmsPageReads, CmsTaxonomyReads {
+  cmsPathHelpers: CmsPathHelpers;
+  buildCmsPath: (locale: string, path: string | readonly string[]) => string | null;
+  parseCmsPath: (path: string) => CmsCanonicalPath | null;
+  isCmsContentForLocale: (item: {
+    locale: string;
+    path: string;
+  }, locale: string) => boolean;
+  buildCmsTaxonomyArchivePath: (kind: CmsTaxonomyKind, taxonomy: {
+    locale: string;
+    slug: string;
+  }) => string | null;
+  isBusabaseCmsEnabled: () => boolean;
+  /** Re-reads the environment on every call — never memoized, unlike the client itself. */
+  getCmsConfig: () => ResolvedCmsConfig | null;
+}
+declare const createCmsIntegration: (config: CmsIntegrationConfig) => CmsIntegration;
+//#endregion
+export { type BlogCardContent, type CmsClientProvider, CmsIntegration, type CmsIntegrationBaseSlugs, type CmsIntegrationCacheConfig, type CmsIntegrationCacheTags, type CmsIntegrationConfig, type CmsPageHelpers, type CmsPageHelpersIntegration, type CmsPageHelpersOptions, type CmsPageMetadataOptions, type CmsPageReads, type CmsPostReads, type CmsPostResolver, type CmsPostResolverDependencies, type CmsPostResolverIntegration, type CmsPostResolverOptions, type CmsTaxonomyReads, DEFAULT_CMS_REVALIDATE_SECONDS, type LocalPostSourceLike, type ResolvedCmsConfig, type ResolvedCmsPostPage, buildCmsCacheKeyPrefix, createCmsClientProvider, createCmsIntegration, createCmsPageHelpers, createCmsPageReads, createCmsPostReads, createCmsPostResolver, createCmsTaxonomyReads, mergeBlogCardsByPath, readCmsEnvConfig, resolveCmsCacheTags };