docs: Resolves #376 (#377)

* docs: Resolves #376 * Bump dependencies * Update pnpm-lock.yaml * Update CodeBlock component * Resolve deployment issue * Update mermaid implementation --------- Co-authored-by: Chen Hui Jing <[email protected]>
interledger · Nov 29, 2023 · 59268b5 · 59268b5
1 parent 821f46f
commit 59268b5
Show file tree

Hide file tree

Showing 29 changed files with 335 additions and 330 deletions.
diff --git a/.github/workflows/deploy-docs.yaml b/.github/workflows/deploy-docs.yaml
@@ -34,7 +34,6 @@ jobs:
 
       - name: Install dependencies
         run: pnpm install
-      - run: pnpm dlx playwright install --with-deps chromium
 
       - name: Build website
         run: |

diff --git a/.github/workflows/test-docs-build.yml b/.github/workflows/test-docs-build.yml
@@ -28,7 +28,6 @@ jobs:
 
       - name: Install dependencies
         run: pnpm install
-      - run: pnpm dlx playwright install --with-deps chromium
 
       - name: Test build website
         run: |

diff --git a/docs/astro.config.mjs b/docs/astro.config.mjs
@@ -1,10 +1,9 @@
 import { defineConfig } from 'astro/config'
 import starlight from '@astrojs/starlight'
 import { generateAPI } from 'starlight-openapi'
-import remarkMermaid from 'remark-mermaidjs'
 
 // Generate the documentation and get the associated sidebar groups.
