feat: add categories method

.changeset/calm-berries-do.md

@@ -0,0 +1,7 @@
+---
+"@vue-storefront/magento-api": minor
+---
+
+[ADDED] `categories` endpoint that allows fetching a list of categories that match the specified filter.
+[CHANGED] `categoryList` endpoint is now deprecated in favor of the new `categories` endpoint.
+```

.changeset/fifty-carpets-play.md

@@ -0,0 +1,5 @@
+---
+"@vue-storefront/magento-types": minor
+---
+
+[ADDED] `categories` endpoint definition.

.changeset/gold-elephants-rescue.md

@@ -0,0 +1,5 @@
+---
+"@vue-storefront/magento-sdk": minor
+---
+
+[ADDED] `categories` method that allows fetching a list of categories that match the specified filter.

packages/api-client/src/api/categories/categories.ts

@@ -0,0 +1,73 @@
+export default `
+  query categories(
+    $filters: CategoryFilterInput,
+    $pageSize: Int,
+    $currentPage: Int
+  ) {
+    categories(
+      filters: $filters,
+      pageSize: $pageSize,
+      currentPage: $currentPage
+    ) {
+      items {
+        children {
+          include_in_menu
+          is_anchor
+          level
+          name
+          position
+          product_count
+          uid
+          url_key
+          url_path
+          url_suffix
+          children {
+            include_in_menu
+            is_anchor
+            level
+            name
+            position
+            product_count
+            uid
+            url_key
+            url_path
+            url_suffix
+            children {
+              include_in_menu
+              is_anchor
+              level
+              name
+              position
+              product_count
+              uid
+              url_key
+              url_path
+              url_suffix
+              children {
+                include_in_menu
+                is_anchor
+                level
+                name
+                position
+                product_count
+                uid
+                url_key
+                url_path
+                url_suffix
+              }
+            }
+          }
+        }
+        product_count
+        name
+        uid
+      }
+      page_info {
+        current_page
+        page_size
+        total_pages
+      }
+      total_count
+    }
+  }
+`;

packages/api-client/src/api/categories/index.ts

@@ -0,0 +1,39 @@
+import { ApolloQueryResult } from "@apollo/client/core";
+import type { CustomHeaders, Query } from "@vue-storefront/magento-types";
+import { CustomQuery, QueryCategoriesArgs } from "@vue-storefront/magento-types";
+import gql from "graphql-tag";
+import categoriesQuery from "./categories";
+import { Context } from "../../types/context";
+import getHeaders from "../getHeaders";
+
+/**
+ * Fetches categories.
+ *
+ * @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
+ */
+export default async function categories(
+  context: Context,
+  params: QueryCategoriesArgs,
+  customQuery: CustomQuery = { categories: "categories" },
+  customHeaders: CustomHeaders = {}
+): Promise<ApolloQueryResult<Query["categories"]>> {
+  const { categories: categoriesGQL } = context.extendQuery(customQuery, {
+    categories: {
+      query: categoriesQuery,
+      variables: { ...params },
+    },
+  });
+
+  return context.client.query<Query["categories"], QueryCategoriesArgs>({
+    query: gql`
+      ${categoriesGQL.query}
+    `,
+    variables: categoriesGQL.variables,
+    context: {
+      headers: getHeaders(context, customHeaders),
+    },
+  });
+}

packages/api-client/src/api/categoryList/index.ts

@@ -8,6 +8,7 @@ import getHeaders from "../getHeaders";
 
 /**
  * Fetches the category list.
+ * @deprecated Use `categories` method instead
  *
  * @param context VSF Context
  * @param params

packages/api-client/src/api/index.ts

@@ -9,6 +9,7 @@ export { default as applyCouponToCart } from "./applyCouponToCart";
 export { default as availableStores } from "./availableStores";
 export { default as cart } from "./cart";
 export { default as cartTotalQty } from "./cartTotalQty";
+export { default as categories } from "./categories";
 export { default as categoryList } from "./categoryList";
 export { default as categorySearch } from "./categorySearch";
 export { default as changeCustomerPassword } from "./changeCustomerPassword";

packages/api-types/src/Api.ts

@@ -20,8 +20,10 @@ import {
   BundleProduct,
   CartItemInput,
   CartQuery,
+  CategoryFilterInput,
   CategoryListQuery,
   CategoryListQueryVariables,
+  CategoryResult,
   CategorySearchQuery,
   CategorySearchQueryVariables,
   ChangeCustomerPasswordMutation,
@@ -54,6 +56,7 @@ import {
   GuestAvailablePaymentMethodsQuery,
   GuestAvailableShippingMethodsQuery,
   InputMaybe,
+  Maybe,
   MergeCartsMutation,
   PlaceOrderInput,
   PlaceOrderMutation,
@@ -220,6 +223,12 @@ export interface MagentoApiMethods {
     customHeaders?: CustomHeaders
   ): Promise<ApolloQueryResult<CartQuery>>;
 
+  categories(
+    currentPage?: InputMaybe<Scalars['Int']>,
+    filters?: InputMaybe<CategoryFilterInput>,
+    pageSize?: InputMaybe<Scalars['Int']>,
+  ): Promise<ApolloQueryResult<Maybe<CategoryResult>>>;
+
   categoryList(
     categoryFilter?: CategoryListQueryVariables,
     customQuery?: CustomQuery,

packages/sdk/__tests__/integration/__config__/customQueries/categories/index.ts

@@ -0,0 +1,12 @@
+export const categories = ({ variables, metadata }: { variables: any; metadata: any }) => {
+  return {
+    variables,
+    query: `
+      query categories {
+        categories {
+          ${metadata.fields}
+        }
+      }
+    `,
+  };
+};

packages/sdk/__tests__/integration/__config__/customQueries/jest.customQueries.ts

@@ -24,6 +24,7 @@ import { applyCouponToCart } from './applyCouponToCart';
 import { removeCouponFromCart } from './removeCouponFromCart';
 import { productDetails } from './productDetails';
 import { categoryList } from './categoryList';
+import { categories } from './categories';
 import { categorySearch } from './categorySearch';
 import { productsList } from './products';
 import { relatedProducts } from './relatedProducts';
@@ -47,6 +48,7 @@ export const customQueries = {
   'remove-coupon-from-cart-custom-query': removeCouponFromCart,
   'product-details-custom-query': productDetails,
   'category-list-custom-query': categoryList,
+  'categories-custom-query': categories,
   'category-search-custom-query': categorySearch,
   'products-custom-query': productsList,
   'related-products-custom-query': relatedProducts,

packages/sdk/__tests__/integration/__nock-fixtures__/[SDK][Integration-Tests]-categories-should-return-customized-categories-result-using-custom-query

@@ -0,0 +1,49 @@
+[
+    {
+        "scope": "https://magento2-instance.vuestorefront.io:443",
+        "method": "GET",
+        "path": "/graphql?query=query+categories%7Bcategories%7Bitems%7Buid+name+__typename%7D__typename%7D%7D&operationName=categories&variables=%7B%7D",
+        "body": "",
+        "status": 200,
+        "response": [
+            "1f8b0800000000000003ab564a492c4954b2aa564a4e2c494dcf2fca4c2d06f1324b5273818ce86aa5d2cc14252b25df745b5b251da5bcc4dc5420cf25352db134a744c119a2a71228131f5f5259900a9587898714a5a62ad5c6e2900d4a2d061aa2545b5b0b004255adab86000000"
+        ],
+        "rawHeaders": [
+            "Server",
+            "nginx/1.14.2",
+            "Date",
+            "Wed, 10 Apr 2024 06:55:53 GMT",
+            "Content-Type",
+            "application/json",
+            "Content-Length",
+            "111",
+            "Connection",
+            "keep-alive",
+            "Vary",
+            "Accept-Encoding",
+            "Set-Cookie",
+            "PHPSESSID=f1p5dgdj3ibd0gt054onvms8si; expires=Wed, 10-Apr-2024 07:55:53 GMT; Max-Age=3600; path=/; domain=magento2-instance.vuestorefront.io; secure; HttpOnly; SameSite=Lax",
+            "X-Content-Type-Options",
+            "nosniff",
+            "X-XSS-Protection",
+            "1; mode=block",
+            "X-Frame-Options",
+            "SAMEORIGIN",
+            "Content-Encoding",
+            "gzip",
+            "X-Varnish",
+            "531710",
+            "Age",
+            "0",
+            "Pragma",
+            "no-cache",
+            "Expires",
+            "-1",
+            "Cache-Control",
+            "no-store, no-cache, must-revalidate, max-age=0",
+            "Accept-Ranges",
+            "bytes"
+        ],
+        "responseIsBinary": false
+    }
+]

packages/sdk/__tests__/integration/__nock-fixtures__/[SDK][Integration-Tests]-categories-should-return-filtered-list-of-categories

@@ -0,0 +1,49 @@
+[
+    {
+        "scope": "https://magento2-instance.vuestorefront.io:443",
+        "method": "GET",
+        "path": "/graphql?query=query+categories%28%24filters%3ACategoryFilterInput%24pageSize%3AInt%24currentPage%3AInt%29%7Bcategories%28filters%3A%24filters+pageSize%3A%24pageSize+currentPage%3A%24currentPage%29%7Bitems%7Bchildren%7Binclude_in_menu+is_anchor+level+name+position+product_count+uid+url_key+url_path+url_suffix+children%7Binclude_in_menu+is_anchor+level+name+position+product_count+uid+url_key+url_path+url_suffix+children%7Binclude_in_menu+is_anchor+level+name+position+product_count+uid+url_key+url_path+url_suffix+children%7Binclude_in_menu+is_anchor+level+name+position+product_count+uid+url_key+url_path+url_suffix+__typename%7D__typename%7D__typename%7D__typename%7Dproduct_count+name+uid+__typename%7Dpage_info%7Bcurrent_page+page_size+total_pages+__typename%7Dtotal_count+__typename%7D%7D&operationName=categories&variables=%7B%22pageSize%22%3A2%2C%22currentPage%22%3A1%2C%22filters%22%3A%7B%22category_uid%22%3A%7B%22in%22%3A%5B%22MjE%3D%22%2C%22MjM%3D%22%2C%22MjU%3D%22%5D%7D%7D%7D",
+        "body": "",
+        "status": 200,
+        "response": [
+            "1f8b0800000000000003bd544d4fc24010fd2b640f9e8a28e0a589178d899a90a8e0c108d96cda812e6c779bdd591149ffbbdb0f534b111b0edc98993733efbd2db325214346fc2d0918c242690e268b3842ec7ebcbb7cc445a841e6019781b021502e690cd212ffd223dc50268348e93c12f00182f8438f481603f1c9230b56808678245186235732c7255a8536401a282bd165fa1eb13c74f8d17274edc0560bba828d4b2c8b01ddb5722bcb4ac23072a53c35eda14acaf2b4b70f6dec7cce3f1dfe3cc258b8e42f4d338f508a9b044abab7850d9b890620a97794e47ba542e763e7ac335e03431371bd6340ffa001cf7503a2625c97c9b06baa812d0d69d37d6a832600753f0607fd78adfb81aebba5f806f4d44a6f34cbbe830993abbae26153f1b052fcb6a3386b6f2bb9813d5ef3ac41f2eaa27a44b7945494ef32ca87fdabefddf3e08d93513b09ff10658bec65e62a3f6656bb3d48b364716eb2aae15f90fff750211379d1e4716df218980ea2173056e093833c6433d39fa692ede00f3a451b49d3f41b0de0ef375a050000"
+        ],
+        "rawHeaders": [
+            "Server",
+            "nginx/1.14.2",
+            "Date",
+            "Tue, 09 Apr 2024 12:52:01 GMT",
+            "Content-Type",
+            "application/json",
+            "Content-Length",
+            "400",
+            "Connection",
+            "keep-alive",
+            "Vary",
+            "Accept-Encoding",
+            "Set-Cookie",
+            "PHPSESSID=g9dpg3ocsudug1stfg3e761f1v; expires=Tue, 09-Apr-2024 13:52:01 GMT; Max-Age=3600; path=/; domain=magento2-instance.vuestorefront.io; secure; HttpOnly; SameSite=Lax",
+            "X-Content-Type-Options",
+            "nosniff",
+            "X-XSS-Protection",
+            "1; mode=block",
+            "X-Frame-Options",
+            "SAMEORIGIN",
+            "Content-Encoding",
+            "gzip",
+            "X-Varnish",
+            "924050",
+            "Age",
+            "0",
+            "Pragma",
+            "no-cache",
+            "Expires",
+            "-1",
+            "Cache-Control",
+            "no-store, no-cache, must-revalidate, max-age=0",
+            "Accept-Ranges",
+            "bytes"
+        ],
+        "responseIsBinary": false
+    }
+]

packages/sdk/__tests__/integration/__nock-fixtures__/[SDK][Integration-Tests]-categories-should-return-list-of-all-categories

@@ -0,0 +1,49 @@
+[
+    {
+        "scope": "https://magento2-instance.vuestorefront.io:443",
+        "method": "GET",
+        "path": "/graphql?query=query+categories%28%24filters%3ACategoryFilterInput%24pageSize%3AInt%24currentPage%3AInt%29%7Bcategories%28filters%3A%24filters+pageSize%3A%24pageSize+currentPage%3A%24currentPage%29%7Bitems%7Bchildren%7Binclude_in_menu+is_anchor+level+name+position+product_count+uid+url_key+url_path+url_suffix+children%7Binclude_in_menu+is_anchor+level+name+position+product_count+uid+url_key+url_path+url_suffix+children%7Binclude_in_menu+is_anchor+level+name+position+product_count+uid+url_key+url_path+url_suffix+children%7Binclude_in_menu+is_anchor+level+name+position+product_count+uid+url_key+url_path+url_suffix+__typename%7D__typename%7D__typename%7D__typename%7Dproduct_count+name+uid+__typename%7Dpage_info%7Bcurrent_page+page_size+total_pages+__typename%7Dtotal_count+__typename%7D%7D&operationName=categories&variables=%7B%7D",
+        "body": "",
+        "status": 200,
+        "response": [
+            "1f8b0800000000000003d5585b6fda3018fd2bc80f7b82512edd3aa43e94addb9844d58e54d534a6c84d4ce212e22c76caba8aff3e278138710c8e1885f246be9bce39f9ec1cf10c6cc820e83d030b32e49010231a3f618666fcc74f1e77b16787c84f1eb06f79918d4cec9b33e447a0d7aa034c4de85b2e0993270f3d220ff4da75e0c319023d70477825a8838050cc30f1935c10123bb2986991c867a0f7fe5d1d44d8e6d5c3878b735e1c859e39454f3c305fb6c7910032570ad16832c17f78f0adcb661e0f6e07b793c13548400b685b25b4a72702ed65112de3dd8d7590c7cd527a47f0bb19fc6fd09a22a663d06a0b06c322838774402512e3a6aa7a13a75f75609aec29404bb81fd3a57b324284c0a2be15e5af84d87c6b6b6f6aa339828cba389404282f5c5e809ba2006e3aae017dbb41c5c08a8254e9deb7400642453d3a1bf5b895569a7757245f2add37d37e08e33d30a03f2d32ee96197705e31f12e3b8bd2ae552edf69c77a788b8cefa843132d31d8776eefe1d14c5b84f076c904355b1f37bed1afafa5bad235858451641dc5e95c3b8592edff7268f78467f8be5083b45c234e9afce5851ff528bfcbf729d284cc650b2188a1bee34d3ca903eda25890e6b2fba6702e940612f54709797d2e18d454b60bf511b8bcdf085a5383243218ea2715bcd50e884d0f7bd6e2361c89fd5d81de8484b457b6758c539e4285a2ae7a0e528551da56310f6c918aa1d835a8672f6305e21f7121d9557d0a25fb984d7ee117244a74a8f508169a9f298bcc1170443cd91ee88db7b7e5e14c949bb73f2e4223bb7077de86837373b79571712d6fbb45bc2cadfa588ef674705a1cf98f988d2dae5ef0807bc89e9d635fb6fe5ea466237494735506e5489eabaa27df3be83cc72b55fcb0f195947223bcffa4b148ba9173c89f2ab396b65f43ea1098c3c565bf580ecfca4443483a1138b3921c9ff8e51c8d132330ea6fb1e6729fecb9fda7c1b1861d04bb2344917468fb82296fb1d510ee69a970ce2a18b55d30af81a3c691b582c16ff00b674324406150000"
+        ],
+        "rawHeaders": [
+            "Server",
+            "nginx/1.14.2",
+            "Date",
+            "Tue, 09 Apr 2024 12:45:55 GMT",
+            "Content-Type",
+            "application/json",
+            "Content-Length",
+            "758",
+            "Connection",
+            "keep-alive",
+            "Vary",
+            "Accept-Encoding",
+            "Set-Cookie",
+            "PHPSESSID=8r1fmr0eekj2b8sjf2425lfvmf; expires=Tue, 09-Apr-2024 13:45:55 GMT; Max-Age=3600; path=/; domain=magento2-instance.vuestorefront.io; secure; HttpOnly; SameSite=Lax",
+            "X-Content-Type-Options",
+            "nosniff",
+            "X-XSS-Protection",
+            "1; mode=block",
+            "X-Frame-Options",
+            "SAMEORIGIN",
+            "Content-Encoding",
+            "gzip",
+            "X-Varnish",
+            "759652",
+            "Age",
+            "0",
+            "Pragma",
+            "no-cache",
+            "Expires",
+            "-1",
+            "Cache-Control",
+            "no-store, no-cache, must-revalidate, max-age=0",
+            "Accept-Ranges",
+            "bytes"
+        ],
+        "responseIsBinary": false
+    }
+]