busabase-cms-sdk 0.1.3 → 0.1.5

package/dist/fallback-5I_dTsOb.d.ts

@@ -0,0 +1,45 @@
+//#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>;
+/**
+ * The answer a read got, when the caller needs to act on it.
+ *
+ * `readCmsOrFallback` deliberately folds "unreachable" into "empty", which is the
+ * right default for rendering — a marketing page should not 500 because the
+ * workspace behind it blinked. It is the wrong answer the moment a page turns it
+ * into a claim: an unreachable CMS then renders as a 404, and whatever caching
+ * sits in front of it persists that as "this content was deleted".
+ *
+ * Reads whose result decides a `notFound()` should go through `readCmsStatus`
+ * instead and be told which answer they actually received.
+ */
+type CmsRead<T> = {
+  status: "ok";
+  data: T;
+} | {
+  status: "unavailable";
+};
+declare const readCmsStatus: <T>(operation: (() => Promise<T>) | null | undefined,
+/**
+ * What "nothing here" looks like for this read.
+ *
+ * Returned as a SUCCESSFUL read when the integration is simply not configured:
+ * an app with no CMS wired up is not broken, it just has no CMS content, and
+ * turning that into an error breaks first-run and CMS-off deployments.
+ */
+whenUnconfigured: T, label: string) => Promise<CmsRead<T>>;
+/**
+ * Unwrap a read, or fail loudly.
+ *
+ * Throwing beats rendering a 404: an error response is not cached, so the page
+ * recovers on the next request, whereas a cached 404 tells crawlers the content
+ * is gone.
+ */
+declare const requireCmsRead: <T>(read: CmsRead<T>, what: string) => T;
+//#endregion
+export { requireCmsRead as i, readCmsOrFallback as n, readCmsStatus as r, CmsRead as t };

package/dist/index.d.ts

@@ -1,14 +1,6 @@
 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
+import { i as requireCmsRead, n as readCmsOrFallback, r as readCmsStatus, t as CmsRead } from "./fallback-5I_dTsOb.js";
 //#region src/links.d.ts
 /** Keep rendered CMS attachments on protocols browsers can navigate safely. */
 declare const getSafeCmsExternalUrl: (value: string) => string | null;
@@ -30,4 +22,4 @@ interface BusabaseCmsSchemaConfig {
   }>;
 }
 //#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 };
+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, CmsRead, 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, readCmsStatus, relationFieldsDTOSchema, replaceField, requireCmsRead, tagFieldsDTOSchema, tagVOSchema, taxonomyFieldsDTOSchema };

package/dist/index.js

@@ -1,5 +1,5 @@
 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";
+import { a as isCmsBlogPostPath, c as parseCmsCanonicalPath, d as requireCmsRead, i as filterCmsPostsByTaxonomy, l as readCmsOrFallback, n as buildCmsTaxonomyArchivePath, o as isCmsContentForLocale, r as createCmsPathHelpers, s as normalizeCmsPath, t as buildCmsCanonicalPath, u as readCmsStatus } from "./routing-Cf35nomf.js";
 //#region src/links.ts
 /** Keep rendered CMS attachments on protocols browsers can navigate safely. */
 const getSafeCmsExternalUrl = (value) => {
@@ -11,4 +11,4 @@ const getSafeCmsExternalUrl = (value) => {
 	}
 };
 //#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 };
+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, readCmsStatus, relationFieldsDTOSchema, replaceField, requireCmsRead, tagFieldsDTOSchema, tagVOSchema, taxonomyFieldsDTOSchema };

package/dist/integration/index.d.ts

@@ -1,5 +1,6 @@
 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 { t as CmsRead } from "../fallback-5I_dTsOb.js";
 import "server-only";
 //#region src/integration/config.d.ts
 /** Next data-cache `revalidate` used when an app does not override it. */
