@spfn/cms 0.1.0-alpha.64 → 0.1.0-alpha.65

package/README.md

@@ -16,7 +16,7 @@ Content Management System for Next.js with JSON-based labels and automatic datab
 
 ## Installation
 
-### Recommended: Using SPFN CLI (Automatic Database Setup)
+### Recommended: Using Superfunction CLI (Automatic Database Setup)
 
 ```bash
 pnpm spfn add @spfn/cms
@@ -59,7 +59,7 @@ pnpm spfn db migrate   # Apply migrations
 Create JSON files organized by sections and categories:
 
 ```
-src/cms/labels/
+src/lib/labels/
   layout/              ← Section name
     nav.json           ← Category
     footer.json
@@ -68,7 +68,7 @@ src/cms/labels/
     features.json
 ```
 
-**Example:** `src/cms/labels/layout/nav.json`
+**Example:** `src/lib/labels/layout/nav.json`
 
 ```json
 {
@@ -89,7 +89,7 @@ src/cms/labels/
 }
 ```
 
-**Multi-language example:** `src/cms/labels/home/hero.json`
+**Multi-language example:** `src/lib/labels/home/hero.json`
 
 ```json
 {
@@ -110,7 +110,7 @@ src/cms/labels/
 }
 ```
 
-**Variable substitution:** `src/cms/labels/layout/footer.json`
+**Variable substitution:** `src/lib/labels/layout/footer.json`
 
 ```json
 {
@@ -127,13 +127,14 @@ Configure `src/server/server.config.ts`:
 
 ```typescript
 import type { ServerConfig } from '@spfn/core/server';
-import { initLabelSync } from '@spfn/cms';
+import { initLabelSync } from '@spfn/cms/server';
+import { DEFAULT_LABELS_DIR } from '@spfn/cms';
 
 export default {
   beforeRoutes: async (app) => {
     await initLabelSync({
       verbose: true,
-      labelsDir: 'src/cms/labels'  // Optional, this is the default
+      // labelsDir: DEFAULT_LABELS_DIR  // Optional, this is the default
     });
   },
 } satisfies ServerConfig;
@@ -205,7 +206,7 @@ export default function Nav() {
 ## File Structure
 
 ```
-src/cms/labels/
+src/lib/labels/
   layout/                  # Section: layout
     nav.json               # Category: nav
     footer.json            # Category: footer
@@ -221,7 +222,7 @@ src/cms/labels/
 
 Example:
 ```
-src/cms/labels/layout/nav.json:
+src/lib/labels/layout/nav.json:
   key: "layout.nav.team" → t('nav.team') in code
 ```
 
@@ -279,6 +280,18 @@ t('greeting', undefined, { name: 'John' })
 
 ## Configuration
 
+### Default Paths
+
+The default label directory path is defined as a constant:
+
+```typescript
+import { DEFAULT_LABELS_DIR } from '@spfn/cms';
+
+console.log(DEFAULT_LABELS_DIR); // 'src/lib/labels'
+```
+
+This constant is used throughout the CMS package and can be referenced in your code to avoid hardcoding paths.
+
 ### Environment Variables
 
 Configure CMS behavior via environment variables in `.env.local`:
@@ -344,7 +357,7 @@ export default async function RootLayout({ children }) {
 ```typescript
 // Client Component
 'use client';
-import { getLocale } from '@spfn/cms/actions';
+import { getLocale } from '@spfn/cms/client';
 import { useEffect, useState } from 'react';
 
 export default function LanguageSwitcher() {
@@ -399,7 +412,7 @@ const { t: tEn } = await getSection('home', 'en');
 ## Architecture
 
 ```
-JSON Files (src/cms/labels/**/*.json)
+JSON Files (src/lib/labels/**/*.json)
               ↓
       loadLabelsFromJson()
               ↓
@@ -425,49 +438,73 @@ JSON Files (src/cms/labels/**/*.json)
 
 ## API Reference
 
-### Server-side API
+### Common API (`@spfn/cms`)
 
+**Configuration:**
+- `getCmsConfig()` - Get current CMS configuration
+- `configureCms(config)` - Update configuration (runtime)
+- `resetCmsConfig()` - Reset configuration to defaults
+
+**Constants:**
+- `DEFAULT_LABELS_DIR` - Default label directory path (`'src/lib/labels'`)
+- `LOCALE_COOKIE_KEY` - Locale cookie key constant
+- Locale helpers: `getLocaleInfo()`, `getSupportedLocales()`, `getFlag()`, `getDialCode()`, `isRTL()`
+
+**Types:**
+- `SectionData`, `SectionAPI`, `CmsConfig`, `LocaleInfo`, `SupportedLocale`
+
+### Server-side API (`@spfn/cms/server`)
+
+**Server Components:**
 - `getSection(section, locale?)` - Get section labels (auto-detects locale if not specified)
 - `getSections(sections, locale?)` - Get multiple sections (auto-detects locale if not specified)
+
+**Backend/Sync:**
 - `initLabelSync(options?)` - Sync labels on server startup
+- `syncAll(sections, options?)` - Sync all sections
+- `syncSection(definition, options?)` - Sync specific section
+- `loadLabelsFromJson(labelsDir)` - Load labels from JSON files
 
-### Server Actions API (`@spfn/cms/actions`)
+**Repositories & Entities:**
+- All repository and entity exports
 
-Available for both server and client components:
+**Codegen:**
+- `createLabelSyncGenerator(config?)` - Generator factory
+- `LabelSyncGenerator` - Generator class
 
+**Locale (Server Actions):**
 - `getLocale()` - Get current locale (cookie → browser → default)
 - `setLocale(locale)` - Set locale (saves to cookie)
 - `getLocales()` - Get supported locale list
-- `LOCALE_COOKIE_KEY` - Locale cookie key constant
+- `getLocaleWithInfo()`, `getLocalesWithInfo()`, `isValidLocale()`
 
-### Configuration API
+### Server Actions API (`@spfn/cms/actions`)
 
-- `getCmsConfig()` - Get current CMS configuration
-- `configureCms(config)` - Update configuration (runtime)
-- `resetCmsConfig()` - Reset configuration to defaults
+*Alias for `@spfn/cms/server` locale functions - available for both server and client components*
 
 ### Client-side API (`@spfn/cms/client`)
 
 - `useSection(section, options?)` - Section labels hook
 - `useSections(sections)` - Multiple sections hook
 - `useCmsStore()` - CMS store hook
-- `cmsApi` - CMS API client
 - `InitCms` - Client initialization component
 
-### Sync API
-
-- `loadLabelsFromJson(labelsDir)` - Load labels from JSON files
-- `syncAll(sections, options?)` - Sync all sections
-- `syncSection(definition, options?)` - Sync specific section
+### Management API (`@spfn/cms/api`)
 
-### Codegen Integration
+⚠️ **Admin only** - Use with proper authentication
 
-- `createLabelSyncGenerator(config?)` - Generator factory
-- `LabelSyncGenerator` - Generator class
+- `cmsApi.cmsLabels.get(options?)` - List labels with filters
+- `cmsApi.cmsLabels.getById(options)` - Get label by ID
+- `cmsApi.cmsLabels.post(options)` - Create new label
+- `cmsApi.cmsLabels.update(options)` - Update label
+- `cmsApi.cmsLabels.delete(options)` - Delete label
+- `cmsApi.cmsLabelsByKey` - Get labels by key
+- `cmsApi.cmsValues` - Manage label values
+- `cmsApi.cmsPublishedCache.get(options)` - Get published cache
 
 ## Development Workflow
 
-1. **Create/Edit JSON files** in `src/cms/labels/`
+1. **Create/Edit JSON files** in `src/lib/labels/`
 2. **Auto-sync happens** (if dev server is running)
 3. **Labels immediately available** via `getSection()` or `useSection()`
 
@@ -478,7 +515,7 @@ Available for both server and client components:
 pnpm dev
 
 # Terminal 2: Edit label file
-echo '{"test": {"key": "layout.test", "defaultValue": "Test"}}' > src/cms/labels/layout/test.json
+echo '{"test": {"key": "layout.test", "defaultValue": "Test"}}' > src/lib/labels/layout/test.json
 
 # Auto-sync triggers
 # ✅ Label sync completed

package/dist/actions-CwvmPG0e.d.ts

@@ -0,0 +1,296 @@
+/**
+ * Locale Constants
+ *
+ * Server/Client 양쪽에서 사용 가능한 locale 관련 상수
+ */
+/**
+ * Locale 쿠키 키
+ */
+declare const LOCALE_COOKIE_KEY = "spfn-locale";
+/**
+ * 지원하는 Locale 타입 (Type-safe)
+ */
+type SupportedLocale = 'ko' | 'ja' | 'zh' | 'zh-TW' | 'zh-HK' | 'hi' | 'th' | 'vi' | 'id' | 'ms' | 'en' | 'en-GB' | 'en-CA' | 'en-AU' | 'en-NZ' | 'es' | 'es-MX' | 'es-AR' | 'es-CO' | 'fr' | 'de' | 'it' | 'pt' | 'nl' | 'sv' | 'no' | 'da' | 'fi' | 'ru' | 'pl' | 'uk' | 'cs' | 'hu' | 'ro' | 'bg' | 'hr' | 'sr' | 'sk' | 'sl' | 'lt' | 'lv' | 'et' | 'el' | 'tr' | 'ar' | 'fa' | 'he' | 'sw';
+/**
+ * 국가/지역 정보 타입
+ */
+interface LocaleInfo {
+    /** Locale 코드 (ISO 639-1) */
+    locale: SupportedLocale;
+    /** 국가 코드 (ISO 3166-1 alpha-2) */
+    countryCode: string;
+    /** 국기 이모지 (HTML/React용) */
+    flag: string;
+    /** 전화번호 국가 코드 */
+    dialCode: string;
+    /** 네이티브 이름 (현지어) */
+    nativeName: string;
+    /** 영어 이름 */
+    englishName: string;
+    /** RTL (Right-to-Left) 여부 */
+    rtl?: boolean;
+    /** 통화 코드 (ISO 4217) */
+    currencyCode?: string;
+    /** 날짜 형식 예시 */
+    dateFormat?: string;
+}
+/**
+ * 사전 정의된 Locale 정보 맵
+ *
+ * 주요 언어/국가 정보를 포함합니다.
+ * 프로젝트에 맞게 추가/수정 가능합니다.
+ */
+declare const LOCALE_INFO_MAP: Record<SupportedLocale, LocaleInfo>;
+/**
+ * Locale 정보 가져오기
+ *
+ * @param locale - Locale 코드 (예: 'ko', 'en', 'ja')
+ * @returns LocaleInfo 또는 undefined
+ *
+ * @example
+ * ```typescript
+ * const koInfo = getLocaleInfo('ko');
+ * console.log(koInfo.flag); // 🇰🇷
+ * console.log(koInfo.dialCode); // +82
+ * ```
+ */
+declare function getLocaleInfo(locale: string): LocaleInfo | undefined;
+/**
+ * 지원하는 모든 Locale 목록 가져오기
+ *
+ * @returns Locale 코드 배열
+ */
+declare function getSupportedLocales(): SupportedLocale[];
+/**
+ * 국기 이모지만 가져오기
+ *
+ * @param locale - Locale 코드
+ * @returns 국기 이모지 또는 빈 문자열
+ *
+ * @example
+ * ```typescript
+ * getFlag('ko'); // 🇰🇷
+ * getFlag('en'); // 🇺🇸
+ * ```
+ */
+declare function getFlag(locale: string): string;
+/**
+ * 전화번호 국가 코드 가져오기
+ *
+ * @param locale - Locale 코드
+ * @returns 전화번호 코드 또는 빈 문자열
+ *
+ * @example
+ * ```typescript
+ * getDialCode('ko'); // +82
+ * getDialCode('en'); // +1
+ * ```
+ */
+declare function getDialCode(locale: string): string;
+/**
+ * RTL (Right-to-Left) 여부 확인
+ *
+ * @param locale - Locale 코드
+ * @returns RTL 여부
+ *
+ * @example
+ * ```typescript
+ * isRTL('ar'); // true (Arabic)
+ * isRTL('ko'); // false (Korean)
+ * ```
+ */
+declare function isRTL(locale: string): boolean;
+
+/**
+ * 현재 locale 가져오기 (Server Action)
+ *
+ * 서버/클라이언트 컴포넌트 모두에서 사용 가능
+ *
+ * 우선순위:
+ * 1. 쿠키 (사용자가 명시적으로 선택한 언어)
+ * 2. 브라우저 언어 감지 (설정에서 활성화된 경우)
+ * 3. 시스템 기본 언어 (CMS 설정)
+ *
+ * @returns 현재 locale (예: 'ko', 'en')
+ *
+ * @example
+ * ```tsx
+ * // Server Component
+ * import { getLocale } from '@spfn/cms/actions';
+ *
+ * export default async function Page()
+ * {
+ *     const locale = await getLocale();
+ *     return <div>Current locale: {locale}</div>;
+ * }
+ * ```
+ *
+ * @example
+ * ```tsx
+ * // Client Component
+ * 'use client';
+ * import { getLocale } from '@spfn/cms/client';
+ *
+ * export default function LanguageSwitcher()
+ * {
+ *     const [locale, setLocale] = useState('');
+ *
+ *     useEffect(() => {
+ *         getLocale().then(setLocale);
+ *     }, []);
+ *
+ *     return <div>Current locale: {locale}</div>;
+ * }
+ * ```
+ */
+declare function getLocale(): Promise<string>;
+/**
+ * Locale 설정하기 (Server Action)
+ *
+ * 서버/클라이언트 컴포넌트 모두에서 사용 가능
+ * 쿠키에 locale을 저장합니다.
+ *
+ * @param locale - 설정할 locale (예: 'ko', 'en')
+ * @throws {Error} 지원하지 않는 locale인 경우
+ *
+ * @example
+ * ```tsx
+ * // Server Component (Server Action)
+ * import { setLocale } from '@spfn/cms/actions';
+ *
+ * export default async function Page()
+ * {
+ *     await setLocale('en');
+ *     return <div>Locale changed</div>;
+ * }
+ * ```
+ *
+ * @example
+ * ```tsx
+ * // Client Component (Server Action)
+ * 'use client';
+ * import { setLocale } from '@spfn/cms/client';
+ *
+ * export default function LanguageSwitcher()
+ * {
+ *     const handleChange = async (newLocale: string) =>
+ *     {
+ *         await setLocale(newLocale);
+ *         window.location.reload(); // 페이지 새로고침
+ *     };
+ *
+ *     return (
+ *         <button onClick={() => handleChange('en')}>
+ *             Switch to English
+ *         </button>
+ *     );
+ * }
+ * ```
+ */
+declare function setLocale(locale: string): Promise<void>;
+/**
+ * 지원하는 locale 목록 가져오기 (Server Action)
+ *
+ * 서버/클라이언트 컴포넌트 모두에서 사용 가능
+ *
+ * @returns 지원하는 locale 배열 (예: ['ko', 'en', 'ja'])
+ *
+ * @example
+ * ```tsx
+ * // Server Component
+ * import { getLocales } from '@spfn/cms/actions';
+ *
+ * export default async function Page()
+ * {
+ *     const locales = await getLocales();
+ *     return <div>Supported: {locales.join(', ')}</div>;
+ * }
+ * ```
+ *
+ * @example
+ * ```tsx
+ * // Client Component
+ * 'use client';
+ * import { getLocales } from '@spfn/cms/client';
+ *
+ * export default function LanguageSwitcher()
+ * {
+ *     const [locales, setLocales] = useState<string[]>([]);
+ *
+ *     useEffect(() => {
+ *         getLocales().then(setLocales);
+ *     }, []);
+ *
+ *     return (
+ *         <div>
+ *             {locales.map(locale => (
+ *                 <button key={locale}>{locale}</button>
+ *             ))}
+ *         </div>
+ *     );
+ * }
+ * ```
+ */
+declare function getLocales(): Promise<string[]>;
+/**
+ * 현재 locale과 상세 정보 함께 가져오기 (Server Action)
+ *
+ * locale 코드와 함께 국가 코드, 국기, 전화번호 코드 등의 상세 정보를 반환합니다.
+ *
+ * @returns Locale 코드와 LocaleInfo 객체
+ *
+ * @example
+ * ```tsx
+ * // Server Component
+ * import { getLocaleWithInfo } from '@spfn/cms/actions';
+ *
+ * export default async function Page()
+ * {
+ *     const { locale, info } = await getLocaleWithInfo();
+ *
+ *     return (
+ *         <div>
+ *             <span>{info?.flag}</span>
+ *             <span>{info?.nativeName}</span>
+ *             <span>{info?.dialCode}</span>
+ *         </div>
+ *     );
+ * }
+ * ```
+ */
+declare function getLocaleWithInfo(): Promise<{
+    locale: string;
+    info: LocaleInfo | undefined;
+}>;
+/**
+ * 지원하는 모든 locale과 상세 정보 가져오기 (Server Action)
+ *
+ * 시스템이 지원하는 모든 locale의 상세 정보를 배열로 반환합니다.
+ * 언어 선택 UI를 만들 때 유용합니다.
+ *
+ * @returns LocaleInfo 배열
+ *
+ * @example
+ * ```tsx
+ * // Server Component
+ * import { getLocalesWithInfo } from '@spfn/cms/actions';
+ *
+ * export default async function LanguageSelector()
+ * {
+ *     const locales = await getLocalesWithInfo();
+ *
+ *     return (
+ *         <select>
+ *             {locales.map(info => (
+ *                 <option key={info.locale} value={info.locale}>
+ *                     {info.flag} {info.nativeName}
+ *                 </option>
+ *             ))}
+ *         </select>
+ *     );
+ * }
+ * ```
+ */
+declare function getLocalesWithInfo(): Promise<LocaleInfo[]>;
+
+export { LOCALE_COOKIE_KEY as L, type SupportedLocale as S, getSupportedLocales as a, getFlag as b, getDialCode as c, LOCALE_INFO_MAP as d, type LocaleInfo as e, getLocale as f, getLocaleInfo as g, getLocales as h, isRTL as i, getLocaleWithInfo as j, getLocalesWithInfo as k, setLocale as s };

package/dist/actions.d.ts

@@ -1,143 +1 @@
-/**
- * 현재 locale 가져오기 (Server Action)
- *
- * 서버/클라이언트 컴포넌트 모두에서 사용 가능
- *
- * 우선순위:
- * 1. 쿠키 (사용자가 명시적으로 선택한 언어)
- * 2. 브라우저 언어 감지 (설정에서 활성화된 경우)
- * 3. 시스템 기본 언어 (CMS 설정)
- *
- * @returns 현재 locale (예: 'ko', 'en')
- *
- * @example
- * ```tsx
- * // Server Component
- * import { getLocale } from '@spfn/cms';
- *
- * export default async function Page()
- * {
- *     const locale = await getLocale();
- *     return <div>Current locale: {locale}</div>;
- * }
- * ```
- *
- * @example
- * ```tsx
- * // Client Component
- * 'use client';
- * import { getLocale } from '@spfn/cms/client';
- *
- * export default function LanguageSwitcher()
- * {
- *     const [locale, setLocale] = useState('');
- *
- *     useEffect(() => {
- *         getLocale().then(setLocale);
- *     }, []);
- *
- *     return <div>Current locale: {locale}</div>;
- * }
- * ```
- */
-declare function getLocale(): Promise<string>;
-/**
- * Locale 설정하기 (Server Action)
- *
- * 서버/클라이언트 컴포넌트 모두에서 사용 가능
- * 쿠키에 locale을 저장합니다.
- *
- * @param locale - 설정할 locale (예: 'ko', 'en')
- * @throws {Error} 지원하지 않는 locale인 경우
- *
- * @example
- * ```tsx
- * // Server Component (Server Action)
- * import { setLocale } from '@spfn/cms';
- *
- * export default async function Page()
- * {
- *     await setLocale('en');
- *     return <div>Locale changed</div>;
- * }
- * ```
- *
- * @example
- * ```tsx
- * // Client Component (Server Action)
- * 'use client';
- * import { setLocale } from '@spfn/cms/client';
- *
- * export default function LanguageSwitcher()
- * {
- *     const handleChange = async (newLocale: string) =>
- *     {
- *         await setLocale(newLocale);
- *         window.location.reload(); // 페이지 새로고침
- *     };
- *
- *     return (
- *         <button onClick={() => handleChange('en')}>
- *             Switch to English
- *         </button>
- *     );
- * }
- * ```
- */
-declare function setLocale(locale: string): Promise<void>;
-/**
- * 지원하는 locale 목록 가져오기 (Server Action)
- *
- * 서버/클라이언트 컴포넌트 모두에서 사용 가능
- *
- * @returns 지원하는 locale 배열 (예: ['ko', 'en', 'ja'])
- *
- * @example
- * ```tsx
- * // Server Component
- * import { getLocales } from '@spfn/cms';
- *
- * export default async function Page()
- * {
- *     const locales = await getLocales();
- *     return <div>Supported: {locales.join(', ')}</div>;
- * }
- * ```
- *
- * @example
- * ```tsx
- * // Client Component
- * 'use client';
- * import { getLocales } from '@spfn/cms/client';
- *
- * export default function LanguageSwitcher()
- * {
- *     const [locales, setLocales] = useState<string[]>([]);
- *
- *     useEffect(() => {
- *         getLocales().then(setLocales);
- *     }, []);
- *
- *     return (
- *         <div>
- *             {locales.map(locale => (
- *                 <button key={locale}>{locale}</button>
- *             ))}
- *         </div>
- *     );
- * }
- * ```
- */
-declare function getLocales(): Promise<string[]>;
-
-/**
- * Locale Constants
- *
- * Server/Client 양쪽에서 사용 가능한 locale 관련 상수
- */
-/**
- * Locale 쿠키 키
- */
-declare const LOCALE_COOKIE_KEY = "spfn-locale";
-
-export { LOCALE_COOKIE_KEY, getLocale, getLocales, setLocale };
+export { L as LOCALE_COOKIE_KEY, f as getLocale, h as getLocales, s as setLocale } from './actions-CwvmPG0e.js';

package/dist/actions.js

@@ -1,7 +1,7 @@
-// src/helpers/locale.actions.ts
-import { cookies, headers } from "next/headers.js";
+// src/server/helpers/locale.actions.ts
+import { cookies, headers } from "next/headers";
 
-// src/cms.config.ts
+// src/server/config/cms.config.ts
 function getEnvVar(key, defaultValue) {
   return process.env[key] || defaultValue;
 }
@@ -29,10 +29,10 @@ function getCmsConfig() {
   return currentConfig;
 }
 
-// src/helpers/locale.constants.ts
+// src/lib/constants/locale.constants.ts
 var LOCALE_COOKIE_KEY = "spfn-locale";
 
-// src/helpers/locale.actions.ts
+// src/server/helpers/locale.actions.ts
 async function detectBrowserLanguage() {
   try {
     const headersList = await headers();