shipd 0.1.3 → 0.1.4

package/features/file-upload/README.md

@@ -0,0 +1,271 @@
+# 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
+

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 },
+    );
+  }
+}

package/features/file-upload/app/dashboard/upload/page.tsx

@@ -0,0 +1,324 @@
+"use client";
+
+import { Button } from "@/components/ui/button";
+import {
+  Card,
+  CardContent,
+  CardDescription,
+  CardHeader,
+  CardTitle,
+} from "@/components/ui/card";
+import { Input } from "@/components/ui/input";
+import { Progress } from "@/components/ui/progress";
+import { Check, FileImage, Upload, X } from "lucide-react";
+import Image from "next/image";
+import { useCallback, useState } from "react";
+import { toast } from "sonner";
+
+interface UploadedFile {
+  id: string;
+  name: string;
+  url: string;
+  size: number;
+  type: string;
+  uploadedAt: Date;
+}
+
+export default function UploadPage() {
+  const [uploading, setUploading] = useState(false);
+  const [uploadProgress, setUploadProgress] = useState(0);
+  const [uploadedFiles, setUploadedFiles] = useState<UploadedFile[]>([]);
+  const [dragActive, setDragActive] = useState(false);
+
+  const handleFileUpload = async (files: FileList | File[]) => {
+    const fileArray = Array.from(files);
+
+    for (const file of fileArray) {
+      if (!file.type.startsWith("image/")) {
+        toast.error(`${file.name} is not an image file`);
+        continue;
+      }
+
+      if (file.size > 5 * 1024 * 1024) {
+        toast.error(`${file.name} is too large (max 5MB)`);
+        continue;
+      }
+
+      setUploading(true);
+      setUploadProgress(0);
+
+      try {
+        const formData = new FormData();
+        formData.append("file", file);
+
+        // Simulate progress
+        const progressInterval = setInterval(() => {
+          setUploadProgress((prev) => {
+            if (prev >= 90) {
+              clearInterval(progressInterval);
+              return prev;
+            }
+            return prev + Math.random() * 20;
+          });
+        }, 200);
+
+        const response = await fetch("/api/upload-image", {
+          method: "POST",
+          body: formData,
+        });
+
+        clearInterval(progressInterval);
+        setUploadProgress(100);
+
+        if (!response.ok) {
+          throw new Error("Upload failed");
+        }
+
+        const { url } = await response.json();
+
+        const uploadedFile: UploadedFile = {
+          id: crypto.randomUUID(),
+          name: file.name,
+          url,
+          size: file.size,
+          type: file.type,
+          uploadedAt: new Date(),
+        };
+
+        setUploadedFiles((prev) => [uploadedFile, ...prev]);
+        toast.success(`${file.name} uploaded successfully`);
+      } catch (error) {
+        console.error("Upload error:", error);
+        toast.error(`Failed to upload ${file.name}`);
+      } finally {
+        setUploading(false);
+        setUploadProgress(0);
+      }
+    }
+  };
+
+  const handleDrag = useCallback((e: React.DragEvent) => {
+    e.preventDefault();
+    e.stopPropagation();
+    if (e.type === "dragenter" || e.type === "dragover") {
+      setDragActive(true);
+    } else if (e.type === "dragleave") {
+      setDragActive(false);
+    }
+  }, []);
+
+  const handleDrop = useCallback((e: React.DragEvent) => {
+    e.preventDefault();
+    e.stopPropagation();
+    setDragActive(false);
+
+    if (e.dataTransfer.files && e.dataTransfer.files[0]) {
+      handleFileUpload(e.dataTransfer.files);
+    }
+  }, []);
+
+  const handleInputChange = (e: React.ChangeEvent<HTMLInputElement>) => {
+    if (e.target.files && e.target.files[0]) {
+      handleFileUpload(e.target.files);
+    }
+  };
+
+  const removeFile = (id: string) => {
+    setUploadedFiles((prev) => prev.filter((file) => file.id !== id));
+  };
+
+  const formatFileSize = (bytes: number) => {
+    if (bytes === 0) return "0 Bytes";
+    const k = 1024;
+    const sizes = ["Bytes", "KB", "MB", "GB"];
+    const i = Math.floor(Math.log(bytes) / Math.log(k));
+    return parseFloat((bytes / Math.pow(k, i)).toFixed(2)) + " " + sizes[i];
+  };
+
+  return (
+    <div className="p-6 space-y-6">
+      <div>
+        <h1 className="text-3xl font-semibold tracking-tight">File Upload</h1>
+        <p className="text-muted-foreground mt-2">
+          Upload images to Cloudflare R2 storage with drag and drop support
+        </p>
+      </div>
+
+      <div className="grid gap-6 md:grid-cols-2">
+        {/* Upload Area */}
+        <Card>
+          <CardHeader>
+            <CardTitle className="flex items-center gap-2">
+              <Upload className="h-5 w-5" />
+              Upload Images
+            </CardTitle>
+            <CardDescription>
+              Upload images to Cloudflare R2. Maximum file size is 5MB.
+            </CardDescription>
+          </CardHeader>
+          <CardContent className="space-y-4">
+            <div
+              className={`relative border-2 border-dashed rounded-lg p-8 text-center transition-colors ${
+                dragActive
+                  ? "border-primary bg-primary/5"
+                  : "border-muted-foreground/25 hover:border-muted-foreground/50"
+              }`}
+              onDragEnter={handleDrag}
+              onDragLeave={handleDrag}
+              onDragOver={handleDrag}
+              onDrop={handleDrop}
+            >
+              <Input
+                type="file"
+                accept="image/*"
+                multiple
+                onChange={handleInputChange}
+                className="absolute inset-0 w-full h-full opacity-0 cursor-pointer"
+                disabled={uploading}
+              />
+              <div className="space-y-2">
+                <FileImage className="h-10 w-10 mx-auto text-muted-foreground" />
+                <div>
+                  <p className="text-sm font-medium">
+                    {dragActive
+                      ? "Drop files here"
+                      : "Click to upload or drag and drop"}
+                  </p>
+                  <p className="text-xs text-muted-foreground">
+                    PNG, JPG, GIF up to 5MB
+                  </p>
+                </div>
+              </div>
+            </div>
+
+            {uploading && (
+              <div className="space-y-2">
+                <div className="flex items-center justify-between text-sm">
+                  <span>Uploading...</span>
+                  <span>{Math.round(uploadProgress)}%</span>
+                </div>
+                <Progress value={uploadProgress} className="h-2" />
+              </div>
+            )}
+          </CardContent>
+        </Card>
+
+        {/* Upload Info */}
+        <Card>
+          <CardHeader>
+            <CardTitle>About R2 Storage</CardTitle>
+            <CardDescription>
+              Cloudflare R2 provides S3-compatible object storage
+            </CardDescription>
+          </CardHeader>
+          <CardContent className="space-y-4">
+            <div className="space-y-3">
+              <div className="flex items-start gap-3">
+                <Check className="h-4 w-4 text-green-500 mt-0.5" />
+                <div className="text-sm">
+                  <p className="font-medium">Global CDN</p>
+                  <p className="text-muted-foreground">
+                    Fast delivery worldwide
+                  </p>
+                </div>
+              </div>
+              <div className="flex items-start gap-3">
+                <Check className="h-4 w-4 text-green-500 mt-0.5" />
+                <div className="text-sm">
+                  <p className="font-medium">Zero Egress Fees</p>
+                  <p className="text-muted-foreground">No bandwidth charges</p>
+                </div>
+              </div>
+              <div className="flex items-start gap-3">
+                <Check className="h-4 w-4 text-green-500 mt-0.5" />
+                <div className="text-sm">
+                  <p className="font-medium">S3 Compatible</p>
+                  <p className="text-muted-foreground">
+                    Works with existing tools
+                  </p>
+                </div>
+              </div>
+              <div className="flex items-start gap-3">
+                <Check className="h-4 w-4 text-green-500 mt-0.5" />
+                <div className="text-sm">
+                  <p className="font-medium">Auto Scaling</p>
+                  <p className="text-muted-foreground">Handles any file size</p>
+                </div>
+              </div>
+            </div>
+          </CardContent>
+        </Card>
+      </div>
+
+      {/* Uploaded Files */}
+      {uploadedFiles.length > 0 && (
+        <Card>
+          <CardHeader>
+            <CardTitle>Uploaded Files ({uploadedFiles.length})</CardTitle>
+            <CardDescription>
+              Recently uploaded images to R2 storage
+            </CardDescription>
+          </CardHeader>
+          <CardContent>
+            <div className="grid gap-4 sm:grid-cols-2 lg:grid-cols-3">
+              {uploadedFiles.map((file) => (
+                <div
+                  key={file.id}
+                  className="group relative border rounded-lg overflow-hidden hover:shadow-md transition-shadow"
+                >
+                  <div className="aspect-video relative bg-muted">
+                    <Image
+                      src={file.url}
+                      alt={file.name}
+                      fill
+                      className="object-cover"
+                      sizes="(max-width: 768px) 100vw, (max-width: 1200px) 50vw, 33vw"
+                    />
+                  </div>
+                  <div className="p-3">
+                    <p
+                      className="font-medium text-sm truncate"
+                      title={file.name}
+                    >
+                      {file.name}
+                    </p>
+                    <div className="flex items-center justify-between text-xs text-muted-foreground mt-1">
+                      <span>{formatFileSize(file.size)}</span>
+                      <span>{file.uploadedAt.toLocaleDateString()}</span>
+                    </div>
+                    <div className="mt-2 flex items-center gap-2">
+                      <Button
+                        size="sm"
+                        variant="outline"
+                        onClick={() => navigator.clipboard.writeText(file.url)}
+                        className="flex-1 text-xs"
+                      >
+                        Copy URL
+                      </Button>
+                      <Button
+                        size="sm"
+                        variant="outline"
+                        onClick={() => window.open(file.url, "_blank")}
+                        className="flex-1 text-xs"
+                      >
+                        Open
+                      </Button>
+                    </div>
+                  </div>
+                  <Button
+                    size="sm"
+                    variant="ghost"
+                    onClick={() => removeFile(file.id)}
+                    className="absolute top-2 right-2 h-8 w-8 p-0 opacity-0 group-hover:opacity-100 transition-opacity bg-background/80 hover:bg-background"
+                  >
+                    <X className="h-4 w-4" />
+                  </Button>
+                </div>
+              ))}
+            </div>
+          </CardContent>
+        </Card>
+      )}
+    </div>
+  );
+}

package/features/file-upload/feature.config.json

@@ -0,0 +1,23 @@
+{
+  "name": "file-upload",
+  "version": "1.0.0",
+  "description": "Cloudflare R2 file upload with drag-and-drop interface",
+  "dependencies": {
+    "@aws-sdk/client-s3": "^3.800.0"
+  },
+  "devDependencies": {},
+  "envVars": [
+    "R2_UPLOAD_IMAGE_ACCESS_KEY_ID",
+    "R2_UPLOAD_IMAGE_SECRET_ACCESS_KEY",
+    "CLOUDFLARE_ACCOUNT_ID",
+    "R2_UPLOAD_IMAGE_BUCKET_NAME"
+  ],
+  "files": [
+    "app/api/upload-image/**/*",
+    "app/dashboard/upload/**/*",
+    "lib/upload-image.ts"
+  ],
+  "requires": [],
+  "conflicts": []
+}
+