@simpleapps-com/augur-api 0.3.0 → 0.3.1

package/dist/cjs/services/ups/client.js

@@ -0,0 +1,243 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.UPSClient = void 0;
+const base_client_1 = require("../../core/base-client");
+const schemas_1 = require("./schemas");
+/**
+ * UPS Shipping Service Client
+ *
+ * Provides comprehensive UPS shipping rate calculation, service comparison,
+ * and shipping cost optimization. Offers detailed UPS service options with
+ * accurate pricing for domestic and international shipments.
+ *
+ * @service ups
+ * @domain shipping-and-logistics
+ */
+class UPSClient extends base_client_1.BaseServiceClient {
+    constructor(http, baseUrl) {
+        super('ups', http, baseUrl || 'https://ups.augur-api.com');
+    }
+    getServiceDescription() {
+        return 'UPS shipping rate calculation and service comparison service';
+    }
+    /**
+     * Check UPS service health and API connectivity
+     *
+     * @fullPath api.ups.healthCheck.get
+     * @service ups
+     * @domain system-health
+     * @dataMethod healthCheckData
+     * @discoverable true
+     * @searchTerms ["health", "status", "availability", "ping", "check", "ups service", "shipping", "carriers"]
+     * @relatedEndpoints ["api.ups.ratesShop.get", "api.shipping.healthCheck.get", "api.logistics.healthCheck.get", "api.commerce.healthCheck.get"]
+     * @commonPatterns ["Health check", "Service status", "UPS service availability", "System monitoring", "Carrier connectivity"]
+     * @workflow ["system-monitoring", "health-checks", "service-discovery", "ups-service-verification", "carrier-status-check"]
+     * @prerequisites ["Service is running", "Valid authentication token", "x-site-id header", "UPS API connectivity"]
+     * @nextSteps ["Use UPS rate endpoints if healthy", "Verify UPS API connectivity", "Monitor UPS service metrics"]
+     * @businessRules ["Returns service and UPS 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 UPS service monitoring"
+     *
+     * @param params Health check parameters with site ID
+     * @returns Promise<HealthCheckResponse> Service health status with UPS API connectivity
+     *
+     * @example
+     * ```typescript
+     * // Check if UPS service is healthy
+     * const response = await client.healthCheck({ 'x-site-id': 'SITE123' });
+     * console.log(response.data.status); // 'healthy'
+     * console.log(response.data.service); // 'ups'
+     * console.log(response.data.ups_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: schemas_1.HealthCheckParamsSchema,
+            responseSchema: schemas_1.HealthCheckResponseSchema,
+        }, params);
+    }
+    /**
+     * Shop UPS shipping rates for packages with comprehensive service options
+     *
+     * @fullPath api.ups.ratesShop.get
+     * @service ups
+     * @domain shipping-and-logistics
+     * @dataMethod ratesShopData
+     * @discoverable true
+     * @searchTerms ["ups rates", "shipping cost", "ups pricing", "package shipping", "ups quotes", "delivery cost", "ground", "air", "next day", "2-day", "3-day", "international"]
+     * @relatedEndpoints ["api.shipping.rates.calculate", "api.logistics.speedship.freight.get", "api.commerce.cart.shipping.calculate", "api.orders.shipping.estimate", "api.customers.addresses.validate"]
+     * @commonPatterns ["Calculate UPS shipping cost", "Compare UPS services", "Get UPS delivery options", "Estimate UPS shipping", "Find cheapest UPS option", "Get fastest UPS delivery"]
+     * @workflow ["e-commerce-checkout", "order-fulfillment", "shipping-estimation", "ups-rate-comparison", "carrier-selection", "delivery-planning", "shipping-cost-analysis"]
+     * @prerequisites ["Valid shipping addresses", "Package weight specified", "Valid authentication token", "x-site-id header", "UPS API access", "Complete address information"]
+     * @nextSteps ["Select UPS service option", "Create UPS shipping label", "Track UPS shipment", "Update order with UPS shipping cost", "Process payment with UPS shipping"]
+     * @businessRules ["Requires origin and destination addresses", "Package weight is mandatory", "Supports single package shipments", "Returns UPS-specific rates and services", "Includes all UPS fees and surcharges", "Respects UPS service area limitations"]
+     * @functionalArea "shipping-and-logistics"
+     * @crossSite "Supports multi-site UPS configurations and different UPS accounts per site"
+     * @caching "Cache UPS rates for 15 minutes, invalidate on address or package changes"
+     * @performance "Single UPS API call, optimized for UPS rate shopping, supports edge caching with cacheSiteId parameter"
+     *
+     * @param params Complete UPS rate shopping request with addresses and package information
+     * @returns Promise<RatesShopResponse> UPS shipping rates with service options and delivery information
+     *
+     * @example
+     * ```typescript
+     * // Calculate UPS rates for e-commerce order
+     * const upsRateRequest = {
+     *   // Origin address (warehouse/fulfillment center)
+     *   fromAddress1: '123 Warehouse Blvd',
+     *   fromCity: 'Los Angeles',
+     *   fromStateProvinceCode: 'CA',
+     *   fromPostalCode: '90210',
+     *   fromCountryCode: 'US',
+     *
+     *   // Customer delivery address
+     *   toAddress1: '456 Customer St',
+     *   toCity: 'New York',
+     *   toStateProvinceCode: 'NY',
+     *   toPostalCode: '10001',
+     *   toCountryCode: 'US',
+     *
+     *   // Package information (required)
+     *   weight: 5, // pounds
+     *
+     *   // Optional caching for performance
+     *   cacheSiteId: 'ECOMMERCE-SITE',
+     *   'x-site-id': 'SITE123'
+     * };
+     *
+     * const response = await client.ratesShop(upsRateRequest);
+     * console.log(response.data.rates); // Array of UPS shipping rates
+     * console.log(response.data.cheapest_rate); // Most economical option
+     * console.log(response.data.fastest_rate); // Quickest delivery option
+     * console.log(response.status); // HTTP status code
+     *
+     * // Get just the rates data
+     * const ratesData = await client.ratesShopData(upsRateRequest);
+     * console.log(ratesData); // Direct UPS rates data access
+     *
+     * // Find ground shipping options
+     * const groundRates = await client.ratesShop({
+     *   ...upsRateRequest,
+     *   // UPS will return available ground services
+     * });
+     *
+     * // International UPS shipping
+     * const internationalRates = await client.ratesShop({
+     *   fromAddress1: '123 US Warehouse',
+     *   fromCity: 'Los Angeles',
+     *   fromStateProvinceCode: 'CA',
+     *   fromPostalCode: '90210',
+     *   fromCountryCode: 'US',
+     *
+     *   toAddress1: '456 International St',
+     *   toCity: 'Toronto',
+     *   toStateProvinceCode: 'ON',
+     *   toPostalCode: 'M5V 3A8',
+     *   toCountryCode: 'CA',
+     *
+     *   weight: 10,
+     *   'x-site-id': 'SITE123'
+     * });
+     *
+     * // Heavy package UPS rates
+     * const heavyPackageRates = await client.ratesShop({
+     *   ...upsRateRequest,
+     *   weight: 50, // 50 pounds
+     * });
+     *
+     * // Use cached rates for performance
+     * const cachedRates = await client.ratesShop({
+     *   ...upsRateRequest,
+     *   cacheSiteId: 'HIGH-VOLUME-SITE', // Enable edge caching
+     * });
+     *
+     * // Handle UPS rate selection
+     * if (ratesData.rates && ratesData.rates.length > 0) {
+     *   const selectedRate = ratesData.cheapest_rate;
+     *   console.log('Selected UPS Service:', selectedRate?.service_name);
+     *   console.log('Cost:', selectedRate?.total_charges);
+     *   console.log('Delivery Date:', selectedRate?.delivery_date);
+     *   console.log('Business Days:', selectedRate?.business_days_in_transit);
+     * }
+     *
+     * // Extract service-specific information
+     * if (ratesData.services_available) {
+     *   console.log('Available UPS Services:');
+     *   ratesData.services_available.forEach(service => {
+     *     console.log(`- ${service.name}: ${service.description}`);
+     *   });
+     * }
+     * ```
+     */
+    async ratesShop(params) {
+        return this.executeRequest({
+            method: 'GET',
+            path: '/rates-shop',
+            paramsSchema: schemas_1.RatesShopParamsSchema,
+            responseSchema: schemas_1.RatesShopResponseSchema,
+        }, params);
+    }
+    // Data methods - return data portion only for convenience
+    /**
+     * Get UPS service health data without full response metadata
+     *
+     * @fullPath api.ups.healthCheckData.get
+     * @service ups
+     * @domain system-health
+     * @dataMethod healthCheckData
+     * @discoverable true
+     * @searchTerms ["health data", "service status", "ups availability", "api connectivity"]
+     * @relatedEndpoints ["api.ups.healthCheck.get", "api.ups.ratesShop.get"]
+     * @commonPatterns ["Get health status", "Check UPS API connectivity", "Service monitoring"]
+     * @workflow ["system-monitoring", "health-checks", "service-verification"]
+     * @prerequisites ["Valid authentication token", "x-site-id header"]
+     * @nextSteps ["Use UPS endpoints if healthy", "Monitor UPS 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 UPS shipping rates data without full response metadata
+     *
+     * @fullPath api.ups.ratesShopData.get
+     * @service ups
+     * @domain shipping-and-logistics
+     * @dataMethod ratesShopData
+     * @discoverable true
+     * @searchTerms ["ups rates data", "shipping cost data", "ups pricing data", "delivery quotes", "carrier rates"]
+     * @relatedEndpoints ["api.ups.ratesShop.get", "api.shipping.rates.calculate", "api.commerce.cart.shipping.calculate"]
+     * @commonPatterns ["Get UPS rates data", "Calculate UPS shipping cost", "Compare UPS service options", "Extract UPS pricing"]
+     * @workflow ["e-commerce-checkout", "order-fulfillment", "shipping-estimation", "ups-rate-analysis"]
+     * @prerequisites ["Valid shipping addresses", "Package weight", "Valid authentication token", "UPS API access"]
+     * @nextSteps ["Select UPS service option", "Create UPS shipping label", "Process payment with UPS cost"]
+     * @businessRules ["Returns only UPS rates data", "No response metadata included", "Direct access to rate comparison"]
+     * @functionalArea "shipping-and-logistics"
+     * @caching "Cache UPS rates for 15 minutes"
+     * @performance "Direct data access, optimal for UPS rate comparisons and e-commerce integrations"
+     *
+     * @param params Complete UPS rate shopping request parameters
+     * @returns Promise<RatesShopData> Direct UPS shipping rates data without response wrapper
+     */
+    async ratesShopData(params) {
+        const response = await this.ratesShop(params);
+        return response.data;
+    }
+}
+exports.UPSClient = UPSClient;
+//# sourceMappingURL=client.js.map

