Error Scenarios & Non-Positive States

oneSDKInstance.on('network_offline', () => {
  showBanner('You are offline. Verification will resume when connection is restored.');
});

oneSDKInstance.on('network_online', () => {
  showBanner('Connection restored. Resuming verification...');
  resumePendingOperations();
});

{
  message: string;      // Human-readable error description
  name: string;         // Error type identifier (empty string if not set)
  payload: unknown;     // Additional error context
}

oneSDKInstance.on('error', (error) => {
  console.error('SDK Error:', {
    message: error.message,
    name: error.name,
    payload: error.payload
  });

  showGenericError(error.message);
});

{
  message: string;
  payload?: unknown;
}

oneSDKInstance.on('warning', (warning) => {
  console.warn('SDK Warning:', warning.message);
});

try {
  const sdk = await OneSdk({
    mode: 'production',
    session: { token: sessionToken }
  });
} catch (error) {
  console.error('Initialization failed:', error);

  // Generate fresh token and retry
  const newToken = await fetchNewTokenFromBackend();
  const sdk = await OneSdk({
    mode: 'production',
    session: { token: newToken }
  });
}

Content-Security-Policy:
  script-src 'self' https://*.frankieone.com [vendor-domains];
  connect-src 'self' https://*.frankieone.com [vendor-domains];
  img-src 'self' https://*.frankieone.com [vendor-domains] data:;

const expirationEpoch = sdk.session.getExpirationEpoch();
const now = Date.now();

if (expirationEpoch && expirationEpoch * 1000 < now) {
  // Session expired — user must start over with a new token from your backend
  console.log('Session expired');
  showMessage('Your session has expired. Please start over.');
}

const entityId = sdk.session.getEntityId();

if (!entityId) {
  console.log('Entity not yet created');
  // First-time user - proceed with data collection
} else {
  console.log('Existing entity:', entityId);
  // Returning user - load existing data
}

const results = await individual.submit({ verify: true });

if (results.status.type === 'failed') {
  console.log('Verification failed');
  console.log('Failed checks:', results.checkResults.filter(c => c.result.type === 'failed'));

  // Check specific issues
  results.checkResults.forEach(check => {
    if (check.issues && check.issues.length > 0) {
      console.log(`Issues in ${check.type}:`, check.issues);
    }
  });
}

if (results.status.type === 'refer') {
  showMessage('Your verification is under review. We\'ll notify you within 24-48 hours.');
}

if (results.status.type === 'wait') {
  // Check what actions are needed
  const actions = results.alertList.filter(alert => alert.type === 'action');

  actions.forEach(action => {
    console.log('Action required:', action.term);
    if (action.extra?.action) {
      console.log('Specific action:', action.extra.action);
    }
  });
}

const { personalChecks } = results;

if (personalChecks.name === false) {
  showError('Name verification failed. Please check your name matches your ID.');
}

if (personalChecks.dateOfBirth === false) {
  showError('Date of birth verification failed.');
}

if (personalChecks.addresses) {
  Object.entries(personalChecks.addresses).forEach(([addressId, isValid]) => {
    if (isValid === false) {
      showError(`Address ${addressId} verification failed.`);
    }
  });
}

const { risk } = results;

if (risk.class === 'high' || risk.class === 'unacceptable') {
  console.log('High risk detected, level:', risk.level);

  // Check for blocklist matches
  if (results.blocklistPotentialMatches.length > 0) {
    console.log('Blocklist matches found:', results.blocklistPotentialMatches);
  }

  // Check for duplicates
  if (results.duplicatePotentialMatches.length > 0) {
    console.log('Duplicate entities found:', results.duplicatePotentialMatches);
  }
}

const results = await individual.submit({ verify: true });

if (results.issues?.creditHeader) {
  console.log('Credit header check flagged an issue — informational, not blocking');
}

// Or read it reactively via the accessor:
const hasCreditHeaderIssue = individual.access('creditHeaderIssue').getValue();

const actions = results.alertList.filter(alert => alert.type === 'action');

actions.forEach(action => {
  console.log('Action required:', action.term);

  if (action.extra?.action) {
    switch (action.extra.action) {
      case 'upload_proof_of_address':
        showUploadForm('Please upload proof of address');
        break;
      case 'additional_document_required':
        showUploadForm('Please upload additional document');
        break;
      case 'document_expired':
        showError('Your document has expired. Please upload a current document.');
        break;
    }
  }
});

const warnings = results.alertList.filter(alert => alert.type === 'warning');

warnings.forEach(warning => {
  console.warn('Warning:', warning.term);
});

if (results.blocklistPotentialMatches.length > 0) {
  console.log('BLOCKLIST MATCH DETECTED');

  results.blocklistPotentialMatches.forEach(match => {
    console.log('Matched entity:', match.entityId);
    console.log('Match confidence:', match.matchStrength);
    console.log('Matched personal fields:', match.matches.personal);
  });

  // Halt verification and escalate
  escalateToCompliance(results);
}

