@fraud-intercept/sdk 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Fraud Intercept
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,104 @@
+# @fraud-intercept/sdk
+
+Typed Node.js client for the Fraud Intercept **Submit Event** API (`POST /api/v1/events`).
+
+> **Note:** npm publish is not live yet. Install from this monorepo path or wait for the public registry release.
+
+## Requirements
+
+- Node.js 18+ (uses global `fetch`)
+
+## Install
+
+```bash
+npm install @fraud-intercept/sdk
+```
+
+## Quick start
+
+```typescript
+import FraudIntercept from '@fraud-intercept/sdk'
+
+const client = new FraudIntercept({
+  apiKey: process.env.FRAUD_INTERCEPT_API_KEY!,
+  baseUrl: 'https://fraud-intercept.com',
+})
+
+const result = await client.checkRegistration({
+  eventId: 'fingerprint-request-id-or-unique-id',
+  email: 'customer@example.com',
+  customerName: 'Jane Doe',
+})
+
+if (result.recommendation === 'block') {
+  // Deny the action
+}
+```
+
+## Event types
+
+Send the appropriate helper at each integration point:
+
+| Helper | `eventType` |
+|--------|-------------|
+| `checkRegistration()` | `register` |
+| `checkLogin()` | `login` |
+| `checkDeposit()` | `deposit` |
+| `checkWithdrawal()` | `withdrawal` |
+
+Or use `submitEvent({ eventType, eventId, ... })` directly.
+
+`EVENT_TYPES` in this package must stay in sync with `lib/utils/event-type.ts` in the main app.
+
+## Configuration
+
+| Option | Required | Default |
+|--------|----------|---------|
+| `apiKey` | Yes | — |
+| `baseUrl` | No | `https://fraud-intercept.com` |
+| `timeout` | No | `10000` (ms) |
+| `retries` | No | `2` (network errors only) |
+
+## Idempotency
+
+Pass a stable key per logical operation to avoid duplicate events on retries:
+
+```typescript
+await client.submitEvent(
+  { eventType: 'deposit', eventId: 'fp_abc', email: 'a@b.com' },
+  { idempotencyKey: 'deposit-user-123-2026-06-03' },
+)
+```
+
+## Response fields
+
+The client returns the API `data` object, including:
+
+- `recommendation` — `allow` | `review` | `block`
+- `score`, `riskLevel`, `triggeredRules`, `flags`
+- `matchedThreat` — Known Threat match (legacy alias: `matchedFraudster`)
+- `device`, `multiAccount`, `coverage`, `notes`
+
+## Errors
+
+- `FraudInterceptError` — validation and API errors (`status`, `code`)
+- `AuthenticationError` — invalid or missing API key (401)
+- `RateLimitError` — rate limit exceeded (429)
+
+Client-side validation runs before any HTTP call (missing `eventId`, invalid `eventType`, no identifiers).
+
+## Development
+
+```bash
+cd packages/sdk
+npm install
+npm run build
+npm test
+```
+
+From the repo root:
+
+```bash
+npm run build:sdk
+npm run test:sdk
+```

package/dist/client.d.ts

@@ -0,0 +1,15 @@
+import { FraudInterceptConfig, CheckDepositRequest, CheckDepositResponse, CheckLoginRequest, CheckLoginResponse, CheckRegistrationRequest, CheckRegistrationResponse, CheckWithdrawalRequest, CheckWithdrawalResponse, SubmitEventOptions, SubmitEventRequest, SubmitEventResponse } from './types';
+export declare class FraudIntercept {
+    private apiKey;
+    private baseUrl;
+    private timeout;
+    private retries;
+    constructor(config: FraudInterceptConfig);
+    submitEvent(request: SubmitEventRequest, options?: SubmitEventOptions): Promise<SubmitEventResponse>;
+    checkRegistration(request: CheckRegistrationRequest, options?: SubmitEventOptions): Promise<CheckRegistrationResponse>;
+    checkLogin(request: CheckLoginRequest, options?: SubmitEventOptions): Promise<CheckLoginResponse>;
+    checkDeposit(request: CheckDepositRequest, options?: SubmitEventOptions): Promise<CheckDepositResponse>;
+    checkWithdrawal(request: CheckWithdrawalRequest, options?: SubmitEventOptions): Promise<CheckWithdrawalResponse>;
+    private validateSubmitEvent;
+    private requestWithRetry;
+}

