fee-schedules/readme.md

# @fin.cx/fee-schedules

`@fin.cx/fee-schedules` is a TypeScript package for country-specific fee schedule data. It gives apps a clean, searchable source of truth for statutory, contractual, and professional fee schedules, starting with Germany's healthcare, legal, court, public compensation, and regulated professional service schedules.

Use it when you need stable identifiers, abbreviations, imported fee table rows, source metadata, and rule sections for fee systems such as `GOÄ`, `GOZ`, `RVG`, `GNotKG`, `GKG`, `HOAI`, `JVEG`, and more.

## Issue Reporting and Security

For reporting bugs, issues, or security vulnerabilities, please visit [community.foss.global/](https://community.foss.global/). This is the central community hub for all issue reporting. Developers who sign and comply with our contribution agreement and go through identification can also get a [code.foss.global/](https://code.foss.global/) account to submit Pull Requests directly.

## Installation

```bash
pnpm add @fin.cx/fee-schedules
```

## Quick Start

```ts
import { FEE_SCHEDULE_CATALOGS, FeeSchedules, feeSchedules } from '@fin.cx/fee-schedules';

const schedules = new FeeSchedules();
const germanyCatalog = FEE_SCHEDULE_CATALOGS.find((catalog) => catalog.countryCode === 'DE');

const germany = schedules.getByCountry('DE');
const goae = schedules.findByAbbreviation('GOÄ');
const goaeNumber1 = schedules.getFeeRow('de-goae', '1');
const legalFeeRows = schedules.searchFeeRows('Einigungsgebühr', 'de-rvg');
const courtFees = feeSchedules.getById('de-gkg');

console.log(germanyCatalog?.schedules.length); // 21
console.log(goae?.description); // Gebührenordnung für Ärzte; privatärztliche Leistungen außerhalb GKV.
console.log(goaeNumber1?.cells); // ['1', 'Beratung - auch mittels Fernsprecher -', '80', '9,12']
console.log(legalFeeRows.map((item) => item.code));
console.log(courtFees?.area); // Gerichte allgemein
console.log(germany.map((item) => item.id));
```

## What You Get

- Country catalogs with stable country codes and country names.
- Individual fee schedule records with stable IDs, abbreviations, areas, and short descriptions.
- Imported fee rows and rule sections for official federal XML schedules.
- Lookup helpers for country code, ID, abbreviation, fee code, and free-text search.
- A ready-to-use singleton (`feeSchedules`) and a configurable class (`FeeSchedules`) for custom catalogs.
- TypeScript interfaces exported directly from the package.

## API

### Exports

| Export | Description |
| --- | --- |
| `FEE_SCHEDULE_DATA_URL` | Raw `code.foss.global` URL used for startup data loading. |
| `feeSchedulePayload` | Full remotely loaded payload. |
| `FEE_SCHEDULE_CATALOGS` | All available country catalogs from the remotely loaded payload. |
| `FEE_SCHEDULE_DATA` | Imported fee data, rule sections, source metadata, and import status from the remotely loaded payload. |
| `SUPPORTED_COUNTRY_CODES` | Country codes derived from `FEE_SCHEDULE_CATALOGS`. |
| `loadFeeSchedulePayload(url?)` | Loads and validates a fee schedule payload from a URL. |
| `FeeSchedules` | Lookup/search class. Can be constructed with the default catalog/data lists or custom lists. |
| `feeSchedules` | Default singleton instance of `FeeSchedules`. |

### Methods

| Method | Description |
| --- | --- |
| `getCountries()` | Returns all loaded country catalogs. |
| `getByCountry(countryCode)` | Returns schedules for a country code such as `DE`. Country lookup is case-insensitive. |
| `getById(id)` | Returns the schedule with the exact stable ID, or `undefined`. |
| `getDataByScheduleId(scheduleId)` | Returns imported source metadata, fee rows, rule sections, and data status. |
| `getFeeRows(scheduleId)` | Returns all imported fee rows for a schedule. |
| `getFeeRow(scheduleId, code)` | Returns the first imported coded fee row matching a schedule and code. |
| `getRuleSections(scheduleId)` | Returns imported rule sections for a schedule. |
| `findByAbbreviation(abbreviation, countryCode?)` | Returns the first schedule matching an abbreviation. Abbreviation lookup normalizes whitespace and casing. |
| `search(query, countryCode?)` | Searches `id`, `area`, `abbreviation`, and `description`. Returns an empty array for empty queries. |
| `searchFeeRows(query, scheduleId?)` | Searches imported fee rows and original source cells. |
| `searchRuleSections(query, scheduleId?)` | Searches imported rule sections. |

### Data Shape

```ts
export type TFeeScheduleCountryCode = string;

export interface IFeeSchedule {
  id: string;
  countryCode: TFeeScheduleCountryCode;
  area: string;
  abbreviation: string;
  description: string;
}

export interface ICountryFeeScheduleCatalog {
  countryCode: TFeeScheduleCountryCode;
  countryName: string;
  schedules: IFeeSchedule[];
}

export interface IFeeScheduleData {
  scheduleId: string;
  dataStatus: 'federal-law-fee-data' | 'federal-law-rules-only' | 'external-source-pending';
  edition: string;
  source: IFeeScheduleSource;
  feeRows: IFeeScheduleFeeRow[];
  ruleSections: IFeeScheduleRuleSection[];
  notes: string[];
}

export interface IFeeSchedulePayload {
  schemaVersion: number;
  generatedAt?: string;
  catalogs: ICountryFeeScheduleCatalog[];
  scheduleData: IFeeScheduleData[];
}
```

Fee rows preserve the original source cells in order. Where the row is code-based, `code`, `description`, `points`, and `amountEur` are populated when those values can be read directly from the source table.

```ts
const row = schedules.getFeeRow('de-goae', '1');

console.log(row?.cells);
// ['1', 'Beratung - auch mittels Fernsprecher -', '80', '9,12']
```

## Data Sources

The package imports official federal XML data from [gesetze-im-internet.de](https://www.gesetze-im-internet.de/) for these schedules: GOÄ, GOZ, GOP, GOT, StBVV, RVG, GNotKG, GKG, FamGKG, GvKostG, JVEG, InsVV, HOAI, and AMPreisV.

Some German fee schedules are not federal XML laws on `gesetze-im-internet.de`. They are represented with explicit `external-source-pending` source metadata until their source-specific importers are added: EBM, BEMA, aG-DRG / FPV, UV-GOÄ, Heilmittel GKV, Hebammenhilfevertrag, and GebüH.

## Generated Files

The npm package does not ship the catalog or fee data payload. Supported countries, schedule metadata, generation source config, fee rows, and rule sections live under `.onlygit/` in git.

Runtime startup loads the generated payload from:

```text
https://code.foss.global/fin.cx/fee-schedules/raw/branch/main/.onlygit/fee-schedules.json
```

Maintainers regenerate the git-only JSON payload with:

```bash
pnpm run generate:germany
```

The generator lives in `scripts/generate-germany.mjs`. It reads `.onlygit/fee-schedules.sources.json`, downloads the official XML ZIP files into `.nogit/fee-schedules-sources/`, extracts them, parses fee table rows and rule sections, and writes:

```text
.onlygit/fee-schedules.json
```

## Germany Catalog

The initial catalog covers 21 German fee schedule systems.

| ID | Area | Abbreviation | Purpose |
| --- | --- | --- | --- |
| `de-goae` | Ärzte privat | `GOÄ` | Gebührenordnung für Ärzte; privatärztliche Leistungen außerhalb GKV. |
| `de-goz` | Zahnärzte privat | `GOZ` | Gebührenordnung für Zahnärzte; privat-/selbst zu zahlende zahnärztliche Leistungen. |
| `de-gop` | Psychotherapeuten privat | `GOP` | Gebührenordnung für Psychologische Psychotherapeuten und Kinder-/Jugendlichenpsychotherapeuten. |
| `de-ebm` | Ärzte GKV | `EBM` | Einheitlicher Bewertungsmaßstab; Abrechnung von Vertragsärzten und Vertragspsychotherapeuten mit der GKV. |
| `de-bema` | Zahnärzte GKV | `BEMA` | Bewertungsmaßstab zahnärztlicher Leistungen; GKV-Abrechnung in Zahnarztpraxen. |
| `de-ag-drg-fpv` | Krankenhäuser | `aG-DRG / FPV` | Fallpauschalen-Katalog und Abrechnungsbestimmungen für stationäre Krankenhausfälle. |
| `de-uv-goae` | Berufsgenossenschaft/Unfallversicherung | `UV-GOÄ` | Gebührenordnung für Ärzte im Bereich gesetzliche Unfallversicherung. |
| `de-got` | Tierärzte | `GOT` | Gebührenordnung für Tierärztinnen und Tierärzte. |
| `de-stbvv` | Steuerberater | `StBVV` | Steuerberatervergütungsverordnung; gesetzliche Vergütung für steuerberatende Vorbehaltsaufgaben. |
| `de-rvg` | Rechtsanwälte | `RVG` | Rechtsanwaltsvergütungsgesetz mit Vergütungsverzeichnis. |
| `de-gnotkg` | Notare / Grundbuch / Nachlass | `GNotKG` | Gerichts- und Notarkostengesetz; bundesweit einheitliche Notarkosten. |
| `de-gkg` | Gerichte allgemein | `GKG` | Gerichtskostengesetz mit Kostenverzeichnis und Gebührentabellen. |
| `de-famgkg` | Familiengericht | `FamGKG` | Gerichtskosten in Familiensachen. |
| `de-gvkostg` | Gerichtsvollzieher | `GvKostG` | Gerichtsvollzieherkostengesetz mit Kostenverzeichnis. |
| `de-jveg` | Sachverständige/Dolmetscher/Zeugen bei Gericht | `JVEG` | Justizvergütungs- und -entschädigungsgesetz. |
| `de-insvv` | Insolvenzverwalter | `InsVV` | Insolvenzrechtliche Vergütungsverordnung. |
| `de-hoai` | Architekten/Ingenieure | `HOAI` | Honorarordnung für Architekten und Ingenieure; heute vor allem Orientierungs-/Auffangsystem für erfasste Planungsleistungen. |
| `de-heilmittel-gkv` | Heilmittel, z. B. Physio/Logo/Ergo | `keine einzelne GO` | GKV-Vergütungsvereinbarungen/Preislisten nach Bundesrahmenverträgen. |
| `de-hebammenhilfevertrag` | Hebammen GKV | `Hebammenhilfevertrag` | Vertrag/Vergütungsvereinbarung nach § 134a SGB V. |
| `de-ampreisv` | Apotheken/Rx-Arzneimittel | `AMPreisV` | Arzneimittelpreisverordnung; Preisbildung für verschreibungspflichtige Arzneimittel. |
| `de-gebueh` | Heilpraktiker | `GebüH` | Gebührenverzeichnis für Heilpraktiker; keine amtliche verbindliche Gebührenordnung, eher Orientierung/übliche Vergütung. |

## Typical Use Cases

- Build country-aware fee schedule selectors.
- Normalize German fee schedule abbreviations in forms and admin systems.
- Enrich billing, compliance, procurement, or legal-tech workflows with stable fee schedule metadata.
- Power search, autocomplete, or classification flows without hand-maintaining the same acronym list in every app.

## Scope

This package includes imported fee rows and rule sections for the German federal schedules currently available as official XML. It does not yet normalize every schedule into a single calculation engine because several schedules use different fee mechanics: points, factors, euro amounts, value tables, formula rules, or external annual catalogs.

## License and Legal Information

This repository contains open-source code licensed under the MIT License. A copy of the license can be found in the [license](./license) file.

**Please note:** The MIT License does not grant permission to use the trade names, trademarks, service marks, or product names of the project, except as required for reasonable and customary use in describing the origin of the work and reproducing the content of the NOTICE file.

### Trademarks

This project is owned and maintained by Task Venture Capital GmbH. The names and logos associated with Task Venture Capital GmbH and any related products or services are trademarks of Task Venture Capital GmbH or third parties, and are not included within the scope of the MIT license granted herein.

Use of these trademarks must comply with Task Venture Capital GmbH's Trademark Guidelines or the guidelines of the respective third-party owners, and any usage must be approved in writing. Third-party trademarks used herein are the property of their respective owners and used only in a descriptive manner, e.g. for an implementation of an API or similar.

### Company Information

Task Venture Capital GmbH  
Registered at District Court Bremen HRB 35230 HB, Germany

For any legal inquiries or further information, please contact us via email at hello@task.vc.

By using this repository, you acknowledge that you have read this section, agree to comply with its terms, and understand that the licensing of the code does not imply endorsement by Task Venture Capital GmbH of any derivative works.