@surbee/cipher

AI-powered survey response validation — detect bots, fraud, AI-generated text, and low-quality responses. Score a response anywhere you collect it, not just inside Surbee.

pnpm add @surbee/cipher

Quick start

import { Cipher } from '@surbee/cipher';

const cipher = new Cipher({
  apiKey: process.env.CIPHER_API_KEY, // cipher_sk_...
  tier: 4,                            // 1–5, higher = more checks
});

const result = await cipher.validate({
  responses: [
    { question: 'Would you recommend us?', answer: 'Yes' },
  ],
  behavioralMetrics: tracker.getMetrics(), // optional
  deviceInfo: tracker.getDeviceInfo(),     // optional
});

result.score;          // 0–1 (higher = better quality)
result.recommendation; // 'keep' | 'review' | 'discard'
result.flags;          // names of checks that fired

Offline mode (tiers 1–2)

Tiers 1 and 2 run fully on-device — no API key, no network. Only the offline checks for the tier are evaluated (AI-powered checks stay server-side).

const cipher = new Cipher({ tier: 2, offline: true }); // no apiKey needed

const result = cipher.validateSync({
  responses: [{ question: 'Rate us', answer: '4', questionType: 'rating' }],
  deviceInfo: tracker.getDeviceInfo(),
});

The decision engine combines failed checks with a noisy-OR, so a single high-confidence signal (a webdriver flag, straight-lining) is enough to flag a response — it is never averaged away by the checks that passed.

Tiers

| Tier | Name | Mode | Notes | | ---- | -------- | ---------------- | --------------------------------------- | | 1 | Basic | offline, free | Behavioral heuristics | | 2 | Standard | offline, free | + device fingerprinting / automation | | 3 | Enhanced | online | + AI content quality | | 4 | Advanced | online | + network + semantic analysis | | 5 | Maximum | online | + cross-respondent fraud-ring detection |

API

• new Cipher(config) — { apiKey?, tier?, thresholds?, offline?, debug?, endpoint? }
• validate(input) — score one response (local when offline, else via API)
• validateSync(input) — synchronous, on-device scoring
• validateBatch({ submissions, crossAnalysis? }) — score many at once
• getTierInfo(tier?) / getAllTiers() — tier metadata and check lists
• estimateCost(responses?) — per-tier cost estimate (0 for tiers 1–2)
• checkStatus() — verify an API key and remaining credits

Individual checks are importable for custom pipelines:

import { checkWebDriverDetected, checkStraightLining } from '@surbee/cipher/checks';

Result shape

{
  score: number,                 // 0–1
  passed: boolean,
  recommendation: 'keep' | 'review' | 'discard',
  confidence: number,            // 0–1
  flags: string[],               // human-readable names of failed checks
  summary: { verdict, issues, positives, suggestion },
  checks: CheckResult[],         // per-check breakdown
  meta: { tier, processingTimeMs, checksRun, checksPassed, requestId, timestamp },
}

License

MIT