saas-backend-kit 1.0.0 → 1.0.1

package/saas-banner.svg

@@ -0,0 +1,239 @@
+<svg xmlns="http://www.w3.org/2000/svg" viewBox="0 0 900 320" width="900" height="320">
+  <defs>
+    <linearGradient id="bg" x1="0%" y1="0%" x2="100%" y2="100%">
+      <stop offset="0%" style="stop-color:#0a0a0f"/>
+      <stop offset="50%" style="stop-color:#0d1117"/>
+      <stop offset="100%" style="stop-color:#111827"/>
+    </linearGradient>
+    <linearGradient id="pipeGrad" x1="0%" y1="0%" x2="100%" y2="0%">
+      <stop offset="0%" style="stop-color:#26d97f;stop-opacity:0"/>
+      <stop offset="50%" style="stop-color:#26d97f;stop-opacity:1"/>
+      <stop offset="100%" style="stop-color:#26d97f;stop-opacity:0"/>
+    </linearGradient>
+    <linearGradient id="pipeGrad2" x1="0%" y1="0%" x2="100%" y2="0%">
+      <stop offset="0%" style="stop-color:#3178c6;stop-opacity:0"/>
+      <stop offset="50%" style="stop-color:#3178c6;stop-opacity:1"/>
+      <stop offset="100%" style="stop-color:#3178c6;stop-opacity:0"/>
+    </linearGradient>
+    <linearGradient id="pipeGrad3" x1="0%" y1="0%" x2="100%" y2="0%">
+      <stop offset="0%" style="stop-color:#ff9900;stop-opacity:0"/>
+      <stop offset="50%" style="stop-color:#ff9900;stop-opacity:1"/>
+      <stop offset="100%" style="stop-color:#ff9900;stop-opacity:0"/>
+    </linearGradient>
+    <filter id="glow-green">
+      <feGaussianBlur stdDeviation="4" result="blur"/>
+      <feMerge><feMergeNode in="blur"/><feMergeNode in="SourceGraphic"/></feMerge>
+    </filter>
+    <filter id="glow-blue">
+      <feGaussianBlur stdDeviation="3" result="blur"/>
+      <feMerge><feMergeNode in="blur"/><feMergeNode in="SourceGraphic"/></feMerge>
+    </filter>
+    <filter id="glow-soft">
+      <feGaussianBlur stdDeviation="2" result="blur"/>
+      <feMerge><feMergeNode in="blur"/><feMergeNode in="SourceGraphic"/></feMerge>
+    </filter>
+  </defs>
+
+  <!-- Background -->
+  <rect width="900" height="320" fill="url(#bg)" rx="14"/>
+
+  <!-- Subtle dot-grid background -->
+  <pattern id="dots" x="0" y="0" width="24" height="24" patternUnits="userSpaceOnUse">
+    <circle cx="1" cy="1" r="0.8" fill="#1e293b" opacity="0.8"/>
+  </pattern>
+  <rect width="900" height="320" fill="url(#dots)" rx="14" opacity="0.6"/>
+
+  <!-- ===================== DATA PIPELINE VISUALIZATION ===================== -->
+  <!-- Horizontal pipeline backbone -->
+  <line x1="60" y1="160" x2="840" y2="160" stroke="#1e293b" stroke-width="2"/>
+
+  <!-- Animated data packet 1 - green -->
+  <rect x="0" y="154" width="36" height="12" rx="6" fill="url(#pipeGrad)" opacity="0.9">
+    <animate attributeName="x" values="-40;900" dur="3.2s" repeatCount="indefinite"/>
+  </rect>
+
+  <!-- Animated data packet 2 - blue -->
+  <rect x="0" y="154" width="28" height="12" rx="6" fill="url(#pipeGrad2)" opacity="0.85">
+    <animate attributeName="x" values="-40;900" dur="3.2s" begin="-1.1s" repeatCount="indefinite"/>
+  </rect>
+
+  <!-- Animated data packet 3 - orange -->
+  <rect x="0" y="154" width="22" height="12" rx="6" fill="url(#pipeGrad3)" opacity="0.8">
+    <animate attributeName="x" values="-40;900" dur="3.2s" begin="-2.0s" repeatCount="indefinite"/>
+  </rect>
+
+  <!-- ===================== MODULE NODES (pipeline stops) ===================== -->
+  <!-- Each node represents a feature of the library -->
+
+  <!-- Node 1: AUTH -->
+  <g filter="url(#glow-blue)">
+    <circle cx="130" cy="160" r="32" fill="#0d1117" stroke="#3178c6" stroke-width="1.8"/>
+    <circle cx="130" cy="160" r="32" fill="none" stroke="#3178c6" stroke-width="1">
+      <animate attributeName="r" values="32;40;32" dur="3s" repeatCount="indefinite"/>
+      <animate attributeName="opacity" values="0.5;0;0.5" dur="3s" repeatCount="indefinite"/>
+    </circle>
+    <text x="130" y="155" text-anchor="middle" font-family="'Courier New',monospace" font-size="9" fill="#3178c6" font-weight="bold">🔐</text>
+    <text x="130" y="168" text-anchor="middle" font-family="'Courier New',monospace" font-size="9" fill="#3178c6" font-weight="bold">AUTH</text>
+    <text x="130" y="204" text-anchor="middle" font-family="'Courier New',monospace" font-size="8" fill="#3178c6" opacity="0.6">JWT · RBAC</text>
+  </g>
+
+  <!-- Connector line -->
+  <line x1="162" y1="160" x2="218" y2="160" stroke="#1e293b" stroke-width="1.5" stroke-dasharray="4,3"/>
+
+  <!-- Node 2: QUEUE -->
+  <g filter="url(#glow-green)">
+    <circle cx="250" cy="160" r="32" fill="#0d1117" stroke="#26d97f" stroke-width="1.8"/>
+    <circle cx="250" cy="160" r="32" fill="none" stroke="#26d97f" stroke-width="1">
+      <animate attributeName="r" values="32;40;32" dur="3.5s" begin="-0.8s" repeatCount="indefinite"/>
+      <animate attributeName="opacity" values="0.5;0;0.5" dur="3.5s" begin="-0.8s" repeatCount="indefinite"/>
+    </circle>
+    <text x="250" y="155" text-anchor="middle" font-family="'Courier New',monospace" font-size="9" fill="#26d97f" font-weight="bold">⚡</text>
+    <text x="250" y="168" text-anchor="middle" font-family="'Courier New',monospace" font-size="9" fill="#26d97f" font-weight="bold">QUEUE</text>
+    <text x="250" y="204" text-anchor="middle" font-family="'Courier New',monospace" font-size="8" fill="#26d97f" opacity="0.6">BullMQ</text>
+  </g>
+
+  <!-- Connector line -->
+  <line x1="282" y1="160" x2="338" y2="160" stroke="#1e293b" stroke-width="1.5" stroke-dasharray="4,3"/>
+
+  <!-- Node 3: NOTIFY -->
+  <g filter="url(#glow-soft)">
+    <circle cx="370" cy="160" r="32" fill="#0d1117" stroke="#f59e0b" stroke-width="1.8"/>
+    <circle cx="370" cy="160" r="32" fill="none" stroke="#f59e0b" stroke-width="1">
+      <animate attributeName="r" values="32;40;32" dur="4s" begin="-1.5s" repeatCount="indefinite"/>
+      <animate attributeName="opacity" values="0.5;0;0.5" dur="4s" begin="-1.5s" repeatCount="indefinite"/>
+    </circle>
+    <text x="370" y="155" text-anchor="middle" font-family="'Courier New',monospace" font-size="9" fill="#f59e0b" font-weight="bold">🔔</text>
+    <text x="370" y="168" text-anchor="middle" font-family="'Courier New',monospace" font-size="9" fill="#f59e0b" font-weight="bold">NOTIFY</text>
+    <text x="370" y="204" text-anchor="middle" font-family="'Courier New',monospace" font-size="8" fill="#f59e0b" opacity="0.6">Email · SMS</text>
+  </g>
+
+  <!-- Connector line -->
+  <line x1="402" y1="160" x2="458" y2="160" stroke="#1e293b" stroke-width="1.5" stroke-dasharray="4,3"/>
+
+  <!-- Node 4: UPLOAD (CENTER - largest) -->
+  <g filter="url(#glow-soft)">
+    <circle cx="490" cy="160" r="36" fill="#0d1117" stroke="#ff9900" stroke-width="2"/>
+    <circle cx="490" cy="160" r="36" fill="none" stroke="#ff9900" stroke-width="1.2">
+      <animate attributeName="r" values="36;48;36" dur="3s" begin="-0.4s" repeatCount="indefinite"/>
+      <animate attributeName="opacity" values="0.5;0;0.5" dur="3s" begin="-0.4s" repeatCount="indefinite"/>
+    </circle>
+    <text x="490" y="154" text-anchor="middle" font-family="'Courier New',monospace" font-size="10" fill="#ff9900" font-weight="bold">☁️</text>
+    <text x="490" y="168" text-anchor="middle" font-family="'Courier New',monospace" font-size="10" fill="#ff9900" font-weight="bold">S3</text>
+    <text x="490" y="208" text-anchor="middle" font-family="'Courier New',monospace" font-size="8" fill="#ff9900" opacity="0.6">AWS Upload</text>
+  </g>
+
+  <!-- Connector line -->
+  <line x1="526" y1="160" x2="578" y2="160" stroke="#1e293b" stroke-width="1.5" stroke-dasharray="4,3"/>
+
+  <!-- Node 5: RATE LIMIT -->
+  <g filter="url(#glow-soft)">
+    <circle cx="610" cy="160" r="32" fill="#0d1117" stroke="#e11d48" stroke-width="1.8"/>
+    <circle cx="610" cy="160" r="32" fill="none" stroke="#e11d48" stroke-width="1">
+      <animate attributeName="r" values="32;40;32" dur="2.8s" begin="-2.1s" repeatCount="indefinite"/>
+      <animate attributeName="opacity" values="0.5;0;0.5" dur="2.8s" begin="-2.1s" repeatCount="indefinite"/>
+    </circle>
+    <text x="610" y="155" text-anchor="middle" font-family="'Courier New',monospace" font-size="9" fill="#e11d48" font-weight="bold">🛡️</text>
+    <text x="610" y="168" text-anchor="middle" font-family="'Courier New',monospace" font-size="9" fill="#e11d48" font-weight="bold">LIMIT</text>
+    <text x="610" y="204" text-anchor="middle" font-family="'Courier New',monospace" font-size="8" fill="#e11d48" opacity="0.6">Rate Guard</text>
+  </g>
+
+  <!-- Connector line -->
+  <line x1="642" y1="160" x2="698" y2="160" stroke="#1e293b" stroke-width="1.5" stroke-dasharray="4,3"/>
+
+  <!-- Node 6: LOGGER -->
+  <g filter="url(#glow-soft)">
+    <circle cx="730" cy="160" r="32" fill="#0d1117" stroke="#8b5cf6" stroke-width="1.8"/>
+    <circle cx="730" cy="160" r="32" fill="none" stroke="#8b5cf6" stroke-width="1">
+      <animate attributeName="r" values="32;40;32" dur="3.8s" begin="-1.0s" repeatCount="indefinite"/>
+      <animate attributeName="opacity" values="0.5;0;0.5" dur="3.8s" begin="-1.0s" repeatCount="indefinite"/>
+    </circle>
+    <text x="730" y="155" text-anchor="middle" font-family="'Courier New',monospace" font-size="9" fill="#8b5cf6" font-weight="bold">📋</text>
+    <text x="730" y="168" text-anchor="middle" font-family="'Courier New',monospace" font-size="9" fill="#8b5cf6" font-weight="bold">LOGGER</text>
+    <text x="730" y="204" text-anchor="middle" font-family="'Courier New',monospace" font-size="8" fill="#8b5cf6" opacity="0.6">Pino · JSON</text>
+  </g>
+
+  <!-- Connector line -->
+  <line x1="762" y1="160" x2="818" y2="160" stroke="#1e293b" stroke-width="1.5" stroke-dasharray="4,3"/>
+
+  <!-- Node 7: CONFIG -->
+  <g filter="url(#glow-soft)">
+    <circle cx="845" cy="160" r="28" fill="#0d1117" stroke="#06b6d4" stroke-width="1.8"/>
+    <circle cx="845" cy="160" r="28" fill="none" stroke="#06b6d4" stroke-width="1">
+      <animate attributeName="r" values="28;36;28" dur="3.2s" begin="-2.6s" repeatCount="indefinite"/>
+      <animate attributeName="opacity" values="0.5;0;0.5" dur="3.2s" begin="-2.6s" repeatCount="indefinite"/>
+    </circle>
+    <text x="845" y="155" text-anchor="middle" font-family="'Courier New',monospace" font-size="9" fill="#06b6d4" font-weight="bold">⚙️</text>
+    <text x="845" y="168" text-anchor="middle" font-family="'Courier New',monospace" font-size="9" fill="#06b6d4" font-weight="bold">CFG</text>
+    <text x="845" y="204" text-anchor="middle" font-family="'Courier New',monospace" font-size="8" fill="#06b6d4" opacity="0.6">Zod · Env</text>
+  </g>
+
+  <!-- ===================== TITLE + SUBTITLE ===================== -->
+  <text x="450" y="50" text-anchor="middle" font-family="'Courier New',monospace" font-size="28" font-weight="bold" fill="#f8fafc" letter-spacing="2" filter="url(#glow-soft)">
+    saas-backend-kit
+    <animate attributeName="opacity" values="0.85;1;0.85" dur="4s" repeatCount="indefinite"/>
+  </text>
+
+  <text x="450" y="76" text-anchor="middle" font-family="'Courier New',monospace" font-size="12" fill="#64748b">
+    Production-grade modular backend toolkit · Node.js · Express · Fastify
+  </text>
+
+  <!-- npm install command badge — animated border -->
+  <rect x="310" y="88" width="280" height="30" rx="6" fill="#0d1117" stroke="#26d97f" stroke-width="1" opacity="0.9">
+    <animate attributeName="stroke-opacity" values="0.4;1;0.4" dur="2s" repeatCount="indefinite"/>
+  </rect>
+  <text x="450" y="108" text-anchor="middle" font-family="'Courier New',monospace" font-size="12" fill="#26d97f">
+    $ npm install saas-backend-kit
+  </text>
+
+  <!-- ===================== FLOATING PARTICLES ===================== -->
+  <circle cx="50" cy="50" r="2" fill="#26d97f" opacity="0.5">
+    <animate attributeName="cy" values="50;270;50" dur="7s" repeatCount="indefinite"/>
+    <animate attributeName="opacity" values="0.5;0;0.5" dur="7s" repeatCount="indefinite"/>
+  </circle>
+  <circle cx="870" cy="90" r="1.5" fill="#3178c6" opacity="0.5">
+    <animate attributeName="cy" values="90;30;90" dur="5s" repeatCount="indefinite"/>
+    <animate attributeName="opacity" values="0.5;0;0.5" dur="5s" repeatCount="indefinite"/>
+  </circle>
+  <circle cx="200" cy="280" r="2" fill="#f59e0b" opacity="0.4">
+    <animate attributeName="cx" values="200;700;200" dur="11s" repeatCount="indefinite"/>
+    <animate attributeName="opacity" values="0.4;0;0.4" dur="11s" repeatCount="indefinite"/>
+  </circle>
+  <circle cx="750" cy="30" r="1.5" fill="#8b5cf6" opacity="0.45">
+    <animate attributeName="cx" values="750;200;750" dur="9s" repeatCount="indefinite"/>
+    <animate attributeName="opacity" values="0.45;0;0.45" dur="9s" repeatCount="indefinite"/>
+  </circle>
+
+  <!-- ===================== BOTTOM STATUS BAR ===================== -->
+  <rect x="0" y="285" width="900" height="35" fill="#080c10" rx="0"/>
+  <rect x="0" y="282" width="900" height="3" fill="#26d97f" opacity="0.25"/>
+
+  <!-- Status indicators -->
+  <circle cx="30" cy="302" r="5" fill="#26d97f">
+    <animate attributeName="opacity" values="1;0.3;1" dur="1.5s" repeatCount="indefinite"/>
+  </circle>
+  <text x="42" y="307" font-family="'Courier New',monospace" font-size="10" fill="#26d97f" opacity="0.8">LIVE</text>
+
+  <text x="90" y="307" font-family="'Courier New',monospace" font-size="10" fill="#64748b">|</text>
+  <text x="100" y="307" font-family="'Courier New',monospace" font-size="10" fill="#64748b" opacity="0.7">MIT Licensed</text>
+
+  <text x="210" y="307" font-family="'Courier New',monospace" font-size="10" fill="#64748b">|</text>
+  <text x="220" y="307" font-family="'Courier New',monospace" font-size="10" fill="#64748b" opacity="0.7">TypeScript Ready</text>
+
+  <text x="360" y="307" font-family="'Courier New',monospace" font-size="10" fill="#64748b">|</text>
+  <text x="370" y="307" font-family="'Courier New',monospace" font-size="10" fill="#64748b" opacity="0.7">7 Modular Plugins</text>
+
+  <text x="520" y="307" font-family="'Courier New',monospace" font-size="10" fill="#64748b">|</text>
+  <text x="530" y="307" font-family="'Courier New',monospace" font-size="10" fill="#64748b" opacity="0.7">Express · Fastify</text>
+
+  <text x="670" y="307" font-family="'Courier New',monospace" font-size="10" fill="#64748b">|</text>
+  <text x="680" y="307" font-family="'Courier New',monospace" font-size="10" fill="#3178c6" opacity="0.85">by @AshishK-M</text>
+
+  <!-- Scrolling ticker on right -->
+  <clipPath id="tickerClip">
+    <rect x="800" y="288" width="95" height="28"/>
+  </clipPath>
+  <text font-family="'Courier New',monospace" font-size="9" fill="#26d97f" opacity="0.6" clip-path="url(#tickerClip)">
+    <tspan x="900" y="305">auth · queue · notify · upload · logger · rateLimit · config</tspan>
+    <animate attributeName="x" values="900;600" dur="8s" repeatCount="indefinite"/>
+  </text>
+</svg>