if (results.status.type === 'failed') {
  if (results.retryPages.length > 0) {
    console.log('Recommended retry pages:', results.retryPages);
    // Navigate user to the first recommended retry page
    navigateToPage(results.retryPages[0].name);
  } else {
    // Backend couldn't determine retry pages - restart the full flow
    restartVerificationFlow();
  }
}

try {
  // retryOptions is NOT enabled by default — pass it explicitly to enable retry behavior
  const results = await individual.submit(
    { verify: true },
    {
      maxRetries: 3,
      backoffDelayMs: 1000
    }
  );
} catch (error) {
  console.error('Submit failed:', error);

  if (error.message.includes('network')) {
    showError('Network error. Please check your connection and try again.');
  } else if (error.message.includes('validation')) {
    showError('Please check your information and try again.');
  } else {
    showError('An error occurred. Please try again later.');
  }
}

{
  getValue(): T;              // Read current value
  setValue(value: T): void;  // Write new value
  observable: Observable<T>; // Subscribe to reactive changes
}

// Read
const name = individual.access('name').getValue();

// Write
individual.access('name').setValue({ givenName: 'John', familyName: 'Doe' });

// Subscribe to reactive changes
individual.access('name').observable.subscribe((newName) => {
  console.log('Name updated:', newName);
});

if (!individual.isPersisted()) {
  showWarning('You have unsaved changes.');
}

// Before navigation
window.addEventListener('beforeunload', (e) => {
  if (!individual.isPersisted()) {
    e.preventDefault();
    e.returnValue = 'You have unsaved changes. Are you sure you want to leave?';
  }
});

// Applies to: IDV, OCR, Biometrics, Device
module.on('vendor_sdk_failed_loading', ({ vendor, errorObject }) => {
  console.error(`Failed to load ${vendor} SDK:`, errorObject);
});

module.on('session_data_failed_loading', ({ code, message }) => {
  console.error('Session failed:', message);
  showError('Unable to start verification. Please try again.');
});

idvFlow.on('results', (results) => {
  if (results.checkStatus === 'FAILED') {
    console.log('IDV verification failed');
    showFailureScreen();
  }
});

idvFlow.on('input_required', (info, status) => {
  if (status === 'INCOMPLETE') {
    showMessage('Verification incomplete. Please complete all required steps.');
    allowRetry();
  }
});

idvFlow.on('input_required', (info, status) => {
  if (status === 'DOCUMENTS_INVALID') {
    showError('Invalid document. Please select a different document type.');
    allowRetry();
  }
});

idvFlow.on('input_required', (info, status) => {
  if (status === 'AWAITING_CONSENT') {
    showMessage('Please provide consent to continue verification.');
    allowRetry();
  }
});

idvFlow.on('input_required', (info, status) => {
  if (status === 'WAITING_SELFIE_UPLOAD') {
    showMessage('Please capture your selfie to continue.');
    allowRetry();
  }
});

idvFlow.on('input_required', (info, status) => {
  if (status === 'WAITING_DOC_UPLOAD') {
    showMessage('Please upload your document to continue.');
    allowRetry();
  }
});

idvFlow.on('input_required', (info, status) => {
  if (status === 'INTERRUPTED') {
    // Remount the module to allow the user to resume
    showMessage('Verification was interrupted. Click retry to continue.');
    showRetryButton(() => idvFlow.mount('#idv-container'));
  }
});

idvFlow.on('input_required', (info, status) => {
  console.log('Input required:', status);

  // Show retry option — remounting the module resumes the flow
  showRetryButton(() => {
    idvFlow.unmount();
    idvFlow.mount('#idv-container');
  });
});

idvFlow.on('detection_failed', ({ message, payload }) => {
  console.error('Detection failed:', message);
  console.error('Details:', payload);
  showError(message || 'Document capture failed. Please try again.');
});

// Only register this listener if using Onfido
idvFlow.on('session_interrupted', () => {
  console.log('User closed verification (Onfido)');
  saveProgress();
  showMessage('You can resume verification later.');
});

ocrComponent.on('input_required', (info, status) => {
  if (status === 'AWAITING_DOCUMENT_UPLOAD_INVALID_TYPE') {
    showError('Invalid document type. Please select a different document.');
  }
});

biometricsComponent.on('session_data_failed_loading', ({ code, message }) => {
  console.error('Session failed:', code, message);
  showError('Failed to start biometric verification. Please try again.');
});

biometricsComponent.on('input_required', (info, status) => {
  console.log('Input required:', status);
  showMessage('Please complete the biometric capture to continue.');
  showRetryButton();
});

biometricsComponent.on('detection_failed', ({ message }) => {
  console.error('Biometric capture failed:', message);
  showError(message || 'Face capture failed. Please try again.');
});

