@groundbrick/storage-service 1.1.1

package/README.md

@@ -0,0 +1,260 @@
+# @groundbrick/storage-service
+
+Serviço de storage plugável e type-safe para Node.js com suporte a múltiplos provedores (Local, S3, GCS, Azure).
+
+## 🚀 Características
+
+- ✅ **Type-Safe**: Totalmente tipado com TypeScript
+- ✅ **Múltiplos Provedores**: Local, AWS S3, Google Cloud Storage, Azure (fácil adicionar novos)
+- ✅ **Interface Única**: Mesma API para todos os provedores
+- ✅ **Zero Vendor Lock-in**: Troque de provedor apenas alterando configuração
+- ✅ **Singleton Pattern**: Controle de instância único
+- ✅ **Pronto para Produção**: Testado e otimizado
+
+## 📦 Instalação
+```bash
+npm install @groundbrick/storage-service
+```
+
+### Dependências Opcionais
+
+Para usar S3:
+```bash
+npm install @aws-sdk/client-s3 @aws-sdk/s3-request-presigner
+```
+
+## 🔧 Uso Básico
+
+### Storage Local
+```typescript
+import { StorageService } from '@groundbrick/storage-service';
+
+const storage = StorageService.getInstance({
+  provider: 'local',
+  config: {
+    basePath: './uploads',
+    baseUrl: 'http://localhost:3000/uploads'
+  }
+});
+
+// Upload
+const result = await storage.upload(
+  fileBuffer,
+  'pets/123/photo.jpg',
+  {
+    contentType: 'image/jpeg',
+    isPublic: true
+  }
+);
+
+console.log(result.url); // http://localhost:3000/uploads/pets/123/photo.jpg
+```
+
+### AWS S3
+```typescript
+import { StorageService } from '@groundbrick/storage-service';
+
+const storage = StorageService.getInstance({
+  provider: 's3',
+  config: {
+    bucket: 'my-bucket',
+    region: 'us-east-1',
+    accessKeyId: process.env.AWS_ACCESS_KEY_ID!,
+    secretAccessKey: process.env.AWS_SECRET_ACCESS_KEY!
+  }
+});
+
+const result = await storage.upload(
+  fileBuffer,
+  'pets/123/photo.jpg',
+  {
+    contentType: 'image/jpeg',
+    metadata: { petId: '123' },
+    isPublic: true
+  }
+);
+```
+
+## 🎯 API
+
+### StorageService
+
+#### `getInstance(config?: StorageConfig): StorageService`
+
+Obtém a instância singleton do serviço.
+
+#### `upload(file: Buffer, path: string, options?: UploadOptions): Promise<StorageResult>`
+
+Faz upload de um arquivo.
+
+**Parâmetros:**
+- `file`: Buffer do arquivo
+- `path`: Caminho relativo onde salvar
+- `options`: Opções de upload (contentType, metadata, isPublic)
+
+**Retorna:** `StorageResult` com url, path, size e contentType
+
+#### `download(path: string): Promise<Buffer>`
+
+Baixa um arquivo.
+
+#### `delete(path: string): Promise<void>`
+
+Deleta um arquivo.
+
+#### `getUrl(path: string): Promise<string>`
+
+Obtém a URL de um arquivo.
+
+#### `exists(path: string): Promise<boolean>`
+
+Verifica se um arquivo existe.
+
+## 🔌 Provedores Disponíveis
+
+### Local
+```typescript
+{
+  provider: 'local',
+  config: {
+    basePath: string;    // Caminho físico no servidor
+    baseUrl: string;     // URL base para acessar os arquivos
+  }
+}
+```
+
+### AWS S3
+```typescript
+{
+  provider: 's3',
+  config: {
+    bucket: string;
+    region: string;
+    accessKeyId: string;
+    secretAccessKey: string;
+    endpoint?: string;   // Para S3-compatible services
+  }
+}
+```
+
+## 📝 Exemplos Práticos
+
+### Integrando com SvelteKit
+```typescript
+// src/lib/server/storage.ts
+import { StorageService } from '@groundbrick/storage-service';
+import { env } from '$env/dynamic/private';
+
+export const storage = StorageService.getInstance({
+  provider: env.STORAGE_PROVIDER as any || 'local',
+  config: env.STORAGE_PROVIDER === 's3' 
+    ? {
+        bucket: env.S3_BUCKET!,
+        region: env.S3_REGION!,
+        accessKeyId: env.S3_ACCESS_KEY_ID!,
+        secretAccessKey: env.S3_SECRET_ACCESS_KEY!
+      }
+    : {
+        basePath: './static/uploads',
+        baseUrl: '/uploads'
+      }
+});
+```
+```typescript
+// src/routes/api/upload/+server.ts
+import { storage } from '$lib/server/storage';
+import { json } from '@sveltejs/kit';
+
+export async function POST({ request }) {
+  const formData = await request.formData();
+  const file = formData.get('file') as File;
+  
+  const buffer = Buffer.from(await file.arrayBuffer());
+  const path = `uploads/${Date.now()}-${file.name}`;
+  
+  const result = await storage.upload(buffer, path, {
+    contentType: file.type,
+    isPublic: true
+  });
+  
+  return json(result);
+}
+```
+
+### Service Layer Pattern
+```typescript
+// services/PetPhotoService.ts
+import { StorageService } from '@groundbrick/storage-service';
+
+export class PetPhotoService {
+  private storage = StorageService.getInstance();
+
+  async uploadPhoto(petId: string, photo: Buffer, mimeType: string) {
+    const fileName = `pets/${petId}/${Date.now()}.${this.getExt(mimeType)}`;
+    return await this.storage.upload(photo, fileName, {
+      contentType: mimeType,
+      metadata: { petId },
+      isPublic: true
+    });
+  }
+
+  async deletePhoto(path: string) {
+    await this.storage.delete(path);
+  }
+
+  private getExt(mimeType: string): string {
+    const map: Record = {
+      'image/jpeg': 'jpg',
+      'image/png': 'png',
+      'image/webp': 'webp'
+    };
+    return map[mimeType] || 'jpg';
+  }
+}
+```
+
+## 🧪 Testes
+```bash
+npm test                 # Roda os testes
+npm run test:watch      # Modo watch
+npm run test:coverage   # Cobertura de testes
+```
+
+## 🏗️ Desenvolvimento
+```bash
+# Clonar o repositório
+git clone https://github.com/groundbrick/storage-service.git
+cd storage-service
+
+# Instalar dependências
+npm install
+
+# Build
+npm run build
+
+# Watch mode
+npm run build:watch
+```
+
+## 📄 Licença
+
+MIT
+
+## 🤝 Contribuindo
+
+Contribuições são bem-vindas! Por favor:
+
+1. Fork o projeto
+2. Crie sua feature branch (`git checkout -b feature/NovaFeature`)
+3. Commit suas mudanças (`git commit -m 'Add: nova feature'`)
+4. Push para a branch (`git push origin feature/NovaFeature`)
+5. Abra um Pull Request
+
+## 🗺️ Roadmap
+
+- [ ] Suporte a Google Cloud Storage
+- [ ] Suporte a Azure Blob Storage
+- [ ] Suporte a Cloudflare R2
+- [ ] Suporte a upload multipart para arquivos grandes
+- [ ] Cache de URLs
+- [ ] Compressão automática de imagens

