# SDK

> Klienti Dart / Flutter (anpheros_sdk) a TypeScript (@anpheros/sdk): stejný tvar, idempotentní vytváření, opakované pokusy, obnovení tokenu a tok souhlasu.

Source: https://developers.anpheros.com/cs/guides/sdks

> Oficiální klientské knihovny pro FHIR R4 healthcare API s bezplatným FHIR sandboxem: pacienti, pozorování, laboratorní výsledky, stavy, léky, International Patient Summary, souhlas pacienta a AI kontext, v TypeScript a Dart / Flutter.

**Anpheros je interoperabilní infrastruktura pro lékařská data pro vytváření zdravotnických aplikací, lékařského softwaru a AI služeb.** Každý pacient má jeden HL7 FHIR R4 záznam, který ovládá; aplikace, kliniky, laboratoře a AI agenti jej čtou a zapisují prostřednictvím Anpheros Platform API — se souhlasem pacienta (OAuth 2.1 / SMART on FHIR), s údaji o původu při každém zápisu a s logem přístupu, které může pacient vidět. Tento repozitář obsahuje oficiální klientské knihovny a spustitelné příklady.

| Jazyk | Balíček | Instalace | Zdroj |
|---|---|---|---|
| Dart / Flutter | [`anpheros_sdk`](https://pub.dev/packages/anpheros_sdk) | `dart pub add anpheros_sdk` | [`dart/anpheros_sdk`](https://github.com/anpheros/anpheros-sdk/tree/main/dart/anpheros_sdk) |
| TypeScript (Node 18+, prohlížeče, Deno, Bun) | [`@anpheros/sdk`](https://www.npmjs.com/package/@anpheros/sdk) | `npm install @anpheros/sdk` | [`ts`](https://github.com/anpheros/anpheros-sdk/tree/main/ts) |

## Rychlý start za 2 minuty

1. **Získejte bezplatný klíč pro sandbox:** přihlaste se na [dashboard](https://platform.anpheros.com/dashboard/) a klikněte na **Get a sandbox key** (`sk_test_…`). Váš sandbox obsahuje 30 syntetických pacientů.
2. **Ověřte funkčnost:**

   ```bash
   curl -H "Authorization: Bearer $ANPHEROS_KEY" "https://platform.anpheros.com/fhir/R4/Patient?_count=3"
   ```

3. **Nainstalujte SDK a načtěte záznam:** `npm install @anpheros/sdk` nebo `dart pub add anpheros_sdk`, poté spusťte kód v sekci [Connect](#connect), nebo naklonujte repozitář [quickstart-ts](https://github.com/anpheros/anpheros-sdk/tree/main/examples/quickstart-ts).

## Pro koho je určen

Vývojáři vytvářející aplikace pro zdraví pacientů a rodiny, backendy lékařských aplikací, integrace klinik a laboratoří a asistenty či agenty s umělou inteligencí, kteří potřebují strukturovaný lékařský kontext pacienta – aniž by museli od nuly navrhovat databázi zdravotních záznamů, systém souhlasu a auditní záznam.

## Získání sandbox klíče

Sandbox je zdarma a samoobslužný. Přihlaste se pomocí Google na [dashboardu](https://platform.anpheros.com/dashboard/) a stiskněte **Získat sandbox klíč**: okamžitě získáte sandbox projekt a klíč. Každý sandbox projekt obsahuje 30 syntetických pacientů — šest měsíců stavů, léků, alergií, laboratorních výsledků a vitálních funkcí — které můžete libovolně měnit a kdykoli resetovat. Sandbox klíče (`sk_test_…`) se nikdy nedostanou k reálným datům pacientů.

Když přejdete do produkčního prostředí, produkce je určena pro ověřené organizace s dohodou o zpracování dat a produkce začíná od 99 € měsíčně s prvním měsícem zdarma ([ceny](https://developers.anpheros.com/cs/guides/pricing)).

## Připojení

```ts
import { Anpheros, apiKey } from '@anpheros/sdk';

const anpheros = new Anpheros({ auth: apiKey(process.env.ANPHEROS_KEY!) });   // sk_test_… in the sandbox
const { data: patients } = await anpheros.patients.list();
const labs = await anpheros.observations.list(patients[0].id, { category: 'laboratory', limit: 10 });
const ctx = await anpheros.context.build({ patient: patients[0].id, task: 'weekly check-in', budget_tokens: 1500, format: 'text' });
```

```dart
import 'package:anpheros_sdk/anpheros_sdk.dart';

final anpheros = Anpheros(auth: AnpherosAuth.apiKey('sk_test_…'));
final patients = await anpheros.patients.list();
final labs = await anpheros.observations.list(patients.data.first.id, category: 'laboratory', limit: 10);
```

API klíče patří na servery. Aplikace jednající jménem osoby používá místo toho OAuth: oba SDK implementují tok souhlasu (autorizační kód + PKCE) a automaticky obnovují tokeny.

## Co pokrývají SDK

Obě pokrývají celou veřejnou plochu (`/v1`, `/fhir/R4`, `/oauth/token`, `/oauth/revoke`) se stejným tvarem: `patients`, `observations`, `conditions`, `medications`, `documents`, `timeline`, `provenance`, `context`, `grants`, `terminology` a surové `fhir`. Test selže při sestavení, pokud v jednom z SDK chybí veřejná trasa, nebo když SDK volá trasu, kterou server nemá.

Obě SDK: automatické `Idempotency-Key` při vytváření, opakované pokusy s exponenciálním zpožděním při 429/5xx, jedno obnovení tokenu při 401, typované chyby s ID požadavku, pomocníci PKCE a tok souhlasu.

## Lékařská data a FHIR

Záznam se skládá ze standardních FHIR R4 zdrojů — 26 typů, včetně `Observation`, `Condition`, `MedicationStatement`, `DocumentReference`, `Immunization` a `AllergyIntolerance` — kódovaných pomocí LOINC, ICD-10, ATC a UCUM. REST API (`/v1`) a FHIR API (`/fhir/R4`) čtou a zapisují stejné zdroje se stejnými ID; `fhir` v obou SDK poskytuje přímý přístup k FHIR (vyhledávání, transakce, `$everything`, `$summary`, `$validate`).

## Příklady

| Příklad | Zobrazuje |
|---|---|
| [quickstart-ts](https://github.com/anpheros/anpheros-sdk/tree/main/examples/quickstart-ts) | zápis a čtení záznamu: měření, laboratorní výsledky, diagnózy, léky, časová osa, FHIR vyhledávání, IPS, kontext AI |
| [quickstart-dart](https://github.com/anpheros/anpheros-sdk/tree/main/examples/quickstart-dart) | totéž z Dart / Flutter |
| [consent-app-ts](https://github.com/anpheros/anpheros-sdk/tree/main/examples/consent-app-ts) | webová aplikace, která žádá o souhlas (OAuth 2.1 + PKCE) a čte záznam pacienta |
| [ai-context-llm](https://github.com/anpheros/anpheros-sdk/tree/main/examples/ai-context-llm) | otázka týkající se záznamu zodpovězená modelem dle vašeho výběru (lokální nebo hostovaný) |
| [fhir-transaction](https://github.com/anpheros/anpheros-sdk/tree/main/examples/fhir-transaction) | FHIR R4 transakční bundle a výsledný International Patient Summary |

Příklady běží proti bezplatnému sandboxu, kde každý sandbox projekt má svých 30 syntetických pacientů – viz [Získat klíč k sandboxu](#get-a-sandbox-key).

## Související repozitáře

| Repozitář | Co to je |
|---|---|
| [fhir-api-openapi](https://github.com/anpheros/fhir-api-openapi) | OpenAPI 3.1 spec a Postman kolekce API |
| [mcp-server](https://github.com/anpheros/mcp-server) | hostovaný FHIR MCP server pro AI agenty: konfigurace pro Claude, Cursor, VS Code |
| [agent-skills](https://github.com/anpheros/agent-skills) | Agent Skill, Claude Code plugin, pravidla pro Cursor a AGENTS.md |
| [fhir-synthetic-patients](https://github.com/anpheros/fhir-synthetic-patients) | 30 syntetických pacientů ve formátu FHIR R4 Bundles a NDJSON |
| [ips-examples](https://github.com/anpheros/ips-examples) | dokumenty International Patient Summary ve formátu FHIR R4 |
| [fhir-validate-action](https://github.com/anpheros/fhir-validate-action) | GitHub Action, která validuje FHIR R4 JSON v CI |
| [lab-results-to-fhir](https://github.com/anpheros/lab-results-to-fhir) | CLI: CSV / HL7 v2 laboratorní zprávy → FHIR Observations |
| [healthcare-app-starters](https://github.com/anpheros/healthcare-app-starters) | šablony pro zdravotnické aplikace v Next.js a Flutter |

## Shoda

Nezpracované výsledky testů, publikované pro kontrolu (výsledky testů, nikoli certifikace): [conformance/](https://github.com/anpheros/anpheros-sdk/tree/main/conformance). Dne 28. září 2026 skupina Standalone Launch testovací sady Inferno SMART App Launch STU2 (v1.0.3) prošla 22 z 22 testů proti platformě. Spuštění EHR není podporováno.

## Dokumentace

- [Průvodci pro vývojáře](https://developers.anpheros.com/guides/)
- [Začínáme](https://developers.anpheros.com/cs/guides/getting-started)
- [FHIR sandbox](https://developers.anpheros.com/cs/guides/fhir-sandbox)
- [Healthcare API](https://developers.anpheros.com/cs/guides/healthcare-api)
- [Platforma Healthcare API](https://developers.anpheros.com/cs/guides/healthcare-api-platform)
- [Platforma FHIR](https://developers.anpheros.com/cs/guides/fhir)
- [Průvodce SDK](https://developers.anpheros.com/cs/guides/sdks)
- [API reference (OpenAPI)](https://developers.anpheros.com/docs)
- [Pro AI asistenty](https://developers.anpheros.com/llms.txt)
- [Anpheros](https://anpheros.com/)

## Problémy a zabezpečení

Chyby nahlašujte v sekci issues tohoto repozitáře. Nikdy do issue nezahrnujte API klíče, tokeny ani data pacientů. Bezpečnostní hlášení: contact@anpheros.com.

## Licence

Apache License 2.0 — viz soubor `LICENSE` v každém balíčku. Copyright 2026 Anpheros.

## @anpheros/sdk

TypeScript klient pro **Anpheros Platform**: zdravotní záznam pacienta ve formátu FHIR R4, izolace projektů, souhlas pacienta (OAuth 2.1 / SMART on FHIR), sledování původu každého zápisu a kontextové API s umělou inteligencí. Běží kdekoli, kde existuje `fetch` (Node 18+, prohlížeče, Deno, Bun).

```ts
import { Anpheros, apiKey } from '@anpheros/sdk';

const anpheros = new Anpheros({ auth: apiKey(process.env.ANPHEROS_KEY!) });
const { data: patients } = await anpheros.patients.list();
const labs = await anpheros.observations.list(patients[0].id, { category: 'laboratory', limit: 10 });
const ctx = await anpheros.context.build({ patient: patients[0].id, task: 'weekly check-in', budget_tokens: 1500, format: 'text' });
```

Jednání jménem osoby:

```ts
import { OAuthFlow, OAuthAuth, generatePkce } from '@anpheros/sdk';

const flow = new OAuthFlow({ baseUrl: BASE, clientId: 'client_…', redirectUri: 'https://myapp.example/callback' });
const pkce = await generatePkce();
location.href = flow.authorizeUrl({ scopes: ['patient/Observation.rs?category=laboratory', 'offline_access'], state, pkce, lang: 'ro' });
// on the callback:
const tokens = await flow.exchange(code, pkce);
const anpheros = new Anpheros({ auth: new OAuthAuth({ tokens, onRefresh: flow.refresh, onTokens: persist }) });
```

Chyby jsou `AnpherosError` (`status`, `type`, `message`, `field`, `requestId`). Vytváření odesílá `Idempotency-Key`; 429/5xx se opakují; vypršené tokeny se jednou obnoví a volání se zopakuje.

## anpheros_sdk

Dart / Flutter klient pro **Anpheros Platform**: backend pro zdravotní data s FHIR R4 záznamem
na pacienta, izolací projektů, souhlasem pacienta (OAuth 2.1 / SMART on FHIR), sledováním původu u každého
zápisu a API pro kontext AI.

```dart
import 'package:anpheros_sdk/anpheros_sdk.dart';

final anpheros = Anpheros(auth: AnpherosAuth.apiKey('sk_test_…'));      // server / sandbox

final patients = await anpheros.patients.list();
final elena = patients.data.first;
final labs = await anpheros.observations.list(elena.id, category: 'laboratory', limit: 10);
final ctx = await anpheros.context.build(ContextRequest(patient: elena.id, task: 'weekly check-in', budgetTokens: 1500));
```

## Jednání jménem osoby (aplikace)

```dart
final flow = OAuthFlow(baseUrl: 'https://…', clientId: 'client_…', redirectUri: 'myapp://callback');
final pkce = Pkce.generate();
final url = flow.authorizeUrl(scopes: ['patient/Observation.rs?category=laboratory', 'patient/MedicationStatement.r', 'offline_access'],
                              state: 'abc', pkce: pkce, lang: 'ro');
// open `url`; on return with ?code=…:
final tokens = await flow.exchange(code: code, pkce: pkce);
final anpheros = Anpheros(auth: AnpherosAuth.oauth(
  accessToken: tokens.accessToken, refreshToken: tokens.refreshToken, expiresAt: tokens.expiresAt,
  onRefresh: flow.refresh, onTokens: persist));
final meds = await anpheros.medications.listMedications(tokens.patient!);
```

Každý objekt nese `fhir` (jeho `/fhir/R4` odkaz); `anpheros.fhir` poskytuje přímý přístup k FHIR
(read, search, create, transaction, `$everything`, `$summary`, `$validate`).

Chyby jsou `AnpherosException` s `status`, `type`, `message`, `field` a `requestId`.
Vytváření automaticky odesílá `Idempotency-Key`; 429/5xx se opakují s backoff; vypršené OAuth
tokeny jsou jednou obnoveny a volání je zopakováno.