@simpleapps-com/augur-api 0.2.13 → 0.3.1

package/dist/esm/services/smarty-streets/client.js

@@ -0,0 +1,271 @@
+import { BaseServiceClient } from '../../core/base-client';
+import { HealthCheckParamsSchema, HealthCheckResponseSchema, PingParamsSchema, PingResponseSchema, USLookupParamsSchema, USLookupResponseSchema, } from './schemas';
+/**
+ * SmartyStreets Address Validation Service Client
+ *
+ * Provides comprehensive US address validation, standardization, and geocoding services
+ * powered by SmartyStreets API. Validates addresses for deliverability, standardizes formatting,
+ * and provides detailed address intelligence for e-commerce, logistics, and data quality.
+ *
+ * @service smarty-streets
+ * @domain address-validation-and-geocoding
+ */
+export class SmartyStreetsClient extends BaseServiceClient {
+    constructor(http, baseUrl) {
+        super('smarty-streets', http, baseUrl || 'https://smarty-streets.augur-api.com');
+    }
+    getServiceDescription() {
+        return 'SmartyStreets address validation service for US address standardization and geocoding';
+    }
+    /**
+     * Check SmartyStreets service health and API connectivity
+     *
+     * @fullPath api.smartyStreets.healthCheck.get
+     * @service smarty-streets
+     * @domain system-health
+     * @dataMethod healthCheckData
+     * @discoverable true
+     * @searchTerms ["health", "status", "availability", "ping", "check", "address service", "smartystreets connectivity", "validation service"]
+     * @relatedEndpoints ["api.smartyStreets.ping.get", "api.smartyStreets.us.lookup", "api.customers.addresses.validate", "api.logistics.healthCheck.get", "api.shipping.healthCheck.get"]
+     * @commonPatterns ["Health check", "Service status", "Address service availability", "System monitoring", "API connectivity test"]
+     * @workflow ["system-monitoring", "health-checks", "service-discovery", "address-validation-setup", "api-status-verification"]
+     * @prerequisites ["Service is running", "Valid authentication token", "x-site-id header", "SmartyStreets API connectivity"]
+     * @nextSteps ["Use address validation endpoints if healthy", "Verify SmartyStreets API credits", "Monitor service metrics"]
+     * @businessRules ["Returns service and API status", "Requires standard authentication", "Standard health check format", "Reports API credit status"]
+     * @functionalArea "system-monitoring"
+     * @caching "No caching - real-time status required"
+     * @performance "Fast response, minimal processing, use for address service monitoring"
+     *
+     * @param params Health check parameters with site ID
+     * @returns Promise<HealthCheckResponse> Service health status with SmartyStreets API connectivity
+     *
+     * @example
+     * ```typescript
+     * // Check if SmartyStreets service is healthy
+     * const response = await client.healthCheck({ 'x-site-id': 'SITE123' });
+     * console.log(response.data.status); // 'healthy'
+     * console.log(response.data.service); // 'smarty-streets'
+     * console.log(response.data.smartystreets_connectivity); // true
+     * console.log(response.status); // HTTP status code
+     *
+     * // Get just the health status
+     * const status = await client.healthCheckData({ 'x-site-id': 'SITE123' });
+     * console.log(status); // Health data object
+     * ```
+     */
+    async healthCheck(params) {
+        return this.executeRequest({
+            method: 'GET',
+            path: '/health-check',
+            paramsSchema: HealthCheckParamsSchema,
+            responseSchema: HealthCheckResponseSchema,
+        }, params);
+    }
+    /**
+     * Ping SmartyStreets service for connectivity verification
+     *
+     * @fullPath api.smartyStreets.ping.get
+     * @service smarty-streets
+     * @domain system-health
+     * @dataMethod pingData
+     * @discoverable true
+     * @searchTerms ["ping", "connectivity", "response time", "pong", "test", "smartystreets ping", "service alive", "latency check"]
+     * @relatedEndpoints ["api.smartyStreets.healthCheck.get", "api.smartyStreets.us.lookup", "api.customers.addresses.ping", "api.logistics.ping.get"]
+     * @commonPatterns ["Ping test", "Connectivity check", "Response time test", "Service alive check", "Latency monitoring"]
+     * @workflow ["system-monitoring", "connectivity-tests", "performance-monitoring", "service-diagnostics", "latency-measurement"]
+     * @prerequisites ["Service is running", "Valid authentication token", "x-site-id header", "Network connectivity"]
+     * @nextSteps ["Use for latency monitoring", "Verify consistent response times", "Include in system health dashboards"]
+     * @businessRules ["Returns pong response", "Measures response time", "Requires standard authentication", "Simple connectivity test"]
+     * @functionalArea "system-monitoring"
+     * @caching "No caching - real-time ping test required"
+     * @performance "Ultra-fast response, use for latency monitoring and connectivity verification"
+     *
+     * @param params Ping parameters with site ID
+     * @returns Promise<PingResponse> Ping response with timing information
+     *
+     * @example
+     * ```typescript
+     * // Test service connectivity
+     * const response = await client.ping({ 'x-site-id': 'SITE123' });
+     * console.log(response.data.message); // 'pong'
+     * console.log(response.data.response_time_ms); // Response time
+     * console.log(response.status); // HTTP status code
+     *
+     * // Get just the ping data
+     * const pingData = await client.pingData({ 'x-site-id': 'SITE123' });
+     * console.log(pingData); // Ping data object
+     * ```
+     */
+    async ping(params) {
+        return this.executeRequest({
+            method: 'GET',
+            path: '/ping',
+            paramsSchema: PingParamsSchema,
+            responseSchema: PingResponseSchema,
+        }, params);
+    }
+    /**
+     * Validate and standardize US addresses using SmartyStreets API
+     *
+     * @fullPath api.smartyStreets.us.lookup
+     * @service smarty-streets
+     * @domain address-validation-and-geocoding
+     * @dataMethod usLookupData
+     * @discoverable true
+     * @searchTerms ["address validation", "us addresses", "standardize", "verify", "lookup", "postal", "zip code", "street address", "delivery", "dpv", "geocoding"]
+     * @relatedEndpoints ["api.customers.addresses.create", "api.customers.addresses.validate", "api.shipping.rates.calculate", "api.commerce.checkout.validateAddress", "api.logistics.addresses.verify"]
+     * @commonPatterns ["Validate customer address", "Standardize shipping address", "Verify delivery address", "Clean address data", "Geocode address", "Check address deliverability"]
+     * @workflow ["address-validation", "customer-onboarding", "checkout-process", "shipping-calculation", "data-quality", "address-standardization", "geocoding-workflow"]
+     * @prerequisites ["Valid US address components", "Valid authentication token", "x-site-id header", "SmartyStreets API access", "Sufficient API credits"]
+     * @nextSteps ["Use standardized address for shipping", "Store validated address", "Calculate shipping rates", "Update customer record", "Process geocoding data"]
+     * @businessRules ["US addresses only", "Requires complete address components", "Returns standardized USPS format", "Validates deliverability", "Provides geocoding data", "Consumes API credits"]
+     * @functionalArea "address-validation-and-geocoding"
+     * @crossSite "Supports multi-site address validation with different API configurations"
+     * @caching "Cache validated addresses for 30 days, invalidate on address changes"
+     * @performance "Batch requests for multiple addresses, implement retry logic for API limits, monitor credit usage"
+     *
+     * @param params Complete US address components for validation
+     * @returns Promise<USLookupResponse> Standardized address with validation results and geocoding data
+     *
+     * @example
+     * ```typescript
+     * // Validate and standardize a customer address
+     * const addressRequest = {
+     *   address1: '1234 Example Street',
+     *   address2: 'Apt 5B',
+     *   city: 'Provo',
+     *   state: 'UT',
+     *   postalCode: '84606',
+     *   'x-site-id': 'SITE123'
+     * };
+     *
+     * const response = await client.usLookup(addressRequest);
+     * console.log(response.data.candidates); // Array of standardized addresses
+     * console.log(response.data.valid_candidates); // Number of valid addresses
+     * console.log(response.status); // HTTP status code
+     *
+     * // Get just the validation data
+     * const validationResult = await client.usLookupData(addressRequest);
+     * console.log(validationResult); // Direct validation results
+     *
+     * // Validate shipping address for e-commerce
+     * const shippingAddress = await client.usLookup({
+     *   address1: '123 Main Street',
+     *   city: 'New York',
+     *   state: 'NY',
+     *   postalCode: '10001',
+     *   'x-site-id': 'ECOMMERCE-SITE'
+     * });
+     *
+     * // Check if address is deliverable
+     * const standardized = shippingAddress.data.candidates[0];
+     * if (standardized?.analysis?.dpv_match_y) {
+     *   console.log('Address is deliverable');
+     *   console.log('Standardized:', standardized.delivery_line_1);
+     *   console.log('ZIP+4:', standardized.zipcode + '-' + standardized.plus4_code);
+     * }
+     *
+     * // Extract geocoding data
+     * if (standardized?.metadata) {
+     *   console.log('County:', standardized.metadata.county_name);
+     *   console.log('Time Zone:', standardized.metadata.time_zone);
+     *   console.log('Carrier Route:', standardized.metadata.carrier_route);
+     * }
+     *
+     * // Handle validation errors
+     * if (shippingAddress.data.valid_candidates === 0) {
+     *   console.log('Invalid address - requires correction');
+     * } else if (shippingAddress.data.ambiguous_candidates > 0) {
+     *   console.log('Multiple matches found - user selection required');
+     * }
+     * ```
+     */
+    async usLookup(params) {
+        return this.executeRequest({
+            method: 'GET',
+            path: '/us/lookup',
+            paramsSchema: USLookupParamsSchema,
+            responseSchema: USLookupResponseSchema,
+        }, params);
+    }
+    // Data methods - return data portion only for convenience
+    /**
+     * Get SmartyStreets service health data without full response metadata
+     *
+     * @fullPath api.smartyStreets.healthCheckData.get
+     * @service smarty-streets
+     * @domain system-health
+     * @dataMethod healthCheckData
+     * @discoverable true
+     * @searchTerms ["health data", "service status", "smartystreets availability", "api connectivity"]
+     * @relatedEndpoints ["api.smartyStreets.healthCheck.get", "api.smartyStreets.us.lookup"]
+     * @commonPatterns ["Get health status", "Check API connectivity", "Service monitoring"]
+     * @workflow ["system-monitoring", "health-checks", "service-verification"]
+     * @prerequisites ["Valid authentication token", "x-site-id header"]
+     * @nextSteps ["Use address validation endpoints if healthy", "Monitor service metrics"]
+     * @businessRules ["Returns only health data object", "No response metadata included"]
+     * @functionalArea "system-monitoring"
+     * @caching "No caching - real-time status required"
+     * @performance "Direct data access, faster for simple health checks"
+     *
+     * @param params Health check parameters with site ID
+     * @returns Promise<HealthCheckData> Direct health status data object
+     */
+    async healthCheckData(params) {
+        const response = await this.healthCheck(params);
+        return response.data;
+    }
+    /**
+     * Get SmartyStreets ping data without full response metadata
+     *
+     * @fullPath api.smartyStreets.pingData.get
+     * @service smarty-streets
+     * @domain system-health
+     * @dataMethod pingData
+     * @discoverable true
+     * @searchTerms ["ping data", "connectivity test", "response time", "service latency"]
+     * @relatedEndpoints ["api.smartyStreets.ping.get", "api.smartyStreets.healthCheck.get"]
+     * @commonPatterns ["Get ping response", "Check connectivity", "Measure latency"]
+     * @workflow ["system-monitoring", "connectivity-tests", "performance-monitoring"]
+     * @prerequisites ["Valid authentication token", "x-site-id header"]
+     * @nextSteps ["Use for latency monitoring", "Include in performance dashboards"]
+     * @businessRules ["Returns only ping data object", "No response metadata included"]
+     * @functionalArea "system-monitoring"
+     * @caching "No caching - real-time ping test required"
+     * @performance "Direct data access, optimal for latency monitoring"
+     *
+     * @param params Ping parameters with site ID
+     * @returns Promise<PingData> Direct ping response data object
+     */
+    async pingData(params) {
+        const response = await this.ping(params);
+        return response.data;
+    }
+    /**
+     * Get US address validation data without full response metadata
+     *
+     * @fullPath api.smartyStreets.usLookupData.get
+     * @service smarty-streets
+     * @domain address-validation-and-geocoding
+     * @dataMethod usLookupData
+     * @discoverable true
+     * @searchTerms ["address data", "validation results", "standardized address", "geocoding data", "dpv results"]
+     * @relatedEndpoints ["api.smartyStreets.us.lookup", "api.customers.addresses.create", "api.shipping.rates.calculate"]
+     * @commonPatterns ["Get address validation results", "Extract standardized address", "Process geocoding data"]
+     * @workflow ["address-validation", "customer-onboarding", "checkout-process", "shipping-calculation"]
+     * @prerequisites ["Valid US address components", "Valid authentication token", "SmartyStreets API access"]
+     * @nextSteps ["Use standardized address", "Store validation results", "Calculate shipping rates"]
+     * @businessRules ["Returns only address validation data", "No response metadata included", "Direct access to candidates array"]
+     * @functionalArea "address-validation-and-geocoding"
+     * @caching "Cache validation results for 30 days"
+     * @performance "Direct data access, optimal for address processing and validation workflows"
+     *
+     * @param params Complete US address components for validation
+     * @returns Promise<USLookupData> Direct address validation results without response wrapper
+     */
+    async usLookupData(params) {
+        const response = await this.usLookup(params);
+        return response.data;
+    }
+}
+//# sourceMappingURL=client.js.map

