vesant-sdk 1.6.0 → 1.6.2

package/dist/tax/index.d.mts

@@ -0,0 +1,255 @@
+import { B as BaseClient, R as RequestOptions } from '../client-ePzhQKp9.mjs';
+
+/**
+ * TypeScript type definitions for Vesant Tax Service API
+ *
+ * Types mirror the Go domain structs in:
+ * - services/transaction-monitoring-service/internal/domain/
+ * - services/transaction-monitoring-service/internal/handler/
+ */
+type CustomerType = 'US_PERSON' | 'NON_US_PERSON' | 'NON_US_ENTITY';
+/**
+ * Form status values stored on the customer_tax_profiles.form_status column.
+ * Matches Go constants CTPFormStatus*.
+ */
+type CTPFormStatus = 'requested' | 'signed' | 'manual' | 'bounced' | 'uploaded' | 'expired' | 're_requested';
+/**
+ * TIN status values stored on the customer_tax_profiles.tin_status column.
+ * Matches Go constants CTPTINStatus*.
+ */
+type CTPTINStatus = 'not_required' | 'pending' | 'submitted' | 'verified' | 'rejected' | 'error' | 'expired';
+/**
+ * CustomerTaxProfileRecord is the per-customer row from customer_tax_profiles.
+ * Returned by GET /api/v1/tax/customer-tax-profiles/{customer_id}
+ */
+interface CustomerTaxProfileRecord {
+    id: string;
+    tenant_id: string;
+    customer_id: string;
+    customer_type: CustomerType;
+    form_type: string;
+    form_status: CTPFormStatus;
+    tin_status: CTPTINStatus;
+    tin_value?: string;
+    recipient_name?: string;
+    business_name?: string;
+    account_number?: string;
+    address?: string;
+    address_city?: string;
+    address_state?: string;
+    address_zip?: string;
+    address_country?: string;
+    customer_name?: string;
+    avalara_form_id?: string;
+    avalara_company_id?: string;
+    signed_at?: string;
+    verified_at?: string;
+    /** ISO date — W-8BEN / W-8BEN-E expires 3 years from signed_at */
+    expiry_date?: string;
+    backup_withholding: boolean;
+    b_notice_received: boolean;
+    e_delivery_consent: boolean;
+    withholding_enabled_by?: string;
+    withholding_enabled_at?: string;
+    tin_due_date?: string;
+    last_tin_check?: string;
+    request_count: number;
+    reminders_sent: number;
+    last_reminder_at?: string;
+    created_at: string;
+    updated_at: string;
+}
+/**
+ * Input for POST /api/v1/tax/customer-tax-profiles/{id}/re-request-form
+ */
+interface ReRequestTaxFormInput {
+    /** Customer email address — required */
+    email: string;
+    /** Customer full name — optional */
+    name?: string;
+}
+/**
+ * Input for POST /api/v1/tax/customer-tax-profiles/{id}/enable-withholding
+ */
+interface EnableWithholdingInput {
+    /** Admin user ID performing the action — required */
+    admin_user_id: string;
+}
+/** Response body from POST .../enable-withholding */
+interface EnableWithholdingResponse {
+    message: string;
+}
+/**
+ * Result returned by POST /api/v1/tax/customer-tax-profiles/{id}/check-tin
+ */
+interface TINCheckResult {
+    tin_result: Record<string, unknown>;
+    profile: CustomerTaxProfileRecord;
+}
+type TransactionAction = 'hold' | 'suspend' | 'release_with_withholding';
+type EmailSendingMethod = 'tenant_email' | 'avalara_direct';
+/**
+ * TaxRules is returned by GET /api/v1/tax/rules.
+ * It extends TenantTaxRules with the platform-wide withdrawal_threshold
+ * from the active VesantGlobalTaxRule for the current year.
+ */
+interface TaxRules {
+    id: string;
+    tenant_id: string;
+    /** Platform-wide IRS withdrawal threshold (from VesantGlobalTaxRule). May be absent if not yet configured. */
+    withdrawal_threshold?: number;
+    trigger_account_creation: boolean;
+    trigger_first_withdrawal: boolean;
+    trigger_threshold: boolean;
+    trigger_manual: boolean;
+    trigger_tin_invalid: boolean;
+    trigger_w8ben_expiry: boolean;
+    trigger_tin_expired: boolean;
+    us_withholding_enabled: boolean;
+    us_withholding_rate: number;
+    non_us_withholding_enabled: boolean;
+    non_us_withholding_rate: number;
+    transaction_action: TransactionAction;
+    reminder_frequency_days: number;
+    reminder_max_count: number;
+    w8ben_expiry_warning_days: number;
+    tin_verification_due_date?: string;
+    email_sending_method: EmailSendingMethod;
+    display_tin_links_on_platform: boolean;
+    tax_treaty_support: boolean;
+    created_at: string;
+    updated_at: string;
+}
+/**
+ * Input for PUT /api/v1/tax/rules.
+ * Mirrors domain.UpdateRulesInput — withholding rates are NOT tenant-configurable.
+ */
+interface UpdateTaxRulesInput {
+    trigger_account_creation: boolean;
+    trigger_first_withdrawal: boolean;
+    trigger_threshold: boolean;
+    trigger_manual: boolean;
+    trigger_tin_invalid: boolean;
+    trigger_w8ben_expiry: boolean;
+    trigger_tin_expired: boolean;
+    us_withholding_enabled: boolean;
+    non_us_withholding_enabled: boolean;
+    transaction_action: TransactionAction;
+    reminder_frequency_days: number;
+    reminder_max_count: number;
+    w8ben_expiry_warning_days: number;
+    tin_verification_due_date?: string;
+    email_sending_method: EmailSendingMethod;
+    display_tin_links_on_platform: boolean;
+    tax_treaty_support: boolean;
+}
+type TaxRuleApprovalStatus = 'pending' | 'approved' | 'rejected';
+interface TaxRuleVersion {
+    id: string;
+    tenant_id: string;
+    version_number: number;
+    proposed_rules: Record<string, unknown>;
+    changed_fields: Record<string, unknown>;
+    changed_by: string;
+    approved_by?: string;
+    approval_status: TaxRuleApprovalStatus;
+    approved_at?: string;
+    activated_at?: string;
+    created_at: string;
+}
+interface ComplianceStatsFilters {
+    /** Predefined range: "7d" | "30d" | "90d" | "1y" */
+    time_range?: string;
+    /** ISO date YYYY-MM-DD (inclusive) */
+    from_date?: string;
+    /** ISO date YYYY-MM-DD (inclusive) */
+    to_date?: string;
+}
+interface DocumentRequestBreakdown {
+    total: number;
+    w9: number;
+    w8ben: number;
+    w8bene: number;
+}
+interface TINStatusBreakdown {
+    verified: number;
+    pending: number;
+    rejected: number;
+}
+interface WFormStatusBreakdown {
+    w9: Record<string, number>;
+    w8ben: Record<string, number>;
+    w8bene: Record<string, number>;
+}
+interface WFormCountBreakdown {
+    w9: number;
+    w8ben: number;
+    w8bene: number;
+}
+interface ComplianceStats {
+    total_taxable_customers: number;
+    total_documents_requested: DocumentRequestBreakdown;
+    tin_verified_customers: number;
+    tin_verification_completion_rate: number;
+    document_completion_count: number;
+    document_completion_rate: number;
+    overdue_documents: number;
+    tin_verification_status: TINStatusBreakdown;
+    w_forms_by_status: WFormStatusBreakdown;
+    w_forms_status_totals: Record<string, number>;
+    w_forms_count: WFormCountBreakdown;
+}
+interface GlobalTaxRule {
+    id: string;
+    withdrawal_threshold: number;
+    default_us_withholding: number;
+    default_non_us_withholding: number;
+    tax_treaty_support: boolean;
+    tax_year: number;
+    configured_by: string;
+    is_active: boolean;
+    created_at: string;
+    updated_at: string;
+}
+interface TreatyCountry {
+    id: string;
+    country_code: string;
+    country_name: string;
+    withholding_rate: number;
+    is_active: boolean;
+    configured_by?: string;
+    created_at: string;
+    updated_at: string;
+}
+interface TreatyCountryListResponse {
+    treaty_countries: TreatyCountry[];
+    count: number;
+}
+interface TaxClientConfig {
+    /** Base URL of the Transaction Monitoring Service API (e.g., "http://localhost:8097") */
+    baseURL: string;
+    tenantId: string;
+    apiKey?: string;
+    headers?: Record<string, string>;
+    timeout?: number;
+    debug?: boolean;
+    environment?: 'production' | 'sandbox';
+}
+
+declare class TaxClient extends BaseClient {
+    constructor(config: TaxClientConfig);
+    getCustomerTaxProfileRecord(customerID: string): Promise<CustomerTaxProfileRecord>;
+    requestTaxForm(customerID: string): Promise<CustomerTaxProfileRecord>;
+    checkTINStatus(customerID: string): Promise<TINCheckResult>;
+    reRequestTaxForm(customerID: string, input: ReRequestTaxFormInput): Promise<CustomerTaxProfileRecord>;
+    enableBackupWithholding(customerID: string, input: EnableWithholdingInput): Promise<EnableWithholdingResponse>;
+    downloadTaxForm(customerID: string, requestOptions?: RequestOptions): Promise<ArrayBuffer>;
+    getTaxRules(): Promise<TaxRules>;
+    updateTaxRules(input: UpdateTaxRulesInput): Promise<TaxRuleVersion>;
+    getComplianceStats(filters?: ComplianceStatsFilters): Promise<ComplianceStats>;
+    getCurrentGlobalTaxRule(): Promise<GlobalTaxRule>;
+    listTreatyCountries(): Promise<TreatyCountryListResponse>;
+    getTreatyCountry(code: string): Promise<TreatyCountry>;
+}
+
+export { type CTPFormStatus, type CTPTINStatus, type ComplianceStats, type ComplianceStatsFilters, type CustomerTaxProfileRecord, type CustomerType, type DocumentRequestBreakdown, type EmailSendingMethod, type EnableWithholdingInput, type EnableWithholdingResponse, type GlobalTaxRule, type ReRequestTaxFormInput, type TINCheckResult, type TINStatusBreakdown, TaxClient, type TaxClientConfig, type TaxRuleApprovalStatus, type TaxRuleVersion, type TaxRules, type TransactionAction, type TreatyCountry, type TreatyCountryListResponse, type UpdateTaxRulesInput, type WFormCountBreakdown, type WFormStatusBreakdown };

