npm package: @kouovo/ph-vite-plugin-editor-api
Description: A Vite plugin that provides a complete JSON and image editing API with a web-based frontend interface for development environments.
Latest version: 0.1.46

# @kouovo/ph-vite-plugin-editor-api

A Vite plugin that provides a complete JSON and image editing API with a web-based frontend interface for development environments.

## Overview

The `@kouovo/ph-vite-plugin-editor-api` package is a comprehensive Vite plugin that creates REST API endpoints for editing JSON files and managing images, along with a built-in web interface for easy file management during development.

## Installation

```bash
npm install @kouovo/ph-vite-plugin-editor-api
# or
pnpm add @kouovo/ph-vite-plugin-editor-api
# or
yarn add @kouovo/ph-vite-plugin-editor-api
```

## Usage

### Basic Configuration

```javascript
// vite.config.js
import { defineConfig } from 'vite';
import { ViteResourcesEditorApi } from '@kouovo/ph-vite-plugin-editor-api';

export default defineConfig({
  plugins: [
    ViteResourcesEditorApi({
      jsonDirectoryPath: './src/data',
      imagesDirectoryPath: './src/assets/images',
      apiBasePath: '/api/editable-json',
      frontendPath: '/json-editor',
      maxImageSize: 5 * 1024 * 1024, // 5MB
      allowedImageTypes: ['image/jpeg', 'image/png', 'image/gif', 'image/webp', 'image/svg+xml']
    })
  ]
});
```

### Alternative JSON-Only Configuration

```javascript
// For JSON editing only (without image features)
import { ViteJsonEditorApi } from '@kouovo/ph-vite-plugin-editor-api';

export default defineConfig({
  plugins: [
    ViteJsonEditorApi({
      directoryPath: './src/data',
      apiBasePath: '/api/json-editor',
      frontendPath: '/json-editor'
    })
  ]
});
```

## Configuration Options

### ViteResourcesEditorApi Options

| Option | Type | Default | Description |
|--------|------|---------|-------------|
| `jsonDirectoryPath` | `string` | **Required** | Path to directory containing JSON files |
| `imagesDirectoryPath` | `string` | **Required** | Path to directory containing image files |
| `apiBasePath` | `string` | `'/api/editable-json'` | Base path for API endpoints |
| `frontendPath` | `string \| null` | `'/json-editor'` | Path for web interface (null to disable) |
| `maxImageSize` | `number` | `1073741824` (1GB) | Maximum image upload size in bytes |
| `allowedImageTypes` | `string[]` | `['image/jpeg', 'image/png', 'image/gif', 'image/webp', 'image/svg+xml']` | Allowed image MIME types |

### ViteJsonEditorApi Options

| Option | Type | Default | Description |
|--------|------|---------|-------------|
| `directoryPath` | `string` | **Required** | Path to directory containing JSON files |
| `apiBasePath` | `string` | `'/api/editable-json'` | Base path for API endpoints |
| `frontendPath` | `string \| null` | `'/json-editor'` | Path for web interface (null to disable) |

## API Endpoints

### JSON Management Endpoints

#### GET `/api/editable-json/list`
Lists all JSON files in the configured directory.

**Response:**
```json
["config.json", "data.json", "settings.json"]
```

#### GET `/api/editable-json/get?filename={filename}`
Retrieves the content of a specific JSON file.

**Parameters:**
- `filename` (query): Name of the JSON file to retrieve

**Response:**
```json
{
  "key1": "value1",
  "key2": "value2",
  "nested": {
    "property": "value"
  }
}
```

#### POST `/api/editable-json/save?filename={filename}`
Saves content to a JSON file and synchronizes keys across other JSON files.

**Parameters:**
- `filename` (query): Name of the JSON file to save

**Request Body:**
```json
{
  "key1": "updated value",
  "key2": "value2",
  "newKey": "new value"
}
```

**Features:**
- Validates JSON structure
- Automatically adds missing keys to other JSON files
- Pretty-prints JSON output
- Atomic file operations

### Image Management Endpoints

#### GET `/api/editable-json/images/list`
Lists all supported image files in the configured directory.