package/dist/esm/services/smarty-streets/client.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"client.js","sourceRoot":"","sources":["../../../../src/services/smarty-streets/client.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,iBAAiB,EAAE,MAAM,wBAAwB,CAAC;AAE3D,OAAO,EACL,uBAAuB,EAEvB,yBAAyB,EAEzB,gBAAgB,EAEhB,kBAAkB,EAElB,oBAAoB,EAEpB,sBAAsB,GAKvB,MAAM,WAAW,CAAC;AAEnB;;;;;;;;;GASG;AACH,MAAM,OAAO,mBAAoB,SAAQ,iBAAiB;IACxD,YAAY,IAAgB,EAAE,OAAgB;QAC5C,KAAK,CAAC,gBAAgB,EAAE,IAAI,EAAE,OAAO,IAAI,sCAAsC,CAAC,CAAC;IACnF,CAAC;IAES,qBAAqB;QAC7B,OAAO,uFAAuF,CAAC;IACjG,CAAC;IAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OAmCG;IACH,KAAK,CAAC,WAAW,CAAC,MAAyB;QACzC,OAAO,IAAI,CAAC,cAAc,CACxB;YACE,MAAM,EAAE,KAAK;YACb,IAAI,EAAE,eAAe;YACrB,YAAY,EAAE,uBAAuB;YACrC,cAAc,EAAE,yBAAyB;SAC1C,EACD,MAAM,CACP,CAAC;IACJ,CAAC;IAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OAkCG;IACH,KAAK,CAAC,IAAI,CAAC,MAAkB;QAC3B,OAAO,IAAI,CAAC,cAAc,CACxB;YACE,MAAM,EAAE,KAAK;YACb,IAAI,EAAE,OAAO;YACb,YAAY,EAAE,gBAAgB;YAC9B,cAAc,EAAE,kBAAkB;SACnC,EACD,MAAM,CACP,CAAC;IACJ,CAAC;IAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OA2EG;IACH,KAAK,CAAC,QAAQ,CAAC,MAAsB;QACnC,OAAO,IAAI,CAAC,cAAc,CACxB;YACE,MAAM,EAAE,KAAK;YACb,IAAI,EAAE,YAAY;YAClB,YAAY,EAAE,oBAAoB;YAClC,cAAc,EAAE,sBAAsB;SACvC,EACD,MAAM,CACP,CAAC;IACJ,CAAC;IAED,0DAA0D;IAE1D;;;;;;;;;;;;;;;;;;;;;OAqBG;IACH,KAAK,CAAC,eAAe,CAAC,MAAyB;QAC7C,MAAM,QAAQ,GAAG,MAAM,IAAI,CAAC,WAAW,CAAC,MAAM,CAAC,CAAC;QAChD,OAAO,QAAQ,CAAC,IAAI,CAAC;IACvB,CAAC;IAED;;;;;;;;;;;;;;;;;;;;;OAqBG;IACH,KAAK,CAAC,QAAQ,CAAC,MAAkB;QAC/B,MAAM,QAAQ,GAAG,MAAM,IAAI,CAAC,IAAI,CAAC,MAAM,CAAC,CAAC;QACzC,OAAO,QAAQ,CAAC,IAAI,CAAC;IACvB,CAAC;IAED;;;;;;;;;;;;;;;;;;;;;OAqBG;IACH,KAAK,CAAC,YAAY,CAAC,MAAsB;QACvC,MAAM,QAAQ,GAAG,MAAM,IAAI,CAAC,QAAQ,CAAC,MAAM,CAAC,CAAC;QAC7C,OAAO,QAAQ,CAAC,IAAI,CAAC;IACvB,CAAC;CACF"}

