@graphcommerce/docs 4.12.0-canary.0 → 4.12.0-canary.2

package/CHANGELOG.md

@@ -1,5 +1,31 @@
 # Change Log
 
+## 4.12.0-canary.2
+
+### Patch Changes
+
+- [#1733](https://github.com/graphcommerce-org/graphcommerce/pull/1733) [`b2d73c726`](https://github.com/graphcommerce-org/graphcommerce/commit/b2d73c726fa123435fa6c54b4e0fd0db2df7c4ab) - Move to <Prev/> instead of <Component/> to call the plugin component ([@paales](https://github.com/paales))
+
+## 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

package/framework/plugins.md

@@ -69,17 +69,16 @@ import { purchaseorder } from '../PurchaseOrder'
 export const component = 'PaymentMethodContextProvider'
 
 // Exported location of the component that you are extending, required
-export const exported =
-  '@graphcommerce/magento-cart-payment-method/PaymentMethodContext/PaymentMethodContext'
+export const exported = '@graphcommerce/magento-cart-payment-method'
 
 function AddPaymentMethodEnhancer(
   props: PluginProps<PaymentMethodContextProviderProps>,
 ) {
-  const { Component, modules, ...rest } = props
-  return <Component {...rest} modules={{ ...modules, purchaseorder }} />
+  const { Prev, modules, ...rest } = props
+  return <Prev {...rest} modules={{ ...modules, purchaseorder }} />
 }
 
-/** The export must be named `Plugin` and must accept a Component to render */
+/** The export must be named `Plugin` and must accept a Prev component to render */
 export const Plugin = AddIncludedMethods
 ```
 
@@ -98,37 +97,59 @@ export const Plugin = AddIncludedMethods
 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'
+/* This file is automatically generated for @graphcommerce/magento-cart-payment-method */
 
-type PaymentMethodContextProviderBaseProps = React.ComponentProps<
+export * from '.'
+import { Plugin as GaPaymentMethodButton } from '@graphcommerce/googleanalytics/plugins/GaPaymentMethodButton'
+import { Plugin as GaPaymentMethodContextProvider } from '@graphcommerce/googleanalytics/plugins/GaPaymentMethodContextProvider'
+import { Plugin as AddIncludedMethods } from '@graphcommerce/magento-payment-included/plugins/AddIncludedMethods'
+import { ComponentProps } from 'react'
+import {
+  PaymentMethodButton as PaymentMethodButtonBase,
+  PaymentMethodContextProvider as PaymentMethodContextProviderBase,
+} from '.'
+
+/**
+ * Interceptor for `<PaymentMethodButton/>` with these plugins:
+ *
+ * - `@graphcommerce/googleanalytics/plugins/GaPaymentMethodButton`
+ */
+type PaymentMethodButtonProps = ComponentProps<typeof PaymentMethodButtonBase>
+
+function GaPaymentMethodButtonInterceptor(props: PaymentMethodButtonProps) {
+  return <GaPaymentMethodButton {...props} Prev={PaymentMethodButtonBase} />
+}
+export const PaymentMethodButton = GaPaymentMethodButtonInterceptor
+
+/**
+ * Interceptor for `<PaymentMethodContextProvider/>` with these plugins:
+ *
+ * - `@graphcommerce/magento-payment-included/plugins/AddIncludedMethods`
+ * - `@graphcommerce/googleanalytics/plugins/GaPaymentMethodContextProvider`
+ */
+type PaymentMethodContextProviderProps = 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
+function AddIncludedMethodsInterceptor(
+  props: PaymentMethodContextProviderProps,
+) {
+  return (
+    <AddIncludedMethods {...props} Prev={PaymentMethodContextProviderBase} />
+  )
+}
+function GaPaymentMethodContextProviderInterceptor(
+  props: PaymentMethodContextProviderProps,
+) {
+  return (
+    <GaPaymentMethodContextProvider
+      {...props}
+      Prev={AddIncludedMethodsInterceptor}
+    />
+  )
+}
+export const PaymentMethodContextProvider =
+  GaPaymentMethodContextProviderInterceptor
 ```
 
 React profile will show that all components are nested:
@@ -170,3 +191,6 @@ 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.12.0-canary.0",
+  "version": "4.12.0-canary.2",
   "sideEffects": true,
   "devDependencies": {
     "@graphcommerce/prettier-config-pwa": "^4.0.7"