BigShield Ruby SDK

gem "bigshield"

require "bigshield"

client = BigShield::Client.new("ev_live_...")
result = client.validate("user@example.com")

puts result.risk_score       # 0-100
puts result.fraud_decision   # "allow" | "block" | "review" | "require_verification"
puts result.recommendation   # "accept" | "review" | "reject"

raise "Please use a valid email address" if result.fraud_decision == "block"

# Simple
client = BigShield::Client.new("ev_live_...")

# Advanced options
client = BigShield::Client.new(
  "ev_live_...",
  base_url: "https://bigshield.app",  # default
  timeout: 30,                         # request timeout in seconds
  retries: 2                           # retry on 5xx errors
)

result = client.validate(
  "user@example.com",
  ip: request.remote_ip,
  user_agent: request.user_agent,
  fingerprint: client_fingerprint,
  wait: true,                                # long-poll for async signals
  webhook_url: "https://myapp.com/webhook",
  metadata: { source: "signup" }
)

puts result.fraud_decision
puts result.fraud_flags   # e.g. ["proxy_ip", "burner_domain"]
puts result.signals       # individual signal results

batch = client.batch_validate(
  ["user1@gmail.com", "fake@tempmail.com", "real@company.org"],
  ip: request.remote_ip
)

blocked = batch.results.select { |r| r.fraud_decision == "block" }
puts "Blocked #{blocked.size} of #{batch.total} emails"

result = client.get_validation("val_a1b2c3d4")

initial = client.validate("user@example.com")

if initial.status == "partial"
  final = client.wait_for_completion(
    initial.id,
    interval: 1.0,      # poll every 1s
    max_attempts: 30     # give up after 30s
  )
end

usage = client.get_usage
puts "#{usage.usage.total} / #{usage.usage.limit} validations used"

health = client.health
puts health.status

client.register_webhook("https://myapp.com/webhook", events: ["validation.completed"])

require "bigshield"

begin
  result = client.validate("test@example.com")
rescue BigShield::AuthError
  # Invalid or missing API key (401)
rescue BigShield::RateLimitError => e
  # Rate limit exceeded (429)
  puts "Retry after #{e.retry_after} seconds"
rescue BigShield::Error => e
  # Other API error
  puts "#{e.code} #{e.status} #{e.message}"
end