busabase-cms-sdk 0.1.4 → 0.1.6

package/dist/integration/index.d.ts

@@ -126,38 +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<PageVO | null>>;
+  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<PageVO | null>>;
+  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 {
@@ -267,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

@@ -131,16 +131,21 @@ 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, readBusabaseLandingPageByPath } = integration;
-	const getCmsPageForRequest = async (lang, path) => {
-		const canonicalPath = buildCmsPath(lang, path);
+	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 readCmsPageForRequest = async (lang, path) => {
-		const canonicalPath = buildCmsPath(lang, path);
+	const readForLocale = async (locale, path) => {
+		const canonicalPath = buildCmsPath(locale, path);
 		if (!canonicalPath) return {
 			status: "ok",
 			data: null
@@ -150,23 +155,71 @@ const createCmsPageHelpers = ({ integration, generatePageMetadata }) => {
 		const page = read.data;
 		return {
 			status: "ok",
-			data: page && isCmsContentForLocale(page, lang) ? page : null
+			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
 	};
 };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "busabase-cms-sdk",
-  "version": "0.1.4",
+  "version": "0.1.6",
   "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",
@@ -47,7 +47,7 @@
     "sanitize-html": "^2.17.6",
     "server-only": "^0.0.1",
     "zod": "^4.3.6",
-    "busabase-sdk": "^0.50.0"
+    "busabase-sdk": "^0.60.0"
   },
   "peerDependencies": {
     "next": ">=15 <17",