package/dist/client.js

@@ -0,0 +1,98 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.FraudIntercept = void 0;
+const types_1 = require("./types");
+const errors_1 = require("./errors");
+const DEFAULT_BASE_URL = 'https://fraud-intercept.com';
+const DEFAULT_TIMEOUT = 10000;
+const DEFAULT_RETRIES = 2;
+const EVENTS_ENDPOINT = '/api/v1/events';
+class FraudIntercept {
+    constructor(config) {
+        if (!config.apiKey) {
+            throw new errors_1.AuthenticationError('apiKey is required');
+        }
+        this.apiKey = config.apiKey;
+        this.baseUrl = (config.baseUrl || DEFAULT_BASE_URL).replace(/\/$/, '');
+        this.timeout = config.timeout || DEFAULT_TIMEOUT;
+        this.retries = config.retries ?? DEFAULT_RETRIES;
+    }
+    async submitEvent(request, options) {
+        this.validateSubmitEvent(request);
+        return this.requestWithRetry(EVENTS_ENDPOINT, request, options?.idempotencyKey);
+    }
+    async checkRegistration(request, options) {
+        return this.submitEvent({ ...request, eventType: 'register' }, options);
+    }
+    async checkLogin(request, options) {
+        return this.submitEvent({ ...request, eventType: 'login' }, options);
+    }
+    async checkDeposit(request, options) {
+        return this.submitEvent({ ...request, eventType: 'deposit' }, options);
+    }
+    async checkWithdrawal(request, options) {
+        return this.submitEvent({ ...request, eventType: 'withdrawal' }, options);
+    }
+    validateSubmitEvent(request) {
+        if (!request.eventType || !types_1.EVENT_TYPES.includes(request.eventType)) {
+            throw new errors_1.FraudInterceptError(`eventType is required and must be one of: ${types_1.EVENT_TYPES.join(', ')}`, 400, 'VALIDATION_ERROR');
+        }
+        if (!request.eventId) {
+            throw new errors_1.FraudInterceptError('eventId is required', 400, 'VALIDATION_ERROR');
+        }
+        if (!request.email && !request.phone && !request.creditCardHash) {
+            throw new errors_1.FraudInterceptError('At least one identifier (email, phone, or creditCardHash) is required', 400, 'VALIDATION_ERROR');
+        }
+    }
+    async requestWithRetry(path, body, idempotencyKey, attempt = 0) {
+        try {
+            const controller = new AbortController();
+            const timeoutId = setTimeout(() => controller.abort(), this.timeout);
+            const headers = {
+                'Content-Type': 'application/json',
+                'X-API-Key': this.apiKey,
+            };
+            if (idempotencyKey) {
+                headers['Idempotency-Key'] = idempotencyKey;
+            }
+            let response;
+            try {
+                response = await fetch(`${this.baseUrl}${path}`, {
+                    method: 'POST',
+                    headers,
+                    body: JSON.stringify(body),
+                    signal: controller.signal,
+                });
+            }
+            finally {
+                clearTimeout(timeoutId);
+            }
+            if (!response.ok) {
+                const errorBody = await response.json().catch(() => ({ error: 'Unknown error' }));
+                const errorMessage = errorBody.error || errorBody.message;
+                if (response.status === 401) {
+                    throw new errors_1.AuthenticationError(errorMessage);
+                }
+                if (response.status === 429) {
+                    throw new errors_1.RateLimitError(errorMessage);
+                }
+                throw new errors_1.FraudInterceptError(errorMessage || `HTTP ${response.status}`, response.status);
+            }
+            const json = await response.json();
+            if (!json.data) {
+                throw new errors_1.FraudInterceptError('API response did not include a data object', 500, 'INVALID_RESPONSE');
+            }
+            return json.data;
+        }
+        catch (error) {
+            if (attempt < this.retries &&
+                error instanceof TypeError) {
+                const delay = Math.pow(2, attempt) * 100;
+                await new Promise(resolve => setTimeout(resolve, delay));
+                return this.requestWithRetry(path, body, idempotencyKey, attempt + 1);
+            }
+            throw error;
+        }
+    }
+}
+exports.FraudIntercept = FraudIntercept;

