@simpleapps-com/augur-api
Version:
TypeScript client library for Augur microservices API endpoints
1,005 lines (1,004 loc) • 191 kB
JavaScript
import { BaseServiceClient } from '../../core/base-client';
import { StandardPaginationParamsSchema } from '../../core/common-schemas';
import { z } from 'zod';
import {
// Health check schemas
HealthCheckResponseSchema, PingResponseSchema,
// Product schemas
ProductSearchParamsSchema, ProductListParamsSchema, ProductLookupParamsSchema, ProductResponseSchema, ProductListResponseSchema, ProductLookupResponseSchema, AccessoryListResponseSchema, BinInfoListResponseSchema,
// Category schemas
CategoryDetailsParamsSchema, CategoryItemsParamsSchema, CategoryListParamsSchema, CategoryLookupParamsSchema, CategoryResponseSchema, CategoryListResponseSchema, CategoryLookupResponseSchema, CategoryPreCacheResponseSchema, CategoryItemsResponseSchema, CategoryAttributesResponseSchema, CategoryFiltersResponseSchema, CategoryImagesResponseSchema,
// Attribute schemas
CreateAttributeRequestSchema, UpdateAttributeRequestSchema, AttributeResponseSchema, AttributeListResponseSchema, AttributeValueListResponseSchema,
// Attribute Group schemas
CreateAttributeGroupRequestSchema, UpdateAttributeGroupRequestSchema, AttributeGroupListParamsSchema, AttributeGroupResponseSchema, AttributeGroupListResponseSchema,
// Stock schemas
GetStockParamsSchema, GetStockResponseSchema,
// Brand schemas
CreateBrandRequestSchema, UpdateBrandRequestSchema, BrandListParamsSchema, BrandResponseSchema, BrandListResponseSchema,
// Alternate Code schemas
// Item attribute value schemas
CreateItemAttributeValueRequestSchema, ItemAttributeValueListResponseSchema, ItemAttributeValueResponseSchema,
// Favorites schemas
CreateItemFavoriteRequestSchema, UpdateItemFavoriteRequestSchema, ItemFavoritesListParamsSchema, ItemFavoriteResponseSchema, ItemFavoriteListResponseSchema,
// Wishlists schemas
CreateItemWishlistHeaderRequestSchema, UpdateItemWishlistHeaderRequestSchema, CreateItemWishlistLineRequestSchema, UpdateItemWishlistLineRequestSchema, ItemWishlistListParamsSchema, ItemWishlistLineListParamsSchema, ItemWishlistHeaderResponseSchema, ItemWishlistHeaderListResponseSchema, ItemWishlistLineResponseSchema, ItemWishlistLineListResponseSchema,
// Variants schemas
CreateItemVariantHeaderRequestSchema, UpdateItemVariantHeaderRequestSchema, CreateItemVariantLineRequestSchema, UpdateItemVariantLineRequestSchema, ItemVariantListParamsSchema, ItemVariantHeaderResponseSchema, ItemVariantHeaderListResponseSchema, ItemVariantLineResponseSchema, ItemVariantLineListResponseSchema,
// FAQ schemas
CreateItemFaqRequestSchema, UpdateItemFaqRequestSchema, ItemFaqListParamsSchema, ItemFaqVoteRequestSchema, ItemFaqResponseSchema, ItemFaqListResponseSchema,
// Brand Items schemas
CreateBrandItemRequestSchema, UpdateBrandItemRequestSchema, BrandItemListParamsSchema, BrandItemResponseSchema, BrandItemListResponseSchema,
// Product Links schemas
CreateProductLinkRequestSchema, UpdateProductLinkRequestSchema, ProductLinkListParamsSchema, ProductLinkResponseSchema, ProductLinkListResponseSchema,
// Sub-parts schemas
CreateSubPartRequestSchema, UpdateSubPartRequestSchema, SubPartListParamsSchema, SubPartResponseSchema, SubPartListResponseSchema,
// Bins schemas
CreateBinRequestSchema, UpdateBinRequestSchema, BinListParamsSchema, InventoryLocationBinListParamsSchema, BinResponseSchema, BinListResponseSchema, InventoryLocationBinListResponseSchema, } from './schemas';
/**
* Items API Client
* @description Client for interacting with Items microservice API endpoints for comprehensive product catalog, inventory, categories, and attributes management
* @fullPath api.items
* @service items
* @domain inventory-management
* @discoverable true
* @searchTerms ["items", "products", "inventory", "catalog", "categories", "attributes", "brands", "stock", "product management", "item lookup"]
* @relatedEndpoints ["api.commerce.cartHeaders", "api.customers.purchasedItems", "api.nexus.receiving", "api.pricing.priceEngine", "api.opensearch.items"]
* @commonPatterns ["Product catalog management", "Inventory tracking", "Category navigation", "Product search", "Stock management"]
* @workflow ["product-catalog-management", "inventory-operations", "e-commerce-integration"]
* @prerequisites ["Valid authentication token", "Inventory management permissions"]
* @nextSteps ["api.commerce.cartHeaders.create for adding to cart", "api.pricing.priceEngine for pricing calculations"]
* @businessRules ["Product visibility based on status and online flags", "Category hierarchy enforcement", "Stock validation for purchasing"]
* @functionalArea "inventory-and-product-management"
* @caching "Product details cached for 10 minutes, categories for 30 minutes"
* @performance "Use pagination for large result sets, implement search filters for better performance"
* @example
* ```typescript
* import { HTTPClient } from '@augur/api-client/core';
* import { ItemsClient } from '@augur/api-client/services/items';
*
* const http = new HTTPClient('items', { siteId: 'your-site-id', bearerToken: 'your-token' });
* const items = new ItemsClient(http);
*
* // Get product details
* const product = await items.invMast.get(12345);
*
* // Search products
* const results = await items.invMast.search({ q: 'cable', limit: 20 });
*
* // Get category with items
* const category = await items.categories.get(100);
* const categoryItems = await items.categories.getItems(100, { limit: 12 });
* ```
*/
export class ItemsClient extends BaseServiceClient {
/**
* Create a new ItemsClient instance
* @param http Configured HTTPClient instance
* @param baseUrl Base URL for the Items API (default: https://items.augur-api.com)
*/
constructor(http, baseUrl = 'https://items.augur-api.com') {
super('items', http, baseUrl);
/**
* Product catalog endpoints (Inventory Master - inv_mast)
* @description Methods for product management including search, details, alternate codes, and accessories
*/
/**
* Category management endpoints
* @description Methods for hierarchical product categorization including category details, items, attributes, and filtering
*/
this.categories = {
/**
* List all categories with filtering and pagination
* @description Retrieve a paginated list of categories with filtering options
* @param params Optional filtering and pagination parameters
* @returns Array of category entities
* @throws ValidationError When parameters are invalid or response is malformed
* @example
* ```typescript
* const categories = await client.categories.list({
* displayOnWebFlag: 'Y',
* limit: 50
* });
* ```
*/
list: async (params) => {
return this.executeRequest({
method: 'GET',
path: '/item-category',
paramsSchema: CategoryListParamsSchema,
responseSchema: CategoryListResponseSchema,
}, params);
},
/**
* Lookup category with hierarchical structure
* @description Retrieve category with subcategories in hierarchical structure
* @param params Lookup parameters including category UID or ID
* @returns Category with subcategories
* @throws ValidationError When parameters are invalid or response is malformed
* @example
* ```typescript
* const categoryLookup = await client.categories.lookup({
* itemCategoryUid: 100,
* includeSubCategories: true
* });
* ```
*/
lookup: async (params) => {
return this.executeRequest({
method: 'GET',
path: '/item-category/lookup',
paramsSchema: CategoryLookupParamsSchema,
responseSchema: CategoryLookupResponseSchema,
}, params);
},
/**
* Pre-cache a single category
* @description Trigger pre-caching for a specific category to improve response times
* @param itemCategoryUid Category unique identifier
* @returns Boolean indicating if pre-cache was queued successfully
* @throws ValidationError When response is malformed
* @example
* ```typescript
* const cached = await client.categories.preCache(100);
* if (cached.data) {
* console.log('Category pre-cache queued successfully');
* }
* ```
*/
preCache: async (itemCategoryUid) => {
return this.executeRequest({
method: 'GET',
path: '/item-category/{id}/precache',
responseSchema: CategoryPreCacheResponseSchema,
}, undefined, { id: String(itemCategoryUid) });
},
/**
* Get category details by ID or path
* @description Retrieve comprehensive category information including children, attributes, and metadata
* @fullPath api.items.categories.get
* @service items
* @domain inventory-management
* @dataMethod categoriesData.get
* @discoverable true
* @searchTerms ["category details", "category info", "category by id", "category lookup", "hierarchical categories"]
* @relatedEndpoints ["api.items.categories.getItems", "api.items.categories.list", "api.items.categories.getAttributes", "api.opensearch.categories"]
* @commonPatterns ["Category navigation", "Get category info", "Category detail page", "Hierarchical browsing"]
* @workflow ["category-navigation", "product-browsing", "taxonomy-management"]
* @prerequisites ["Valid category UID or path", "Category access permissions"]
* @nextSteps ["api.items.categories.getItems", "api.items.categories.getAttributes", "api.items.categories.getFilters"]
* @businessRules ["Returns category hierarchy", "Includes subcategories if requested", "Respects category visibility settings"]
* @functionalArea "category-and-taxonomy-management"
* @caching "Cache for 30 minutes, invalidate on category structure changes"
* @performance "Optimized for category navigation, supports path-based lookups"
* @param itemCategoryUid Category unique identifier (use 0 for path-based lookup)
* @param params Optional parameters for path lookup, filtering, and children pagination
* @returns Complete category details with children and attributes
* @throws ValidationError When parameters are invalid or response is malformed
* @example
* ```typescript
* // Get category by ID
* const category = await client.categories.get(100);
* console.log(category.data.itemCategoryDesc, category.data.path);
*
* // Get category by path
* const categoryByPath = await client.categories.get(0, {
* path: '/Electronics/Cables'
* });
*
* // Get category with filtered children
* const categoryWithChildren = await client.categories.get(100, {
* childrenLimit: 10,
* childrenFilter: 'audio'
* });
* ```
*/
get: async (itemCategoryUid, params) => {
return this.executeRequest({
method: 'GET',
path: '/categories/{id}',
paramsSchema: CategoryDetailsParamsSchema,
responseSchema: CategoryResponseSchema,
}, params, { id: String(itemCategoryUid) });
},
/**
* Get items within a category
* @description Retrieve items within a specific category with advanced filtering, sorting, and pagination
* @param itemCategoryUid Category unique identifier
* @param params Optional filtering, sorting, and pagination parameters
* @returns Array of category items with optional stock information
* @throws ValidationError When parameters are invalid or response is malformed
* @example
* ```typescript
* // Get category items with basic pagination
* const items = await client.categories.getItems(100, { limit: 12 });
*
* // Get items with filtering and stock information
* const filteredItems = await client.categories.getItems(100, {
* limit: 20,
* sortBy: 'listPrice|ASC',
* includeStock: 'Y',
* displayOnWebFlag: 'Y',
* filters: JSON.stringify([
* { attributeId: 'color', values: ['red', 'blue'], operator: 'IN' }
* ])
* });
*
* // Search within category
* const searchResults = await client.categories.getItems(100, {
* q: 'wireless',
* limit: 10
* });
* ```
*/
getItems: async (itemCategoryUid, params) => {
return this.executeRequest({
method: 'GET',
path: '/categories/{id}/items',
paramsSchema: CategoryItemsParamsSchema,
responseSchema: CategoryItemsResponseSchema,
}, params, { id: String(itemCategoryUid) });
},
/**
* Get attributes available for a category
* @description Retrieve attributes available for filtering within a category
* @param itemCategoryUid Category unique identifier
* @returns Array of category attributes with their available values
* @throws ValidationError When response is malformed
* @example
* ```typescript
* const attributes = await client.categories.getAttributes(100);
* attributes.data.forEach(attr => {
* console.log(`${attr.attributeDesc}: ${attr.values?.join(', ')}`);
* });
* ```
*/
getAttributes: async (itemCategoryUid) => {
return this.executeRequest({
method: 'GET',
path: '/categories/{id}/attributes',
responseSchema: CategoryAttributesResponseSchema,
}, undefined, { id: String(itemCategoryUid) });
},
/**
* Get available filter options for a category
* @description Get available filter options for a category based on its items
* @param itemCategoryUid Category unique identifier
* @returns Array of filter options with values and counts
* @throws ValidationError When response is malformed
* @example
* ```typescript
* const filters = await client.categories.getFilters(100);
* filters.data.forEach(filter => {
* console.log(`${filter.attributeDesc}:`);
* filter.values.forEach(value => {
* console.log(` ${value.value} (${value.count})`);
* });
* });
* ```
*/
getFilters: async (itemCategoryUid) => {
return this.executeRequest({
method: 'GET',
path: '/categories/{id}/filters',
responseSchema: CategoryFiltersResponseSchema,
}, undefined, { id: String(itemCategoryUid) });
},
/**
* Get images for a category
* @description Retrieve images associated with a category
* @param itemCategoryUid Category unique identifier
* @returns Array of category images
* @throws ValidationError When response is malformed
* @example
* ```typescript
* const images = await client.categories.getImages(100);
* images.data.forEach(image => {
* console.log(`Image: ${image.imagePath} (${image.imageType})`);
* });
* ```
*/
getImages: async (itemCategoryUid) => {
return this.executeRequest({
method: 'GET',
path: '/categories/{id}/images',
responseSchema: CategoryImagesResponseSchema,
}, undefined, { id: String(itemCategoryUid) });
},
};
/**
* Category data-only endpoints
* @description Data-only methods that return just the data portion of category responses
*/
this.categoriesData = {
/**
* Get category details data only
* @description Returns only the data portion of category details response
* @fullPath api.items.categoriesData.get
* @service items
* @domain inventory-management
* @discoverable true
* @searchTerms ["category data", "category details data only"]
* @relatedEndpoints ["api.items.categories.get"]
* @commonPatterns ["Get category data without metadata"]
* @param itemCategoryUid Category unique identifier
* @param params Optional parameters
* @returns Category data only
*/
get: async (itemCategoryUid, params) => {
const response = await this.categories.get(itemCategoryUid, params);
return response.data;
},
/**
* List categories data only
* @description Returns only the data portion of category list response
* @fullPath api.items.categoriesData.list
* @service items
* @domain inventory-management
* @discoverable true
* @searchTerms ["category list data", "categories data only"]
* @relatedEndpoints ["api.items.categories.list"]
* @commonPatterns ["List categories without metadata"]
* @param params Optional filtering parameters
* @returns Category list data only
*/
list: async (params) => {
const response = await this.categories.list(params);
return response.data;
},
/**
* Get category items data only
* @description Returns only the data portion of category items response
* @fullPath api.items.categoriesData.getItems
* @service items
* @domain inventory-management
* @discoverable true
* @searchTerms ["category items data", "items in category data only"]
* @relatedEndpoints ["api.items.categories.getItems"]
* @commonPatterns ["Get category items without metadata"]
* @param itemCategoryUid Category unique identifier
* @param params Optional filtering parameters
* @returns Category items data only
*/
getItems: async (itemCategoryUid, params) => {
const response = await this.categories.getItems(itemCategoryUid, params);
return response.data;
},
};
/**
* Attribute management endpoints
* @description Methods for managing product attributes including CRUD operations
*/
this.attributes = {
/**
* List all attributes
* @description Retrieve a paginated list of available attributes
* @param params Optional pagination parameters
* @returns Array of attributes
* @throws ValidationError When parameters are invalid or response is malformed
* @example
* ```typescript
* const attributes = await client.attributes.list({ limit: 50 });
* attributes.data.forEach(attr => {
* console.log(`${attr.attributeId}: ${attr.attributeDesc} (${attr.dataType})`);
* });
* ```
*/
list: async (params) => {
return this.executeRequest({
method: 'GET',
path: '/attributes',
paramsSchema: StandardPaginationParamsSchema,
responseSchema: AttributeListResponseSchema,
}, params);
},
/**
* Get attribute details by ID
* @description Retrieve details for a specific attribute
* @param attributeUid Attribute unique identifier
* @returns Attribute details
* @throws ValidationError When response is malformed
* @example
* ```typescript
* const attribute = await client.attributes.get(123);
* console.log(attribute.attributeDesc, attribute.dataType, attribute.maxLength);
* ```
*/
get: this.createGetMethod('/attributes/{id}', AttributeResponseSchema),
/**
* Create a new attribute
* @description Create a new attribute with specified properties
* @param request Attribute creation data
* @returns Created attribute information
* @throws ValidationError When request is invalid or response is malformed
* @example
* ```typescript
* const newAttribute = await client.attributes.create({
* attributeId: 'material',
* attributeDesc: 'Material Type',
* dataType: 'string',
* maxLength: 100,
* sequenceNo: 10
* });
* ```
*/
create: this.createCreateMethod('/attributes', CreateAttributeRequestSchema, AttributeResponseSchema),
/**
* Update an existing attribute
* @description Update an existing attribute with new information
* @param attributeUid Attribute unique identifier
* @param request Attribute update data
* @returns Updated attribute information
* @throws ValidationError When request is invalid or response is malformed
* @example
* ```typescript
* const updated = await client.attributes.update(123, {
* attributeDesc: 'Updated Material Type',
* maxLength: 150
* });
* ```
*/
update: this.createUpdateMethod('/attributes/{id}', UpdateAttributeRequestSchema, AttributeResponseSchema),
/**
* Delete an attribute
* @description Soft delete an attribute (sets status to inactive)
* @param attributeUid Attribute unique identifier
* @returns Boolean indicating successful deletion
* @throws ValidationError When response is malformed
* @example
* ```typescript
* const deleted = await client.attributes.delete(123);
* if (deleted) {
* console.log('Attribute successfully deleted');
* }
* ```
*/
delete: async (attributeUid) => {
await this.executeRequest({
method: 'DELETE',
path: '/attributes/{id}',
responseSchema: z.undefined(),
}, undefined, { id: String(attributeUid) });
return true;
},
};
/**
* Stock and location management endpoints
* @description Methods for inventory stock information across locations
*/
this.stock = {
/**
* Get comprehensive stock details for an item
* @description Retrieve comprehensive stock information for an item across all locations with detailed calculations
* @param invMastUid Inventory master unique identifier
* @param params Optional parameters for filtering and including additional data
* @returns Stock details with location breakdown and company summary
* @throws ValidationError When response is malformed
* @example
* ```typescript
* const stockInfo = await client.stock.getDetails(12345);
* console.log('Company Summary:', stockInfo.data.companySummary);
*
* stockInfo.data.stockData.forEach(location => {
* console.log(`Location ${location.locationName}: ${location.qtyOnHand} on hand, ${location.qtyAvailable} available`);
* console.log(` Calculated: ${location.calcQtyOnHand} (${location.defaultSellingUnit})`);
* });
* ```
*/
getDetails: async (invMastUid, params) => {
return this.executeRequest({
method: 'GET',
path: '/inv-loc/{id}/stock',
paramsSchema: GetStockParamsSchema,
responseSchema: GetStockResponseSchema,
}, params, { id: String(invMastUid) });
},
};
/**
* Brand management endpoints
* @description Methods for managing product brands including CRUD operations
*/
this.brands = {
/**
* List all brands
* @description Retrieve a paginated list of brands with filtering options
* @param params Optional filtering and pagination parameters
* @returns Array of brands
* @throws ValidationError When parameters are invalid or response is malformed
* @example
* ```typescript
* const brands = await client.brands.list({ limit: 50, statusCd: 704 });
* brands.data.forEach(brand => {
* console.log(`${brand.brandsId}: ${brand.brandsName}`);
* });
* ```
*/
list: async (params) => {
return this.executeRequest({
method: 'GET',
path: '/brands',
paramsSchema: BrandListParamsSchema,
responseSchema: BrandListResponseSchema,
}, params);
},
/**
* Get brand details by ID
* @description Retrieve details for a specific brand
* @param brandsUid Brand unique identifier
* @returns Brand details
* @throws ValidationError When response is malformed
* @example
* ```typescript
* const brand = await client.brands.get(123);
* console.log(brand.data.brandsName, brand.data.brandsDesc);
* ```
*/
get: this.createGetMethod('/brands/{id}', BrandResponseSchema),
/**
* Create a new brand
* @description Create a new brand with specified properties
* @param request Brand creation data
* @returns Created brand information
* @throws ValidationError When request is invalid or response is malformed
* @example
* ```typescript
* const newBrand = await client.brands.create({
* brandsName: 'ACME Corporation',
* brandsDesc: 'Leading manufacturer'
* });
* ```
*/
create: this.createCreateMethod('/brands', CreateBrandRequestSchema, BrandResponseSchema),
/**
* Update an existing brand
* @description Update an existing brand with new information
* @param brandsUid Brand unique identifier
* @param request Brand update data
* @returns Updated brand information
* @throws ValidationError When request is invalid or response is malformed
* @example
* ```typescript
* const updated = await client.brands.update(123, {
* brandsName: 'ACME Corporation LLC',
* brandsDesc: 'Updated description'
* });
* ```
*/
update: this.createUpdateMethod('/brands/{id}', UpdateBrandRequestSchema, BrandResponseSchema),
/**
* Delete a brand
* @description Soft delete a brand (sets status to inactive)
* @param brandsUid Brand unique identifier
* @returns Boolean indicating successful deletion
* @throws ValidationError When response is malformed
* @example
* ```typescript
* const deleted = await client.brands.delete(123);
* if (deleted) {
* console.log('Brand successfully deleted');
* }
* ```
*/
delete: async (brandsUid) => {
await this.executeRequest({
method: 'DELETE',
path: '/brands/{id}',
responseSchema: z.undefined(),
}, undefined, { id: String(brandsUid) });
return true;
},
};
/**
* Attribute group management endpoints
* @description Methods for managing attribute groups with comprehensive CRUD operations
*/
this.attributeGroups = {
/**
* List all attribute groups
* @description Retrieve a list of attribute groups with filtering options
* @param params Optional filtering and pagination parameters
* @returns Array of attribute group summaries
* @throws ValidationError When parameters are invalid or response is malformed
* @example
* ```typescript
* const groups = await client.attributeGroups.list({
* statusCd: 704,
* limit: 50
* });
* groups.data.forEach(group => {
* console.log(`${group.attributeGroupId}: ${group.attributeGroupDesc}`);
* });
* ```
*/
list: async (params) => {
return this.executeRequest({
method: 'GET',
path: '/attribute-groups',
paramsSchema: AttributeGroupListParamsSchema,
responseSchema: AttributeGroupListResponseSchema,
}, params);
},
/**
* Get attribute group details by ID
* @description Retrieve details for a specific attribute group
* @param attributeGroupUid Attribute group unique identifier
* @returns Complete attribute group details
* @throws ValidationError When response is malformed
* @example
* ```typescript
* const group = await client.attributeGroups.get(123);
* console.log(group.data.attributeGroupDesc, group.data.attributeGroupType);
* ```
*/
get: this.createGetMethod('/attribute-groups/{id}', AttributeGroupResponseSchema),
/**
* Create a new attribute group
* @description Create a new attribute group with specified properties
* @param request Attribute group creation data
* @returns Created attribute group information
* @throws ValidationError When request is invalid or response is malformed
* @example
* ```typescript
* const newGroup = await client.attributeGroups.create({
* attributeGroupDesc: 'Electronics Category',
* attributeGroupType: 3526,
* statusCd: 704
* });
* ```
*/
create: this.createCreateMethod('/attribute-groups', CreateAttributeGroupRequestSchema, AttributeGroupResponseSchema),
/**
* Update an existing attribute group
* @description Update an existing attribute group with new information
* @param attributeGroupUid Attribute group unique identifier
* @param request Attribute group update data
* @returns Updated attribute group information
* @throws ValidationError When request is invalid or response is malformed
* @example
* ```typescript
* const updated = await client.attributeGroups.update(123, {
* attributeGroupDesc: 'Updated Electronics Category',
* statusCd: 704
* });
* ```
*/
update: this.createUpdateMethod('/attribute-groups/{id}', UpdateAttributeGroupRequestSchema, AttributeGroupResponseSchema),
/**
* Delete an attribute group
* @description Soft delete an attribute group (sets status to inactive)
* @param attributeGroupUid Attribute group unique identifier
* @returns Updated attribute group with deleted status
* @throws ValidationError When response is malformed
* @example
* ```typescript
* const deleted = await client.attributeGroups.delete(123);
* console.log('Deleted group status:', deleted.data.statusCd); // Should be 700
* ```
*/
delete: async (attributeGroupUid) => {
return this.executeRequest({
method: 'DELETE',
path: '/attribute-groups/{id}',
responseSchema: AttributeGroupResponseSchema,
}, undefined, { id: String(attributeGroupUid) });
},
};
/**
* Attribute value management endpoints
* @description Methods for managing attribute values
*/
this.attributeValues = {
/**
* List all attribute values
* @description Retrieve a list of attribute values
* @param params Optional pagination parameters
* @returns Array of attribute values
* @throws ValidationError When parameters are invalid or response is malformed
* @example
* ```typescript
* const values = await client.attributeValues.list();
* values.data.forEach(value => {
* console.log(`${value.attributeValue} (${value.displayValue})`);
* });
* ```
*/
list: async (params) => {
return this.executeRequest({
method: 'GET',
path: '/attribute-values',
paramsSchema: StandardPaginationParamsSchema,
responseSchema: AttributeValueListResponseSchema,
}, params);
},
/**
* Get attribute value details by ID
* @description Retrieve details for a specific attribute value
* @param attributeValueUid Attribute value unique identifier
* @returns Attribute value details
* @throws ValidationError When response is malformed
* @example
* ```typescript
* const value = await client.attributeValues.get(123);
* console.log(value.attributeValue, value.displayValue);
* ```
*/
get: async (attributeValueUid) => {
const response = await this.executeRequest({
method: 'GET',
path: '/attribute-values/{id}',
responseSchema: AttributeValueListResponseSchema,
}, undefined, { id: String(attributeValueUid) });
return response.data[0];
},
};
/**
* Item attribute value management endpoints
* @description Methods for managing item-specific attribute values
*/
this.itemAttributeValues = {
/**
* List item attribute values
* @description Retrieve a list of item attribute values
* @param params Optional pagination parameters
* @returns Array of item attribute values
* @throws ValidationError When parameters are invalid or response is malformed
* @example
* ```typescript
* const itemValues = await client.itemAttributeValues.list();
* itemValues.data.forEach(value => {
* console.log(`Item ${value.invMastUid}, Attribute ${value.attributeUid}: ${value.attributeValue}`);
* });
* ```
*/
list: async (params) => {
return this.executeRequest({
method: 'GET',
path: '/item-attribute-values',
paramsSchema: StandardPaginationParamsSchema,
responseSchema: ItemAttributeValueListResponseSchema,
}, params);
},
/**
* Create item attribute value
* @description Create a new item attribute value relationship
* @param request Item attribute value creation data
* @returns Created item attribute value information
* @throws ValidationError When request is invalid or response is malformed
* @example
* ```typescript
* const newValue = await client.itemAttributeValues.create({
* invMastUid: 12345,
* attributeUid: 456,
* attributeValue: 'red',
* displayValue: 'Red'
* });
* ```
*/
create: this.createCreateMethod('/item-attribute-values', CreateItemAttributeValueRequestSchema, ItemAttributeValueResponseSchema),
};
/**
* Health monitoring endpoints
* @description Service health monitoring and connectivity testing
*/
this.health = {
/**
* Service health check
* @description Verify service health and trigger seed jobs if needed
* @fullPath api.items.health.check
* @service items
* @domain system-health
* @dataMethod healthData.check
* @discoverable true
* @searchTerms ["health check", "service status", "system health", "service monitoring"]
* @relatedEndpoints ["api.joomla.health.check", "api.nexus.health.check", "api.commerce.health.check"]
* @commonPatterns ["Check service health", "Monitor system status", "Verify connectivity"]
* @workflow ["service-monitoring", "health-verification", "system-diagnostics"]
* @prerequisites ["Valid authentication token", "System monitoring permissions"]
* @nextSteps ["Service-specific operations", "Error handling if health fails"]
* @businessRules ["Returns site configuration", "Triggers maintenance jobs if needed", "Validates authentication"]
* @functionalArea "system-monitoring-and-health"
* @caching "No caching, real-time health status"
* @performance "Lightweight endpoint for frequent monitoring"
* @returns Health check response with site information
* @throws ValidationError When response is malformed
* @example
* ```typescript
* const health = await client.health.check();
* console.log('Site ID:', health.data.siteId);
* console.log('Site Hash:', health.data.siteHash);
* ```
*/
check: this.createHealthCheckMethod(HealthCheckResponseSchema),
/**
* Simple connectivity test
* @description Simple connectivity test endpoint (no authentication required)
* @fullPath api.items.health.ping
* @service items
* @domain system-health
* @dataMethod healthData.ping
* @discoverable true
* @searchTerms ["ping", "connectivity test", "service alive", "basic health"]
* @relatedEndpoints ["api.joomla.health.ping", "api.nexus.health.ping", "api.commerce.health.ping"]
* @commonPatterns ["Test connectivity", "Basic health check", "Service alive check"]
* @workflow ["connectivity-verification", "basic-monitoring"]
* @prerequisites ["Network connectivity"]
* @nextSteps ["api.items.health.check for full health verification"]
* @businessRules ["No authentication required", "Always returns 'pong'", "Minimal resource usage"]
* @functionalArea "basic-connectivity-testing"
* @caching "No caching, real-time response"
* @performance "Ultra-lightweight endpoint for basic monitoring"
* @returns Ping response
* @throws ValidationError When response is malformed
* @example
* ```typescript
* const pong = await client.health.ping();
* console.log(pong.data); // "pong"
* ```
*/
ping: async () => {
return this.executeRequest({
method: 'GET',
path: '/ping',
responseSchema: PingResponseSchema,
requiresAuth: false,
});
},
};
/**
* Health monitoring data-only endpoints
* @description Data-only methods that return just the data portion of health responses
*/
this.healthData = {
/**
* Service health check data only
* @description Returns only the data portion of health check response
* @fullPath api.items.healthData.check
* @service items
* @domain system-health
* @discoverable true
* @searchTerms ["health data", "service status data", "health check data only"]
* @relatedEndpoints ["api.items.health.check"]
* @commonPatterns ["Get health status without metadata"]
* @returns Health check data only
*/
check: async () => {
const response = await this.health.check();
return response.data;
},
/**
* Simple connectivity test data only
* @description Returns only the data portion of ping response
* @fullPath api.items.healthData.ping
* @service items
* @domain system-health
* @discoverable true
* @searchTerms ["ping data", "connectivity data", "service alive data"]
* @relatedEndpoints ["api.items.health.ping"]
* @commonPatterns ["Test connectivity without metadata"]
* @returns Ping data only
*/
ping: async () => {
const response = await this.health.ping();
return response.data;
},
};
/**
* Item favorites management endpoints
* @description Methods for managing user favorite items
*/
this.itemFavorites = {
/**
* List user's favorite items
* @description Retrieve a list of the current user's favorite items
* @fullPath api.items.itemFavorites.list
* @service items
* @domain user-preferences
* @dataMethod itemFavoritesData.list
* @discoverable true
* @searchTerms ["favorites", "user favorites", "liked items", "bookmarked items", "favorite products"]
* @relatedEndpoints ["api.items.itemWishlist.list", "api.customers.users.preferences"]
* @commonPatterns ["Show user favorites", "Manage favorite items", "User preference management"]
* @workflow ["user-preferences", "favorites-management"]
* @prerequisites ["Valid authentication token", "User context"]
* @nextSteps ["api.items.invMast.get for product details", "api.commerce.cartHeaders.addItem for adding to cart"]
* @businessRules ["Shows only current user's favorites", "Respects product visibility", "Returns active favorites only"]
* @functionalArea "user-preference-management"
* @caching "Cache for 5 minutes, invalidate on favorites changes"
* @performance "Paginated results for large favorite lists"
* @param params Optional filtering and pagination parameters
* @returns Array of user's favorite items
* @throws ValidationError When parameters are invalid or response is malformed
* @example
* ```typescript
* const favorites = await client.itemFavorites.list({ limit: 20 });
* favorites.data.forEach(fav => {
* console.log(`Favorite: ${fav.itemDesc} (${fav.itemId})`);
* });
* ```
*/
list: async (params) => {
return this.executeRequest({
method: 'GET',
path: '/item-favorites',
paramsSchema: ItemFavoritesListParamsSchema,
responseSchema: ItemFavoriteListResponseSchema,
}, params);
},
/**
* Add item to favorites
* @description Add an item to the current user's favorites
* @param request Favorite item creation data
* @returns Created favorite item information
* @throws ValidationError When request is invalid or response is malformed
* @example
* ```typescript
* const favorite = await client.itemFavorites.create({
* invMastUid: 12345,
* itemNote: 'Great product for my projects'
* });
* ```
*/
create: this.createCreateMethod('/item-favorites', CreateItemFavoriteRequestSchema, ItemFavoriteResponseSchema),
/**
* Remove item from favorites
* @description Remove an item from the current user's favorites
* @param favoriteUid Favorite item unique identifier
* @returns Success response
* @throws ValidationError When response is malformed
* @example
* ```typescript
* await client.itemFavorites.delete(123);
* ```
*/
delete: this.createDeleteMethod('/item-favorites/{id}', ItemFavoriteResponseSchema),
/**
* Update favorite item
* @description Update a favorite item's information
* @param favoriteUid Favorite item unique identifier
* @param request Update data
* @returns Updated favorite item information
* @throws ValidationError When request is invalid or response is malformed
* @example
* ```typescript
* const updated = await client.itemFavorites.update(123, {
* itemNote: 'Updated note about this favorite item'
* });
* ```
*/
update: this.createUpdateMethod('/item-favorites/{id}', UpdateItemFavoriteRequestSchema, ItemFavoriteResponseSchema),
};
/**
* Item favorites data-only endpoints
* @description Data-only methods that return just the data portion of favorites responses
*/
this.itemFavoritesData = {
/**
* List user's favorite items data only
* @description Returns only the data portion of favorites list response
* @param params Optional filtering and pagination parameters
* @returns Array of favorite items data
*/
list: async (params) => {
const response = await this.itemFavorites.list(params);
return response.data;
},
};
/**
* Item wishlists management endpoints
* @description Methods for managing user wishlists and wishlist items
*/
this.itemWishlist = {
/**
* List user's wishlists
* @description Retrieve a list of the current user's wishlists
* @fullPath api.items.itemWishlist.list
* @service items
* @domain user-preferences
* @dataMethod itemWishlistData.list
* @discoverable true
* @searchTerms ["wishlists", "user wishlists", "shopping lists", "saved lists", "wishlist management"]
* @relatedEndpoints ["api.items.itemFavorites.list", "api.commerce.cartHeaders.list"]
* @commonPatterns ["Show user wishlists", "Manage wishlist collections", "Shopping list management"]
* @workflow ["user-preferences", "wishlist-management"]
* @prerequisites ["Valid authentication token", "User context"]
* @nextSteps ["api.items.itemWishlist.getLines for wishlist items", "api.commerce.cartHeaders.create for converting to cart"]