servcraft 0.1.0 → 0.1.3

package/docs/modules/SWAGGER.md

@@ -0,0 +1,305 @@
+# Swagger Module
+
+OpenAPI 3.0 documentation with Swagger UI integration.
+
+## Features
+
+- **OpenAPI 3.0** - Full OpenAPI specification support
+- **Swagger UI** - Interactive API documentation at `/docs`
+- **JWT Auth** - Bearer token authentication support
+- **Common Schemas** - Pre-built response schemas
+- **Zod Integration** - Convert Zod schemas to JSON Schema
+
+## Usage
+
+### Basic Setup
+
+```typescript
+import Fastify from 'fastify';
+import { registerSwagger } from 'servcraft/modules/swagger';
+
+const app = Fastify();
+
+await registerSwagger(app, {
+  title: 'My API',
+  description: 'API documentation',
+  version: '1.0.0',
+  tags: [
+    { name: 'Auth', description: 'Authentication endpoints' },
+    { name: 'Users', description: 'User management' },
+    { name: 'Products', description: 'Product catalog' },
+  ],
+  servers: [
+    { url: 'http://localhost:3000', description: 'Development' },
+    { url: 'https://api.example.com', description: 'Production' },
+  ],
+  contact: {
+    name: 'API Support',
+    email: 'support@example.com',
+  },
+  license: {
+    name: 'MIT',
+    url: 'https://opensource.org/licenses/MIT',
+  },
+});
+
+// Documentation available at http://localhost:3000/docs
+```
+
+### Route Documentation
+
+```typescript
+fastify.post('/api/users', {
+  schema: {
+    description: 'Create a new user',
+    tags: ['Users'],
+    summary: 'Create user',
+    body: {
+      type: 'object',
+      required: ['email', 'password', 'name'],
+      properties: {
+        email: { type: 'string', format: 'email' },
+        password: { type: 'string', minLength: 8 },
+        name: { type: 'string' },
+      },
+    },
+    response: {
+      201: {
+        description: 'User created successfully',
+        type: 'object',
+        properties: {
+          success: { type: 'boolean' },
+          data: {
+            type: 'object',
+            properties: {
+              id: { type: 'string', format: 'uuid' },
+              email: { type: 'string' },
+              name: { type: 'string' },
+            },
+          },
+        },
+      },
+      400: commonResponses.error,
+    },
+    security: [{ bearerAuth: [] }],
+  },
+}, async (request, reply) => {
+  // Handler
+});
+```
+
+### Common Response Schemas
+
+```typescript
+import { commonResponses, paginationQuery, idParam } from 'servcraft/modules/swagger';
+
+// Success response
+commonResponses.success
+// { success: boolean, data: object }
+
+// Error response
+commonResponses.error
+// { success: boolean, message: string, errors: object }
+
+// Unauthorized
+commonResponses.unauthorized
+// { success: boolean, message: 'Unauthorized' }
+
+// Not found
+commonResponses.notFound
+// { success: boolean, message: 'Resource not found' }
+
+// Paginated response
+commonResponses.paginated
+// { success: boolean, data: { data: [], meta: { total, page, ... } } }
+```
+
+### Query Parameters
+
+```typescript
+// Pagination query parameters
+fastify.get('/api/users', {
+  schema: {
+    querystring: paginationQuery,
+    // Adds: page, limit, sortBy, sortOrder, search
+  },
+});
+
+// ID parameter
+fastify.get('/api/users/:id', {
+  schema: {
+    params: idParam,
+    // Adds: id (uuid)
+  },
+});
+```
+
+### Authentication
+
+```typescript
+// Protected route
+fastify.get('/api/profile', {
+  schema: {
+    tags: ['Users'],
+    security: [{ bearerAuth: [] }],
+    response: {
+      200: userSchema,
+      401: commonResponses.unauthorized,
+    },
+  },
+});
+
+// Public route (no security)
+fastify.get('/api/public', {
+  schema: {
+    tags: ['Public'],
+    // No security property = public endpoint
+  },
+});
+```
+
+## Configuration
+
+```typescript
+interface SwaggerConfig {
+  title: string;
+  description?: string;
+  version: string;
+  tags?: Array<{
+    name: string;
+    description?: string;
+  }>;
+  servers?: Array<{
+    url: string;
+    description?: string;
+  }>;
+  contact?: {
+    name?: string;
+    email?: string;
+    url?: string;
+  };
+  license?: {
+    name: string;
+    url?: string;
+  };
+}
+```
+
+## Schema Examples
+
+### User Schema
+
+```typescript
+const userSchema = {
+  type: 'object',
+  properties: {
+    id: { type: 'string', format: 'uuid' },
+    email: { type: 'string', format: 'email' },
+    name: { type: 'string' },
+    role: { type: 'string', enum: ['user', 'admin'] },
+    createdAt: { type: 'string', format: 'date-time' },
+  },
+};
+```
+
+### Request Body
+
+```typescript
+const createUserBody = {
+  type: 'object',
+  required: ['email', 'password'],
+  properties: {
+    email: {
+      type: 'string',
+      format: 'email',
+      description: 'User email address',
+    },
+    password: {
+      type: 'string',
+      minLength: 8,
+      description: 'Password (min 8 characters)',
+    },
+    name: {
+      type: 'string',
+      maxLength: 100,
+      description: 'Display name',
+    },
+  },
+};
+```
+
+### Array Response
+
+```typescript
+const usersListResponse = {
+  type: 'object',
+  properties: {
+    success: { type: 'boolean' },
+    data: {
+      type: 'array',
+      items: userSchema,
+    },
+    meta: {
+      type: 'object',
+      properties: {
+        total: { type: 'integer' },
+        page: { type: 'integer' },
+        limit: { type: 'integer' },
+        totalPages: { type: 'integer' },
+      },
+    },
+  },
+};
+```
+
+## Complete Route Example
+
+```typescript
+fastify.route({
+  method: 'GET',
+  url: '/api/products',
+  schema: {
+    description: 'Get all products with pagination and filtering',
+    tags: ['Products'],
+    summary: 'List products',
+    querystring: {
+      type: 'object',
+      properties: {
+        page: { type: 'integer', default: 1 },
+        limit: { type: 'integer', default: 20 },
+        category: { type: 'string', description: 'Filter by category' },
+        minPrice: { type: 'number', description: 'Minimum price' },
+        maxPrice: { type: 'number', description: 'Maximum price' },
+        search: { type: 'string', description: 'Search term' },
+      },
+    },
+    response: {
+      200: {
+        description: 'List of products',
+        ...commonResponses.paginated,
+      },
+    },
+  },
+  handler: async (request, reply) => {
+    // Implementation
+  },
+});
+```
+
+## Swagger UI Features
+
+The documentation UI at `/docs` includes:
+- **Try It Out** - Execute API calls directly
+- **Filter** - Search endpoints
+- **Expand/Collapse** - Organize by tags
+- **Request Duration** - Show response times
+- **Authorization** - Set bearer token
+
+## Best Practices
+
+1. **Consistent Tags** - Group related endpoints
+2. **Detailed Descriptions** - Document parameters and responses
+3. **Examples** - Provide example values
+4. **Error Responses** - Document all error cases
+5. **Security** - Mark authenticated endpoints
+6. **Versioning** - Include version in title

