@roottale/cms-client 0.7.0 → 0.8.0

package/CHANGELOG.md

@@ -1,5 +1,21 @@
 # @roottale/cms-client
 
+## 0.8.0
+
+### Minor Changes
+
+- 2d1b14c: feat: 플랫폼에서 블로그 표시 제어 (목차/작성자/발행일 + 목차 제목)
+  - **cms-client**: `fetchBlogSettings()` + `RootTaleBlogSettings` + `resolvePostDisplay()`
+    (명시 prop > 글별 override[post.metaJson.display] > 사이트 기본값 우선순위) +
+    `DEFAULT_BLOG_SETTINGS`.
+  - **cms-renderer-next / cms-renderer-astro**: RootTaleBlogPost/List 가 사이트
+    설정(/blog-settings)과 글별 override 를 읽어 목차·작성자·발행일 표시를 결정.
+    `showTableOfContents` prop 은 더 이상 강제값이 아니라 명시 override(미지정 시
+    플랫폼 설정 따름). 목차 제목도 플랫폼 설정 사용.
+
+  admin /design 의 "블로그 표시" 설정 + 에디터의 글별 "표시 옵션" 으로 제어한다.
+  (공개 API `/v1/cms/public/blog-settings` 는 api-core 배포로 함께 제공.)
+
 ## 0.7.0
 
 ### Minor Changes

package/dist/server.d.ts

