@vesant-sdk/transaction 0.1.1-next.f2f4e87 → 0.1.2-dev.8d808aa

package/dist/index.d.mts

@@ -1,45 +1,47 @@
-import { Timestamp, BaseClient, BaseClientConfig, RequestOptions } from '@vesant-sdk/core';
+import { BaseClient, RequestOptions, BaseClientConfig, VesantError, WebhookDedupStore } from '@vesant-sdk/core';
 
 /**
  * TypeScript types for the Transaction Monitoring (TM) Service
  */
-
-type TransactionType = "deposit" | "withdrawal" | "transfer" | "payment" | "refund" | "fee" | "adjustment" | "bet" | "payout";
-type TransactionMode = "fiat" | "crypto" | "bank_transfer" | "card" | "wallet" | "ach" | "wire_transfer" | "swift";
-type TransactionStatus = "pending" | "processing" | "completed" | "failed" | "cancelled" | "reversed" | "suspend" | "hold";
+type TransactionType = "withdrawal" | "deposit" | "transfer" | "bet" | "payment" | "adjustment" | "payout";
+type TransactionMode = "wire_transfer" | "crypto" | "swift" | "ach" | "bank_transfer" | "card";
+type TransactionSubType = "sweepstakes" | "cash";
+type TransactionStatus = "pending" | "processing" | "completed" | "failed" | "cancelled" | "reversed" | "blocked" | "flagged" | "hold" | "suspend";
 interface TransactionCreateDTO {
     tx_id: string;
     reference: string;
-    tenant_id?: string;
     customer_id: string;
     transaction_type: TransactionType;
     transaction_mode: TransactionMode;
+    sub_type?: TransactionSubType;
     amount: string;
-    currency: string;
-    /**
-     * Required for non-USD currencies. The backend only auto-converts when currency is "USD".
-     * If omitted for crypto or foreign-currency withdrawals, withheld_usd and released_usd
-     * will be 0 and the gateway will receive $0.
-     */
+    /** Defaults server-side to `amount` when omitted and `currency` is USD. */
     amount_usd?: number;
+    currency: string;
     status?: TransactionStatus;
     source_account?: string;
     destination_account?: string;
     country?: string;
     ip_address?: string;
-    metadata?: Record<string, any>;
-    beneficiary_comment?: string;
-    transaction_date: Timestamp;
+    /** Spelling matches the backend's JSON tag — `beneficiary_comment` is ignored by the API. */
+    benificiary_comment?: string;
+    metadata?: Record<string, unknown>;
+    transaction_date: string;
+    /** Device fingerprint ID from the Sift beacon. */
+    device_id?: string;
+    /** Session ID for session-level fraud signals. */
+    session_id?: string;
+    /** Raw User-Agent string forwarded to Sift for device classification. Falls back to the request's own header. */
+    user_agent?: string;
 }
 type WithholdingType = "none" | "backup_us" | "backup_non_us" | "treaty";
 /** Reason backup withholding or treaty rate was applied. */
 type WithholdingReason = "tin_not_verified" | "customer_tax_form_not_verified" | "b_notice_backup_withholding";
 /**
- * Reason a withdrawal was blocked (status = "suspend" or "hold").
+ * Reason a withdrawal was suspended (status = "suspend").
  * Reflects TIN/W-9 deficiencies that triggered the tenant's configured transaction action.
  */
 type HoldReason = "no_tax_profile_found" | "tin_rejected" | "tin_expired" | "tin_not_provided" | "tin_not_verified" | "form_not_certified";
