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 <[email protected]> --------- Co-authored-by: Matt Maribojoc <[email protected]> --------- Co-authored-by: Matt Maribojoc <[email protected]>
vuestorefront · Apr 19, 2024 · 6672edf · 6672edf
1 parent 8138228
commit 6672edf
Show file tree

Hide file tree

Showing 79 changed files with 3,431 additions and 341 deletions.
diff --git a/.changeset/eighty-papayas-occur.md 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<MagentoEndpoints>,
+      { 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
@@ -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
@@ -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<MagentoModuleType>(magentoModule, { 
-    apiUrl: 'http://localhost:8181/magento'
-  })
+  magento: buildModule(middlewareModule<Endpoints>, {
+    apiUrl: "http://localhost:8181/magento",
+  }),
 };
 
-export const sdk = initSDK<typeof sdkConfig>(sdkConfig);
+export const sdk = initSDK(sdkConfig);
 ```
 
-<!-- 3. Your SDK is ready! You can now import it in the different parts of your frontend application and call methods with `sdk.magento.<METHOD_NAME>`. To see a full list of methods offered by the Magento 2 module, check out the [API Reference](../reference/api/index.md). -->
+2. Your SDK is ready! You can now import it in the different parts of your frontend application and call methods with `sdk.magento.<METHOD_NAME>`. 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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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
@@ -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 |