From 57f8d44a2148c584926470bf652aadfdee305899 Mon Sep 17 00:00:00 2001 From: Scott Antonac Date: Mon, 27 May 2024 16:33:22 +1000 Subject: [PATCH] docs: add checkout diagrams --- docs/src/Gemfile.lock | 113 +++++++++++---------- docs/src/_config.yml | 3 + docs/src/_includes/mermaid_config.js | 11 ++ docs/src/_sass/color_schemes/afterpay.scss | 1 + docs/src/_sass/custom/custom.scss | 4 + docs/src/getting-started/cash-app-pay.md | 77 ++++++++++++++ docs/src/getting-started/checkout-v1.md | 45 ++++++++ docs/src/getting-started/checkout-v2.md | 49 ++++++++- docs/src/getting-started/configuration.md | 3 +- 9 files changed, 250 insertions(+), 56 deletions(-) create mode 100644 docs/src/_includes/mermaid_config.js diff --git a/docs/src/Gemfile.lock b/docs/src/Gemfile.lock index c029bf9c..1d1bc7f8 100644 --- a/docs/src/Gemfile.lock +++ b/docs/src/Gemfile.lock @@ -1,46 +1,56 @@ GEM remote: https://rubygems.org/ specs: - activesupport (7.0.5) + activesupport (7.1.3.3) + base64 + bigdecimal concurrent-ruby (~> 1.0, >= 1.0.2) + connection_pool (>= 2.2.5) + drb i18n (>= 1.6, < 2) minitest (>= 5.1) + mutex_m tzinfo (~> 2.0) - addressable (2.8.4) + addressable (2.8.6) public_suffix (>= 2.0.2, < 6.0) + base64 (0.2.0) + bigdecimal (3.1.8) coffee-script (2.4.1) coffee-script-source execjs - coffee-script-source (1.11.1) + coffee-script-source (1.12.2) colorator (1.1.0) - commonmarker (0.23.9) - concurrent-ruby (1.2.2) - dnsruby (1.70.0) + commonmarker (0.23.10) + concurrent-ruby (1.2.3) + connection_pool (2.4.1) + dnsruby (1.72.1) simpleidn (~> 0.2.1) + drb (2.2.1) em-websocket (0.5.3) eventmachine (>= 0.12.9) http_parser.rb (~> 0) ethon (0.16.0) ffi (>= 1.15.0) eventmachine (1.2.7) - execjs (2.8.1) - faraday (2.7.6) + execjs (2.9.1) + faraday (2.8.1) + base64 faraday-net_http (>= 2.0, < 3.1) ruby2_keywords (>= 0.0.4) faraday-net_http (3.0.2) - ffi (1.15.5) + ffi (1.16.3) forwardable-extended (2.6.0) - gemoji (3.0.1) - github-pages (228) - github-pages-health-check (= 1.17.9) - jekyll (= 3.9.3) - jekyll-avatar (= 0.7.0) - jekyll-coffeescript (= 1.1.1) + gemoji (4.1.0) + github-pages (231) + github-pages-health-check (= 1.18.2) + jekyll (= 3.9.5) + jekyll-avatar (= 0.8.0) + jekyll-coffeescript (= 1.2.2) jekyll-commonmark-ghpages (= 0.4.0) - jekyll-default-layout (= 0.1.4) - jekyll-feed (= 0.15.1) + jekyll-default-layout (= 0.1.5) + jekyll-feed (= 0.17.0) jekyll-gist (= 1.5.0) - jekyll-github-metadata (= 2.13.0) + jekyll-github-metadata (= 2.16.1) jekyll-include-cache (= 0.2.1) jekyll-mentions (= 1.6.0) jekyll-optional-front-matter (= 0.3.2) @@ -67,28 +77,28 @@ GEM jekyll-theme-tactile (= 0.2.0) jekyll-theme-time-machine (= 0.2.0) jekyll-titles-from-headings (= 0.5.3) - jemoji (= 0.12.0) - kramdown (= 2.3.2) + jemoji (= 0.13.0) + kramdown (= 2.4.0) kramdown-parser-gfm (= 1.1.0) liquid (= 4.0.4) mercenary (~> 0.3) minima (= 2.5.1) nokogiri (>= 1.13.6, < 2.0) - rouge (= 3.26.0) + rouge (= 3.30.0) terminal-table (~> 1.4) - github-pages-health-check (1.17.9) + github-pages-health-check (1.18.2) addressable (~> 2.3) dnsruby (~> 1.60) - octokit (~> 4.0) - public_suffix (>= 3.0, < 5.0) + octokit (>= 4, < 8) + public_suffix (>= 3.0, < 6.0) typhoeus (~> 1.3) html-pipeline (2.14.3) activesupport (>= 2) nokogiri (>= 1.4) http_parser.rb (0.8.0) - i18n (1.14.1) + i18n (1.14.5) concurrent-ruby (~> 1.0) - jekyll (3.9.3) + jekyll (3.9.5) addressable (~> 2.4) colorator (~> 1.0) em-websocket (~> 0.5) @@ -101,11 +111,11 @@ GEM pathutil (~> 0.9) rouge (>= 1.7, < 4) safe_yaml (~> 1.0) - jekyll-avatar (0.7.0) + jekyll-avatar (0.8.0) jekyll (>= 3.0, < 5.0) - jekyll-coffeescript (1.1.1) + jekyll-coffeescript (1.2.2) coffee-script (~> 2.2) - coffee-script-source (~> 1.11.1) + coffee-script-source (~> 1.12) jekyll-commonmark (1.4.0) commonmarker (~> 0.22) jekyll-commonmark-ghpages (0.4.0) @@ -113,15 +123,15 @@ GEM jekyll (~> 3.9.0) jekyll-commonmark (~> 1.4.0) rouge (>= 2.0, < 5.0) - jekyll-default-layout (0.1.4) - jekyll (~> 3.0) - jekyll-feed (0.15.1) + jekyll-default-layout (0.1.5) + jekyll (>= 3.0, < 5.0) + jekyll-feed (0.17.0) jekyll (>= 3.7, < 5.0) jekyll-gist (1.5.0) octokit (~> 4.2) - jekyll-github-metadata (2.13.0) + jekyll-github-metadata (2.16.1) jekyll (>= 3.4, < 5.0) - octokit (~> 4.0, != 4.4.0) + octokit (>= 4, < 7, != 4.4.0) jekyll-include-cache (0.2.1) jekyll (>= 3.7, < 5.0) jekyll-mentions (1.6.0) @@ -192,26 +202,27 @@ GEM jekyll (>= 3.3, < 5.0) jekyll-watch (2.2.1) listen (~> 3.0) - jemoji (0.12.0) - gemoji (~> 3.0) + jemoji (0.13.0) + gemoji (>= 3, < 5) html-pipeline (~> 2.2) jekyll (>= 3.0, < 5.0) - kramdown (2.3.2) + kramdown (2.4.0) rexml kramdown-parser-gfm (1.1.0) kramdown (~> 2.0) liquid (4.0.4) - listen (3.8.0) + listen (3.9.0) rb-fsevent (~> 0.10, >= 0.10.3) rb-inotify (~> 0.9, >= 0.9.10) mercenary (0.3.6) - mini_portile2 (2.8.2) + mini_portile2 (2.8.6) minima (2.5.1) jekyll (>= 3.5, < 5.0) jekyll-feed (~> 0.9) jekyll-seo-tag (~> 2.1) - minitest (5.18.0) - nokogiri (1.15.2) + minitest (5.23.1) + mutex_m (0.2.0) + nokogiri (1.15.6) mini_portile2 (~> 2.8.2) racc (~> 1.4) octokit (4.25.1) @@ -219,13 +230,14 @@ GEM sawyer (~> 0.9) pathutil (0.16.2) forwardable-extended (~> 2.6) - public_suffix (4.0.7) - racc (1.7.0) + public_suffix (5.0.5) + racc (1.8.0) rb-fsevent (0.11.2) - rb-inotify (0.10.1) + rb-inotify (0.11.1) ffi (~> 1.0) - rexml (3.2.5) - rouge (3.26.0) + rexml (3.2.8) + strscan (>= 3.0.9) + rouge (3.30.0) ruby2_keywords (0.0.5) rubyzip (2.3.2) safe_yaml (1.0.5) @@ -237,17 +249,14 @@ GEM sawyer (0.9.2) addressable (>= 2.3.5) faraday (>= 0.17.3, < 3) - simpleidn (0.2.1) - unf (~> 0.1.4) + simpleidn (0.2.3) + strscan (3.1.0) terminal-table (1.8.0) unicode-display_width (~> 1.1, >= 1.1.1) - typhoeus (1.4.0) + typhoeus (1.4.1) ethon (>= 0.9.0) tzinfo (2.0.6) concurrent-ruby (~> 1.0) - unf (0.1.4) - unf_ext - unf_ext (0.0.8.2) unicode-display_width (1.8.0) PLATFORMS diff --git a/docs/src/_config.yml b/docs/src/_config.yml index 05c313cb..4d9c0f38 100644 --- a/docs/src/_config.yml +++ b/docs/src/_config.yml @@ -28,3 +28,6 @@ callouts: info: title: Info color: blue + +mermaid: + version: "10.9.1" diff --git a/docs/src/_includes/mermaid_config.js b/docs/src/_includes/mermaid_config.js new file mode 100644 index 00000000..ece7b6d3 --- /dev/null +++ b/docs/src/_includes/mermaid_config.js @@ -0,0 +1,11 @@ +{ + theme: "base", + 'themeVariables': { + 'primaryColor': '#b2fce4', + 'primaryBorderColor': '#dfdfdf', + 'lineColor': '#F8B229', + 'secondaryColor': '#006100', + 'tertiaryColor': '#fff', + 'fontFamily': 'system-ui, -apple-system, blinkmacsystemfont, "Segoe UI", roboto, "Helvetica Neue", arial, sans-serif, "Segoe UI Emoji"' + } +} diff --git a/docs/src/_sass/color_schemes/afterpay.scss b/docs/src/_sass/color_schemes/afterpay.scss index a470496c..2bc9aac0 100644 --- a/docs/src/_sass/color_schemes/afterpay.scss +++ b/docs/src/_sass/color_schemes/afterpay.scss @@ -5,3 +5,4 @@ $feedback-color: rgb(223, 234, 246); $sidebar-color: $white; $nav-width: 18.75rem; $nav-width-md: 18.75rem; +$content-width: 60rem; diff --git a/docs/src/_sass/custom/custom.scss b/docs/src/_sass/custom/custom.scss index c582ab67..7d0cea84 100644 --- a/docs/src/_sass/custom/custom.scss +++ b/docs/src/_sass/custom/custom.scss @@ -38,6 +38,10 @@ code { color: white; display: inline-block; padding: 4px; + + &.language-mermaid { + display: block; + } } img { diff --git a/docs/src/getting-started/cash-app-pay.md b/docs/src/getting-started/cash-app-pay.md index cfc4e16b..ab270ea3 100644 --- a/docs/src/getting-started/cash-app-pay.md +++ b/docs/src/getting-started/cash-app-pay.md @@ -206,6 +206,83 @@ Afterpay.validateCashAppOrder(jwt: cashData.jwt, customerId: customerId, grantId The approved customer request will have grants associated with it which can be used with Afterpay’s Capture Payment API. Pass the `grantId` along with the token to capture using a server-to-server request. +## Sequence Diagram + +The below diagram describes the happy path. + +``` mermaid +%%{ + init: { + 'theme': 'base', + 'themeVariables': { + 'primaryColor': '#00c846', + 'primaryTextColor': '#FFFFFF', + 'primaryBorderColor': '#dfdfdf', + 'signalTextColor': '#000000', + 'signalColor': '#000000', + 'secondaryColor': '#006100', + 'tertiaryColor': '#fff' + } + } +}%% + +sequenceDiagram + participant App + participant Afterpay SDK + participant Cash App Pay SDK + participant Proxy Server + + participant Afterpay API + Note over App,Afterpay API: Setup + + App->>Afterpay SDK: Configure the SDK + Note over App,Afterpay SDK: Required for setting environment + + App->>Cash App Pay SDK: Create Cash App Pay instance + Note over App,Cash App Pay SDK: Ensure same environment
as Afterpay SDK config + + App->>App: Implement
deep linking + + App->>Cash App Pay SDK: Register for state updates + + Note over App,Afterpay API: Create Customer Request and Capture + + App->>Proxy Server: Get Token Request + + Proxy Server->>Afterpay API: Create Checkout Request + Note over Proxy Server,Afterpay API: Ensure same environment
as Afterpay SDK config

