@p2pdotme/sdk 1.0.0

package/dist/fraud-engine.d.cts

@@ -0,0 +1,194 @@
+import * as neverthrow from 'neverthrow';
+
+declare class SdkError<TCode extends string = string> extends Error {
+    readonly code: TCode;
+    readonly cause?: unknown;
+    readonly context?: Record<string, unknown>;
+    constructor(message: string, options: {
+        code: TCode;
+        cause?: unknown;
+        context?: Record<string, unknown>;
+    });
+}
+
+type FraudEngineErrorCode = "API_ERROR" | "ENCRYPTION_ERROR" | "SIGNING_ERROR" | "VALIDATION_ERROR" | "NETWORK_ERROR" | "PLACE_ORDER_ERROR";
+declare class FraudEngineError extends SdkError<FraudEngineErrorCode> {
+    constructor(message: string, options: {
+        code: FraudEngineErrorCode;
+        cause?: unknown;
+        context?: Record<string, unknown>;
+    });
+}
+
+interface Logger {
+    debug(message: string, data?: Record<string, unknown>): void;
+    info(message: string, data?: Record<string, unknown>): void;
+    warn(message: string, data?: Record<string, unknown>): void;
+    error(message: string, data?: Record<string, unknown>): void;
+}
+declare const noopLogger: Logger;
+
+interface FraudEngineSigner {
+    /**
+     * The subject address tracked by the fraud engine — the wallet that places
+     * on-chain orders and appears in reports, watchlist, and risk scoring.
+     *
+     * - For thirdweb smart wallets (ERC-4337 / account abstraction) this is the
+     *   smart account address.
+     * - For plain EOA wallets this is the same address that produces signatures.
+     */
+    readonly address: string;
+    /**
+     * The address of the key that actually produces the EIP-191 signature.
+     * Defaults to {@link address} when omitted.
+     *
+     * Set this only when the tracked subject is a smart wallet whose admin EOA
+     * is the real signer (smart wallet contracts cannot sign EIP-191 directly).
+     * In that case, {@link address} is the smart wallet and `signerAddress` is
+     * the admin EOA.
+     */
+    readonly signerAddress?: string;
+    signMessage(message: string): Promise<string>;
+}
+interface FraudEngineConfig {
+    readonly apiUrl: string;
+    readonly encryptionKey: string;
+    readonly seonRegion?: string;
+    readonly logger?: Logger;
+}
+type ActivityType = "buy_order" | "fingerprint";
+interface DeviceDetails {
+    readonly userAgent: string;
+    readonly platform: string;
+    readonly language: string;
+    readonly languages: string[];
+    readonly screenWidth: number;
+    readonly screenHeight: number;
+    readonly devicePixelRatio: number;
+    readonly timezone: string;
+    readonly timezoneOffset: number;
+    readonly cookiesEnabled: boolean;
+    readonly doNotTrack: string | null;
+    readonly online: boolean;
+    readonly connectionType?: string;
+    readonly deviceMemory?: number;
+    readonly hardwareConcurrency?: number;
+    readonly touchSupport: boolean;
+    readonly maxTouchPoints: number;
+    readonly vendor: string;
+    readonly appVersion: string;
+    readonly colorDepth: number;
+    readonly pixelDepth: number;
+    readonly ip?: string;
+    readonly seonSession?: string;
+}
+interface BuyOrderDetails {
+    readonly cryptoAmount: number;
+    readonly fiatAmount: number;
+    readonly currency: string;
+    readonly recipientAddress: string;
+    readonly fee: number;
+    readonly amountAfterFee: number;
+    readonly paymentMethod?: string;
+    readonly estimatedProcessingTime?: string;
+}
+interface UserDetails {
+    readonly currency?: string;
+    readonly country?: string;
+    readonly language?: string;
+    readonly loginMethod?: "email" | "google" | "phone" | "passkey" | "unknown";
+    readonly loginEmail?: string;
+    readonly loginPhone?: string;
+}
+interface FraudCheckApiResponse {
+    readonly success: boolean;
+    readonly approved: boolean;
+    readonly activity_log_id: number;
+    readonly message: string;
+}
+interface FraudCheckResult {
+    readonly approved: boolean;
+    readonly activityLogId: number;
+    readonly message: string;
+    /**
+     * Link an on-chain order ID to this activity log record.
+     * Call after the buy order is placed on-chain (fire-and-forget).
+     * The signer and activityLogId are captured internally — just pass the orderId.
+     */
+    linkOrder(orderId: string): neverthrow.ResultAsync<LinkOrderResult, FraudEngineError>;
+}
+interface LinkOrderResult {
+    readonly success: boolean;
+    readonly message: string;
+}
+interface FingerprintLogResult {
+    readonly success: boolean;
+    readonly message: string;
+}
+type ProcessBuyOrderResult = {
+    readonly status: "placed";
+    readonly orderId: string;
+} | {
+    readonly status: "rejected";
+    readonly message: string;
+};
+interface FraudEngine {
+    init(): Promise<void>;
+    /**
+     * Low-level: run fraud check only. Returns result with `linkOrder()` for manual linking.
+     * For most consumers, prefer `processBuyOrder()` which handles the full flow.
+     */
+    checkBuyOrder(params: {
+        signer: FraudEngineSigner;
+        orderDetails: BuyOrderDetails;
+        userDetails?: UserDetails;
+        orderSource?: string;
+    }): neverthrow.ResultAsync<FraudCheckResult, FraudEngineError>;
+    /**
+     * Full orchestration: fraud check → place order → auto-link.
+     *
+     * - Runs fraud check on all buy orders (backend handles currency-specific logic).
+     *   If rejected, returns `{ status: "rejected" }` without calling `placeOrder`.
+     *   If approved, calls `placeOrder`, auto-links activity log, returns `{ status: "placed", orderId }`.
+     * - Fail-open: if fraud check API errors, still calls `placeOrder` (no linking since no activityLogId).
+     * - Linking is fire-and-forget: if link fails, order is already placed — error is logged, not propagated.
+     */
+    processBuyOrder(params: {
+        signer: FraudEngineSigner;
+        orderDetails: BuyOrderDetails;
+        userDetails?: UserDetails;
+        orderSource?: string;
+        placeOrder: () => Promise<string>;
+    }): neverthrow.ResultAsync<ProcessBuyOrderResult, FraudEngineError>;
+    logFingerprint(params: {
+        signer: FraudEngineSigner;
+    }): neverthrow.ResultAsync<FingerprintLogResult | null, FraudEngineError>;
+    getFingerprint(): Promise<{
+        visitorId: string;
+        confidence: number;
+    } | null>;
+    getDeviceDetails(): Promise<DeviceDetails>;
+    cleanupSeonStorage(): void;
+}
+
+declare function createFraudEngine(config: FraudEngineConfig): FraudEngine;
+
+declare function getBasicDeviceDetails(): Omit<DeviceDetails, "ip" | "seonSession">;
+declare function fetchIpAddress(): Promise<string | undefined>;
+declare function getDeviceDetails(seonSession?: string): Promise<DeviceDetails>;
+
+declare function encryptPayload(payload: string, aad: string, encryptionKeyHex: string): Promise<string>;
+
+declare function loadFingerprintAgent(): Promise<void>;
+declare function getFingerprint(timeoutMs?: number): Promise<{
+    visitorId: string;
+    confidence: number;
+} | null>;
+
+declare function initSeon(): void;
+declare function getSeonSession(region: string): Promise<string | undefined>;
+declare function cleanupSeonStorage(): void;
+
+declare function getSignedHeaders(signer: FraudEngineSigner, action: "activity-log" | "link-order" | "fingerprint-log"): Promise<Record<string, string>>;
+
+export { type ActivityType, type BuyOrderDetails, type DeviceDetails, type FingerprintLogResult, type FraudCheckApiResponse, type FraudCheckResult, type FraudEngine, type FraudEngineConfig, FraudEngineError, type FraudEngineErrorCode, type FraudEngineSigner, type LinkOrderResult, type Logger, type ProcessBuyOrderResult, type UserDetails, cleanupSeonStorage, createFraudEngine, encryptPayload, fetchIpAddress, getBasicDeviceDetails, getDeviceDetails, getFingerprint, getSeonSession, getSignedHeaders, initSeon, loadFingerprintAgent, noopLogger };

