cmx-sdk 0.1.10 → 0.1.13

package/README.md

@@ -1,95 +1,393 @@
-# CMX SDK
+# cmx-sdk
 
-CLI tool for managing CMX schemas and content.
+Official SDK for building content-driven websites with CMX (Content Management Experience).
 
 ## Installation
 
 ```bash
 npm install cmx-sdk
+# or
+pnpm add cmx-sdk
+# or
+yarn add cmx-sdk
 ```
 
-## Environment Variables
+## Features
 
-```bash
-CMX_API_URL=https://your-api-url.com
+- Type-Safe API Client - Fetch content from CMX Admin with full TypeScript support
+- MDX Rendering - Server-side MDX compilation with reference resolution
+- MDX Components - Pre-built React components (Callout, Embed, BlogCard, Image, etc.)
+- Next.js Optimized - Built-in support for ISR, caching, and revalidation
+- Customizable - Inject your own custom components into MDX rendering
+
+## Quick Start
+
+### 1. Set up environment variables
+
+Create a `.env.local` file:
+
+```env
+CMX_API_URL=https://your-cmx-admin.example.com
 CMX_API_KEY=your_api_key_here
 ```
 
-## Commands
+### 2. Fetch content
 
-### create-collection
+```tsx
+import { getCollectionContents, getCollectionContentDetail } from 'cmx-sdk';
 
-Create a new collection.
+// List contents in a collection
+const { collection, contents } = await getCollectionContents('blog');
 
-```bash
-# Using JSON
-cmx-sdk create-collection --json '{"type":"post","slug":"blog","name":"ブログ"}'
+// Get a specific content with references
+const { collection, content, references } = await getCollectionContentDetail('blog', 'my-post');
+```
+
+### 3. Render MDX content
 
-# Using individual options
-cmx-sdk create-collection --type post --slug blog --name ブログ --description "ブログ記事"
+```tsx
+import { renderMdx } from 'cmx-sdk';
+
+// Render MDX with reference resolution (BlogCard, Image, etc.)
+const { rendered } = await renderMdx(content.mdx, references);
+return <article>{rendered}</article>;
+
+// With custom components
+import { FeatureCard } from './components/custom';
+const { rendered } = await renderMdx(content.mdx, references, {
+  additionalComponents: { FeatureCard },
+});
 ```
 
-### create-data-type
+## API Reference
 
-Create a new data type.
+### Content Fetching
 
