feat(api-interception): add FHIR API interception example

Author: GenaRazmakhnin

aidbox-custom-operations/fhir-api-intersept/.env.tpl

@@ -0,0 +1,47 @@
+BOX_SETTINGS_MODE=read-write
+
+BOX_BOOTSTRAP_FHIR_PACKAGES="hl7.fhir.r4.core#4.0.1"
+BOX_FHIR_TERMINOLOGY_SERVICE_BASE_URL=https://tx.health-samurai.io/fhir
+BOX_FHIR_SCHEMA_VALIDATION=true
+BOX_FHIR_CREATEDAT_URL=https://aidbox.app/ex/createdAt
+BOX_FHIR_CORRECT_AIDBOX_FORMAT=true
+BOX_FHIR_COMPLIANT_MODE=true
+BOX_FHIR_SEARCH_COMPARISONS=true
+BOX_FHIR_JSON_SCHEMA_DATETIME_REGEX='#{:fhir-datetime}'
+BOX_FHIR_SEARCH_INCLUDE_CONFORMANT=true
+BOX_FHIR_SEARCH_AUTHORIZE_INLINE_REQUESTS=true
+BOX_SECURITY_AUDIT_LOG_ENABLED=true
+
+BOX_INIT_BUNDLE=file:///tmp/init-bundle.json
+
+POSTGRES_PORT="5432"
+POSTGRES_USER=postgres
+POSTGRES_PASSWORD=postgres
+POSTGRES_DB=aidbox
+
+BOX_DB_HOST=aidbox-db
+BOX_DB_PORT="5432"
+BOX_DB_USER=postgres
+BOX_DB_PASSWORD=postgres
+BOX_DB_DATABASE=aidbox
+BOX_DB_POOL_MAXIMUM_POOL_SIZE=8
+
+BOX_WEB_THREAD=8
+BOX_WEB_PORT=8888
+BOX_WEB_BASE_URL=http://aidbox:8888
+
+BOX_ROOT_CLIENT_SECRET=secret
+BOX_ROOT_CLIENT_ID=root
+
+BOX_ADMIN_ID=admin
+BOX_ADMIN_PASSWORD=password
+
+APP_PORT=4000
+APP_URL=http://node-app:4000
+APP_SECRET=secret
+APP_CALLBACK_URL=/aidbox
+APP_ID=my-app
+
+BOX_SECURITY_AUTH_KEYS_SECRET=auth-key-secret
+BOX_SECURITY_AUTH_KEYS_PRIVATE="-----BEGIN RSA PRIVATE KEY-----\nMIIEpAIBAAKCAQEApbUYGNmCz1P8G0j/FFOjx1d5GNssJ/jj6xasSwTIbjjt6FtY\nCDw8o7hayOc/u8aUqXCGhK3JD2T9gtKv9/rV30w4YzmHhA8OOuLJE7tfh/PJA4Hn\n4i2JJ30BuoZ7rPTlTRGdc1FS3XFdmBQtnplEkJ7y8qbdrVme3Kbtn+BR1BdtgwSy\nbpNH2yqh3bb6PwpgNSMH7BIkBWL4A6QDpaFf1/9jSNE1vO25ssLC+bhFQNWLYriu\n+HogzEf9NWIrR2W29mI1QiA7wqvEuhg1yx38ylWD8GhCGL6+2QLKBYgp7DIGv6Uo\nTnqcVISatdQ51lVcCPmU6L1BhmcXVti6dWBI+wIDAQABAoIBAFKMOcJbTKpKvLq8\n7PErz1lFDpreyArrlmKsy0ydx9j8vCt1oY+MrmqisnsFk/7PaIxV9XUP+6qTFSUA\nHtAKYVOZLTfk10jmlSCpjCCrxWW9AISiSKkoJPyKbfuE9gRNhRMU9NoXB5Av4r+Z\nQbaRxJHE1OMjVCgAjr592786qJjd+shhY8ZLchrxctpBj6/4T2Rd4Q8ltyEV3hiy\noYaFVp9g332bFw7jZSuxgedZojNO6xPvbparTAgVDDwKB+CVUhuZ5EXWwemRvwoc\nYZM1UKPgtCqBZwm2GRv7s6XzJKBAZEMxcL7hS0RfijCe4MJcZlUCoM43Tf5XqDlT\nMmoXnPECgYEA4dkY/uqDLjJep5+4imRbceotxV2CZoJRQ0D85Ewu3tm9zdXhqL4p\n3XAOcNnqj7xBP3qkb/cXZumwdAIZns4kO1kw5hVQLX+xwMAJuravxp8sYJkx3CLO\noaOPNnlhGRv35fg4ZnoHHMO2C0wUmtSqsi6vE1EObYsIIFil58pI0NECgYEAu9SL\ne6AUCI/sdDlrTXQ8fdW8XSSJYPhZHqAvOAZfkeG4uuA2Qzxe8yUSES7z5V29futl\nWU7x+FWfqzkjh8qerviydAEFxVOpZ99ih9VB9dAwz3nX3OCoz3EUFmQGtTMxQmbo\nfW9sT4E6R7Hpa5jKnYvixk6u4p3aoEaZI4KeUAsCgYEA2OC3hiQBcN1h1Com9o7E\n2bF93qebT4EZNDI2J62Y3NvPztfy6S4j2cd/tpMtEnY/WgwV2Ic5a9RBZEWYAM4I\nMQ3HTUtuQSL8uRIwxaIlTeEQpnq2TKUINGRyZGdO/OPEvIwO7SmFpvOx30tiBgTv\nHkiCS1RtPHhkh1tZhirUneECgYAxNmARVQDKuYLXdM/jbEgJJD4FHXSNHqSi/I9C\nm5DgtQZkmCg/d4rdI+JW9Dlc6DGlFmHog2GskiqSfxcLFhB7gZeoAziS2fexynqT\nYlG06QZQ5fij24z/RP5hW3XSdgY7AqF5c/8p2Y7+h+PDmDXGD4esM6NoprlIcxbe\nkfOOvwKBgQCoOpkW+OWnxPLawmG/gv8+s5CsfOPUpURwAjltSXz9LXvsJmWQPQVG\np4sKEOJidYyt24YrIHi9/UEqRi+uuRQ4zCuXS6UjXftjAarPIPGkL/1S6B1Z91zg\nE5C0rXOvAlrvK09p4HGXLrwQxjrWt8R7rPvaD2yqVKLP4liFj8RMdg==\n-----END RSA PRIVATE KEY-----\n"
+BOX_SECURITY_AUTH_KEYS_PUBLIC="-----BEGIN PUBLIC KEY-----\nMIIBIjANBgkqhkiG9w0BAQEFAAOCAQ8AMIIBCgKCAQEApbUYGNmCz1P8G0j/FFOj\nx1d5GNssJ/jj6xasSwTIbjjt6FtYCDw8o7hayOc/u8aUqXCGhK3JD2T9gtKv9/rV\n30w4YzmHhA8OOuLJE7tfh/PJA4Hn4i2JJ30BuoZ7rPTlTRGdc1FS3XFdmBQtnplE\nkJ7y8qbdrVme3Kbtn+BR1BdtgwSybpNH2yqh3bb6PwpgNSMH7BIkBWL4A6QDpaFf\n1/9jSNE1vO25ssLC+bhFQNWLYriu+HogzEf9NWIrR2W29mI1QiA7wqvEuhg1yx38\nylWD8GhCGL6+2QLKBYgp7DIGv6UoTnqcVISatdQ51lVcCPmU6L1BhmcXVti6dWBI\n+wIDAQAB\n-----END PUBLIC KEY-----\n"

