@polaris/sdk documentation.
@polaris/sdk is the unified MIRA-facing SDK facade. It exposes two subpath exports: @polaris/sdk/fhir for the typed FHIR client and @polaris/sdk/llm for capability-based LLM gateway types. The low-level @polaris/fhir-de package remains available for resource builders and generated profile classes.
@polaris/sdk/fhir
Typed FHIR client — createFhirDeClient, FhirDeClient, transport SPI, error types, AnonymizingTransport, and mock transport.
Full API reference →
@polaris/sdk/llm
LLM gateway types — AnonymizedPrompt, routeRequest, scanForPii, capability and intent types. Hono and server-runtime symbols are excluded; js-yaml and zod are bundled inline.
Full API reference →
Sections
Eight sections. All stable.
Every section here documents what is in the published package today. Surfaces under development are marked explicitly in-work where applicable. The FHIR Client API section covers the full @polaris/sdk/fhir surface. The LLM Gateway section covers capability-based model routing via @polaris/sdk/llm.
getting started
stableInstall, configure registry, and build your first resource.
Registry setup for npm.cognovis.de, install instructions for @polaris/sdk, and working first examples for both FHIR client and LLM gateway types.
resource builders
stableSeven core resource builders with working examples.
Patient, Practitioner, PractitionerRole, Organization, Encounter, Condition, and Claim — real import paths and examples that match the shipped builders.
api examples
stableCopyable API examples for MIRA workflows.
Patient lookup, patient writes, encounters, ChargeItems, and encounter billing lookup using the published SDK surface.
extensions
stableGerman extensions: BSNR, LANR, versichertenArt, GKV/PKV.
IG-only constants exported from @polaris/fhir-de. No hardcoded URLs — import the constant and the URL stays correct as the IG evolves.
version policy
stableCanonical base URL, version pinning, and changelog format.
Canonical base is https://fhir.cognovis.de/praxis/. In v0.x, pin to an exact version — minor versions may carry breaking changes.
integration
stableStandalone Aidbox vs Polaris platform usage.
Two modes: use createFhirDeClient directly against your own Aidbox, or integrate via the Polaris platform adapter endpoints.
troubleshooting
stableCommon validation errors and fixes.
Organization.address type required, birthDate absent vs empty string, meta pattern, Transport SPI, FhirDeProfileMismatchError, and registry auth errors.
fhir client api
stableFull API reference for @polaris/sdk/fhir.
createFhirDeClient, FhirDeClient, ResourceClient, FhirTransport SPI, AnonymizingTransport, extractNextPageUrl, error classes, and createMockFhirTransport — with TypeScript signatures, descriptions, and runnable examples.
Package names
The recommended package is @polaris/sdk. The registry is npm.cognovis.de — not the public npm registry. @polaris/fhir-de is available for low-level access.
No server deps in /llm
@polaris/sdk/llm excludes Hono and server-runtime symbols. js-yaml and zod are bundled inline — no separate node_modules entries are needed; consumers get them at zero extra install cost. Server-only symbols (createApp, loadCatalogFromFile) are intentionally excluded.
IG-only policy
No extension URLs are hardcoded in application code. All constants are imported from @polaris/fhir-de, which sources them from the canonical IGs at fhir.cognovis.de/praxis/.