-```bash
-cmx-sdk create-data-type --json '{"slug":"staff","name":"スタッフ","fields":[...]}'
+```tsx
+import {
+  getCollectionContents,
+  getCollectionContentDetail,
+  getDataEntries,
+  getDataEntry,
+  getPreviewByToken,
+} from 'cmx-sdk';
+
+// Get contents from a collection
+const { contents } = await getCollectionContents('blog');
+
+// Get a specific content with resolved references
+const { content, references } = await getCollectionContentDetail('blog', 'my-post');
+
+// Get data entries (custom data types)
+const { items } = await getDataEntries('team-members');
+
+// Get data entries with options
+const { items } = await getDataEntries('team-members', {
+  sortBy: 'createdAt',
+  sortOrder: 'desc',
+  limit: 10,
+});
+
+// Get a specific data entry
+const entry = await getDataEntry('team-members', 'entry-id');
+
+// Get preview content by token (no auth required)
+const preview = await getPreviewByToken(token);
+if (preview) {
+  const { content } = await renderMdx(preview.content.mdx, preview.references);
+}
+```
+
+### MDX Rendering
+
+```tsx
+import { renderMdx, renderMdxPreview } from 'cmx-sdk';
+
+// Full rendering with reference resolution
+const { content, references } = await renderMdx(item.mdx, item.references);
+
+// With custom components injected
+const { content } = await renderMdx(item.mdx, item.references, {
+  additionalComponents: { FeatureCard, PricingTable },
+});
+
+// Preview rendering (no reference resolution)
+const element = await renderMdxPreview(mdxString);
+```
+
+### Cache Tags
+
+Use Next.js cache tags for on-demand revalidation:
+
+```tsx
+import { CACHE_TAGS, sdkFetchWithTags } from 'cmx-sdk';
+
+// Built-in cache tags used by convenience functions:
+// CACHE_TAGS.collections       - all collections
+// CACHE_TAGS.collection(slug)  - specific collection
+// CACHE_TAGS.content(col, content) - specific content
+// CACHE_TAGS.data              - all data types
+// CACHE_TAGS.dataType(slug)    - specific data type
+
+// Revalidate by tag
+import { revalidateTag } from 'next/cache';
+revalidateTag(CACHE_TAGS.collection('blog'));
+
+// Low-level: fetch with custom cache tags
+const data = await sdkFetchWithTags<T>(
+  '/collections/blog/contents',
+  [CACHE_TAGS.collections, CACHE_TAGS.collection('blog')]
+);
+```
+
+### Preview Mode
+
+```tsx
+import { getPreviewByToken, renderMdx } from 'cmx-sdk';
+
+const preview = await getPreviewByToken(token);
+if (preview) {
+  const { content } = await renderMdx(preview.content.mdx, preview.references);
+  return <article>{content}</article>;
+}
+```
+
+## Components
+
+The SDK includes MDX components that are automatically available in `renderMdx`:
+
+### Standard Components
+
+- `Callout` - Highlighted information boxes (info, warning, error, success)
+- `Embed` - External content embedding (YouTube, Twitter, etc.)
+- `Button` - Interactive buttons
+
+### Reference-Resolving Components
+
+These components automatically resolve references from the API response:
+
+- `BlogCard` - Linked content cards (resolves content title, slug, description)
+- `Image` - Asset images with variants (resolves URL, alt text, dimensions)
+
+### Component Catalog
+
+Access component metadata and validation:
+
+```tsx
+import {
+  componentCatalog,
+  isValidComponent,
+  validateComponentProps,
+  validateMdx,
+} from 'cmx-sdk';
+
+// Check if a component is valid
+isValidComponent('Callout'); // true
+
+// Validate component props
+const result = validateComponentProps('Callout', {
+  type: 'info',
+  title: 'Note',
+});
+
+// Validate entire MDX content
+const validation = validateMdx(mdxString);
 ```
 
-### create-form
+## Code Generation (CLI)
+
+Generate typed functions and interfaces from your CMX data types and collections.
 
-Create a new form definition.
+### Usage
 
 ```bash
-cmx-sdk create-form --json '{"slug":"contact","name":"お問い合わせ","fields":[...]}'
+npx cmx-sdk generate
 ```
 
-### sync-components
+This fetches your workspace's schema from the CMX API and generates TypeScript files in `cmx/generated/`.
 
-Sync custom components.
+### Options
 
 ```bash