@@ -113,6 +114,8 @@ interface CmsPageReads {
   getBusabaseLandingPageByPath: (path: string) => Promise<PageVO | null>;
   listBusabaseLandingPagesOrFallback: () => Promise<PageVO[]>;
   getBusabaseLandingPageByPathOrFallback: (path: string) => Promise<PageVO | null>;
+  /** Status-aware variant, for callers that turn a missing page into a 404. */
+  readBusabaseLandingPageByPath: (path: string) => Promise<CmsRead<PageVO | null>>;
 }
 declare const createCmsPageReads: ({ getCms, requireCms }: CmsClientProvider, appLabel: string) => CmsPageReads;
 /** The argument object an app's own `generatePageMetadata` helper accepts. */
@@ -123,29 +126,73 @@ interface CmsPageMetadataOptions {
   lang: string;
   type: "website" | "article";
 }
+/**
+ * All the locale resolver actually reads off a Page: its canonical path and its locale. Kept
+ * deliberately narrower than `PageVO` so an app whose own Page VO omits SDK fields it does not
+ * store (Buda drops `hero`/`features`/`faqs`) still flows through these helpers with its own
+ * type intact, instead of being silently widened back to `PageVO`.
+ */
+type CmsPageIdentity = Pick<PageVO, "path" | "locale">;
+/**
+ * A Page resolved for one request, carrying the locale that actually supplied the content.
+ * `isLocaleFallback` is what a route reads to decide whether to render a "not translated yet,
+ * showing English" notice. Structurally mirrors `ResolvedCmsPostPage` on the Post side.
+ */
+interface ResolvedCmsPage<TPage extends CmsPageIdentity = PageVO> {
+  page: TPage;
+  requestedLocale: string;
+  contentLocale: string;
+  isLocaleFallback: boolean;
+}
 /** The slice of a `CmsIntegration` the Page helpers depend on. */