package/dist/esm/services/smarty-streets/index.d.ts

@@ -0,0 +1,4 @@
+export { SmartyStreetsClient } from './client';
+export type { HealthCheckParams, PingParams, USLookupParams, HealthCheckData, PingData, AddressComponent, AddressMetadata, AddressAnalysis, StandardizedAddress, USLookupResult, USLookupData, HealthCheckResponse, PingResponse, USLookupResponse, } from './schemas';
+export { HealthCheckParamsSchema, PingParamsSchema, USLookupParamsSchema, HealthCheckDataSchema, PingDataSchema, AddressComponentSchema, AddressMetadataSchema, AddressAnalysisSchema, StandardizedAddressSchema, USLookupResultSchema, USLookupDataSchema, HealthCheckResponseSchema, PingResponseSchema, USLookupResponseSchema, } from './schemas';
+//# sourceMappingURL=index.d.ts.map

package/dist/esm/services/smarty-streets/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../src/services/smarty-streets/index.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,mBAAmB,EAAE,MAAM,UAAU,CAAC;AAC/C,YAAY,EACV,iBAAiB,EACjB,UAAU,EACV,cAAc,EACd,eAAe,EACf,QAAQ,EACR,gBAAgB,EAChB,eAAe,EACf,eAAe,EACf,mBAAmB,EACnB,cAAc,EACd,YAAY,EACZ,mBAAmB,EACnB,YAAY,EACZ,gBAAgB,GACjB,MAAM,WAAW,CAAC;AACnB,OAAO,EACL,uBAAuB,EACvB,gBAAgB,EAChB,oBAAoB,EACpB,qBAAqB,EACrB,cAAc,EACd,sBAAsB,EACtB,qBAAqB,EACrB,qBAAqB,EACrB,yBAAyB,EACzB,oBAAoB,EACpB,kBAAkB,EAClB,yBAAyB,EACzB,kBAAkB,EAClB,sBAAsB,GACvB,MAAM,WAAW,CAAC"}

