we0-cms-api/README.md

A CMS API package for Next.js applications with dynamic table management

# we0-cms-api

A powerful CMS API package for Next.js applications with dynamic table management and PostgreSQL support.

## Features

- 🚀 Dynamic table creation and management
- 📊 RESTful API for models and data operations
- 🔧 TypeScript support with full type definitions
- 💾 PostgreSQL database with Sequelize ORM
- 🎯 Easy integration with Next.js API routes
- 📝 Comprehensive CRUD operations

## Installation

```bash
npm install we0-cms-api
# or
yarn add we0-cms-api
# or
pnpm add we0-cms-api
```

### Peer Dependencies

Make sure you have the following peer dependencies installed:

```bash
npm install next sequelize pg pg-hstore
```

## Quick Start

### 1. Database Configuration

First, initialize the database connection in your Next.js app:

```typescript
// lib/cms-config.ts
import { initializeDatabase, DatabaseConfig } from 'we0-cms-api'

const dbConfig: DatabaseConfig = {
  host: process.env.DB_HOST || 'localhost',
  port: parseInt(process.env.DB_PORT || '5432'),
  database: process.env.DB_NAME || 'cms_db',
  username: process.env.DB_USER || 'postgres',
  password: process.env.DB_PASSWORD || 'password',
  logging: process.env.NODE_ENV === 'development'
}

// Initialize database connection
initializeDatabase(dbConfig)
```

### 2. Create API Routes

#### Models Management API

Create `app/api/cms/models/route.ts`:

```typescript
import { createModelRoute } from 'we0-cms-api'

export const { GET, POST, PUT, DELETE } = createModelRoute()
```

#### Dynamic Data Management API

Create `app/api/cms/data/[tableName]/route.ts`:

```typescript
import { createDynamicDataRoute } from 'we0-cms-api'

export const { GET, POST, PUT, DELETE } = createDynamicDataRoute()
```

#### Alternative: One-liner Setup

Use the convenience function to create all routes at once:

```typescript
// app/api/cms/models/route.ts
import { createCmsRoutes } from 'we0-cms-api'

const routes = createCmsRoutes()
export const { GET, POST, PUT, DELETE } = routes.models
```

```typescript
// app/api/cms/data/[tableName]/route.ts  
import { createCmsRoutes } from 'we0-cms-api'

const routes = createCmsRoutes()
export const { GET, POST, PUT, DELETE } = routes.data
```

## API Usage

### Models API

#### GET `/api/cms/models` - Get all models
```bash
curl "http://localhost:3000/api/cms/models?page=1&limit=10&name=user"
```

#### POST `/api/cms/models` - Create a new model
```bash
curl -X POST "http://localhost:3000/api/cms/models" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "用户模型",
    "table_name": "users",
    "json_schema": {
      "fields": [
        {
          "name": "name",
          "type": "string",
          "required": true,
          "maxLength": 100,
          "comment": "用户姓名"
        },
        {
          "name": "email",
          "type": "email",
          "unique": true,
          "required": true,
          "comment": "用户邮箱"
        },
        {
          "name": "age",
          "type": "integer",
          "comment": "年龄"
        }
      ]
    }
  }'
```

#### PUT `/api/cms/models` - Update a model
```bash
curl -X PUT "http://localhost:3000/api/cms/models" \
  -H "Content-Type: application/json" \
  -d '{
    "id": 1,
    "name": "更新的用户模型"
  }'
```

#### DELETE `/api/cms/models?id=1` - Delete a model
```bash
curl -X DELETE "http://localhost:3000/api/cms/models?id=1"
```

### Data API

#### GET `/api/cms/data/users` - Get table data
```bash
curl "http://localhost:3000/api/cms/data/users?page=1&limit=10&search=john"
```

#### POST `/api/cms/data/users` - Create new data
```bash
curl -X POST "http://localhost:3000/api/cms/data/users" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "John Doe",
    "email": "john@example.com",
    "age": 30
  }'
```

#### PUT `/api/cms/data/users` - Update data
```bash
curl -X PUT "http://localhost:3000/api/cms/data/users" \
  -H "Content-Type: application/json" \
  -d '{
    "id": 1,
    "name": "John Smith",
    "age": 31
  }'
```

#### DELETE `/api/cms/data/users?id=1` - Delete data
```bash
curl -X DELETE "http://localhost:3000/api/cms/data/users?id=1"
```

## Advanced Usage

### Custom Service Usage

```typescript
import { 
  initializeDatabase, 
  getDynamicTableService, 
  initializeCmsModel,
  DatabaseConfig 
} from 'we0-cms-api'

// Initialize database
const dbConfig: DatabaseConfig = { /* your config */ }
initializeDatabase(dbConfig)

// Use the dynamic table service directly
const tableService = getDynamicTableService()

// Create a custom table
await tableService.createTable('custom_table', {
  fields: [
    { name: 'title', type: 'string', required: true },
    { name: 'content', type: 'text' }
  ]
})

// Use the CMS model directly
const CmsModel = initializeCmsModel()
const models = await CmsModel.findAll()
```

### Type Definitions

```typescript
import type { 
  JsonSchema, 
  SchemaField, 
  CmsModelAttributes,
  ApiResponse,
  PaginatedResponse 
} from 'we0-cms-api'

// Define your schema
const userSchema: JsonSchema = {
  fields: [
    {
      name: 'username',
      type: 'string',
      required: true,
      unique: true,
      maxLength: 50
    },
    {
      name: 'profile',
      type: 'json'
    }
  ]
}
```

## Environment Variables

Create a `.env.local` file in your project root:

```env
DB_HOST=localhost
DB_PORT=5432
DB_NAME=cms_db
DB_USER=postgres
DB_PASSWORD=your_password
```

## Field Types

Supported field types for JSON schema:

- `string` - Variable length string
- `text` - Long text
- `integer` - Integer number
- `float` - Floating point number
- `boolean` - True/false value
- `date` - Date only
- `datetime` - Date and time
- `json` - JSON object
- `email` - Email string (validated as string)

## Error Handling

All API responses follow a consistent format:

```typescript
interface ApiResponse<T = any> {
  success: boolean
  message?: string
  data?: T
  error?: string
}
```

## Contributing

1. Fork the repository
2. Create your feature branch (`git checkout -b feature/amazing-feature`)
3. Commit your changes (`git commit -m 'Add some amazing feature'`)
4. Push to the branch (`git push origin feature/amazing-feature`)
5. Open a Pull Request

## License

MIT

## Support

For support, please open an issue on the GitHub repository or contact the maintainers.