@surbee/cipher 0.1.0 → 0.2.0

package/dist/types-C8t_T3bP.d.mts

@@ -0,0 +1,251 @@
+/**
+ * Cipher SDK Types
+ *
+ * Core type definitions for the Cipher response validation system.
+ * Implementation details are hidden - the SDK communicates with Surbee's
+ * secure validation engine.
+ */
+type CipherTier = 1 | 2 | 3 | 4 | 5;
+type CheckId = 'rapid_completion' | 'uniform_timing' | 'low_interaction' | 'straight_line_answers' | 'impossibly_fast' | 'minimal_effort' | 'excessive_paste' | 'pointer_spikes' | 'webdriver_detected' | 'automation_detected' | 'no_plugins' | 'suspicious_user_agent' | 'device_fingerprint_mismatch' | 'screen_anomaly' | 'suspicious_pauses' | 'robotic_typing' | 'mouse_teleporting' | 'no_corrections' | 'excessive_tab_switching' | 'window_focus_loss' | 'ai_content_basic' | 'contradiction_basic' | 'hover_behavior' | 'scroll_patterns' | 'mouse_acceleration' | 'vpn_detection' | 'datacenter_ip' | 'plagiarism_basic' | 'quality_assessment' | 'semantic_analysis' | 'ai_content_full' | 'contradiction_full' | 'plagiarism_full' | 'fraud_ring_detection' | 'answer_sharing' | 'coordinated_timing' | 'device_sharing' | 'tor_detection' | 'proxy_detection' | 'timezone_validation' | 'baseline_deviation' | 'perplexity_analysis' | 'burstiness_analysis';
+interface CheckResult {
+    /** The check that was run */
+    checkId: CheckId;
+    /** Whether the check passed */
+    passed: boolean;
+    /** Suspicion score (0-1, higher = more suspicious) */
+    score: number;
+    /** Human-readable details */
+    details?: string;
+    /** Structured diagnostic data behind the score (shape varies per check) */
+    data?: Record<string, unknown>;
+}
+interface ResponseInput {
+    /** The question text */
+    question: string;
+    /** The user's answer */
+    answer: string;
+    /** Question type for context */
+    questionType?: 'text' | 'multiple_choice' | 'rating' | 'scale' | 'boolean';
+    /** Time spent on this question in milliseconds */
+    responseTimeMs?: number;
+    /** Question index in the survey */
+    questionIndex?: number;
+}
+interface ValidationInput {
+    /** Array of question/answer pairs */
+    responses: ResponseInput[];
+    /** Behavioral metrics from client-side tracking */
+    behavioralMetrics?: BehavioralMetrics;
+    /** Device/browser information */
+    deviceInfo?: DeviceInfo;
+    /** Survey context */
+    context?: SurveyContext;
+}
+interface SurveyContext {
+    /** Survey ID for cross-respondent analysis */
+    surveyId?: string;
+    /** Expected completion time in seconds */
+    expectedDurationSeconds?: number;
+    /** Actual completion time in seconds */
+    actualDurationSeconds?: number;
+    /** Survey type for context-aware analysis */
+    surveyType?: 'nps' | 'csat' | 'research' | 'feedback' | 'quiz';
+    /** Total number of questions */
+    totalQuestions?: number;
+}
+interface BehavioralMetrics {
+    sessionId: string;
+    startedAt: number;
+    duration: number;
+    lastActiveAt: number;
+    mouseMovements: MouseMovement[];
+    mouseClicks: MouseClick[];
+    mouseMovementCount: number;
+    avgMouseVelocity: number;
+    keystrokeDynamics: KeystrokeEvent[];
+    keypressCount: number;
+    backspaceCount: number;
+    avgKeystrokeDwell: number;
+    keystrokeVariance: number;
+    scrollEvents: ScrollEvent[];
+    scrollEventCount: number;
+    focusEvents: FocusEvent[];
+    tabSwitchCount: number;
+    totalBlurDuration: number;
+    pasteEvents: number;
+    copyEvents: number;
+    hoverEvents: HoverEvent[];
+    responseTime: number[];
+    questionStartTimes: Record<string, number>;
+}
+interface MouseMovement {
+    x: number;
+    y: number;
+    t: number;
+    velocity: number;
+}
+interface MouseClick {
+    x: number;
+    y: number;
+    t: number;
+    hadHover: boolean;
+}
+interface KeystrokeEvent {
+    key: string;
+    downAt: number;
+    upAt: number;
+    dwell: number;
+    flightTime: number;
+}
+interface ScrollEvent {
+    y: number;
+    t: number;
+    velocity: number;
+}
+interface FocusEvent {
+    type: 'focus' | 'blur' | 'hidden' | 'visible';
+    t: number;
+}
+interface HoverEvent {
+    element: string;
+    duration: number;
+    t: number;
+}
+interface DeviceInfo {
+    userAgent: string;
+    platform: string;
+    language: string;
+    languages: string[];
+    timezone: string;
+    timezoneOffset: number;
+    screenWidth: number;
+    screenHeight: number;
+    screenAvailWidth: number;
+    screenAvailHeight: number;
+    colorDepth: number;
+    pixelRatio: number;
+    touchSupport: boolean;
+    maxTouchPoints: number;
+    hardwareConcurrency: number;
+    deviceMemory: number;
+    cookiesEnabled: boolean;
+    webDriver: boolean;
+    automationDetected: boolean;
+    canvasFingerprint: string | null;
+    webglVendor: string | null;
+    webglRenderer: string | null;
+    pluginCount: number;
+    collectedAt: number;
+}
+interface ValidationResult {
+    /** Overall quality score (0-1, higher = better quality) */
+    score: number;
+    /** Whether the response passed validation */
+    passed: boolean;
+    /** Recommendation for the response */
+    recommendation: 'keep' | 'review' | 'discard';
+    /** Confidence in the assessment (0-1) */
+    confidence: number;
+    /** Flags that were triggered */
+    flags: string[];
+    /** Human-readable summary analysis */
+    summary: ValidationSummary;
+    /** Detailed check results */
+    checks: CheckResult[];
+    /** Processing metadata */
+    meta: ValidationMeta;
+}
+interface ValidationSummary {
+    /** Short verdict (e.g., "Likely legitimate", "Suspected bot") */
+    verdict: string;
+    /** List of issues found */
+    issues: string[];
+    /** List of positive signals */
+    positives: string[];
+    /** Actionable suggestion for the user */
+    suggestion: string;
+}
+interface ValidationMeta {
+    /** Tier used for validation */
+    tier: CipherTier;
+    /** Processing time in milliseconds */
+    processingTimeMs: number;
+    /** Number of checks run */
+    checksRun: number;
+    /** Number of checks passed */
+    checksPassed: number;
+    /** Request ID for support */
+    requestId: string;
+    /** Timestamp */
+    timestamp: number;
+}
+interface CipherConfig {
+    /**
+     * API key from Surbee dashboard (Settings > API Keys)
+     * Format: cipher_sk_...
+     *
+     * Optional only when `offline: true` — tier 1–2 checks run locally with no
+     * key. Online validation (tiers 3–5 / `validate()`) always requires a key.
+     */
+    apiKey?: string;
+    /**
+     * Validation tier (1-5)
+     * - Tier 1-2: Basic checks (~free)
+     * - Tier 3: Enhanced analysis
+     * - Tier 4: Advanced validation
+     * - Tier 5: Maximum accuracy
+     */
+    tier?: CipherTier;
+    /** Custom thresholds */
+    thresholds?: {
+        /** Score below this = fail (default: 0.4) */
+        fail?: number;
+        /** Score below this = review (default: 0.7) */
+        review?: number;
+    };
+    /** Enable debug logging */
+    debug?: boolean;
+    /**
+     * Run validation entirely on-device with no API calls. Only the offline
+     * checks for the selected tier are evaluated (AI-powered checks are skipped).
+     * Recommended for tiers 1–2, which are fully offline.
+     */
+    offline?: boolean;
+    /** Custom API endpoint (for enterprise/self-hosted) */
+    endpoint?: string;
+}
+interface BatchValidationInput {
+    submissions: ValidationInput[];
+    /** Enable cross-submission fraud detection (tier 5) */
+    crossAnalysis?: boolean;
+}
+interface BatchValidationResult {
+    results: ValidationResult[];
+    summary: {
+        total: number;
+        passed: number;
+        review: number;
+        failed: number;
+        avgScore: number;
+    };
+    /** Cross-submission fraud indicators (tier 5 only) */
+    fraudIndicators?: FraudIndicators;
+}
+interface FraudIndicators {
+    /** Response IDs with duplicate answers */
+    duplicateAnswers: string[];
+    /** Whether coordinated timing was detected */
+    coordinatedTiming: boolean;
+    /** Whether device sharing was detected */
+    deviceSharing: boolean;
+    /** Fraud ring score (0-1) */
+    fraudRingScore: number;
+}
+interface CipherError {
+    code: CipherErrorCode;
+    message: string;
+    details?: Record<string, unknown>;
+}
+type CipherErrorCode = 'INVALID_API_KEY' | 'RATE_LIMITED' | 'INSUFFICIENT_CREDITS' | 'INVALID_INPUT' | 'TIER_NOT_AVAILABLE' | 'SERVER_ERROR' | 'NETWORK_ERROR';
+
+export type { BatchValidationInput as B, CipherConfig as C, DeviceInfo as D, FraudIndicators as F, HoverEvent as H, KeystrokeEvent as K, MouseMovement as M, ResponseInput as R, SurveyContext as S, ValidationInput as V, ValidationResult as a, BatchValidationResult as b, CipherTier as c, CheckId as d, BehavioralMetrics as e, ValidationSummary as f, ValidationMeta as g, CheckResult as h, CipherError as i, CipherErrorCode as j, MouseClick as k, ScrollEvent as l, FocusEvent as m };