package/dist/errors.d.ts

@@ -0,0 +1,11 @@
+export declare class FraudInterceptError extends Error {
+    status: number;
+    code: string;
+    constructor(message: string, status: number, code?: string);
+}
+export declare class AuthenticationError extends FraudInterceptError {
+    constructor(message?: string);
+}
+export declare class RateLimitError extends FraudInterceptError {
+    constructor(message?: string);
+}

package/dist/errors.js

@@ -0,0 +1,26 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.RateLimitError = exports.AuthenticationError = exports.FraudInterceptError = void 0;
+class FraudInterceptError extends Error {
+    constructor(message, status, code = 'UNKNOWN_ERROR') {
+        super(message);
+        this.name = 'FraudInterceptError';
+        this.status = status;
+        this.code = code;
+    }
+}
+exports.FraudInterceptError = FraudInterceptError;
+class AuthenticationError extends FraudInterceptError {
+    constructor(message = 'Invalid or missing API key') {
+        super(message, 401, 'AUTHENTICATION_ERROR');
+        this.name = 'AuthenticationError';
+    }
+}
+exports.AuthenticationError = AuthenticationError;
+class RateLimitError extends FraudInterceptError {
+    constructor(message = 'Rate limit exceeded') {
+        super(message, 429, 'RATE_LIMIT_ERROR');
+        this.name = 'RateLimitError';
+    }
+}
+exports.RateLimitError = RateLimitError;

package/dist/index.d.ts

@@ -0,0 +1,5 @@
+export { FraudIntercept } from './client';
+export { FraudInterceptError, AuthenticationError, RateLimitError } from './errors';
+export type { EventType, SubmitEventRequest, SubmitEventOptions, SubmitEventResponse, MultiAccountMetadata, EventHelperRequest, FraudInterceptConfig, CheckRegistrationRequest, CheckRegistrationResponse, CheckLoginRequest, CheckLoginResponse, CheckDepositRequest, CheckDepositResponse, CheckWithdrawalRequest, CheckWithdrawalResponse, Flag, TriggeredRule, MatchedThreat, MatchedFraudster, AthleteMatch, DeviceInfo, MultiAccountInfo, DetectionCoverage, ResponseNote, } from './types';
+export { EVENT_TYPES } from './types';
+export { FraudIntercept as default } from './client';

package/dist/index.js

@@ -0,0 +1,13 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.default = exports.EVENT_TYPES = exports.RateLimitError = exports.AuthenticationError = exports.FraudInterceptError = exports.FraudIntercept = void 0;
+var client_1 = require("./client");
+Object.defineProperty(exports, "FraudIntercept", { enumerable: true, get: function () { return client_1.FraudIntercept; } });
+var errors_1 = require("./errors");
+Object.defineProperty(exports, "FraudInterceptError", { enumerable: true, get: function () { return errors_1.FraudInterceptError; } });
+Object.defineProperty(exports, "AuthenticationError", { enumerable: true, get: function () { return errors_1.AuthenticationError; } });
+Object.defineProperty(exports, "RateLimitError", { enumerable: true, get: function () { return errors_1.RateLimitError; } });
+var types_1 = require("./types");
+Object.defineProperty(exports, "EVENT_TYPES", { enumerable: true, get: function () { return types_1.EVENT_TYPES; } });
+var client_2 = require("./client");
+Object.defineProperty(exports, "default", { enumerable: true, get: function () { return client_2.FraudIntercept; } });

package/dist/types.d.ts