-type JSONB = Record<string, any>;
 type Transaction = {
     id: string;
     tx_id: string;
@@ -48,26 +50,21 @@ type Transaction = {
     customer_id: string;
     transaction_type: TransactionType;
     transaction_mode: TransactionMode;
+    sub_type?: TransactionSubType;
     amount: string;
     withheld_amount: string;
     released_amount: string;
     withholding_rate: number;
-    withholding_type?: WithholdingType;
-    /** Set when withholding applies; null/absent when withholding_type is "none". */
-    withholding_reason?: WithholdingReason;
-    /** Set when status is "suspend" or "hold" due to TIN/W-9 deficiency. */
-    hold_reason?: HoldReason;
-    /** Gross transaction amount in USD. */
-    amount_usd?: number;
-    /** Withheld amount in USD. */
-    withheld_usd?: number;
-    /** Released (net) amount in USD. */
-    released_usd?: number;
+    withholding_type: string;
+    withholding_reason?: string;
+    hold_reason?: string;
+    amount_usd: number;
+    withheld_usd: number;
+    released_usd: number;
     /**
      * True when this is the customer's first withdrawal.
-     * Correct on the POST /transactions response and on tm.transaction.callback (both read
-     * from the in-memory struct before any DB re-fetch). Not persisted — getTransaction()
-     * always returns false regardless of actual history.
+     * Correct on the POST /transactions response and on tm.transaction.callback.
+     * Not persisted — getTransaction() always returns false regardless of actual history.
      */
     is_first_withdrawal?: boolean;
     tax_year: number;
@@ -78,8 +75,8 @@ type Transaction = {
     country?: string;
     ip_address?: string;
     risk_score: number;
-    metadata?: JSONB;
-    beneficiary_comment?: string;
+    metadata?: Record<string, unknown>;
+    benificiary_comment?: string;
     transaction_date: string;
     created_at: string;
     updated_at: string;
@@ -96,45 +93,45 @@ interface TransactionClientConfig {
     environment?: 'production' | 'sandbox';
 }
 /**
- * Response from POST /api/v1/tm/transactions.
+ * Response from POST /api/v1/transactions.
  *
- * Status → outcome mapping:
- *   "completed" — Vesant accepted; trigger the payment gateway (clean TIN,
- *                 backup withholding applied, or treaty rate applied)
- *   "hold"      — blocked, hold_reason set, no funds moved
- *   "suspend"   — blocked, hold_reason set, no funds moved
+ * Status → outcome mapping (withdrawal transactions only):
+ *   "pending"  — Vesant accepted; trigger the payment gateway (full release,
+ *                backup withholding applied, or treaty rate applied)
+ *   "suspend"  — blocked, hold_reason set, no funds moved
  */
 type TransactionCreateResponse = {
     transaction: Transaction;
     message: string;
 };
 /**
- * Fired after every transaction is created.
- * Delivers the final transaction state including withholding outcome so clients
- * can mirror it without a separate polling call.
+ * Fired after every transaction is created and after a suspended transaction is released.
+ * Delivers the final compliance-evaluated state including withholding outcome.
  */
 interface TransactionCallbackEvent {
     event_type: "tm.transaction.callback";
+    id: string;
+    tenant_id: string;
+    entity_id: string;
+    user_id: string;
     tx_id: string;
     reference: string;
     customer_id: string;
-    transaction_type: TransactionType;
-    transaction_mode: TransactionMode;
-    status: TransactionStatus;
+    transaction_type: string;
+    transaction_mode: string;
+    status: string;
     amount: string;
     currency: string;
     withheld_amount: string;
     released_amount: string;
     withholding_rate: number;
-    withholding_type: WithholdingType;
-    /** Null when withholding_type is "none". */
-    withholding_reason: WithholdingReason | null;
+    withholding_type: string;
+    withholding_reason?: string | null;
+    hold_reason?: string | null;
     amount_usd: number;
     withheld_usd: number;
     released_usd: number;
     is_first_withdrawal: boolean;
-    /** Set when status is "suspend" or "hold"; null otherwise. */
-    hold_reason: HoldReason | null;
     transaction_date: string;
 }
 /**
@@ -154,34 +151,173 @@ interface TransactionHeldEvent {
 }
 /** Discriminated union of all TM service webhook event payloads. */
 type TransactionWebhookEvent = TransactionCallbackEvent | TransactionHeldEvent;
+interface TmTenantSettings {
+    tenant_id: string;
+    transaction_monitoring_enabled: boolean;
+    tax_monitoring_enabled: boolean;
+}
+/**
+ * Semantic handler interface for the three withholding outcomes of a tm.transaction.callback.
+ * Register with TransactionWebhookHandler.registerCallbackHandler().
+ */
+interface TransactionCallbackHandler {
+    onWithheld?(event: TransactionCallbackEvent): void | Promise<void>;
+    onHeld?(event: TransactionCallbackEvent): void | Promise<void>;
+    onReleased?(event: TransactionCallbackEvent): void | Promise<void>;
+}
+
+type WithdrawalState = 'vesant_pending' | 'withheld' | 'suspend' | 'released' | 'failed';
+declare class PendingWithdrawal {
+    private _state;
+    private _event;
+    private _error;
+    private _waitPromise;
+    private _resolveWait?;
+    private _rejectWait?;
+    readonly tx_id: string;
+    readonly initialTransaction: Transaction;
+    constructor(tx_id: string, transaction: Transaction);
+    status(): WithdrawalState;
+    callbackEvent(): TransactionCallbackEvent | null;
+    wait(signal?: AbortSignal): Promise<TransactionCallbackEvent>;
+    /** Called by TransactionWebhookHandler when the tm.transaction.callback arrives for this tx_id. */
+    _settle(event: TransactionCallbackEvent): void;
+    /** Called to fail the pending withdrawal with a generic error (e.g. abort, network loss). */
+    _fail(err: unknown): void;
+}
+
+type CustomerType = 'US_PERSON' | 'NON_US_PERSON' | 'NON_US_ENTITY';
+type CTPFormStatus = 'requested' | 'signed' | 'manual' | 'bounced' | 'uploaded' | 'expired' | 're_requested';
+type CTPTINStatus = 'not_required' | 'pending' | 'submitted' | 'verified' | 'rejected' | 'error' | 'expired';
+interface CustomerTaxProfileRecord {
+    id: string;
+    tenant_id: string;
+    customer_id: string;
+    customer_type: CustomerType;
+    form_type: string;
+    form_status: CTPFormStatus;
+    tin_status: CTPTINStatus;
+    tin_value?: string;
+    recipient_name?: string;
+    business_name?: string;
+    account_number?: string;
+    address?: string;
+    address_city?: string;
+    address_state?: string;
+    address_zip?: string;
+    address_country?: string;
+    customer_name?: string;
+    avalara_form_id?: string;
+    avalara_company_id?: string;
+    signed_at?: string;
+    verified_at?: string;
+    expiry_date?: string;
+    backup_withholding: boolean;
+    b_notice_received: boolean;
+    e_delivery_consent: boolean;
+    withholding_enabled_by?: string;
+    withholding_enabled_at?: string;
+    tin_due_date?: string;
+    last_tin_check?: string;
+    request_count: number;
+    reminders_sent: number;
+    last_reminder_at?: string;
+    created_at: string;
+    updated_at: string;
+}
+type TaxFormTrigger = 'trigger_account_creation' | 'trigger_first_withdrawal' | 'trigger_threshold' | 'trigger_manual' | 'trigger_tin_invalid' | 'trigger_w8ben_expiry' | 'trigger_tin_expired';
+interface CustomerTaxProfileDocuments {
+    w_form: string;
+    '1099_form': string;
+}
+interface RequestTaxFormWithProfileInput {
+    customer_id: string;
+    email: string;
+    trigger: TaxFormTrigger;
+    first_name?: string;
+    last_name?: string;
+    date_of_birth?: string;
+    phone_number?: string;
+    country?: string;
+    state?: string;
+    city?: string;
+    zip_code?: string;
+    address?: string;
+    ip_address?: string;
+    form_type?: string;
+}
+interface RequestTaxFormWithProfileOutput {
+    profile?: CustomerTaxProfileRecord;
+    request_id?: string;
+    reference_id?: string;
+    form_id?: string;
+    public_url?: string;
+}
+
+declare class TaxTransactionClient extends BaseClient {
+    getCustomerDocuments(customerID: string): Promise<CustomerTaxProfileDocuments>;
+    requestTaxFormWithProfile(input: RequestTaxFormWithProfileInput, requestOptions?: RequestOptions): Promise<RequestTaxFormWithProfileOutput>;
+}
 
 /**
  * TransactionClient — SDK for the Transaction Monitoring service
  */
 
 declare class TransactionClient extends BaseClient {
+    readonly tax: TaxTransactionClient;
     constructor(config: BaseClientConfig);
+    /**
+     * Submit a transaction via the unified ingestion endpoint.
+     *
+     * POST /api/v1/transactions is gated on ANY of transaction monitoring, tax,
+     * or fraud being enabled for the tenant, so fraud-only and tax-only tenants
+     * can ingest even with TM switched off.
+     */
     createTransaction(request: TransactionCreateDTO, requestOptions?: RequestOptions): Promise<TransactionCreateResponse>;
+    submitWithdrawal(request: TransactionCreateDTO, requestOptions?: RequestOptions): Promise<PendingWithdrawal>;
     getTransaction(transactionId: string, requestOptions?: RequestOptions): Promise<Transaction>;
+    getSettings(): Promise<TmTenantSettings>;
+}
+
+declare class DuplicateTransactionError extends VesantError {
+    readonly tx_id: string;
+    constructor(tx_id: string, message?: string);
+}
+declare class TaxHoldError extends Error {
+    readonly tx_id: string;
+    readonly hold_reason: HoldReason;
+    readonly event: TransactionCallbackEvent;
+    constructor(event: TransactionCallbackEvent);
 }
 
 type EventHandler<T> = (event: T) => void | Promise<void>;
+declare const TRANSACTION_SIGNATURE_HEADER = "x-webhook-signature";
 interface TransactionWebhookHandlerConfig {
     secret: string;
     /** Reject duplicate event_type+tx_id pairs within replayWindow. Default: true. */
     replayProtection?: boolean;
     /** How long (ms) to remember seen events for replay detection. Default: 300_000 (5 min). */
     replayWindow?: number;
+    /** Pluggable dedup store for replay protection (default: in-memory, process-local). */
+    dedupStore?: WebhookDedupStore;
 }
 declare class TransactionWebhookHandler {
     private readonly handlers;
     private readonly secret;
     private readonly replayProtection;
     private readonly replayWindow;
-    private seenEvents;
+    private readonly dedupStore;
+    private readonly pendingWithdrawals;
+    private callbackHandler;
     constructor(config: TransactionWebhookHandlerConfig);
     on(eventType: 'tm.transaction.callback', handler: EventHandler<TransactionCallbackEvent>): this;
     on(eventType: 'tm.transaction.held', handler: EventHandler<TransactionHeldEvent>): this;
+    /** Register a semantic callback handler for the three withholding outcomes. Replaces any previous handler. */
+    registerCallbackHandler(handler: TransactionCallbackHandler): this;
+    /** Track a PendingWithdrawal so it is auto-settled when its tm.transaction.callback arrives. */
+    link(pending: PendingWithdrawal): this;
+    /** Stop tracking a PendingWithdrawal by tx_id. */
+    unlink(tx_id: string): this;
     /** Verify HMAC-SHA256 signature only. Returns false instead of throwing. */
     verify(rawBody: string, signature: string): Promise<boolean>;
     /** Parse and validate required fields. Does not verify signature — use verifyAndParse in production. */
@@ -192,4 +328,4 @@ declare class TransactionWebhookHandler {
     handle(body: string, signature: string): Promise<void>;
 }
 
-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 };
+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 };