@simpleapps-com/augur-api
Version:
TypeScript client library for Augur microservices API endpoints
139 lines • 7.62 kB
JavaScript
import { UsLookupParamsSchema, UsLookupResponseSchema } from '../schemas';
/**
* Creates the us resource methods
* OpenAPI Path: /us/* → us.*
* @description US address validation and standardization endpoints
*/
export function createUsResource(executeRequest) {
return {
/**
* Lookup operations for /us/lookup endpoint
* Following OpenAPI Path Mirroring Pattern
*/
lookup: {
/**
* Validate and standardize US addresses using SmartyStreets API
*
* @fullPath api.smartyStreets.us.lookup.get
* @service smarty-streets
* @domain address-validation-and-geocoding
* @dataMethod usData.lookup.get
* @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.us.lookup.get(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.usData.lookup.get(addressRequest);
* console.log(validationResult); // Direct validation results
*
* // Validate shipping address for e-commerce
* const shippingAddress = await client.us.lookup.get({
* 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');
* }
* ```
*/
get: async (params) => {
return executeRequest({
method: 'GET',
path: '/us/lookup',
paramsSchema: UsLookupParamsSchema,
responseSchema: UsLookupResponseSchema,
}, params);
},
},
};
}
/**
* Creates the usData resource methods (data-only versions)
*/
export function createUsDataResource(us) {
return {
/**
* Lookup operations for /us/lookup endpoint (data-only)
*/
lookup: {
/**
* Get US address validation data without full response metadata
*
* @fullPath api.smartyStreets.us.lookup.getData
* @service smarty-streets
* @domain address-validation-and-geocoding
* @dataMethod us.lookup.getData
* @discoverable true
* @searchTerms ["address data", "validation results", "standardized address", "geocoding data", "dpv results"]
* @relatedEndpoints ["api.smartyStreets.us.lookup.get", "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
*/
get: async (params) => {
const response = await us.lookup.get(params);
return response.data;
},
},
};
}
//# sourceMappingURL=us.js.map