@xenterprises/fastify-ximagepipeline 1.0.0

package/INTEGRATION_GUIDE.md

@@ -0,0 +1,554 @@
+# 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! 🎉