package/dist/cjs/services/ups/client.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"client.js","sourceRoot":"","sources":["../../../../src/services/ups/client.ts"],"names":[],"mappings":";;;AAAA,wDAA2D;AAE3D,uCAWmB;AAEnB;;;;;;;;;GASG;AACH,MAAa,SAAU,SAAQ,+BAAiB;IAC9C,YAAY,IAAgB,EAAE,OAAgB;QAC5C,KAAK,CAAC,KAAK,EAAE,IAAI,EAAE,OAAO,IAAI,2BAA2B,CAAC,CAAC;IAC7D,CAAC;IAES,qBAAqB;QAC7B,OAAO,8DAA8D,CAAC;IACxE,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,iCAAuB;YACrC,cAAc,EAAE,mCAAyB;SAC1C,EACD,MAAM,CACP,CAAC;IACJ,CAAC;IAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OAgHG;IACH,KAAK,CAAC,SAAS,CAAC,MAAuB;QACrC,OAAO,IAAI,CAAC,cAAc,CACxB;YACE,MAAM,EAAE,KAAK;YACb,IAAI,EAAE,aAAa;YACnB,YAAY,EAAE,+BAAqB;YACnC,cAAc,EAAE,iCAAuB;SACxC,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,aAAa,CAAC,MAAuB;QACzC,MAAM,QAAQ,GAAG,MAAM,IAAI,CAAC,SAAS,CAAC,MAAM,CAAC,CAAC;QAC9C,OAAO,QAAQ,CAAC,IAAI,CAAC;IACvB,CAAC;CACF;AA7OD,8BA6OC"}

