@graphcommerce/algolia-search 6.2.0-canary.91 → 6.2.0-canary.92

package/CHANGELOG.md

@@ -1,5 +1,11 @@
 # @graphcommerce/algolia-search
 
+## 6.2.0-canary.92
+
+### Patch Changes
+
+- [#2026](https://github.com/graphcommerce-org/graphcommerce/pull/2026) [`c1b76eb4d`](https://github.com/graphcommerce-org/graphcommerce/commit/c1b76eb4d70cf5cef9f768bb1f4986e639b31932) - Improved documentation @graphcommerce/algolia-search ([@mikekeehnen](https://github.com/mikekeehnen))
+
 ## 6.2.0-canary.91
 
 ## 6.2.0-canary.90

package/Config.graphqls

@@ -69,4 +69,14 @@ extend input GraphCommerceConfig {
   Configures algolia search debounce time. This will slow down the search response.
   """
   algoliaSearchDebounceTime: Int
+
+  """
+  Configure your Algolia HyGraph index. This will create a new index for HyGraph data if it doesn't exist in Algolia.
+  """
+  algoliaHygraphIndex: String
+
+  """
+  Configure your Algolia HyGraph secret. This will be used to authenticate the HyGraph data.
+  """
+  hygraphSecret: String
 }

package/README.md

@@ -26,9 +26,77 @@ Storefront configuration values:
   - filterAttributes (containing a list of the following values)
     - aggregation
     - toAlgoliaAttribute
+- sortOptions
+  - label
+  - value
+
+## When to use filterAttributes?
+
+The filterAttributes configuration is used to map the filter attributes from the
+Magento 2 API to Algolia API. This is needed because some of the attributes in
+Algolia don't match with the indexed attributes in Algolia. We currently support
+some default attributes that are Magento 2 native, which means you don't have to
+add them to the filterAttributes configuration. These attributes are:
+
+- price
+- category_uid
+
+If you want to map other attributes, you can add them to the filterAttributes
+configuration. For example, if you want to map the `color` attribute, you can
+add the following configuration:
+
+```
+filterAttributes: [
+  {
+    aggregation: 'color',
+    toAlgoliaAttribute: 'color',
+  },
+]
+```
+
+Filling in the aggregation (Magento 2) enables this plugin to read the
+aggregation properties, such as the label and the options. The
+toAlgoliaAttribute (Algolia) is the attribute that is used in the Algolia index
+and connects the correct values to the aggregation.
+
+## When to use sortOptions?
+
+You can use the sortOptions to define new sorting options inside the Algolia
+plugin. The label is the name of the sorting option that is shown in the UI. The
+value is the value that is used to find the sort index in the Algolia API. For
+example, if you want to add a new sorting option called `Newest`, you can add
+the following configuration:
+
+```
+sortOptions: [
+  {
+    label: 'Newest',
+    value: 'newest-product-index',
+  },
+]
+```
+
+## What is the recommended algoliaSearchDebounceTime?
+
+We've added a debounce time to the search feature to prevent it from being
+called too frequently. This means that the search function will wait for a
+specified amount of time before executing, which reduces the number of queries
+sent to the Algolia API and can reduce cost. The default debounce time is 0
+milliseconds for optimal responsiveness, but you can adjust it by adding the
+`algoliaSearchDebounceTime` parameter to your Graphcommerce configuration as
+following:
+
+```
+algoliaSearchDebounceTime: 500
+
+```
 
 ## Add server side hydration to Algolia Search
 
+**_NOTE:_** Server side hydration is currently not supported due to the current
+requirement of `useRouter` inside this plugin. We are working on a solution to
+this problem.
+
 1. Add `react-instantsearch-hooks-server` package to your project
 
 ```
@@ -56,12 +124,15 @@ type SearchResultProps = DefaultPageQuery &
 ```
 
 3. Add the `getServerState` method from the `react-instantsearch-hooks-server`
-   package to the imports of your search page
+   package and the `renderToString` method from the `react-dom/server` package
+   to the imports of your search page.
 
 ```
 ...
 import { getServerState } from 'react-instantsearch-hooks-server'
+import {renderToString } from 'react-dom/server'
 ...
+
 ```
 
 4. Assign the result of the `getServerState` method to the `serverState`
@@ -109,3 +180,66 @@ return {
 
 +     <SearchContext serverProps={serverState}>
 ```
+
+## Add Algolia indexing to Magento 2
+
+1. Follow the algolia docs to enable the Algolia integration in Magento 2
+   [here](https://www.algolia.com/doc/integration/magento-2/getting-started/quick-start/?client=php).
+
+## Add Algolia indexing to HyGraph
+
+1. Add the `algoliasearch` package to your project
+
+```
+yarn add algoliasearch
+```
+
+2. Add the `@hygraph/utils` package to your project
+
+```
+yarn add @hygraph/utils
+```
+
+3. Create two new api routes in your project, one for adding an entry and one
+   for removing an entry from the Algolia index.
+
+```
+- pages
+  - api
+    - algolia
+      - add.ts
+      - remove.ts
+```
+
+**_NOTE:_** Both the `add.ts` and `remove.ts` files are implemented with
+signature verification. This is to prevent unwanted requests to your api routes.
+You can read more about signature verification for webhooks
+[here](https://hygraph.com/blog/introducing-signed-webhooks).
+
+4. The following code is an example of how the `add.ts` file could look like.
+   This file is responsible for adding an entry to the Algolia index.
+
+```ts
+import { addHygraphRecord } from '@graphcommerce/algolia-search'
+import { NextApiRequest, NextApiResponse } from 'next'
+
+export default (req: NextApiRequest, res: NextApiResponse) =>
+  addHygraphRecord(req, res)
+```
+
+5. The following code is an example of how the `remove.ts` file could look like.
+   This file is responsible for removing an entry from the Algolia index.
+
+```ts
+import { removeHygraphRecord } from '@graphcommerce/algolia-search'
+import { NextApiRequest, NextApiResponse } from 'next'
+
+export default (req: NextApiRequest, res: NextApiResponse) =>
+  await removeHygraphRecord(req, res)
+```
+
+6. Follow the webhook setup guide to add the webhooks to your HyGraph project.
+
+You can follow
+[these](https://hygraph.com/docs/guides/webhooks/webhooks-overview#configure-webhooks)
+instructions to configure the webhooks in your HyGraph project.

package/api/add-hygraph-record.ts

@@ -0,0 +1,60 @@
+import { Page } from '@graphcommerce/graphql-mesh'
+import { verifyWebhookSignature } from '@hygraph/utils'
+import algoliasearch from 'algoliasearch'
+import { NextApiRequest, NextApiResponse } from 'next'
+
+type AlgoliaResult = {
+  objectID: string
+  slug: string
+  name: string
+  content: string
+  url: string
+  algoliaLastUpdateAtCET: string
+}
+
+const algolia = algoliasearch(
+  import.meta.graphCommerce.algoliaApplicationId,
+  import.meta.graphCommerce.algoliaSearchOnlyApiKey,
+)
+
+const indexName = import.meta.graphCommerce.algoliaHygraphIndex
+const index = typeof indexName === 'string' ? algolia.initIndex(indexName) : undefined
+
+export function addHygraphRecord(req: NextApiRequest, res: NextApiResponse) {
+  if (req.method !== 'POST') res.end()
+
+  const { body } = req
+  const gcms = req.headers['gcms-signature']
+  const signature = Array.isArray(gcms) ? gcms[0] : gcms
+  const secret = import.meta.graphCommerce.hygraphSecret
+
+  if (!index) return res.status(400).send('Missing "algoliaHygraphIndex" config variable')
+  if (!secret) return res.status(400).send('Missing "hygraphSecret" config variable')
+  if (!signature) return res.status(400).send('Missing gcms-signature header')
+
+  if (!verifyWebhookSignature({ body, signature, secret })) res.status(401).end()
+
+  try {
+    const { data } = body
+
+    const { id: objectID, localizations } = data
+
+    const objects = localizations.map((localization: Page & { updatedAt: string }) => {
+      const url = `${import.meta.graphCommerce.canonicalBaseUrl}/${localization?.url}`
+      const algoliaObject: AlgoliaResult = {
+        name: localization?.title ?? '',
+        content: localization?.metaDescription,
+        url,
+        slug: localization?.url,
+        algoliaLastUpdateAtCET: localization?.updatedAt,
+        objectID,
+      }
+
+      return index.saveObject(algoliaObject)
+    })
+
+    return res.status(201).send(objects)
+  } catch (err) {
+    return res.status(400).send(err)
+  }
+}

package/api/remove-hygraph-record.ts

@@ -0,0 +1,36 @@
+import { verifyWebhookSignature } from '@hygraph/utils'
+import algoliasearch from 'algoliasearch'
+import { NextApiRequest, NextApiResponse } from 'next'
+
+const algolia = algoliasearch(
+  import.meta.graphCommerce.algoliaApplicationId,
+  import.meta.graphCommerce.algoliaSearchOnlyApiKey,
+)
+
+const indexName = import.meta.graphCommerce.algoliaHygraphIndex
+const index = indexName ? algolia.initIndex(indexName) : undefined
+
+export async function removeHygraphRecord(req: NextApiRequest, res: NextApiResponse) {
+  if (req.method !== 'DELETE') return res.end()
+
+  const { body } = req
+  const gcms = req.headers['gcms-signature']
+  const signature = Array.isArray(gcms) ? gcms[0] : gcms
+  const secret = import.meta.graphCommerce.hygraphSecret
+
+  if (!index) return res.status(400).send('Missing "algoliaHygraphIndex" config variable')
+  if (!secret) return res.status(400).send('Missing "hygraphSecret" config variable')
+  if (!signature) return res.status(400).send('Missing gcms-signature header')
+
+  if (!verifyWebhookSignature({ body, signature, secret })) res.status(401).end()
+
+  try {
+    const { id: objectID, ...rest } = body
+
+    await index.deleteObject(objectID as string)
+
+    return res.status(201).send(rest)
+  } catch (err) {
+    return res.status(400).send(err)
+  }
+}

package/index.ts

@@ -0,0 +1,2 @@
+export * from './api/add-hygraph-record'
+export * from './api/remove-hygraph-record'

package/package.json

@@ -2,7 +2,7 @@
   "name": "@graphcommerce/algolia-search",
   "homepage": "https://www.graphcommerce.org/",
   "repository": "github:graphcommerce-org/graphcommerce",
-  "version": "6.2.0-canary.91",
+  "version": "6.2.0-canary.92",
   "sideEffects": false,
   "prettier": "@graphcommerce/prettier-config-pwa",
   "eslintConfig": {
@@ -12,20 +12,20 @@
     }
   },
   "devDependencies": {
-    "@graphcommerce/eslint-config-pwa": "6.2.0-canary.91",
-    "@graphcommerce/next-config": "^6.2.0-canary.91",
-    "@graphcommerce/prettier-config-pwa": "6.2.0-canary.91",
-    "@graphcommerce/typescript-config-pwa": "6.2.0-canary.91"
+    "@graphcommerce/eslint-config-pwa": "6.2.0-canary.92",
+    "@graphcommerce/next-config": "^6.2.0-canary.92",
+    "@graphcommerce/prettier-config-pwa": "6.2.0-canary.92",
+    "@graphcommerce/typescript-config-pwa": "6.2.0-canary.92"
   },
   "dependencies": {
-    "@graphcommerce/graphql": "6.2.0-canary.91",
-    "@graphcommerce/ecommerce-ui": "6.2.0-canary.91",
-    "@graphcommerce/magento-search": "6.2.0-canary.91",
-    "@graphcommerce/next-config": "^6.2.0-canary.91",
-    "@graphcommerce/next-ui": "6.2.0-canary.91",
-    "@graphcommerce/magento-product": "6.2.0-canary.91",
-    "@graphcommerce/graphql-mesh": "6.2.0-canary.91",
-    "@graphcommerce/magento-store": "6.2.0-canary.91",
+    "@graphcommerce/graphql": "6.2.0-canary.92",
+    "@graphcommerce/ecommerce-ui": "6.2.0-canary.92",
+    "@graphcommerce/magento-search": "6.2.0-canary.92",
+    "@graphcommerce/next-config": "^6.2.0-canary.92",
+    "@graphcommerce/next-ui": "6.2.0-canary.92",
+    "@graphcommerce/magento-product": "6.2.0-canary.92",
+    "@graphcommerce/graphql-mesh": "6.2.0-canary.92",
+    "@graphcommerce/magento-store": "6.2.0-canary.92",
     "algoliasearch": "^4.15.0",
     "react-instantsearch-hooks-web": "^6.41.0"
   },
@@ -38,4 +38,4 @@
     "react": "^18.2.0",
     "react-dom": "^18.2.0"
   }
-}
+}