package/dist/tax/index.d.ts

@@ -0,0 +1,255 @@
+import { B as BaseClient, R as RequestOptions } from '../client-ePzhQKp9.js';
+
+/**
+ * TypeScript type definitions for Vesant Tax Service API
+ *
+ * Types mirror the Go domain structs in:
+ * - services/transaction-monitoring-service/internal/domain/
+ * - services/transaction-monitoring-service/internal/handler/
+ */
+type CustomerType = 'US_PERSON' | 'NON_US_PERSON' | 'NON_US_ENTITY';
+/**
+ * Form status values stored on the customer_tax_profiles.form_status column.
+ * Matches Go constants CTPFormStatus*.
+ */
+type CTPFormStatus = 'requested' | 'signed' | 'manual' | 'bounced' | 'uploaded' | 'expired' | 're_requested';
+/**
+ * TIN status values stored on the customer_tax_profiles.tin_status column.
+ * Matches Go constants CTPTINStatus*.
+ */
+type CTPTINStatus = 'not_required' | 'pending' | 'submitted' | 'verified' | 'rejected' | 'error' | 'expired';
+/**
+ * CustomerTaxProfileRecord is the per-customer row from customer_tax_profiles.
+ * Returned by GET /api/v1/tax/customer-tax-profiles/{customer_id}
+ */
+interface CustomerTaxProfileRecord {
+    id: string;
+    tenant_id: string;
+    customer_id: string;
+    customer_type: CustomerType;
+    form_type: string;
+    form_status: CTPFormStatus;
+    tin_status: CTPTINStatus;
+    tin_value?: string;
+    recipient_name?: string;
+    business_name?: string;
+    account_number?: string;
+    address?: string;
+    address_city?: string;
+    address_state?: string;
+    address_zip?: string;
+    address_country?: string;
+    customer_name?: string;
+    avalara_form_id?: string;
+    avalara_company_id?: string;
+    signed_at?: string;
+    verified_at?: string;
+    /** ISO date — W-8BEN / W-8BEN-E expires 3 years from signed_at */
+    expiry_date?: string;
+    backup_withholding: boolean;
+    b_notice_received: boolean;
+    e_delivery_consent: boolean;
+    withholding_enabled_by?: string;
+    withholding_enabled_at?: string;
+    tin_due_date?: string;
+    last_tin_check?: string;
+    request_count: number;
+    reminders_sent: number;
+    last_reminder_at?: string;
+    created_at: string;
+    updated_at: string;
+}
+/**
+ * Input for POST /api/v1/tax/customer-tax-profiles/{id}/re-request-form
+ */
+interface ReRequestTaxFormInput {
+    /** Customer email address — required */
+    email: string;
+    /** Customer full name — optional */
+    name?: string;
+}
+/**
+ * Input for POST /api/v1/tax/customer-tax-profiles/{id}/enable-withholding
+ */
+interface EnableWithholdingInput {
+    /** Admin user ID performing the action — required */
+    admin_user_id: string;
+}
+/** Response body from POST .../enable-withholding */
+interface EnableWithholdingResponse {
+    message: string;
+}
+/**
+ * Result returned by POST /api/v1/tax/customer-tax-profiles/{id}/check-tin
+ */
+interface TINCheckResult {
+    tin_result: Record<string, unknown>;
+    profile: CustomerTaxProfileRecord;
+}
+type TransactionAction = 'hold' | 'suspend' | 'release_with_withholding';
+type EmailSendingMethod = 'tenant_email' | 'avalara_direct';
+/**
+ * TaxRules is returned by GET /api/v1/tax/rules.
+ * It extends TenantTaxRules with the platform-wide withdrawal_threshold
+ * from the active VesantGlobalTaxRule for the current year.
+ */
+interface TaxRules {
+    id: string;
+    tenant_id: string;
+    /** Platform-wide IRS withdrawal threshold (from VesantGlobalTaxRule). May be absent if not yet configured. */
+    withdrawal_threshold?: number;
+    trigger_account_creation: boolean;
+    trigger_first_withdrawal: boolean;
+    trigger_threshold: boolean;
+    trigger_manual: boolean;
+    trigger_tin_invalid: boolean;
+    trigger_w8ben_expiry: boolean;
+    trigger_tin_expired: boolean;
+    us_withholding_enabled: boolean;
+    us_withholding_rate: number;
+    non_us_withholding_enabled: boolean;
+    non_us_withholding_rate: number;
+    transaction_action: TransactionAction;
+    reminder_frequency_days: number;
+    reminder_max_count: number;
+    w8ben_expiry_warning_days: number;
+    tin_verification_due_date?: string;
+    email_sending_method: EmailSendingMethod;
+    display_tin_links_on_platform: boolean;
+    tax_treaty_support: boolean;
+    created_at: string;
+    updated_at: string;
+}
+/**
+ * Input for PUT /api/v1/tax/rules.
+ * Mirrors domain.UpdateRulesInput — withholding rates are NOT tenant-configurable.
+ */
+interface UpdateTaxRulesInput {
+    trigger_account_creation: boolean;
+    trigger_first_withdrawal: boolean;
+    trigger_threshold: boolean;
+    trigger_manual: boolean;
+    trigger_tin_invalid: boolean;
+    trigger_w8ben_expiry: boolean;
+    trigger_tin_expired: boolean;
+    us_withholding_enabled: boolean;
+    non_us_withholding_enabled: boolean;
+    transaction_action: TransactionAction;
+    reminder_frequency_days: number;
+    reminder_max_count: number;
+    w8ben_expiry_warning_days: number;
+    tin_verification_due_date?: string;
+    email_sending_method: EmailSendingMethod;
+    display_tin_links_on_platform: boolean;
+    tax_treaty_support: boolean;
+}
+type TaxRuleApprovalStatus = 'pending' | 'approved' | 'rejected';
+interface TaxRuleVersion {
+    id: string;
+    tenant_id: string;
+    version_number: number;
+    proposed_rules: Record<string, unknown>;
+    changed_fields: Record<string, unknown>;
+    changed_by: string;
+    approved_by?: string;
+    approval_status: TaxRuleApprovalStatus;
+    approved_at?: string;
+    activated_at?: string;
+    created_at: string;
+}
+interface ComplianceStatsFilters {
+    /** Predefined range: "7d" | "30d" | "90d" | "1y" */
+    time_range?: string;
+    /** ISO date YYYY-MM-DD (inclusive) */
+    from_date?: string;
+    /** ISO date YYYY-MM-DD (inclusive) */
+    to_date?: string;
+}
+interface DocumentRequestBreakdown {
+    total: number;
+    w9: number;
+    w8ben: number;
+    w8bene: number;
+}
+interface TINStatusBreakdown {
+    verified: number;
+    pending: number;
+    rejected: number;
+}
+interface WFormStatusBreakdown {
+    w9: Record<string, number>;
+    w8ben: Record<string, number>;
+    w8bene: Record<string, number>;
+}
+interface WFormCountBreakdown {
+    w9: number;
+    w8ben: number;
+    w8bene: number;
+}
+interface ComplianceStats {
+    total_taxable_customers: number;
+    total_documents_requested: DocumentRequestBreakdown;
+    tin_verified_customers: number;
+    tin_verification_completion_rate: number;
+    document_completion_count: number;
+    document_completion_rate: number;
+    overdue_documents: number;
+    tin_verification_status: TINStatusBreakdown;
+    w_forms_by_status: WFormStatusBreakdown;
+    w_forms_status_totals: Record<string, number>;
+    w_forms_count: WFormCountBreakdown;
+}
+interface GlobalTaxRule {
+    id: string;
+    withdrawal_threshold: number;
+    default_us_withholding: number;
+    default_non_us_withholding: number;
+    tax_treaty_support: boolean;
+    tax_year: number;
+    configured_by: string;
+    is_active: boolean;
+    created_at: string;
+    updated_at: string;
+}
+interface TreatyCountry {
+    id: string;
+    country_code: string;
+    country_name: string;
+    withholding_rate: number;
+    is_active: boolean;
+    configured_by?: string;
+    created_at: string;
+    updated_at: string;
+}
+interface TreatyCountryListResponse {
+    treaty_countries: TreatyCountry[];
+    count: number;
+}
+interface TaxClientConfig {
+    /** Base URL of the Transaction Monitoring Service API (e.g., "http://localhost:8097") */
+    baseURL: string;
+    tenantId: string;
+    apiKey?: string;
+    headers?: Record<string, string>;
+    timeout?: number;
+    debug?: boolean;
+    environment?: 'production' | 'sandbox';
+}
+
+declare class TaxClient extends BaseClient {
+    constructor(config: TaxClientConfig);
+    getCustomerTaxProfileRecord(customerID: string): Promise<CustomerTaxProfileRecord>;
+    requestTaxForm(customerID: string): Promise<CustomerTaxProfileRecord>;
+    checkTINStatus(customerID: string): Promise<TINCheckResult>;
+    reRequestTaxForm(customerID: string, input: ReRequestTaxFormInput): Promise<CustomerTaxProfileRecord>;
+    enableBackupWithholding(customerID: string, input: EnableWithholdingInput): Promise<EnableWithholdingResponse>;
+    downloadTaxForm(customerID: string, requestOptions?: RequestOptions): Promise<ArrayBuffer>;
+    getTaxRules(): Promise<TaxRules>;
+    updateTaxRules(input: UpdateTaxRulesInput): Promise<TaxRuleVersion>;
+    getComplianceStats(filters?: ComplianceStatsFilters): Promise<ComplianceStats>;
+    getCurrentGlobalTaxRule(): Promise<GlobalTaxRule>;
+    listTreatyCountries(): Promise<TreatyCountryListResponse>;
+    getTreatyCountry(code: string): Promise<TreatyCountry>;
+}
+
+export { type CTPFormStatus, type CTPTINStatus, type ComplianceStats, type ComplianceStatsFilters, type CustomerTaxProfileRecord, type CustomerType, type DocumentRequestBreakdown, type EmailSendingMethod, type EnableWithholdingInput, type EnableWithholdingResponse, type GlobalTaxRule, type ReRequestTaxFormInput, type TINCheckResult, type TINStatusBreakdown, TaxClient, type TaxClientConfig, type TaxRuleApprovalStatus, type TaxRuleVersion, type TaxRules, type TransactionAction, type TreatyCountry, type TreatyCountryListResponse, type UpdateTaxRulesInput, type WFormCountBreakdown, type WFormStatusBreakdown };