npm package: @groundbrick/storage-service
Description: Serviço de storage plugável com suporte a múltiplos provedores (Local, S3, GCS, Azure)
Author: GroundBrick
Latest version: 1.2.0

# @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