@vesant-sdk/transaction 0.1.1-next.f2f4e87 → 0.1.1

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.
Files changed (7) hide show
  1. package/dist/index.d.mts +172 -52
  2. package/dist/index.d.ts +172 -52
  3. package/dist/index.js +175 -18
  4. package/dist/index.js.map +1 -1
  5. package/dist/index.mjs +172 -20
  6. package/dist/index.mjs.map +1 -1
  7. package/package.json +6 -10
package/dist/index.d.mts CHANGED
@@ -1,45 +1,38 @@
1
- import { Timestamp, BaseClient, BaseClientConfig, RequestOptions } from '@vesant-sdk/core';
1
+ import { BaseClient, RequestOptions, BaseClientConfig, VesantError, WebhookDedupStore } from '@vesant-sdk/core';
2
2
 
3
3
  /**
4
4
  * TypeScript types for the Transaction Monitoring (TM) Service
5
5
  */
6
-
7
- type TransactionType = "deposit" | "withdrawal" | "transfer" | "payment" | "refund" | "fee" | "adjustment" | "bet" | "payout";
8
- type TransactionMode = "fiat" | "crypto" | "bank_transfer" | "card" | "wallet" | "ach" | "wire_transfer" | "swift";
9
- type TransactionStatus = "pending" | "processing" | "completed" | "failed" | "cancelled" | "reversed" | "suspend" | "hold";
6
+ type TransactionType = "withdrawal" | "deposit" | "transfer" | "bet" | "payment" | "adjustment" | "payout";
7
+ type TransactionMode = "wire_transfer" | "crypto" | "swift" | "ach" | "bank_transfer" | "card";
8
+ type TransactionSubType = "sweepstakes" | "cash";
9
+ type TransactionStatus = "pending" | "processing" | "completed" | "failed" | "cancelled" | "reversed" | "blocked" | "flagged" | "hold" | "suspend";
10
10
  interface TransactionCreateDTO {
11
11
  tx_id: string;
12
12
  reference: string;
13
- tenant_id?: string;
14
13
  customer_id: string;
15
14
  transaction_type: TransactionType;
16
15
  transaction_mode: TransactionMode;
16
+ sub_type?: TransactionSubType;
17
17
  amount: string;
18
+ amount_usd: number;
18
19
  currency: string;
19
- /**
20
- * Required for non-USD currencies. The backend only auto-converts when currency is "USD".
21
- * If omitted for crypto or foreign-currency withdrawals, withheld_usd and released_usd
22
- * will be 0 and the gateway will receive $0.
23
- */
24
- amount_usd?: number;
25
- status?: TransactionStatus;
26
20
  source_account?: string;
27
21
  destination_account?: string;
28
22
  country?: string;
29
23
  ip_address?: string;
30
- metadata?: Record<string, any>;
31
- beneficiary_comment?: string;
32
- transaction_date: Timestamp;
24
+ benificiary_comment?: string;
25
+ metadata?: Record<string, unknown>;
26
+ transaction_date: string;
33
27
  }
34
28
  type WithholdingType = "none" | "backup_us" | "backup_non_us" | "treaty";
35
29
  /** Reason backup withholding or treaty rate was applied. */
36
30
  type WithholdingReason = "tin_not_verified" | "customer_tax_form_not_verified" | "b_notice_backup_withholding";
37
31
  /**
38
- * Reason a withdrawal was blocked (status = "suspend" or "hold").
32
+ * Reason a withdrawal was suspended (status = "suspend").
39
33
  * Reflects TIN/W-9 deficiencies that triggered the tenant's configured transaction action.
40
34
  */
41
35
  type HoldReason = "no_tax_profile_found" | "tin_rejected" | "tin_expired" | "tin_not_provided" | "tin_not_verified" | "form_not_certified";
