@allsign/embedded

JavaScript SDK for embedding AllSign signing flows directly in your web application.

Status: v0.1.0 — scaffolding. Validation, types, errors, and entry points are shipped. The iframe lifecycle (modal/inline/slider mounting, postMessage handling, auto-resize) is the next milestone (tracked in ALLSI-190).

Install

npm install @allsign/embedded

Or via CDN (available once first version is published):

<script src="https://js.allsign.io/v1.js" async></script>

Quickstart

import { AllSign } from '@allsign/embedded';

// 1. Your BACKEND creates the signing session with your secret key
//    and returns the client_secret to your frontend:
//
//    POST https://api.allsign.io/v2/signing-sessions
//    Authorization: Bearer allsign_live_sk_TU_SECRET_KEY
//    { "document_id": "...", "signer_email": "..." }
//    → { "client_secret": "as_sess_xxx_secret_yyy", ... }

// 2. Your FRONTEND uses the client_secret to mount the signing widget:
const session = AllSign.init({
  clientSecret: 'as_sess_xxx_secret_yyy',
  locale: 'es-MX',
  onSuccess: (result) => {
    console.log('Firmado:', result.signatureId);
  },
  onExit: (metadata) => {
    console.log('Salió:', metadata.reason);
  },
});

session.modal(); // or session.inline('#container') or session.slider()

Only one credential in the browser

The SDK accepts a single public credential: the clientSecret returned by POST /v2/signing-sessions. It's ephemeral (15 minutes), single-use, and scoped to exactly one signing session.

There is no publishable key. Following the modern Plaid link-token model (which Plaid adopted in 2020 when it deprecated its publicKey), the clientSecret itself does all the work: identifies the tenant, scopes the permissions, and is safe to send to the browser because it's short-lived and limited in blast radius.

If you paste a secret key (allsign_live_sk_*) into AllSign.init() by mistake, the SDK throws SECRET_KEY_PASSED_AS_CLIENT_SECRET immediately with a descriptive error that tells you how to generate a clientSecret server-side instead.

React

The SDK ships a React hook at the /react subpath:

import { useAllSignLink } from '@allsign/embedded/react';

function SignButton({ clientSecret }) {
  const { open, ready, error } = useAllSignLink({
    clientSecret,
    onSuccess: (result) => console.log('Firmado:', result.signatureId),
    onExit: (metadata) => console.log('Salió:', metadata.reason),
  });

  if (error) return <p>Error: {error.message}</p>;
  return <button onClick={open} disabled={!ready}>Firmar</button>;
}

React is declared as an optional peer dependency — you only need it installed if you import from @allsign/embedded/react.

TypeScript

Full type declarations are shipped with the package:

import type {
  AllSignInitOptions,
  AllSignSession,
  SigningResult,
  ExitMetadata,
  SigningEvent,
  ThemeOptions,
  Locale,
} from '@allsign/embedded';

import type {
  UseAllSignLinkOptions,
  UseAllSignLinkReturn,
} from '@allsign/embedded/react';

Error handling

All errors thrown by the SDK are instances of AllSignError with a stable code you can branch on:

import { AllSign, AllSignError, AllSignErrorCode } from '@allsign/embedded';

try {
  const session = AllSign.init({ clientSecret });
} catch (e) {
  if (e instanceof AllSignError) {
    switch (e.code) {
      case AllSignErrorCode.MISSING_CLIENT_SECRET:
      case AllSignErrorCode.INVALID_CLIENT_SECRET_FORMAT:
        // Your backend didn't return a valid client_secret
        break;
      case AllSignErrorCode.SECRET_KEY_PASSED_AS_CLIENT_SECRET:
        // You passed a secret key to the frontend — SECURITY BUG, fix it
        break;
      case AllSignErrorCode.SESSION_EXPIRED:
        // Create a new signing session server-side and retry
        break;
      // ... see src/core/errors.ts for the full catalog
    }
  }
  throw e;
}

Development

# Install deps
npm install

# Run tests (unit, jsdom)
npm test

# Typecheck
npm run typecheck

# Build (ESM + CJS + UMD + d.ts per entry)
npm run build

Release pipeline (planned)

• main branch → npm publish on tag + upload to js.allsign.io/v1.js
• Semver: loader API stable at v1.x, additive events are minors, type breaks are majors
• Size budgets: loader <3KB gzip, core <50KB gzip

Links

• Docs: developers.allsign.io/embedded
• Backend API: developers.allsign.io
• Dashboard (iframe host): allsign.io
• Issues: github.com/binaryme/allsign-embedded-sdk/issues

License

MIT