npm - @vesant-sdk/transaction - Versions diffs - 0.1.0 → 0.1.1-dev.059da4f - Mend

@vesant-sdk/transaction 0.1.0 → 0.1.1-dev.059da4f

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

package/dist/index.d.mts CHANGED Viewed

@@ -1,32 +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";
-type TransactionMode = "fiat" | "crypto" | "bank_transfer" | "card" | "wallet";
-type TransactionStatus = "pending" | "processing" | "completed" | "failed" | "cancelled" | "reversed";
+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;
-    status: TransactionStatus;
-    source_account: string;
-    destination_account: string;
-    country: string;
-    ip_address: string;
-    metadata: Record<string, any>;
-    benificiary_comment: string;
-    transaction_date: Timestamp;
+    source_account?: string;
+    destination_account?: string;
+    country?: string;
+    ip_address?: string;
+    benificiary_comment?: string;
+    metadata?: Record<string, unknown>;
+    transaction_date: string;
 }
 type WithholdingType = "none" | "backup_us" | "backup_non_us" | "treaty";
-type JSONB = Record<string, any>;
+/** 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 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 Transaction = {
     id: string;
     tx_id: string;
@@ -35,12 +41,23 @@ 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: string;
     withholding_reason?: string;
-    withholding_type?: WithholdingType;
+    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.
+     * Not persisted — getTransaction() always returns false regardless of actual history.
+     */
+    is_first_withdrawal?: boolean;
     tax_year: number;
     currency: string;
     status: TransactionStatus;
@@ -49,7 +66,7 @@ type Transaction = {
     country?: string;
     ip_address?: string;
     risk_score: number;
-    metadata?: JSONB;
+    metadata?: Record<string, unknown>;
     benificiary_comment?: string;
     transaction_date: string;
     created_at: string;
@@ -66,10 +83,99 @@ interface TransactionClientConfig {
     debug?: boolean;
     environment?: 'production' | 'sandbox';
 }
+/**
+ * Response from POST /api/v1/tm/transactions.
+ *
+ * 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 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: string;
+    transaction_mode: string;
+    status: string;
+    amount: string;
+    currency: string;
+    withheld_amount: string;
+    released_amount: string;
+    withholding_rate: number;
+    withholding_type: string;
+    withholding_reason?: string | null;
+    hold_reason?: string | null;
+    amount_usd: number;
+    withheld_usd: number;
+    released_usd: number;
+    is_first_withdrawal: boolean;
+    transaction_date: string;
+}
+/**
+ * Fired when a withdrawal is blocked due to missing or unverified W-9/TIN
+ * (status = "suspend" or "hold").
+ * Use this to notify the customer that TIN verification or W-9 submission is required.
+ */
+interface TransactionHeldEvent {
+    event_type: "tm.transaction.held";
+    tx_id: string;
+    customer_id: string;
+    customer_email: string;
+    customer_name: string;
+    /** Reflects the tenant's configured transaction action that was applied. */
+    action: "suspend" | "hold";
+    hold_reason: HoldReason;
+}
+/** 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
@@ -78,7 +184,56 @@ type TransactionCreateResponse = {
 declare class TransactionClient extends BaseClient {
     constructor(config: BaseClientConfig);
     createTransaction(request: TransactionCreateDTO, requestOptions?: RequestOptions): Promise<TransactionCreateResponse>;
-    getTransaction(transactionId: string, requestOptions?: RequestOptions): Promise<void>;
+    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;
+}
+declare class TransactionWebhookHandler {
+    private readonly handlers;
+    private readonly secret;
+    private readonly replayProtection;
+    private readonly replayWindow;
+    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. */
+    parse(body: string): TransactionWebhookEvent;
+    /** Verify signature, parse, and check for replays. Throws ValidationError on any failure. */
+    verifyAndParse(body: string, signature: string): Promise<TransactionWebhookEvent>;
+    /** Verify signature, parse, and dispatch to registered handlers. */
+    handle(body: string, signature: string): Promise<void>;
 }
