@dani-builder/strapi-client 0.1.0 → 0.2.0

package/AGENTS.md

@@ -0,0 +1,117 @@
+# @dani-builder/strapi-client
+
+TypeScript client library for the Daniworks Builder CMS (Strapi v5). Provides typed API functions, populate builders, and media utilities for SSR-safe data fetching.
+
+## Import Paths
+
+```ts
+import { createStrapiClient, getPage, getMediaUrl } from '@dani-builder/strapi-client';       // everything
+import type { PageDocument, HeroBlock } from '@dani-builder/strapi-client/types';              // types only
+import { createStrapiClient, isStrapiError } from '@dani-builder/strapi-client/client';        // client factory
+import { getPagePopulate, coreBlockPopulates } from '@dani-builder/strapi-client/populate';    // populate builders
+import { getPage, listArticles, postInquiry } from '@dani-builder/strapi-client/api';          // API functions
+import { getMediaUrl, getAssetUrl } from '@dani-builder/strapi-client/utils';                  // media helpers
+```
+
+## Quick Start
+
+```ts
+const client = createStrapiClient({ baseUrl: 'http://localhost:1337', apiToken: '...' });
+const page = await getPage(client, documentId);              // Smart endpoint (server-side populate)
+const page2 = await getPageBySlug(client, 'about');          // REST with client-side populate
+const global = await getGlobal(client, { locale: 'ko' });   // Smart endpoint
+```
+
+## Key Concepts
+
+- **Smart vs REST** — Smart endpoints (`/api/builder/*`) use server-side populate via plugin. REST endpoints use client-side populate builders. Prefer Smart when available.
+- **Dynamic Zone discrimination** — Use `block.__component` to switch on block type (e.g. `'blocks.hero'`).
+- **Populate builders** — `getPagePopulate()`, `getGlobalPopulate()`, etc. build nested populate objects. Pass `customBlocks` to extend.
+- **Media URL resolution** — `getMediaUrl(url, mediaHost)` resolves relative paths. `getAssetUrl(asset, format, mediaHost)` gets a specific format with fallback.
+
+## Critical Rules
+
+1. **Variants are exact enum values** — DO NOT invent variant names. Only use values defined in the type (e.g. `'side-by-side' | 'media-extending' | 'fullscreen-media' | 'stacked-media'` for HeroBlock). See [Block Reference](./docs/block-reference.md).
+2. **Media policy varies by field** — Some fields accept images+videos, others images-only. Check the block's media policy before rendering `<video>`. See [Media Policy Summary](./docs/block-reference.md#media-policy-summary).
+3. **All media fields are nullable** — Always render defensively (`asset && <img ... />`). Even required media in sub-components may be null at the API level.
+4. **BlocksContent is structured JSON** — `Article.body`, `FAQ.answer`, and `ContentBlock.body` are `BlockNode[]` arrays, NOT HTML or Markdown. Use a Blocks renderer.
+5. **Section.theme is a Tailwind preset key** — Map to your design tokens (e.g. `'dark'` → dark background + light text). DO NOT apply arbitrary CSS colors.
+6. **`name` fields are admin-only** — Blocks with `name` (Features, Slider, Highlights, etc.) use it for CMS identification. DO NOT display it in the frontend.
+7. **Series uses `/api/all-series`** — The pluralName differs from singularName. DO NOT use `/api/series`.
+8. **Inquiry has no draftAndPublish** — `postInquiry` creates immediately-visible records. No publish step needed.
+
+## MCP Content Creation Guide
+
+LLM(Claude Code)이 MCP를 통해 Strapi CMS에 직접 페이지/콘텐츠를 등록하는 워크플로우.
+
+### 추천 MCP 서버
+
+**`@bschauer/strapi-mcp-server`** (npm: `@bschauer/strapi-mcp-server`)
+- Strapi v5 호환, API Token 인증, `strapi_rest` 도구로 REST CRUD 지원
+- `strapi-mcp` (l33tdawg)는 v5에서 create 실패 — 사용 금지
+
+### 설정 순서
+
+1. Strapi Admin → Settings → API Tokens → **Full access / Unlimited** 토큰 생성
+2. `~/.mcp/strapi-mcp-server.config.json`에 서버 등록:
+```json
+{ "my-cms": { "api_url": "http://localhost:1337", "api_key": "<token>", "version": "5.*" } }
+```
+3. 프로젝트 루트 `.mcp.json`에 MCP 서버 설정 (상세: 프로젝트 CLAUDE.md 참조)
+4. **`npx daniworks-builder sync` 필수** — schema뿐 아니라 routes/controllers/services도 생성하여 REST CRUD 엔드포인트 활성화
+
+### 페이지 생성 패턴
+
+```json
+// POST api/pages (via strapi_rest, server="my-cms")
+{
+  "data": {
+    "title": "서비스 소개",
+    "slug": "services",
+    "locale": "ko",
+    "headerMode": "offset",
+    "blocks": [
+      {
+        "__component": "blocks.hero",
+        "variant": "side-by-side",
+        "section": {
+          "heading": "최고의 서비스",
+          "subheading": "고객에게 가치를 전달합니다",
+          "theme": "dark"
+        },
+        "ctaLink": { "label": "시작하기", "href": "/contact" }
+      },
+      {
+        "__component": "blocks.features",
+        "variant": "simple-grid",
+        "section": {
+          "heading": "주요 기능",
+          "theme": "default"
+        },
+        "items": [
+          { "label": "빠른 개발", "description": "CMS 기반 빠른 페이지 구축" },
+          { "label": "유연한 레이아웃", "description": "15가지 블록 조합" }
+        ]
+      }
+    ]
+  }
+}
+```
+
+### 핵심 주의사항
+
+9. **`data` 래퍼 필수** — POST/PUT body는 `{ "data": { ... } }`. 이중 래핑 금지.
+10. **`locale` 필수** — i18n 활성 CT는 `locale` 누락 시 `Invalid key` 에러.
+11. **블록 텍스트는 `section` 안에** — heading/subheading/theme은 블록이 아닌 `section` 서브컴포넌트에 위치. Hero에 `title` 필드 없음.
+12. **`__component` 필수** — Dynamic zone의 각 블록 객체에 반드시 포함.
+13. **컴포넌트 스키마 먼저 확인** — `strapi_get_components`로 실제 필드명 확인 후 데이터 작성. 필드명 추측 금지.
+14. **미디어는 별도 업로드** — `strapi_upload_media` → ID 획득 → PUT으로 연결.
+15. **Deep populate는 Smart API** — `api/builder/pages/:docId`로 모든 중첩 데이터 조회.
+
+## Documentation
+
+| File | Content |
+|------|---------|
+| [docs/api-guide.md](./docs/api-guide.md) | Client setup, 19 API functions, Smart vs REST, populate builders, error handling, i18n |
+| [docs/block-reference.md](./docs/block-reference.md) | 14 blocks + Section: variants, fields, media policies, constraints, sub-components |
+| [docs/content-types.md](./docs/content-types.md) | 11 content types: fields, relations, i18n, DZ unions, BlocksContent structure |

