Skip to main content

JavaScript / TypeScript SDK

The official TurboDocx Deliverable SDK for JavaScript and TypeScript applications. Generate documents from templates with dynamic variable injection, download source files and PDFs, and manage deliverables programmatically. Available on npm as @turbodocx/sdk.

Installation​

npm install @turbodocx/sdk

Requirements​

  • Node.js 18+ or modern browser
  • TypeScript 4.7+ (optional, for type checking)

Configuration​

const { Deliverable } = require("@turbodocx/sdk");

// Configure globally (recommended for server-side)
Deliverable.configure({
  apiKey: process.env.TURBODOCX_API_KEY, // Required: Your TurboDocx API key
  orgId: process.env.TURBODOCX_ORG_ID, // Required: Your organization ID
  // Optional: override base URL for testing
  // baseUrl: 'https://api.turbodocx.com'
});
No Sender Email Required

Unlike TurboSign, the Deliverable module only requires apiKey and orgId — no sender email or name is needed.

Environment Variables​

# .env
TURBODOCX_API_KEY=your_api_key_here
TURBODOCX_ORG_ID=your_org_id_here

Quick Start​

Generate a document from a template​

const { Deliverable } = require("@turbodocx/sdk");

Deliverable.configure({
  apiKey: process.env.TURBODOCX_API_KEY,
  orgId: process.env.TURBODOCX_ORG_ID,
});

// Generate a document from a template with variables
const result = await Deliverable.generateDeliverable({
  name: "Q1 Report",
  templateId: "your-template-id",
  variables: [
    { placeholder: "{CompanyName}", text: "Acme Corporation", mimeType: "text" },
    { placeholder: "{Date}", text: "2026-03-12", mimeType: "text" },
  ],
  description: "Quarterly business report",
  tags: ["reports", "quarterly"],
});

console.log(JSON.stringify(result, null, 2));

Download and manage deliverables​

const { Deliverable } = require("@turbodocx/sdk");
const { writeFileSync } = require("fs");

// List deliverables with pagination
const list = await Deliverable.listDeliverables({ limit: 10, showTags: true });
console.log(`Total: ${list.totalRecords}`);

// Get deliverable details
const details = await Deliverable.getDeliverableDetails("deliverable-uuid");
console.log(`Name: ${details.name}`);

// Download source file (DOCX/PPTX)
const buffer = await Deliverable.downloadSourceFile("deliverable-uuid");
writeFileSync("report.docx", Buffer.from(buffer));

// Download PDF
const pdfBuffer = await Deliverable.downloadPDF("deliverable-uuid");
writeFileSync("report.pdf", Buffer.from(pdfBuffer));

// Update deliverable
await Deliverable.updateDeliverableInfo("deliverable-uuid", {
  name: "Q1 Report - Final",
  description: "Final quarterly business report",
});

// Delete deliverable
await Deliverable.deleteDeliverable("deliverable-uuid");

Variable Types​

The Deliverable module supports four variable types for template injection:

1. Text Variables​

Inject plain text values into template placeholders:

const variables = [
  { placeholder: "{CompanyName}", text: "Acme Corporation", mimeType: "text" },
  { placeholder: "{Date}", text: "2026-03-12", mimeType: "text" },
];

2. HTML Variables​

Inject rich HTML content with formatting:

const variables = [
  {
    placeholder: "{Summary}",
    text: "<p>This is a <strong>formatted</strong> summary with <em>rich text</em>.</p>",
    mimeType: "html",
  },
];

3. Image Variables​

Inject images by providing a URL or base64-encoded content:

const variables = [
  {
    placeholder: "{Logo}",
    text: "https://example.com/logo.png",
    mimeType: "image",
  },
];

4. Markdown Variables​

Inject markdown content that gets converted to formatted text:

const variables = [
  {
    placeholder: "{Notes}",
    text: "## Key Points\n- First item\n- Second item\n\n**Important:** Review before submission.",
    mimeType: "markdown",
  },
];
Variable Stack

For repeating content (e.g., table rows), use variableStack instead of text to provide multiple values for the same placeholder. See the Types section for details.