-export { type JSONB, type Transaction, TransactionClient, type TransactionClientConfig, type TransactionCreateDTO, type TransactionCreateResponse, type TransactionMode, type TransactionStatus, type TransactionType, 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 CHANGED Viewed

@@ -1,32 +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";
-type TransactionMode = "fiat" | "crypto" | "bank_transfer" | "card" | "wallet";
-type TransactionStatus = "pending" | "processing" | "completed" | "failed" | "cancelled" | "reversed";
+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;
-    status: TransactionStatus;
-    source_account: string;
-    destination_account: string;
-    country: string;
-    ip_address: string;
-    metadata: Record<string, any>;
-    benificiary_comment: string;
-    transaction_date: Timestamp;
+    source_account?: string;
+    destination_account?: string;
+    country?: string;
+    ip_address?: string;
+    benificiary_comment?: string;
+    metadata?: Record<string, unknown>;
+    transaction_date: string;
 }
 type WithholdingType = "none" | "backup_us" | "backup_non_us" | "treaty";
-type JSONB = Record<string, any>;
+/** 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 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 Transaction = {
     id: string;
     tx_id: string;
@@ -35,12 +41,23 @@ 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: string;
     withholding_reason?: string;
-    withholding_type?: WithholdingType;
+    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.
+     * Not persisted — getTransaction() always returns false regardless of actual history.
+     */
+    is_first_withdrawal?: boolean;
     tax_year: number;
     currency: string;
     status: TransactionStatus;
@@ -49,7 +66,7 @@ type Transaction = {
     country?: string;
     ip_address?: string;
     risk_score: number;
-    metadata?: JSONB;
+    metadata?: Record<string, unknown>;
     benificiary_comment?: string;
     transaction_date: string;
     created_at: string;
@@ -66,10 +83,99 @@ interface TransactionClientConfig {
     debug?: boolean;
     environment?: 'production' | 'sandbox';
 }
+/**
+ * Response from POST /api/v1/tm/transactions.
+ *
+ * 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 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: string;
+    transaction_mode: string;
+    status: string;
+    amount: string;
+    currency: string;
+    withheld_amount: string;
+    released_amount: string;
+    withholding_rate: number;
+    withholding_type: string;
+    withholding_reason?: string | null;
+    hold_reason?: string | null;
+    amount_usd: number;
+    withheld_usd: number;
+    released_usd: number;
+    is_first_withdrawal: boolean;
+    transaction_date: string;
+}
+/**
+ * Fired when a withdrawal is blocked due to missing or unverified W-9/TIN
+ * (status = "suspend" or "hold").
+ * Use this to notify the customer that TIN verification or W-9 submission is required.
+ */
+interface TransactionHeldEvent {
+    event_type: "tm.transaction.held";
+    tx_id: string;
+    customer_id: string;
+    customer_email: string;
+    customer_name: string;
+    /** Reflects the tenant's configured transaction action that was applied. */
+    action: "suspend" | "hold";
+    hold_reason: HoldReason;
+}
+/** 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
@@ -78,7 +184,56 @@ type TransactionCreateResponse = {
 declare class TransactionClient extends BaseClient {
     constructor(config: BaseClientConfig);
     createTransaction(request: TransactionCreateDTO, requestOptions?: RequestOptions): Promise<TransactionCreateResponse>;
-    getTransaction(transactionId: string, requestOptions?: RequestOptions): Promise<void>;
+    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;
+}
+declare class TransactionWebhookHandler {
+    private readonly handlers;
+    private readonly secret;
+    private readonly replayProtection;
+    private readonly replayWindow;
+    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. */
+    parse(body: string): TransactionWebhookEvent;
+    /** Verify signature, parse, and check for replays. Throws ValidationError on any failure. */
+    verifyAndParse(body: string, signature: string): Promise<TransactionWebhookEvent>;
+    /** Verify signature, parse, and dispatch to registered handlers. */
+    handle(body: string, signature: string): Promise<void>;
 }
-export { type JSONB, type Transaction, TransactionClient, type TransactionClientConfig, type TransactionCreateDTO, type TransactionCreateResponse, type TransactionMode, type TransactionStatus, type TransactionType, 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 CHANGED Viewed

@@ -2,25 +2,237 @@
 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) {
-    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);
   }
