@surbee/cipher 0.1.0 → 0.2.0

package/dist/index.mjs

@@ -1,64 +1,625 @@
-// src/cipher.ts
-var DEFAULT_CONFIG = {
-  tier: 3,
-  thresholds: {
-    fail: 0.4,
-    review: 0.7
+import {
+  runBehavioralChecks,
+  runContentChecks,
+  runDeviceChecks,
+  runTimingChecks
+} from "./chunk-P2MIOVFQ.mjs";
+
+// src/tiers.ts
+var CHECKS = {
+  // ============================================
+  // TIER 1 - Basic Behavioral (Offline)
+  // ============================================
+  rapid_completion: {
+    id: "rapid_completion",
+    name: "Rapid Completion",
+    description: "Detects impossibly fast survey completion",
+    tier: 1,
+    category: "behavioral",
+    offline: true
   },
-  debug: false,
-  endpoint: "https://api.surbee.com/v1/cipher"
+  uniform_timing: {
+    id: "uniform_timing",
+    name: "Uniform Timing",
+    description: "Detects robotic consistent response times",
+    tier: 1,
+    category: "behavioral",
+    offline: true
+  },
+  low_interaction: {
+    id: "low_interaction",
+    name: "Low Interaction",
+    description: "Detects minimal mouse/keyboard activity",
+    tier: 1,
+    category: "behavioral",
+    offline: true
+  },
+  straight_line_answers: {
+    id: "straight_line_answers",
+    name: "Straight-Lining",
+    description: "Detects selecting same option repeatedly",
+    tier: 1,
+    category: "content",
+    offline: true
+  },
+  impossibly_fast: {
+    id: "impossibly_fast",
+    name: "Speed Reading",
+    description: "Detects reading faster than humanly possible",
+    tier: 1,
+    category: "timing",
+    offline: true
+  },
+  minimal_effort: {
+    id: "minimal_effort",
+    name: "Minimal Effort",
+    description: "Detects very short or low-quality text responses",
+    tier: 1,
+    category: "content",
+    offline: true
+  },
+  // ============================================
+  // TIER 2 - Device/Automation (Offline)
+  // ============================================
+  excessive_paste: {
+    id: "excessive_paste",
+    name: "Excessive Paste",
+    description: "Detects heavy copy-paste behavior",
+    tier: 2,
+    category: "behavioral",
+    offline: true
+  },
+  pointer_spikes: {
+    id: "pointer_spikes",
+    name: "Pointer Velocity Spikes",
+    description: "Detects unnatural mouse movement patterns",
+    tier: 2,
+    category: "behavioral",
+    offline: true
+  },
+  webdriver_detected: {
+    id: "webdriver_detected",
+    name: "WebDriver Detection",
+    description: "Detects Selenium/automation tools",
+    tier: 2,
+    category: "device",
+    offline: true
+  },
+  automation_detected: {
+    id: "automation_detected",
+    name: "Automation Detection",
+    description: "Detects headless browsers and bots",
+    tier: 2,
+    category: "device",
+    offline: true
+  },
+  no_plugins: {
+    id: "no_plugins",
+    name: "Missing Plugins",
+    description: "Detects suspicious browser configurations",
+    tier: 2,
+    category: "device",
+    offline: true
+  },
+  suspicious_user_agent: {
+    id: "suspicious_user_agent",
+    name: "Suspicious User Agent",
+    description: "Detects bot-like user agent strings",
+    tier: 2,
+    category: "device",
+    offline: true
+  },
+  device_fingerprint_mismatch: {
+    id: "device_fingerprint_mismatch",
+    name: "Device Mismatch",
+    description: "Detects inconsistent device characteristics",
+    tier: 2,
+    category: "device",
+    offline: true
+  },
+  screen_anomaly: {
+    id: "screen_anomaly",
+    name: "Screen Anomaly",
+    description: "Detects impossible screen dimensions",
+    tier: 2,
+    category: "device",
+    offline: true
+  },
+  suspicious_pauses: {
+    id: "suspicious_pauses",
+    name: "Suspicious Pauses",
+    description: "Detects unusual gaps in activity",
+    tier: 2,
+    category: "timing",
+    offline: true
+  },
+  // ============================================
+  // TIER 3 - Enhanced Behavioral + Light AI
+  // ============================================
+  robotic_typing: {
+    id: "robotic_typing",
+    name: "Robotic Typing",
+    description: "Detects uniform keystroke timing",
+    tier: 3,
+    category: "behavioral",
+    offline: true
+  },
+  mouse_teleporting: {
+    id: "mouse_teleporting",
+    name: "Mouse Teleporting",
+    description: "Detects large instant mouse jumps",
+    tier: 3,
+    category: "behavioral",
+    offline: true
+  },
+  no_corrections: {
+    id: "no_corrections",
+    name: "No Corrections",
+    description: "Detects perfect typing with no backspaces",
+    tier: 3,
+    category: "behavioral",
+    offline: true
+  },
+  excessive_tab_switching: {
+    id: "excessive_tab_switching",
+    name: "Tab Switching",
+    description: "Detects frequent tab/window changes",
+    tier: 3,
+    category: "content",
+    offline: true
+  },
+  window_focus_loss: {
+    id: "window_focus_loss",
+    name: "Focus Loss",
+    description: "Detects extended periods away from survey",
+    tier: 3,
+    category: "content",
+    offline: true
+  },
+  ai_content_basic: {
+    id: "ai_content_basic",
+    name: "AI Content (Basic)",
+    description: "Light AI-generated text detection",
+    tier: 3,
+    category: "ai",
+    offline: false
+  },
+  contradiction_basic: {
+    id: "contradiction_basic",
+    name: "Contradiction (Basic)",
+    description: "Basic response consistency check",
+    tier: 3,
+    category: "ai",
+    offline: false
+  },
+  // ============================================
+  // TIER 4 - Advanced Analysis
+  // ============================================
+  hover_behavior: {
+    id: "hover_behavior",
+    name: "Hover Patterns",
+    description: "Analyzes mouse hover behavior before clicks",
+    tier: 4,
+    category: "behavioral",
+    offline: true
+  },
+  scroll_patterns: {
+    id: "scroll_patterns",
+    name: "Scroll Patterns",
+    description: "Analyzes reading/scrolling behavior",
+    tier: 4,
+    category: "behavioral",
+    offline: true
+  },
+  mouse_acceleration: {
+    id: "mouse_acceleration",
+    name: "Mouse Acceleration",
+    description: "Analyzes natural mouse acceleration",
+    tier: 4,
+    category: "behavioral",
+    offline: true
+  },
+  vpn_detection: {
+    id: "vpn_detection",
+    name: "VPN Detection",
+    description: "Detects VPN/proxy usage",
+    tier: 4,
+    category: "network",
+    offline: false
+  },
+  datacenter_ip: {
+    id: "datacenter_ip",
+    name: "Datacenter IP",
+    description: "Detects cloud/datacenter IPs",
+    tier: 4,
+    category: "network",
+    offline: false
+  },
+  plagiarism_basic: {
+    id: "plagiarism_basic",
+    name: "Plagiarism (Basic)",
+    description: "Quick check for copied content",
+    tier: 4,
+    category: "ai",
+    offline: false
+  },
+  quality_assessment: {
+    id: "quality_assessment",
+    name: "Quality Assessment",
+    description: "AI assessment of response quality",
+    tier: 4,
+    category: "ai",
+    offline: false
+  },
+  semantic_analysis: {
+    id: "semantic_analysis",
+    name: "Semantic Analysis",
+    description: "AI analysis of response meaning",
+    tier: 4,
+    category: "ai",
+    offline: false
+  },
+  // ============================================
+  // TIER 5 - Maximum (Opus 4.5)
+  // ============================================
+  ai_content_full: {
+    id: "ai_content_full",
+    name: "AI Content (Full)",
+    description: "Comprehensive AI-generated text detection",
+    tier: 5,
+    category: "ai",
+    offline: false
+  },
+  contradiction_full: {
+    id: "contradiction_full",
+    name: "Contradiction (Full)",
+    description: "Deep semantic contradiction analysis",
+    tier: 5,
+    category: "ai",
+    offline: false
+  },
+  plagiarism_full: {
+    id: "plagiarism_full",
+    name: "Plagiarism (Full)",
+    description: "Comprehensive plagiarism detection",
+    tier: 5,
+    category: "ai",
+    offline: false
+  },
+  fraud_ring_detection: {
+    id: "fraud_ring_detection",
+    name: "Fraud Ring",
+    description: "Detects coordinated fraud attempts",
+    tier: 5,
+    category: "ai",
+    offline: false
+  },
+  answer_sharing: {
+    id: "answer_sharing",
+    name: "Answer Sharing",
+    description: "Detects identical answers across respondents",
+    tier: 5,
+    category: "ai",
+    offline: false
+  },
+  coordinated_timing: {
+    id: "coordinated_timing",
+    name: "Coordinated Timing",
+    description: "Detects synchronized submissions",
+    tier: 5,
+    category: "ai",
+    offline: false
+  },
+  device_sharing: {
+    id: "device_sharing",
+    name: "Device Sharing",
+    description: "Detects same device across respondents",
+    tier: 5,
+    category: "ai",
+    offline: false
+  },
+  tor_detection: {
+    id: "tor_detection",
+    name: "Tor Detection",
+    description: "Detects Tor exit node IPs",
+    tier: 5,
+    category: "network",
+    offline: false
+  },
+  proxy_detection: {
+    id: "proxy_detection",
+    name: "Proxy Detection",
+    description: "Detects proxy server usage",
+    tier: 5,
+    category: "network",
+    offline: false
+  },
+  timezone_validation: {
+    id: "timezone_validation",
+    name: "Timezone Validation",
+    description: "Validates timezone consistency",
+    tier: 5,
+    category: "network",
+    offline: true
+  },
+  baseline_deviation: {
+    id: "baseline_deviation",
+    name: "Baseline Deviation",
+    description: "Compares against established behavioral baseline",
+    tier: 5,
+    category: "ai",
+    offline: false
+  },
+  perplexity_analysis: {
+    id: "perplexity_analysis",
+    name: "Perplexity Analysis",
+    description: "Statistical text predictability analysis",
+    tier: 5,
+    category: "ai",
+    offline: false
+  },
+  burstiness_analysis: {
+    id: "burstiness_analysis",
+    name: "Burstiness Analysis",
+    description: "Sentence length variation analysis",
+    tier: 5,
+    category: "ai",
+    offline: false
+  }
 };
-var TIER_INFO = {
+var TIERS = {
   1: {
     name: "Basic",
-    description: "Essential fraud detection with behavioral heuristics",
-    checksCount: 6
+    description: "Essential fraud detection with behavioral heuristics. Free, fully offline.",
+    checks: {
+      behavioral: ["rapid_completion", "uniform_timing", "low_interaction"],
+      timing: ["impossibly_fast"],
+      device: [],
+      content: ["straight_line_answers", "minimal_effort"],
+      network: [],
+      ai: []
+    },
+    aiModel: null,
+    offline: true,
+    estimatedCostPerResponse: 0
   },
   2: {
     name: "Standard",
-    description: "Adds device fingerprinting and automation detection",
-    checksCount: 15
+    description: "Adds device fingerprinting and automation detection. Free, fully offline.",
+    checks: {
+      behavioral: ["rapid_completion", "uniform_timing", "low_interaction", "excessive_paste", "pointer_spikes"],
+      timing: ["impossibly_fast", "suspicious_pauses"],
+      device: ["webdriver_detected", "automation_detected", "no_plugins", "suspicious_user_agent", "device_fingerprint_mismatch", "screen_anomaly"],
+      content: ["straight_line_answers", "minimal_effort"],
+      network: [],
+      ai: []
+    },
+    aiModel: null,
+    offline: true,
+    estimatedCostPerResponse: 0
   },
   3: {
     name: "Enhanced",
-    description: "Adds AI-powered content quality analysis",
-    checksCount: 22
+    description: "Adds Claude Sonnet 4.5 for content quality analysis. ~$0.003 per response.",
+    checks: {
+      behavioral: ["rapid_completion", "uniform_timing", "low_interaction", "excessive_paste", "pointer_spikes", "robotic_typing", "mouse_teleporting", "no_corrections"],
+      timing: ["impossibly_fast", "suspicious_pauses"],
+      device: ["webdriver_detected", "automation_detected", "no_plugins", "suspicious_user_agent", "device_fingerprint_mismatch", "screen_anomaly"],
+      content: ["straight_line_answers", "minimal_effort", "excessive_tab_switching", "window_focus_loss"],
+      network: [],
+      ai: ["ai_content_basic", "contradiction_basic"]
+    },
+    aiModel: "claude-sonnet-4-5-20250514",
+    offline: false,
+    estimatedCostPerResponse: 3e-3
   },
   4: {
     name: "Advanced",
-    description: "Full behavioral analysis with network validation",
-    checksCount: 30
+    description: "Full behavioral analysis + semantic AI. ~$0.01 per response.",
+    checks: {
+      behavioral: ["rapid_completion", "uniform_timing", "low_interaction", "excessive_paste", "pointer_spikes", "robotic_typing", "mouse_teleporting", "no_corrections", "hover_behavior", "scroll_patterns", "mouse_acceleration"],
+      timing: ["impossibly_fast", "suspicious_pauses"],
+      device: ["webdriver_detected", "automation_detected", "no_plugins", "suspicious_user_agent", "device_fingerprint_mismatch", "screen_anomaly"],
+      content: ["straight_line_answers", "minimal_effort", "excessive_tab_switching", "window_focus_loss"],
+      network: ["vpn_detection", "datacenter_ip"],
+      ai: ["ai_content_basic", "contradiction_basic", "plagiarism_basic", "quality_assessment", "semantic_analysis"]
+    },
+    aiModel: "claude-sonnet-4-5-20250514",
+    offline: false,
+    estimatedCostPerResponse: 0.01
   },
   5: {
     name: "Maximum",
-    description: "All 43 checks with cross-respondent fraud detection",
-    checksCount: 43
+    description: "All 40+ checks with Claude Opus 4.5. Maximum accuracy. ~$0.05 per response.",
+    checks: {
+      behavioral: ["rapid_completion", "uniform_timing", "low_interaction", "excessive_paste", "pointer_spikes", "robotic_typing", "mouse_teleporting", "no_corrections", "hover_behavior", "scroll_patterns", "mouse_acceleration"],
+      timing: ["impossibly_fast", "suspicious_pauses"],
+      device: ["webdriver_detected", "automation_detected", "no_plugins", "suspicious_user_agent", "device_fingerprint_mismatch", "screen_anomaly"],
+      content: ["straight_line_answers", "minimal_effort", "excessive_tab_switching", "window_focus_loss"],
+      network: ["vpn_detection", "datacenter_ip", "tor_detection", "proxy_detection", "timezone_validation"],
+      ai: ["ai_content_full", "contradiction_full", "plagiarism_full", "quality_assessment", "semantic_analysis", "fraud_ring_detection", "answer_sharing", "coordinated_timing", "device_sharing", "baseline_deviation", "perplexity_analysis", "burstiness_analysis"]
+    },
+    aiModel: "claude-opus-4-5-20250514",
+    offline: false,
+    estimatedCostPerResponse: 0.05
   }
 };
+function getChecksForTier(tier) {
+  const config = TIERS[tier];
+  return [
+    ...config.checks.behavioral,
+    ...config.checks.timing,
+    ...config.checks.device,
+    ...config.checks.content,
+    ...config.checks.network,
+    ...config.checks.ai
+  ];
+}
+function getOfflineChecksForTier(tier) {
+  return getChecksForTier(tier).filter((id) => CHECKS[id].offline);
+}
+function estimateCost(tier, responses) {
+  return TIERS[tier].estimatedCostPerResponse * responses;
+}
+
+// src/scoring.ts
+function checkName(checkId) {
+  return CHECKS[checkId]?.name ?? checkId;
+}
+function clamp01(n) {
+  return Math.max(0, Math.min(1, n));
+}
+function noisyOr(scores) {
+  return 1 - scores.reduce((product, s) => product * (1 - clamp01(s)), 1);
+}
+function offlineRequestId() {
+  return `req_local_${Math.random().toString(36).slice(2, 12)}`;
+}
+function buildSummary(checks, score, recommendation) {
+  const failed = checks.filter((c) => !c.passed);
+  let verdict;
+  if (score >= 0.85) verdict = "High-quality legitimate response";
+  else if (score >= 0.7) verdict = "Likely legitimate with minor concerns";
+  else if (score >= 0.5) verdict = "Borderline quality \u2014 manual review recommended";
+  else if (score >= 0.3) verdict = "Multiple issues detected \u2014 likely low quality";
+  else verdict = "Suspected fraudulent or bot response";
+  const issues = failed.map((c) => c.details ?? checkName(c.checkId));
+  const positives = [];
+  const failedIds = new Set(failed.map((c) => c.checkId));
+  if (![...failedIds].some((id) => id.includes("timing") || id === "rapid_completion" || id === "impossibly_fast")) {
+    positives.push("Response timing appears natural");
+  }
+  if (![...failedIds].some((id) => id.includes("automation") || id === "webdriver_detected")) {
+    positives.push("No automation tools detected");
+  }
+  if (![...failedIds].some((id) => id.includes("ai_content"))) {
+    positives.push("Content appears human-written");
+  }
+  if (!failedIds.has("minimal_effort")) {
+    positives.push("Response shows reasonable effort");
+  }
+  let suggestion;
+  if (recommendation === "keep") suggestion = "Response can be accepted as-is";
+  else if (recommendation === "review") suggestion = "Consider manual review before accepting";
+  else suggestion = "Response should be rejected or flagged for investigation";
+  return { verdict, issues, positives, suggestion };
+}
+function buildResult(checks, tier, thresholds, processingTimeMs) {
+  const failedChecks = checks.filter((c) => !c.passed);
+  const passedChecks = checks.filter((c) => c.passed);
+  const hardSuspicion = noisyOr(failedChecks.map((c) => c.score));
+  const softMean = checks.length > 0 ? passedChecks.reduce((sum, c) => sum + c.score, 0) / checks.length : 0;
+  const softSuspicion = Math.min(0.35, softMean);
+  const suspicion = 1 - (1 - hardSuspicion) * (1 - softSuspicion);
+  const score = clamp01(1 - suspicion);
+  const passed = score >= thresholds.fail;
+  let recommendation;
+  if (score >= thresholds.review) recommendation = "keep";
+  else if (score >= thresholds.fail) recommendation = "review";
+  else recommendation = "discard";
+  const flags = failedChecks.map((c) => checkName(c.checkId));
+  const summary = buildSummary(checks, score, recommendation);
+  const strongestSignal = checks.reduce((max, c) => Math.max(max, c.score), 0);
+  const confidence = clamp01(0.5 + checks.length * 0.015 + strongestSignal * 0.2);
+  return {
+    score,
+    passed,
+    recommendation,
+    confidence,
+    flags,
+    summary,
+    checks,
+    meta: {
+      tier,
+      processingTimeMs,
+      checksRun: checks.length,
+      checksPassed: passedChecks.length,
+      requestId: offlineRequestId(),
+      timestamp: Date.now()
+    }
+  };
+}
+function buildBatchResult(results, submissions, crossAnalysis) {
+  const total = results.length;
+  const passed = results.filter((r) => r.recommendation === "keep").length;
+  const review = results.filter((r) => r.recommendation === "review").length;
+  const failed = results.filter((r) => r.recommendation === "discard").length;
+  const avgScore = total > 0 ? results.reduce((sum, r) => sum + r.score, 0) / total : 0;
+  const batch = {
+    results,
+    summary: { total, passed, review, failed, avgScore }
+  };
+  if (crossAnalysis) {
+    batch.fraudIndicators = detectFraudIndicators(submissions);
+  }
+  return batch;
+}
+function detectFraudIndicators(submissions) {
+  const seen = /* @__PURE__ */ new Map();
+  const duplicateAnswers = [];
+  submissions.forEach((sub, index) => {
+    const key = sub.responses.map((r) => `${r.question}=${r.answer}`).join("|");
+    if (seen.has(key)) {
+      const id = sub.context?.surveyId ?? `submission_${index}`;
+      duplicateAnswers.push(id);
+    } else {
+      seen.set(key, index);
+    }
+  });
+  return {
+    duplicateAnswers,
+    coordinatedTiming: false,
+    deviceSharing: false,
+    fraudRingScore: clamp01(duplicateAnswers.length / Math.max(1, submissions.length))
+  };
+}
+
+// src/cipher.ts
+var DEFAULT_CONFIG = {
+  tier: 3,
+  thresholds: {
+    fail: 0.4,
+    review: 0.7
+  },
+  debug: false,
+  offline: false,
+  endpoint: "https://api.surbee.com/v1/cipher"
+};
 var Cipher = class {
   config;
-  constructor(config) {
-    if (!config.apiKey) {
-      throw new Error("API key is required. Get one from Settings > API Keys in your Surbee dashboard.");
-    }
-    if (!config.apiKey.startsWith("cipher_sk_") && !config.apiKey.startsWith("cipher_pk_")) {
-      throw new Error("Invalid API key format. Keys should start with cipher_sk_ or cipher_pk_");
+  constructor(config = {}) {
+    const offline = config.offline ?? DEFAULT_CONFIG.offline;
+    if (config.apiKey) {
+      if (!config.apiKey.startsWith("cipher_sk_") && !config.apiKey.startsWith("cipher_pk_")) {
+        throw new Error("Invalid API key format. Keys should start with cipher_sk_ or cipher_pk_");
+      }
+    } else if (!offline) {
+      throw new Error(
+        "API key is required for online validation. Pass { offline: true } to run tier 1\u20132 checks locally, or get a key from Settings > API Keys in your Surbee dashboard."
+      );
     }
     this.config = {
-      apiKey: config.apiKey,
+      apiKey: config.apiKey ?? "",
       tier: config.tier ?? DEFAULT_CONFIG.tier,
       thresholds: {
         fail: config.thresholds?.fail ?? DEFAULT_CONFIG.thresholds.fail,
         review: config.thresholds?.review ?? DEFAULT_CONFIG.thresholds.review
       },
       debug: config.debug ?? DEFAULT_CONFIG.debug,
+      offline,
       endpoint: config.endpoint ?? DEFAULT_CONFIG.endpoint
     };
   }
   /**
-   * 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).
    */
   async validate(input) {
+    if (this.config.offline) {
+      return this.validateSync(input);
+    }
     const response = await this.request("/validate", {
       tier: this.config.tier,
       thresholds: this.config.thresholds,
@@ -67,32 +628,80 @@ var Cipher = class {
     return response;
   }
   /**
-   * 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) {
+    const start = Date.now();
+    const checks = this.runOfflineChecks(input);
+    return buildResult(checks, this.config.tier, this.config.thresholds, Date.now() - start);
+  }
+  /**
+   * Validate multiple responses in batch.
+   *
+   * Runs locally when `offline: true`, otherwise calls Surbee's batch endpoint.
    */
   async validateBatch(input) {
+    const crossAnalysis = input.crossAnalysis ?? this.config.tier === 5;
+    if (this.config.offline) {
+      const results = input.submissions.map((submission) => this.validateSync(submission));
+      return buildBatchResult(results, input.submissions, crossAnalysis);
+    }
     const response = await this.request("/validate/batch", {
       tier: this.config.tier,
       thresholds: this.config.thresholds,
       submissions: input.submissions,
-      crossAnalysis: input.crossAnalysis ?? this.config.tier === 5
+      crossAnalysis
     });
     return response;
   }
   /**
-   * Get tier information
+   * Run the offline checks that apply to the configured tier.
+   */
+  runOfflineChecks(input) {
+    const { responses, behavioralMetrics, deviceInfo, context } = input;
+    const all = [
+      ...runTimingChecks(responses, behavioralMetrics, context),
+      ...runBehavioralChecks(behavioralMetrics),
+      ...runContentChecks(responses, behavioralMetrics),
+      ...runDeviceChecks(deviceInfo)
+    ];
+    const byId = new Map(all.map((c) => [c.checkId, c]));
+    const offlineIds = getOfflineChecksForTier(this.config.tier);
+    return offlineIds.map((id) => byId.get(id)).filter((c) => Boolean(c));
+  }
+  /**
+   * Estimate the per-response API cost for a number of responses at the
+   * configured tier (tiers 1–2 are free).
+   */
+  estimateCost(responses = 1) {
+    return estimateCost(this.config.tier, responses);
+  }
+  /**
+   * Get tier information, including the list of checks it runs.
    */
   getTierInfo(tier) {
     const t = tier ?? this.config.tier;
-    return TIER_INFO[t];
+    const config = TIERS[t];
+    const checks = getChecksForTier(t);
+    return {
+      tier: t,
+      name: config.name,
+      description: config.description,
+      checks,
+      checksCount: checks.length,
+      aiModel: config.aiModel,
+      offline: config.offline,
+      estimatedCostPerResponse: config.estimatedCostPerResponse
+    };
   }
   /**
    * Get all available tiers
    */
   getAllTiers() {
-    return Object.entries(TIER_INFO).map(([tier, info]) => ({
-      tier: Number(tier),
-      ...info
-    }));
+    return [1, 2, 3, 4, 5].map((tier) => this.getTierInfo(tier));
   }
   /**
    * Check API key validity and credits
@@ -105,6 +714,11 @@ var Cipher = class {
    * Make API request to Surbee
    */
   async request(path, body) {
+    if (!this.config.apiKey) {
+      throw this.createError(401, {
+        message: "This Cipher instance has no API key. Provide one to use online validation, or call validateSync() for offline checks."
+      });
+    }
     const url = `${this.config.endpoint}${path}`;
     if (this.config.debug) {
       console.log(`[Cipher] POST ${url}`);