@roottale/cms-client 0.1.0

package/CHANGELOG.md

@@ -0,0 +1,21 @@
+# @roottale/cms-client
+
+## 0.1.0
+
+### Minor Changes
+
+- d1b5d35: cms-\* public renderer 패키지 npm public publish — Phase 1 dogfood.
+
+  ADR-0029 §0 amend (publish-only dormant) 는 design system 5 패키지 (tokens, ui-css, ui-react, ui-astro, ui-admin) 에 한정. cms-\* 는 별도 정책 — 실행 로직 + 5-20 외부 customer site 직접 의존 + schema 호환 + 보안 경계. Codex consult verdict (session `019e6703…`) 정합.
+
+  변경:
+  - 4 패키지 `private: true` 해제 + `publishConfig.access: "public"`
+  - `@roottale/cms-renderer-next` 에서 `@roottale/tokens/tokens.css` import 제거 — 모든 `--rt-*` 변수에 static fallback 으로 self-contained. tokens dormant 와 무관하게 동작.
+  - `RootTaleLeadForm` RSC 추가 — 외부 사이트 진단 폼 (`vertical`/`redirectUrl` props, medical 국외이전 동의 자동).
+  - README + repository / homepage / keywords 메타 정비
+  - `peerDependencies.react: ^19` 명시 (cms-renderer-next)
+  - `cms-renderer-astro` 도 동등 surface 유지를 위해 동시 publish
+
+  후속:
+  - ADR 신규 — cms-\* publish 정책 (별 PR)
+  - Astro 측 LeadForm 컴포넌트 (현재 `@roottale/ui-astro` 위치, `cms-renderer-astro` 로 이동 검토)

package/README.md