package/dist/cjs/services/ups/index.d.ts

@@ -0,0 +1,4 @@
+export { UPSClient } from './client';
+export type { HealthCheckParams, RatesShopParams, HealthCheckData, UPSService, UPSRate, BillingWeight, UPSPackage, RatesShopData, HealthCheckResponse, RatesShopResponse, } from './schemas';
+export { HealthCheckParamsSchema, RatesShopParamsSchema, HealthCheckDataSchema, UPSServiceSchema, UPSRateSchema, BillingWeightSchema, UPSPackageSchema, RatesShopDataSchema, HealthCheckResponseSchema, RatesShopResponseSchema, } from './schemas';
+//# sourceMappingURL=index.d.ts.map

package/dist/cjs/services/ups/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../src/services/ups/index.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,SAAS,EAAE,MAAM,UAAU,CAAC;AACrC,YAAY,EACV,iBAAiB,EACjB,eAAe,EACf,eAAe,EACf,UAAU,EACV,OAAO,EACP,aAAa,EACb,UAAU,EACV,aAAa,EACb,mBAAmB,EACnB,iBAAiB,GAClB,MAAM,WAAW,CAAC;AACnB,OAAO,EACL,uBAAuB,EACvB,qBAAqB,EACrB,qBAAqB,EACrB,gBAAgB,EAChB,aAAa,EACb,mBAAmB,EACnB,gBAAgB,EAChB,mBAAmB,EACnB,yBAAyB,EACzB,uBAAuB,GACxB,MAAM,WAAW,CAAC"}

