@vesant-sdk/fraud 0.1.1-next.f221d37 → 0.1.2-dev.254dc8c

package/dist/index.d.ts

@@ -4,7 +4,7 @@ import { RiskLevel, Timestamp, BaseClient, RequestOptions } from '@vesant-sdk/co
  * Fraud event type unions aligned with fraud-service support matrix.
  */
 /** Events that run Sift scoring + rule engine */
-type ScoredFraudEventType = '$create_account' | '$login' | '$logout' | '$update_account' | '$update_password' | '$transaction' | '$wager';
+type ScoredFraudEventType = '$create_account' | '$create_order' | '$login' | '$logout' | '$update_account' | '$update_password' | '$transaction' | '$wager';
 /** Feedback-only; no meaningful fraud score in response */
 type ChargebackFraudEventType = '$chargeback';
 /** Union accepted by scoreEvent / scoreEventsBulk */
@@ -12,7 +12,7 @@ type SupportedFraudEventType = ScoredFraudEventType | ChargebackFraudEventType;
 declare const SCORED_FRAUD_EVENT_TYPES: readonly ScoredFraudEventType[];
 declare const CHARGEBACK_FRAUD_EVENT_TYPE: "$chargeback";
 declare const SUPPORTED_FRAUD_EVENT_TYPES: readonly SupportedFraudEventType[];
-declare const PLANNED_FRAUD_EVENT_TYPES: readonly ["$verification", "$link_session_to_user", "$security_notification", "$create_order", "$update_order", "$order_status", "$add_promotion"];
+declare const PLANNED_FRAUD_EVENT_TYPES: readonly ["$verification", "$link_session_to_user", "$security_notification", "$update_order", "$order_status", "$add_promotion"];
 /**
  * Listed in Vesant dashboard / future API — NOT valid for scoreEvent today.
  * @deprecated Not supported by POST /api/v1/fraud/score
@@ -104,13 +104,175 @@ declare const TransactionStatus: {
     readonly Failure: "$failure";
     readonly Pending: "$pending";
 };
+type SiftPaymentType = '$cash' | '$check' | '$credit_card' | '$crypto_currency' | '$debit_card' | '$digital_wallet' | '$electronic_fund_transfer' | '$financing' | '$gift_card' | '$invoice' | '$in_app_purchase' | '$money_order' | '$points' | '$prepaid_card' | '$store_credit' | '$third_party_processor' | '$voucher' | '$sepa_credit' | '$sepa_instant_credit' | '$sepa_direct_debit' | '$ach_credit' | '$ach_debit' | '$wire_credit' | '$wire_debit';
+declare const SiftPaymentTypeValues: readonly ["$cash", "$check", "$credit_card", "$crypto_currency", "$debit_card", "$digital_wallet", "$electronic_fund_transfer", "$financing", "$gift_card", "$invoice", "$in_app_purchase", "$money_order", "$points", "$prepaid_card", "$store_credit", "$third_party_processor", "$voucher", "$sepa_credit", "$sepa_instant_credit", "$sepa_direct_debit", "$ach_credit", "$ach_debit", "$wire_credit", "$wire_debit"];
+declare const PaymentType: {
+    readonly Cash: "$cash";
+    readonly Check: "$check";
+    readonly CreditCard: "$credit_card";
+    readonly CryptoCurrency: "$crypto_currency";
+    readonly DebitCard: "$debit_card";
+    readonly DigitalWallet: "$digital_wallet";
+    readonly ElectronicFundTransfer: "$electronic_fund_transfer";
+    readonly Financing: "$financing";
+    readonly GiftCard: "$gift_card";
+    readonly Invoice: "$invoice";
+    readonly InAppPurchase: "$in_app_purchase";
+    readonly MoneyOrder: "$money_order";
+    readonly Points: "$points";
+    readonly PrepaidCard: "$prepaid_card";
+    readonly StoreCredit: "$store_credit";
+    readonly ThirdPartyProcessor: "$third_party_processor";
+    readonly Voucher: "$voucher";
+    readonly SepaCredit: "$sepa_credit";
+    readonly SepaInstantCredit: "$sepa_instant_credit";
+    readonly SepaDirectDebit: "$sepa_direct_debit";
+    readonly AchCredit: "$ach_credit";
+    readonly AchDebit: "$ach_debit";
+    readonly WireCredit: "$wire_credit";
+    readonly WireDebit: "$wire_debit";
+};
+type SiftWalletType = '$crypto' | '$digital' | '$fiat';
+declare const SiftWalletTypeValues: readonly ["$crypto", "$digital", "$fiat"];
+declare const WalletType: {
+    readonly Crypto: "$crypto";
+    readonly Digital: "$digital";
+    readonly Fiat: "$fiat";
+};
 type FraudRiskLevel = 'low' | 'medium' | 'high' | 'critical';
 
 /**
- * Custom metadata for fraud score requests (non-Sift reserved keys).
+ * Metadata for fraud score requests.
+ * Plain keys are Vesant rule signals; $-prefixed keys are Sift pass-through (or set via typed fields).
  */
