npm package: @run-true/fde-sdk
Description: TypeScript SDK for the FDE Fraud Decision Engine API
Author: Run True Decision
Latest version: 1.0.0

# @run-true/fde-sdk

TypeScript SDK for the [FDE Fraud Decision Engine](https://fde.run-true.com) API.

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

## Requirements

- Node.js 18+

## Installation

```bash
npm install @run-true/fde-sdk
```

## Quick Start

```typescript
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: 'alice@example.com',
    },
  },
});

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.

```typescript
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

```typescript
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:

```typescript
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

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