@xenterprises/fastify-ximagepipeline 1.1.0 → 1.1.1

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@xenterprises/fastify-ximagepipeline",
   "type": "module",
-  "version": "1.1.0",
+  "version": "1.1.1",
   "description": "Fastify plugin for image uploads with EXIF stripping, moderation, variant generation, and R2 storage with job queue",
   "main": "src/xImagePipeline.js",
   "exports": {

package/FILES.md

@@ -1,212 +0,0 @@
-# xMedia Plugin - File Listing
-
-## Core Files
-
-### Main Plugin
-- **src/xMedia.js** (145 lines)
-  - Plugin initialization and configuration
-  - Route registration
-  - Worker setup
-  - Variant presets
-
-### Services
-- **src/services/s3.js** (168 lines)
-  - R2/S3 client initialization
-  - Upload, download, delete operations
-  - Public URL generation
-  - Batch operations
-
-### Utilities
-- **src/utils/image.js** (230 lines)
-  - EXIF stripping
-  - Image metadata extraction
-  - Variant generation
-  - Blurhash generation
-  - Image validation
-
-### Routes
-- **src/routes/upload.js** (97 lines)
-  - POST /media/upload endpoint
-  - File validation
-  - Job creation
-  - 202 response
-
-- **src/routes/status.js** (77 lines)
-  - GET /media/status/:jobId endpoint
-  - Job status retrieval
-  - Media data response
-  - HTTP status codes
-
-### Workers
-- **src/workers/processor.js** (368 lines)
-  - Job queue polling
-  - Processing pipeline
-  - Pessimistic locking
-  - Error handling and retry
-  - Stale lock recovery
-
-## Configuration Files
-
-- **package.json** (40 lines)
-  - Dependencies and dev dependencies
-  - Scripts
-  - Package metadata
-
-- **SCHEMA.prisma** (76 lines)
-  - MediaStatus enum
-  - MediaQueue model
-  - Media model
-  - Database indexes
-  - Example relations
-
-## Documentation
-
-- **README.md** (500+ lines)
-  - Feature overview
-  - Installation guide
-  - Setup instructions
-  - API documentation
-  - Frontend examples
-  - Configuration guide
-  - Troubleshooting
-
-- **IMPLEMENTATION_SUMMARY.md** (400+ lines)
-  - Completed components
-  - Directory structure
-  - Processing pipeline
-  - Configuration options
-  - Quick start guide
-  - Design decisions
-  - Future enhancements
-
-- **INTEGRATION_GUIDE.md** (350+ lines)
-  - Step-by-step integration
-  - Environment setup
-  - Prisma schema addition
-  - Plugin registration
-  - Frontend examples
-  - R2 setup
-  - Troubleshooting
-  - Usage examples
-
-- **FILES.md** (this file)
-  - File listing and line counts
-
-## Testing
-
-- **test/xMedia.test.js** (280 lines)
-  - Plugin registration tests
-  - Configuration tests
-  - Route tests
-  - Variant preset tests
-
-## Statistics
-
-### Code Files
-- Total lines: ~1,200+
-- Files: 7 source files
-- Services: 1
-- Utilities: 1
-- Routes: 2
-- Workers: 1
-
-### Documentation
-- README: 500+ lines
-- Implementation Summary: 400+ lines
-- Integration Guide: 350+ lines
-- Total docs: 1,250+ lines
-
-### Total Project Size
-- Source code: 1,200+ lines
-- Tests: 280 lines
-- Documentation: 1,250+ lines
-- **Grand Total: 2,730+ lines**
-
-## Directory Tree
-
-```
-xMedia/
-├── src/
-│   ├── xMedia.js                    (145 lines) - Main plugin
-│   ├── services/
-│   │   └── s3.js                    (168 lines) - R2/S3 integration
-│   ├── utils/
-│   │   └── image.js                 (230 lines) - Image processing
-│   ├── routes/
-│   │   ├── upload.js                (97 lines) - Upload endpoint
-│   │   └── status.js                (77 lines) - Status endpoint
-│   └── workers/
-│       └── processor.js             (368 lines) - Job processor
-├── test/
-│   └── xMedia.test.js               (280 lines) - Test suite
-├── package.json                     (40 lines)
-├── SCHEMA.prisma                    (76 lines)
-├── README.md                        (500+ lines)
-├── IMPLEMENTATION_SUMMARY.md        (400+ lines)
-├── INTEGRATION_GUIDE.md             (350+ lines)
-└── FILES.md                         (this file)
-```
-
-## Feature Matrix
-
-| Feature | File | Status |
-|---------|------|--------|
-| Plugin initialization | xMedia.js | ✅ |
-| R2/S3 integration | services/s3.js | ✅ |
-| File uploads | routes/upload.js | ✅ |
-| Status checking | routes/status.js | ✅ |
-| EXIF stripping | utils/image.js | ✅ |
-| Variant generation | utils/image.js | ✅ |
-| Blurhash generation | utils/image.js | ✅ |
-| Image validation | utils/image.js | ✅ |
-| Job queueing | routes/upload.js | ✅ |
-| Worker processing | workers/processor.js | ✅ |
-| Moderation hooks | workers/processor.js | ✅ |
-| Retry logic | workers/processor.js | ✅ |
-| Lock management | workers/processor.js | ✅ |
-| Database models | SCHEMA.prisma | ✅ |
-| API documentation | README.md | ✅ |
-| Setup guide | INTEGRATION_GUIDE.md | ✅ |
-| Tests | test/xMedia.test.js | ✅ |
-
-## Implementation Status
-
-- ✅ Core plugin complete
-- ✅ S3/R2 integration complete
-- ✅ Image processing complete
-- ✅ Upload endpoint complete
-- ✅ Status endpoint complete
-- ✅ Worker processor complete
-- ✅ Database schema defined
-- ✅ Comprehensive documentation
-- ✅ Integration guide
-- ✅ Basic test suite
-- ⏳ Moderation API integration (hook exists, stub ready)
-- ⏳ Production monitoring setup
-- ⏳ CDN cache configuration
-
-## Ready for Production
-
-This plugin is production-ready with:
-- ✅ Complete error handling
-- ✅ Comprehensive logging
-- ✅ Database transactions
-- ✅ Job retry logic
-- ✅ Stale lock recovery
-- ✅ Rate limiting hooks
-- ✅ Security validation
-- ✅ CORS configuration
-- ✅ Performance optimization
-
-## Next Steps for User
-
-1. Copy files to your project
-2. Install dependencies
-3. Add Prisma schema
-4. Configure R2 bucket
-5. Register plugin
-6. Build frontend integration
-7. Deploy to production
-8. Monitor job queue
-
-**Total implementation time: ~2,730 lines of code and documentation**

package/IMPLEMENTATION_SUMMARY.md

@@ -1,427 +0,0 @@
-# xMedia Plugin - Implementation Summary
-
-## ✅ Completed Components
-
-### 1. **Core Plugin** ✅
-- **File**: `src/xMedia.js`
-- **Features**:
-  - Plugin initialization with comprehensive configuration
-  - R2 client setup
-  - Route registration
-  - Worker initialization and management
-  - Default variant specifications
-  - Variant presets (avatar, member_photo, gallery, hero, content)
-
-### 2. **R2/S3 Integration Service** ✅
-- **File**: `src/services/s3.js`
-- **Functions**:
-  - `initializeS3Client()` - Create S3 client for R2
-  - `uploadToS3()` - Upload file with metadata
-  - `downloadFromS3()` - Download file buffer
-  - `deleteFromS3()` - Delete single object
-  - `listFromS3()` - List objects with prefix
-  - `getSignedUrlForS3()` - Generate signed URLs for protected content
-  - `getPublicUrl()` - Generate public URL for media
-  - `batchDeleteFromS3()` - Delete multiple objects
-
-### 3. **Image Processing Utilities** ✅
-- **File**: `src/utils/image.js`
-- **Functions**:
-  - `stripExif()` - Remove EXIF metadata while preserving orientation
-  - `getImageMetadata()` - Extract image properties
-  - `generateVariants()` - Create WebP variants at multiple sizes
-  - `generateBlurhash()` - Generate loading placeholder
-  - `calculateFitDimensions()` - Calculate aspect-ratio-preserving dimensions
-  - `getAspectRatio()` - Get aspect ratio string
-  - `validateImage()` - Validate image dimensions and format
-
-### 4. **Upload Endpoint** ✅
-- **File**: `src/routes/upload.js`
-- **Route**: `POST /media/upload`
-- **Features**:
-  - Multipart file upload handling
-  - File type validation
-  - File size validation
-  - Source type validation
-  - Staging bucket upload
-  - MediaQueue job creation
-  - 202 Accepted response with jobId
-
-### 5. **Status Endpoint** ✅
-- **File**: `src/routes/status.js`
-- **Route**: `GET /media/status/:jobId`
-- **Features**:
-  - Job status retrieval
-  - Job progress tracking
-  - Result retrieval when complete
-  - Moderation details when rejected
-  - Error details when failed
-  - Appropriate HTTP status codes (202, 200, 400, 500)
-
-### 6. **Worker Processor** ✅
-- **File**: `src/workers/processor.js`
-- **Features**:
-  - Job queue polling
-  - Pessimistic locking (prevents duplicate processing)
-  - Job processing pipeline:
-    1. Download from staging
-    2. Strip EXIF
-    3. Content moderation (pluggable)
-    4. Generate variants
-    5. Generate blurhash
-    6. Upload to R2
-    7. Create Media record
-    8. Update job status
-    9. Cleanup staging
-  - Error handling with retry logic
-  - Stale lock recovery
-  - Worker lifecycle management
-
-### 7. **Prisma Schema** ✅
-- **File**: `SCHEMA.prisma`
-- **Models**:
-  - `MediaStatus` enum
-  - `MediaQueue` model with locking and retry tracking
-  - `Media` model with URLs, metadata, and focal points
-  - Database indexes for performance
-  - Example relations for User/Band integration
-
-### 8. **Package Configuration** ✅
-- **File**: `package.json`
-- **Dependencies**:
-  - @aws-sdk/client-s3
-  - @aws-sdk/s3-request-presigner
-  - blurhash
-  - fastify-plugin
-  - sharp
-- **DevDependencies**: fastify, @fastify/multipart
-
-### 9. **Documentation** ✅
-- **File**: `README.md` (comprehensive)
-  - Feature overview
-  - Installation instructions
-  - Setup guide (Prisma, plugin registration)
-  - API endpoint documentation
-  - Frontend usage examples (React, Nuxt)
-  - Processing pipeline explanation
-  - Configuration guide
-  - Environment variables
-  - Performance tips
-  - Troubleshooting guide
-
-### 10. **Test Suite** ✅
-- **File**: `test/xMedia.test.js`
-- **Coverage**:
-  - Plugin registration tests
-  - Configuration validation
-  - Route availability
-  - Variant presets
-  - Worker configuration
-
-## 📁 Directory Structure
-
-```
-xMedia/
-├── src/
-│   ├── xMedia.js                 # Main plugin
-│   ├── services/
-│   │   └── s3.js                 # R2/S3 integration
-│   ├── utils/
-│   │   └── image.js              # Image processing
-│   ├── routes/
-│   │   ├── upload.js             # Upload endpoint
-│   │   └── status.js             # Status endpoint
-│   └── workers/
-│       └── processor.js          # Job queue processor
-├── test/
-│   └── xMedia.test.js            # Test suite
-├── package.json                  # Dependencies
-├── README.md                      # Documentation
-├── SCHEMA.prisma                 # Database schema
-└── IMPLEMENTATION_SUMMARY.md     # This file
-```
-
-## 🔄 Processing Pipeline
-
-```
-Upload Request
-    ↓
-Validate File (type, size)
-    ↓
-Generate Staging Key
-    ↓
-Upload to R2 Staging Bucket
-    ↓
-Create MediaQueue Job
-    ↓
-Return 202 Accepted
-    ↓
-[Worker Polling]
-    ↓
-Lock Job (prevent duplicate processing)
-    ↓
-Download from Staging
-    ↓
-Strip EXIF Data
-    ↓
-Content Moderation (if configured)
-    ├─ REJECTED → Clean up, mark REJECTED
-    └─ APPROVED
-    ↓
-Generate WebP Variants
-    ↓
-Generate Blurhash
-    ↓
-Upload Variants & Original to R2
-    ↓
-Create Media Record
-    ↓
-Update MediaQueue Status to COMPLETE
-    ↓
-Delete Staging File
-    ↓
-Ready for Frontend Consumption
-```
-
-## 🎛️ Configuration Options
-
-```javascript
-{
-  // Required
-  r2: {
-    endpoint: String,           // https://[id].r2.cloudflarestorage.com
-    region: String,             // 'auto' for R2
-    accessKeyId: String,
-    secretAccessKey: String,
-    bucket: String,
-  },
-  db: PrismaClient,
-
-  // Optional
-  moderation: {
-    provider: String,           // 'rekognition', 'vision', etc.
-    apiKey: String,
-    // ... provider-specific config
-  },
-
-  variants: {                     // Override defaults
-    [key: String]: {
-      width: Number,
-      height: Number | null,
-      fit: 'cover' | 'inside',
-    }
-  },
-
-  worker: {
-    enabled: Boolean,            // true
-    pollInterval: Number,        // 5000ms
-    maxAttempts: Number,         // 3
-    lockTimeout: Number,         // 300000ms
-    failOnError: Boolean,        // false
-  },
-
-  stagingPath: String,           // 'staging'
-  mediaPath: String,             // 'media'
-  originalsPath: String,         // 'originals'
-  maxFileSize: Number,           // 50MB
-  allowedMimeTypes: String[],    // JPEG, PNG, WebP, GIF
-}
-```
-
-## 🚀 Quick Start
-
-### 1. Install Dependencies
-```bash
-npm install @xenterprises/fastify-xmedia @fastify/multipart
-npm install -D fastify
-```
-
-### 2. Add Prisma Models
-Copy models from `SCHEMA.prisma` to your `schema.prisma` and run:
-```bash
-npx prisma migrate dev
-```
-
-### 3. Register Plugin
-```javascript
-import xMedia from '@xenterprises/fastify-xmedia';
-import multipart from '@fastify/multipart';
-
-await fastify.register(multipart);
-await fastify.register(xMedia, {
-  r2: { /* R2 config */ },
-  db: prisma,
-});
-```
-
-### 4. Upload Image
-```bash
-curl -F "file=@photo.jpg" \
-     -F "sourceType=avatar" \
-     -F "sourceId=user123" \
-     http://localhost:3000/media/upload
-```
-
-### 5. Check Status
-```bash
-curl http://localhost:3000/media/status/[jobId]
-```
-
-## 🔌 Integrations
-
-### Source Types & Variants
-- **avatar**: xs, sm
-- **member_photo**: xs, sm, md
-- **gallery**: md, lg, xl
-- **hero**: lg, xl, 2xl
-- **content**: md, lg
-
-### Content Moderation (Pluggable)
-- AWS Rekognition
-- Google Vision AI
-- Sightengine
-- Custom APIs
-
-### Storage
-- Cloudflare R2 (S3-compatible)
-- AWS S3 (compatible)
-- MinIO (compatible)
-
-## 📊 Database Schema
-
-### MediaQueue
-- Job status tracking (PENDING, PROCESSING, COMPLETE, REJECTED, FAILED)
-- Retry logic with max attempts
-- Pessimistic locking (lockedAt, lockedBy)
-- Error tracking
-- Moderation results
-
-### Media
-- Variant URLs (JSON object)
-- Original file URL
-- Image properties (width, height, format, aspect ratio)
-- Blurhash for loading placeholders
-- Focal point for smart cropping
-- Source tracking (sourceType, sourceId)
-
-## ⚙️ Advanced Features
-
-### Focal Points
-- User-provided hint for smart cropping
-- Stored as `{ x: 0-1, y: 0-1 }`
-- Used by frontend for better crop positioning
-
-### Blurhash
-- Perceptual hash for image preview
-- Instant UI placeholder while loading
-- Generated from small thumbnail
-
-### Variant Presets
-- Different source types get different variants
-- Avatar: small previews (xs, sm)
-- Hero: large backgrounds (lg, xl, 2xl)
-- Extensible with custom sourceTypes
-
-### Retry Logic
-- Automatic retry on processing failure
-- Configurable max attempts (default: 3)
-- Stale lock recovery (locks > 5 min)
-
-### Cleanup
-- Staging files auto-delete after 24h (R2 lifecycle)
-- Manual cleanup functions provided
-- Orphaned staging file cleanup
-
-## 🧪 Testing
-
-Run tests with:
-```bash
-npm test
-```
-
-Test coverage includes:
-- Plugin registration
-- Configuration validation
-- Route availability
-- Variant presets
-- Worker setup
-
-## 📝 Implementation Notes
-
-### Design Decisions
-
-1. **Job Queue Pattern**: Decouples upload from processing for better UX
-2. **Pessimistic Locking**: Simple, effective duplicate prevention
-3. **WebP Format**: Best compression for web images
-4. **Variant Presets**: Balance between flexibility and simplicity
-5. **Blurhash**: Industry-standard loading placeholder
-
-### Error Handling
-
-- File validation before upload
-- Transaction-like processing (all-or-nothing)
-- Retry logic with exponential backoff capability
-- Graceful degradation if moderation unavailable
-- Comprehensive error messages
-
-### Performance
-
-- Streaming file uploads (not loading full files in memory)
-- Efficient image processing with sharp
-- Indexed database queries for job polling
-- Batch operations for cleanup
-- Optional CDN caching
-
-## 🔐 Security Considerations
-
-- File type validation (whitelist)
-- File size limits
-- EXIF stripping (privacy protection)
-- Content moderation (policy enforcement)
-- Signed URLs for protected content
-- CORS configuration for R2
-
-## 🎯 Next Steps
-
-### For Production
-
-1. ✅ Implement moderation API integration
-2. ✅ Set up R2 bucket and lifecycle policies
-3. ✅ Add proper error logging/monitoring
-4. ✅ Implement webhook callbacks for job completion
-5. ✅ Add rate limiting per user/IP
-6. ✅ Set up CDN in front of R2
-7. ✅ Add image optimization (AVIF, etc.)
-8. ✅ Implement analytics/usage tracking
-
-### For Enhancement
-
-- Direct browser uploads (presigned URLs)
-- Video support with thumbnails
-- Batch uploads
-- Face detection for smart cropping
-- Custom filters/effects
-- Image comparison (similarity search)
-
-## 📚 Documentation Files
-
-- `README.md` - User-facing documentation
-- `SCHEMA.prisma` - Database schema template
-- `IMPLEMENTATION_SUMMARY.md` - This file
-- Source code comments - Comprehensive JSDoc
-
-## ✨ Summary
-
-The xMedia plugin provides a production-ready image processing pipeline with:
-- ✅ Complete file upload handling
-- ✅ Automatic image optimization (EXIF strip, WebP variants)
-- ✅ Content moderation hooks
-- ✅ Job queue with retry logic
-- ✅ R2 storage integration
-- ✅ Status tracking and polling
-- ✅ Comprehensive error handling
-- ✅ Database-backed processing
-- ✅ Extensive documentation
-- ✅ Test coverage
-
-All components are implemented and ready for integration into your Fastify application.

package/INTEGRATION_GUIDE.md

@@ -1,554 +0,0 @@
-# xMedia Integration Guide
-
-Quick reference for integrating xMedia into your Fastify application.
-
-## Step 1: Install Package
-
-```bash
-npm install @xenterprises/fastify-xmedia @fastify/multipart
-```
-
-## Step 2: Set Environment Variables
-
-```bash
-# .env
-R2_ENDPOINT=https://[account-id].r2.cloudflarestorage.com
-R2_ACCESS_KEY_ID=your_access_key
-R2_SECRET_ACCESS_KEY=your_secret_key
-R2_BUCKET=your-bucket-name
-
-DATABASE_URL=postgresql://user:password@localhost:5432/dbname
-
-# Optional
-MODERATION_PROVIDER=rekognition
-MODERATION_API_KEY=your_api_key
-```
-
-## Step 3: Update Prisma Schema
-
-Add this to your `schema.prisma`:
-
-```prisma
-enum MediaStatus {
-  PENDING
-  PROCESSING
-  COMPLETE
-  REJECTED
-  FAILED
-}
-
-enum ModerationResult {
-  APPROVED
-  REJECTED
-  FLAGGED
-}
-
-model MediaQueue {
-  id String @id @default(cuid())
-  status MediaStatus @default(PENDING)
-  sourceType String
-  sourceId String
-  stagingKey String
-  originalFilename String
-  mimeType String
-  fileSize Int
-  mediaId String?
-  media Media? @relation(fields: [mediaId], references: [id], onDelete: SetNull)
-  attempts Int @default(0)
-  maxAttempts Int @default(3)
-  errorMsg String?
-  moderationResult ModerationResult?
-  moderationDetails Json?
-  lockedAt DateTime?
-  lockedBy String?
-  createdAt DateTime @default(now())
-  updatedAt DateTime @updatedAt
-
-  @@index([status, createdAt])
-  @@index([sourceType, sourceId])
-  @@index([lockedAt])
-}
-
-model Media {
-  id String @id @default(cuid())
-  urls Json @default("{}")
-  originalUrl String
-  width Int
-  height Int
-  format String
-  aspectRatio String
-  blurhash String
-  focalPoint Json @default("{\"x\": 0.5, \"y\": 0.5}")
-  sourceType String
-  sourceId String
-  originalFilename String
-  mimeType String
-  fileSize Int
-  exifStripped Boolean @default(true)
-  createdAt DateTime @default(now())
-  updatedAt DateTime @updatedAt
-  queue MediaQueue[]
-
-  @@index([sourceType, sourceId])
-  @@index([createdAt])
-}
-```
-
-Then migrate:
-```bash
-npx prisma migrate dev --name add_media_tables
-```
-
-## Step 4: Register Plugin in Fastify
-
-```javascript
-// server.js or main app file
-import Fastify from 'fastify';
-import multipart from '@fastify/multipart';
-import xMedia from '@xenterprises/fastify-xmedia';
-import { PrismaClient } from '@prisma/client';
-
-const fastify = Fastify();
-const prisma = new PrismaClient();
-
-// Register multipart first (required for file uploads)
-await fastify.register(multipart);
-
-// Register xMedia plugin
-await fastify.register(xMedia, {
-  // Required configuration
-  r2: {
-    endpoint: process.env.R2_ENDPOINT,
-    region: 'auto',
-    accessKeyId: process.env.R2_ACCESS_KEY_ID,
-    secretAccessKey: process.env.R2_SECRET_ACCESS_KEY,
-    bucket: process.env.R2_BUCKET,
-  },
-
-  db: prisma,
-
-  // Optional: Content moderation
-  moderation: process.env.MODERATION_PROVIDER ? {
-    provider: process.env.MODERATION_PROVIDER,
-    apiKey: process.env.MODERATION_API_KEY,
-  } : null,
-
-  // Optional: Worker configuration
-  worker: {
-    enabled: true,                  // Process jobs in background
-    pollInterval: 5000,             // Check for new jobs every 5 seconds
-    maxAttempts: 3,                 // Retry failed jobs 3 times
-    lockTimeout: 5 * 60 * 1000,     // Release locks after 5 minutes
-  },
-});
-
-await fastify.listen({ port: 3000 });
-```
-
-## Step 5: Create Frontend Upload Form
-
-### React Example
-
-```jsx
-import { useState } from 'react';
-
-export function AvatarUpload({ userId, onComplete }) {
-  const [jobId, setJobId] = useState(null);
-  const [status, setStatus] = useState(null);
-  const [loading, setLoading] = useState(false);
-  const [error, setError] = useState(null);
-
-  const handleUpload = async (file) => {
-    setLoading(true);
-    const formData = new FormData();
-    formData.append('file', file);
-    formData.append('sourceType', 'avatar');
-    formData.append('sourceId', userId);
-
-    try {
-      const response = await fetch('/media/upload', {
-        method: 'POST',
-        body: formData,
-      });
-
-      const data = await response.json();
-      setJobId(data.jobId);
-      pollStatus(data.jobId);
-    } catch (err) {
-      setError(err.message);
-      setLoading(false);
-    }
-  };
-
-  const pollStatus = async (id) => {
-    const maxAttempts = 120; // 2 minutes with 1s intervals
-    let attempts = 0;
-
-    const interval = setInterval(async () => {
-      attempts++;
-
-      try {
-        const response = await fetch(`/media/status/${id}`);
-        const data = await response.json();
-        setStatus(data);
-
-        if (data.status === 'COMPLETE') {
-          setLoading(false);
-          onComplete?.(data.media);
-          clearInterval(interval);
-        } else if (data.status === 'REJECTED') {
-          setError(`Image rejected: ${data.reason}`);
-          setLoading(false);
-          clearInterval(interval);
-        } else if (data.status === 'FAILED') {
-          setError(`Processing failed: ${data.error}`);
-          setLoading(false);
-          clearInterval(interval);
-        } else if (attempts >= maxAttempts) {
-          setError('Processing timeout');
-          setLoading(false);
-          clearInterval(interval);
-        }
-      } catch (err) {
-        console.error('Status check error:', err);
-      }
-    }, 1000);
-  };
-
-  return (
-    <div>
-      <input
-        type="file"
-        accept="image/*"
-        onChange={(e) => handleUpload(e.target.files[0])}
-        disabled={loading}
-      />
-
-      {loading && <p>Processing...</p>}
-      {error && <p style={{ color: 'red' }}>{error}</p>}
-
-      {status?.media && (
-        <div>
-          <img src={status.media.urls.sm} alt="Avatar" width={200} />
-          <p>Upload complete!</p>
-        </div>
-      )}
-    </div>
-  );
-}
-```
-
-### Nuxt Example
-
-```vue
-<template>
-  <div class="upload-container">
-    <input
-      ref="fileInput"
-      type="file"
-      accept="image/*"
-      @change="handleFileSelect"
-      :disabled="loading"
-    />
-
-    <div v-if="loading" class="loading">
-      Processing image...
-    </div>
-
-    <div v-if="error" class="error">
-      {{ error }}
-    </div>
-
-    <div v-if="media" class="complete">
-      <img :src="media.urls.sm" :alt="media.originalFilename" />
-      <p>Upload complete!</p>
-    </div>
-  </div>
-</template>
-
-<script setup>
-import { ref } from 'vue';
-
-const props = defineProps({
-  sourceType: { type: String, default: 'avatar' },
-  sourceId: { type: String, required: true },
-});
-
-const emit = defineEmits(['complete']);
-
-const fileInput = ref(null);
-const jobId = ref(null);
-const status = ref(null);
-const media = ref(null);
-const loading = ref(false);
-const error = ref(null);
-
-const handleFileSelect = async (event) => {
-  const file = event.target.files?.[0];
-  if (!file) return;
-
-  loading.value = true;
-  error.value = null;
-
-  const formData = new FormData();
-  formData.append('file', file);
-  formData.append('sourceType', props.sourceType);
-  formData.append('sourceId', props.sourceId);
-
-  try {
-    const response = await fetch('/media/upload', {
-      method: 'POST',
-      body: formData,
-    });
-
-    const data = await response.json();
-    jobId.value = data.jobId;
-    pollStatus();
-  } catch (err) {
-    error.value = `Upload failed: ${err.message}`;
-    loading.value = false;
-  }
-};
-
-const pollStatus = async () => {
-  const maxAttempts = 120;
-  let attempts = 0;
-
-  const interval = setInterval(async () => {
-    attempts++;
-
-    try {
-      const response = await fetch(`/media/status/${jobId.value}`);
-      const data = await response.json();
-      status.value = data;
-
-      if (data.status === 'COMPLETE') {
-        media.value = data.media;
-        loading.value = false;
-        emit('complete', data.media);
-        clearInterval(interval);
-      } else if (data.status === 'REJECTED') {
-        error.value = `Image rejected: ${data.reason}`;
-        loading.value = false;
-        clearInterval(interval);
-      } else if (data.status === 'FAILED') {
-        error.value = `Processing failed: ${data.error}`;
-        loading.value = false;
-        clearInterval(interval);
-      } else if (attempts >= maxAttempts) {
-        error.value = 'Processing timeout';
-        loading.value = false;
-        clearInterval(interval);
-      }
-    } catch (err) {
-      console.error('Status check error:', err);
-    }
-  }, 1000);
-};
-</script>
-
-<style scoped>
-.upload-container {
-  display: flex;
-  flex-direction: column;
-  gap: 1rem;
-}
-
-.loading {
-  color: #0066cc;
-}
-
-.error {
-  color: #cc0000;
-}
-
-.complete {
-  color: #00aa00;
-}
-
-.complete img {
-  max-width: 200px;
-  border-radius: 8px;
-  margin: 1rem 0;
-}
-</style>
-```
-
-## Step 6: Usage Examples
-
-### Upload an Avatar
-
-```bash
-curl -X POST \
-  -F "file=@avatar.jpg" \
-  -F "sourceType=avatar" \
-  -F "sourceId=user-123" \
-  http://localhost:3000/media/upload
-```
-
-Response:
-```json
-{
-  "jobId": "clh7k9w1j000...",
-  "message": "File uploaded. Processing started.",
-  "statusUrl": "/media/status/clh7k9w1j000..."
-}
-```
-
-### Check Processing Status
-
-```bash
-curl http://localhost:3000/media/status/clh7k9w1j000...
-```
-
-When complete:
-```json
-{
-  "jobId": "clh7k9w1j000...",
-  "status": "COMPLETE",
-  "sourceType": "avatar",
-  "sourceId": "user-123",
-  "media": {
-    "id": "media-...",
-    "urls": {
-      "xs": "https://bucket.r2.dev/media/avatar/user-123/.../xs.webp",
-      "sm": "https://bucket.r2.dev/media/avatar/user-123/.../sm.webp"
-    },
-    "originalUrl": "https://bucket.r2.dev/originals/avatar/user-123/.../original.jpg",
-    "width": 1920,
-    "height": 1920,
-    "aspectRatio": "1:1",
-    "blurhash": "UeKUpMx..."
-  }
-}
-```
-
-## Step 7: R2 Setup
-
-### Create R2 Bucket
-
-1. Go to Cloudflare dashboard
-2. Navigate to R2
-3. Create new bucket
-4. Note the endpoint URL
-
-### Set CORS Policy
-
-In R2 bucket settings:
-```json
-{
-  "CORSRules": [
-    {
-      "AllowedOrigins": ["https://yourdomain.com"],
-      "AllowedMethods": ["GET"],
-      "AllowedHeaders": ["*"],
-      "MaxAgeSeconds": 3600
-    }
-  ]
-}
-```
-
-### Set Lifecycle Policy
-
-In R2 bucket settings:
-- Delete objects in `/staging/` older than 1 day
-- Keep `/media/` and `/originals/` permanently
-
-## Step 8: Optional - Connect to User Model
-
-Add to your User Prisma model:
-
-```prisma
-model User {
-  id String @id @default(cuid())
-  // ... other fields
-
-  // Avatar relationship
-  avatar Media? @relation(fields: [avatarId], references: [id], onDelete: SetNull)
-  avatarId String?
-}
-```
-
-Then update avatar:
-
-```javascript
-// After upload completes
-await prisma.user.update({
-  where: { id: userId },
-  data: { avatarId: media.id },
-});
-```
-
-## Step 9: Display Images
-
-```jsx
-// In your React/Nuxt components
-function UserProfile({ user }) {
-  const avatar = user.avatar;
-
-  if (!avatar) return <DefaultAvatar />;
-
-  return (
-    <img
-      src={avatar.urls.sm}  // Mobile
-      srcSet={`
-        ${avatar.urls.xs} 80w,
-        ${avatar.urls.sm} 200w
-      `}
-      alt={user.name}
-      style={{ borderRadius: '50%', width: 200 }}
-    />
-  );
-}
-```
-
-## Step 10: Error Handling
-
-Common issues and solutions:
-
-### R2 Upload Fails
-- ✅ Verify credentials
-- ✅ Check bucket name
-- ✅ Ensure endpoint URL is correct
-- ✅ Check CORS policy
-
-### Jobs Stuck in PROCESSING
-- ✅ Jobs auto-recover after 5 minutes
-- ✅ Check worker logs
-- ✅ Verify database connectivity
-
-### Images Rejected
-- ✅ Check moderation settings
-- ✅ Review moderation flags in job details
-- ✅ Adjust moderation thresholds
-
-## Troubleshooting Checklist
-
-- [ ] Prisma models migrated
-- [ ] Environment variables set
-- [ ] R2 bucket created and configured
-- [ ] CORS policy set on R2
-- [ ] Lifecycle policy set on R2
-- [ ] Plugin registered in correct order
-- [ ] `@fastify/multipart` registered before xMedia
-- [ ] Database connection working
-- [ ] Worker is running (check logs)
-
-## Support
-
-For issues or questions:
-- Check `README.md` for detailed documentation
-- Review `IMPLEMENTATION_SUMMARY.md` for architecture
-- Check worker logs: `console.info()` statements
-- Inspect `MediaQueue` table for job details
-
-## Next Steps
-
-1. ✅ Upload test image
-2. ✅ Verify processing completes
-3. ✅ Display images in UI
-4. ✅ Add moderation (optional)
-5. ✅ Set up monitoring
-6. ✅ Configure CDN cache
-
-Happy image uploading! 🎉

package/test/xImagePipeline.test.js

@@ -1,196 +0,0 @@
-// test/xImagePipeline.test.js
-import { test } from "node:test";
-import assert from "node:assert";
-import Fastify from "fastify";
-import multipart from "@fastify/multipart";
-import xImagePipeline from "../src/xImagePipeline.js";
-
-// Mock database
-const mockDb = {
-  mediaQueue: {
-    create: async (data) => ({
-      id: "test-job-" + Date.now(),
-      ...data.data,
-    }),
-    findUnique: async (query) => ({
-      id: query.where.id,
-      status: "COMPLETE",
-      sourceType: "avatar",
-      sourceId: "user123",
-    }),
-    findFirst: async () => null,
-    update: async (query) => ({ count: 1 }),
-    updateMany: async () => ({ count: 0 }),
-  },
-  media: {
-    create: async (data) => ({
-      id: "media-123",
-      ...data.data,
-    }),
-  },
-};
-
-// Mock R2 config
-const mockR2Config = {
-  endpoint: "https://example.r2.cloudflarestorage.com",
-  region: "auto",
-  accessKeyId: "mock-key",
-  secretAccessKey: "mock-secret",
-  bucket: "test-bucket",
-};
-
-test("xImagePipeline Plugin - registers successfully with required config", async () => {
-  const fastify = Fastify({ logger: false });
-  try {
-    await fastify.register(multipart);
-    await fastify.register(xImagePipeline, {
-      r2: mockR2Config,
-      db: mockDb,
-    });
-    assert.ok(true, "Plugin registered successfully");
-  } finally {
-    try {
-      await fastify.close();
-    } catch {
-      // Ignore
-    }
-  }
-});
-
-test("xImagePipeline Plugin - throws error without R2 config", async () => {
-  const fastify = Fastify({ logger: false });
-  try {
-    await assert.rejects(
-      async () => {
-        await fastify.register(multipart);
-        await fastify.register(xImagePipeline, {
-          db: mockDb,
-        });
-      },
-      /R2 configuration is required/
-    );
-  } finally {
-    try {
-      await fastify.close();
-    } catch {
-      // Ignore
-    }
-  }
-});
-
-test("xImagePipeline Plugin - throws error without database", async () => {
-  const fastify = Fastify({ logger: false });
-  try {
-    await assert.rejects(
-      async () => {
-        await fastify.register(multipart);
-        await fastify.register(xImagePipeline, {
-          r2: mockR2Config,
-        });
-      },
-      /Database instance/
-    );
-  } finally {
-    try {
-      await fastify.close();
-    } catch {
-      // Ignore
-    }
-  }
-});
-
-test("xImagePipeline Routes - GET /media/status/:jobId returns job status", async () => {
-  const fastify = Fastify({ logger: false });
-  try {
-    await fastify.register(multipart);
-    await fastify.register(xImagePipeline, {
-      r2: mockR2Config,
-      db: mockDb,
-    });
-
-    const response = await fastify.inject({
-      method: "GET",
-      url: "/image-pipeline/status/test-job-123",
-    });
-
-    assert.equal(response.statusCode, 200);
-    const body = JSON.parse(response.payload);
-    assert.ok(body.jobId, "Response should have jobId");
-    assert.ok(body.status, "Response should have status");
-  } finally {
-    try {
-      await fastify.close();
-    } catch {
-      // Ignore
-    }
-  }
-});
-
-test("xImagePipeline Configuration - accepts custom variants config", async () => {
-  const fastify = Fastify({ logger: false });
-  const customConfig = {
-    r2: mockR2Config,
-    db: mockDb,
-    variants: {
-      custom: {
-        xs: { width: 100, height: 100, fit: "cover" },
-        lg: { width: 800, height: 600, fit: "inside" },
-      },
-    },
-  };
-  try {
-    await fastify.register(multipart);
-    await fastify.register(xImagePipeline, customConfig);
-    assert.ok(true, "Plugin registered with custom variants");
-  } finally {
-    try {
-      await fastify.close();
-    } catch {
-      // Ignore
-    }
-  }
-});
-
-test("xImagePipeline Configuration - accepts worker configuration", async () => {
-  const fastify = Fastify({ logger: false });
-  const configWithWorker = {
-    r2: mockR2Config,
-    db: mockDb,
-    worker: {
-      enabled: true,
-      pollInterval: 10000,
-      maxAttempts: 5,
-    },
-  };
-  try {
-    await fastify.register(multipart);
-    await fastify.register(xImagePipeline, configWithWorker);
-    assert.ok(true, "Plugin registered with worker config");
-  } finally {
-    try {
-      await fastify.close();
-    } catch {
-      // Ignore
-    }
-  }
-});
-
-test("xImagePipeline Variant Presets - has predefined variant presets", async () => {
-  const fastify = Fastify({ logger: false });
-  try {
-    await fastify.register(multipart);
-    await fastify.register(xImagePipeline, {
-      r2: mockR2Config,
-      db: mockDb,
-    });
-
-    // Just verify plugin registered - variants are available via plugin configuration
-    assert.ok(true, "Plugin has variant presets configured");
-  } finally {
-    try {
-      await fastify.close();
-    } catch {
-      // Ignore
-    }
-  }
-});