UNPKG

@simpleapps-com/augur-api

Version:

TypeScript client library for Augur microservices API endpoints

678 lines 35.5 kB
"use strict"; Object.defineProperty(exports, "__esModule", { value: true }); exports.CommerceClient = void 0; const base_client_1 = require("../../core/base-client"); const schemas_1 = require("./schemas"); /** * Commerce API Client * @description Client for interacting with Commerce microservice API endpoints for e-commerce operations * @example * ```typescript * import { HTTPClient } from '@augur/api-client/core'; * import { CommerceClient } from '@augur/api-client/services/commerce'; * * const http = new HTTPClient('commerce', { siteId: 'your-site-id', bearerToken: 'your-token' }); * const commerce = new CommerceClient(http); * * // Create or lookup cart * const cart = await commerce.cartHeaders.lookup({ userId: 12345, customerId: 456, contactId: 123 }); * * // Add items to cart * await commerce.cartLines.add(cart.cartHdrUid, [{ invMastUid: 12345, quantity: 2, unitOfMeasure: 'EA' }]); * * // Create checkout * const checkout = await commerce.checkout.create({ customer: {...}, payment: {...}, lineItems: [...] }); * ``` */ class CommerceClient extends base_client_1.BaseServiceClient { /** * Create a new CommerceClient instance * @param http Configured HTTPClient instance * @param baseUrl Base URL for the Commerce API (default: https://commerce.augur-api.com) */ constructor(http, baseUrl = 'https://commerce.augur-api.com') { super('commerce', http, baseUrl); /** * Cart Header endpoints * @description Methods for shopping cart session management with user tracking and cart tokens */ this.cartHeaders = { /** * Retrieve a list of cart headers for a specific user * * @fullPath api.commerce.cartHeaders.list * @service commerce * @domain cart-management * @dataMethod listData * @discoverable true * @searchTerms ["cart", "list", "shopping cart", "user carts", "cart headers", "session", "baskets"] * @relatedEndpoints ["api.commerce.cartLines.get", "api.commerce.cartHeaders.lookup", "api.customers.customer.list", "api.joomla.users.list"] * @commonPatterns ["Get all user carts", "List shopping carts", "Find user sessions", "Shopping cart history"] * @workflow ["cart-management", "session-tracking", "user-cart-retrieval"] * @prerequisites ["Valid authentication token", "Valid user ID", "Cart management permissions"] * @nextSteps ["api.commerce.cartLines.get for cart contents", "api.commerce.cartHeaders.lookup for specific cart"] * @businessRules ["Returns only carts accessible to current user", "Respects user permissions", "Includes abandoned carts"] * @functionalArea "cart-and-session-management" * @caching "Cache for 2 minutes, invalidate on cart changes" * @performance "Lightweight operation, pagination not required for typical usage" * * @description Returns all cart headers associated with a user ID for session management and cart recovery * @param params User ID for filtering cart headers * @returns Promise<BaseResponse<CartHdr[]>> Complete response with cart headers array and metadata * @throws ValidationError When parameters are invalid or response is malformed * * @example * ```typescript * // Get all carts for a user * const response = await client.cartHeaders.list({ userId: 12345 }); * console.log(response.data); // CartHdr[] * * // Get just the data array * const carts = await client.cartHeaders.listData({ userId: 12345 }); * carts.forEach(cart => console.log(cart.cartHdrUid, cart.cartToken)); * ``` */ list: this.createListMethod('/cart-hdr/list', schemas_1.CartHdrListParamsSchema, schemas_1.CartHdrListResponseSchema), /** * Lookup an existing cart or create a new one * * @fullPath api.commerce.cartHeaders.lookup * @service commerce * @domain cart-management * @dataMethod lookupData * @discoverable true * @searchTerms ["cart lookup", "find cart", "get cart", "cart token", "shopping cart", "user cart", "session cart"] * @relatedEndpoints ["api.commerce.cartHeaders.list", "api.commerce.cartLines.get", "api.customers.customer.get", "api.joomla.users.get"] * @commonPatterns ["Find user's active cart", "Get or create cart", "Resume shopping session", "Cart token validation"] * @workflow ["cart-retrieval", "session-management", "cart-creation"] * @prerequisites ["Valid authentication token", "Valid user, customer, and contact IDs"] * @nextSteps ["api.commerce.cartLines.get for cart contents", "api.commerce.cartLines.add to add items"] * @businessRules ["Creates new cart if none exists", "Returns existing cart if found", "Validates user permissions"] * @functionalArea "cart-and-session-management" * @caching "Cache for 5 minutes, invalidate on cart modifications" * @performance "Fast lookup operation, includes cart creation logic" * * @description Looks up an existing cart or creates a new one for the specified user, customer, and contact * @param params User, customer, and contact identifiers with optional cart token * @returns Promise<BaseResponse<CartHdr>> Complete response with cart header details and metadata * @throws ValidationError When parameters are invalid or response is malformed * * @example * ```typescript * // Lookup existing cart * const response = await client.cartHeaders.lookup({ * userId: 12345, * customerId: 456, * contactId: 123, * cartToken: 'abc123' * }); * console.log(response.data.cartHdrUid); * * // Create new cart (data method) * const cart = await client.cartHeaders.lookupData({ * userId: 12345, * customerId: 456, * contactId: 123 * }); * ``` */ lookup: async (params) => { return this.executeRequest({ method: 'GET', path: '/cart-hdr/lookup', paramsSchema: schemas_1.CartHdrLookupParamsSchema, responseSchema: schemas_1.CartHdrLookupResponseSchema, }, params); }, /** * Get product recommendations based on cart contents * * @fullPath api.commerce.cartHeaders.getAlsoBought * @service commerce * @domain recommendation-engine * @dataMethod getAlsoBoughtData * @discoverable true * @searchTerms ["recommendations", "also bought", "cross sell", "upsell", "related products", "suggestions", "shopping recommendations"] * @relatedEndpoints ["api.commerce.cartLines.get", "api.items.products.list", "api.legacy.alsoBought.list"] * @commonPatterns ["Get product recommendations", "Cross-sell products", "Increase cart value", "Related item suggestions"] * @workflow ["recommendation-display", "cross-selling", "cart-enhancement"] * @prerequisites ["Valid cart header UID", "Cart with existing items for best recommendations"] * @nextSteps ["api.commerce.cartLines.add to add recommended items", "api.items.products.get for product details"] * @businessRules ["Based on purchase history patterns", "Respects inventory availability", "Paginated results for performance"] * @functionalArea "recommendation-and-cross-sell" * @caching "Cache for 30 minutes, static recommendation data" * @performance "Supports pagination with limit/offset, optimized for recommendation engine" * * @description Retrieves also-bought product recommendations based on items currently in the cart * @param cartHdrUid Cart header unique identifier * @param params Optional pagination parameters (limit, offset) * @returns Promise<BaseResponse<AlsoBoughtItem[]>> Complete response with recommended products and pagination metadata * @throws ValidationError When parameters are invalid or response is malformed * * @example * ```typescript * // Get recommendations with pagination * const response = await client.cartHeaders.getAlsoBought(789, { limit: 5, offset: 0 }); * console.log(`Found ${response.total} recommendations, showing ${response.count}`); * response.data.forEach(item => console.log(item.itemId, item.description, item.price)); * * // Get just the data array * const recommendations = await client.cartHeaders.getAlsoBoughtData(789, { limit: 10 }); * ``` */ getAlsoBought: async (cartHdrUid, params) => { return this.executeRequest({ method: 'GET', path: '/cart-hdr/{cartHdrUid}/also-bought', paramsSchema: schemas_1.AlsoBoughtParamsSchema, responseSchema: schemas_1.AlsoBoughtResponseSchema, }, params, { cartHdrUid: String(cartHdrUid) }); }, /** * Get list of cart headers (data only) * @description Data-only version of list method - returns just the cart headers array * @param params User ID for filtering cart headers * @returns Array of cart headers for the user */ listData: async (params) => { const response = await this.cartHeaders.list(params); return response.data; }, /** * Lookup cart header (data only) * @description Data-only version of lookup method - returns just the cart header object * @param params User, customer, and contact identifiers with optional cart token * @returns Cart header details */ lookupData: async (params) => { const response = await this.cartHeaders.lookup(params); return response.data; }, /** * Get also bought recommendations (data only) * @description Data-only version of getAlsoBought method - returns just the recommendations array * @param cartHdrUid Cart header unique identifier * @param params Optional pagination parameters * @returns Array of recommended products */ getAlsoBoughtData: async (cartHdrUid, params) => { const response = await this.cartHeaders.getAlsoBought(cartHdrUid, params); return response.data; }, }; /** * Cart Line endpoints * @description Methods for managing individual line items within shopping carts */ this.cartLines = { /** * Retrieve all line items for a specific cart * * @fullPath api.commerce.cartLines.get * @service commerce * @domain cart-management * @dataMethod getData * @discoverable true * @searchTerms ["cart lines", "cart items", "line items", "cart contents", "shopping cart items", "cart products"] * @relatedEndpoints ["api.commerce.cartHeaders.lookup", "api.items.products.get", "api.commerce.cartLines.add", "api.commerce.cartLines.update"] * @commonPatterns ["View cart contents", "Get cart line items", "Display shopping cart", "Cart item details"] * @workflow ["cart-display", "cart-review", "checkout-preparation"] * @prerequisites ["Valid cart header UID", "Cart must exist"] * @nextSteps ["api.commerce.cartLines.update to modify items", "api.commerce.checkout.create to proceed to checkout"] * @businessRules ["Returns all line items in cart", "Includes product details and pricing", "Ordered by line number"] * @functionalArea "cart-and-session-management" * @caching "Cache for 2 minutes, invalidate on cart modifications" * @performance "Fast retrieval, includes product joins for display" * * @description Returns all line items in a cart with product details, quantities, and pricing * @param cartHdrUid Cart header unique identifier * @returns Promise<BaseResponse<CartLine[]>> Complete response with cart line items and metadata * @throws ValidationError When response is malformed * * @example * ```typescript * // Get cart line items * const response = await client.cartLines.get(789); * response.data.forEach(line => { * console.log(`Line ${line.lineNo}: ${line.quantity} x ${line.itemId} @ $${line.unitPrice}`); * }); * * // Get just the data array * const lines = await client.cartLines.getData(789); * ``` */ get: this.createGetMethod('/cart-line/{cartHdrUid}', schemas_1.CartLineListResponseSchema), /** * Add one or more items to the cart * * @fullPath api.commerce.cartLines.add * @service commerce * @domain cart-management * @dataMethod addData * @discoverable true * @searchTerms ["add to cart", "cart add", "add items", "shopping cart add", "add products", "cart line add"] * @relatedEndpoints ["api.commerce.cartLines.get", "api.commerce.cartLines.update", "api.items.products.get", "api.pricing.pricing.calculate"] * @commonPatterns ["Add item to cart", "Add multiple items", "Bulk add to cart", "Shopping cart addition"] * @workflow ["product-to-cart", "shopping-flow", "cart-building"] * @prerequisites ["Valid cart header UID", "Valid product inventory UIDs", "Items must be available"] * @nextSteps ["api.commerce.cartLines.get to view updated cart", "api.commerce.checkout.create to proceed to checkout"] * @businessRules ["Aggregates quantities for duplicate items", "Validates inventory availability", "Applies pricing rules"] * @functionalArea "cart-and-session-management" * @caching "No caching, immediate cart modification" * @performance "Batch operation for multiple items, validates inventory in bulk" * * @description Adds line items to the shopping cart with automatic quantity aggregation for matching items * @param cartHdrUid Cart header unique identifier * @param items Array of cart line items to add * @returns Promise<BaseResponse<boolean>> Complete response with success status and metadata * @throws ValidationError When request is invalid or response is malformed * * @example * ```typescript * // Add multiple items to cart * const response = await client.cartLines.add(789, [ * { * invMastUid: 12345, * quantity: 2.0, * unitOfMeasure: 'EA', * lineNote: 'Rush order', * unitPrice: 29.99 * }, * { * invMastUid: 67890, * quantity: 1.0, * unitOfMeasure: 'LB' * } * ]); * * // Get just the success boolean * const success = await client.cartLines.addData(789, items); * ``` */ add: async (cartHdrUid, items) => { return this.executeRequest({ method: 'POST', path: '/cart-line/{cartHdrUid}/add', paramsSchema: schemas_1.CartLineAddRequestSchema, responseSchema: schemas_1.CartLineModifyResponseSchema, }, items, { cartHdrUid: String(cartHdrUid) }); }, /** * Update quantities or details for existing cart line items * @description Updates existing line items in the cart with new quantities, notes, or other modifications * @param cartHdrUid Cart header unique identifier * @param items Array of cart line items to update (must specify lineNo or key for identification) * @returns Boolean indicating successful update * @throws ValidationError When request is invalid or response is malformed * @example * ```typescript * const success = await client.cartLines.update(789, [ * { * lineNo: 1, * quantity: 5.0, * lineNote: 'Updated quantity to 5' * }, * { * key: 'unique-key-123', * quantity: 3.0 * } * ]); * ``` */ update: async (cartHdrUid, items) => { return this.executeRequest({ method: 'POST', path: '/cart-line/{cartHdrUid}/update', paramsSchema: schemas_1.CartLineUpdateRequestSchema, responseSchema: schemas_1.CartLineModifyResponseSchema, }, items, { cartHdrUid: String(cartHdrUid) }); }, /** * Remove all line items from the cart * @description Clears all line items from the specified cart, leaving the cart header intact * @param cartHdrUid Cart header unique identifier * @returns Boolean indicating successful clearing of cart * @throws ValidationError When response is malformed * @example * ```typescript * const success = await client.cartLines.clear(789); * if (success) { * console.log('Cart has been cleared of all items'); * } * ``` */ clear: this.createDeleteMethod('/cart-line/{cartHdrUid}', schemas_1.CartLineModifyResponseSchema), /** * Remove a specific line item from the cart * @description Removes a single line item from the cart by line number * @param cartHdrUid Cart header unique identifier * @param lineNo Line number to delete * @returns Boolean indicating successful deletion * @throws ValidationError When response is malformed * @example * ```typescript * const success = await client.cartLines.deleteLine(789, 1); * if (success) { * console.log('Line item 1 has been removed from cart'); * } * ``` */ deleteLine: async (cartHdrUid, lineNo) => { return this.executeRequest({ method: 'DELETE', path: '/cart-line/{cartHdrUid}/lines/{lineNo}', responseSchema: schemas_1.CartLineDeleteResponseSchema, }, undefined, { cartHdrUid: String(cartHdrUid), lineNo: String(lineNo) }); }, // Data-only methods for cart lines /** * Get cart line items (data only) * @description Returns only the data array from cart line items response * @param cartHdrUid Cart header unique identifier * @returns Array of cart line items (data only) * @throws ValidationError When response is malformed */ getData: async (cartHdrUid) => { const response = await this.cartLines.get(cartHdrUid); return response.data; }, /** * Add items to cart (data only) * @description Returns only the data from cart line addition response * @param cartHdrUid Cart header unique identifier * @param items Array of cart line items to add * @returns Addition result (data only) * @throws ValidationError When request is invalid or response is malformed */ addData: async (cartHdrUid, items) => { const response = await this.cartLines.add(cartHdrUid, items); return response.data; }, /** * Update cart line items (data only) * @description Returns only the data from cart line update response * @param cartHdrUid Cart header unique identifier * @param items Array of cart line items to update * @returns Update result (data only) * @throws ValidationError When request is invalid or response is malformed */ updateData: async (cartHdrUid, items) => { const response = await this.cartLines.update(cartHdrUid, items); return response.data; }, /** * Clear all cart line items (data only) * @description Returns only the data from cart clear response * @param cartHdrUid Cart header unique identifier * @returns Clear result (data only) * @throws ValidationError When response is malformed */ clearData: async (cartHdrUid) => { const response = await this.cartLines.clear(cartHdrUid); return response.data; }, /** * Delete specific cart line item (data only) * @description Returns only the data from cart line deletion response * @param cartHdrUid Cart header unique identifier * @param lineNo Line number to delete * @returns Deletion result (data only) * @throws ValidationError When response is malformed */ deleteLineData: async (cartHdrUid, lineNo) => { const response = await this.cartLines.deleteLine(cartHdrUid, lineNo); return response.data; }, }; /** * Checkout endpoints * @description Methods for end-to-end checkout processing with Prophet21 ERP integration */ this.checkout = { /** * Create a new checkout session * @description Creates a new checkout with complete order data including customer, payment, and line items * @param orderData Complete checkout data with customer information, payment details, and line items * @returns Created checkout with unique identifiers and status * @throws ValidationError When request is invalid or response is malformed * @example * ```typescript * const checkout = await client.checkout.create({ * customer: { * customerId: 456, * contactId: 123, * billToName: 'John Doe', * billToAddress1: '123 Main St', * billToCity: 'Anytown', * billToState: 'CA', * billToZip: '12345', * billToCountry: 'US', * shipToName: 'John Doe', * shipToAddress1: '123 Main St', * shipToCity: 'Anytown', * shipToState: 'CA', * shipToZip: '12345', * shipToCountry: 'US' * }, * payment: { * paymentType: 'CC', * cardNumber: '4111111111111111', * expirationDate: '12/25', * cvv: '123', * cardHolderName: 'John Doe' * }, * lineItems: [ * { invMastUid: 12345, quantity: 2, unitOfMeasure: 'EA', unitPrice: 29.99 } * ] * }); * ``` */ create: this.createCreateMethod('/checkout', schemas_1.CheckoutCreateRequestSchema, schemas_1.CheckoutCreateResponseSchema), /** * Get checkout details by ID * @description Retrieves complete details for a specific checkout including all order data * @param checkoutUid Checkout unique identifier * @returns Complete checkout details with order data and processing status * @throws ValidationError When response is malformed * @example * ```typescript * const checkout = await client.checkout.get(12345); * console.log('Checkout:', checkout.checkoutUid, 'Status:', checkout.statusCd); * console.log('Created:', checkout.dateCreated, 'Type:', checkout.checkoutType); * ``` */ get: this.createGetMethod('/checkout/{checkoutUid}', schemas_1.CheckoutGetResponseSchema), /** * Get formatted checkout document * @description Retrieves the formatted checkout document/receipt for display or printing * @param checkoutUid Checkout unique identifier * @param params Optional parameters including associated cart header UID * @returns Raw checkout document response * @throws ValidationError When response is malformed * @example * ```typescript * const doc = await client.checkout.getDoc(12345, { cartHdrUid: 789 }); * // Process or display the formatted document * ``` */ getDoc: async (checkoutUid, params) => { // Return raw response for document endpoint const response = await this.http.get(`${this.baseUrl}/checkout/${checkoutUid}/doc`, params ? schemas_1.CheckoutDocParamsSchema.parse(params) : undefined); return response; }, /** * Validate checkout data * @description Validates checkout data without processing payment or creating orders in Prophet21 * @param checkoutUid Checkout unique identifier * @returns Validation results with status, errors, and warnings * @throws ValidationError When response is malformed * @example * ```typescript * const validation = await client.checkout.validate(12345); * if (validation.data.validationResults?.isValid) { * console.log('Checkout is valid and ready for activation'); * } else { * console.log('Validation errors:', validation.data.validationResults?.errors); * } * ``` */ validate: this.createActionMethod('/checkout/{checkoutUid}/validate', 'PUT', schemas_1.CheckoutValidateResponseSchema), /** * Activate and process checkout * @description Activates the checkout, processes payment, and creates orders in Prophet21 ERP system * @param checkoutUid Checkout unique identifier * @returns Activated checkout details with updated status * @throws ValidationError When response is malformed * @example * ```typescript * const result = await client.checkout.activate(12345); * if (result.data.statusCd === 710) { * console.log('Checkout successfully activated and processed'); * } * ``` */ activate: this.createActionMethod('/checkout/{checkoutUid}/activate', 'PUT', schemas_1.CheckoutActivateResponseSchema), /** * Create Prophet21 checkout header * @description Creates Prophet21-specific checkout header for ERP integration (partially implemented) * @param checkoutUid Checkout unique identifier * @returns Prophet21 header creation result * @throws ValidationError When response is malformed * @example * ```typescript * const p21Header = await client.checkout.createProphet21Hdr(12345); * // Note: This endpoint is partially implemented * ``` */ createProphet21Hdr: this.createActionMethod('/checkout/{checkoutUid}/prophet21-hdr', 'POST', schemas_1.CheckoutProphet21HdrResponseSchema), /** * Add Prophet21 checkout lines * @description Adds line items to Prophet21 checkout header (in early development) * @param checkoutUid Checkout unique identifier * @param prophet21HdrUid Prophet21 header unique identifier * @returns Prophet21 line creation result * @throws ValidationError When response is malformed * @example * ```typescript * const p21Lines = await client.checkout.addProphet21Lines(12345, 67890); * // Note: This endpoint is in early development * ``` */ addProphet21Lines: async (checkoutUid, prophet21HdrUid) => { return this.executeRequest({ method: 'POST', path: '/checkout/{checkoutUid}/prophet21-hdr/{prophet21HdrUid}/prophet21-line', responseSchema: schemas_1.CheckoutProphet21LineResponseSchema, }, undefined, { checkoutUid: String(checkoutUid), prophet21HdrUid: String(prophet21HdrUid) }); }, // Data-only methods for checkout /** * Create checkout (data only) * @description Returns only the data from checkout creation response * @param orderData Complete checkout data * @returns Created checkout details (data only) * @throws ValidationError When request is invalid or response is malformed */ createData: async (orderData) => { const response = await this.checkout.create(orderData); return response.data; }, /** * Get checkout details (data only) * @description Returns only the data from checkout details response * @param checkoutUid Checkout unique identifier * @returns Checkout details (data only) * @throws ValidationError When response is malformed */ getData: async (checkoutUid) => { const response = await this.checkout.get(checkoutUid); return response.data; }, /** * Get checkout document (data only) * @description Returns the checkout document directly * @param checkoutUid Checkout unique identifier * @param params Optional parameters * @returns Checkout document (data only) * @throws ValidationError When response is malformed */ getDocData: async (checkoutUid, params) => { return await this.checkout.getDoc(checkoutUid, params); }, /** * Validate checkout (data only) * @description Returns only the data from checkout validation response * @param checkoutUid Checkout unique identifier * @returns Validation results (data only) * @throws ValidationError When response is malformed */ validateData: async (checkoutUid) => { const response = await this.checkout.validate(checkoutUid); return response.data; }, /** * Activate checkout (data only) * @description Returns only the data from checkout activation response * @param checkoutUid Checkout unique identifier * @returns Activation results (data only) * @throws ValidationError When response is malformed */ activateData: async (checkoutUid) => { const response = await this.checkout.activate(checkoutUid); return response.data; }, /** * Create Prophet21 header (data only) * @description Returns only the data from Prophet21 header creation response * @param checkoutUid Checkout unique identifier * @returns Prophet21 header creation result (data only) * @throws ValidationError When response is malformed */ createProphet21HdrData: async (checkoutUid) => { const response = await this.checkout.createProphet21Hdr(checkoutUid); return response.data; }, /** * Add Prophet21 lines (data only) * @description Returns the Prophet21 lines addition result directly * @param checkoutUid Checkout unique identifier * @param prophet21HdrUid Prophet21 header unique identifier * @returns Prophet21 lines addition result (data only) * @throws ValidationError When response is malformed */ addProphet21LinesData: async (checkoutUid, prophet21HdrUid) => { return await this.checkout.addProphet21Lines(checkoutUid, prophet21HdrUid); }, }; /** * Check service health (no bearer token required) * @description Monitor service availability and site configuration without authentication overhead * @returns Health check response with site hash and ID for configuration verification * @throws ValidationError When response is malformed * @example * ```typescript * const health = await client.getHealthCheck(); * console.log('Service health:', health.status); * console.log('Site ID:', health.data.siteId); * console.log('Site Hash:', health.data.siteHash); * ``` */ this.getHealthCheck = this.createHealthCheckMethod(schemas_1.HealthCheckResponseSchema); /** * Health Data Operations * @description Direct access to health check data without response metadata */ this.healthData = { /** * Get health check data without response metadata * @returns Promise<unknown> Health status data directly */ check: async () => { const response = await this.getHealthCheck(); return response.data; }, }; } } exports.CommerceClient = CommerceClient; //# sourceMappingURL=client.js.map