// Incorrect
oneSdkInstance.component('device', { activityType: 'registration' }); // ✗ lowercase

// Correct
oneSdkInstance.component('device', { activityType: 'REGISTRATION' }); // ✓ uppercase

deviceComponent.on('device_characteristics_extracted', ({ deviceCharacteristics }) => {
  console.log('Device data collected — should appear in dashboard');
});

formComponent.on('form:welcome:failed', (payload) => {
  console.error('Welcome screen failed to load');
  showError('Unable to start verification. Please refresh the page.');
});

formComponent.on('form:review:failed', (payload) => {
  console.log('Verification failed');
  showCustomFailureUI();
});

formComponent.on('form:review:partial', (payload) => {
  showCustomPartialUI();
});

formComponent.on('form:review:pending', (payload) => {
  showCustomPendingUI();
});

const failResult = sdk.component('form', {
  name: 'RESULT',
  type: 'manual',
  state: 'FAIL',
  title: { label: 'Verification Failed' },
  descriptions: [{ label: 'We were unable to verify your information.' }]
});

failResult.on('form:result:loaded', () => {
  console.log('Failure screen displayed');
});

const timeoutResult = sdk.component('form', {
  name: 'RESULT',
  type: 'manual',
  state: 'TIMEOUT',
  title: { label: 'Your session has timed out' },
  descriptions: [{ label: 'The identity verification process took too long and has timed out. Please close this window and try again.' }]
});

timeoutResult.on('form:result:timeout', () => {
  console.log('Timeout screen displayed');
});

{
  name: 'REVIEW',
  // ...
  cta: {
    label: 'Submit',
    timeoutRetryMiliseconds: 5000,  // Auto-retry delay ms — the form retries automatically after this
    retryAmount: 3,                 // Max retry attempts per submission
    retryAttemptString: 'Error submitting form. Give it a moment to retry.',
    maxRetryAttemptedString: 'Something went wrong, please contact customer service or try again.'
  }
}

const retry = sdk.component('form', {
  name: 'RETRY',
  type: 'manual'
});

retry.on('form:retry:loaded', (payload) => {
  console.log('User can correct data and retry eKYC');
});

// ✓ Good
oneSDKInstance.on('error', (error) => {
  logError(error);
  showUserFriendlyMessage(error);
});

// ✗ Bad - No error handler
oneSDKInstance.on('results', handleResults); // Missing error handler

// ✓ Good
oneSDKInstance.on('error', (error) => {
  if (error.name === 'network_error') {
    showMessage('Please check your internet connection and try again.');
  } else {
    showMessage('Something went wrong. Please try again later.');
  }
});

// ✗ Bad - Technical jargon
oneSDKInstance.on('error', (error) => {
  alert(error.message); // May contain technical details
});

// ✓ Good
const results = await individual.submit({ verify: true });

switch (results.status.type) {
  case 'passed':
    navigateToSuccess();
    break;
  case 'failed':
    showFailureScreen(results);
    break;
  case 'refer':
    showPendingReview();
    break;
  case 'wait':
    showAdditionalInfoRequired(results.alertList);
    break;
  default:
    handleUnexpectedStatus(results.status.type);
}

// ✗ Bad - Only checking success
if (results.status.type === 'passed') {
  navigateToSuccess();
}
// Missing handling for all other states

// ✓ Good
oneSDKInstance.on('error', (error) => {
  // Log to analytics/monitoring
  logToSentry({
    message: error.message,
    name: error.name,
    payload: error.payload,
    timestamp: Date.now()
  });

  // Show user-friendly message
  showError('An error occurred. Our team has been notified.');
});

// ✓ Good
let isOnline = true;

oneSDKInstance.on('network_offline', () => {
  isOnline = false;
  showBanner('You are offline. Changes will be saved when connection is restored.');
  disableSubmitButton();
});

oneSDKInstance.on('network_online', () => {
  if (!isOnline) {
    isOnline = true;
    hideBanner();
    enableSubmitButton();
    retryPendingOperations();
  }
});

// ✓ Good
async function performVerification() {
  const expirationEpoch = sdk.session.getExpirationEpoch();
  const fiveMinutes = 5 * 60 * 1000;

  if (expirationEpoch && (expirationEpoch * 1000 - Date.now()) < fiveMinutes) {
    console.warn('Session expiring soon — request a new token from your backend');
    // There is no token refresh mechanism — must obtain new token from backend
    const newToken = await fetchNewTokenFromBackend();
    await reinitializeSDK(newToken);
  }

  // Proceed with verification
  const results = await individual.submit({ verify: true });
}

// ✗ Not needed in production
oneSDKInstance.on('telemetry', (event) => {
  console.log('Telemetry:', event); // Only useful for FrankieOne debugging
});

const idv = oneSdk.flow("idv");
idv.on('error', (error) => {
  console.error('Onfido error:', error);
});