@@ -46,9 +46,216 @@ export class AuthRules extends APIResource {
4646 v2 : V2API . V2 = new V2API . V2 ( this . _client ) ;
4747}
4848
49+ /**
50+ * Behavioral feature state for a card or account derived from its transaction
51+ * history.
52+ *
53+ * Derived statistical features (averages, standard deviations, z-scores) are
54+ * computed using Welford's online algorithm over approved transactions. Average
55+ * fields are null when fewer than 5 approved transactions have been recorded.
56+ * Standard deviation fields are null when fewer than 30 approved transactions have
57+ * been recorded.
58+ *
59+ * 3DS fields (`three_ds_success_rate`, `three_ds_success_count`,
60+ * `three_ds_total_count`) are card-scoped and will be null for account responses.
61+ *
62+ * Raw fields (`seen_countries`, `seen_mccs`, `approved_txn_amount_m2`, etc.) are
63+ * included so clients can compute their own transaction-specific derivations, such
64+ * as checking whether a new transaction's country is in `seen_countries` to
65+ * determine `is_new_country`, or computing a z-score using the raw mean and M2
66+ * values.
67+ */
68+ export interface SignalsResponse {
69+ /**
70+ * The Welford M2 accumulator for lifetime approved transaction amounts. Used
71+ * together with `avg_transaction_amount` and `approved_txn_count` to compute the
72+ * z-score of a new transaction amount (variance = M2 / (count - 1)).
73+ */
74+ approved_txn_amount_m2 : number | null ;
75+
76+ /**
77+ * The Welford M2 accumulator for approved transaction amounts over the last 30
78+ * days.
79+ */
80+ approved_txn_amount_m2_30d : number | null ;
81+
82+ /**
83+ * The Welford M2 accumulator for approved transaction amounts over the last 7
84+ * days.
85+ */
86+ approved_txn_amount_m2_7d : number | null ;
87+
88+ /**
89+ * The Welford M2 accumulator for approved transaction amounts over the last 90
90+ * days.
91+ */
92+ approved_txn_amount_m2_90d : number | null ;
93+
94+ /**
95+ * The total number of approved transactions over the entity's lifetime.
96+ */
97+ approved_txn_count : number | null ;
98+
99+ /**
100+ * The number of approved transactions in the last 30 days.
101+ */
102+ approved_txn_count_30d : number | null ;
103+
104+ /**
105+ * The number of approved transactions in the last 7 days.
106+ */
107+ approved_txn_count_7d : number | null ;
108+
109+ /**
110+ * The number of approved transactions in the last 90 days.
111+ */
112+ approved_txn_count_90d : number | null ;
113+
114+ /**
115+ * The average approved transaction amount over the entity's lifetime, in cents.
116+ * Null if fewer than 5 approved transactions have been recorded.
117+ */
118+ avg_transaction_amount : number | null ;
119+
120+ /**
121+ * The average approved transaction amount over the last 30 days, in cents. Null if
122+ * fewer than 5 approved transactions in window.
123+ */
124+ avg_transaction_amount_30d : number | null ;
125+
126+ /**
127+ * The average approved transaction amount over the last 7 days, in cents. Null if
128+ * fewer than 5 approved transactions in window.
129+ */
130+ avg_transaction_amount_7d : number | null ;
131+
132+ /**
133+ * The average approved transaction amount over the last 90 days, in cents. Null if
134+ * fewer than 5 approved transactions in window.
135+ */
136+ avg_transaction_amount_90d : number | null ;
137+
138+ /**
139+ * The number of distinct merchant countries seen in the entity's transaction
140+ * history.
141+ */
142+ distinct_country_count : number | null ;
143+
144+ /**
145+ * The number of distinct MCCs seen in the entity's transaction history.
146+ */
147+ distinct_mcc_count : number | null ;
148+
149+ /**
150+ * The timestamp of the first approved transaction for the entity, in ISO 8601
151+ * format.
152+ */
153+ first_txn_at : string | null ;
154+
155+ /**
156+ * Whether the entity has no prior transaction history. Returns true if no history
157+ * is found. Null if transaction history exists but a first transaction timestamp
158+ * is unavailable.
159+ */
160+ is_first_transaction : boolean | null ;
161+
162+ /**
163+ * The merchant country of the last card-present transaction.
164+ */
165+ last_cp_country : string | null ;
166+
167+ /**
168+ * The merchant postal code of the last card-present transaction.
169+ */
170+ last_cp_postal_code : string | null ;
171+
172+ /**
173+ * The timestamp of the last card-present transaction, in ISO 8601 format.
174+ */
175+ last_cp_timestamp : string | null ;
176+
177+ /**
178+ * The timestamp of the most recent approved transaction for the entity, in ISO
179+ * 8601 format.
180+ */
181+ last_txn_approved_at : string | null ;
182+
183+ /**
184+ * The set of merchant countries seen in the entity's transaction history. Clients
185+ * can use this to determine whether a new transaction's country is novel (i.e.
186+ * compute `is_new_country`).
187+ */
188+ seen_countries : Array < string > | null ;
189+
190+ /**
191+ * The set of MCCs seen in the entity's transaction history. Clients can use this
192+ * to determine whether a new transaction's MCC is novel (i.e. compute
193+ * `is_new_mcc`).
194+ */
195+ seen_mccs : Array < string > | null ;
196+
197+ /**
198+ * The set of card acceptor IDs seen in the card's approved transaction history,
199+ * capped at the 1000 most recently seen. Null for account responses. Clients can
200+ * use this to determine whether a new transaction's merchant is novel (i.e.
201+ * compute `is_new_merchant`).
202+ */
203+ seen_merchants : Array < string > | null ;
204+
205+ /**
206+ * The standard deviation of approved transaction amounts over the entity's
207+ * lifetime, in cents. Null if fewer than 30 approved transactions have been
208+ * recorded.
209+ */
210+ stdev_transaction_amount : number | null ;
211+
212+ /**
213+ * The standard deviation of approved transaction amounts over the last 30 days, in
214+ * cents. Null if fewer than 30 approved transactions in window.
215+ */
216+ stdev_transaction_amount_30d : number | null ;
217+
218+ /**
219+ * The standard deviation of approved transaction amounts over the last 7 days, in
220+ * cents. Null if fewer than 30 approved transactions in window.
221+ */
222+ stdev_transaction_amount_7d : number | null ;
223+
224+ /**
225+ * The standard deviation of approved transaction amounts over the last 90 days, in
226+ * cents. Null if fewer than 30 approved transactions in window.
227+ */
228+ stdev_transaction_amount_90d : number | null ;
229+
230+ /**
231+ * The number of successful 3DS authentications for the card. Null for account
232+ * responses.
233+ */
234+ three_ds_success_count : number | null ;
235+
236+ /**
237+ * The 3DS authentication success rate for the card, as a percentage from 0.0 to
238+ * 100.0. Null for account responses.
239+ */
240+ three_ds_success_rate : number | null ;
241+
242+ /**
243+ * The total number of 3DS authentication attempts for the card. Null for account
244+ * responses.
245+ */
246+ three_ds_total_count : number | null ;
247+
248+ /**
249+ * The number of days since the last approved transaction on the entity.
250+ */
251+ time_since_last_transaction_days : number | null ;
252+ }
253+
49254AuthRules . V2 = V2 ;
50255
51256export declare namespace AuthRules {
257+ export { type SignalsResponse as SignalsResponse } ;
258+
52259 export {
53260 V2 as V2 ,
54261 type AuthRule as AuthRule ,
![stainless-app[bot]](https://avatars.githubusercontent.com/in/378072?v=4&size=40){kind=avatar}
0 commit comments