package/dist/types-C8t_T3bP.d.ts

@@ -0,0 +1,251 @@
+/**
+ * Cipher SDK Types
+ *
+ * Core type definitions for the Cipher response validation system.
+ * Implementation details are hidden - the SDK communicates with Surbee's
+ * secure validation engine.
+ */
+type CipherTier = 1 | 2 | 3 | 4 | 5;
+type CheckId = 'rapid_completion' | 'uniform_timing' | 'low_interaction' | 'straight_line_answers' | 'impossibly_fast' | 'minimal_effort' | 'excessive_paste' | 'pointer_spikes' | 'webdriver_detected' | 'automation_detected' | 'no_plugins' | 'suspicious_user_agent' | 'device_fingerprint_mismatch' | 'screen_anomaly' | 'suspicious_pauses' | 'robotic_typing' | 'mouse_teleporting' | 'no_corrections' | 'excessive_tab_switching' | 'window_focus_loss' | 'ai_content_basic' | 'contradiction_basic' | 'hover_behavior' | 'scroll_patterns' | 'mouse_acceleration' | 'vpn_detection' | 'datacenter_ip' | 'plagiarism_basic' | 'quality_assessment' | 'semantic_analysis' | 'ai_content_full' | 'contradiction_full' | 'plagiarism_full' | 'fraud_ring_detection' | 'answer_sharing' | 'coordinated_timing' | 'device_sharing' | 'tor_detection' | 'proxy_detection' | 'timezone_validation' | 'baseline_deviation' | 'perplexity_analysis' | 'burstiness_analysis';
+interface CheckResult {
+    /** The check that was run */
+    checkId: CheckId;
+    /** Whether the check passed */
+    passed: boolean;
+    /** Suspicion score (0-1, higher = more suspicious) */
+    score: number;
+    /** Human-readable details */
+    details?: string;
+    /** Structured diagnostic data behind the score (shape varies per check) */
+    data?: Record<string, unknown>;
+}
+interface ResponseInput {
+    /** The question text */
+    question: string;
+    /** The user's answer */
+    answer: string;
+    /** Question type for context */
+    questionType?: 'text' | 'multiple_choice' | 'rating' | 'scale' | 'boolean';
+    /** Time spent on this question in milliseconds */
+    responseTimeMs?: number;
+    /** Question index in the survey */
+    questionIndex?: number;
+}
+interface ValidationInput {
+    /** Array of question/answer pairs */
+    responses: ResponseInput[];
+    /** Behavioral metrics from client-side tracking */
+    behavioralMetrics?: BehavioralMetrics;
+    /** Device/browser information */
+    deviceInfo?: DeviceInfo;
+    /** Survey context */
+    context?: SurveyContext;
+}
+interface SurveyContext {
+    /** Survey ID for cross-respondent analysis */
+    surveyId?: string;
+    /** Expected completion time in seconds */
+    expectedDurationSeconds?: number;
+    /** Actual completion time in seconds */
+    actualDurationSeconds?: number;
+    /** Survey type for context-aware analysis */
+    surveyType?: 'nps' | 'csat' | 'research' | 'feedback' | 'quiz';
+    /** Total number of questions */
+    totalQuestions?: number;
+}
+interface BehavioralMetrics {
+    sessionId: string;
+    startedAt: number;
+    duration: number;
+    lastActiveAt: number;
+    mouseMovements: MouseMovement[];
+    mouseClicks: MouseClick[];
+    mouseMovementCount: number;
+    avgMouseVelocity: number;
+    keystrokeDynamics: KeystrokeEvent[];
+    keypressCount: number;
+    backspaceCount: number;
+    avgKeystrokeDwell: number;
+    keystrokeVariance: number;
+    scrollEvents: ScrollEvent[];
+    scrollEventCount: number;
+    focusEvents: FocusEvent[];
+    tabSwitchCount: number;
+    totalBlurDuration: number;
+    pasteEvents: number;
+    copyEvents: number;
+    hoverEvents: HoverEvent[];
+    responseTime: number[];
+    questionStartTimes: Record<string, number>;
+}
+interface MouseMovement {
+    x: number;
+    y: number;
+    t: number;
+    velocity: number;
+}
+interface MouseClick {
+    x: number;
+    y: number;
+    t: number;
+    hadHover: boolean;
+}
+interface KeystrokeEvent {
+    key: string;
+    downAt: number;
+    upAt: number;
+    dwell: number;
+    flightTime: number;
+}
+interface ScrollEvent {
+    y: number;
+    t: number;
+    velocity: number;
+}
+interface FocusEvent {
+    type: 'focus' | 'blur' | 'hidden' | 'visible';
+    t: number;
+}
+interface HoverEvent {
+    element: string;
+    duration: number;
+    t: number;
+}
+interface DeviceInfo {
+    userAgent: string;
+    platform: string;
+    language: string;
+    languages: string[];
+    timezone: string;
+    timezoneOffset: number;
+    screenWidth: number;
+    screenHeight: number;
+    screenAvailWidth: number;
+    screenAvailHeight: number;
+    colorDepth: number;
+    pixelRatio: number;
+    touchSupport: boolean;
+    maxTouchPoints: number;
+    hardwareConcurrency: number;
+    deviceMemory: number;
+    cookiesEnabled: boolean;
+    webDriver: boolean;
+    automationDetected: boolean;
+    canvasFingerprint: string | null;
+    webglVendor: string | null;
+    webglRenderer: string | null;
+    pluginCount: number;
+    collectedAt: number;
+}
+interface ValidationResult {
+    /** Overall quality score (0-1, higher = better quality) */
+    score: number;
+    /** Whether the response passed validation */
+    passed: boolean;
+    /** Recommendation for the response */
+    recommendation: 'keep' | 'review' | 'discard';
+    /** Confidence in the assessment (0-1) */
+    confidence: number;
+    /** Flags that were triggered */
+    flags: string[];
+    /** Human-readable summary analysis */
+    summary: ValidationSummary;
+    /** Detailed check results */
+    checks: CheckResult[];
+    /** Processing metadata */
+    meta: ValidationMeta;
+}
+interface ValidationSummary {
+    /** Short verdict (e.g., "Likely legitimate", "Suspected bot") */
+    verdict: string;
+    /** List of issues found */
+    issues: string[];
+    /** List of positive signals */
+    positives: string[];
+    /** Actionable suggestion for the user */
+    suggestion: string;
+}
+interface ValidationMeta {
+    /** Tier used for validation */
+    tier: CipherTier;
+    /** Processing time in milliseconds */
+    processingTimeMs: number;
+    /** Number of checks run */
+    checksRun: number;
+    /** Number of checks passed */
+    checksPassed: number;
+    /** Request ID for support */
+    requestId: string;
+    /** Timestamp */
+    timestamp: number;
+}
+interface CipherConfig {
+    /**
+     * API key from Surbee dashboard (Settings > API Keys)
+     * Format: cipher_sk_...
+     *
+     * Optional only when `offline: true` — tier 1–2 checks run locally with no
+     * key. Online validation (tiers 3–5 / `validate()`) always requires a key.
+     */
+    apiKey?: string;
+    /**
+     * Validation tier (1-5)
+     * - Tier 1-2: Basic checks (~free)
+     * - Tier 3: Enhanced analysis
+     * - Tier 4: Advanced validation
+     * - Tier 5: Maximum accuracy
+     */
+    tier?: CipherTier;
+    /** Custom thresholds */
+    thresholds?: {
+        /** Score below this = fail (default: 0.4) */
+        fail?: number;
+        /** Score below this = review (default: 0.7) */
+        review?: number;
+    };
+    /** Enable debug logging */
+    debug?: boolean;
+    /**
+     * Run validation entirely on-device with no API calls. Only the offline
+     * checks for the selected tier are evaluated (AI-powered checks are skipped).
+     * Recommended for tiers 1–2, which are fully offline.
+     */
+    offline?: boolean;
+    /** Custom API endpoint (for enterprise/self-hosted) */
+    endpoint?: string;
+}
+interface BatchValidationInput {
+    submissions: ValidationInput[];
+    /** Enable cross-submission fraud detection (tier 5) */
+    crossAnalysis?: boolean;
+}
+interface BatchValidationResult {
+    results: ValidationResult[];
+    summary: {
+        total: number;
+        passed: number;
+        review: number;
+        failed: number;
+        avgScore: number;
+    };
+    /** Cross-submission fraud indicators (tier 5 only) */
+    fraudIndicators?: FraudIndicators;
+}
+interface FraudIndicators {
+    /** Response IDs with duplicate answers */
+    duplicateAnswers: string[];
+    /** Whether coordinated timing was detected */
+    coordinatedTiming: boolean;
+    /** Whether device sharing was detected */
+    deviceSharing: boolean;
+    /** Fraud ring score (0-1) */
+    fraudRingScore: number;
+}
+interface CipherError {
+    code: CipherErrorCode;
+    message: string;
+    details?: Record<string, unknown>;
+}
+type CipherErrorCode = 'INVALID_API_KEY' | 'RATE_LIMITED' | 'INSUFFICIENT_CREDITS' | 'INVALID_INPUT' | 'TIER_NOT_AVAILABLE' | 'SERVER_ERROR' | 'NETWORK_ERROR';
+
+export type { BatchValidationInput as B, CipherConfig as C, DeviceInfo as D, FraudIndicators as F, HoverEvent as H, KeystrokeEvent as K, MouseMovement as M, ResponseInput as R, SurveyContext as S, ValidationInput as V, ValidationResult as a, BatchValidationResult as b, CipherTier as c, CheckId as d, BehavioralMetrics as e, ValidationSummary as f, ValidationMeta as g, CheckResult as h, CipherError as i, CipherErrorCode as j, MouseClick as k, ScrollEvent as l, FocusEvent as m };