package/package.json

@@ -0,0 +1,83 @@
+{
+  "name": "@groundbrick/storage-service",
+  "version": "1.1.1",
+  "description": "Serviço de storage plugável com suporte a múltiplos provedores (Local, S3, GCS, Azure)",
+  "type": "module",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "files": [
+    "dist",
+    "README.md",
+    "LICENSE"
+  ],
+  "exports": {
+    ".": {
+      "import": "./dist/index.js",
+      "require": "./dist/index.js",
+      "types": "./dist/index.d.ts"
+    }
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json",
+    "build:watch": "tsc -p tsconfig.build.json --watch",
+    "clean": "rm -rf dist",
+    "prepublishOnly": "npm run clean && npm run build",
+    "lint": "eslint src --ext .ts",
+    "format": "prettier --write \"src/**/*.ts\"",
+    "prepare": "npm run build"
+  },
+  "keywords": [
+    "storage",
+    "s3",
+    "azure",
+    "gcs",
+    "file-upload",
+    "cloud-storage",
+    "typescript"
+  ],
+  "author": "GroundBrick",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/groundbrick/storage-service.git"
+  },
+  "bugs": {
+    "url": "https://github.com/groundbrick/storage-service/issues"
+  },
+  "homepage": "https://github.com/groundbrick/storage-service#readme",
+  "publishConfig": {
+    "access": "public"
+  },
+  "devDependencies": {
+    "@types/jest": "^29.5.11",
+    "@types/mime-types": "^3.0.1",
+    "@types/node": "^20.19.9",
+    "@typescript-eslint/eslint-plugin": "^6.17.0",
+    "@typescript-eslint/parser": "^6.17.0",
+    "eslint": "^8.56.0",
+    "jest": "^29.7.0",
+    "prettier": "^3.1.1",
+    "ts-jest": "^29.1.1",
+    "typescript": "^5.3.3"
+  },
+  "dependencies": {
+    "@aws-sdk/client-s3": "^3.484.0",
+    "@aws-sdk/s3-request-presigner": "^3.484.0",
+    "mime-types": "^2.1.35"
+  },
+  "peerDependencies": {
+    "@aws-sdk/client-s3": "^3.0.0",
+    "@aws-sdk/s3-request-presigner": "^3.0.0"
+  },
+  "peerDependenciesMeta": {
+    "@aws-sdk/client-s3": {
+      "optional": true
+    },
+    "@aws-sdk/s3-request-presigner": {
+      "optional": true
+    }
+  },
+  "engines": {
+    "node": ">=16.0.0"
+  }
+}