package/src/config/index.ts

@@ -24,6 +24,11 @@ export const envSchema = z.object({
   RATE_LIMIT_WINDOW: z.string().default('1m'),
   RATE_LIMIT_LIMIT: z.string().default('100'),
   LOG_LEVEL: z.enum(['fatal', 'error', 'warn', 'info', 'debug', 'trace']).default('info'),
+  AWS_REGION: z.string().default('us-east-1'),
+  AWS_ACCESS_KEY_ID: z.string().optional(),
+  AWS_SECRET_ACCESS_KEY: z.string().optional(),
+  AWS_S3_BUCKET: z.string().optional(),
+  AWS_ENDPOINT: z.string().optional(),
 });
 
 export type EnvConfig = z.infer<typeof envSchema>;

package/src/index.ts

@@ -5,6 +5,7 @@ export { logger } from './logger';
 export { rateLimit, createRateLimiter } from './rate-limit';
 export { config } from './config';
 export { ResponseHelper, response } from './response';
+export { upload, s3Service, S3Service } from './upload';
 export { createApp, createExpressApp, SaaSAppBuilder, PluginManager, Plugin, AppOptions } from './plugin';
 
 export { AuthOptions, User, JWTPayload, TokenPair, LoginCredentials, RegisterData, Role, Permission, RolePermissions } from './auth/types';