-type FraudCustomMetadata = Record<string, unknown>;
-declare function hasReservedMetadataKey(metadata: FraudCustomMetadata): string | undefined;
+interface FraudRuleSignalMetadata {
+    /** Rule signal payment method (e.g. "$credit_card"), not Sift $payment_method object */
+    payment_method?: string;
+    country?: string;
+    /** Customer date of birth, ISO 8601 (YYYY-MM-DD). Useful on onboarding ($create_account). */
+    date_of_birth?: string;
+    two_fa_enabled?: boolean;
+    two_fa_disabled?: boolean;
+    two_fa_method_changed?: boolean;
+    ip_country_mismatch?: boolean;
+    is_first_deposit?: boolean;
+    cumulative_deposit_amount?: number;
+    deposit_count?: number;
+    failed_deposit_count?: number;
+    is_first_withdrawal?: boolean;
+    withdrawal_method_differs?: boolean;
+    cumulative_withdrawal_amount?: number;
+    withdrawal_count?: number;
+    hours_since_last_deposit?: number;
+    days_since_last_activity?: number;
+    hours_since_account_creation?: number;
+}
+/** Extra Sift fields forwarded verbatim in metadata (e.g. $referrer_user_id, $promotions). */
+type SiftPassThroughMetadata = Record<`$${string}`, unknown>;
+type FraudCustomMetadata = FraudRuleSignalMetadata & SiftPassThroughMetadata & Record<string, unknown>;
+/** Maps typed request fields to metadata keys they populate (typed values win on normalize). */
+declare const TYPED_SIFT_METADATA_KEYS: Readonly<Record<string, string>>;
+declare function findMetadataConflictWithTypedFields(metadata: FraudCustomMetadata, request: Record<string, unknown>): string | undefined;
+
+/**
+ * Optional top-level rule-signal fields copied into plain metadata on the wire.
+ */
+interface LoginRuleSignals {
+    ip_country_mismatch?: boolean;
+}
+interface UpdateAccountRuleSignals {
+    two_fa_enabled?: boolean;
+    two_fa_disabled?: boolean;
+    two_fa_method_changed?: boolean;
+}
+interface TransactionRuleSignals {
+    payment_method?: string;
+    is_first_deposit?: boolean;
+    cumulative_deposit_amount?: number;
+    deposit_count?: number;
+    failed_deposit_count?: number;
+    is_first_withdrawal?: boolean;
+    withdrawal_method_differs?: boolean;
+    cumulative_withdrawal_amount?: number;
+    withdrawal_count?: number;
+    hours_since_last_deposit?: number;
+    days_since_last_activity?: number;
+    hours_since_account_creation?: number;
+}
+declare const LOGIN_RULE_SIGNAL_KEYS: readonly ["ip_country_mismatch"];
+declare const UPDATE_ACCOUNT_RULE_SIGNAL_KEYS: readonly ["two_fa_enabled", "two_fa_disabled", "two_fa_method_changed"];
+declare const TRANSACTION_RULE_SIGNAL_KEYS: readonly ["payment_method", "is_first_deposit", "cumulative_deposit_amount", "deposit_count", "failed_deposit_count", "is_first_withdrawal", "withdrawal_method_differs", "cumulative_withdrawal_amount", "withdrawal_count", "hours_since_last_deposit", "days_since_last_activity", "hours_since_account_creation"];
+
+/**
+ * Sift-aligned structured fields normalized into metadata.$* on the wire.
+ */
+interface SiftBillingAddress {
+    name?: string;
+    phone?: string;
+    address_1?: string;
+    address_2?: string;
+    city?: string;
+    region?: string;
+    country?: string;
+    zipcode?: string;
+    [key: string]: unknown;
+}
+interface SiftPaymentMethod {
+    payment_type?: string;
+    payment_gateway?: string;
+    card_bin?: string;
+    card_last4?: string;
+    avs_result_code?: string;
+    cvv_result_code?: string;
+    verification_status?: string;
+    routing_number?: string;
+    account_holder_name?: string;
+    account_number_last5?: string;
+    bank_name?: string;
+    bank_country?: string;
+    wallet_address?: string;
+    wallet_type?: '$crypto' | '$digital' | '$fiat' | string;
+    paypal_payer_id?: string;
+    paypal_payer_email?: string;
+    /**
+     * @deprecated Not a Sift field — use account_number_last5. Stripped by normalizeSiftPaymentMethod.
+     */
+    account_number_last4?: string;
+    /**
+     * @deprecated Not a Sift field — moved to metadata by normalizeSiftPaymentMethod.
+     */
+    account_id?: string | number;
+    /**
+     * @deprecated Not a Sift field — moved to metadata by normalizeSiftPaymentMethod.
+     */
+    wallet_address_last4?: string;
+    /**
+     * @deprecated Not a Sift field — moved to metadata by normalizeSiftPaymentMethod.
+     */
+    crypto_currency?: string;
+    /**
+     * @deprecated Not a Sift field — moved to metadata by normalizeSiftPaymentMethod.
+     */
+    network?: string;
+    [key: string]: unknown;
+}
+interface SiftApp {
+    os?: string;
+    os_version?: string;
+    device_manufacturer?: string;
+    device_model?: string;
+    device_unique_id?: string;
+    app_name?: string;
+    app_version?: string;
+    client_language?: string;
+    [key: string]: unknown;
+}
+interface SiftBrowser {
+    user_agent?: string;
+    accept_language?: string;
+    content_language?: string;
+    [key: string]: unknown;
+}
 
 /**
  * Discriminated fraud score request types keyed on event_type.
@@ -124,16 +286,37 @@ interface FraudScoreRequestBase {
     ip_address?: string;
     device_id?: string;
     user_agent?: string;
+    /** Maps to metadata.$session_id */
+    session_id?: string;
+    /** Maps to metadata.$user_email */
+    user_email?: string;
+    /** Maps to metadata.$name */
+    name?: string;
+    /** Maps to metadata.$phone */
+    phone?: string;
+    /** Maps to metadata.$payment_method (Sift object) — typically on transactions */
+    sift_payment_method?: SiftPaymentMethod;
+    /** Maps to metadata.$payment_methods (Sift array) — account create/update baseline */
+    payment_methods?: SiftPaymentMethod[];
+    /** Maps to metadata.$billing_address */
+    billing_address?: SiftBillingAddress;
+    /** Maps to metadata.$app */
+    app?: SiftApp;
     /**
-     * Custom fields only — keys must NOT start with '$'.
-     * Sift reserved fields belong on typed request fields.
+     * Plain Vesant rule signals and optional $-prefixed Sift pass-through keys.
+     * Prefer typed fields for common Sift keys ($session_id, $user_email, etc.).
      */
     metadata?: FraudCustomMetadata;
