vesant-sdk 1.5.2 → 1.6.1

package/dist/index.mjs

@@ -240,7 +240,7 @@ var noopLogger = {
 };
 
 // src/core/version.ts
-var SDK_VERSION = "1.5.2";
+var SDK_VERSION = "1.6.1";
 
 // src/shared/browser-utils.ts
 function generateUUID() {
@@ -414,6 +414,19 @@ var BaseClient = class {
       if (this.rateLimitTracker) {
         this.rateLimitTracker.updateFromHeaders(response.headers);
       }
+      if (requestOptions?.responseType === "arraybuffer") {
+        if (!response.ok) {
+          let errData = {};
+          try {
+            errData = await response.json();
+          } catch {
+          }
+          this.handleErrorResponse(response.status, errData, requestId);
+        }
+        this.circuitBreaker?.onSuccess();
+        const buffer = await response.arrayBuffer();
+        return buffer;
+      }
       let data;
       try {
         data = await response.json();
@@ -1523,17 +1536,34 @@ var ComplianceClient = class {
     const startTime = Date.now();
     this.validateRegistrationRequest(request);
     let geoVerification = null;
+    let cipherTextResult;
     try {
       if (this.config.debug) {
         this.logger.debug("Starting registration verification", { customerId: request.customerId });
       }
-      geoVerification = await this.geoClient.verifyIP({
-        ip_address: request.ipAddress,
-        user_id: request.customerId,
-        event_type: "registration",
-        device_fingerprint: request.deviceFingerprint
-      }, requestOptions);
-      const blockReasons = this.evaluateRegistrationBlock(geoVerification);
+      const customerData = request.cipherText ? {
+        full_name: request.fullName,
+        email: request.emailAddress,
+        phone: request.phoneNumber,
+        date_of_birth: request.dateOfBirth
+      } : void 0;
+      [cipherTextResult, geoVerification] = await Promise.all([
+        this.executeCipherTextValidation(
+          request.cipherText,
+          request.customerId,
+          "registration",
+          request.ipAddress,
+          customerData,
+          requestOptions
+        ),
+        this.geoClient.verifyIP({
+          ip_address: request.ipAddress,
+          user_id: request.customerId,
+          event_type: "registration",
+          device_fingerprint: request.deviceFingerprint
+        }, requestOptions)
+      ]);
+      const blockReasons = this.evaluateRegistrationBlock(geoVerification, cipherTextResult);
       if (blockReasons.length > 0) {
         if (this.config.debug) {
           this.logger.debug("Registration blocked at geo stage", { blockReasons });
@@ -1545,7 +1575,8 @@ var ComplianceClient = class {
           requiresKYC: false,
           requiresEDD: false,
           blockReasons,
-          processingTime: Date.now() - startTime
+          processingTime: Date.now() - startTime,
+          cipherTextValidation: cipherTextResult
         };
       }
       const profile = await this.riskClient.createProfile({
@@ -1580,7 +1611,8 @@ var ComplianceClient = class {
         requiresKYC,
         requiresEDD,
         blockReasons: [],
-        processingTime: Date.now() - startTime
+        processingTime: Date.now() - startTime,
+        cipherTextValidation: cipherTextResult
       };
     } catch (error) {
       if (this.config.debug) {
@@ -1608,7 +1640,7 @@ var ComplianceClient = class {
    * @param geoVerification - Geolocation verification result
    * @returns Array of block reasons (empty if allowed)
    */
-  evaluateRegistrationBlock(geoVerification) {
+  evaluateRegistrationBlock(geoVerification, cipherTextResult) {
     const blockReasons = [];
     if (geoVerification.is_blocked) {
       blockReasons.push(...geoVerification.risk_reasons);
@@ -1642,6 +1674,20 @@ var ComplianceClient = class {
         blockReasons.push("critical_risk_level");
       }
     }
+    if (cipherTextResult) {
+      if (!cipherTextResult.valid) {
+        blockReasons.push("ciphertext_validation_failed");
+      }
+      if (cipherTextResult.risk?.is_blocked) {
+        blockReasons.push(...cipherTextResult.risk.block_reasons || []);
+      }
+      if (cipherTextResult.risk?.location_mismatch) {
+        blockReasons.push("gps_ip_location_mismatch");
+      }
+    }
+    if (geoVerification.gps_required && !cipherTextResult) {
+      blockReasons.push("gps_verification_required");
+    }
     return [...new Set(blockReasons)];
   }
   /**
@@ -1772,7 +1818,15 @@ var ComplianceClient = class {
       if (this.config.debug) {
         this.logger.debug("Starting login verification", { customerId: request.customerId });
       }
-      const [geoVerification, profileResult] = await Promise.all([
+      const [cipherTextResult, geoVerification, profileResult] = await Promise.all([
+        this.executeCipherTextValidation(
+          request.cipherText,
+          request.customerId,
+          "login",
+          request.ipAddress,
+          void 0,
+          requestOptions
+        ),
         this.geoClient.verifyIP({
           ip_address: request.ipAddress,
           user_id: request.customerId,
@@ -1781,10 +1835,23 @@ var ComplianceClient = class {
         }, requestOptions),
         this.riskClient.getProfile(request.customerId, requestOptions).catch(() => null)
       ]);
+      const loginBlockReasons = this.getBlockReasons(geoVerification, profileResult, cipherTextResult);
+      const isBlocked = !geoVerification.is_compliant || geoVerification.is_blocked || !!cipherTextResult?.risk?.is_blocked || cipherTextResult?.valid === false || geoVerification.gps_required && !cipherTextResult;
+      if (isBlocked && !profileResult) {
+        return {
+          allowed: false,
+          geolocation: geoVerification,
+          profile: null,
+          requiresStepUp: false,
+          blockReasons: loginBlockReasons,
+          processingTime: Date.now() - startTime,
+          cipherTextValidation: cipherTextResult
+        };
+      }
       let profile;
       if (profileResult) {
         profile = profileResult;
-        if (this.shouldUpdateProfile(profile, geoVerification.location.city)) {
+        if (!isBlocked && this.shouldUpdateProfile(profile, geoVerification.location.city)) {
           profile = await this.riskClient.updateProfile(profile.id, {
             last_recorded_activity: (/* @__PURE__ */ new Date()).toISOString(),
             location: `${geoVerification.location.city}, ${geoVerification.location.country}`,
@@ -1797,15 +1864,15 @@ var ComplianceClient = class {
         }
         profile = await this.createProfileFromGeo(request.customerId, geoVerification);
       }
-      const isAllowed = geoVerification.is_compliant && !geoVerification.is_blocked && profile.customer_status !== "suspended";
-      const requiresStepUp = geoVerification.risk_level === "high" || geoVerification.risk_level === "critical";
+      const requiresStepUp = geoVerification.risk_level === "high" || geoVerification.risk_level === "critical" || cipherTextResult?.risk?.location_mismatch === true;
       return {
-        allowed: isAllowed,
+        allowed: !isBlocked && profile.customer_status !== "suspended",
         geolocation: geoVerification,
         profile,
         requiresStepUp,
-        blockReasons: this.getBlockReasons(geoVerification, profile),
-        processingTime: Date.now() - startTime
+        blockReasons: isBlocked || profile.customer_status === "suspended" ? this.getBlockReasons(geoVerification, profile, cipherTextResult) : [],
+        processingTime: Date.now() - startTime,
+        cipherTextValidation: cipherTextResult
       };
     } catch (error) {
       throw new ComplianceError("Login verification failed", error instanceof Error ? error.message : void 0);
@@ -1852,27 +1919,58 @@ var ComplianceClient = class {
           currency: request.currency
         });
       }
-      const [geoVerification, profile] = await Promise.all([
+      const [cipherTextResult, geoVerification, profileResult] = await Promise.all([
+        this.executeCipherTextValidation(
+          request.cipherText,
+          request.customerId,
+          "transaction",
+          request.ipAddress,
+          void 0,
+          requestOptions
+        ),
         this.geoClient.verifyIP({
           ip_address: request.ipAddress,
           user_id: request.customerId,
           event_type: "transaction",
           device_fingerprint: request.deviceFingerprint
         }, requestOptions),
-        this.riskClient.getProfile(request.customerId, requestOptions)
+        this.riskClient.getProfile(request.customerId, requestOptions).catch(() => null)
       ]);
+      const geoBlocked = !geoVerification.is_compliant || geoVerification.is_blocked || !!cipherTextResult?.risk?.is_blocked || cipherTextResult?.valid === false || geoVerification.gps_required && !cipherTextResult;
+      if (geoBlocked && !profileResult) {
+        return {
+          allowed: false,
+          geolocation: geoVerification,
+          profile: null,
+          transactionRisk: { score: 0, level: "low", factors: [], allowed: false, requiresManualReview: false },
+          requiresApproval: false,
+          blockReasons: this.getTransactionBlockReasons(
+            geoVerification,
+            { score: 0, level: "low", factors: [], allowed: false, requiresManualReview: false },
+            true,
+            cipherTextResult
+          ),
+          processingTime: Date.now() - startTime,
+          cipherTextValidation: cipherTextResult
+        };
+      }
+      if (!profileResult) {
+        throw new ComplianceError("Customer profile not found", request.customerId);
+      }
+      const profile = profileResult;
       const transactionRisk = this.calculateTransactionRisk(
         request.amount,
         request.currency,
         geoVerification,
-        profile
+        profile,
+        cipherTextResult
       );
       const jurisdictionAllowed = this.checkJurisdictionLimits(
         request.amount,
         request.currency,
         geoVerification.jurisdiction
       );
-      const isAllowed = geoVerification.is_compliant && !geoVerification.is_blocked && jurisdictionAllowed && transactionRisk.allowed;
+      const isAllowed = !geoBlocked && jurisdictionAllowed && transactionRisk.allowed && profile.customer_status !== "suspended";
       return {
         allowed: isAllowed,
         geolocation: geoVerification,
@@ -1882,9 +1980,11 @@ var ComplianceClient = class {
         blockReasons: this.getTransactionBlockReasons(
           geoVerification,
           transactionRisk,
-          jurisdictionAllowed
+          jurisdictionAllowed,
+          cipherTextResult
         ),
-        processingTime: Date.now() - startTime
+        processingTime: Date.now() - startTime,
+        cipherTextValidation: cipherTextResult
       };
     } catch (error) {
       throw new ComplianceError("Transaction verification failed", error instanceof Error ? error.message : void 0);
@@ -1899,12 +1999,22 @@ var ComplianceClient = class {
   async verifyEvent(request, requestOptions) {
     const startTime = Date.now();
     this.validateEventRequest(request);
-    const geoVerification = await this.geoClient.verifyIP({
-      ip_address: request.ipAddress,
-      user_id: request.customerId,
-      event_type: request.eventType,
-      device_fingerprint: request.deviceFingerprint
-    }, requestOptions);
+    const [cipherTextResult, geoVerification] = await Promise.all([
+      this.executeCipherTextValidation(
+        request.cipherText,
+        request.customerId,
+        request.eventType,
+        request.ipAddress,
+        void 0,
+        requestOptions
+      ),
+      this.geoClient.verifyIP({
+        ip_address: request.ipAddress,
+        user_id: request.customerId,
+        event_type: request.eventType,
+        device_fingerprint: request.deviceFingerprint
+      }, requestOptions)
+    ]);
     if (this.config.autoCreateProfiles) {
       try {
         const profile = await this.riskClient.getProfile(request.customerId, requestOptions);
@@ -1917,11 +2027,26 @@ var ComplianceClient = class {
         }
       }
     }
+    const cipherTextBlocked = cipherTextResult ? !cipherTextResult.valid || cipherTextResult.risk?.is_blocked === true : false;
+    const blockReasons = [...geoVerification.risk_reasons];
+    if (cipherTextResult) {
+      if (!cipherTextResult.valid) {
+        blockReasons.push("ciphertext_validation_failed");
+      }
+      if (cipherTextResult.risk?.is_blocked) {
+        blockReasons.push(...cipherTextResult.risk.block_reasons || []);
+      }
+    }
+    const gpsBlocked = geoVerification.gps_required && !cipherTextResult;
+    if (gpsBlocked) {
+      blockReasons.push("gps_verification_required");
+    }
     return {
-      allowed: geoVerification.is_compliant && !geoVerification.is_blocked,
+      allowed: geoVerification.is_compliant && !geoVerification.is_blocked && !cipherTextBlocked && !gpsBlocked,
       geolocation: geoVerification,
-      blockReasons: geoVerification.risk_reasons,
-      processingTime: Date.now() - startTime
+      blockReasons: [...new Set(blockReasons)],
+      processingTime: Date.now() - startTime,
+      cipherTextValidation: cipherTextResult
     };
   }
   // ============================================================================
@@ -1950,7 +2075,29 @@ var ComplianceClient = class {
       kyc_status: "pending"
     });
   }
-  calculateTransactionRisk(amount, currency, geoVerification, profile) {
+  /**
+   * Execute cipherText validation with graceful degradation.
+   * Returns undefined if cipherText is not provided or validation fails.
+   */
+  async executeCipherTextValidation(cipherText, userId, eventType, ipAddress, customerData, requestOptions) {
+    if (!cipherText) return void 0;
+    try {
+      return await this.geoClient.validateCipherText(
+        cipherText,
+        userId,
+        eventType,
+        ipAddress,
+        customerData,
+        requestOptions
+      );
+    } catch (err) {
+      this.logger.warn("CipherText validation failed, proceeding with IP-only", {
+        error: err instanceof Error ? err.message : "Unknown error"
+      });
+      return void 0;
+    }
+  }
+  calculateTransactionRisk(amount, currency, geoVerification, profile, cipherTextResult) {
     if (!this._currencyRatesCustomized && !this._currencyRatesWarned) {
       this._currencyRatesWarned = true;
       this.logger.warn(
@@ -1983,6 +2130,15 @@ var ComplianceClient = class {
       riskScore += 50;
       factors.push("account_suspended");
     }
+    if (cipherTextResult) {
+      if (cipherTextResult.risk?.location_mismatch) {
+        riskScore += 20;
+        factors.push("gps_ip_location_mismatch");
+      }
+      if (cipherTextResult.risk?.score) {
+        riskScore += cipherTextResult.risk.score * 0.2;
+      }
+    }
     return {
       score: Math.min(riskScore, 100),
       level: this.getRiskLevel(riskScore),
@@ -2008,20 +2164,33 @@ var ComplianceClient = class {
     if (score >= 40) return "medium";
     return "low";
   }
-  getBlockReasons(geoVerification, profile) {
+  getBlockReasons(geoVerification, profile, cipherTextResult) {
     const reasons = [];
     if (geoVerification.is_blocked) {
       reasons.push(...geoVerification.risk_reasons);
     }
-    if (profile.customer_status === "suspended") {
-      reasons.push("account_suspended");
+    if (profile) {
+      if (profile.customer_status === "suspended") {
+        reasons.push("account_suspended");
+      }
+      if (profile.has_sanctions) {
+        reasons.push("sanctions_match");
+      }
+    }
+    if (cipherTextResult) {
+      if (!cipherTextResult.valid) {
+        reasons.push("ciphertext_validation_failed");
+      }
+      if (cipherTextResult.risk?.is_blocked) {
+        reasons.push(...cipherTextResult.risk.block_reasons || []);
+      }
     }
-    if (profile.has_sanctions) {
-      reasons.push("sanctions_match");
+    if (geoVerification.gps_required && !cipherTextResult) {
+      reasons.push("gps_verification_required");
     }
-    return reasons;
+    return [...new Set(reasons)];
   }
-  getTransactionBlockReasons(geoVerification, transactionRisk, jurisdictionAllowed) {
+  getTransactionBlockReasons(geoVerification, transactionRisk, jurisdictionAllowed, cipherTextResult) {
     const reasons = [];
     if (!geoVerification.is_compliant) {
       reasons.push("non_compliant_jurisdiction");
@@ -2032,7 +2201,18 @@ var ComplianceClient = class {
     if (!transactionRisk.allowed) {
       reasons.push(...transactionRisk.factors);
     }
-    return reasons;
+    if (cipherTextResult) {
+      if (!cipherTextResult.valid) {
+        reasons.push("ciphertext_validation_failed");
+      }
+      if (cipherTextResult.risk?.is_blocked) {
+        reasons.push(...cipherTextResult.risk.block_reasons || []);
+      }
+    }
+    if (geoVerification.gps_required && !cipherTextResult) {
+      reasons.push("gps_verification_required");
+    }
+    return [...new Set(reasons)];
   }
   // ============================================================================
   // Location Request Methods
@@ -2853,235 +3033,93 @@ var TaxClient = class extends BaseClient {
     };
     super(baseConfig);
   }
-  // ============================================================================
-  // Tax Enable / Disable Configuration
-  // ============================================================================
-  /**
-   * Get the tax enabled/disabled state for the tenant
-   *
-   * @returns The current tax config (tax_enabled flag)
-   *
-   * @example
-   * ```typescript
-   * const config = await client.getTaxConfig();
-   * console.log(`Tax enabled: ${config.tax_enabled}`);
-   * ```
-   */
-  async getTaxConfig() {
-    const res = await this.request("/api/v1/tax/config");
-    return res.tax_config;
+  // ==========================================================================
+  // P1 — Customer Tax Profile (core compliance flow)
+  // ==========================================================================
+  async getCustomerTaxProfileRecord(customerID) {
+    return this.request(
+      `/api/v1/tax/customer-tax-profiles/${customerID}`
+    );
   }
-  /**
-   * Enable or disable tax compliance features for the tenant
-   *
-   * @param request - Object with tax_enabled boolean
-   * @returns Updated tax config
-   *
-   * @example
-   * ```typescript
-   * // Enable tax
-   * const config = await client.updateTaxConfig({ tax_enabled: true });
-   *
-   * // Disable tax
-   * const config = await client.updateTaxConfig({ tax_enabled: false });
-   * ```
-   */
-  async updateTaxConfig(request) {
-    const res = await this.request("/api/v1/tax/config", {
-      method: "PUT",
-      body: JSON.stringify({ tax_config: request })
-    });
-    return res.tax_config;
+  async requestTaxForm(customerID) {
+    return this.request(
+      `/api/v1/tax/customer-tax-profiles/${customerID}/request-form`,
+      { method: "POST" }
+    );
   }
-  // ============================================================================
-  // Solicitation Trigger Configuration
-  // ============================================================================
-  /**
-   * Get solicitation triggers for the tenant
-   *
-   * @returns List of solicitation triggers with their enabled state
-   *
-   * @example
-   * ```typescript
-   * const triggers = await client.getSolicitationTriggers();
-   * triggers.forEach(t => console.log(`${t.label}: ${t.enabled}`));
-   * ```
-   */
-  async getSolicitationTriggers() {
-    const res = await this.request(
-      "/api/v1/tax/solicitation/config"
+  async checkTINStatus(customerID) {
+    return this.requestWithRetry(
+      `/api/v1/tax/customer-tax-profiles/${customerID}/check-tin`,
+      { method: "POST" }
     );
-    return res.solicitation_triggers;
   }
-  /**
-   * Update solicitation triggers for the tenant
-   *
-   * @param triggers - Array of triggers with updated enabled/threshold values
-   * @returns Updated triggers
-   *
-   * @example
-   * ```typescript
-   * const triggers = await client.updateSolicitationTriggers([
-   *   { type: 'first_withdrawal', enabled: true, label: 'First Withdrawal', description: '...' },
-   *   { type: 'threshold_based', enabled: true, label: 'Threshold', description: '...', threshold_amount: 600 },
-   * ]);
-   * ```
-   */
-  async updateSolicitationTriggers(triggers) {
-    const res = await this.request(
-      "/api/v1/tax/solicitation/config",
+  async reRequestTaxForm(customerID, input) {
+    return this.request(
+      `/api/v1/tax/customer-tax-profiles/${customerID}/re-request-form`,
       {
-        method: "PUT",
-        body: JSON.stringify({ solicitation_triggers: triggers })
+        method: "POST",
+        body: JSON.stringify(input)
       }
     );
-    return res.solicitation_triggers;
   }
-  // ============================================================================
-  // Reminder Configuration
-  // ============================================================================
-  /**
-   * Get the reminder configuration for the tenant
-   *
-   * @returns Reminder config (enabled, max_reminders, frequency_days)
-   *
-   * @example
-   * ```typescript
-   * const config = await client.getReminderConfig();
-   * console.log(`Reminders enabled: ${config.enabled}, every ${config.frequency_days} days`);
-   * ```
-   */
-  async getReminderConfig() {
-    const res = await this.request(
-      "/api/v1/tax/solicitation/reminder-config"
-    );
-    return res.reminder_config;
-  }
-  /**
-   * Update the reminder configuration for the tenant
-   *
-   * @param config - Reminder configuration to set
-   * @returns Updated reminder config
-   *
-   * @example
-   * ```typescript
-   * const updated = await client.updateReminderConfig({
-   *   enabled: true,
-   *   max_reminders: 3,
-   *   frequency_days: 7,
-   * });
-   * ```
-   */
-  async updateReminderConfig(config) {
-    const res = await this.request(
-      "/api/v1/tax/solicitation/reminder-config",
+  async enableBackupWithholding(customerID, input) {
+    return this.request(
+      `/api/v1/tax/customer-tax-profiles/${customerID}/enable-withholding`,
       {
-        method: "PUT",
-        body: JSON.stringify({ reminder_config: config })
+        method: "POST",
+        body: JSON.stringify(input)
       }
     );
-    return res.reminder_config;
   }
-  // ============================================================================
-  // Tax Forms
-  // ============================================================================
-  /**
-   * List tax forms with optional filters and pagination
-   *
-   * @param filters - Optional filters (customer_id, form_type, form_status, etc.)
-   * @returns Paginated list of tax forms
-   *
-   * @example
-   * ```typescript
-   * const result = await client.listTaxForms({ form_type: 'W-9', form_status: 'Pending' });
-   * console.log(`Found ${result.total} forms`);
-   * ```
-   */
-  async listTaxForms(filters) {
-    const params = {};
-    if (filters) {
-      if (filters.customer_id) params.customer_id = filters.customer_id;
-      if (filters.form_type) params.form_type = filters.form_type;
-      if (filters.form_status) params.form_status = filters.form_status;
-      if (filters.tin_status) params.tin_status = filters.tin_status;
-      if (filters.avalara_company_id) params.avalara_company_id = filters.avalara_company_id;
-      if (filters.search) params.search = filters.search;
-      if (filters.start_date) params.start_date = filters.start_date;
-      if (filters.end_date) params.end_date = filters.end_date;
-      if (filters.page) params.page = filters.page;
-      if (filters.page_size) params.limit = filters.page_size;
-    }
-    return this.request(`/api/v1/tax/forms${this.buildQueryString(params)}`);
-  }
-  /**
-   * Get a tax form by ID
-   *
-   * @param formId - Tax form UUID
-   * @returns Tax form details
-   */
-  async getTaxForm(formId) {
-    return this.request(`/api/v1/tax/forms/${formId}`);
-  }
-  /**
-   * Get lifecycle events for a tax form
-   *
-   * @param formId - Tax form UUID
-   * @returns List of lifecycle events
-   */
-  async getTaxFormLifecycleEvents(formId) {
-    const res = await this.request(
-      `/api/v1/tax/forms/${formId}/lifecycle`
+  async downloadTaxForm(customerID, requestOptions) {
+    return this.request(
+      `/api/v1/tax/customer-tax-profiles/${customerID}/download-form`,
+      { method: "GET" },
+      void 0,
+      { ...requestOptions, responseType: "arraybuffer" }
     );
-    return res.lifecycle_events;
   }
-  // ============================================================================
-  // Customer Tax Profile
-  // ============================================================================
-  /**
-   * Get the full tax profile for a customer (all forms + lifecycle events)
-   *
-   * @param customerID - Customer ID
-   * @returns Customer tax profile with all forms and events
-   *
-   * @example
-   * ```typescript
-   * const profile = await client.getCustomerTaxProfile('cust_123');
-   * console.log(`Customer has ${profile.tax_forms.length} tax forms`);
-   * ```
-   */
-  async getCustomerTaxProfile(customerID) {
-    return this.request(`/api/v1/tax/profile/${customerID}`);
+  // ==========================================================================
+  // P2 — Tenant Tax Rules
+  // ==========================================================================
+  async getTaxRules() {
+    const res = await this.request("/api/v1/tax/rules");
+    return res.rules;
   }
-  // ============================================================================
-  // Tax Companies
-  // ============================================================================
-  /**
-   * List Avalara tax companies for the tenant
-   *
-   * @param page - Page number (default: 1)
-   * @param pageSize - Items per page (default: 20)
-   * @returns Paginated list of tax companies
-   */
-  async listTaxCompanies(page, pageSize) {
+  async updateTaxRules(input) {
+    const res = await this.request("/api/v1/tax/rules", {
+      method: "PUT",
+      body: JSON.stringify({ rules: input })
+    });
+    return res.version;
+  }
+  async getComplianceStats(filters) {
     const params = {};
-    if (page) params.page = page;
-    if (pageSize) params.limit = pageSize;
+    if (filters?.time_range) params.time_range = filters.time_range;
+    if (filters?.from_date) params.from_date = filters.from_date;
+    if (filters?.to_date) params.to_date = filters.to_date;
     return this.request(
-      `/api/v1/tax/companies${this.buildQueryString(params)}`
+      `/api/v1/tax/tenant/w-form-tenant-stats${this.buildQueryString(params)}`
     );
   }
-  /**
-   * Get a tax company by ID
-   *
-   * @param companyId - Tax company UUID
-   * @returns Tax company details
-   */
-  async getTaxCompany(companyId) {
-    return this.request(`/api/v1/tax/companies/${companyId}`);
+  // ==========================================================================
+  // P3 — Global Tax Rule & Treaty Countries
+  // ==========================================================================
+  async getCurrentGlobalTaxRule() {
+    const res = await this.request(
+      "/api/v1/tm/tenant/global-tax-rules/current"
+    );
+    return res.data;
+  }
+  async listTreatyCountries() {
+    return this.request("/api/v1/tax/treaty-countries");
+  }
+  async getTreatyCountry(code) {
+    const res = await this.request(
+      `/api/v1/tax/treaty-countries/${encodeURIComponent(code)}`
+    );
+    return res.treaty_country;
   }
-  // ============================================================================
-  // Utility Methods (inherited from BaseClient: healthCheck, updateConfig, getConfig, buildQueryString)
-  // ============================================================================
 };
 
 // src/transaction/client.ts