@@ -14,3 +15,4 @@ export { LoggerConfig, LogLevel } from './logger';
 export { RateLimitOptions } from './rate-limit';
 export { EnvConfig, ConfigOptions } from './config';
 export { ApiResponse, PaginatedResponse, ErrorResponse } from './response';
+export { S3Config, UploadOptions, UploadResult, SignedUrlOptions, FileObject } from './upload';

package/src/upload/index.ts

@@ -0,0 +1,268 @@
+import { S3Client, PutObjectCommand, DeleteObjectCommand, GetObjectCommand, ListObjectsV2Command } from '@aws-sdk/client-s3';
+import { getSignedUrl } from '@aws-sdk/s3-request-presigner';
+import { config } from '../config';
+import { logger } from '../logger';
+
+export interface S3Config {
+  region?: string;
+  accessKeyId?: string;
+  secretAccessKey?: string;
+  bucket: string;
+  endpoint?: string;
+  forcePathStyle?: boolean;
+}
+
+export interface UploadOptions {
+  key?: string;
+  contentType?: string;
+  expiresIn?: number;
+  metadata?: Record<string, string>;
+}
+
+export interface UploadResult {
+  key: string;
+  url: string;
+  bucket: string;
+  contentType?: string;
+  size?: number;
+}
+
+export interface SignedUrlOptions {
+  expiresIn?: number;
+}
+
+export interface FileObject {
+  key: string;
+  lastModified?: Date;
+  size?: number;
+  contentType?: string;
+}
+
+class S3Service {
+  private client: S3Client | null = null;
+  private bucket: string;
+  private initialized: boolean = false;
+
+  constructor() {
+    this.bucket = '';
+  }
+
+  initialize(config: S3Config): void {
+    this.client = new S3Client({
+      region: config.region || 'us-east-1',
+      credentials: config.accessKeyId && config.secretAccessKey
+        ? {
+            accessKeyId: config.accessKeyId,
+            secretAccessKey: config.secretAccessKey,
+          }
+        : undefined,
+      endpoint: config.endpoint,
+      forcePathStyle: config.forcePathStyle || false,
+    });
+
+    this.bucket = config.bucket;
+    this.initialized = true;
+    logger.info('S3 service initialized', { bucket: this.bucket });
+  }
+
+  isInitialized(): boolean {
+    return this.initialized;
+  }
+
+  private ensureInitialized(): void {
+    if (!this.initialized) {
+      const region = config.get('AWS_REGION') || 'us-east-1';
+      const bucket = config.get('AWS_S3_BUCKET') || '';
+      
+      this.initialize({
+        region,
+        accessKeyId: config.get('AWS_ACCESS_KEY_ID'),
+        secretAccessKey: config.get('AWS_SECRET_ACCESS_KEY'),
+        bucket,
+        endpoint: config.get('AWS_ENDPOINT'),
+      });
+    }
+  }
+
+  async upload(
+    file: Buffer | Uint8Array | string,
+    options: UploadOptions = {}
+  ): Promise<UploadResult> {
+    this.ensureInitialized();
+
+    const key = options.key || this.generateKey();
+    const contentType = options.contentType || this.guessContentType(key);
+
+    const command = new PutObjectCommand({
+      Bucket: this.bucket,
+      Key: key,
+      Body: file,
+      ContentType: contentType,
+      Metadata: options.metadata,
+    });
+
+    await this.client!.send(command);
+
+    const url = await this.getSignedUrl(key, { expiresIn: options.expiresIn || 3600 });
+
+    logger.info('File uploaded to S3', { key, bucket: this.bucket, contentType });
+
+    return {
+      key,
+      url,
+      bucket: this.bucket,
+      contentType,
+    };
+  }
+
+  async uploadImage(
+    file: Buffer | Uint8Array | string,
+    filename: string,
+    options: UploadOptions = {}
+  ): Promise<UploadResult> {
+    const key = options.key || `images/${Date.now()}-${filename}`;
+    
+    return this.upload(file, {
+      ...options,
+      key,
+      contentType: options.contentType || this.getImageContentType(filename),
+    });
+  }
+
+  async uploadVideo(
+    file: Buffer | Uint8Array | string,
+    filename: string,
+    options: UploadOptions = {}
+  ): Promise<UploadResult> {
+    const key = options.key || `videos/${Date.now()}-${filename}`;
+    
+    return this.upload(file, {
+      ...options,
+      key,
+      contentType: options.contentType || this.getVideoContentType(filename),
+    });
+  }
+
+  async delete(key: string): Promise<void> {
+    this.ensureInitialized();
+
+    const command = new DeleteObjectCommand({
+      Bucket: this.bucket,
+      Key: key,
+    });
+
+    await this.client!.send(command);
+    logger.info('File deleted from S3', { key, bucket: this.bucket });
+  }
+
+  async getSignedUrl(key: string, options: SignedUrlOptions = {}): Promise<string> {
+    this.ensureInitialized();
+
+    const command = new GetObjectCommand({
+      Bucket: this.bucket,
+      Key: key,
+    });
+
+    return getSignedUrl(this.client!, command, {
+      expiresIn: options.expiresIn || 3600,
+    });
+  }
+
+  async getPublicUrl(key: string): Promise<string> {
+    return `https://${this.bucket}.s3.${config.get('AWS_REGION') || 'us-east-1'}.amazonaws.com/${key}`;
+  }
+
+  async listFiles(prefix?: string, maxKeys: number = 1000): Promise<FileObject[]> {
+    this.ensureInitialized();
+
+    const command = new ListObjectsV2Command({
+      Bucket: this.bucket,
+      Prefix: prefix,
+      MaxKeys: maxKeys,
+    });
+
+    const response = await this.client!.send(command);
+    
+    return (response.Contents || []).map((item) => ({
+      key: item.Key || '',
+      lastModified: item.LastModified,
+      size: item.Size,
+    }));
+  }
+
+  private generateKey(): string {
+    const timestamp = Date.now();
+    const random = Math.random().toString(36).substring(2, 15);
+    return `uploads/${timestamp}-${random}`;
+  }
+
+  private guessContentType(key: string): string {
+    const ext = key.split('.').pop()?.toLowerCase();
+    
+    const contentTypes: Record<string, string> = {
+      jpg: 'image/jpeg',
+      jpeg: 'image/jpeg',
+      png: 'image/png',
+      gif: 'image/gif',
+      webp: 'image/webp',
+      svg: 'image/svg+xml',
+      mp4: 'video/mp4',
+      webm: 'video/webm',
+      mov: 'video/quicktime',
+      avi: 'video/x-msvideo',
+      pdf: 'application/pdf',
+      json: 'application/json',
+      txt: 'text/plain',
+    };
+
+    return contentTypes[ext || ''] || 'application/octet-stream';
+  }
+
+  private getImageContentType(filename: string): string {
+    const ext = filename.split('.').pop()?.toLowerCase();
+    const imageTypes: Record<string, string> = {
+      jpg: 'image/jpeg',
+      jpeg: 'image/jpeg',
+      png: 'image/png',
+      gif: 'image/gif',
+      webp: 'image/webp',
+      svg: 'image/svg+xml',
+    };
+    return imageTypes[ext || ''] || 'image/jpeg';
+  }
+
+  private getVideoContentType(filename: string): string {
+    const ext = filename.split('.').pop()?.toLowerCase();
+    const videoTypes: Record<string, string> = {
+      mp4: 'video/mp4',
+      webm: 'video/webm',
+      mov: 'video/quicktime',
+      avi: 'video/x-msvideo',
+      mkv: 'video/x-matroska',
+      ogv: 'video/ogg',
+    };
+    return videoTypes[ext || ''] || 'video/mp4';
+  }
+}
+
+export const s3Service = new S3Service();
+
+export const upload = {
+  initialize: (config: S3Config) => s3Service.initialize(config),
+  
+  file: (file: Buffer | Uint8Array | string, options?: UploadOptions) => 
+    s3Service.upload(file, options),
+  
+  image: (file: Buffer | Uint8Array | string, filename: string, options?: UploadOptions) =>
+    s3Service.uploadImage(file, filename, options),
+  
+  video: (file: Buffer | Uint8Array | string, filename: string, options?: UploadOptions) =>
+    s3Service.uploadVideo(file, filename, options),
+  
+  delete: (key: string) => s3Service.delete(key),
+  getSignedUrl: (key: string, options?: SignedUrlOptions) => s3Service.getSignedUrl(key, options),
+  getPublicUrl: (key: string) => s3Service.getPublicUrl(key),
+  listFiles: (prefix?: string, maxKeys?: number) => s3Service.listFiles(prefix, maxKeys),
+};
+
+export default upload;

package/tsup.config.ts

@@ -10,13 +10,14 @@ export default defineConfig({
     'rate-limit/index': 'src/rate-limit/index.ts',
     'config/index': 'src/config/index.ts',
     'response/index': 'src/response/index.ts',
+    'upload/index': 'src/upload/index.ts',
   },
   format: ['cjs', 'esm'],
   dts: false,
   splitting: false,
   sourcemap: true,
   clean: false,
-  external: ['express', 'fastify', 'ioredis', 'bullmq'],
+  external: ['express', 'fastify', 'ioredis', 'bullmq', '@aws-sdk/client-s3', '@aws-sdk/s3-request-presigner'],
   treeshake: true,
   exports: {
     namedExports: true,