Merge pull request #79 from naomiaro/feat/examples

feat: add examples to CDOGS repo

app/.prettierrc

@@ -0,0 +1,4 @@
+{
+  "semi": true,
+  "singleQuote": true
+}

examples/.prettierrc

@@ -0,0 +1,4 @@
+{
+  "semi": true,
+  "singleQuote": true
+}

examples/01-authenticated.sh

@@ -0,0 +1,38 @@
+#! /usr/bin/env bash
+
+# Retrieve a valid bearer token from oidc.
+token=$(curl --request POST \
+   --url 'https://dev.oidc.gov.bc.ca/auth/realms/jbd6rnxw/protocol/openid-connect/token' \
+   -H 'content-type: application/x-www-form-urlencoded' \
+   --data grant_type=client_credentials \
+   --data client_id="$CLIENT_ID" \
+   --data client_secret="$CLIENT_SECRET" | jq -r '.access_token')
+
+# The template to be rendered is base64 encoded so we can POST the info to CDOGS.
+base64_encoded_template=$(base64 -i template.txt)
+
+# This sends data to CDOGS so that our template.txt can be rendered out to file test.pdf.
+curl --request POST \
+   --url 'https://cdogs-dev.apps.silver.devops.gov.bc.ca/api/v2/template/render' \
+   -H "Authorization: Bearer $token" \
+   -H 'content-type: application/json' \
+   -o 'test.pdf' \
+   --data-binary @- << EOF
+{
+  "data": {
+    "firstName": "Jane",
+    "lastName": "Smith"
+  },
+  "template": {
+    "encodingType": "base64",
+    "fileType": "txt",
+    "content": "$base64_encoded_template"
+  },
+  "options": {
+    "cacheReport": false,
+    "convertTo": "pdf",
+    "overwrite": true,
+    "reportName": "{d.firstName}-{d.lastName}.pdf"
+  }
+}
+EOF

examples/01-unauthenticated.sh

