FHIR client: typed German FHIR over any transport.

Real mode (default)

import { createFhirDeClient } from '@polaris/sdk/fhir'
import { FPDEPatientProfile } from '@polaris/fhir-de'

// Provide your own fetch-based transport
const myTransport = {
  async request(method, path, init) {
    const url = new URL(path, 'https://aidbox.example.com/fhir')
    if (init?.query) {
      for (const [k, v] of Object.entries(init.query)) {
        [v].flat().forEach(val => url.searchParams.append(k, val))
      }
    }
    const res = await fetch(url, {
      method,
      headers: {
        'Content-Type': 'application/json',
        Authorization: 'Basic ' + btoa('admin:secret'),
        ...init?.headers,
      },
      body: init?.body ? JSON.stringify(init.body) : undefined,
    })
    if (!res.ok) throw new Error(`HTTP ${res.status}`)
    return res.json()
  },
}

const client = createFhirDeClient({
  baseUrl: 'https://aidbox.example.com/fhir',
  transport: myTransport,
})

const patients = client.forProfile(FPDEPatientProfile, 'Patient')
const patient = await patients.read('pat-12345')
// patient is typed as FPDEPatientProfile | null

Anonymized mode

// POLARIS_ANON_SALT must be set before this call:
// process.env.POLARIS_ANON_SALT = 'demo-salt-replace-in-production-use-32-plus-random-bytes'
// In production, generate with: crypto.randomBytes(32).toString('hex')

import { createFhirDeClient } from '@polaris/sdk/fhir'
import { FPDEPatientProfile } from '@polaris/fhir-de'

const client = createFhirDeClient({
  baseUrl: 'https://aidbox.example.com/fhir',
  transport: myTransport,
  piiMode: 'anonymized',  // wraps transport in AnonymizingTransport
})

// All responses have PII stripped:
// name, address, telecom, identifier, photo removed
// birthDate is NOT stripped (use purpose-limitation controls if needed)
// Resource IDs replaced with SHA-256 hashed versions
// Free text scanned for KV numbers, phone numbers, dates
const patients = client.forProfile(FPDEPatientProfile, 'Patient')
const patient = await patients.read('pat-12345')
// patient.name === undefined (stripped)
// patient.id === 'anon-3f8a2b1c94d7' (hashed)

Minimal fetch transport

import type { FhirTransport } from '@polaris/sdk/fhir'
import { FhirDeHttpError } from '@polaris/sdk/fhir'

function createFetchTransport(
  baseUrl: string,
  token: string
): FhirTransport {
  return {
    async request(method, path, init) {
      const url = new URL(path, baseUrl)
      if (init?.query) {
        for (const [k, vs] of Object.entries(init.query)) {
          ;[vs].flat().forEach(v => url.searchParams.append(k, v))
        }
      }
      const res = await fetch(url, {
        method,
        headers: {
          'Content-Type': 'application/json',
          Authorization: `Bearer ${token}`,
          ...init?.headers,
        },
        body: init?.body ? JSON.stringify(init.body) : undefined,
      })
      if (!res.ok) {
        const body = await res.json().catch(() => null)
        throw new FhirDeHttpError(res.status, body)
      }
      return res.json()
    },
  }
}

Axios transport (Node.js)

import axios from 'axios'
import type { FhirTransport } from '@polaris/sdk/fhir'
import { FhirDeHttpError } from '@polaris/sdk/fhir'

function createAxiosTransport(
  baseUrl: string,
  apiKey: string
): FhirTransport {
  const http = axios.create({
    baseURL: baseUrl,
    headers: { Authorization: `Basic ${apiKey}` },
  })
  return {
    async request(method, path, init) {
      try {
        const res = await http.request({
          method,
          url: path,
          params: init?.query,
          data: init?.body,
          headers: init?.headers,
        })
        return res.data
      } catch (err: any) {
        if (axios.isAxiosError(err) && err.response) {
          throw new FhirDeHttpError(
            err.response.status,
            err.response.data
          )
        }
        throw err
      }
    },
  }
}

Paginating search results

import {
  createFhirDeClient,
  extractNextPageUrl,
} from '@polaris/sdk/fhir'
import { FPDEPatientProfile } from '@polaris/fhir-de'

const client = createFhirDeClient({ baseUrl, transport })
const patients = client.forProfile(FPDEPatientProfile, 'Patient')

// Collect all pages
const allPatients: FPDEPatientProfile[] = []

// First page via search()
let page = await patients.search({ _count: '50' })
allPatients.push(...page)

// Subsequent pages using the raw bundle link
let bundle = await transport.request('GET', 'Patient?_count=50') as any
let nextUrl = extractNextPageUrl(bundle)
while (nextUrl) {
  bundle = await transport.request('GET', nextUrl) as any
  // extract entries from bundle.entry
  nextUrl = extractNextPageUrl(bundle)
}

Null safety

import { extractNextPageUrl } from '@polaris/sdk/fhir'

// Safe on malformed or missing bundles:
extractNextPageUrl(null)        // → null
extractNextPageUrl(undefined)   // → null
extractNextPageUrl({})          // → null (no link field)
extractNextPageUrl({ link: [] }) // → null (no next relation)

// Only returns a value when relation === 'next' exists:
extractNextPageUrl({
  link: [
    { relation: 'self', url: 'https://aidbox.example.com/fhir/Patient' },
    { relation: 'next', url: 'https://aidbox.example.com/fhir/Patient?_page=2' },
  ],
})
// → 'Patient?_page=2'

Unit test example

import {
  createFhirDeClient,
  createMockFhirTransport,
} from '@polaris/sdk/fhir'
import { FPDEPatientProfile } from '@polaris/fhir-de'

// Pre-load a fixture patient
const mock = createMockFhirTransport({
  fixtures: [{
    resourceType: 'Patient',
    id: 'test-patient-1',
    meta: { profile: ['https://fhir.cognovis.de/praxis/StructureDefinition/fpde-patient'] },
    name: [{ family: 'Mustermann', given: ['Max'] }],
    birthDate: '1980-05-12',
  }],
})

const client = createFhirDeClient({
  baseUrl: 'http://mock',
  transport: mock,
})
const patients = client.forProfile(FPDEPatientProfile, 'Patient')

// In your test:
const patient = await patients.read('test-patient-1')
// → the fixture, fully typed

// Inspect the store
console.log(mock.store.size)  // 1

Create & verify in tests

import {
  createFhirDeClient,
  createMockFhirTransport,
} from '@polaris/sdk/fhir'
import { FPDECoverageGKVProfile } from '@polaris/fhir-de'

// Start with empty store (no fixtures)
const mock = createMockFhirTransport()

const client = createFhirDeClient({
  baseUrl: 'http://mock',
  transport: mock,
})
const coverages = client.forProfile(FPDECoverageGKVProfile, 'Coverage')

// POST a pre-built resource
const cov = await coverages.createResource(myCoverageResource)

// Verify the store was updated
console.log(mock.store.has(cov.id!))  // true

// Delete and verify
await coverages.delete(cov.id!)
console.log(mock.store.has(cov.id!))  // false