@vesant-sdk/fraud 0.1.0 → 0.1.1-dev.0d9ee60
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +67 -0
- package/dist/index.d.mts +197 -11
- package/dist/index.d.ts +197 -11
- package/dist/index.js +461 -20
- package/dist/index.js.map +1 -1
- package/dist/index.mjs +436 -22
- package/dist/index.mjs.map +1 -1
- package/package.json +47 -39
package/README.md
ADDED
|
@@ -0,0 +1,67 @@
|
|
|
1
|
+
# @vesant-sdk/fraud
|
|
2
|
+
|
|
3
|
+
Fraud detection and scoring client for the Vesant Compliance Platform.
|
|
4
|
+
|
|
5
|
+
## Install
|
|
6
|
+
|
|
7
|
+
```bash
|
|
8
|
+
npm install @vesant-sdk/fraud
|
|
9
|
+
```
|
|
10
|
+
|
|
11
|
+
Requires `@vesant-sdk/core` (installed automatically as a dependency).
|
|
12
|
+
|
|
13
|
+
## Quick start
|
|
14
|
+
|
|
15
|
+
```typescript
|
|
16
|
+
import { FraudClient, TransactionType } from '@vesant-sdk/fraud';
|
|
17
|
+
|
|
18
|
+
const fraud = new FraudClient({
|
|
19
|
+
baseURL: process.env.VESANT_API_URL!,
|
|
20
|
+
tenantId: process.env.VESANT_TENANT_ID!,
|
|
21
|
+
apiKey: process.env.VESANT_API_KEY!,
|
|
22
|
+
});
|
|
23
|
+
|
|
24
|
+
const result = await fraud.scoreEvent({
|
|
25
|
+
customer_id: 'customer-uuid',
|
|
26
|
+
sift_user_id: 'stable-sift-user-id',
|
|
27
|
+
event_type: '$transaction',
|
|
28
|
+
transaction_id: 'TX-001',
|
|
29
|
+
amount: 99.99,
|
|
30
|
+
currency: 'USD',
|
|
31
|
+
transaction_type: TransactionType.Sale,
|
|
32
|
+
});
|
|
33
|
+
```
|
|
34
|
+
|
|
35
|
+
## Supported events
|
|
36
|
+
|
|
37
|
+
| Category | `event_type` values |
|
|
38
|
+
|----------|---------------------|
|
|
39
|
+
| Scored | `$create_account`, `$login`, `$logout`, `$update_account`, `$update_password`, `$transaction`, `$wager` |
|
|
40
|
+
| Feedback | `$chargeback` (no meaningful score/decision) |
|
|
41
|
+
|
|
42
|
+
Types such as `$verification` appear in the Vesant dashboard but are **not** accepted by `scoreEvent` (SDK rejects them before HTTP).
|
|
43
|
+
|
|
44
|
+
## Migration from 0.1.x
|
|
45
|
+
|
|
46
|
+
1. **Transactions** — add required `amount` (> 0) and `currency`.
|
|
47
|
+
2. **Wagers** — add `wager_type`, `wager_status`, `amount`, `currency`; `transaction_id` is the wager id.
|
|
48
|
+
3. **Password updates** — add `password_reason` and `password_status` (use `PasswordUpdateReason` / `PasswordUpdateStatus` constants).
|
|
49
|
+
4. **Chargebacks** — use `event_type: '$chargeback'` with `transaction_id` or `order_id`.
|
|
50
|
+
5. **Metadata** — do not put `$`-prefixed Sift keys in `metadata`; use typed request fields.
|
|
51
|
+
|
|
52
|
+
## API normalization
|
|
53
|
+
|
|
54
|
+
Until the fraud-service maps all Sift fields at the top level, the client copies some typed fields into `metadata` on the wire (e.g. `password_reason` → `metadata.$reason`). Use `buildScoreRequestPreview(request)` to inspect the JSON body sent to the API.
|
|
55
|
+
|
|
56
|
+
## Validation
|
|
57
|
+
|
|
58
|
+
```typescript
|
|
59
|
+
import { validateScoreRequest } from '@vesant-sdk/fraud';
|
|
60
|
+
|
|
61
|
+
validateScoreRequest(request); // throws ValidationError from @vesant-sdk/core
|
|
62
|
+
```
|
|
63
|
+
|
|
64
|
+
## Docs
|
|
65
|
+
|
|
66
|
+
- [Fraud Integration Guide](../../../docs/guides/fraud-integration.md)
|
|
67
|
+
- [FraudClient API Reference](../../../docs/api-reference/fraud-client.md)
|
package/dist/index.d.mts
CHANGED
|
@@ -1,22 +1,192 @@
|
|
|
1
|
-
import {
|
|
1
|
+
import { RiskLevel, Timestamp, BaseClient, RequestOptions } from '@vesant-sdk/core';
|
|
2
2
|
|
|
3
3
|
/**
|
|
4
|
-
* Fraud
|
|
4
|
+
* Fraud event type unions aligned with fraud-service support matrix.
|
|
5
5
|
*/
|
|
6
|
+
/** Events that run Sift scoring + rule engine */
|
|
7
|
+
type ScoredFraudEventType = '$create_account' | '$login' | '$logout' | '$update_account' | '$update_password' | '$transaction' | '$wager';
|
|
8
|
+
/** Feedback-only; no meaningful fraud score in response */
|
|
9
|
+
type ChargebackFraudEventType = '$chargeback';
|
|
10
|
+
/** Union accepted by scoreEvent / scoreEventsBulk */
|
|
11
|
+
type SupportedFraudEventType = ScoredFraudEventType | ChargebackFraudEventType;
|
|
12
|
+
declare const SCORED_FRAUD_EVENT_TYPES: readonly ScoredFraudEventType[];
|
|
13
|
+
declare const CHARGEBACK_FRAUD_EVENT_TYPE: "$chargeback";
|
|
14
|
+
declare const SUPPORTED_FRAUD_EVENT_TYPES: readonly SupportedFraudEventType[];
|
|
15
|
+
declare const PLANNED_FRAUD_EVENT_TYPES: readonly ["$verification", "$link_session_to_user", "$security_notification", "$create_order", "$update_order", "$order_status", "$add_promotion"];
|
|
16
|
+
/**
|
|
17
|
+
* Listed in Vesant dashboard / future API — NOT valid for scoreEvent today.
|
|
18
|
+
* @deprecated Not supported by POST /api/v1/fraud/score
|
|
19
|
+
*/
|
|
20
|
+
type PlannedFraudEventType = (typeof PLANNED_FRAUD_EVENT_TYPES)[number];
|
|
21
|
+
/**
|
|
22
|
+
* @deprecated Use SupportedFraudEventType; kept for migration
|
|
23
|
+
*/
|
|
24
|
+
type FraudEventType = SupportedFraudEventType | (typeof PLANNED_FRAUD_EVENT_TYPES)[number];
|
|
25
|
+
declare function isPlannedFraudEventType(eventType: string): eventType is (typeof PLANNED_FRAUD_EVENT_TYPES)[number];
|
|
26
|
+
declare function isSupportedFraudEventType(eventType: string): eventType is SupportedFraudEventType;
|
|
27
|
+
|
|
28
|
+
/**
|
|
29
|
+
* Sift-aligned enum types and const objects for fraud scoring requests.
|
|
30
|
+
*/
|
|
31
|
+
type SiftTransactionType = '$sale' | '$authorize' | '$capture' | '$void' | '$refund' | '$deposit' | '$withdrawal' | '$transfer' | '$buy' | '$sell' | '$send' | '$receive';
|
|
32
|
+
declare const SiftTransactionTypeValues: readonly ["$sale", "$authorize", "$capture", "$void", "$refund", "$deposit", "$withdrawal", "$transfer", "$buy", "$sell", "$send", "$receive"];
|
|
33
|
+
declare const TransactionType: {
|
|
34
|
+
readonly Sale: "$sale";
|
|
35
|
+
readonly Authorize: "$authorize";
|
|
36
|
+
readonly Capture: "$capture";
|
|
37
|
+
readonly Void: "$void";
|
|
38
|
+
readonly Refund: "$refund";
|
|
39
|
+
readonly Deposit: "$deposit";
|
|
40
|
+
readonly Withdrawal: "$withdrawal";
|
|
41
|
+
readonly Transfer: "$transfer";
|
|
42
|
+
readonly Buy: "$buy";
|
|
43
|
+
readonly Sell: "$sell";
|
|
44
|
+
readonly Send: "$send";
|
|
45
|
+
readonly Receive: "$receive";
|
|
46
|
+
};
|
|
47
|
+
type SiftChargebackState = '$received' | '$accepted' | '$disputed' | '$won' | '$lost';
|
|
48
|
+
declare const SiftChargebackStateValues: readonly ["$received", "$accepted", "$disputed", "$won", "$lost"];
|
|
49
|
+
declare const ChargebackState: {
|
|
50
|
+
readonly Received: "$received";
|
|
51
|
+
readonly Accepted: "$accepted";
|
|
52
|
+
readonly Disputed: "$disputed";
|
|
53
|
+
readonly Won: "$won";
|
|
54
|
+
readonly Lost: "$lost";
|
|
55
|
+
};
|
|
56
|
+
type SiftChargebackReason = '$fraud' | '$duplicate' | '$product_not_received' | '$product_unacceptable' | '$authorization' | '$consumer_disputes' | '$processing_errors' | '$cancel_subscription' | '$friendly_fraud' | '$ach_return' | '$ach_reversal' | '$other';
|
|
57
|
+
declare const SiftChargebackReasonValues: readonly ["$fraud", "$duplicate", "$product_not_received", "$product_unacceptable", "$authorization", "$consumer_disputes", "$processing_errors", "$cancel_subscription", "$friendly_fraud", "$ach_return", "$ach_reversal", "$other"];
|
|
58
|
+
declare const ChargebackReason: {
|
|
59
|
+
readonly Fraud: "$fraud";
|
|
60
|
+
readonly Duplicate: "$duplicate";
|
|
61
|
+
readonly ProductNotReceived: "$product_not_received";
|
|
62
|
+
readonly ProductUnacceptable: "$product_unacceptable";
|
|
63
|
+
readonly Authorization: "$authorization";
|
|
64
|
+
readonly ConsumerDisputes: "$consumer_disputes";
|
|
65
|
+
readonly ProcessingErrors: "$processing_errors";
|
|
66
|
+
readonly CancelSubscription: "$cancel_subscription";
|
|
67
|
+
readonly FriendlyFraud: "$friendly_fraud";
|
|
68
|
+
readonly AchReturn: "$ach_return";
|
|
69
|
+
readonly AchReversal: "$ach_reversal";
|
|
70
|
+
readonly Other: "$other";
|
|
71
|
+
};
|
|
72
|
+
type SiftLoginStatus = '$success' | '$failure';
|
|
73
|
+
declare const SiftLoginStatusValues: readonly ["$success", "$failure"];
|
|
74
|
+
declare const LoginStatus: {
|
|
75
|
+
readonly Success: "$success";
|
|
76
|
+
readonly Failure: "$failure";
|
|
77
|
+
};
|
|
78
|
+
type SiftLoginFailureReason = '$account_unknown' | '$account_suspended' | '$account_disabled' | '$wrong_password';
|
|
79
|
+
declare const SiftLoginFailureReasonValues: readonly ["$account_unknown", "$account_suspended", "$account_disabled", "$wrong_password"];
|
|
80
|
+
type SiftPasswordUpdateReason = '$user_update' | '$forgot_password' | '$forced_reset';
|
|
81
|
+
declare const SiftPasswordUpdateReasonValues: readonly ["$user_update", "$forgot_password", "$forced_reset"];
|
|
82
|
+
declare const PasswordUpdateReason: {
|
|
83
|
+
readonly UserUpdate: "$user_update";
|
|
84
|
+
readonly ForgotPassword: "$forgot_password";
|
|
85
|
+
readonly ForcedReset: "$forced_reset";
|
|
86
|
+
};
|
|
87
|
+
type SiftPasswordUpdateStatus = '$pending' | '$success' | '$failure';
|
|
88
|
+
declare const SiftPasswordUpdateStatusValues: readonly ["$pending", "$success", "$failure"];
|
|
89
|
+
declare const PasswordUpdateStatus: {
|
|
90
|
+
readonly Pending: "$pending";
|
|
91
|
+
readonly Success: "$success";
|
|
92
|
+
readonly Failure: "$failure";
|
|
93
|
+
};
|
|
94
|
+
type SiftWagerStatus = '$accept' | '$cancel';
|
|
95
|
+
declare const SiftWagerStatusValues: readonly ["$accept", "$cancel"];
|
|
96
|
+
declare const WagerStatus: {
|
|
97
|
+
readonly Accept: "$accept";
|
|
98
|
+
readonly Cancel: "$cancel";
|
|
99
|
+
};
|
|
100
|
+
type SiftTransactionStatus = '$success' | '$failure' | '$pending';
|
|
101
|
+
declare const SiftTransactionStatusValues: readonly ["$success", "$failure", "$pending"];
|
|
102
|
+
declare const TransactionStatus: {
|
|
103
|
+
readonly Success: "$success";
|
|
104
|
+
readonly Failure: "$failure";
|
|
105
|
+
readonly Pending: "$pending";
|
|
106
|
+
};
|
|
107
|
+
type FraudRiskLevel = 'low' | 'medium' | 'high' | 'critical';
|
|
108
|
+
|
|
109
|
+
/**
|
|
110
|
+
* Custom metadata for fraud score requests (non-Sift reserved keys).
|
|
111
|
+
*/
|
|
112
|
+
type FraudCustomMetadata = Record<string, unknown>;
|
|
113
|
+
declare function hasReservedMetadataKey(metadata: FraudCustomMetadata): string | undefined;
|
|
6
114
|
|
|
7
|
-
|
|
8
|
-
|
|
115
|
+
/**
|
|
116
|
+
* Discriminated fraud score request types keyed on event_type.
|
|
117
|
+
*/
|
|
118
|
+
|
|
119
|
+
interface FraudScoreRequestBase {
|
|
120
|
+
/** Tenant customer UUID or stable ID */
|
|
9
121
|
customer_id: string;
|
|
122
|
+
/** Sift $user_id — typically stable per customer */
|
|
10
123
|
sift_user_id: string;
|
|
11
|
-
event_type: FraudEventType;
|
|
12
|
-
transaction_id?: string;
|
|
13
|
-
amount?: number;
|
|
14
|
-
currency?: string;
|
|
15
124
|
ip_address?: string;
|
|
16
125
|
device_id?: string;
|
|
17
126
|
user_agent?: string;
|
|
18
|
-
|
|
127
|
+
/**
|
|
128
|
+
* Custom fields only — keys must NOT start with '$'.
|
|
129
|
+
* Sift reserved fields belong on typed request fields.
|
|
130
|
+
*/
|
|
131
|
+
metadata?: FraudCustomMetadata;
|
|
132
|
+
}
|
|
133
|
+
interface CreateAccountScoreRequest extends FraudScoreRequestBase {
|
|
134
|
+
event_type: '$create_account';
|
|
135
|
+
}
|
|
136
|
+
interface LoginScoreRequest extends FraudScoreRequestBase {
|
|
137
|
+
event_type: '$login';
|
|
138
|
+
login_status?: SiftLoginStatus;
|
|
139
|
+
login_failure_reason?: SiftLoginFailureReason;
|
|
140
|
+
}
|
|
141
|
+
interface LogoutScoreRequest extends FraudScoreRequestBase {
|
|
142
|
+
event_type: '$logout';
|
|
143
|
+
}
|
|
144
|
+
interface UpdateAccountScoreRequest extends FraudScoreRequestBase {
|
|
145
|
+
event_type: '$update_account';
|
|
19
146
|
}
|
|
147
|
+
interface UpdatePasswordScoreRequest extends FraudScoreRequestBase {
|
|
148
|
+
event_type: '$update_password';
|
|
149
|
+
password_reason: SiftPasswordUpdateReason;
|
|
150
|
+
password_status: SiftPasswordUpdateStatus;
|
|
151
|
+
}
|
|
152
|
+
interface TransactionScoreRequest extends FraudScoreRequestBase {
|
|
153
|
+
event_type: '$transaction';
|
|
154
|
+
amount: number;
|
|
155
|
+
currency: string;
|
|
156
|
+
transaction_id?: string;
|
|
157
|
+
transaction_type?: SiftTransactionType;
|
|
158
|
+
transaction_status?: SiftTransactionStatus;
|
|
159
|
+
decline_category?: string;
|
|
160
|
+
transfer_recipient_user_id?: string;
|
|
161
|
+
}
|
|
162
|
+
interface WagerScoreRequest extends FraudScoreRequestBase {
|
|
163
|
+
event_type: '$wager';
|
|
164
|
+
transaction_id: string;
|
|
165
|
+
wager_type: string;
|
|
166
|
+
wager_status: SiftWagerStatus;
|
|
167
|
+
amount: number;
|
|
168
|
+
currency: string;
|
|
169
|
+
wager_event_type?: string;
|
|
170
|
+
wager_event_name?: string;
|
|
171
|
+
wager_event_id?: string;
|
|
172
|
+
}
|
|
173
|
+
interface ChargebackScoreRequest extends FraudScoreRequestBase {
|
|
174
|
+
event_type: ChargebackFraudEventType;
|
|
175
|
+
transaction_id?: string;
|
|
176
|
+
order_id?: string;
|
|
177
|
+
chargeback_state?: SiftChargebackState;
|
|
178
|
+
chargeback_reason?: SiftChargebackReason;
|
|
179
|
+
ach_return_code?: string;
|
|
180
|
+
}
|
|
181
|
+
type FraudScoreRequest = CreateAccountScoreRequest | LoginScoreRequest | LogoutScoreRequest | UpdateAccountScoreRequest | UpdatePasswordScoreRequest | TransactionScoreRequest | WagerScoreRequest | ChargebackScoreRequest;
|
|
182
|
+
type ScoredFraudScoreRequest = Extract<FraudScoreRequest, {
|
|
183
|
+
event_type: ScoredFraudEventType;
|
|
184
|
+
}>;
|
|
185
|
+
|
|
186
|
+
/**
|
|
187
|
+
* Fraud scoring types — responses and re-exports.
|
|
188
|
+
*/
|
|
189
|
+
|
|
20
190
|
type FraudReactionType = 'approve' | 'reject' | 'hold' | 'restrict' | 'block' | 'refund' | 'void_transaction' | 'reverse_transaction' | 'freeze_account' | 'block_withdrawal' | 'limit_withdrawal' | 'disable_payment_method' | 'revoke_session' | 'require_reauth' | 'trigger_alert' | 'no_alert' | 'escalate' | 'increase_priority' | 'create_case' | 'auto_lock_account' | 'notify_team' | (string & Record<string, never>);
|
|
21
191
|
interface TenantAction {
|
|
22
192
|
type: FraudReactionType;
|
|
@@ -36,6 +206,13 @@ interface FraudScoreResponseData {
|
|
|
36
206
|
alert_reference?: string;
|
|
37
207
|
tenant_actions: TenantAction[];
|
|
38
208
|
}
|
|
209
|
+
/**
|
|
210
|
+
* Chargeback feedback responses may omit meaningful score/decision values.
|
|
211
|
+
*/
|
|
212
|
+
interface ChargebackScoreResponseData extends Omit<FraudScoreResponseData, 'score' | 'decision'> {
|
|
213
|
+
score?: number;
|
|
214
|
+
decision?: FraudDecision;
|
|
215
|
+
}
|
|
39
216
|
interface FraudScoreResponseMetadata {
|
|
40
217
|
request_id?: string;
|
|
41
218
|
processing_ms?: number;
|
|
@@ -57,7 +234,16 @@ interface FraudScoreResponseEnvelope<T> {
|
|
|
57
234
|
declare class FraudClient extends BaseClient {
|
|
58
235
|
scoreEvent(request: FraudScoreRequest, requestOptions?: RequestOptions): Promise<FraudScoreResponseEnvelope<FraudScoreResponseData>>;
|
|
59
236
|
scoreEventsBulk(requests: FraudScoreRequest[], requestOptions?: RequestOptions): Promise<FraudScoreResponseEnvelope<FraudScoreResponseData[]>>;
|
|
60
|
-
private validateScoreRequest;
|
|
61
237
|
}
|
|
62
238
|
|
|
63
|
-
|
|
239
|
+
declare function validateScoreRequest(request: FraudScoreRequest, index?: number): void;
|
|
240
|
+
|
|
241
|
+
declare function normalizeScoreRequestForApi(request: FraudScoreRequest): Record<string, unknown>;
|
|
242
|
+
|
|
243
|
+
/**
|
|
244
|
+
* Returns the JSON body that would be sent to POST /api/v1/fraud/score after normalization.
|
|
245
|
+
* Useful for debugging without calling the API.
|
|
246
|
+
*/
|
|
247
|
+
declare function buildScoreRequestPreview(request: FraudScoreRequest): Record<string, unknown>;
|
|
248
|
+
|
|
249
|
+
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 };
|
package/dist/index.d.ts
CHANGED
|
@@ -1,22 +1,192 @@
|
|
|
1
|
-
import {
|
|
1
|
+
import { RiskLevel, Timestamp, BaseClient, RequestOptions } from '@vesant-sdk/core';
|
|
2
2
|
|
|
3
3
|
/**
|
|
4
|
-
* Fraud
|
|
4
|
+
* Fraud event type unions aligned with fraud-service support matrix.
|
|
5
5
|
*/
|
|
6
|
+
/** Events that run Sift scoring + rule engine */
|
|
7
|
+
type ScoredFraudEventType = '$create_account' | '$login' | '$logout' | '$update_account' | '$update_password' | '$transaction' | '$wager';
|
|
8
|
+
/** Feedback-only; no meaningful fraud score in response */
|
|
9
|
+
type ChargebackFraudEventType = '$chargeback';
|
|
10
|
+
/** Union accepted by scoreEvent / scoreEventsBulk */
|
|
11
|
+
type SupportedFraudEventType = ScoredFraudEventType | ChargebackFraudEventType;
|
|
12
|
+
declare const SCORED_FRAUD_EVENT_TYPES: readonly ScoredFraudEventType[];
|
|
13
|
+
declare const CHARGEBACK_FRAUD_EVENT_TYPE: "$chargeback";
|
|
14
|
+
declare const SUPPORTED_FRAUD_EVENT_TYPES: readonly SupportedFraudEventType[];
|
|
15
|
+
declare const PLANNED_FRAUD_EVENT_TYPES: readonly ["$verification", "$link_session_to_user", "$security_notification", "$create_order", "$update_order", "$order_status", "$add_promotion"];
|
|
16
|
+
/**
|
|
17
|
+
* Listed in Vesant dashboard / future API — NOT valid for scoreEvent today.
|
|
18
|
+
* @deprecated Not supported by POST /api/v1/fraud/score
|
|
19
|
+
*/
|
|
20
|
+
type PlannedFraudEventType = (typeof PLANNED_FRAUD_EVENT_TYPES)[number];
|
|
21
|
+
/**
|
|
22
|
+
* @deprecated Use SupportedFraudEventType; kept for migration
|
|
23
|
+
*/
|
|
24
|
+
type FraudEventType = SupportedFraudEventType | (typeof PLANNED_FRAUD_EVENT_TYPES)[number];
|
|
25
|
+
declare function isPlannedFraudEventType(eventType: string): eventType is (typeof PLANNED_FRAUD_EVENT_TYPES)[number];
|
|
26
|
+
declare function isSupportedFraudEventType(eventType: string): eventType is SupportedFraudEventType;
|
|
27
|
+
|
|
28
|
+
/**
|
|
29
|
+
* Sift-aligned enum types and const objects for fraud scoring requests.
|
|
30
|
+
*/
|
|
31
|
+
type SiftTransactionType = '$sale' | '$authorize' | '$capture' | '$void' | '$refund' | '$deposit' | '$withdrawal' | '$transfer' | '$buy' | '$sell' | '$send' | '$receive';
|
|
32
|
+
declare const SiftTransactionTypeValues: readonly ["$sale", "$authorize", "$capture", "$void", "$refund", "$deposit", "$withdrawal", "$transfer", "$buy", "$sell", "$send", "$receive"];
|
|
33
|
+
declare const TransactionType: {
|
|
34
|
+
readonly Sale: "$sale";
|
|
35
|
+
readonly Authorize: "$authorize";
|
|
36
|
+
readonly Capture: "$capture";
|
|
37
|
+
readonly Void: "$void";
|
|
38
|
+
readonly Refund: "$refund";
|
|
39
|
+
readonly Deposit: "$deposit";
|
|
40
|
+
readonly Withdrawal: "$withdrawal";
|
|
41
|
+
readonly Transfer: "$transfer";
|
|
42
|
+
readonly Buy: "$buy";
|
|
43
|
+
readonly Sell: "$sell";
|
|
44
|
+
readonly Send: "$send";
|
|
45
|
+
readonly Receive: "$receive";
|
|
46
|
+
};
|
|
47
|
+
type SiftChargebackState = '$received' | '$accepted' | '$disputed' | '$won' | '$lost';
|
|
48
|
+
declare const SiftChargebackStateValues: readonly ["$received", "$accepted", "$disputed", "$won", "$lost"];
|
|
49
|
+
declare const ChargebackState: {
|
|
50
|
+
readonly Received: "$received";
|
|
51
|
+
readonly Accepted: "$accepted";
|
|
52
|
+
readonly Disputed: "$disputed";
|
|
53
|
+
readonly Won: "$won";
|
|
54
|
+
readonly Lost: "$lost";
|
|
55
|
+
};
|
|
56
|
+
type SiftChargebackReason = '$fraud' | '$duplicate' | '$product_not_received' | '$product_unacceptable' | '$authorization' | '$consumer_disputes' | '$processing_errors' | '$cancel_subscription' | '$friendly_fraud' | '$ach_return' | '$ach_reversal' | '$other';
|
|
57
|
+
declare const SiftChargebackReasonValues: readonly ["$fraud", "$duplicate", "$product_not_received", "$product_unacceptable", "$authorization", "$consumer_disputes", "$processing_errors", "$cancel_subscription", "$friendly_fraud", "$ach_return", "$ach_reversal", "$other"];
|
|
58
|
+
declare const ChargebackReason: {
|
|
59
|
+
readonly Fraud: "$fraud";
|
|
60
|
+
readonly Duplicate: "$duplicate";
|
|
61
|
+
readonly ProductNotReceived: "$product_not_received";
|
|
62
|
+
readonly ProductUnacceptable: "$product_unacceptable";
|
|
63
|
+
readonly Authorization: "$authorization";
|
|
64
|
+
readonly ConsumerDisputes: "$consumer_disputes";
|
|
65
|
+
readonly ProcessingErrors: "$processing_errors";
|
|
66
|
+
readonly CancelSubscription: "$cancel_subscription";
|
|
67
|
+
readonly FriendlyFraud: "$friendly_fraud";
|
|
68
|
+
readonly AchReturn: "$ach_return";
|
|
69
|
+
readonly AchReversal: "$ach_reversal";
|
|
70
|
+
readonly Other: "$other";
|
|
71
|
+
};
|
|
72
|
+
type SiftLoginStatus = '$success' | '$failure';
|
|
73
|
+
declare const SiftLoginStatusValues: readonly ["$success", "$failure"];
|
|
74
|
+
declare const LoginStatus: {
|
|
75
|
+
readonly Success: "$success";
|
|
76
|
+
readonly Failure: "$failure";
|
|
77
|
+
};
|
|
78
|
+
type SiftLoginFailureReason = '$account_unknown' | '$account_suspended' | '$account_disabled' | '$wrong_password';
|
|
79
|
+
declare const SiftLoginFailureReasonValues: readonly ["$account_unknown", "$account_suspended", "$account_disabled", "$wrong_password"];
|
|
80
|
+
type SiftPasswordUpdateReason = '$user_update' | '$forgot_password' | '$forced_reset';
|
|
81
|
+
declare const SiftPasswordUpdateReasonValues: readonly ["$user_update", "$forgot_password", "$forced_reset"];
|
|
82
|
+
declare const PasswordUpdateReason: {
|
|
83
|
+
readonly UserUpdate: "$user_update";
|
|
84
|
+
readonly ForgotPassword: "$forgot_password";
|
|
85
|
+
readonly ForcedReset: "$forced_reset";
|
|
86
|
+
};
|
|
87
|
+
type SiftPasswordUpdateStatus = '$pending' | '$success' | '$failure';
|
|
88
|
+
declare const SiftPasswordUpdateStatusValues: readonly ["$pending", "$success", "$failure"];
|
|
89
|
+
declare const PasswordUpdateStatus: {
|
|
90
|
+
readonly Pending: "$pending";
|
|
91
|
+
readonly Success: "$success";
|
|
92
|
+
readonly Failure: "$failure";
|
|
93
|
+
};
|
|
94
|
+
type SiftWagerStatus = '$accept' | '$cancel';
|
|
95
|
+
declare const SiftWagerStatusValues: readonly ["$accept", "$cancel"];
|
|
96
|
+
declare const WagerStatus: {
|
|
97
|
+
readonly Accept: "$accept";
|
|
98
|
+
readonly Cancel: "$cancel";
|
|
99
|
+
};
|
|
100
|
+
type SiftTransactionStatus = '$success' | '$failure' | '$pending';
|
|
101
|
+
declare const SiftTransactionStatusValues: readonly ["$success", "$failure", "$pending"];
|
|
102
|
+
declare const TransactionStatus: {
|
|
103
|
+
readonly Success: "$success";
|
|
104
|
+
readonly Failure: "$failure";
|
|
105
|
+
readonly Pending: "$pending";
|
|
106
|
+
};
|
|
107
|
+
type FraudRiskLevel = 'low' | 'medium' | 'high' | 'critical';
|
|
108
|
+
|
|
109
|
+
/**
|
|
110
|
+
* Custom metadata for fraud score requests (non-Sift reserved keys).
|
|
111
|
+
*/
|
|
112
|
+
type FraudCustomMetadata = Record<string, unknown>;
|
|
113
|
+
declare function hasReservedMetadataKey(metadata: FraudCustomMetadata): string | undefined;
|
|
6
114
|
|
|
7
|
-
|
|
8
|
-
|
|
115
|
+
/**
|
|
116
|
+
* Discriminated fraud score request types keyed on event_type.
|
|
117
|
+
*/
|
|
118
|
+
|
|
119
|
+
interface FraudScoreRequestBase {
|
|
120
|
+
/** Tenant customer UUID or stable ID */
|
|
9
121
|
customer_id: string;
|
|
122
|
+
/** Sift $user_id — typically stable per customer */
|
|
10
123
|
sift_user_id: string;
|
|
11
|
-
event_type: FraudEventType;
|
|
12
|
-
transaction_id?: string;
|
|
13
|
-
amount?: number;
|
|
14
|
-
currency?: string;
|
|
15
124
|
ip_address?: string;
|
|
16
125
|
device_id?: string;
|
|
17
126
|
user_agent?: string;
|
|
18
|
-
|
|
127
|
+
/**
|
|
128
|
+
* Custom fields only — keys must NOT start with '$'.
|
|
129
|
+
* Sift reserved fields belong on typed request fields.
|
|
130
|
+
*/
|
|
131
|
+
metadata?: FraudCustomMetadata;
|
|
132
|
+
}
|
|
133
|
+
interface CreateAccountScoreRequest extends FraudScoreRequestBase {
|
|
134
|
+
event_type: '$create_account';
|
|
135
|
+
}
|
|
136
|
+
interface LoginScoreRequest extends FraudScoreRequestBase {
|
|
137
|
+
event_type: '$login';
|
|
138
|
+
login_status?: SiftLoginStatus;
|
|
139
|
+
login_failure_reason?: SiftLoginFailureReason;
|
|
140
|
+
}
|
|
141
|
+
interface LogoutScoreRequest extends FraudScoreRequestBase {
|
|
142
|
+
event_type: '$logout';
|
|
143
|
+
}
|
|
144
|
+
interface UpdateAccountScoreRequest extends FraudScoreRequestBase {
|
|
145
|
+
event_type: '$update_account';
|
|
19
146
|
}
|
|
147
|
+
interface UpdatePasswordScoreRequest extends FraudScoreRequestBase {
|
|
148
|
+
event_type: '$update_password';
|
|
149
|
+
password_reason: SiftPasswordUpdateReason;
|
|
150
|
+
password_status: SiftPasswordUpdateStatus;
|
|
151
|
+
}
|
|
152
|
+
interface TransactionScoreRequest extends FraudScoreRequestBase {
|
|
153
|
+
event_type: '$transaction';
|
|
154
|
+
amount: number;
|
|
155
|
+
currency: string;
|
|
156
|
+
transaction_id?: string;
|
|
157
|
+
transaction_type?: SiftTransactionType;
|
|
158
|
+
transaction_status?: SiftTransactionStatus;
|
|
159
|
+
decline_category?: string;
|
|
160
|
+
transfer_recipient_user_id?: string;
|
|
161
|
+
}
|
|
162
|
+
interface WagerScoreRequest extends FraudScoreRequestBase {
|
|
163
|
+
event_type: '$wager';
|
|
164
|
+
transaction_id: string;
|
|
165
|
+
wager_type: string;
|
|
166
|
+
wager_status: SiftWagerStatus;
|
|
167
|
+
amount: number;
|
|
168
|
+
currency: string;
|
|
169
|
+
wager_event_type?: string;
|
|
170
|
+
wager_event_name?: string;
|
|
171
|
+
wager_event_id?: string;
|
|
172
|
+
}
|
|
173
|
+
interface ChargebackScoreRequest extends FraudScoreRequestBase {
|
|
174
|
+
event_type: ChargebackFraudEventType;
|
|
175
|
+
transaction_id?: string;
|
|
176
|
+
order_id?: string;
|
|
177
|
+
chargeback_state?: SiftChargebackState;
|
|
178
|
+
chargeback_reason?: SiftChargebackReason;
|
|
179
|
+
ach_return_code?: string;
|
|
180
|
+
}
|
|
181
|
+
type FraudScoreRequest = CreateAccountScoreRequest | LoginScoreRequest | LogoutScoreRequest | UpdateAccountScoreRequest | UpdatePasswordScoreRequest | TransactionScoreRequest | WagerScoreRequest | ChargebackScoreRequest;
|
|
182
|
+
type ScoredFraudScoreRequest = Extract<FraudScoreRequest, {
|
|
183
|
+
event_type: ScoredFraudEventType;
|
|
184
|
+
}>;
|
|
185
|
+
|
|
186
|
+
/**
|
|
187
|
+
* Fraud scoring types — responses and re-exports.
|
|
188
|
+
*/
|
|
189
|
+
|
|
20
190
|
type FraudReactionType = 'approve' | 'reject' | 'hold' | 'restrict' | 'block' | 'refund' | 'void_transaction' | 'reverse_transaction' | 'freeze_account' | 'block_withdrawal' | 'limit_withdrawal' | 'disable_payment_method' | 'revoke_session' | 'require_reauth' | 'trigger_alert' | 'no_alert' | 'escalate' | 'increase_priority' | 'create_case' | 'auto_lock_account' | 'notify_team' | (string & Record<string, never>);
|
|
21
191
|
interface TenantAction {
|
|
22
192
|
type: FraudReactionType;
|
|
@@ -36,6 +206,13 @@ interface FraudScoreResponseData {
|
|
|
36
206
|
alert_reference?: string;
|
|
37
207
|
tenant_actions: TenantAction[];
|
|
38
208
|
}
|
|
209
|
+
/**
|
|
210
|
+
* Chargeback feedback responses may omit meaningful score/decision values.
|
|
211
|
+
*/
|
|
212
|
+
interface ChargebackScoreResponseData extends Omit<FraudScoreResponseData, 'score' | 'decision'> {
|
|
213
|
+
score?: number;
|
|
214
|
+
decision?: FraudDecision;
|
|
215
|
+
}
|
|
39
216
|
interface FraudScoreResponseMetadata {
|
|
40
217
|
request_id?: string;
|
|
41
218
|
processing_ms?: number;
|
|
@@ -57,7 +234,16 @@ interface FraudScoreResponseEnvelope<T> {
|
|
|
57
234
|
declare class FraudClient extends BaseClient {
|
|
58
235
|
scoreEvent(request: FraudScoreRequest, requestOptions?: RequestOptions): Promise<FraudScoreResponseEnvelope<FraudScoreResponseData>>;
|
|
59
236
|
scoreEventsBulk(requests: FraudScoreRequest[], requestOptions?: RequestOptions): Promise<FraudScoreResponseEnvelope<FraudScoreResponseData[]>>;
|
|
60
|
-
private validateScoreRequest;
|
|
61
237
|
}
|
|
62
238
|
|
|
63
|
-
|
|
239
|
+
declare function validateScoreRequest(request: FraudScoreRequest, index?: number): void;
|
|
240
|
+
|
|
241
|
+
declare function normalizeScoreRequestForApi(request: FraudScoreRequest): Record<string, unknown>;
|
|
242
|
+
|
|
243
|
+
/**
|
|
244
|
+
* Returns the JSON body that would be sent to POST /api/v1/fraud/score after normalization.
|
|
245
|
+
* Useful for debugging without calling the API.
|
|
246
|
+
*/
|
|
247
|
+
declare function buildScoreRequestPreview(request: FraudScoreRequest): Record<string, unknown>;
|
|
248
|
+
|
|
249
|
+
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 };
|