**Response:**
```json
["logo.png", "banner.jpg", "icon.svg"]
```

#### GET `/api/editable-json/images/view/{filename}`
Serves an image file with proper MIME type and caching headers.

**Parameters:**
- `filename` (path): Name of the image file to serve

**Features:**
- Automatic MIME type detection
- Security validation
- Caching headers
- Path traversal protection

#### POST `/api/editable-json/images/upload`
Uploads one or more image files with validation and security checks.

**Request:** `multipart/form-data`
- `image` (file): Image file(s) to upload (multiple files supported)

**Response:**
```json
{
  "message": "Processed 2 file(s). 2 succeeded, 0 failed.",
  "results": [
    {
      "originalFilename": "photo.jpg",
      "filename": "photo.jpg",
      "success": true,
      "message": "Uploaded successfully."
    }
  ]
}
```

**Features:**
- Multiple file upload support
- File type validation
- Size limit enforcement
- Secure filename sanitization
- Detailed upload results

#### DELETE `/api/editable-json/images/delete?filename={filename}`
Deletes an image file from the directory.

**Parameters:**
- `filename` (query): Name of the image file to delete

**Response:**
```json
{
  "message": "Image 'filename.jpg' deleted successfully."
}
```

## Web Interface Features

### JSON Editor
- **Interactive Key-Value Editor**: Visual editor for JSON object properties
- **Real-time Validation**: Immediate feedback on JSON syntax errors
- **Change Detection**: Tracks unsaved changes with visual indicators
- **File Management**: Switch between multiple JSON files
- **Auto-sync**: Automatically propagates new keys to other JSON files

### Image Manager
- **Visual Gallery**: Grid view of all available images
- **Drag & Drop Upload**: Support for multiple file uploads
- **Image Previews**: Thumbnails with click-to-enlarge modal
- **Integration**: Direct image filename insertion into JSON values
- **File Management**: Delete images with confirmation

### Advanced Features
- **Responsive Design**: Works on desktop and mobile devices
- **Keyboard Shortcuts**: Efficient navigation and editing
- **Progress Indicators**: Real-time feedback for uploads and operations
- **Error Handling**: Comprehensive error messages and recovery
- **Accessibility**: WCAG compliant interface elements

## Security Features

### Input Validation
- **JSON Structure Validation**: Ensures valid JSON object format
- **Filename Sanitization**: Prevents path traversal attacks
- **File Type Validation**: Strict MIME type checking
- **Size Limits**: Configurable upload size restrictions

### Path Security
- **Directory Containment**: Operations limited to configured directories
- **Filename Restrictions**: Blocks dangerous characters and patterns
- **Extension Validation**: Only allows specified file extensions
- **Buffer Analysis**: Uses file-type detection for robust validation

## Development Features

### Hot Reload Support
- **File Watching**: Automatically reflects external file changes
- **State Persistence**: Maintains editor state across reloads
- **Error Recovery**: Graceful handling of file system changes

### Integration
- **Vite Plugin API**: Full integration with Vite development server
- **Middleware Support**: Custom request processing
- **Error Handling**: Comprehensive error reporting and logging

## Error Handling

The plugin includes comprehensive error handling for:
- **File System Errors**: Missing files, permission issues
- **Validation Errors**: Invalid JSON format, unsupported file types
- **Network Errors**: Upload failures, connection issues
- **Security Errors**: Path traversal attempts, unauthorized access

## Performance Optimizations

- **Parallel Operations**: Concurrent file processing
- **Efficient Caching**: Optimized file serving with cache headers
- **Memory Management**: Streaming file operations where possible
- **Lazy Loading**: On-demand resource loading in the frontend

## TypeScript Support

The package is fully typed with comprehensive TypeScript definitions:
- Configuration option interfaces
- API response types
- Error handling types
- Plugin integration types

## Browser Support

- Modern browsers with ES6+ support
- File API for drag & drop uploads
- Fetch API for HTTP requests
- Grid and Flexbox CSS support

## Development Commands

```bash
# Build the plugin
npm run build

# Type checking
npm run typecheck

# Development (if using examples)
npm run dev
```

## License

MIT