+  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 = {
+      "tm.transaction.callback": [],
+      "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;
+  }
+  on(eventType, handler) {
+    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);
+  }
+  /** Parse and validate required fields. Does not verify signature — use verifyAndParse in production. */
+  parse(body) {
+    const event = JSON.parse(body);
+    if (!event.event_type || !event.tx_id) {
+      throw new core.ValidationError(
+        "Invalid TM webhook event: missing required fields (event_type, tx_id)",
+        ["event_type", "tx_id"]
+      );
+    }
+    return event;
+  }
+  /** Verify signature, parse, and check for replays. Throws ValidationError on any failure. */
+  async verifyAndParse(body, signature) {
+    const isValid = await core.verifyWebhookSignature(body, signature, this.secret);
+    if (!isValid) {
+      throw new core.ValidationError("Invalid webhook signature", ["signature"]);
+    }
+    const event = this.parse(body);
+    if (this.replayProtection) {
+      const key = `${event.event_type}:${event.tx_id}`;
+      if (this.seenEvents.has(key)) {
+        throw new core.ValidationError(
+          `Duplicate webhook event: ${event.event_type} for ${event.tx_id} has already been processed`,
+          ["tx_id"]
+        );
+      }
+      const now = Date.now();
+      this.seenEvents.set(key, now);
+      if (this.seenEvents.size > 1e3) {
+        for (const [k, seenAt] of this.seenEvents) {
+          if (now - seenAt > this.replayWindow) {
+            this.seenEvents.delete(k);
+          }
+        }
+      }
+    }
+    return event;
+  }
+  /** 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);
+    }
+  }
 };
+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
 //# sourceMappingURL=index.js.map

package/dist/index.js.map CHANGED Viewed

	@@ -1 +1 @@
1	- {"version":3,"sources":["../src/client.ts"],"names":["BaseClient"],"mappings":";;;;;AAQO,IAAM,iBAAA,GAAN,cAAgCA,eAAA,CAAW;AAAA,EAChD,YAAY,MAAA,EAA0B;AACpC,IAAA,KAAA,CAAM,MAAM,CAAA;AAAA,EACd;AAAA,EAEA,MAAM,iBAAA,CACJ,OAAA,EACA,cAAA,EACoC;AACpC,IAAA,MAAM,IAAA,GAAO,MAAM,IAAA,CAAK,gBAAA,CAA4C,yBAAA,EAA2B;AAAA,MAC7F,MAAA,EAAQ,MAAA;AAAA,MACR,IAAA,EAAM,IAAA,CAAK,SAAA,CAAU,OAAO;AAAA,KAC9B,EAAG,MAAA,EAAW,MAAA,EAAW,cAAc,CAAA;AACvC,IAAA,OAAO,IAAA;AAAA,EACT;AAAA,EAEA,MAAM,cAAA,CAAe,aAAA,EAAuB,cAAA,EAAgD;AAC1F,IAAA,MAAM,IAAA,CAAK,gBAAA,CAAuB,CAAA,+BAAA,EAAkC,aAAa,CAAA,CAAA,EAAI;AAAA,MACnF,MAAA,EAAQ;AAAA,KACV,EAAG,MAAA,EAAW,MAAA,EAAW,cAAc,CAAA;AAAA,EACzC;AACF","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 { 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<void> {\n await this.requestWithRetry<void>(`/api/v1/tm/transactions/status/${transactionId}`, {\n method: 'GET',\n }, undefined, undefined, requestOptions);\n }\n}\n"]}
1	+ {"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 CHANGED Viewed

@@ -1,4 +1,92 @@
-import { BaseClient } 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,138 @@ 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) {
-    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);
   }
+  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 = {
+      "tm.transaction.callback": [],
+      "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;
+  }
+  on(eventType, handler) {
+    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);
+  }
+  /** Parse and validate required fields. Does not verify signature — use verifyAndParse in production. */
+  parse(body) {
+    const event = JSON.parse(body);
+    if (!event.event_type || !event.tx_id) {
+      throw new ValidationError(
+        "Invalid TM webhook event: missing required fields (event_type, tx_id)",
+        ["event_type", "tx_id"]
+      );
+    }
+    return event;
+  }
+  /** Verify signature, parse, and check for replays. Throws ValidationError on any failure. */
+  async verifyAndParse(body, signature) {
+    const isValid = await verifyWebhookSignature(body, signature, this.secret);
+    if (!isValid) {
+      throw new ValidationError("Invalid webhook signature", ["signature"]);
+    }
+    const event = this.parse(body);
+    if (this.replayProtection) {
+      const key = `${event.event_type}:${event.tx_id}`;
+      if (this.seenEvents.has(key)) {
+        throw new ValidationError(
+          `Duplicate webhook event: ${event.event_type} for ${event.tx_id} has already been processed`,
+          ["tx_id"]
+        );
+      }
+      const now = Date.now();
+      this.seenEvents.set(key, now);
+      if (this.seenEvents.size > 1e3) {
+        for (const [k, seenAt] of this.seenEvents) {
+          if (now - seenAt > this.replayWindow) {
+            this.seenEvents.delete(k);
+          }
+        }
+      }
+    }
+    return event;
+  }
+  /** 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);
+    }
+  }
 };
-export { TransactionClient };
+export { DuplicateTransactionError, PendingWithdrawal, TRANSACTION_SIGNATURE_HEADER, TaxHoldError, TransactionClient, TransactionWebhookHandler };
 //# sourceMappingURL=index.mjs.map
 //# sourceMappingURL=index.mjs.map

package/dist/index.mjs.map CHANGED Viewed

	@@ -1 +1 @@
1	- {"version":3,"sources":["../src/client.ts"],"names":[],"mappings":";;;AAQO,IAAM,iBAAA,GAAN,cAAgC,UAAA,CAAW;AAAA,EAChD,YAAY,MAAA,EAA0B;AACpC,IAAA,KAAA,CAAM,MAAM,CAAA;AAAA,EACd;AAAA,EAEA,MAAM,iBAAA,CACJ,OAAA,EACA,cAAA,EACoC;AACpC,IAAA,MAAM,IAAA,GAAO,MAAM,IAAA,CAAK,gBAAA,CAA4C,yBAAA,EAA2B;AAAA,MAC7F,MAAA,EAAQ,MAAA;AAAA,MACR,IAAA,EAAM,IAAA,CAAK,SAAA,CAAU,OAAO;AAAA,KAC9B,EAAG,MAAA,EAAW,MAAA,EAAW,cAAc,CAAA;AACvC,IAAA,OAAO,IAAA;AAAA,EACT;AAAA,EAEA,MAAM,cAAA,CAAe,aAAA,EAAuB,cAAA,EAAgD;AAC1F,IAAA,MAAM,IAAA,CAAK,gBAAA,CAAuB,CAAA,+BAAA,EAAkC,aAAa,CAAA,CAAA,EAAI;AAAA,MACnF,MAAA,EAAQ;AAAA,KACV,EAAG,MAAA,EAAW,MAAA,EAAW,cAAc,CAAA;AAAA,EACzC;AACF","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 { 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<void> {\n await this.requestWithRetry<void>(`/api/v1/tm/transactions/status/${transactionId}`, {\n method: 'GET',\n }, undefined, undefined, requestOptions);\n }\n}\n"]}
1	+ {"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 CHANGED Viewed

@@ -1,6 +1,6 @@
 {
   "name": "@vesant-sdk/transaction",
-  "version": "0.1.0",
+  "version": "0.1.1-dev.059da4f",
   "description": "Transaction monitoring client for the Vesant Compliance Platform",
   "main": "./dist/index.js",
   "module": "./dist/index.mjs",
@@ -12,7 +12,9 @@
       "require": "./dist/index.js"
     }
   },
-  "files": ["dist"],
+  "files": [
+    "dist"
+  ],
   "scripts": {
     "build": "tsup",
     "dev": "tsup --watch",
@@ -21,7 +23,12 @@
     "type-check": "tsc --noEmit",
     "lint": "eslint src --ext .ts"
   },
-  "keywords": ["vesant", "compliance", "transaction", "transaction-monitoring"],
+  "keywords": [
+    "vesant",
+    "compliance",
+    "transaction",
+    "transaction-monitoring"
+  ],
   "author": "Vesant Compliance",
   "license": "MIT",
   "dependencies": {