@roottale/cms-client 0.66.0 → 0.67.0

package/CHANGELOG.md

@@ -1,5 +1,16 @@
 # @roottale/cms-client
 
+## 0.67.0
+
+### Minor Changes
+
+- 30d26ac: 공통 메타데이터 해석기·고유 경로 조회·Next SSR 빌더와 캐시 태그를 추가합니다. 기존 canonical과 강제 robots 정책을 보존하고 공유 이미지 대체 텍스트를 OG·X에 동일하게 적용합니다. 분류의 공유 전용 설정과 메타데이터 조회·수정 MCP 도구, Pro 하향 후 공개 적용 유지 계약을 문서와 예제에 반영합니다. 분류 색인 전환을 선언한 사이트가 공개 분류 응답의 `category_index_activated`를 확인한 뒤에만 분류 검색 제외를 적용하도록 안내합니다.
+
+### Patch Changes
+
+- Updated dependencies [30d26ac]
+  - @roottale/cms-core@0.67.0
+
 ## 0.66.0
 
 ### Minor Changes

package/dist/server.d.ts

@@ -2,6 +2,8 @@ import { InquiryFormDefinition, InquiryAnswer } from '@roottale/inquiry-forms';
 export { InquiryAnswer, InquiryFormDefinition, InquiryFormField, InquiryKind } from '@roottale/inquiry-forms';
 import { InquiryAttribution } from './attribution.js';
 export { parseAttributionJson } from './attribution.js';
+import { PublicRouteMetadata } from '@roottale/cms-core';
+export { MetadataDefaultRules, MetadataDefaultRulesSchema, MetadataDefaultsDeclaration, MetadataDefaultsInput, MetadataField, MetadataPatch, MetadataResolutionInput, MetadataRobotsPolicy, MetadataTextRule, MetadataValues, PublicRouteMetadata, formatMetadataDefaults, metadataContentImageUrl, readMetadataValues, resolveMetadata } from '@roottale/cms-core';
 
 /**
  * `@roottale/cms-client/server` — RootTale CMS Public API server-side fetch client.
@@ -754,6 +756,10 @@ interface CmsCategoryCount {
     description: string | null;
     seoTitle: string | null;
     seoDescription: string | null;
+    /** 공유 전용 설정. 본문 분류 이미지와 별도로 관리한다. */
+    seoOgImage?: string | null;
+    seoOgImageAlt?: string | null;
+    seoNofollow?: boolean | null;
     imageMediaId?: string | null;
     imageUrl?: string | null;
     imageAlt?: string | null;