package/docs/api-guide.md

@@ -0,0 +1,223 @@
+# API Guide
+
+## Client Setup
+
+```ts
+import { createStrapiClient } from '@dani-builder/strapi-client/client';
+
+const client = createStrapiClient({
+  baseUrl: 'http://localhost:1337',  // Strapi server URL
+  apiToken: process.env.STRAPI_TOKEN,  // optional Bearer token
+  mediaHost: 'https://cdn.example.com',  // optional CDN override for media URLs
+  defaultLocale: 'ko',  // optional default locale
+});
+```
+
+`createStrapiClient` returns an Axios instance with:
+- `Authorization: Bearer <token>` header (if `apiToken` provided)
+- `Content-Type: application/json`
+- `qs` params serializer (Strapi-compatible nested query format)
+
+## API Functions
+
+| Function | Method | Endpoint | Returns | Notes |
+|----------|--------|----------|---------|-------|
+| `getPage(client, docId, opts?)` | GET | `/api/builder/pages/:docId` | `PageDocument` | Smart endpoint |
+| `getPageBySlug(client, slug, opts?)` | GET | `/api/pages` | `PageDocument \| null` | REST, filter by slug |
+| `listPages(client, opts?)` | GET | `/api/builder/pages` | `{ data, meta }` | Smart, no blocks |
+| `listPagesRest(client, opts?)` | GET | `/api/pages` | `{ data, meta }` | REST, with SEO populate |
+| `getArticle(client, docId, opts?)` | GET | `/api/articles/:docId` | `ArticleDocument` | REST, full populate |
+| `getArticleBySlug(client, slug, opts?)` | GET | `/api/articles` | `ArticleDocument \| null` | REST, filter by slug |
+| `listArticles(client, opts?)` | GET | `/api/articles` | `{ data, meta }` | Filter: category, tag, author, series |
+| `getGlobal(client, opts?)` | GET | `/api/builder/global` | `GlobalDocument` | Smart endpoint |
+| `getGlobalRest(client, opts?)` | GET | `/api/global` | `GlobalDocument` | REST, client-side populate |
+| `getNavigation(client, opts?)` | GET | `/api/navigation` | `NavigationDocument` | REST |
+| `getSiteSettings(client)` | GET | `/api/site-setting` | `SiteSettingsDocument` | No locale, no draftAndPublish |
+| `listFaqs(client, opts?)` | GET | `/api/faqs` | `{ data, meta }` | Filter: category; sort: sortOrder:asc |
+| `listCategories(client, opts?)` | GET | `/api/categories` | `{ data, meta }` | Sort: sortOrder:asc |
+| `listTags(client, opts?)` | GET | `/api/tags` | `{ data, meta }` | Sort: name:asc |
+| `listAuthors(client, opts?)` | GET | `/api/authors` | `{ data, meta }` | With avatar populate |
+| `getAuthorBySlug(client, slug)` | GET | `/api/authors` | `AuthorDocument \| null` | Filter by slug |
+| `listSeries(client, opts?)` | GET | `/api/all-series` | `{ data, meta }` | Note: `/all-series` not `/series` |
+| `getSeriesBySlug(client, slug, locale?)` | GET | `/api/all-series` | `SeriesDocument \| null` | Filter by slug |
+| `postInquiry(client, data)` | POST | `/api/inquiries` | `InquiryDocument` | Body: `InquiryFormData` |
+
+## Smart vs REST
+
+**Smart endpoints** are provided by the Builder plugin and apply server-side populate (optimal field selection):
+
+| Smart Endpoint | Equivalent REST |
+|---------------|----------------|
+| `/api/builder/pages` | `/api/pages` (list, no blocks) |
+| `/api/builder/pages/:docId` | `/api/pages/:docId` (single, full blocks) |
+| `/api/builder/global` | `/api/global` (full populate) |
+
+**When to use which:**
+- **Smart** — Default choice. Populate is optimized server-side; smaller payloads.
+- **REST** — When you need slug-based lookup (`getPageBySlug`), custom populate, or the Smart endpoint is unavailable.
+
+`getPageBySlug` uses REST because Smart endpoints only support documentId lookup, not slug filters.
+
+## Populate Builders
+
+Populate builders construct the nested `populate` parameter for REST queries:
+
+| Builder | Used For |
+|---------|----------|
+| `getPagePopulate(customBlocks?)` | Page with all DZ blocks deep-populated |
+| `getPageListPopulate()` | Page list — SEO only, no blocks |
+| `getGlobalPopulate(customBlocks?)` | Global with footer, seo, siteWideBlocks, home, favicon |
+| `getArticlePopulate()` | Article with seo, cover, gallery, relations |
+| `getArticleListPopulate()` | Article list with cover, categories, tags, author |
+| `getNavigationPopulate()` | Navigation with logos and nav groups |
+| `getSiteSettingsPopulate()` | SiteSettings with analytics, chatbot, verifications |
+| `getFaqPopulate()` | FAQ with category |
+
+**Extending with custom blocks:**
+
+```ts
+const customBlocks = {
+  'blocks.custom-block': {
+    populate: { section: { populate: { backgroundImage: true } }, items: true },
+  },
+};
+const populate = getPagePopulate(customBlocks);
+```
+
+**Low-level populate objects** are also exported:
+- `coreBlockPopulates` — Record of all 14 block UIDs + `elements.section` with their populate
+- `seoPopulate` — SEO component with ogImage
+- `footerPopulate` — Footer with socialLinks, otherLinks, sitemap, logo
+
+## Query Patterns
+
+### Fetch a page by slug
+
+```ts
+const page = await getPageBySlug(client, 'about', { locale: 'ko' });
+if (!page) return notFound();
+// page.blocks is PageBlocks[] — discriminate with __component
+```
+
+### List articles with filters
+
+```ts
+const { data: articles, meta } = await listArticles(client, {
+  category: 'tech',      // filter by category slug
+  tag: 'react',          // filter by tag slug
+  page: 1,
+  pageSize: 10,
+  sort: 'firstPublishedAt:desc',
+});
+```
+
+### Fetch global layout data
+
+```ts
+const global = await getGlobal(client, { locale: 'ko' });
+// global.footer — Footer component
+// global.siteWideBlocks — SiteWideBlocks[] (max 4 block types)
+// global.seo — default SEO
+```
+
+### Submit inquiry
+
+```ts
+const inquiry = await postInquiry(client, {
+  name: 'John Doe',
+  email: 'john@example.com',
+  subject: 'General inquiry',
+  message: 'Hello...',
+});
+```
+
+## Media URL Resolution
+
+```ts
+import { getMediaUrl, getAssetUrl } from '@dani-builder/strapi-client/utils';
+
+// Resolve relative URL to absolute
+const url = getMediaUrl('/uploads/photo.jpg', 'https://cdn.example.com');
+// → 'https://cdn.example.com/uploads/photo.jpg'
+
+// Already-absolute URLs pass through
+getMediaUrl('https://external.com/img.png');
+// → 'https://external.com/img.png'
+
+// Get a specific format with fallback to original
+const thumbUrl = getAssetUrl(article.cover, 'medium', mediaHost);
+// Available formats: 'thumbnail' | 'small' | 'medium' | 'large'
+// Falls back to original URL if requested format doesn't exist
+```
+
+## Error Handling
+
+```ts
+import { isStrapiError } from '@dani-builder/strapi-client/client';
+
+try {
+  const page = await getPage(client, docId);
+} catch (error) {
+  if (isStrapiError(error)) {
+    // error.response.data.error has: { status, name, message, details }
+    console.error(error.response!.data.error.message);
+  }
+  throw error;
+}
+```
+
+`StrapiError` shape:
+```ts
+{
+  data: null;
+  error: {
+    status: number;      // HTTP status code
+    name: string;        // e.g. 'NotFoundError'
+    message: string;     // Human-readable message
+    details: Record<string, unknown>;
+  };
+}
+```
+
+## i18n Support
+
+| Content Type | i18n | Base Type |
+|-------------|------|-----------|
+| Page | yes | `StrapiI18nDocument` |
+| Article | yes | `StrapiI18nDocument` |
+| FAQ | yes | `StrapiI18nDocument` |
+| Category | yes | `StrapiI18nDocument` |
+| Tag | yes | `StrapiI18nDocument` |
+| Series | yes | `StrapiI18nDocument` |
+| Navigation | yes | `StrapiI18nDocument` |
+| Global | yes | `StrapiI18nDocument` |
+| Author | no | `StrapiDocument` |
+| Inquiry | no | `StrapiDocument` |
+| SiteSettings | no | `StrapiDocument` |
+
+Pass `locale` in query options for i18n-enabled types. Non-i18n types ignore the locale parameter.
+
+## Project Wrapping Pattern
+
+Wrap the client in a project-level `lib/strapi/` module to centralize configuration:
+
+```ts
+// lib/strapi/client.ts
+import { createStrapiClient } from '@dani-builder/strapi-client/client';
+
+export const strapi = createStrapiClient({
+  baseUrl: process.env.STRAPI_URL!,
+  apiToken: process.env.STRAPI_TOKEN!,
+  mediaHost: process.env.STRAPI_MEDIA_HOST,
+});
+
+// lib/strapi/queries.ts
+import { strapi } from './client';
+import { getPage, getGlobal, listArticles } from '@dani-builder/strapi-client/api';
+
+export const fetchPage = (docId: string, locale?: string) =>
+  getPage(strapi, docId, { locale });
+
+export const fetchGlobal = (locale?: string) =>
+  getGlobal(strapi, { locale });
+```