API Reference​

Configure​

Configure the SDK with your API credentials and organization settings.

Example:

const { Deliverable } = require("@turbodocx/sdk");

Deliverable.configure({
  apiKey: process.env.TURBODOCX_API_KEY,
  orgId: process.env.TURBODOCX_ORG_ID,
  // Optional: override for testing
  // baseUrl: 'https://api.turbodocx.com'
});
API Credentials Required

Both apiKey and orgId parameters are required for all API requests. To get your credentials, follow the Get Your Credentials steps from the SDKs main page.

Generate deliverable​

Generate a new document from a template with variable substitution.

const result = await Deliverable.generateDeliverable({
  name: "Q1 Report",
  templateId: "your-template-id",
  variables: [
    { placeholder: "{CompanyName}", text: "Acme Corp", mimeType: "text" },
    { placeholder: "{Date}", text: "2026-03-12", mimeType: "text" },
  ],
  description: "Quarterly business report",
  tags: ["reports", "quarterly"],
});

console.log(JSON.stringify(result, null, 2));

List deliverables​

List deliverables with pagination, search, and filtering.

const list = await Deliverable.listDeliverables({
  limit: 10,
  offset: 0,
  query: "report",
  showTags: true,
});

console.log(JSON.stringify(list, null, 2));

Get deliverable details​

Retrieve the full details of a single deliverable, including variables and fonts.

const details = await Deliverable.getDeliverableDetails("deliverable-uuid", {
  showTags: true,
});

console.log(JSON.stringify(details, null, 2));

Update deliverable info​

Update a deliverable's name, description, or tags.

const result = await Deliverable.updateDeliverableInfo("deliverable-uuid", {
  name: "Q1 Report - Final",
  description: "Final quarterly business report",
  tags: ["reports", "final"],
});

console.log(JSON.stringify(result, null, 2));

Delete deliverable​

Soft-delete a deliverable.

const result = await Deliverable.deleteDeliverable("deliverable-uuid");

console.log(JSON.stringify(result, null, 2));

Download source file​

Download the original source file (DOCX or PPTX).

const buffer = await Deliverable.downloadSourceFile("deliverable-uuid");

// Node.js: Save to file
const { writeFileSync } = require("fs");
writeFileSync("report.docx", Buffer.from(buffer));

Download PDF​

Download the PDF version of a deliverable.

const buffer = await Deliverable.downloadPDF("deliverable-uuid");

// Node.js: Save to file
const { writeFileSync } = require("fs");
writeFileSync("report.pdf", Buffer.from(buffer));

Error Handling​

The SDK provides typed error classes for different failure scenarios. All errors extend the base TurboDocxError class.

Error Classes​

Error ClassStatus CodeCodeDescription
TurboDocxErrorvariesvariesBase error class for all SDK errors
AuthenticationError401AUTHENTICATION_ERRORInvalid or missing API credentials
ValidationError400VALIDATION_ERRORInvalid request parameters
NotFoundError404NOT_FOUNDDeliverable or template not found
RateLimitError429RATE_LIMIT_EXCEEDEDToo many requests
NetworkError-NETWORK_ERRORNetwork connectivity issues

Handling Errors​

const {
  Deliverable,
  TurboDocxError,
  AuthenticationError,
  ValidationError,
  NotFoundError,
  RateLimitError,
  NetworkError,
} = require("@turbodocx/sdk");

try {
  const result = await Deliverable.generateDeliverable({
    name: "Q1 Report",
    templateId: "your-template-id",
    variables: [
      { placeholder: "{CompanyName}", text: "Acme Corp", mimeType: "text" },
    ],
  });
} catch (error) {
  if (error instanceof AuthenticationError) {
    console.error("Authentication failed:", error.message);
    // Check your API key and org ID
  } else if (error instanceof ValidationError) {
    console.error("Validation error:", error.message);
    // Check request parameters
  } else if (error instanceof NotFoundError) {
    console.error("Resource not found:", error.message);
    // Template or deliverable doesn't exist
  } else if (error instanceof RateLimitError) {
    console.error("Rate limited:", error.message);
    // Wait and retry
  } else if (error instanceof NetworkError) {
    console.error("Network error:", error.message);
    // Check connectivity
  } else if (error instanceof TurboDocxError) {
    console.error("SDK error:", error.message, error.statusCode, error.code);
  }
}