-interface CmsPageHelpersIntegration {
+interface CmsPageHelpersIntegration<TPage extends CmsPageIdentity = PageVO> {
   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>;
+  getBusabaseLandingPageByPathOrFallback: (path: string) => Promise<TPage | null>;
+  /** Status-aware variant, for callers that turn a missing page into a 404. */
+  readBusabaseLandingPageByPath: (path: string) => Promise<CmsRead<TPage | null>>;
 }
-interface CmsPageHelpersOptions<TMetadata> {
-  integration: CmsPageHelpersIntegration;
+interface CmsPageHelpersOptions<TMetadata, TPage extends CmsPageIdentity = PageVO> {
+  integration: CmsPageHelpersIntegration<TPage>;
   /**
    * 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>;
+interface CmsPageHelpers<TMetadata, TPage extends CmsPageIdentity = PageVO> {
+  /**
+   * STRICT per-locale lookup: no English fallback, `null` when this exact locale has no Page.
+   * Callers that run their own cross-locale cascade (Buda's use-case resolver cascades CMS →
+   * bundled ICP → editorial before falling back) must use this — handing them the fallback
+   * variant makes every locale look translated, which silently suppresses the "showing English"
+   * notice and mislabels the content locale.
+   */
+  getCmsPageForLocale: (locale: string, path: string | readonly string[]) => Promise<TPage | null>;
+  /**
+   * The resolved Page only. Falls back to English when the requested locale has no translation,
+   * so an untranslated Page renders in English instead of 404ing — the same rule the Post
+   * resolver applies. Use `resolveCmsPageForRequest` when the route needs to know it fell back.
+   */
+  getCmsPageForRequest: (lang: string, path: string | readonly string[]) => Promise<TPage | null>;
+  /** Same resolution as `getCmsPageForRequest`, plus which locale supplied the content. */
+  resolveCmsPageForRequest: (lang: string, path: string | readonly string[]) => Promise<ResolvedCmsPage<TPage> | null>;
+  /**
+   * Status-aware variant. A CMS Page has no local-MDX equivalent, so a catch-all
+   * route cannot otherwise tell "no page at this path" (a correct, cacheable
+   * 404) from "the CMS is unreachable" (a 404 that would be cached as though the
+   * page had been deleted).
+   */
+  readCmsPageForRequest: (lang: string, path: string | readonly string[]) => Promise<CmsRead<TPage | null>>;
+  /** Status-aware variant of `resolveCmsPageForRequest`. */
+  readResolvedCmsPageForRequest: (lang: string, path: string | readonly string[]) => Promise<CmsRead<ResolvedCmsPage<TPage> | null>>;
   generateCmsPageMetadata: (page: PageVO, lang: string) => TMetadata | Record<string, never>;
 }
-declare const createCmsPageHelpers: <TMetadata>({ integration, generatePageMetadata }: CmsPageHelpersOptions<TMetadata>) => CmsPageHelpers<TMetadata>;
+declare const createCmsPageHelpers: <TMetadata, TPage extends CmsPageIdentity = PageVO>({ integration, generatePageMetadata }: CmsPageHelpersOptions<TMetadata, TPage>) => CmsPageHelpers<TMetadata, TPage>;
 //#endregion
 //#region src/integration/posts.d.ts
 interface CmsPostReads {
@@ -222,6 +269,13 @@ interface CmsTaxonomyReads {
   listBusabaseCategoriesOrFallback: () => Promise<CategoryVO[]>;
   listBusabaseTags: () => Promise<TagVO[]>;
   listBusabaseTagsOrFallback: () => Promise<TagVO[]>;
+  /**
+   * Status-aware variants, for callers that turn the result into a 404.
+   * A Category or Tag exists only in the CMS — there is no local fallback — so
+   * "the CMS is unreachable" and "no such taxonomy" are otherwise identical here.
+   */
+  readBusabaseCategories: () => Promise<CmsRead<CategoryVO[]>>;
+  readBusabaseTags: () => Promise<CmsRead<TagVO[]>>;
 }
 declare const createCmsTaxonomyReads: ({ getCms, requireCms }: CmsClientProvider, appLabel: string) => CmsTaxonomyReads;
 //#endregion
@@ -248,4 +302,4 @@ interface CmsIntegration extends CmsPostReads, CmsPageReads, CmsTaxonomyReads {
 }
 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 };
+export { type BlogCardContent, type CmsClientProvider, CmsIntegration, type CmsIntegrationBaseSlugs, type CmsIntegrationCacheConfig, type CmsIntegrationCacheTags, type CmsIntegrationConfig, type CmsPageHelpers, type CmsPageHelpersIntegration, type CmsPageHelpersOptions, type CmsPageIdentity, 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 ResolvedCmsPage, type ResolvedCmsPostPage, buildCmsCacheKeyPrefix, createCmsClientProvider, createCmsIntegration, createCmsPageHelpers, createCmsPageReads, createCmsPostReads, createCmsPostResolver, createCmsTaxonomyReads, mergeBlogCardsByPath, readCmsEnvConfig, resolveCmsCacheTags };

package/dist/integration/index.js

@@ -1,4 +1,4 @@
-import { l as readCmsOrFallback, r as createCmsPathHelpers, s as normalizeCmsPath } from "../routing-C3lkVAZ8.js";
+import { l as readCmsOrFallback, r as createCmsPathHelpers, s as normalizeCmsPath, u as readCmsStatus } from "../routing-Cf35nomf.js";
 import { createCachedBusabaseCms } from "../next.js";
 import "server-only";
 import { cache } from "react";
@@ -118,6 +118,10 @@ const createCmsClientProvider = (config) => {
 const createCmsPageReads = ({ getCms, requireCms }, appLabel) => ({
 	listBusabaseLandingPages: async () => requireCms().pages.list(),
 	getBusabaseLandingPageByPath: async (path) => requireCms().pages.getByPath(path),
+	readBusabaseLandingPageByPath: async (path) => {
+		const cms = getCms();
+		return readCmsStatus(cms ? () => cms.pages.getByPath(path) : null, null, `get ${appLabel} page`);
+	},
 	listBusabaseLandingPagesOrFallback: async () => {
 		const cms = getCms();
 		return readCmsOrFallback(cms ? () => cms.pages.list() : null, [], `list ${appLabel} landing pages`);
@@ -127,27 +131,95 @@ const createCmsPageReads = ({ getCms, requireCms }, appLabel) => ({
 		return readCmsOrFallback(cms ? () => cms.pages.getByPath(path) : null, null, `get ${appLabel} landing page ${path}`);
 	}
 });
+/**
+* The locale every other locale falls back to when it has no translation of a Page.
+* Mirrors the Post resolver in ./posts.ts — see `resolvePostPageWithDependencies`.
+*/
+const FALLBACK_LOCALE = "en";
 const createCmsPageHelpers = ({ integration, generatePageMetadata }) => {
-	const { buildCmsPath, getBusabaseLandingPageByPathOrFallback, isCmsContentForLocale, parseCmsPath } = integration;
-	const getCmsPageForRequest = async (lang, path) => {
-		const canonicalPath = buildCmsPath(lang, path);
+	const { buildCmsPath, getBusabaseLandingPageByPathOrFallback, isCmsContentForLocale, parseCmsPath, readBusabaseLandingPageByPath } = integration;
+	const getForLocale = async (locale, path) => {
+		const canonicalPath = buildCmsPath(locale, path);
 		if (!canonicalPath) return null;
 		const page = await getBusabaseLandingPageByPathOrFallback(canonicalPath);
-		return page && isCmsContentForLocale(page, lang) ? page : null;
+		return page && isCmsContentForLocale(page, locale) ? page : null;
+	};
+	const readForLocale = async (locale, path) => {
+		const canonicalPath = buildCmsPath(locale, path);
+		if (!canonicalPath) return {
+			status: "ok",
+			data: null
+		};
+		const read = await readBusabaseLandingPageByPath(canonicalPath);
+		if (read.status !== "ok") return read;
+		const page = read.data;
+		return {
+			status: "ok",
+			data: page && isCmsContentForLocale(page, locale) ? page : null
+		};
+	};
+	const resolved = (page, requestedLocale, contentLocale) => ({
+		page,
+		requestedLocale,
+		contentLocale,
+		isLocaleFallback: contentLocale !== requestedLocale
+	});
+	const resolveCmsPageForRequest = async (lang, path) => {
+		if (!buildCmsPath(lang, path)) return null;
+		const requested = await getForLocale(lang, path);
+		if (requested) return resolved(requested, lang, lang);
+		if (lang === FALLBACK_LOCALE) return null;
+		const fallback = await getForLocale(FALLBACK_LOCALE, path);
+		return fallback ? resolved(fallback, lang, FALLBACK_LOCALE) : null;
+	};
+	const getCmsPageForRequest = async (lang, path) => (await resolveCmsPageForRequest(lang, path))?.page ?? null;
+	const readResolvedCmsPageForRequest = async (lang, path) => {
+		if (!buildCmsPath(lang, path)) return {
+			status: "ok",
+			data: null
+		};
+		const requested = await readForLocale(lang, path);
+		if (requested.status !== "ok") return requested;
+		if (requested.data) return {
+			status: "ok",
+			data: resolved(requested.data, lang, lang)
+		};
+		if (lang === FALLBACK_LOCALE) return {
+			status: "ok",
+			data: null
+		};
+		const fallback = await readForLocale(FALLBACK_LOCALE, path);
+		if (fallback.status !== "ok") return fallback;
+		return {
+			status: "ok",
+			data: fallback.data ? resolved(fallback.data, lang, FALLBACK_LOCALE) : null
+		};
+	};
+	const readCmsPageForRequest = async (lang, path) => {
+		const read = await readResolvedCmsPageForRequest(lang, path);
+		return read.status === "ok" ? {
+			status: "ok",
+			data: read.data?.page ?? null
+		} : read;
 	};
 	const generateCmsPageMetadata = (page, lang) => {
 		const parsed = parseCmsPath(page.path);
-		if (!parsed || parsed.locale !== lang) return {};
+		if (!parsed) return {};
+		const contentLocale = isCmsContentForLocale(page, lang) ? lang : parsed.locale;
 		return generatePageMetadata({
 			title: page.seoTitle ?? page.title,
 			description: page.seoDescription ?? "",
 			path: parsed.pathWithoutLocale,
-			lang,
+			lang: contentLocale,
 			type: "website"
 		});
 	};
 	return {
+		getCmsPageForLocale: getForLocale,
 		getCmsPageForRequest,
+		resolveCmsPageForRequest,
+		readCmsPageForRequest,
+		readResolvedCmsPageForRequest,
 		generateCmsPageMetadata
 	};
 };
@@ -238,6 +310,14 @@ const createCmsTaxonomyReads = ({ getCms, requireCms }, appLabel) => ({
 		return readCmsOrFallback(cms ? () => cms.categories.list() : null, [], `list ${appLabel} categories`);
 	},
 	listBusabaseTags: async () => requireCms().tags.list(),
+	readBusabaseCategories: async () => {
+		const cms = getCms();
+		return readCmsStatus(cms ? () => cms.categories.list() : null, [], `list ${appLabel} categories`);
+	},
+	readBusabaseTags: async () => {
+		const cms = getCms();
+		return readCmsStatus(cms ? () => cms.tags.list() : null, [], `list ${appLabel} tags`);
+	},
 	listBusabaseTagsOrFallback: async () => {
 		const cms = getCms();
 		return readCmsOrFallback(cms ? () => cms.tags.list() : null, [], `list ${appLabel} tags`);

package/dist/{routing-C3lkVAZ8.js → routing-Cf35nomf.js}

@@ -14,6 +14,32 @@ const readCmsOrFallback = async (operation, fallback, label) => {
 		return fallback;
 	}
 };
+const readCmsStatus = async (operation, whenUnconfigured, label) => {
+	if (!operation) return {
+		status: "ok",
+		data: whenUnconfigured
+	};
+	try {
+		return {
+			status: "ok",
+			data: await operation()
+		};
+	} catch (error) {
+		console.warn(`[busabase-cms] ${label} failed`, error);
+		return { status: "unavailable" };
+	}
+};
+/**
+* Unwrap a read, or fail loudly.
+*
+* Throwing beats rendering a 404: an error response is not cached, so the page
+* recovers on the next request, whereas a cached 404 tells crawlers the content
+* is gone.
+*/
+const requireCmsRead = (read, what) => {
+	if (read.status === "unavailable") throw new Error(`Busabase CMS unreachable while rendering ${what}`);
+	return read.data;
+};
 //#endregion
 //#region src/routing.ts
 const normalizeSegment = (segment) => {
@@ -88,4 +114,4 @@ const filterCmsPostsByTaxonomy = (posts, kind, taxonomy) => {
 	return posts.filter((post) => post.locale === taxonomy.locale && post[relationKey].includes(taxonomy.id));
 };
 //#endregion
-export { isCmsBlogPostPath as a, parseCmsCanonicalPath as c, filterCmsPostsByTaxonomy as i, readCmsOrFallback as l, buildCmsTaxonomyArchivePath as n, isCmsContentForLocale as o, createCmsPathHelpers as r, normalizeCmsPath as s, buildCmsCanonicalPath as t };
+export { isCmsBlogPostPath as a, parseCmsCanonicalPath as c, requireCmsRead as d, filterCmsPostsByTaxonomy as i, readCmsOrFallback as l, buildCmsTaxonomyArchivePath as n, isCmsContentForLocale as o, createCmsPathHelpers as r, normalizeCmsPath as s, buildCmsCanonicalPath as t, readCmsStatus as u };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "busabase-cms-sdk",
-  "version": "0.1.3",
+  "version": "0.1.5",
   "description": "Typed Posts, Pages, Categories, and Tags for Busabase CMS, Next.js, and Fumadocs.",
   "license": "MIT",
   "homepage": "https://github.com/busabase/busabase/tree/main/packages/busabase-cms-sdk",
@@ -41,13 +41,13 @@
   ],
   "sideEffects": false,
   "dependencies": {
-    "busabase-sdk": "^0.30.1",
     "fumadocs-core": "16.14.5",
     "rehype-sanitize": "^6.0.0",
     "remark-gfm": "^4.0.1",
     "sanitize-html": "^2.17.6",
     "server-only": "^0.0.1",
-    "zod": "^4.3.6"
+    "zod": "^4.3.6",
+    "busabase-sdk": "^0.53.0"
   },
   "peerDependencies": {
     "next": ">=15 <17",
@@ -62,7 +62,7 @@
     }
   },
   "devDependencies": {
-    "@types/node": "^24.13.2",
+    "@types/node": "^26.3.0",
     "@types/react": "^19.2.17",
     "@types/sanitize-html": "^2.16.1",
     "next": "16.3.3",