SDK Reference

import { init } from '@toffee/sdk'

const toffee = init({
  apiKey: 'YOUR_API_KEY',
  endpoint: 'https://api.toffee.at',
  onDetection: (result) => console.log(result),
})

toffee.identify({ userId: 'user-123', plan: 'pro' })

const result = toffee.getDetection()
if (result?.isAgent) {
  console.log('Bot detected:', result.riskTier)
}

toffee.destroy()

import { identify } from '@toffee/sdk'

identify({ userId: 'user-123' })

import { getDetection } from '@toffee/sdk'

const result = getDetection()

interface ToffeeConfig {
  /** Your site API key (required) */
  apiKey: string

  /** Site ID — usually inferred from the API key */
  siteId?: string

  /** API endpoint URL. Default: '/api/v1/events' */
  endpoint?: string

  /** Called every time the detection probability updates */
  onDetection?: (result: DetectionOutput) => void

  /** Log detection info to the browser console. Default: false */
  debug?: boolean
}

interface ToffeeInstance {
  /** Start detection (called automatically by init) */
  start: () => void

  /** Attach custom properties to the session */
  identify: (properties: Record<string, string>) => void

  /** Get the current detection result, or null */
  getDetection: () => DetectionOutput | null

  /** Tear down listeners, flush events, clean up */
  destroy: () => void
}

interface DetectionOutput {
  /** Legacy score (0–100) */
  score: number

  /** Calibrated probability (0.0–1.0) */
  probability: number

  /** Risk tier derived from probability */
  riskTier: RiskTier

  /** true if probability >= 0.50 */
  isAgent: boolean

  /** Per-detector results */
  results: DetectorResult[]

  /** ML model classification (when available) */
  classification: ModelClassification
}

type RiskTier =
  | 'definite-bot'    // probability >= 0.95
  | 'likely-bot'      // probability >= 0.80
  | 'suspicious'      // probability >= 0.50
  | 'likely-human'    // probability >= 0.20
  | 'definite-human'  // probability < 0.20

interface ModelClassification {
  /** Final classification */
  classification: 'human' | 'bot' | 'agent'

  /** Confidence probabilities */
  probabilities: {
    human: number
    bot: number
    agent: number
  }

  /** Whether this came from the ML model or heuristics */
  source: 'model' | 'heuristic'
}

interface DetectorResult {
  /** Which detector produced this result */
  detector: DetectorName

  /** Raw score from this detector (0–100) */
  rawScore: number

  /** Signals that fired */
  signals: string[]
}

type DetectorName =
  | 'user-agent'
  | 'headless'
  | 'automation'
  | 'behavioral'
  | 'navigator'
  | 'fingerprint'