Travel Rule Widget SDK reference

new TravelRuleWidget<T extends TravelRuleWidgetFlow = TravelRuleWidgetFlow>(
  session: TravelRuleWidgetSession,
  options?: TravelRuleWidgetOptions
)

// Generic flow type (default)
const widget = new TravelRuleWidget(session);

// Specific flow type for better type inference
const depositWidget = new TravelRuleWidget<'deposit-form'>(session);
const withdrawalWidget = new TravelRuleWidget<'withdrawal-form'>(session);

type TravelRuleWidgetOptions = {
  debug?: boolean;
  layout?: WidgetLayout;
  theme?: WidgetThemeOption;
};

const widget = new TravelRuleWidget(session, {
  layout: 'fluid'
});

const widget = new TravelRuleWidget(session, {
  theme: {
    appearance: 'dark',
    primary: { light: '#6200EA', dark: '#BB86FC' },
    // Alternatively, a single color string applies to both appearances, e.g. primary: '#6200EA'
    // primary: '#6200EA',
    fontFamily: 'Inter, sans-serif',
    components: {
      button: { borderRadius: '8px' }
    }
  }
});

// Ensure the container has appropriate sizing
const container = document.getElementById('tr-container');

widget.mountIframe(container);

widget.unmount();

widget.on('complete', (event) => {
  console.log('Travel Rule form completed:', event.detail.value);
});

const handleComplete = (event) => {
  console.log('Travel Rule form completed:', event.detail.value);
};

// Register the listener
widget.on('complete', handleComplete);

// Remove the listener
widget.off('complete', handleComplete);

type TravelRuleWidgetCompleteEvent<T = TravelRuleWidgetFlow> = {
  detail: {
    value: T;
  };
};

widget.on('complete', (event: TravelRuleWidgetCompleteEvent) => {
  const travelRuleData = event.detail.value;

  console.log('Travel Rule form completed:', travelRuleData);

  // Send the data to your backend to resolve the RFI or create the transaction
  await submitTravelRuleData(travelRuleData);

  widget.unmount();
});

const depositWidget = new TravelRuleWidget<'deposit-form'>(session);

depositWidget.on('complete', async (event) => {
  // Use the travel rule data to resolve the quote requirement
  await resolveQuoteRequirement(quoteId, event.detail.value);

  depositWidget.unmount();
});

const withdrawalWidget = new TravelRuleWidget<'withdrawal-form'>(session);

withdrawalWidget.on('complete', async (event) => {
  // Use the travel rule data when creating the transaction
  await createTransaction({
    ...transactionParams,
    travelRuleData: event.detail.value
  });

  withdrawalWidget.unmount();
});

type TravelRuleWidgetCancelEvent = {
  detail: {};
}

widget.on('cancel', (event: TravelRuleWidgetCancelEvent) => {
  console.log('Travel Rule form cancelled by user');

  widget.unmount();
});

type TravelRuleWidgetError = {
  name: string;
  code: string;
  message: string;
  details?: Record<string, unknown>;
  stack?: string;
  cause?: TravelRuleWidgetError;
  httpStatusCode?: number;
}

type TravelRuleWidgetErrorEvent = {
  detail: {
    error: TravelRuleWidgetError;
  };
};

widget.on('error', (event: TravelRuleWidgetErrorEvent) => {
  const { error } = event.detail;
  console.error('Travel Rule form error:', error);

  // Handle specific error types
  if (error.code === 'entity_not_found') {
    // Quote or transaction not found - may have expired
    handleExpiredSession();
  } else if (error.code === 'validation_failed') {
    // Form validation error (shouldn't happen in normal flow)
    console.error('Validation error:', error.details);
  } else {
    // Generic error handling
    showGenericError(error.message);
  }

  widget.unmount();
});

type TravelRuleWidgetReadyEvent = {
  detail: {};
}

widget.on('ready', (event: TravelRuleWidgetReadyEvent) => {
  console.log('Travel Rule form is ready');
});

type TravelRuleWidgetSession = {
  url: string;
  token: string;
  flow: TravelRuleWidgetFlow;
  data: TravelRuleWidgetData;
}

type TravelRuleWidgetFlow = 'deposit-form' | 'withdrawal-form';

type TravelRuleWidgetData = {
  provider: 'notabene';
  parameters: object;
};

type TravelRuleResult = Record<string, unknown>;

type WidgetLayout = 'boxed' | 'fluid';

type WidgetThemeOption = {
  appearance?: 'light' | 'dark';
  primary?: ColorTokenValue;
  primaryForeground?: ColorTokenValue;
  foreground?: ColorTokenValue;
  emphasisForeground?: ColorTokenValue;
  background?: ColorTokenValue;
  fontFamily?: FontFamily;
  components?: {
    button?: { borderRadius?: string };
    input?: { borderRadius?: string };
    card?: { borderRadius?: string };
  };
};

type ColorTokenValue = string | { light: string; dark: string };

type FontFamily = string | Partial<Record<'mono' | 'sans' | 'serif', string>>;

import { TravelRuleWidget } from '@uphold/enterprise-travel-rule-widget-web-sdk';

// Create a Travel Rule Widget session from your backend
const session = await createTravelRuleWidgetSession(quoteId);

// Initialize the Widget with type inference
const widget = new TravelRuleWidget<'deposit-form'>(session, { debug: true });

// Handle ready event
widget.on('ready', () => {
  console.log('Travel Rule form is ready');
});

// Handle completion with the Travel Rule data
widget.on('complete', async (event) => {
  const travelRuleData = event.detail.value;
  console.log('Travel Rule form completed:', travelRuleData);

  try {
    // Send the data to your backend to resolve the quote requirement
    await resolveQuoteRequirement(quoteId, travelRuleData);

    // Proceed with the transaction flow
    showSuccessMessage('Travel Rule compliance completed');
  } catch (error) {
    console.error('Failed to submit Travel Rule data:', error);
    showErrorMessage('Failed to submit compliance information');
  }

  widget.unmount();
});

// Handle cancellation
widget.on('cancel', () => {
  console.log('Travel Rule form cancelled by user');
  showCancellationMessage();
  widget.unmount();
});

// Handle errors with specific error handling
widget.on('error', (event) => {
  const { error } = event.detail;
  console.error('Travel Rule form error:', error);

  if (error.code === 'entity_not_found') {
    showErrorMessage('Session expired. Please start over.');
  } else {
    showErrorMessage(error.message);
  }

  widget.unmount();
});

// Mount the Widget to a DOM element
widget.mountIframe(document.getElementById('tr-container'));