DPU Cloud SDK

A comprehensive TypeScript SDK for interacting with DPU (Data Processing Unit) storage services. This package provides upload, download, compression, and translation capabilities for file management in cloud environments.

Features

• 📁 File Upload & Download - Support for single and multi-part uploads with progress tracking
• 🗜️ Compression - Compress folders and monitor compression status
• 🌐 Translation - Translate files between different formats
• ⚙️ Configurable Base URL - Customize domain for different environments
• 🔐 Token Management - Built-in token refresh support
• 🚀 Worker Threads - Parallel file processing with automatic worker management
• ♻️ Retry Logic - Automatic retry with exponential backoff
• 📊 Progress Tracking - Real-time upload/download progress callbacks

Installation

npm install dpu-cloud-sdk

Quick Start

Basic Setup

import { DPUClient } from 'dpu-cloud-sdk';

const client = new DPUClient(
  accessToken,
  refreshTokenCallback
);

With Custom Base URL

import { DPUClient } from 'dpu-cloud-sdk';

const client = new DPUClient(
  accessToken,
  refreshTokenCallback,
  3, // maxRetry
  'https://your-custom-domain.com' // Custom base URL
);

Configuration

Setting Base URL

There are multiple ways to configure the base URL:

1. Via Constructor (Recommended)

const client = new DPUClient(
  accessToken,
  refreshTokenCallback,
  maxRetry,
  'https://api.yourdomain.com'
);

2. Via dpuConfig (Global)

import { dpuConfig, DPUClient } from 'dpu-cloud-sdk';

// Set globally before creating client
dpuConfig.setBaseURL('https://api.yourdomain.com');

const client = new DPUClient(accessToken, refreshTokenCallback);

3. Via setConfig

import { dpuConfig } from 'dpu-cloud-sdk';

dpuConfig.setConfig({
  baseURL: 'https://api.yourdomain.com'
});

Environment-based Configuration

// For development
dpuConfig.setBaseURL(process.env.REACT_APP_API_URL || 'https://dev-api.yourdomain.com');

// For production
dpuConfig.setBaseURL('https://api.yourdomain.com');

Usage Examples

File Upload

Single File Upload with Progress

import { DPUClient } from 'dpu-cloud-sdk';

const client = new DPUClient(accessToken, refreshTokenCallback);

const uploadedId = await client.uploadSingleFile(
  bucketName,
  fileKey,
  file,
  {
    onProgress: (percentage) => {
      console.log(`Upload progress: ${percentage}%`);
    }
  }
);

Multiple Files Upload

const fileMap = new Map([
  [fileKey1, file1],
  [fileKey2, file2],
  [fileKey3, file3]
]);

const results = await client.uploadMultipleFiles(
  bucketName,
  fileMap,
  {
    onProgress: (fileKey, percentage) => {
      console.log(`${fileKey}: ${percentage}%`);
    }
  }
);

File Download

const downloadUrl = await client.getUrlToDownload(
  bucketName,
  fileName
);

// Download the file
window.location.href = downloadUrl;

Compression

Compress Folder

const compressResult = await client.compressFolder(
  bucketName,
  folderPath,
  {
    onProgress: (status) => {
      console.log('Compression status:', status);
    }
  }
);

console.log('Compression ID:', compressResult.dataId);

Get Compression Status

const status = await client.getStatusCompress(compressionId);
console.log('Compression status:', status);

Translation

Translate File

const translateRequest = {
  bucketName: 'my-bucket',
  fileName: 'document.pdf',
  targetFormat: 'docx'
};

const translateResult = await client.translateFile(translateRequest);
console.log('Translation ID:', translateResult.dataId);

Get Translation Status

const status = await client.getStatusTranslate(translateId);
console.log('Translation progress:', status.percentage);

Get Translation Status for Specific File

const fileStatus = await client.getStatusTranslateFile(
  translateId,
  fileName
);

API Methods

DPUClient Methods

Upload Methods

• uploadSingleFile(bucketName, fileKey, file, options?) - Upload a single file
• uploadMultipleFiles(bucketName, fileMap, options?) - Upload multiple files
• uploadSingleFileWithCustomFileName(bucketName, customName, file, options?) - Upload with custom name
• uploadSingleFileWithInitUpload(bucketName, fileKey, file, options?) - Upload with init upload

Download Methods

