@run-true/fde-sdk

TypeScript SDK for the FDE Fraud Decision Engine API.

Supports all three V1 endpoints with full TypeScript types and JWT+HMAC authentication.

Requirements

• Node.js 18+

Installation

npm install @run-true/fde-sdk

Quick Start

import { FdeClient } from '@run-true/fde-sdk';

const client = new FdeClient({
  endpoint: 'https://fde.run-true.com',
  jwtSigningKey: process.env.FDE_JWT_SIGNING_KEY!,
  hmacKey: process.env.FDE_HMAC_KEY!,
  clientId: process.env.FDE_CLIENT_ID!,
});

// Evaluate risk
const result = await client.evaluateRisk({
  eventCode: 'login',
  sessionId: 'sess-abc123',
  deviceToken: 'device-fingerprint-token',
  userId: 'user-001',
  userIp: '1.2.3.4',
  eventDetail: {
    Login: {
      UserLoginName: '[email protected]',
    },
  },
});

console.log(result.risk_score, result.decision);
// e.g. 15 "accept"

API

new FdeClient(options)

| Option | Type | Required | Description | |--------|------|----------|-------------| | endpoint | string | Yes | Base URL, e.g. "https://fde.run-true.com" | | jwtSigningKey | string | Yes | HS256 signing secret | | hmacKey | string | Yes | Hex-encoded HMAC-SHA256 key | | clientId | string | Yes | JWT sub claim — your client identifier | | jwtIssuer | string | No | JWT iss claim (default: "fde") | | jwtAudience | string | No | JWT aud claim (default: "fde-risk-api") |

client.evaluateRisk(request, options?)

POST /v1/risk/evaluate — real-time fraud risk assessment.

const result = await client.evaluateRisk(request, { explain: true });
// result.explanation contains SHAP feature attributions

Returns RiskEvaluateResponse.

client.submitOutcome(request)

POST /v1/risk/outcome — record the outcome of a transaction.

Returns OutcomeResponse ({ request_id: string }).

client.submitLabels(request)

POST /v1/risk/labels — submit fraud labels for prior events (up to 100 per call).

Returns SubmitLabelsResponse.

Authentication

Every request is signed with two layers:

1. JWT (HS256) — Authorization: Bearer <token>. Token expires in 5 minutes and is regenerated per request.
2. HMAC-SHA256 — X-FDE-Signature: <hex>. Signs timestamp + "\n" + SHA256(body) using your hex-encoded HMAC key.

The SDK handles both layers automatically. The request body is serialised to JSON exactly once, and the same bytes are used for both the HMAC computation and the HTTP body — ensuring byte-exactness.

Error Handling

import { FdeClient, FdeApiError } from '@run-true/fde-sdk';

try {
  const result = await client.evaluateRisk(request);
} catch (err) {
  if (err instanceof FdeApiError) {
    console.error(`API error ${err.status}: ${err.body}`);
  } else {
    throw err;
  }
}

Environment Variables

The SDK does not read environment variables directly. Pass credentials explicitly via constructor options. A typical pattern:

const client = new FdeClient({
  endpoint: process.env.FDE_ENDPOINT ?? 'https://fde.run-true.com',
  jwtSigningKey: process.env.FDE_JWT_SIGNING_KEY!,
  hmacKey: process.env.FDE_HMAC_KEY!,
  clientId: process.env.FDE_CLIENT_ID!,
});

Development

npm install
npm run build       # compile to dist/
npm test            # run Vitest unit tests
npm run type-check  # type-check without emitting