-# From file
-cmx-sdk sync-components --file components.json
+npx cmx-sdk generate --output src/cmx/generated   # Custom output directory
+```
 
-# From JSON string
-cmx-sdk sync-components --json '{"components":[...]}'
+### Requirements
+
+Set `CMX_API_URL` and `CMX_API_KEY` in your `.env` or `.env.local`:
+
+```env
+CMX_API_URL=https://your-cmx-admin.example.com
+CMX_API_KEY=your_api_key_here
 ```
 
-### import-schema
+### Generated Output
 
-Import collections, data types, and forms from a schema file.
+```
+cmx/generated/
+├── index.ts
+├── collections/
+│   ├── index.ts
+│   ├── blog.ts          # getBlogContents(), getBlogContentDetail()
+│   └── docs.ts          # getDocsContents(), getDocsContentDetail()
+└── data-types/
+    ├── index.ts
+    ├── team-members.ts   # TeamMember type, getTeamMembers(), getTeamMember()
+    └── faq.ts            # Faq type, getFaqs(), getFaq()
+```
 
-```bash
-cmx-sdk import-schema --file schema.json
-```
-
-**schema.json format:**
-
-```json
-{
-  "collections": [
-    { "type": "post", "slug": "blog", "name": "ブログ" }
-  ],
-  "dataTypes": [
-    { "slug": "staff", "name": "スタッフ", "fields": [...] }
-  ],
-  "forms": [
-    { "slug": "contact", "name": "お問い合わせ", "fields": [...] }
-  ]
+### Using Generated Code
+
+```tsx
+// Before (generic, no type safety)
+import { getDataEntries } from "cmx-sdk"
+const { items } = await getDataEntries("team-members")
+const name = items[0].name // ❌ type is unknown
+
+// After (typed, auto-generated)
+import { getTeamMembers } from "./cmx/generated"
+const { items } = await getTeamMembers()
+const name = items[0].name // ✅ type is string
+```
+
+Data type fields are mapped to TypeScript types:
+
+| Field Type | TypeScript Type |
+|---|---|
+| text, textarea, richtext, url, email | `string` |
+| number | `number` |
+| boolean | `boolean` |
+| date, datetime | `string` |
+| select (with choices) | `"value1" \| "value2"` |
+| multiselect | `string[]` or union array |
+| image, file | `string` |
+| relation | `string` (or `string[]` if multiple) |
+| json | `unknown` |
+
+Non-required fields are typed as `T | null`.
+
+## TypeScript
+
+The SDK is fully typed. Import types as needed:
+
+```tsx
+import type {
+  // API response types
+  CollectionContentsResponse,
+  CollectionContentDetailResponse,
+  DataListResponse,
+  DataEntryItem,
+  PreviewResponse,
+  References,
+  ContentReference,
+  AssetReference,
+  // Rendering types
+  RenderResult,
+  RenderOptions,
+  ResolvedReferences,
+  // Component types
+  ComponentDefinition,
+  ValidationResult,
+} from 'cmx-sdk';
+```
+
+## Advanced Usage
+
+### Low-Level Generated Functions
+
+For advanced use cases, the SDK also exports the raw Orval-generated endpoint functions:
+
+```tsx
+import {
+  getCollectionsSlugContents,
+  getCollectionsSlugContentsContentSlug,
+  getDataTypeSlug,
+  getPreviewToken,
+} from 'cmx-sdk';
+
+// These return { data, status, headers } instead of just the data
+const response = await getCollectionsSlugContents('blog');
+if (response.status === 200) {
+  const contents = response.data;
 }
 ```
 
-## Development
+### Direct Fetcher Access
 
-```bash
-# Build
-npm run build
+```tsx
+import {
+  sdkFetcher,
+  sdkFetchWithTags,
+  getSdkApiBaseUrl,
+  getSdkApiToken,
+} from 'cmx-sdk';
+
+// Use the fetcher directly for custom endpoints
+const data = await sdkFetchWithTags<MyType>('/custom/endpoint', ['my-tag']);
+```
+
+## Environment Variables
+
+| Variable | Description | Required |
+|----------|-------------|----------|
+| `CMX_API_URL` | CMX Admin API base URL | Yes |
+| `CMX_API_KEY` | API key for authentication | Yes |
+
+## Next.js Integration
+
+The SDK is optimized for Next.js App Router (Server Components):
+
+```tsx
+// app/blog/[slug]/page.tsx
+import { getCollectionContents, getCollectionContentDetail, renderMdx } from 'cmx-sdk';
 
-# Watch mode
-npm run dev
+export default async function BlogContent({
+  params,
+}: {
+  params: Promise<{ slug: string }>;
+}) {
+  const { slug } = await params;
+  const { content, references } = await getCollectionContentDetail('blog', slug);
+  const { content: rendered } = await renderMdx(content.mdx, references);
 
-# Clean
-npm run clean
+  return (
+    <article>
+      <h1>{content.title}</h1>
+      <p>{content.description}</p>
+      <div className="prose">{rendered}</div>
+    </article>
+  );
+}
+
+export async function generateStaticParams() {
+  const { contents } = await getCollectionContents('blog');
+  return contents.map((item) => ({ slug: item.slug }));
+}
+
+export async function generateMetadata({
+  params,
+}: {
+  params: Promise<{ slug: string }>;
+}) {
+  const { slug } = await params;
+  const { content } = await getCollectionContentDetail('blog', slug);
+  return {
+    title: content.title,
+    description: content.description,
+  };
+}
 ```
+
+## Examples
+
+Check out the [CMX Starter Kit](https://github.com/kzkm-lab/cmx-starter-kit) for a complete example of using the SDK.
+
+## License
+
+MIT
+
+## Links
+
+- [Documentation](https://github.com/kzkm-lab/cmx)
+- [CMX Starter Kit](https://github.com/kzkm-lab/cmx-starter-kit)
+- [Issues](https://github.com/kzkm-lab/cmx/issues)