🟩Node SDK

Official JavaScript/TypeScript SDK for the Docs-Dispatcher API. Build document generation, email dispatch, SMS, invoicing, and e-signature workflows with full type safety and modern async/await patterns.

Features

• 📧 Email Dispatch - Send templated emails with attachments

• 📄 File Generation - Generate PDFs, DOCX, XLSX, and more from templates

• 📱 SMS Dispatch - Send SMS messages via multiple providers

• 📮 Postal Dispatch - Send physical mail

• ✍️ E-Signature - Electronic signature workflows (simple, advanced, qualified)

• 🧾 Invoice Generation - Create invoices, quotes, and credit notes (v0.7.0+)

• 🔐 JWT Authentication - Modern Bearer token auth (v0.7.0+)

• 📦 Upload & Targets - Upload to Zoho CRM and other platforms

• 🎯 TypeScript - Full type safety with IntelliSense support

• ✅ Client-side Validation - Catch errors before API calls

Requirements

• Node.js: ^22.0.0 (LTS recommended)

• Package Manager: Yarn 4.8+ or npm 8+

Installation

Using Yarn (Recommended)

yarn add docs-dispatcher-sdk

Using npm

npm install docs-dispatcher-sdk

Quick Start

Basic Authentication

The simplest way to get started is with username/password authentication:

import DocsDispatcher from 'docs-dispatcher-sdk'

// Simple setup with username/password
const dd = DocsDispatcher.create({
  username: 'your-username',
  password: 'your-password'
})

// Check API health
await dd.healthCheck()

Bearer Token Authentication (Recommended)

For production applications, use JWT Bearer tokens:

import DocsDispatcher, { BearerAuth } from 'docs-dispatcher-sdk'
import axios from 'axios'

const auth = new BearerAuth('your-jwt-token')
const http = new DocsDispatcher.Http.AxiosAdapter(axios)
const dd = new DocsDispatcher(auth, http)

Get Your API Token: Log in to the Docs-Dispatcher dashboard and navigate to Settings → API Tokens to generate a new token.

Service Examples

Email Dispatch

Send templated emails with dynamic data:

import { MailDispatcher } from 'docs-dispatcher-sdk'

const email = new DocsDispatcher.Service.MailDispatcher({
  from: '[email protected]',
  to: ['[email protected]'],
  subject: 'Hello from DocsDispatcher',
  templateName: 'welcome-email',
  data: {
    username: 'John Doe',
    activationLink: 'https://example.com/activate'
  }
})

await dd.withBaseService(email).dispatch()

Common Use Cases:

• Welcome emails

• Password reset notifications

• Order confirmations

• Invoice delivery

File Generation

Generate documents from templates in various formats:

const file = new DocsDispatcher.Service.FileDispatcher()
  .setTemplateName('contract-template')
  .setResultFileName('contract-signed.pdf')
  .setData({
    clientName: 'John Doe',
    contractDate: '2025-01-15',
    amount: '$10,000'
  })
  .setResultFormat(DocsDispatcher.RETURN_FORMATS.PDF)

const response = await dd.withBaseService(file).dispatch()

Supported Formats:

• PDF

• DOCX (Microsoft Word)

• XLSX (Microsoft Excel)

• HTML

• PNG/JPG/SVG images

See Template Management for template creation.

SMS Dispatch

Send SMS messages via configured providers:

const sms = new DocsDispatcher.Service.SMSDispatcher({
  to: '[phone]',
  smsContent: 'Your verification code is: 123456',
  provider: 'SMS_FACTOR'
})

await dd.withBaseService(sms).dispatch()

Supported Providers:

• SMS Factor

• Twilio

• AWS SNS

• Others (see SMS Providers)

Invoice Generation

Create invoices, quotes, or credit notes with full customization:

import {
  InvoiceDocumentType,
  CustomerType,
  DiscountType
} from 'docs-dispatcher-sdk'

// Build customer using builder pattern
const customer = new DocsDispatcher.Builder.InvoiceCustomerBuilder()
  .asCompany('Acme Corporation')
  .withEmail('[email protected]')
  .withBillingAddress({
    street1: '123 Business Ave',
    city: 'New York',
    zipCode: '10001',
    country: 'US'
  })
  .withVatNumber('US123456789')
  .build()

