v2.1.0 - Streaming upload + task.type populated

✨ Highlights

🚀 Streaming upload

FilesAPI.upload() now streams a chunked multipart/form-data body instead of buffering the entire payload in memory. No more OOM cliff at ~200 MB. Safe for arbitrarily large files.

🐛 Fixed: task.type is no longer empty

client.getTask(id) previously hardcoded task.type = "". With api 1.38.5+, the SDK reads the new type field from /v1/tasks/{id} and populates the Task instance correctly. Older API deployments still fall back to "" gracefully.

🔧 New public API

• HttpClient.postStream(path, body, contentType, extraHeaders?) — streaming POST. Skips retry (consumed streams can't be replayed).
• New named exports: buildMultipartStream, sanitizeFilename.
• TaskStatusResponse.type?: string typed for the new API response shape.

⚠️ Behaviour change

Uploads previously could be retried up to 3 times on transient network failures because the body was a fully-buffered FormData. Streamed uploads cannot be replayed, so a failed upload now surfaces the error immediately. All other operations retain the existing retry behaviour (3 retries, exponential backoff on 408/500/502/503/504).

🧪 Tests

90 tests passing (12 new streaming tests covering binary byte preservation, chunk boundaries, large-input streaming, source-stream error propagation, sanitized filename, multipart envelope structure).

🔒 Security

• 0 npm audit vulnerabilities (vite 7.3.1 → 7.3.2, postcss 8.5.6 → 8.5.15, brace-expansion transitive bump).

📦 Install

npm install conversiontools@2.1.0

Full Changelog: v2.0.4...v2.1.0

v2.0.4

• Update dependencies (minimatch, rollup, flatted, picomatch)

v2.0.3

What's new

• onProgress callback in downloadTo() — track download progress with loaded, total, percent events
• onDownloadProgress config option is now wired through convert() → task.downloadTo()
• Fix: SDK version in User-Agent header is now injected at build time from package.json — was previously hardcoded as 2.0.0

Installation

npm install conversiontools@2.0.3

Upgrade

npm install conversiontools@latest

v2.0.2

What's Changed

• feat: add config option to override user agent

Full Changelog: v2.0.1...v2.0.2

v2.0.1

What's Changed

• Bump glob from 10.4.5 to 10.5.0 by @dependabot[bot] in #10
• chore: update deps by @drdmitry in #11

Full Changelog: v2.0.0...v2.0.1

2.0.0 - Modern TypeScript Client Library

🚀 Release v2.0.0: Modern TypeScript Client Library

Overview

This PR introduces conversiontools v2.0.0, a complete rewrite of the Node.js client library with modern architecture, full TypeScript support, and enhanced developer experience.

🎯 What's New in v2

Core Improvements

• Full TypeScript Support - Complete type definitions with IntelliSense for all methods and options
• Dual Module Support - Native ESM and CommonJS compatibility
• Streaming Support - Efficient handling of large files with Node.js streams
• Progress Tracking - Real-time callbacks for upload, conversion, and download progress
• Smart Retry Logic - Automatic retry with exponential backoff for failed requests
• Modern Stack - Built on native fetch API, Node 18+, zero heavy dependencies
• Webhook Support - Async notifications for task completion
• Sandbox Mode - Unlimited testing without consuming quota

Developer Experience

• Cleaner API - More intuitive method names and parameter structure
• Better Error Handling - Typed error classes for specific error scenarios
• Improved Documentation - Comprehensive README with examples and migration guide
• Enhanced Debugging - Better error messages and logging capabilities

🔄 Breaking Changes from v1

1. Constructor & Initialization

// v1
const ConversionClient = require('conversiontools');
const client = new ConversionClient('api-token');

// v2
const { ConversionToolsClient } = require('conversiontools');
const client = new ConversionToolsClient({
  apiToken: 'api-token'
});

2. Conversion Method

// v1
await client.run('convert.xml_to_excel', {
  filename: './input.xml',
  outputFilename: './output.xlsx',
  options: { sandbox: true }
});

// v2
await client.convert({
  type: 'convert.xml_to_excel',
  input: './input.xml',
  output: './output.xlsx',
  options: { sandbox: true }
});

3. Parameter Names

• filename → input
• outputFilename → output
• Constructor now accepts configuration object instead of string token

4. Module Exports

• Named exports instead of default export
• ConversionClient → ConversionToolsClient

✨ New Features

1. TypeScript Support

import { ConversionToolsClient, RateLimitError } from 'conversiontools';

const client = new ConversionToolsClient({
  apiToken: 'your-token',
});

// Full type safety and IntelliSense
await client.convert({
  type: 'convert.xml_to_csv',
  input: './data.xml',
  output: './result.csv',
  options: {
    delimiter: 'comma', // IntelliSense suggests valid values
  },
});

2. Progress Tracking

const client = new ConversionToolsClient({
  apiToken: 'your-token',
  onUploadProgress: (progress) => {
    console.log(`Upload: ${progress.percent}%`);
  },
  onConversionProgress: (progress) => {
    console.log(`Converting: ${progress.percent}%`);
  },
  onDownloadProgress: (progress) => {
    console.log(`Download: ${progress.percent}%`);
  },
});

3. Advanced Task Control

// Step-by-step control
const fileId = await client.files.upload('./data.xml');
const task = await client.createTask({
  type: 'convert.xml_to_excel',
  options: { file_id: fileId },
});

await task.wait({
  onProgress: (status) => {
    console.log(`Status: ${status.status}`);
  },
});

await task.downloadTo('./result.xlsx');

4. Streaming Support

// Stream large files efficiently
const stream = await client.files.downloadStream(fileId);
stream.pipe(fs.createWriteStream('./output.xlsx'));

5. Enhanced Error Handling

import {
  RateLimitError,
  ValidationError,
  ConversionError,
} from 'conversiontools';

try {
  await client.convert({ /* ... */ });
} catch (error) {
  if (error instanceof RateLimitError) {
    console.error('Quota exceeded:', error.limits);
  } else if (error instanceof ValidationError) {
    console.error('Invalid input:', error.message);
  }
}

📦 Package Structure

dist/
├── index.js          # ESM build
├── index.cjs         # CommonJS build
├── index.d.ts        # TypeScript types (ESM)
├── index.d.cts       # TypeScript types (CommonJS)
├── legacy.js         # v1 compatibility (ESM)
├── legacy.cjs        # v1 compatibility (CommonJS)
└── ...

🔙 Backward Compatibility

V1 API is still available via legacy import for gradual migration:

const ConversionClient = require('conversiontools/legacy');
const client = new ConversionClient('your-api-token');

await client.run('convert.xml_to_excel', {
  filename: 'data.xml',
  outputFilename: 'result.xlsx',
});

Note: Legacy API is deprecated and will be removed in v3.

🧪 Testing

• ✅ Unit tests for all core functionality
• ✅ Integration tests with live API
• ✅ TypeScript type checking
• ✅ ESM and CommonJS compatibility tests
• ✅ Example files verified in examples/ directory

📝 Documentation Updates

• ✅ README.md updated with v2 examples
• ✅ Migration guide from v1 to v2
• ✅ API reference documentation
• ✅ TypeScript usage examples
• ✅ Example files in examples/ directory

🌐 Web Frontend Updates

Web frontend has been updated to showcase v2 API:

• ✅ HomePage.jsx code example updated
• ✅ ApiPricing.jsx code example updated
• ✅ v2 features highlighted (TypeScript, streaming, progress tracking)

📊 Bundle Size

• v1: ~45KB (minified)
• v2: ~38KB (minified) - 15% smaller despite more features

🔐 Security

• ✅ Dependencies updated to latest secure versions
• ✅ No known vulnerabilities
• ✅ Supports Node.js 18+ with native security features

⚙️ Requirements

• Node.js: 18.0.0 or higher
• API Token: From https://conversiontools.io/profile

🚀 Migration Checklist for Users

• Update package: npm install conversiontools@latest
• Change import: const { ConversionToolsClient } = require('conversiontools')
• Update constructor: new ConversionToolsClient({ apiToken: '...' })
• Change method: client.run() → client.convert()
• Update parameters: filename → input, outputFilename → output
• Test with sandbox: true before production deployment
• Optional: Add progress callbacks, error handling, etc.

📋 Pre-Merge Checklist

• All tests passing
• TypeScript types generated
• ESM and CommonJS builds working
• README.md updated
• Migration guide included
• Examples verified
• CHANGELOG.md updated
• Version bumped to 2.0.0 in package.json
• Web frontend examples updated
• No breaking changes to REST API
• Backward compatibility layer (legacy) working

🎉 Post-Merge Tasks

• Publish to npm: npm publish
• Create GitHub release with changelog
• Update documentation site
• Announce v2 release (blog post, email, social media)
• Monitor npm downloads and GitHub issues
• Notify enterprise customers of v2 availability

🤝 Contributors

@drdmitry

---

⚠️ Important: This is a major version release with breaking changes. Users on v1 should review the migration guide and test thoroughly before upgrading production systems. Legacy v1 API is available via conversiontools/legacy for gradual migration.

🔗 Links:

• Migration Guide
• Examples
• Conversion Tools API Documentation

1.0.3

• Updated modules
• Added examples with async/await, conversion by URL