Quick Start

// scorika-client.ts - Production-ready Scorika client

interface ScoreResult {
  case_id: string | null;
  score: number;
  decision: 'allow' | 'review' | 'deny';
  confidence: number;
  signals: Array<{ type: string; risk: string; reason_codes: string[] }>;
  fallback?: boolean;
}

class ScorikaClient {
  private baseUrl = 'https://api.scorika.com/v1';
  private timeout = 5000;  // 5 seconds - never block critical flows!

  constructor(private apiKey: string) {}

  async score(input: { email?: string; ip?: string }): Promise<ScoreResult> {
    const controller = new AbortController();
    const timeoutId = setTimeout(() => controller.abort(), this.timeout);

    try {
      const response = await fetch(`${this.baseUrl}/score`, {
        method: 'POST',
        headers: {
          'X-Api-Key': this.apiKey,
          'Content-Type': 'application/json',
        },
        body: JSON.stringify(input),
        signal: controller.signal,  // IMPORTANT: Enable timeout!
      });

      clearTimeout(timeoutId);

      if (!response.ok) {
        throw new Error(`API error: ${response.status}`);
      }

      const json = await response.json();
      return json.data as ScoreResult;

    } catch (error) {
      clearTimeout(timeoutId);

      // Fallback: allow but flag for async review
      console.error('Scorika unavailable:', error);
      return {
        case_id: null,
        score: 50,
        decision: 'review',
        confidence: 0,
        signals: [],
        fallback: true,
      };
    }
  }
}

// Usage example
const client = new ScorikaClient('sk_live_your_api_key');

async function handleCheckout(email: string, ip: string) {
  const result = await client.score({ email, ip });

  if (result.fallback) {
    console.log('⚠ Scorika unavailable - proceeding with async review');
    // Queue order for background verification
    return { proceed: true, needsReview: true };
  }

  if (result.decision === 'deny') {
    return { proceed: false, reason: 'High risk detected' };
  }

  return { proceed: true, needsReview: result.decision === 'review' };
}

export { ScorikaClient, ScoreResult };

# scorika_client.rb - Production-ready Scorika client

require 'net/http'
require 'json'
require 'uri'
require 'timeout'

module Scorika
  class Error < StandardError; end
  class TimeoutError < Error; end

  ScoreResult = Struct.new(
    :case_id, :score, :decision, :confidence, :signals, :fallback,
    keyword_init: true
  ) do
    def allow?; decision == 'allow'; end
    def deny?; decision == 'deny'; end
    def review?; decision == 'review'; end
  end

  class Client
    BASE_URL = 'https://api.scorika.com/v1'.freeze
    TIMEOUT = 5  # seconds - never block critical flows!

    def initialize(api_key)
      @api_key = api_key
    end

    def score(email: nil, ip: nil)
      payload = { email: email, ip: ip }.compact
      response = post('/score', payload)
      parse_result(response['data'])
    rescue Net::OpenTimeout, Net::ReadTimeout, Errno::ECONNREFUSED => e
      # Fallback: allow but flag for async review
      warn "Scorika unavailable: #{e.message}, using fallback"
      fallback_result
    end

    private

    def post(path, payload)
      uri = URI.parse("#{BASE_URL}#{path}")
      http = Net::HTTP.new(uri.host, uri.port)
      http.use_ssl = true
      http.open_timeout = TIMEOUT  # Connection timeout
      http.read_timeout = TIMEOUT  # Response timeout

      request = Net::HTTP::Post.new(uri.path)
      request['X-Api-Key'] = @api_key
      request['Content-Type'] = 'application/json'
      request.body = payload.to_json

      response = http.request(request)
      JSON.parse(response.body)
    end

    def parse_result(data)
      ScoreResult.new(
        case_id: data['case_id'],
        score: data['score'],
        decision: data['decision'],
        confidence: data['confidence'],
        signals: data['signals'] || [],
        fallback: false
      )
    end

    def fallback_result
      ScoreResult.new(
        case_id: nil,
        score: 50,
        decision: 'review',
        confidence: 0.0,
        signals: [],
        fallback: true
      )
    end
  end
end

# Usage example
client = Scorika::Client.new('sk_live_your_api_key')
result = client.score(email: 'user@example.com', ip: '1.2.3.4')

if result.fallback
  puts "⚠ Scorika unavailable - proceeding with async review"
elsif result.allow?
  puts "✓ Allowed (score: #{result.score})"
elsif result.review?
  puts "⚠ Review needed (score: #{result.score})"
else
  puts "✗ Denied (score: #{result.score})"
end