package/dist/cjs/services/ups/index.js

@@ -0,0 +1,18 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.RatesShopResponseSchema = exports.HealthCheckResponseSchema = exports.RatesShopDataSchema = exports.UPSPackageSchema = exports.BillingWeightSchema = exports.UPSRateSchema = exports.UPSServiceSchema = exports.HealthCheckDataSchema = exports.RatesShopParamsSchema = exports.HealthCheckParamsSchema = exports.UPSClient = void 0;
+// UPS Service Exports
+var client_1 = require("./client");
+Object.defineProperty(exports, "UPSClient", { enumerable: true, get: function () { return client_1.UPSClient; } });
+var schemas_1 = require("./schemas");
+Object.defineProperty(exports, "HealthCheckParamsSchema", { enumerable: true, get: function () { return schemas_1.HealthCheckParamsSchema; } });
+Object.defineProperty(exports, "RatesShopParamsSchema", { enumerable: true, get: function () { return schemas_1.RatesShopParamsSchema; } });
+Object.defineProperty(exports, "HealthCheckDataSchema", { enumerable: true, get: function () { return schemas_1.HealthCheckDataSchema; } });
+Object.defineProperty(exports, "UPSServiceSchema", { enumerable: true, get: function () { return schemas_1.UPSServiceSchema; } });
+Object.defineProperty(exports, "UPSRateSchema", { enumerable: true, get: function () { return schemas_1.UPSRateSchema; } });
+Object.defineProperty(exports, "BillingWeightSchema", { enumerable: true, get: function () { return schemas_1.BillingWeightSchema; } });
+Object.defineProperty(exports, "UPSPackageSchema", { enumerable: true, get: function () { return schemas_1.UPSPackageSchema; } });
+Object.defineProperty(exports, "RatesShopDataSchema", { enumerable: true, get: function () { return schemas_1.RatesShopDataSchema; } });
+Object.defineProperty(exports, "HealthCheckResponseSchema", { enumerable: true, get: function () { return schemas_1.HealthCheckResponseSchema; } });
+Object.defineProperty(exports, "RatesShopResponseSchema", { enumerable: true, get: function () { return schemas_1.RatesShopResponseSchema; } });
+//# sourceMappingURL=index.js.map

package/dist/cjs/services/ups/index.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../../src/services/ups/index.ts"],"names":[],"mappings":";;;AAAA,sBAAsB;AACtB,mCAAqC;AAA5B,mGAAA,SAAS,OAAA;AAalB,qCAWmB;AAVjB,kHAAA,uBAAuB,OAAA;AACvB,gHAAA,qBAAqB,OAAA;AACrB,gHAAA,qBAAqB,OAAA;AACrB,2GAAA,gBAAgB,OAAA;AAChB,wGAAA,aAAa,OAAA;AACb,8GAAA,mBAAmB,OAAA;AACnB,2GAAA,gBAAgB,OAAA;AAChB,8GAAA,mBAAmB,OAAA;AACnB,oHAAA,yBAAyB,OAAA;AACzB,kHAAA,uBAAuB,OAAA"}