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
| Field | Type | Required | Description |
|---|---|---|---|
containerId | string | No | HTML element ID where UI will be rendered |
signerIdSelector | string | null | Either this or signerId | ID of input element to monitor for signer identifier |
signerId | string | null | Either this or signerIdSelector | Direct signer identifier value |
displayMethod | TCDisplayMethod | null | No | How to display documents (individual, group, scroll, buttonAssent) |
shouldOpenModal | boolean | null | No | Open document terms in modal (true) or new tab (false) |
manualAcceptance | boolean | No | Require manual accept() call (default: false) |
optional | boolean | No | Mark packet as optional (default: false). Rejected when displayMethod is buttonAssent |
assentActionLabel | string | Required for buttonAssent | Label of your submit button, named in the notice |
assentActionSelector | string | No | CSS 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
| Field | Type | Description |
|---|---|---|
packetId | string | The packet ID this configuration applies to |
displayOptions | TCDisplayOptions | Display 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
| Value | Description |
|---|---|
individual | Separate checkbox for each document |
group | Single checkbox for all documents in packet |
scroll | Scrollable container that must be scrolled to bottom |
buttonAssent | Notice 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
| Value | Description |
|---|---|
production | Production environment (default) |
staging | Staging/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
| Value | Description |
|---|---|
'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
| Field | Type | Description |
|---|---|---|
isValid | boolean | Whether all required validations pass |
allAccepted | boolean | Whether all documents are accepted |
signerId | string | null | Current signer identifier |
packetId | string | The 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
| Field | Type | Description |
|---|---|---|
allPacketsValid | boolean | Whether all required packets are valid |
allPacketsAccepted | boolean | Whether all checked packets are accepted |
packets | object | Per-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
| Field | Type | Description |
|---|---|---|
id | string | The packet ID that was verified |
displayName | string | The packet's display name. Empty when verificationFailed is true |
documents | array | Verification details for each document in the packet. Empty when verificationFailed is true |
userCompliant | boolean | Whether the user has accepted the latest version of every document in the packet. Also true when verificationFailed is true (see below) |
verificationFailed | boolean | true when the library could not get an answer from the API, so userCompliant is a placeholder rather than a real result |
Document Fields
| Field | Type | Description |
|---|---|---|
id | string | The document ID |
displayName | string | The document's display name |
latestVersion | string | The document's current version |
latestAgreement | string | The 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
| Field | Type | Description |
|---|---|---|
message | string | Human-readable error message |
code | string | Error code (if available) |
details | any | Additional 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
- Review API Reference Overview
- Learn about Events
- Explore Display Options