placedocuments

PlaceDocuments

Lightweight helper around the DocuSign eSignature API that creates and sends an envelope from an array of document objects. It handles JWT authentication via the DocuSign SDK and returns the created envelopeId.

What It Does

• Accepts an array of documents (base64 content plus metadata).
• Builds a DocuSign EnvelopeDefinition and sends it using JWT auth.
• Returns { envelopeId } when the envelope is successfully created.

Exported API

• sendDeclaration(documents: DeclarationDocument[], options: SendDeclarationOptions): Promise<{ envelopeId: string }>
  • Required options.recipients: { signerEmail, signerName, ccEmail, ccName }
  • Optional options.status: 'created' | 'sent' (defaults to 'created')
  • Optional options.tabs: anchor-based or coordinate-based placement. For anchors, set anchorString and offsets; for explicit coordinates, set xPosition, yPosition, and optional pageNumber.

Document Shape

Each document you pass must include these fields:

• documentBase64 — Base64-encoded file contents
• name — Filename to show in DocuSign
• fileExtension — e.g., pdf, docx
• documentId — String identifier unique within the envelope (e.g., "1", "2")

TypeScript interface used by the entry point:

export interface DeclarationDocument {
  documentBase64: string;
  name: string;
  fileExtension: string;
  documentId: string;
}

Install

npm install placedocuments

Build (if working from source):

npm run build

Quick Start

import { sendDeclaration } from 'placedocuments';

const docs = [
  {
    documentBase64: 'BASE64_PDF_HERE',
    name: 'My Document.pdf',
    fileExtension: 'pdf',
    documentId: '1',
  },
];

const result = await sendDeclaration(docs, {
  recipients: {
    signerEmail: '[e-mail]',
    signerName: 'Signer Name',
    ccEmail: '[e-mail]',
    ccName: 'CC Name',
  },
});
console.log(result.envelopeId);

With recipients and explicit tab coordinates:

const result = await sendDeclaration(docs, {
  recipients: {
    signerEmail: '[e-mail]',
    signerName: 'Signer Name',
    ccEmail: '[e-mail]',
    ccName: 'CC Name',
  },
  status: 'sent',
  tabs: { xPosition: 100, yPosition: 150, pageNumber: 1 },
});

Configuration

The library uses DocuSign JWT auth. By default, src/config.js reads some values from environment variables and falls back to config/appSettings.json (and a private key file path). You should prefer environment variables and avoid keeping real secrets in the repo.

Environment variables (template in .env.example):

• DS_CLIENT_ID — DocuSign Integration Key (GUID)
• DS_IMPERSONATED_USER_GUID — GUID of the user being impersonated
• DS_PRIVATE_KEY_PATH — Filesystem path to your RSA private key (PEM)
• DS_JWT_CLIENT_ID — Optional; often the same as DS_CLIENT_ID
• DS_SIGNER_EMAIL, DS_SIGNER_NAME, DS_CC_EMAIL, DS_CC_NAME — Optional recipient defaults (not recommended to hard-code)

Notes:

• This library does not load .env automatically; set env vars in your process or have your app load them (e.g., dotenv) before using this package.
• Do not commit secrets (private keys, client IDs tied to real accounts) to version control. Rotate any secrets already committed.
• Recipients are required and provided via options.recipients. Tab placement is optional and controlled via options.tabs (anchor-based by default, or explicit coordinates).

Testing

• Unit tests: The sendDeclaration test mocks the envelope generator and does not hit the live DocuSign API.
• Integration: If you want a live call, write an integration test that imports sendDeclaration and provides valid recipients and documents, and ensure your DocuSign JWT credentials are configured as described in Configuration.

Caveats

• Tab placement in the current implementation uses the anchor string **signature_1**. If your documents don’t include this anchor, the signature field may not appear where expected.
• Error handling and logging in the base implementation are minimal and may need to be hardened for production use (avoid logging base64 document contents or PII).

Changes in this version:

• Removed hard-coded recipients; callers must pass recipients via options.
• Safer logging: prints document count and IDs only, never base64 bodies.
• Throws on envelope creation failures instead of continuing with undefined results.

License

ISC