Skip to main content
Version: Isle Royale (2.5.0)

Type Definitions

TypeScript type definitions for the ToughClicks JavaScript SDK.

TCDisplayOptions​

Configuration options for displaying a packet.

interface TCDisplayOptions {
containerId?: string;
signerIdSelector: string | null;
signerId: string | null;
displayMethod: TCDisplayMethod | null;
shouldOpenModal: boolean | null;
manualAcceptance: boolean | false;
optional?: boolean;
assentActionLabel?: string;
assentActionSelector?: string;
}

Fields​

FieldTypeRequiredDescription
containerIdstringNoHTML element ID where UI will be rendered
signerIdSelectorstring | nullEither this or signerIdID of input element to monitor for signer identifier
signerIdstring | nullEither this or signerIdSelectorDirect signer identifier value
displayMethodTCDisplayMethod | nullNoHow to display documents (individual, group, scroll, buttonAssent)
shouldOpenModalboolean | nullNoOpen document terms in modal (true) or new tab (false)
manualAcceptancebooleanNoRequire manual accept() call (default: false)
optionalbooleanNoMark packet as optional (default: false). Rejected when displayMethod is buttonAssent
assentActionLabelstringRequired for buttonAssentLabel of your submit button, named in the notice
assentActionSelectorstringNoCSS selector for your submit button, used to evidence proximity

Example​

const options: TCDisplayOptions = {
containerId: 'tc-agreements',
signerIdSelector: 'email-input',
signerId: null,
displayMethod: TCDisplayMethod.individual,
shouldOpenModal: true,
manualAcceptance: false,
optional: false
};

TCPacketDisplayOptions​

Display options for a specific packet.

interface TCPacketDisplayOptions {
packetId: string;
displayOptions: TCDisplayOptions;
}

Fields​

FieldTypeDescription
packetIdstringThe packet ID this configuration applies to
displayOptionsTCDisplayOptionsDisplay options for this packet

Example​

const packetOptions: TCPacketDisplayOptions = {
packetId: 'my-packet-id',
displayOptions: {
containerId: 'packet-container',
signerId: 'user@example.com',
displayMethod: TCDisplayMethod.individual,
shouldOpenModal: false,
manualAcceptance: false
}
};

TCDisplayMethod​

Enum defining how documents are displayed to users.

enum TCDisplayMethod {
individual = 'individual',
group = 'group',
scroll = 'scroll',
buttonAssent = 'buttonAssent'
}

Values​

ValueDescription
individualSeparate checkbox for each document
groupSingle checkbox for all documents in packet
scrollScrollable container that must be scrolled to bottom
buttonAssentNotice with no checkbox; the visitor's click on your own submit button is the agreement

Example​

import { TCDisplayMethod } from '@toughclicks/js-client-sdk';

const method: TCDisplayMethod = TCDisplayMethod.individual;

TCEnvironment​

Enum defining the ToughClicks environment.

enum TCEnvironment {
production = 'production',
staging = 'staging'
}

Values​

ValueDescription
productionProduction environment (default)
stagingStaging/sandbox environment for testing

Example​

import { TCEnvironment } from '@toughclicks/js-client-sdk';

const tc = new ToughClicks(
token,
packetId,
true,
TCEnvironment.staging
);

TCEventTypes​

String literal type for event names.

type TCEventTypes = 'tc-valid' | 'tc-accepted' | 'tc-internal-error';

Values​

ValueDescription
'tc-valid'Validation state changed
'tc-accepted'All packets accepted successfully
'tc-internal-error'Internal error occurred

Example​

const eventType: TCEventTypes = 'tc-valid';

tc.on(eventType, (state) => {
console.log('Event fired:', state);
});

TCState​

State object passed to tc-valid and tc-accepted event handlers (single packet).

interface TCState {
isValid: boolean;
allAccepted: boolean;
signerId: string | null;
packetId: string;
}

Fields​

FieldTypeDescription
isValidbooleanWhether all required validations pass
allAcceptedbooleanWhether all documents are accepted
signerIdstring | nullCurrent signer identifier
packetIdstringThe packet ID

TCMultiPacketState​

State object passed to event handlers when using multiple packets.

interface TCMultiPacketState {
allPacketsValid: boolean;
allPacketsAccepted: boolean;
packets: {
[packetId: string]: {
isValid: boolean;
allAccepted: boolean;
signerId: string | null;
}
};
}