@@ -1345,6 +1351,34 @@ declare function sitePatternPresentationAttributes(presentation: CmsSitePatternP
  */
 declare function selectSitePatternForSlot(patternSlots: Readonly<Record<string, string | null>> | null | undefined, patterns: readonly CmsSitePattern[], slot?: string): CmsSitePattern | null;
 
+declare const METADATA_CACHE_TAG = "rt-metadata";
+declare const SITE_METADATA_DEFAULTS_CACHE_TAG = "rt-metadata-defaults";
+/** locale를 생략한 요청은 사이트 기본 locale을 조회한다. */
+declare function routeMetadataCacheTag(routeKey: string, locale?: string): string;
+interface FetchRouteMetadataOptions {
+    apiKey: string;
+    baseUrl?: string;
+    siteId?: string;
+    routeKey: string;
+    locale?: string;
+    signal?: AbortSignal;
+    /** 기본 300초. 웹훅 유실 시 재조회하며, 0이면 항상 최신값을 읽는다. */
+    revalidate?: number;
+}
+/**
+ * 고유 route key 직접 조회. 등록되지 않은 경로만 null이며, 연결된 빈 설정은
+ * overrides:{}인 객체다. HTTP/네트워크/응답 오류는 throw하여 빈 설정으로 캐시하지 않는다.
+ * 공개 읽기는 구독 등급을 검사하지 않아 요금제 하향 후에도 기존 설정을 유지한다.
+ */
+declare function fetchRouteMetadata(options: FetchRouteMetadataOptions): Promise<PublicRouteMetadata | null>;
+
+/**
+ * 배포 도구가 정규화해 등록한 manifest의 SHA-256(64자리 hex).
+ * 이 함수는 스키마 검사·기본값 채우기를 하지 않는다. 원본 JSON을 그대로 해시하면
+ * 등록 API가 정규화한 계약과 달라질 수 있으므로 배포 시 정규화한 manifest를 사용한다.
+ */
+declare function metadataContractChecksum(normalizedContract: unknown): Promise<string>;
+
 /**
  * 설정류 fetch 캐시 tag 한 벌 (ADR-0096 Phase C).
  *
@@ -1657,4 +1691,4 @@ declare function formatKoreanPhoneNumber(input: string): string;
  */
 declare function submitInquiry(options: SubmitInquiryOptions): Promise<SubmitInquiryResult>;
 
-export { type ActionDockAction, type ActionDockKind, type ActionDockPosition, type ActionDockSettings, type AnalyticsTagConfig, type AnalyticsTagProvider, type AnnouncementItem, type AnnouncementSettings, type AnnouncementTone, type AnnouncementVariant, type ArticleSchemaInput, BLOG_SETTINGS_CACHE_TAG, BUSINESS_CACHE_TAG, type BusinessDayCode, type BusinessOpeningHours, type BusinessType, CMS_CLIENT_VERSION, COLLECTIONS_CACHE_TAG, CmsApiError, type CmsArchiveRelatedGroup, type CmsArchiveRelatedPost, type CmsCategoryCount, type CmsCategoryCounts, type CmsContentModel, type CmsExposureCampaign, type CmsExposureDecision, type CmsFieldMetaEntry, type CmsPostContent, type CmsPostContentPage, type CmsPostPreviewContent, type CmsPostPreviewInfo, type CmsPostTranslationRef, type CmsPostType, type CmsRouteCollection, type CmsSearchHit, type CmsSitePattern, type CmsSitePatternPresentation, type CmsTaxonomyKind, type CmsTermRef, DEFAULT_BLOG_SETTINGS, DEFAULT_SITE_PATTERN_PRESENTATION, EXPOSURE_CACHE_TAG, type FetchAnalyticsOptions, type FetchAuthorsOptions, type FetchBlogSettingsOptions, type FetchBusinessProfileOptions, type FetchCategoryCountsOptions, type FetchCollectionsOptions, type FetchContentModelsOptions, type FetchExposureDecisionOptions, type FetchExposureOptions, type FetchInquiryFormOptions, type FetchMenuOptions, type FetchMenusOptions, type FetchPageBySlugOptions, type FetchPostOptions, type FetchPostPreviewOptions, type FetchPostsOptions, type FetchRedirectsOptions, type FetchSiteInquiriesOptions, type FetchSiteInquiryOptions, type FetchSitePatternsOptions, type FetchThemeOptions, type FormInquiryReceipt, INQUIRY_ERROR_MESSAGES, InquiryAttribution, type InquiryBoardSettings, type InquiryVertical, LOCAL_BUSINESS_MAX_SERVICES, LOCAL_BUSINESS_SERVICE_MAX_LENGTH, type LocalBusinessProfileInput, MENUS_CACHE_TAG, POST_FOOTER_PATTERN_SLOT, type PublishedInquiryForm, type ResolvedPostDisplay, type RootTaleAuthor, type RootTaleBlogPostCta, type RootTaleBlogSettings, type RootTaleBusinessProfile, type RootTaleMenu, type RootTaleMenuItem, type RootTaleRedirect, type RootTaleSiteProfile, type RootTaleSitemapSettings, type RootTaleTheme, type RssFeedInput, type RssItemInput, SETTINGS_CACHE_TAGS, SITE_PATTERNS_CACHE_TAG, type SearchPostsOptions, type SiteAnalyticsTags, type SiteInquiryDetail, type SiteInquiryListItem, type SiteInquiryListPage, type SiteInquiryStatus, type SiteNavColumn, type SiteNavCta, type SiteNavGroup, type SiteNavLink, type SiteNavSettings, type SiteVerificationMetadata, type SiteVerificationSettings, type SubmitFormInquiryFields, type SubmitFormInquiryOptions, type SubmitFormInquiryResult, type SubmitInquiryFields, type SubmitInquiryOptions, type SubmitInquiryResult, type SubmitSiteInquiryFields, type SubmitSiteInquiryOptions, type SubmitSiteInquiryResult, THEME_CACHE_TAG, articleSchema, breadcrumbSchema, businessProfileFromWire, collectionPageSchema, contentIdMeta, faqSchema, fetchAnalyticsConfig, fetchAuthors, fetchBlogSettings, fetchBusinessProfile, fetchCategoryCounts, fetchCollections, fetchCollectionsSafeDefault, fetchContentModels, fetchExposure, fetchExposureDecision, fetchInquiryForm, fetchMenu, fetchMenus, fetchPageBySlug, fetchPost, fetchPostPreview, fetchPosts, fetchRedirects, fetchSiteInquiries, fetchSiteInquiry, fetchSitePatterns, fetchTheme, formatKoreanPhoneNumber, generateRssXml, inquiryErrorMessage, isPreviewExpiredError, jsonLdJson, jsonLdScript, localBusinessSchema, organizationSchema, parseInquiryRedirect, profilePageSchema, resolvePostDisplay, resolveSearchHitPath, rssItemsFromPosts, searchPosts, selectRelatedPosts, selectSitePatternForSlot, sitePatternPresentationAttributes, siteVerificationMetadata, submitFormInquiry, submitInquiry, submitSiteInquiry, websiteSchema };
+export { type ActionDockAction, type ActionDockKind, type ActionDockPosition, type ActionDockSettings, type AnalyticsTagConfig, type AnalyticsTagProvider, type AnnouncementItem, type AnnouncementSettings, type AnnouncementTone, type AnnouncementVariant, type ArticleSchemaInput, BLOG_SETTINGS_CACHE_TAG, BUSINESS_CACHE_TAG, type BusinessDayCode, type BusinessOpeningHours, type BusinessType, CMS_CLIENT_VERSION, COLLECTIONS_CACHE_TAG, CmsApiError, type CmsArchiveRelatedGroup, type CmsArchiveRelatedPost, type CmsCategoryCount, type CmsCategoryCounts, type CmsContentModel, type CmsExposureCampaign, type CmsExposureDecision, type CmsFieldMetaEntry, type CmsPostContent, type CmsPostContentPage, type CmsPostPreviewContent, type CmsPostPreviewInfo, type CmsPostTranslationRef, type CmsPostType, type CmsRouteCollection, type CmsSearchHit, type CmsSitePattern, type CmsSitePatternPresentation, type CmsTaxonomyKind, type CmsTermRef, DEFAULT_BLOG_SETTINGS, DEFAULT_SITE_PATTERN_PRESENTATION, EXPOSURE_CACHE_TAG, type FetchAnalyticsOptions, type FetchAuthorsOptions, type FetchBlogSettingsOptions, type FetchBusinessProfileOptions, type FetchCategoryCountsOptions, type FetchCollectionsOptions, type FetchContentModelsOptions, type FetchExposureDecisionOptions, type FetchExposureOptions, type FetchInquiryFormOptions, type FetchMenuOptions, type FetchMenusOptions, type FetchPageBySlugOptions, type FetchPostOptions, type FetchPostPreviewOptions, type FetchPostsOptions, type FetchRedirectsOptions, type FetchRouteMetadataOptions, type FetchSiteInquiriesOptions, type FetchSiteInquiryOptions, type FetchSitePatternsOptions, type FetchThemeOptions, type FormInquiryReceipt, INQUIRY_ERROR_MESSAGES, InquiryAttribution, type InquiryBoardSettings, type InquiryVertical, LOCAL_BUSINESS_MAX_SERVICES, LOCAL_BUSINESS_SERVICE_MAX_LENGTH, type LocalBusinessProfileInput, MENUS_CACHE_TAG, METADATA_CACHE_TAG, POST_FOOTER_PATTERN_SLOT, type PublishedInquiryForm, type ResolvedPostDisplay, type RootTaleAuthor, type RootTaleBlogPostCta, type RootTaleBlogSettings, type RootTaleBusinessProfile, type RootTaleMenu, type RootTaleMenuItem, type RootTaleRedirect, type RootTaleSiteProfile, type RootTaleSitemapSettings, type RootTaleTheme, type RssFeedInput, type RssItemInput, SETTINGS_CACHE_TAGS, SITE_METADATA_DEFAULTS_CACHE_TAG, SITE_PATTERNS_CACHE_TAG, type SearchPostsOptions, type SiteAnalyticsTags, type SiteInquiryDetail, type SiteInquiryListItem, type SiteInquiryListPage, type SiteInquiryStatus, type SiteNavColumn, type SiteNavCta, type SiteNavGroup, type SiteNavLink, type SiteNavSettings, type SiteVerificationMetadata, type SiteVerificationSettings, type SubmitFormInquiryFields, type SubmitFormInquiryOptions, type SubmitFormInquiryResult, type SubmitInquiryFields, type SubmitInquiryOptions, type SubmitInquiryResult, type SubmitSiteInquiryFields, type SubmitSiteInquiryOptions, type SubmitSiteInquiryResult, THEME_CACHE_TAG, articleSchema, breadcrumbSchema, businessProfileFromWire, collectionPageSchema, contentIdMeta, faqSchema, fetchAnalyticsConfig, fetchAuthors, fetchBlogSettings, fetchBusinessProfile, fetchCategoryCounts, fetchCollections, fetchCollectionsSafeDefault, fetchContentModels, fetchExposure, fetchExposureDecision, fetchInquiryForm, fetchMenu, fetchMenus, fetchPageBySlug, fetchPost, fetchPostPreview, fetchPosts, fetchRedirects, fetchRouteMetadata, fetchSiteInquiries, fetchSiteInquiry, fetchSitePatterns, fetchTheme, formatKoreanPhoneNumber, generateRssXml, inquiryErrorMessage, isPreviewExpiredError, jsonLdJson, jsonLdScript, localBusinessSchema, metadataContractChecksum, organizationSchema, parseInquiryRedirect, profilePageSchema, resolvePostDisplay, resolveSearchHitPath, routeMetadataCacheTag, rssItemsFromPosts, searchPosts, selectRelatedPosts, selectSitePatternForSlot, sitePatternPresentationAttributes, siteVerificationMetadata, submitFormInquiry, submitInquiry, submitSiteInquiry, websiteSchema };

package/dist/server.js

@@ -4,7 +4,7 @@ import {
 
 // src/server-base.ts
 var DEFAULT_BASE_URL = "https://api.roottale.com";
-var CLIENT_VERSION = true ? "0.66.0" : "dev";
+var CLIENT_VERSION = true ? "0.67.0" : "dev";
 var CMS_CLIENT_VERSION = CLIENT_VERSION;
 function authHeaders(apiKey) {
   return {
@@ -559,6 +559,9 @@ async function fetchCategoryCounts(options) {
           description: typeof o.description === "string" ? o.description : null,
           seoTitle: typeof o.seo_title === "string" ? o.seo_title : null,
           seoDescription: typeof o.seo_description === "string" ? o.seo_description : null,
+          seoOgImage: typeof o.seo_og_image === "string" ? o.seo_og_image : null,
+          seoOgImageAlt: typeof o.seo_og_image_alt === "string" ? o.seo_og_image_alt : null,
+          seoNofollow: typeof o.seo_nofollow === "boolean" ? o.seo_nofollow : null,
           imageMediaId: typeof o.image_media_id === "string" ? o.image_media_id : null,
           imageUrl: typeof o.image_url === "string" ? o.image_url : null,
           imageAlt: typeof o.image_alt === "string" ? o.image_alt : null,
@@ -1196,6 +1199,63 @@ function selectSitePatternForSlot(patternSlots, patterns, slot = POST_FOOTER_PAT
   return patterns.find((pattern) => pattern.key === key) ?? null;
 }
 
+// src/server-metadata.ts
+import { MetadataRobotsPolicySchema, MetadataValuesSchema } from "@roottale/cms-core";
+import { readMetadataValues, resolveMetadata, formatMetadataDefaults, metadataContentImageUrl, MetadataDefaultRulesSchema } from "@roottale/cms-core";
+var METADATA_CACHE_TAG = "rt-metadata";
+var SITE_METADATA_DEFAULTS_CACHE_TAG = "rt-metadata-defaults";
+function routeMetadataCacheTag(routeKey, locale) {
+  if (!/^[a-z][a-z0-9]*(?:-[a-z0-9]+)*$/.test(routeKey) || routeKey.length > 160) throw new Error("Invalid metadata route key");
+  const language = locale?.trim().toLowerCase() || "default";
+  if (!/^[a-z0-9]+(?:-[a-z0-9]+)*$/.test(language) || language.length > 40) {
+    throw new Error("Invalid metadata locale");
+  }
+  return `${METADATA_CACHE_TAG}:${routeKey}:${language}`;
+}
+async function fetchRouteMetadata(options) {
+  assertServer();
+  const routeTag = routeMetadataCacheTag(options.routeKey, options.locale);
+  const params = new URLSearchParams({ route_key: options.routeKey });
+  if (options.locale) params.set("locale", options.locale);
+  if (options.siteId) params.set("site_id", options.siteId);
+  const baseUrl = (options.baseUrl ?? DEFAULT_BASE_URL).replace(/\/+$/, "");
+  const response = await fetch(`${baseUrl}/v1/cms/public/metadata?${params}`, buildGetInit(options.apiKey, {
+    signal: options.signal,
+    revalidate: options.revalidate ?? 300,
+    tags: [METADATA_CACHE_TAG, SITE_METADATA_DEFAULTS_CACHE_TAG, routeTag]
+  }));
+  if (!response.ok) throw await toApiError(response);
+  const json = await response.json();
+  if (!json || typeof json !== "object" || !("metadata" in json)) throw unexpectedResponse(response.status);
+  if (json.metadata === null) return null;
+  if (!isRouteMetadata(json.metadata) || json.metadata.routeKey !== options.routeKey) throw unexpectedResponse(response.status);
+  return json.metadata;
+}
+function isValues(value) {
+  return MetadataValuesSchema.safeParse(value).success;
+}
+function isRouteMetadata(value) {
+  if (!value || typeof value !== "object" || Array.isArray(value)) return false;
+  const row = value;
+  return typeof row.routeKey === "string" && typeof row.locale === "string" && typeof row.path === "string" && row.path.startsWith("/") && !row.path.startsWith("//") && typeof row.version === "string" && isValues(row.overrides) && isValues(row.defaults) && isValues(row.effective) && (row.fallback === void 0 || isValues(row.fallback)) && (row.robots === void 0 || MetadataRobotsPolicySchema.safeParse(row.robots).success) && Array.isArray(row.supportedFields) && row.supportedFields.every((field) => ["title", "description", "ogImage", "ogImageAlt", "noindex", "nofollow"].includes(field));
+}
+function unexpectedResponse(status) {
+  return new CmsApiError("RootTale CMS API returned invalid route metadata", status, "unexpected_response");
+}
+
+// src/metadata-contract-checksum.ts
+function canonicalize(value) {
+  if (Array.isArray(value)) return value.map(canonicalize);
+  if (!value || typeof value !== "object") return value;
+  return Object.fromEntries(Object.entries(value).sort(([left], [right]) => left.localeCompare(right)).map(([key, child]) => [key, canonicalize(child)]));
+}
+async function metadataContractChecksum(normalizedContract) {
+  const json = JSON.stringify(canonicalize(normalizedContract));
+  if (json === void 0) throw new Error("Metadata contract must be a normalized JSON value");
+  const digest = await globalThis.crypto.subtle.digest("SHA-256", new TextEncoder().encode(json));
+  return Array.from(new Uint8Array(digest), (byte) => byte.toString(16).padStart(2, "0")).join("");
+}
+
 // src/server-cache-tags.ts
 var SETTINGS_CACHE_TAGS = [
   THEME_CACHE_TAG,
@@ -1204,7 +1264,9 @@ var SETTINGS_CACHE_TAGS = [
   BLOG_SETTINGS_CACHE_TAG,
   COLLECTIONS_CACHE_TAG,
   EXPOSURE_CACHE_TAG,
-  SITE_PATTERNS_CACHE_TAG
+  SITE_PATTERNS_CACHE_TAG,
+  METADATA_CACHE_TAG,
+  SITE_METADATA_DEFAULTS_CACHE_TAG
 ];
 
 // src/seo.ts
@@ -1651,8 +1713,11 @@ export {
   LOCAL_BUSINESS_MAX_SERVICES,
   LOCAL_BUSINESS_SERVICE_MAX_LENGTH,
   MENUS_CACHE_TAG,
+  METADATA_CACHE_TAG,
+  MetadataDefaultRulesSchema,
   POST_FOOTER_PATTERN_SLOT,
   SETTINGS_CACHE_TAGS,
+  SITE_METADATA_DEFAULTS_CACHE_TAG,
   SITE_PATTERNS_CACHE_TAG,
   THEME_CACHE_TAG,
   articleSchema,
@@ -1679,23 +1744,30 @@ export {
   fetchPostPreview,
   fetchPosts,
   fetchRedirects,
+  fetchRouteMetadata,
   fetchSiteInquiries,
   fetchSiteInquiry,
   fetchSitePatterns,
   fetchTheme,
   formatKoreanPhoneNumber,
+  formatMetadataDefaults,
   generateRssXml,
   inquiryErrorMessage,
   isPreviewExpiredError,
   jsonLdJson,
   jsonLdScript,
   localBusinessSchema,
+  metadataContentImageUrl,
+  metadataContractChecksum,
   organizationSchema,
   parseAttributionJson,
   parseInquiryRedirect,
   profilePageSchema,
+  readMetadataValues,
+  resolveMetadata,
   resolvePostDisplay,
   resolveSearchHitPath,
+  routeMetadataCacheTag,
   rssItemsFromPosts,
   searchPosts,
   selectRelatedPosts,