-const { openAPISidebarGroups, starlightOpenAPI } = await generateAPI([
+const { starlightOpenAPI } = await generateAPI([
   {
     base: 'apis/resource-server',
     label: 'Open Payments',
@@ -20,9 +19,6 @@ const { openAPISidebarGroups, starlightOpenAPI } = await generateAPI([
 // https://astro.build/config
 export default defineConfig({
   site: 'https://openpayments.guide',
-  markdown: {
-    remarkPlugins: [remarkMermaid]
-  },
   integrations: [
     starlight({
       title: 'Open Payments',
@@ -33,6 +29,12 @@ export default defineConfig({
         './node_modules/@interledger/docs-design-system/src/styles/ilf-docs.css',
         './src/styles/openpayments.css'
       ],
+      expressiveCode: {
+        styleOverrides: {
+          borderColor: 'transparent',
+          borderRadius: 'var(--border-radius)'
+        }
+      },
       logo: {
         src: './public/favicon.svg'
       },
@@ -74,6 +76,10 @@ export default defineConfig({
           label: 'Code snippets',
           collapsed: true,
           items: [
+            {
+              label: 'Before you begin',
+              link: '/snippets/before-you-begin'
+            },
             {
               label: 'Wallet addresses',
               collapsed: true,

diff --git a/docs/package.json b/docs/package.json
@@ -10,15 +10,15 @@
     "astro": "astro"
   },
   "dependencies": {
-    "@astrojs/starlight": "^0.11.2",
-    "@interledger/docs-design-system": "^0.1.2",
-    "astro": "3.4.0",
-    "remark-mermaidjs": "^6.0.0",
+    "@astrojs/starlight": "^0.13.1",
+    "@interledger/docs-design-system": "^0.2.1",
+    "astro": "3.6.3",
+    "mermaid": "^10.6.1",
     "sharp": "^0.32.6",
     "shiki": "0.14.5",
     "starlight-openapi": "^0.3.1"
   },
   "devDependencies": {
-    "prettier": "3.0.3"
+    "prettier": "3.1.0"
   }
 }
diff --git a/docs/src/content/docs/introduction/op-flow.mdx b/docs/src/content/docs/introduction/op-flow.mdx
@@ -2,7 +2,7 @@
 title: Open Payments flow
 ---
 
-import { MermaidWrapper } from '@interledger/docs-design-system'
+import { MermaidWrapper, Mermaid } from '@interledger/docs-design-system'
 
 This page describes the Open Payments flow at a high level. The sequence diagrams are for illustrative purposes and are not an exact representation of the flow.
 
@@ -14,142 +14,147 @@ In this flow, assume the client's end-user is the payer and that the client alre
 
 <MermaidWrapper client:load>
 
-```mermaid
-sequenceDiagram
+<Mermaid
+  graph={`sequenceDiagram
+    participant C as Client
+    participant PAW as Payee's wallet address
 
-participant C as Client
-participant PAW as Payee's wallet address
+    C->>PAW: GET wallet address
+    PAW->>C: 200 Wallet address found, returns public info incl. auth server
 
-C->>PAW: GET wallet address
-PAW->>C: 200 Wallet address found, returns public info incl. auth server
-```
+`}
+/>
 
 </MermaidWrapper>
 
 2. The client requests/receives a grant from the payee's authorization server to create an `incoming-payment` resource on the payee’s account. The client then sends a request to the resource server to create the resource. When created, the resource server returns unique payment details the client will use to address one or more payments to the payee.
 
 <MermaidWrapper client:load>
 
-```mermaid
-sequenceDiagram
+<Mermaid
+  graph={`sequenceDiagram
+    participant C as Client
+    participant AS as Authorization server
+    participant RS as Resource server
 
-participant C as Client
-participant AS as Authorization server
-participant RS as Resource server
+    C->>AS: Grant request (POST) with type=incoming-payment
+    AS->>C: 200 OK, returns access token
+    C->>RS: Create incoming payment resource (POST)
+    RS->>C: 201 Incoming payment created
 
-C->>AS: Grant request (POST) with type=incoming-payment
-AS->>C: 200 OK, returns access token
-C->>RS: Create incoming payment resource (POST)
-RS->>C: 201 Incoming payment created
-```
+`}
+/>
 
 </MermaidWrapper>
 
 3. The client requests/receives a grant from the end-user's authorization server to create a `quote` resource on the user's account. The client then sends a request to the user's resource server to create the resource. When created, the resource server returns, among other things, a quote `id` and the amount it will cost to make the payment.
 
 <MermaidWrapper client:load>
 
-```mermaid
-sequenceDiagram
+<Mermaid
+  graph={`sequenceDiagram
+    participant C as Client
+    participant AS as Authorization server
+    participant RS as Resource server
 
-participant C as Client
-participant AS as Authorization server
-participant RS as Resource server
+    C->>AS: Grant request (POST) with type=quote
+    AS->>C: 200 OK, returns access token
+    C->>RS: Create quote resource (POST)
+    RS->>C: 201 Quote created
 
-C->>AS: Grant request (POST) with type=quote
-AS->>C: 200 OK, returns access token
-C->>RS: Create quote resource (POST)
-RS->>C: 201 Quote created
-```
+`}
+/>
 
 </MermaidWrapper>
 
 4. The client issues an [interactive grant request](/introduction/grants/#outgoing-payment-grant) to the end-user's authorization server to obtain the user's explicit consent to send a payment of X amount. While the client must facilitate the interaction, the authorization server is responsible for the interface and collecting consent.
 
 <MermaidWrapper client:load>
 
-```mermaid
-sequenceDiagram
+<Mermaid
+  graph={`sequenceDiagram
+    participant C as Client
+    participant AS as Authorization server
 
-participant C as Client
-participant AS as Authorization server
+    C->>AS: Grant request (POST) with type=outgoing-payment, interact object
+    AS->>C: 200 OK, returns interaction instructions
+    C->>AS: Sends end-user to redirect URI to initiate interaction flow
 
-C->>AS: Grant request (POST) with type=outgoing-payment, interact object
-AS->>C: 200 OK, returns interaction instructions
-C->>AS: Sends end-user to redirect URI to initiate interaction flow
-
-```
+`}
+/>
 
 </MermaidWrapper>
 
 5. After consent is obtained, the client requests/receives permission to continue the grant request and create an `outgoing-payment` resource on the end-user's payment account. When created, the setup of the payment is complete and the Open Payments flow ends.
 
 <MermaidWrapper client:load>
 
-```mermaid
-sequenceDiagram
+<Mermaid
+  graph={`sequenceDiagram
 
-participant C as Client
-participant AS as Authorization server
+    participant C as Client
+    participant AS as Authorization server
 
-AS->>AS: End-user interacts with authorization server and approves the grant
-AS->>C: Redirects end-user to client's finish URI, includes hash and interaction reference
-C->>C: Verifies hash
-C->>AS: Grant continuation request (POST) with interaction reference
-AS->>C: 200 Success with access_token
+    AS->>AS: End-user interacts with authorization server and approves the grant
+    AS->>C: Redirects end-user to client's finish URI, includes hash and interaction reference
+    C->>C: Verifies hash
+    C->>AS: Grant continuation request (POST) with interaction reference
+    AS->>C: 200 Success with access_token
 
-```
+`}
+/>
 
 </MermaidWrapper>
 
 ## Complex flow
 
 <MermaidWrapper client:load>
 
-```mermaid
-sequenceDiagram
-
-participant Cu as Customer
-participant A2 as Auth Server B
-participant R2 as Backend B
-participant R1 as Backend A
-participant A1 as Auth Server A
-participant Cl as Merchant
-
-activate Cl
-Cl->>+A1: incoming payment grant request
-A1->>-Cl: grant + access token
-Cl->>+R1: incoming payment creation request
-R1->>+A1: token introspection
-A1->>-R1: token valid + grant details
-R1->>-Cl: incoming payment
-rect rgba(0, 0, 255, .1)
-Cl->>+Cu: request wallet address
-Cu->>Cl: wallet address
-end
-Cl->>+R2: query customer's wallet address
-R2->>-Cl: wallet address details including auth server endpoint
-Cl->>+A2: quote grant request
-A2->>-Cl: grant + access token
-Cl->>+R2: quote creation request
-R2->>+A2: token introspection
-A2->>-R2: token valid + grant details
-R2->>-Cl: quote
-Cl->>+A2: outgoing payment grant request
-A2->>-Cl: IdP redirect info
-rect rgba(0, 0, 255, .1)
-Cl->>Cu: redirect to IdP
-Cu->>Cu: consent to grant request
-Cu->>-Cl: interaction finished
-end
-Cl->>+A2: continue grant request
-A2->>-Cl: grant + access token
-Cl->>+R2: outgoing payment creation request
-R2->>+A2: token introspection
-A2->>-R2: token valid + grant details
-R2->>R2: grant accounting
-R2->>-Cl: outgoing payment
-deactivate Cl
-```
+<Mermaid
+  graph={`sequenceDiagram
+    participant Cu as Customer
+    participant A2 as Auth Server B
+    participant R2 as Backend B
+    participant R1 as Backend A
+    participant A1 as Auth Server A
+    participant Cl as Merchant
+
+    activate Cl
+    Cl->>+A1: incoming payment grant request
+    A1->>-Cl: grant + access token
+    Cl->>+R1: incoming payment creation request
+    R1->>+A1: token introspection
+    A1->>-R1: token valid + grant details
+    R1->>-Cl: incoming payment
+    rect rgba(0, 0, 255, .1)
+    Cl->>+Cu: request wallet address
+    Cu->>Cl: wallet address
+    end
+    Cl->>+R2: query customer's wallet address
+    R2->>-Cl: wallet address details including auth server endpoint
+    Cl->>+A2: quote grant request
+    A2->>-Cl: grant + access token
+    Cl->>+R2: quote creation request
+    R2->>+A2: token introspection
+    A2->>-R2: token valid + grant details
+    R2->>-Cl: quote
+    Cl->>+A2: outgoing payment grant request
+    A2->>-Cl: IdP redirect info
+    rect rgba(0, 0, 255, .1)
+    Cl->>Cu: redirect to IdP
+    Cu->>Cu: consent to grant request
+    Cu->>-Cl: interaction finished
+    end
+    Cl->>+A2: continue grant request
+    A2->>-Cl: grant + access token
+    Cl->>+R2: outgoing payment creation request
+    R2->>+A2: token introspection
+    A2->>-R2: token valid + grant details
+    R2->>R2: grant accounting
+    R2->>-Cl: outgoing payment
+    deactivate Cl
+
+`}
+/>
 
 </MermaidWrapper>
diff --git a/docs/src/content/docs/snippets/before-you-begin.mdx b/docs/src/content/docs/snippets/before-you-begin.mdx
@@ -0,0 +1,50 @@
+---
+title: Interledger testnet
+---
+
+import { LinkOut } from '@interledger/docs-design-system'
+
+Before you begin working with our code snippets, we recommend getting set up on the Interledger testnet on <LinkOut href='https://rafiki.money'>rafiki.money</LinkOut>.
+
+The Interledger testnet lets you create developer keys and test wallets funded with play money for making Interledger transactions via the Open Payments API.
+
+## Create an Interledger testnet account
+
+You can create an Interledger testnet account via <LinkOut href="https://rafiki.money">rafiki.money</LinkOut>.
+
+1.  Click **Create an account** at the bottom right of the screen.
+2.  Enter your e-mail address, a password, confirm the password and click the arrowhead.
+3.  Go to your inbox and look for an e-mail sent by `[email protected]` with the subject "[Rafiki.Money] Verify your account" and click **Confirm my email address.** <br /><img src="/img/snippets/rafiki-money-step4.png" alt="Confirm email address" class="img-outline" width="350" height="auto" />
+4.  Click **Login to your account** at the email verification screen. <br /><img src="/img/snippets/rafiki-money-step5.png" alt="Log in with new account at rafiki.money" class="img-outline" width="350" height="auto" />
+5.  Log in with your credentials.
+6.  Enter any First and Last name on the Complete KYC screen and click **Get Wallet Account.** Note that since this is a test environment, the country, city and address fields will already be filled in. <br /><img src="/img/snippets/rafiki-money-step8.png" alt="Get wallet account at rafiki.money" class="img-outline" width="350" height="auto" />
+7.  Click **Verify your identity** on the pop-up window. <br /><img src="/img/snippets/rafiki-money-step9.png" alt="Identity verification at rafiki.money" class="img-outline" width="350" height="auto" />
+8.  Click **Verify Account** at the Complete KYC screen. Note that since this is a test environment "Passport" will be selected as the verification method and images will be uploaded by default. <br /><img src="/img/snippets/rafiki-money-step10.png" alt="Verify account at rafiki.money" class="img-outline" width="350" height="auto" />
+9.  Click **Go to your account overview** on the pop-up window. <br /><img src="/img/snippets/rafiki-money-step11.png" alt="Account overview dashboard on rafiki.money" class="img-outline" width="350" height="auto" />
+
+You're now ready to create a testnet wallet and add money to it!
+
+## Create a testnet wallet
+
+The first time you access the <LinkOut href="https://rafiki.money">testnet</LinkOut>, you'll be guided through creating a new wallet account.
+
+1. If you've completed or skipped the guide, you can create a wallet account by clicking **New Account.** <br /><img src="/img/snippets/rafiki-money-step13.png" alt="Set up new account at rafiki.money" class="img-outline" width="300" height="auto" />
+2. Enter a name for the account, choose an asset code from the drop-down menu and click **Create account.** <br /><img src="/img/snippets/rafiki-money-step15.png" alt="Enter name and create account on rafiki.money" class="img-outline" width="300" height="auto" />
+3. Click **View Account.** <br /><img src="/img/snippets/rafiki-money-step16.png" alt="Click to view account created on rafiki.money" class="img-outline" width="350" height="auto" />
+4. Click **Add payment pointer.** <br /><img src="/img/snippets/rafiki-money-step17.png" alt="Add a payment pointer for the new account on rafiki.money" class="img-outline" width="400" height="auto" />
+5. Enter a Payment Pointer name and a Public name and then click **Create.** <br /><img src="/img/snippets/rafiki-money-step19.png" alt="Create payment pointer on rafiki.money" class="img-outline" width="400" height="auto" />
+6. Click **Add money.** <br /><img src="/img/snippets/rafiki-money-step20.png" alt="Add money to payment pointer on rafiki.money" class="img-outline" width="400" height="auto" />
+7. Fund your wallet by entering an amount, then click **Add money.** <br /><img src="/img/snippets/rafiki-money-step21.png" alt="Enter amount and add money to the payment pointer on rafiki.money" class="img-outline" width="400" height="auto" />
+
+Congratulations, you now have a funded wallet on the Interledger testnet!
+
+## Obtain a public-private key pair and key ID
+
+Before you can initialize an authenticated Open Payments client, you must obtain a public-private key pair and a key ID.
+
+1. Sign in to the <LinkOut href='https://rafiki.money'>Interledger testnet</LinkOut>.
+2. Select **Settings > Developer Keys**.
+3. Expand the drop-down menu for your wallet account.<br /><img src="/img/snippets/generate-keys.png" alt="Expanded account showing payment pointer and Generate public & private key button" class="img-outline" style="max-width:600px;"/>
+4. Click **Generate public & private key**. Your key ID and public key appear on the site. A private key file named `private.key` automatically downloads to your machine. <img src="/img/snippets/view-keys.png" alt="Expanded account showing key ID, option to show public key, and button to revoke public/private keys" class="img-outline" style="max-height:300px;"/>
+
+You can now use your keys and payment pointer to initialize an authenticated Open Payments client.
diff --git a/docs/src/content/docs/snippets/grant-continue.mdx b/docs/src/content/docs/snippets/grant-continue.mdx
@@ -5,7 +5,7 @@ title: Continue a grant request
 import { Disclosure, CodeBlock, LinkOut } from '@interledger/docs-design-system'
 import { Tabs, TabItem } from '@astrojs/starlight/components'
 import ChunkedSnippet from '/src/components/ChunkedSnippet.astro'
-import Global from '/src/partials/global-prerequisites.mdx'
+import Begin from '/src/partials/before-you-begin.mdx'
 import Ts from '/src/partials/ts-prerequisites.mdx'
 
 During a grant request flow, an authorization server can require an individual (typically a client's end user) to approve the grant by interacting directly with the server. For example, by tapping an Approve button on a web page provided by the auth server.
@@ -16,7 +16,7 @@ These code snippets enable an authorized client to send a grant continuation req
 
 ## Before you begin
 
-<Global />
+<Begin />
 
 ## Issue grant continuation request