@icure/medindex-sdk

Thin TypeScript SDK for iCure's medINDEX REST layer (the Swiss medication reference database, served by hci-medication-module's standalone Spring Boot module in hci-medication-importer).

This SDK is deliberately independent of iCure's sdk-codegen/Kotlin-Multiplatform pipeline — see docs/adr/0001-openapi-based-not-sdk-codegen.md for why. Types are generated from the standalone server's own OpenAPI spec; the client wrapper on top is hand-written.

Status

src/types/generated.ts is real openapi-typescript output, generated from a live standalone server's OpenAPI spec (see openapi.json, a manually-regenerated snapshot). Do not hand-edit it — re-run npm run regenerate-spec (see scripts/regenerate-spec.sh) against a live standalone server whenever the backend DTOs change. src/types/dto.ts is the one hand-maintained file: it aliases generated.ts's components['schemas'][...] types to the flat names the rest of the SDK uses.

Usage (once published)

import { MedIndexClient } from '@icure/medindex-sdk'

const client = new MedIndexClient({ baseUrl: 'https://medindex.example.com/rest/v2/medindex' })

for await (const product of client.product.iterateByLabel('aspirin', 'de')) {
  console.log(product.brandName)
}

// Search by active substance/molecule name, or by ATC code / class prefix.
// Both need a server new enough to expose /product/bySubstance and /product/byAtc (0.2.0+ pairing) — older servers 404.
for await (const product of client.product.iterateBySubstance('paracetamol', 'de')) {
  console.log(product.brandName)
}
for await (const product of client.product.iterateByAtc('N02BE01')) {
  console.log(product.brandName)
}

// Every product/package search accepts { activeOnly: false } to include records the source
// has soft-deleted (server default: active only).
for await (const product of client.product.iterateByLabel('aspirin', 'de', { activeOnly: false })) {
  console.log(product.active, product.names.de)
}

// Full price history of a package — every raw price row, active and historical alike, unlike
// the package's own current-only `prices` snapshot. Rows exist only for data imported by a
// server new enough to map them.
const history = await client.price.byPackageId('medpkg:7680123')

// A product's published monograph (medINDEX Brevier): the product carries only an id + title
// reference; fetch the monograph for its Markdown sections (indications, posology,
// contra-indications - never HTML) and its structured composition. Needs a server exposing
// /monograph (0.4.0+ pairing) and a data import run since that upgrade - older servers 404.
const product = await client.product.byId('medprod:1000143')
if (product.monograph?.id) {
  const monograph = await client.monograph.byId(product.monograph.id)
  console.log(monograph.titles.de, monograph.posology.de, monograph.composition)
}

// The Swiss healthcare-provider register (physicians, pharmacies, hospitals, ...), keyed by
// GLN. Name search is word-prefix over family and given name, optionally narrowed to one
// provider type (D physician, O other, P pharmacy, H hospital). Same 0.4.0+ server requirement.
for await (const provider of client.serviceProvider.iterateByName('dorta', { type: 'D' })) {
  console.log(provider.title, provider.name, provider.additionalName, provider.addresses[0]?.city)
}
const provider = await client.serviceProvider.byGln('7601000014429')

Servers paired with 0.4.0 also expose more on the existing types, with no SDK call needed: MedicationProductDto.genericCode, .monographId and .monograph (the reference above), a group (which side of the interaction the product sits on) and title on each entry of .interactions, MedicationPackageDto.tradeStatus, .insuranceCodes and .specialtyList (reimbursement-list membership and Spezialitätenliste data), and MedIndexVersionDto.htmlTagCounts. Price row ids gained a trailing :{validFrom} segment (medprice:{pharmacode}:{partnerId}:{priceType}:{validFrom}).

Development

npm install
npm run build       # tsup -> dist/ (ESM + CJS + .d.ts)
npm test            # vitest
npm run typecheck   # tsc --noEmit

Error handling

Every failure mode throws a typed error (see src/errors.ts): MedIndexNotFoundError, MedIndexValidationError, MedIndexServerError, MedIndexNetworkError — all extending MedIndexError.

Publishing

Tag a commit with a semver tag (vX.Y.Z) on main; the publish GitHub Actions workflow builds, tests, and publishes to the public npm registry under @icure/medindex-sdk.