s3-storage-dtb 0.0.1

package/README.md

@@ -0,0 +1,484 @@
+# s3-storage-dtb
+
+Paquete de almacenamiento de archivos para Node.js y NestJS. 
+
+## 🎯 Dos Modos de Uso
+
+El paquete ofrece **dos modos** que puedes elegir según tus necesidades:
+
+### 📁 Modo Local (StorageCore)
+Almacena archivos directamente en el sistema de archivos de tu servidor. **Ideal para:**
+- Desarrollo local
+- Aplicaciones que corren en el mismo servidor
+- Cuando no necesitas un backend separado
+
+### 🌐 Modo Cliente (StorageClient)  
+Se conecta a un backend remoto mediante HTTP. **Ideal para:
+- Producción con backend separado
+- Múltiples aplicaciones compartiendo almacenamiento
+- Escalabilidad y distribución
+
+## Características
+
+- ✅ Almacenamiento local de archivos (StorageCore)
+- ✅ Cliente HTTP para backend remoto (StorageClient)
+- ✅ Autenticación con API keys
+- ✅ Validación de tipos MIME
+- ✅ Límites de tamaño de archivo
+- ✅ Sanitización de rutas (protección contra path traversal)
+- ✅ Metadata de archivos
+- ✅ Listado y paginación
+- ✅ Compatible con Node.js puro y NestJS
+- ✅ TypeScript con tipos completos
+
+## Instalación
+
+```bash
+npm install s3-storage-dtb
+```
+
+Para uso con NestJS, también necesitas:
+
+```bash
+npm install @nestjs/common
+```
+
+## 🚀 Inicio Rápido
+
+### Elegir el Modo Correcto
+
+**¿Necesitas almacenar archivos localmente?** → Usa `StorageCore`  
+**¿Necesitas conectarte a un backend remoto?** → Usa `StorageClient`
+
+Ambos tienen la **misma API**, solo cambia la inicialización.
+
+---
+
+## 📁 Modo Local (StorageCore)
+
+### Configuración
+
+```typescript
+import { StorageCore } from 's3-storage-dtb';
+
+// ✅ Configuración simple - Solo necesitas la ruta
+const storage = new StorageCore({
+  rootPath: './uploads',  // Donde se guardarán los archivos
+  maxFileSize: '50mb',   // Opcional: límite de tamaño
+  allowedMimeTypes: ['image/*', 'video/*']  // Opcional: tipos permitidos
+});
+```
+
+### Uso Completo
+
+```typescript
+import { StorageCore } from 's3-storage-dtb';
+import { readFileSync } from 'fs';
+
+const storage = new StorageCore({
+  rootPath: './uploads',
+  maxFileSize: '50mb',
+  allowedMimeTypes: ['image/*', 'video/*']
+});
+
+// Todas las operaciones son iguales
+const buffer = readFileSync('./mi-imagen.jpg');
+const path = await storage.uploadFile('images/photo.jpg', buffer, 'image/jpeg');
+const stream = await storage.downloadFile(path);
+const metadata = await storage.getFileMetadata(path);
+const { files, total } = await storage.listFiles('images');
+await storage.deleteFile(path);
+const exists = await storage.fileExists(path);
+```
+
+---
+
+## 🌐 Modo Cliente (StorageClient)
+
+### Configuración
+
+```typescript
+import { StorageClient } from 's3-storage-dtb';
+
+// ✅ Configuración simple - Solo necesitas URL y API key
+const client = new StorageClient({
+  baseUrl: 'https://api.midominio.com',  // URL del backend
+  apiKey: 'sk_live_xxx',                 // Tu API key
+  timeout: 30000                         // Opcional: timeout en ms
+});
+```
+
+### Ejemplos de baseUrl
+
+```typescript
+// Con dominio
+new StorageClient({ baseUrl: 'https://api.midominio.com', apiKey: 'sk_xxx' });
+
+// Con IP directa
+new StorageClient({ baseUrl: 'http://192.168.1.100:3000', apiKey: 'sk_xxx' });
+
+// Con puerto personalizado
+new StorageClient({ baseUrl: 'http://localhost:8080', apiKey: 'sk_xxx' });
+```
+
+### Uso Completo
+
+```typescript
+import { StorageClient } from 's3-storage-dtb';
+import { readFileSync } from 'fs';
+
+const client = new StorageClient({
+  baseUrl: 'https://api.midominio.com',
+  apiKey: 'sk_live_xxx'
+});
+
+// ⚠️ IMPORTANTE: La API es IDÉNTICA a StorageCore
+const buffer = readFileSync('./mi-imagen.jpg');
+const path = await client.uploadFile('images/photo.jpg', buffer, 'image/jpeg');
+const stream = await client.downloadFile(path);
+const metadata = await client.getFileMetadata(path);
+const { files, total } = await client.listFiles('images');
+await client.deleteFile(path);
+const exists = await client.fileExists(path);
+```
+
+---
+
+## 🔄 Cambiar Entre Modos
+
+Como ambos tienen la misma API, cambiar de modo es **súper simple**:
+
+### Opción 1: Variable de Entorno
+
+```typescript
+import { StorageCore, StorageClient } from 's3-storage-dtb';
+
+// Usar variable de entorno para decidir el modo
+const useRemote = process.env.STORAGE_MODE === 'remote';
+
+const storage = useRemote
+  ? new StorageClient({
+      baseUrl: process.env.STORAGE_URL!,
+      apiKey: process.env.STORAGE_API_KEY!
+    })
+  : new StorageCore({
+      rootPath: process.env.STORAGE_PATH || './uploads'
+    });
+
+// El resto del código es idéntico
+await storage.uploadFile('images/photo.jpg', buffer, 'image/jpeg');
+```
+
+### Opción 2: Factory Function
+
+```typescript
+import { StorageCore, StorageClient } from 's3-storage-dtb';
+
+function createStorage() {
+  if (process.env.STORAGE_URL && process.env.STORAGE_API_KEY) {
+    // Modo remoto
+    return new StorageClient({
+      baseUrl: process.env.STORAGE_URL,
+      apiKey: process.env.STORAGE_API_KEY
+    });
+  }
+  
+  // Modo local (por defecto)
+  return new StorageCore({
+    rootPath: process.env.STORAGE_PATH || './uploads'
+  });
+}
+
+const storage = createStorage();
+// Usar normalmente
+await storage.uploadFile('images/photo.jpg', buffer, 'image/jpeg');
+```
+
+### Opción 3: TypeScript con Interfaz Común
+
+```typescript
+import { StorageCore, StorageClient } from 's3-storage-dtb';
+import type { FileMetadata, ListFilesOptions } from 's3-storage-dtb';
+
+// Interfaz común para ambos modos
+interface Storage {
+  uploadFile(path: string, buffer: Buffer, mimeType: string, prefix?: string): Promise<string>;
+  downloadFile(path: string): Promise<Readable>;
+  deleteFile(path: string): Promise<void>;
+  getFileMetadata(path: string): Promise<FileMetadata>;
+  listFiles(directoryPath?: string, options?: ListFilesOptions): Promise<{files: FileMetadata[], total: number}>;
+  fileExists(path: string): Promise<boolean>;
+}
+
+// Crear instancia según configuración
+const storage: Storage = process.env.STORAGE_MODE === 'remote'
+  ? new StorageClient({ baseUrl: process.env.STORAGE_URL!, apiKey: process.env.STORAGE_API_KEY! })
+  : new StorageCore({ rootPath: './uploads' });
+
+// Código tipo-seguro
+await storage.uploadFile('images/photo.jpg', buffer, 'image/jpeg');
+```
+
+## Uso desde NestJS
+
+### Configuración básica
+
+```typescript
+import { Module } from '@nestjs/common';
+import { StorageModule } from 's3-storage-dtb/nestjs';
+
+@Module({
+  imports: [
+    StorageModule.forRoot({
+      rootPath: './uploads',
+      maxFileSize: '50mb',
+      allowedMimeTypes: ['image/*', 'video/*']
+    })
+  ]
+})
+export class AppModule {}
+```
+
+### Configuración asíncrona
+
+```typescript
+import { Module } from '@nestjs/common';
+import { ConfigModule, ConfigService } from '@nestjs/config';
+import { StorageModule } from 's3-storage-dtb/nestjs';
+
+@Module({
+  imports: [
+    ConfigModule.forRoot(),
+    StorageModule.forRootAsync({
+      useFactory: (config: ConfigService) => ({
+        rootPath: config.get('STORAGE_ROOT_PATH', './uploads'),
+        maxFileSize: config.get('STORAGE_MAX_SIZE', '50mb'),
+        allowedMimeTypes: config.get('STORAGE_ALLOWED_TYPES', ['image/*'])
+      }),
+      inject: [ConfigService]
+    })
+  ]
+})
+export class AppModule {}
+```
+
+### Usar en un servicio
+
+```typescript
+import { Injectable } from '@nestjs/common';
+import { StorageService } from 's3-storage-dtb/nestjs';
+
+@Injectable()
+export class FilesService {
+  constructor(private readonly storage: StorageService) {}
+
+  async uploadFile(filePath: string, buffer: Buffer, mimeType: string) {
+    return this.storage.uploadFile(filePath, buffer, mimeType);
+  }
+
+  async downloadFile(path: string) {
+    return this.storage.downloadFile(path);
+  }
+}
+```
+
+## 📖 API Completa
+
+### ⚡ Métodos Comunes (Ambos Modos)
+
+Ambos `StorageCore` y `StorageClient` tienen **exactamente la misma API**:
+
+```typescript
+// Subir archivo
+uploadFile(path: string, buffer: Buffer, mimeType: string, prefix?: string): Promise<string>
+
+// Descargar archivo (retorna stream)
+downloadFile(path: string): Promise<Readable>
+
+// Eliminar archivo
+deleteFile(path: string): Promise<void>
+
+// Obtener metadata
+getFileMetadata(path: string): Promise<FileMetadata>
+
+// Listar archivos
+listFiles(directoryPath?: string, options?: ListFilesOptions): Promise<{files: FileMetadata[], total: number}>
+
+// Verificar existencia
+fileExists(path: string): Promise<boolean>
+```
+
+### 🔧 Configuración
+
+#### StorageCore (Modo Local)
+
+```typescript
+new StorageCore(options: StorageCoreOptions)
+
+interface StorageCoreOptions {
+  rootPath: string;              // Ruta donde se guardan archivos
+  maxFileSize?: string;           // Opcional: "50mb", "1gb", etc.
+  allowedMimeTypes?: string[];    // Opcional: ["image/*", "video/*"]
+}
+```
+
+#### StorageClient (Modo Remoto)
+
+```typescript
+new StorageClient(options: StorageClientOptions)
+
+interface StorageClientOptions {
+  baseUrl: string;    // URL del backend: "https://api.com" o "http://192.168.1.100:3000"
+  apiKey: string;      // API key: "sk_live_xxx"
+  timeout?: number;    // Opcional: timeout en ms (default: 30000)
+}
+```
+
+**Nota:** El cliente automáticamente agrega el prefijo `/apifiles` a las URLs y maneja la autenticación con API keys.
+
+#### Constructor
+
+```typescript
+new StorageCore(options: StorageCoreOptions)
+```
+
+**Opciones:**
+- `rootPath` (string, requerido): Ruta raíz donde se almacenarán los archivos
+- `maxFileSize` (string, opcional): Tamaño máximo de archivo (ej: "50mb", "1gb"). Por defecto: "50mb"
+- `allowedMimeTypes` (string[], opcional): Tipos MIME permitidos (ej: ["image/*", "video/*"]). Por defecto: ["*"]
+
+#### Métodos
+
+##### `uploadFile(path, buffer, mimeType, prefix?)`
+
+Sube un archivo al almacenamiento.
+
+- `path` (string): Ruta relativa donde se guardará el archivo
+- `buffer` (Buffer): Contenido del archivo
+- `mimeType` (string): Tipo MIME del archivo
+- `prefix` (string, opcional): Prefijo para el nombre del archivo (se genera un UUID)
+
+**Retorna:** `Promise<string>` - Ruta relativa del archivo guardado
+
+##### `downloadFile(path)`
+
+Descarga un archivo como stream.
+
+- `path` (string): Ruta relativa del archivo
+
+**Retorna:** `Promise<Readable>` - Stream de Node.js
+
+##### `deleteFile(path)`
+
+Elimina un archivo.
+
+- `path` (string): Ruta relativa del archivo
+
+**Retorna:** `Promise<void>`
+
+##### `getFileMetadata(path)`
+
+Obtiene metadata de un archivo.
+
+- `path` (string): Ruta relativa del archivo
+
+**Retorna:** `Promise<FileMetadata>`
+
+##### `listFiles(directoryPath?, options?)`
+
+Lista archivos en un directorio.
+
+- `directoryPath` (string, opcional): Ruta del directorio (vacío para raíz)
+- `options` (ListFilesOptions, opcional):
+  - `limit` (number): Número máximo de archivos
+  - `offset` (number): Offset para paginación
+  - `prefix` (string): Filtrar por prefijo en el nombre
+
+**Retorna:** `Promise<{ files: FileMetadata[], total: number }>`
+
+##### `fileExists(path)`
+
+Verifica si un archivo existe.
+
+- `path` (string): Ruta relativa del archivo
+
+**Retorna:** `Promise<boolean>`
+
+## Tipos
+
+### FileMetadata
+
+```typescript
+interface FileMetadata {
+  name: string;
+  path: string;
+  size: number;
+  mimeType: string;
+  createdAt: Date;
+  modifiedAt: Date;
+  checksum?: string;
+}
+```
+
+## 📋 Comparación Rápida
+
+| Característica | StorageCore (Local) | StorageClient (Remoto) |
+|---------------|---------------------|------------------------|
+| **Inicialización** | `new StorageCore({ rootPath })` | `new StorageClient({ baseUrl, apiKey })` |
+| **Almacenamiento** | Sistema de archivos local | Backend remoto vía HTTP |
+| **API** | ✅ Idéntica | ✅ Idéntica |
+| **Autenticación** | ❌ No requiere | ✅ Requiere API key |
+| **Ideal para** | Desarrollo, mismo servidor | Producción, múltiples apps |
+| **Configuración** | Solo ruta | URL + API key |
+
+## 💡 Recomendaciones
+
+- **Desarrollo**: Usa `StorageCore` con `rootPath: './uploads'`
+- **Producción**: Usa `StorageClient` con variables de entorno
+- **Cambio fácil**: Ambos tienen la misma API, solo cambia la inicialización
+
+### ListFilesOptions
+
+```typescript
+interface ListFilesOptions {
+  limit?: number;
+  offset?: number;
+  prefix?: string;
+}
+```
+
+## Errores
+
+El paquete lanza errores personalizados que extienden `StorageError`:
+
+- `FileNotFoundError`: El archivo no existe
+- `InvalidMimeTypeError`: Tipo MIME no permitido
+- `FileTooLargeError`: El archivo excede el tamaño máximo
+- `UploadError`: Error al subir archivo
+- `DownloadError`: Error al descargar archivo
+- `DeleteError`: Error al eliminar archivo
+- `MetadataError`: Error al obtener metadata
+- `ListError`: Error al listar archivos
+
+Todos los errores tienen una propiedad `code` para identificación:
+
+```typescript
+try {
+  await storage.uploadFile('path', buffer, 'image/jpeg');
+} catch (error) {
+  if (error instanceof FileNotFoundError) {
+    console.error('Código:', error.code); // 'FILE_NOT_FOUND'
+  }
+}
+```
+
+## Seguridad
+
+- **Sanitización de rutas**: Protección contra path traversal (`..`)
+- **Validación de caracteres**: Solo permite caracteres seguros en rutas
+- **Validación de MIME types**: Verifica tipos de archivo permitidos
+- **Límites de tamaño**: Previene archivos demasiado grandes
+
+## Licencia
+
+MIT

