feat: migrate api spec 3ppi isp api

vuepress/docs/.vuepress/config.js

@@ -304,10 +304,35 @@ module.exports = {
           sidebarDepth: 2
         },
         {
-          title: '3PPI/ISP API',
+          title: 'Thirdparty API',
           collapsable: false,
+          path: 'thirdparty/',
           children: [
-            ['3ppi-pisp/', 'Overview'],
+            {
+              title: 'API Definitions',
+              path: 'fspiop/logical-data-model',
+              collapsable: true
+            },
+            {
+              title: 'Transaction Patterns',
+              path: 'thirdparty/transaction-patterns',
+              collapsable: true,
+              children: [
+                {
+                  title: 'Transaction Patterns Linking',
+                  path: 'thirdparty/transaction-patterns-linking'
+                },
+                {
+                  title: 'Transaction Patterns Transfer',
+                  path: 'thirdparty/transaction-patterns-transfer'
+                }
+              ]
+            },
+            {
+              title: 'Data Models',
+              path: 'thirdparty/data-models',
+              collapsable: true
+            },
           ],
           sidebarDepth: 2
         },

vuepress/docs/api/thirdparty/README.md

@@ -0,0 +1,41 @@
+# Third Party API
+
+The Third Party API is an API for non-fund-holding participants to interact over a centralized Mojaloop hub.
+Specifically, this API allows Payment Initiation Service Providers (PISPs) to act as a proxy in initiating
+payments, while allowing for the strong authentication of users.
+
+## Terms
+
+The following terms are commonly used across the Third Party API Documentation
+
+| **Term** | **Alternative and Related Terms** | **Definition** | **Source** |
+| --- | --- | --- | --- |
+| **Payment Initiation Service Provider** | PISP, 3rd Party Payment Initiator (3PPI) | Regulated entities like retail banks or third parties, that allow customers to make payments without accessing bank accounts or cards | [PSD2](https://eur-lex.europa.eu/legal-content/EN/TXT/?uri=CELEX%3A32015L2366&qid=1633311418487) |
+| **FSP** | Provider, Financial Service Provider (FSP), Payment Service Provider, Digital Financial Services Provider (DFSP) | The entity that provides a digital financial service to an end user (either a consumer, a business, or a government.) In a closed-loop payment system, the Payment System Operator is also the provider. In an open-loop payment system, the providers are the banks or non-banks which participate in that system. | [ITU-T](https://www.itu.int/dms_pub/itu-t/opb/tut/T-TUT-ECOPO-2018-PDF-E.pdf) |
+| **User**                                | End User                                 | An end user that is shared between a PISP and DFSP. Mostly used in the context of a real human being, but this could also be a machine user, or a business for example |
+| **Consent**                             | Account Link                             | A representation of an agreement between the DFSP, PISP and User | |
+| **Auth-Service**                        |                                          | A service run by the Mojaloop Hub that is responsible for verifying and storing Consents, and verifying transaction request signatures | |
+
+## API Definitions
+
+The Third Party API is defined across the following OpenAPI 3.0 files:
+
+- [Third Party API - PISP](./thirdparty-pisp-v1.0.yaml)
+- [Third Party API - DFSP](./thirdparty-dfsp-v1.0.yaml)
+
+The implementation of these APIs will depend on the role of the participant. PISPs should implement the [Third Party API - PISP](./thirdparty-pisp-v1.0.yaml)
+interface in order to request and manage Account Linking operations, and initiate Third Party Transaction Requests.
+
+DFSPs who wish to support Account Linking operations, and be able to respond to and verify Third Party Transaction Requests should
+implement the [Third Party API - DFSP](./thirdparty-dfsp-v1.0.yaml).
+
+## Transaction Patterns
+
+The interactions and examples of how a DFSP and PISP will interact with the Third Party API can be found in the following Transaction Patterns Documents:
+
+1. [Linking](./transaction-patterns-linking.md) describes how an account link and credential can be established between a DFSP and a PISP
+2. [Transfer](./transaction-patterns-transfer.md) describes how a PISP can initate a payment from a DFSP's account using the account link
+
+## Data Models
+
+The [Data Models Document](./data-models.md) describes in detail the Data Models used in the Third Party API

vuepress/docs/api/thirdparty/_sync_docs.sh

@@ -0,0 +1,22 @@
+#!/usr/bin/env bash
+
+##
+# Synchronises the definition docs from their disparate locations into one place.
+#
+# The API Spec for the Third Party API is managed by the api-snippets project
+##
+
+set -eu
+
+DIR="$( cd "$( dirname "${BASH_SOURCE[0]}" )" && pwd )"
+GIT_URL="https://github.com/mojaloop/api-snippets.git"
+BRANCH='master'
+CLONE_DIR='/tmp/api-snippets'
+
+rm -rf ${CLONE_DIR}
+
+git clone -b ${BRANCH} ${GIT_URL} ${CLONE_DIR}
+
+# API definition, grab from mojaloop/pisp-project
+cp ${CLONE_DIR}/thirdparty/openapi3/thirdparty-dfsp-api.yaml ${DIR}/thirdparty-dfsp-v1.0.yaml
+cp ${CLONE_DIR}/thirdparty/openapi3/thirdparty-pisp-api.yaml ${DIR}/thirdparty-pisp-v1.0.yaml

vuepress/docs/api/thirdparty/assets/README.md

@@ -0,0 +1,15 @@
+# thirdparty-api/assets
+
+Supporting Assets for the Third Party API Specification
+
+
+## Rebuild all Puml -> svg
+
+For consistent rending of sequence diagrams, we build the .puml sources to .svgs using the following script
+
+```bash
+./_build_plantuml_all.sh
+```
+
+This also ensures that the sequence diagrams are easily readable inline in markdown documents.
+

vuepress/docs/api/thirdparty/assets/_build_plantuml_all.sh

@@ -0,0 +1,33 @@
+#!/usr/bin/env bash
+
+DIR="$( cd "$( dirname "${BASH_SOURCE[0]}" )" && pwd )"
+PUML_PORT=9999
+export PUML_BASE_URL=http://localhost:${PUML_PORT}
+
+##
+# searches through repo for plantuml sources
+# and exports them using `node-plantuml`
+##
+
+trap ctrl_c INT
+function ctrl_c() {
+  echo "exit early - stopping docker"
+  docker stop puml-local
+  exit 1
+}
+
+# run the docker puml server
+docker run -d --rm \
+  --name puml-local \
+  -p ${PUML_PORT}:8080 \
+  plantuml/plantuml-server:jetty-v1.2020.21
+
+# Wait for docker to be up
+sleep 2
+
+for i in $(find ${DIR}/diagrams -name '*.puml'); do
+  echo "rendering .puml -> .svg for diagram diagram: $i"
+  ${DIR}/_render_svg.js $i $(echo $i | sed 's/puml/svg/g')
+done
+
+docker stop puml-local

vuepress/docs/api/thirdparty/assets/_build_plantuml_diff.sh

@@ -0,0 +1,36 @@
+#!/usr/bin/env bash
+
+DIR="$( cd "$( dirname "${BASH_SOURCE[0]}" )" && pwd )"
+PUML_PORT=9999
+export PUML_BASE_URL=http://localhost:${PUML_PORT}
+
+##
+# searches through repo for plantuml sources
+# and exports them using `node-plantuml`
+##
+
+trap ctrl_c INT
+function ctrl_c() {
+  echo "exit early - stopping docker"
+  docker stop puml-local
+  exit 1
+}
+
+# run the docker puml server
+docker run -d --rm \
+  --name puml-local \
+  -p ${PUML_PORT}:8080 \
+  plantuml/plantuml-server:jetty-v1.2020.21
+
+# Wait for docker to be up
+sleep 2
+
+for i in $(git diff --staged --name-only `find ${DIR}/../docs -name '*.puml'`); do
+  echo "rendering .puml -> .svg for diagram diagram: $i"
+  ${DIR}/_render_svg.js $i $(echo $i | sed 's/puml/svg/g')
+done
+
+
+git add ./
+
+docker stop puml-local

vuepress/docs/api/thirdparty/assets/_render_svg.js

@@ -0,0 +1,64 @@
+#!/usr/bin/env node
+
+
+/**
+ * Uses plantuml server to render a puml to svg
+ */
+
+const fs = require('fs')
+const path = require('path')
+const util = require('util')
+const got = require('got')
+const SVGO = require('svgo')
+const plantumlEncoder = require('plantuml-encoder')
+
+const rendererBaseUrl = process.env.PUML_BASE_URL || 'http://www.plantuml.com/plantuml'
+
+svgo = new SVGO({
+  js2svg: { pretty: true, indent: 2 },
+  plugins: [
+    { removeComments: true },
+  ]
+});
+
+async function main() {
+  let [_, _script, inputPath, outputPath] = process.argv
+
+  if (!inputPath) {
+    console.log("usage: ./_render_svg.js <input path> [<output path>]")
+    process.exit(1)
+  }
+
+  // If not specified, replace .puml or .plantuml with `.svg`
+  if (!outputPath) {
+    outputPath = inputPath.replace('.puml', '.svg')
+      .replace('.plantuml', '.svg')
+  }
+
+  const rawPumlContents = fs.readFileSync(inputPath)
+  const encoded = plantumlEncoder.encode(rawPumlContents.toString())
+  const url = path.join(rendererBaseUrl, 'svg', encoded)
+  let result
+  try {
+    result = await got.get(url)
+  } catch (err) {
+    console.log('http request failed to render puml with error', err.message)
+    if (err.message.indexOf('Response code 403') > -1) {
+      console.log('Note: sometimes the public puml renderer fails when the input diagrams are too large. Try running your own renderer server with docker.')
+    }
+
+    if (err.message.indexOf('Response code 400') > -1) {
+      console.log('This could be due to bad syntax in the puml diagram. Url is:')
+      console.log(url)
+    }
+
+    process.exit(1)
+  }
+
+  // Strip comments and prettify svg
+  // This makes sure that our .svg files are deterministic and diffable
+  const formatted = await svgo.optimize(result.body)
+  fs.writeFileSync(outputPath, formatted.data)
+}
+
+main()

vuepress/docs/api/thirdparty/assets/diagrams/linking/0-pre-linking.puml

@@ -0,0 +1,49 @@
+@startuml
+
+' declaring skinparam
+skinparam shadowing false
+skinparam defaultFontName Verdana
+skinparam monochrome true
+skinparam SequenceLifeLineBackgroundColor WhiteSmoke
+skinparam SequenceLifeLineBorderColor Black
+skinparam ParticipantFontStyle Bold
+skinparam ParticipantFontSize 20
+skinparam ParticipantBackgroundColor WhiteSmoke
+skinparam ArrowColor Black
+
+hide footbox
+
+title PISP Linking: Pre-linking
+
+box "Mobile device"
+    participant App
+end box
+
+box "PISP"
+    participant PISP
+end box
+
+box "Mojaloop"
+    participant Switch
+end box
+
+autonumber 1 "<b>PRE-#</b>"
+activate App
+App -> PISP ++: What DFSPs are available to link with?
+
+
+PISP -> Switch ++: ""GET /services/THIRD_PARTY_DFSP""\n""FSPIOP-Source: pispa""\n""FSPIOP-Destination: switch""
+Switch --> PISP: ""202 Accepted""
+deactivate PISP
+
+Switch -> PISP ++: ""PUT /services/THIRD_PARTY_DFSP""\n""FSPIOP-Source: switch""\n""FSPIOP-Destination: pispa""\n\
+ ""{""\n\
+  ""  "serviceProviders": ["" \n\
+  ""    "dfspa", "dfspb""" \n\
+  ""  ]"" \n\
+ ""}""
+PISP --> Switch: ""200 OK""
+
+PISP --> App --: We have dfspa and dfspb\n
+
+@enduml