Storage

HeroMate ofrece almacenamiento de archivos con Cloudflare R2 (compatible con S3). Cada proyecto puede crear múltiples buckets para organizar archivos, con acceso público o privado. Los uploads van directamente a R2 usando URLs presignadas, y los archivos privados se sirven mediante URLs firmadas a través de un Cloudflare Worker.

Conceptos Clave

• Buckets — contenedores de nivel superior para organizar archivos. Cada bucket es público (servido vía CDN, sin autenticación) o privado (requiere URL firmada).
• Uploads Presignados — el SDK obtiene una URL presignada del engine, luego sube el archivo directamente a R2. Ningún dato pasa por tu servidor.
• URLs Firmadas — URLs con tiempo limitado para descargar archivos privados, verificadas por un Cloudflare Worker.
• Rutas de archivos — los archivos se organizan por ID de entidad y carpeta, ej. {entity_id}/image/avatars/photo.jpg.

Buckets

Los buckets se almacenan en la tabla storage.buckets. Cada bucket tiene:

Crear un Bucket

Puedes crear buckets desde la sección de Storage en el dashboard de tu proyecto, o vía la API:

// Usando el SDK
const bucket = dypai.storage.from('invoices');

Flujo de Upload

HeroMate usa un upload en 3 fases que envía archivos directamente a Cloudflare R2, manteniendo tu servidor ligero:

1. FIRMAR   → El cliente solicita una URL presignada al engine
2. SUBIR    → El cliente sube el archivo directamente a R2 con la URL presignada
3. VERIFICAR → El cliente confirma el upload, el engine registra los metadatos en la BD

Usando el SDK

const { data, error } = await dypai.storage
  .from('documents')
  .upload('invoices/inv-001.pdf', file, {
    onProgress: (pct) => console.log(`${pct}%`),
    clientUpload: true  // Upload directo a R2, no a través de la API
  });

if (data) {
  console.log('Ruta del archivo:', data.file_path);
  console.log('ID del archivo:', data.file_id);
}

El SDK gestiona el flujo completo de 3 fases automáticamente. El callback onProgress proporciona progreso en tiempo real ya que el archivo va directamente del navegador a R2.

Descargar Archivos

Archivos Privados (URLs Firmadas)

Los archivos privados requieren una URL firmada con tiempo limitado:

const { data } = await dypai.storage
  .from('documents')
  .createSignedUrl('invoices/inv-001.pdf', 15); // Válida por 15 minutos

console.log(data.signedUrl);
// → https://media.dypai.es/b/documents/invoices/inv-001.pdf?exp=...&sig=...

Descargar a Disco

await dypai.storage
  .from('documents')
  .download('invoices/inv-001.pdf', { fileName: 'factura.pdf' });

Listar Archivos

const { data: result } = await dypai.storage
  .from('documents')
  .list('invoices/2024', { page: 1, perPage: 20 });

result.data.forEach(file => {
  console.log(file.name, file.size, file.mime_type);
});

if (result.hasMore) {
  // Obtener siguiente página con { page: 2 }
}

Eliminar Archivos

await dypai.storage
  .from('documents')
  .remove('temp/old-file.txt');

Límites y uso de storage

El almacenamiento de objetos se mide a nivel de workspace (organización): el límite viene de tu plan de org y se comparte entre todas las apps del workspace. Cuando superas la cuota de object storage, los nuevos uploads se bloquean hasta que liberes espacio o subas de plan.

Sigue tu consumo desde la página de Usage por proyecto (Observe → Usage), que muestra Object storage junto a Build minutes y Database storage.

Límites de Tamaño

El tamaño máximo de archivo depende del tipo. Estos límites son aproximados y pueden cambiar — tómalos como referencia:

Tipos de Archivo Bloqueados

Por seguridad, las siguientes extensiones están bloqueadas:

• Ejecutables: .exe, .msi, .dmg, .pkg, .deb, .rpm
• Scripts: .bat, .cmd, .sh, .ps1, .vbs, .scr
• Office con macros: .xlsm, .pptm, .docm
• Java: .jar, .class
• Apps: .app, .ipa, .apk

Siguientes Pasos

• Referencia SDK Storage — todos los métodos de storage disponibles en el SDK cliente.
• API Builder — crea workflows personalizados de upload/download.
• Uso y Cuotas — sigue el object storage frente al límite de tu plan.