cmx-sdk 0.1.1 → 0.1.3

package/README.md

@@ -1,393 +1,95 @@
-# cmx-sdk
+# CMX SDK
 
-Official SDK for building content-driven websites with CMX (Content Management Experience).
+CLI tool for managing CMX schemas and content.
 
 ## Installation
 
 ```bash
 npm install cmx-sdk
-# or
-pnpm add cmx-sdk
-# or
-yarn add cmx-sdk
 ```
 
-## Features
-
-- 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:
+## Environment Variables
 
-```env
-CMX_API_URL=https://your-cmx-admin.example.com
+```bash
+CMX_API_URL=https://your-api-url.com
 CMX_API_KEY=your_api_key_here
 ```
 
-### 2. Fetch content
-
-```tsx
-import { getCollectionPosts, getCollectionPostDetail } from 'cmx-sdk';
-
-// List posts in a collection
-const { collection, posts } = await getCollectionPosts('blog');
-
-// Get a specific post with references
-const { collection, post, references } = await getCollectionPostDetail('blog', 'my-post');
-```
-
-### 3. Render MDX content
-
-```tsx
-import { renderMdx } from 'cmx-sdk';
-
-// Render MDX with reference resolution (BlogCard, Image, etc.)
-const { content } = await renderMdx(post.mdx, references);
-return <article>{content}</article>;
-
-// With custom components
-import { FeatureCard } from './components/custom';
-const { content } = await renderMdx(post.mdx, references, {
-  additionalComponents: { FeatureCard },
-});
-```
-
-## API Reference
-
-### Content Fetching
-
-```tsx
-import {
-  getCollectionPosts,
-  getCollectionPostDetail,
-  getDataEntries,
-  getDataEntry,
-  getPreviewByToken,
-} from 'cmx-sdk';
-
-// Get posts from a collection
-const { posts } = await getCollectionPosts('blog');
-
-// Get a specific post with resolved references
-const { post, references } = await getCollectionPostDetail('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.post.mdx, preview.references);
-}
-```
-
-### MDX Rendering
-
-```tsx
-import { renderMdx, renderMdxPreview } from 'cmx-sdk';
-
-// Full rendering with reference resolution
-const { content, references } = await renderMdx(post.mdx, post.references);
-
-// With custom components injected
-const { content } = await renderMdx(post.mdx, post.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, publicFetchWithTags } from 'cmx-sdk';
-
-// Built-in cache tags used by convenience functions:
-// CACHE_TAGS.collections       - all collections
-// CACHE_TAGS.collection(slug)  - specific collection
-// CACHE_TAGS.post(col, post)   - specific post
-// 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 publicFetchWithTags<T>(
-  '/collections/blog/posts',
-  [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.post.mdx, preview.references);
-  return <article>{content}</article>;
-}
-```
-
-## Components
-
-The SDK includes MDX components that are automatically available in `renderMdx`:
-
-### Standard Components
+## Commands
 
-- `Callout` - Highlighted information boxes (info, warning, error, success)
-- `Embed` - External content embedding (YouTube, Twitter, etc.)
-- `Button` - Interactive buttons
+### create-collection
 
-### Reference-Resolving Components
+Create a new collection.
 
-These components automatically resolve references from the API response:
-
-- `BlogCard` - Linked post cards (resolves post 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',
-});
+```bash
+# Using JSON
+cmx-sdk create-collection --json '{"type":"post","slug":"blog","name":"ブログ"}'
 
-// Validate entire MDX content
-const validation = validateMdx(mdxString);
+# Using individual options
+cmx-sdk create-collection --type post --slug blog --name ブログ --description "ブログ記事"
 ```
 
-## Code Generation (CLI)
-
-Generate typed functions and interfaces from your CMX data types and collections.
+### create-data-type
 
-### Usage
+Create a new data type.
 
 ```bash
-npx cmx-sdk generate
+cmx-sdk create-data-type --json '{"slug":"staff","name":"スタッフ","fields":[...]}'
 ```
 
-This fetches your workspace's schema from the CMX API and generates TypeScript files in `generated/cmx/`.
+### create-form
 
-### Options
+Create a new form definition.
 
 ```bash