// Build invoice items
const items = [
  new DocsDispatcher.Builder.InvoiceItemBuilder('Consulting Services', 150.00)
    .withQuantity(10)
    .withTaxPercent(20)
    .withDiscount(DiscountType.PERCENTAGE, 10, '10% volume discount')
    .build(),
  new DocsDispatcher.Builder.InvoiceItemBuilder('Support Plan', 500.00)
    .withTaxPercent(20)
    .build()
]

// Create invoice
const invoice = new DocsDispatcher.Service.InvoiceDispatcher({
  customer,
  items,
  documentType: InvoiceDocumentType.INVOICE,
  issueDate: '2025-01-15',
  provider: 'ipaidthat', // or 'qonto', 'stripe'
  sendByEmail: true,
  paymentTerms: 30,
  notes: 'Thank you for your business!',
  discount: {
    type: DiscountType.ABSOLUTE,
    value: 50,
    description: 'Early payment discount'
  }
})

// Set result format to PDF
invoice.setResultFormat(DocsDispatcher.RETURN_FORMATS.PDF)

// Dispatch invoice
const response = await dd.withBaseService(invoice).dispatch()

Invoice Providers:

• iPaidThat: French invoicing platform

• Qonto: European business banking

• Stripe: Payment processing with invoicing

See Invoice Providers for configuration details.

E-Signature Workflows

Request electronic signatures with configurable signature types:

const esign = new DocsDispatcher.Service.ESignDispatcher({
  documentName: 'Service Agreement',
  signatureType: 'ADVANCED', // or 'SIMPLE', 'QUALIFIED'
  signers: [
    {
      firstname: 'John',
      lastname: 'Doe',
      email: '[email protected]',
      phoneNumber: '[phone]'
    }
  ]
})
  .setTemplateName('agreement-template')
  .setData({ agreementDate: '2025-01-15' })

await dd.withBaseService(esign).dispatch()

Signature Types:

• SIMPLE: Basic electronic signature

• ADVANCED: Identity-verified signature

• QUALIFIED: Legally binding qualified signature (eIDAS compliant)

See E-Signature Providers for provider configuration.

Upload to CRM Targets

Upload generated documents to external platforms:

import { TargetTypes } from 'docs-dispatcher-sdk'

const file = new DocsDispatcher.Service.FileDispatcher()
  .setTemplateName('report-template')
  .setData({ reportMonth: 'January' })
  .addTarget({
    id: 'crm-contact-id',
    type: 'contact',
    target: TargetTypes.ZohoCrm
  })

await dd.withBaseService(file).dispatch()

Supported Targets:

• Zoho CRM

• Universal targets (configurable endpoints)

Advanced Features

Customer Types

The SDK supports three customer types for invoicing:

Individual Customer

For B2C transactions with consumers:

const individual = new DocsDispatcher.Builder.InvoiceCustomerBuilder()
  .asIndividual('John', 'Doe')
  .withEmail('[email protected]')
  .withBillingAddress({
    street1: '456 Main St',
    city: 'Paris',
    zipCode: '75001',
    country: 'FR'
  })
  .withDisplayName('John Doe')
  .build()

Company Customer

For B2B transactions with businesses:

const company = new DocsDispatcher.Builder.InvoiceCustomerBuilder()
  .asCompany('Tech Solutions Inc')
  .withEmail('[email protected]')
  .withRegistrationNumber('123456789')
  .withVatNumber('US123456789')
  .withBillingAddress({
    street1: '789 Corporate Blvd',
    city: 'San Francisco',
    zipCode: '94102',
    country: 'US'
  })
  .build()

Freelance Customer

For transactions with freelancers/self-employed:

const freelance = new DocsDispatcher.Builder.InvoiceCustomerBuilder()
  .asFreelance('Jane', 'Smith')
  .withEmail('[email protected]')
  .withBusinessName('Jane Smith Consulting')
  .withRegistrationNumber('987654321')
  .withVatNumber('FR987654321')
  .withBillingAddress({
    street1: '321 Freelance Ave',
    city: 'Lyon',
    zipCode: '69001',
    country: 'FR'
  })
  .build()

Document Types

Choose the appropriate document type for your use case:

import { InvoiceDocumentType } from 'docs-dispatcher-sdk'

// Standard invoice
documentType: InvoiceDocumentType.INVOICE

// Electronic invoice (e-facture, for French businesses)
documentType: InvoiceDocumentType.E_INVOICE

// Quote/Estimate
documentType: InvoiceDocumentType.QUOTE

// Credit note
documentType: InvoiceDocumentType.CREDIT

Validation

The SDK includes built-in client-side validation to catch errors before making API calls:

