@trustsig/types

TypeScript types for the TrustSig SDK: the verdict your server receives, the options each package takes, and the TrustSig Pro API shapes.

You rarely need to install this yourself. @trustsig/server re-exports all of it, and @trustsig/client and @trustsig/react depend on it. Install it directly to share TrustSig types between services, to type your own tooling against the TrustSig API, or to import TrustSigEnv in a frontend.

npm install @trustsig/types

Everything here is a type except the TrustSigEnv enum. Nothing touches window; window.TrustSig is declared by @trustsig/client.

Usage

import type { BotAnalysisResponse } from '@trustsig/types';

export function auditRecord(verdict: BotAnalysisResponse) {
  return {
    action: verdict.action,
    risk: verdict.risk?.score,
    device: verdict.identity?.device_id,
    reasons: verdict.risk?.reason_codes ?? [],
  };
}

import { TrustSigClient } from '@trustsig/client';
import { TrustSigEnv } from '@trustsig/types';

const trustsig = new TrustSigClient({ siteKey, env: TrustSigEnv.STAGING });

| Import | Contents | | --- | --- | | @trustsig/types | Everything, including the Pro types. | | @trustsig/types/pro | Pro types only. |

Core types

| Type | Description | | --- | --- | | TrustSigEnv | Enum: PROD, STAGING, DEV. | | TrustSigAction | 'ALLOW' \| 'CHALLENGE' \| 'BLOCK'. | | BotAnalysisResponse | The verdict verifyRemote returns. | | TrustSigErrorCode | TOKEN_MISSING, API_FAIL, MALFORMED_RESPONSE. TOKEN_EXPIRED, TOKEN_REUSED, and CRYPTO_FAIL remain in the union but are no longer produced. | | TrustSigOptions, TrustSigVerifyOptions | Options for new TrustSig() and verifyRemote(). | | TrustSigInclude, TrustSigDetailGroup | Values for the include option. | | TrustSigResponse | { request_id, token }, what the browser SDK hands you. | | TrustSigFlushOptions, TrustSigBehaviorHandle | Options for flushMouse and the value onBehaviorReady receives. | | BehaviorResponse | What getBehavior returns: TrustSigBehaviorResult and TrustSigBehaviorDevice. | | TrustSigScanResult, TrustSigGlobal | The raw script result and the shape of window.TrustSig. |

Verdict blocks

BotAnalysisResponse keeps action, is_bot, score, and issued_at stable on every account. The rest of the verdict sits in named blocks, all optional because accounts on the legacy contract receive none of them.

| Field | Type | Contents | | --- | --- | --- | | risk | TrustSigRisk | Continuous score, TrustSigRiskLevel, reason_codes, revision counters. | | identity | TrustSigIdentity | device_id, confidence, degraded, first and last sighting. | | device | TrustSigDevice | What the browser reported, split into screen, hardware, locale, and further groups. | | network | TrustSigNetwork | Location, connection_type, VPN, Tor, datacenter, and mobile flags, TLS. | | integrity | TrustSigIntegrity | Automation, anti-detect browser, tampering, and spoofing findings. | | behavior | TrustSigBehavior | mouse, the pointer-movement verdict. | | velocity | TrustSigVelocity | How often the device was seen in fixed windows. | | flags | TrustSigFlags | Flat booleans for one-line checks. |

Most device and network fields arrive only when requested with include. Each field's doc comment names the group that carries it.

An unmeasured field holds its type's zero (0, '', []). TrustSigDevice, TrustSigNetwork, TrustSigIdentity, TrustSigVelocity, and TrustSigSpoofing carry a measured map saying which values are real readings. The @trustsig/server README describes every field.

Reason codes

TrustSigReasonCode lists every code this release knows, and also accepts any string, so a code TrustSig adds later is never a type error and editors still autocomplete the known ones. TrustSigReasonCodeGroup names the groups: automation, integrity, environment, behavior, challenge, velocity, reputation, network, device, trust, token. Only trust holds positive findings. TrustSigReasonCodeCatalog and TrustSigReasonCodeDoc type the catalogue served at GET /api/v1/meta/reason-codes.

Pro types

Pro decisions are ProDecision ('ALLOW' | 'REVIEW' | 'BLOCK'), not TrustSigAction. Pro keys identify the project, so no Pro type carries a project id.

| Area | Types | | --- | --- | | Decisions and errors | ProDecision, ProErrorCode, ProCredentialScope | | Options | ProOptions, ProClientOptions, ProSessionStorage | | Verify | ProVerifyInput, ProVerifyResponse, ProClientResponse | | Events | ProEventKind, ProEventInput, ProEventVerdict, ProEventVelocity, ProReasonDetail | | Interactions | ProInteractionInput, ProInteractionsResponse | | Identity | ProIdentityConfidence, ProAccountTraits, ProDeviceJoin | | Verdict details | ProEnrichment, ProNamedSignals, ProBehavior, ProMouseBehavior, ProSpoof | | Duplicate accounts | ProAltVerdict, ProAltAccount, ProAltLink | | Request binding | ProRequestContext, ProTlsContext, ProBindingReport, ProBindingVerdict | | Action proofs | ProChallenge, ProChallengeOptions, ProProofResult, ProProofFailure, ProVerifyProofOptions | | Devices | ProEntity, ProEntityAccount, ProEntityAccountsResponse, ProEntityMouse, ProEntitySpoof, ProMouseSession, ProLinkageRun | | Rules | ProRule, ProRuleAction, ProRuleState, ProRulesVersion, ProRulesView | | Reputation and labels | ProReputationKind, ProReputationStatus, ProLabelReportKind, ProLabelValue, ProLabelSubjectType | | Telegram Mini Apps | ProTelegramInitData, ProTelegramVerification | | Operations | ProUsage, ProAnalyticsView, ProWebhookEvent, ProEngine, ProEnforcement, ProTrainingStatus |

Fields added after your release

BotAnalysisResponse, ProVerifyResponse, ProEventVerdict, and every verdict block carry an index signature, and the server SDK passes unknown response fields through. A field TrustSig adds is readable before this package declares it, typed as unknown:

const region = verdict.network?.some_new_field as string | undefined;

Related packages

• @trustsig/server: verify tokens on your server
• @trustsig/client: browser SDK
• @trustsig/react: React provider and hooks
• GitHub repository and issues

MIT licensed.