@xenterprises/fastify-xstorage 1.0.0

package/QUICK_START.md

@@ -0,0 +1,345 @@
+# Quick Start Guide
+
+Get up and running with xStorage in 5 minutes.
+
+## 1. Install
+
+```bash
+npm install @xenterprises/fastify-xstorage @aws-sdk/client-s3 @aws-sdk/s3-request-presigner @fastify/multipart
+```
+
+**For image processing** (optional), also install [@xenterprises/fastify-ximagepipeline](https://github.com/x-enterprises/fastify-plugins/tree/main/fastify-ximagepipeline)
+
+## 2. Setup Storage Provider
+
+### Digital Ocean Spaces
+
+1. Go to https://cloud.digitalocean.com/spaces
+2. Create a new Space
+3. Go to API → Tokens/Keys
+4. Generate new Spaces access key
+5. Configure CORS in your Space settings
+
+### AWS S3
+
+1. Go to https://console.aws.amazon.com/s3
+2. Create new bucket
+3. Go to IAM → Users → Create user
+4. Attach policy: `AmazonS3FullAccess`
+5. Create access keys
+
+### Cloudflare R2
+
+1. Go to https://dash.cloudflare.com/r2
+2. Create new bucket
+3. Create API token with R2 edit permissions
+4. Set up custom domain (optional)
+
+## 3. Configure Environment
+
+Create `.env`:
+
+```bash
+# Digital Ocean Spaces
+STORAGE_ENDPOINT=https://nyc3.digitaloceanspaces.com
+STORAGE_REGION=us-east-1
+STORAGE_ACCESS_KEY_ID=your_access_key_here
+STORAGE_SECRET_ACCESS_KEY=your_secret_key_here
+STORAGE_BUCKET=your-bucket-name
+STORAGE_PUBLIC_URL=https://your-bucket-name.nyc3.digitaloceanspaces.com
+
+PORT=3000
+```
+
+## 4. Basic Setup
+
+```javascript
+import Fastify from "fastify";
+import multipart from "@fastify/multipart";
+import xStorage from "@xenterprises/fastify-xstorage";
+
+const fastify = Fastify({ logger: true });
+
+// Register multipart for file uploads
+await fastify.register(multipart, {
+  limits: {
+    fileSize: 10 * 1024 * 1024, // 10MB
+  },
+});
+
+// Register xStorage
+await fastify.register(xStorage, {
+  endpoint: process.env.STORAGE_ENDPOINT,
+  region: process.env.STORAGE_REGION,
+  accessKeyId: process.env.STORAGE_ACCESS_KEY_ID,
+  secretAccessKey: process.env.STORAGE_SECRET_ACCESS_KEY,
+  bucket: process.env.STORAGE_BUCKET,
+  publicUrl: process.env.STORAGE_PUBLIC_URL,
+});
+
+await fastify.listen({ port: 3000 });
+```
+
+## 5. Upload Files
+
+```javascript
+fastify.post("/upload", async (request, reply) => {
+  const data = await request.file();
+  const buffer = await data.toBuffer();
+
+  const result = await fastify.xStorage.upload(buffer, data.filename, {
+    folder: "uploads",
+  });
+
+  // Store in your database
+  return {
+    success: true,
+    file: {
+      storageKey: result.key, // Store for deletion
+      url: result.url,
+      size: result.size,
+      contentType: result.contentType,
+    },
+  };
+});
+```
+
+**For image uploads with processing**, use [@xenterprises/fastify-ximagepipeline](https://github.com/x-enterprises/fastify-plugins/tree/main/fastify-ximagepipeline) for:
+- Automatic optimization and format conversion
+- Thumbnail generation
+- EXIF stripping
+- Multiple variant generation (WebP, AVIF)
+
+## 6. Store in Database
+
+Example with Prisma:
+
+```javascript
+fastify.post("/upload", async (request, reply) => {
+  const data = await request.file();
+  const buffer = await data.toBuffer();
+
+  // Upload to storage
+  const result = await fastify.xStorage.upload(buffer, data.filename, {
+    folder: "uploads",
+  });
+
+  // Save to database
+  const file = await fastify.prisma.file.create({
+    data: {
+      filename: data.filename,
+      storageKey: result.key, // Store for deletion
+      size: result.size,
+      contentType: result.contentType,
+      userId: request.user.id,
+    },
+  });
+
+  return { success: true, file };
+});
+```
+
+## 7. Delete Files
+
+```javascript
+fastify.delete("/files/:id", async (request, reply) => {
+  const { id } = request.params;
+
+  // Get file from database
+  const file = await fastify.prisma.file.findUnique({
+    where: { id },
+  });
+
+  // Delete from storage
+  await fastify.xStorage.delete(file.storageKey);
+
+  // Delete from database
+  await fastify.prisma.file.delete({
+    where: { id },
+  });
+
+  return { success: true };
+});
+```
+
+## 8. Test Locally
+
+```bash
+# Start server
+npm run dev
+
+# Upload a file
+curl -X POST http://localhost:3000/upload \
+  -F "file=@./test-image.jpg"
+
+# You'll get back:
+{
+  "success": true,
+  "file": {
+    "url": "https://your-bucket.nyc3.digitaloceanspaces.com/uploads/test-image-a1b2c3d4.jpg",
+    "key": "uploads/test-image-a1b2c3d4.jpg",
+    "size": 245678
+  }
+}
+
+# Visit the URL in your browser to verify it works!
+```
+
+## Common Use Cases
+
+### Document Upload with Validation
+
+```javascript
+import { helpers } from "@xenterprises/fastify-xstorage";
+
+fastify.post("/documents", async (request, reply) => {
+  const data = await request.file();
+
+  // Validate file type
+  if (!helpers.isPdf(data.filename) && !helpers.isImage(data.filename)) {
+    return reply.code(400).send({ error: "Only PDF and images allowed" });
+  }
+
+  const buffer = await data.toBuffer();
+
+  // Upload file
+  const result = await fastify.xStorage.upload(buffer, data.filename, {
+    folder: "documents",
+  });
+
+  // For images, use xImagePipeline for processing
+  // For PDFs, store as-is
+
+  await fastify.prisma.document.create({
+    data: {
+      filename: data.filename,
+      storageKey: result.key,
+      size: result.size,
+      contentType: result.contentType,
+    },
+  });
+
+  return { success: true, document: result };
+});
+```
+
+### Generate Signed URLs for Private Files
+
+```javascript
+// Get download URL for private file
+fastify.get("/documents/:id/download", async (request, reply) => {
+  const { id } = request.params;
+
+  const document = await fastify.prisma.document.findUnique({ where: { id } });
+
+  // Generate signed URL valid for 1 hour
+  const signedUrl = await fastify.xStorage.getSignedUrl(
+    document.storageKey,
+    3600
+  );
+
+  return { download: signedUrl };
+});
+```
+
+### Batch Upload
+
+```javascript
+fastify.post("/batch-upload", async (request, reply) => {
+  const parts = request.parts();
+  const files = [];
+
+  for await (const part of parts) {
+    if (part.type === "file") {
+      const buffer = await part.toBuffer();
+      files.push({ file: buffer, filename: part.filename });
+    }
+  }
+
+  const results = await fastify.xStorage.uploadMultiple(files, {
+    folder: "batch-uploads",
+  });
+
+  return { success: true, files: results };
+});
+```
+
+### Image Processing
+
+For user avatars, product images, and other image processing needs, use **[@xenterprises/fastify-ximagepipeline](https://github.com/x-enterprises/fastify-plugins/tree/main/fastify-ximagepipeline)** which handles:
+- Automatic optimization and resizing
+- WebP/AVIF conversion
+- Thumbnail generation with multiple sizes
+- EXIF stripping
+- Blur hash generation
+
+## Tips
+
+1. **Always store the storage key** in your database
+   - `storageKey` - For deleting or accessing files later
+   - Store reference to key, not just the URL
+
+2. **Use folders** to organize files logically
+   ```javascript
+   folder: "users/123/documents"
+   folder: "invoices/2024/january"
+   folder: "receipts/2024"
+   ```
+
+3. **Use signed URLs for private files**
+   ```javascript
+   const signedUrl = await fastify.xStorage.getSignedUrl(key, 3600);
+   // Expires in 1 hour
+   ```
+
+4. **Validate file types** before uploading
+   ```javascript
+   import { helpers } from "@xenterprises/fastify-xstorage";
+
+   if (!helpers.isPdf(filename)) {
+     return reply.code(400).send({ error: "Only PDFs allowed" });
+   }
+   ```
+
+5. **Delete old files** when replacing
+   ```javascript
+   if (oldFile.storageKey) {
+     await fastify.xStorage.delete(oldFile.storageKey);
+   }
+   ```
+
+6. **Use batch operations** for better performance
+   ```javascript
+   await fastify.xStorage.uploadMultiple(files, { folder: "uploads" });
+   await fastify.xStorage.deleteMultiple(keys);
+   ```
+
+## Next Steps
+
+- [Full Documentation](./README.md)
+- [Testing Guide](./TESTING.md)
+- [Complete Examples](./EXAMPLES.md)
+
+## Troubleshooting
+
+### Files not uploading?
+
+1. Check credentials are correct
+2. Verify bucket exists and is accessible
+3. Check IAM permissions (should allow S3 operations)
+4. Ensure CORS is configured on bucket
+5. Check file size limits
+
+### Signed URLs not working?
+
+1. Verify credentials are correct
+2. Check file actually exists in bucket
+3. Check URL hasn't expired
+4. Try with longer expiration time
+
+### Connection issues?
+
+1. Verify `endpoint` URL is correct
+2. Check network connectivity to S3 provider
+3. Ensure credentials haven't expired
+4. Verify region is correct for AWS S3