package/docs/block-reference.md

@@ -0,0 +1,601 @@
+# Block Reference
+
+## Quick Reference Table
+
+| Block | `__component` | Variants | Media Policy | Items Type |
+|-------|--------------|----------|-------------|-----------|
+| Hero | `blocks.hero` | `side-by-side`, `media-extending`, `fullscreen-media`, `stacked-media` | heroMedia: images+videos | — |
+| Features | `blocks.features` | `simple-grid`, `dual-column`, `media-aside`, `media-aside-compact` | media: images only | `FeatureItem[]` |
+| CTA | `blocks.cta` | `inline-spread`, `inline-centered`, `inline-stacked`, `card-stacked`, `card-centered`, `card-horizontal` | ctaMedia: images+videos | — |
+| Slider | `blocks.slider` | `cover-flow`, `card-slider` | — | `SliderItem[]` |
+| InquiryForm | `blocks.inquiry-form` | — | — | — |
+| FAQ | `blocks.faq` | — | — | `FaqDocument[]` (relation) |
+| Highlights | `blocks.highlights` | `dual-column`, `triple-column`, `alternating` | media: images+videos | `HighlightItem[]` |
+| BentoGrid | `blocks.bento-grid` | — (layout via `columns` + item spans) | — | `BentoItem[]` |
+| Testimonials | `blocks.testimonials` | `centered`, `side-by-side`, `card-grid`, `subtle-grid` | media: images+videos | `TestimonialItem[]` |
+| LogoCloud | `blocks.logo-cloud` | `inline`, `grid`, `split` | — | `LogoItem[]` |
+| Stats | `blocks.stats` | `simple`, `card-grid`, `split` | media: images+videos | `StatItem[]` |
+| Pricing | `blocks.pricing` | `two-column`, `three-column`, `single`, `with-comparison` | — | `PricingTier[]` |
+| Content | `blocks.content` | `prose`, `wide`, `full-width` | — | — |
+| Team | `blocks.team` | `grid`, `large-image`, `compact` | — | `TeamMember[]` |
+
+---
+
+## Media Policy Summary
+
+### Images + Videos
+
+These fields accept both image and video uploads. Render `<video>` or `<img>` based on `asset.mime`.
+
+| Field | Component |
+|-------|-----------|
+| `heroMedia` | `blocks.hero` |
+| `ctaMedia` | `blocks.cta` |
+| `media` | `blocks.highlights` |
+| `media` | `blocks.testimonials` |
+| `media` | `blocks.stats` |
+| `media` | `shared.highlight-item` |
+| `media` | `shared.slider-item` |
+
+### Images Only
+
+These fields reject video uploads. Always render as `<img>`.
+
+| Field | Component |
+|-------|-----------|
+| `media` | `blocks.features` |
+| `backgroundImage` | `elements.section` |
+| `logo` | `elements.footer` |
+| `logo` | `shared.logo-item` |
+| `avatar` | `shared.testimonial-item` |
+| `logo` | `shared.testimonial-item` |
+| `media` | `shared.bento-item` |
+| `photo` | `shared.team-member` |
+| `ogImage` | `shared.seo` |
+| `mainLogo` | Navigation CT |
+| `darkLogo` | Navigation CT |
+| `favicon` | Global CT |
+| `cover` | Article CT |
+| `gallery` | Article CT |
+| `avatar` | Author CT |
+| `cover` | Series CT |
+
+---
+
+## Section (`elements.section`)
+
+Every block has an optional `section: Section | null` field. Section provides the heading, theme, and background for the block. It can also appear standalone in `Page.blocks` as a separator.
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `heading` | `string \| null` | Section heading |
+| `subheading` | `string \| null` | Subheading |
+| `kickerText` | `string \| null` | Small text above heading |
+| `anchorId` | `string \| null` | Anchor ID for in-page navigation |
+| `headerAlign` | `'auto' \| 'left' \| 'center' \| 'right' \| null` | Heading alignment |
+| `theme` | `'default' \| 'light' \| 'dark' \| 'accent' \| 'muted' \| 'contrast'` | Tailwind preset key |
+| `backgroundImage` | `StrapiMedia \| null` | Background image (images only) |
+| `backgroundImageOpacity` | `number \| null` | Opacity 0–1 for background image overlay |
+
+**Constraints:**
+- `theme` maps to a Tailwind preset in the frontend theme config. DO NOT use arbitrary CSS colors.
+- `backgroundImage` is images-only. DO NOT attempt to use video backgrounds here.
+
+---
+
+## Hero (`blocks.hero`)
+
+**`__component`: `'blocks.hero'`**
+**Used in:** Page.blocks, Global.siteWideBlocks
+
+### Variants
+
+| Value | Layout |
+|-------|--------|
+| `side-by-side` | Text on one side, media on the other — split layout |
+| `media-extending` | Media extends beyond container bounds |
+| `fullscreen-media` | Full-viewport background media with text overlay |
+| `stacked-media` | Media below the text content |
+
+### Fields
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `variant` | enum | Layout variant (see above) |
+| `section` | `Section \| null` | Section wrapper |
+| `heroMedia` | `StrapiMedia \| null` | Hero media — **images+videos** |
+| `ctaText` | `string \| null` | Supplementary CTA text |
+| `ctaLink` | `Link \| null` | Primary CTA link |
+| `secondaryLink` | `Link \| null` | Secondary link |
+| `headerMode` | `'none' \| 'transparent-black' \| 'transparent-white'` | Header overlay mode for navigation |
+
+**Constraints:**
+- `heroMedia` accepts images+videos. Check `mime` to decide between `<img>` and `<video>`.
+- `headerMode` controls how the page header (navigation) renders over this hero. `none` = default header, `transparent-*` = transparent with light/dark text.
+- DO NOT confuse `headerMode` here with `Page.headerMode` (`'overlay' | 'offset'`).
+
+---
+
+## Features (`blocks.features`)
+
+**`__component`: `'blocks.features'`**
+**Used in:** Page.blocks, Global.siteWideBlocks
+
+### Variants
+
+| Value | Layout |
+|-------|--------|
+| `simple-grid` | Icon+text items in a uniform grid |
+| `dual-column` | Two-column grid layout |
+| `media-aside` | Items on one side, media image on the other |
+| `media-aside-compact` | Compact version of media-aside |
+
+### Fields
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `name` | `string \| null` | Admin label — DO NOT display |
+| `variant` | enum | Layout variant |
+| `section` | `Section \| null` | Section wrapper |
+| `media` | `StrapiMedia \| null` | Supporting image — **images only** |
+| `items` | `FeatureItem[]` | Feature items list |
+
+**Constraints:**
+- `media` is images-only and only relevant for `media-aside` / `media-aside-compact` variants.
+- DO NOT render the `media` field for `simple-grid` or `dual-column` variants.
+
+---
+
+## CTA (`blocks.cta`)
+
+**`__component`: `'blocks.cta'`**
+**Used in:** Page.blocks
+
+### Variants
+
+| Value | Layout |
+|-------|--------|
+| `inline-spread` | Text and buttons spread horizontally |
+| `inline-centered` | Centered text with buttons below |
+| `inline-stacked` | Text and buttons stacked vertically |
+| `card-stacked` | Card container with stacked content |
+| `card-centered` | Card container with centered content |
+| `card-horizontal` | Card container with horizontal layout |
+
+### Fields
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `section` | `Section \| null` | Section wrapper |
+| `variant` | enum | Layout variant |
+| `ctaMedia` | `StrapiMedia \| null` | CTA media — **images+videos** |
+| `ctaText` | `string \| null` | Supplementary text |
+| `ctaLink` | `Link \| null` | Primary CTA link |
+| `secondaryLink` | `Link \| null` | Secondary link |
+
+**Constraints:**
+- `ctaMedia` accepts images+videos. Most relevant for `card-*` variants.
+- `inline-*` variants are borderless/background-less; `card-*` variants have a card container.
+
+---
+
+## Slider (`blocks.slider`)
+
+**`__component`: `'blocks.slider'`**
+**Used in:** Page.blocks, Global.siteWideBlocks
+
+### Variants
+
+| Value | Layout |
+|-------|--------|
+| `cover-flow` | Cover-flow style with center-focused active slide |
+| `card-slider` | Card-based slider/carousel |
+
+### Fields
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `name` | `string \| null` | Admin label — DO NOT display |
+| `variant` | enum | Slider style |
+| `section` | `Section \| null` | Section wrapper |
+| `items` | `SliderItem[]` | Slider items (media required per item) |
+
+**Constraints:**
+- Each `SliderItem.media` is required (images+videos). Always render media for each slide.
+
+---
+
+## InquiryForm (`blocks.inquiry-form`)
+
+**`__component`: `'blocks.inquiry-form'`**
+**Used in:** Page.blocks, Global.siteWideBlocks
+
+### Fields
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `section` | `Section \| null` | Section wrapper |
+| `successMessage` | `string \| null` | Message displayed after successful submission |
+
+**Constraints:**
+- The form UI is rendered by the frontend (not from CMS data). Submit to `postInquiry(client, data)`.
+- Form fields: `name` (required), `email`, `phone`, `subject`, `message` — see `InquiryFormData` type.
+
+---
+
+## FAQ (`blocks.faq`)
+
+**`__component`: `'blocks.faq'`**
+**Used in:** Page.blocks
+
+### Fields
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `section` | `Section \| null` | Section wrapper |
+| `items` | `FaqDocument[]` | FAQ entries (relation: oneToMany → `api::faq.faq`) |
+
+**Constraints:**
+- `items` are full FAQ documents (with `question`, `answer`, `category`, `sortOrder`).
+- `answer` is `BlocksContent | null` — use a Blocks renderer, not markdown.
+- No variant — use a single accordion/expandable pattern.
+
+---
+
+## Highlights (`blocks.highlights`)
+
+**`__component`: `'blocks.highlights'`**
+**Used in:** Page.blocks
+
+### Variants
+
+| Value | Layout |
+|-------|--------|
+| `dual-column` | Two-column image+text grid |
+| `triple-column` | Three-column grid |
+| `alternating` | Zigzag layout — alternating image/text sides |
+
+### Fields
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `name` | `string \| null` | Admin label — DO NOT display |
+| `variant` | enum | Layout variant |
+| `media` | `StrapiMedia \| null` | Block-level supporting media — **images+videos** |
+| `section` | `Section \| null` | Section wrapper |
+| `items` | `HighlightItem[]` | Highlight items (each has required media) |
+
+**Constraints:**
+- Block-level `media` is a supporting visual, not per-item media.
+- Each `HighlightItem.media` is required (images+videos).
+- For `alternating` variant, items alternate between text-left/media-right and media-left/text-right.
+
+---
+
+## BentoGrid (`blocks.bento-grid`)
+
+**`__component`: `'blocks.bento-grid'`**
+**Used in:** Page.blocks
+
+### Fields
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `name` | `string \| null` | Admin label — DO NOT display |
+| `section` | `Section \| null` | Section wrapper |
+| `columns` | `number` | Grid columns (2–4, default 3) |
+| `items` | `BentoItem[]` | Grid items with colSpan/rowSpan |
+
+**Constraints:**
+- No variant — layout is controlled by `columns` + each item's `colSpan`/`rowSpan`.
+- Use CSS Grid: `grid-template-columns: repeat(columns, 1fr)`.
+- `BentoItem.media` is images-only.
+- Each item's `colSpan` (1–4) and `rowSpan` (1–3) define its grid area.
+
+---
+
+## Testimonials (`blocks.testimonials`)
+
+**`__component`: `'blocks.testimonials'`**
+**Used in:** Page.blocks
+
+### Variants
+
+| Value | Layout |
+|-------|--------|
+| `centered` | Single/few quotes centered, large format |
+| `side-by-side` | Quote + supporting media in split layout |
+| `card-grid` | Multiple testimonials as cards in a grid |
+| `subtle-grid` | Multiple testimonials in a minimal grid |
+
+### Fields
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `name` | `string \| null` | Admin label — DO NOT display |
+| `variant` | enum | Layout variant |
+| `section` | `Section \| null` | Section wrapper |
+| `media` | `StrapiMedia \| null` | Block-level supporting media — **images+videos** |
+| `items` | `TestimonialItem[]` | Testimonial items |
+
+**Constraints:**
+- Block-level `media` is primarily used with `side-by-side` variant.
+- `TestimonialItem.avatar` and `TestimonialItem.logo` are images-only.
+- `TestimonialItem.rating` is 1–5 integer or null. Render as star rating when present.
+
+---
+
+## LogoCloud (`blocks.logo-cloud`)
+
+**`__component`: `'blocks.logo-cloud'`**
+**Used in:** Page.blocks
+
+### Variants
+
+| Value | Layout |
+|-------|--------|
+| `inline` | Logos in a single horizontal row (4–8 logos) |
+| `grid` | Logos in a grid layout (8+ logos) |
+| `split` | Text on left (section heading/subheading) + logo grid on right |
+
+### Fields
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `name` | `string \| null` | Admin label — DO NOT display |
+| `variant` | enum | Layout variant |
+| `section` | `Section \| null` | Section wrapper |
+| `items` | `LogoItem[]` | Logo items |
+
+**Constraints:**
+- No block-level media. `split` variant uses `section.heading`/`subheading` for text.
+- `LogoItem.logo` is required (images only).
+
+---
+
+## Stats (`blocks.stats`)
+
+**`__component`: `'blocks.stats'`**
+**Used in:** Page.blocks
+
+### Variants
+
+| Value | Layout |
+|-------|--------|
+| `simple` | Horizontal row of stats (use section.theme for dark/light) |
+| `card-grid` | Stats displayed as cards in a grid |
+| `split` | Stats on one side + media on the other |
+
+### Fields
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `name` | `string \| null` | Admin label — DO NOT display |
+| `variant` | enum | Layout variant |
+| `section` | `Section \| null` | Section wrapper |
+| `media` | `StrapiMedia \| null` | Supporting media — **images+videos** |
+| `items` | `StatItem[]` | Stat items |
+
+**Constraints:**
+- `media` is only relevant for `split` variant. DO NOT render it for `simple` or `card-grid`.
+- `StatItem.value` is a string (e.g. `"10,000+"`, `"99.9%"`). DO NOT parse it as a number.
+
+---
+
+## Pricing (`blocks.pricing`)
+
+**`__component`: `'blocks.pricing'`**
+**Used in:** Page.blocks
+
+### Variants
+
+| Value | Layout |
+|-------|--------|
+| `two-column` | Side-by-side comparison of 2 plans |
+| `three-column` | Three plans (Good/Better/Best) |
+| `single` | Single plan detail view |
+| `with-comparison` | Plans + feature comparison table below |
+
+### Fields
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `name` | `string \| null` | Admin label — DO NOT display |
+| `variant` | enum | Layout variant |
+| `section` | `Section \| null` | Section wrapper |
+| `items` | `PricingTier[]` | Pricing tiers |
+
+**Constraints:**
+- `PricingTier.price` is a string (e.g. `"$29"`, `"Free"`, `"Contact us"`). DO NOT parse as number.
+- `PricingTier.featureList` is richtext (Markdown). Render as a bullet list.
+- `PricingTier.highlighted` marks the recommended plan — apply visual emphasis (ribbon, border, etc.).
+
+---
+
+## Content (`blocks.content`)
+
+**`__component`: `'blocks.content'`**
+**Used in:** Page.blocks
+
+### Variants
+
+| Value | Layout |
+|-------|--------|
+| `prose` | Reading-optimized width (max-w-prose). For long-form text. |
+| `wide` | Wider container. For content with images/tables. |
+| `full-width` | Full container width. For notices, terms. |
+
+### Fields
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `section` | `Section \| null` | Section wrapper |
+| `variant` | enum | Content width variant |
+| `body` | `BlocksContent` | Rich text body — **required** |
+
+**Constraints:**
+- `body` is `BlocksContent` (structured JSON), NOT HTML or Markdown. Use a Blocks renderer.
+- No `name`, no `items`, no `media` — the Blocks editor supports inline images.
+
+---
+
+## Team (`blocks.team`)
+
+**`__component`: `'blocks.team'`**
+**Used in:** Page.blocks
+
+### Variants
+
+| Value | Layout |
+|-------|--------|
+| `grid` | Standard grid — circular/square photos + name/role/bio. For 4–12 members. |
+| `large-image` | Large photo emphasis. For leadership/key members. |
+| `compact` | Small photos + minimal info. For large teams (12+). |
+
+### Fields
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `name` | `string \| null` | Admin label — DO NOT display |
+| `variant` | enum | Layout variant |
+| `section` | `Section \| null` | Section wrapper |
+| `items` | `TeamMember[]` | Team members |
+
+**Constraints:**
+- `TeamMember.photo` is images-only.
+- `TeamMember.socialLinks` is `Link[]` — render as icon links.
+
+---
+
+## Shared Sub-Components
+
+### FeatureItem (`shared.feature-item`)
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `label` | `string \| null` | Item label |
+| `description` | `string \| null` | Markdown richtext |
+| `icon` | `string \| null` | Icon picker value |
+| `infoText` | `string \| null` | Supplementary info text |
+| `link` | `Link \| null` | Optional link |
+
+### HighlightItem (`shared.highlight-item`)
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `label` | `string \| null` | Item label |
+| `description` | `string \| null` | Markdown richtext |
+| `media` | `StrapiMedia` | **Required** — images+videos |
+| `link` | `Link \| null` | Optional link |
+
+### SliderItem (`shared.slider-item`)
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `label` | `string \| null` | Item label |
+| `description` | `string \| null` | Description text |
+| `link` | `Link \| null` | Optional link |
+| `media` | `StrapiMedia` | **Required** — images+videos |
+
+### BentoItem (`shared.bento-item`)
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `title` | `string \| null` | Item title |
+| `description` | `string \| null` | Description text |
+| `media` | `StrapiMedia \| null` | Screenshot/illustration — images only |
+| `icon` | `string \| null` | Decorative icon |
+| `colSpan` | `number` | Column span (1–4, default 1) |
+| `rowSpan` | `number` | Row span (1–3, default 1) |
+| `link` | `Link \| null` | Optional link |
+
+### TestimonialItem (`shared.testimonial-item`)
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `quote` | `string` | **Required** — testimonial text |
+| `authorName` | `string \| null` | Author name |
+| `authorRole` | `string \| null` | Author title/role |
+| `avatar` | `StrapiMedia \| null` | Profile image — images only |
+| `logo` | `StrapiMedia \| null` | Company logo — images only |
+| `rating` | `number \| null` | Star rating 1–5 |
+
+### LogoItem (`shared.logo-item`)
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `logo` | `StrapiMedia` | **Required** — images only |
+| `companyName` | `string \| null` | Company name (for alt text/accessibility) |
+| `link` | `Link \| null` | Optional link |
+
+### StatItem (`shared.stat-item`)
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `value` | `string` | **Required** — formatted value string |
+| `label` | `string \| null` | Short label |
+| `description` | `string \| null` | Supplementary description |
+
+### PricingTier (`shared.pricing-tier`)
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `planName` | `string` | **Required** — plan name |
+| `price` | `string` | **Required** — formatted price string |
+| `billingPeriod` | `string \| null` | e.g. "/mo", "/year" |
+| `description` | `string \| null` | Plan description |
+| `featureList` | `string \| null` | Markdown bullet list |
+| `ctaLink` | `Link \| null` | CTA link |
+| `highlighted` | `boolean` | Recommended plan flag |
+
+### TeamMember (`shared.team-member`)
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `memberName` | `string` | **Required** — member name |
+| `role` | `string \| null` | Title/role |
+| `bio` | `string \| null` | Short bio |
+| `photo` | `StrapiMedia \| null` | Profile photo — images only |
+| `socialLinks` | `Link[]` | Social media links |
+
+### Link (`shared.link`)
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `label` | `string` | **Required** — link label |
+| `href` | `string` | **Required** — URL |
+| `newWindow` | `boolean` | Open in new window (default false) |
+| `icon` | `string \| null` | Icon picker value |
+
+---
+
+## DZ Discrimination Pattern
+
+```ts
+import type { PageBlocks, SiteWideBlocks } from '@dani-builder/strapi-client/types';
+
+function renderBlock(block: PageBlocks) {
+  switch (block.__component) {
+    case 'blocks.hero':        return <HeroSection block={block} />;
+    case 'blocks.features':    return <FeaturesSection block={block} />;
+    case 'blocks.cta':         return <CtaSection block={block} />;
+    case 'blocks.slider':      return <SliderSection block={block} />;
+    case 'blocks.inquiry-form': return <InquiryFormSection block={block} />;
+    case 'blocks.faq':         return <FaqSection block={block} />;
+    case 'blocks.highlights':  return <HighlightsSection block={block} />;
+    case 'blocks.bento-grid':  return <BentoGridSection block={block} />;
+    case 'blocks.testimonials': return <TestimonialsSection block={block} />;
+    case 'blocks.logo-cloud':  return <LogoCloudSection block={block} />;
+    case 'blocks.stats':       return <StatsSection block={block} />;
+    case 'blocks.pricing':     return <PricingSection block={block} />;
+    case 'blocks.content':     return <ContentSection block={block} />;
+    case 'blocks.team':        return <TeamSection block={block} />;
+    case 'elements.section':   return <SectionDivider section={block} />;
+    default: return null;
+  }
+}
+```
+
+**PageBlocks union** (15 members): `Section | HeroBlock | FeaturesBlock | CtaBlock | SliderBlock | InquiryFormBlock | FaqBlock | HighlightsBlock | BentoGridBlock | TestimonialsBlock | LogoCloudBlock | StatsBlock | PricingBlock | ContentBlock | TeamBlock`
+
+**SiteWideBlocks union** (4 members): `SliderBlock | InquiryFormBlock | HeroBlock | FeaturesBlock`