package/docs/modules/UPLOAD.md

@@ -0,0 +1,296 @@
+# Upload Module
+
+File upload service with multiple storage providers and image transformation support.
+
+## Features
+
+- **Multiple Providers** - Local, AWS S3, Google Cloud Storage, Cloudinary
+- **File Validation** - MIME type and size validation
+- **Image Transformation** - Resize, crop, format conversion
+- **Signed URLs** - Secure temporary URLs for private files
+- **User Storage Tracking** - Track storage usage per user
+
+## Supported Providers
+
+| Provider | Use Case |
+|----------|----------|
+| Local | Development, simple deployments |
+| AWS S3 | Production, scalable storage |
+| Google Cloud Storage | GCP infrastructure |
+| Cloudinary | Image optimization, transformations |
+
+## Usage
+
+### Configuration
+
+```typescript
+import { createUploadService } from 'servcraft/modules/upload';
+
+// Local storage
+const uploadService = createUploadService({
+  provider: 'local',
+  maxFileSize: 10 * 1024 * 1024, // 10MB
+  allowedMimeTypes: ['image/jpeg', 'image/png', 'application/pdf'],
+  local: {
+    uploadDir: './uploads',
+    publicPath: '/uploads',
+  },
+});
+
+// AWS S3
+const s3Service = createUploadService({
+  provider: 's3',
+  maxFileSize: 50 * 1024 * 1024,
+  s3: {
+    bucket: 'my-bucket',
+    region: 'us-east-1',
+    accessKeyId: process.env.AWS_ACCESS_KEY_ID!,
+    secretAccessKey: process.env.AWS_SECRET_ACCESS_KEY!,
+  },
+});
+
+// Cloudinary
+const cloudinaryService = createUploadService({
+  provider: 'cloudinary',
+  cloudinary: {
+    cloudName: process.env.CLOUDINARY_CLOUD_NAME!,
+    apiKey: process.env.CLOUDINARY_API_KEY!,
+    apiSecret: process.env.CLOUDINARY_API_SECRET!,
+    folder: 'uploads',
+  },
+});
+```
+
+### Single File Upload
+
+```typescript
+// Fastify route example
+fastify.post('/upload', async (request, reply) => {
+  const file = await request.file();
+
+  const uploaded = await uploadService.upload(file, {
+    folder: 'avatars',
+    filename: `user-${userId}-avatar`,
+    isPublic: true,
+  });
+
+  return { url: uploaded.url, id: uploaded.id };
+});
+```
+
+### Multiple Files Upload
+
+```typescript
+fastify.post('/upload-multiple', async (request, reply) => {
+  const files = await request.files();
+  const fileArray = [];
+
+  for await (const file of files) {
+    fileArray.push(file);
+  }
+
+  const uploaded = await uploadService.uploadMultiple(fileArray, {
+    folder: 'documents',
+  });
+
+  return uploaded.map(f => ({ id: f.id, url: f.url }));
+});
+```
+
+### Image Transformation
+
+```typescript
+const uploaded = await uploadService.upload(file, {
+  transform: {
+    width: 300,
+    height: 300,
+    fit: 'cover',
+    format: 'webp',
+    quality: 80,
+  },
+});
+```
+
+### File Management
+
+```typescript
+// Get file by ID
+const file = await uploadService.getFile(fileId);
+
+// Delete file
+await uploadService.deleteFile(fileId);
+
+// Get signed URL (for private files)
+const signedUrl = await uploadService.getSignedUrl(fileId, 3600); // 1 hour
+```
+
+### User Storage Management
+
+```typescript
+// Get user's files
+const files = await uploadService.getFilesByUser(userId, {
+  limit: 20,
+  offset: 0,
+});
+
+// Get storage usage
+const usage = await uploadService.getUserStorageUsage(userId);
+// { totalSize: 15728640, fileCount: 12 }
+
+// Delete all user files
+await uploadService.deleteUserFiles(userId);
+```
+
+## Configuration Types
+
+```typescript
+interface UploadConfig {
+  provider: 'local' | 's3' | 'cloudinary' | 'gcs';
+  maxFileSize: number; // in bytes
+  allowedMimeTypes: string[];
+
+  local?: {
+    uploadDir: string;
+    publicPath: string;
+  };
+
+  s3?: {
+    bucket: string;
+    region: string;
+    accessKeyId: string;
+    secretAccessKey: string;
+  };
+
+  cloudinary?: {
+    cloudName: string;
+    apiKey: string;
+    apiSecret: string;
+    folder?: string;
+  };
+
+  gcs?: {
+    projectId: string;
+    bucket: string;
+    keyFilename?: string;
+  };
+}
+
+interface UploadOptions {
+  folder?: string;
+  filename?: string;
+  isPublic?: boolean;
+  transform?: ImageTransformOptions;
+}
+
+interface ImageTransformOptions {
+  width?: number;
+  height?: number;
+  fit?: 'cover' | 'contain' | 'fill' | 'inside' | 'outside';
+  format?: 'jpeg' | 'png' | 'webp' | 'avif';
+  quality?: number;
+  grayscale?: boolean;
+  blur?: number;
+}
+```
+
+## Response Types
+
+```typescript
+interface UploadedFile {
+  id: string;
+  originalName: string;
+  filename: string;
+  mimetype: string;
+  size: number;
+  path: string;
+  url: string;
+  provider: string;
+  bucket?: string;
+  userId?: string;
+  createdAt: Date;
+}
+```
+
+## Fastify Integration
+
+```typescript
+import fastifyMultipart from '@fastify/multipart';
+
+// Register multipart
+fastify.register(fastifyMultipart, {
+  limits: {
+    fileSize: 10 * 1024 * 1024, // 10MB
+  },
+});
+
+// Upload route with validation
+fastify.post('/api/files', async (request, reply) => {
+  const file = await request.file();
+
+  if (!file) {
+    return reply.status(400).send({ error: 'No file provided' });
+  }
+
+  try {
+    const uploaded = await uploadService.upload(file, {
+      folder: 'documents',
+      isPublic: false,
+    });
+
+    return {
+      id: uploaded.id,
+      url: uploaded.url,
+      size: uploaded.size,
+      mimetype: uploaded.mimetype,
+    };
+  } catch (error) {
+    if (error.message.includes('File type not allowed')) {
+      return reply.status(400).send({ error: error.message });
+    }
+    throw error;
+  }
+});
+```
+
+## Database Schema
+
+```sql
+CREATE TABLE uploaded_files (
+  id UUID PRIMARY KEY,
+  user_id TEXT,
+  original_name TEXT NOT NULL,
+  filename TEXT NOT NULL,
+  mimetype TEXT NOT NULL,
+  size INTEGER NOT NULL,
+  path TEXT NOT NULL,
+  url TEXT NOT NULL,
+  provider TEXT NOT NULL,
+  bucket TEXT,
+  created_at TIMESTAMP DEFAULT NOW()
+);
+
+CREATE INDEX idx_uploaded_files_user ON uploaded_files(user_id);
+```
+
+## Default Allowed MIME Types
+
+```typescript
+[
+  'image/jpeg',
+  'image/png',
+  'image/gif',
+  'image/webp',
+  'application/pdf',
+  'text/plain',
+  'application/json',
+]
+```
+
+## Best Practices
+
+1. **Validate on Server** - Always validate file types server-side
+2. **Use Signed URLs** - Use signed URLs for sensitive files
+3. **Set Size Limits** - Configure appropriate file size limits
+4. **Clean Up** - Implement cleanup for orphaned files
+5. **CDN** - Use CDN for public files in production
+6. **Virus Scanning** - Consider virus scanning for user uploads