Common errors and fixes.

Fix

import { buildPatient } from '@polaris/fhir-de'

// Correct: do not pass birthDate at all when not known
const patient = buildPatient({
  id: 'pat-001',
  firstName: 'Anna',
  lastName: 'Müller',
  // birthDate: undefined    ← omit the key entirely
  // birthDate: ''           ← this causes 422
})

// buildPatient() handles this automatically:
// it deletes the birthDate key when the value is falsy.

// If you build the resource manually, use:
const resource = { resourceType: 'Patient', name: [{ use: 'official', family: 'Müller' }] }
// Do NOT add: resource.birthDate = ''

Fix

import { createFhirDeClient, FhirDeHttpError } from '@polaris/fhir-de'
import type { FhirTransport } from '@polaris/fhir-de'

// You must implement FhirTransport
const baseUrl = 'https://aidbox.example.com/fhir'

const transport: FhirTransport = {
  async request(method, path, init) {
    const normalizedPath = path.startsWith('/') ? path : `/${path}`
    const url = new URL(`${baseUrl.replace(/\/$/, '')}${normalizedPath}`)

    if (init?.query) {
      for (const [key, value] of Object.entries(init.query)) {
        const values = Array.isArray(value) ? value : [value]
        for (const item of values) url.searchParams.append(key, item)
      }
    }

    const res = await fetch(url, {
      method,
      headers: {
        'Content-Type': 'application/fhir+json',
        Accept: 'application/fhir+json',
        'Authorization': `Bearer ${process.env.AIDBOX_TOKEN}`,
        ...init?.headers,
      },
      body: init?.body == null ? undefined : JSON.stringify(init.body),
    })

    const body = res.status === 204 ? null : await res.json().catch(() => null)
    if (!res.ok) throw new FhirDeHttpError(res.status, body)
    return body
  },
}

// Then pass it to createFhirDeClient
const client = createFhirDeClient({
  baseUrl,
  transport,
})

Fix

# Set the env var before starting your process:
export POLARIS_ANON_SALT="your-secret-salt-string"

# Or in a .env file (loaded by Bun automatically):
POLARIS_ANON_SALT=your-secret-salt-string

# In tests you can pass the salt explicitly instead of using the env var:
import { AnonymizingTransport } from '@polaris/fhir-de'

const anonTransport = new AnonymizingTransport(transport, 'test-salt')
const client = createFhirDeClient({ baseUrl, transport: anonTransport })

// Note: the salt must remain stable across deployments.
// Changing it changes all hashed IDs — anon-<hash> values are no longer
// consistent with previously returned hashes.