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

package/CHANGELOG.md

@@ -1,5 +1,25 @@
 # 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

package/framework/plugins.md

@@ -69,8 +69,7 @@ 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>,
@@ -170,3 +169,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.1",
   "sideEffects": true,
   "devDependencies": {
     "@graphcommerce/prettier-config-pwa": "^4.0.7"