← Back to eSignature Overview

@memberjunction/esignature

The core primitive of the MemberJunction eSignature subsystem. This package defines the provider-agnostic contract every signing vendor implements, the normalized types that describe an envelope's lifecycle, and the engines that orchestrate sending, status tracking, document persistence, and auditing.

Provider driver packages (DocuSign, PandaDoc, Dropbox Sign) depend on this package; they implement its contract. Your application depends on this package's engine; it never talks to a vendor directly.

npm install @memberjunction/esignature
Copy

Two entry points

This package ships two importable surfaces, deliberately separated so client bundles stay free of server-only dependencies:

graph TB
    subgraph root["@memberjunction/esignature  (browser-safe)"]
        Types["types
normalized contracts"]
        BSP["BaseSignatureProvider
the driver contract"]
        SEB["SignatureEngineBase
metadata cache"]
    end

    subgraph server["@memberjunction/esignature/server  (server-only)"]
        SE["SignatureEngine
lifecycle + persistence"]
        Util["driver init + credentials"]
        Art["artifact file-back"]
    end

    SE --> SEB
    SE --> BSP
    Util --> Cred["@memberjunction/credentials"]
    Art --> Storage["@memberjunction/storage"]

    style root fill:#2d8659,stroke:#1a5c3a,color:#fff
    style server fill:#8a5a2d,stroke:#5c3a1a,color:#fff
    style Cred fill:#444,stroke:#222,color:#fff
    style Storage fill:#444,stroke:#222,color:#fff
Copy

Why the split? The server engine decrypts credentials and writes to the database — it pulls in @memberjunction/credentials, which has no place in a browser bundle. The root entry gives UI code everything it needs (the contract, the types, and a read-only metadata cache) without that weight.

The provider contract: BaseSignatureProvider

Every signing vendor is wrapped in a driver that extends this abstract class and registers itself with the MJ class factory:

@RegisterClass(BaseSignatureProvider, 'DocuSign')
export class DocuSignSignatureProvider extends BaseSignatureProvider { … }
Copy

The engine never imports a driver by name — it resolves one at runtime from the ServerDriverKey on the provider record. Add a vendor by publishing a new driver package; the engine picks it up with zero changes.

Operations

classDiagram
    class BaseSignatureProvider {
        <>
        +initialize(config) Promise
        +IsConfigured bool
        +CreateEnvelope(req)* EnvelopeResult
        +GetEnvelopeStatus(id)* EnvelopeStatusResult
        +DownloadSignedDocument(id)* SignedDocumentResult
        +VoidEnvelope(id, reason)* OperationResult
        +CreateEmbeddedSigningUrl(req) SigningUrlResult
        +ApplyTemplate(req) EnvelopeResult
        +ResendNotification(id) OperationResult
        +ParseWebhookEvent(payload, headers) NormalizedSignatureEvent
        +VerifyWebhookSignature(body, headers) WebhookVerificationResult
        +getSupportedOperations()* SignatureOperation[]
        +supportsOperation(op) bool
    }
Copy

Optional operations have safe default implementations that return a clear "not supported" result — a driver only overrides what its vendor actually offers. Callers check supportsOperation(...) or getSupportedOperations() before relying on an optional feature.

Implementing a new provider? See Adding a provider below, and the existing drivers for reference: DocuSign · PandaDoc · Dropbox Sign.

Normalized types

The contract speaks one vocabulary regardless of vendor. The most important shapes:

Status

type EnvelopeStatus =
  | 'Draft' | 'Sent' | 'Delivered' | 'Signed'
  | 'Completed' | 'Declined' | 'Voided' | 'Unknown';
Copy

Each driver maps its vendor's native statuses onto this set, so application code branches on one stable enumeration.

Requests & results (abridged)

interface CreateEnvelopeRequest {
  title: string;
  message?: string;
  documents: SignatureDocumentInput[];   // { bytes, filename, contentType }
  recipients: SignatureRecipientInput[];  // { email, name?, routingOrder?, role? }
  sendImmediately?: boolean;
  metadata?: Record<string, unknown>;
}

interface EnvelopeResult {
  Success: boolean;
  externalEnvelopeId?: string;
  status?: EnvelopeStatus;
  signingUrl?: string;
  ErrorMessage?: string;
}

interface NormalizedSignatureEvent {
  externalEnvelopeId: string;
  status: EnvelopeStatus;
  occurredAt: string;   // ISO 8601 timestamp
  raw: unknown;
}
Copy

Results follow the MemberJunction convention of a Success boolean plus an optional ErrorMessage — never thrown exceptions for expected outcomes.

The engines

SignatureEngine — server-side orchestration

The heart of the subsystem. It resolves accounts to drivers, decrypts credentials, executes provider operations, and persists the entire lifecycle. Imported from the /server subpath:

import { SignatureEngine } from '@memberjunction/esignature/server';
Copy

flowchart TD
    Send["SendForSignature()"] --> Resolve["Resolve account → provider → driver"]
    Resolve --> Decrypt["Decrypt credentials
(Credential vault)"]
    Decrypt --> Init["driver.initialize(mergedConfig)"]
    Init --> Create["driver.CreateEnvelope()"]
    Create --> Persist["Create Request + Documents +
Recipients + Log rows"]
    Persist --> Return["Return result"]

    style Send fill:#2d8659,stroke:#1a5c3a,color:#fff
    style Decrypt fill:#8a5a2d,stroke:#5c3a1a,color:#fff
Copy

SignatureEngineBase — browser-safe metadata cache

A BaseEngine subclass (like FileStorageEngineBase) that caches the Providers and Accounts metadata for read-only use — perfect for populating a UI dropdown of available accounts. It does not decrypt credentials or touch a vendor.

import { SignatureEngineBase } from '@memberjunction/esignature';

await SignatureEngineBase.Instance.Config(false, contextUser);
const accounts = SignatureEngineBase.Instance.Accounts;
const account  = SignatureEngineBase.Instance.GetAccountByName('Production DocuSign');
Copy

Data model

Six entities back the subsystem. Field-level detail:

MJ: Signature Providers

Registry of provider types. Seeded via metadata (metadata/signature-providers/), not SQL.

MJ: Signature Accounts

A configured instance of a provider.

MJ: Signature Requests

The envelope. Links to an originating record via the polymorphic pair.

MJ: Signature Request Documents

MJ: Signature Request Recipients

MJ: Signature Request Logs

All six get the standard __mj_CreatedAt / __mj_UpdatedAt columns and full CRUD stored procedures from CodeGen.

Usage

Using the Actions (no-code)

The simplest path. Four Actions (in @memberjunction/core-actions) wrap the engine for AI agents and workflow builders — no TypeScript required:

Using the engine (server-side code)

import { SignatureEngine } from '@memberjunction/esignature/server';

// 1. Send — from raw bytes
const sent = await SignatureEngine.Instance.SendForSignature({
  signatureAccountId,
  title: 'Service Agreement',
  message: 'Please review and sign.',
  documents: [{ bytes: pdf, filename: 'agreement.pdf', contentType: 'application/pdf' }],
  recipients: [{ email: 'alice@acme.com', name: 'Alice Smith', routingOrder: 1 }],
  entityId, recordId,           // link to your domain record
  contextUser,                  // passed inside the options object
});

// 2. Check status later (these methods take contextUser as a positional argument)
const status = await SignatureEngine.Instance.RefreshStatus(sent.signatureRequestId, contextUser);

// 3. Download the signed copy (filed back to storage automatically)
const signed = await SignatureEngine.Instance.DownloadSigned(sent.signatureRequestId, contextUser);

// 4. Or cancel
await SignatureEngine.Instance.Void(sent.signatureRequestId, 'Superseded by amendment', contextUser);
Copy

Browser-safe metadata access

import { SignatureEngineBase } from '@memberjunction/esignature';

await SignatureEngineBase.Instance.Config(false, contextUser);
const options = SignatureEngineBase.Instance.AccountsWithProviders; // for a UI picker
Copy

Credential handling

Vendor secrets never live in code or config files — they're stored encrypted in the MJ Credential vault and resolved just in time.

sequenceDiagram
    participant Eng as SignatureEngine
    participant Acct as Signature Account
    participant Vault as Credential Vault
    participant Drv as Driver

    Eng->>Acct: Look up account
    Eng->>Vault: Decrypt CredentialID (subsystem "eSignature")
    Vault-->>Eng: { apiKey / oauth keys / tokens }
    Eng->>Eng: Merge provider defaults + account config + secrets
    Eng->>Drv: initialize(mergedConfig)
    Note over Drv,Vault: On OAuth token rotation,
driver calls onTokenRefresh →
engine persists new tokens to vault
Copy

Configuration is layered: provider-type defaults (non-secret) → per-account overrides → decrypted credential values (highest precedence). OAuth drivers can hand rotated tokens back to the engine via an onTokenRefresh callback, which persists them so the next call uses fresh tokens.

Inbound webhooks

Signing vendors push status changes to MemberJunction at POST /esignature/webhook/:driverKey. The endpoint (in MJ Server) is intentionally unauthenticated by MJ — trust comes from the provider's own signature, verified over the raw request bytes. The policy is verify-if-configured: a configured-but-invalid signature is logged and not applied; a missing secret is accepted with a warning.

flowchart TD
    In["POST /esignature/webhook/:driverKey"] --> Parse["Bare driver parses payload
(no credentials needed)"]
    Parse --> Find{"Owning Signature Request
found by envelope ID?"}
    Find -->|no| Accept202["202 — received, not actioned
(logged)"]
    Find -->|yes| Verify{"HMAC over raw bytes"}
    Verify -->|secret set & mismatch| Mismatch["202 — verification failed
logged, status NOT applied"]
    Verify -->|verified| Apply["200 — update status + log"]
    Verify -->|no secret configured| ApplyWarn["200 — apply + warn"]

    style Mismatch fill:#8a2d2d,stroke:#5c1a1a,color:#fff
    style Apply fill:#2d8659,stroke:#1a5c3a,color:#fff
    style ApplyWarn fill:#8a5a2d,stroke:#5c3a1a,color:#fff
    style Accept202 fill:#8a5a2d,stroke:#5c3a1a,color:#fff
Copy

• Invalid signature (a secret is configured but the HMAC doesn't match): the failure is logged, the envelope status is left unchanged, and the endpoint returns 202 — accepted-but-not-actioned, so the provider doesn't hammer the endpoint with retries of a payload MJ will never trust.
• No secret configured: the event is applied with a warning logged — convenient for development, with a nudge to configure a secret for production.
• Verified event: status applied and logged, 200.
• Unknown envelope: 202 — accepted (so the provider stops retrying) but not actioned.
• Malformed requests fail fast: missing driver key → 400; no system user → 503; unexpected error → 500.

Adding a new provider

1. Create a package depending on @memberjunction/esignature.
2. Subclass BaseSignatureProvider, implement the four required operations (plus any optional ones your vendor supports), and map the vendor's statuses onto EnvelopeStatus.
3. Register it: @RegisterClass(BaseSignatureProvider, 'YourVendorKey').
4. Add a MJ: Signature Providers metadata row whose ServerDriverKey matches that key.
5. Export the driver from your package's index.ts so importing the package triggers registration.

The engine resolves your driver by key the first time an account that uses it sends a document — no engine changes, no wiring.

Testing

cd packages/eSignature/Base && npm run test
Copy

Unit tests cover the BaseSignatureProvider contract — that optional operations default to "not supported", that capability discovery is accurate, and that the base class behaves correctly against mock drivers.

Related