package/package.json

@@ -1,22 +1,33 @@
 {
   "name": "@surbee/cipher",
-  "version": "0.1.0",
+  "version": "0.2.0",
   "description": "AI-powered survey response validation - detect fraud, bots, and low-quality responses",
   "main": "dist/index.js",
   "module": "dist/index.mjs",
   "types": "dist/index.d.ts",
+  "files": [
+    "dist"
+  ],
+  "sideEffects": false,
   "exports": {
     ".": {
       "types": "./dist/index.d.ts",
       "import": "./dist/index.mjs",
       "require": "./dist/index.js"
+    },
+    "./checks": {
+      "types": "./dist/checks/index.d.ts",
+      "import": "./dist/checks/index.mjs",
+      "require": "./dist/checks/index.js"
     }
   },
   "scripts": {
-    "build": "tsup src/index.ts --format cjs,esm --dts --clean",
-    "dev": "tsup src/index.ts --format cjs,esm --dts --watch",
+    "build": "tsup src/index.ts src/checks/index.ts --format cjs,esm --dts --clean",
+    "dev": "tsup src/index.ts src/checks/index.ts --format cjs,esm --dts --watch",
     "lint": "eslint src/",
-    "typecheck": "tsc --noEmit"
+    "typecheck": "tsc --noEmit",
+    "test": "tsx --test test/*.test.ts",
+    "prepublishOnly": "npm run build"
   },
   "keywords": [
     "survey",
@@ -37,6 +48,7 @@
   "devDependencies": {
     "@types/node": "^20.0.0",
     "tsup": "^8.0.0",
+    "tsx": "^4.21.0",
     "typescript": "^5.0.0"
   },
   "engines": {