@simpleapps-com/augur-api 0.3.2 → 0.4.0

package/dist/esm/services/avalara/client.js

@@ -1,154 +1,212 @@
 import { BaseServiceClient } from '../../core/base-client';
-import { HealthCheckResponseSchema, RatesRequestParamsSchema, RatesResponseSchema, } from './schemas';
+import { HealthCheckResponseSchema, RatesResponseSchema, } from './schemas';
 /**
  * Avalara Tax Service Client
- *
- * Provides access to Avalara tax calculation endpoints for real-time tax rate
- * computation and compliance.
- *
+ * @description Client for interacting with Avalara tax calculation API endpoints for real-time tax rate computation and compliance
+ * @fullPath api.avalara
  * @service avalara
  * @domain tax-calculation
+ * @discoverable true
+ * @searchTerms ["avalara", "tax calculation", "sales tax", "vat", "tax compliance", "tax rates", "e-commerce tax"]
+ * @relatedEndpoints ["api.avalara.healthCheck.get", "api.avalara.rates.create", "api.commerce.orders.create", "api.commerce.cartHeaders.checkout"]
+ * @commonPatterns ["Tax calculation", "Sales tax compliance", "E-commerce tax processing", "Multi-jurisdiction tax"]
+ * @workflow ["e-commerce-checkout", "tax-compliance", "order-processing", "financial-reporting"]
+ * @functionalArea "tax-and-compliance"
+ * @businessRules ["Requires valid bearer authentication", "Real-time tax calculation", "Multi-jurisdiction support", "Compliance with local tax laws"]
+ * @performance "Optimized for e-commerce checkout flows and bulk tax calculations"
+ * @example
+ * ```typescript
+ * import { HTTPClient } from '@augur/api-client/core';
+ * import { AvalaraClient } from '@augur/api-client/services/avalara';
+ *
+ * const http = new HTTPClient('avalara', { siteId: 'your-site-id', bearerToken: 'your-token' });
+ * const avalara = new AvalaraClient(http);
+ *
+ * // Check service health
+ * const health = await avalara.healthCheck.get();
+ * const healthData = await avalara.healthCheck.getData();
+ *
+ * // Calculate tax rates
+ * const taxRequest = {
+ *   lines: [{ amount: 100.00, description: 'Widget' }],
+ *   addresses: {
+ *     shipTo: {
+ *       line1: '123 Main St',
+ *       city: 'Irvine',
+ *       region: 'CA',
+ *       country: 'US',
+ *       postalCode: '92602'
+ *     }
+ *   },
+ *   type: 'SalesOrder'
+ * };
+ * const taxResult = await avalara.rates.create(taxRequest);
+ * const taxData = await avalara.rates.getData(taxRequest);
+ * ```
  */
 export class AvalaraClient extends BaseServiceClient {
     constructor(http, baseUrl) {
         super('avalara', http, baseUrl || 'https://avalara.augur-api.com');
         /**
-         * Check service health and availability
-         *
-         * @fullPath api.avalara.healthCheck.get
-         * @service avalara
-         * @domain system-health
-         * @dataMethod healthCheckData
-         * @discoverable true
-         * @searchTerms ["health", "status", "availability", "ping", "check", "tax service"]
-         * @relatedEndpoints ["api.avalara.rates.calculate", "api.agrWork.healthCheck.get", "api.agrInfo.healthCheck.get", "api.commerce.healthCheck.get"]
-         * @commonPatterns ["Health check", "Service status", "Tax service availability", "System monitoring"]
-         * @workflow ["system-monitoring", "health-checks", "service-discovery", "tax-service-verification"]
-         * @prerequisites ["Service is running", "Valid authentication token", "x-site-id header"]
-         * @nextSteps ["Use tax calculation endpoints if healthy", "Verify tax service connectivity", "Monitor service metrics"]
-         * @businessRules ["Returns service status and basic info", "Requires standard authentication", "Standard health check format"]
-         * @functionalArea "system-monitoring"
-         * @caching "No caching - real-time status required"
-         * @performance "Fast response, minimal processing, use for tax service monitoring"
-         *
-         * @returns Promise<HealthCheckResponse> Service health status
-         *
-         * @example
-         * ```typescript
-         * // Check if tax service is healthy
-         * const response = await client.healthCheck();
-         * console.log(response.data); // Health status string
-         * console.log(response.status); // HTTP status code
-         *
-         * // Get just the health status
-         * const status = await client.healthCheckData();
-         * console.log(status); // Direct string access
-         * ```
-         */
-        this.healthCheck = this.createHealthCheckMethod(HealthCheckResponseSchema);
-        /**
-         * Calculate tax rates for transaction lines
-         *
-         * @fullPath api.avalara.rates.calculate
-         * @service avalara
-         * @domain tax-calculation
-         * @dataMethod ratesCalculateData
-         * @discoverable true
-         * @searchTerms ["tax", "rates", "calculate", "avalara", "sales tax", "vat", "compliance", "transaction"]
-         * @relatedEndpoints ["api.commerce.orders.create", "api.commerce.cartHeaders.checkout", "api.items.pricing.calculate", "api.customers.addresses.validate"]
-         * @commonPatterns ["Calculate sales tax", "Get tax rates", "Tax compliance", "E-commerce tax calculation", "Multi-jurisdiction tax"]
-         * @workflow ["e-commerce-checkout", "order-processing", "tax-compliance", "invoice-generation", "financial-reporting"]
-         * @prerequisites ["Valid transaction data", "Public bearer token", "x-site-id header", "Valid addresses", "Product/service lines"]
-         * @nextSteps ["Apply calculated tax to order", "Store tax calculation results", "Generate compliant invoice", "Submit tax returns"]
-         * @businessRules ["Requires valid addresses", "Supports multiple tax jurisdictions", "Real-time calculation", "Compliance with local tax laws", "Handles exemptions and special rates"]
-         * @functionalArea "tax-and-compliance"
-         * @crossSite "Multi-site tax calculation support"
-         * @caching "Cache for 1 hour for identical requests, tax rates change infrequently"
-         * @performance "Optimize by batching multiple line items, use address validation for accuracy"
-         *
-         * @param params Tax calculation request parameters including lines, addresses, and transaction details
-         * @returns Promise<RatesResponse> Complete tax calculation results with rates, amounts, and jurisdiction details
-         *
-         * @example
-         * ```typescript
-         * // Calculate tax for a simple sale
-         * const taxRequest = {
-         *   lines: [{
-         *     amount: 100.00,
-         *     description: 'Widget',
-         *     quantity: 1
-         *   }],
-         *   addresses: {
-         *     shipTo: {
-         *       line1: '123 Main St',
-         *       city: 'Irvine',
-         *       region: 'CA',
-         *       country: 'US',
-         *       postalCode: '92602'
-         *     }
-         *   },
-         *   type: 'SalesOrder',
-         *   date: '2024-01-15',
-         *   companyCode: 'DEFAULT'
-         * };
-         *
-         * const response = await client.ratesCalculate(taxRequest);
-         * console.log(response.data.totalTax); // Total tax amount
-         * console.log(response.data.lines); // Tax details per line
-         *
-         * // Get just the calculation result
-         * const taxResult = await client.ratesCalculateData(taxRequest);
-         * console.log(taxResult.totalTax); // Direct access to tax amount
-         *
-         * // Multi-line transaction with shipping
-         * const complexRequest = {
-         *   lines: [
-         *     { amount: 50.00, description: 'Product A', taxCode: 'P0000000' },
-         *     { amount: 30.00, description: 'Product B', taxCode: 'P0000000' },
-         *     { amount: 10.00, description: 'Shipping', taxCode: 'FR010000' }
-         *   ],
-         *   addresses: {
-         *     shipFrom: {
-         *       line1: '100 Warehouse Blvd',
-         *       city: 'Los Angeles',
-         *       region: 'CA',
-         *       country: 'US',
-         *       postalCode: '90210'
-         *     },
-         *     shipTo: {
-         *       line1: '456 Customer Ave',
-         *       city: 'New York',
-         *       region: 'NY',
-         *       country: 'US',
-         *       postalCode: '10001'
-         *     }
-         *   },
-         *   type: 'SalesInvoice',
-         *   customerCode: 'CUST001',
-         *   commit: true
-         * };
-         *
-         * const complexResult = await client.ratesCalculateData(complexRequest);
-         * ```
-         */
-        this.ratesCalculate = this.createCreateMethod('/rates', RatesRequestParamsSchema, RatesResponseSchema);
-        // Data-only methods for direct access to response data
-        /**
-         * Get health check status data only
-         * @returns Promise<string> Health status string
+         * Health Check Operations
+         * @description System health monitoring and availability verification for Avalara tax service
          */
-        this.healthCheckData = async () => {
-            const response = await this.healthCheck();
-            return response.data;
+        this.healthCheck = {
+            /**
+             * Check service health and availability
+             *
+             * @fullPath api.avalara.healthCheck.get
+             * @service avalara
+             * @domain system-health
+             * @dataMethod healthCheck.getData - returns only the health status data without metadata
+             * @discoverable true
+             * @searchTerms ["health", "status", "availability", "ping", "check", "tax service", "monitoring"]
+             * @relatedEndpoints ["api.avalara.rates.create", "api.agrWork.healthCheck.get", "api.agrInfo.healthCheck.get", "api.commerce.healthCheck.get", "api.items.healthCheck.get"]
+             * @commonPatterns ["Health check", "Service status", "Tax service availability", "System monitoring"]
+             * @workflow ["system-monitoring", "health-checks", "service-discovery", "tax-service-verification"]
+             * @prerequisites ["Service is running", "Valid authentication token", "x-site-id header"]
+             * @nextSteps ["Use tax calculation endpoints if healthy", "Verify tax service connectivity", "Monitor service metrics"]
+             * @businessRules ["Returns service status and basic info", "Requires standard authentication", "Standard health check format"]
+             * @functionalArea "system-monitoring"
+             * @caching "No caching - real-time status required"
+             * @performance "Fast response, minimal processing, use for tax service monitoring"
+             *
+             * @returns Promise<HealthCheckResponse> Service health status
+             *
+             * @example
+             * ```typescript
+             * // Check if tax service is healthy
+             * const response = await client.healthCheck.get();
+             * console.log(response.data); // Health status string
+             * console.log(response.status); // HTTP status code
+             *
+             * // Get just the health status
+             * const status = await client.healthCheck.getData();
+             * console.log(status); // Direct string access
+             * ```
+             */
+            get: async () => {
+                return this.executeRequest({
+                    method: 'GET',
+                    path: '/health-check',
+                    responseSchema: HealthCheckResponseSchema,
+                }, undefined);
+            },
+            /**
+             * Get health check status data only
+             * @returns Promise<string> Health status string
+             */
+            getData: async () => {
+                const response = await this.healthCheck.get();
+                return response.data;
+            },
         };
         /**
-         * Calculate tax rates and return calculation result data only
-         * @param params Tax calculation request parameters
-         * @returns Promise<TaxCalculationResult> Tax calculation result with rates and amounts
+         * Tax Rates Operations
+         * @description Tax calculation and rate computation for transaction lines and addresses
          */
-        this.ratesCalculateData = async (params) => {
-            const response = await this.ratesCalculate(params);
-            return response.data;
+        this.rates = {
+            /**
+             * Calculate tax rates for transaction lines
+             *
+             * @fullPath api.avalara.rates.create
+             * @service avalara
+             * @domain tax-calculation
+             * @dataMethod rates.getData - returns only the tax calculation data without metadata
+             * @discoverable true
+             * @searchTerms ["tax", "rates", "calculate", "avalara", "sales tax", "vat", "compliance", "transaction", "create"]
+             * @relatedEndpoints ["api.commerce.orders.create", "api.commerce.cartHeaders.checkout", "api.items.pricing.calculate", "api.customers.addresses.validate"]
+             * @commonPatterns ["Calculate sales tax", "Get tax rates", "Tax compliance", "E-commerce tax calculation", "Multi-jurisdiction tax"]
+             * @workflow ["e-commerce-checkout", "order-processing", "tax-compliance", "invoice-generation", "financial-reporting"]
+             * @prerequisites ["Valid transaction data", "Public bearer token", "x-site-id header", "Valid addresses", "Product/service lines"]
+             * @nextSteps ["Apply calculated tax to order", "Store tax calculation results", "Generate compliant invoice", "Submit tax returns"]
+             * @businessRules ["Requires valid addresses", "Supports multiple tax jurisdictions", "Real-time calculation", "Compliance with local tax laws", "Handles exemptions and special rates"]
+             * @functionalArea "tax-and-compliance"
+             * @crossSite "Multi-site tax calculation support"
+             * @caching "Cache for 1 hour for identical requests, tax rates change infrequently"
+             * @performance "Optimize by batching multiple line items, use address validation for accuracy"
+             *
+             * @param params Tax calculation request parameters including lines, addresses, and transaction details
+             * @returns Promise<RatesResponse> Complete tax calculation results with rates, amounts, and jurisdiction details
+             *
+             * @example
+             * ```typescript
+             * // Calculate tax for a simple sale
+             * const taxRequest = {
+             *   lines: [{
+             *     amount: 100.00,
+             *     description: 'Widget',
+             *     quantity: 1
+             *   }],
+             *   addresses: {
+             *     shipTo: {
+             *       line1: '123 Main St',
+             *       city: 'Irvine',
+             *       region: 'CA',
+             *       country: 'US',
+             *       postalCode: '92602'
+             *     }
+             *   },
+             *   type: 'SalesOrder',
+             *   date: '2024-01-15',
+             *   companyCode: 'DEFAULT'
+             * };
+             *
+             * const response = await client.rates.create(taxRequest);
+             * console.log(response.data.totalTax); // Total tax amount
+             * console.log(response.data.lines); // Tax details per line
+             *
+             * // Get just the calculation result
+             * const taxResult = await client.rates.getData(taxRequest);
+             * console.log(taxResult.totalTax); // Direct access to tax amount
+             *
+             * // Multi-line transaction with shipping
+             * const complexRequest = {
+             *   lines: [
+             *     { amount: 50.00, description: 'Product A', taxCode: 'P0000000' },
+             *     { amount: 30.00, description: 'Product B', taxCode: 'P0000000' },
+             *     { amount: 10.00, description: 'Shipping', taxCode: 'FR010000' }
+             *   ],
+             *   addresses: {
+             *     shipFrom: {
+             *       line1: '100 Warehouse Blvd',
+             *       city: 'Los Angeles',
+             *       region: 'CA',
+             *       country: 'US',
+             *       postalCode: '90210'
+             *     },
+             *     shipTo: {
+             *       line1: '456 Customer Ave',
+             *       city: 'New York',
+             *       region: 'NY',
+             *       country: 'US',
+             *       postalCode: '10001'
+             *     }
+             *   },
+             *   type: 'SalesInvoice',
+             *   customerCode: 'CUST001',
+             *   commit: true
+             * };
+             *
+             * const complexResult = await client.rates.getData(complexRequest);
+             * ```
+             */
+            create: async (params) => {
+                return this.executeRequest({
+                    method: 'POST',
+                    path: '/rates',
+                    responseSchema: RatesResponseSchema,
+                }, params);
+            },
+            /**
+             * Calculate tax rates and return calculation result data only
+             * @param params Tax calculation request parameters
+             * @returns Promise<TaxCalculationResult> Tax calculation result with rates and amounts
+             */
+            getData: async (params) => {
+                const response = await this.rates.create(params);
+                return response.data;
+            },
         };
     }
     getServiceDescription() {

package/dist/esm/services/avalara/client.js.map

@@ -1 +1 @@
-{"version":3,"file":"client.js","sourceRoot":"","sources":["../../../../src/services/avalara/client.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,iBAAiB,EAAE,MAAM,wBAAwB,CAAC;AAE3D,OAAO,EACL,yBAAyB,EACzB,wBAAwB,EAExB,mBAAmB,GAEpB,MAAM,WAAW,CAAC;AAEnB;;;;;;;;GAQG;AACH,MAAM,OAAO,aAAc,SAAQ,iBAAiB;IAClD,YAAY,IAAgB,EAAE,OAAgB;QAC5C,KAAK,CAAC,SAAS,EAAE,IAAI,EAAE,OAAO,IAAI,+BAA+B,CAAC,CAAC;QAOrE;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;WAgCG;QACM,gBAAW,GAAG,IAAI,CAAC,uBAAuB,CAAC,yBAAyB,CAAC,CAAC;QAE/E;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;WAoFG;QACM,mBAAc,GAAG,IAAI,CAAC,kBAAkB,CAC/C,QAAQ,EACR,wBAAwB,EACxB,mBAAmB,CACpB,CAAC;QAEF,uDAAuD;QAEvD;;;WAGG;QACM,oBAAe,GAAG,KAAK,IAAqB,EAAE;YACrD,MAAM,QAAQ,GAAG,MAAM,IAAI,CAAC,WAAW,EAAE,CAAC;YAC1C,OAAO,QAAQ,CAAC,IAAI,CAAC;QACvB,CAAC,CAAC;QAEF;;;;WAIG;QACM,uBAAkB,GAAG,KAAK,EACjC,MAA0B,EACK,EAAE;YACjC,MAAM,QAAQ,GAAG,MAAM,IAAI,CAAC,cAAc,CAAC,MAAM,CAAC,CAAC;YACnD,OAAO,QAAQ,CAAC,IAAI,CAAC;QACvB,CAAC,CAAC;IAzJF,CAAC;IAES,qBAAqB;QAC7B,OAAO,mFAAmF,CAAC;IAC7F,CAAC;CAsJF"}
+{"version":3,"file":"client.js","sourceRoot":"","sources":["../../../../src/services/avalara/client.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,iBAAiB,EAAE,MAAM,wBAAwB,CAAC;AAE3D,OAAO,EACL,yBAAyB,EAEzB,mBAAmB,GAEpB,MAAM,WAAW,CAAC;AAEnB;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2CG;AACH,MAAM,OAAO,aAAc,SAAQ,iBAAiB;IAClD,YAAY,IAAgB,EAAE,OAAgB;QAC5C,KAAK,CAAC,SAAS,EAAE,IAAI,EAAE,OAAO,IAAI,+BAA+B,CAAC,CAAC;QAOrE;;;WAGG;QACH,gBAAW,GAAG;YACZ;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;eAgCG;YACH,GAAG,EAAE,KAAK,IAAI,EAAE;gBACd,OAAO,IAAI,CAAC,cAAc,CACxB;oBACE,MAAM,EAAE,KAAK;oBACb,IAAI,EAAE,eAAe;oBACrB,cAAc,EAAE,yBAAyB;iBAC1C,EACD,SAAS,CACV,CAAC;YACJ,CAAC;YAED;;;eAGG;YACH,OAAO,EAAE,KAAK,IAAqB,EAAE;gBACnC,MAAM,QAAQ,GAAG,MAAM,IAAI,CAAC,WAAW,CAAC,GAAG,EAAE,CAAC;gBAC9C,OAAO,QAAQ,CAAC,IAAI,CAAC;YACvB,CAAC;SACF,CAAC;QAEF;;;WAGG;QACH,UAAK,GAAG;YACN;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;eAoFG;YACH,MAAM,EAAE,KAAK,EAAE,MAA0B,EAAE,EAAE;gBAC3C,OAAO,IAAI,CAAC,cAAc,CACxB;oBACE,MAAM,EAAE,MAAM;oBACd,IAAI,EAAE,QAAQ;oBACd,cAAc,EAAE,mBAAmB;iBACpC,EACD,MAAM,CACP,CAAC;YACJ,CAAC;YAED;;;;eAIG;YACH,OAAO,EAAE,KAAK,EAAE,MAA0B,EAAiC,EAAE;gBAC3E,MAAM,QAAQ,GAAG,MAAM,IAAI,CAAC,KAAK,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC;gBACjD,OAAO,QAAQ,CAAC,IAAI,CAAC;YACvB,CAAC;SACF,CAAC;IA/KF,CAAC;IAES,qBAAqB;QAC7B,OAAO,mFAAmF,CAAC;IAC7F,CAAC;CA4KF"}