From edca656fc3d5719c09349a55a126f804bf563c26 Mon Sep 17 00:00:00 2001 From: Kevin Harper Date: Sun, 3 Nov 2024 23:25:44 -0600 Subject: [PATCH 1/4] Add user account functions --- astro.config.mjs | 1 + .../docs/dropins/user-account/functions.mdx | 543 ++++++++++++++++++ 2 files changed, 544 insertions(+) create mode 100644 src/content/docs/dropins/user-account/functions.mdx diff --git a/astro.config.mjs b/astro.config.mjs index 1c40cf87..128cee5e 100644 --- a/astro.config.mjs +++ b/astro.config.mjs @@ -238,6 +238,7 @@ export default defineConfig({ collapsed: true, items: [ { label: 'Overview', link: '/dropins/user-account/' }, + { label: 'Functions', link: '/dropins/user-account/functions/' }, ] }] diff --git a/src/content/docs/dropins/user-account/functions.mdx b/src/content/docs/dropins/user-account/functions.mdx new file mode 100644 index 00000000..614a8f91 --- /dev/null +++ b/src/content/docs/dropins/user-account/functions.mdx @@ -0,0 +1,543 @@ +--- +title: User account functions +description: Learn about the API functions provided by the User Account dropin. +--- + +import OptionsTable from '@components/OptionsTable.astro'; + +## createCustomerAddress + +The `createCustomerAddress` function creates an address for an existing customer using the `CustomerAddressesModel` object as an argument. The functions calls the [`createCustomerAddress`](https://developer.adobe.com/commerce/webapi/graphql/schema/customer/mutations/create-customer-address/) mutation. + +```ts +export const createCustomerAddress = async ( + address: CustomerAddressesModel +): Promise +``` + + + +The `CustomerAddressesModel` object has the following fields: + + + + +### Returns + +Returns a promise that resolves to a string. + +### Usage + +To create a new address: + +```ts +import { createCustomerAddress } from '@/account/api/createCustomerAddress'; + +const address = { + firstName: 'John', + lastName: 'Doe', + city: 'Los Angeles', + company: 'Adobe', + countryCode: 'US', + region: { + region: 'California', + regionCode: 'CA', + regionId: '12', + }, + telephone: '1234567890', + postcode: '90001', + street: '123 Main St', + streetMultiline_2: 'Suite 100', + defaultShipping: true, + defaultBilling: true, +}; +``` + +## getAttributesForm + +The `getAttributesForm` function uses the [`attributesForm`](https://developer.adobe.com/commerce/webapi/graphql/schema/attributes/queries/attributes-form/) query to retrieve EAV attributes associated with customer and customer address frontend forms. The `formCode` parameter must be one of the following values: `customer_account_create`, `customer_account_edit`, `customer_address_create`, or `customer_address_edit`. + +```ts +export const getAttributesForm = async ( + formCode: string +): Promise +``` + + + +### Returns + +Returns a promise that resolves to an `AttributesFormModel` array. It has the following shape: + +```javascript +{ + items { + code + default_value + entity_type + frontend_class + frontend_input + is_required + is_unique + label + options { + is_default + label + value + } + ... on CustomerAttributeMetadata { + multiline_count + sort_order + validate_rules { + name + value + } + } + } + errors { + type + message + } + } +``` + +### Usage + +To get attributes associated with the `customer_address_edit` form: + +```ts +import { getAttributesForm } from '@/account/api/getAttributesForm'; + +getAttributesForm(formCode: 'customer_address_edit'); +``` + +## getCountries + +The `getCountries` function uses the [`countries`](https://developer.adobe.com/commerce/webapi/graphql/schema/directory/queries/countries/) query to retrieve a list of countries. + +```ts +export const getCountries = async (): Promise<{ + availableCountries: Country[] | []; + countriesWithRequiredRegion: string[]; + optionalZipCountries: string[]; +}> +``` + +### Returns + +Returns a promise that resolves to arrays of countries, regions, and postal codes. + +```ts +{ + countries { + two_letter_abbreviation + full_name_locale + } + storeConfig { + countries_with_required_region + optional_zip_countries + } + } +``` + +### Usage + +To get a list of countries: + +```javascript +import { getCountries } from '@/account/api/getCountries'; + +getCountries(); +``` + +## getCustomer + +The `getCustomer` function retrieves the customer information for the logged-in customer. The function uses the [`customer`](https://developer.adobe.com/commerce/webapi/graphql/schema/customer/queries/customer/) query. + +```ts +export const getCustomer = async (): Promise +``` + +### Returns + +Returns a promise that resolves to CustomerDataModelShort object: + +```ts +export interface CustomerDataModelShort { + firstName: string; + lastName: string; + middleName: string; + dateOfBirth: string; + dob: string; + prefix: string; + gender: 1 | 2 | string; + suffix: string; + email: string; + createdAt: string; + [key: string]: string | boolean | number; +} +``` + +### Usage + +To get details about the customer: + +```javascript +import { getCustomer } from '@/account/api/getCustomer'; + +getCustomer(); +``` + +## getCustomerAddress + +The `getCustomerAddress` function returns an array of addresses associated with the current customer. The function uses the [`customer`](https://developer.adobe.com/commerce/webapi/graphql/schema/customer/queries/customer/) query. + +```ts +export const getCustomerAddress = async (): Promise< + CustomerAddressesModel[] +> +``` + +### Returns + +Returns a promise that resolves to `CustomerAddressesModel` object: + +```ts +export interface CustomerAddressesModel { + firstName?: string; + lastName?: string; + city?: string; + company?: string; + countryCode?: string; + region?: { region: string; regionCode: string; regionId: string | number }; + telephone?: string; + id?: string; + vatId?: string; + postcode?: string; + street?: string; + streetMultiline_2?: string; + defaultShipping?: boolean; + defaultBilling?: boolean; +} +``` + +### Usage + +To get information about customer address + +```javascript +import { getCustomerAddress } from '@/account/api/getCustomerAddress'; + +getCustomerAddress(); +``` + +## getRegions + +The `getRegions` function uses the [`country`](https://developer.adobe.com/commerce/webapi/graphql/schema/directory/queries/country/) query to retrieve a list of states or provinves for a specific country. + + +```ts +export const getRegions = async ( + countryCode: string +): Promise + +### Returns + +Returns a promise that resolves to a `RegionTransform` array: + +```ts +export interface RegionTransform { + text: string; + value: string; + id?: string | number; +} +``` + +### Usage + +To get a list of regions for a specific country: + +```ts +import { getRegions } from '@/account/api/getRegions'; + +getRegions(countryCode: "AS"); +``` + +## getStoreConfig + +The `getStoreConfig` function uses the [`storeConfig`](https://developer.adobe.com/commerce/webapi/graphql/schema/store/queries/store-config/) query to retrieve details about password requirements. + +```ts +export const getStoreConfig = async (): Promise +``` + +### Returns + +Returns a promise that resolves to a `StoreConfigModel` object: + +```ts +export interface StoreConfigModel { + minLength: number; + requiredCharacterClasses: number; +} +``` + +### Usage + +To get the store configuration: + +```ts +import { getStoreConfig } from '@/account/api/getStoreConfig'; + +getStoreConfig(); +``` + +## removeCustomerAddress + +The `removeCustomerAddress` function removes an address associated with the current customer. The function uses the [`deleteCustomerAddress`](https://developer.adobe.com/commerce/webapi/graphql/schema/customer/mutations/delete-address/) mutation. + + +```ts +export const removeCustomerAddress = async ( + addressId: number +): Promise +``` + + + +### Returns + +Returns a promise that resolves to a boolean value that indicates whether the address was removed. + +### Usage + +To remove an address: + +```ts +import { removeCustomerAddress } from '@/account/api/removeCustomerAddress'; + +removeCustomerAddress(id: "1"); +``` + +## updateCustomer + +The `updateCustomer` function updates the logged-in customer. The function uses the [`updateCustomerV2`](https://developer.adobe.com/commerce/webapi/graphql/schema/customer/mutations/update-v2/) mutation. + +The `form` object keys are converted to snake_case using the `convertKeysCase` utility with specific mappings for `firstName`, `lastName`, `middleName`, and `custom_attributesV2`. + +```ts +export const updateCustomer = async ( + form: Record +): Promise +``` + + + +### Returns + +Returns a promise that resolves to a string, which could be a success message or an error message. + +### Usage + +To update the customer: + +```ts +import { updateCustomer } from '@/account/api/updateCustomer'; + +updateCustomer(form: CustomerUpdateInput); +``` + +## updateCustomerAddress + +The `updateCustomerAddress` function updates an address associated with the current customer. The function uses the [`updateCustomerAddress`](https://developer.adobe.com/commerce/webapi/graphql/schema/customer/mutations/update-address/) mutation. + +The `forms` object includes an `addressId`, Aa number representing the ID of the address to be updated and other address details as defined in CustomerAddressesModel. + +```ts +export const updateCustomerAddress = async ( + forms: ExtendedAddressFormProps +): Promise +``` + + + +The `CustomerAddressesModel` object has the following shape: + + + +### Returns + +Returns a promise that resolves to a string, which could be a success message or an error message. + +### Usage + +To update the customer address: + +```ts +updateCustomerAddress(forms: { + "addressId": 1, + "city": "Austin", + "countryCode": "US", + "countryId": "US", + "defaultBilling": true, + "defaultShipping": true, + "firstname": "John", + "lastname": "Doe", + "postcode": "78759", + "region": { + "regionId": 57, + "regionCode": "TX" + }, + "street": ["123 Main St"], +}); +``` + +## updateCustomerEmail + +The `updateCustomerEmail` function updates the email address of the logged-in customer. The function calls the [`updateCustomerEmail`](https://developer.adobe.com/commerce/webapi/graphql/schema/customer/mutations/update-email/) mutation. + + +```ts +export const updateCustomerEmail = async ( + email: string, + password: string +): Promise +``` + + + +### Returns + +Returns a promise that resolves to a string, which could be a success message or an error message. + +### Usage + +To update the customer's email address: + +```ts +import { updateCustomerEmail } from '@/account/api/updateCustomerEmail'; + +updateCustomerEmail(forms: { + "email": "test@email.com", + "password": "xyz789abc123", +}); +``` + +## updateCustomerPassword + +The `updateCustomerPassword` function updates the password of the logged-in customer. The function calls the [`changeCustomerPassword`](https://developer.adobe.com/commerce/webapi/graphql/schema/customer/mutations/change-password/) mutation. + + +```ts +export const updateCustomerPassword = async ({ + currentPassword, + newPassword, +}: ChangeCustomerPasswordProps): Promise +``` + + + +### Returns + +Returns a promise that resolves to a string, which could be the customer's email if the password change is successful, or an error message if there are errors. + +### Usage + +To update the customer's password: + +```ts +import { updateCustomerPassword } from '@/account/api/updateCustomerPassword'; + +updateCustomerPassword({ "currentPassword": "xyz789abc123", "newPassword": "123xyz789abc" }); +``` From 4a5149b5967251a740cbe007dc74c2e637ed4be0 Mon Sep 17 00:00:00 2001 From: Kevin Harper Date: Mon, 4 Nov 2024 17:02:33 -0600 Subject: [PATCH 2/4] fix typos --- .../docs/dropins/user-account/functions.mdx | 20 +++++++++---------- 1 file changed, 9 insertions(+), 11 deletions(-) diff --git a/src/content/docs/dropins/user-account/functions.mdx b/src/content/docs/dropins/user-account/functions.mdx index 614a8f91..f12e6d77 100644 --- a/src/content/docs/dropins/user-account/functions.mdx +++ b/src/content/docs/dropins/user-account/functions.mdx @@ -7,7 +7,7 @@ import OptionsTable from '@components/OptionsTable.astro'; ## createCustomerAddress -The `createCustomerAddress` function creates an address for an existing customer using the `CustomerAddressesModel` object as an argument. The functions calls the [`createCustomerAddress`](https://developer.adobe.com/commerce/webapi/graphql/schema/customer/mutations/create-customer-address/) mutation. +The `createCustomerAddress` function creates an address for an existing customer using the `CustomerAddressesModel` object as an argument. The function calls the [`createCustomerAddress`](https://developer.adobe.com/commerce/webapi/graphql/schema/customer/mutations/create-customer-address/) mutation. ```ts export const createCustomerAddress = async ( @@ -19,7 +19,7 @@ export const createCustomerAddress = async ( compact options={[ ['Parameter', 'Type', 'Req?', 'Description'], - ['address', 'CustomerAddressesModel', 'Y', 'An object containing the address information.'], + ['address', 'CustomerAddressesModel', 'Yes', 'An object containing the address information.'], ]} /> @@ -32,9 +32,9 @@ The `CustomerAddressesModel` object has the following fields: ['firstName', 'string', 'No', 'The first name of the customer.'], ['lastName', 'string', 'No', 'The family name of the customer.'], ['city', 'string', 'No', 'The city of the address.'], - ['company', 'string', 'No', 'A company .'], + ['company', 'string', 'No', 'An optional company name specified by the customer.'], ['countryCode', 'string', 'No', 'The two-letter code representing the customer\'s country.'], - ['region', 'object', 'No', 'This object has the shape "{ region: string; regionCode: string; regionId: string | number }".'], + ['region', 'object', 'No', 'This object has the structure "{ region: string; regionCode: string; regionId: string | number }".'], ['telephone', 'string', 'No', 'The telephone number.'], ['id', 'string', 'No', 'The address ID.'], ['vatId', 'string', 'No', 'The VAT ID.'], @@ -49,7 +49,7 @@ The `CustomerAddressesModel` object has the following fields: ### Returns -Returns a promise that resolves to a string. +Returns a promise that resolves to a string, which could be a success message or an error message. ### Usage @@ -98,7 +98,7 @@ export const getAttributesForm = async ( ### Returns -Returns a promise that resolves to an `AttributesFormModel` array. It has the following shape: +Returns a promise that resolves to an `AttributesFormModel` array. It has the following structure: ```javascript { @@ -129,7 +129,7 @@ Returns a promise that resolves to an `AttributesFormModel` array. It has the fo type message } - } +} ``` ### Usage @@ -168,7 +168,7 @@ Returns a promise that resolves to arrays of countries, regions, and postal code countries_with_required_region optional_zip_countries } - } +} ``` ### Usage @@ -254,7 +254,7 @@ export interface CustomerAddressesModel { ### Usage -To get information about customer address +To get information about the customer address: ```javascript import { getCustomerAddress } from '@/account/api/getCustomerAddress'; @@ -473,7 +473,6 @@ updateCustomerAddress(forms: { The `updateCustomerEmail` function updates the email address of the logged-in customer. The function calls the [`updateCustomerEmail`](https://developer.adobe.com/commerce/webapi/graphql/schema/customer/mutations/update-email/) mutation. - ```ts export const updateCustomerEmail = async ( email: string, @@ -511,7 +510,6 @@ updateCustomerEmail(forms: { The `updateCustomerPassword` function updates the password of the logged-in customer. The function calls the [`changeCustomerPassword`](https://developer.adobe.com/commerce/webapi/graphql/schema/customer/mutations/change-password/) mutation. - ```ts export const updateCustomerPassword = async ({ currentPassword, From fdc6c0b98a6bc663a64685d8530d71c173ff32a3 Mon Sep 17 00:00:00 2001 From: Kevin Harper Date: Tue, 5 Nov 2024 11:44:24 -0600 Subject: [PATCH 3/4] add getOrderHistoryList --- .../docs/dropins/user-account/functions.mdx | 37 +++++++++++++++++++ 1 file changed, 37 insertions(+) diff --git a/src/content/docs/dropins/user-account/functions.mdx b/src/content/docs/dropins/user-account/functions.mdx index f12e6d77..406b1243 100644 --- a/src/content/docs/dropins/user-account/functions.mdx +++ b/src/content/docs/dropins/user-account/functions.mdx @@ -262,6 +262,43 @@ import { getCustomerAddress } from '@/account/api/getCustomerAddress'; getCustomerAddress(); ``` +## getOrderHistoryList + +The `getOrderHistoryList` function is an asynchronous function that retrieves a list of customer orders using the [`customer`](https://developer.adobe.com/commerce/webapi/graphql/schema/customer/queries/customer/) query. . It optionally takes parameters for pagination and filtering. + +```ts +export const getOrderHistoryList = async ( + pageSize: number, + selectOrdersDate: string, + currentPage: number +): Promise +``` + + + +### Returns + +Returns a promise that resolves to an `OrderHistory` object or null. + +### Usage + +To get a list of customer orders: + +```ts +import { getOrderHistoryList } from '@/account/api/getOrderHistoryList'; + +getOrderHistoryList(); +``` + + ## getRegions The `getRegions` function uses the [`country`](https://developer.adobe.com/commerce/webapi/graphql/schema/directory/queries/country/) query to retrieve a list of states or provinves for a specific country. From d99fe1c7e30261f50aa980d686c249480680137b Mon Sep 17 00:00:00 2001 From: Kevin Harper Date: Wed, 6 Nov 2024 09:54:52 -0600 Subject: [PATCH 4/4] Apply suggestions from code review Co-authored-by: Jeff Matthews --- src/content/docs/dropins/user-account/functions.mdx | 12 ++++++------ 1 file changed, 6 insertions(+), 6 deletions(-) diff --git a/src/content/docs/dropins/user-account/functions.mdx b/src/content/docs/dropins/user-account/functions.mdx index 406b1243..c6c29b23 100644 --- a/src/content/docs/dropins/user-account/functions.mdx +++ b/src/content/docs/dropins/user-account/functions.mdx @@ -1,5 +1,5 @@ --- -title: User account functions +title: User Account functions description: Learn about the API functions provided by the User Account dropin. --- @@ -191,7 +191,7 @@ export const getCustomer = async (): Promise ### Returns -Returns a promise that resolves to CustomerDataModelShort object: +Returns a promise that resolves to `CustomerDataModelShort` object: ```ts export interface CustomerDataModelShort { @@ -264,7 +264,7 @@ getCustomerAddress(); ## getOrderHistoryList -The `getOrderHistoryList` function is an asynchronous function that retrieves a list of customer orders using the [`customer`](https://developer.adobe.com/commerce/webapi/graphql/schema/customer/queries/customer/) query. . It optionally takes parameters for pagination and filtering. +The `getOrderHistoryList` function is an asynchronous function that retrieves a list of customer orders using the [`customer`](https://developer.adobe.com/commerce/webapi/graphql/schema/customer/queries/customer/) query. It optionally takes parameters for pagination and filtering. ```ts export const getOrderHistoryList = async ( @@ -278,7 +278,7 @@ export const getOrderHistoryList = async ( compact options={[ ['Parameter', 'Type', 'Req?', 'Description'], - ['pageSize', 'number', 'No', 'the maximum number of results to return at once. The default value is 20.'], + ['pageSize', 'number', 'No', 'The maximum number of results to return at once. The default value is 20.'], ['selectOrdersDate', 'string', 'No', 'Represents a date filter for the orders.'], ['currentPage', 'number', 'No', 'The current page of the order history list. The default value is 1.'], ]} @@ -314,7 +314,7 @@ export const getRegions = async ( compact options={[ ['Parameter', 'Type', 'Req?', 'Description'], - ['countryCode', 'string', 'Yes', 'a two-letter abbreviation for the country ID'], + ['countryCode', 'string', 'Yes', 'A two-letter abbreviation for the country ID.'], ]} /> @@ -440,7 +440,7 @@ updateCustomer(form: CustomerUpdateInput); The `updateCustomerAddress` function updates an address associated with the current customer. The function uses the [`updateCustomerAddress`](https://developer.adobe.com/commerce/webapi/graphql/schema/customer/mutations/update-address/) mutation. -The `forms` object includes an `addressId`, Aa number representing the ID of the address to be updated and other address details as defined in CustomerAddressesModel. +The `forms` object includes an `addressId`, which is a number representing the ID of the address to be updated and other address details as defined in `CustomerAddressesModel`. ```ts export const updateCustomerAddress = async (