@xenterprises/fastify-xstorage 1.0.0

package/EXAMPLES.md

@@ -0,0 +1,797 @@
+# Examples
+
+Real-world examples showing how to use xStorage in production applications.
+
+## Table of Contents
+
+- [User Profile Pictures](#user-profile-pictures)
+- [Product Images with Variants](#product-images-with-variants)
+- [Document Management](#document-management)
+- [Photo Gallery](#photo-gallery)
+- [PDF Invoice System](#pdf-invoice-system)
+- [File Attachment System](#file-attachment-system)
+- [Image Optimization Pipeline](#image-optimization-pipeline)
+- [Multi-tenant File Storage](#multi-tenant-file-storage)
+
+## User Profile Pictures
+
+Upload user avatars with automatic thumbnail generation.
+
+```javascript
+import Fastify from "fastify";
+import multipart from "@fastify/multipart";
+import xStorage from "@xenterprises/fastify-xstorage";
+
+const fastify = Fastify({ logger: true });
+
+await fastify.register(multipart);
+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,
+});
+
+// Upload avatar
+fastify.post("/users/:userId/avatar", async (request, reply) => {
+  const { userId } = request.params;
+  const data = await request.file();
+
+  // Validate file type
+  if (!helpers.isImage(data.filename)) {
+    return reply.code(400).send({ error: "Only images allowed" });
+  }
+
+  const buffer = await data.toBuffer();
+
+  // Delete old avatar if exists
+  const user = await fastify.prisma.user.findUnique({
+    where: { id: userId },
+    select: { avatarKey: true, avatarThumbKey: true },
+  });
+
+  if (user.avatarKey) {
+    await fastify.storage.delete(user.avatarKey);
+    await fastify.storage.delete(user.avatarThumbKey);
+  }
+
+  // Upload new avatar with thumbnail
+  const result = await fastify.images.uploadWithThumbnails(buffer, data.filename, {
+    imageOptions: {
+      folder: `users/${userId}/avatar`,
+      quality: 85,
+      format: "webp",
+      resize: { width: 500, height: 500, fit: "cover" },
+    },
+    thumbnailOptions: {
+      folder: `users/${userId}/avatar/thumbs`,
+      sizes: [
+        { name: "small", width: 50, height: 50 },
+        { name: "medium", width: 150, height: 150 },
+      ],
+      format: "webp",
+      quality: 80,
+      fit: "cover",
+    },
+  });
+
+  // Update database
+  await fastify.prisma.user.update({
+    where: { id: userId },
+    data: {
+      avatarUrl: result.original.url,
+      avatarKey: result.original.key,
+      avatarThumbUrl: result.thumbnails.find((t) => t.size === "medium").url,
+      avatarThumbKey: result.thumbnails.find((t) => t.size === "medium").key,
+      avatarSmallUrl: result.thumbnails.find((t) => t.size === "small").url,
+    },
+  });
+
+  return {
+    success: true,
+    avatar: {
+      url: result.original.url,
+      thumbnail: result.thumbnails.find((t) => t.size === "medium").url,
+    },
+  };
+});
+
+// Delete avatar
+fastify.delete("/users/:userId/avatar", async (request, reply) => {
+  const { userId } = request.params;
+
+  const user = await fastify.prisma.user.findUnique({
+    where: { id: userId },
+    select: { avatarKey: true, avatarThumbKey: true },
+  });
+
+  if (user.avatarKey) {
+    await fastify.storage.delete(user.avatarKey);
+    await fastify.storage.delete(user.avatarThumbKey);
+
+    await fastify.prisma.user.update({
+      where: { id: userId },
+      data: {
+        avatarUrl: null,
+        avatarKey: null,
+        avatarThumbUrl: null,
+        avatarThumbKey: null,
+      },
+    });
+  }
+
+  return { success: true };
+});
+```
+
+## Product Images with Variants
+
+E-commerce product images with multiple sizes.
+
+```javascript
+fastify.post("/products/:productId/images", async (request, reply) => {
+  const { productId } = request.params;
+  const parts = request.parts();
+  const uploadedImages = [];
+
+  for await (const part of parts) {
+    if (part.type === "file") {
+      const buffer = await part.toBuffer();
+
+      // Generate multiple variants
+      const result = await fastify.images.uploadWithThumbnails(buffer, part.filename, {
+        imageOptions: {
+          folder: `products/${productId}`,
+          quality: 90,
+          format: "webp",
+          resize: { width: 2000, height: 2000, fit: "inside" },
+        },
+        thumbnailOptions: {
+          folder: `products/${productId}/variants`,
+          sizes: [
+            { name: "thumbnail", width: 100, height: 100 }, // Grid view
+            { name: "card", width: 300, height: 300 }, // Card view
+            { name: "detail", width: 800, height: 800 }, // Product detail
+            { name: "zoom", width: 1500, height: 1500 }, // Zoom view
+          ],
+          format: "webp",
+          quality: 85,
+          fit: "inside",
+        },
+      });
+
+      uploadedImages.push(result);
+    }
+  }
+
+  // Save to database
+  const createdImages = await fastify.prisma.productImage.createMany({
+    data: uploadedImages.map((img, index) => ({
+      productId,
+      position: index,
+      originalUrl: img.original.url,
+      originalKey: img.original.key,
+      thumbnailUrl: img.thumbnails.find((t) => t.size === "thumbnail").url,
+      cardUrl: img.thumbnails.find((t) => t.size === "card").url,
+      detailUrl: img.thumbnails.find((t) => t.size === "detail").url,
+      zoomUrl: img.thumbnails.find((t) => t.size === "zoom").url,
+      width: img.original.width,
+      height: img.original.height,
+    })),
+  });
+
+  return {
+    success: true,
+    images: uploadedImages,
+    count: uploadedImages.length,
+  };
+});
+
+// Reorder product images
+fastify.patch("/products/:productId/images/reorder", async (request, reply) => {
+  const { productId } = request.params;
+  const { imageIds } = request.body; // Array of image IDs in new order
+
+  await Promise.all(
+    imageIds.map((imageId, index) =>
+      fastify.prisma.productImage.update({
+        where: { id: imageId, productId },
+        data: { position: index },
+      })
+    )
+  );
+
+  return { success: true };
+});
+
+// Delete product image
+fastify.delete("/products/:productId/images/:imageId", async (request, reply) => {
+  const { productId, imageId } = request.params;
+
+  const image = await fastify.prisma.productImage.findUnique({
+    where: { id: imageId, productId },
+  });
+
+  if (!image) {
+    return reply.code(404).send({ error: "Image not found" });
+  }
+
+  // Delete all variants from storage
+  await fastify.storage.delete(image.originalKey);
+  await fastify.storage.delete(image.thumbnailUrl.replace(process.env.STORAGE_PUBLIC_URL + "/", ""));
+  await fastify.storage.delete(image.cardUrl.replace(process.env.STORAGE_PUBLIC_URL + "/", ""));
+  await fastify.storage.delete(image.detailUrl.replace(process.env.STORAGE_PUBLIC_URL + "/", ""));
+  await fastify.storage.delete(image.zoomUrl.replace(process.env.STORAGE_PUBLIC_URL + "/", ""));
+
+  // Delete from database
+  await fastify.prisma.productImage.delete({
+    where: { id: imageId },
+  });
+
+  return { success: true };
+});
+```
+
+## Document Management
+
+Upload and manage documents with metadata.
+
+```javascript
+import { helpers } from "@xenterprises/fastify-xstorage";
+
+fastify.post("/documents", async (request, reply) => {
+  const data = await request.file();
+  const { category, tags, description } = request.body;
+
+  // Validate file type
+  const allowedTypes = ["pdf", "doc", "docx", "xls", "xlsx", "txt"];
+  if (!helpers.isValidFileType(data.filename, allowedTypes)) {
+    return reply.code(400).send({
+      error: `Only ${allowedTypes.join(", ")} files allowed`,
+    });
+  }
+
+  const buffer = await data.toBuffer();
+  const isPdf = helpers.isPdf(data.filename);
+
+  // Upload document
+  let result;
+  if (isPdf) {
+    result = await fastify.pdfs.upload(buffer, data.filename, {
+      folder: `documents/${category}`,
+    });
+  } else {
+    result = await fastify.storage.upload(buffer, data.filename, {
+      folder: `documents/${category}`,
+      metadata: {
+        category,
+        uploadedBy: request.user.id,
+        uploadedAt: new Date().toISOString(),
+      },
+    });
+  }
+
+  // Save to database
+  const document = await fastify.prisma.document.create({
+    data: {
+      filename: data.filename,
+      originalFilename: data.filename,
+      url: result.url,
+      key: result.key,
+      size: result.size,
+      contentType: result.contentType,
+      category,
+      tags: tags ? tags.split(",") : [],
+      description,
+      pageCount: result.pageCount || null,
+      uploadedById: request.user.id,
+    },
+  });
+
+  return {
+    success: true,
+    document,
+  };
+});
+
+// Search documents
+fastify.get("/documents/search", async (request, reply) => {
+  const { q, category, tags } = request.query;
+
+  const documents = await fastify.prisma.document.findMany({
+    where: {
+      AND: [
+        q ? { originalFilename: { contains: q, mode: "insensitive" } } : {},
+        category ? { category } : {},
+        tags ? { tags: { hasSome: tags.split(",") } } : {},
+      ],
+    },
+    include: {
+      uploadedBy: {
+        select: { id: true, name: true, email: true },
+      },
+    },
+    orderBy: { createdAt: "desc" },
+  });
+
+  return {
+    success: true,
+    documents,
+    count: documents.length,
+  };
+});
+
+// Download document
+fastify.get("/documents/:id/download", async (request, reply) => {
+  const { id } = request.params;
+
+  const document = await fastify.prisma.document.findUnique({
+    where: { id },
+  });
+
+  if (!document) {
+    return reply.code(404).send({ error: "Document not found" });
+  }
+
+  // Generate signed URL for secure download
+  const signedUrl = await fastify.storage.getSignedUrl(document.key, 300); // 5 minutes
+
+  return reply.redirect(signedUrl);
+});
+```
+
+## Photo Gallery
+
+Build a photo gallery with albums.
+
+```javascript
+fastify.post("/albums/:albumId/photos", async (request, reply) => {
+  const { albumId } = request.params;
+  const parts = request.parts();
+  const uploadedPhotos = [];
+
+  for await (const part of parts) {
+    if (part.type === "file") {
+      const buffer = await part.toBuffer();
+
+      // Get image metadata
+      const metadata = await fastify.images.getMetadata(buffer);
+
+      // Upload with thumbnails
+      const result = await fastify.images.uploadWithThumbnails(buffer, part.filename, {
+        imageOptions: {
+          folder: `albums/${albumId}/photos`,
+          quality: 90,
+          format: "webp",
+        },
+        thumbnailOptions: {
+          folder: `albums/${albumId}/thumbnails`,
+          sizes: [
+            { name: "thumb", width: 200, height: 200 },
+            { name: "medium", width: 600, height: 600 },
+            { name: "large", width: 1200, height: 1200 },
+          ],
+          format: "webp",
+          quality: 80,
+          fit: "cover",
+        },
+      });
+
+      uploadedPhotos.push({
+        result,
+        metadata,
+      });
+    }
+  }
+
+  // Save to database
+  const photos = await fastify.prisma.photo.createMany({
+    data: uploadedPhotos.map((photo) => ({
+      albumId,
+      originalUrl: photo.result.original.url,
+      originalKey: photo.result.original.key,
+      thumbUrl: photo.result.thumbnails.find((t) => t.size === "thumb").url,
+      mediumUrl: photo.result.thumbnails.find((t) => t.size === "medium").url,
+      largeUrl: photo.result.thumbnails.find((t) => t.size === "large").url,
+      width: photo.result.original.width,
+      height: photo.result.original.height,
+      format: photo.metadata.format,
+    })),
+  });
+
+  return {
+    success: true,
+    photos: uploadedPhotos,
+    count: uploadedPhotos.length,
+  };
+});
+
+// Get album with photos
+fastify.get("/albums/:albumId", async (request, reply) => {
+  const { albumId } = request.params;
+
+  const album = await fastify.prisma.album.findUnique({
+    where: { id: albumId },
+    include: {
+      photos: {
+        orderBy: { createdAt: "desc" },
+      },
+    },
+  });
+
+  if (!album) {
+    return reply.code(404).send({ error: "Album not found" });
+  }
+
+  return {
+    success: true,
+    album,
+  };
+});
+
+// Delete album (with all photos)
+fastify.delete("/albums/:albumId", async (request, reply) => {
+  const { albumId } = request.params;
+
+  const photos = await fastify.prisma.photo.findMany({
+    where: { albumId },
+  });
+
+  // Delete all photos from storage
+  const keys = photos.flatMap((photo) => [
+    photo.originalKey,
+    helpers.getKeyFromUrl(photo.thumbUrl, process.env.STORAGE_PUBLIC_URL),
+    helpers.getKeyFromUrl(photo.mediumUrl, process.env.STORAGE_PUBLIC_URL),
+    helpers.getKeyFromUrl(photo.largeUrl, process.env.STORAGE_PUBLIC_URL),
+  ]);
+
+  await fastify.storage.deleteMultiple(keys);
+
+  // Delete from database
+  await fastify.prisma.album.delete({
+    where: { id: albumId },
+  });
+
+  return { success: true };
+});
+```
+
+## PDF Invoice System
+
+Generate and store PDF invoices.
+
+```javascript
+import { PDFDocument, StandardFonts, rgb } from "pdf-lib";
+
+fastify.post("/invoices/:invoiceId/generate", async (request, reply) => {
+  const { invoiceId } = request.params;
+
+  // Get invoice data
+  const invoice = await fastify.prisma.invoice.findUnique({
+    where: { id: invoiceId },
+    include: {
+      customer: true,
+      items: true,
+    },
+  });
+
+  // Create PDF (simplified example)
+  const pdfDoc = await PDFDocument.create();
+  const page = pdfDoc.addPage([600, 800]);
+  const font = await pdfDoc.embedFont(StandardFonts.Helvetica);
+
+  page.drawText(`Invoice #${invoice.number}`, {
+    x: 50,
+    y: 750,
+    size: 24,
+    font,
+  });
+
+  page.drawText(`Customer: ${invoice.customer.name}`, {
+    x: 50,
+    y: 700,
+    size: 12,
+    font,
+  });
+
+  // ... add more content
+
+  const pdfBytes = await pdfDoc.save();
+  const pdfBuffer = Buffer.from(pdfBytes);
+
+  // Upload to storage
+  const result = await fastify.pdfs.upload(pdfBuffer, `invoice-${invoice.number}.pdf`, {
+    folder: `invoices/${new Date().getFullYear()}`,
+  });
+
+  // Update database
+  await fastify.prisma.invoice.update({
+    where: { id: invoiceId },
+    data: {
+      pdfUrl: result.url,
+      pdfKey: result.key,
+    },
+  });
+
+  return {
+    success: true,
+    invoice: {
+      id: invoice.id,
+      pdfUrl: result.url,
+    },
+  };
+});
+
+// Merge multiple invoices
+fastify.post("/invoices/merge", async (request, reply) => {
+  const { invoiceIds } = request.body;
+
+  // Download all invoice PDFs
+  const invoices = await fastify.prisma.invoice.findMany({
+    where: { id: { in: invoiceIds } },
+  });
+
+  const pdfBuffers = await Promise.all(
+    invoices.map((invoice) => fastify.storage.download(invoice.pdfKey))
+  );
+
+  // Merge PDFs
+  const merged = await fastify.pdfs.merge(pdfBuffers, "merged-invoices.pdf", {
+    folder: "invoices/merged",
+  });
+
+  return {
+    success: true,
+    pdf: merged,
+  };
+});
+```
+
+## File Attachment System
+
+Generic file attachment system for any model.
+
+```javascript
+fastify.post("/attachments", async (request, reply) => {
+  const data = await request.file();
+  const { attachableType, attachableId, name, description } = request.body;
+
+  const buffer = await data.toBuffer();
+
+  // Determine folder based on type
+  const folder = `attachments/${attachableType.toLowerCase()}s/${attachableId}`;
+
+  // Upload file
+  const result = await fastify.storage.upload(buffer, data.filename, {
+    folder,
+    metadata: {
+      attachableType,
+      attachableId,
+      uploadedBy: request.user.id,
+    },
+  });
+
+  // Save to database
+  const attachment = await fastify.prisma.attachment.create({
+    data: {
+      name: name || data.filename,
+      description,
+      filename: data.filename,
+      url: result.url,
+      key: result.key,
+      size: result.size,
+      contentType: result.contentType,
+      attachableType,
+      attachableId,
+      uploadedById: request.user.id,
+    },
+  });
+
+  return {
+    success: true,
+    attachment,
+  };
+});
+
+// Get attachments for a resource
+fastify.get("/attachments/:attachableType/:attachableId", async (request, reply) => {
+  const { attachableType, attachableId } = request.params;
+
+  const attachments = await fastify.prisma.attachment.findMany({
+    where: {
+      attachableType,
+      attachableId,
+    },
+    include: {
+      uploadedBy: {
+        select: { id: true, name: true },
+      },
+    },
+    orderBy: { createdAt: "desc" },
+  });
+
+  return {
+    success: true,
+    attachments,
+  };
+});
+
+// Example usage:
+// POST /attachments
+// {
+//   attachableType: "Post",
+//   attachableId: "post-123",
+//   file: [file]
+// }
+//
+// GET /attachments/Post/post-123
+```
+
+## Image Optimization Pipeline
+
+Automatically optimize and resize images on upload.
+
+```javascript
+fastify.post("/uploads/optimize", async (request, reply) => {
+  const data = await request.file();
+
+  if (!helpers.isImage(data.filename)) {
+    return reply.code(400).send({ error: "Only images allowed" });
+  }
+
+  const buffer = await data.toBuffer();
+
+  // Get original metadata
+  const metadata = await fastify.images.getMetadata(buffer);
+
+  // Generate responsive sizes
+  const responsiveSizes = helpers.generateResponsiveSizes(metadata.width, metadata.height);
+
+  // Upload original (optimized)
+  const original = await fastify.images.upload(buffer, data.filename, {
+    folder: "images/originals",
+    quality: 90,
+    format: "webp",
+  });
+
+  // Generate responsive variants
+  const variants = await Promise.all(
+    responsiveSizes.map(async (size) => {
+      const resized = await fastify.images.upload(buffer, data.filename, {
+        folder: `images/responsive/${size.name}`,
+        quality: 85,
+        format: "webp",
+        resize: {
+          width: size.width,
+          height: size.height,
+          fit: "inside",
+        },
+      });
+
+      return {
+        size: size.name,
+        width: size.width,
+        height: size.height,
+        url: resized.url,
+        key: resized.key,
+      };
+    })
+  );
+
+  return {
+    success: true,
+    image: {
+      original,
+      variants,
+      metadata,
+    },
+  };
+});
+```
+
+## Multi-tenant File Storage
+
+Isolate files by tenant/organization.
+
+```javascript
+// Middleware to get tenant
+fastify.decorateRequest("tenant", null);
+
+fastify.addHook("preHandler", async (request, reply) => {
+  const tenantId = request.headers["x-tenant-id"];
+
+  if (!tenantId) {
+    return reply.code(400).send({ error: "Tenant ID required" });
+  }
+
+  const tenant = await fastify.prisma.tenant.findUnique({
+    where: { id: tenantId },
+  });
+
+  if (!tenant) {
+    return reply.code(404).send({ error: "Tenant not found" });
+  }
+
+  request.tenant = tenant;
+});
+
+// Upload file for tenant
+fastify.post("/files", async (request, reply) => {
+  const data = await request.file();
+  const buffer = await data.toBuffer();
+
+  // Upload to tenant-specific folder
+  const result = await fastify.storage.upload(buffer, data.filename, {
+    folder: `tenants/${request.tenant.id}/files`,
+    metadata: {
+      tenantId: request.tenant.id,
+      uploadedBy: request.user.id,
+    },
+  });
+
+  // Save to database
+  const file = await fastify.prisma.file.create({
+    data: {
+      tenantId: request.tenant.id,
+      filename: data.filename,
+      url: result.url,
+      key: result.key,
+      size: result.size,
+      uploadedById: request.user.id,
+    },
+  });
+
+  return {
+    success: true,
+    file,
+  };
+});
+
+// List tenant files
+fastify.get("/files", async (request, reply) => {
+  const files = await fastify.prisma.file.findMany({
+    where: { tenantId: request.tenant.id },
+    orderBy: { createdAt: "desc" },
+  });
+
+  return {
+    success: true,
+    files,
+  };
+});
+
+// Delete tenant file (with authorization check)
+fastify.delete("/files/:id", async (request, reply) => {
+  const { id } = request.params;
+
+  const file = await fastify.prisma.file.findUnique({
+    where: { id },
+  });
+
+  if (!file) {
+    return reply.code(404).send({ error: "File not found" });
+  }
+
+  // Ensure file belongs to tenant
+  if (file.tenantId !== request.tenant.id) {
+    return reply.code(403).send({ error: "Access denied" });
+  }
+
+  // Delete from storage
+  await fastify.storage.delete(file.key);
+
+  // Delete from database
+  await fastify.prisma.file.delete({
+    where: { id },
+  });
+
+  return { success: true };
+});
+```
+
+## Next Steps
+
+- See [README.md](./README.md) for complete API reference
+- See [TESTING.md](./TESTING.md) for testing guide