Add custom request headers and resumable concurrent downloads

[AndreyVMarkelov]

Summary

This PR adds support for per-request HTTP headers and introduces a Node.js helper for reliable file downloads.

The new extraHeaders option allows callers to provide headers such as Range on individual SDK requests while preventing overrides of SDK-managed headers.

It also adds a public downloadFile helper for Node.js that supports resumable downloads, concurrent byte ranges, retries, integrity validation, and progress reporting.

Changes

Per-request headers

• Add extraHeaders?: Record<string, string> to DropboxRequestOptions
• Apply custom headers to RPC, upload, and download requests
• Preserve SDK-managed headers case-insensitively:
  • Authorization
  • Content-Type
  • Dropbox-API-Arg
• Add JavaScript and TypeScript coverage

Example:

const result = await dbx.filesDownload(
  { path: '/large-file.bin' },
  {
    extraHeaders: {
      Range: 'bytes=0-1048575',
    },
  },
);

Node.js download helper

• Add downloadFile and DropboxFileDownloader as public exports
• Write downloads to localPath + ".part" before finalizing
• Resume existing partial downloads with range requests
• Support bounded concurrent range downloads
• Validate 206 Partial Content responses
• Validate Content-Range and response body lengths
• Pin retries to the original file revision
• Retry transient failures with exponential backoff
• Support cancellation and per-request timeouts
• Report cumulative progress
• Handle partial fs.write() completions
• Verify the final file size
• Verify Dropbox content_hash using streaming reads
• Support empty files
• Clean up invalid partial files safely

Example:

const { Dropbox, downloadFile } = require('dropbox');

const dbx = new Dropbox({
  accessToken: process.env.DROPBOX_ACCESS_TOKEN,
});

await downloadFile(
  dbx,
  '/large-file.bin',
  'large-file.bin',
  {
    parallelDownloads: 4,
    progress: ({ bytesWritten, totalBytes, resumedFrom }) => {
      console.log({
        bytesWritten,
        totalBytes,
        resumedFrom,
      });
    },
  },
);

[codecov]

Codecov Report

❌ Patch coverage is 85.66434% with 41 lines in your changes missing coverage. Please review.
✅ Project coverage is 72.89%. Comparing base (97b3f37) to head (2ae17c5).

Files with missing lines	Patch %	Lines
src/filedownload.js	85.03%	41 Missing ⚠️

Additional details and impacted files

@@            Coverage Diff             @@
##             main    #1201      +/-   ##
==========================================
+ Coverage   68.89%   72.89%   +4.00%     
==========================================
  Files           9       10       +1     
  Lines         913     1199     +286     
==========================================
+ Hits          629      874     +245     
- Misses        284      325      +41     

Flag	Coverage Δ
integration	48.12% <42.65%> (-1.72%)	⬇️
unit	72.14% <85.66%> (+4.23%)	⬆️

Flags with carried forward coverage won't be shown. Click here to find out more.

☔ View full report in Codecov by Harness.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.
• 📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.