SDK Storage

File uploads and downloads go through your HeroMate endpoints, which lets the backend validate permissions before generating upload URLs, signed download URLs, or delete actions.

Recommended Client Methods

Use these methods for file flows:

• dypai.api.upload(endpoint, file, { params, onProgress })
• dypai.api.download(endpoint, body?, { fileName, params })
• dypai.api.post(endpoint, body) when you want the signed URL or storage response manually
• dypai.api.delete(endpoint, { params }) for deletion flows

Upload

Use dypai.api.upload() for browser uploads. The SDK still performs the Smart Upload flow automatically:

1. Ask your endpoint for a presigned upload URL
2. Upload the binary directly to R2/S3
3. Confirm the upload back through the 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('Real storage path:', data?.storage_path);

Important: use storage_path

During upload the backend may append a UUID or normalize the filename. Save storage_path in your database, not the original file_path.

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

Download

For secure downloads, call a backend endpoint that validates ownership and then returns the signed URL or triggers the download.

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

If you want the signed URL manually:

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

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

List Files

For listing, call a workflow endpoint that wraps dypai_storage with operation: "list":

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

Delete

Delete files through an endpoint as well:

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

Backend Pattern

On the backend, your endpoint typically uses a dypai_storage node. A generic endpoint can support upload, download, read, list, or delete via input.operation.

For user-facing downloads, prefer a dedicated endpoint that first validates ownership with SQL and only then calls dypai_storage.