@xenterprises/fastify-ximagepipeline 1.1.0 → 1.2.0

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/SCHEMA.prisma

@@ -1,113 +0,0 @@
-// This schema should be added to your main Prisma schema.prisma file
-// It defines the models needed for the xMedia pipeline
-
-enum MediaStatus {
-  PENDING
-  PROCESSING
-  COMPLETE
-  REJECTED
-  FAILED
-}
-
-enum ModerationResult {
-  APPROVED
-  REJECTED
-  FLAGGED
-}
-
-model MediaQueue {
-  id String @id @default(cuid())
-
-  // Job status
-  status MediaStatus @default(PENDING)
-
-  // Source information
-  sourceType String // avatar, gallery, hero, member_photo, content, etc.
-  sourceId String // userId, bandId, etc.
-
-  // File information
-  stagingKey String // Key in R2 staging bucket
-  originalFilename String
-  mimeType String
-  fileSize Int
-
-  // Processing results
-  mediaId String? // FK to Media after processing
-  media Media? @relation(fields: [mediaId], references: [id], onDelete: SetNull)
-
-  // Error tracking
-  attempts Int @default(0)
-  maxAttempts Int @default(3)
-  errorMsg String?
-
-  // Moderation results
-  moderationResult ModerationResult?
-  moderationDetails Json? // Full moderation API response
-
-  // Locking for worker process
-  lockedAt DateTime?
-  lockedBy String? // Worker ID that locked this job
-
-  // Timestamps
-  createdAt DateTime @default(now())
-  updatedAt DateTime @updatedAt
-
-  @@index([status, createdAt])
-  @@index([sourceType, sourceId])
-  @@index([lockedAt])
-}
-
-model Media {
-  id String @id @default(cuid())
-
-  // Variant URLs (object mapping variant name to URL)
-  // e.g., { "xs": "https://...", "sm": "https://...", "md": "https://..." }
-  urls Json @default("{}")
-  originalUrl String // URL to full-resolution original
-
-  // Image properties
-  width Int
-  height Int
-  format String // jpeg, png, webp, gif
-  aspectRatio String // e.g., "16:9", "4:3", "1:1"
-
-  // Loading placeholder
-  blurhash String // For instant UI placeholder
-
-  // For smart cropping
-  focalPoint Json @default("{\"x\": 0.5, \"y\": 0.5}") // { x: 0-1, y: 0-1 }
-
-  // Source information (denormalized for queries)
-  sourceType String
-  sourceId String
-
-  // File information
-  originalFilename String
-  mimeType String
-  fileSize Int
-
-  // Metadata
-  exifStripped Boolean @default(true)
-  createdAt DateTime @default(now())
-  updatedAt DateTime @updatedAt
-
-  // Relations (optional - add as needed)
-  // User.avatar => Media
-  // Band.avatar => Media
-  // Gallery items, etc.
-
-  queue MediaQueue[]
-
-  @@index([sourceType, sourceId])
-  @@index([createdAt])
-}
-
-// Example: Add to User model
-// avatar Media? @relation(fields: [avatarId], references: [id], onDelete: SetNull)
-// avatarId String?
-
-// Example: Add to Band model
-// avatar Media? @relation(fields: [avatarId], references: [id], onDelete: SetNull)
-// avatarId String?
-// hero Media? @relation(fields: [heroId], references: [id], onDelete: SetNull)
-// heroId String?