zeos-images

Uma biblioteca Node.js para upload e gerenciamento de imagens com suporte a S3/Wasabi.

Instalação

npm install zeos-images

Uso Básico

Configuração Standalone

import { ZeosImages } from 'zeos-images';

const imageService = new ZeosImages({
    endpoint: 'https://s3.us-west-1.wasabisys.com',
    bucket: 'meu-bucket',
    accessKey: 'SUA_ACCESS_KEY',
    secretKey: 'SUA_SECRET_KEY',
    region: 'us-west-1', // opcional
    publicUrl: 'https://images.seusite.com', // opcional
    uploadPath: 'uploads', // opcional
    maxFileSize: 5 * 1024 * 1024, // opcional, padrão: 5MB
});

// Upload de arquivo
const result = await imageService.upload({
    buffer: fileBuffer,
    originalname: 'foto.jpg',
    mimetype: 'image/jpeg',
    size: fileBuffer.length
});

if (result.success) {
    console.log('URL da imagem:', result.url);
} else {
    console.error('Erro:', result.error);
}

// Obter arquivo
const file = await imageService.getFile('1234567890-foto.jpg');

// Deletar arquivo
await imageService.deleteFile('1234567890-foto.jpg');

Com Express (Middleware)

import express from 'express';
import { ZeosImages, createUploadRouter } from 'zeos-images';

const app = express();

const imageService = new ZeosImages({
    endpoint: process.env.S3_ENDPOINT,
    bucket: process.env.S3_BUCKET,
    accessKey: process.env.S3_ACCESS_KEY,
    secretKey: process.env.S3_SECRET_KEY,
    publicUrl: 'https://images.seusite.com'
});

// Criar router com rotas pré-configuradas
const uploadRouter = createUploadRouter(imageService, {
    uploadPath: '/upload',      // POST /api/images/upload
    getPath: '/uploads/:filename' // GET /api/images/uploads/:filename
});

app.use('/api/images', uploadRouter);

app.listen(3000, () => {
    console.log('Servidor rodando na porta 3000');
});

Middleware Customizado

import express from 'express';
import { ZeosImages, createUploadMiddleware } from 'zeos-images';

const app = express();

const imageService = new ZeosImages({
    endpoint: process.env.S3_ENDPOINT,
    bucket: process.env.S3_BUCKET,
    accessKey: process.env.S3_ACCESS_KEY,
    secretKey: process.env.S3_SECRET_KEY
});

const upload = createUploadMiddleware({
    maxFileSize: 10 * 1024 * 1024, // 10MB
    blockedExtensions: ['.exe', '.bat', '.sh']
});

app.post('/upload', upload.single('file'), async (req, res) => {
    const result = await imageService.upload(req.file);
    
    if (result.success) {
        res.json({ url: result.url });
    } else {
        res.status(400).json({ error: result.error });
    }
});

API

ZeosImages

Constructor

new ZeosImages(config)

| Parâmetro | Tipo | Obrigatório | Descrição | |-----------|------|-------------|-----------| | endpoint | string | ✅ | URL do endpoint S3/Wasabi | | bucket | string | ✅ | Nome do bucket | | accessKey | string | ✅ | Chave de acesso | | secretKey | string | ✅ | Chave secreta | | region | string | ❌ | Região (padrão: 'us-west-1') | | publicUrl | string | ❌ | URL pública base para os arquivos | | uploadPath | string | ❌ | Prefixo/pasta para uploads (padrão: 'uploads') | | maxFileSize | number | ❌ | Tamanho máximo em bytes (padrão: 5MB) | | blockedExtensions | string[] | ❌ | Extensões bloqueadas |

Métodos

upload(file)

Faz upload de um arquivo.

const result = await imageService.upload({
    buffer: Buffer,
    originalname: string,
    mimetype: string,
    size?: number
});
// Returns: { success: boolean, url?: string, error?: string }

getFile(filename)

Obtém um arquivo do storage.

const result = await imageService.getFile('filename.jpg');
// Returns: { success: boolean, data?: Object, error?: string }

deleteFile(filename)

Deleta um arquivo do storage.

const result = await imageService.deleteFile('filename.jpg');
// Returns: { success: boolean, error?: string }

isExtensionAllowed(filename)

Verifica se a extensão do arquivo é permitida.

const allowed = imageService.isExtensionAllowed('foto.jpg');
// Returns: boolean

createUploadMiddleware(options)

Cria um middleware multer configurado.

const upload = createUploadMiddleware({
    maxFileSize: 5 * 1024 * 1024,
    blockedExtensions: ['.exe']
});

createUploadRouter(zeosImages, options)

Cria um Express Router com rotas de upload pré-configuradas.

const router = createUploadRouter(imageService, {
    uploadPath: '/upload',
    getPath: '/uploads/:filename'
});

Extensões Bloqueadas por Padrão

• .xll, .exe, .bat, .sh, .cmd, .com, .cpl, .msi
• .js, .php
• .svg, .html, .htm, .shtml, .xhtml

Validações

• Verificação de extensão de arquivo
• Verificação de tamanho máximo
• Verificação de conteúdo malicioso em SVGs (scripts, iframes, etc.)

Variáveis de Ambiente Recomendadas

S3_ENDPOINT=https://s3.us-west-1.wasabisys.com
S3_BUCKET=meu-bucket
S3_ACCESS_KEY=sua-access-key
S3_SECRET_KEY=sua-secret-key
S3_REGION=us-west-1

Licença

MIT