Appearance

useDownloadApi Composable ​

File Information ​

  • Path: app/composables/api/useDownloadApi.ts
  • Purpose: Download operations API (single files, multiple files, ZIP generation)
  • Category: Utility API Composable

Overview ​

The useDownloadApi composable provides functionality for downloading assets, including single file downloads, multiple file ZIP downloads, and image asset downloads with progress tracking.

Functions ​

downloadFile ​

Downloads a single file (blob) with progress tracking.

Signature:

typescript
downloadFile(payload: {
  id: string
  url: string
  name: string
  file_type?: string
  collection_id?: string
  callCountApi?: boolean
  useModernDownload?: boolean
  extras?: Record<string, any>
  multiple?: boolean
  onProgress?: (progress: number, loaded: number, total: number) => void
}): Promise<{ blob: Blob, finalName: string } | void>

Parameters:

  • id: string - Asset ID
  • url: string - Download URL
  • name: string - File name
  • file_type?: string - File type/extension
  • collection_id?: string - Collection ID (for collection assets)
  • callCountApi?: boolean - Whether to call count API (default: true)
  • useModernDownload?: boolean - Use modern download method (default: false)
  • extras?: Record<string, any> - Additional parameters
  • multiple?: boolean - Whether downloading multiple files (default: false)
  • onProgress?: (progress, loaded, total) => void - Progress callback

Returns:

  • Promise<{ blob: Blob, finalName: string } | void> - Blob and final name, or void for legacy downloads

Usage:

typescript
const { downloadFile } = useDownloadApi()

// Modern download with progress
const { blob, finalName } = await downloadFile({
  id: assetId,
  url: assetUrl,
  name: 'asset.png',
  useModernDownload: true,
  onProgress: (progress, loaded, total) => {
    console.log(`Download progress: ${progress}%`)
  }
})

// Download blob
const url = URL.createObjectURL(blob)
const a = document.createElement('a')
a.href = url
a.download = finalName
a.click()

downloadMultipleFiles ​

Downloads multiple files as a ZIP archive.

Signature:

typescript
downloadMultipleFiles(payload: {
  files?: string[]
  folders?: string[]
  collection_id?: string
  share_id?: string
  download_name?: string
  shareWorkspaceId?: string
  shareMode?: boolean
}): Promise<any>

Parameters:

  • files?: string[] - Array of file IDs
  • folders?: string[] - Array of folder IDs
  • collection_id?: string - Collection ID
  • share_id?: string - Share ID
  • download_name?: string - ZIP file name
  • shareWorkspaceId?: string - Share workspace ID
  • shareMode?: boolean - Whether in share mode (default: false)

Returns:

  • Promise<any> - Download response with status and URL/filename

Response Types:

  • { status: 'email-notification', message: string } - Email notification sent
  • { status: 'success-direct-link', url: string, name: string, file_type: string } - Direct download link
  • { status: 'fetch', zipUrl: string, filename: string, payload: any } - Use with finalDownload

API Endpoint:

  • POST /digital/generate-zip-data (normal mode)
  • POST /share-zip-data (share mode)

Usage:

typescript
const { downloadMultipleFiles, finalDownload } = useDownloadApi()

// Generate ZIP
const response = await downloadMultipleFiles({
  files: ['1', '2', '3'],
  folders: ['10', '11'],
  download_name: 'my-download'
})

if (response.status === 'fetch') {
  // Use StreamSaver for large files
  const { res, finalFilename } = await finalDownload(response)
  // Download using StreamSaver...
}

downloadImageAsset ​

Downloads a generated image asset.

Signature:

typescript
downloadImageAsset(payload: {
  assetId: string
  fileName: string
  fileType: string
  isDetailsPage?: boolean
}): Promise<{ blob: Blob }>

Parameters:

  • assetId: string - Asset ID
  • fileName: string - File name
  • fileType: string - File type (png, jpg, etc.)
  • isDetailsPage?: boolean - Whether on details page

Returns:

  • Promise<{ blob: Blob }> - Image blob

API Endpoint: POST /digital/download-file (responseType: 'blob')

Usage:

typescript
const { downloadImageAsset } = useDownloadApi()

const { blob } = await downloadImageAsset({
  assetId: '123',
  fileName: 'image',
  fileType: 'png'
})

// Download blob
const url = URL.createObjectURL(blob)
const a = document.createElement('a')
a.href = url
a.download = 'image.png'
a.click()

finalDownload ​

Performs the final download operation for ZIP files using StreamSaver.

Signature:

typescript
finalDownload(downloadMultipleResponse: any): Promise<{ res: Response, finalFilename: string }>

Parameters:

  • downloadMultipleResponse: any - Response from downloadMultipleFiles with status 'fetch'

Returns:

  • Promise<{ res: Response, finalFilename: string }> - Fetch response and final filename

Usage:

typescript
const { downloadMultipleFiles, finalDownload } = useDownloadApi()

const response = await downloadMultipleFiles({ files: ['1', '2'] })

if (response.status === 'fetch') {
  const { res, finalFilename } = await finalDownload(response)
  
  // Use StreamSaver for download
  const fileStream = streamSaver.createWriteStream(finalFilename)
  const writer = fileStream.getWriter()
  
  const reader = res.body!.getReader()
  // Stream download...
}

Error Handling ​

All functions include error handling. Components should handle errors:

typescript
try {
  const { blob } = await downloadFile({ ... })
} catch (error) {
  console.error('Download failed:', error)
  // Show error message
}

Integration ​

The composable uses:

  • useSnackbar() - For success/error messages
  • useHelpers() - For helper functions
  • $api - For API calls

Use Cases ​

Single File Download ​

typescript
const { downloadFile } = useDownloadApi()

const downloadAsset = async (asset: Asset) => {
  try {
    const { blob, finalName } = await downloadFile({
      id: asset.id,
      url: asset.url,
      name: asset.name,
      useModernDownload: true,
      onProgress: (progress) => {
        downloadProgress.value = progress
      }
    })
    
    // Download blob
    downloadBlob(blob, finalName)
  } catch (error) {
    snackbar.showError('Download failed')
  }
}

Multiple File ZIP Download ​

typescript
const { downloadMultipleFiles } = useDownloadApi()

const downloadSelected = async (selectedItems: string[]) => {
  const response = await downloadMultipleFiles({
    files: selectedItems,
    download_name: 'selected-assets'
  })
  
  if (response.status === 'email-notification') {
    snackbar.showSuccess(response.message)
  } else if (response.status === 'success-direct-link') {
    window.open(response.url, '_blank')
  } else {
    // Use StreamSaver for large ZIPs
    await handleStreamDownload(response)
  }
}