shipd 0.1.3 → 0.2.0

package/features/file-upload/README.md

@@ -0,0 +1,329 @@
+# File Upload Module - Integration Guide
+
+**Module Version:** 1.0.0  
+**Last Updated:** 2025-12-22  
+**Standalone:** ✅ Yes (can work independently)
+
+---
+
+## Overview
+
+This module adds file upload functionality using Cloudflare R2 (S3-compatible object storage). It includes a drag-and-drop upload interface, progress tracking, and image preview.
+
+**Key Features:**
+- Cloudflare R2 integration (S3-compatible)
+- Drag-and-drop file upload
+- Image upload with validation
+- Progress tracking
+- File size validation (5MB max)
+- Image preview gallery
+- Public URL generation
+
+---
+
+## Files Added
+
+### Pages/Routes
+- `app/dashboard/upload/page.tsx` - File upload interface with drag-and-drop
+
+### API Routes
+- `app/api/upload-image/route.ts` - Image upload API endpoint
+
+### Utilities/Libraries
+- `lib/upload-image.ts` - R2 upload utility functions
+
+---
+
+## Dependencies
+
+### Package Dependencies
+The following packages will be added to `package.json`:
+- `@aws-sdk/client-s3@^3.800.0` - AWS SDK for S3-compatible storage (R2)
+
+### Required Modules
+- None - File Upload module is standalone
+
+### Optional Integration
+- **Auth Module** - For protecting upload routes (works without it, but uploads should be protected)
+
+---
+
+## Environment Variables
+
+Add these to your `.env.local`:
+
+```env
+# File Upload (Cloudflare R2)
+R2_UPLOAD_IMAGE_ACCESS_KEY_ID="your-r2-access-key-id"
+R2_UPLOAD_IMAGE_SECRET_ACCESS_KEY="your-r2-secret-access-key"
+CLOUDFLARE_ACCOUNT_ID="your-cloudflare-account-id"
+R2_UPLOAD_IMAGE_BUCKET_NAME="your-bucket-name"
+```
+
+**Required Variables:**
+- `R2_UPLOAD_IMAGE_ACCESS_KEY_ID` - R2 access key ID
+- `R2_UPLOAD_IMAGE_SECRET_ACCESS_KEY` - R2 secret access key
+- `CLOUDFLARE_ACCOUNT_ID` - Your Cloudflare account ID
+- `R2_UPLOAD_IMAGE_BUCKET_NAME` - Your R2 bucket name
+
+**Where to get them:**
+- **Cloudflare R2**: [dash.cloudflare.com](https://dash.cloudflare.com) - Create R2 bucket and API tokens
+- Create an R2 bucket in Cloudflare dashboard
+- Generate API tokens with read/write permissions
+- Get account ID from Cloudflare dashboard
+
+**Note:** You'll also need to configure a public domain for your R2 bucket to generate public URLs. Update `lib/upload-image.ts` with your public R2 domain.
+
+---
+
+## Manual Integration Steps
+
+If you're appending this module to an existing project, follow these steps:
+
+### Step 1: Install Dependencies
+
+```bash
+npm install
+# or
+pnpm install
+# or
+yarn install
+```
+
+The append command automatically adds missing dependencies to `package.json`, but you need to install them.
+
+### Step 2: Set Up Cloudflare R2
+
+1. Create a Cloudflare account (if you don't have one)
+2. Navigate to R2 in the Cloudflare dashboard
+3. Create a new R2 bucket
+4. Generate API tokens with read/write permissions
+5. Get your account ID from the dashboard
+
+### Step 3: Configure Public Domain (Optional)
+
+To generate public URLs, you need to configure a custom domain for your R2 bucket:
+
+1. In R2 dashboard, go to your bucket settings
+2. Configure a custom domain or use R2.dev domain
+3. Update `lib/upload-image.ts` with your public domain:
+
+```typescript
+const publicUrl = `https://your-custom-domain.com/${key}`;
+// or
+const publicUrl = `https://pub-xxxxx.r2.dev/${key}`;
+```
+
+### Step 4: Add Environment Variables
+
+1. Copy `.env.example` to `.env.local` (if not exists)
+2. Add all required R2 environment variables
+3. Restart dev server after adding env vars
+
+### Step 5: Verify Installation
+
+1. Check that `app/api/upload-image/route.ts` exists
+2. Check that `app/dashboard/upload/page.tsx` exists
+3. Check that `lib/upload-image.ts` exists
+4. Start your dev server: `npm run dev`
+5. Visit `http://localhost:3000/dashboard/upload` to test uploads
+
+---
+
+## Usage Examples
+
+### Using the Upload Page
+
+1. Navigate to `/dashboard/upload`
+2. Drag and drop images or click to select
+3. Watch upload progress
+4. View uploaded images in the gallery
+5. Copy image URLs or open in new tab
+
+### Using Upload Function Programmatically
+
+```typescript
+import { uploadImageAssets } from "@/lib/upload-image";
+
+// Upload a file buffer
+const buffer = Buffer.from(fileData);
+const filename = "my-image.png";
+const url = await uploadImageAssets(buffer, filename);
+console.log("Uploaded to:", url);
+```
+
+### Customizing Upload Limits
+
+Edit `app/api/upload-image/route.ts` to change limits:
+
+```typescript
+// Change max file size (default: 10MB)
+const maxSizeInBytes = 20 * 1024 * 1024; // 20MB
+
+// Change allowed MIME types
+const allowedMimeTypes = [
+  "image/jpeg",
+  "image/png",
+  // Add more types
+];
+```
+
+---
+
+## Customization
+
+### Styling
+- Upload UI uses Tailwind CSS classes
+- Customize colors in `tailwind.config.ts`
+- Modify upload area styles in `app/dashboard/upload/page.tsx`
+
+### Configuration
+- File size limits in `app/api/upload-image/route.ts`
+- Allowed file types in `app/api/upload-image/route.ts`
+- Public URL generation in `lib/upload-image.ts`
+
+### Features
+- Drag-and-drop is built-in
+- Progress tracking is automatic
+- Image preview gallery is included
+
+---
+
+## Integration Points
+
+### Files That May Need Manual Updates
+
+**lib/upload-image.ts**:
+- Update public URL domain to match your R2 bucket configuration
+- Customize bucket settings if needed
+
+**app/api/upload-image/route.ts**:
+- Adjust file size limits
+- Modify allowed file types
+- Add authentication checks if needed
+
+**Middleware** (if auth module installed):
+- Upload routes should be protected
+- Add `/dashboard/upload` to protected routes if needed
+
+---
+
+## Troubleshooting
+
+### Common Issues
+
+**Issue:** "R2_UPLOAD_IMAGE_ACCESS_KEY_ID is not defined" error
+**Solution:**
+- Add all R2 environment variables to `.env.local`
+- Get credentials from Cloudflare R2 dashboard
+- Restart dev server after adding env vars
+
+**Issue:** Upload fails with "Access Denied"
+**Solution:**
+- Verify API tokens have correct permissions
+- Check bucket name is correct
+- Ensure account ID is correct
+
+**Issue:** Public URLs not working
+**Solution:**
+- Configure public domain for R2 bucket
+- Update `lib/upload-image.ts` with correct public domain
+- Ensure bucket has public read access
+
+**Issue:** "File too large" error
+**Solution:**
+- Check file size limits in `app/api/upload-image/route.ts`
+- Adjust `maxSizeInBytes` if needed
+- Client-side validation also checks 5MB limit
+
+---
+
+## Next Steps
+
+After installing this module:
+
+1. Set up Cloudflare R2 bucket
+2. Generate API tokens
+3. Add environment variables to `.env.local`
+4. Configure public domain for bucket
+5. Update public URL in `lib/upload-image.ts`
+6. Test upload functionality
+7. Add authentication if needed
+
+---
+
+## Related Modules
+
+This module works well with:
+- **Auth Module** - For protecting upload routes
+
+**Note:** File Upload module is optional and standalone. No other modules are required.
+
+---
+
+## Module Status
+
+✅ **Standalone Package** - Can be installed independently  
+✅ **Drag & Drop** - Built-in drag-and-drop interface  
+✅ **Progress Tracking** - Real-time upload progress  
+✅ **Image Preview** - Gallery of uploaded images  
+✅ **Well Documented** - Comprehensive integration guide
+
+---
+
+## AI Integration Prompt
+
+**For AI Assistants:** Use this prompt to understand and integrate the File Upload module into an existing Next.js application.
+
+```
+The File Upload module has been appended to this Next.js project. Your task is to ensure it's properly integrated and functional.
+
+**Installed Packages:**
+- @aws-sdk/client-s3@^3.800.0 - AWS SDK for S3-compatible storage (Cloudflare R2)
+
+**Files Added:**
+- app/api/upload-image/route.ts - API route for handling image uploads (POST handler)
+- app/dashboard/upload/page.tsx - File upload interface with drag-and-drop
+- lib/upload-image.ts - R2 upload utility functions
+
+**Environment Variables Required:**
+- R2_UPLOAD_IMAGE_ACCESS_KEY_ID - Cloudflare R2 access key ID
+- R2_UPLOAD_IMAGE_SECRET_ACCESS_KEY - Cloudflare R2 secret access key
+- CLOUDFLARE_ACCOUNT_ID - Cloudflare account ID
+- R2_UPLOAD_IMAGE_BUCKET_NAME - R2 bucket name
+
+**Integration Steps:**
+1. Verify app/api/upload-image/route.ts exists and exports POST handler
+2. Check that upload page exists: app/dashboard/upload/page.tsx
+3. Verify upload utility exists: lib/upload-image.ts
+4. Ensure all R2 environment variables are set in .env.local
+5. Test upload API: POST multipart/form-data with file to /api/upload-image
+6. Test upload page: Visit /dashboard/upload
+7. If auth module installed: Verify upload routes are protected
+
+**Key Integration Points:**
+- API route: Handles multipart/form-data, validates file type/size, uploads to R2
+- File validation: Checks MIME type (image/jpeg, image/png, image/webp) and size (max 10MB)
+- R2 client: Uses S3Client from @aws-sdk/client-s3 with R2 endpoint
+- Public URLs: Generates public URLs for uploaded images (requires R2 public domain)
+- Upload UI: Drag-and-drop interface with progress tracking and image preview gallery
+
+**Dependencies:**
+- OPTIONAL: Auth module (for protecting upload routes)
+- No hard dependencies on other Shipd modules
+
+**Common Issues to Check:**
+- If "R2_UPLOAD_IMAGE_ACCESS_KEY_ID is not defined": Add all R2 env vars to .env.local
+- If upload fails with "Access Denied": Verify R2 API tokens have correct permissions
+- If public URLs not working: Configure public domain for R2 bucket and update lib/upload-image.ts
+- If "File too large" error: Check file size limits in route.ts (default: 10MB)
+
+**Next Steps After Integration:**
+- Set up Cloudflare R2 bucket
+- Generate R2 API tokens with read/write permissions
+- Add all R2 environment variables to .env.local
+- Configure public domain for bucket in Cloudflare dashboard
+- Update public URL domain in lib/upload-image.ts
+- Test upload functionality at /dashboard/upload
+- Add authentication checks if needed
+```

package/features/file-upload/app/api/upload-image/route.ts

@@ -0,0 +1,64 @@
+import { uploadImageAssets } from "@/lib/upload-image";
+import { NextRequest, NextResponse } from "next/server";
+
+export const config = {
+  api: { bodyParser: false }, // Disable default body parsing
+};
+
+export async function POST(req: NextRequest) {
+  try {
+    // Parse the form data
+    const formData = await req.formData();
+    const file = formData.get("file") as File | null;
+
+    if (!file) {
+      return NextResponse.json({ error: "No file provided" }, { status: 400 });
+    }
+
+    // Validate MIME type - only allow image files
+    const allowedMimeTypes = [
+      "image/jpeg",
+      "image/jpg",
+      "image/png",
+      "image/gif",
+      "image/webp",
+      "image/svg+xml",
+    ];
+
+    if (!allowedMimeTypes.includes(file.type)) {
+      return NextResponse.json(
+        { error: "Invalid file type. Only image files are allowed." },
+        { status: 400 },
+      );
+    }
+
+    // Validate file size - limit to 10MB
+    const maxSizeInBytes = 10 * 1024 * 1024; // 10MB
+    if (file.size > maxSizeInBytes) {
+      return NextResponse.json(
+        { error: "File too large. Maximum size allowed is 10MB." },
+        { status: 400 },
+      );
+    }
+
+    // Convert file to buffer
+    const arrayBuffer = await file.arrayBuffer();
+    const buffer = Buffer.from(arrayBuffer);
+
+    // Generate a unique filename with original extension
+    const fileExt = file.name.split(".").pop() || "";
+    const timestamp = Date.now();
+    const filename = `upload-${timestamp}.${fileExt || "png"}`;
+
+    // Upload the file
+    const url = await uploadImageAssets(buffer, filename);
+
+    return NextResponse.json({ url });
+  } catch (error) {
+    console.error("Upload error:", error);
+    return NextResponse.json(
+      { error: "Failed to process upload" },
+      { status: 500 },
+    );
+  }
+}