5.0.0

[leonatherton]

5.0.0 Modernization

Major Improvements

1. ✅ ES Modules

• Changed from CommonJS (require) to ES modules (import/export)
• Added "type": "module" to package.json
• Proper exports field for better module resolution

2. ✅ Async/Await API

• Replaced callbacks with clean async/await
• Returns proper promises
• Much easier error handling

3. ✅ Callback-Based Progress Tracking

• Clean progress tracking with optional callback parameter

4. ✅ Proper Error Classes

• ConversionError - For conversion failures
• ConversionTimeoutError - For timeouts
• AuthenticationError - For auth failures
• Better error handling and debugging

5. ✅ Class-Based API

• IDRCloudClient class - Main client with clean, promise-based methods

6. ✅ Streaming with openAsBlob()

• Uses Node.js 20+ fs.openAsBlob() for efficient file streaming
• No event loop blocking
• Efficient for large files

7. ✅ Zero Dependencies

• Removed form-data dependency
• Uses native fetch API
• Uses native FormData
• Smaller package size

8. ✅ Better Retry Logic

• Exponential backoff on errors
• Configurable max retries

9. ✅ Modern Code

• Cleaner, more maintainable code
• Better separation of concerns
• JSDoc documentation for IDE support

API Comparison

Old Way (v4.x):

const Converter = require('@idrsolutions/idrcloudclient');

Converter.convert({
    endpoint: 'https://cloud.idrsolutions.com/buildvu',
    parameters: {
        input: Converter.UPLOAD,
        file: './example.pdf'
    },
    username: 'user',
    password: 'pass',
    success: (data) => {
        console.log('Success!', data);
    },
    failure: (error) => {
        console.error('Error:', error);
    },
    progress: (data) => {
        console.log('Progress:', data);
    }
});

New Way (v5.0):

import IDRCloudClient, { INPUT } from '@idrsolutions/idrcloudclient';

const client = new IDRCloudClient('https://cloud.idrsolutions.com/buildvu', {
    username: 'user',
    password: 'pass'
});

try {
    const result = await client.convert({
        input: INPUT.UPLOAD,
        file: './example.pdf'
    });
    console.log('Success!', result);
} catch (error) {
    console.error('Error:', error);
}

With Progress (v5.0):

const result = await client.convert(
    {
        input: INPUT.UPLOAD,
        file: './example.pdf'
    },
    {
        onProgress: (progress) => {
            console.log('Progress:', progress.state);
        }
    }
);

Files Created/Modified

Modified:

• ✅ idrcloudclient.js - Completely rewritten with modern API
• ✅ package.json - Updated to v5.0.0, ES modules, Node.js 20+

New Files:

• ✅ examples.js - 11 complete usage examples
• ✅ examples-browser.html - Browser usage examples with File API
• ✅ MIGRATION.md - Comprehensive migration guide
• ✅ BROWSER_SUPPORT.md - Browser-specific guidance and security notes
• ✅ MODERNIZATION_SUMMARY.md - This file documenting the v5.0 changes

Benefits Summary

Feature	Old (v4.x)	New (v5.0)
Module System	CommonJS	ES Modules ✅
API Style	Callbacks	Async/Await ✅
Dependencies	1 (form-data)	0 ✅
Error Handling	Generic errors	Custom error classes ✅
Progress Tracking	Callback in params	Optional callback parameter ✅
File Handling	readFileSync	openAsBlob (streaming) ✅
Retry Logic	Basic	Exponential backoff ✅
Code Structure	IIFE	Classes ✅
Browser Support	❌	Full support ✅

Key Features

Token Authentication for IDR Cloud

The v5.0 API supports both token-based authentication (for IDR cloud) and username/password authentication (for self-hosted servers):

// IDR Cloud (token)
const client = new IDRCloudClient('https://cloud.idrsolutions.com/cloud/buildvu', {
    token: 'your-api-token'
});

// Self-hosted (username/password)
const client = new IDRCloudClient('http://localhost:8080/buildvu', {
    username: 'user',
    password: 'pass'
});

Universal JavaScript Support

The same library works in both Node.js and browsers with zero modifications. The code automatically detects the environment and adapts accordingly:

• Node.js: Supports file paths (streamed via fs.openAsBlob()), Buffers, and Blobs
• Browser: Supports File objects and Blobs

Fire-and-Forget Pattern

The v5.0 API supports non-polling mode for async processing:

// Return immediately, server notifies webhook when done
const response = await client.convert(
    {
        input: INPUT.UPLOAD,
        file: './document.pdf',
        callbackUrl: 'https://example.com/webhook'
    },
    { poll: false }
);
console.log('Started:', response.uuid);

Notes

• The API is now promise-based and works seamlessly with async/await and try/catch
• File streaming via fs.openAsBlob() is memory-efficient for large PDFs in Node.js
• Browser support is full-featured with File API integration
• All 11 examples in examples.js demonstrate different usage patterns and features

[JacobIDR]

Just double checking, I thought FormData wasn't native on NodeJS and required the library, is this not the case anymore?

[leonatherton]

Just double checking, I thought FormData wasn't native on NodeJS and required the library, is this not the case anymore?

It was added at the same time as the fetch API https://nodejs.org/api/globals.html#class-formdata

[daniel-warren]

I don't see an option 2, so would suggest changing to:

Suggested change

	// Option 1: Using fs.createReadStream (Node.js)
	// Using fs.createReadStream (Node.js)