feat: add categories method (#1514)

* feat: add categories method

* chore: add changeset

* feat: add CR fixes

.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
+ }
+]