@simpleapps-com/augur-api
Version:
TypeScript client library for Augur microservices API endpoints
615 lines • 29.4 kB
JavaScript
import { BaseServiceClient } from '../../core/base-client';
import {
// Customer schemas
CustomerListParamsSchema, CustomerListResponseSchema, CustomerLookupParamsSchema, CustomerLookupResponseSchema, CustomerResponseSchema,
// Contact schemas
ContactCreateParamsSchema, ContactListParamsSchema, ContactListResponseSchema, ContactResponseSchema, ContactCustomersParamsSchema, ContactCustomersResponseSchema, ContactUserDefinedFieldsResponseSchema,
// Web allowance schemas
WebAllowanceResponseSchema,
// Address schemas
AddressListParamsSchema, AddressListResponseSchema,
// Ship-to schemas
ShipToAddressListParamsSchema, ShipToAddressListResponseSchema, ShipToAddressCreateParamsSchema, ShipToAddressResponseSchema,
// Order schemas
OrderListParamsSchema, OrderHeaderListResponseSchema, OrderDocumentListResponseSchema, OrderDocumentResponseSchema,
// Invoice schemas
InvoiceListParamsSchema, InvoiceListResponseSchema, InvoiceResponseSchema,
// Quote schemas
QuoteListParamsSchema, QuoteListResponseSchema, QuoteResponseSchema,
// Purchase history schemas
PurchasedItemListParamsSchema, PurchasedItemListResponseSchema,
// Data refresh schemas
DataRefreshResponseSchemaResponse,
// Health check schema
HealthCheckResponseSchema, } from './schemas';
/**
* Customers API Client
* @description Client for interacting with Customers microservice API endpoints
* @example
* ```typescript
* import { HTTPClient } from '@augur/api-client/core';
* import { CustomersClient } from '@augur/api-client/services/customers';
*
* const http = new HTTPClient('customers', { siteId: 'your-site-id', bearerToken: 'your-token' });
* const customers = new CustomersClient(http);
*
* // List customers
* const customerList = await customers.customer.list({ limit: 10 });
*
* // Get customer by ID
* const customer = await customers.customer.get(123);
*
* // Search customers
* const searchResults = await customers.customer.lookup({ q: 'Acme Corp' });
* ```
*/
export class CustomersClient extends BaseServiceClient {
/**
* Create a new CustomersClient instance
* @param http Configured HTTPClient instance
* @param baseUrl Base URL for the Customers API (default: https://customers.augur-api.com)
*/
constructor(http, baseUrl = 'https://customers.augur-api.com') {
super('customers', http, baseUrl);
/**
* Customer management endpoints
* @description Methods for customer CRUD operations and lookups
*/
this.customer = {
/**
* Retrieve a paginated list of customer documents
* @description Returns customers with optional filtering by class5Id and search query
* @param params Optional filtering and pagination parameters
* @returns Array of customer documents
* @throws ValidationError When parameters are invalid or response is malformed
* @example
* ```typescript
* // Get all customers
* const customers = await client.customer.list();
*
* // Get filtered customers
* const filtered = await client.customer.list({
* class5Id: 'GOLD',
* limit: 50,
* q: 'Acme'
* });
* ```
*/
list: this.createListMethod('/customer', CustomerListParamsSchema, CustomerListResponseSchema),
/**
* Get complete customer document by ID
* @description Returns full customer document including addresses, contacts, and ship-to addresses
* @param customerId Customer ID
* @returns Complete customer document
* @throws ValidationError When response is malformed
* @example
* ```typescript
* const customer = await client.customer.get(12345);
* console.log(customer.data.customerName, customer.data.addresses);
* ```
*/
get: this.createGetMethod('/customer/{customerId}/doc', CustomerResponseSchema),
/**
* Search for customers by name or ID with summary information
* @description Returns customer ID and name for lookup purposes
* @param params Search parameters with required query string
* @returns Array of customer lookup results
* @throws ValidationError When parameters are invalid or response is malformed
* @example
* ```typescript
* const results = await client.customer.lookup({ q: 'Acme Corporation' });
* ```
*/
lookup: async (params) => {
return this.executeRequest({
method: 'GET',
path: '/customer/lookup',
paramsSchema: CustomerLookupParamsSchema,
responseSchema: CustomerLookupResponseSchema,
}, params);
},
/**
* Customer address management
* @description Methods for looking up customer addresses
*/
addresses: {
/**
* Lookup customer addresses with search functionality
* @description Returns customer addresses matching search query
* @param customerId Customer ID
* @param params Search parameters with required query string
* @returns Array of customer addresses
* @throws ValidationError When parameters are invalid or response is malformed
* @example
* ```typescript
* const addresses = await client.customer.addresses.list(12345, { q: 'Main' });
* ```
*/
list: async (customerId, params) => {
return this.executeRequest({
method: 'GET',
path: '/customer/{customerId}/address',
paramsSchema: AddressListParamsSchema,
responseSchema: AddressListResponseSchema,
}, params, { customerId: String(customerId) });
},
},
/**
* Customer contact management
* @description Methods for managing customer contacts
*/
contacts: {
/**
* Lookup contacts associated with a customer
* @description Returns contacts matching search query for the specified customer
* @param customerId Customer ID
* @param params Search parameters with required query string
* @returns Array of customer contacts
* @throws ValidationError When parameters are invalid or response is malformed
* @example
* ```typescript
* const contacts = await client.customer.contacts.list(12345, { q: 'John' });
* ```
*/
list: async (customerId, params) => {
return this.executeRequest({
method: 'GET',
path: '/customer/{customerId}/contacts',
paramsSchema: ContactListParamsSchema,
responseSchema: ContactListResponseSchema,
}, params, { customerId: String(customerId) });
},
/**
* Create a new contact for a customer
* @description Creates a new contact with permissions and role information
* @param customerId Customer ID
* @param data Contact creation parameters
* @returns Created contact details
* @throws ValidationError When data is invalid or response is malformed
* @example
* ```typescript
* const newContact = await client.customer.contacts.create(12345, {
* firstName: 'Jane',
* lastName: 'Doe',
* email: 'jane.doe@acme.com',
* title: 'Procurement Specialist',
* role: 'BUYER'
* });
* ```
*/
create: async (customerId, data) => {
return this.executeRequest({
method: 'POST',
path: '/customer/{customerId}/contacts',
paramsSchema: ContactCreateParamsSchema,
responseSchema: ContactResponseSchema,
}, data, { customerId: String(customerId) });
},
},
/**
* Customer ship-to address management
* @description Methods for managing customer ship-to addresses
*/
shipTo: {
/**
* List customer ship-to addresses
* @description Returns ship-to addresses with optional search filtering
* @param customerId Customer ID
* @param params Optional search and pagination parameters
* @returns Array of ship-to addresses
* @throws ValidationError When parameters are invalid or response is malformed
* @example
* ```typescript
* // Get all ship-to addresses
* const shipToAddresses = await client.customer.shipTo.list(12345, {});
*
* // Search ship-to addresses
* const filtered = await client.customer.shipTo.list(12345, { q: 'warehouse' });
* ```
*/
list: async (customerId, params) => {
return this.executeRequest({
method: 'GET',
path: '/customer/{customerId}/ship-to',
paramsSchema: ShipToAddressListParamsSchema,
responseSchema: ShipToAddressListResponseSchema,
}, params, { customerId: String(customerId) });
},
/**
* Create a new ship-to address for a customer
* @description Creates a new shipping destination address
* @param customerId Customer ID
* @param data Ship-to address creation parameters
* @returns Created ship-to address details
* @throws ValidationError When data is invalid or response is malformed
* @example
* ```typescript
* const newShipTo = await client.customer.shipTo.create(12345, {
* shipToName: 'New Warehouse',
* address1: '789 Commerce Drive',
* city: 'Atlanta',
* state: 'GA',
* zipCode: '30309',
* country: 'USA'
* });
* ```
*/
create: async (customerId, data) => {
return this.executeRequest({
method: 'POST',
path: '/customer/{customerId}/ship-to',
paramsSchema: ShipToAddressCreateParamsSchema,
responseSchema: ShipToAddressResponseSchema,
}, data, { customerId: String(customerId) });
},
},
/**
* Customer order management
* @description Methods for viewing customer orders
*/
orders: {
/**
* List customer orders
* @description Returns customer orders with different detail levels based on fullDocument parameter
* @param customerId Customer ID (number)
* @param params Optional filtering and pagination parameters
* @param params.addressId Filter by specific ship-to address ID (number, optional)
* @param params.fullDocument Controls response detail level (string, optional):
* - 'Y' (default): Returns complete order documents with orderLines array and shipping details
* - 'N': Returns order headers only - summary information without line items
* @param params.limit Maximum number of results to return (number, optional, default: 10)
* @param params.offset Number of results to skip for pagination (number, optional, default: 0)
* @param params.orderBy Sort ordering in format 'field|direction' (string, optional, default: 'date_created|DESC')
* @param params.q Search query string (string, optional)
* @returns Promise resolving to either OrderHeaderListResponse or OrderDocumentListResponse
* @throws ValidationError When parameters are invalid or response is malformed
*
* @example Basic usage
* ```typescript
* // Get complete order documents (default behavior)
* const fullOrders = await client.customer.orders.list(12345);
* // Returns: OrderDocumentListResponse
*
* // Get order headers with pagination
* const paginatedHeaders = await client.customer.orders.list(12345, {
* limit: 25,
* offset: 50,
* fullDocument: 'N'
* });
* ```
*
* @example Advanced usage
* ```typescript
* // Get complete order documents with line items
* const fullOrders = await client.customer.orders.list(12345, {
* fullDocument: 'Y',
* orderBy: 'order_date|DESC',
* q: 'PO-2023'
* });
* // Returns: OrderDocumentListResponse
*
* // Filter by ship-to address
* const addressOrders = await client.customer.orders.list(12345, {
* addressId: 67890,
* fullDocument: 'N'
* });
* ```
*
* @note Parameter Types
* - fullDocument must be exactly 'Y' or 'N' (strings, not boolean)
* - orderBy format: 'field_name|ASC' or 'field_name|DESC'
* - All parameters are optional; method works without any parameters
*/
list: async (customerId, params) => {
// Runtime schema selection based on fullDocument parameter
const isFullDocument = params?.fullDocument === 'Y';
const responseSchema = isFullDocument
? OrderDocumentListResponseSchema
: OrderHeaderListResponseSchema;
return this.executeRequest({
method: 'GET',
path: '/customer/{customerId}/orders',
paramsSchema: OrderListParamsSchema,
responseSchema: responseSchema,
}, params, { customerId: String(customerId) });
},
/**
* Get specific customer order details
* @description Returns complete order information including line items and shipping details
* @param customerId Customer ID
* @param orderNo Order number
* @returns Complete order document with line items (always returns full document)
* @throws ValidationError When response is malformed
* @example
* ```typescript
* const order = await client.customer.orders.get(12345, 123456);
* // Returns: OrderDocumentResponse with full order details and line items
* ```
*/
get: async (customerId, orderNo) => {
return this.executeRequest({
method: 'GET',
path: '/customer/{customerId}/orders/{orderNo}',
responseSchema: OrderDocumentResponseSchema,
}, undefined, { customerId: String(customerId), orderNo: String(orderNo) });
},
},
/**
* Customer invoice management
* @description Methods for viewing customer invoices
*/
invoices: {
/**
* List customer invoices
* @description Returns customer invoices with required search query
* @param customerId Customer ID
* @param params Search parameters with required query string and optional shipToId filter
* @returns Array of customer invoices
* @throws ValidationError When parameters are invalid or response is malformed
* @example
* ```typescript
* const invoices = await client.customer.invoices.list(12345, { q: '2023' });
* ```
*/
list: async (customerId, params) => {
return this.executeRequest({
method: 'GET',
path: '/customer/{customerId}/invoices',
paramsSchema: InvoiceListParamsSchema,
responseSchema: InvoiceListResponseSchema,
}, params, { customerId: String(customerId) });
},
/**
* Get specific customer invoice details
* @description Returns complete invoice information including line items and payments
* @param customerId Customer ID
* @param invoiceNo Invoice number
* @returns Complete invoice details
* @throws ValidationError When response is malformed
* @example
* ```typescript
* const invoice = await client.customer.invoices.get(12345, 789123);
* ```
*/
get: async (customerId, invoiceNo) => {
return this.executeRequest({
method: 'GET',
path: '/customer/{customerId}/invoices/{invoiceNo}',
responseSchema: InvoiceResponseSchema,
}, undefined, { customerId: String(customerId), invoiceNo: String(invoiceNo) });
},
},
/**
* Customer quote management
* @description Methods for viewing customer quotes
*/
quotes: {
/**
* List customer quotes
* @description Returns customer quotes with pagination and ordering
* @param customerId Customer ID
* @param params Optional pagination and ordering parameters
* @returns Array of customer quotes
* @throws ValidationError When parameters are invalid or response is malformed
* @example
* ```typescript
* const quotes = await client.customer.quotes.list(12345);
* ```
*/
list: async (customerId, params) => {
return this.executeRequest({
method: 'GET',
path: '/customer/{customerId}/quotes',
paramsSchema: QuoteListParamsSchema,
responseSchema: QuoteListResponseSchema,
}, params, { customerId: String(customerId) });
},
/**
* Get specific customer quote details
* @description Returns complete quote information including line items and terms
* @param customerId Customer ID
* @param quoteNo Quote number
* @returns Complete quote details
* @throws ValidationError When response is malformed
* @example
* ```typescript
* const quote = await client.customer.quotes.get(12345, 456789);
* ```
*/
get: async (customerId, quoteNo) => {
return this.executeRequest({
method: 'GET',
path: '/customer/{customerId}/quotes/{quoteNo}',
responseSchema: QuoteResponseSchema,
}, undefined, { customerId: String(customerId), quoteNo: String(quoteNo) });
},
},
/**
* Customer purchase history
* @description Methods for viewing customer purchase history
*/
purchaseHistory: {
/**
* List customer purchase history
* @description Returns items purchased by customer with frequency and pricing information
* @param customerId Customer ID
* @param params Optional pagination and ordering parameters
* @returns Array of purchased items with history
* @throws ValidationError When parameters are invalid or response is malformed
* @example
* ```typescript
* const history = await client.customer.purchaseHistory.list(12345, {
* orderBy: 'date_last_purchased|DESC'
* });
* ```
*/
list: async (customerId, params) => {
return this.executeRequest({
method: 'GET',
path: '/customer/{customerId}/purchased-items',
paramsSchema: PurchasedItemListParamsSchema,
responseSchema: PurchasedItemListResponseSchema,
}, params, { customerId: String(customerId) });
},
},
};
/**
* Contact management endpoints
* @description Methods for individual contact operations
*/
this.contacts = {
/**
* Get complete contact document by ID
* @description Returns full contact details including login credentials and permissions
* @param contactId Contact ID
* @returns Complete contact document
* @throws ValidationError When response is malformed
* @example
* ```typescript
* const contact = await client.contacts.get(12345);
* console.log(contact.data.firstName, contact.data.permissions);
* ```
*/
get: this.createGetMethod('/contacts/{contactId}/doc', ContactResponseSchema),
/**
* Get web allowance information for a contact (USCCO specific)
* @description Returns web allowance details including current usage and remaining balance
* @param contactId Contact ID
* @returns Web allowance information
* @throws ValidationError When response is malformed
* @example
* ```typescript
* const allowance = await client.contacts.getWebAllowance(12345);
* console.log(allowance.data.remainingAllowance);
* ```
*/
getWebAllowance: async (contactId) => {
return this.executeRequest({
method: 'GET',
path: '/contacts/{contactId}/web-allowance',
responseSchema: WebAllowanceResponseSchema,
}, undefined, { contactId: String(contactId) });
},
/**
* List customers associated with a sales representative contact
* @description Returns customers managed by the specified sales rep contact
* @param contactId Contact ID (sales rep)
* @param params Optional filtering and pagination parameters
* @returns Array of customers managed by the sales rep
* @throws ValidationError When parameters are invalid or response is malformed
* @example
* ```typescript
* const customers = await client.contacts.getCustomers(12345, {
* class5Id: 'GOLD',
* q: 'Acme'
* });
* ```
*/
getCustomers: async (contactId, params) => {
return this.executeRequest({
method: 'GET',
path: '/contacts/{contactId}/customers',
paramsSchema: ContactCustomersParamsSchema,
responseSchema: ContactCustomersResponseSchema,
}, params, { contactId: String(contactId) });
},
/**
* List user-defined fields for a contact
* @description Returns custom fields configured for the contact
* @param contactId Contact ID
* @returns Contact user-defined fields
* @throws ValidationError When response is malformed
* @example
* ```typescript
* const customFields = await client.contacts.getUserDefinedFields(12345);
* ```
*/
getUserDefinedFields: async (contactId) => {
return this.executeRequest({
method: 'GET',
path: '/contacts-ud/{contactId}',
responseSchema: ContactUserDefinedFieldsResponseSchema,
}, undefined, { contactId: String(contactId) });
},
/**
* Trigger contact data refresh from Prophet 21
* @description Initiates synchronization of contact data from the ERP system
* @returns Refresh operation status
* @throws ValidationError When response is malformed
* @example
* ```typescript
* const refresh = await client.contacts.refresh();
* console.log(refresh.data.jobId);
* ```
*/
refresh: async () => {
return this.executeRequest({
method: 'GET',
path: '/contacts/refresh',
responseSchema: DataRefreshResponseSchemaResponse,
});
},
};
/**
* Ship-to address refresh endpoints
* @description Methods for triggering data refresh operations
*/
this.shipToRefresh = {
/**
* Trigger ship-to address data refresh from Prophet 21
* @description Initiates synchronization of ship-to address data from the ERP system
* @returns Refresh operation status
* @throws ValidationError When response is malformed
* @example
* ```typescript
* const refresh = await client.shipToRefresh.refresh();
* console.log(refresh.data.jobId);
* ```
*/
refresh: async () => {
return this.executeRequest({
method: 'GET',
path: '/ship-to/refresh',
responseSchema: DataRefreshResponseSchemaResponse,
});
},
};
/**
* Order entry contacts customer refresh endpoints
* @description Methods for triggering OE contacts customer data refresh
*/
this.oeContactsCustomerRefresh = {
/**
* Trigger order entry contacts customer data refresh
* @description Initiates synchronization of OE contacts customer data
* @returns Refresh operation status
* @throws ValidationError When response is malformed
* @example
* ```typescript
* const refresh = await client.oeContactsCustomerRefresh.refresh();
* console.log(refresh.data.jobId);
* ```
*/
refresh: async () => {
return this.executeRequest({
method: 'GET',
path: '/oe-contacts-customer/refresh',
responseSchema: DataRefreshResponseSchemaResponse,
});
},
};
/**
* Health check endpoint
* @description Monitor service health and connectivity
* @returns Service health status including site information
* @throws ValidationError When response is malformed
* @example
* ```typescript
* const health = await client.getHealthCheck();
* console.log(health.data.siteId, health.data.siteHash);
* ```
*/
this.getHealthCheck = this.createHealthCheckMethod(HealthCheckResponseSchema);
}
}
//# sourceMappingURL=client.js.map