+    /**
+     * When true, payment_methods / sift_payment_method are passed through without
+     * Sift field normalization (for tenants sending pre-normalized wire keys).
+     */
+    skip_payment_method_normalization?: boolean;
 }
 interface CreateAccountScoreRequest extends FraudScoreRequestBase {
     event_type: '$create_account';
 }
-interface LoginScoreRequest extends FraudScoreRequestBase {
+interface LoginScoreRequest extends FraudScoreRequestBase, LoginRuleSignals {
     event_type: '$login';
     login_status?: SiftLoginStatus;
     login_failure_reason?: SiftLoginFailureReason;
@@ -141,15 +324,19 @@ interface LoginScoreRequest extends FraudScoreRequestBase {
 interface LogoutScoreRequest extends FraudScoreRequestBase {
     event_type: '$logout';
 }
-interface UpdateAccountScoreRequest extends FraudScoreRequestBase {
+interface UpdateAccountScoreRequest extends FraudScoreRequestBase, UpdateAccountRuleSignals {
     event_type: '$update_account';
+    /** Maps to metadata.$verification_phone_number */
+    verification_phone_number?: string;
 }
 interface UpdatePasswordScoreRequest extends FraudScoreRequestBase {
     event_type: '$update_password';
-    password_reason: SiftPasswordUpdateReason;
-    password_status: SiftPasswordUpdateStatus;
+    /** Defaults to $user_update on the wire when omitted */
+    password_reason?: SiftPasswordUpdateReason;
+    /** Defaults to $success on the wire when omitted */
+    password_status?: SiftPasswordUpdateStatus;
 }
-interface TransactionScoreRequest extends FraudScoreRequestBase {
+interface TransactionScoreRequest extends FraudScoreRequestBase, TransactionRuleSignals {
     event_type: '$transaction';
     amount: number;
     currency: string;
@@ -159,6 +346,29 @@ interface TransactionScoreRequest extends FraudScoreRequestBase {
     decline_category?: string;
     transfer_recipient_user_id?: string;
 }
+interface CreateOrderScoreRequest extends FraudScoreRequestBase {
+    event_type: '$create_order';
+    session_id?: string;
+    user_email?: string;
+    verification_phone_number?: string;
+    order_id?: string;
+    amount: number;
+    currency_code: string;
+    exchange_rate?: unknown;
+    payment_methods?: SiftPaymentMethod[];
+    billing_address?: SiftBillingAddress;
+    shipping_address?: SiftBillingAddress;
+    expedited_shipping?: boolean;
+    shipping_method?: '$electronic' | '$physical' | (string & Record<string, never>);
+    shipping_carrier?: string;
+    shipping_tracking_numbers?: string[];
+    brand_name?: string;
+    site_country?: string;
+    site_domain?: string;
+    ip?: string;
+    browser?: SiftBrowser;
+    app?: SiftApp;
+}
 interface WagerScoreRequest extends FraudScoreRequestBase {
     event_type: '$wager';
     transaction_id: string;
@@ -178,7 +388,7 @@ interface ChargebackScoreRequest extends FraudScoreRequestBase {
     chargeback_reason?: SiftChargebackReason;
     ach_return_code?: string;
 }
-type FraudScoreRequest = CreateAccountScoreRequest | LoginScoreRequest | LogoutScoreRequest | UpdateAccountScoreRequest | UpdatePasswordScoreRequest | TransactionScoreRequest | WagerScoreRequest | ChargebackScoreRequest;
+type FraudScoreRequest = CreateAccountScoreRequest | LoginScoreRequest | LogoutScoreRequest | UpdateAccountScoreRequest | UpdatePasswordScoreRequest | TransactionScoreRequest | CreateOrderScoreRequest | WagerScoreRequest | ChargebackScoreRequest;
 type ScoredFraudScoreRequest = Extract<FraudScoreRequest, {
     event_type: ScoredFraudEventType;
 }>;
@@ -246,4 +456,29 @@ declare function normalizeScoreRequestForApi(request: FraudScoreRequest): Record
  */
 declare function buildScoreRequestPreview(request: FraudScoreRequest): Record<string, unknown>;
 
-export { CHARGEBACK_FRAUD_EVENT_TYPE, type ChargebackFraudEventType, ChargebackReason, type ChargebackScoreRequest, type ChargebackScoreResponseData, ChargebackState, type CreateAccountScoreRequest, FraudClient, type FraudCustomMetadata, type FraudDecision, type FraudEventType, type FraudReactionType, type FraudRiskLevel, type FraudScoreRequest, type FraudScoreRequestBase, type FraudScoreResponseData, type FraudScoreResponseEnvelope, type FraudScoreResponseMetadata, type LoginScoreRequest, LoginStatus, type LogoutScoreRequest, PLANNED_FRAUD_EVENT_TYPES, PasswordUpdateReason, PasswordUpdateStatus, type PlannedFraudEventType, SCORED_FRAUD_EVENT_TYPES, SUPPORTED_FRAUD_EVENT_TYPES, type ScoredFraudEventType, type ScoredFraudScoreRequest, type SiftChargebackReason, SiftChargebackReasonValues, type SiftChargebackState, SiftChargebackStateValues, type SiftLoginFailureReason, SiftLoginFailureReasonValues, type SiftLoginStatus, SiftLoginStatusValues, type SiftPasswordUpdateReason, SiftPasswordUpdateReasonValues, type SiftPasswordUpdateStatus, SiftPasswordUpdateStatusValues, type SiftTransactionStatus, SiftTransactionStatusValues, type SiftTransactionType, SiftTransactionTypeValues, type SiftWagerStatus, SiftWagerStatusValues, type SupportedFraudEventType, type TenantAction, type TransactionScoreRequest, TransactionStatus, TransactionType, type UpdateAccountScoreRequest, type UpdatePasswordScoreRequest, type WagerScoreRequest, WagerStatus, buildScoreRequestPreview, hasReservedMetadataKey, isPlannedFraudEventType, isSupportedFraudEventType, normalizeScoreRequestForApi, validateScoreRequest };
+/**
+ * Maps tenant-internal payment type signals to Sift-valid $payment_type values.
+ * Returns undefined when the value cannot be mapped.
+ */
+declare function normalizeSiftPaymentType(value: string | undefined): SiftPaymentType | undefined;
+/**
+ * Normalizes last-4/last-5 account digits for Sift $account_number_last5.
+ */
+declare function toSiftAccountNumberLast5(value: unknown): string | undefined;
+type NormalizePaymentMethodResult = {
+    method: SiftPaymentMethod;
+    metadataExtras?: Record<string, unknown>;
+};
+/**
+ * Normalizes a single payment method object for Sift wire format.
+ */
+declare function normalizeSiftPaymentMethod(raw: Record<string, unknown>): NormalizePaymentMethodResult | null;
+/**
+ * Normalizes payment method arrays and aggregates stripped metadata.
+ */
+declare function normalizeSiftPaymentMethods(methods: SiftPaymentMethod[] | undefined): {
+    payment_methods?: SiftPaymentMethod[];
+    metadata?: Record<string, unknown>;
+};
+
+export { CHARGEBACK_FRAUD_EVENT_TYPE, type ChargebackFraudEventType, ChargebackReason, type ChargebackScoreRequest, type ChargebackScoreResponseData, ChargebackState, type CreateAccountScoreRequest, type CreateOrderScoreRequest, FraudClient, type FraudCustomMetadata, type FraudDecision, type FraudEventType, type FraudReactionType, type FraudRiskLevel, type FraudRuleSignalMetadata, type FraudScoreRequest, type FraudScoreRequestBase, type FraudScoreResponseData, type FraudScoreResponseEnvelope, type FraudScoreResponseMetadata, LOGIN_RULE_SIGNAL_KEYS, type LoginRuleSignals, type LoginScoreRequest, LoginStatus, type LogoutScoreRequest, PLANNED_FRAUD_EVENT_TYPES, PasswordUpdateReason, PasswordUpdateStatus, PaymentType, type PlannedFraudEventType, SCORED_FRAUD_EVENT_TYPES, SUPPORTED_FRAUD_EVENT_TYPES, type ScoredFraudEventType, type ScoredFraudScoreRequest, type SiftApp, type SiftBillingAddress, type SiftBrowser, type SiftChargebackReason, SiftChargebackReasonValues, type SiftChargebackState, SiftChargebackStateValues, type SiftLoginFailureReason, SiftLoginFailureReasonValues, type SiftLoginStatus, SiftLoginStatusValues, type SiftPassThroughMetadata, type SiftPasswordUpdateReason, SiftPasswordUpdateReasonValues, type SiftPasswordUpdateStatus, SiftPasswordUpdateStatusValues, type SiftPaymentMethod, type SiftPaymentType, SiftPaymentTypeValues, type SiftTransactionStatus, SiftTransactionStatusValues, type SiftTransactionType, SiftTransactionTypeValues, type SiftWagerStatus, SiftWagerStatusValues, type SiftWalletType, SiftWalletTypeValues, type SupportedFraudEventType, TRANSACTION_RULE_SIGNAL_KEYS, TYPED_SIFT_METADATA_KEYS, type TenantAction, type TransactionRuleSignals, type TransactionScoreRequest, TransactionStatus, TransactionType, UPDATE_ACCOUNT_RULE_SIGNAL_KEYS, type UpdateAccountRuleSignals, type UpdateAccountScoreRequest, type UpdatePasswordScoreRequest, type WagerScoreRequest, WagerStatus, WalletType, buildScoreRequestPreview, findMetadataConflictWithTypedFields, isPlannedFraudEventType, isSupportedFraudEventType, normalizeScoreRequestForApi, normalizeSiftPaymentMethod, normalizeSiftPaymentMethods, normalizeSiftPaymentType, toSiftAccountNumberLast5, validateScoreRequest };