package/dist/client/index.d.ts

@@ -0,0 +1,3 @@
+export { StorageClient } from './storage-client';
+export type { StorageClientOptions } from './storage-client';
+//# sourceMappingURL=index.d.ts.map

package/dist/client/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/client/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,aAAa,EAAE,MAAM,kBAAkB,CAAC;AACjD,YAAY,EAAE,oBAAoB,EAAE,MAAM,kBAAkB,CAAC"}

package/dist/client/index.js

@@ -0,0 +1,6 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.StorageClient = void 0;
+var storage_client_1 = require("./storage-client");
+Object.defineProperty(exports, "StorageClient", { enumerable: true, get: function () { return storage_client_1.StorageClient; } });
+//# sourceMappingURL=index.js.map

package/dist/client/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/client/index.ts"],"names":[],"mappings":";;;AAAA,mDAAiD;AAAxC,+GAAA,aAAa,OAAA"}

package/dist/client/storage-client.d.ts

@@ -0,0 +1,26 @@
+import { Readable } from 'stream';
+import type { FileMetadata, ListFilesOptions } from '../types';
+export interface StorageClientOptions {
+    baseUrl: string;
+    apiKey: string;
+    timeout?: number;
+}
+export declare class StorageClient {
+    private readonly baseUrl;
+    private readonly apiKey;
+    private readonly timeout;
+    private readonly apiPrefix;
+    constructor(options: StorageClientOptions);
+    private getHeaders;
+    private request;
+    uploadFile(filePath: string, buffer: Buffer, mimeType: string, prefix?: string): Promise<string>;
+    downloadFile(path: string): Promise<Readable>;
+    deleteFile(path: string): Promise<void>;
+    getFileMetadata(path: string): Promise<FileMetadata>;
+    listFiles(directoryPath?: string, options?: ListFilesOptions): Promise<{
+        files: FileMetadata[];
+        total: number;
+    }>;
+    fileExists(path: string): Promise<boolean>;
+}
+//# sourceMappingURL=storage-client.d.ts.map

