@surbee/cipher 0.1.0 → 0.2.0

package/dist/index.d.mts

@@ -1,241 +1,5 @@
-/**
- * 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;
-}
-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_...
-     */
-    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;
-    /** 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';
+import { C as CipherConfig, V as ValidationInput, a as ValidationResult, B as BatchValidationInput, b as BatchValidationResult, c as CipherTier, d as CheckId } from './types-C8t_T3bP.mjs';
+export { e as BehavioralMetrics, h as CheckResult, i as CipherError, j as CipherErrorCode, D as DeviceInfo, m as FocusEvent, F as FraudIndicators, H as HoverEvent, K as KeystrokeEvent, k as MouseClick, M as MouseMovement, R as ResponseInput, l as ScrollEvent, S as SurveyContext, g as ValidationMeta, f as ValidationSummary } from './types-C8t_T3bP.mjs';
 
 /**
  * Cipher - AI-powered survey response validation
@@ -256,31 +20,61 @@ type CipherErrorCode = 'INVALID_API_KEY' | 'RATE_LIMITED' | 'INSUFFICIENT_CREDIT
  */
 declare class Cipher {
     private config;
-    constructor(config: CipherConfig);
+    constructor(config?: CipherConfig);
     /**
-     * Validate a single response
+     * Validate a single response.
+     *
+     * Runs locally when `offline: true`, otherwise calls Surbee's validation
+     * engine (which can run the AI-powered checks for tiers 3–5).
      */
     validate(input: ValidationInput): Promise<ValidationResult>;
     /**
-     * Validate multiple responses in batch
+     * Validate a single response synchronously, fully on-device.
+     *
+     * Only the offline checks for the configured tier are evaluated; AI-powered
+     * checks (tiers 3+) are skipped. No API key or network access required.
+     */
+    validateSync(input: ValidationInput): ValidationResult;
+    /**
+     * Validate multiple responses in batch.
+     *
+     * Runs locally when `offline: true`, otherwise calls Surbee's batch endpoint.
      */
     validateBatch(input: BatchValidationInput): Promise<BatchValidationResult>;
     /**
-     * Get tier information
+     * Run the offline checks that apply to the configured tier.
+     */
+    private runOfflineChecks;
+    /**
+     * Estimate the per-response API cost for a number of responses at the
+     * configured tier (tiers 1–2 are free).
+     */
+    estimateCost(responses?: number): number;
+    /**
+     * Get tier information, including the list of checks it runs.
      */
     getTierInfo(tier?: CipherTier): {
+        tier: CipherTier;
         name: string;
         description: string;
+        checks: CheckId[];
         checksCount: number;
+        aiModel: string | null;
+        offline: boolean;
+        estimatedCostPerResponse: number;
     };
     /**
      * Get all available tiers
      */
     getAllTiers(): {
+        tier: CipherTier;
         name: string;
         description: string;
+        checks: CheckId[];
         checksCount: number;
-        tier: CipherTier;
+        aiModel: string | null;
+        offline: boolean;
+        estimatedCostPerResponse: number;
     }[];
     /**
      * Check API key validity and credits
@@ -338,4 +132,4 @@ declare class Cipher {
 
 declare const VERSION = "0.1.0";
 
-export { type BatchValidationInput, type BatchValidationResult, type BehavioralMetrics, type CheckId, type CheckResult, Cipher, type CipherConfig, type CipherError, type CipherErrorCode, type CipherTier, type DeviceInfo, type FocusEvent, type FraudIndicators, type HoverEvent, type KeystrokeEvent, type MouseClick, type MouseMovement, type ResponseInput, type ScrollEvent, type SurveyContext, VERSION, type ValidationInput, type ValidationMeta, type ValidationResult, type ValidationSummary };
+export { BatchValidationInput, BatchValidationResult, CheckId, Cipher, CipherConfig, CipherTier, VERSION, ValidationInput, ValidationResult };

package/dist/index.d.ts

@@ -1,241 +1,5 @@
-/**
- * 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;
-}
-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_...
-     */
-    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;
-    /** 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';
+import { C as CipherConfig, V as ValidationInput, a as ValidationResult, B as BatchValidationInput, b as BatchValidationResult, c as CipherTier, d as CheckId } from './types-C8t_T3bP.js';
+export { e as BehavioralMetrics, h as CheckResult, i as CipherError, j as CipherErrorCode, D as DeviceInfo, m as FocusEvent, F as FraudIndicators, H as HoverEvent, K as KeystrokeEvent, k as MouseClick, M as MouseMovement, R as ResponseInput, l as ScrollEvent, S as SurveyContext, g as ValidationMeta, f as ValidationSummary } from './types-C8t_T3bP.js';
 
 /**
  * Cipher - AI-powered survey response validation
@@ -256,31 +20,61 @@ type CipherErrorCode = 'INVALID_API_KEY' | 'RATE_LIMITED' | 'INSUFFICIENT_CREDIT
  */
 declare class Cipher {
     private config;
-    constructor(config: CipherConfig);
+    constructor(config?: CipherConfig);
     /**
-     * Validate a single response
+     * Validate a single response.
+     *
+     * Runs locally when `offline: true`, otherwise calls Surbee's validation
+     * engine (which can run the AI-powered checks for tiers 3–5).
      */
     validate(input: ValidationInput): Promise<ValidationResult>;
     /**
-     * Validate multiple responses in batch
+     * Validate a single response synchronously, fully on-device.
+     *
+     * Only the offline checks for the configured tier are evaluated; AI-powered
+     * checks (tiers 3+) are skipped. No API key or network access required.
+     */
+    validateSync(input: ValidationInput): ValidationResult;
+    /**
+     * Validate multiple responses in batch.
+     *
+     * Runs locally when `offline: true`, otherwise calls Surbee's batch endpoint.
      */
     validateBatch(input: BatchValidationInput): Promise<BatchValidationResult>;
     /**
-     * Get tier information
+     * Run the offline checks that apply to the configured tier.
+     */
+    private runOfflineChecks;
+    /**
+     * Estimate the per-response API cost for a number of responses at the
+     * configured tier (tiers 1–2 are free).
+     */
+    estimateCost(responses?: number): number;
+    /**
+     * Get tier information, including the list of checks it runs.
      */
     getTierInfo(tier?: CipherTier): {
+        tier: CipherTier;
         name: string;
         description: string;
+        checks: CheckId[];
         checksCount: number;
+        aiModel: string | null;
+        offline: boolean;
+        estimatedCostPerResponse: number;
     };
     /**
      * Get all available tiers
      */
     getAllTiers(): {
+        tier: CipherTier;
         name: string;
         description: string;
+        checks: CheckId[];
         checksCount: number;
-        tier: CipherTier;
+        aiModel: string | null;
+        offline: boolean;
+        estimatedCostPerResponse: number;
     }[];
     /**
      * Check API key validity and credits
@@ -338,4 +132,4 @@ declare class Cipher {
 
 declare const VERSION = "0.1.0";
 
-export { type BatchValidationInput, type BatchValidationResult, type BehavioralMetrics, type CheckId, type CheckResult, Cipher, type CipherConfig, type CipherError, type CipherErrorCode, type CipherTier, type DeviceInfo, type FocusEvent, type FraudIndicators, type HoverEvent, type KeystrokeEvent, type MouseClick, type MouseMovement, type ResponseInput, type ScrollEvent, type SurveyContext, VERSION, type ValidationInput, type ValidationMeta, type ValidationResult, type ValidationSummary };
+export { BatchValidationInput, BatchValidationResult, CheckId, Cipher, CipherConfig, CipherTier, VERSION, ValidationInput, ValidationResult };