• getUrlToDownload(bucketName, fileName) - Get download URL
• downloadSingleFile(bucketName, fileName, options?) - Download file directly
• downloadMultipleFiles(bucketName, fileNames, options?) - Download multiple files

Compression Methods

• compressFolder(bucketName, folderPath, options?) - Compress a folder
• getStatusCompress(compressionId) - Check compression status
• cancelCompressionDownload(compressionId) - Cancel compression

Translation Methods

• translateFile(request, options?) - Start file translation
• getStatusTranslate(translateId) - Get translation status
• getStatusTranslateFile(translateId, fileName) - Get specific file translation status
• getEPSGRegionCode(region) - Get EPSG code for region
• getFileTileSet(translateId) - Get file tile set

Object Methods

• getObjectDetail(bucketName, fileName) - Get object details
• getObjects(bucketName) - List objects in bucket
• applyPermissionToObjects(data) - Apply permissions to objects

Configuration Options

DPUClient Constructor

new DPUClient(
  accessToken?: string,           // JWT access token
  reFreshToken?: () => Promise<string>,  // Callback to refresh token
  maxRetry?: number,              // Max retry attempts (default: 3)
  baseURL?: string                // Custom API base URL
)

Upload Options

interface UploadOptions {
  onProgress?: (percentage: number) => void;
  cancellationToken?: AbortController;
  fileKey?: string;
  dataUploadId?: string;
}

Download Options

interface DownloadOptions {
  onProgress?: (loadedBytes: number, totalBytes: number) => void;
  cancellationToken?: AbortController;
}

Error Handling

The SDK includes built-in error handling with automatic retries for transient failures:

try {
  const result = await client.uploadSingleFile(bucketName, fileKey, file);
  console.log('Upload successful:', result);
} catch (error) {
  console.error('Upload failed:', error.message);
  // Handle error appropriately
}

Common Error Status Codes

• 200 - Success
• 400 - Bad Request
• 401 - Unauthorized (Token expired or invalid)
• 403 - Forbidden (Insufficient permissions)
• 404 - Not Found (Resource doesn't exist)
• 500 - Internal Server Error

Token Management

Automatic Token Refresh

Provide a refresh token callback to automatically refresh tokens when they expire:

const refreshTokenCallback = async () => {
  const response = await fetch('/api/refresh-token', {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' }
  });
  const { token } = await response.json();
  return token;
};

const client = new DPUClient(
  initialAccessToken,
  refreshTokenCallback
);

Advanced Usage

Cancelling Operations

Use AbortController to cancel ongoing operations:

const cancellationToken = new AbortController();

setTimeout(() => {
  cancellationToken.abort(); // Cancel after 5 seconds
}, 5000);

try {
  await client.uploadSingleFile(
    bucketName,
    fileKey,
    largeFile,
    { cancellationToken }
  );
} catch (error) {
  if (error.name === 'AbortError') {
    console.log('Upload cancelled');
  }
}

Parallel Uploads with Progress

const files = [file1, file2, file3];

const promises = files.map((file, index) =>
  client.uploadSingleFile(
    bucketName,
    `file-${index}`,
    file,
    {
      onProgress: (percentage) => {
        console.log(`File ${index}: ${percentage}%`);
      }
    }
  )
);

const results = await Promise.all(promises);

Performance Tips

1. Use Multiple Files Upload - More efficient for batch operations than individual uploads
2. Monitor Progress - Implement progress callbacks for better UX
3. Optimize Chunk Size - Default is 5MB per chunk (configurable)
4. Limit Concurrent Workers - Default max 20 workers (adjust based on system resources)
5. Handle Token Refresh - Implement token refresh callback to avoid interruptions

Browser Compatibility

• Chrome 90+
• Firefox 88+
• Safari 14+
• Edge 90+

TypeScript Support

This package is fully typed with TypeScript. All models and interfaces are exported:

import {
  DPUClient,
  dpuConfig,
  InitUploadResponse,
  PresignURLResponse,
  TranslateInfo,
  CompressStatus
} from 'dpu-cloud-sdk';

Support & Documentation

For issues, questions, or contributions, please contact the development team or check the internal documentation.

License

ISC

Changelog

v1.0.0

• Initial release
• File upload/download functionality
• Compression support
• Translation support
• Configurable base URL
• Token refresh support
• Progress tracking
• Retry logic