@luminpdf/lumin-embed-signing-sdk

SDK for embedding the Lumin signing experience inside your web app.

Install

npm install @luminpdf/lumin-embed-signing-sdk

Quick example

import { LuminSigning } from '@luminpdf/lumin-embed-signing-sdk';

const client = new LuminSigning();

client.on('signed', ({ signatureRequestId, signerEmail }) => {
  console.log('Signed!', signatureRequestId, signerEmail);
});

client.on('declined', ({ reason }) => {
  console.log('Declined', reason);
});

client.on('error', ({ code, message }) => {
  console.error('Error:', code, message);
});

client.on('close', () => {
  console.log('Session closed');
});

// signUrl and token come from your backend's signing-session API
const session = client.open({
  containerId: 'signing-container',
  signUrl,
  token,
});

API

new LuminSigning(config?)

| Option | Type | Default | Description | |--------|------|---------|-------------| | debug | boolean | false | Enable [lumin-signing] console output for troubleshooting |

client.open(options)

| Option | Type | Description | |--------|------|-------------| | containerId | string | ID of the DOM element to render the signing iframe into | | signUrl | string | The sign_url returned by the signing-session API | | token | string | The token returned by the signing-session API |

Returns a SigningSession instance.

Events

| Event | Payload | Description | |-------|---------|-------------| | open | { signUrl } | Iframe created and loading | | loaded | { signatureRequestId, signerEmail, expiresAt? } | Handshake complete, signing UI ready | | signed | { sessionId, signatureRequestId, signerEmail } | Signer completed signing | | declined | { sessionId, signatureRequestId, signerEmail, reason? } | Signer declined to sign | | cancel | { sessionId, signatureRequestId, signerEmail } | Signer dismissed the signing UI | | expire | { sessionId, signatureRequestId, signerEmail } | Session expired | | error | { sessionId, code, message } | An error occurred | | close | {} | Session closed (always fires last) |

All terminal events (signed, declined, cancel, expire, error) automatically close the session and remove the iframe. The close event always fires after them.

session.close()

Manually close the session and remove the iframe.

Debug logging

Pass debug: true to surface [lumin-signing] … console output for troubleshooting:

const client = new LuminSigning({ debug: true });

When debug is not set (the default), all logging is a no-op with zero runtime overhead. Sensitive values are redacted in logs -- emails are masked, nonces are truncated, session IDs are partially hidden, and the JWT token is never logged.

Build

npm run build:prod   # production build
npm test             # run all tests
npm run typecheck    # TypeScript check

License

MIT