package/dist/client/storage-client.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"storage-client.d.ts","sourceRoot":"","sources":["../../src/client/storage-client.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,QAAQ,EAAE,MAAM,QAAQ,CAAC;AAElC,OAAO,KAAK,EAAE,YAAY,EAAE,gBAAgB,EAAE,MAAM,UAAU,CAAC;AAa/D,MAAM,WAAW,oBAAoB;IACnC,OAAO,EAAE,MAAM,CAAC;IAChB,MAAM,EAAE,MAAM,CAAC;IACf,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAWD,qBAAa,aAAa;IACxB,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAS;IACjC,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAS;IAChC,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAS;IACjC,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAuB;gBAErC,OAAO,EAAE,oBAAoB;IAczC,OAAO,CAAC,UAAU;YAQJ,OAAO;IA6Ff,UAAU,CACd,QAAQ,EAAE,MAAM,EAChB,MAAM,EAAE,MAAM,EACd,QAAQ,EAAE,MAAM,EAChB,MAAM,CAAC,EAAE,MAAM,GACd,OAAO,CAAC,MAAM,CAAC;IA4BZ,YAAY,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,QAAQ,CAAC;IAe7C,UAAU,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC;IAYvC,eAAe,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,YAAY,CAAC;IA8CpD,SAAS,CACb,aAAa,GAAE,MAAW,EAC1B,OAAO,GAAE,gBAAqB,GAC7B,OAAO,CAAC;QAAE,KAAK,EAAE,YAAY,EAAE,CAAC;QAAC,KAAK,EAAE,MAAM,CAAA;KAAE,CAAC;IAkC9C,UAAU,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,OAAO,CAAC;CAWjD"}