@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')

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.