42
- type JSONB = Record<string, any>;
43
36
  type Transaction = {
44
37
  id: string;
45
38
  tx_id: string;
@@ -48,26 +41,21 @@ type Transaction = {
48
41
  customer_id: string;
49
42
  transaction_type: TransactionType;
50
43
  transaction_mode: TransactionMode;
44
+ sub_type?: TransactionSubType;
51
45
  amount: string;
52
46
  withheld_amount: string;
53
47
  released_amount: string;
54
48
  withholding_rate: number;
55
- withholding_type?: WithholdingType;
56
- /** Set when withholding applies; null/absent when withholding_type is "none". */
57
- withholding_reason?: WithholdingReason;
58
- /** Set when status is "suspend" or "hold" due to TIN/W-9 deficiency. */
59
- hold_reason?: HoldReason;
60
- /** Gross transaction amount in USD. */
61
- amount_usd?: number;
62
- /** Withheld amount in USD. */
63
- withheld_usd?: number;
64
- /** Released (net) amount in USD. */
65
- released_usd?: number;
49
+ withholding_type: string;
50
+ withholding_reason?: string;
51
+ hold_reason?: string;
52
+ amount_usd: number;
53
+ withheld_usd: number;
54
+ released_usd: number;
66
55
  /**
67
56
  * True when this is the customer's first withdrawal.
68
- * Correct on the POST /transactions response and on tm.transaction.callback (both read
69
- * from the in-memory struct before any DB re-fetch). Not persisted — getTransaction()
70
- * always returns false regardless of actual history.
57
+ * Correct on the POST /transactions response and on tm.transaction.callback.
58
+ * Not persisted — getTransaction() always returns false regardless of actual history.
71
59
  */
72
60
  is_first_withdrawal?: boolean;
73
61
  tax_year: number;
@@ -78,8 +66,8 @@ type Transaction = {
78
66
  country?: string;
79
67
  ip_address?: string;
80
68
  risk_score: number;
81
- metadata?: JSONB;
82
- beneficiary_comment?: string;
69
+ metadata?: Record<string, unknown>;
70
+ benificiary_comment?: string;
83
71
  transaction_date: string;
84
72
  created_at: string;
85
73
  updated_at: string;
@@ -98,43 +86,43 @@ interface TransactionClientConfig {
98
86
  /**
99
87
  * Response from POST /api/v1/tm/transactions.
100
88
  *
101
- * Status → outcome mapping:
102
- * "completed" — Vesant accepted; trigger the payment gateway (clean TIN,
103
- * backup withholding applied, or treaty rate applied)
104
- * "hold" — blocked, hold_reason set, no funds moved
105
- * "suspend" — blocked, hold_reason set, no funds moved
89
+ * Status → outcome mapping (withdrawal transactions only):
90
+ * "pending" — Vesant accepted; trigger the payment gateway (full release,
91
+ * backup withholding applied, or treaty rate applied)
92
+ * "suspend" — blocked, hold_reason set, no funds moved
106
93
  */
107
94
  type TransactionCreateResponse = {
108
95
  transaction: Transaction;
109
96
  message: string;
110
97
  };
111
98
  /**
112
- * Fired after every transaction is created.
113
- * Delivers the final transaction state including withholding outcome so clients
114
- * can mirror it without a separate polling call.
99
+ * Fired after every transaction is created and after a suspended transaction is released.
100
+ * Delivers the final compliance-evaluated state including withholding outcome.
115
101
  */
116
102
  interface TransactionCallbackEvent {
117
103
  event_type: "tm.transaction.callback";
104
+ id: string;
105
+ tenant_id: string;
106
+ entity_id: string;
107
+ user_id: string;
118
108
  tx_id: string;
119
109
  reference: string;
120
110
  customer_id: string;
121
- transaction_type: TransactionType;
122
- transaction_mode: TransactionMode;
123
- status: TransactionStatus;
111
+ transaction_type: string;
112
+ transaction_mode: string;
113
+ status: string;
124
114
  amount: string;
125
115
  currency: string;
126
116
  withheld_amount: string;
127
117
  released_amount: string;
128
118
  withholding_rate: number;
129
- withholding_type: WithholdingType;
130
- /** Null when withholding_type is "none". */
131
- withholding_reason: WithholdingReason | null;
119
+ withholding_type: string;
120
+ withholding_reason?: string | null;
121
+ hold_reason?: string | null;
132
122
  amount_usd: number;
133
123
  withheld_usd: number;
134
124
  released_usd: number;
135
125
  is_first_withdrawal: boolean;
136
- /** Set when status is "suspend" or "hold"; null otherwise. */
137
- hold_reason: HoldReason | null;
138
126
  transaction_date: string;
139
127
  }
140
128
  /**
@@ -154,34 +142,166 @@ interface TransactionHeldEvent {
154
142
  }
155
143
  /** Discriminated union of all TM service webhook event payloads. */
156
144
  type TransactionWebhookEvent = TransactionCallbackEvent | TransactionHeldEvent;
145
+ interface TmTenantSettings {
146
+ tenant_id: string;
147
+ transaction_monitoring_enabled: boolean;
148
+ tax_monitoring_enabled: boolean;
149
+ }
150
+ /**
151
+ * Semantic handler interface for the three withholding outcomes of a tm.transaction.callback.
152
+ * Register with TransactionWebhookHandler.registerCallbackHandler().
153
+ */
154
+ interface TransactionCallbackHandler {
155
+ onWithheld?(event: TransactionCallbackEvent): void | Promise<void>;
156
+ onHeld?(event: TransactionCallbackEvent): void | Promise<void>;
157
+ onReleased?(event: TransactionCallbackEvent): void | Promise<void>;
158
+ }
159
+
160
+ type WithdrawalState = 'vesant_pending' | 'withheld' | 'suspend' | 'released' | 'failed';
161
+ declare class PendingWithdrawal {
162
+ private _state;
163
+ private _event;
164
+ private _error;
165
+ private _waitPromise;
166
+ private _resolveWait?;
167
+ private _rejectWait?;
168
+ readonly tx_id: string;
169
+ readonly initialTransaction: Transaction;
170
+ constructor(tx_id: string, transaction: Transaction);
171
+ status(): WithdrawalState;
172
+ callbackEvent(): TransactionCallbackEvent | null;
173
+ wait(signal?: AbortSignal): Promise<TransactionCallbackEvent>;
174
+ /** Called by TransactionWebhookHandler when the tm.transaction.callback arrives for this tx_id. */
175
+ _settle(event: TransactionCallbackEvent): void;
176
+ /** Called to fail the pending withdrawal with a generic error (e.g. abort, network loss). */
177
+ _fail(err: unknown): void;
178
+ }
179
+
180
+ type CustomerType = 'US_PERSON' | 'NON_US_PERSON' | 'NON_US_ENTITY';
181
+ type CTPFormStatus = 'requested' | 'signed' | 'manual' | 'bounced' | 'uploaded' | 'expired' | 're_requested';
182
+ type CTPTINStatus = 'not_required' | 'pending' | 'submitted' | 'verified' | 'rejected' | 'error' | 'expired';
183
+ interface CustomerTaxProfileRecord {
184
+ id: string;
185
+ tenant_id: string;
186
+ customer_id: string;
187
+ customer_type: CustomerType;
188
+ form_type: string;
189
+ form_status: CTPFormStatus;
190
+ tin_status: CTPTINStatus;
191
+ tin_value?: string;
192
+ recipient_name?: string;
193
+ business_name?: string;
194
+ account_number?: string;
195
+ address?: string;
196
+ address_city?: string;
197
+ address_state?: string;
198
+ address_zip?: string;
199
+ address_country?: string;
200
+ customer_name?: string;
201
+ avalara_form_id?: string;
202
+ avalara_company_id?: string;
203
+ signed_at?: string;
204
+ verified_at?: string;
205
+ expiry_date?: string;
206
+ backup_withholding: boolean;
207
+ b_notice_received: boolean;
208
+ e_delivery_consent: boolean;
209
+ withholding_enabled_by?: string;
210
+ withholding_enabled_at?: string;
211
+ tin_due_date?: string;
212
+ last_tin_check?: string;
213
+ request_count: number;
214
+ reminders_sent: number;
215
+ last_reminder_at?: string;
216
+ created_at: string;
217
+ updated_at: string;
218
+ }
219
+ type TaxFormTrigger = 'trigger_account_creation' | 'trigger_first_withdrawal' | 'trigger_threshold' | 'trigger_manual' | 'trigger_tin_invalid' | 'trigger_w8ben_expiry' | 'trigger_tin_expired';
220
+ interface CustomerTaxProfileDocuments {
221
+ w_form: string;
222
+ '1099_form': string;
223
+ }
224
+ interface RequestTaxFormWithProfileInput {
225
+ customer_id: string;
226
+ email: string;
227
+ trigger: TaxFormTrigger;
228
+ first_name?: string;
229
+ last_name?: string;
230
+ date_of_birth?: string;
231
+ phone_number?: string;
232
+ country?: string;
233
+ state?: string;
234
+ city?: string;
235
+ zip_code?: string;
236
+ address?: string;
237
+ ip_address?: string;
238
+ form_type?: string;
239
+ }
240
+ interface RequestTaxFormWithProfileOutput {
241
+ profile?: CustomerTaxProfileRecord;
242
+ request_id?: string;
243
+ reference_id?: string;
244
+ form_id?: string;
245
+ public_url?: string;
246
+ }
247
+
248
+ declare class TaxTransactionClient extends BaseClient {
249
+ getCustomerDocuments(customerID: string): Promise<CustomerTaxProfileDocuments>;
250
+ requestTaxFormWithProfile(input: RequestTaxFormWithProfileInput, requestOptions?: RequestOptions): Promise<RequestTaxFormWithProfileOutput>;
251
+ }
157
252
 
158
253
  /**
159
254
  * TransactionClient — SDK for the Transaction Monitoring service
160
255
  */
161
256
 
162
257
  declare class TransactionClient extends BaseClient {
258
+ readonly tax: TaxTransactionClient;
163
259
  constructor(config: BaseClientConfig);
164
260
  createTransaction(request: TransactionCreateDTO, requestOptions?: RequestOptions): Promise<TransactionCreateResponse>;
261
+ submitWithdrawal(request: TransactionCreateDTO, requestOptions?: RequestOptions): Promise<PendingWithdrawal>;
165
262
  getTransaction(transactionId: string, requestOptions?: RequestOptions): Promise<Transaction>;
263
+ getSettings(): Promise<TmTenantSettings>;
264
+ }
265
+
266
+ declare class DuplicateTransactionError extends VesantError {
267
+ readonly tx_id: string;
268
+ constructor(tx_id: string, message?: string);
269
+ }
270
+ declare class TaxHoldError extends Error {
271
+ readonly tx_id: string;
272
+ readonly hold_reason: HoldReason;
273
+ readonly event: TransactionCallbackEvent;
274
+ constructor(event: TransactionCallbackEvent);
166
275
  }
167
276
 
168
277
  type EventHandler<T> = (event: T) => void | Promise<void>;
278
+ declare const TRANSACTION_SIGNATURE_HEADER = "x-webhook-signature";
169
279
  interface TransactionWebhookHandlerConfig {
170
280
  secret: string;
171
281
  /** Reject duplicate event_type+tx_id pairs within replayWindow. Default: true. */
172
282
  replayProtection?: boolean;
173
283
  /** How long (ms) to remember seen events for replay detection. Default: 300_000 (5 min). */
174
284
  replayWindow?: number;
285
+ /** Pluggable dedup store for replay protection (default: in-memory, process-local). */
286
+ dedupStore?: WebhookDedupStore;
175
287
  }
176
288
  declare class TransactionWebhookHandler {
177
289
  private readonly handlers;
178
290
  private readonly secret;
179
291
  private readonly replayProtection;
180
292
  private readonly replayWindow;
181
- private seenEvents;
293
+ private readonly dedupStore;
294
+ private readonly pendingWithdrawals;
295
+ private callbackHandler;
182
296
  constructor(config: TransactionWebhookHandlerConfig);
183
297
  on(eventType: 'tm.transaction.callback', handler: EventHandler<TransactionCallbackEvent>): this;
184
298
  on(eventType: 'tm.transaction.held', handler: EventHandler<TransactionHeldEvent>): this;
299
+ /** Register a semantic callback handler for the three withholding outcomes. Replaces any previous handler. */
300
+ registerCallbackHandler(handler: TransactionCallbackHandler): this;
301
+ /** Track a PendingWithdrawal so it is auto-settled when its tm.transaction.callback arrives. */
302
+ link(pending: PendingWithdrawal): this;
303
+ /** Stop tracking a PendingWithdrawal by tx_id. */
304
+ unlink(tx_id: string): this;
185
305
  /** Verify HMAC-SHA256 signature only. Returns false instead of throwing. */
186
306
  verify(rawBody: string, signature: string): Promise<boolean>;
187
307
  /** Parse and validate required fields. Does not verify signature — use verifyAndParse in production. */
@@ -192,4 +312,4 @@ declare class TransactionWebhookHandler {
192
312
  handle(body: string, signature: string): Promise<void>;
193
313
  }
194
314
 
195
- export { type HoldReason, type JSONB, type Transaction, type TransactionCallbackEvent, TransactionClient, type TransactionClientConfig, type TransactionCreateDTO, type TransactionCreateResponse, type TransactionHeldEvent, type TransactionMode, type TransactionStatus, type TransactionType, type TransactionWebhookEvent, TransactionWebhookHandler, type TransactionWebhookHandlerConfig, type WithholdingReason, type WithholdingType };
315
+ export { type CTPFormStatus, type CTPTINStatus, type CustomerTaxProfileDocuments, type CustomerTaxProfileRecord, type CustomerType, DuplicateTransactionError, type HoldReason, PendingWithdrawal, type RequestTaxFormWithProfileInput, type RequestTaxFormWithProfileOutput, TRANSACTION_SIGNATURE_HEADER, type TaxFormTrigger, TaxHoldError, TaxTransactionClient, type TmTenantSettings, type Transaction, type TransactionCallbackEvent, type TransactionCallbackHandler, TransactionClient, type TransactionClientConfig, type TransactionCreateDTO, type TransactionCreateResponse, type TransactionHeldEvent, type TransactionMode, type TransactionStatus, type TransactionSubType, type TransactionType, type TransactionWebhookEvent, TransactionWebhookHandler, type TransactionWebhookHandlerConfig, type WithdrawalState, type WithholdingReason, type WithholdingType };
package/dist/index.d.ts CHANGED
@@ -1,45 +1,38 @@
1
- import { Timestamp, BaseClient, BaseClientConfig, RequestOptions } from '@vesant-sdk/core';
1
+ import { BaseClient, RequestOptions, BaseClientConfig, VesantError, WebhookDedupStore } from '@vesant-sdk/core';
2
2
 
3
3
  /**
4
4
  * TypeScript types for the Transaction Monitoring (TM) Service
5
5
  */
6
-
7
- type TransactionType = "deposit" | "withdrawal" | "transfer" | "payment" | "refund" | "fee" | "adjustment" | "bet" | "payout";
8
- type TransactionMode = "fiat" | "crypto" | "bank_transfer" | "card" | "wallet" | "ach" | "wire_transfer" | "swift";
9
- type TransactionStatus = "pending" | "processing" | "completed" | "failed" | "cancelled" | "reversed" | "suspend" | "hold";
6
+ type TransactionType = "withdrawal" | "deposit" | "transfer" | "bet" | "payment" | "adjustment" | "payout";
7
+ type TransactionMode = "wire_transfer" | "crypto" | "swift" | "ach" | "bank_transfer" | "card";
8
+ type TransactionSubType = "sweepstakes" | "cash";
9
+ type TransactionStatus = "pending" | "processing" | "completed" | "failed" | "cancelled" | "reversed" | "blocked" | "flagged" | "hold" | "suspend";
10
10
  interface TransactionCreateDTO {
11
11
  tx_id: string;
12
12
  reference: string;
13
- tenant_id?: string;
14
13
  customer_id: string;
15
14
  transaction_type: TransactionType;
16
15
  transaction_mode: TransactionMode;
16
+ sub_type?: TransactionSubType;
17
17
  amount: string;
18
+ amount_usd: number;
18
19
  currency: string;
19
- /**
20
- * Required for non-USD currencies. The backend only auto-converts when currency is "USD".
21
- * If omitted for crypto or foreign-currency withdrawals, withheld_usd and released_usd
22
- * will be 0 and the gateway will receive $0.
23
- */
24
- amount_usd?: number;
25
- status?: TransactionStatus;
26
20
  source_account?: string;
27
21
  destination_account?: string;
28
22
  country?: string;
29
23
  ip_address?: string;
30
- metadata?: Record<string, any>;
31
- beneficiary_comment?: string;
32
- transaction_date: Timestamp;
24
+ benificiary_comment?: string;
25
+ metadata?: Record<string, unknown>;
26
+ transaction_date: string;
33
27
  }
34
28
  type WithholdingType = "none" | "backup_us" | "backup_non_us" | "treaty";
35
29
  /** Reason backup withholding or treaty rate was applied. */
36
30
  type WithholdingReason = "tin_not_verified" | "customer_tax_form_not_verified" | "b_notice_backup_withholding";
37
31
  /**
38
- * Reason a withdrawal was blocked (status = "suspend" or "hold").
32
+ * Reason a withdrawal was suspended (status = "suspend").
39
33
  * Reflects TIN/W-9 deficiencies that triggered the tenant's configured transaction action.
40
34
  */
41
35
  type HoldReason = "no_tax_profile_found" | "tin_rejected" | "tin_expired" | "tin_not_provided" | "tin_not_verified" | "form_not_certified";
42
- type JSONB = Record<string, any>;
43
36
  type Transaction = {
44
37
  id: string;
45
38
  tx_id: string;
@@ -48,26 +41,21 @@ type Transaction = {
48
41
  customer_id: string;
49
42
  transaction_type: TransactionType;
50
43
  transaction_mode: TransactionMode;
44
+ sub_type?: TransactionSubType;
51
45
  amount: string;
52
46
  withheld_amount: string;
53
47
  released_amount: string;
54
48
  withholding_rate: number;
55
- withholding_type?: WithholdingType;
56
- /** Set when withholding applies; null/absent when withholding_type is "none". */
57
- withholding_reason?: WithholdingReason;
58
- /** Set when status is "suspend" or "hold" due to TIN/W-9 deficiency. */
59
- hold_reason?: HoldReason;
60
- /** Gross transaction amount in USD. */
61
- amount_usd?: number;
62
- /** Withheld amount in USD. */
63
- withheld_usd?: number;
64
- /** Released (net) amount in USD. */
65
- released_usd?: number;
49
+ withholding_type: string;
50
+ withholding_reason?: string;
51
+ hold_reason?: string;
52
+ amount_usd: number;
53
+ withheld_usd: number;
54
+ released_usd: number;
66
55
  /**
67
56
  * True when this is the customer's first withdrawal.
68
- * Correct on the POST /transactions response and on tm.transaction.callback (both read
69
- * from the in-memory struct before any DB re-fetch). Not persisted — getTransaction()
70
- * always returns false regardless of actual history.
57
+ * Correct on the POST /transactions response and on tm.transaction.callback.
58
+ * Not persisted — getTransaction() always returns false regardless of actual history.
71
59
  */
72
60
  is_first_withdrawal?: boolean;
73
61
  tax_year: number;
@@ -78,8 +66,8 @@ type Transaction = {
78
66
  country?: string;
79
67
  ip_address?: string;
80
68
  risk_score: number;
81
- metadata?: JSONB;
82
- beneficiary_comment?: string;
69
+ metadata?: Record<string, unknown>;
70
+ benificiary_comment?: string;
83
71
  transaction_date: string;
84
72
  created_at: string;
85
73
  updated_at: string;
@@ -98,43 +86,43 @@ interface TransactionClientConfig {
98
86
  /**
99
87
  * Response from POST /api/v1/tm/transactions.
100
88
  *
101
- * Status → outcome mapping:
102
- * "completed" — Vesant accepted; trigger the payment gateway (clean TIN,
103
- * backup withholding applied, or treaty rate applied)
104
- * "hold" — blocked, hold_reason set, no funds moved
105
- * "suspend" — blocked, hold_reason set, no funds moved
89
+ * Status → outcome mapping (withdrawal transactions only):
90
+ * "pending" — Vesant accepted; trigger the payment gateway (full release,
91
+ * backup withholding applied, or treaty rate applied)
92
+ * "suspend" — blocked, hold_reason set, no funds moved
106
93
  */
107
94
  type TransactionCreateResponse = {
108
95
  transaction: Transaction;
109
96
  message: string;
110
97
  };
111
98
  /**
112
- * Fired after every transaction is created.
113
- * Delivers the final transaction state including withholding outcome so clients
114
- * can mirror it without a separate polling call.
99
+ * Fired after every transaction is created and after a suspended transaction is released.
100
+ * Delivers the final compliance-evaluated state including withholding outcome.
115
101
  */
116
102
  interface TransactionCallbackEvent {
117
103
  event_type: "tm.transaction.callback";
104
+ id: string;
105
+ tenant_id: string;
106
+ entity_id: string;
107
+ user_id: string;
118
108
  tx_id: string;
119
109
  reference: string;
120
110
  customer_id: string;
121
- transaction_type: TransactionType;
122
- transaction_mode: TransactionMode;
123
- status: TransactionStatus;
111
+ transaction_type: string;
112
+ transaction_mode: string;
113
+ status: string;
124
114
  amount: string;
125
115
  currency: string;
126
116
  withheld_amount: string;
127
117
  released_amount: string;
128
118
  withholding_rate: number;
129
- withholding_type: WithholdingType;
130
- /** Null when withholding_type is "none". */
131
- withholding_reason: WithholdingReason | null;
119
+ withholding_type: string;
120
+ withholding_reason?: string | null;
121
+ hold_reason?: string | null;
132
122
  amount_usd: number;
133
123
  withheld_usd: number;
134
124
  released_usd: number;
135
125
  is_first_withdrawal: boolean;
136
- /** Set when status is "suspend" or "hold"; null otherwise. */
137
- hold_reason: HoldReason | null;
138
126
  transaction_date: string;
139
127
  }
140
128
  /**
@@ -154,34 +142,166 @@ interface TransactionHeldEvent {
154
142
  }
155
143
  /** Discriminated union of all TM service webhook event payloads. */
156
144
  type TransactionWebhookEvent = TransactionCallbackEvent | TransactionHeldEvent;
145
+ interface TmTenantSettings {
146
+ tenant_id: string;
147
+ transaction_monitoring_enabled: boolean;
148
+ tax_monitoring_enabled: boolean;
149
+ }
150
+ /**
151
+ * Semantic handler interface for the three withholding outcomes of a tm.transaction.callback.
152
+ * Register with TransactionWebhookHandler.registerCallbackHandler().
153
+ */
154
+ interface TransactionCallbackHandler {
155
+ onWithheld?(event: TransactionCallbackEvent): void | Promise<void>;
156
+ onHeld?(event: TransactionCallbackEvent): void | Promise<void>;
157
+ onReleased?(event: TransactionCallbackEvent): void | Promise<void>;
158
+ }
159
+
160
+ type WithdrawalState = 'vesant_pending' | 'withheld' | 'suspend' | 'released' | 'failed';
161
+ declare class PendingWithdrawal {
162
+ private _state;
163
+ private _event;
164
+ private _error;
165
+ private _waitPromise;
166
+ private _resolveWait?;
167
+ private _rejectWait?;
168
+ readonly tx_id: string;
169
+ readonly initialTransaction: Transaction;
170
+ constructor(tx_id: string, transaction: Transaction);
171
+ status(): WithdrawalState;
172
+ callbackEvent(): TransactionCallbackEvent | null;
173
+ wait(signal?: AbortSignal): Promise<TransactionCallbackEvent>;
174
+ /** Called by TransactionWebhookHandler when the tm.transaction.callback arrives for this tx_id. */
175
+ _settle(event: TransactionCallbackEvent): void;
176
+ /** Called to fail the pending withdrawal with a generic error (e.g. abort, network loss). */
177
+ _fail(err: unknown): void;
178
+ }
179
+
180
+ type CustomerType = 'US_PERSON' | 'NON_US_PERSON' | 'NON_US_ENTITY';
181
+ type CTPFormStatus = 'requested' | 'signed' | 'manual' | 'bounced' | 'uploaded' | 'expired' | 're_requested';
182
+ type CTPTINStatus = 'not_required' | 'pending' | 'submitted' | 'verified' | 'rejected' | 'error' | 'expired';
183
+ interface CustomerTaxProfileRecord {
184
+ id: string;
185
+ tenant_id: string;
186
+ customer_id: string;
187
+ customer_type: CustomerType;
188
+ form_type: string;
189
+ form_status: CTPFormStatus;
190
+ tin_status: CTPTINStatus;
191
+ tin_value?: string;
192
+ recipient_name?: string;
193
+ business_name?: string;
194
+ account_number?: string;
195
+ address?: string;
196
+ address_city?: string;
197
+ address_state?: string;
198
+ address_zip?: string;
199
+ address_country?: string;
200
+ customer_name?: string;
201
+ avalara_form_id?: string;
202
+ avalara_company_id?: string;
203
+ signed_at?: string;
204
+ verified_at?: string;
205
+ expiry_date?: string;
206
+ backup_withholding: boolean;
207
+ b_notice_received: boolean;
208
+ e_delivery_consent: boolean;
209
+ withholding_enabled_by?: string;
210
+ withholding_enabled_at?: string;
211
+ tin_due_date?: string;
212
+ last_tin_check?: string;
213
+ request_count: number;
214
+ reminders_sent: number;
215
+ last_reminder_at?: string;
216
+ created_at: string;
217
+ updated_at: string;
218
+ }
219
+ type TaxFormTrigger = 'trigger_account_creation' | 'trigger_first_withdrawal' | 'trigger_threshold' | 'trigger_manual' | 'trigger_tin_invalid' | 'trigger_w8ben_expiry' | 'trigger_tin_expired';
220
+ interface CustomerTaxProfileDocuments {
221
+ w_form: string;
222
+ '1099_form': string;
223
+ }
224
+ interface RequestTaxFormWithProfileInput {
225
+ customer_id: string;
226
+ email: string;
227
+ trigger: TaxFormTrigger;
228
+ first_name?: string;
229
+ last_name?: string;
230
+ date_of_birth?: string;
231
+ phone_number?: string;
232
+ country?: string;
233
+ state?: string;
234
+ city?: string;
235
+ zip_code?: string;
236
+ address?: string;
237
+ ip_address?: string;
238
+ form_type?: string;
239
+ }
240
+ interface RequestTaxFormWithProfileOutput {
241
+ profile?: CustomerTaxProfileRecord;
242
+ request_id?: string;
243
+ reference_id?: string;
244
+ form_id?: string;
245
+ public_url?: string;
246
+ }
247
+
248
+ declare class TaxTransactionClient extends BaseClient {
249
+ getCustomerDocuments(customerID: string): Promise<CustomerTaxProfileDocuments>;
250
+ requestTaxFormWithProfile(input: RequestTaxFormWithProfileInput, requestOptions?: RequestOptions): Promise<RequestTaxFormWithProfileOutput>;
251
+ }
157
252
 
158
253
  /**
159
254
  * TransactionClient — SDK for the Transaction Monitoring service
160
255
  */
161
256
 
162
257
  declare class TransactionClient extends BaseClient {
258
+ readonly tax: TaxTransactionClient;
163
259
  constructor(config: BaseClientConfig);
164
260
  createTransaction(request: TransactionCreateDTO, requestOptions?: RequestOptions): Promise<TransactionCreateResponse>;
261
+ submitWithdrawal(request: TransactionCreateDTO, requestOptions?: RequestOptions): Promise<PendingWithdrawal>;
165
262
  getTransaction(transactionId: string, requestOptions?: RequestOptions): Promise<Transaction>;
263
+ getSettings(): Promise<TmTenantSettings>;
264
+ }
265
+
266
+ declare class DuplicateTransactionError extends VesantError {
267
+ readonly tx_id: string;
268
+ constructor(tx_id: string, message?: string);
269
+ }
270
+ declare class TaxHoldError extends Error {
271
+ readonly tx_id: string;
272
+ readonly hold_reason: HoldReason;
273
+ readonly event: TransactionCallbackEvent;
274
+ constructor(event: TransactionCallbackEvent);
166
275
  }
167
276
 
168
277
  type EventHandler<T> = (event: T) => void | Promise<void>;
278
+ declare const TRANSACTION_SIGNATURE_HEADER = "x-webhook-signature";
169
279
  interface TransactionWebhookHandlerConfig {
170
280
  secret: string;
171
281
  /** Reject duplicate event_type+tx_id pairs within replayWindow. Default: true. */
172
282
  replayProtection?: boolean;
173
283
  /** How long (ms) to remember seen events for replay detection. Default: 300_000 (5 min). */
174
284
  replayWindow?: number;
285
+ /** Pluggable dedup store for replay protection (default: in-memory, process-local). */
286
+ dedupStore?: WebhookDedupStore;
175
287
  }
176
288
  declare class TransactionWebhookHandler {
177
289
  private readonly handlers;
178
290
  private readonly secret;
179
291
  private readonly replayProtection;
180
292
  private readonly replayWindow;
181
- private seenEvents;
293
+ private readonly dedupStore;
294
+ private readonly pendingWithdrawals;
295
+ private callbackHandler;
182
296
  constructor(config: TransactionWebhookHandlerConfig);
183
297
  on(eventType: 'tm.transaction.callback', handler: EventHandler<TransactionCallbackEvent>): this;
184
298
  on(eventType: 'tm.transaction.held', handler: EventHandler<TransactionHeldEvent>): this;
299
+ /** Register a semantic callback handler for the three withholding outcomes. Replaces any previous handler. */
300
+ registerCallbackHandler(handler: TransactionCallbackHandler): this;
301
+ /** Track a PendingWithdrawal so it is auto-settled when its tm.transaction.callback arrives. */
302
+ link(pending: PendingWithdrawal): this;
303
+ /** Stop tracking a PendingWithdrawal by tx_id. */
304
+ unlink(tx_id: string): this;
185
305
  /** Verify HMAC-SHA256 signature only. Returns false instead of throwing. */
186
306
  verify(rawBody: string, signature: string): Promise<boolean>;
187
307
  /** Parse and validate required fields. Does not verify signature — use verifyAndParse in production. */
@@ -192,4 +312,4 @@ declare class TransactionWebhookHandler {
192
312
  handle(body: string, signature: string): Promise<void>;
193
313
  }
194
314
 
195
- export { type HoldReason, type JSONB, type Transaction, type TransactionCallbackEvent, TransactionClient, type TransactionClientConfig, type TransactionCreateDTO, type TransactionCreateResponse, type TransactionHeldEvent, type TransactionMode, type TransactionStatus, type TransactionType, type TransactionWebhookEvent, TransactionWebhookHandler, type TransactionWebhookHandlerConfig, type WithholdingReason, type WithholdingType };
315
+ export { type CTPFormStatus, type CTPTINStatus, type CustomerTaxProfileDocuments, type CustomerTaxProfileRecord, type CustomerType, DuplicateTransactionError, type HoldReason, PendingWithdrawal, type RequestTaxFormWithProfileInput, type RequestTaxFormWithProfileOutput, TRANSACTION_SIGNATURE_HEADER, type TaxFormTrigger, TaxHoldError, TaxTransactionClient, type TmTenantSettings, type Transaction, type TransactionCallbackEvent, type TransactionCallbackHandler, TransactionClient, type TransactionClientConfig, type TransactionCreateDTO, type TransactionCreateResponse, type TransactionHeldEvent, type TransactionMode, type TransactionStatus, type TransactionSubType, type TransactionType, type TransactionWebhookEvent, TransactionWebhookHandler, type TransactionWebhookHandlerConfig, type WithdrawalState, type WithholdingReason, type WithholdingType };