package/dist/esm/services/smarty-streets/index.js

@@ -0,0 +1,4 @@
+// SmartyStreets Service Exports
+export { SmartyStreetsClient } from './client';
+export { HealthCheckParamsSchema, PingParamsSchema, USLookupParamsSchema, HealthCheckDataSchema, PingDataSchema, AddressComponentSchema, AddressMetadataSchema, AddressAnalysisSchema, StandardizedAddressSchema, USLookupResultSchema, USLookupDataSchema, HealthCheckResponseSchema, PingResponseSchema, USLookupResponseSchema, } from './schemas';
+//# sourceMappingURL=index.js.map

package/dist/esm/services/smarty-streets/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../../src/services/smarty-streets/index.ts"],"names":[],"mappings":"AAAA,gCAAgC;AAChC,OAAO,EAAE,mBAAmB,EAAE,MAAM,UAAU,CAAC;AAiB/C,OAAO,EACL,uBAAuB,EACvB,gBAAgB,EAChB,oBAAoB,EACpB,qBAAqB,EACrB,cAAc,EACd,sBAAsB,EACtB,qBAAqB,EACrB,qBAAqB,EACrB,yBAAyB,EACzB,oBAAoB,EACpB,kBAAkB,EAClB,yBAAyB,EACzB,kBAAkB,EAClB,sBAAsB,GACvB,MAAM,WAAW,CAAC"}