@vesant-sdk/transaction 0.1.1-dev.9b89b96 → 0.1.1-dev.ab7ff29

package/dist/index.d.mts

@@ -1,45 +1,38 @@
-import { Timestamp, BaseClient, BaseClientConfig, RequestOptions } from '@vesant-sdk/core';
+import { BaseClient, BaseClientConfig, RequestOptions, VesantError } 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;
+    amount_usd: number;
     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.
-     */
-    amount_usd?: number;
-    status?: TransactionStatus;
     source_account?: string;
     destination_account?: string;
     country?: string;
     ip_address?: string;
-    metadata?: Record<string, any>;
-    beneficiary_comment?: string;
-    transaction_date: Timestamp;
+    benificiary_comment?: string;
+    metadata?: Record<string, unknown>;
+    transaction_date: 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 +41,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 +66,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;
@@ -98,43 +86,43 @@ interface TransactionClientConfig {
 /**
  * Response from POST /api/v1/tm/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,6 +142,40 @@ 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;
+}
 
 /**
  * TransactionClient — SDK for the Transaction Monitoring service
@@ -162,10 +184,24 @@ type TransactionWebhookEvent = TransactionCallbackEvent | TransactionHeldEvent;
 declare class TransactionClient extends BaseClient {
     constructor(config: BaseClientConfig);
     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. */
@@ -178,10 +214,18 @@ declare class TransactionWebhookHandler {
     private readonly secret;
     private readonly replayProtection;
     private readonly replayWindow;
-    private seenEvents;
+    private readonly seenEvents;
+    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 +236,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 { DuplicateTransactionError, type HoldReason, PendingWithdrawal, TRANSACTION_SIGNATURE_HEADER, TaxHoldError, 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

@@ -1,45 +1,38 @@
-import { Timestamp, BaseClient, BaseClientConfig, RequestOptions } from '@vesant-sdk/core';
+import { BaseClient, BaseClientConfig, RequestOptions, VesantError } 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;
+    amount_usd: number;
     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.
-     */
-    amount_usd?: number;
-    status?: TransactionStatus;
     source_account?: string;
     destination_account?: string;
     country?: string;
     ip_address?: string;
-    metadata?: Record<string, any>;
-    beneficiary_comment?: string;
-    transaction_date: Timestamp;
+    benificiary_comment?: string;
+    metadata?: Record<string, unknown>;
+    transaction_date: 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 +41,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 +66,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;
@@ -98,43 +86,43 @@ interface TransactionClientConfig {
 /**
  * Response from POST /api/v1/tm/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,6 +142,40 @@ 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;
+}
 
 /**
  * TransactionClient — SDK for the Transaction Monitoring service
@@ -162,10 +184,24 @@ type TransactionWebhookEvent = TransactionCallbackEvent | TransactionHeldEvent;
 declare class TransactionClient extends BaseClient {
     constructor(config: BaseClientConfig);
     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. */
@@ -178,10 +214,18 @@ declare class TransactionWebhookHandler {
     private readonly secret;
     private readonly replayProtection;
     private readonly replayWindow;
-    private seenEvents;
+    private readonly seenEvents;
+    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 +236,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 { DuplicateTransactionError, type HoldReason, PendingWithdrawal, TRANSACTION_SIGNATURE_HEADER, TaxHoldError, 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.js

@@ -2,25 +2,132 @@
 
 var core = require('@vesant-sdk/core');
 
+// src/client.ts
+var DuplicateTransactionError = class _DuplicateTransactionError extends core.VesantError {
+  constructor(tx_id, message = `Duplicate transaction: ${tx_id} already exists`) {
+    super(message, "DUPLICATE_TRANSACTION", 409);
+    this.name = "DuplicateTransactionError";
+    this.tx_id = tx_id;
+    Object.setPrototypeOf(this, _DuplicateTransactionError.prototype);
+  }
+};
+var TaxHoldError = class _TaxHoldError extends Error {
+  constructor(event) {
+    super(`Transaction ${event.tx_id} held: ${event.hold_reason}`);
+    this.name = "TaxHoldError";
+    this.tx_id = event.tx_id;
+    this.hold_reason = event.hold_reason;
+    this.event = event;
+    Object.setPrototypeOf(this, _TaxHoldError.prototype);
+  }
+};
+
+// src/pending-withdrawal.ts
+var PendingWithdrawal = class {
+  constructor(tx_id, transaction) {
+    this._state = "vesant_pending";
+    this._event = null;
+    this._error = void 0;
+    // Deferred promise — created lazily only when wait() is called.
+    this._waitPromise = null;
+    this.tx_id = tx_id;
+    this.initialTransaction = transaction;
+  }
+  status() {
+    return this._state;
+  }
+  callbackEvent() {
+    return this._event;
+  }
+  wait(signal) {
+    if (this._state !== "vesant_pending") {
+      if (this._state === "suspend" || this._state === "failed") {
+        return Promise.reject(this._error);
+      }
+      if (this._event !== null) {
+        return Promise.resolve(this._event);
+      }
+    }
+    if (!this._waitPromise) {
+      this._waitPromise = new Promise((resolve, reject) => {
+        this._resolveWait = resolve;
+        this._rejectWait = reject;
+      });
+    }
+    if (signal) {
+      if (signal.aborted) {
+        this._fail(new core.VesantError("Request aborted", "REQUEST_ABORTED"));
+      } else {
+        signal.addEventListener("abort", () => {
+          this._fail(new core.VesantError("Request aborted", "REQUEST_ABORTED"));
+        }, { once: true });
+      }
+    }
+    return this._waitPromise;
+  }
+  /** Called by TransactionWebhookHandler when the tm.transaction.callback arrives for this tx_id. */
+  _settle(event) {
+    if (this._state !== "vesant_pending") return;
+    this._event = event;
+    if (event.status === "hold" || event.status === "suspend") {
+      this._state = "suspend";
+      this._error = new TaxHoldError(event);
+      this._rejectWait?.(this._error);
+    } else if (event.withholding_type === "none") {
+      this._state = "released";
+      this._resolveWait?.(event);
+    } else {
+      this._state = "withheld";
+      this._resolveWait?.(event);
+    }
+  }
+  /** Called to fail the pending withdrawal with a generic error (e.g. abort, network loss). */
+  _fail(err) {
+    if (this._state !== "vesant_pending") return;
+    this._state = "failed";
+    this._error = err;
+    this._rejectWait?.(err);
+  }
+};
+
 // src/client.ts
 var TransactionClient = class extends core.BaseClient {
   constructor(config) {
     super(config);
   }
   async createTransaction(request, requestOptions) {
-    const data = await this.requestWithRetry("/api/v1/tm/transactions", {
-      method: "POST",
-      body: JSON.stringify(request)
-    }, void 0, void 0, requestOptions);
-    return data;
+    try {
+      return await this.requestWithRetry("/api/v1/tm/transactions", {
+        method: "POST",
+        body: JSON.stringify(request)
+      }, void 0, void 0, requestOptions);
+    } catch (error) {
+      if (error instanceof core.VesantError && error.statusCode === 409) {
+        const transaction = await this.getTransaction(request.tx_id, requestOptions);
+        return { transaction, message: "Transaction already exists" };
+      }
+      throw error;
+    }
+  }
+  async submitWithdrawal(request, requestOptions) {
+    const response = await this.createTransaction(
+      { ...request, transaction_type: "withdrawal" },
+      requestOptions
+    );
+    return new PendingWithdrawal(response.transaction.tx_id, response.transaction);
   }
   async getTransaction(transactionId, requestOptions) {
-    const data = await this.requestWithRetry(`/api/v1/tm/transactions/status/${transactionId}`, {
+    return this.requestWithRetry(`/api/v1/tm/transactions/status/${transactionId}`, {
       method: "GET"
     }, void 0, void 0, requestOptions);
-    return data;
+  }
+  async getSettings() {
+    return this.requestWithRetry("/api/v1/tm/settings", {
+      method: "GET"
+    });
   }
 };
+var TRANSACTION_SIGNATURE_HEADER = "x-webhook-signature";
 var TransactionWebhookHandler = class {
   constructor(config) {
     this.handlers = {
@@ -28,6 +135,8 @@ var TransactionWebhookHandler = class {
       "tm.transaction.held": []
     };
     this.seenEvents = /* @__PURE__ */ new Map();
+    this.pendingWithdrawals = /* @__PURE__ */ new Map();
+    this.callbackHandler = null;
     this.secret = config.secret;
     this.replayProtection = config.replayProtection ?? true;
     this.replayWindow = config.replayWindow ?? 3e5;
@@ -36,6 +145,21 @@ var TransactionWebhookHandler = class {
     this.handlers[eventType].push(handler);
     return this;
   }
+  /** Register a semantic callback handler for the three withholding outcomes. Replaces any previous handler. */
+  registerCallbackHandler(handler) {
+    this.callbackHandler = handler;
+    return this;
+  }
+  /** Track a PendingWithdrawal so it is auto-settled when its tm.transaction.callback arrives. */
+  link(pending) {
+    this.pendingWithdrawals.set(pending.tx_id, pending);
+    return this;
+  }
+  /** Stop tracking a PendingWithdrawal by tx_id. */
+  unlink(tx_id) {
+    this.pendingWithdrawals.delete(tx_id);
+    return this;
+  }
   /** Verify HMAC-SHA256 signature only. Returns false instead of throwing. */
   async verify(rawBody, signature) {
     return core.verifyWebhookSignature(rawBody, signature, this.secret);
@@ -81,6 +205,22 @@ var TransactionWebhookHandler = class {
   /** Verify signature, parse, and dispatch to registered handlers. */
   async handle(body, signature) {
     const event = await this.verifyAndParse(body, signature);
+    if (event.event_type === "tm.transaction.callback") {
+      const pending = this.pendingWithdrawals.get(event.tx_id);
+      if (pending) {
+        pending._settle(event);
+        this.pendingWithdrawals.delete(event.tx_id);
+      }
+      if (this.callbackHandler) {
+        if (event.status === "hold" || event.status === "suspend") {
+          await this.callbackHandler.onHeld?.(event);
+        } else if (event.withholding_type === "none") {
+          await this.callbackHandler.onReleased?.(event);
+        } else {
+          await this.callbackHandler.onWithheld?.(event);
+        }
+      }
+    }
     const handlers = this.handlers[event.event_type];
     for (const handler of handlers) {
       await handler(event);
@@ -88,6 +228,10 @@ var TransactionWebhookHandler = class {
   }
 };
 
+exports.DuplicateTransactionError = DuplicateTransactionError;
+exports.PendingWithdrawal = PendingWithdrawal;
+exports.TRANSACTION_SIGNATURE_HEADER = TRANSACTION_SIGNATURE_HEADER;
+exports.TaxHoldError = TaxHoldError;
 exports.TransactionClient = TransactionClient;
 exports.TransactionWebhookHandler = TransactionWebhookHandler;
 //# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"sources":["../src/client.ts","../src/webhook-handler.ts"],"names":["BaseClient","verifyWebhookSignature","ValidationError"],"mappings":"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","file":"index.js","sourcesContent":["/**\n * TransactionClient — SDK for the Transaction Monitoring service\n */\n\nimport { BaseClient } from '@vesant-sdk/core';\nimport type { BaseClientConfig, RequestOptions } from '@vesant-sdk/core';\nimport type { Transaction, TransactionCreateDTO, TransactionCreateResponse } from './types';\n\nexport class TransactionClient extends BaseClient {\n  constructor(config: BaseClientConfig) {\n    super(config);\n  }\n\n  async createTransaction(\n    request: TransactionCreateDTO,\n    requestOptions?: RequestOptions\n  ): Promise<TransactionCreateResponse> {\n    const data = await this.requestWithRetry<TransactionCreateResponse>('/api/v1/tm/transactions', {\n      method: 'POST',\n      body: JSON.stringify(request),\n    }, undefined, undefined, requestOptions);\n    return data;\n  }\n\n  async getTransaction(transactionId: string, requestOptions?: RequestOptions): Promise<Transaction> {\n    const data = await this.requestWithRetry<Transaction>(`/api/v1/tm/transactions/status/${transactionId}`, {\n      method: 'GET',\n    }, undefined, undefined, requestOptions);\n    return data;\n  }\n}\n","import { verifyWebhookSignature, ValidationError } from '@vesant-sdk/core';\nimport type {\n  TransactionCallbackEvent,\n  TransactionHeldEvent,\n  TransactionWebhookEvent,\n} from './types';\n\ntype EventHandler<T> = (event: T) => void | Promise<void>;\n\ntype HandlerMap = {\n  'tm.transaction.callback': Array<EventHandler<TransactionCallbackEvent>>;\n  'tm.transaction.held': Array<EventHandler<TransactionHeldEvent>>;\n};\n\nexport interface TransactionWebhookHandlerConfig {\n  secret: string;\n  /** Reject duplicate event_type+tx_id pairs within replayWindow. Default: true. */\n  replayProtection?: boolean;\n  /** How long (ms) to remember seen events for replay detection. Default: 300_000 (5 min). */\n  replayWindow?: number;\n}\n\nexport class TransactionWebhookHandler {\n  private readonly handlers: HandlerMap = {\n    'tm.transaction.callback': [],\n    'tm.transaction.held': [],\n  };\n  private readonly secret: string;\n  private readonly replayProtection: boolean;\n  private readonly replayWindow: number;\n  private seenEvents = new Map<string, number>();\n\n  constructor(config: TransactionWebhookHandlerConfig) {\n    this.secret = config.secret;\n    this.replayProtection = config.replayProtection ?? true;\n    this.replayWindow = config.replayWindow ?? 300_000;\n  }\n\n  on(eventType: 'tm.transaction.callback', handler: EventHandler<TransactionCallbackEvent>): this;\n  on(eventType: 'tm.transaction.held', handler: EventHandler<TransactionHeldEvent>): this;\n  on(eventType: keyof HandlerMap, handler: EventHandler<TransactionCallbackEvent> | EventHandler<TransactionHeldEvent>): this {\n    (this.handlers[eventType] as Array<typeof handler>).push(handler);\n    return this;\n  }\n\n  /** Verify HMAC-SHA256 signature only. Returns false instead of throwing. */\n  async verify(rawBody: string, signature: string): Promise<boolean> {\n    return verifyWebhookSignature(rawBody, signature, this.secret);\n  }\n\n  /** Parse and validate required fields. Does not verify signature — use verifyAndParse in production. */\n  parse(body: string): TransactionWebhookEvent {\n    const event = JSON.parse(body) as TransactionWebhookEvent;\n    if (!event.event_type || !event.tx_id) {\n      throw new ValidationError(\n        'Invalid TM webhook event: missing required fields (event_type, tx_id)',\n        ['event_type', 'tx_id']\n      );\n    }\n    return event;\n  }\n\n  /** Verify signature, parse, and check for replays. Throws ValidationError on any failure. */\n  async verifyAndParse(body: string, signature: string): Promise<TransactionWebhookEvent> {\n    const isValid = await verifyWebhookSignature(body, signature, this.secret);\n    if (!isValid) {\n      throw new ValidationError('Invalid webhook signature', ['signature']);\n    }\n\n    const event = this.parse(body);\n\n    if (this.replayProtection) {\n      const key = `${event.event_type}:${event.tx_id}`;\n      if (this.seenEvents.has(key)) {\n        throw new ValidationError(\n          `Duplicate webhook event: ${event.event_type} for ${event.tx_id} has already been processed`,\n          ['tx_id']\n        );\n      }\n      const now = Date.now();\n      this.seenEvents.set(key, now);\n      if (this.seenEvents.size > 1000) {\n        for (const [k, seenAt] of this.seenEvents) {\n          if (now - seenAt > this.replayWindow) {\n            this.seenEvents.delete(k);\n          }\n        }\n      }\n    }\n\n    return event;\n  }\n\n  /** Verify signature, parse, and dispatch to registered handlers. */\n  async handle(body: string, signature: string): Promise<void> {\n    const event = await this.verifyAndParse(body, signature);\n    const handlers = this.handlers[event.event_type] as Array<EventHandler<typeof event>>;\n    for (const handler of handlers) {\n      await handler(event);\n    }\n  }\n}\n"]}
+{"version":3,"sources":["../src/errors.ts","../src/pending-withdrawal.ts","../src/client.ts","../src/webhook-handler.ts"],"names":["VesantError","BaseClient","verifyWebhookSignature","ValidationError"],"mappings":"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","file":"index.js","sourcesContent":["import { VesantError } from '@vesant-sdk/core';\nimport type { TransactionCallbackEvent, HoldReason } from './types';\n\nexport class DuplicateTransactionError extends VesantError {\n  readonly tx_id: string;\n\n  constructor(tx_id: string, message = `Duplicate transaction: ${tx_id} already exists`) {\n    super(message, 'DUPLICATE_TRANSACTION', 409);\n    this.name = 'DuplicateTransactionError';\n    this.tx_id = tx_id;\n    Object.setPrototypeOf(this, DuplicateTransactionError.prototype);\n  }\n}\n\nexport class TaxHoldError extends Error {\n  readonly tx_id: string;\n  readonly hold_reason: HoldReason;\n  readonly event: TransactionCallbackEvent;\n\n  constructor(event: TransactionCallbackEvent) {\n    super(`Transaction ${event.tx_id} held: ${event.hold_reason}`);\n    this.name = 'TaxHoldError';\n    this.tx_id = event.tx_id;\n    this.hold_reason = event.hold_reason as HoldReason;\n    this.event = event;\n    Object.setPrototypeOf(this, TaxHoldError.prototype);\n  }\n}\n","import { VesantError } from '@vesant-sdk/core';\nimport { TaxHoldError } from './errors';\nimport type { Transaction, TransactionCallbackEvent } from './types';\n\nexport type WithdrawalState = 'vesant_pending' | 'withheld' | 'suspend' | 'released' | 'failed';\n\nexport class PendingWithdrawal {\n  private _state: WithdrawalState = 'vesant_pending';\n  private _event: TransactionCallbackEvent | null = null;\n  private _error: unknown = undefined;\n\n  // Deferred promise — created lazily only when wait() is called.\n  private _waitPromise: Promise<TransactionCallbackEvent> | null = null;\n  private _resolveWait?: (event: TransactionCallbackEvent) => void;\n  private _rejectWait?: (err: unknown) => void;\n\n  readonly tx_id: string;\n  readonly initialTransaction: Transaction;\n\n  constructor(tx_id: string, transaction: Transaction) {\n    this.tx_id = tx_id;\n    this.initialTransaction = transaction;\n  }\n\n  status(): WithdrawalState {\n    return this._state;\n  }\n\n  callbackEvent(): TransactionCallbackEvent | null {\n    return this._event;\n  }\n\n  wait(signal?: AbortSignal): Promise<TransactionCallbackEvent> {\n    if (this._state !== 'vesant_pending') {\n      if (this._state === 'suspend' || this._state === 'failed') {\n        return Promise.reject(this._error);\n      }\n      if (this._event !== null) {\n        return Promise.resolve(this._event);\n      }\n    }\n\n    if (!this._waitPromise) {\n      this._waitPromise = new Promise<TransactionCallbackEvent>((resolve, reject) => {\n        this._resolveWait = resolve;\n        this._rejectWait = reject;\n      });\n    }\n\n    if (signal) {\n      if (signal.aborted) {\n        this._fail(new VesantError('Request aborted', 'REQUEST_ABORTED'));\n      } else {\n        signal.addEventListener('abort', () => {\n          this._fail(new VesantError('Request aborted', 'REQUEST_ABORTED'));\n        }, { once: true });\n      }\n    }\n\n    return this._waitPromise;\n  }\n\n  /** Called by TransactionWebhookHandler when the tm.transaction.callback arrives for this tx_id. */\n  _settle(event: TransactionCallbackEvent): void {\n    if (this._state !== 'vesant_pending') return;\n    this._event = event;\n    if (event.status === 'hold' || event.status === 'suspend') {\n      this._state = 'suspend';\n      this._error = new TaxHoldError(event);\n      this._rejectWait?.(this._error);\n    } else if (event.withholding_type === 'none') {\n      this._state = 'released';\n      this._resolveWait?.(event);\n    } else {\n      this._state = 'withheld';\n      this._resolveWait?.(event);\n    }\n  }\n\n  /** Called to fail the pending withdrawal with a generic error (e.g. abort, network loss). */\n  _fail(err: unknown): void {\n    if (this._state !== 'vesant_pending') return;\n    this._state = 'failed';\n    this._error = err;\n    this._rejectWait?.(err);\n  }\n}\n","/**\n * TransactionClient — SDK for the Transaction Monitoring service\n */\nimport { BaseClient, VesantError } from '@vesant-sdk/core';\nimport type { BaseClientConfig, RequestOptions } from '@vesant-sdk/core';\nimport type { Transaction, TransactionCreateDTO, TransactionCreateResponse, TmTenantSettings } from './types';\nimport { PendingWithdrawal } from './pending-withdrawal';\n\nexport class TransactionClient extends BaseClient {\n  constructor(config: BaseClientConfig) {\n    super(config);\n  }\n\n  async createTransaction(\n    request: TransactionCreateDTO,\n    requestOptions?: RequestOptions\n  ): Promise<TransactionCreateResponse> {\n    try {\n      return await this.requestWithRetry<TransactionCreateResponse>('/api/v1/tm/transactions', {\n        method: 'POST',\n        body: JSON.stringify(request),\n      }, undefined, undefined, requestOptions);\n    } catch (error) {\n      if (error instanceof VesantError && error.statusCode === 409) {\n        const transaction = await this.getTransaction(request.tx_id, requestOptions);\n        return { transaction, message: 'Transaction already exists' };\n      }\n      throw error;\n    }\n  }\n\n  async submitWithdrawal(\n    request: TransactionCreateDTO,\n    requestOptions?: RequestOptions\n  ): Promise<PendingWithdrawal> {\n    const response = await this.createTransaction(\n      { ...request, transaction_type: 'withdrawal' },\n      requestOptions\n    );\n    return new PendingWithdrawal(response.transaction.tx_id, response.transaction);\n  }\n\n  async getTransaction(transactionId: string, requestOptions?: RequestOptions): Promise<Transaction> {\n    return this.requestWithRetry<Transaction>(`/api/v1/tm/transactions/status/${transactionId}`, {\n      method: 'GET',\n    }, undefined, undefined, requestOptions);\n  }\n\n  async getSettings(): Promise<TmTenantSettings> {\n    return this.requestWithRetry<TmTenantSettings>('/api/v1/tm/settings', {\n      method: 'GET',\n    });\n  }\n}\n","import { verifyWebhookSignature, ValidationError } from '@vesant-sdk/core';\nimport { PendingWithdrawal } from './pending-withdrawal';\nimport type {\n  TransactionCallbackEvent,\n  TransactionCallbackHandler,\n  TransactionHeldEvent,\n  TransactionWebhookEvent,\n} from './types';\n\ntype EventHandler<T> = (event: T) => void | Promise<void>;\n\ntype HandlerMap = {\n  'tm.transaction.callback': Array<EventHandler<TransactionCallbackEvent>>;\n  'tm.transaction.held': Array<EventHandler<TransactionHeldEvent>>;\n};\n\nexport const TRANSACTION_SIGNATURE_HEADER = 'x-webhook-signature';\n\nexport interface TransactionWebhookHandlerConfig {\n  secret: string;\n  /** Reject duplicate event_type+tx_id pairs within replayWindow. Default: true. */\n  replayProtection?: boolean;\n  /** How long (ms) to remember seen events for replay detection. Default: 300_000 (5 min). */\n  replayWindow?: number;\n}\n\nexport class TransactionWebhookHandler {\n  private readonly handlers: HandlerMap = {\n    'tm.transaction.callback': [],\n    'tm.transaction.held': [],\n  };\n  private readonly secret: string;\n  private readonly replayProtection: boolean;\n  private readonly replayWindow: number;\n  private readonly seenEvents = new Map<string, number>();\n  private readonly pendingWithdrawals = new Map<string, PendingWithdrawal>();\n  private callbackHandler: TransactionCallbackHandler | null = null;\n\n  constructor(config: TransactionWebhookHandlerConfig) {\n    this.secret = config.secret;\n    this.replayProtection = config.replayProtection ?? true;\n    this.replayWindow = config.replayWindow ?? 300_000;\n  }\n\n  on(eventType: 'tm.transaction.callback', handler: EventHandler<TransactionCallbackEvent>): this;\n  on(eventType: 'tm.transaction.held', handler: EventHandler<TransactionHeldEvent>): this;\n  on(eventType: keyof HandlerMap, handler: EventHandler<TransactionCallbackEvent> | EventHandler<TransactionHeldEvent>): this {\n    (this.handlers[eventType] as Array<typeof handler>).push(handler);\n    return this;\n  }\n\n  /** Register a semantic callback handler for the three withholding outcomes. Replaces any previous handler. */\n  registerCallbackHandler(handler: TransactionCallbackHandler): this {\n    this.callbackHandler = handler;\n    return this;\n  }\n\n  /** Track a PendingWithdrawal so it is auto-settled when its tm.transaction.callback arrives. */\n  link(pending: PendingWithdrawal): this {\n    this.pendingWithdrawals.set(pending.tx_id, pending);\n    return this;\n  }\n\n  /** Stop tracking a PendingWithdrawal by tx_id. */\n  unlink(tx_id: string): this {\n    this.pendingWithdrawals.delete(tx_id);\n    return this;\n  }\n\n  /** Verify HMAC-SHA256 signature only. Returns false instead of throwing. */\n  async verify(rawBody: string, signature: string): Promise<boolean> {\n    return verifyWebhookSignature(rawBody, signature, this.secret);\n  }\n\n  /** Parse and validate required fields. Does not verify signature — use verifyAndParse in production. */\n  parse(body: string): TransactionWebhookEvent {\n    const event = JSON.parse(body) as TransactionWebhookEvent;\n    if (!event.event_type || !event.tx_id) {\n      throw new ValidationError(\n        'Invalid TM webhook event: missing required fields (event_type, tx_id)',\n        ['event_type', 'tx_id']\n      );\n    }\n    return event;\n  }\n\n  /** Verify signature, parse, and check for replays. Throws ValidationError on any failure. */\n  async verifyAndParse(body: string, signature: string): Promise<TransactionWebhookEvent> {\n    const isValid = await verifyWebhookSignature(body, signature, this.secret);\n    if (!isValid) {\n      throw new ValidationError('Invalid webhook signature', ['signature']);\n    }\n\n    const event = this.parse(body);\n\n    if (this.replayProtection) {\n      const key = `${event.event_type}:${event.tx_id}`;\n      if (this.seenEvents.has(key)) {\n        throw new ValidationError(\n          `Duplicate webhook event: ${event.event_type} for ${event.tx_id} has already been processed`,\n          ['tx_id']\n        );\n      }\n      const now = Date.now();\n      this.seenEvents.set(key, now);\n      if (this.seenEvents.size > 1000) {\n        for (const [k, seenAt] of this.seenEvents) {\n          if (now - seenAt > this.replayWindow) {\n            this.seenEvents.delete(k);\n          }\n        }\n      }\n    }\n\n    return event;\n  }\n\n  /** Verify signature, parse, and dispatch to registered handlers. */\n  async handle(body: string, signature: string): Promise<void> {\n    const event = await this.verifyAndParse(body, signature);\n\n    if (event.event_type === 'tm.transaction.callback') {\n      const pending = this.pendingWithdrawals.get(event.tx_id);\n      if (pending) {\n        pending._settle(event);\n        this.pendingWithdrawals.delete(event.tx_id);\n      }\n\n      if (this.callbackHandler) {\n        if (event.status === 'hold' || event.status === 'suspend') {\n          await this.callbackHandler.onHeld?.(event);\n        } else if (event.withholding_type === 'none') {\n          await this.callbackHandler.onReleased?.(event);\n        } else {\n          await this.callbackHandler.onWithheld?.(event);\n        }\n      }\n    }\n\n    const handlers = this.handlers[event.event_type] as Array<EventHandler<typeof event>>;\n    for (const handler of handlers) {\n      await handler(event);\n    }\n  }\n}\n"]}

package/dist/index.mjs

@@ -1,4 +1,92 @@
-import { BaseClient, verifyWebhookSignature, ValidationError } from '@vesant-sdk/core';
+import { VesantError, BaseClient, verifyWebhookSignature, ValidationError } from '@vesant-sdk/core';
+
+// src/client.ts
+var DuplicateTransactionError = class _DuplicateTransactionError extends VesantError {
+  constructor(tx_id, message = `Duplicate transaction: ${tx_id} already exists`) {
+    super(message, "DUPLICATE_TRANSACTION", 409);
+    this.name = "DuplicateTransactionError";
+    this.tx_id = tx_id;
+    Object.setPrototypeOf(this, _DuplicateTransactionError.prototype);
+  }
+};
+var TaxHoldError = class _TaxHoldError extends Error {
+  constructor(event) {
+    super(`Transaction ${event.tx_id} held: ${event.hold_reason}`);
+    this.name = "TaxHoldError";
+    this.tx_id = event.tx_id;
+    this.hold_reason = event.hold_reason;
+    this.event = event;
+    Object.setPrototypeOf(this, _TaxHoldError.prototype);
+  }
+};
+
+// src/pending-withdrawal.ts
+var PendingWithdrawal = class {
+  constructor(tx_id, transaction) {
+    this._state = "vesant_pending";
+    this._event = null;
+    this._error = void 0;
+    // Deferred promise — created lazily only when wait() is called.
+    this._waitPromise = null;
+    this.tx_id = tx_id;
+    this.initialTransaction = transaction;
+  }
+  status() {
+    return this._state;
+  }
+  callbackEvent() {
+    return this._event;
+  }
+  wait(signal) {
+    if (this._state !== "vesant_pending") {
+      if (this._state === "suspend" || this._state === "failed") {
+        return Promise.reject(this._error);
+      }
+      if (this._event !== null) {
+        return Promise.resolve(this._event);
+      }
+    }
+    if (!this._waitPromise) {
+      this._waitPromise = new Promise((resolve, reject) => {
+        this._resolveWait = resolve;
+        this._rejectWait = reject;
+      });
+    }
+    if (signal) {
+      if (signal.aborted) {
+        this._fail(new VesantError("Request aborted", "REQUEST_ABORTED"));
+      } else {
+        signal.addEventListener("abort", () => {
+          this._fail(new VesantError("Request aborted", "REQUEST_ABORTED"));
+        }, { once: true });
+      }
+    }
+    return this._waitPromise;
+  }
+  /** Called by TransactionWebhookHandler when the tm.transaction.callback arrives for this tx_id. */
+  _settle(event) {
+    if (this._state !== "vesant_pending") return;
+    this._event = event;
+    if (event.status === "hold" || event.status === "suspend") {
+      this._state = "suspend";
+      this._error = new TaxHoldError(event);
+      this._rejectWait?.(this._error);
+    } else if (event.withholding_type === "none") {
+      this._state = "released";
+      this._resolveWait?.(event);
+    } else {
+      this._state = "withheld";
+      this._resolveWait?.(event);
+    }
+  }
+  /** Called to fail the pending withdrawal with a generic error (e.g. abort, network loss). */
+  _fail(err) {
+    if (this._state !== "vesant_pending") return;
+    this._state = "failed";
+    this._error = err;
+    this._rejectWait?.(err);
+  }
+};
 
 // src/client.ts
 var TransactionClient = class extends BaseClient {
@@ -6,19 +94,38 @@ var TransactionClient = class extends BaseClient {
     super(config);
   }
   async createTransaction(request, requestOptions) {
-    const data = await this.requestWithRetry("/api/v1/tm/transactions", {
-      method: "POST",
-      body: JSON.stringify(request)
-    }, void 0, void 0, requestOptions);
-    return data;
+    try {
+      return await this.requestWithRetry("/api/v1/tm/transactions", {
+        method: "POST",
+        body: JSON.stringify(request)
+      }, void 0, void 0, requestOptions);
+    } catch (error) {
+      if (error instanceof VesantError && error.statusCode === 409) {
+        const transaction = await this.getTransaction(request.tx_id, requestOptions);
+        return { transaction, message: "Transaction already exists" };
+      }
+      throw error;
+    }
+  }
+  async submitWithdrawal(request, requestOptions) {
+    const response = await this.createTransaction(
+      { ...request, transaction_type: "withdrawal" },
+      requestOptions
+    );
+    return new PendingWithdrawal(response.transaction.tx_id, response.transaction);
   }
   async getTransaction(transactionId, requestOptions) {
-    const data = await this.requestWithRetry(`/api/v1/tm/transactions/status/${transactionId}`, {
+    return this.requestWithRetry(`/api/v1/tm/transactions/status/${transactionId}`, {
       method: "GET"
     }, void 0, void 0, requestOptions);
-    return data;
+  }
+  async getSettings() {
+    return this.requestWithRetry("/api/v1/tm/settings", {
+      method: "GET"
+    });
   }
 };
+var TRANSACTION_SIGNATURE_HEADER = "x-webhook-signature";
 var TransactionWebhookHandler = class {
   constructor(config) {
     this.handlers = {
@@ -26,6 +133,8 @@ var TransactionWebhookHandler = class {
       "tm.transaction.held": []
     };
     this.seenEvents = /* @__PURE__ */ new Map();
+    this.pendingWithdrawals = /* @__PURE__ */ new Map();
+    this.callbackHandler = null;
     this.secret = config.secret;
     this.replayProtection = config.replayProtection ?? true;
     this.replayWindow = config.replayWindow ?? 3e5;
@@ -34,6 +143,21 @@ var TransactionWebhookHandler = class {
     this.handlers[eventType].push(handler);
     return this;
   }
+  /** Register a semantic callback handler for the three withholding outcomes. Replaces any previous handler. */
+  registerCallbackHandler(handler) {
+    this.callbackHandler = handler;
+    return this;
+  }
+  /** Track a PendingWithdrawal so it is auto-settled when its tm.transaction.callback arrives. */
+  link(pending) {
+    this.pendingWithdrawals.set(pending.tx_id, pending);
+    return this;
+  }
+  /** Stop tracking a PendingWithdrawal by tx_id. */
+  unlink(tx_id) {
+    this.pendingWithdrawals.delete(tx_id);
+    return this;
+  }
   /** Verify HMAC-SHA256 signature only. Returns false instead of throwing. */
   async verify(rawBody, signature) {
     return verifyWebhookSignature(rawBody, signature, this.secret);
@@ -79,6 +203,22 @@ var TransactionWebhookHandler = class {
   /** Verify signature, parse, and dispatch to registered handlers. */
   async handle(body, signature) {
     const event = await this.verifyAndParse(body, signature);
+    if (event.event_type === "tm.transaction.callback") {
+      const pending = this.pendingWithdrawals.get(event.tx_id);
+      if (pending) {
+        pending._settle(event);
+        this.pendingWithdrawals.delete(event.tx_id);
+      }
+      if (this.callbackHandler) {
+        if (event.status === "hold" || event.status === "suspend") {
+          await this.callbackHandler.onHeld?.(event);
+        } else if (event.withholding_type === "none") {
+          await this.callbackHandler.onReleased?.(event);
+        } else {
+          await this.callbackHandler.onWithheld?.(event);
+        }
+      }
+    }
     const handlers = this.handlers[event.event_type];
     for (const handler of handlers) {
       await handler(event);
@@ -86,6 +226,6 @@ var TransactionWebhookHandler = class {
   }
 };
 
-export { TransactionClient, TransactionWebhookHandler };
+export { DuplicateTransactionError, PendingWithdrawal, TRANSACTION_SIGNATURE_HEADER, TaxHoldError, TransactionClient, TransactionWebhookHandler };
 //# sourceMappingURL=index.mjs.map
 //# sourceMappingURL=index.mjs.map

package/dist/index.mjs.map

@@ -1 +1 @@
-{"version":3,"sources":["../src/client.ts","../src/webhook-handler.ts"],"names":[],"mappings":"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","file":"index.mjs","sourcesContent":["/**\n * TransactionClient — SDK for the Transaction Monitoring service\n */\n\nimport { BaseClient } from '@vesant-sdk/core';\nimport type { BaseClientConfig, RequestOptions } from '@vesant-sdk/core';\nimport type { Transaction, TransactionCreateDTO, TransactionCreateResponse } from './types';\n\nexport class TransactionClient extends BaseClient {\n  constructor(config: BaseClientConfig) {\n    super(config);\n  }\n\n  async createTransaction(\n    request: TransactionCreateDTO,\n    requestOptions?: RequestOptions\n  ): Promise<TransactionCreateResponse> {\n    const data = await this.requestWithRetry<TransactionCreateResponse>('/api/v1/tm/transactions', {\n      method: 'POST',\n      body: JSON.stringify(request),\n    }, undefined, undefined, requestOptions);\n    return data;\n  }\n\n  async getTransaction(transactionId: string, requestOptions?: RequestOptions): Promise<Transaction> {\n    const data = await this.requestWithRetry<Transaction>(`/api/v1/tm/transactions/status/${transactionId}`, {\n      method: 'GET',\n    }, undefined, undefined, requestOptions);\n    return data;\n  }\n}\n","import { verifyWebhookSignature, ValidationError } from '@vesant-sdk/core';\nimport type {\n  TransactionCallbackEvent,\n  TransactionHeldEvent,\n  TransactionWebhookEvent,\n} from './types';\n\ntype EventHandler<T> = (event: T) => void | Promise<void>;\n\ntype HandlerMap = {\n  'tm.transaction.callback': Array<EventHandler<TransactionCallbackEvent>>;\n  'tm.transaction.held': Array<EventHandler<TransactionHeldEvent>>;\n};\n\nexport interface TransactionWebhookHandlerConfig {\n  secret: string;\n  /** Reject duplicate event_type+tx_id pairs within replayWindow. Default: true. */\n  replayProtection?: boolean;\n  /** How long (ms) to remember seen events for replay detection. Default: 300_000 (5 min). */\n  replayWindow?: number;\n}\n\nexport class TransactionWebhookHandler {\n  private readonly handlers: HandlerMap = {\n    'tm.transaction.callback': [],\n    'tm.transaction.held': [],\n  };\n  private readonly secret: string;\n  private readonly replayProtection: boolean;\n  private readonly replayWindow: number;\n  private seenEvents = new Map<string, number>();\n\n  constructor(config: TransactionWebhookHandlerConfig) {\n    this.secret = config.secret;\n    this.replayProtection = config.replayProtection ?? true;\n    this.replayWindow = config.replayWindow ?? 300_000;\n  }\n\n  on(eventType: 'tm.transaction.callback', handler: EventHandler<TransactionCallbackEvent>): this;\n  on(eventType: 'tm.transaction.held', handler: EventHandler<TransactionHeldEvent>): this;\n  on(eventType: keyof HandlerMap, handler: EventHandler<TransactionCallbackEvent> | EventHandler<TransactionHeldEvent>): this {\n    (this.handlers[eventType] as Array<typeof handler>).push(handler);\n    return this;\n  }\n\n  /** Verify HMAC-SHA256 signature only. Returns false instead of throwing. */\n  async verify(rawBody: string, signature: string): Promise<boolean> {\n    return verifyWebhookSignature(rawBody, signature, this.secret);\n  }\n\n  /** Parse and validate required fields. Does not verify signature — use verifyAndParse in production. */\n  parse(body: string): TransactionWebhookEvent {\n    const event = JSON.parse(body) as TransactionWebhookEvent;\n    if (!event.event_type || !event.tx_id) {\n      throw new ValidationError(\n        'Invalid TM webhook event: missing required fields (event_type, tx_id)',\n        ['event_type', 'tx_id']\n      );\n    }\n    return event;\n  }\n\n  /** Verify signature, parse, and check for replays. Throws ValidationError on any failure. */\n  async verifyAndParse(body: string, signature: string): Promise<TransactionWebhookEvent> {\n    const isValid = await verifyWebhookSignature(body, signature, this.secret);\n    if (!isValid) {\n      throw new ValidationError('Invalid webhook signature', ['signature']);\n    }\n\n    const event = this.parse(body);\n\n    if (this.replayProtection) {\n      const key = `${event.event_type}:${event.tx_id}`;\n      if (this.seenEvents.has(key)) {\n        throw new ValidationError(\n          `Duplicate webhook event: ${event.event_type} for ${event.tx_id} has already been processed`,\n          ['tx_id']\n        );\n      }\n      const now = Date.now();\n      this.seenEvents.set(key, now);\n      if (this.seenEvents.size > 1000) {\n        for (const [k, seenAt] of this.seenEvents) {\n          if (now - seenAt > this.replayWindow) {\n            this.seenEvents.delete(k);\n          }\n        }\n      }\n    }\n\n    return event;\n  }\n\n  /** Verify signature, parse, and dispatch to registered handlers. */\n  async handle(body: string, signature: string): Promise<void> {\n    const event = await this.verifyAndParse(body, signature);\n    const handlers = this.handlers[event.event_type] as Array<EventHandler<typeof event>>;\n    for (const handler of handlers) {\n      await handler(event);\n    }\n  }\n}\n"]}
+{"version":3,"sources":["../src/errors.ts","../src/pending-withdrawal.ts","../src/client.ts","../src/webhook-handler.ts"],"names":["VesantError"],"mappings":"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","file":"index.mjs","sourcesContent":["import { VesantError } from '@vesant-sdk/core';\nimport type { TransactionCallbackEvent, HoldReason } from './types';\n\nexport class DuplicateTransactionError extends VesantError {\n  readonly tx_id: string;\n\n  constructor(tx_id: string, message = `Duplicate transaction: ${tx_id} already exists`) {\n    super(message, 'DUPLICATE_TRANSACTION', 409);\n    this.name = 'DuplicateTransactionError';\n    this.tx_id = tx_id;\n    Object.setPrototypeOf(this, DuplicateTransactionError.prototype);\n  }\n}\n\nexport class TaxHoldError extends Error {\n  readonly tx_id: string;\n  readonly hold_reason: HoldReason;\n  readonly event: TransactionCallbackEvent;\n\n  constructor(event: TransactionCallbackEvent) {\n    super(`Transaction ${event.tx_id} held: ${event.hold_reason}`);\n    this.name = 'TaxHoldError';\n    this.tx_id = event.tx_id;\n    this.hold_reason = event.hold_reason as HoldReason;\n    this.event = event;\n    Object.setPrototypeOf(this, TaxHoldError.prototype);\n  }\n}\n","import { VesantError } from '@vesant-sdk/core';\nimport { TaxHoldError } from './errors';\nimport type { Transaction, TransactionCallbackEvent } from './types';\n\nexport type WithdrawalState = 'vesant_pending' | 'withheld' | 'suspend' | 'released' | 'failed';\n\nexport class PendingWithdrawal {\n  private _state: WithdrawalState = 'vesant_pending';\n  private _event: TransactionCallbackEvent | null = null;\n  private _error: unknown = undefined;\n\n  // Deferred promise — created lazily only when wait() is called.\n  private _waitPromise: Promise<TransactionCallbackEvent> | null = null;\n  private _resolveWait?: (event: TransactionCallbackEvent) => void;\n  private _rejectWait?: (err: unknown) => void;\n\n  readonly tx_id: string;\n  readonly initialTransaction: Transaction;\n\n  constructor(tx_id: string, transaction: Transaction) {\n    this.tx_id = tx_id;\n    this.initialTransaction = transaction;\n  }\n\n  status(): WithdrawalState {\n    return this._state;\n  }\n\n  callbackEvent(): TransactionCallbackEvent | null {\n    return this._event;\n  }\n\n  wait(signal?: AbortSignal): Promise<TransactionCallbackEvent> {\n    if (this._state !== 'vesant_pending') {\n      if (this._state === 'suspend' || this._state === 'failed') {\n        return Promise.reject(this._error);\n      }\n      if (this._event !== null) {\n        return Promise.resolve(this._event);\n      }\n    }\n\n    if (!this._waitPromise) {\n      this._waitPromise = new Promise<TransactionCallbackEvent>((resolve, reject) => {\n        this._resolveWait = resolve;\n        this._rejectWait = reject;\n      });\n    }\n\n    if (signal) {\n      if (signal.aborted) {\n        this._fail(new VesantError('Request aborted', 'REQUEST_ABORTED'));\n      } else {\n        signal.addEventListener('abort', () => {\n          this._fail(new VesantError('Request aborted', 'REQUEST_ABORTED'));\n        }, { once: true });\n      }\n    }\n\n    return this._waitPromise;\n  }\n\n  /** Called by TransactionWebhookHandler when the tm.transaction.callback arrives for this tx_id. */\n  _settle(event: TransactionCallbackEvent): void {\n    if (this._state !== 'vesant_pending') return;\n    this._event = event;\n    if (event.status === 'hold' || event.status === 'suspend') {\n      this._state = 'suspend';\n      this._error = new TaxHoldError(event);\n      this._rejectWait?.(this._error);\n    } else if (event.withholding_type === 'none') {\n      this._state = 'released';\n      this._resolveWait?.(event);\n    } else {\n      this._state = 'withheld';\n      this._resolveWait?.(event);\n    }\n  }\n\n  /** Called to fail the pending withdrawal with a generic error (e.g. abort, network loss). */\n  _fail(err: unknown): void {\n    if (this._state !== 'vesant_pending') return;\n    this._state = 'failed';\n    this._error = err;\n    this._rejectWait?.(err);\n  }\n}\n","/**\n * TransactionClient — SDK for the Transaction Monitoring service\n */\nimport { BaseClient, VesantError } from '@vesant-sdk/core';\nimport type { BaseClientConfig, RequestOptions } from '@vesant-sdk/core';\nimport type { Transaction, TransactionCreateDTO, TransactionCreateResponse, TmTenantSettings } from './types';\nimport { PendingWithdrawal } from './pending-withdrawal';\n\nexport class TransactionClient extends BaseClient {\n  constructor(config: BaseClientConfig) {\n    super(config);\n  }\n\n  async createTransaction(\n    request: TransactionCreateDTO,\n    requestOptions?: RequestOptions\n  ): Promise<TransactionCreateResponse> {\n    try {\n      return await this.requestWithRetry<TransactionCreateResponse>('/api/v1/tm/transactions', {\n        method: 'POST',\n        body: JSON.stringify(request),\n      }, undefined, undefined, requestOptions);\n    } catch (error) {\n      if (error instanceof VesantError && error.statusCode === 409) {\n        const transaction = await this.getTransaction(request.tx_id, requestOptions);\n        return { transaction, message: 'Transaction already exists' };\n      }\n      throw error;\n    }\n  }\n\n  async submitWithdrawal(\n    request: TransactionCreateDTO,\n    requestOptions?: RequestOptions\n  ): Promise<PendingWithdrawal> {\n    const response = await this.createTransaction(\n      { ...request, transaction_type: 'withdrawal' },\n      requestOptions\n    );\n    return new PendingWithdrawal(response.transaction.tx_id, response.transaction);\n  }\n\n  async getTransaction(transactionId: string, requestOptions?: RequestOptions): Promise<Transaction> {\n    return this.requestWithRetry<Transaction>(`/api/v1/tm/transactions/status/${transactionId}`, {\n      method: 'GET',\n    }, undefined, undefined, requestOptions);\n  }\n\n  async getSettings(): Promise<TmTenantSettings> {\n    return this.requestWithRetry<TmTenantSettings>('/api/v1/tm/settings', {\n      method: 'GET',\n    });\n  }\n}\n","import { verifyWebhookSignature, ValidationError } from '@vesant-sdk/core';\nimport { PendingWithdrawal } from './pending-withdrawal';\nimport type {\n  TransactionCallbackEvent,\n  TransactionCallbackHandler,\n  TransactionHeldEvent,\n  TransactionWebhookEvent,\n} from './types';\n\ntype EventHandler<T> = (event: T) => void | Promise<void>;\n\ntype HandlerMap = {\n  'tm.transaction.callback': Array<EventHandler<TransactionCallbackEvent>>;\n  'tm.transaction.held': Array<EventHandler<TransactionHeldEvent>>;\n};\n\nexport const TRANSACTION_SIGNATURE_HEADER = 'x-webhook-signature';\n\nexport interface TransactionWebhookHandlerConfig {\n  secret: string;\n  /** Reject duplicate event_type+tx_id pairs within replayWindow. Default: true. */\n  replayProtection?: boolean;\n  /** How long (ms) to remember seen events for replay detection. Default: 300_000 (5 min). */\n  replayWindow?: number;\n}\n\nexport class TransactionWebhookHandler {\n  private readonly handlers: HandlerMap = {\n    'tm.transaction.callback': [],\n    'tm.transaction.held': [],\n  };\n  private readonly secret: string;\n  private readonly replayProtection: boolean;\n  private readonly replayWindow: number;\n  private readonly seenEvents = new Map<string, number>();\n  private readonly pendingWithdrawals = new Map<string, PendingWithdrawal>();\n  private callbackHandler: TransactionCallbackHandler | null = null;\n\n  constructor(config: TransactionWebhookHandlerConfig) {\n    this.secret = config.secret;\n    this.replayProtection = config.replayProtection ?? true;\n    this.replayWindow = config.replayWindow ?? 300_000;\n  }\n\n  on(eventType: 'tm.transaction.callback', handler: EventHandler<TransactionCallbackEvent>): this;\n  on(eventType: 'tm.transaction.held', handler: EventHandler<TransactionHeldEvent>): this;\n  on(eventType: keyof HandlerMap, handler: EventHandler<TransactionCallbackEvent> | EventHandler<TransactionHeldEvent>): this {\n    (this.handlers[eventType] as Array<typeof handler>).push(handler);\n    return this;\n  }\n\n  /** Register a semantic callback handler for the three withholding outcomes. Replaces any previous handler. */\n  registerCallbackHandler(handler: TransactionCallbackHandler): this {\n    this.callbackHandler = handler;\n    return this;\n  }\n\n  /** Track a PendingWithdrawal so it is auto-settled when its tm.transaction.callback arrives. */\n  link(pending: PendingWithdrawal): this {\n    this.pendingWithdrawals.set(pending.tx_id, pending);\n    return this;\n  }\n\n  /** Stop tracking a PendingWithdrawal by tx_id. */\n  unlink(tx_id: string): this {\n    this.pendingWithdrawals.delete(tx_id);\n    return this;\n  }\n\n  /** Verify HMAC-SHA256 signature only. Returns false instead of throwing. */\n  async verify(rawBody: string, signature: string): Promise<boolean> {\n    return verifyWebhookSignature(rawBody, signature, this.secret);\n  }\n\n  /** Parse and validate required fields. Does not verify signature — use verifyAndParse in production. */\n  parse(body: string): TransactionWebhookEvent {\n    const event = JSON.parse(body) as TransactionWebhookEvent;\n    if (!event.event_type || !event.tx_id) {\n      throw new ValidationError(\n        'Invalid TM webhook event: missing required fields (event_type, tx_id)',\n        ['event_type', 'tx_id']\n      );\n    }\n    return event;\n  }\n\n  /** Verify signature, parse, and check for replays. Throws ValidationError on any failure. */\n  async verifyAndParse(body: string, signature: string): Promise<TransactionWebhookEvent> {\n    const isValid = await verifyWebhookSignature(body, signature, this.secret);\n    if (!isValid) {\n      throw new ValidationError('Invalid webhook signature', ['signature']);\n    }\n\n    const event = this.parse(body);\n\n    if (this.replayProtection) {\n      const key = `${event.event_type}:${event.tx_id}`;\n      if (this.seenEvents.has(key)) {\n        throw new ValidationError(\n          `Duplicate webhook event: ${event.event_type} for ${event.tx_id} has already been processed`,\n          ['tx_id']\n        );\n      }\n      const now = Date.now();\n      this.seenEvents.set(key, now);\n      if (this.seenEvents.size > 1000) {\n        for (const [k, seenAt] of this.seenEvents) {\n          if (now - seenAt > this.replayWindow) {\n            this.seenEvents.delete(k);\n          }\n        }\n      }\n    }\n\n    return event;\n  }\n\n  /** Verify signature, parse, and dispatch to registered handlers. */\n  async handle(body: string, signature: string): Promise<void> {\n    const event = await this.verifyAndParse(body, signature);\n\n    if (event.event_type === 'tm.transaction.callback') {\n      const pending = this.pendingWithdrawals.get(event.tx_id);\n      if (pending) {\n        pending._settle(event);\n        this.pendingWithdrawals.delete(event.tx_id);\n      }\n\n      if (this.callbackHandler) {\n        if (event.status === 'hold' || event.status === 'suspend') {\n          await this.callbackHandler.onHeld?.(event);\n        } else if (event.withholding_type === 'none') {\n          await this.callbackHandler.onReleased?.(event);\n        } else {\n          await this.callbackHandler.onWithheld?.(event);\n        }\n      }\n    }\n\n    const handlers = this.handlers[event.event_type] as Array<EventHandler<typeof event>>;\n    for (const handler of handlers) {\n      await handler(event);\n    }\n  }\n}\n"]}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vesant-sdk/transaction",
-  "version": "0.1.1-dev.9b89b96",
+  "version": "0.1.1-dev.ab7ff29",
   "description": "Transaction monitoring client for the Vesant Compliance Platform",
   "main": "./dist/index.js",
   "module": "./dist/index.mjs",