@@ -0,0 +1,85 @@
+# @roottale/cms-client
+
+RootTale CMS public API fetch client — **server-only**. Bearer auth (`rtlk_cust_*`), refuses to run in the browser.
+
+Companion of [`@roottale/cms-renderer-next`](https://www.npmjs.com/package/@roottale/cms-renderer-next) (React RSC) and [`@roottale/cms-renderer-astro`](https://www.npmjs.com/package/@roottale/cms-renderer-astro). Use this directly if you want raw data; use the renderer packages if you want HTML/React out.
+
+## Install
+
+```bash
+npm install @roottale/cms-client
+# or
+pnpm add @roottale/cms-client
+```
+
+Zero runtime dependencies. Uses global `fetch` (node ≥18.18).
+
+## Setup
+
+```bash
+# .env.local — SERVER ONLY, never NEXT_PUBLIC_*
+ROOTTALE_API_KEY=rtlk_cust_xxxxxxxxxxxxxxxxxx
+```
+
+## Usage
+
+```ts
+import { fetchPosts, fetchPost } from "@roottale/cms-client/server";
+
+// List published posts
+const page = await fetchPosts({
+  apiKey: process.env.ROOTTALE_API_KEY!,
+  limit: 10,
+  type: "post", // or "page"
+});
+//   page.items: CmsPostContent[]
+//   page.hasMore: boolean
+//   page.nextCursor: string | null
+
+// Get one post by slug or id
+const post = await fetchPost({
+  apiKey: process.env.ROOTTALE_API_KEY!,
+  slugOrId: "hello-world",
+});
+//   post: CmsPostContent | null  (null = 404)
+```
+
+`CmsPostContent.bodyJson` is Tiptap-compatible Block JSON. Render it with `@roottale/cms-renderer-next` or your own renderer.
+
+## Errors
+
+`CmsApiError` (thrown on non-2xx, except 404 which returns `null`):
+
+```ts
+import { CmsApiError } from "@roottale/cms-client/server";
+
+try {
+  await fetchPosts({ apiKey });
+} catch (err) {
+  if (err instanceof CmsApiError) {
+    err.status; // HTTP status (e.g. 401, 429)
+    err.code;   // API error code (e.g. "invalid_key", "rate_limited")
+    err.message;
+  }
+  throw err;
+}
+```
+
+## Security boundary
+
+`assertServer()` throws if you import this in the browser. Shipping `rtlk_cust_*` to the client breaks the security model (ADR-0023 §5.1 #15). Keep all calls inside Server Components, Route Handlers, `getServerSideProps`, or build-time scripts.
+
+## API base URL
+
+Defaults to `https://api.roottale.com`. Override via `baseUrl` option for staging/preview:
+
+```ts
+await fetchPosts({
+  apiKey,
+  baseUrl: process.env.ROOTTALE_API_BASE ?? "https://api.roottale.com",
+});
+```
+
+## License
+
+Proprietary (UNLICENSED). Issued under the RootTale customer contract.

package/package.json

@@ -0,0 +1,44 @@
+{
+  "name": "@roottale/cms-client",
+  "version": "0.1.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": "./src/server.ts",
+  "exports": {
+    "./server": "./src/server.ts",
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "src/",
+    "README.md",
+    "CHANGELOG.md"
+  ],
+  "dependencies": {},
+  "devDependencies": {
+    "@types/node": "^22.0.0",
+    "typescript": "^5.7.0",
+    "vitest": "^2.1.0"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "keywords": [
+    "roottale",
+    "cms",
+    "client",
+    "api",
+    "ssr"
+  ],
+  "license": "UNLICENSED",
+  "homepage": "https://github.com/RootTale/roottale-platform/tree/main/packages/cms-client",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/RootTale/roottale-platform.git",
+    "directory": "packages/cms-client"
+  },
+  "scripts": {
+    "build": "tsc --noEmit",
+    "type-check": "tsc --noEmit",
+    "test": "vitest run --passWithNoTests"
+  }
+}

package/src/server.ts

@@ -0,0 +1,214 @@
+/**
+ * `@roottale/cms-client/server` — RootTale CMS Public API server-side fetch client.
+ *
+ * 외부 고객사 사이트가 RootTale CMS 콘텐츠를 fetch 하기 위한 SSR-only client.
+ * Bearer (`rtlk_cust_*`) 인증, 브라우저 직접 호출 금지 (ADR-0023 §5.1 #15).
+ *
+ * 사용 예 (Next.js server component):
+ * ```ts
+ * import { fetchPosts } from "@roottale/cms-client/server";
+ *
+ * const posts = await fetchPosts({
+ *   apiKey: process.env.ROOTTALE_API_KEY!,
+ *   limit: 10,
+ * });
+ * ```
+ *
+ * 데이터 모델 = ADR-0034 `posts` (WP 7.0-aligned, type=post|page).
+ * Phase 1 scope: list + get. WP import/export, draft preview = 별도 PR.
+ */
+
+export type CmsPostType = "post" | "page";
+
+export interface CmsPostContent {
+  /** UUIDv7. */
+  id: string;
+  /** Owning tenant id. */
+  tenantId: string;
+  /** Owning site id (ADR-0034 P4 dual-key). */
+  siteId: string;
+  /** WP post type. */
+  type: CmsPostType;
+  /** Lowercase kebab-case slug (1-120 chars). */
+  slug: string;
+  title: string;
+  excerpt: string | null;
+  /** Media id (resolved by renderer / consumer to URL). */
+  featuredMediaId: string | null;
+  authorId: string | null;
+  /** Tiptap / Gutenberg-compatible Block JSON. Sanitization is renderer's responsibility. */
+  bodyJson: Record<string, unknown>;
+  /** Public API only exposes `published`. */
+  status: "published";
+  /** Per-post meta (SEO overrides, canonical, og, ...). */
+  metaJson: Record<string, unknown>;
+  /** ISO 8601. */
+  publishedAt: string;
+  /** ISO 8601. */
+  createdAt: string;
+  /** ISO 8601. */
+  updatedAt: string;
+}
+
+export interface CmsPostContentPage {
+  items: CmsPostContent[];
+  nextCursor: string | null;
+  hasMore: boolean;
+}
+
+const DEFAULT_BASE_URL = "https://api.roottale.com";
+
+export interface FetchPostsOptions {
+  /** `rtlk_cust_*` API key. Required. */
+  apiKey: string;
+  /** Override the API base URL. Defaults to `https://api.roottale.com`. */
+  baseUrl?: string;
+  /** Page size, 1-100, default 20. */
+  limit?: number;
+  /** Opaque pagination cursor returned from previous call. */
+  cursor?: string;
+  /** Filter by post type (`post` or `page`). Default = both. */
+  type?: CmsPostType;
+  /** Override the auto-resolved site id (Phase 1 = 1 site/tenant, usually omitted). */
+  siteId?: string;
+  /** Optional AbortSignal. */
+  signal?: AbortSignal;
+}
+
+export interface FetchPostOptions {
+  apiKey: string;
+  baseUrl?: string;
+  /** Slug (kebab-case) or UUIDv7 id. */
+  slugOrId: string;
+  /** Override the auto-resolved site id. */
+  siteId?: string;
+  signal?: AbortSignal;
+}
+
+export class CmsApiError extends Error {
+  readonly status: number;
+  readonly code: string;
+  constructor(message: string, status: number, code: string) {
+    super(message);
+    this.name = "CmsApiError";
+    this.status = status;
+    this.code = code;
+  }
+}
+
+export async function fetchPosts(options: FetchPostsOptions): Promise<CmsPostContentPage> {
+  assertServer();
+  const baseUrl = (options.baseUrl ?? DEFAULT_BASE_URL).replace(/\/+$/, "");
+  const params = new URLSearchParams();
+  if (options.limit !== undefined) params.set("limit", String(options.limit));
+  if (options.cursor) params.set("cursor", options.cursor);
+  if (options.type) params.set("type", options.type);
+  if (options.siteId) params.set("site_id", options.siteId);
+  const qs = params.toString();
+  const url = `${baseUrl}/v1/cms/public/posts${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()) as {
+    items: CmsPostWire[];
+    has_more: boolean;
+    next_cursor: string | null;
+  };
+  return {
+    items: json.items.map(fromWire),
+    hasMore: json.has_more,
+    nextCursor: json.next_cursor,
+  };
+}
+
+export async function fetchPost(options: FetchPostOptions): Promise<CmsPostContent | null> {
+  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/posts/${encodeURIComponent(options.slugOrId)}${qs ? `?${qs}` : ""}`;
+
+  const response = await fetch(url, {
+    method: "GET",
+    headers: { authorization: `Bearer ${options.apiKey}` },
+    signal: options.signal,
+  });
+
+  if (response.status === 404) return null;
+  if (!response.ok) {
+    throw await toApiError(response);
+  }
+
+  const json = (await response.json()) as CmsPostWire;
+  return fromWire(json);
+}
+
+type CmsPostWire = {
+  id: string;
+  tenant_id: string;
+  site_id: string;
+  type: CmsPostType;
+  slug: string;
+  title: string;
+  excerpt: string | null;
+  featured_media_id: string | null;
+  author_id: string | null;
+  body_json: Record<string, unknown>;
+  status: "published";
+  meta_json: Record<string, unknown>;
+  published_at: string;
+  created_at: string;
+  updated_at: string;
+};
+
+function fromWire(wire: CmsPostWire): CmsPostContent {
+  return {
+    id: wire.id,
+    tenantId: wire.tenant_id,
+    siteId: wire.site_id,
+    type: wire.type,
+    slug: wire.slug,
+    title: wire.title,
+    excerpt: wire.excerpt,
+    featuredMediaId: wire.featured_media_id,
+    authorId: wire.author_id,
+    bodyJson: wire.body_json,
+    status: wire.status,
+    metaJson: wire.meta_json,
+    publishedAt: wire.published_at,
+    createdAt: wire.created_at,
+    updatedAt: wire.updated_at,
+  };
+}
+
+async function toApiError(response: Response): Promise<CmsApiError> {
+  let code = "request_failed";
+  let message = `RootTale CMS API error: ${response.status}`;
+  try {
+    const body = (await response.json()) as { code?: string; message?: string };
+    if (body.code) code = body.code;
+    if (body.message) message = body.message;
+  } catch {
+    /* ignore body parse */
+  }
+  return new CmsApiError(message, response.status, code);
+}
+
+function assertServer(): void {
+  if (typeof window !== "undefined") {
+    throw new Error(
+      "@roottale/cms-client/server must not run in the browser. " +
+        "Move this call to a Server Component, getServerSideProps, or a Route Handler. " +
+        "Shipping API keys to the browser breaks the security model (ADR-0023 §5.1 #15).",
+    );
+  }
+}