const errors: ValidationError[] = []
const isValid = invoice.validate(errors)

if (!isValid) {
  console.error('Validation errors:', errors)
  // Output:
  // [
  //   { path: ['customer', 'email'], message: 'Customer email is required' },
  //   { path: ['items'], message: 'At least one item is required' }
  // ]
}

Benefits:

• Faster feedback (no network round-trip)

• Detailed error paths

• Type-safe error handling

• Reduced API quota usage

Service Composition

Chain multiple services in a single API call:

// Generate document, send via email, and upload to CRM
const file = new DocsDispatcher.Service.FileDispatcher()
  .setTemplateName('proposal-template')
  .setData({ proposalId: 'PROP-2025-001' })

const email = new DocsDispatcher.Service.MailDispatcher({
  from: '[email protected]',
  to: ['[email protected]'],
  subject: 'Your Proposal'
})

const upload = new DocsDispatcher.Service.UploadDispatcher({
  target: TargetTypes.ZohoCrm,
  targetId: 'contact-123'
})

await dd
  .withBaseService(file)
  .withComposableService(email)
  .withComposableService(upload)
  .dispatch()

TypeScript Support

The SDK is written in TypeScript and provides full type definitions:

import DocsDispatcher, {
  MailDispatcher,
  FileDispatcher,
  InvoiceDispatcher,
  InvoiceDocumentType,
  CustomerType,
  DiscountType,
  ValidationError
} from 'docs-dispatcher-sdk'

// Full IntelliSense and autocomplete
const invoice: InvoiceDispatcher = new DocsDispatcher.Service.InvoiceDispatcher({
  // Type-safe properties
})

// Type-safe return values
const response: ApiResponse = await dd.withBaseService(invoice).dispatch()

Return Formats

Specify how you want the API to return generated documents:

// Available formats
DocsDispatcher.RETURN_FORMATS.PDF
DocsDispatcher.RETURN_FORMATS.DOCX
DocsDispatcher.RETURN_FORMATS.XLSX
DocsDispatcher.RETURN_FORMATS.HTML
DocsDispatcher.RETURN_FORMATS.PNG
DocsDispatcher.RETURN_FORMATS.JPG
DocsDispatcher.RETURN_FORMATS.SVG

// Usage
file.setResultFormat(DocsDispatcher.RETURN_FORMATS.PDF)

The actual available formats depend on your template's rendering engine. See Template Engines for details.

Error Handling

The SDK throws structured errors for different failure scenarios:

try {
  await dd.withBaseService(invoice).dispatch()
} catch (error) {
  if (error.code === 401) {
    console.error('Authentication failed: Invalid token')
  } else if (error.code === 400) {
    console.error('Validation error:', error.message)
  } else if (error.code === 404) {
    console.error('Template not found')
  } else {
    console.error('Unexpected error:', error)
  }
}

See Troubleshooting for common errors and solutions.

API Compatibility

SDK Version	API Version	Features
v0.7.0+	v3.6.2+	Bearer Auth, Invoice Dispatcher, Universal Targets
v0.6.x	v3.6.1	Partial support, BasicAuth
v0.5.x	v3.5.x	BasicAuth only, no InvoiceDispatcher

Upgrade Recommendation: If you're using API v3.5.x or earlier, consider upgrading to v3.6.2+ to access the full feature set including Bearer Auth and Invoice Dispatcher.

Documentation

• Online API Documentation: https://docs-dispatcher-io.gitlab.io/docs-dispatcher-clients/docsdispatcher-js-client/doc/

• API Specification: https://api.docs-dispatcher.io/docs

• Swagger UI: https://api.docs-dispatcher.io/docs/swagger

• CHANGELOG: View on GitLab

Repository

• GitLab: https://gitlab.com/docs-dispatcher-io/docs-dispatcher-clients/docsdispatcher-js-client

• Pipeline:

• Coverage:

Contributing

To contribute or run tests locally:

1. Clone the repository

2. Copy .env.dist to .env and configure credentials

3. Run yarn install

4. Run yarn test

Publishing New Versions

For maintainers:

yarn version --new-version x.y.z
# Rebase main on this tag
# Trigger pipeline on main

Next Steps

Learn from Examples	Recipes & Use Cases
Configure Providers	Service Providers
Troubleshoot Issues	SDK Troubleshooting
Manage Templates	Template Management

Support

• Issues: GitLab Issues

• Email: [email protected]

• Documentation: https://docs-dispatcher.io/docs