package/docs/content-types.md

@@ -0,0 +1,393 @@
+# Content Types
+
+## Overview
+
+| Content Type | Kind | draftAndPublish | i18n | Slug | Key Relations |
+|-------------|------|----------------|------|------|---------------|
+| Page | collection | yes | yes | `slug` | blocks (DZ), seo |
+| Article | collection | yes | yes | `slug` | categories, tags, author, series, related_posts |
+| FAQ | collection | yes | yes | — | category |
+| Inquiry | collection | no | no | — | — |
+| Category | collection | no | yes | `slug` | — |
+| Tag | collection | no | yes | `slug` | — |
+| Author | collection | no | no | `slug` | — |
+| Series | collection | no | yes | `slug` | — |
+| Navigation | single | yes | yes | — | globalNavigation, primaryLink, secondaryLink |
+| Global | single | yes | yes | — | home (Page), footer, seo, siteWideBlocks (DZ) |
+| SiteSettings | single | no | no | — | analyticsSettings, chatbot, siteVerifications |
+
+---
+
+## Collection Types
+
+### Page
+
+```ts
+interface Page {
+  title: string;
+  slug: string;
+  seo: Seo | null;
+  blocks: PageBlocks[];            // DZ — 15 block types
+  headerMode: 'overlay' | 'offset';
+}
+type PageDocument = StrapiI18nDocument & Page;
+```
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `title` | `string` | Page title |
+| `slug` | `string` | URL slug |
+| `seo` | `Seo \| null` | SEO metadata |
+| `blocks` | `PageBlocks[]` | Dynamic Zone — see [Block Reference](./block-reference.md) |
+| `headerMode` | `'overlay' \| 'offset'` | How the navigation header relates to the first block |
+
+`headerMode`:
+- `overlay` — Header overlaps the first block (hero with transparent header)
+- `offset` — Header takes its own space above the first block
+
+### Article
+
+```ts
+interface Article {
+  title: string;
+  slug: string;
+  body: BlocksContent;
+  summary: string | null;
+  excerpt: string | null;
+  cover: StrapiMedia | null;
+  gallery: StrapiMedia[];
+  reading_time: number;
+  firstPublishedAt: string | null;
+  seo: Seo | null;
+  categories: CategoryDocument[];
+  tags: TagDocument[];
+  author: AuthorDocument | null;
+  series: SeriesDocument | null;
+  series_order: number;
+  related_posts: ArticleDocument[];
+}
+type ArticleDocument = StrapiI18nDocument & Article;
+```
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `title` | `string` | Article title |
+| `slug` | `string` | URL slug |
+| `body` | `BlocksContent` | Article body — structured JSON (NOT HTML) |
+| `summary` | `string \| null` | Short summary for cards/lists |
+| `excerpt` | `string \| null` | Longer excerpt for previews |
+| `cover` | `StrapiMedia \| null` | Cover image — images only |
+| `gallery` | `StrapiMedia[]` | Image gallery — images only |
+| `reading_time` | `number` | Estimated reading time in minutes |
+| `firstPublishedAt` | `string \| null` | Original publish date (ISO string) |
+| `seo` | `Seo \| null` | SEO metadata |
+| `categories` | `CategoryDocument[]` | Related categories |
+| `tags` | `TagDocument[]` | Related tags |
+| `author` | `AuthorDocument \| null` | Article author |
+| `series` | `SeriesDocument \| null` | Article series |
+| `series_order` | `number` | Order within series |
+| `related_posts` | `ArticleDocument[]` | Related articles |
+
+- `summary` vs `excerpt`: `summary` is a 1–2 sentence blurb for card UIs; `excerpt` is a longer preview paragraph.
+- `body` is `BlocksContent` — use a Blocks renderer component.
+
+### FAQ
+
+```ts
+interface Faq {
+  question: string | null;
+  answer: BlocksContent | null;
+  sortOrder: number | null;
+  category: CategoryDocument | null;
+}
+type FaqDocument = StrapiI18nDocument & Faq;
+```
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `question` | `string \| null` | FAQ question |
+| `answer` | `BlocksContent \| null` | Answer — structured JSON (NOT HTML) |
+| `sortOrder` | `number \| null` | Display order |
+| `category` | `CategoryDocument \| null` | Related category |
+
+### Inquiry
+
+```ts
+interface Inquiry {
+  name: string;
+  email: string | null;
+  phone: string | null;
+  subject: string | null;
+  message: string | null;
+}
+type InquiryDocument = StrapiDocument & Inquiry;  // no i18n, no draftAndPublish
+```
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `name` | `string` | Submitter name (required) |
+| `email` | `string \| null` | Email address |
+| `phone` | `string \| null` | Phone number |
+| `subject` | `string \| null` | Inquiry subject |
+| `message` | `string \| null` | Message body |
+
+**POST body type:**
+
+```ts
+interface InquiryFormData {
+  name: string;          // required
+  email?: string;
+  phone?: string;
+  subject?: string;
+  message?: string;
+}
+```
+
+Inquiry is POST-only from the frontend. Records are created immediately (no publish step).
+
+### Category
+
+```ts
+interface Category {
+  name: string;
+  slug: string;
+  description: string | null;
+  sortOrder: number | null;
+}
+type CategoryDocument = StrapiI18nDocument & Category;
+```
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `name` | `string` | Category name |
+| `slug` | `string` | URL slug |
+| `description` | `string \| null` | Category description |
+| `sortOrder` | `number \| null` | Display order |
+
+### Tag
+
+```ts
+interface Tag {
+  name: string;
+  slug: string;
+  color: string | null;
+  description: string | null;
+}
+type TagDocument = StrapiI18nDocument & Tag;
+```
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `name` | `string` | Tag name |
+| `slug` | `string` | URL slug |
+| `color` | `string \| null` | Hex color string (color picker) |
+| `description` | `string \| null` | Tag description |
+
+### Author
+
+```ts
+interface Author {
+  name: string;
+  slug: string;
+  role: string | null;
+  bio: string | null;       // Markdown richtext
+  avatar: StrapiMedia | null;
+  email: string | null;
+}
+type AuthorDocument = StrapiDocument & Author;  // no i18n
+```
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `name` | `string` | Author name |
+| `slug` | `string` | URL slug |
+| `role` | `string \| null` | Title/role |
+| `bio` | `string \| null` | Bio (Markdown richtext) |
+| `avatar` | `StrapiMedia \| null` | Profile image — images only |
+| `email` | `string \| null` | Contact email |
+
+### Series
+
+```ts
+interface Series {
+  name: string;
+  slug: string;
+  description: string | null;
+  cover: StrapiMedia | null;
+}
+type SeriesDocument = StrapiI18nDocument & Series;
+```
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `name` | `string` | Series name |
+| `slug` | `string` | URL slug |
+| `description` | `string \| null` | Series description |
+| `cover` | `StrapiMedia \| null` | Cover image — images only |
+
+API endpoint: `/api/all-series` (pluralName `all-series` differs from singularName `series`).
+
+---
+
+## Single Types
+
+### Navigation
+
+```ts
+interface Navigation {
+  mainLogo: StrapiMedia | null;
+  darkLogo: StrapiMedia | null;
+  globalNavigation: NavigationGroup[];
+  primaryLink: Link | null;
+  secondaryLink: Link | null;
+  align: 'left' | 'center' | 'right';
+}
+type NavigationDocument = StrapiI18nDocument & Navigation;
+```
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `mainLogo` | `StrapiMedia \| null` | Main logo — images only |
+| `darkLogo` | `StrapiMedia \| null` | Dark mode logo — images only |
+| `globalNavigation` | `NavigationGroup[]` | Nav groups with nested links |
+| `primaryLink` | `Link \| null` | Primary action link (e.g. "Get Started") |
+| `secondaryLink` | `Link \| null` | Secondary link (e.g. "Login") |
+| `align` | `'left' \| 'center' \| 'right'` | Logo/nav alignment |
+
+### Global
+
+```ts
+interface Global {
+  sitename: string;
+  seo: Seo | null;
+  home: PageDocument | null;
+  footer: Footer | null;
+  siteWideBlocks: SiteWideBlocks[];
+  darkModeEnabled: boolean;
+  defaultTheme: 'light' | 'dark' | null;
+  favicon: StrapiMedia | null;
+}
+type GlobalDocument = StrapiI18nDocument & Global;
+```
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `sitename` | `string` | Site name |
+| `seo` | `Seo \| null` | Default SEO (fallback for pages without SEO) |
+| `home` | `PageDocument \| null` | Relation to homepage Page |
+| `footer` | `Footer \| null` | Footer component |
+| `siteWideBlocks` | `SiteWideBlocks[]` | DZ — blocks rendered on every page |
+| `darkModeEnabled` | `boolean` | Whether dark mode is enabled |
+| `defaultTheme` | `'light' \| 'dark' \| null` | Default color scheme |
+| `favicon` | `StrapiMedia \| null` | Site favicon — images only |
+
+`siteWideBlocks` accepts only 4 block types: `SliderBlock | InquiryFormBlock | HeroBlock | FeaturesBlock`.
+
+### SiteSettings
+
+```ts
+interface SiteSettings {
+  analyticsSettings: AnalyticsSetting[];
+  chatbot: ChatbotSetting | null;
+  siteVerifications: SiteVerification[];
+}
+type SiteSettingsDocument = StrapiDocument & SiteSettings;  // no i18n
+```
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `analyticsSettings` | `AnalyticsSetting[]` | Analytics providers (repeatable) |
+| `chatbot` | `ChatbotSetting \| null` | Chatbot configuration |
+| `siteVerifications` | `SiteVerification[]` | Search engine verification meta tags |
+
+API endpoint: `/api/site-setting` (singularName `site-setting`).
+
+---
+
+## Relation Map
+
+```
+Page ──blocks──▶ [DZ: 14 blocks + Section]
+  │                     │
+  │                blocks.faq ──items──▶ FAQ ──category──▶ Category
+  │
+  └──seo──▶ Seo
+
+Article ──┬──categories──▶ Category[]
+          ├──tags──▶ Tag[]
+          ├──author──▶ Author
+          ├──series──▶ Series
+          ├──related_posts──▶ Article[]
+          └──seo──▶ Seo
+
+Global ──┬──home──▶ Page
+         ├──footer──▶ Footer ──sitemap──▶ NavigationGroup[] ──links──▶ Link[]
+         ├──siteWideBlocks──▶ [DZ: 4 block types]
+         └──seo──▶ Seo
+
+Navigation ──globalNavigation──▶ NavigationGroup[] ──links──▶ Link[]
+
+SiteSettings ──┬──analyticsSettings──▶ AnalyticsSetting[]
+               ├──chatbot──▶ ChatbotSetting
+               └──siteVerifications──▶ SiteVerification[]
+```
+
+---
+
+## BlocksContent Structure
+
+`BlocksContent` is the JSON output of Strapi's Blocks editor. It is an array of `BlockNode` objects.
+
+**Used in:** `Article.body`, `FAQ.answer`, `ContentBlock.body`
+
+```ts
+type BlocksContent = BlockNode[];
+
+type BlockNode =
+  | BlockParagraph    // { type: 'paragraph', children: BlockInlineNode[] }
+  | BlockHeading      // { type: 'heading', level: 1-6, children: BlockInlineNode[] }
+  | BlockList         // { type: 'list', format: 'ordered'|'unordered', children: BlockListItem[] }
+  | BlockQuote        // { type: 'quote', children: BlockInlineNode[] }
+  | BlockCode         // { type: 'code', children: BlockTextChild[] }
+  | BlockImage;       // { type: 'image', image: StrapiMedia, children: [{ type: 'text', text: '' }] }
+
+type BlockInlineNode = BlockTextChild | BlockLinkChild;
+
+// BlockTextChild: { type: 'text', text: string, bold?, italic?, underline?, strikethrough?, code? }
+// BlockLinkChild: { type: 'link', url: string, children: BlockTextChild[] }
+```
+
+DO NOT treat BlocksContent as HTML or Markdown. Use a dedicated renderer that walks the node tree.
+
+---
+
+## Document Base Fields
+
+### StrapiDocument
+
+All content type documents extend this:
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `id` | `number` | Internal database ID |
+| `documentId` | `string` | Stable document ID (use for API queries) |
+| `createdAt` | `string` | ISO date string |
+| `updatedAt` | `string` | ISO date string |
+| `publishedAt` | `string \| null` | Publish date (null if draft) |
+
+### StrapiI18nDocument
+
+Extends `StrapiDocument` with:
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `locale` | `string` | Locale code (e.g. `'ko'`, `'en'`) |
+
+### StrapiComponent
+
+Base for all component instances:
+
+| Field | Type | Description |
+|-------|------|-------------|
+| `id` | `number` | Component instance ID |
+| `__component` | `string` | Component UID (e.g. `'blocks.hero'`, `'shared.link'`) |

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dani-builder/strapi-client",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "description": "TypeScript client for Daniworks Builder CMS (Strapi v5)",
   "license": "MIT",
   "type": "module",
@@ -31,7 +31,9 @@
     }
   },
   "files": [
-    "dist"
+    "dist",
+    "AGENTS.md",
+    "docs"
   ],
   "publishConfig": {
     "access": "public"
@@ -41,16 +43,16 @@
     "url": "https://github.com/hojinzs/daniworks-builder-v2.git",
     "directory": "packages/strapi-client"
   },
-  "scripts": {
-    "build": "tsc"
-  },
   "dependencies": {
     "axios": "^1.7.0",
     "qs": "^6.13.0"
   },
   "devDependencies": {
-    "@repo/typescript-config": "workspace:*",
     "@types/qs": "^6.9.0",
-    "typescript": "5.9.2"
+    "typescript": "5.9.2",
+    "@repo/typescript-config": "0.0.0"
+  },
+  "scripts": {
+    "build": "tsc"
   }
-}
+}