Deflect Node.js SDK

Official (early) Node.js SDK for the Deflect Bot Protection API.

Status: Experimental pre-release. API surface may change.

Installation

npm install @deflectbot/deflect-node
# or
yarn add @deflectbot/deflect-node

Quick Start

import Deflect from '@deflectbot/deflect-node';

const deflect = new Deflect({
  apiKey: process.env.DEFLECT_API_KEY!,
  actionId: process.env.DEFLECT_ACTION_ID!
});

// Verify client-side token
const verdict = await deflect.getVerdict({
  token: userSessionToken,
  // optional identity enrichment
  user_id: userId,        // required for access control
  email: userEmail,       // optional
  phone_number: userPhone // optional
});

if (verdict.verdict?.can_pass) {
  // allow
} else {
  // challenge / block
}

API

new Deflect(options)

| Option | Type | Required | Description | |--------|------|----------|-------------| | apiKey | string | Yes | Your Deflect API key | | actionId | string | Yes | Action ID from dashboard | | baseUrl | string | No | Override base URL (defaults to https://api.deflect.bot) | | timeoutMs | number | No | Request timeout (default 4000) | | fetchImplementation | Fetch | No | Custom fetch (Node <18 use undici) | | maxRetries | number | No | Additional retry attempts for network/timeouts/5xx (default 2) |

getVerdict(request: DeflectVerdictRequest | string)

Returns a Promise<DeflectVerdictResponse> with structure mirroring the public docs.

The function accepts either:

• A DeflectVerdictRequest object with optional user identifiers
• A string token

const verdict = await deflect.getVerdict({
  token: userSessionToken,
  user_id: 'user-123',           // optional
  email: '[email protected]',     // optional
  phone_number: '+15555551234'   // optional
});


const verdict = await deflect.getVerdict(userSessionToken);

DeflectVerdictRequest Interface: | Field | Type | Required | Description | |-------|------|----------|-------------| | token | string | Yes | Session token from frontend SDK | | user_id | string | No | Optional user identifier | | email | string | No | Optional user email | | phone_number | string | No | Optional user phone number |

Middleware has been intentionally omitted; integrate however you prefer (manually call getVerdict with the token supplied by your frontend layer).

getEmailIntelligence(email: string)

Returns a Promise<DeflectEmailIntelligenceResponse> with email validation and trust information.

const emailInfo = await deflect.getEmailIntelligence('[email protected]');
if (emailInfo.success && emailInfo.data?.is_valid && emailInfo.data?.is_trusted) {
  // Email is valid and trusted
  console.log('Trust score:', emailInfo.data.trust_score);
  console.log('Normalized:', emailInfo.data.normalized_email);
}

Response includes:

• is_valid - Whether the email is valid
• is_trusted - Whether the email is from a trusted domain
• trust_score - Numeric trust score
• has_aliasing - Whether the email uses aliasing
• normalized_email - Normalized email address
• domain - Email domain

getPhoneIntelligence(phone: string)

Returns a Promise<DeflectPhoneIntelligenceResponse> with phone number validation and risk information.

const phoneInfo = await deflect.getPhoneIntelligence('+15555551234');
if (phoneInfo.success && phoneInfo.data?.is_valid && !phoneInfo.data?.is_threat) {
  // Phone is valid and not a threat
  console.log('Carrier:', phoneInfo.data.carrier);
  console.log('Risk score:', phoneInfo.data.risk_score);
}

Response includes:

• is_valid - Whether the phone number is valid
• e164_format - Phone number in E.164 format
• country_code - Country code
• country - Country ISO code
• country_name - Full country name
• number_type - Type of number (mobile, landline, etc.)
• line_type - Line type classification
• carrier - Phone carrier name
• carrier_type - Type of carrier
• risk_score - Numeric risk score
• is_disposable - Whether it's a disposable number
• is_virtual - Whether it's a virtual number
• is_threat - Whether it's flagged as a threat
• is_spam - Whether it's flagged as spam
• last_updated - Last update timestamp

getIpIntelligence(ip: string)

Returns a Promise<DeflectIpIntelligenceResponse> with IP address intelligence and geolocation.

const ipInfo = await deflect.getIpIntelligence('8.8.8.8');
if (ipInfo.success && ipInfo.data && !ipInfo.data.is_vpn && !ipInfo.data.is_threat) {
  // IP is not using VPN and not a threat
  console.log('Location:', ipInfo.data.city, ipInfo.data.country);
  console.log('ISP:', ipInfo.data.isp);
}

Response includes:

• is_vpn - Whether IP is using a VPN
• is_datacenter_proxy - Whether IP is a datacenter proxy
• is_residential_proxy - Whether IP is a residential proxy
• is_bogon - Whether IP is a bogon address
• is_tor_node - Whether IP is a Tor exit node
• is_threat - Whether IP is flagged as a threat
• city - City name
• postal_code - Postal code
• country - Country ISO code
• continent - Continent code
• latitude - Geographic latitude
• longitude - Geographic longitude
• asn_number - ASN number
• asn_organization - ASN organization name
• isp - Internet service provider name

Error Handling

Errors throw DeflectError with optional status and causeBody (API error body). Timeouts produce status 408. Network errors have status undefined.

Retries

The client retries instantly (no backoff) up to maxRetries additional times for:

• Network errors (thrown before a response)
• Timeouts (AbortError)
• 5xx HTTP responses It does not retry 4xx responses.

try {
  await deflect.getVerdict(token);
} catch (e) {
  if (e instanceof DeflectError) {
    console.error('Deflect error', e.status, e.causeBody);
  }
}

Contributing

• Build: npm run build
• Dev watch: npm run dev
• Lint: npm run lint
• Test: npm test

License

MIT