Error Properties​

All errors include these properties:

PropertyTypeDescription
messagestringHuman-readable error description
statusCodenumber \| undefinedHTTP status code (if applicable)
codestring \| undefinedMachine-readable error code

TypeScript Types​

The SDK exports TypeScript types for full type safety. Import them directly from the package.

Importing Types​

import type {
  // Variable types
  DeliverableVariable,
  VariableMimeType,
  // Request types
  DeliverableConfig,
  CreateDeliverableRequest,
  UpdateDeliverableRequest,
  ListDeliverablesOptions,
  // Response types
  CreateDeliverableResponse,
  UpdateDeliverableResponse,
  DeleteDeliverableResponse,
  DeliverableListResponse,
  // Record types
  DeliverableRecord,
  Tag,
  Font,
} from "@turbodocx/sdk";

VariableMimeType​

Union type for variable content types:

type VariableMimeType = "text" | "html" | "image" | "markdown";

DeliverableVariable​

Variable configuration for template injection:

PropertyTypeRequiredDescription
placeholderstringYesTemplate placeholder (e.g., {CompanyName})
textstringNo*Value to inject
mimeTypeVariableMimeTypeYes"text", "html", "image", or "markdown"
isDisabledbooleanNoSkip this variable during generation
subvariablesDeliverableVariable[]NoNested sub-variables for HTML content
variableStackobject \| arrayNoMultiple instances for repeating content
aiPromptstringNoAI prompt for content generation (max 16,000 chars)

*Required unless variableStack is provided or isDisabled is true.

CreateDeliverableRequest​

Request configuration for generateDeliverable:

PropertyTypeRequiredDescription
namestringYesDeliverable name (3-255 characters)
templateIdstringYesTemplate ID to generate from
variablesDeliverableVariable[]YesVariables for template substitution
descriptionstringNoDescription (up to 65,535 characters)
tagsstring[]NoTag strings to associate

UpdateDeliverableRequest​

Request configuration for updateDeliverableInfo:

PropertyTypeRequiredDescription
namestringNoUpdated name (3-255 characters)
descriptionstringNoUpdated description
tagsstring[]NoReplace all tags (empty array to remove)

ListDeliverablesOptions​

Options for listDeliverables:

PropertyTypeRequiredDescription
limitnumberNoResults per page (1-100, default 6)
offsetnumberNoResults to skip (default 0)
querystringNoSearch query to filter by name
showTagsbooleanNoInclude tags in the response

DeliverableRecord​

The deliverable object returned by listDeliverables:

PropertyTypeDescription
idstringUnique deliverable ID (UUID)
namestringDeliverable name
descriptionstringDescription text
templateIdstringSource template ID
createdBystringUser ID of the creator
emailstringCreator's email address
fileSizenumberFile size in bytes
fileTypestringMIME type of the generated file
defaultFontstringDefault font used
fontsFont[]Fonts used in the document
isActivebooleanWhether the deliverable is active
createdOnstringISO 8601 creation timestamp
updatedOnstringISO 8601 last update timestamp
tagsTag[]Associated tags (when showTags=true)

DeliverableDetailRecord​

The deliverable object returned by getDeliverableDetails. Includes all fields from DeliverableRecord except fileSize, plus:

PropertyTypeDescription
templateNamestringSource template name
templateNotDeletedbooleanWhether the source template still exists
variablesDeliverableVariable[]Parsed variable objects with values

Tag​

Tag object included when showTags is enabled:

PropertyTypeDescription
idstringTag unique identifier (UUID)
labelstringTag display name
isActivebooleanWhether the tag is active
updatedOnstringISO 8601 last update timestamp
createdOnstringISO 8601 creation timestamp
createdBystringUser ID of the tag creator
orgIdstringOrganization ID

Additional Documentation​

For detailed information about advanced configuration and API concepts, see:

Core API References​

Resources​