Documentation

import { BigShield } from 'bigshield';

const shield = new BigShield('ev_live_...');
const result = await shield.validate('user@example.com');

if (result.fraud_decision === 'block') {
  throw new Error('Please use a valid email address');
}

const result = await shield.validate('user@example.com', {
  ip: req.headers['x-forwarded-for'],       // enables IP signals
  user_agent: req.headers['user-agent'],     // stored for analysis
  fingerprint: clientFingerprint,            // device fingerprint hash
  wait: true,                                // long-poll for async signals
  webhook_url: 'https://myapp.com/webhook',
  metadata: { source: 'signup' },
});

console.log(result.fraud_decision);  // 'allow' | 'block' | 'require_verification' | 'review'
console.log(result.fraud_flags);     // ['proxy_ip', 'burner_domain']

const result = await shield.validate(email, {
  ip: req.headers['x-forwarded-for'],
  user_agent: req.headers['user-agent'],
});

switch (result.fraud_decision) {
  case 'allow':
    await createAccount(email);
    break;
  case 'review':
    await createAccount(email, { flagged: true });
    break;
  case 'require_verification':
    await sendVerificationEmail(email);
    break;
  case 'block':
    return res.status(400).json({ error: 'Signup blocked' });
}

// Check specific fraud flags
if (result.fraud_flags?.includes('proxy_ip')) {
  await logSuspiciousSignup(email, 'proxy');
}

const { results, total, completed } = await shield.batchValidate(
  ['user1@gmail.com', 'fake@tempmail.com', 'real@company.org'],
  {
    ip: req.headers['x-forwarded-for'],
    user_agent: req.headers['user-agent'],
  },
);

const blocked = results.filter(r => r.fraud_decision === 'block');
console.log(`Blocked ${blocked.length} of ${total} emails`);

const result = await shield.getValidation('val_a1b2c3d4');

curl "https://bigshield.app/api/v1/domain-score?domain=example.com"

curl -X POST https://bigshield.app/api/v1/feedback \
  -H "Authorization: Bearer ev_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "email": "user@example.com",
    "feedback": "false_positive",
    "notes": "This is a legitimate customer"
  }'

const usage = await shield.getUsage();

console.log(`${usage.usage.total} / ${usage.usage.limit} validations used`);
console.log(`Plan: ${usage.plan}`);

import { BigShield, AuthError, RateLimitError, BigShieldError } from 'bigshield';

try {
  await shield.validate('test@example.com');
} catch (err) {
  if (err instanceof AuthError) {
    // Invalid or missing API key (401)
  } else if (err instanceof RateLimitError) {
    // Rate limit exceeded (429)
    console.log(`Retry after ${err.retryAfter} seconds`);
  } else if (err instanceof BigShieldError) {
    // Other API error
    console.log(err.code, err.status, err.details);
  }
}

import { BigShield } from 'bigshield';

// Simple — just pass your API key
const shield = new BigShield('ev_live_...');

// Advanced options
const shield = new BigShield({
  apiKey: 'ev_live_...',
  baseUrl: 'https://bigshield.app',  // default
  timeout: 30000,                     // request timeout in ms
  retries: 2,                         // retry on 5xx errors
});

const initial = await shield.validate('user@example.com');

if (initial.status === 'partial') {
  const final = await shield.waitForCompletion(initial.id, {
    interval: 1000,   // poll every 1s
    maxAttempts: 30,   // give up after 30s
  });

  console.log(final.risk_score); // Updated with all signals
}