Request body should
contain `isCashAppPay: true` + + Afterpay API-->>Proxy Server: Create Checkout Response + + Note over Afterpay API,Proxy Server: Body contains a token + + Proxy Server-->>App: Get Token Response + + App->>Afterpay SDK: Sign the token + + Afterpay SDK->>Afterpay API: Token signing request + + Afterpay API-->>Afterpay SDK: Token signing response + + Afterpay SDK-->>App: Decoded token data + + App->>Cash App Pay SDK: Create a customer request + + App->>Cash App Pay SDK: Authorize the customer request + + App->>Afterpay SDK: Validate the order + + App->>Proxy Server: Upon approved state send capture request + Note over App,Proxy Server: Pass the Grant Id (from the approved state)
and token in the body + + Proxy Server->>Afterpay API: Capture Payment Request + + Afterpay API-->>Proxy Server: Capture Payment Response + + Proxy Server-->>App: Capture Payment Respnse + + App->>App: Handle payment
capture response +``` [custom-url-schemes]: https://developer.apple.com/documentation/xcode/defining-a-custom-url-scheme-for-your-app [universal-links]: https://developer.apple.com/ios/universal-links/ diff --git a/docs/src/getting-started/checkout-v1.md b/docs/src/getting-started/checkout-v1.md index f3cdbc15..6dc5e775 100644 --- a/docs/src/getting-started/checkout-v1.md +++ b/docs/src/getting-started/checkout-v1.md @@ -107,3 +107,48 @@ struct MyView: View { } ``` + +## Sequence Diagram + +The below diagram describes the happy path. + +``` mermaid +sequenceDiagram + participant App + participant Afterpay SDK + participant Proxy Server + participant Afterpay API + + Note over App,Afterpay API: Setup + + App->>Afterpay SDK: Configure the SDK + Note over App,Afterpay SDK: Only required if
setting consumer locale + + Note over App,Afterpay API: Create checkout and Capture + + App->>Proxy Server: Get Checkout URL Request + + Proxy Server->>Afterpay API: Create Checkout Request + Note over Proxy Server,Afterpay API: Ensure same environment
as Afterpay SDK config + + Afterpay API-->>Proxy Server: Create Checkout Response + Note over Afterpay API,Proxy Server: Body contains a URL + + Proxy Server-->>App: Get URL Response + + App->>Afterpay SDK: Launch the checkout
with the URL + + Note over App,Afterpay API: Consumer confirms Afterpay checkout + + Afterpay SDK-->>App: Checkout result + + App->>Proxy Server: Capture request + + Proxy Server->>Afterpay API: Capture request + + Afterpay API-->>Proxy Server: Capture response + + Proxy Server-->>App: Capture Response + + App->>App: Handle response +``` diff --git a/docs/src/getting-started/checkout-v2.md b/docs/src/getting-started/checkout-v2.md index 3f9bcdf1..cf923ff9 100644 --- a/docs/src/getting-started/checkout-v2.md +++ b/docs/src/getting-started/checkout-v2.md @@ -17,9 +17,6 @@ nav_order: 3 {:toc} -{: .alert } -Checkout v2 is not available at this time for the following regions: France, Italy, Spain. - Checkout version 2 allows you to load the checkout token on demand via `didCommenceCheckout` while presenting a loading view. It also supports `express` checkout features and callbacks which can either be handled in line or via a checkout handler object. {: .note } @@ -122,5 +119,51 @@ final class MyViewController: UIViewController { } ``` +## Sequence Diagram + +The below diagram describes the happy path. + +``` mermaid +sequenceDiagram + participant App + participant Afterpay SDK + participant Proxy Server + participant Afterpay API + + Note over App,Afterpay API: Setup + + App->>Afterpay SDK: Configure the SDK + + App->>Afterpay SDK: Setup checkout handlers + + Note over App,Afterpay API: Create checkout and Capture + + App->>Proxy Server: Get Checkout Token Request + + Proxy Server->>Afterpay API: Create Checkout Request + Note over Proxy Server,Afterpay API: Ensure same environment
as Afterpay SDK config + + Afterpay API-->>Proxy Server: Create Checkout Response + Note over Afterpay API,Proxy Server: Body contains a Token + + Proxy Server-->>App: Get Token Response + + App->>Afterpay SDK: Launch the checkout
with the Token + + Note over App,Afterpay API: Consumer confirms Afterpay checkout + + Afterpay SDK-->>App: Checkout result + + App->>Proxy Server: Capture request + + Proxy Server->>Afterpay API: Capture request + + Afterpay API-->>Proxy Server: Capture response + + Proxy Server-->>App: Capture Response + + App->>App: Handle response +``` + [example-server-param]: https://github.com/afterpay/sdk-example-server/blob/5781eadb25d7f5c5d872e754fdbb7214a8068008/src/routes/checkout.ts#L28 [express-checkout]: https://developers.afterpay.com/afterpay-online/reference#what-is-express-checkout diff --git a/docs/src/getting-started/configuration.md b/docs/src/getting-started/configuration.md index 25d0850b..33f457b6 100644 --- a/docs/src/getting-started/configuration.md +++ b/docs/src/getting-started/configuration.md @@ -18,7 +18,8 @@ let configuration = try Configuration( maximumAmount: response.maximumAmount.amount, currencyCode: response.maximumAmount.currency, locale: Locale(identifier: "en_US"), - environment: .sandbox + environment: .sandbox, + consumerLocale: Locale(identifier: "en_US") // optional. overrides device locale ) Afterpay.setConfiguration(configuration)