conversiontools

v2.0.1

Published

8 days ago

Modern TypeScript/JavaScript library to convert files using Conversion Tools API at https://conversiontools.io - supports ESM & CommonJS with full TypeScript types

0High
0Medium
0Low

drdmitry

conversiontools conversion tools convert document file api sdk client typescript xml json excel pdf csv

Conversion Tools Node.js Client (v2)

Modern TypeScript/JavaScript library for converting files using the Conversion Tools API. Convert between 100+ file formats including XML, JSON, Excel, PDF, CSV, images, audio, video, and more.

✨ What's New in v2

🎯 Full TypeScript Support - Complete type definitions with IntelliSense
📦 Dual Module Support - Works with both ESM and CommonJS
🚀 Streaming Support - Handle large files efficiently
📊 Progress Tracking - Monitor upload, conversion, and download progress
🔄 Smart Retry Logic - Automatic retry with exponential backoff
🎨 Better DX - Cleaner API with improved error handling
🔌 Webhook Support - Async notifications for task completion
🧪 Sandbox Mode - Unlimited testing without consuming quota
⚡ Modern Stack - Native fetch, Node 18+, zero heavy dependencies

Installation

npm install conversiontools

Or with Yarn:

yarn add conversiontools

Quick Start

const { ConversionToolsClient } = require('conversiontools');

// Initialize client
const client = new ConversionToolsClient({
  apiToken: 'your-api-token', // Get from https://conversiontools.io/profile
});

// Convert XML to Excel
await client.convert({
  type: 'convert.xml_to_excel',
  input: './data.xml',
  output: './result.xlsx',
});

Features

📁 100+ File Format Conversions

Convert between all major file formats:

Documents: XML, JSON, Excel, PDF, CSV, Word, PowerPoint, Markdown
Images: JPG, PNG, WebP, AVIF, HEIC, SVG, TIFF
eBooks: ePUB, MOBI, AZW, AZW3, FB2
Audio: MP3, WAV, FLAC
Video: MP4, MOV, MKV, AVI
And more...

🚀 Simple API

// One-liner conversions
await client.convert({
  type: 'convert.json_to_excel',
  input: './data.json',
  output: './result.xlsx',
});

// With options
await client.convert({
  type: 'convert.xml_to_csv',
  input: './data.xml',
  output: './result.csv',
  options: {
    delimiter: 'comma',
    quote: true,
  },
});

// URL-based conversions
await client.convert({
  type: 'convert.website_to_pdf',
  input: { url: 'https://example.com' },
  output: './website.pdf',
  options: {
    images: true,
    javascript: true,
  },
});

📊 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}%`);
  },
});

await client.convert({
  type: 'convert.pdf_to_excel',
  input: './large-file.pdf',
  output: './result.xlsx',
});

🎯 TypeScript Support

Full type safety with IntelliSense:

import { ConversionToolsClient, RateLimitError } from 'conversiontools';

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

// TypeScript knows all valid conversion types and options
await client.convert({
  type: 'convert.xml_to_csv',
  input: './data.xml',
  output: './result.csv',
  options: {
    delimiter: 'comma', // IntelliSense suggests: comma | semicolon | vertical_bar | tabulation
    quote: true,
  },
});

🔄 Advanced Control

For fine-grained control over the conversion process:

// Step 1: Upload file
const fileId = await client.files.upload('./data.xml');

// Step 2: Create task
const task = await client.createTask({
  type: 'convert.xml_to_excel',
  options: {
    file_id: fileId,
  },
});

// Step 3: Wait for completion
await task.wait({
  onProgress: (status) => {
    console.log(`Status: ${status.status}, Progress: ${status.conversionProgress}%`);
  },
});

// Step 4: Download result
await task.downloadTo('./result.xlsx');

🧪 Sandbox Mode

Test your integration without consuming quota:

await client.convert({
  type: 'convert.json_to_excel',
  input: './test-data.json',
  options: {
    sandbox: true, // ✨ Doesn't count against quota
  },
});

🎨 Error Handling

Type-safe error handling:

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

try {
  await client.convert({ /* ... */ });
} catch (error) {
  if (error instanceof RateLimitError) {
    console.error('Quota exceeded:', error.limits);
    console.error('Upgrade at: https://conversiontools.io/api-pricing');
  } else if (error instanceof ValidationError) {
    console.error('Invalid input:', error.message);
  } else if (error instanceof ConversionError) {
    console.error('Conversion failed:', error.message);
  } else if (error instanceof FileNotFoundError) {
    console.error('File not found:', error.message);
  }
}

API Reference