aidbox-custom-operations/fhir-api-intersept/Dockerfile

@@ -0,0 +1,12 @@
+FROM node:18-alpine
+
+WORKDIR /app
+
+COPY package*.json ./
+RUN npm ci
+
+COPY . .
+
+EXPOSE 4000
+
+CMD ["npm", "run", "dev"] 

aidbox-custom-operations/fhir-api-intersept/README.md

@@ -0,0 +1,127 @@
+---
+features: [API interception, Custom operations, Fastify, App framework, FHIR extensions]
+languages: [TypeScript]
+---
+# Aidbox: Intercept a FHIR endpoint
+
+This example demonstrates how to intercept a standard Aidbox FHIR endpoint with a custom application, apply extra logic, and then continue the normal persistence flow through Aidbox.
+
+Aidbox provides the ["App" functionality](https://docs.aidbox.app/app-development/aidbox-sdk/apps), which allows you to create an App entity and define operations for FHIR requests. In this example, Aidbox delegates `POST /fhir/Encounter` to a Node.js service. The service updates the incoming Encounter resource, sends the modified resource back to Aidbox, and returns Aidbox's response to the original caller.
+
+## How it works?
+
+You define an App entity in Aidbox that points to your custom HTTP server. Then, you register an Operation entity that tells Aidbox to delegate matching FHIR requests to your App.
+
+We use the [init-bundle logic](https://docs.aidbox.app/configuration/init-bundle), which loads the App and Operation resources into Aidbox as a FHIR transactional bundle on startup (`./init-bundle.json`).
+Aidbox expects the Node.js service to be available at `http://host.docker.internal:4000`, as defined in the App resource.
+
+```JSON
+{
+  "type": "transaction",
+  "entry": [
+    {
+      "resource": {
+        "id": "node-service-1",
+        "resourceType": "App",
+        "apiVersion": 1,
+        "type": "app",
+        "endpoint": { "url": "http://host.docker.internal:4000", "type": "http-rpc", "secret": "secret" }
+      },
+      "request": { "method": "PUT", "url": "/App/node-service-1" }
+    }, {
+      "resource": {
+        "id": "encounter-fhir-api",
+        "resourceType": "Operation",
+        "app": { "reference": "App/node-service-1" },
+        "module": "node-service-1",
+        "action": "proto.app/endpoint",
+        "request": ["post", "fhir", "Encounter"]
+      },
+      "request": { "method": "PUT", "url": "/Operation/encounter-fhir-api" }
+    }
+  ]
+}
+```
+
+The interception logic is implemented in `src/index.ts`:
+
+1. Aidbox receives `POST /fhir/Encounter`.
+2. Aidbox forwards the request to the Node.js service.
+3. The service adds an `identifier` to the Encounter:
+
+```JSON
+{
+  "system": "organization-1",
+  "value": "00001"
+}
+```
+
+4. The service calls Aidbox directly with `POST /Encounter` and the modified resource.
+5. The service returns Aidbox's response status and response body to the original client.
+
+This pattern is useful when you need to enrich, validate, audit, route, or call external systems before allowing the original FHIR operation to continue.
+
+## Prerequisites
+
+- Node.js >= 18.0
+- Docker (optional)
+
+
+## STEP 1: Environment and Aidbox license
+
+Copy `.env.tpl` file into `.env` file:
+
+```shell
+cp .env.tpl .env
+```
+
+If you are hosting Aidbox on your local computer, obtain the self-hosted license as described in the [documentation](https://docs.aidbox.app/getting-started/run-aidbox-locally-with-docker).
+
+Add the license (`AIDBOX_LICENSE`) int the .env file.
+
+## STEP 2: Run aidbox and node-app in Docker
+
+```shell
+npm install
+docker compose up
+```
+
+## Step 3: Open and log in into Aidbox instance
+
+Open in browser http://localhost:8888
+
+And log in with username: `admin` and password: `password`
+
+## Step 4: Request `POST /fhir/Encounter` using REST Console
+
+Aidbox delegates the request to the Node.js service using the App feature. The service intercepts the request, adds an Encounter identifier, persists the modified Encounter through Aidbox, and returns Aidbox's response.
+
+### You can test the endpoint using curl:
+
+```shell
+curl -H "Authorization: Basic cm9vdDpzZWNyZXQ=" \
+  -H "Content-Type: application/json" \
+  -X POST http://localhost:8888/fhir/Encounter \
+  -d '{
+    "resourceType": "Encounter",
+    "status": "planned",
+    "class": {
+      "system": "http://terminology.hl7.org/CodeSystem/v3-ActCode",
+      "code": "AMB",
+      "display": "ambulatory"
+    }
+  }'
+```
+
+The persisted Encounter contains the identifier added by the interception service:
+
+```JSON
+{
+  "identifier": [
+    {
+      "system": "organization-1",
+      "value": "00001"
+    }
+  ]
+}
+```

aidbox-custom-operations/fhir-api-intersept/build/index.d.ts

@@ -0,0 +1 @@
+export {};

aidbox-custom-operations/fhir-api-intersept/build/index.js

@@ -0,0 +1,64 @@
+import Fastify from 'fastify';
+import healthcheck from 'fastify-healthcheck';
+import dotenv from 'dotenv';
+const requestToString = (request) => {
+    return "/" + request.map((item) => {
+        if (typeof item === "string")
+            return item;
+        return `:${item.name}`;
+    }).join("/");
+};
+dotenv.config();
+if (!process.env.BOX_WEB_BASE_URL)
+    throw "BOX_WEB_BASE_URL is not provided!";
+if (!process.env.BOX_ROOT_CLIENT_ID)
+    throw "BOX_ROOT_CLIENT_ID is not provided!";
+if (!process.env.BOX_ROOT_CLIENT_SECRET)
+    throw "BOX_ROOT_CLIENT_SECRET is not provided!";
+console.log(process.env.BOX_WEB_BASE_URL);
+const aidbox = async (path, options = {}) => {
+    const url = `${process.env.BOX_WEB_BASE_URL}${path}`;
+    const username = process.env.BOX_ROOT_CLIENT_ID;
+    const password = process.env.BOX_ROOT_CLIENT_SECRET;
+    const basic = Buffer.from(`${username}:${password}`).toString('base64');
+    const headers = {
+        ...(options.headers || {}),
+        'Authorization': `Basic ${basic}`,
+        'Content-Type': 'application/json',
+    };
+    return fetch(url, { ...options, headers });
+};
+const fastify = Fastify({
+    logger: true
+});
+fastify.register(healthcheck);
+fastify.post('/', async (req, res) => {
+    const { operation, request } = req.body;
+    const [method, ...rest] = operation.request;
+    console.log("Incoming request:", requestToString(rest));
+    console.log("Method:", method);
+    console.log("Data:", request.resource);
+    if ("/fhir/Encounter" === requestToString(rest) && method === "post") {
+        const encounter = { ...request.resource, identifier: [{ system: "organization-1", value: "00001" }] };
+        // Here you can do any kind of interception logic: run functions, make async http calls etc.
+        // In this case we update Encounter resource with identifier, save it and response with original OperationOutcome:
+        const response = await aidbox('/Encounter', { method: "POST", body: JSON.stringify(encounter) });
+        const operationOutcome = await response.json();
+        console.dir(operationOutcome);
+        return res.status(response.status).send(operationOutcome);
+    }
+    return res.status(404).send({ error: "Not Supported" });
+});
+const start = async () => {
+    try {
+        const port = process.env.APP_PORT ? parseInt(process.env.APP_PORT) : 4000;
+        const host = '0.0.0.0';
+        await fastify.listen({ port, host });
+        fastify.log.info(`Server listening on ${host}:${port}`);
+    }
+    catch (err) {
+        fastify.log.error(err);
+        process.exit(1);
+    }
+};
+start();

aidbox-custom-operations/fhir-api-intersept/build/tsconfig.tsbuildinfo

@@ -0,0 +1 @@
+{"root":["../src/index.ts"],"version":"5.8.3"}

aidbox-custom-operations/fhir-api-intersept/docker-compose.yaml

@@ -0,0 +1,37 @@
+volumes:
+  pg_data:
+    name: pg_data
+services:
+  aidbox-db:
+    image: healthsamurai/aidboxdb:16.1
+    pull_policy: always
+    ports:
+      - "${PGHOSTPORT}:5432"
+    volumes:
+      - "pg_data:/data:delegated"
+    environment:
+      POSTGRES_USER: "${PGUSER}"
+      POSTGRES_PASSWORD: "${PGPASSWORD}"
+      POSTGRES_DB: "${PGDATABASE}"
+
+  aidbox:
+    image: healthsamurai/aidboxone:edge
+    # pull_policy: always
+    depends_on: ["aidbox-db"]
+    volumes:
+      - ./init-bundle.json:/tmp/init-bundle.json
+    ports:
+      - "${BOX_WEB_PORT}:${BOX_WEB_PORT}"
+    env_file:
+      - .env
+
+  app:
+    build: .
+    ports:
+      - "${APP_PORT:-4000}:4000"
+    env_file:
+      - .env
+    volumes:
+      - ./src:/app/src
+      - ./nodemon.json:/app/nodemon.json
+    depends_on: ["aidbox"]

aidbox-custom-operations/fhir-api-intersept/init-bundle.json

@@ -0,0 +1,25 @@
+{
+  "type": "transaction",
+  "entry": [
+    {
+      "resource": {
+        "id": "node-service-1",
+        "resourceType": "App",
+        "apiVersion": 1,
+        "type": "app",
+        "endpoint": { "url": "http://host.docker.internal:4000", "type": "http-rpc", "secret": "secret" }
+      },
+      "request": { "method": "PUT", "url": "/App/node-service-1" }
+    }, {
+      "resource": {
+        "id": "encounter-fhir-api",
+        "resourceType": "Operation",
+        "app": { "reference": "App/node-service-1" },
+        "module": "node-service-1",
+        "action": "proto.app/endpoint",
+        "request": ["post", "fhir", "Encounter"]
+      },
+      "request": { "method": "PUT", "url": "/Operation/encounter-fhir-api" }
+    }
+  ]
+}

aidbox-custom-operations/fhir-api-intersept/nodemon.json

@@ -0,0 +1,6 @@
+{
+  "watch": ["src"],
+  "ext": "ts",
+  "ignore": ["src/**/*.spec.ts"],
+  "exec": "node --loader ts-node/esm src/index.ts"
+}