Skip to main content
The SDK surfaces errors through two mechanisms: thrown Error objects (via promise rejection or synchronous throws) and structured error objects within VerificationResult.

​
Synchronous Errors (Constructor)

These errors are thrown immediately when constructing a new Transcrypts instance with invalid options.
Error messageCauseWhen
Transcrypts: apiKey is requiredapiKey is missing, empty, or falsy in options.new Transcrypts()

​
Promise Rejections (verify)

The verify() method rejects its promise in these scenarios:
Error messageCause
Transcrypts: ssn is requiredssn is missing, empty, or falsy in options.
Verification failedThe widget reported a verification failure with no specific message.
(dynamic message)The widget reported a verification failure with a specific message.

​
Structured Errors in VerificationResult

When the user dismisses the widget (close button, Escape key, or backdrop click), verify() resolves (does not reject) with the following result: 
{
  success: false,
  verified: false,
  error: {
    code: 'USER_CLOSED',
    message: 'User closed the verification widget',
  },
}
User dismissals resolve the promise rather than rejecting it. This allows you to distinguish between user-initiated closures and actual verification failures in your control flow.

​
Error Codes Reference

CodeDescriptionPromise behavior
USER_CLOSEDThe user dismissed the widget without completing verification.Resolves

​
Complete Example

The following example demonstrates the full SDK API: initialization, event subscriptions, verification, result handling, and cleanup. 
import { Transcrypts } from 'transcrypts';
import type { VerificationResult, TranscryptsEvent } from 'transcrypts';

// 1. Initialize the SDK
const transcrypts = new Transcrypts({
  apiKey: 'your-api-key',
});

// 2. Subscribe to widget lifecycle events
const unsubscribeReady = transcrypts.on('ready', (event: TranscryptsEvent) => {
  console.log('Widget is ready');
});

const unsubscribeLoaded = transcrypts.on('loaded', (event: TranscryptsEvent) => {
  console.log('Widget has loaded');
});

transcrypts.on('verification_started', (event: TranscryptsEvent) => {
  console.log('User started verification');
});

transcrypts.on('verification_complete', (event: TranscryptsEvent) => {
  console.log('Verification complete event:', event.payload);
});

transcrypts.on('verification_failed', (event: TranscryptsEvent) => {
  console.log('Verification failed event:', event.payload);
});

transcrypts.on('close', (event: TranscryptsEvent) => {
  console.log('Widget closed by user');
});

// 3. Run verification
async function runVerification() {
  try {
    const result: VerificationResult = await transcrypts.verify({
      ssn: '123-45-6789',
      user: {
        firstName: 'Jane',
        lastName: 'Doe',
        email: 'jane@example.com',
      },
    });

    // 4. Handle results
    if (result.success && result.verified) {
      console.log('Verification ID:', result.verificationId);
      console.log('User ID:', result.userId);

      // Process work experience records
      if (result.workExperience) {
        for (const job of result.workExperience) {
          console.log(`${job.position} at ${job.companyName}`);
          console.log(`  From: ${job.startDate}`);
          console.log(`  To: ${job.endDate ?? 'Present'}`);
          console.log(`  Current: ${job.isCurrentJob}`);
          console.log(`  Verified: ${job.verified}`);
        }
      }
    } else if (result.error) {
      // User closed the widget
      console.log('Verification not completed:', result.error.message);
    }
  } catch (error) {
    // Verification failed (widget reported failure)
    console.error('Verification error:', (error as Error).message);
  } finally {
    // 5. Clean up event listeners when done
    unsubscribeReady();
    unsubscribeLoaded();
  }
}

runVerification();