@@ -0,0 +1,106 @@
+export interface FraudInterceptConfig {
+    apiKey: string;
+    baseUrl?: string;
+    timeout?: number;
+    retries?: number;
+}
+/** Keep in sync with lib/utils/event-type.ts in the main app. */
+export declare const EVENT_TYPES: readonly ["register", "login", "deposit", "withdrawal"];
+export type EventType = typeof EVENT_TYPES[number];
+export type RiskLevel = 'low' | 'medium' | 'high' | (string & {});
+export type Recommendation = 'allow' | 'review' | 'block' | (string & {});
+export interface SubmitEventRequest {
+    eventType: EventType;
+    eventId: string;
+    email?: string;
+    phone?: string;
+    customerName?: string;
+    dateOfBirth?: string;
+    creditCardHash?: string;
+    userId?: string;
+    ipAddress?: string;
+}
+export interface SubmitEventOptions {
+    idempotencyKey?: string;
+}
+export type EventHelperRequest = Omit<SubmitEventRequest, 'eventType'>;
+export type CheckRegistrationRequest = EventHelperRequest;
+export type CheckLoginRequest = EventHelperRequest;
+export type CheckDepositRequest = EventHelperRequest;
+export type CheckWithdrawalRequest = EventHelperRequest;
+export interface Flag {
+    rule: string;
+    points?: number;
+    detail: string;
+}
+export interface MultiAccountMetadata {
+    kind: 'same_brand_device_count' | 'same_brand_ip_count';
+    count: number;
+    threshold: number;
+    window_days: 30;
+    evidence_strength: 'hard' | 'soft';
+}
+export interface TriggeredRule {
+    ruleId: string;
+    name: string;
+    action: string;
+    condition?: string;
+    multi_account_metadata?: MultiAccountMetadata;
+}
+export interface MatchedThreat {
+    id: string;
+    riskLevel: string;
+    crossBrandCount: number;
+}
+/** @deprecated Use MatchedThreat */
+export type MatchedFraudster = MatchedThreat;
+export interface AthleteMatch {
+    athleteId: string;
+    athleteName: string;
+    confidence: 'high' | 'medium' | 'low';
+    matchType: string;
+    isActive: boolean;
+}
+export interface DeviceInfo {
+    visitorId: string | null;
+    suspectScore: number | null;
+    vpn: boolean | null;
+    bot: boolean | null;
+    incognito: boolean | null;
+    datacenterIp: boolean | null;
+}
+export interface MultiAccountInfo {
+    deviceCount: number;
+    ipCount: number;
+}
+export interface DetectionCoverage {
+    identity: boolean;
+    crossBrand: boolean;
+    deviceIntelligence: boolean;
+}
+export interface ResponseNote {
+    code: string;
+    text: string;
+}
+export interface SubmitEventResponse {
+    eventType: EventType;
+    score: number;
+    riskLevel: RiskLevel;
+    recommendation: Recommendation;
+    scoreRecommendation?: Recommendation;
+    triggeredRules: TriggeredRule[];
+    flags: Flag[];
+    matchedThreat: MatchedThreat | null;
+    matchedFraudster?: MatchedFraudster | null;
+    athleteMatch: AthleteMatch | null;
+    device: DeviceInfo;
+    multiAccount: MultiAccountInfo;
+    coverage: DetectionCoverage;
+    notes: ResponseNote[];
+    eventId: string;
+    responseTimeMs: number;
+}
+export type CheckRegistrationResponse = SubmitEventResponse;
+export type CheckLoginResponse = SubmitEventResponse;
+export type CheckDepositResponse = SubmitEventResponse;
+export type CheckWithdrawalResponse = SubmitEventResponse;

package/dist/types.js

@@ -0,0 +1,5 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.EVENT_TYPES = void 0;
+/** Keep in sync with lib/utils/event-type.ts in the main app. */
+exports.EVENT_TYPES = ['register', 'login', 'deposit', 'withdrawal'];

package/package.json

@@ -0,0 +1,19 @@
+{
+  "name": "@fraud-intercept/sdk",
+  "version": "0.1.0",
+  "description": "Fraud Intercept SDK for real-time Digital Trust event scoring",
+  "main": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "files": ["dist"],
+  "scripts": {
+    "build": "tsc",
+    "test": "vitest run",
+    "prepublishOnly": "npm run build"
+  },
+  "keywords": ["fraud", "digital-trust", "risk-scoring", "device-intelligence"],
+  "license": "MIT",
+  "devDependencies": {
+    "typescript": "^5.7.2",
+    "vitest": "^4.0.18"
+  }
+}