From 6672edfbd8ef85764c39c974a82751c052456cb6 Mon Sep 17 00:00:00 2001 From: Wojciech Sikora <35867383+WojtekTheWebDev@users.noreply.github.com> Date: Fri, 19 Apr 2024 12:53:36 +0200 Subject: [PATCH] refactor: add TSDocs focused on SDK usage and deprecate magentoModule (#1519) * refactor: prepare migration to middlewareModule * chore: deprecate magentoModule * docs: document usage of middlewareModule with Magento 2 integration (#1520) * docs: document usage of middlewareModule with Magento 2 integration * Update docs/content/2.getting-started/3.supported-features.md Co-authored-by: Matt Maribojoc --------- Co-authored-by: Matt Maribojoc --------- Co-authored-by: Matt Maribojoc --- .changeset/eighty-papayas-occur.md | 38 ++++++ .changeset/gorgeous-news-notice.md | 5 + .../2.getting-started/1.quick-start.md | 121 ++++++++---------- .../2.getting-started/3.supported-features.md | 4 + docs/content/3.basics/1.products.md | 12 +- docs/content/3.basics/2.cart.md | 18 +-- docs/content/3.basics/3.authenthication.md | 2 +- docs/content/3.basics/4.users.md | 10 +- docs/content/3.basics/5.wishlist.md | 6 +- docs/content/3.basics/6.checkout.md | 22 ++-- docs/content/3.basics/7.misc.md | 28 ++-- docs/content/4.advanced/custom-queries.md | 59 +++++---- .../src/api/addBundleProductsToCart/index.ts | 92 +++++++++++++ .../addConfigurableProductsToCart/index.ts | 87 ++++++++++++- .../addDownloadableProductsToCart/index.ts | 4 - .../src/api/addProductToWishList/index.ts | 60 +++++++++ .../src/api/addProductsToCart/index.ts | 90 ++++++++++++- .../src/api/addSimpleProductsToCart/index.ts | 3 + .../src/api/addVirtualProductsToCart/index.ts | 4 - .../src/api/applyCouponToCart/index.ts | 65 +++++++++- .../src/api/availableStores/index.ts | 55 +++++++- packages/api-client/src/api/cart/index.ts | 57 ++++++++- .../api-client/src/api/cartTotalQty/index.ts | 16 +++ .../api-client/src/api/categories/index.ts | 55 +++++++- .../api-client/src/api/categoryList/index.ts | 9 +- .../src/api/categorySearch/index.ts | 81 ++++++++++-- .../src/api/changeCustomerPassword/index.ts | 59 ++++++++- .../api-client/src/api/cmsBlocks/index.ts | 66 +++++++++- packages/api-client/src/api/cmsPage/index.ts | 61 ++++++++- .../api-client/src/api/countries/index.ts | 58 ++++++++- packages/api-client/src/api/country/index.ts | 4 - .../src/api/createCustomer/index.ts | 64 ++++++++- .../src/api/createCustomerAddress/index.ts | 74 ++++++++++- .../src/api/createEmptyCart/index.ts | 15 +++ .../src/api/createProductReview/index.ts | 24 +++- packages/api-client/src/api/currency/index.ts | 81 +++++++++++- .../src/api/customMutation/index.ts | 33 +++++ .../api-client/src/api/customQuery/index.ts | 49 +++++++ packages/api-client/src/api/customer/index.ts | 73 ++++++++++- .../api-client/src/api/customerCart/index.ts | 59 ++++++++- .../src/api/customerProductReview/index.ts | 2 +- .../src/api/deleteCustomerAddress/index.ts | 15 ++- .../src/api/generateCustomerToken/index.ts | 61 ++++++++- .../index.ts | 30 +++++ .../index.ts | 68 +++++++++- .../api/getAvailablePaymentMethods/index.ts | 34 ++++- .../api/getAvailableShippingMethods/index.ts | 62 +++++++++ .../src/api/getCustomerAddresses/index.ts | 61 ++++++++- .../api-client/src/api/mergeCarts/index.ts | 64 +++++++++ .../api-client/src/api/placeOrder/index.ts | 84 +++++++++++- .../src/api/productDetails/index.ts | 85 +++++++++++- .../api-client/src/api/productReview/index.ts | 67 +++++++++- .../api/productReviewRatingsMetadata/index.ts | 63 ++++++++- packages/api-client/src/api/products/index.ts | 86 ++++++++++++- .../src/api/relatedProducts/index.ts | 94 +++++++++++++- .../src/api/removeCouponFromCart/index.ts | 65 +++++++++- .../src/api/removeItemFromCart/index.ts | 70 +++++++++- .../api/removeProductsFromWishlist/index.ts | 63 +++++++++ .../api/requestPasswordResetEmail/index.ts | 16 ++- .../api-client/src/api/resetPassword/index.ts | 18 ++- packages/api-client/src/api/reviews/index.ts | 61 ++++++++- .../src/api/revokeCustomerToken/index.ts | 13 +- packages/api-client/src/api/route/index.ts | 66 +++++++++- .../src/api/setBillingAddressOnCart/index.ts | 73 +++++++++++ .../src/api/setGuestEmailOnCart/index.ts | 16 ++- .../src/api/setPaymentMethodOnCart/index.ts | 67 +++++++++- .../api/setShippingAddressesOnCart/index.ts | 99 +++++++++++++- .../src/api/setShippingMethodsOnCart/index.ts | 85 +++++++++++- .../api-client/src/api/storeConfig/index.ts | 55 +++++++- .../api/subscribeEmailToNewsletter/index.ts | 16 ++- .../src/api/updateCartItems/index.ts | 66 +++++++++- .../src/api/updateCustomer/index.ts | 67 +++++++++- .../src/api/updateCustomerAddress/index.ts | 58 ++++++++- .../src/api/updateCustomerEmail/index.ts | 56 ++++++++ .../src/api/upsellProducts/index.ts | 82 +++++++++++- .../api-client/src/api/urlResolver/index.ts | 6 +- packages/api-client/src/api/wishlist/index.ts | 3 + .../src/api/wishlistItemsCount/index.ts | 15 +++ packages/sdk/src/index.ts | 37 +++++- 79 files changed, 3431 insertions(+), 341 deletions(-) create mode 100644 .changeset/eighty-papayas-occur.md create mode 100644 .changeset/gorgeous-news-notice.md diff --git a/.changeset/eighty-papayas-occur.md b/.changeset/eighty-papayas-occur.md new file mode 100644 index 000000000..70223458c --- /dev/null +++ b/.changeset/eighty-papayas-occur.md @@ -0,0 +1,38 @@ +--- +"@vue-storefront/magento-sdk": patch +--- + +[CHANGED] `magentoModule` has been deprecated. Use `middlewareModule` from `@vue-storefront/sdk` package instead. + +```diff +- import { initSDK, buildModule } from '@vue-storefront/sdk'; +- import { magentoModule } from '@vsf-enterprise/magento-sdk' ++ import { initSDK, buildModule, middlewareModule } from '@vue-storefront/sdk'; ++ import { Endpoints as MagentoEndpoints } from '@vsf-enterprise/sapcc-api'; // In Alokai Storefront you should import it from `storefront-middleware/types.ts` + +const sdkConfig = { + magento: + buildModule( +- magentoModule, ++ middlewareModule, + { apiUrl: 'http://localhost:8181/magento' } + ) +}; +``` + +Updating your `magentoModule` to this version should not disrupt your existing code; however, switching to `middlewareModule` will require certain modifications. + +To migrate: + +- Use custom query as a second argument of `middlewareModule` function. + +```diff +const customQuery = { + cart: 'cart-custom-query', + metadata: { + fields: 'id items { uid }' + } +}; +- const cart = await sdk.magento.cart({ cartId: '123'}, { customQuery }); ++ const cart = await sdk.magento.cart({ cartId: '123'}, customQuery); +``` diff --git a/.changeset/gorgeous-news-notice.md b/.changeset/gorgeous-news-notice.md new file mode 100644 index 000000000..1af4b91f6 --- /dev/null +++ b/.changeset/gorgeous-news-notice.md @@ -0,0 +1,5 @@ +--- +"@vue-storefront/magento-api": patch +--- + +[CHANGED] Update TSDocs of API methods. Now, they contain examples of usage. diff --git a/docs/content/2.getting-started/1.quick-start.md b/docs/content/2.getting-started/1.quick-start.md index 2e54f6599..377fe6a15 100644 --- a/docs/content/2.getting-started/1.quick-start.md +++ b/docs/content/2.getting-started/1.quick-start.md @@ -4,7 +4,6 @@ Your Alokai application has two parts: 1. **Server Middleware** - an Express.js application that can connect to your various third-party services (like Magento). - 2. **Front-end application** - any application using JavaScript or TypeScript that can connect to the server middleware. Popular choices include [Nuxt](https://nuxt.com/) and [Next.js](https://nextjs.org/). In this section, we will explain in a step-by-step guide how to use Magento 2 integration in each part of your Alokai application. @@ -22,7 +21,6 @@ Learn more about the SDK in our [Key concepts: SDK](/sdk) docs. - Magento configured - if you don't have your Magento 2 configured, see our [Magento Installation](./magento.md) guide. - Install Node.js version >=16.0 - ## Server Middleware The first step to setup your integration is to create and configure your server middleware layer to connect to your Magento 2 backend. @@ -33,11 +31,10 @@ For an example of a generic server middleware configuration, check out one of [o If you have the server middleware configured, you can move directly to the [SDK preparation](./quick-start.md#configuring-the-sdk) part. ::: - 1. Install the dependencies needed to create your server middleware and to create a server-to-server connection with the Magento 2 backend and the server middleware. ```bash -yarn add @vue-storefront/middleware @vue-storefront/magento-api +yarn add @vue-storefront/middleware @vue-storefront/magento-api # npm install @vue-storefront/middleware @vue-storefront/magento-api @@ -49,53 +46,53 @@ yarn add @vue-storefront/middleware @vue-storefront/magento-api ```javascript // middleware.config.js -import {config} from "dotenv"; +import { config } from "dotenv"; config(); const cookieNames = { - currencyCookieName: 'vsf-currency', - countryCookieName: 'vsf-country', - localeCookieName: 'vsf-locale', - cartCookieName: 'vsf-cart', - customerCookieName: 'vsf-customer', - storeCookieName: 'vsf-store', - messageCookieName: 'vsf-message' + currencyCookieName: "vsf-currency", + countryCookieName: "vsf-country", + localeCookieName: "vsf-locale", + cartCookieName: "vsf-cart", + customerCookieName: "vsf-customer", + storeCookieName: "vsf-store", + messageCookieName: "vsf-message", }; export const integrations = { magento: { - location: '@vue-storefront/magento-api/server', - configuration: { - api: process.env.VSF_MAGENTO_GRAPHQL_URL, - cookies: { - ...cookieNames, - }, - cookiesDefaultOpts: { - httpOnly: process.env.VSF_COOKIE_HTTP_ONLY || false, - secure: process.env.VSF_COOKIE_SECURE || false, - sameSite: process.env.VSF_COOKIE_SAME_SITE || 'lax', - path: process.env.VSF_COOKIE_PATH || '/', - }, - defaultStore: 'default', - customApolloHttpLinkOptions: { - useGETForQueries: true, - }, - magentoBaseUrl: process.env.VSF_MAGENTO_BASE_URL, - magentoApiEndpoint: process.env.VSF_MAGENTO_GRAPHQL_URL, - imageProvider: process.env.NUXT_IMAGE_PROVIDER, - recaptcha: { - isEnabled: process.env.VSF_RECAPTCHA_ENABLED === 'true', - sitekey: process.env.VSF_RECAPTCHA_SITE_KEY, - secretkey: process.env.VSF_RECAPTCHA_SECRET_KEY, - version: process.env.VSF_RECAPTCHA_VERSION, - score: process.env.VSF_RECAPTCHA_MIN_SCORE, - }, - customer: { - customer_create_account_confirm: true, - }, + location: "@vue-storefront/magento-api/server", + configuration: { + api: process.env.VSF_MAGENTO_GRAPHQL_URL, + cookies: { + ...cookieNames, + }, + cookiesDefaultOpts: { + httpOnly: process.env.VSF_COOKIE_HTTP_ONLY || false, + secure: process.env.VSF_COOKIE_SECURE || false, + sameSite: process.env.VSF_COOKIE_SAME_SITE || "lax", + path: process.env.VSF_COOKIE_PATH || "/", }, - } + defaultStore: "default", + customApolloHttpLinkOptions: { + useGETForQueries: true, + }, + magentoBaseUrl: process.env.VSF_MAGENTO_BASE_URL, + magentoApiEndpoint: process.env.VSF_MAGENTO_GRAPHQL_URL, + imageProvider: process.env.NUXT_IMAGE_PROVIDER, + recaptcha: { + isEnabled: process.env.VSF_RECAPTCHA_ENABLED === "true", + sitekey: process.env.VSF_RECAPTCHA_SITE_KEY, + secretkey: process.env.VSF_RECAPTCHA_SECRET_KEY, + version: process.env.VSF_RECAPTCHA_VERSION, + score: process.env.VSF_RECAPTCHA_MIN_SCORE, + }, + customer: { + customer_create_account_confirm: true, + }, + }, + }, }; ``` @@ -124,9 +121,9 @@ NUXT_IMAGE_PROVIDER=ipx ```javascript // middleware.js -import {createServer} from "@vue-storefront/middleware"; -import {integrations} from "./middleware.config.js"; -import cors from 'cors'; +import { createServer } from "@vue-storefront/middleware"; +import { integrations } from "./middleware.config.js"; +import cors from "cors"; (async () => { const app = await createServer({ integrations }); @@ -150,7 +147,6 @@ import cors from 'cors'; console.log(`Middleware started: ${host}:${port}`); }); })(); - ``` 5. Your middleware is ready. You can start it by running `node middleware.js`. Most likely, you'll want to setup this command as a script in your `package.json` file. @@ -167,40 +163,29 @@ import cors from 'cors'; ## Configuring the SDK -Now, let's configure the SDK in the frontend part of your application to communicate with the server middleware. +Now, let's configure the SDK in the frontend part of your application to communicate with the server middleware. -1. Install the SDK package and the Magento 2 module. These packages will allow you to create an instance of the SDK and then extend it with methods to communicate with Magento 2 via your server middleware. - -```bash -yarn add @vue-storefront/sdk @vue-storefront/magento-sdk - -# npm install @vue-storefront/sdk @vue-storefront/magento-sdk - -# pnpm install @vue-storefront/sdk @vue-storefront/magento-sdk -``` - -2. Initialize the SDK. Configure Magento 2 module with `apiUrl` that points to the server middleware. +1. Initialize the SDK. Configure `middlewareModule` with `apiUrl` that points to the Magento 2 integration in the Alokai Middleware. ```ts -import { buildModule, initSDK } from '@vue-storefront/sdk'; -import { magentoModule, MagentoModuleType } from '@vue-storefront/sdk/magento-sdk'; +import { buildModule, initSDK, middlewareModule } from "@vue-storefront/sdk"; +import { Endpoints } from "@vue-storefront/magento-api"; const sdkConfig = { - magento: buildModule(magentoModule, { - apiUrl: 'http://localhost:8181/magento' - }) + magento: buildModule(middlewareModule, { + apiUrl: "http://localhost:8181/magento", + }), }; -export const sdk = initSDK(sdkConfig); +export const sdk = initSDK(sdkConfig); ``` - +2. Your SDK is ready! You can now import it in the different parts of your frontend application and call methods with `sdk.magento.`. To see a full list of methods offered by the Magento 2 integration, check out the [API Reference](/integrations/magento/api/magento-api). For example, we can call the `products` method to fetch products from Magento 2. ```ts -import { sdk } from './sdk'; -const products = await sdk.magento.products({}) +import { sdk } from "./sdk"; +const products = await sdk.magento.products({}); // returns ProductInterface[] - ``` diff --git a/docs/content/2.getting-started/3.supported-features.md b/docs/content/2.getting-started/3.supported-features.md index be97cb0b8..656d222bf 100644 --- a/docs/content/2.getting-started/3.supported-features.md +++ b/docs/content/2.getting-started/3.supported-features.md @@ -2,6 +2,10 @@ This page lists the Magento 2 features supported by this integration. +:::tip API Reference +You can find descriptions and examples for all of the available SAPCC module methods in the [API Reference](/integrations/magento/api/magento-api). +::: + ## Product types | Feature | Is supported | Additional comments | diff --git a/docs/content/3.basics/1.products.md b/docs/content/3.basics/1.products.md index 0e7c91536..39876884a 100644 --- a/docs/content/3.basics/1.products.md +++ b/docs/content/3.basics/1.products.md @@ -3,17 +3,17 @@ In this section, we will cover the basics of products. We will show you how to fetch products from in a variety of ways. ## Overview -There are two main functions to fetch products from Magento 2: [productDetails](../api/magento-sdk/productDetails) and [products](../api/magento-sdk/products). Both are very similar and accept the same arguments. The main difference is in the reponse they return. The [productDetails](../api/magento-sdk/productDetails) method returns a single product related data, while the [products](../reference/api/magento-sdk/products) method returns a list of products related data. +There are two main functions to fetch products from Magento 2: [productDetails](/integrations/magento/api/magento-api/productDetails) and [products](/integrations/magento/api/magento-api/products). Both are very similar and accept the same arguments. The main difference is in the reponse they return. The [productDetails](/integrations/magento/api/magento-api/productDetails) method returns a single product related data, while the [products](/integrations/magento/api/magento-api/products) method returns a list of products related data. The first one is optimized to be used on single product pages, while the second one is optimized to be used on product list pages like category pages, search results pages, etc. ## References | Method | Description | |--------------------------------------------------------------------|--------------------------------| -| [productDetails](../api/magento-sdk/productDetails) | Method to fetch product details | -| [products](../api/magento-sdk/products) | Method to fetch products | -| [relatedProducts](../api/magento-sdk/relatedProducts) | Method to fetch related products | -| [upsellProducts](../api/magento-sdk/upsellProducts) | Method to fetch upsell products | -| [productReview](../api/magento-sdk/productReview) | Method to fetch reviews | +| [productDetails](/integrations/magento/api/magento-api/productDetails) | Method to fetch product details | +| [products](/integrations/magento/api/magento-api/products) | Method to fetch products | +| [relatedProducts](/integrations/magento/api/magento-api/relatedProducts) | Method to fetch related products | +| [upsellProducts](/integrations/magento/api/magento-api/upsellProducts) | Method to fetch upsell products | +| [productReview](/integrations/magento/api/magento-api/productReview) | Method to fetch reviews | diff --git a/docs/content/3.basics/2.cart.md b/docs/content/3.basics/2.cart.md index de93b7986..7bfc4bcd0 100644 --- a/docs/content/3.basics/2.cart.md +++ b/docs/content/3.basics/2.cart.md @@ -14,15 +14,15 @@ Using listed method you can implement the full cart functionality in your storef ## References | Method | Description | |------------------------------------------------------------------------------|----------------------------------------------------| -| [cart](../api/magento-sdk/cart) | Method to fetch/guestrt data | -| [customerCart](../api/magento-sdk/customerCart) | Method to fetch logged in customer cart data | -| [createEmptyCart](../api/magento-sdk/createEmptyCart) | Method to create a new cart | -| [updateCartItems](../api/magento-sdk/updateCartItems) | Method to update cart items | -| [removeItemFromCart](../api/magento-sdk/removeItemFromCart) | Method to remove item from cart | -| [applyCouponToCart](../api/magento-sdk/applyCouponToCart) | Method to apply coupon to cart | -| [removeCouponFromCart](../api/magento-sdk/removeCouponFromCart) | Method to remove coupon from cart | -| [cartTotalQty](../api/magento-sdk/cartTotalQty) | Method to fetch cart total items quantity | -| [mergeCarts](../api/magento-sdk/mergeCarts) | Method to merge guest and logged in customer carts | +| [cart](/integrations/magento/api/magento-api/cart) | Method to fetch/guestrt data | +| [customerCart](/integrations/magento/api/magento-api/customerCart) | Method to fetch logged in customer cart data | +| [createEmptyCart](/integrations/magento/api/magento-api/createEmptyCart) | Method to create a new cart | +| [updateCartItems](/integrations/magento/api/magento-api/updateCartItems) | Method to update cart items | +| [removeItemFromCart](/integrations/magento/api/magento-api/removeItemFromCart) | Method to remove item from cart | +| [applyCouponToCart](/integrations/magento/api/magento-api/applyCouponToCart) | Method to apply coupon to cart | +| [removeCouponFromCart](/integrations/magento/api/magento-api/removeCouponFromCart) | Method to remove coupon from cart | +| [cartTotalQty](/integrations/magento/api/magento-api/cartTotalQty) | Method to fetch cart total items quantity | +| [mergeCarts](/integrations/magento/api/magento-api/mergeCarts) | Method to merge guest and logged in customer carts | diff --git a/docs/content/3.basics/3.authenthication.md b/docs/content/3.basics/3.authenthication.md index 83bcc3b58..4adf3b01a 100644 --- a/docs/content/3.basics/3.authenthication.md +++ b/docs/content/3.basics/3.authenthication.md @@ -15,4 +15,4 @@ Methods like `customer`, `customerCart`, `updateCustomer`, `changeCustomerPasswo ## References | Method | Description | |-----------------------------------------------------------------------|-----------------------------------| -| [generateCustomerToken](/integrations/magento/api/magento-sdk/generateCustomerToken) | Method to generate customer token | +| [generateCustomerToken](/integrations/magento/api/magento-api/generateCustomerToken) | Method to generate customer token | diff --git a/docs/content/3.basics/4.users.md b/docs/content/3.basics/4.users.md index e3cf1a00b..eef8b2db0 100644 --- a/docs/content/3.basics/4.users.md +++ b/docs/content/3.basics/4.users.md @@ -11,11 +11,11 @@ Methods in this section helps you to implement full user functionality in your s ## References | Method | Description | |----------------------------------------------------------------------------------|------------------------------------| -| [customer](../api/magento-sdk/customer) | Method to fetch customer data | -| [createCustomer](../api/magento-sdk/createCustomer) | Method to create new customer | -| [updateCustomer](../api/magento-sdk/updateCustomer) | Method to update customer | -| [changeCustomerPassword](../api/magento-sdk/changeCustomerPassword) | Method to change customer password | -| [createCustomerAddress](../api/magento-sdk/createCustomerAddress) | Method to create customer address | +| [customer](/integrations/magento/api/magento-api/customer) | Method to fetch customer data | +| [createCustomer](/integrations/magento/api/magento-api/createCustomer) | Method to create new customer | +| [updateCustomer](/integrations/magento/api/magento-api/updateCustomer) | Method to update customer | +| [changeCustomerPassword](/integrations/magento/api/magento-api/changeCustomerPassword) | Method to change customer password | +| [createCustomerAddress](/integrations/magento/api/magento-api/createCustomerAddress) | Method to create customer address | diff --git a/docs/content/3.basics/5.wishlist.md b/docs/content/3.basics/5.wishlist.md index 2fbc3a296..c229b5078 100644 --- a/docs/content/3.basics/5.wishlist.md +++ b/docs/content/3.basics/5.wishlist.md @@ -11,6 +11,6 @@ Because only logged in users can have a wishlist, all methods in this section re ## References | Method | Description | |------------------------------------------------------------------------------------|----------------------------------------------| -| [addProductToWishlist](../api/magento-sdk/addProductToWishList) | Method to add a product to wishlist | -| [removeProductsFromWishlist](../api/magento-sdk/removeProductsFromWishlist) | Method to remove a product to wishlist | -| [wishlistItemsCount](../api/magento-sdk/wishlistItemsCount) | Method to get items quantity in the wishlist | +| [addProductToWishlist](/integrations/magento/api/magento-api/addProductToWishList) | Method to add a product to wishlist | +| [removeProductsFromWishlist](/integrations/magento/api/magento-api/removeProductsFromWishlist) | Method to remove a product to wishlist | +| [wishlistItemsCount](/integrations/magento/api/magento-api/wishlistItemsCount) | Method to get items quantity in the wishlist | diff --git a/docs/content/3.basics/6.checkout.md b/docs/content/3.basics/6.checkout.md index ed6501a9c..65975475b 100644 --- a/docs/content/3.basics/6.checkout.md +++ b/docs/content/3.basics/6.checkout.md @@ -10,14 +10,14 @@ We provide a set of methods that allow you to implement the full checkout functi | Method | Description | |--------------------------------------------------------------------------------------------------------------|----------------------------------------------------| -| [getAvailableShippingMethods](../api/magento-sdk/getAvailableShippingMethods) | Method to fetch guest available shipping methods | -| [getAvailablePaymentMethods](../api/magento-sdk/getAvailablePaymentMethods) | Method to fetch guest available payment methods | -| [getAvailableCustomerShippingMethods](../api/magento-sdk/getAvailableCustomerShippingMethods) | Method to fetch customer available sipping methods | -| [getAvailableCustomerPaymentMethods](../api/magento-sdk/getAvailableCustomerPaymentMethods) | Method to fetch customer available payment methods | -| [getCustomerAddresses](../api/magento-sdk/getCustomerAddresses) | Method to fetch customer addresses | -| [setShippingAddressesOnCart](../api/magento-sdk/setShippingAddressesOnCart) | Method to set shipping addresses on cart | -| [setBillingAddressOnCart](../api/magento-sdk/setBillingAddressOnCart) | Method to set billing addresse on cart | -| [setShippingMethodsOnCart](../api/magento-sdk/setShippingMethodsOnCart) | Method to set shipping methods on cart | -| [setPaymentMethodOnCart](../api/magento-sdk/setPaymentMethodOnCart) | Method to set payment method on cart | -| [setGuestEmailOnCart](../api/magento-sdk/setGuestEmailOnCart) | Method to set email on the guest cart | -| [placeOrder](../api/magento-sdk/placeOrder) | Method to place an order | +| [getAvailableShippingMethods](/integrations/magento/api/magento-api/getAvailableShippingMethods) | Method to fetch guest available shipping methods | +| [getAvailablePaymentMethods](/integrations/magento/api/magento-api/getAvailablePaymentMethods) | Method to fetch guest available payment methods | +| [getAvailableCustomerShippingMethods](/integrations/magento/api/magento-api/getAvailableCustomerShippingMethods) | Method to fetch customer available sipping methods | +| [getAvailableCustomerPaymentMethods](/integrations/magento/api/magento-api/getAvailableCustomerPaymentMethods) | Method to fetch customer available payment methods | +| [getCustomerAddresses](/integrations/magento/api/magento-api/getCustomerAddresses) | Method to fetch customer addresses | +| [setShippingAddressesOnCart](/integrations/magento/api/magento-api/setShippingAddressesOnCart) | Method to set shipping addresses on cart | +| [setBillingAddressOnCart](/integrations/magento/api/magento-api/setBillingAddressOnCart) | Method to set billing addresse on cart | +| [setShippingMethodsOnCart](/integrations/magento/api/magento-api/setShippingMethodsOnCart) | Method to set shipping methods on cart | +| [setPaymentMethodOnCart](/integrations/magento/api/magento-api/setPaymentMethodOnCart) | Method to set payment method on cart | +| [setGuestEmailOnCart](/integrations/magento/api/magento-api/setGuestEmailOnCart) | Method to set email on the guest cart | +| [placeOrder](/integrations/magento/api/magento-api/placeOrder) | Method to place an order | diff --git a/docs/content/3.basics/7.misc.md b/docs/content/3.basics/7.misc.md index 00bf5cb1b..d8a71ee60 100644 --- a/docs/content/3.basics/7.misc.md +++ b/docs/content/3.basics/7.misc.md @@ -8,50 +8,50 @@ Methdos in this section are used to fetch various configuration data. | Method | Description | |--------------------------------------------------------------------|----------------------------------| -| [availableStores](../api/magento-sdk/availableStores) | Method to fetch available stores | -| [countries](../api/magento-sdk/countries) | Method to fetch available countries | -| [currency](../api/magento-sdk/currency) | Method to fetch available currency | -| [storeConfig](../api/magento-sdk/storeConfig) | Method to fetch available storeConfig | +| [availableStores](/integrations/magento/api/magento-api/availableStores) | Method to fetch available stores | +| [countries](/integrations/magento/api/magento-api/countries) | Method to fetch available countries | +| [currency](/integrations/magento/api/magento-api/currency) | Method to fetch available currency | +| [storeConfig](/integrations/magento/api/magento-api/storeConfig) | Method to fetch available storeConfig | ### CMS Methods in this section are used to fetch CMS data. | Method | Description | |--------------------------------------------------------------------|----------------------------------| -| [cmsBlocks](../api/magento-sdk/cmsBlocks) | Method to fetch cms blocks | -| [cmsPage](../api/magento-sdk/cmsPage) | Method to fetch cms page | +| [cmsBlocks](/integrations/magento/api/magento-api/cmsBlocks) | Method to fetch cms blocks | +| [cmsPage](/integrations/magento/api/magento-api/cmsPage) | Method to fetch cms page | ### Routing Methods in this section are used to fetch routing data. | Method | Description | |----------------------------------------------|-----------------------------------| -| [route](../api/magento-sdk/route) | Method to fetch route object data | +| [route](/integrations/magento/api/magento-api/route) | Method to fetch route object data | ### Customer reviews Methods in this section are used to fetch customer reviews data. | Method | Description | |----------------------------------------------------------------------------------------------|---------------------------------------------| -| [createProductReview](../api/magento-sdk/createProductReview) | Method to create product review | -| [productReview](../api/magento-sdk/productReview) | Method to fetch product review | -| [reviews](../api/magento-sdk/reviews) | Method to fetch reviews created by customer | -| [productReviewRatingsMetadata](../api/magento-sdk/productReviewRatingsMetadata) | Method to fetch product reviews metadata | +| [createProductReview](/integrations/magento/api/magento-api/createProductReview) | Method to create product review | +| [productReview](/integrations/magento/api/magento-api/productReview) | Method to fetch product review | +| [reviews](/integrations/magento/api/magento-api/reviews) | Method to fetch reviews created by customer | +| [productReviewRatingsMetadata](/integrations/magento/api/magento-api/productReviewRatingsMetadata) | Method to fetch product reviews metadata | ### Newsletter Methods in this section are used to fetch newsletter data. | Method | Description | |-------------------------------------------------------------------------------------|------------------------------------------| -| [subscribeEmailToNewsletter](../api/magento-sdk/subscribeEmailToNewsletter) | Method to subscribe to newsletter | +| [subscribeEmailToNewsletter](/integrations/magento/api/magento-api/subscribeEmailToNewsletter) | Method to subscribe to newsletter | ### Custom Queries Methods in this section are used to create custom queries and mutations. | Method | Description | |------------------------------------------------------------|------------------------------------| -| [customQuery](../api/magento-sdk/customQuery) | Method to create a custom query | -| [customMutation](../api/magento-sdk/customMutation) | Method to create a custom mutation | +| [customQuery](/integrations/magento/api/magento-api/customQuery) | Method to create a custom query | +| [customMutation](/integrations/magento/api/magento-api/customMutation) | Method to create a custom mutation | diff --git a/docs/content/4.advanced/custom-queries.md b/docs/content/4.advanced/custom-queries.md index 3173fea66..fc1d88263 100644 --- a/docs/content/4.advanced/custom-queries.md +++ b/docs/content/4.advanced/custom-queries.md @@ -4,11 +4,11 @@ Sometimes, you may need to fetch data from the API that is not covered by the default methods. In this case, you can use the the custom queries feature to extend defaults by your own GraphQL queries. - Creating a custom query requires a few steps: -* adding a custom query to the `middleware.config.js` file, -* (optional) overwriting the default response interface. -* using the custom query in the method. + +- adding a custom query to the `middleware.config.js` file, +- (optional) overwriting the default response interface. +- using the custom query in the method. ## Custom queries in middleware.config.js @@ -19,24 +19,27 @@ In the example below, we are adding a custom query called `customer-custom-query ```ts // middleware.config.js -module.exports = { - integrations: { - magento: { +// ... + +export const integrations = { + magento: { + location: "@vue-storefront/magento-api/server", + configuration: { // ... - customQueries: { - 'customer-custom-query': ({ query, variables, metadata }) => ({ - variables, - query: ` + }, + customQueries: { + "customer-custom-query": ({ query, variables, metadata }) => ({ + variables, + query: ` query customer { customer { ${metadata.fields} } } - ` - }), - } - } - } + `, + }), + }, + }, }; ``` @@ -51,30 +54,26 @@ Notice how we are using the type parameter to overwrite the default response int ::: ```ts -import { sdk } from '~/sdk.config.ts'; +import { sdk } from "~/sdk.config.ts"; type CustomerCustomQueryResponse = { customer: { email: string; firstname: string; lastname: string; - } -} + }; +}; const customQuery = { - customer: 'customer-custom-query', + customer: "customer-custom-query", metadata: { - fields: 'email firstname lastname' - } + fields: "email firstname lastname", + }, }; // We assume that token was already fetched and stored in the `token` variable. -const result = await sdk.magento.customer({ - customQuery, - customHeaders: { Authorization: `Bearer ${token}` } -}); +const result = await sdk.magento.customer( + customQuery, + customHeaders: { Authorization: `Bearer ${token}` }, +); ``` - - diff --git a/packages/api-client/src/api/addBundleProductsToCart/index.ts b/packages/api-client/src/api/addBundleProductsToCart/index.ts index 0b0dd235f..a3f766d98 100644 --- a/packages/api-client/src/api/addBundleProductsToCart/index.ts +++ b/packages/api-client/src/api/addBundleProductsToCart/index.ts @@ -11,6 +11,98 @@ import addBundleProductsToCartQuery from "./addBundleProductsToCart"; import { Context } from "../../types/context"; import getHeaders from "../getHeaders"; +/** + * Add bundle products to cart. + * + * @example + * Adding bundle products to cart with default parameters. + * ```ts + * import { sdk } from '~/sdk.config.ts'; + * + * const cart = await sdk.magento.addBundleProductsToCart( + * { + * cart_id: '123', + * cart_items: [ + * { + * data: { + * quantity: 1, + * sku: TEST_BUNDLE_SKU, + * }, + * bundle_options: [ + * { + * id: 1, + * quantity: 1, + * value: ['1'], + * }, + * { + * id: 2, + * quantity: 1, + * value: ['4'], + * }, + * { + * id: 3, + * quantity: 1, + * value: ['5'], + * }, + * { + * id: 4, + * quantity: 1, + * value: ['8'], + * }, + * ] + * } + * ); + * ``` + * + * @example + * Creating a custom GraphQL query for adding bundle products to cart + * + * ```ts + * module.exports = { + * integrations: { + * magento: { + * customQueries: { + * 'add-bundle-products-to-cart-custom-query': ({ variables, metadata }) => ({ + * variables, + * query: ` + * mutation addBundleProductsToCart($input: AddBundleProductsToCartInput) { + * addBundleProductsToCart(input: $input) { + * cart { + * ${metadata.fields} + * } + * } + * }`, + * }), + * }, + * } + * } + * }; + * ``` + * + * @example + * Using a custom GraphQL query to modify response containing the cart, which is sent as part of the adding product to cart mutation + * + * ```ts + * import { sdk } from '~/sdk.config.ts'; + * // reduce the amount of fields returned by the query, when compared to the default query + * const customQuery = { + * cart: 'add-bundle-products-to-cart-custom-query', + * metadata: { + * fields: 'id items { uid }' + * } + * }; + * + * + * const cart = await sdk.magento.addBundleProductsToCart( + * { + * // use the payload from the previous example + * }, + * customQuery + * ); + * + * // Result will contain only the fields specified in the custom query. + * ``` + */ export async function addBundleProductsToCart( context: Context, input: AddBundleProductsToCartInput, diff --git a/packages/api-client/src/api/addConfigurableProductsToCart/index.ts b/packages/api-client/src/api/addConfigurableProductsToCart/index.ts index d6e883251..8aa4be17c 100644 --- a/packages/api-client/src/api/addConfigurableProductsToCart/index.ts +++ b/packages/api-client/src/api/addConfigurableProductsToCart/index.ts @@ -12,11 +12,88 @@ import addConfigurableProductsToCartMutation from "./addConfigurableProductsToCa import getHeaders from "../getHeaders"; /** - * Adds a set of configurable products to a specified cart - * @param context VSF Context - * @param input ID of the cart and products to be added - * @param [customQuery] (optional) - custom GraphQL query that extends the default one - * @param customHeaders (optional) - custom headers that extends the default headers + * Add configurable products to cart. + * + * @example + * Adding configurable products to cart with default parameters. + * ```ts + * import { sdk } from '~/sdk.config.ts'; + * + * const cart = await sdk.magento.addConfigurableProductsToCart( + * { + * cart_id: '123', + * cart_items: [ + * { + * data: { + * quantity: 1, + * sku: 'MH01-XS-Black', + * }, + * parent_sku: 'MH01', + * customizable_options: [], + * } + * ] + * } + * ); + * ``` + * + * @example + * Creating a custom GraphQL query for adding configurable products to cart + * + * ```ts + * module.exports = { + * integrations: { + * magento: { + * customQueries: { + * 'add-configurable-products-to-cart-custom-query': ({ variables, metadata }) => ({ + * variables, + * query: ` + * mutation addConfigurableProductsToCart($input: AddConfigurableProductsToCartInput) { + * addConfigurableProductsToCart(input: $input) { + * cart { + * ${metadata.fields} + * } + * } + * }`, + * }), + * }, + * } + * } + * }; + * ``` + * + * @example + * Using a custom GraphQL query to modify response containing the cart, which is sent as part of the adding product to cart mutation + * + * ```ts + * import { sdk } from '~/sdk.config.ts'; + * // reduce the amount of fields returned by the query, when compared to the default query + * const customQuery = { + * cart: 'add-configurable-products-to-cart-custom-query', + * metadata: { + * fields: 'id items { uid }' + * } + * }; + * + * + * const cart = await sdk.magento.addConfigurableProductsToCart( + * { + * cart_id: '123', + * cart_items: [ + * { + * data: { + * quantity: 1, + * sku: 'MH01-XS-Black', + * }, + * parent_sku: 'MH01', + * customizable_options: [], + * } + * ] + * }, + * customQuery + * ); + * + * // Result will contain only the fields specified in the custom query. + * ``` */ export async function addConfigurableProductsToCart( context: Context, diff --git a/packages/api-client/src/api/addDownloadableProductsToCart/index.ts b/packages/api-client/src/api/addDownloadableProductsToCart/index.ts index 13ece73a5..1887d1fed 100644 --- a/packages/api-client/src/api/addDownloadableProductsToCart/index.ts +++ b/packages/api-client/src/api/addDownloadableProductsToCart/index.ts @@ -12,10 +12,6 @@ import getHeaders from "../getHeaders"; /** * Adds a set of downloadable products to a specified cart - * @param context VSF Context - * @param input ID of the cart and products to be added - * @param customQuery custom GraphQL query that extends the default one - * @param customHeaders (optional) - custom headers that extends the default headers */ export async function addDownloadableProductsToCart( context: Context, diff --git a/packages/api-client/src/api/addProductToWishList/index.ts b/packages/api-client/src/api/addProductToWishList/index.ts index f210c8e72..462091a13 100644 --- a/packages/api-client/src/api/addProductToWishList/index.ts +++ b/packages/api-client/src/api/addProductToWishList/index.ts @@ -5,6 +5,66 @@ import addProductsToWishListQuery from "./addProductsToWishlist"; import { Context } from "../../types/context"; import getHeaders from "../getHeaders"; +/** + * Add products to wishlist + * + * @example + * ```ts + * import { sdk } from '~/sdk.config.ts'; + * + * const wishlist = await sdk.magento.addProductToWishList({ + * // Wishlist ID + * id: '258', + * // Products to add to wishlist with given ID + * items: [{quantity: 1, sku: 'WSH12'}] + * }); + * ``` + * + * @example + * Creating a custom GraphQL query for searching categories + * + * ```ts + * module.exports = { + * integrations: { + * magento: { + * customQueries: { + * 'add-product-to-wishlist-custom-query': ({ variables, metadata }) => ({ + * variables, + * query: ` + * mutation addProductsToWishlist($id: ID!, $items: [WishlistItemInput!]!) { + * addProductsToWishlist(wishlistId: $id, wishlistItems: $items) { + * wishlist { + * ${metadata.fields} + * } + * } + * }` + * }), + * }, + * } + * } + * } + * ``` + * + * @example + * Using a custom GraphQL query (mutation) to add products to wishlist + * + * ```ts + * import { sdk } from '~/sdk.config.ts'; + * const customQuery = { + * addProductsToWishList: 'add-product-to-wishlist-custom-query', + * metadata: { + * fields: 'id items_count' + * } + * }; + * + * const result = await sdk.magento.addProductToWishList({ + * id: '258', + * items: [{ quantity: 1, sku: '258'}] + * }, customQuery); + * + * // Returned wishlist will contain only the fields specified in the custom query. + * ``` + */ export async function addProductToWishList( context: Context, input: AddProductsToWishlistMutationVariables, diff --git a/packages/api-client/src/api/addProductsToCart/index.ts b/packages/api-client/src/api/addProductsToCart/index.ts index 211a0eb7e..02047a988 100644 --- a/packages/api-client/src/api/addProductsToCart/index.ts +++ b/packages/api-client/src/api/addProductsToCart/index.ts @@ -6,11 +6,91 @@ import addProductsToCartMutation from "./addProductsToCart"; import getHeaders from "../getHeaders"; /** - * Adds products to the specified cart - * @param context VSF Context - * @param input ID of the cart and products to be added - * @param [customQuery] (optional) - custom GraphQL query that extends the default one - * @param customHeaders (optional) - custom headers that extends the default headers + * Add products to cart. + * + * @example + * Simple usage: + * ```ts + * import { sdk } from '~/sdk.config.ts'; + * + * // add products to cart with default parameters (returns cart) + * const cart = await sdk.magento.addProductsToCart( + * { + * cartId: '123', + * cartItems: [ + * { + * sku: 'WSH12', + * quantity: 1, + * selected_options: [ + * // option IDs retrieved from product + * 'Y29uZmlndXJhYmxlLzkzLzUz', + * 'Y29uZmlndXJhYmxlLzE0NC8xNzE=' + * ] + * } + * ] + * } + * ); + * ``` + * + * @example + * Creating a custom GraphQL query for adding products to cart + * + * ```ts + * module.exports = { + * integrations: { + * magento: { + * customQueries: { + * 'add-products-to-cart-custom-query': ({ variables, metadata }) => ({ + * variables, + * query: ` + * mutation addProductsToCart($cartId: String!, $cartItems: [CartItemInput!]!) { + * addProductsToCart(cartId: $cartId, cartItems: $cartItems) { + * cart { + * ${metadata.fields} + * } + * } + * }` + * + * }), + * }, + * } + * } + * }; + * ``` + * + * @example + * Using a custom GraphQL query to modify response containing the cart, which is sent as part of the adding product to cart mutation + * + * ```ts + * import { sdk } from '~/sdk.config.ts'; + * // reduce the amount of fields returned by the query, when compared to the default query + * const customQuery = { + * cart: 'add-products-to-cart-custom-query', + * metadata: { + * fields: 'id items { uid }' + * } + * }; + * + * + * const cart = await sdk.magento.addProductsToCart( + * { + * cartId: '123', + * cartItems: [ + * { + * sku: 'WSH12', + * quantity: 1, + * selected_options: [ + * 'Y29uZmlndXJhYmxlLzkzLzUz', + * 'Y29uZmlndXJhYmxlLzE0NC8xNzE=' + * ] + * } + * ] + * }, + * customQuery + * ); + * + * // Result will contain only the fields specified in the custom query. + * ``` */ export async function addProductsToCart( context: Context, diff --git a/packages/api-client/src/api/addSimpleProductsToCart/index.ts b/packages/api-client/src/api/addSimpleProductsToCart/index.ts index 736842e1f..d3697a2c6 100644 --- a/packages/api-client/src/api/addSimpleProductsToCart/index.ts +++ b/packages/api-client/src/api/addSimpleProductsToCart/index.ts @@ -10,6 +10,9 @@ import addSimpleProductsToCartQuery from "./addSimpleProductsToCart"; import { Context } from "../../types/context"; import getHeaders from "../getHeaders"; +/** + * Add simple products to cart. + */ export async function addSimpleProductsToCart( context: Context, input: AddSimpleProductsToCartInput, diff --git a/packages/api-client/src/api/addVirtualProductsToCart/index.ts b/packages/api-client/src/api/addVirtualProductsToCart/index.ts index 5b9d13ab0..20b39bf4f 100644 --- a/packages/api-client/src/api/addVirtualProductsToCart/index.ts +++ b/packages/api-client/src/api/addVirtualProductsToCart/index.ts @@ -12,10 +12,6 @@ import getHeaders from "../getHeaders"; /** * Adds a set of virtual products to a specified cart - * @param context VSF Context - * @param input ID of the cart and products to add - * @param customQuery custom GraphQL query that extends the default one - * @param customHeaders (optional) - custom headers that extends the default headers */ export async function addVirtualProductsToCart( context: Context, diff --git a/packages/api-client/src/api/applyCouponToCart/index.ts b/packages/api-client/src/api/applyCouponToCart/index.ts index 59086255e..971312e31 100644 --- a/packages/api-client/src/api/applyCouponToCart/index.ts +++ b/packages/api-client/src/api/applyCouponToCart/index.ts @@ -7,11 +7,66 @@ import applyCouponToCartMutation from "./applyCouponToCart"; import getHeaders from "../getHeaders"; /** - * Applies a coupon to a given card - * @param context VSF context - * @param input ID of the card and coupon to apply - * @param customQuery custom GraphQL query that extends the default one - * @param customHeaders (optional) - custom headers that extends the default headers + * Apply coupon to cart + * + * @example + * Simple usage: + * ```ts + * import { sdk } from '~/sdk.config.ts'; + * + * // apply coupon parameters + * const params = { + * cart_id: 'test-cart-id', + * coupon_code: 'test-coupon-code' + * }; + * + * // The result of the coupon application + * const result = await sdk.magento.applyCouponToCart(params); + * ``` + * + * @example + * Creating a custom GraphQL query for getting cart + * + * ```ts + * module.exports = { + * integrations: { + * magento: { + * customQueries: { + * 'apply-coupon-to-cart-custom-query': ({ variables, metadata }) => ({ + * variables, + * query: ` + * mutation applyCouponToCart($input: ApplyCouponToCartInput) { + * applyCouponToCart(input: $input) { + * ${metadata.fields} + * } + * }` + * }), + * }, + * } + * } + * }; + * ``` + * + * @example + * Using a custom GraphQL query to fetch reduced amount of data + * + * ```ts + * import { sdk } from '~/sdk.config.ts'; + * const customQuery = { + * applyCouponToCart: 'apply-coupon-to-cart-custom-query', + * metadata: { + * fields: 'cart { applied_coupons { code } }' + * } + * }; + * + * const params = { + * cart_id: 'test-cart-id', + * coupon_code: 'test-coupon-code' + * }; + * + * // The result will contain only fields configured in the custom query + * const result = await sdk.magento.applyCouponToCart(params, customQuery); + * ``` */ export async function applyCouponToCart( context: Context, diff --git a/packages/api-client/src/api/availableStores/index.ts b/packages/api-client/src/api/availableStores/index.ts index 16d0fe4fd..30a38b846 100644 --- a/packages/api-client/src/api/availableStores/index.ts +++ b/packages/api-client/src/api/availableStores/index.ts @@ -7,7 +7,60 @@ import { Context } from "../../types/context"; import getHeaders from "../getHeaders"; /** - * Returns list of available stores + * Fetch available stores + * + * @example + * Simple usage: + * ```ts + * import { sdk } from '~/sdk.config.ts'; + * + * // fetch available stores + * const result = await sdk.magento.availableStores(); + * + * // result.data.availableStores contains the available stores + * ``` + * + * @example + * Creating a custom GraphQL query + * + * ```ts + * module.exports = { + * integrations: { + * magento: { + * customQueries: { + * 'available-stores-custom-query': ({ variables, metadata }) => ({ + * variables, + * query: ` + * query availableStores { + * availableStores { + * ${metadata?.fields} + * } + * } + * ` + * }), + * }, + * } + * } + * }; + * ``` + * + * @example + * Using a custom GraphQL query to reduce the amount of fields returned by the query + * + * ```ts + * import { sdk } from '~/sdk.config.ts'; + * // reduce the amount of fields returned by the query, when compared to the default query + * const customQuery = { + * availableStores: 'available-stores-custom-query', + * metadata: { + * fields: 'code store_name' + * } + * }; + * + * const result = await sdk.magento.availableStores(customQuery); + * + * // result.data.availableStores contains the available stores with only the fields specified in the custom query + * ``` */ export async function availableStores( context: Context, diff --git a/packages/api-client/src/api/cart/index.ts b/packages/api-client/src/api/cart/index.ts index 4dc5c907c..edb18b2ba 100644 --- a/packages/api-client/src/api/cart/index.ts +++ b/packages/api-client/src/api/cart/index.ts @@ -6,11 +6,58 @@ import cartQuery from "./cart"; import getHeaders from "../getHeaders"; /** - * Fetches a cart by its ID - * @param context VSF context - * @param cartId ID of the cart to fetch - * @param customQuery custom GraphQL query that extends the default one - * @param customHeaders (optional) - custom headers that extends the default headers + * Get cart + * + * @example + * Simple usage: + * ```ts + * import { sdk } from '~/sdk.config.ts'; + * + * // fetch cart with default parameters + * const cart = await sdk.magento.cart({ cartId: '123' }); + * ``` + * + * @example + * Creating a custom GraphQL query for getting cart + * + * ```ts + * module.exports = { + * integrations: { + * magento: { + * customQueries: { + * 'cart-custom-query': ({ variables, metadata }) => ({ + * variables, + * query: ` + * query cart($cartId: String!) { + * cart(cart_id:$cartId) { + * ${metadata.fields} + * } + * }` + * ` + * }), + * }, + * } + * } + * }; + * ``` + * + * @example + * Using a custom GraphQL query to fetch cart + * + * ```ts + * import { sdk } from '~/sdk.config.ts'; + * // reduce the amount of fields returned by the query, when compared to the default query + * const customQuery = { + * cart: 'cart-custom-query', + * metadata: { + * fields: 'id items { uid }' + * } + * }; + * + * const cart = await sdk.magento.cart({ cartId: '123'}, customQuery); + * + * // Cart will contain only the fields specified in the custom query. + * ``` */ export async function cart( context: Context, diff --git a/packages/api-client/src/api/cartTotalQty/index.ts b/packages/api-client/src/api/cartTotalQty/index.ts index 404b48bce..6fbb87b7c 100644 --- a/packages/api-client/src/api/cartTotalQty/index.ts +++ b/packages/api-client/src/api/cartTotalQty/index.ts @@ -6,6 +6,22 @@ import cartTotalQtyQuery from "./cartTotalQty"; import { Context } from "../../types/context"; import getHeaders from "../getHeaders"; +/** + * Resolve cart total quantity + * This method is optimized to fetch only total quantity of the cart and not the whole cart object. + * Do not use `cart` query inf you want to fetch only total quantity of the cart. + * + * @example + * Simple usage: + * ```ts + * import { sdk } from '~/sdk.config.ts'; + * + * // fetch total quantity of the cart + * const { data } await sdk.magento.cartTotalQty({cartId: 'some_cart_id' }); + * + * // total quantity of the cart available in data.cart.total_quantity + * ``` + */ export async function cartTotalQty(context: Context, cartId: string, customHeaders: CustomHeaders = {}): Promise> { return context.client.query({ query: gql` diff --git a/packages/api-client/src/api/categories/index.ts b/packages/api-client/src/api/categories/index.ts index 852d21ac0..6bc74b1b3 100644 --- a/packages/api-client/src/api/categories/index.ts +++ b/packages/api-client/src/api/categories/index.ts @@ -7,12 +7,57 @@ import { Context } from "../../types/context"; import getHeaders from "../getHeaders"; /** - * Fetches categories. + * Fetch list of all categories matching specified filters * - * @param context Context - * @param params - * @param [customQuery] (optional) - custom GraphQL query that extends the default query - * @param customHeaders (optional) - custom headers that extends the default headers + * @example + * Simple usage: + * ```ts + * import { sdk } from '~/sdk.config.ts'; + * + * // fetch list of categories with default parameters + * const categories = await sdk.magento.categories({}); + * ``` + * + * @example + * Creating a custom GraphQL query for fetching categories. + * + * ```ts + * module.exports = { + * integrations: { + * magento: { + * customQueries: { + * 'categories-custom-query': ({ variables, metadata }) => ({ + * variables, + * query: ` + * query categories { + * categories { + * ${metadata.fields} + * } + * } + * ` + * }), + * }, + * } + * } + * }; + * ``` + * + * @example + * Using a custom GraphQL query to fetch categories. + * + * ```ts + * import { sdk } from '~/sdk.config.ts'; + * const customQuery = { + * categories: 'categories-custom-query', + * metadata: { + * fields: 'items { uid name }' + * } + * }; + * + * const categories = await sdk.magento.categories({}, customQuery); + * + * // Category list will contain only the fields specified in the custom query. + * ``` */ export async function categories( context: Context, diff --git a/packages/api-client/src/api/categoryList/index.ts b/packages/api-client/src/api/categoryList/index.ts index 1642be361..52f362f70 100644 --- a/packages/api-client/src/api/categoryList/index.ts +++ b/packages/api-client/src/api/categoryList/index.ts @@ -7,13 +7,10 @@ import { Context } from "../../types/context"; import getHeaders from "../getHeaders"; /** - * Fetches the category list. - * @deprecated Use `categories` method instead + * Fetch list of all categories without filters * - * @param context VSF Context - * @param params - * @param [customQuery] (optional) - custom GraphQL query that extends the default query - * @param customHeaders (optional) - custom headers that extends the default headers + * @deprecated + * Use `categories` method instead. */ export async function categoryList( context: Context, diff --git a/packages/api-client/src/api/categorySearch/index.ts b/packages/api-client/src/api/categorySearch/index.ts index 82f5e31c9..1d859cdc8 100644 --- a/packages/api-client/src/api/categorySearch/index.ts +++ b/packages/api-client/src/api/categorySearch/index.ts @@ -6,14 +6,79 @@ import { Context } from "../../types/context"; import getHeaders from "../getHeaders"; /** - * Searches for categories using received filters. - * - * @param context VSF Context - * @param filters filters used to search for categories. A filter contains at - * least one attribute, a comparison operator, and the value that is being - * searched for. - * @param [customQuery] (optional) - custom GraphQL query that extends the default query - * @param customHeaders (optional) - custom headers that extends the default headers + * Search categories + * + * @example + * Simple usage without filters + * ```ts + * import { sdk } from '~/sdk.config.ts'; + * + * // fetch list of categories with default parameters + * const categories = await sdk.magento.categorySearch(); + * ``` + * + * @example + * Usage with filters + * + * ```ts + * import { sdk } from '~/sdk.config.ts'; + * + * // make a request to fetch list of categories with custom parameters + * const details = await sdk.magento.categorySearch({ + * filters: { + * category_uid: { + * in: ['MjA='] + * } + * } + * }); + * ``` + * + * @example + * Creating a custom GraphQL query for searching categories + * + * ```ts + * module.exports = { + * integrations: { + * magento: { + * customQueries: { + * 'category-search-custom-query': ({ variables, metadata }) => ({ + * variables, + * query: ` + query categorySearch($filters: CategoryFilterInput) { + categoryList(filters: $filters) { + ${metadata.fields} + } + } + * ` + * }), + * }, + * } + * } + * }; + * ``` + * + * @example + * Using a custom GraphQL query to search categories. + * + * ```ts + * import { sdk } from '~/sdk.config.ts'; + * const customQuery = { + * categorySearch: 'category-search-custom-query', + * metadata: { + * fields: 'children_count products { total_count }' + * } + * }; + * + * const result = await sdk.magento.categorySearch({ + * filter: { + * category_uid: { + * in: ['=MjA'] + * } + * } + * }, customQuery); + * + * // Details will contain only the fields specified in the custom query. + * ``` */ export async function categorySearch( context: Context, diff --git a/packages/api-client/src/api/changeCustomerPassword/index.ts b/packages/api-client/src/api/changeCustomerPassword/index.ts index 03279c5d5..3be712ea7 100644 --- a/packages/api-client/src/api/changeCustomerPassword/index.ts +++ b/packages/api-client/src/api/changeCustomerPassword/index.ts @@ -7,7 +7,64 @@ import { Context } from "../../types/context"; import getHeaders from "../getHeaders"; /** - * Changes password of the current customer. To override the default query, use the `changeCustomerPassword` query key. + * Change customer password. + * + * @example + * Simple usage, change customer password: + * ```ts + * import { sdk } from '~/sdk.config.ts'; + * + * const result = await sdk.magento.changeCustomerPassword({ + * currentPassword: 'currentPassword', + * newPassword: 'newPassword' + * }); + * ``` + * + * @example + * Creating a custom GraphQL query for changeCustomerPassword: + * + * ```ts + * module.exports = { + * integrations: { + * magento: { + * customQueries: { + * 'change-customer-password-custom-query': ({ variables, metadata }) => ({ + * variables, + * query: ` + * mutation changeCustomerPassword($currentPassword: String!, $newPassword: String!) { + * changeCustomerPassword( + * currentPassword: $currentPassword + * newPassword: $newPassword + * ) { + * ${metadata.fields} + * } + * } + * ` + * }), + * }, + * } + * } + * }; + * ``` + * + * @example + * Using a custom GraphQL query to narrow down the response data: + * + * ```ts + * import { sdk } from '~/sdk.config.ts'; + * // reduce the amount of fields returned by the query, when compared to the default query + * const customQuery = { + * changeCustomerPassword: 'change-customer-password-custom-query', + * metadata: { + * fields: 'email' + * } + * }; + * + * const result = await sdk.magento.changeCustomerPassword({ + * currentPassword: 'currentPassword', + * newPassword: 'newPassword' + * }, customQuery); + * ``` */ export async function changeCustomerPassword( context: Context, diff --git a/packages/api-client/src/api/cmsBlocks/index.ts b/packages/api-client/src/api/cmsBlocks/index.ts index 49982e7d3..70e5490df 100644 --- a/packages/api-client/src/api/cmsBlocks/index.ts +++ b/packages/api-client/src/api/cmsBlocks/index.ts @@ -7,12 +7,68 @@ import { Context } from "../../types/context"; import getHeaders from "../getHeaders"; /** - * Fetch CMS Blocks from Magento Api. + * Fetch cms blocks. * - * @param context - VSF Context - * @param identifiers - identifiers of CMS blocks - * @param [customQuery] - (optional) - custom GraphQL query that extends the default cmsBlocks query - * @param customHeaders (optional) - custom headers that extends the default headers + * @example + * Simple usage: + * ```ts + * import { sdk } from '~/sdk.config.ts'; + * + * // fetch few cms blocks by their identifiers + * const { data } = await sdk.magento.cmsBlocks({ + * identifiers: ['id1', 'id2'] + * }); + * + * // result will contain cms blocks with the specified identifiers + * data.cmsBlocks.items.forEach(block => console.log(block.identifier)); + * ``` + * + * @example + * Creating a custom GraphQL query + * + * ```ts + * module.exports = { + * integrations: { + * magento: { + * customQueries: { + * 'cms-blocks-custom-query': ({ variables, metadata }) => ({ + * variables, + * query: ` + * query cmsBlock($identifiers: [String]) { + * cmsBlocks(identifiers: $identifiers) { + * items { + * ${metadata.fields} + * } + * } + * } + * ` + * }), + * }, + * } + * } + * }; + * ``` + * + * @example + * Using a custom GraphQL query to reduce the amount of fields returned by the query + * + * ```ts + * import { sdk } from '~/sdk.config.ts'; + * // reduce the amount of fields returned by the query, when compared to the default query + * // fetch only title + * const customQuery = { + * cmsBlocks: 'cms-blocks-custom-query', + * metadata: { + * fields: 'title' + * } + * }; + * + * const { data } = await sdk.magento.cmsBlocks({ + * identifiers: ['id1', 'id2'] + * }, customQuery); + * + * // data will contain only block titles + * ``` */ export async function cmsBlocks( context: Context, diff --git a/packages/api-client/src/api/cmsPage/index.ts b/packages/api-client/src/api/cmsPage/index.ts index 178ff738f..53ec66924 100644 --- a/packages/api-client/src/api/cmsPage/index.ts +++ b/packages/api-client/src/api/cmsPage/index.ts @@ -8,11 +8,62 @@ import { Context } from "../../types/context"; import getHeaders from "../getHeaders"; /** - * Fetch CMS Page from Magento - * @param context - VSF Context - * @param identifier - identifier of CMS page - * @param customQuery - (optional) - custom query that extends default cmsPage GraphQL query - * @param customHeaders (optional) - custom headers that extends the default headers + * Fetch CMS page + * + * @example + * Simple usage: + * ```ts + * import { sdk } from '~/sdk.config.ts'; + * + * // fetch home page by the page identifier + * const result = await sdk.magento.cmsPage({ + * identifier: 'home' + * }); + * ``` + * + * @example + * Creating a custom GraphQL query + * + * ```ts + * module.exports = { + * integrations: { + * magento: { + * customQueries: { + * 'cms-page-custom-query': ({ variables, metadata }) => ({ + * variables, + * query: ` + * query cmsPage($identifier: String) { + * cmsPage(identifier:$identifier) { + * ${metadata?.fields} + * } + * } + * ` + * }), + * }, + * } + * } + * }; + * ``` + * + * @example + * Using a custom GraphQL query to reduce the amount of fields returned by the query + * + * ```ts + * import { sdk } from '~/sdk.config.ts'; + * // reduce the amount of fields to only the content and title + * const customQuery = { + * cmsPage: 'cms-page-custom-query', + * metadata: { + * fields: 'title content' + * } + * }; + * + * const result = await sdk.magento.cmsPage({ + * identifier: 'home' + * }, customQuery); + * + * // result will only contain the title and content fields + * ``` */ export async function cmsPage( context: Context, diff --git a/packages/api-client/src/api/countries/index.ts b/packages/api-client/src/api/countries/index.ts index a0705b69c..94779c653 100644 --- a/packages/api-client/src/api/countries/index.ts +++ b/packages/api-client/src/api/countries/index.ts @@ -7,10 +7,60 @@ import { Context } from "../../types/context"; import getHeaders from "../getHeaders"; /** - * Loads the list of countries - * @param context VSF Context - * @param [customQuery] (optional) - custom GraphQL query that extends the default one - * @param customHeaders (optional) - custom headers that extends the default headers + * Fetch list of countries + * + * @example + * Simple usage: + * ```ts + * import { sdk } from '~/sdk.config.ts'; + * + * // fetch list of countries + * const result = await sdk.magento.countries(); + * + * // result.data.countries is an array of countries + * ``` + * + * @example + * Creating a custom GraphQL query + * + * ```ts + * module.exports = { + * integrations: { + * magento: { + * customQueries: { + * 'countries-custom-query': ({ variables, metadata }) => ({ + * variables, + * query: ` + * query countriesList { + * countries { + * ${metadata?.fields} + * } + * } + * ` + * }), + * }, + * } + * } + * }; + * ``` + * + * @example + * Using a custom GraphQL query to reduce the amount of fields returned by the query + * + * ```ts + * import { sdk } from '~/sdk.config.ts'; + * // reduce the amount of fields returned by the query, when compared to the default query + * const customQuery = { + * countries: 'countries-custom-query', + * metadata: { + * fields: 'full_name_english' + * } + * }; + * + * const result = await sdk.magento.countries(customQuery); + * + * // result.data.countries will only contain the full_name_english field + * ``` */ export async function countries( context: Context, diff --git a/packages/api-client/src/api/country/index.ts b/packages/api-client/src/api/country/index.ts index a779f8127..b50ac3aca 100644 --- a/packages/api-client/src/api/country/index.ts +++ b/packages/api-client/src/api/country/index.ts @@ -7,10 +7,6 @@ import getHeaders from "../getHeaders"; /** * Fetches the information about a country given its ID - * @param context VSF Context - * @param id ID of the country to be fetched - * @param [customQuery] (optional) - custom GraphQL query that extends the default one - * @param customHeaders (optional) - custom headers that extends the default headers */ export async function country( context: Context, diff --git a/packages/api-client/src/api/createCustomer/index.ts b/packages/api-client/src/api/createCustomer/index.ts index cc1a7e47e..522dd52d1 100644 --- a/packages/api-client/src/api/createCustomer/index.ts +++ b/packages/api-client/src/api/createCustomer/index.ts @@ -9,7 +9,69 @@ import { Context } from "../../types/context"; import getHeaders from "../getHeaders"; /** - * Registers a new customer. To override the default query, use the `createCustomer` query key. + * Create a new customer. + * + * @example + * Simple usage with basic customer data: + * ```ts + * import { sdk } from '~/sdk.config.ts'; + * + * const params = { + * email: 'john.doe@gmail.com' + * firstname: 'John', + * lastname: 'Doe', + * } + * + * const result = await sdk.magento.createCustomer(params); + * ``` + @example + * Creating a custom GraphQL query for creating a customer + * + * ```ts + * module.exports = { + * integrations: { + * magento: { + * customQueries: { + * 'create-customer-custom-query': ({ variables, metadata }) => ({ + * variables, + * query: ` + * query customer { + * customer { + * ${metadata.fields} + * } + * } + * ` + * }), + * }, + * } + * } + * }; + * ``` + * + * @example + * Using a custom GraphQL query to fetch customer + * + * ```ts + * import { sdk } from '~/sdk.config.ts'; + * // reduce the amount of fields returned by the query, when compared to the default query + * + * const customQuery = { + * customer: 'create customer-custom-query', + * metadata: { + * fields: 'email firstname lastname' + * } + * }; + * + * const params = { + * email: 'john.doe@gmail.com' + * firstname: 'John', + * lastname: 'Doe', + * } + * + * const result = await sdk.magento.createCustomer(params, customQuery) + * + * // result will contain only the fields specified in the custom query. + * ``` */ export async function createCustomer( context: Context, diff --git a/packages/api-client/src/api/createCustomerAddress/index.ts b/packages/api-client/src/api/createCustomerAddress/index.ts index 158313601..367fb9863 100644 --- a/packages/api-client/src/api/createCustomerAddress/index.ts +++ b/packages/api-client/src/api/createCustomerAddress/index.ts @@ -12,12 +12,76 @@ import { Context } from "../../types/context"; import getHeaders from "../getHeaders"; /** - * Creates a customer address. + * Create a customer address. * - * @param context VSF Context - * @param input new customer address data - * @param [customQuery] (optional) - custom GraphQL query that extends the default query - * @param customHeaders (optional) - custom headers that extends the default headers + * @example + * Simple usage: + * ```ts + * import { sdk } from '~/sdk.config.ts'; + * + * const address: CustomerAddressInput = { + * city: 'some city', + * country_code: CountryCodeEnum.Us, + * default_billing: false, + * default_shipping: false, + * firstname: 'John', + * lastname: 'Doe', + * postcode: '08701', + * street: ['street'], + * telephone: '123123123', + * region: { + * region_code: 'NJ', + * region_id: 41, + * region: 'New Jersey' + * } + * }; + * + * // customer address will be created for the currently logged in customer + * await sdk.magento.createCustomerAddress(address); + * ``` + * + * @example + * Creating a custom GraphQL query + * + * ```ts + * module.exports = { + * integrations: { + * magento: { + * customQueries: { + * 'create-customer-address-custom-query': ({ variables, metadata }) => ({ + * variables, + * query: ` + * mutation createCustomerAddress($input: CustomerAddressInput!) { + * createCustomerAddress(input: $input) { + * ${metadata.fields} + * } + * } + * ` + * }), + * }, + * } + * } + * }; + * ``` + * + * @example + * Using a custom GraphQL query to reduce the amount of data returned by the API + * + * ```ts + * import { sdk } from '~/sdk.config.ts'; + * // reduce the amount of fields returned by the query, when compared to the default query + * const customQuery = { + * createCustomerAddress: 'create-customer-address-custom-query', + * metadata: { + * fields: 'id city' + * } + * }; + * + * // address parameter is the same as in the simple usage example + * const result = await sdk.magento.createCustomerAddress(address, customQuery); + * + * result.data.createCustomerAddress.city; // 'some city' + * ``` */ export async function createCustomerAddress( context: Context, diff --git a/packages/api-client/src/api/createEmptyCart/index.ts b/packages/api-client/src/api/createEmptyCart/index.ts index cbb1bd224..c0a100dbc 100644 --- a/packages/api-client/src/api/createEmptyCart/index.ts +++ b/packages/api-client/src/api/createEmptyCart/index.ts @@ -6,6 +6,21 @@ import createEmptyCartQuery from "./createEmptyCart"; import { Context } from "../../types/context"; import getHeaders from "../getHeaders"; +/** + * Create an empty cart. + * + * @example + * Simple usage: + * ```ts + * import { sdk } from '~/sdk.config.ts'; + * + * // create an empty cart + * const cart = await sdk.magento.createEmptyCart(); + * + * // cart id can be accessed from the response + * const cartId = cart.data.createEmptyCart; + * ``` + */ export async function createEmptyCart(context: Context, customHeaders: CustomHeaders = {}): Promise> { return context.client.mutate({ mutation: gql` diff --git a/packages/api-client/src/api/createProductReview/index.ts b/packages/api-client/src/api/createProductReview/index.ts index b288654cf..75263a748 100644 --- a/packages/api-client/src/api/createProductReview/index.ts +++ b/packages/api-client/src/api/createProductReview/index.ts @@ -9,7 +9,29 @@ import recaptchaValidator from "../../helpers/recaptcha/recaptchaValidator"; import getHeaders from "../getHeaders"; /** - * Creates a new product review + * Create product review + * + * @example + * Simple usage: + * ```ts + * import { sdk } from '~/sdk.config.ts'; + * + * // create review data structure + * const review = { + * sku: 'some-sku', + * nickname: 'john.doe', + * summary: 'awesome thing, whatever it is!', + * text: 'this is a test review', + * ratings: [{ + * id: 'NA==', // base64 encoded id + * value_id: 'MjA=' // base64 encoded value_id + * }] + * }; + * + * const result = await sdk.magento.createProductReview(review); + * + * // result will contain the created review and summary data + * ``` */ export async function createProductReview( context: Context, diff --git a/packages/api-client/src/api/currency/index.ts b/packages/api-client/src/api/currency/index.ts index e794c9dad..ec37360f5 100644 --- a/packages/api-client/src/api/currency/index.ts +++ b/packages/api-client/src/api/currency/index.ts @@ -7,11 +7,84 @@ import { Context } from "../../types/context"; import getHeaders from "../getHeaders"; /** - * Fetches the currency information. + * Fetch available currencies in a store. * - * @param context VSF context - * @param [customQuery] (optional) - custom GraphQL query that extends the default query - * @param customHeaders (optional) - custom headers that extends the default headers + * @example + * Simple usage: + * ```ts + * import { sdk } from '~/sdk.config.ts'; + * + * // fetch available currencies + * const result = await sdk.magento.currency(); + * + * // result would be something like: + * // { + * // "data": { + * // "currency": { + * // "_currency_code": "EUR", + * // "_currency_symbol": "€", + * // "default_display_currency_code": "EUR", + * // "default_display_currency_symbol": "€", + * // "available_currency_codes": [ + * // "EUR", + * // "USD" + * // ], + * // "exchange_rates": [ + * // { + * // "currency_to": "EUR", + * // "rate": 1 + * // }, + * // { + * // "currency_to": "USD", + * // "rate": 1.2 + * // } + * // ] + * // } + * // } + * // } + * ``` + * + * @example + * Creating a custom GraphQL query + * + * ```ts + * module.exports = { + * integrations: { + * magento: { + * customQueries: { + * 'currency-custom-query': ({ variables, metadata }) => ({ + * variables, + * query: ` + * query currency { + * currency{ + * ${metadata?.fields} + * } + * } + * ` + * }), + * }, + * } + * } + * }; + * ``` + * + * @example + * Using a custom GraphQL query to fetch a list of currencies with limited number of fields + * + * ```ts + * import { sdk } from '~/sdk.config.ts'; + * // reduce the amount of fields returned by the query, when compared to the default query + * const customQuery = { + * currency: 'currency-custom-query', + * metadata: { + * fields: '_currency_code' + * } + * }; + * + * const result = await sdk.magento.currency(customQuery); + * + * // result will contain only the _currency_code field + * ``` */ export async function currency( context: Context, diff --git a/packages/api-client/src/api/customMutation/index.ts b/packages/api-client/src/api/customMutation/index.ts index 8b27d84a6..4fb0e0d54 100644 --- a/packages/api-client/src/api/customMutation/index.ts +++ b/packages/api-client/src/api/customMutation/index.ts @@ -4,6 +4,39 @@ import type { CustomHeaders } from "@vue-storefront/magento-types"; import { Context } from "../../types/context"; import getHeaders from "../getHeaders"; +/** + * Send an arbitrary GraphQL mutation to the Magento GraphQL endpoint + * For sending query, please see {@link https://docs.vuestorefront.io/integrations/magento/api/magento-api/customQuery | customQuery}. + * + * @example + * Simple usage: + * ```ts + * import { sdk } from '~/sdk.config.ts'; + * + * // Prepare custom mutation + * // Do not use gql-tag (gql``) here. + * // For syntax highlighting (provided by respective IDE extensions), add the `#graphql` comment at the start of the template string + * const mutation = `#graphql + * mutation generateCustomerToken($email: String!, $password: String!) { + * generateCustomerToken(email: $email, password: $password) { + * token + * } + * } + *`; + * + * // Prepare mutation variables + * const mutationVariables = { + * email: TEST_USER_EMAIL, + * password: TEST_USER_PASSWORD + * }; + * + * // use custom mutation and variables to fetch response adjusted to your needs + * const result = await sdk.magento.customMutation({ + * mutation, + * mutationVariables + * }); + * ``` + */ export async function customMutation( context: Context, { diff --git a/packages/api-client/src/api/customQuery/index.ts b/packages/api-client/src/api/customQuery/index.ts index c11758ae9..9e1198d80 100644 --- a/packages/api-client/src/api/customQuery/index.ts +++ b/packages/api-client/src/api/customQuery/index.ts @@ -4,6 +4,55 @@ import type { CustomHeaders } from "@vue-storefront/magento-types"; import { Context } from "../../types/context"; import getHeaders from "../getHeaders"; +/** + * Send an arbitrary GraphQL query to the Magento GraphQL endpoint + * For sending mutation, please see {@link https://docs.vuestorefront.io/integrations/magento/api/magento-api/customMutation | customMutation}. + * + * @example + * Simple usage: + * ```ts + * import { sdk } from '~/sdk.config.ts'; + * + * // Do not use gql-tag (gql``) here. + * // For syntax highlighting (provided by respective IDE extensions), add the `#graphql` comment at the start of the template string + * + * const query = `#graphql + * query($search: String!) { + * products(search: $search) { + * items { + * name + * } + * } + * } + * `; + * + * const queryVariables: GetProductSearchParams = { search: "t-shirt" }; + * + * // fetch query response + * const customQueryResult = await sdk.magento.customQuery({ + * query: query, + * queryVariables + * }); + * ``` + * + * @example + * If you want the method to send a GET instead of a POST request, + * use the `options.clientConfig` parameter. + * + * ```ts + * const customQueryResult = await sdk.magento.customQuery( + * { + * query, + * queryVariables + * }, + * { + * clientConfig: { + * method: 'GET' + * } + * } + * ); + * ``` + */ export async function customQuery( context: Context, { diff --git a/packages/api-client/src/api/customer/index.ts b/packages/api-client/src/api/customer/index.ts index 7322837a0..81b6cdee5 100644 --- a/packages/api-client/src/api/customer/index.ts +++ b/packages/api-client/src/api/customer/index.ts @@ -6,7 +6,78 @@ import { Context } from "../../types/context"; import getHeaders from "../getHeaders"; /** - * Returns the information about the current customer. To override the default query, use the `customer` query key. + * Get current customer information + * + * @example + * The `customer()` returns the currently active user. + * This means that the request needs to contain an authorization token, which will tell Magento whose customer data should be fetched. + * + * If your browser has a VSF customer cookie saved, you can just call `customer()` without any parameters - the token will be attached automatically on every request to the middleware. + * + * Simple usage: + * ```ts + * import { sdk } from '~/sdk.config.ts'; + * + * // fetch customer + * const customer = await sdk.magento.customer(); + * ``` + * + * @example + * If you're calling `customer()` in a non-browser context (for example in integration tests) where it's not possible to save a cookie, + * you can attach the token manually using `customHeaders` + * + * Usage with manual authorization: + * ```ts + * import { sdk } from '~/sdk.config.ts'; + * + * const token = '123' + * const customHeaders = { Authorization: `Bearer {token}` } + * + * // fetch customer + * const customer = await sdk.magento.customer({ customHeaders }); + * ``` + * + * @example + * Creating a custom GraphQL query for fetching customer + * + * ```ts + * module.exports = { + * integrations: { + * magento: { + * customQueries: { + * 'customer-custom-query': ({ variables, metadata }) => ({ + * variables, + * query: ` + * query customer { + * customer { + * ${metadata.fields} + * } + * } + * ` + * }), + * }, + * } + * } + * }; + * ``` + * + * @example + * Using a custom GraphQL query to fetch customer + * + * ```ts + * import { sdk } from '~/sdk.config.ts'; + * // reduce the amount of fields returned by the query, when compared to the default query + * const customQuery = { + * customer: 'customer-custom-query', + * metadata: { + * fields: 'email firstname lastname' + * } + * }; + * + * const customer = await sdk.magento.customer(customQuery); + * + * // customer will contain only the fields specified in the custom query. + * ``` */ export async function customer( context: Context, diff --git a/packages/api-client/src/api/customerCart/index.ts b/packages/api-client/src/api/customerCart/index.ts index 57efed71b..2cd37f8ec 100644 --- a/packages/api-client/src/api/customerCart/index.ts +++ b/packages/api-client/src/api/customerCart/index.ts @@ -6,10 +6,61 @@ import customerCartQuery from "./customerCart"; import getHeaders from "../getHeaders"; /** - * Fetches the cart of the current logged in user - * @param context VSF context - * @param customQuery custom GraphQL query that extends the default one - * @param customHeaders (optional) - custom headers that extends the default headers + * Fetch customer cart. + * + * @example + * Simple usage: + * ```ts + * import { sdk } from '~/sdk.config.ts'; + * + * // fetch customer cart + * const { data } = await sdk.magento.customerCart(); + * + * // data contains cart details + * const email = data?.customerCart?.email; + * + * ``` + * + * @example + * Creating a custom GraphQL query for customerCart + * + * ```ts + * module.exports = { + * integrations: { + * magento: { + * customQueries: { + * 'customer-cart-custom-query': ({ variables, metadata }) => ({ + * variables, + * query: ` + * query customerCart { + * customerCart { + * ${metadata.fields} + * } + * }` + * }), + * }, + * } + * } + * }; + * ``` + * + * @example + * Using a custom GraphQL query to reduce the amount of fields returned by the query, when compared to the default query + * + * ```ts + * import { sdk } from '~/sdk.config.ts'; + * // reduce the amount of fields returned by the query, when compared to the default query + * const customQuery = { + * customerCart: 'customer-cart-custom-query', + * metadata: { + * fields: 'id email items { id sku } + * } + * }; + * + * const result = await sdk.magento.customerCart(customQuery); + * + * // result contains cart details with only the fields specified in the custom query + * ``` */ export async function customerCart( context: Context, diff --git a/packages/api-client/src/api/customerProductReview/index.ts b/packages/api-client/src/api/customerProductReview/index.ts index c96be6e81..c85bccf01 100644 --- a/packages/api-client/src/api/customerProductReview/index.ts +++ b/packages/api-client/src/api/customerProductReview/index.ts @@ -14,7 +14,7 @@ import getHeaders from "../getHeaders"; /** * Returns product reviews created by the current customer * - * @deprecated Use {@link @vue-storefront/magento-api#reviews} instead. + * @deprecated Use {@link https://docs.alokai.com/integrations/magento/api/magento-api/reviews | reviews} instead. * */ export async function customerProductReview( diff --git a/packages/api-client/src/api/deleteCustomerAddress/index.ts b/packages/api-client/src/api/deleteCustomerAddress/index.ts index 89fe2ef3d..48eb92e3b 100644 --- a/packages/api-client/src/api/deleteCustomerAddress/index.ts +++ b/packages/api-client/src/api/deleteCustomerAddress/index.ts @@ -6,11 +6,18 @@ import { Context } from "../../types/context"; import getHeaders from "../getHeaders"; /** - * Deletes a customer address. + * Delete a customer address. * - * @param context VSF Context - * @param addressId ID of the customer address to delete - * @param customHeaders (optional) - custom headers that extends the default headers + * @example + * Simple usage: + * ```ts + * import { sdk } from '~/sdk.config.ts'; + * + * const addressId = 12; + * // customer address will be remove for the currently logged in customer + * const response = await sdk.magento.deleteCustomerAddress({ id: addressId }); + * // response.data?.deleteCustomerAddress - result is stored here, it's boolean + * ``` */ export async function deleteCustomerAddress( context: Context, diff --git a/packages/api-client/src/api/generateCustomerToken/index.ts b/packages/api-client/src/api/generateCustomerToken/index.ts index 368495eff..6070c584b 100644 --- a/packages/api-client/src/api/generateCustomerToken/index.ts +++ b/packages/api-client/src/api/generateCustomerToken/index.ts @@ -9,7 +9,66 @@ import { Context } from "../../types/context"; import getHeaders from "../getHeaders"; /** - * Logs in the customer based on provided username and password. To override the default query, use the `generateCustomerToken` query key. + * Generate customer token + * + * @example + * Simple usage: + * ```ts + * import { sdk } from '~/sdk.config.ts'; + * + * // fetch token + * const result = await sdk.magento.generateCustomerToken({ + * email: 'some-email', + * password: 'some-password' + * }); + * + * // Token is now available in result.data.generateCustomerToken.token + * ``` + * + * * @example + * Creating a custom GraphQL query to fetch additional data: + * + * ```ts + * module.exports = { + * integrations: { + * magento: { + * customQueries: { + * 'generate-customer-token-custom-query': ({ variables, metadata }) => ({ + * variables, + * query: ` + * mutation generateCustomerToken($email: String!, $password: String!) { + * generateCustomerToken(email: $email, password: $password) { + * ${metadata.fields} + * } + * } + * }` + * }), + * }, + * } + * } + * }; + * ``` + * + * @example + * Using a custom GraphQL query created in the previous example. + * + * ```ts + * import { sdk } from '~/sdk.config.ts'; + * + * // reduce the amount of fields returned by the query, when compared to the default query + * const customQuery = { + * route: 'generate-customer-token-custom-query', + * metadata: { + * fields: 'token additional_field' + * } + * }; + * + * // data will contain only the fields specified in the custom query. + * const result = await sdk.magento.generateCustomerToken({ + * email: 'some-email', + * password: 'some-password' + * }, customQuery); + * ``` */ export async function generateCustomerToken( context: Context, diff --git a/packages/api-client/src/api/getAvailableCustomerPaymentMethods/index.ts b/packages/api-client/src/api/getAvailableCustomerPaymentMethods/index.ts index 50231c910..590d42210 100644 --- a/packages/api-client/src/api/getAvailableCustomerPaymentMethods/index.ts +++ b/packages/api-client/src/api/getAvailableCustomerPaymentMethods/index.ts @@ -6,6 +6,36 @@ import { Context } from "../../types/context"; import getHeaders from "../getHeaders"; import CustomerAvailablePaymentMethods from "./CustomerPaymentMethods"; +/** + * Fetch available payment methods for a logged in customer. + * + * @example + * Simple usage: + * ```ts + * import { sdk } from '~/sdk.config.ts'; + * + * // fetch available payment methods for a logged in customer + * const result = await sdk.magento.getAvailableCustomerPaymentMethods(); + * + * // example result + * { + * "data": { + * "cart": { + * "__typename": "Cart", + * "available_payment_methods": [ + * { + * "__typename": "AvailablePaymentMethod", + * "code": "checkmo", + * "title": "Check / Money order" + * } + * ] + * } + * }, + * "loading": false, + * "networkStatus": 7 + * } + * ``` + */ export async function getAvailableCustomerPaymentMethods( context: Context, customHeaders: CustomHeaders = {} diff --git a/packages/api-client/src/api/getAvailableCustomerShippingMethods/index.ts b/packages/api-client/src/api/getAvailableCustomerShippingMethods/index.ts index ad322cc82..3ce5dfaa9 100644 --- a/packages/api-client/src/api/getAvailableCustomerShippingMethods/index.ts +++ b/packages/api-client/src/api/getAvailableCustomerShippingMethods/index.ts @@ -7,10 +7,70 @@ import CustomerAvailableShippingMethods from "./CustomerShippingMethods"; import getHeaders from "../getHeaders"; /** - * Retrive available shipping methods for current customer - * @param context VSF Context - * @param [customQuery] (optional) - custom GraphQL query that extends the default one - * @param customHeaders (optional) - custom headers that extends the default headers + * Fetch available shipping methods for current customer. + * Customer must be logged in. + * + * @example + * Simple usage: + * ```ts + * import { sdk } from '~/sdk.config.ts'; + * + * // fetch available shipping methods for current customer + * const result = await sdk.magento.getAvailableCustomerShippingMethods(); + * // e.g. output: + * // { + * // "data": { + * // "customerCart": { + * // "shipping_addresses": [ + * // address1: { + * // "available_shipping_methods": [...] + * // }, + * // ] + * // } + * ``` + * + * @example + * Creating a custom GraphQL query + * + * ```ts + * module.exports = { + * integrations: { + * magento: { + * customQueries: { + * 'get-available-customer-shipping-methods-custom-query': ({ variables, metadata }) => ({ + * variables, + * query: ` + * query CustomerAvailableShippingMethods { + * customerCart { + * ${metadata?.fields} + * } + * } + * ` + * }), + * }, + * } + * } + * }; + * ``` + * + * @example + * Using a custom GraphQL query to reduce the amount of data returned by the API + * + * ```ts + * import { sdk } from '~/sdk.config.ts'; + * // reduce the amount of fields returned by the query, when compared to the default query + * + * const customQuery = { + * getAvailableCustomerShippingMethods: 'get-available-customer-shipping-methods-custom-query', + * metadata: { + * fields: 'shipping_addresses { available_shipping_methods { available method_title } }' + * } + * }; + * + * const result = await sdk.magento.getAvailableCustomerShippingMethods(customQuery); + * + * // the result will contain only the data defined in the custom query + * ``` */ export async function getAvailableCustomerShippingMethods( context: Context, diff --git a/packages/api-client/src/api/getAvailablePaymentMethods/index.ts b/packages/api-client/src/api/getAvailablePaymentMethods/index.ts index 608788cfe..b710b7487 100644 --- a/packages/api-client/src/api/getAvailablePaymentMethods/index.ts +++ b/packages/api-client/src/api/getAvailablePaymentMethods/index.ts @@ -6,11 +6,37 @@ import GuestAvailablePaymentMethods from "./GuestAvailablePaymentMethods"; import getHeaders from "../getHeaders"; /** - * Fetches the available payment methods for the received cart. + * Get available payment methods for the received guest cart. + * To get available customer payment methods use {@link https://docs.vuestorefront.io/integrations/magento/api/magento-api/getAvailableCustomerPaymentMethods | getAvailableCustomerPaymentMethods }. * - * @param context VSF context - * @param cartId cart ID - * @param customHeaders (optional) - custom headers that extends the default headers + * @example + * Simple usage: + * ```ts + * import { sdk } from '~/sdk.config.ts'; + * + * // fetch guest available payment methods + * const result = await sdk.magento.getAvailablePaymentMethods({ + * cartId: 'masked-cart-id' + * }); + * + * // example result + * { + * "data": { + * "cart": { + * "__typename": "Cart", + * "available_payment_methods": [ + * { + * "__typename": "AvailablePaymentMethod", + * "code": "checkmo", + * "title": "Check / Money order" + * } + * ] + * } + * }, + * "loading": false, + * "networkStatus": 7 + * } + * ``` */ export async function getAvailablePaymentMethods( context: Context, diff --git a/packages/api-client/src/api/getAvailableShippingMethods/index.ts b/packages/api-client/src/api/getAvailableShippingMethods/index.ts index 51705f4b1..d5de38c01 100644 --- a/packages/api-client/src/api/getAvailableShippingMethods/index.ts +++ b/packages/api-client/src/api/getAvailableShippingMethods/index.ts @@ -5,6 +5,68 @@ import { Context } from "../../types/context"; import GuestAvailableShippingMethods from "./GuestAvailableShippingMethods"; import getHeaders from "../getHeaders"; +/** + * Fetch guest's available shipping methods + * + * @example + * Simple usage: + * ```ts + * import { sdk } from '~/sdk.config.ts'; + * + * // fetch guest's available shipping methods + * const result = await sdk.magento.getAvailableShippingMethods({ + * cart_id: TEST_CART_ID + * }); + * // array of available shipping methods for selected shipping address: + * result.data.cart.shipping_addresses[0].available_shipping_methods[0]; + * ``` + * + * @example + * Creating a custom GraphQL query for fetching only what's requested from shipping methods + * + * ```ts + * module.exports = { + * integrations: { + * magento: { + * customQueries: { + * 'get-available-shipping-methods-custom-query': ({ variables, metadata }) => ({ + * variables, + * query: ` + * query GuestAvailableShippingMethods($cart_id: String!) { + * cart(cart_id:$cart_id) { + * shipping_addresses { + * available_shipping_methods { + * ${metadata.fields} + * } + * } + * } + * } + * ` + * }), + * }, + * } + * } + * }; + * ``` + * + * @example + * Using a custom GraphQL query to fetch only method_title field + * + * ```ts + * import { sdk } from '~/sdk.config.ts'; + * // reduce the amount of fields returned by the query, when compared to the default query + * const customQuery = { + * shippingMethods: 'get-available-shipping-methods-custom-query', + * metadata: { + * fields: 'method_title' + * } + * }; + * + * const result = await sdk.magento.getAvailableShippingMethods({ cart_id: '123'}, customQuery); + * + * // result contains the customer addresses with only the city method_title. Of course, it has same shape as in the "simple usage" example. + * ``` + */ export async function getAvailableShippingMethods( context: Context, params: GuestAvailableShippingMethodsQueryVariables, diff --git a/packages/api-client/src/api/getCustomerAddresses/index.ts b/packages/api-client/src/api/getCustomerAddresses/index.ts index 300866e4d..85c6b4207 100644 --- a/packages/api-client/src/api/getCustomerAddresses/index.ts +++ b/packages/api-client/src/api/getCustomerAddresses/index.ts @@ -7,11 +7,64 @@ import { Context } from "../../types/context"; import getHeaders from "../getHeaders"; /** - * Fetches customer addresses. + * Get customer addresses. + * Customer must be logged in before calling this method. * - * @param context - VSF Context - * @param [customQuery] - (optional) - custom GraphQL query that extends the default query - * @param customHeaders (optional) - custom headers that extends the default headers + * @example + * Simple usage: + * ```ts + * import { sdk } from '~/sdk.config.ts'; + * + * // fetch customer addresses if customer is logged in + * const { data } = await sdk.magento.getCustomerAddresses(); + * + * // data contains the customer addresses + * data.customer.addresses; // array of customer addresses + * ``` + * + * @example + * Creating a custom GraphQL query + * + * ```ts + * module.exports = { + * integrations: { + * magento: { + * customQueries: { + * 'get-customer-addresses-custom-query': ({ variables, metadata }) => ({ + * variables, + * query: ` + * query getCustomerAddresses { + * customer { + * addresses { + * ${metadata.fields} + * } + * } + * } + * ` + * }), + * }, + * } + * } + * }; + * ``` + * + * @example + * Using a custom GraphQL query to reduce the amount of data returned by the query + * + * ```ts + * import { sdk } from '~/sdk.config.ts'; + * // reduce the amount of fields returned by the query, when compared to the default query + * const customQuery = { + * getCustomerAddresses: 'get-customer-addresses-custom-query', + * metadata: { + * fields: 'city' + * } + * }; + * + * const { data } = await sdk.magento.getCustomerAddresses(customQuery); + * + * // data contains the customer addresses with only the city field + * ``` */ export async function getCustomerAddresses( context: Context, diff --git a/packages/api-client/src/api/mergeCarts/index.ts b/packages/api-client/src/api/mergeCarts/index.ts index c6bc66895..3b2b1ade4 100644 --- a/packages/api-client/src/api/mergeCarts/index.ts +++ b/packages/api-client/src/api/mergeCarts/index.ts @@ -5,6 +5,70 @@ import mergeCartsQuery from "./mergeCarts"; import { Context } from "../../types/context"; import getHeaders from "../getHeaders"; +/** + * Merge carts + * + * @example + * Simple usage: + * ```ts + * import { sdk } from '~/sdk.config.ts'; + * + * const params = { + * sourceCartId: 'pCS0ykep1l3wGlPKSyWLJq5fb1DxIQcp', + * // this cart needs to have been created by a logged in user + * destinationCartId: 'xiYYh2ep0l3xGtPsz2WLJf5f31DxBJx0' + * } + * + * // merge carts and return the result (cart) + * const mergedCart = await sdk.magento.mergeCarts(params); + * ``` + * + * @example + * Creating a custom GraphQL query for merging carts + * + * ```ts + * module.exports = { + * integrations: { + * magento: { + * customQueries: { + * 'merge-carts-custom-query': ({ variables, metadata }) => ({ + * variables, + * query: ` + * mutation mergeCarts($sourceCartId: String!, $destinationCartId: String!) { + * mergeCarts(source_cart_id: $sourceCartId, destination_cart_id: $destinationCartId) { + * ${metadata.fields} + * } + * } + * ` + * }), + * }, + * } + * } + * }; + * ``` + * + * @example + * Using a custom GraphQL query to merge carts + * + * ```ts + * import { sdk } from '~/sdk.config.ts'; + * // reduce the amount of fields returned by the query, when compared to the default query + * const customQuery = { + * cart: 'merge-carts-custom-query', + * metadata: { + * fields: 'id items { product { name } }' + * } + * }; + * + * const params = { + * sourceCartId: 'pCS0ykep1l3wGlPKSyWLJq5fb1DxIQcp', + * destinationCartId: 'xiYYh2ep0l3xGtPsz2WLJf5f31DxBJx0' + * } + * const mergedCart = await sdk.magento.mergeCarts(params, customQuery); + * + * // Merged cart will contain only the fields specified in the custom query. + * ``` + */ export async function mergeCarts( context: Context, params: { diff --git a/packages/api-client/src/api/placeOrder/index.ts b/packages/api-client/src/api/placeOrder/index.ts index a512eda5f..083a76f83 100644 --- a/packages/api-client/src/api/placeOrder/index.ts +++ b/packages/api-client/src/api/placeOrder/index.ts @@ -7,11 +7,87 @@ import { Context } from "../../types/context"; import getHeaders from "../getHeaders"; /** - * Places an order for received cart. + * Place an order. * - * @param context VSF Context - * @param input the order's input, containing the cart's ID - * @param customHeaders (optional) - custom headers that extends the default headers + * @example + * Simple usage: + * ```ts + * import { sdk } from '~/sdk.config.ts'; + * + * // place an order + * const result = await sdk.magento.placeOrder({cart_id: 'some-cart-id'}); + * + * // example result: + * { + * "data": { + * "placeOrder": { + * "__typename": "PlaceOrderOutput", + * "order": { + * "__typename": "Order", + * "order_number": "000000522" + * } + * } + * } + * } + * ``` + * + * @example + * The complete flow of placing an order for a guest user: + * + * ```ts + * const emptyCart = await sdk.magento.createEmptyCart(); // create an empty cart + * const cartId = emptyCart?.data?.createEmptyCart || ''; // get cart id from the response + * + * // set guest email on the cart + * await sdk.magento.setGuestEmailOnCart({ cart_id: cartId, email: 'john.doe+test@vuestorefront.io' }); + * + * // add products to the cart + * await sdk.magento.addProductsToCart({ + * cartId, + * cartItems: [ + * { + * quantity: 1, + * sku: 'some-sku', + * // size and color + * selected_options: ['Y29uZmlndXJhYmxlLzkzLzUz', 'Y29uZmlndXJhYmxlLzE0NC8xNzE='] + * } + * ] + * }); + * + * const address = { + * firstname: 'John', + * lastname: 'Doe', + * city: 'New York', + * country_code: 'US', + * street: ['Street 1', 'Street 2'], + * telephone: '123 123 123', + * region: 'AL', + * postcode: '10001', + * save_in_address_book: false + * } + * + * // set shipping and billing address + * await sdk.magento.setShippingAddressesOnCart({ + * cart_id: cartId, + * shipping_addresses: [{ address }] + * }); + * await sdk.magento.setBillingAddressOnCart({ + * cart_id: cartId, + * billing_address: { address } + * }); + * + * // + * await sdk.magento.setShippingMethodsOnCart({ + * cart_id: cartId, + * shipping_methods: [{ carrier_code: 'flatrate', method_code: 'flatrate' }] + * }); + * await sdk.magento.setPaymentMethodOnCart({ + * cart_id: cartId, + * payment_method: { code: 'checkmo' } + * }); + * + * // place the order + * const result = await sdk.magento.placeOrder({ cart_id: cartId }); */ export async function placeOrder( context: Context, diff --git a/packages/api-client/src/api/productDetails/index.ts b/packages/api-client/src/api/productDetails/index.ts index 4e48a7d4a..9ad1cb540 100644 --- a/packages/api-client/src/api/productDetails/index.ts +++ b/packages/api-client/src/api/productDetails/index.ts @@ -23,12 +23,87 @@ type Variables = { }; /** - * Fetches the list of products with details using sort, filters and pagination. + * Get products details * - * @param context VSF context - * @param searchParams params with sort, filters and pagination - * @param [customQuery] (optional) - custom GraphQL query that extends the default query - * @param customHeaders (optional) - custom headers that extends the default headers + * @example + * Simple usage without filters, sorting or pagination: + * ```ts + * import { sdk } from '~/sdk.config.ts'; + * + * // fetch list of products with default parameters + * const details = await sdk.magento.productDetails({}); + * ``` + * + * @example + * Usage with filters, sorting and pagination: + * + * ```ts + * import { sdk } from '~/sdk.config.ts'; + * + * // make a request to fetch list of products with custom parameters + * const details = await sdk.magento.productDetails({ + * pageSize: 20, + * currentPage: 1, + * filter: { + * sku: { + * eq: PRODUCT_SKU + * } + * } + * }); + * ``` + * + * @example + * Creating a custom GraphQL query for adding product details. + * + * ```ts + * module.exports = { + * integrations: { + * magento: { + * customQueries: { + * 'product-details-custom-query': ({ variables, metadata }) => ({ + * variables, + * query: ` + * query productDetails( + * $search: String = "", + * $filter: ProductAttributeFilterInput, + * $pageSize: Int = 10, + * $currentPage: Int = 1, + * $sort: ProductAttributeSortInput + * ) { + * products(search: $search, filter: $filter, sort: $sort, pageSize: $pageSize, currentPage: $currentPage) { + * ${metadata.fields} + * } + * } + * ` + * }), + * }, + * } + * } + * }; + * ``` + * + * @example + * Using a custom GraphQL query to fetch product details. + * + * ```ts + * import { sdk } from '~/sdk.config.ts'; + * const customQuery = { + * productDetails: 'product-details-custom-query', + * metadata: { + * fields: 'items { sku name }' + * } + * }; + * + * const details = await sdk.magento.productDetails({ + * filter: { + * sku: { + * eq: 'some-sku' // optional SKU filter + * } + * } + * }, customQuery); + * + * // Details will contain only the fields specified in the custom query. + * ``` */ export async function productDetails( context: Context, diff --git a/packages/api-client/src/api/productReview/index.ts b/packages/api-client/src/api/productReview/index.ts index 129aae401..9e3fd145e 100644 --- a/packages/api-client/src/api/productReview/index.ts +++ b/packages/api-client/src/api/productReview/index.ts @@ -22,7 +22,72 @@ type Variables = { }; /** - * Returns reviews of the provided product + * Fetch product reviews + * + * @example + * Simple usage: + * ```ts + * import { sdk } from '~/sdk.config.ts'; + * + * // fetch all products reviews (default pagination limit is 10) + * const result = await sdk.magento.productReview({}); + * ``` + * @example + * Fetching reviews for a specific product: + * + * ```ts + * import { sdk } from '~/sdk.config.ts'; + * + * const result = await sdk.magento.productReview({ filter: { sku: { eq: '24-MB01' } ); + * ``` + * @example + * Creating a custom GraphQL query + * + * ```ts + * module.exports = { + * integrations: { + * magento: { + * customQueries: { + * 'product-review-custom-query': ({ variables, metadata }) => ({ + * variables, + * query: ` + * query productReview($search: String = "", $filter: ProductAttributeFilterInput, $pageSize: Int = 10, $currentPage: Int = 1, $sort: ProductAttributeSortInput) { + * products(search: $search, filter: $filter, sort: $sort) { + * items { + * review_count + * reviews(pageSize: $pageSize, currentPage: $currentPage) { + * items { + * ${metadata?.fields} + * } + * } + * } + * } + * } + * ` + * }), + * }, + * } + * } + * }; + * ``` + * + * @example + * Using a custom GraphQL query to change the amount of fields returned by the query: + * + * ```ts + * import { sdk } from '~/sdk.config.ts'; + * // reduce the amount of fields returned by the query, when compared to the default query + * const customQuery = { + * productReview: 'product-review-custom-query', + * metadata: { + * fields: 'average_rating' + * } + * }; + * + * const result = await sdk.magento.productReview({}, customQuery); + * + * // result.data.products.items[0].reviews.items[0] will only contain the average_rating field + * ``` */ export async function productReview( context: Context, diff --git a/packages/api-client/src/api/productReviewRatingsMetadata/index.ts b/packages/api-client/src/api/productReviewRatingsMetadata/index.ts index d092e9e1f..1dd1a4eaf 100644 --- a/packages/api-client/src/api/productReviewRatingsMetadata/index.ts +++ b/packages/api-client/src/api/productReviewRatingsMetadata/index.ts @@ -6,7 +6,68 @@ import { Context } from "../../types/context"; import getHeaders from "../getHeaders"; /** - * Returns the active ratings attributes and the values each rating can have. + * Get the active ratings attributes and the values each rating can have. + * + * @example + * Simple usage: + * ```ts + * import { sdk } from '~/sdk.config.ts'; + * + * // fetch the active ratings attributes and the values each rating can have + * const { data } = await sdk.magento.productReviewRatingsMetadata(); + * + * data.productReviewRatingsMetadata.items; // array of review's attributes + * data.productReviewRatingsMetadata.items[0].values; // array of possible values of the review's attributes + * ``` + * + * @example + * Creating a custom GraphQL query + * + * ```ts + * module.exports = { + * integrations: { + * magento: { + * customQueries: { + * 'product-review-ratings-metadata-custom-query': ({ variables, metadata }) => ({ + * variables, + * query: ` + * query productReviewRatingsMetadata { + * productReviewRatingsMetadata { + * items { + * ${metadata.fields} + * } + * } + * } + * ` + * }), + * }, + * } + * } + * }; + * ``` + * + * @example + * Using a custom GraphQL query to reduce the amount of data returned by the query + * + * ```ts + * import { sdk } from '~/sdk.config.ts'; + * // reduce the amount of fields returned by the query, when compared to the default query + * const customQuery = { + * productReviewRatingsMetadata: 'product-review-ratings-metadata-custom-query', + * metadata: { + * fields: ` + * name + * values { + * value + * } + * ` + * } + * }; + * + * const { data } = await sdk.magento.productReviewRatingsMetadata(customQuery); + * + * // data.productReviewRatingsMetadata.items[0] will contain only the fields specified in the custom query. + * ``` */ export async function productReviewRatingsMetadata( context: Context, diff --git a/packages/api-client/src/api/products/index.ts b/packages/api-client/src/api/products/index.ts index 1342da789..fce1659ee 100644 --- a/packages/api-client/src/api/products/index.ts +++ b/packages/api-client/src/api/products/index.ts @@ -23,13 +23,87 @@ type Variables = { }; /** - * Fetches products using received search term and params for filter, sort and - * pagination. + * Get products * - * @param context VSF context - * @param searchParams search term and params for filter, sort and pagination - * @param [customQuery] (optional) - custom GraphQL query that extends the default query - * @param customHeaders (optional) - custom headers that extends the default headers + * @example + * Simple usage without filters, sorting or pagination: + * ```ts + * import { sdk } from '~/sdk.config.ts'; + * + * // fetch list of products with default parameters + * const details = await sdk.magento.products({}); + * ``` + * + * @example + * Usage with filters, sorting and pagination: + * + * ```ts + * import { sdk } from '~/sdk.config.ts'; + * + * // make a request to fetch list of products with custom parameters + * const details = await sdk.magento.products({ + * pageSize: 20, + * currentPage: 1, + * filter: { + * sku: { + * eq: PRODUCT_SKU + * } + * } + * }); + * ``` + * + * @example + * Creating a custom GraphQL query for fetching products. + * + * ```ts + * module.exports = { + * integrations: { + * magento: { + * customQueries: { + * 'products-custom-query': ({ variables, metadata }) => ({ + * variables, + * query: ` + * query productsList( + * $search: String = "", + * $filter: ProductAttributeFilterInput, + * $pageSize: Int = 10, + * $currentPage: Int = 1, + * $sort: ProductAttributeSortInput + * ) { + * products(search: $search, filter: $filter, sort: $sort, pageSize: $pageSize, currentPage: $currentPage) { + * ${metadata.fields} + * } + * } + * ` + * }), + * }, + * } + * } + * }; + * ``` + * + * @example + * Using a custom GraphQL query to fetch products list. + * + * ```ts + * import { sdk } from '~/sdk.config.ts'; + * const customQuery = { + * products: 'products-custom-query', + * metadata: { + * fields: 'items { sku name }' + * } + * }; + * + * const products = await sdk.magento.products({ + * filter: { + * sku: { + * eq: 'some-sku' // optional SKU filter + * } + * } + * }, customQuery); + * + * // Products will contain only the fields specified in the custom query. + * ``` */ export async function products( context: Context, diff --git a/packages/api-client/src/api/relatedProducts/index.ts b/packages/api-client/src/api/relatedProducts/index.ts index cbcd5bf32..4521a822a 100644 --- a/packages/api-client/src/api/relatedProducts/index.ts +++ b/packages/api-client/src/api/relatedProducts/index.ts @@ -22,13 +22,95 @@ type Variables = { }; /** - * Searches for related products using params for sorting, filtering and - * pagination. + * Get related products * - * @param context VSF context - * @param searchParams params for sorting, filtering and pagination - * @param [customQuery] (optional) - custom GraphQL query that extends the default query - * @param customHeaders (optional) - custom headers that extends the default headers + * @example + * Simple usage without filters, sorting or pagination: + * ```ts + * import { sdk } from '~/sdk.config.ts'; + * + * // Fetch list of products filtered by the SKU + * // Only the parent product is affected by filters + * const products = await sdk.magento.relatedProduct({ + * pageSize: 1, + * filter: { + * sku: { + * eq: PRODUCT_SKU + * } + * } + * }); + * ``` + * + * @example + * Usage with filters, sorting and pagination: + * + * ```ts + * import { sdk } from '~/sdk.config.ts'; + * + * // make a request to fetch list of products with custom parameters + * const products = await sdk.magento.relatedProduct({ + * pageSize: 20, + * currentPage: 1, + * filter: { + * sku: { + * eq: PRODUCT_SKU + * } + * } + * }); + * ``` + * + * @example + * Creating a custom GraphQL query getting related products. + * + * ```ts + * module.exports = { + * integrations: { + * magento: { + * customQueries: { + * 'related-product-custom-query': ({ variables, metadata }) => ({ + * variables, + * query: ` + * query relatedProduct( + * $search: String = "", + * $filter: ProductAttributeFilterInput, + * $pageSize: Int = 10, + * $currentPage: Int = 1, + * $sort: ProductAttributeSortInput + * ) { + * products(search: $search, filter: $filter, sort: $sort, pageSize: $pageSize, currentPage: $currentPage) { + * ${metadata.fields} + * } + * } + * ` + * }), + * }, + * } + * } + * }; + * ``` + * + * @example + * Using a custom GraphQL query to fetch related products. + * + * ```ts + * import { sdk } from '~/sdk.config.ts'; + * const customQuery = { + * relatedProduct: 'related-product-custom-query', + * metadata: { + * fields: 'items { related_products { uid __typename } }' + * } + * }; + * + * const result = await sdk.magento.relatedProduct({ + * filter: { + * sku: { + * eq: 'some-sku' // optional SKU filter + * } + * } + * }, customQuery); + * + * // Result will contain only the fields specified in the custom query. + * ``` */ export async function relatedProducts( context: Context, diff --git a/packages/api-client/src/api/removeCouponFromCart/index.ts b/packages/api-client/src/api/removeCouponFromCart/index.ts index 17c788d99..88a48461e 100644 --- a/packages/api-client/src/api/removeCouponFromCart/index.ts +++ b/packages/api-client/src/api/removeCouponFromCart/index.ts @@ -12,11 +12,66 @@ import removeCouponFromCartMutation from "./removeCouponFromCart"; import getHeaders from "../getHeaders"; /** - * Removes a coupon from a cart - * @param context VSF context - * @param input ID of the cart and coupon to remove - * @param customQuery custom GraphQL query that extends the default one - * @param customHeaders (optional) - custom headers that extends the default headers + * Remove coupon from cart + * + * @example + * Simple usage: + * ```ts + * import { sdk } from '~/sdk.config.ts'; + * + * // assuming that the coupon code is already applied to the cart + * const params = { + * cart_id: 'test-cart-id', + * }; + * + * // Remove coupon from cart + * const result = await sdk.magento.removeCouponFromCart(params); + * ``` + * + * @example + * Creating a custom GraphQL query for getting cart + * + * ```ts + * module.exports = { + * integrations: { + * magento: { + * customQueries: { + * 'remove-coupon-from-cart-custom-query': ({ variables, metadata }) => ({ + * variables, + * query: ` + * mutation removeCouponFromCart($input: RemoveCouponFromCartInput) { + * removeCouponFromCart(input: $input) { + * ${metadata.fields} + * } + * }` + * }), + * }, + * } + * } + * }; + * ``` + * + * @example + * Using a custom GraphQL query to fetch reduced amount of data + * + * ```ts + * import { sdk } from '~/sdk.config.ts'; + * + * const customQuery = { + * removeCouponFromCart: 'remove-coupon-from-cart-custom-query', + * metadata: { + * fields: 'cart { applied_coupons { code } }' + * } + * }; + * + * // The only required parameter is cart_id + * const params = { + * cart_id: 'test-cart-id', + * }; + * + * // The result will contain only fields configured in the custom query + * const result = await sdk.magento.removeCouponFromCart(params, customQuery); + * ``` */ export async function removeCouponFromCart( context: Context, diff --git a/packages/api-client/src/api/removeItemFromCart/index.ts b/packages/api-client/src/api/removeItemFromCart/index.ts index e382802f2..8bdb04040 100644 --- a/packages/api-client/src/api/removeItemFromCart/index.ts +++ b/packages/api-client/src/api/removeItemFromCart/index.ts @@ -7,11 +7,71 @@ import removeItemFromCartMutation from "./removeItemFromCart"; import getHeaders from "../getHeaders"; /** - * Removes an item from the given cart - * @param context VSF context - * @param input ID of the cart and item to be removed from it - * @param customQuery custom GraphQL query that extends the default one - * @param customHeaders (optional) - custom headers that extends the default headers + * Remove item from cart. + * + * @example + * Simple usage: + * ```ts + * import { sdk } from '~/sdk.config.ts'; + * + * // Assumes that the cart has an item with the UID 'MY='. + * // Configure method parameters + * const params = { cart_id: TEST_CART_ID, cart_item_uid: 'MY=' } + * + * const result = await sdk.magento.removeItemFromCart(params); + * + * // result will contain the updated cart. + * // you can look at the cart items to see that the item with the UID 'MY=' has been removed. + * const hasItem = result.data?.removeItemFromCart!.cart!.items!.find(item => item!.uid === 'MY='); + * ``` + * + * @example + * Creating a custom GraphQL query for manipulating the cart response data. + * + * ```ts + * module.exports = { + * integrations: { + * magento: { + * customQueries: { + * 'remove-item-from-cart-custom-query': ({ variables, metadata }) => ({ + * variables, + * query: ` + * mutation removeItemFromCart($input: RemoveItemFromCartInput) { + * removeItemFromCart(input: $input) { + * cart { + * ${metadata.fields} + * } + * } + * }` + * }), + * }, + * } + * } + * }; + * ``` + * + * @example + * Using a custom GraphQL query created in the previous example. + * + * ```ts + * import { sdk } from '~/sdk.config.ts'; + * // reduce the amount of fields returned by the query, when compared to the default query + * // this will reduce the amount of data transferred from the server to the client. + * + * // All we need is the cart ID and the email address of the customer. + * const customQuery = { + * cart: 'remove-item-from-cart-custom-query', + * metadata: { + * fields: 'id email' + * } + * }; + * + * // Assumes that the cart has an item with the UID 'MY='. + * // Uses params from the previous example and the custom query. + * const result = await sdk.magento.removeItemFromCart(params, customQuery); + * + * // result will contain only the fields specified in the custom query. + * ``` */ export async function removeItemFromCart( context: Context, diff --git a/packages/api-client/src/api/removeProductsFromWishlist/index.ts b/packages/api-client/src/api/removeProductsFromWishlist/index.ts index 86f66bf22..e55175a48 100644 --- a/packages/api-client/src/api/removeProductsFromWishlist/index.ts +++ b/packages/api-client/src/api/removeProductsFromWishlist/index.ts @@ -6,6 +6,69 @@ import removeProductsFromWishlistQuery from "./removeProductsFromWishlist"; import { Context } from "../../types/context"; import getHeaders from "../getHeaders"; +/** + * Remove products from wishlist + * Customer must be logged in to perform this operation. (token in headers) + * + * @example + * Simple usage: + * ```ts + * import { sdk } from '~/sdk.config.ts'; + * + * // remove + * const result = await sdk.magento.removeProductsFromWishlist({ + * id: 'some-wishlist-id', + * items: ['some-product-id'] + * }); + * ``` + * + * @example + * Creating a custom GraphQL query + * + * ```ts + * module.exports = { + * integrations: { + * magento: { + * customQueries: { + * 'remove-products-from-wishlist-custom-query': ({ variables, metadata }) => ({ + * variables, + * query: ` + * mutation removeProductsFromWishlist($id: ID!, $items: [ID!]!) { + * removeProductsFromWishlist(wishlistId: $id, wishlistItemsIds: $items) { + * wishlist { + * ${metadata.fields} + * } + * } + * } + * ` + * }), + * }, + * } + * } + * }; + * ``` + * + * @example + * Using a custom GraphQL query to reduce the amount of data returned by the API + * + * ```ts + * import { sdk } from '~/sdk.config.ts'; + * // reduce the amount of fields returned by the query, when compared to the default query + * const customQuery = { + * removeProductsFromWishlist: 'remove-products-from-wishlist-custom-query', + * metadata: { + * fields: 'id' + * } + * }; + * + * const result = await sdk.magento.removeProductsFromWishlist({ + * id: 'some-wishlist-id', + * items: ['item-id-1', 'item-id-2'] + * }, customQuery); + * + * // result should be narrowed to only contain the `id` field + * ``` + */ export async function removeProductsFromWishlist( context: Context, input: RemoveProductsFromWishlistMutationVariables, diff --git a/packages/api-client/src/api/requestPasswordResetEmail/index.ts b/packages/api-client/src/api/requestPasswordResetEmail/index.ts index 6ef58a6df..5a0df2ef2 100644 --- a/packages/api-client/src/api/requestPasswordResetEmail/index.ts +++ b/packages/api-client/src/api/requestPasswordResetEmail/index.ts @@ -10,10 +10,18 @@ import { Context } from "../../types/context"; import getHeaders from "../getHeaders"; /** - * Requests a password reset email to be sent to the user - * @param context VSF Context - * @param input Email for which to request a password reset - * @param customHeaders (optional) - custom headers that extends the default headers + * Request password reset email + * + * @example + * Simple usage: + * ```ts + * import { sdk } from '~/sdk.config.ts'; + * + * // trigger sending of password reset email + * const result = await sdk.magento.requestPasswordResetEmail({ email: 'john.doe@gmail.com'}); + * + * // result.data.requestPasswordResetEmail contains the boolean response from the API + * ``` */ export async function requestPasswordResetEmail( context: Context, diff --git a/packages/api-client/src/api/resetPassword/index.ts b/packages/api-client/src/api/resetPassword/index.ts index c96bd2339..0c23b269c 100644 --- a/packages/api-client/src/api/resetPassword/index.ts +++ b/packages/api-client/src/api/resetPassword/index.ts @@ -10,10 +10,20 @@ import recaptchaValidator from "../../helpers/recaptcha/recaptchaValidator"; import getHeaders from "../getHeaders"; /** - * Resets a user's password - * @param context VSF Context - * @param input Params used to reset a user's password - * @param customHeaders (optional) - custom headers that extends the default headers + * Reset customer password. + * + * @example + * Simple usage: + * ```ts + * import { sdk } from '~/sdk.config.ts'; + * + * // fetch resetPassword + * const await sdk.magento.resetPassword({ + * email: 'customer.email@gmail.com' + * newPassword: 'newPassword', + * resetPasswordToken: 'resetPasswordToken' // token obtained from email {@link @vue-storefront/magento-sdk#requestPasswordResetEmail} + * }); + * ``` */ export async function resetPassword( context: Context, diff --git a/packages/api-client/src/api/reviews/index.ts b/packages/api-client/src/api/reviews/index.ts index 0014ed715..330d26262 100644 --- a/packages/api-client/src/api/reviews/index.ts +++ b/packages/api-client/src/api/reviews/index.ts @@ -12,7 +12,66 @@ import { Context } from "../../types/context"; import getHeaders from "../getHeaders"; /** - * Returns product reviews created by the current customer + * Fetch customer reviews + * + * @example + * Simple usage: + * ```ts + * import { sdk } from '~/sdk.config.ts'; + * + * // fetch reviews, customer must be logged in + * const result = await sdk.magento.reviews(); + * + * // log all reviews + * result?.data?.customer?.reviews?.items.forEach(review => console.log(review)); + * ``` + * + * @example + * Creating a custom GraphQL query + * + * ```ts + * module.exports = { + * integrations: { + * magento: { + * customQueries: { + * 'customer-product-review-custom-query': ({ variables, metadata }) => ({ + * variables, + * query: ` + * query reviews($pageSize: Int = 10, $currentPage: Int = 1) { + * customer { + * reviews(pageSize: $pageSize, currentPage: $currentPage) { + * ${metadata?.fields} + * } + * } + * } + * ` + * }), + * }, + * } + * } + * }; + * ``` + * + * @example + * Using a custom GraphQL query to reduce the amount of fields returned by the query + * + * ```ts + * import { sdk } from '~/sdk.config.ts'; + * // reduce the amount of fields returned by the query, when compared to the default query + * // fetch only text + * + * const customQuery = { + * reviews: 'customer-product-review-custom-query', + * metadata: { + * fields: 'items { text }' + * } + * }; + * + * const result = await sdk.magento.reviews({}, customQuery); + * + * // result will only contain the text of the reviews + * result?.data?.customer?.reviews?.items.forEach(review => console.log(review.text)); + * ``` */ export async function reviews( context: Context, diff --git a/packages/api-client/src/api/revokeCustomerToken/index.ts b/packages/api-client/src/api/revokeCustomerToken/index.ts index d9d0d3812..accfb83a2 100644 --- a/packages/api-client/src/api/revokeCustomerToken/index.ts +++ b/packages/api-client/src/api/revokeCustomerToken/index.ts @@ -7,7 +7,18 @@ import { Context } from "../../types/context"; import getHeaders from "../getHeaders"; /** - * Logs out the current customer. To override the default query, use the `revokeCustomerToken` query key. + * Revoke customer token. + * It is used to log out the current customer. + * + * @example + * Simple usage if the customer is logged in and the token is valid: + * + * ```ts + * import { sdk } from '~/sdk.config.ts'; + * + * // token will be invalidated and the customer will be logged out + * await sdk.magento.revokeCustomerToken(); + * ``` */ export async function revokeCustomerToken(context: Context, customHeaders: CustomHeaders = {}): Promise> { return context.client.mutate({ diff --git a/packages/api-client/src/api/route/index.ts b/packages/api-client/src/api/route/index.ts index 6425a932c..372722e5d 100644 --- a/packages/api-client/src/api/route/index.ts +++ b/packages/api-client/src/api/route/index.ts @@ -6,12 +6,68 @@ import type { Context } from "../../types/context"; import getHeaders from "../getHeaders"; /** - * Returns the canonical URL for a specified product, category, or CMS page + * Resolve a route object data * - * @param context VSF Context - * @param url the URL to be resolved - * @param [customQuery] (optional) - custom GraphQL query that extends the default one - * @param customHeaders (optional) - custom headers that extends the default headers + * @example + * Simple usage: + * ```ts + * import { sdk } from '~/sdk.config.ts'; + * + * // fetch route object data + * const result = await sdk.magento.route({ + * url: 'aether-gym-pant.html' + * }); + * + * // Example result: + * { + * data: { + * route: { type: 'PRODUCT', sku: 'MP11', __typename: 'ConfigurableProduct' } + * }, + * loading: false, + * networkStatus: 7 + * } + * ``` + * * @example + * Creating a custom GraphQL query to fetch additional data: + * + * ```ts + * module.exports = { + * integrations: { + * magento: { + * customQueries: { + * 'route-custom-query': ({ variables, metadata }) => ({ + * variables, + * query: ` + * query route($url: String!) { + * route(url: $url) { + * ${metadata?.fields} + * } + * } + * }` + * }), + * }, + * } + * } + * }; + * ``` + * + * @example + * Using a custom GraphQL query created in the previous example. + * + * ```ts + * import { sdk } from '~/sdk.config.ts'; + * + * // reduce the amount of fields returned by the query, when compared to the default query + * const customQuery = { + * route: 'route-custom-query', + * metadata: { + * fields: 'type ... on CategoryInterface { uid name image}' // fetch additional name and image fields + * } + * }; + * + * // data will contain only the fields specified in the custom query. + * const { data } = await sdk.magento.route({ url: 'women.html' }, customQuery); + * ``` */ export async function route( context: Context, diff --git a/packages/api-client/src/api/setBillingAddressOnCart/index.ts b/packages/api-client/src/api/setBillingAddressOnCart/index.ts index a63cbbc9d..c3d6f46fd 100644 --- a/packages/api-client/src/api/setBillingAddressOnCart/index.ts +++ b/packages/api-client/src/api/setBillingAddressOnCart/index.ts @@ -11,6 +11,79 @@ import setBillingAddressOnCartQuery from "./setBillingAddressOnCart"; import { Context } from "../../types/context"; import getHeaders from "../getHeaders"; +/** + * Set billing address on the cart + * + * @example + * Simple usage: + * ```ts + * import { sdk } from '~/sdk.config.ts'; + * + * // Prepare parameters + * const params = { + * cart_id: 'some-cart-id', + * billing_address: { + * address: { + * firstname: 'John', + * lastname: 'Doe', + * city: 'New York', + * country_code: 'US', + * street: ['Street 1', 'Street 2'], + * telephone: '123 123 123', + * region: 'AL', + * postcode: '10001', + * save_in_address_book: false + * }, + * } + * }; + * + * // Set shipping address on the cart + * await sdk.magento.setBillingAddressOnCart(params); + * ``` + + * @example + * Creating a custom GraphQL query for reducing the amount of fields returned by the query, when compared to the default query. + * + * ```ts + * module.exports = { + * integrations: { + * magento: { + * customQueries: { + * 'set-billing-address-on-cart-custom-query': ({ variables, metadata }) => ({ + * variables, + * query: ` + * mutation setBillingAddressOnCart($input: SetBillingAddressOnCartInput) { + * setBillingAddressOnCart(input: $input) { + * cart { + * ${metadata.fields} + * } + * } + * }` + * }), + * }, + * } + * } + * }; + * ``` + * + * @example + * Using a custom GraphQL query created in the previous example. + * + * ```ts + * import { sdk } from '~/sdk.config.ts'; + * + * // reduce the amount of fields returned by the query, when compared to the default query + * const customQuery = { + * setBillingAddressOnCart: 'set-billing-address-on-cart-custom-query', + * metadata: { + * fields: 'billing_address { city }' + * } + * }; + * + * // data will contain only the fields specified in the custom query. + * const { data } = await sdk.magento.setBillingAddressOnCart(params, customQuery); + * ``` + */ export async function setBillingAddressOnCart( context: Context, input: SetBillingAddressOnCartInput, diff --git a/packages/api-client/src/api/setGuestEmailOnCart/index.ts b/packages/api-client/src/api/setGuestEmailOnCart/index.ts index 0ca60726b..83fbdbf66 100644 --- a/packages/api-client/src/api/setGuestEmailOnCart/index.ts +++ b/packages/api-client/src/api/setGuestEmailOnCart/index.ts @@ -13,10 +13,18 @@ import getHeaders from "../getHeaders"; /** * Set the guest user email on the cart - * @param context VSF Context - * @param input Variables to set guest email - * @param [customQuery] (optional) - Custom query that will extend default one - * @param customHeaders (optional) - custom headers that extends the default headers + * + * @example + * Simple usage: + * ```ts + * import { sdk } from '~/sdk.config.ts'; + * + * // set an email on the cart + * const result = await sdk.magento.setGuestEmailOnCart({ cart_id: 'some-cart-id', email: 'some-email' }); + * + * // new email will be set on the cart + * // data.setGuestEmailOnCart.cart.email will contain the email address + * ``` */ export async function setGuestEmailOnCart( context: Context, diff --git a/packages/api-client/src/api/setPaymentMethodOnCart/index.ts b/packages/api-client/src/api/setPaymentMethodOnCart/index.ts index 00304895c..5afb36f3f 100644 --- a/packages/api-client/src/api/setPaymentMethodOnCart/index.ts +++ b/packages/api-client/src/api/setPaymentMethodOnCart/index.ts @@ -13,12 +13,69 @@ import { Context } from "../../types/context"; import getHeaders from "../getHeaders"; /** - * Sets received payment method on cart. + * Set payment method on cart. * - * @param context VSF context - * @param input params containing the cart's ID and the payment method - * @param [customQuery] (optional) - custom GraphQL query that extends the default query - * @param customHeaders (optional) - custom headers that extends the default headers + * @example + * Simple usage: + * ```ts + * import { sdk } from '~/sdk.config.ts'; + * + * const params = { + * cart_id: 'some-cart-id' + * payment_method: { + * code: 'checkmo' + * } + * }; + * + * // sets payment method on cart and return payment information + * // data contains properties like `available_payment_methods` and `selected_payment_method` + * const { data } = await sdk.magento.setPaymentMethodOnCart(params); + * ``` + * + * @example + * Creating a custom GraphQL query for configuring the response data structure + * + * ```ts + * module.exports = { + * integrations: { + * magento: { + * customQueries: { + * 'set-payment-method-on-cart-custom-query': ({ variables, metadata }) => ({ + * variables, + * query: ` + * mutation setPaymentMethodOnCart($input: SetPaymentMethodOnCartInput) { + * setPaymentMethodOnCart(input: $input) { + * cart { + * ${metadata.fields} + * } + * } + * } + * ` + * }), + * }, + * } + * } + * }; + * ``` + * + * @example + * Using a custom GraphQL query created with the `set-payment-method-on-cart-custom-query` in the previous example + * + * ```ts + * import { sdk } from '~/sdk.config.ts'; + * // reduce the amount of fields returned by the query, when compared to the default query + * const customQuery = { + * setPaymentMethodOnCart: 'set-payment-method-on-cart-custom-query', + * metadata: { + * fields: 'available_payment_methods { code title }' + * } + * }; + * + * // Params and options are the same as in the previous example + * const { data } = await sdk.magento.setPaymentMethodOnCart(params, customQuery); + * + * // data contains only the properties selected in the custom query + * ``` */ export async function setPaymentMethodOnCart( context: Context, diff --git a/packages/api-client/src/api/setShippingAddressesOnCart/index.ts b/packages/api-client/src/api/setShippingAddressesOnCart/index.ts index 5e87c1d8a..2a59861ef 100644 --- a/packages/api-client/src/api/setShippingAddressesOnCart/index.ts +++ b/packages/api-client/src/api/setShippingAddressesOnCart/index.ts @@ -12,12 +12,101 @@ import type { Context } from "../../types/context"; import getHeaders from "../getHeaders"; /** - * Sets a shipping address on received cart. + * Set shipping addresses on the cart + * It should be used to set single or multiple shipping addresses on the cart. * - * @param context VSF context - * @param input params with cart ID and shipping address. - * @param [customQuery] (optional) - custom GraphQL query that extends the default one - * @param customHeaders (optional) - custom headers that extends the default headers + * @example + * Simple usage: + * ```ts + * import { sdk } from '~/sdk.config.ts'; + * + * // Prepare parameters + * const params = { + * cart_id: 'some-cart-id', + * shipping_addresses: [ + * { + * address: { + * firstname: 'John', + * lastname: 'Doe', + * city: 'New York', + * country_code: 'US', + * street: ['Street 1', 'Street 2'], + * telephone: '123 123 123', + * region: 'AL', + * postcode: '10001', + * save_in_address_book: false + * }, + * } + * ] + * }; + * + * // Set shipping address on the cart + * await sdk.magento.setShippingAddressesOnCart(params); + * ``` + * @example + * You can also use the `setShippingAddressesOnCart` method to set multiple shipping addresses on the cart. + * ```ts + * import { sdk } from '~/sdk.config.ts'; + * + * // Prepare parameters + * const params = { + * cart_id: 'some-cart-id', + * shipping_addresses: [ + * { + * address: address1, // address1 is an object with address details + * }, + * { + * address: address2, // address2 is an object with address details + * } + * ]; + * + * // This will set address1 and address2 on the cart + * await sdk.magento.setShippingAddressesOnCart(params); + * ``` + * + * + * @example + * Creating a custom GraphQL query for reducing the amount of fields returned by the query, when compared to the default query. + * + * ```ts + * module.exports = { + * integrations: { + * magento: { + * customQueries: { + * 'set-shipping-addresses-on-cart-custom-query': ({ variables, metadata }) => ({ + * variables, + * query: ` + * mutation setShippingAddressesOnCart($input: SetShippingAddressesOnCartInput) { + * setShippingAddressesOnCart(input: $input) { + * cart { + * ${metadata.fields} + * } + * } + * }` + * }), + * }, + * } + * } + * }; + * ``` + * + * @example + * Using a custom GraphQL query created in the previous example. + * + * ```ts + * import { sdk } from '~/sdk.config.ts'; + * + * // reduce the amount of fields returned by the query, when compared to the default query + * const customQuery = { + * cart: 'set-shipping-addresses-on-cart-custom-query', + * metadata: { + * fields: 'shipping_addresses { city }' + * } + * }; + * + * // data will contain only the fields specified in the custom query. + * const { data } = await sdk.magento.setShippingAddressesOnCart(params, customQuery); + * ``` */ export async function setShippingAddressesOnCart( context: Context, diff --git a/packages/api-client/src/api/setShippingMethodsOnCart/index.ts b/packages/api-client/src/api/setShippingMethodsOnCart/index.ts index 3120d2a43..ed27596e2 100644 --- a/packages/api-client/src/api/setShippingMethodsOnCart/index.ts +++ b/packages/api-client/src/api/setShippingMethodsOnCart/index.ts @@ -12,12 +12,87 @@ import type { Context } from "../../types/context"; import getHeaders from "../getHeaders"; /** - * Sets a shipping method on received cart. + * Set shipping methods on cart. + * Before using this method, you need to set shipping address on cart. * - * @param context VSF context - * @param input params with cart ID and shipping method. - * @param [customQuery] (optional) - custom GraphQL query that extends the default one - * @param customHeaders (optional) - custom headers that extends the default headers + * @example + * Simple usage: + * ```ts + * import { sdk } from '~/sdk.config.ts'; + * + * // Assuming that shipping address is already set on cart. + * // if not, you need to set shipping address on cart first. + * + * const params = { + * cart_id: 'some-cart-id', + * shipping_methods: [ + * { + * carrier_code: 'flatrate', + * method_code: 'flatrate' + * } + * ] + * }; + * + * const { data } = await sdk.magento.setShippingMethodsOnCart(params); + * + * // you can get set shipping methods on cart response from + * // data?.setShippingMethodsOnCart?.cart?.shipping_addresses?.[0]?.selected_shipping_method?.method_code + * ``` + * + * @example + * Creating a custom GraphQL query to change the amount of fields returned by the query, when compared to the default query + * + * ```ts + * module.exports = { + * integrations: { + * magento: { + * customQueries: { + * 'set-shipping-methods-on-cart-custom-query': ({ variables, metadata }) => ({ + * variables, + * query: ` + * mutation setShippingMethodsOnCart($input: SetShippingMethodsOnCartInput) { + * setShippingMethodsOnCart(input: $input) { + * cart { + * ${metadata.fields} + * } + * } + * }` + * }), + * }, + * } + * } + * }; + * ``` + * + * @example + * Using a custom GraphQL query created in the previous example + * + * ```ts + * import { sdk } from '~/sdk.config.ts'; + * // reduce the amount of fields returned by the query, when compared to the default query + * // you will get only selected_shipping_method.method_code field + * + * const customQuery = { + * setShippingMethodsOnCart: 'set-shipping-methods-on-cart-custom-query', + * metadata: { + * fields: 'shipping_addresses { selected_shipping_method { method_code } }' + * } + * }; + * + * const params = { + * cart_id: 'some-cart-id', + * shipping_methods: [ + * { + * carrier_code: 'flatrate', + * method_code: 'flatrate' + * } + * ] + * }; + * + * const { data } = await sdk.magento.setShippingMethodsOnCart(params, customQuery); + * + * // data will contain only the fields specified in the custom query. + * ``` */ export async function setShippingMethodsOnCart( context: Context, diff --git a/packages/api-client/src/api/storeConfig/index.ts b/packages/api-client/src/api/storeConfig/index.ts index 28370d791..52ad41119 100644 --- a/packages/api-client/src/api/storeConfig/index.ts +++ b/packages/api-client/src/api/storeConfig/index.ts @@ -7,10 +7,57 @@ import { Context } from "../../types/context"; import getHeaders from "../getHeaders"; /** - * Fetches the store configuration from the API - * @param context VSF Context - * @param [customQuery] (optional) - custom GraphQL query that extends the default one - * @param customHeaders (optional) - custom headers that extends the default headers + * Fetch store configuration + * + * @example + * Simple usage: + * ```ts + * import { sdk } from '~/sdk.config.ts'; + * + * // fetch store configuration + * const result = await sdk.magento.storeConfig(); + * + * // result?.data?.storeConfig contains the store configuration + * ``` + * + * @example + * + * ```ts + * module.exports = { + * integrations: { + * magento: { + * customQueries: { + * 'store-config-custom-query': ({ variables, metadata }) => ({ + * variables, + * query: ` + * query storeConfig { + * storeConfig { + * ${metadata?.fields} + * } + * } + * ` + * }), + * }, + * } + * } + * }; + * ``` + * + * @example + * Using a custom GraphQL query to select only the fields you need + * + * ```ts + * import { sdk } from '~/sdk.config.ts'; + * // we want to fetch only logo related data + * const customQuery = { + * storeConfig: 'store-config-custom-query', + * metadata: { + * fields: 'logo_alt logo_height logo_width' + * } + * }; + * + * const result = await sdk.magento.storeConfig(customQuery); + * ``` */ export async function storeConfig( context: Context, diff --git a/packages/api-client/src/api/subscribeEmailToNewsletter/index.ts b/packages/api-client/src/api/subscribeEmailToNewsletter/index.ts index e047d0d01..3fd3263b4 100644 --- a/packages/api-client/src/api/subscribeEmailToNewsletter/index.ts +++ b/packages/api-client/src/api/subscribeEmailToNewsletter/index.ts @@ -6,10 +6,18 @@ import { Context } from "../../types/context"; import getHeaders from "../getHeaders"; /** - * Subscribes an email in the newsletter. - * @param context VSF context - * @param input params with the email to subscribe - * @param customHeaders (optional) - custom headers that extends the default headers + * Allows guests and registered customers to sign up to receive newsletters. + * + * @example + * Simple usage: + * ```ts + * import { sdk } from '~/sdk.config.ts'; + * + * // subscribe an email in the newsletter. * const email = 'somemail@vsf.local'; + * const result = await sdk.magento.subscribeEmailToNewsletter({ email }); + * + * result.data?.subscribeEmailToNewsletter?.status; // status of the operation. Possible values: https://developer.adobe.com/commerce/webapi/graphql/schema/customer/mutations/subscribe-email-to-newsletter/#subscriptionstatusesenum + * ``` */ export async function subscribeEmailToNewsletter( context: Context, diff --git a/packages/api-client/src/api/updateCartItems/index.ts b/packages/api-client/src/api/updateCartItems/index.ts index 855490f26..f248d8a52 100644 --- a/packages/api-client/src/api/updateCartItems/index.ts +++ b/packages/api-client/src/api/updateCartItems/index.ts @@ -7,11 +7,67 @@ import updateCartItemsMutation from "./updateCartItems"; import getHeaders from "../getHeaders"; /** - * Updates the contents of the given cart - * @param context VSF context - * @param input ID of the cart and the items to update it - * @param customQuery custom GraphQL query that extends the default one - * @param customHeaders (optional) - custom headers that extends the default headers + * Update items in the cart + * + * @example + * Simple usage, updating the quantity of a cart item: + * ```ts + * import { sdk } from '~/sdk.config.ts'; + * + * // update the quantity of a cart item + * const result = await sdk.magento.updateCartItems({ + * cart_id: 'some-cart-id' + * cart_items: [{ + * cart_item_uid: 'MY=', + * quantity: 10 // update the quantity to 10 + * }] + * }); + * + * // result will contain the updated cart. + * ``` + * + * @example + * Creating a custom GraphQL query for manipulating the cart response data. + * ```ts + * module.exports = { + * integrations: { + * magento: { + * customQueries: { + * 'update-cart-items-custom-query': ({ variables, metadata }) => ({ + * variables, + * query: ` + * mutation updateCartItems($input: UpdateCartItemsInput) { + * updateCartItems(input: $input) { + * cart { + * ${metadata.fields} + * } + * } + * }` + * }), + * }, + * } + * } + * }; + * ``` + * + * @example + * Using a custom GraphQL query created in the previous example. + * Note that the custom query must be passed to the `customQuery` property of the `options` parameter. + * The `metadata` property of the `options` parameter can be used to pass additional data to the custom query. + * ```ts + * import { sdk } from '~/sdk.config.ts'; + * // reduce the amount of fields returned by the query, when compared to the default query + * const customQuery = { + * updateCartItems: 'update-cart-items-custom-query', + * metadata: { + * fields: 'id items { uid quantity product { uid sku }}' + * } + * }; + * + * // update the quantity of a cart item with params and custom query + * // Params are the same as in the previous example. + * const result = await sdk.magento.updateCartItems(params, customQuery); + * ``` */ export async function updateCartItems( context: Context, diff --git a/packages/api-client/src/api/updateCustomer/index.ts b/packages/api-client/src/api/updateCustomer/index.ts index 3e586feee..cc0ae760f 100644 --- a/packages/api-client/src/api/updateCustomer/index.ts +++ b/packages/api-client/src/api/updateCustomer/index.ts @@ -7,7 +7,72 @@ import { Context } from "../../types/context"; import getHeaders from "../getHeaders"; /** - * Updates the data of the current customer. To override the default query, use the `updateCustomer` query key. + * Update customer data. + * Customer data is updated based on the current customer token. + * + * @example + * Simple usage: + * ```ts + * import { sdk } from '~/sdk.config.ts'; + * + * // Updates customer first name + * const result = await sdk.magento.updateCustomer({ + * firstname: 'New John' + * }); + * + * // result contains updated customer data + * console.log(result); // result.data.updateCustomerV2.customer.firstname === 'New John' + * ``` + * + * @example + * Creating a custom GraphQL query + * + * ```ts + * module.exports = { + * integrations: { + * magento: { + * customQueries: { + * 'update-customer-custom-query': ({ variables, metadata }) => ({ + * variables, + * query: ` + * mutation updateCustomer($input: CustomerUpdateInput!) { + * updateCustomerV2(input: $input) { + * customer { + * ${metadata.fields} + * } + * } + * } + * ` + * }), + * }, + * } + * } + * }; + * ``` + * + * @example + * Using a custom GraphQL query to reduce the amount of data returned by the query + * + * ```ts + * import { sdk } from '~/sdk.config.ts'; + * // reduce the amount of fields returned by the query, when compared to the default query + * const customQuery = { + * updateCustomer: 'update-customer-custom-query', + * metadata: { + * fields: 'firstname lastname' + * } + * }; + * + * const result = await sdk.magento.updateCustomer({ + * firstname: 'New John' + * lastname: 'New Doe' + * }, customQuery); + * + * // result contains only the fields specified in the custom query + * // result.data.updateCustomerV2.customer.firstname === 'New John' + * // result.data.updateCustomerV2.customer.lastname === 'New Doe' + * console.log(result); // result.data.updateCustomerV2.customer.firstname === 'New John' + * ``` */ export async function updateCustomer( context: Context, diff --git a/packages/api-client/src/api/updateCustomerAddress/index.ts b/packages/api-client/src/api/updateCustomerAddress/index.ts index 88a3f87cb..e7da3b39c 100644 --- a/packages/api-client/src/api/updateCustomerAddress/index.ts +++ b/packages/api-client/src/api/updateCustomerAddress/index.ts @@ -6,12 +6,60 @@ import { Context } from "../../types/context"; import getHeaders from "../getHeaders"; /** - * Updates a customer address. + * Update customer address + * The user needs to be logged in in order to send this request * - * @param context VSF Context - * @param params object with address identifier and the updated data - * @param [customQuery] (optional) custom GraphQL query that extends the default query - * @param customHeaders (optional) - custom headers that extends the default headers + * @example + * Simple usage: + * ```ts + * import { sdk } from '~/sdk.config.ts'; + * + * // fetch updated customer address + * const result = await sdk.magento.updateCustomerAddress(); + * ``` + * + * @example + * Creating a custom GraphQL query for updating customer address + * + * ```ts + * module.exports = { + * integrations: { + * magento: { + * customQueries: { + * 'update-customer-address-custom-query': ({ variables, metadata }) => ({ + * variables, + * query: ` + * mutation updateCustomerAddress($id: Int!, $input: CustomerAddressInput) { + * updateCustomerAddress(id: $id, input: $input) { + * ${metadata.fields} + * } + * } + * ` + * ` + * }), + * }, + * } + * } + * }; + * ``` + * + * @example + * Using a custom GraphQL query to update customer address + * + * ```ts + * import { sdk } from '~/sdk.config.ts'; + * // reduce the amount of fields returned by the query, when compared to the default query + * const customQuery = { + * updateCustomerAddress: 'update-customer-address-custom-query', + * metadata: { + * fields: 'id city company' + * } + * }; + * + * const result = await sdk.magento.updateCustomerAddress({ id: 308, input: { city: "Warsaw" } }, customQuery); + * + * // result will contain only the fields specified in the custom query. + * ``` */ export async function updateCustomerAddress( context: Context, diff --git a/packages/api-client/src/api/updateCustomerEmail/index.ts b/packages/api-client/src/api/updateCustomerEmail/index.ts index c2823f787..2aeef3df1 100644 --- a/packages/api-client/src/api/updateCustomerEmail/index.ts +++ b/packages/api-client/src/api/updateCustomerEmail/index.ts @@ -5,6 +5,62 @@ import updateCustomerEmailQuery from "./updateCustomerEmail"; import { Context } from "../../types/context"; import getHeaders from "../getHeaders"; +/** + * Update customer email + * + * @example + * Simple usage: + * ```ts + * import { sdk } from '~/sdk.config.ts'; + * + * // update customer + * const result = await sdk.magento.updateCustomerEmail({ email: "johndoe@example.com", password: "hunter2" }); + * ``` + * + * @example + * Creating a custom GraphQL query for updating customer + * + * ```ts + * module.exports = { + * integrations: { + * magento: { + * customQueries: { + * 'update-customer-email-custom-query': ({ variables, metadata }) => ({ + * variables, + * query: ` + * mutation updateCustomerEmail($email: String!, $password: String!) { + * updateCustomerEmail(email: $email, password: $password){ + * customer { + * ${metadata.fields} + * } + * } + * } + * ` + * }), + * }, + * } + * } + * }; + * ``` + * + * @example + * Using a custom GraphQL query to update customer + * + * ```ts + * import { sdk } from '~/sdk.config.ts'; + * // reduce the amount of fields returned by the query, when compared to the default query + * const customQuery = { + * updateCustomerEmail: 'update-customer-email-custom-query', + * metadata: { + * fields: 'email firstname' + * } + * }; + * + * const result = await sdk.magento.updateCustomerEmail({ email: "johndoe@example.com", password: "hunter2" }, customQuery); + * + * // Result will contain only the fields specified in the custom query. + * ``` + */ export async function updateCustomerEmail( context: Context, input: UpdateCustomerEmailMutationVariables, diff --git a/packages/api-client/src/api/upsellProducts/index.ts b/packages/api-client/src/api/upsellProducts/index.ts index 0fdb4b62d..ac2642df5 100644 --- a/packages/api-client/src/api/upsellProducts/index.ts +++ b/packages/api-client/src/api/upsellProducts/index.ts @@ -22,7 +22,87 @@ type Variables = { }; /** - * Returns upsell products matching the provided parameters. To override the default query, use the `upsellProducts` query key. + * Get upsell products for a given product. + * + * @example + * Simple usage without filters, sorting or pagination: + * ```ts + * import { sdk } from '~/sdk.config.ts'; + * + * // fetch list of upsell-products with default parameters + * const upsellProducts = await sdk.magento.upsellProducts({}); + * ``` + * + * @example + * Usage with filters, sorting and pagination: + * + * ```ts + * import { sdk } from '~/sdk.config.ts'; + * + * // make a request to fetch list of products with upsell products + * const upsellProducts = await sdk.magento.upsellProducts({ + * pageSize: 20, + * currentPage: 1, + * filter: { + * sku: { + * eq: PRODUCT_SKU + * } + * } + * }); + * ``` + * + * @example + * Creating a custom GraphQL query for getting upsellProducts. + * + * ```ts + * module.exports = { + * integrations: { + * magento: { + * customQueries: { + * 'upsell-products-custom-query': ({ variables, metadata }) => ({ + * variables, + * query: ` + * query upsellProducts( + * $search: String = "", + * $filter: ProductAttributeFilterInput, + * $pageSize: Int = 10, + * $currentPage: Int = 1, + * $sort: ProductAttributeSortInput + * ) { + * products(search: $search, filter: $filter, sort: $sort, pageSize: $pageSize, currentPage: $currentPage) { + * ${metadata.fields} + * } + * } + * ` + * }), + * }, + * } + * } + * }; + * ``` + * + * @example + * Using a custom GraphQL query to fetch upsell-products. + * + * ```ts + * import { sdk } from '~/sdk.config.ts'; + * const customQuery = { + * upsellProducts: 'upsell-products-custom-query', + * metadata: { + * fields: 'items { sku name upsell_products { sku } }' + * } + * }; + * + * const upsellProducts = await sdk.magento.upsellProducts({ + * filter: { + * sku: { + * eq: 'some-sku' // optional SKU filter + * } + * } + * }, customQuery); + * + * // upsellProducts will contain only the fields specified in the custom query. + * ``` */ export async function upsellProducts( context: Context, diff --git a/packages/api-client/src/api/urlResolver/index.ts b/packages/api-client/src/api/urlResolver/index.ts index 25723435c..266a29364 100644 --- a/packages/api-client/src/api/urlResolver/index.ts +++ b/packages/api-client/src/api/urlResolver/index.ts @@ -7,11 +7,7 @@ import getHeaders from "../getHeaders"; /** * Fetches the resolver for received URL. * - * @param context VSF Context - * @param url the URL to be resolved - * @param [customQuery] (optional) - custom GraphQL query that extends the default one - * @param customHeaders (optional) - custom headers that extends the default headers - * @deprecated - use route instead + * @deprecated - use {@link https://docs.alokai.com/integrations/magento/api/magento-api/route | route} instead. */ export async function urlResolver( context: Context, diff --git a/packages/api-client/src/api/wishlist/index.ts b/packages/api-client/src/api/wishlist/index.ts index f74a729d3..109042612 100644 --- a/packages/api-client/src/api/wishlist/index.ts +++ b/packages/api-client/src/api/wishlist/index.ts @@ -10,6 +10,9 @@ type Variables = { currentPage: number; }; +/** + * Get wishlist. + */ export async function wishlist( context: Context, searchParams: WishlistQueryVariables, diff --git a/packages/api-client/src/api/wishlistItemsCount/index.ts b/packages/api-client/src/api/wishlistItemsCount/index.ts index 6afa345ff..d25ba6bf5 100644 --- a/packages/api-client/src/api/wishlistItemsCount/index.ts +++ b/packages/api-client/src/api/wishlistItemsCount/index.ts @@ -6,6 +6,21 @@ import wishlistItemsCountQuery from "./wishlistItemsCount"; import { Context } from "../../types/context"; import getHeaders from "../getHeaders"; +/** + * Count items in the wishlist + * + * @example + * Simple usage: + * ```ts + * import { sdk } from '~/sdk.config.ts'; + * + * // returns items counter of each wishlist for currently logged in customer + * const response = await sdk.magento.wishlistItemsCount(); + * // response.data?.customer!.wishlists - array with object containing items counter. + * // response.data?.customer!.wishlists[X]!.items_count - items_counter for each selected wishlist. + * // index of element in the array isn't equal wishlist's id in the magento. + * ``` + */ export async function wishlistItemsCount(context: Context, customHeaders: CustomHeaders = {}): Promise> { return context.client.query({ query: gql` diff --git a/packages/sdk/src/index.ts b/packages/sdk/src/index.ts index 65bc159df..8b01be2c2 100644 --- a/packages/sdk/src/index.ts +++ b/packages/sdk/src/index.ts @@ -13,7 +13,42 @@ export interface MagentoModuleType extends Module { /** * Magento module. * - * @example + * @deprecated + * + * Use `middlewareModule` instead. + * + * ```diff + * - import { initSDK, buildModule } from '@vue-storefront/sdk'; + * - import { magentoModule } from '@vsf-enterprise/magento-sdk' + * + import { initSDK, buildModule, middlewareModule } from '@vue-storefront/sdk'; + * + import { Endpoints as MagentoEndpoints } from '@vsf-enterprise/magento-api'; + * + * const sdkConfig = { + * magneto: + * buildModule( + * - magentoModule, + * + middlewareModule, + * { apiUrl: 'http://localhost:8181/magneto' } + * ) + * }; + * + * export const sdk = initSDK(sdkConfig); + * + * // Breaking changes: + * // - Custom queries are now a second argument of the methods. + * + * const customQuery = { + * cart: 'cart-custom-query', + * metadata: { + * fields: 'id items { uid }' + * } + * }; + * - const cart = await sdk.magento.cart({ cartId: '123'}, { customQuery }); + * + const cart = await sdk.magento.cart({ cartId: '123'}, customQuery); + * + * ``` + * + * @example * Initialization of the Magento module. * * ```js