diff --git a/packages/types/src/customer/service.ts b/packages/types/src/customer/service.ts index 22ec786704..392b2da621 100644 --- a/packages/types/src/customer/service.ts +++ b/packages/types/src/customer/service.ts @@ -23,7 +23,7 @@ import { } from "./mutations" /** - * The main service interface for the customer module. + * The main service interface for the Customer Module. */ export interface ICustomerModuleService extends IModuleService { /** @@ -36,19 +36,23 @@ export interface ICustomerModuleService extends IModuleService { * @returns {Promise} The retrieved customer. * * @example - * A simple example that retrieves a {type name} by its ID: + * A simple example that retrieves a customer by its ID: * * ```ts - * {example-code} + * const customer = + * await customerModuleService.retrieve("cus_123") * ``` * * To specify relations that should be retrieved: * * ```ts - * {example-code} + * const customer = await customerModuleService.retrieve( + * "cus_123", + * { + * relations: ["groups"], + * } + * ) * ``` - * - * */ retrieve( customerId: string, @@ -57,14 +61,20 @@ export interface ICustomerModuleService extends IModuleService { ): Promise /** - * This method creates customers + * This method creates customers. * * @param {CreateCustomerDTO[]} data - The customers to be created. * @param {Context} sharedContext - A context used to share resources, such as transaction manager, between the application and the module. * @returns {Promise} The created customers. * * @example - * {example-code} + * const customers = await customerModuleService.create([ + * { + * email: "john@smith.com", + * first_name: "John", + * last_name: "Smith", + * }, + * ]) */ create( data: CreateCustomerDTO[], @@ -72,27 +82,36 @@ export interface ICustomerModuleService extends IModuleService { ): Promise /** - * This method creates customer + * This method creates a customer. * * @param {CreateCustomerDTO} data - The customer to be created. * @param {Context} sharedContext - A context used to share resources, such as transaction manager, between the application and the module. * @returns {Promise} The created customer. * * @example - * {example-code} + * const customer = await customerModuleService.create({ + * email: "john@smith.com", + * first_name: "John", + * last_name: "Smith", + * }) */ create(data: CreateCustomerDTO, sharedContext?: Context): Promise /** - * This method updates existing customer. + * This method updates an existing customer. * * @param {string} customerId - The customer's ID. - * @param {CustomerUpdatableFields} data - The details to update in the customer. + * @param {CustomerUpdatableFields} data - The updatable fields of a customer. * @param {Context} sharedContext - A context used to share resources, such as transaction manager, between the application and the module. * @returns {Promise} The updated customer. * * @example - * {example-code} + * const customer = await customerModuleService.update( + * "cus_123", + * { + * first_name: "Matt", + * } + * ) */ update( customerId: string, @@ -103,13 +122,18 @@ export interface ICustomerModuleService extends IModuleService { /** * This method updates existing customers. * - * @param {string[]} customerIds - The list of customer ID's to update. - * @param {CustomerUpdatableFields} data - The details to update in the customers. + * @param {string[]} customerIds - The IDs of customers to update. + * @param {CustomerUpdatableFields} data - The attributes to update in the customers. * @param {Context} sharedContext - A context used to share resources, such as transaction manager, between the application and the module. * @returns {Promise} The updated customers. * * @example - * {example-code} + * const customers = await customerModuleService.update( + * ["cus_123", "cus_321"], + * { + * company_name: "Acme", + * } + * ) */ update( customerIds: string[], @@ -118,15 +142,20 @@ export interface ICustomerModuleService extends IModuleService { ): Promise /** - * This method updates existing customers. Updated customers are selected based on the filters provided in the `selector` parameter. + * This method updates existing customers. * - * @param {FilterableCustomerProps} selector - The filters to specify which customers should be updated. - * @param {CustomerUpdatableFields} data - The details to update in the customers. + * @param {FilterableCustomerProps} selector - The filters that specify which API keys should be updated. + * @param {CustomerUpdatableFields} data - The attributes to update in the customers. * @param {Context} sharedContext - A context used to share resources, such as transaction manager, between the application and the module. * @returns {Promise} The updated customers. * * @example - * {example-code} + * const customers = await customerModuleService.update( + * { company_name: "Acme" }, + * { + * company_name: "Acme Inc.", + * } + * ) */ update( selector: FilterableCustomerProps, @@ -142,31 +171,33 @@ export interface ICustomerModuleService extends IModuleService { * @returns {Promise} Resolves when the customer is deleted successfully. * * @example - * {example-code} + * await customerModuleService.delete("cus_123") */ delete(customerId: string, sharedContext?: Context): Promise /** * This method deletes customers by their IDs. * - * @param {string[]} customerIds - The list of IDs of customers to delete. + * @param {string[]} customerIds - The IDs of customers. * @param {Context} sharedContext - A context used to share resources, such as transaction manager, between the application and the module. * @returns {Promise} Resolves when the customers are deleted successfully. * * @example - * {example-code} + * await customerModuleService.delete(["cus_123", "cus_321"]) */ delete(customerIds: string[], sharedContext?: Context): Promise /** - * This method deletes customers matching the specified filters in the `selector` parameter. + * This method deletes a customer matching the specified filters. * - * @param {FilterableCustomerProps} selector - The filters to specify which customers should be deleted. + * @param {FilterableCustomerProps} selector - The filters that specify which customers should be deleted. * @param {Context} sharedContext - A context used to share resources, such as transaction manager, between the application and the module. - * @returns {Promise} Resolves when the customers are deleted. + * @returns {Promise} Resolves when the customers are deleted successfully. * * @example - * {example-code} + * await customerModuleService.delete({ + * id: ["cus_123"], + * }) */ delete( selector: FilterableCustomerProps, @@ -176,13 +207,20 @@ export interface ICustomerModuleService extends IModuleService { /** * This method creates customer groups. * - * @param {CreateCustomerGroupDTO[]} data - The details of the customer groups to create. + * @param {CreateCustomerGroupDTO[]} data - The customer groups to be created. * @param {Context} sharedContext - A context used to share resources, such as transaction manager, between the application and the module. * @returns {Promise} The created customer groups. * - * * @privateRemarks * TODO should be pluralized + * + * @example + * const customerGroup = + * await customerModuleService.createCustomerGroup([ + * { + * name: "VIP", + * }, + * ]) */ createCustomerGroup( data: CreateCustomerGroupDTO[], @@ -192,12 +230,18 @@ export interface ICustomerModuleService extends IModuleService { /** * This method creates a customer group. * - * @param {CreateCustomerGroupDTO} data - The details of the customer group to create. + * @param {CreateCustomerGroupDTO} data - The customer group to be created. * @param {Context} sharedContext - A context used to share resources, such as transaction manager, between the application and the module. * @returns {Promise} The created customer group. * * @privateRemarks * TODO should be pluralized + * + * @example + * const customerGroup = + * await customerModuleService.createCustomerGroup({ + * name: "VIP", + * }) */ createCustomerGroup( data: CreateCustomerGroupDTO, @@ -207,26 +251,15 @@ export interface ICustomerModuleService extends IModuleService { /** * This method retrieves a customer group by its ID. * - * @param {string} groupId - The group's ID. + * @param {string} groupId - The customer group's ID. * @param {FindConfig} config - The configurations determining how the customer group is retrieved. Its properties, such as `select` or `relations`, accept the * attributes or relations associated with a customer group. * @param {Context} sharedContext - A context used to share resources, such as transaction manager, between the application and the module. - * @returns {Promise} The retrieved customer group(s). + * @returns {Promise} The retrieved customer group. * * @example - * A simple example that retrieves a {type name} by its ID: - * - * ```ts - * {example-code} - * ``` - * - * To specify relations that should be retrieved: - * - * ```ts - * {example-code} - * ``` - * - * + * const customerGroup = + * await customerModuleService.retrieve("cusgroup_123") */ retrieveCustomerGroup( groupId: string, @@ -235,15 +268,21 @@ export interface ICustomerModuleService extends IModuleService { ): Promise /** - * This method updates existing customer group. + * This method updates an existing customer group. * * @param {string} groupId - The group's ID. - * @param {CustomerGroupUpdatableFields} data - The details to update in the customer group. + * @param {CustomerGroupUpdatableFields} data - The attributes to update in the customer group. * @param {Context} sharedContext - A context used to share resources, such as transaction manager, between the application and the module. * @returns {Promise} The updated customer group. * * @example - * {example-code} + * const customerGroup = + * await customerModuleService.updateCustomerGroups( + * "cusgroup_123", + * { + * name: "Very Important", + * } + * ) */ updateCustomerGroups( groupId: string, @@ -254,13 +293,19 @@ export interface ICustomerModuleService extends IModuleService { /** * This method updates existing customer groups. * - * @param {string[]} groupIds - The list of customer groups IDs to update. - * @param {CustomerGroupUpdatableFields} data - The details to update in the customer groups. + * @param {string[]} groupIds - The IDs of customer groups. + * @param {CustomerGroupUpdatableFields} data - The attributes to update in the customer groups. * @param {Context} sharedContext - A context used to share resources, such as transaction manager, between the application and the module. * @returns {Promise} The updated customer groups. * * @example - * {example-code} + * const customerGroups = + * await customerModuleService.updateCustomerGroups( + * ["cusgroup_123", "cusgroup_321"], + * { + * name: "Very Important", + * } + * ) */ updateCustomerGroups( groupIds: string[], @@ -269,15 +314,23 @@ export interface ICustomerModuleService extends IModuleService { ): Promise /** - * This method updates existing customer groups. Updated groups are selected based on the filters provided in the `selector` parameter. + * This method updates existing customer groups. * - * @param {FilterableCustomerGroupProps} selector - The filters to specify which groups should be updated. - * @param {CustomerGroupUpdatableFields} data - The details to update in the customer groups. + * @param {FilterableCustomerGroupProps} selector - The filters that specify which customer groups should be updates. + * @param {CustomerGroupUpdatableFields} data - The attributes to update in the customer groups. * @param {Context} sharedContext - A context used to share resources, such as transaction manager, between the application and the module. * @returns {Promise} The updated customer groups. * * @example - * {example-code} + * const customerGroups = + * await customerModuleService.updateCustomerGroups( + * { + * name: "VIP", + * }, + * { + * name: "Very Important", + * } + * ) */ updateCustomerGroups( selector: FilterableCustomerGroupProps, @@ -288,24 +341,29 @@ export interface ICustomerModuleService extends IModuleService { /** * This method deletes a customer group by its ID. * - * @param {string} groupId - The group's ID. + * @param {string} groupId - The customer group's ID. * @param {Context} sharedContext - A context used to share resources, such as transaction manager, between the application and the module. - * @returns {Promise} Resolves when the customer group is deleted. + * @returns {Promise} Resolves when the customer group is deleted successfully. * * @example - * {example-code} + * await customerModuleService.deleteCustomerGroups( + * "cusgroup_123" + * ) */ deleteCustomerGroups(groupId: string, sharedContext?: Context): Promise /** - * This method deletes customer groups by their ID. + * This method deletes customer groups by their IDs. * - * @param {string[]} groupIds - The list of IDs of customer groups to delete. + * @param {string[]} groupIds - The IDs of customer groups. * @param {Context} sharedContext - A context used to share resources, such as transaction manager, between the application and the module. - * @returns {Promise} Resolves when the customer groups are deleted. + * @returns {Promise} Resolves when the customer groups are deleted successfully. * * @example - * {example-code} + * await customerModuleService.deleteCustomerGroups([ + * "cusgroup_123", + * "cusgroup_321", + * ]) */ deleteCustomerGroups( groupIds: string[], @@ -313,14 +371,16 @@ export interface ICustomerModuleService extends IModuleService { ): Promise /** - * This method deletes customer groups matching the specified filters in the `selector` parameter. + * This method deletes customer groups matching the specified filters. * - * @param {FilterableCustomerGroupProps} selector - The filters to specify which groups should be deleted. + * @param {FilterableCustomerGroupProps} selector - The filters that specify which customer group to delete. * @param {Context} sharedContext - A context used to share resources, such as transaction manager, between the application and the module. - * @returns {Promise} Resolves when the customer groups are deleted. + * @returns {Promise} Resolves when the customer groups are deleted successfully. * * @example - * {example-code} + * await customerModuleService.deleteCustomerGroups({ + * name: "VIP", + * }) */ deleteCustomerGroups( selector: FilterableCustomerGroupProps, @@ -328,14 +388,18 @@ export interface ICustomerModuleService extends IModuleService { ): Promise /** - * This method adds customers to a group. + * This method adds a customer to a group. * * @param {GroupCustomerPair} groupCustomerPair - The details of the customer and the group it should be added to. * @param {Context} sharedContext - A context used to share resources, such as transaction manager, between the application and the module. * @returns {Promise<{ id: string; }>} The ID of the relation between the customer and the group. * * @example - * {example-code} + * const customerGroupCustomerId = + * await customerModuleService.addCustomerToGroup({ + * customer_id: "cus_123", + * customer_group_id: "cus_321", + * }) */ addCustomerToGroup( groupCustomerPair: GroupCustomerPair, @@ -350,13 +414,18 @@ export interface ICustomerModuleService extends IModuleService { /** * This method adds customers to groups. * - * @param {GroupCustomerPair[]} groupCustomerPairs - A list of customer-group pairs, where each item in the list indicates the customer and what - * group it should be added to. + * @param {GroupCustomerPair[]} groupCustomerPairs - A list of items, each being the details of a customer and the group it should be added to. * @param {Context} sharedContext - A context used to share resources, such as transaction manager, between the application and the module. - * @returns {Promise<{ id: string; }[]>} The list of IDs of the relations created between the customers and the groups. + * @returns {Promise<{ id: string; }[]>} The IDs of the relations between each of the customer and group pairs. * * @example - * {example-code} + * const customerGroupCustomerIds = + * await customerModuleService.addCustomerToGroup([ + * { + * customer_id: "cus_123", + * customer_group_id: "cus_321", + * }, + * ]) */ addCustomerToGroup( groupCustomerPairs: GroupCustomerPair[], @@ -373,12 +442,18 @@ export interface ICustomerModuleService extends IModuleService { /** * This method removes a customer from a group. * - * @param {GroupCustomerPair} groupCustomerPair - The details of the customer and which group to remove it from. + * @param {GroupCustomerPair} groupCustomerPair - The details of the customer and the group it should be removed from. * @param {Context} sharedContext - A context used to share resources, such as transaction manager, between the application and the module. * @returns {Promise} Resolves when the customer is removed from the group successfully. * * @privateRemarks * TODO should be pluralized + * + * @example + * await customerModuleService.removeCustomerFromGroup({ + * customer_id: "cus_123", + * customer_group_id: "cus_321", + * }) */ removeCustomerFromGroup( groupCustomerPair: GroupCustomerPair, @@ -388,13 +463,20 @@ export interface ICustomerModuleService extends IModuleService { /** * This method removes customers from groups. * - * @param {GroupCustomerPair[]} groupCustomerPairs - A list of customer-group pairs, where each item in the list indicates the customer and what - * group it should be removed from. + * @param {GroupCustomerPair[]} groupCustomerPairs - A list of items, each being the details of a customer and the group it should be removed from. * @param {Context} sharedContext - A context used to share resources, such as transaction manager, between the application and the module. * @returns {Promise} Resolves when the customers are removed from the groups successfully. * * @privateRemarks * TODO should be pluralized + * + * @example + * await customerModuleService.removeCustomerFromGroup([ + * { + * customer_id: "cus_123", + * customer_group_id: "cus_321", + * }, + * ]) */ removeCustomerFromGroup( groupCustomerPairs: GroupCustomerPair[], @@ -402,14 +484,22 @@ export interface ICustomerModuleService extends IModuleService { ): Promise /** - * This method adds addresses to a customer. + * This method adds addresses to customers. * - * @param {CreateCustomerAddressDTO[]} addresses - The customer addresses to be created. + * @param {CreateCustomerAddressDTO[]} addresses - A list of items, each being the details of the address to add to a customer. * @param {Context} sharedContext - A context used to share resources, such as transaction manager, between the application and the module. - * @returns {Promise} The created customer addresses. + * @returns {Promise} The list of created addresses. * * @example - * {example-code} + * const addresses = await customerModuleService.addAddresses([ + * { + * customer_id: "cus_123", + * address_name: "Home", + * address_1: "432 Stierlin Rd", + * city: "Mountain View", + * country_code: "us", + * }, + * ]) */ addAddresses( addresses: CreateCustomerAddressDTO[], @@ -417,14 +507,20 @@ export interface ICustomerModuleService extends IModuleService { ): Promise /** - * This method adds an address to a customer + * This method adds an address to a customer. * - * @param {CreateCustomerAddressDTO} address - The customer address to be created. + * @param {CreateCustomerAddressDTO} address - The details of the address to add to a customer. * @param {Context} sharedContext - A context used to share resources, such as transaction manager, between the application and the module. - * @returns {Promise} The created customer address. + * @returns {Promise} The created address. * * @example - * {example-code} + * const address = await customerModuleService.addAddresses({ + * customer_id: "cus_123", + * address_name: "Home", + * address_1: "432 Stierlin Rd", + * city: "Mountain View", + * country_code: "us", + * }) */ addAddresses( address: CreateCustomerAddressDTO, @@ -432,15 +528,21 @@ export interface ICustomerModuleService extends IModuleService { ): Promise /** - * This method updates an existing address by its ID. + * This method updates an address. * * @param {string} addressId - The address's ID. - * @param {UpdateCustomerAddressDTO} data - The attributes to update in the customer address. + * @param {UpdateCustomerAddressDTO} data - The attributes to update in the address. * @param {Context} sharedContext - A context used to share resources, such as transaction manager, between the application and the module. - * @returns {Promise} The updated addresses. + * @returns {Promise} The updated address. * * @example - * {example-code} + * const address = await customerModuleService.updateAddresses( + * "cuaddr_123", + * { + * first_name: "John", + * last_name: "Smith", + * } + * ) */ updateAddresses( addressId: string, @@ -451,13 +553,19 @@ export interface ICustomerModuleService extends IModuleService { /** * This method updates existing addresses. * - * @param {string[]} addressIds - The list of IDs of addresses to update. - * @param {UpdateCustomerAddressDTO} data - The attributes to update in each customer address. + * @param {string[]} addressIds - The IDs of addresses to update. + * @param {UpdateCustomerAddressDTO} data - The attributes to update in the addresses. * @param {Context} sharedContext - A context used to share resources, such as transaction manager, between the application and the module. - * @returns {Promise} The updated customer addresses. + * @returns {Promise} The updated addresses. * * @example - * {example-code} + * const addresses = await customerModuleService.updateAddresses( + * ["cuaddr_123", "cuaddr_321"], + * { + * first_name: "John", + * last_name: "Smith", + * } + * ) */ updateAddresses( addressIds: string[], @@ -466,15 +574,20 @@ export interface ICustomerModuleService extends IModuleService { ): Promise /** - * This method updates addresses matching the specified filters in the `selector` parameter. + * This method updates existing addresses matching the specified filters. * - * @param {FilterableCustomerAddressProps} selector - The filters to specify which addresses should be updated. - * @param {UpdateCustomerAddressDTO} data - The attributes to update in each customer address. + * @param {FilterableCustomerAddressProps} selector - The filters that specify which address should be updated. + * @param {UpdateCustomerAddressDTO} data - The attributes to update in the addresses. * @param {Context} sharedContext - A context used to share resources, such as transaction manager, between the application and the module. - * @returns {Promise} The updated customer addresses. + * @returns {Promise} The updated addresses. * * @example - * {example-code} + * const addresses = await customerModuleService.updateAddresses( + * { first_name: "John" }, + * { + * last_name: "Smith", + * } + * ) */ updateAddresses( selector: FilterableCustomerAddressProps, @@ -490,31 +603,37 @@ export interface ICustomerModuleService extends IModuleService { * @returns {Promise} Resolves when the address is deleted successfully. * * @example - * {example-code} + * await customerModuleService.deleteAddresses("cuaddr_123") */ deleteAddresses(addressId: string, sharedContext?: Context): Promise /** * This method deletes addresses by their IDs. * - * @param {string[]} addressIds - The list of IDs of addresses to delete. + * @param {string[]} addressIds - The IDs of addresses. * @param {Context} sharedContext - A context used to share resources, such as transaction manager, between the application and the module. * @returns {Promise} Resolves when the addresses are deleted successfully. * * @example - * {example-code} + * await customerModuleService.deleteAddresses([ + * "cuaddr_123", + * "cuaddr_321", + * ]) */ deleteAddresses(addressIds: string[], sharedContext?: Context): Promise /** - * This method deletes addresses matching the specified filters in the `selector` parameter. + * This method deletes addresses matching the specified filters. * - * @param {FilterableCustomerAddressProps} selector - The filters to specify which addresses should be deleted. + * @param {FilterableCustomerAddressProps} selector - The filters that specify which addresses should be deleted. * @param {Context} sharedContext - A context used to share resources, such as transaction manager, between the application and the module. - * @returns {Promise} Resolves when the addresses are deleted. + * @returns {Promise} Resolves when the addresses are deleted successfully. * * @example - * {example-code} + * await customerModuleService.deleteAddresses({ + * first_name: "John", + * last_name: "Smith", + * }) */ deleteAddresses( selector: FilterableCustomerAddressProps, @@ -524,32 +643,48 @@ export interface ICustomerModuleService extends IModuleService { /** * This method retrieves a paginated list of addresses based on optional filters and configuration. * - * @param {FilterableCustomerAddressProps} filters - The filters to apply on the retrieved customer address. - * @param {FindConfig} config - The configurations determining how the customer address is retrieved. Its properties, such as `select` or `relations`, accept the - * attributes or relations associated with a customer address. + * @param {FilterableCustomerAddressProps} filters - The filters to apply on the retrieved addresss. + * @param {FindConfig} config - The configurations determining how the address is retrieved. Its properties, such as `select` or `relations`, accept the + * attributes or relations associated with a address. * @param {Context} sharedContext - A context used to share resources, such as transaction manager, between the application and the module. * @returns {Promise} The list of addresses. * * @example - * To retrieve a list of {type name} using their IDs: + * To retrieve a list of addresses using their IDs: * * ```ts - * {example-code} + * const addresses = await customerModuleService.listAddresses({ + * id: ["cuaddr_123", "cuaddr_321"], + * }) * ``` * - * To specify relations that should be retrieved within the {type name}: + * To specify relations that should be retrieved within the addresses: * * ```ts - * {example-code} + * const addresses = await customerModuleService.listAddresses( + * { + * id: ["cuaddr_123", "cuaddr_321"], + * }, + * { + * relations: ["customer"], + * } + * ) * ``` * - * By default, only the first `{default limit}` records are retrieved. You can control pagination by specifying the `skip` and `take` properties of the `config` parameter: + * By default, only the first `15` records are retrieved. You can control pagination by specifying the `skip` and `take` properties of the `config` parameter: * * ```ts - * {example-code} + * const addresses = await customerModuleService.listAddresses( + * { + * id: ["cuaddr_123", "cuaddr_321"], + * }, + * { + * relations: ["customer"], + * take: 20, + * skip: 2, + * } + * ) * ``` - * - * */ listAddresses( filters?: FilterableCustomerAddressProps, @@ -560,32 +695,51 @@ export interface ICustomerModuleService extends IModuleService { /** * This method retrieves a paginated list of addresses along with the total count of available addresses satisfying the provided filters. * - * @param {FilterableCustomerAddressProps} filters - The filters to apply on the retrieved customer address. - * @param {FindConfig} config - The configurations determining how the customer address is retrieved. Its properties, such as `select` or `relations`, accept the - * attributes or relations associated with a customer address. + * @param {FilterableCustomerAddressProps} filters - The filters to apply on the retrieved addresss. + * @param {FindConfig} config - The configurations determining how the address is retrieved. Its properties, such as `select` or `relations`, accept the + * attributes or relations associated with a address. * @param {Context} sharedContext - A context used to share resources, such as transaction manager, between the application and the module. * @returns {Promise<[CustomerAddressDTO[], number]>} The list of addresses along with their total count. * * @example - * To retrieve a list of {type name} using their IDs: + * To retrieve a list of addresses using their IDs: * * ```ts - * {example-code} + * const [addresses, count] = + * await customerModuleService.listAndCountAddresses({ + * id: ["cuaddr_123", "cuaddr_321"], + * }) * ``` * - * To specify relations that should be retrieved within the {type name}: + * To specify relations that should be retrieved within the addresses: * * ```ts - * {example-code} + * const [addresses, count] = + * await customerModuleService.listAndCountAddresses( + * { + * id: ["cuaddr_123", "cuaddr_321"], + * }, + * { + * relations: ["customer"], + * } + * ) * ``` * - * By default, only the first `{default limit}` records are retrieved. You can control pagination by specifying the `skip` and `take` properties of the `config` parameter: + * By default, only the first `15` records are retrieved. You can control pagination by specifying the `skip` and `take` properties of the `config` parameter: * * ```ts - * {example-code} + * const [addresses, count] = + * await customerModuleService.listAndCountAddresses( + * { + * id: ["cuaddr_123", "cuaddr_321"], + * }, + * { + * relations: ["customer"], + * take: 20, + * skip: 2, + * } + * ) * ``` - * - * */ listAndCountAddresses( filters?: FilterableCustomerAddressProps, @@ -594,34 +748,53 @@ export interface ICustomerModuleService extends IModuleService { ): Promise<[CustomerAddressDTO[], number]> /** - * This method retrieves a paginated list of customer group's customers based on optional filters and configuration. + * This method retrieves a paginated list of relations between customer and groups based on optional filters and configuration. * - * @param {FilterableCustomerGroupCustomerProps} filters - The filters to apply on the retrieved customer group customer. - * @param {FindConfig} config - The configurations determining how the customer group customer is retrieved. Its properties, such as `select` or `relations`, accept the - * attributes or relations associated with a customer group customer. + * @param {FilterableCustomerGroupCustomerProps} filters - The filters to apply on the retrieved customer-group relations. + * @param {FindConfig} config - The configurations determining how the customer-group relations is retrieved. Its properties, such as `select` or `relations`, accept the + * attributes or relations associated with a customer-group relations. * @param {Context} sharedContext - A context used to share resources, such as transaction manager, between the application and the module. - * @returns {Promise} The list of customer group's customers. + * @returns {Promise} The list of customer-group relations. * * @example - * To retrieve a list of {type name} using their IDs: + * To retrieve a list of customer-group relations using their IDs: * * ```ts - * {example-code} + * const customerGroupCustomerRels = + * await customerModuleService.listCustomerGroupCustomers({ + * id: ["cusgc_123"], + * }) * ``` * - * To specify relations that should be retrieved within the {type name}: + * To specify relations that should be retrieved within the customer-group relations: * * ```ts - * {example-code} + * const customerGroupCustomerRels = + * await customerModuleService.listCustomerGroupCustomers( + * { + * id: ["cusgc_123"], + * }, + * { + * relations: ["customer", "customer_group"], + * } + * ) * ``` * - * By default, only the first `{default limit}` records are retrieved. You can control pagination by specifying the `skip` and `take` properties of the `config` parameter: + * By default, only the first `15` records are retrieved. You can control pagination by specifying the `skip` and `take` properties of the `config` parameter: * * ```ts - * {example-code} + * const customerGroupCustomerRels = + * await customerModuleService.listCustomerGroupCustomers( + * { + * id: ["cusgc_123"], + * }, + * { + * relations: ["customer", "customer_group"], + * take: 20, + * skip: 2, + * } + * ) * ``` - * - * */ listCustomerGroupCustomers( filters?: FilterableCustomerGroupCustomerProps, @@ -632,32 +805,48 @@ export interface ICustomerModuleService extends IModuleService { /** * This method retrieves a paginated list of customers based on optional filters and configuration. * - * @param {FilterableCustomerProps} filters - The filters to apply on the retrieved customer. + * @param {FilterableCustomerProps} filters - The filters to apply on the retrieved customers. * @param {FindConfig} config - The configurations determining how the customer is retrieved. Its properties, such as `select` or `relations`, accept the * attributes or relations associated with a customer. * @param {Context} sharedContext - A context used to share resources, such as transaction manager, between the application and the module. * @returns {Promise} The list of customers. * * @example - * To retrieve a list of {type name} using their IDs: + * To retrieve a list of customers using their IDs: * * ```ts - * {example-code} + * const customers = await customerModuleService.list({ + * id: ["cus_123", "cus_321"], + * }) * ``` * - * To specify relations that should be retrieved within the {type name}: + * To specify relations that should be retrieved within the customers: * * ```ts - * {example-code} + * const customers = await customerModuleService.list( + * { + * id: ["cus_123", "cus_321"], + * }, + * { + * relations: ["groups"], + * } + * ) * ``` * - * By default, only the first `{default limit}` records are retrieved. You can control pagination by specifying the `skip` and `take` properties of the `config` parameter: + * By default, only the first `15` records are retrieved. You can control pagination by specifying the `skip` and `take` properties of the `config` parameter: * * ```ts - * {example-code} + * const customers = await customerModuleService.list( + * { + * id: ["cus_123", "cus_321"], + * }, + * { + * relations: ["groups"], + * take: 20, + * skip: 2, + * } + * ) * ``` - * - * */ list( filters?: FilterableCustomerProps, @@ -668,32 +857,48 @@ export interface ICustomerModuleService extends IModuleService { /** * This method retrieves a paginated list of customers along with the total count of available customers satisfying the provided filters. * - * @param {FilterableCustomerProps} filters - The filters to apply on the retrieved customer. + * @param {FilterableCustomerProps} filters - The filters to apply on the retrieved customers. * @param {FindConfig} config - The configurations determining how the customer is retrieved. Its properties, such as `select` or `relations`, accept the * attributes or relations associated with a customer. * @param {Context} sharedContext - A context used to share resources, such as transaction manager, between the application and the module. * @returns {Promise<[CustomerDTO[], number]>} The list of customers along with their total count. * * @example - * To retrieve a list of {type name} using their IDs: + * To retrieve a list of customers using their IDs: * * ```ts - * {example-code} + * const [customers, count] = await customerModuleService.list({ + * id: ["cus_123", "cus_321"], + * }) * ``` * - * To specify relations that should be retrieved within the {type name}: + * To specify relations that should be retrieved within the customers: * * ```ts - * {example-code} + * const [customers, count] = await customerModuleService.list( + * { + * id: ["cus_123", "cus_321"], + * }, + * { + * relations: ["groups"], + * } + * ) * ``` * - * By default, only the first `{default limit}` records are retrieved. You can control pagination by specifying the `skip` and `take` properties of the `config` parameter: + * By default, only the first `15` records are retrieved. You can control pagination by specifying the `skip` and `take` properties of the `config` parameter: * * ```ts - * {example-code} + * const [customers, count] = await customerModuleService.list( + * { + * id: ["cus_123", "cus_321"], + * }, + * { + * relations: ["groups"], + * take: 20, + * skip: 2, + * } + * ) * ``` - * - * */ listAndCount( filters?: FilterableCustomerProps, @@ -704,32 +909,51 @@ export interface ICustomerModuleService extends IModuleService { /** * This method retrieves a paginated list of customer groups based on optional filters and configuration. * - * @param {FilterableCustomerGroupProps} filters - The filters to apply on the retrieved customer group. + * @param {FilterableCustomerGroupProps} filters - The filters to apply on the retrieved customer groups. * @param {FindConfig} config - The configurations determining how the customer group is retrieved. Its properties, such as `select` or `relations`, accept the * attributes or relations associated with a customer group. * @param {Context} sharedContext - A context used to share resources, such as transaction manager, between the application and the module. * @returns {Promise} The list of customer groups. * * @example - * To retrieve a list of {type name} using their IDs: + * To retrieve a list of customer groups using their IDs: * * ```ts - * {example-code} + * const customerGroups = + * await customerModuleService.listCustomerGroups({ + * id: ["cusgroup_123", "cusgroup_321"], + * }) * ``` * - * To specify relations that should be retrieved within the {type name}: + * To specify relations that should be retrieved within the customer groups: * * ```ts - * {example-code} + * const customerGroups = + * await customerModuleService.listCustomerGroups( + * { + * id: ["cusgroup_123", "cusgroup_321"], + * }, + * { + * relations: ["customers"], + * } + * ) * ``` * - * By default, only the first `{default limit}` records are retrieved. You can control pagination by specifying the `skip` and `take` properties of the `config` parameter: + * By default, only the first `15` records are retrieved. You can control pagination by specifying the `skip` and `take` properties of the `config` parameter: * * ```ts - * {example-code} + * const customerGroups = + * await customerModuleService.listCustomerGroups( + * { + * id: ["cusgroup_123", "cusgroup_321"], + * }, + * { + * relations: ["customers"], + * take: 20, + * skip: 2, + * } + * ) * ``` - * - * */ listCustomerGroups( filters?: FilterableCustomerGroupProps, @@ -740,32 +964,51 @@ export interface ICustomerModuleService extends IModuleService { /** * This method retrieves a paginated list of customer groups along with the total count of available customer groups satisfying the provided filters. * - * @param {FilterableCustomerGroupProps} filters - The filters to apply on the retrieved customer group. + * @param {FilterableCustomerGroupProps} filters - The filters to apply on the retrieved customer groups. * @param {FindConfig} config - The configurations determining how the customer group is retrieved. Its properties, such as `select` or `relations`, accept the * attributes or relations associated with a customer group. * @param {Context} sharedContext - A context used to share resources, such as transaction manager, between the application and the module. * @returns {Promise<[CustomerGroupDTO[], number]>} The list of customer groups along with their total count. * * @example - * To retrieve a list of {type name} using their IDs: + * To retrieve a list of customer groups using their IDs: * * ```ts - * {example-code} + * const [customerGroups, count] = + * await customerModuleService.listCustomerGroups({ + * id: ["cusgroup_123", "cusgroup_321"], + * }) * ``` * - * To specify relations that should be retrieved within the {type name}: + * To specify relations that should be retrieved within the customer groups: * * ```ts - * {example-code} + * const [customerGroups, count] = + * await customerModuleService.listCustomerGroups( + * { + * id: ["cusgroup_123", "cusgroup_321"], + * }, + * { + * relations: ["customers"], + * } + * ) * ``` * - * By default, only the first `{default limit}` records are retrieved. You can control pagination by specifying the `skip` and `take` properties of the `config` parameter: + * By default, only the first `15` records are retrieved. You can control pagination by specifying the `skip` and `take` properties of the `config` parameter: * * ```ts - * {example-code} + * const [customerGroups, count] = + * await customerModuleService.listCustomerGroups( + * { + * id: ["cusgroup_123", "cusgroup_321"], + * }, + * { + * relations: ["customers"], + * take: 20, + * skip: 2, + * } + * ) * ``` - * - * */ listAndCountCustomerGroups( filters?: FilterableCustomerGroupProps, @@ -776,13 +1019,17 @@ export interface ICustomerModuleService extends IModuleService { /** * This method soft deletes customers by their IDs. * - * @param {string[]} customerIds - The list of IDs of customers to soft delete. + * @param {string[]} customerIds - The IDs of customers. * @param {SoftDeleteReturn} config - An object that is used to specify an entity's related entities that should be soft-deleted when the main entity is soft-deleted. * @param {Context} sharedContext - A context used to share resources, such as transaction manager, between the application and the module. - * @returns {Promise>} Resolves when the customers are deleted successfully. + * @returns {Promise>} An object that includes the IDs of related records that were also soft deleted, such as the ID of the associated address. + * The object's keys are the ID attribute names of the customer entity's relations, such as `address_id`, and its value is an array of strings, each being the ID of a record associated + * with the customer through this relation, such as the IDs of associated address. + * + * If there are no related records, the promise resolves to `void`. * * @example - * {example-code} + * await customerModuleService.softDelete(["cus_123"]) */ softDelete( customerIds: string[], @@ -791,19 +1038,17 @@ export interface ICustomerModuleService extends IModuleService { ): Promise | void> /** - * This method restores soft deleted customers by their IDs. + * This method restores soft deleted customer by their IDs. * - * @param {string[]} customerIds - The list of IDs of customers to restore. - * @param {RestoreReturn} config - Configurations determining which relations to restore along with each of the customers. You can pass to its `returnLinkableKeys` - * property any of the customer's relation attribute names, such as `addresses`. + * @param {string[]} customerIds - The IDs of customers. + * @param {RestoreReturn} config - Configurations determining which relations to restore along with each of the customer. You can pass to its `returnLinkableKeys` + * property any of the customer's relation attribute names, such as `groups`. * @param {Context} sharedContext - A context used to share resources, such as transaction manager, between the application and the module. - * @returns {Promise>} An object that includes the IDs of related records that were restored, such as the ID of associated address. - * The object's keys are the ID attribute names of the customer entity's relations, - * and its value is an array of strings, each being the ID of the record associated with the customer through this relation, - * such as the IDs of associated addresses. + * @returns {Promise>} An object that includes the IDs of related records that were restored. + * If there are no related records restored, the promise resolves to `void`. * * @example - * {example-code} + * await customerModuleService.restore(["cus_123"]) */ restore( customerIds: string[], @@ -814,13 +1059,16 @@ export interface ICustomerModuleService extends IModuleService { /** * This method soft deletes customer groups by their IDs. * - * @param {string[]} groupIds - The list of IDs of customer groups to soft delete. + * @param {string[]} groupIds - The IDs of customer groups. * @param {SoftDeleteReturn} config - An object that is used to specify an entity's related entities that should be soft-deleted when the main entity is soft-deleted. * @param {Context} sharedContext - A context used to share resources, such as transaction manager, between the application and the module. - * @returns {Promise>} Resolves whe the customer groups are soft-deleted successfully. + * @returns {Promise>} An object that includes the IDs of related records that were also soft deleted. + * If there are no related records, the promise resolves to `void`. * * @example - * {example-code} + * await customerModuleService.softDeleteCustomerGroups([ + * "cusgroup_123", + * ]) */ softDeleteCustomerGroups( groupIds: string[], @@ -829,19 +1077,19 @@ export interface ICustomerModuleService extends IModuleService { ): Promise | void> /** - * This method restores soft deleted customer groups by their IDs. + * This method restores a soft deleted customer group by its IDs. * - * @param {string[]} groupIds - The list of IDs of customer groups to restore. - * @param {RestoreReturn} config - Configurations determining which relations to restore along with each of the customer group. You can pass to its `returnLinkableKeys` + * @param {string[]} groupIds - The IDs of customer groups. + * @param {RestoreReturn} config - Configurations determining which relations to restore along with each of the customer groups. You can pass to its `returnLinkableKeys` * property any of the customer group's relation attribute names, such as `customers`. * @param {Context} sharedContext - A context used to share resources, such as transaction manager, between the application and the module. - * @returns {Promise>} An object that includes the IDs of related records that were restored, such as the ID of associated customer. - * The object's keys are the ID attribute names of the customer group entity's relations, - * and its value is an array of strings, each being the ID of the record associated with the customer through this relation, - * such as the IDs of associated customer. + * @returns {Promise>} An object that includes the IDs of related records that were restored. + * If there are no related records restored, the promise resolves to `void`. * * @example - * {example-code} + * await customerModuleService.restoreCustomerGroups([ + * "cusgroup_123", + * ]) */ restoreCustomerGroups( groupIds: string[],