@graphcommerce/docs 4.11.1 → 4.12.0-canary.1

package/CHANGELOG.md

@@ -1,5 +1,31 @@
 # Change Log
 
+## 4.12.0-canary.1
+
+### Minor Changes
+
+- [#1729](https://github.com/graphcommerce-org/graphcommerce/pull/1729) [`c37187a51`](https://github.com/graphcommerce-org/graphcommerce/commit/c37187a513670ebcf09e99eb4a762c8bdb5df7e4) - Moved Magento Cart Pickup shipping method to the [GraphCommerce plugin system](https://www.graphcommerce.org/docs/framework/plugins)
+
+  Upgrade guide:
+
+  - The upgrade removes `@graphcommerce/magento-cart-pickup` package from your `package.json`, remove them for now.
+  - Proceed to upgrade normally
+  - Add back `@graphcommerce/magento-cart-pickup`, following the [GraphCommerce Magento docs](https://graphcommerce.org/docs/magento). ([@paales](https://github.com/paales))
+
+- [#1729](https://github.com/graphcommerce-org/graphcommerce/pull/1729) [`2e68e0560`](https://github.com/graphcommerce-org/graphcommerce/commit/2e68e0560690bbf9bad6dc2b33d6e2ddb16197ce) - Adyen Payment gateway support ([@paales](https://github.com/paales))
+
+- [#1729](https://github.com/graphcommerce-org/graphcommerce/pull/1729) [`366b05a7d`](https://github.com/graphcommerce-org/graphcommerce/commit/366b05a7da174a8a7c665b44e11422d8c873e4ed) - MultiSafePay Payment gateway support ([@paales](https://github.com/paales))
+
+### Patch Changes
+
+- [#1729](https://github.com/graphcommerce-org/graphcommerce/pull/1729) [`78980b009`](https://github.com/graphcommerce-org/graphcommerce/commit/78980b009a3055006a50e0f54a4414ccf5570860) - Loosen node version constraint ([@paales](https://github.com/paales))
+
+## 4.12.0-canary.0
+
+### Minor Changes
+
+- [#1718](https://github.com/graphcommerce-org/graphcommerce/pull/1718) [`16abc9995`](https://github.com/graphcommerce-org/graphcommerce/commit/16abc9995377f5c00032674de0a1ea3ebad88c4c) - Introducing a new **Plugin system for GraphCommerce** which allows you to extend GraphCommerce in a plug-and-play manner. [Read the documentation to learn more](https://github.com/graphcommerce-org/graphcommerce/blob/main/docs/framework/plugins.md) ([@paales](https://github.com/paales))
+
 ## 4.11.1
 
 ### Patch Changes

package/framework/plugins.md

@@ -0,0 +1,174 @@
+# Plugins
+
+GraphCommerce plugin system allows you to extend GraphCommerce in a
+plug-and-play manner. Install a new package and the code will be added at the
+right places.
+
+- Plug-and-play: It is be possible to install packages after which they
+  immediately work.
+- No runtime overhead: The plugin system is fully implemented in webpack and
+- Easy plugin creation: Configuration should happen in the plugin file, not a
+  separate configuration file.
+
+## What problem are we solving?
+
+Without plugins the only way to add new functionality is by modifying the code
+of your project at multiple places. We often pass props to components to
+customize them, but sometimes we also place hooks at multiple places.
+
+For example, to add a new payment method it was necessary to modify the props of
+`<PaymentMethodContextProvider methods={[...braintree]}>`
+
+This causes problems:
+
+- Upgrades: If GraphCommerce changes something somewhere in the code where you
+  have already modified the code, you get an upgrade conflict which you have to
+  manually resolve. By using plugins you can avoid this.
+- New packages: When you install a complex new package, it can happen that you
+  have to modify the code of your project at multiple places. This is not
+  necessary with plugins.
+
+## What is a plugin?
+
+A plugin is a way to modify React Components by wrapping them, without having to
+modify the code in `examples/magento-graphcms` or `your-project`.
+
+For the M2 people: Think of around plugins, but without configuration files and
+no performance penalty.
+
+In the [PR](https://github.com/graphcommerce-org/graphcommerce/pull/1718) I have
+made the
+[`<PaymentMethodContextProvider />`](https://github.com/graphcommerce-org/graphcommerce/pull/1718/files#diff-d5b4da6c34d4b40dc8ac5d1c5967bc6f5aaa70d0d5ac79552f3a980b17a88ea9R115)
+work with plugins.
+
+The actual plugins are:
+
+- [AddBraintreeMethods](https://github.com/graphcommerce-org/graphcommerce/pull/1718/files#diff-14391e8c8f598e720b3e99ece1248987d68eb6133d354a3a55ef82331905be5b)
+- [AddIncludedMethods](https://github.com/graphcommerce-org/graphcommerce/pull/1718/files#diff-c3d57b802463ed40925b558049a56992202be975f3c86982e6a753e2830bdb9f)
+- [AddPaypalMethods](https://github.com/graphcommerce-org/graphcommerce/pull/1718/files#diff-934d7a9d597b01b6da875f61ca1cdfd57e0e0817e7126ce6216fd82dc4b6f899)
+- [AddMollieMethods](https://github.com/graphcommerce-org/graphcommerce/pull/1718/files#diff-76e6fc63dee67f55cbad4f13dc7b1b764da6235b88ed8d987c7044b7ef7fc942)
+
+The result of this is that:
+
+- The payment methods are added to the `<PaymentMethodContextProvider />` via
+  plugins.
+- These plugins are only applied if the relevant package is installed.
+
+### How do I make a plugin?
+
+In the root of my project, i've created a plugin
+`examples/magento-graphcms/plugins/AddPaymentMethodEnhancer.tsx` that adds
+purchaseorder to `<PaymentMethodContextProvider/>`
+
+```tsx
+import type { PaymentMethodContextProviderProps } from '@graphcommerce/magento-cart-payment-method'
+import type { PluginProps } from '@graphcommerce/next-config'
+import { purchaseorder } from '../PurchaseOrder'
+
+// Component to extend, required
+export const component = 'PaymentMethodContextProvider'
+
+// Exported location of the component that you are extending, required
+export const exported = '@graphcommerce/magento-cart-payment-method'
+
+function AddPaymentMethodEnhancer(
+  props: PluginProps<PaymentMethodContextProviderProps>,
+) {
+  const { Component, modules, ...rest } = props
+  return <Component {...rest} modules={{ ...modules, purchaseorder }} />
+}
+
+/** The export must be named `Plugin` and must accept a Component to render */
+export const Plugin = AddIncludedMethods
+```
+
+### How does it work?
+
+1. It generates a list of all packages with `graphcommerce` in the package
+   `name` (All `@graphcommerce/*` packages and
+   `@my-company/graphcommerce-plugin-name`).
+2. It does a glob search for plugins in the plugins folders for each package:
+   `${packageLocation}/plugins/**/*.tsx`.
+3. Statically Analyse the plugins, check if the `component` and `exported`
+   exports exist and generate the plugin configuration.
+4. Generate `PaymentMethodContext.interceptor.tsx` and place it next to the
+   existing component
+
+Example of generated interceptor with additional comments:
+
+```tsx
+// All plugins are imported, which will be used to enhance the original component.
+import { Plugin as AddIncludedMethods } from '@graphcommerce/magento-payment-included/plugins/AddIncludedMethods'
+import { Plugin as AddPaypalMethods } from '@graphcommerce/magento-payment-paypal/plugins/AddPaypalMethods'
+
+// This file is placed next to the original component, so it is imported with a relative path, in the Webpack plugin we
+// load the original file if it is loaded from the interceptor.
+import { PaymentMethodContextProvider as PaymentMethodContextProviderBase } from './PaymentMethodContext'
+
+// All original exports are exported, if the original file exports more than we're intercepting, it will still work.
+export * from './PaymentMethodContext'
+
+type PaymentMethodContextProviderBaseProps = React.ComponentProps<
+  typeof PaymentMethodContextProviderBase
+>
+
+// We create new Interceptor components here, which allows us to wrap multiple plugins around the original component.
+const AddIncludedMethodsInterceptor = (
+  props: PaymentMethodContextProviderBaseProps,
+) => (
+  //For the first plugin we use the original component.
+  <AddIncludedMethods {...props} Component={PaymentMethodContextProviderBase} />
+)
+const AddPaypalMethodsInterceptor = (
+  props: PaymentMethodContextProviderBaseProps,
+) => (
+  // For the next components we use the previous Interceptor component.
+  <AddPaypalMethods {...props} Component={AddIncludedMethodsInterceptor} />
+)
+
+// Finally we return the resulting interceptor component.
+export const PaymentMethodContextProvider = AddPaypalMethodsInterceptor
+```
+
+React profile will show that all components are nested:
+
+![](https://user-images.githubusercontent.com/1244416/197813853-e8aa329e-41bc-4f56-8aac-2464cc37032f.png)
+
+### Possible use cases
+
+In the examples above we've extended the payment methods, but it should also
+work for other things such as:
+
+- Googletagmanager
+- Googleanalytics
+- Google recaptcha
+- Compare functionality?
+- Wishlist functionality?
+- Abstraction between GraphCommerce and Backends? (Magento, BigCommerce,
+  CommerceTools, etc.)
+
+### Limitations
+
+Work is planned to lift these limitations, but for now:
+
+React Refresh doesn't work correctly with Plugins, it will force a page reload
+on each file change and will throw an error in the console. To solve this issue,
+move your actual plugin outside of the plugin file and only have the plugin be a
+configuration file.
+
+It currently isn't possible to provide a plugin sort order. The project root is
+intercepting last, followed by the packages in reverse alphabetical order,
+followed by dependencies' dependencies. We don't generate a proper graph at the
+moment to figure out the actual dependencies but is an artifact of how we
+resolve the dependencies.
+
+There currently isn't a way for the plugin to determine if the plugin should be
+activated at all. For example, the code for Google Analytics should only be
+added if the user has configured it. This is currently not possible. Of if a
+user wants to disable a plugin, this is currently not possible.
+
+It is currently is only possible to extend React Components. This however sets
+the foundation to allow for a more flexible plugin system in the future.
+
+Plugins should be optional for GraphCommerce to function properly. Plugins for
+mandatory packages shouldn't exist.

package/getting-started/create.md

@@ -47,9 +47,9 @@ If you want to test a GraphCommerce storefront using a pre-configured Magento
 demo store and a pre-configured GraphCMS project with demo content, then you
 need to only install the dependencies. This is the quickest approach.
 
-- Install and use node 14/16: `nvm install 16` or `nvm use 16`
-- Install yarn: `corepack enable` (for node 16) or `npm install --global yarn`
-  (for node 14)
+- Install and use node 14/16/18: `nvm install 16` or `nvm use 16`
+- Install yarn: `corepack enable` (for node 16/18) or
+  `npm install --global yarn` (for node 14)
 
 ## Step 1: Create a new GraphCommerce app
 
@@ -135,16 +135,6 @@ List of routes and store_codes:
 > }
 > ```
 
-### Remove unused PSP's
-
-The example has Payment Service Providers integrated (Mollie, Braintree). Remove
-the ones your Magento backend doesn't support.
-
-- Remove Payment Service integrations from package.json:
-  `@graphcommerce/mollie-magento-payment` and/or
-  `@graphcommerce/magento-payment-braintree`
-- Remove Payment Service references from `pages/checkout/payment.tsx`
-
 ## Step 3: Start the development environment
 
 - `yarn` Install the dependencies
@@ -166,3 +156,4 @@ Visit the GraphQL Playground running at http://localhost:3000/api/graphql
 - [Start building a GraphCommerce custom storefront](../getting-started/start-building.md)
   by customizing text and component styles, fetching data from server
   components, and making changes to GraphQL queries.
+- [Install optional Magento packages](../magento/readme.md)

package/magento/implementing-payment-gateways.md

@@ -0,0 +1,168 @@
+# Magento payment gateway requirements
+
+Payment gateways are the most important part of any e-commerce store. In this
+section, we will discuss the requirements for implementing a payment gateway in
+Magento 2 that is compatible with GraphCommerce.
+
+There are multiple flows to handle payments.
+
+## Flow 1: Redirecting payment gateway
+
+The first step is to call setPaymentMethodOnCart and placeOrder.
+
+```ts
+const variables = {
+  cartId: 'currentCartId',
+  paymentMethod: {
+    code: 'my_payment_method',
+    my_gateway: {
+      return_url: 'https://my-site.com/checkout/billing?token=$TOKEN',
+      custom_field: 'blabla',
+    },
+  },
+}
+```
+
+```graphql
+mutation MyGatewayPaymentOptionsAndPlaceOrder(
+  $cartId: String!
+  $paymentMethod: PaymentMethodInput!
+) {
+  setPaymentMethodOnCart(
+    input: { cart_id: $cartId, payment_method: $paymentMethod }
+  ) {
+    cart {
+      selected_payment_method {
+        ...SelectedPaymentMethod
+      }
+    }
+  }
+  placeOrder(input: { cart_id: $cartId }) {
+    order {
+      order_number
+      my_gateway_status {
+        token
+        status # Will probably be REDIRECT_SHOPPER
+        redirect_url
+      }
+    }
+  }
+}
+```
+
+When the query succeeds the GraphCommerce payment module will redirect to the
+payment_url. The customer handles it's payment on the payment gateway's website.
+One of the following things can happen:
+
+- Result 1: The customer has successfully paid and the customer is redirected
+  back to the `return_url` with the $TOKEN injected.
+- Result 2: The customer has failed their pauyment and the customer is
+  redirected back to the `return_url` with the $TOKEN injected.
+- Result 3: The customer presses back in their browser and we still get the
+  token from the `placeOrder` mutation.
+
+GraphCommerce now needs to check if the payment has indeed succeeded by calling
+the payment gateway's custom endpoint:
+
+```graphql
+mutation MyGatewayProcessPayment($cartId: String!, $token: String!) {
+  myGatewayPaymentStatus(input: { cartId: $cartId, token: $string }) {
+    status
+    error_message
+    cart {
+      # it will optionally return the cart if it hasn't succeeded yet and is recovered.
+      id
+    }
+  }
+}
+```
+
+After that GraphCommerce van either:
+
+- Redirect to the success page
+- Restore the cart, show the error message and let the customer checkout again.
+
+### The GraphQL Schema for the above example looks something like this:
+
+```graphql
+input PaymentMethodInput {
+  my_gateway: MyGatewayPaymentInput
+}
+
+input MyGatewayPaymentInput {
+  """
+  The URL to redirect the customer to after the payment has been processed.
+
+  This will should be a fully qualified URL: `https://mydomain.com/checkout/payment?token=$TOKEN`
+  $TOKEN will be repaced with the payment gateway token.
+
+  This information should be stored in the database (encryped if required)
+  """
+  return_url: String!
+  """
+  Payment gateway can accept any custom field, for example an issuer or any additional information that can be configured in the checkout.
+
+  This information should be stored in the database (encryped if required)
+  """
+  custom_field: String
+}
+
+type Order {
+  my_gateway_status: MyGatewayStatus
+}
+
+type Mutation {
+  myGatewayPaymentStatus: MyGatewayStatus
+}
+
+type MyGatewayStatus {
+  """
+  Returns the secret token that is used to check the payment status and is understood by the external payment gateway.
+  """
+  token: String!
+  """
+  Status of the current payment.
+  """
+  status: MyGatewayStatusEnum!
+  """
+  Returned when status ERROR and there is a message to show to the customer from the gateway
+  """
+  error_message: String
+  """
+  Returned when the status is REDIRECT_SHOPPER
+  """
+  redirect_url: String
+  """
+  Retuned when when the cart has been restored on status CANCELLED, ERROR, REFUSED
+  """
+  cart: Cart
+}
+
+"""
+StatusEnum of the payment gateway.
+Should probably look something like the following but can be extended / reduced according payment gateway's requirements.
+"""
+enum MyGatewayStatusEnum {
+  """
+  Will be returned when the order is placed.
+  """
+  REDIRECT_SHOPPER
+  """
+  Will be returned when the customer has cancelled the payment on the external site.
+  Will be returned if the customer has pressed back in their browser.
+  """
+  CANCELLED
+  """
+  Will be returned if the payment hasn't succeeded, to be used in tandem with error_message
+  """
+  ERROR
+  """
+  Will be returned if the payment was rejected by the payment gateway.
+  """
+  REFUSED
+  """
+  Payment has succeeded
+  """
+  SUCCESS
+}
+```

package/magento/readme.md

@@ -0,0 +1,17 @@
+# Magento
+
+To integrate with Magento, most of the functionality should work out-of-the box
+if Magento exposes a working GraphQL API.
+
+## Optional packages
+
+- [Store Pickup / MSI](https://github.com/graphcommerce-org/graphcommerce/tree/main/packages/magento-cart-pickup)
+
+## Payment gateways
+
+- [PayPal](https://github.com/graphcommerce-org/graphcommerce/tree/main/packages/magento-payment-paypal)
+- [Mollie](https://github.com/graphcommerce-org/graphcommerce/tree/main/packages/mollie-magento-payment)
+- [Braintree](https://github.com/graphcommerce-org/graphcommerce/tree/main/packages/magento-payment-braintree)
+- [Adyen](https://github.com/graphcommerce-org/graphcommerce/tree/main/packages/magento-payment-adyen)
+- [MultiSafePay](https://github.com/graphcommerce-org/graphcommerce/tree/main/packages/magento-payment-multisafepay)
+- [Klarna](https://github.com/graphcommerce-org/graphcommerce/tree/main/packages/magento-payment-klarna)

package/package.json

@@ -2,7 +2,7 @@
   "name": "@graphcommerce/docs",
   "homepage": "https://www.graphcommerce.org/docs",
   "repository": "github:graphcommerce-org/graphcommerce/docs",
-  "version": "4.11.1",
+  "version": "4.12.0-canary.1",
   "sideEffects": true,
   "devDependencies": {
     "@graphcommerce/prettier-config-pwa": "^4.0.7"