fraudshield-sdk

JavaScript/TypeScript SDK for the FraudShield fraud-detection API. Covers transaction analysis only — analytics and API key management are handled on the dashboard, not through this SDK. Works in Node.js 18+ (uses native fetch), both as CommonJS and ESM.

Install

npm install fraudshield-sdk

Usage

import { Client } from "fraudshield-sdk";

const client = new Client({ apiKey: "fs_test_..." });

const result = await client.transactions.analyze({
  userId: "U123",
  amount: 50000,
  currency: "NGN",
  deviceId: "dev_1",
});

if (result.isBlocked) {
  throw new PaymentError("Declined");
}

console.log(result.riskScore, result.decision, result.triggeredRules);

CommonJS works the same way:

const { Client } = require("fraudshield-sdk");

Extra fields passed to analyze(...) beyond the named ones are sent straight through as additional JSON fields, so new API parameters work without an SDK update:

await client.transactions.analyze({
  userId: "U123",
  amount: 50000,
  currency: "NGN",
  merchantCategory: "electronics", // passed through as-is
});

Auth

apiKey is sent as Authorization: Api-Key <key> on every request. Alternatively, set FRAUDSHIELD_API_KEY as an environment variable and omit apiKey in the constructor (Node.js only).

Base URL

Defaults to the FraudShield dev/staging tunnel. Override for production or local development:

const client = new Client({
  apiKey: "fs_test_...",
  baseUrl: "https://your-api-host/api/v1",
});

Errors

All errors extend FraudShieldError:

import {
  FraudShieldError,
  AuthenticationError,
  ValidationError,
  RateLimitError,
  APIError,
  APIConnectionError,
} from "fraudshield-sdk";

try {
  await client.transactions.analyze({ userId: "U123", amount: 50000, currency: "NGN" });
} catch (err) {
  if (err instanceof AuthenticationError) {
    // bad/missing API key
  } else if (err instanceof ValidationError) {
    // bad request payload
  } else if (err instanceof RateLimitError) {
    // err.retryAfter may tell you how long to wait (ms)
  } else if (err instanceof APIError) {
    // 5xx from the server
  } else if (err instanceof APIConnectionError) {
    // couldn't reach the server at all
  } else if (err instanceof FraudShieldError) {
    // any other SDK error
  }
}

Connection errors and 429/5xx responses are automatically retried with exponential backoff (maxRetries: 2 by default, configurable in the Client constructor).

Idempotency

Pass idempotencyKey to analyze(...) to safely retry the same request without double-processing on the server side (if supported by the API).

Development

npm install
npm run typecheck
npm test
npm run build