appwrite-utils-cli/.appwrite/import/README.md

Appwrite Utility Functions to help with database management, data conversion, data import, migrations, and much more. Meant to be used as a CLI tool, I do not recommend installing this in frontend environments.

# Import Configurations

This directory contains YAML-based import configurations that demonstrate the powerful import capabilities of Appwrite Utils CLI 1.0.0.

## Available Import Configurations

### 1. Users Import (`users-import.yaml`)
- **Purpose**: Import user data with avatar file downloads
- **Features**:
  - Downloads avatar images from picsum.photos URLs
  - Creates user accounts in Appwrite Auth
  - Validates email addresses and phone numbers
  - Handles user deduplication based on email
  - Converts social links and preferences JSON
- **Data Source**: `importData/users.json` (12 sample users)

### 2. Categories Import (`categories-import.yaml`)
- **Purpose**: Import hierarchical category structure
- **Features**:
  - Downloads cover images from URLs
  - Handles parent-child relationships
  - Supports category hierarchy up to 5 levels
  - SEO metadata handling
- **Data Source**: `importData/categories.json` (10 categories with hierarchy)

### 3. Posts Import (`posts-import.yaml`)
- **Purpose**: Import blog posts with relationships and media
- **Features**:
  - Downloads featured images and gallery images
  - Links posts to authors (Users collection)
  - Links posts to categories (Categories collection)
  - Handles arrays (tags, gallery)
  - Rich content with HTML support
  - SEO metadata and social sharing images
- **Data Source**: `importData/posts.json` (10 blog posts)

## File Handling Features

All import configurations demonstrate advanced file handling:

- **URL Downloads**: Automatically downloads images from picsum.photos
- **File Naming**: Uses template patterns like `{user_id}_avatar`
- **Multiple Files**: Supports gallery arrays with multiple images
- **File Validation**: Handles missing or invalid URLs gracefully
- **Storage Integration**: Uploads to appropriate Appwrite storage buckets

## Usage

### Run Individual Imports
```bash
# Import users with avatars
npx appwrite-utils-cli appwrite-migrate --import --collectionIds Users

# Import categories with hierarchy
npx appwrite-utils-cli appwrite-migrate --import --collectionIds Categories

# Import posts with relationships
npx appwrite-utils-cli appwrite-migrate --import --collectionIds Posts
```

### Run All Imports
```bash
# Import all collections in order
npx appwrite-utils-cli appwrite-migrate --import --dbIds main
```

## Import Order

For best results, import in this order due to relationships:

1. **Users** (no dependencies)
2. **Categories** (self-referential relationships)
3. **Posts** (depends on Users and Categories)

## Configuration Highlights

### Rate Limiting
- **Users**: 25 items per batch (avatar downloads)
- **Categories**: 50 items per batch (cover images)
- **Posts**: 20 items per batch (multiple images per post)

### Validation
- Email validation for users
- URL validation for file downloads
- Required field validation
- Length constraints for text fields

### Relationships
- **Posts → Users**: Author relationship via userId
- **Posts → Categories**: Category relationship via categoryId
- **Categories → Categories**: Parent-child hierarchy

### File Downloads
- **User avatars**: 500x500 images from picsum.photos
- **Category covers**: 800x400 images from picsum.photos
- **Post images**: Various sizes (1200x600, 800x400, etc.)
- **Social images**: 1200x630 for social media sharing

## Testing

### Dry Run
Test configurations without actual import:
```bash
npx appwrite-utils-cli appwrite-migrate --import --dryRun
```

### Validation Only
Validate data without importing:
```bash
npx appwrite-utils-cli appwrite-migrate --writeData
```

## Customization

These configurations serve as examples. You can:

1. **Modify data sources**: Update file paths in YAML configs
2. **Add/remove fields**: Modify attribute mappings
3. **Change validation rules**: Add or remove validation constraints
4. **Adjust batch sizes**: Optimize for your server capacity
5. **Add custom converters**: Extend data transformation logic

## File Structure

```
.appwrite/
├── collections/           # YAML collection definitions
│   ├── Users.yaml
│   ├── Posts.yaml
│   └── Categories.yaml
├── importData/           # Source data files
│   ├── users.json
│   ├── posts.json
│   └── categories.json
├── import/               # Import configurations
│   ├── users-import.yaml
│   ├── posts-import.yaml
│   └── categories-import.yaml
└── config.yaml          # Main project configuration
```

## Support

For questions about the import system:
- Check the main README.md for CLI usage
- Review YAML schema files in `.yaml_schemas/`
- See example configurations in this directory
- Test with `--dryRun` flag before actual import