@@ -129,6 +129,48 @@ interface FetchThemeOptions {
  * 네트워크/서버 에러는 throw — 호출자가 fallback 처리.
  */
 declare function fetchTheme(options: FetchThemeOptions): Promise<RootTaleTheme>;
+/**
+ * 블로그 표시 설정 — admin /design 의 "블로그 표시" 에서 저장한 사이트 기본값.
+ * renderer 가 prop 미지정 시 이 값을 기본으로 적용 (글별 override 는 post 의
+ * metaJson.display 가 우선).
+ */
+interface RootTaleBlogSettings {
+    showTableOfContents: boolean;
+    showAuthor: boolean;
+    showDate: boolean;
+    /** 목차 상단 제목. null = renderer 기본("목차"). */
+    tocTitle: string | null;
+}
+interface FetchBlogSettingsOptions {
+    apiKey: string;
+    baseUrl?: string;
+    siteId?: string;
+    signal?: AbortSignal;
+}
+/**
+ * tenant 의 블로그 표시 기본값을 가져온다. 네트워크/서버 에러는 throw —
+ * 호출자(renderer)가 안전 기본값으로 fallback.
+ */
+declare function fetchBlogSettings(options: FetchBlogSettingsOptions): Promise<RootTaleBlogSettings>;
+/** fetch 실패/미설정 시 사용할 안전 기본값 (기존 렌더러 동작). */
+declare const DEFAULT_BLOG_SETTINGS: RootTaleBlogSettings;
+interface ResolvedPostDisplay {
+    showTableOfContents: boolean;
+    showAuthor: boolean;
+    showDate: boolean;
+    tocTitle: string;
+}
+/**
+ * 글 1건의 실제 표시 여부 결정. 우선순위:
+ *   명시 prop > 글별 override(post.metaJson.display) > 사이트 기본값(settings).
+ * tocTitle: 명시 prop > settings.tocTitle > "목차".
+ */
+declare function resolvePostDisplay(post: {
+    metaJson?: Record<string, unknown> | null;
+}, settings: RootTaleBlogSettings, explicit?: {
+    showTableOfContents?: boolean;
+    tableOfContentsTitle?: string;
+}): ResolvedPostDisplay;
 declare class CmsApiError extends Error {
     readonly status: number;
     readonly code: string;
@@ -137,4 +179,4 @@ declare class CmsApiError extends Error {
 declare function fetchPosts(options: FetchPostsOptions): Promise<CmsPostContentPage>;
 declare function fetchPost(options: FetchPostOptions): Promise<CmsPostContent | null>;
 
-export { CmsApiError, type CmsPostContent, type CmsPostContentPage, type CmsPostType, type CmsTaxonomyKind, type CmsTermRef, type FetchPostOptions, type FetchPostsOptions, type FetchThemeOptions, type RootTaleTheme, fetchPost, fetchPosts, fetchTheme };
+export { CmsApiError, type CmsPostContent, type CmsPostContentPage, type CmsPostType, type CmsTaxonomyKind, type CmsTermRef, DEFAULT_BLOG_SETTINGS, type FetchBlogSettingsOptions, type FetchPostOptions, type FetchPostsOptions, type FetchThemeOptions, type ResolvedPostDisplay, type RootTaleBlogSettings, type RootTaleTheme, fetchBlogSettings, fetchPost, fetchPosts, fetchTheme, resolvePostDisplay };

package/dist/server.js

@@ -22,6 +22,45 @@ async function fetchTheme(options) {
   if (json.radius) theme.radius = json.radius;
   return theme;
 }
+async function fetchBlogSettings(options) {
+  assertServer();
+  const baseUrl = (options.baseUrl ?? DEFAULT_BASE_URL).replace(/\/+$/, "");
+  const params = new URLSearchParams();
+  if (options.siteId) params.set("site_id", options.siteId);
+  const qs = params.toString();
+  const url = `${baseUrl}/v1/cms/public/blog-settings${qs ? `?${qs}` : ""}`;
+  const response = await fetch(url, {
+    method: "GET",
+    headers: { authorization: `Bearer ${options.apiKey}` },
+    signal: options.signal
+  });
+  if (!response.ok) {
+    throw await toApiError(response);
+  }
+  const json = await response.json();
+  return {
+    showTableOfContents: json.show_table_of_contents === true,
+    showAuthor: json.show_author !== false,
+    showDate: json.show_date !== false,
+    tocTitle: typeof json.toc_title === "string" && json.toc_title.length > 0 ? json.toc_title : null
+  };
+}
+var DEFAULT_BLOG_SETTINGS = {
+  showTableOfContents: false,
+  showAuthor: true,
+  showDate: true,
+  tocTitle: null
+};
+function resolvePostDisplay(post, settings, explicit) {
+  const display = post.metaJson && typeof post.metaJson === "object" ? post.metaJson.display : void 0;
+  const ov = (key) => display && typeof display[key] === "boolean" ? display[key] : void 0;
+  return {
+    showTableOfContents: explicit?.showTableOfContents ?? ov("toc") ?? settings.showTableOfContents,
+    showAuthor: ov("author") ?? settings.showAuthor,
+    showDate: ov("date") ?? settings.showDate,
+    tocTitle: explicit?.tableOfContentsTitle ?? settings.tocTitle ?? "\uBAA9\uCC28"
+  };
+}
 var CmsApiError = class extends Error {
   status;
   code;
@@ -117,8 +156,11 @@ function assertServer() {
 }
 export {
   CmsApiError,
+  DEFAULT_BLOG_SETTINGS,
+  fetchBlogSettings,
   fetchPost,
   fetchPosts,
-  fetchTheme
+  fetchTheme,
+  resolvePostDisplay
 };
 //# sourceMappingURL=server.js.map

package/dist/server.js.map

@@ -1 +1 @@
-{"version":3,"sources":["../src/server.ts"],"sourcesContent":["/**\n * `@roottale/cms-client/server` — RootTale CMS Public API server-side fetch client.\n *\n * 외부 고객사 사이트가 RootTale CMS 콘텐츠를 fetch 하기 위한 SSR-only client.\n * Bearer (`rtlk_cust_*`) 인증, 브라우저 직접 호출 금지 (ADR-0023 §5.1 #15).\n *\n * 사용 예 (Next.js server component):\n * ```ts\n * import { fetchPosts } from \"@roottale/cms-client/server\";\n *\n * const posts = await fetchPosts({\n *   apiKey: process.env.ROOTTALE_API_KEY!,\n *   limit: 10,\n * });\n * ```\n *\n * 데이터 모델 = ADR-0034 `posts` (WP 7.0-aligned, type=post|page).\n * Phase 1 scope: list + get. WP import/export, draft preview = 별도 PR.\n */\n\nexport type CmsPostType = \"post\" | \"page\";\n\nexport type CmsTaxonomyKind = \"category\" | \"tag\" | \"custom\";\n\nexport interface CmsTermRef {\n  id: string;\n  taxonomy: CmsTaxonomyKind;\n  slug: string;\n  name: string;\n}\n\nexport interface CmsPostContent {\n  /** UUIDv7. */\n  id: string;\n  /** Owning tenant id. */\n  tenantId: string;\n  /** Owning site id (ADR-0034 P4 dual-key). */\n  siteId: string;\n  /** WP post type. */\n  type: CmsPostType;\n  /** Lowercase kebab-case slug (1-120 chars). */\n  slug: string;\n  title: string;\n  excerpt: string | null;\n  /** Media id (resolved by renderer / consumer to URL). */\n  featuredMediaId: string | null;\n  authorId: string | null;\n  /** Public display name for the post author. Email is not exposed. */\n  authorName: string | null;\n  /** Tiptap / Gutenberg-compatible Block JSON. Sanitization is renderer's responsibility. */\n  bodyJson: Record<string, unknown>;\n  /** Public API only exposes `published`. */\n  status: \"published\";\n  /** Per-post meta (SEO overrides, canonical, og, ...). */\n  metaJson: Record<string, unknown>;\n  /**\n   * Attached taxonomy terms (categories + tags + custom). Server 가 category →\n   * tag → custom 순서로 정렬해 보내며, 각 taxonomy 내부는 name asc. attach 가 0 개면\n   * 빈 배열. category 만 추출하려면 `terms.filter(t => t.taxonomy === \"category\")`.\n   */\n  terms: CmsTermRef[];\n  /** ISO 8601. */\n  publishedAt: string;\n  /** ISO 8601. */\n  createdAt: string;\n  /** ISO 8601. */\n  updatedAt: string;\n}\n\nexport interface CmsPostContentPage {\n  items: CmsPostContent[];\n  nextCursor: string | null;\n  hasMore: boolean;\n}\n\nconst DEFAULT_BASE_URL = \"https://api.roottale.com\";\n\nexport interface FetchPostsOptions {\n  /** `rtlk_cust_*` API key. Required. */\n  apiKey: string;\n  /** Override the API base URL. Defaults to `https://api.roottale.com`. */\n  baseUrl?: string;\n  /** Page size, 1-100, default 20. */\n  limit?: number;\n  /** Opaque pagination cursor returned from previous call. */\n  cursor?: string;\n  /** Filter by post type (`post` or `page`). Default = both. */\n  type?: CmsPostType;\n  /** Override the auto-resolved site id (Phase 1 = 1 site/tenant, usually omitted). */\n  siteId?: string;\n  /** Optional AbortSignal. */\n  signal?: AbortSignal;\n}\n\nexport interface FetchPostOptions {\n  apiKey: string;\n  baseUrl?: string;\n  /** Slug (kebab-case) or UUIDv7 id. */\n  slugOrId: string;\n  /** Override the auto-resolved site id. */\n  siteId?: string;\n  signal?: AbortSignal;\n}\n\n/**\n * 외부 사이트가 cms-renderer 에 주입할 RootTale 디자인 토큰.\n * admin /design (mysite.roottale.com) 에서 저장한 값과 동일한 shape.\n * 미설정 필드는 응답에서 누락 → renderer 의 CSS fallback 이 사용된다.\n */\nexport interface RootTaleTheme {\n  colors?: {\n    primary?: string;\n    primaryForeground?: string;\n    foreground?: string;\n    background?: string;\n    muted?: string;\n    mutedForeground?: string;\n    border?: string;\n  };\n  fonts?: {\n    body?: string;\n    display?: string;\n  };\n  radius?: {\n    md?: string;\n  };\n}\n\nexport interface FetchThemeOptions {\n  apiKey: string;\n  baseUrl?: string;\n  siteId?: string;\n  signal?: AbortSignal;\n}\n\n/**\n * tenant 의 RootTale 디자인 토큰을 가져온다. admin /design 의 마지막 저장값\n * (없으면 빈 객체) — renderer 가 이 값을 CSS 변수로 주입한다.\n *\n * 자동 fetch (renderer 가 theme prop 없을 때) 와 명시 호출 모두 지원.\n * 네트워크/서버 에러는 throw — 호출자가 fallback 처리.\n */\nexport async function fetchTheme(options: FetchThemeOptions): Promise<RootTaleTheme> {\n  assertServer();\n  const baseUrl = (options.baseUrl ?? DEFAULT_BASE_URL).replace(/\\/+$/, \"\");\n  const params = new URLSearchParams();\n  if (options.siteId) params.set(\"site_id\", options.siteId);\n  const qs = params.toString();\n  const url = `${baseUrl}/v1/cms/public/theme${qs ? `?${qs}` : \"\"}`;\n\n  const response = await fetch(url, {\n    method: \"GET\",\n    headers: { authorization: `Bearer ${options.apiKey}` },\n    signal: options.signal,\n  });\n\n  if (!response.ok) {\n    throw await toApiError(response);\n  }\n\n  const json = (await response.json()) as {\n    colors?: RootTaleTheme[\"colors\"];\n    fonts?: RootTaleTheme[\"fonts\"];\n    radius?: RootTaleTheme[\"radius\"];\n  };\n  const theme: RootTaleTheme = {};\n  if (json.colors) theme.colors = json.colors;\n  if (json.fonts) theme.fonts = json.fonts;\n  if (json.radius) theme.radius = json.radius;\n  return theme;\n}\n\nexport class CmsApiError extends Error {\n  readonly status: number;\n  readonly code: string;\n  constructor(message: string, status: number, code: string) {\n    super(message);\n    this.name = \"CmsApiError\";\n    this.status = status;\n    this.code = code;\n  }\n}\n\nexport async function fetchPosts(options: FetchPostsOptions): Promise<CmsPostContentPage> {\n  assertServer();\n  const baseUrl = (options.baseUrl ?? DEFAULT_BASE_URL).replace(/\\/+$/, \"\");\n  const params = new URLSearchParams();\n  if (options.limit !== undefined) params.set(\"limit\", String(options.limit));\n  if (options.cursor) params.set(\"cursor\", options.cursor);\n  if (options.type) params.set(\"type\", options.type);\n  if (options.siteId) params.set(\"site_id\", options.siteId);\n  const qs = params.toString();\n  const url = `${baseUrl}/v1/cms/public/posts${qs ? `?${qs}` : \"\"}`;\n\n  const response = await fetch(url, {\n    method: \"GET\",\n    headers: { authorization: `Bearer ${options.apiKey}` },\n    signal: options.signal,\n  });\n\n  if (!response.ok) {\n    throw await toApiError(response);\n  }\n\n  const json = (await response.json()) as {\n    items: CmsPostWire[];\n    has_more: boolean;\n    next_cursor: string | null;\n  };\n  return {\n    items: json.items.map(fromWire),\n    hasMore: json.has_more,\n    nextCursor: json.next_cursor,\n  };\n}\n\nexport async function fetchPost(options: FetchPostOptions): Promise<CmsPostContent | null> {\n  assertServer();\n  const baseUrl = (options.baseUrl ?? DEFAULT_BASE_URL).replace(/\\/+$/, \"\");\n  const params = new URLSearchParams();\n  if (options.siteId) params.set(\"site_id\", options.siteId);\n  const qs = params.toString();\n  const url = `${baseUrl}/v1/cms/public/posts/${encodeURIComponent(options.slugOrId)}${qs ? `?${qs}` : \"\"}`;\n\n  const response = await fetch(url, {\n    method: \"GET\",\n    headers: { authorization: `Bearer ${options.apiKey}` },\n    signal: options.signal,\n  });\n\n  if (response.status === 404) return null;\n  if (!response.ok) {\n    throw await toApiError(response);\n  }\n\n  const json = (await response.json()) as CmsPostWire;\n  return fromWire(json);\n}\n\ntype CmsPostWire = {\n  id: string;\n  tenant_id: string;\n  site_id: string;\n  type: CmsPostType;\n  slug: string;\n  title: string;\n  excerpt: string | null;\n  featured_media_id: string | null;\n  author_id: string | null;\n  author_name?: string | null;\n  body_json: Record<string, unknown>;\n  status: \"published\";\n  meta_json: Record<string, unknown>;\n  /** 0.2.0 이전 서버는 미포함 — backward-compat 차원에서 optional. */\n  terms?: CmsTermRef[];\n  published_at: string;\n  created_at: string;\n  updated_at: string;\n};\n\nfunction fromWire(wire: CmsPostWire): CmsPostContent {\n  return {\n    id: wire.id,\n    tenantId: wire.tenant_id,\n    siteId: wire.site_id,\n    type: wire.type,\n    slug: wire.slug,\n    title: wire.title,\n    excerpt: wire.excerpt,\n    featuredMediaId: wire.featured_media_id,\n    authorId: wire.author_id,\n    authorName: wire.author_name ?? null,\n    bodyJson: wire.body_json,\n    status: wire.status,\n    metaJson: wire.meta_json,\n    terms: wire.terms ?? [],\n    publishedAt: wire.published_at,\n    createdAt: wire.created_at,\n    updatedAt: wire.updated_at,\n  };\n}\n\nasync function toApiError(response: Response): Promise<CmsApiError> {\n  let code = \"request_failed\";\n  let message = `RootTale CMS API error: ${response.status}`;\n  try {\n    const body = (await response.json()) as { code?: string; message?: string };\n    if (body.code) code = body.code;\n    if (body.message) message = body.message;\n  } catch {\n    /* ignore body parse */\n  }\n  return new CmsApiError(message, response.status, code);\n}\n\nfunction assertServer(): void {\n  if (typeof window !== \"undefined\") {\n    throw new Error(\n      \"@roottale/cms-client/server must not run in the browser. \" +\n        \"Move this call to a Server Component, getServerSideProps, or a Route Handler. \" +\n        \"Shipping API keys to the browser breaks the security model (ADR-0023 §5.1 #15).\",\n    );\n  }\n}\n"],"mappings":"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","names":[]}
+{"version":3,"sources":["../src/server.ts"],"sourcesContent":["/**\n * `@roottale/cms-client/server` — RootTale CMS Public API server-side fetch client.\n *\n * 외부 고객사 사이트가 RootTale CMS 콘텐츠를 fetch 하기 위한 SSR-only client.\n * Bearer (`rtlk_cust_*`) 인증, 브라우저 직접 호출 금지 (ADR-0023 §5.1 #15).\n *\n * 사용 예 (Next.js server component):\n * ```ts\n * import { fetchPosts } from \"@roottale/cms-client/server\";\n *\n * const posts = await fetchPosts({\n *   apiKey: process.env.ROOTTALE_API_KEY!,\n *   limit: 10,\n * });\n * ```\n *\n * 데이터 모델 = ADR-0034 `posts` (WP 7.0-aligned, type=post|page).\n * Phase 1 scope: list + get. WP import/export, draft preview = 별도 PR.\n */\n\nexport type CmsPostType = \"post\" | \"page\";\n\nexport type CmsTaxonomyKind = \"category\" | \"tag\" | \"custom\";\n\nexport interface CmsTermRef {\n  id: string;\n  taxonomy: CmsTaxonomyKind;\n  slug: string;\n  name: string;\n}\n\nexport interface CmsPostContent {\n  /** UUIDv7. */\n  id: string;\n  /** Owning tenant id. */\n  tenantId: string;\n  /** Owning site id (ADR-0034 P4 dual-key). */\n  siteId: string;\n  /** WP post type. */\n  type: CmsPostType;\n  /** Lowercase kebab-case slug (1-120 chars). */\n  slug: string;\n  title: string;\n  excerpt: string | null;\n  /** Media id (resolved by renderer / consumer to URL). */\n  featuredMediaId: string | null;\n  authorId: string | null;\n  /** Public display name for the post author. Email is not exposed. */\n  authorName: string | null;\n  /** Tiptap / Gutenberg-compatible Block JSON. Sanitization is renderer's responsibility. */\n  bodyJson: Record<string, unknown>;\n  /** Public API only exposes `published`. */\n  status: \"published\";\n  /** Per-post meta (SEO overrides, canonical, og, ...). */\n  metaJson: Record<string, unknown>;\n  /**\n   * Attached taxonomy terms (categories + tags + custom). Server 가 category →\n   * tag → custom 순서로 정렬해 보내며, 각 taxonomy 내부는 name asc. attach 가 0 개면\n   * 빈 배열. category 만 추출하려면 `terms.filter(t => t.taxonomy === \"category\")`.\n   */\n  terms: CmsTermRef[];\n  /** ISO 8601. */\n  publishedAt: string;\n  /** ISO 8601. */\n  createdAt: string;\n  /** ISO 8601. */\n  updatedAt: string;\n}\n\nexport interface CmsPostContentPage {\n  items: CmsPostContent[];\n  nextCursor: string | null;\n  hasMore: boolean;\n}\n\nconst DEFAULT_BASE_URL = \"https://api.roottale.com\";\n\nexport interface FetchPostsOptions {\n  /** `rtlk_cust_*` API key. Required. */\n  apiKey: string;\n  /** Override the API base URL. Defaults to `https://api.roottale.com`. */\n  baseUrl?: string;\n  /** Page size, 1-100, default 20. */\n  limit?: number;\n  /** Opaque pagination cursor returned from previous call. */\n  cursor?: string;\n  /** Filter by post type (`post` or `page`). Default = both. */\n  type?: CmsPostType;\n  /** Override the auto-resolved site id (Phase 1 = 1 site/tenant, usually omitted). */\n  siteId?: string;\n  /** Optional AbortSignal. */\n  signal?: AbortSignal;\n}\n\nexport interface FetchPostOptions {\n  apiKey: string;\n  baseUrl?: string;\n  /** Slug (kebab-case) or UUIDv7 id. */\n  slugOrId: string;\n  /** Override the auto-resolved site id. */\n  siteId?: string;\n  signal?: AbortSignal;\n}\n\n/**\n * 외부 사이트가 cms-renderer 에 주입할 RootTale 디자인 토큰.\n * admin /design (mysite.roottale.com) 에서 저장한 값과 동일한 shape.\n * 미설정 필드는 응답에서 누락 → renderer 의 CSS fallback 이 사용된다.\n */\nexport interface RootTaleTheme {\n  colors?: {\n    primary?: string;\n    primaryForeground?: string;\n    foreground?: string;\n    background?: string;\n    muted?: string;\n    mutedForeground?: string;\n    border?: string;\n  };\n  fonts?: {\n    body?: string;\n    display?: string;\n  };\n  radius?: {\n    md?: string;\n  };\n}\n\nexport interface FetchThemeOptions {\n  apiKey: string;\n  baseUrl?: string;\n  siteId?: string;\n  signal?: AbortSignal;\n}\n\n/**\n * tenant 의 RootTale 디자인 토큰을 가져온다. admin /design 의 마지막 저장값\n * (없으면 빈 객체) — renderer 가 이 값을 CSS 변수로 주입한다.\n *\n * 자동 fetch (renderer 가 theme prop 없을 때) 와 명시 호출 모두 지원.\n * 네트워크/서버 에러는 throw — 호출자가 fallback 처리.\n */\nexport async function fetchTheme(options: FetchThemeOptions): Promise<RootTaleTheme> {\n  assertServer();\n  const baseUrl = (options.baseUrl ?? DEFAULT_BASE_URL).replace(/\\/+$/, \"\");\n  const params = new URLSearchParams();\n  if (options.siteId) params.set(\"site_id\", options.siteId);\n  const qs = params.toString();\n  const url = `${baseUrl}/v1/cms/public/theme${qs ? `?${qs}` : \"\"}`;\n\n  const response = await fetch(url, {\n    method: \"GET\",\n    headers: { authorization: `Bearer ${options.apiKey}` },\n    signal: options.signal,\n  });\n\n  if (!response.ok) {\n    throw await toApiError(response);\n  }\n\n  const json = (await response.json()) as {\n    colors?: RootTaleTheme[\"colors\"];\n    fonts?: RootTaleTheme[\"fonts\"];\n    radius?: RootTaleTheme[\"radius\"];\n  };\n  const theme: RootTaleTheme = {};\n  if (json.colors) theme.colors = json.colors;\n  if (json.fonts) theme.fonts = json.fonts;\n  if (json.radius) theme.radius = json.radius;\n  return theme;\n}\n\n/**\n * 블로그 표시 설정 — admin /design 의 \"블로그 표시\" 에서 저장한 사이트 기본값.\n * renderer 가 prop 미지정 시 이 값을 기본으로 적용 (글별 override 는 post 의\n * metaJson.display 가 우선).\n */\nexport interface RootTaleBlogSettings {\n  showTableOfContents: boolean;\n  showAuthor: boolean;\n  showDate: boolean;\n  /** 목차 상단 제목. null = renderer 기본(\"목차\"). */\n  tocTitle: string | null;\n}\n\nexport interface FetchBlogSettingsOptions {\n  apiKey: string;\n  baseUrl?: string;\n  siteId?: string;\n  signal?: AbortSignal;\n}\n\n/**\n * tenant 의 블로그 표시 기본값을 가져온다. 네트워크/서버 에러는 throw —\n * 호출자(renderer)가 안전 기본값으로 fallback.\n */\nexport async function fetchBlogSettings(\n  options: FetchBlogSettingsOptions,\n): Promise<RootTaleBlogSettings> {\n  assertServer();\n  const baseUrl = (options.baseUrl ?? DEFAULT_BASE_URL).replace(/\\/+$/, \"\");\n  const params = new URLSearchParams();\n  if (options.siteId) params.set(\"site_id\", options.siteId);\n  const qs = params.toString();\n  const url = `${baseUrl}/v1/cms/public/blog-settings${qs ? `?${qs}` : \"\"}`;\n\n  const response = await fetch(url, {\n    method: \"GET\",\n    headers: { authorization: `Bearer ${options.apiKey}` },\n    signal: options.signal,\n  });\n\n  if (!response.ok) {\n    throw await toApiError(response);\n  }\n\n  const json = (await response.json()) as {\n    show_table_of_contents?: boolean;\n    show_author?: boolean;\n    show_date?: boolean;\n    toc_title?: string | null;\n  };\n  return {\n    showTableOfContents: json.show_table_of_contents === true,\n    showAuthor: json.show_author !== false,\n    showDate: json.show_date !== false,\n    tocTitle:\n      typeof json.toc_title === \"string\" && json.toc_title.length > 0\n        ? json.toc_title\n        : null,\n  };\n}\n\n/** fetch 실패/미설정 시 사용할 안전 기본값 (기존 렌더러 동작). */\nexport const DEFAULT_BLOG_SETTINGS: RootTaleBlogSettings = {\n  showTableOfContents: false,\n  showAuthor: true,\n  showDate: true,\n  tocTitle: null,\n};\n\nexport interface ResolvedPostDisplay {\n  showTableOfContents: boolean;\n  showAuthor: boolean;\n  showDate: boolean;\n  tocTitle: string;\n}\n\n/**\n * 글 1건의 실제 표시 여부 결정. 우선순위:\n *   명시 prop > 글별 override(post.metaJson.display) > 사이트 기본값(settings).\n * tocTitle: 명시 prop > settings.tocTitle > \"목차\".\n */\nexport function resolvePostDisplay(\n  post: { metaJson?: Record<string, unknown> | null },\n  settings: RootTaleBlogSettings,\n  explicit?: { showTableOfContents?: boolean; tableOfContentsTitle?: string },\n): ResolvedPostDisplay {\n  const display =\n    post.metaJson && typeof post.metaJson === \"object\"\n      ? ((post.metaJson as Record<string, unknown>).display as\n          | Record<string, unknown>\n          | undefined)\n      : undefined;\n  const ov = (key: string): boolean | undefined =>\n    display && typeof display[key] === \"boolean\"\n      ? (display[key] as boolean)\n      : undefined;\n  return {\n    showTableOfContents:\n      explicit?.showTableOfContents ?? ov(\"toc\") ?? settings.showTableOfContents,\n    showAuthor: ov(\"author\") ?? settings.showAuthor,\n    showDate: ov(\"date\") ?? settings.showDate,\n    tocTitle: explicit?.tableOfContentsTitle ?? settings.tocTitle ?? \"목차\",\n  };\n}\n\nexport class CmsApiError extends Error {\n  readonly status: number;\n  readonly code: string;\n  constructor(message: string, status: number, code: string) {\n    super(message);\n    this.name = \"CmsApiError\";\n    this.status = status;\n    this.code = code;\n  }\n}\n\nexport async function fetchPosts(options: FetchPostsOptions): Promise<CmsPostContentPage> {\n  assertServer();\n  const baseUrl = (options.baseUrl ?? DEFAULT_BASE_URL).replace(/\\/+$/, \"\");\n  const params = new URLSearchParams();\n  if (options.limit !== undefined) params.set(\"limit\", String(options.limit));\n  if (options.cursor) params.set(\"cursor\", options.cursor);\n  if (options.type) params.set(\"type\", options.type);\n  if (options.siteId) params.set(\"site_id\", options.siteId);\n  const qs = params.toString();\n  const url = `${baseUrl}/v1/cms/public/posts${qs ? `?${qs}` : \"\"}`;\n\n  const response = await fetch(url, {\n    method: \"GET\",\n    headers: { authorization: `Bearer ${options.apiKey}` },\n    signal: options.signal,\n  });\n\n  if (!response.ok) {\n    throw await toApiError(response);\n  }\n\n  const json = (await response.json()) as {\n    items: CmsPostWire[];\n    has_more: boolean;\n    next_cursor: string | null;\n  };\n  return {\n    items: json.items.map(fromWire),\n    hasMore: json.has_more,\n    nextCursor: json.next_cursor,\n  };\n}\n\nexport async function fetchPost(options: FetchPostOptions): Promise<CmsPostContent | null> {\n  assertServer();\n  const baseUrl = (options.baseUrl ?? DEFAULT_BASE_URL).replace(/\\/+$/, \"\");\n  const params = new URLSearchParams();\n  if (options.siteId) params.set(\"site_id\", options.siteId);\n  const qs = params.toString();\n  const url = `${baseUrl}/v1/cms/public/posts/${encodeURIComponent(options.slugOrId)}${qs ? `?${qs}` : \"\"}`;\n\n  const response = await fetch(url, {\n    method: \"GET\",\n    headers: { authorization: `Bearer ${options.apiKey}` },\n    signal: options.signal,\n  });\n\n  if (response.status === 404) return null;\n  if (!response.ok) {\n    throw await toApiError(response);\n  }\n\n  const json = (await response.json()) as CmsPostWire;\n  return fromWire(json);\n}\n\ntype CmsPostWire = {\n  id: string;\n  tenant_id: string;\n  site_id: string;\n  type: CmsPostType;\n  slug: string;\n  title: string;\n  excerpt: string | null;\n  featured_media_id: string | null;\n  author_id: string | null;\n  author_name?: string | null;\n  body_json: Record<string, unknown>;\n  status: \"published\";\n  meta_json: Record<string, unknown>;\n  /** 0.2.0 이전 서버는 미포함 — backward-compat 차원에서 optional. */\n  terms?: CmsTermRef[];\n  published_at: string;\n  created_at: string;\n  updated_at: string;\n};\n\nfunction fromWire(wire: CmsPostWire): CmsPostContent {\n  return {\n    id: wire.id,\n    tenantId: wire.tenant_id,\n    siteId: wire.site_id,\n    type: wire.type,\n    slug: wire.slug,\n    title: wire.title,\n    excerpt: wire.excerpt,\n    featuredMediaId: wire.featured_media_id,\n    authorId: wire.author_id,\n    authorName: wire.author_name ?? null,\n    bodyJson: wire.body_json,\n    status: wire.status,\n    metaJson: wire.meta_json,\n    terms: wire.terms ?? [],\n    publishedAt: wire.published_at,\n    createdAt: wire.created_at,\n    updatedAt: wire.updated_at,\n  };\n}\n\nasync function toApiError(response: Response): Promise<CmsApiError> {\n  let code = \"request_failed\";\n  let message = `RootTale CMS API error: ${response.status}`;\n  try {\n    const body = (await response.json()) as { code?: string; message?: string };\n    if (body.code) code = body.code;\n    if (body.message) message = body.message;\n  } catch {\n    /* ignore body parse */\n  }\n  return new CmsApiError(message, response.status, code);\n}\n\nfunction assertServer(): void {\n  if (typeof window !== \"undefined\") {\n    throw new Error(\n      \"@roottale/cms-client/server must not run in the browser. \" +\n        \"Move this call to a Server Component, getServerSideProps, or a Route Handler. \" +\n        \"Shipping API keys to the browser breaks the security model (ADR-0023 §5.1 #15).\",\n    );\n  }\n}\n"],"mappings":"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","names":[]}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@roottale/cms-client",
-  "version": "0.7.0",
+  "version": "0.8.0",
   "type": "module",
   "description": "RootTale CMS Public API server-side fetch client (Bearer rtlk_cust_* auth). SSR-only — refuses to run in the browser to prevent key leak (ADR-0023 §5.1 #15). Pairs with @roottale/cms-renderer-next / @roottale/cms-renderer-astro.",
   "main": "./dist/server.js",