Fields​

FieldTypeDescription
allPacketsValidbooleanWhether all required packets are valid
allPacketsAcceptedbooleanWhether all checked packets are accepted
packetsobjectPer-packet state information

Example​

tc.on('tc-valid', (state: TCMultiPacketState) => {
console.log('All valid?', state.allPacketsValid);

// Check individual packet states
if (state.packets['packet1']?.isValid) {
console.log('Packet 1 is valid');
}
});

TCVerificationResponse​

Response from the verify() method, one per packet.

interface TCVerificationResponse {
id: string;
displayName: string;
documents: {
id: string;
displayName: string;
latestVersion: string;
latestAgreement: string;
}[];
userCompliant: boolean;
verificationFailed: boolean;
}

Fields​

FieldTypeDescription
idstringThe packet ID that was verified
displayNamestringThe packet's display name. Empty when verificationFailed is true
documentsarrayVerification details for each document in the packet. Empty when verificationFailed is true
userCompliantbooleanWhether the user has accepted the latest version of every document in the packet. Also true when verificationFailed is true (see below)
verificationFailedbooleantrue when the library could not get an answer from the API, so userCompliant is a placeholder rather than a real result

Document Fields​

FieldTypeDescription
idstringThe document ID
displayNamestringThe document's display name
latestVersionstringThe document's current version
latestAgreementstringThe version the user last accepted, or "" if they never accepted it

When verification fails​

If the API can't be reached, times out, or returns an error, verify() fails open: that packet's result is

{ id: '<packetId>', displayName: '', documents: [], userCompliant: true, verificationFailed: true }

and the library emits tc-internal-error. Failing open keeps sign-up and login flows working during an outage. If an unanswered check must not count as compliance in your app, check verificationFailed before userCompliant. See Error Handling.

Example​

const results: TCVerificationResponse[] = await tc.verify('user@example.com');

results.forEach(result => {
if (result.verificationFailed) {
console.warn(`Could not verify packet ${result.id}`);
return;
}
console.log(`Packet ${result.id}: ${result.userCompliant ? 'compliant' : 'needs acceptance'}`);

result.documents.forEach(doc => {
if (doc.latestAgreement === doc.latestVersion) {
console.log(` ✓ ${doc.displayName} v${doc.latestVersion} accepted`);
} else {
console.log(` ✗ ${doc.displayName} v${doc.latestVersion} not accepted`);
}
});
});

TCContextState​

Custom context state for advanced use cases.

interface TCContextState {
[key: string]: any;
}

Provides additional context information for acceptance records.

Example​

const getPageContext = (): TCContextState => {
return {
currentPage: window.location.pathname,
referrer: document.referrer,
sessionId: getSessionId(),
userAgent: navigator.userAgent
};
};

const tc = new ToughClicks(
token,
packetId,
false,
'production',
undefined, // packetDisplayOptions
getPageContext
);

TCInternalError​

Error object passed to tc-internal-error event handler.

interface TCInternalError {
message: string;
code?: string;
details?: any;
}

Fields​

FieldTypeDescription
messagestringHuman-readable error message
codestringError code (if available)
detailsanyAdditional error details

Example​

tc.on('tc-internal-error', (error: TCInternalError) => {
console.error('ToughClicks error:', error.message);

if (error.code) {
console.error('Error code:', error.code);
}

// Report to error tracking service
Sentry.captureException(new Error(error.message), {
extra: error.details
});
});

Using Types in TypeScript​

Import and use types in your TypeScript projects:

import {
ToughClicks,
TCDisplayOptions,
TCPacketDisplayOptions,
TCDisplayMethod,
TCEnvironment,
TCEventTypes,
TCMultiPacketState,
TCVerificationResponse
} from '@toughclicks/js-client-sdk';

// Typed variables
const options: TCDisplayOptions = {
containerId: 'tc-container',
signerId: 'user@example.com',
displayMethod: TCDisplayMethod.individual,
shouldOpenModal: true,
manualAcceptance: false
};

// Typed event handler
tc.on('tc-valid', (state: TCMultiPacketState) => {
if (state.allPacketsValid) {
console.log('All packets are valid!');
}
});

// Typed async function
const verifyUser = async (userId: string): Promise<boolean> => {
const results: TCVerificationResponse[] = await tc.verify(userId);
return results.every(r => r.userCompliant && !r.verificationFailed);
};

Next Steps​