@@ -0,0 +1,39 @@
+#! /usr/bin/env bash
+
+# Examples below are using a locally running docker image without keycloak.
+
+# This uploads a template to CDOGS, caches it for later rendering, and returns a resulting template hash.
+template_hash=$(curl -v -F template=@template.txt http://localhost:3000/api/v2/template)
+
+echo "template_hash $template_hash"
+
+# Response body is a template string ex.
+# bffe2a344ec1f8fb4fc1a1496df4ca29277da310f64eaa8748a1888b7a2198c5
+
+# If the template is already cached an error is returned:
+# template_hash {
+#   "type":"https://httpstatuses.com/405",
+#   "title":"Method Not Allowed",
+#   "status":405,
+#   "detail":"File already cached. Hash 'bffe2a344ec1f8fb4fc1a1496df4ca29277da310f64eaa8748a1888b7a2198c5'."
+# }
+
+# This sends data to CDOGS so that our template.txt can be rendered out to file test.pdf.
+curl --request POST \
+   --url "http://localhost:3000/api/v2/template/$template_hash/render" \
+   -H 'content-type: application/json' \
+   -o 'test.pdf' \
+   --data-binary @- << EOF
+{
+  "data": {
+    "firstName": "Joe",
+    "lastName": "Smith"
+  },
+  "options": {
+    "cacheReport": false,
+    "convertTo": "pdf",
+    "overwrite": true,
+    "reportName": "{d.firstName}_{d.lastName}.pdf"
+  }
+}
+EOF

examples/README.md

@@ -0,0 +1,57 @@
+# Example usage of CDOGS
+
+If you would like to use the KeyCloak Realm `jbd6rnxw` hosted by the Common Services Team (as used by this token endpoint `https://dev.oidc.gov.bc.ca/auth/realms/jbd6rnxw/protocol/openid-connect/token`), you can request client setup with [GETOK](https://getok.nrs.gov.bc.ca/app/about)
+
+## Node
+
+There is an example of using node.js in file `server.js`.
+
+To run the example:
+
+```
+npm install
+```
+
+```
+CLIENT_ID="your_keycloak_client_id" CLIENT_SECRET="your_keycloak_client_secret" node server.js
+```
+
+## Curl
+
+Assuming you have an environment including
+
+```
+CLIENT_ID="your_keycloak_client_id"
+CLIENT_SECRET="your_keycloak_client_secret"
+```
+
+where authentication is required, there are some example bash scripts.
+
+# CDOGS with Docker
+
+```sh
+> docker pull bcgovimages/common-document-generation-service:latest
+```
+
+## CDOGS without auth
+
+### Quickstart
+
+```sh
+> docker run -it --rm -p 3000:3000 bcgovimages/common-document-generation-service:latest
+```
+
+### Creating a volume to persist the document cache
+```sh
+> docker volume create carbone-cache
+# View details about your new volume
+> docker volume inspect carbone-cache
+# Start the CDOGS container with the new volume to persist the document cache.
+# /tmp/carbone-files is the default for CACHE_DIR
+> docker run -d -p 3000:3000 --name CDOGS -v carbone-cache:/tmp/carbone-files bcgovimages/common-document-generation-service:latest
+```
+
+## CDOGS with auth
+```sh
+> docker run -it --rm -p 3000:3000 -e KC_CLIENTID=<id> -e KC_CLIENTSECRET=<secret> -e KC_ENABLED=true -e KC_PUBLICKEY=<publickey> -e KC_REALM=<realm> -e KC_SERVERURL=<url> bcgovimages/common-document-generation-service:latest
+```

examples/doc-caching.js

@@ -0,0 +1,96 @@
+import fetch from 'node-fetch';
+import fs from 'fs';
+import { fileFromSync } from 'fetch-blob/from.js';
+import { FormData } from 'formdata-polyfill/esm.min.js';
+
+const template = fileFromSync('./template.txt');
+const fd = new FormData();
+let templateHash;
+
+fd.append('template', template);
+
+const cdogsTemplateCacheResponse = await fetch(
+  'http://localhost:3000/api/v2/template',
+  {
+    method: 'POST',
+    body: fd,
+  }
+);
+
+if (cdogsTemplateCacheResponse.ok) {
+  templateHash = await cdogsTemplateCacheResponse.text();
+
+  /*
+   * If this response is successful, it will return the hash that relates to this uploaded template.
+   * It must be saved for further api usage.
+   */
+
+  console.log(templateHash);
+  //   bffe2a344ec1f8fb4fc1a1496df4ca29277da310f64eaa8748a1888b7a2198c5
+} else {
+  const apiError = await cdogsTemplateCacheResponse.json();
+
+  /*
+   * If this response is not successful an (RFC 7807) `api-problem` is returned.
+   * https://www.npmjs.com/package/api-problem
+   */
+
+  console.log(apiError);
+  //   {
+  //     type: 'https://httpstatuses.com/405',
+  //     title: 'Method Not Allowed',
+  //     status: 405,
+  //     detail: "File already cached. Hash 'bffe2a344ec1f8fb4fc1a1496df4ca29277da310f64eaa8748a1888b7a2198c5'."
+  //   }
+
+  process.exit(1);
+}
+
+const cdogsRenderResponse = await fetch(
+  `http://localhost:3000/api/v2/template/${templateHash}/render`,
+  {
+    method: 'POST',
+    body: JSON.stringify({
+      data: {
+        firstName: 'Common',
+        lastName: 'Services',
+      },
+      options: {
+        cacheReport: false,
+        convertTo: 'pdf',
+      },
+    }),
+    headers: {
+      'Content-Type': 'application/json',
+    },
+  }
+);
+
+const pdf = await cdogsRenderResponse.arrayBuffer();
+
+// saves a file test.pdf - the CDOGS output.
+fs.writeFileSync('test.pdf', Buffer.from(pdf), 'binary');
+
+// Removing the template from the cache
+const cdogsTemplateDeleteResponse = await fetch(
+  `http://localhost:3000/api/v2/template/${templateHash}`,
+  {
+    method: 'DELETE',
+  }
+);
+
+if (cdogsTemplateDeleteResponse.ok) {
+  const OK = await cdogsTemplateDeleteResponse.text();
+
+  // just prints OK.
+  console.log(OK);
+} else {
+  const apiError = await cdogsTemplateDeleteResponse.json();
+
+  /*
+   * If this response is not successful an (RFC 7807) `api-problem` is returned.
+   * https://www.npmjs.com/package/api-problem
+   */
+
+  console.log(apiError);
+}

examples/package.json

@@ -0,0 +1,19 @@
+{
+  "name": "examples",
+  "private": true,
+  "type": "module",
+  "version": "1.0.0",
+  "description": "",
+  "main": "server.js",
+  "scripts": {
+    "test": "echo \"Error: no test specified\" && exit 1",
+    "start": "node server.js"
+  },
+  "author": "",
+  "license": "Apache-2.0",
+  "dependencies": {
+    "fetch-blob": "^3.1.3",
+    "formdata-polyfill": "^4.0.10",
+    "node-fetch": "^3.1.0"
+  }
+}