package/dist/fraud-engine.d.ts

@@ -0,0 +1,194 @@
+import * as neverthrow from 'neverthrow';
+
+declare class SdkError<TCode extends string = string> extends Error {
+    readonly code: TCode;
+    readonly cause?: unknown;
+    readonly context?: Record<string, unknown>;
+    constructor(message: string, options: {
+        code: TCode;
+        cause?: unknown;
+        context?: Record<string, unknown>;
+    });
+}
+
+type FraudEngineErrorCode = "API_ERROR" | "ENCRYPTION_ERROR" | "SIGNING_ERROR" | "VALIDATION_ERROR" | "NETWORK_ERROR" | "PLACE_ORDER_ERROR";
+declare class FraudEngineError extends SdkError<FraudEngineErrorCode> {
+    constructor(message: string, options: {
+        code: FraudEngineErrorCode;
+        cause?: unknown;
+        context?: Record<string, unknown>;
+    });
+}
+
+interface Logger {
+    debug(message: string, data?: Record<string, unknown>): void;
+    info(message: string, data?: Record<string, unknown>): void;
+    warn(message: string, data?: Record<string, unknown>): void;
+    error(message: string, data?: Record<string, unknown>): void;
+}
+declare const noopLogger: Logger;
+
+interface FraudEngineSigner {
+    /**
+     * The subject address tracked by the fraud engine — the wallet that places
+     * on-chain orders and appears in reports, watchlist, and risk scoring.
+     *
+     * - For thirdweb smart wallets (ERC-4337 / account abstraction) this is the
+     *   smart account address.
+     * - For plain EOA wallets this is the same address that produces signatures.
+     */
+    readonly address: string;
+    /**
+     * The address of the key that actually produces the EIP-191 signature.
+     * Defaults to {@link address} when omitted.
+     *
+     * Set this only when the tracked subject is a smart wallet whose admin EOA
+     * is the real signer (smart wallet contracts cannot sign EIP-191 directly).
+     * In that case, {@link address} is the smart wallet and `signerAddress` is
+     * the admin EOA.
+     */
+    readonly signerAddress?: string;
+    signMessage(message: string): Promise<string>;
+}
+interface FraudEngineConfig {
+    readonly apiUrl: string;
+    readonly encryptionKey: string;
+    readonly seonRegion?: string;
+    readonly logger?: Logger;
+}
+type ActivityType = "buy_order" | "fingerprint";
+interface DeviceDetails {
+    readonly userAgent: string;
+    readonly platform: string;
+    readonly language: string;
+    readonly languages: string[];
+    readonly screenWidth: number;
+    readonly screenHeight: number;
+    readonly devicePixelRatio: number;
+    readonly timezone: string;
+    readonly timezoneOffset: number;
+    readonly cookiesEnabled: boolean;
+    readonly doNotTrack: string | null;
+    readonly online: boolean;
+    readonly connectionType?: string;
+    readonly deviceMemory?: number;
+    readonly hardwareConcurrency?: number;
+    readonly touchSupport: boolean;
+    readonly maxTouchPoints: number;
+    readonly vendor: string;
+    readonly appVersion: string;
+    readonly colorDepth: number;
+    readonly pixelDepth: number;
+    readonly ip?: string;
+    readonly seonSession?: string;
+}
+interface BuyOrderDetails {
+    readonly cryptoAmount: number;
+    readonly fiatAmount: number;
+    readonly currency: string;
+    readonly recipientAddress: string;
+    readonly fee: number;
+    readonly amountAfterFee: number;
+    readonly paymentMethod?: string;
+    readonly estimatedProcessingTime?: string;
+}
+interface UserDetails {
+    readonly currency?: string;
+    readonly country?: string;
+    readonly language?: string;
+    readonly loginMethod?: "email" | "google" | "phone" | "passkey" | "unknown";
+    readonly loginEmail?: string;
+    readonly loginPhone?: string;
+}
+interface FraudCheckApiResponse {
+    readonly success: boolean;
+    readonly approved: boolean;
+    readonly activity_log_id: number;
+    readonly message: string;
+}
+interface FraudCheckResult {
+    readonly approved: boolean;
+    readonly activityLogId: number;
+    readonly message: string;
+    /**
+     * Link an on-chain order ID to this activity log record.
+     * Call after the buy order is placed on-chain (fire-and-forget).
+     * The signer and activityLogId are captured internally — just pass the orderId.
+     */
+    linkOrder(orderId: string): neverthrow.ResultAsync<LinkOrderResult, FraudEngineError>;
+}
+interface LinkOrderResult {
+    readonly success: boolean;
+    readonly message: string;
+}
+interface FingerprintLogResult {
+    readonly success: boolean;
+    readonly message: string;
+}
+type ProcessBuyOrderResult = {
+    readonly status: "placed";
+    readonly orderId: string;
+} | {
+    readonly status: "rejected";
+    readonly message: string;
+};
+interface FraudEngine {
+    init(): Promise<void>;
+    /**
+     * Low-level: run fraud check only. Returns result with `linkOrder()` for manual linking.
+     * For most consumers, prefer `processBuyOrder()` which handles the full flow.
+     */
+    checkBuyOrder(params: {
+        signer: FraudEngineSigner;
+        orderDetails: BuyOrderDetails;
+        userDetails?: UserDetails;
+        orderSource?: string;
+    }): neverthrow.ResultAsync<FraudCheckResult, FraudEngineError>;
+    /**
+     * Full orchestration: fraud check → place order → auto-link.
+     *
+     * - Runs fraud check on all buy orders (backend handles currency-specific logic).
+     *   If rejected, returns `{ status: "rejected" }` without calling `placeOrder`.
+     *   If approved, calls `placeOrder`, auto-links activity log, returns `{ status: "placed", orderId }`.
+     * - Fail-open: if fraud check API errors, still calls `placeOrder` (no linking since no activityLogId).
+     * - Linking is fire-and-forget: if link fails, order is already placed — error is logged, not propagated.
+     */
+    processBuyOrder(params: {
+        signer: FraudEngineSigner;
+        orderDetails: BuyOrderDetails;
+        userDetails?: UserDetails;
+        orderSource?: string;
+        placeOrder: () => Promise<string>;
+    }): neverthrow.ResultAsync<ProcessBuyOrderResult, FraudEngineError>;
+    logFingerprint(params: {
+        signer: FraudEngineSigner;
+    }): neverthrow.ResultAsync<FingerprintLogResult | null, FraudEngineError>;
+    getFingerprint(): Promise<{
+        visitorId: string;
+        confidence: number;
+    } | null>;
+    getDeviceDetails(): Promise<DeviceDetails>;
+    cleanupSeonStorage(): void;
+}
+
+declare function createFraudEngine(config: FraudEngineConfig): FraudEngine;
+
+declare function getBasicDeviceDetails(): Omit<DeviceDetails, "ip" | "seonSession">;
+declare function fetchIpAddress(): Promise<string | undefined>;
+declare function getDeviceDetails(seonSession?: string): Promise<DeviceDetails>;
+
+declare function encryptPayload(payload: string, aad: string, encryptionKeyHex: string): Promise<string>;
+
+declare function loadFingerprintAgent(): Promise<void>;
+declare function getFingerprint(timeoutMs?: number): Promise<{
+    visitorId: string;
+    confidence: number;
+} | null>;
+
+declare function initSeon(): void;
+declare function getSeonSession(region: string): Promise<string | undefined>;
+declare function cleanupSeonStorage(): void;
+
+declare function getSignedHeaders(signer: FraudEngineSigner, action: "activity-log" | "link-order" | "fingerprint-log"): Promise<Record<string, string>>;
+
+export { type ActivityType, type BuyOrderDetails, type DeviceDetails, type FingerprintLogResult, type FraudCheckApiResponse, type FraudCheckResult, type FraudEngine, type FraudEngineConfig, FraudEngineError, type FraudEngineErrorCode, type FraudEngineSigner, type LinkOrderResult, type Logger, type ProcessBuyOrderResult, type UserDetails, cleanupSeonStorage, createFraudEngine, encryptPayload, fetchIpAddress, getBasicDeviceDetails, getDeviceDetails, getFingerprint, getSeonSession, getSignedHeaders, initSeon, loadFingerprintAgent, noopLogger };