@velion-la/onboarding-sdk (Loader)

Thin client for the Velion Onboarding flow. This package creates an iframe that loads the full onboarding app from your CDN (e.g. https://static.velion.la/sdk) and bridges configuration and events via postMessage. You get the same API as before with a minimal bundle (~5 kB); the heavy UI (document capture, liveness, fingerprint) runs inside the iframe.

npm · License

Overview

Your backend defines which steps are required per session; the SDK (loader + app in iframe) fetches that configuration at runtime and runs the flow. All requests use Authorization: Bearer <sessionToken>.

Key points:

• Zero framework dependency for consumers. Works with Angular, Vue, React, or plain HTML.
• Optional cdnUrl. Default is https://static.velion.la/sdk. Override for staging or self-hosted app.
• Same API. VelionOnboarding, onSuccess, onError, onStepChange, theme, etc. unchanged.

Installation

npm install @velion-la/onboarding-sdk
# or: yarn add @velion-la/onboarding-sdk
# or: pnpm add @velion-la/onboarding-sdk

Quick Start

import { VelionOnboarding, SdkErrorCode } from '@velion-la/onboarding-sdk';

const { session_id, session_token, expires_at } = await fetch('/api/kyc/sessions', {
  method: 'POST',
}).then(r => r.json());

const sdk = new VelionOnboarding({
  containerId:  'kyc-container',
  sessionId:    session_id,
  sessionToken: session_token,
  expiresAt:    expires_at,
  apiUrl:       'https://<your-domain>.velion.la/gateway/api/v1/onboarding',
  locale:       'es',
  theme:        { primaryColor: '#0052CC', borderRadius: '10px' },
  onSuccess:    (result) => console.log('Done:', result.status),
  onError:      (err) => console.error(err.code, err.message),
  onStepChange: (step, index, total) => { /* progress UI */ },
});

await sdk.start();

window.addEventListener('beforeunload', () => sdk.destroy());

Host page container

Style the container element only (containerId). The loader sets the iframe to full width and keeps its height in sync with the container’s computed height (ResizeObserver + window resize). If the container still has zero height at first paint, the iframe uses an internal fallback (min(85vh, 880px)) until layout provides a real height—similar to how other web SDKs expect a sized wrapper.

You do not need CSS on the iframe itself. Examples:

#kyc-container {
  width: 100%;
  height: 700px;
  max-width: 900px;
  margin: 0 auto;
}

or full viewport height:

#kyc-container {
  width: 100%;
  height: 100vh;
}

More detail: app/README.md (integration notes for the hosted app).

Configuration

| Property | Type | Required | Default | Description | | -------------- | -------- | -------- | ------------------------------- | ----------- | | containerId | string | ✓ | — | id of the DOM element where the iframe is inserted. | | sessionId | string | ✓ | — | Session identifier from your backend. | | sessionToken | string | ✓ | — | Short-lived Bearer token (e.g. JWT). | | apiUrl | string | ✓ | — | Gateway base URL (no trailing slash). | | cdnUrl | string | | 'https://static.velion.la/sdk'| Base URL of the onboarding app (iframe source). | | expiresAt | string | | — | ISO-8601 token expiry. | | theme | VelionTheme | | — | Primary color, border radius, etc. | | locale | string | | 'es' | BCP 47 locale for UI. | | onSuccess | (result: OnboardingResult) => void | | — | Called when the flow completes. | | onError | (error: SdkError) => void | | — | Called on unrecoverable errors. | | onStepChange | (step, index, total) => void | | — | Called when the active step changes. | | onStepComplete | (step: OnboardingStep) => void | | — | Called after each step succeeds. | | onTokenExpired | () => Promise<{ sessionToken: string; expiresAt?: string }> | | — | Optional. When the iframe reports token expiry, return a new token so the flow can continue. |

All other options from the full SDK (e.g. livenessDisplayText) are passed through to the app in the iframe.

Instance methods

• sdk.start(): Promise<void> — Starts the flow (loads iframe, sends config).
• sdk.getStatus(): SdkStatus — Returns current state ('IDLE' | 'RUNNING' | 'COMPLETED' | 'ERROR' | 'DESTROYED').
• sdk.destroy(): void — Removes the iframe and cleans up. Idempotent.
• VelionOnboarding.getVersion(): string — Static; returns SDK version.

Plain HTML (UMD)

<div id="kyc-container"></div>
<script src="https://cdn.velion.la/sdk/v1.0.0/velion-sdk.umd.js"></script>
<script>
  const sdk = new VelionSDK.VelionOnboarding({
    containerId: 'kyc-container',
    sessionId: '...',
    sessionToken: '...',
    apiUrl: 'https://<your-domain>.velion.la/gateway/api/v1/onboarding',
    onSuccess: (r) => console.log(r.status),
    onError: (e) => console.error(e.code, e.message),
  });
  sdk.start();
</script>

The UMD bundle exposes window.VelionSDK.

Error handling

Errors are delivered via onError with a SdkError object (code, message, optional cameraCode, httpStatus, cause). Common codes: SESSION_EXPIRED, SESSION_FETCH_FAILED, CAMERA_ERROR, CONTAINER_NOT_FOUND, FINGERPRINT_FAILED, LIVENESS_FAILED, etc. Use onTokenExpired to refresh the token when the iframe reports expiry.

Backend and CDN

• Your backend must implement the Velion Session API (e.g. GET /sessions/:id, POST /sessions/:id/fingerprint, document and liveness endpoints). The loader passes apiUrl and sessionToken to the app; all requests are made from the iframe.
• The onboarding app must be deployed at the URL you set in cdnUrl (default https://static.velion.la/sdk). Build and deploy the app project from this repository to that path.

Publishing (maintainers)

From the loader/ directory:

1. npm run build
2. npm version patch|minor|major
3. npm publish

files in package.json includes dist, README.md, and LICENSE.