SDK Storage

Las subidas y descargas de archivos pasan por tus endpoints de HeroMate, lo que permite que el backend valide permisos antes de generar URLs de upload, URLs firmadas de descarga o acciones de borrado.

Métodos recomendados en cliente

Usa estos métodos para flujos de archivos:

• dypai.api.upload(endpoint, file, { params, onProgress })
• dypai.api.download(endpoint, body?, { fileName, params })
• dypai.api.post(endpoint, body) cuando quieres obtener manualmente la signed URL o la respuesta de storage
• dypai.api.delete(endpoint, { params }) para flujos de eliminación

Upload

Usa dypai.api.upload() para las subidas desde navegador. El SDK sigue ejecutando automáticamente el flujo Smart Upload:

1. Pedir a tu endpoint una URL presignada de upload
2. Subir el binario directamente a R2/S3
3. Confirmar el upload de nuevo a través del endpoint

const { data, error } = await dypai.api.upload('storage_files', file, {
  params: {
    operation: 'upload',
    file_path: `invoices/${file.name}`,
  },
  onProgress: (pct) => console.log(`Upload: ${pct}%`),
});

if (error) {
  console.error(error.message);
  return;
}

console.log('Ruta real en storage:', data?.storage_path);

Importante: usa storage_path

Durante el upload el backend puede añadir un UUID o normalizar el nombre del archivo. Guarda storage_path en tu base de datos, no el file_path original.

const storedPath = data?.storage_path || data?.file_path;

Download

Para descargas seguras, llama a un endpoint backend que valide la propiedad del archivo y después devuelva la signed URL o dispare la descarga.

const { data, error } = await dypai.api.download(
  'download_invoice_document',
  { entity_id: invoice.id },
  { fileName: 'invoice.pdf' }
);

Si quieres obtener la signed URL manualmente:

const { data, error } = await dypai.api.post('download_invoice_document', {
  entity_id: invoice.id,
});

const signedUrl = data?.signedUrl || data?.signed_url;

Listar archivos

Para listar, llama a un endpoint workflow que envuelva dypai_storage con operation: "list":

const { data, error } = await dypai.api.post('storage_files', {
  operation: 'list',
  prefix: 'invoices/2024',
});

Eliminar

Elimina archivos también a través de un endpoint:

const { error } = await dypai.api.delete('storage_delete_files', {
  params: { file_path: storedPath },
});

Patrón backend

En backend, tu endpoint suele usar un nodo dypai_storage. Un endpoint genérico puede soportar upload, download, read, list o delete usando input.operation.

Para descargas visibles por usuario, conviene un endpoint dedicado que primero valide propiedad con SQL y solo después invoque dypai_storage.