API Reference — Web

createVerifierSDK(config)

Creates and returns a VerifierSDK instance.

import { createVerifierSDK } from '@vecu/verifier-web-sdk';

const sdk = createVerifierSDK({
  stage: 'production',
  bearerToken: 'your-token',
});

Configuration

The SDK automatically resolves the correct endpoint for each stage. The apiBaseUrl property is available for local mock server testing only.

SDK Methods

startVerification(container, options) — Container-Based UI

Renders the built-in verification UI into a DOM element. Handles all states automatically.

const cleanup = await sdk.startVerification(container, {
  vin: '1HGBH41JXMN109186',
  proximity: { thresholdMiles: 5.0 },
  onApproved: result => {
    /* VerificationApproved */
  },
  onDenied: result => {
    /* VerificationDenied */
  },
  onExpired: result => {
    /* VerificationExpired */
  },
  onError: error => {
    /* VerifierError */
  },
});

Options:

Returns: Promise<CleanupFunction> — call to unmount UI and stop polling.

createPresentationRequest(vin, options?) — Headless

Creates a verification request and returns QR content.

const result = await sdk.createPresentationRequest('1HGBH41JXMN109186', {
  proximity: { thresholdMiles: 5.0 },
});
if (result.ok) {
  const { request_id, qr_content, expires_at } = result.data;
}

Returns: Promise<ApiResult<CreatePresentationResponse>>

startPolling()

Starts polling for verification status. Stops automatically on terminal states.

Returns: () => void — cleanup function to stop polling.

stopPolling()

Manually stop polling.

getStatus() / getRequest()

Get current verification status or full request state.

on(type, listener) / off(type, listener) / once(type, listener)

Subscribe/unsubscribe to events. on and once return an unsubscribe function. once automatically removes the listener after the first invocation.

destroy()

Clean up all resources. Sets sdk.isDestroyed = true.

Events

sdk.on('request:created', event => {
  event.requestId; // string
  event.qrContent; // string — display as QR code
  event.vin; // string
});

sdk.on('status:changed', event => {
  event.previousStatus; // VerificationStatus | null
  event.currentStatus; // VerificationStatus
});

sdk.on('polling:started', event => {
  event.requestId; // string
  event.intervalMs; // number
});

sdk.on('polling:stopped', event => {
  event.requestId; // string
  event.reason; // 'terminal_state' | 'timeout' | 'manual' | 'error' | 'restart'
});

sdk.on('error', event => {
  event.error; // VerifierError
});

Verification Status Types

Status is a discriminated union on the status field:

All statuses share a common shape with requestId, createdAt?, and expiresAt?:

// Pending — waiting for driver to scan
{ status: 'pending', requestId: string, createdAt?: string, expiresAt?: string }

// Approved — credential verified, OK to release vehicle
{
  status: 'approved',
  requestId: string,
  createdAt?: string,
  expiresAt?: string,
  verifiedClaims?: {
    vin: string,
    originLocation?: string,
    destinationLocation?: string,
  },
  proximityCheck?: {
    status: 'pass' | 'fail' | 'unchecked',
    distanceMiles: number | null,
    thresholdMiles: number | null,
    originCoordinates: { lat: number, lng: number } | null,
    deviceCoordinates: { lat: number, lng: number } | null,
  },
}

// Denied — DO NOT release vehicle
{ status: 'denied', requestId: string, createdAt?: string, expiresAt?: string, error?: string }

// Expired — session timed out
{ status: 'expired', requestId: string, createdAt?: string, expiresAt?: string }

Type guards:

import { isApproved, isDenied, isTerminalStatus } from '@vecu/verifier-web-sdk';

if (isApproved(status)) {
  /* terminal — OK to release */
}
if (isTerminalStatus(status)) {
  /* approved | denied | expired */
}

Proximity Types

ProximityConfig

Passed via startVerification options or createPresentationRequest. The SDK automatically retrieves device GPS coordinates using platform location services. If location permission is not granted, the proximity check result will be unchecked.

interface ProximityConfig {
  thresholdMiles: number; // Max allowed distance from origin (miles)
}

ProximityCheck

Returned on VerificationApproved.proximityCheck when proximity was evaluated.

Error Types

Errors are a discriminated union on code:

All errors include code, message, and timestamp.

import { isVerifierError } from '@vecu/verifier-web-sdk';

React Components & Hooks

Imported from @vecu/verifier-web-sdk/react.

VerificationView

Full verification flow component with built-in UI. Mirrors the React Native VerificationView.

import { useVerifierSDK, VerificationView } from '@vecu/verifier-web-sdk/react';

<VerificationView
  sdk={sdk}
  vin='1HGBH41JXMN109186'
  onApproved={result => {
    /* VerificationApproved */
  }}
  onDenied={result => {
    /* VerificationDenied */
  }}
  onExpired={result => {
    /* VerificationExpired */
  }}
  onError={error => {
    /* VerifierError */
  }}
  className='my-custom-class'
  useDefaultStyles={true}
/>;

useVerifierSDK(config)

Creates an SDK instance tied to the component lifecycle. Automatically destroys on unmount.

import { useVerifierSDK } from '@vecu/verifier-web-sdk/react';

const sdk = useVerifierSDK(config);
// Auto-creates/destroys SDK with component lifecycle
// Handles React StrictMode double-mounting

useVerification(sdk, vin, callbacks?)

Manages the full verification flow and returns UI state. Powers VerificationView internally.

import { useVerifierSDK, useVerification } from '@vecu/verifier-web-sdk/react';

const sdk = useVerifierSDK(config);
const { state, restart } = useVerification(sdk, vin, {
  onApproved: result => {
    /* ... */
  },
  onDenied: result => {
    /* ... */
  },
});

Returns:

• state: UIState — current state ('loading' | 'qr' | 'qr-expired' | 'approved' | 'denied' | 'expired' | 'error')
• restart: () => void — restart the verification flow with a new QR code

Error Factory Functions

Helper functions for creating typed errors:

import {
  createNetworkError,
  createApiError,
  createValidationError,
  createTimeoutError,
  createSessionError,
  isVerifierError,
} from '@vecu/verifier-web-sdk';

const error = createNetworkError('Connection failed', originalError);
const apiErr = createApiError('Not found', 404, { detail: '...' });
const valErr = createValidationError('Invalid VIN', 'vin');
const timeErr = createTimeoutError('Polling timed out', 300000);
const sessErr = createSessionError('Session expired', 'session-123');