Nutrient DWS TypeScript Client


A Node.js TypeScript client library for Nutrient Document Web Services (DWS) API. This library provides a type-safe and ergonomic interface for document processing operations including conversion, merging, compression, watermarking, and text extraction.

> Note: This package is published as @nutrient-sdk/dws-client-typescript on NPM. The package provides full TypeScript support and is designed specifically for Node.js environments.

Features

- 📄 Powerful document processing: Convert, OCR, edit, compress, watermark, redact, and digitally sign documents
- 🤖 LLM friendly: Built-in support for popular Coding Agents (Claude Code, GitHub Copilot, JetBrains Junie, Cursor, Windsurf) and documentation on Context7
- 🔄 100% mapping with DWS Processor API: Complete coverage of all Nutrient DWS Processor API capabilities
- 🛠️ Convenient functions with sane defaults: Simple interfaces for common operations with smart default settings
- ⛓️ Chainable operations: Build complex document workflows with intuitive method chaining
- 🔐 Flexible authentication and security: Support for API keys and async token providers with secure handling
- ✅ Highly tested: Comprehensive test suite ensuring reliability and stability
- 🔒 Type-safe: Full TypeScript support with comprehensive type definitions
- 📦 Multiple module formats: ESM and CommonJS builds

Installation

``bash
npm install @nutrient-sdk/dws-client-typescript
`

or

`bash
yarn add @nutrient-sdk/dws-client-typescript
`

Migration Guides

- v2.0.0: See docs/MIGRATION.md for URL input changes and sign() restrictions.

Integration with Coding Agents

This package has built-in support with popular coding agents like Claude Code, GitHub Copilot, Cursor, and Windsurf by exposing scripts that will inject rules instructing the coding agents on how to use the package. This ensures that the coding agent doesn't hallucinate documentation, as well as making full use of all the features offered in Nutrient DWS TypeScript Client.

`bash


Adding code rule to Claude Code

npx dws-add-claude-code-rule

Adding code rule to GitHub Copilot

npx dws-add-github-copilot-rule

Adding code rule to Junie (Jetbrains)

npx dws-add-junie-rule

Adding code rule to Cursor

npx dws-add-cursor-rule

Adding code rule to Windsurf

npx dws-add-windsurf-rule
`

The documentation for Nutrient DWS TypeScript Client is also available on Context7

Quick Start

`typescript
import { NutrientClient } from '@nutrient-sdk/dws-client-typescript';

const client = new NutrientClient({
apiKey: 'nutr_sk_your_secret_key'
});
`

$3

Most methods accept URLs directly. The URL is passed to the server, which fetches the content—this avoids SSRF vulnerabilities since the client never fetches URLs itself.

`typescript
// Pass URL as a string
const result = await client.convert('https://example.com/document.pdf', 'docx');

// Or as an object (useful for TypeScript type narrowing)
const result = await client.convert({ type: 'url', url: 'https://example.com/document.pdf' }, 'docx');

// URLs also work with the workflow builder
const result = await client.workflow()
.addFilePart('https://example.com/document.pdf')
.outputPdf()
.execute();
`

Exception: The sign() method only accepts local files (file paths, Buffers, streams) because the underlying API endpoint doesn't support URL inputs. For signing remote files, fetch the content first:

`typescript
// Fetch and pass the bytes for signing
const response = await fetch('https://example.com/document.pdf');
const buffer = Buffer.from(await response.arrayBuffer());
const result = await client.sign(buffer, { / signature options / });
`

Direct Methods

The client provides numerous methods for document processing:

`typescript
// Convert a document
const pdfResult = await client.convert('document.docx', 'pdf');

// Extract text
const textResult = await client.extractText('document.pdf');

// Add a watermark
const watermarkedDoc = await client.watermarkText('document.pdf', 'CONFIDENTIAL');

// Merge multiple documents
const mergedPdf = await client.merge(['doc1.pdf', 'doc2.pdf', 'doc3.pdf']);
`

For a complete list of available methods with examples, see the Methods Documentation.




Workflow System

The client also provide a fluent builder pattern with staged interfaces to create document processing workflows:

`typescript
const result = await client
.workflow()
.addFilePart('document.pdf')
.addFilePart('appendix.pdf')
.applyAction(BuildActions.watermarkText('CONFIDENTIAL', {
opacity: 0.5,
fontSize: 48
}))
.outputPdf({
optimize: {
mrcCompression: true,
imageOptimizationQuality: 2
}
})
.execute();
`

The workflow system follows a staged approach:
1. Add document parts (files, HTML, pages)
2. Apply actions (optional)
3. Set output format
4. Execute or perform a dry run

For detailed information about the workflow system, including examples and best practices, see the Workflow Documentation.

Error Handling

The library provides a comprehensive error hierarchy:

`typescript
import {
NutrientError,
ValidationError,
APIError,
AuthenticationError,
NetworkError
} from '@nutrient-sdk/dws-client-typescript';

try {
const result = await client.convert('file.docx', 'pdf');
} catch (error) {
if (error instanceof ValidationError) {
// Invalid input parameters
console.error('Invalid input:', error.message, error.details);
} else if (error instanceof AuthenticationError) {
// Authentication failed
console.error('Auth error:', error.message, error.statusCode);
} else if (error instanceof APIError) {
// API returned an error
console.error('API error:', error.message, error.statusCode, error.details);
} else if (error instanceof NetworkError) {
// Network request failed
console.error('Network error:', error.message, error.details);
}
}
`

Testing

The library includes comprehensive unit and integration tests:

`bash


Run all tests

npm test

Run with coverage report

npm test -- --coverage

Run only unit tests

npm run test:unit

Run integration tests (requires API key)

NUTRIENT_API_KEY=your_key npm run test:integration
`

The library maintains high test coverage across all API methods, including:
- Unit tests for all public methods
- Integration tests for real API interactions

Contributing

We welcome contributions to improve the library! Please follow our development standards to ensure code quality and maintainability.

Quick start for contributors:

1. Clone and setup the repository
2. Make changes following atomic commit practices
3. Use conventional commits for clear change history
4. Include appropriate tests for new features

For detailed contribution guidelines, see the Contributing Guide.

Project Structure

`
src/
├── __tests__/ # Test files
├── builders/ # Builder classes
├── generated/ # Generated code
├── types/ # TypeScript interfaces and types
├── build.ts # Build utilities
├── client.ts # Main NutrientClient class
├── errors.ts # Error classes
├── http.ts # HTTP layer
├── inputs.ts # Input handling
├── workflow.ts # WorkflowBuilder class
└── index.ts # Public exports
``

CI/CD

This project uses GitHub Actions for continuous integration and deployment:

- CI: Runs linting, type checking, and tests on every push and PR
- Integration Tests: Tests against the real Nutrient API
- Scheduled Integration Tests: Daily API compatibility check
- Security: Automated security scanning

For security reasons, API keys are stored as GitHub Secrets and Integration tests only run on trusted sources.

License

This project is licensed under the MIT License - see the LICENSE file for details.

Support

For issues and feature requests, please use the GitHub issue tracker.

For questions about the Nutrient DWS Processor API, refer to the official documentation.