-npx cmx-sdk generate --output src/generated/cmx   # Custom output directory
-```
-
-### 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
-```
-
-### Generated Output
-
-```
-generated/cmx/
-├── index.ts
-├── collections/
-│   ├── index.ts
-│   ├── blog.ts          # getBlogPosts(), getBlogPostDetail()
-│   └── docs.ts          # getDocsPosts(), getDocsPostDetail()
-└── data-types/
-    ├── index.ts
-    ├── team-members.ts   # TeamMember type, getTeamMembers(), getTeamMember()
-    └── faq.ts            # Faq type, getFaqs(), getFaq()
-```
-
-### 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 "./generated/cmx"
-const { items } = await getTeamMembers()
-const name = items[0].name // ✅ type is string
+cmx-sdk create-form --json '{"slug":"contact","name":"お問い合わせ","fields":[...]}'
 ```
 
-Data type fields are mapped to TypeScript types:
+### sync-components
 
-| 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` |
+Sync custom components.
 
-Non-required fields are typed as `T | null`.
-
-## TypeScript
-
-The SDK is fully typed. Import types as needed:
+```bash
+# From file
+cmx-sdk sync-components --file components.json
 
-```tsx
-import type {
-  // API response types
-  CollectionPostsResponse,
-  CollectionPostDetailResponse,
-  DataListResponse,
-  DataEntryItem,
-  PreviewResponse,
-  References,
-  PostReference,
-  AssetReference,
-  // Rendering types
-  RenderResult,
-  RenderOptions,
-  ResolvedReferences,
-  // Component types
-  ComponentDefinition,
-  ValidationResult,
-} from 'cmx-sdk';
+# From JSON string
+cmx-sdk sync-components --json '{"components":[...]}'
 ```
 
-## Advanced Usage
+### import-schema
 
-### Low-Level Generated Functions
+Import collections, data types, and forms from a schema file.
 
-For advanced use cases, the SDK also exports the raw Orval-generated endpoint functions:
-
-```tsx
-import {
-  getCollectionsSlugPosts,
-  getCollectionsSlugPostsContentSlug,
-  getDataTypeSlug,
-  getPreviewToken,
-} from 'cmx-sdk';
-
-// These return { data, status, headers } instead of just the data
-const response = await getCollectionsSlugPosts('blog');
-if (response.status === 200) {
-  const posts = response.data;
+```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": [...] }
+  ]
 }
 ```
 
-### Direct Fetcher Access
-
-```tsx
-import {
-  publicFetcher,
-  publicFetchWithTags,
-  getPublicApiBaseUrl,
-  getPublicApiToken,
-} from 'cmx-sdk';
-
-// Use the fetcher directly for custom endpoints
-const data = await publicFetchWithTags<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 { getCollectionPosts, getCollectionPostDetail, renderMdx } from 'cmx-sdk';
+## Development
 
-export default async function BlogPost({
-  params,
-}: {
-  params: Promise<{ slug: string }>;
-}) {
-  const { slug } = await params;
-  const { post, references } = await getCollectionPostDetail('blog', slug);
-  const { content } = await renderMdx(post.mdx, references);
-
-  return (
-    <article>
-      <h1>{post.title}</h1>
-      <p>{post.description}</p>
-      <div className="prose">{content}</div>
-    </article>
-  );
-}
+```bash
+# Build
+npm run build
 
-export async function generateStaticParams() {
-  const { posts } = await getCollectionPosts('blog');
-  return posts.map((post) => ({ slug: post.slug }));
-}
+# Watch mode
+npm run dev
 
-export async function generateMetadata({
-  params,
-}: {
-  params: Promise<{ slug: string }>;
-}) {
-  const { slug } = await params;
-  const { post } = await getCollectionPostDetail('blog', slug);
-  return {
-    title: post.title,
-    description: post.description,
-  };
-}
+# Clean
+npm run clean
 ```
-
-## 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)

package/dist/cli.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};