# SDK

> Klienti Dart / Flutter (anpheros_sdk) a TypeScript (@anpheros/sdk): rovnaký tvar, idempotentné vytváranie, opakovanie, obnovenie tokenu a tok súhlasu.

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

> Oficiálne klientske knižnice pre FHIR R4 zdravotnícke API s bezplatným FHIR sandboxom: pacienti, pozorovania, laboratórne výsledky, stavy, lieky, International Patient Summary, súhlas pacienta a AI kontext, v TypeScript a Dart / Flutter.

**Anpheros je interoperabilná infraštruktúra lekárskych dát pre budovanie zdravotníckych aplikácií, lekárskeho softvéru a AI služieb.** Každý pacient má jeden HL7 FHIR R4 záznam, ktorý ovláda; aplikácie, kliniky, laboratóriá a AI agenti ho čítajú a zapisujú prostredníctvom Anpheros Platform API — so súhlasom pacienta (OAuth 2.1 / SMART on FHIR), s pôvodom pri každom zápise a s denníkom prístupu, ktorý pacient môže vidieť. Tento repozitár obsahuje oficiálne klientske knižnice a spustiteľné príklady.

| Jazyk | Balík | Inštalácia | 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+, prehliadač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) |

## Rýchly štart za 2 minúty

1. **Získajte bezplatný sandbox kľúč:** prihláste sa na [dashboard](https://platform.anpheros.com/dashboard/) a stlačte **Get a sandbox key** (`sk_test_…`). Váš sandbox obsahuje 30 syntetických pacientov.
2. **Overte funkčnosť:**

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

3. **Nainštalujte SDK a prečítajte záznam:** `npm install @anpheros/sdk` alebo `dart pub add anpheros_sdk`, potom spustite kód v sekcii [Connect](#connect), alebo naklonujte [quickstart-ts](https://github.com/anpheros/anpheros-sdk/tree/main/examples/quickstart-ts).

## Pre koho je určený

Vývojári, ktorí vytvárajú aplikácie pre zdravie pacientov a rodín, backendy pre zdravotnícke aplikácie, integrácie kliník a laboratórií, a AI asistentov alebo agentov, ktorí potrebujú štruktúrovaný lekársky kontext pacienta – bez nutnosti navrhovať od základu lekársku databázu, systém súhlasu a auditný záznam.

## Získajte kľúč pre sandbox

Sandbox je bezplatný a samoobslužný. Prihláste sa pomocou Google na [dashboard](https://platform.anpheros.com/dashboard/) a stlačte **Získať kľúč pre sandbox**: okamžite získate sandbox projekt a kľúč. Každý sandbox projekt obsahuje vlastných 30 syntetických pacientov — šesť mesiacov anamnéz, liekov, alergií, laboratórnych výsledkov a vitálnych funkcií — ktoré môžete voľne meniť a kedykoľvek resetovať. Kľúče pre sandbox (`sk_test_…`) sa nikdy nedostanú k reálnym údajom pacientov.

Keď prejdete do produkcie, produkcia je určená pre overené organizácie s dohodou o spracovaní údajov a produkcia začína od 99 € mesačne s prvým mesiacom zdarma ([ceny](https://developers.anpheros.com/sk/guides/pricing)).

## Pripojenie

```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 kľúče patria na servery. Aplikácia konajúca v mene osoby namiesto toho používa OAuth: obe SDK implementujú tok súhlasu (authorization code + PKCE) a automaticky obnovujú tokeny.

## Čo pokrývajú SDK

Obe pokrývajú celú verejnú plochu (`/v1`, `/fhir/R4`, `/oauth/token`, `/oauth/revoke`) s rovnakým tvarom: `patients`, `observations`, `conditions`, `medications`, `documents`, `timeline`, `provenance`, `context`, `grants`, `terminology` a surové `fhir`. Test zlyhá pri zostavovaní, keď v jednom zo SDK chýba verejná trasa alebo keď SDK volá trasu, ktorú server nemá.

Obe SDK: automatické `Idempotency-Key` pri vytváraní, opätovné pokusy s oneskorením pri 429/5xx, jedno obnovenie tokenu pri 401, typované chyby s ID požiadavky, pomocníci PKCE a tok súhlasu.

## Lekárske dáta a FHIR

Záznam pozostáva zo štandardných FHIR R4 zdrojov — 26 typov, vrátane `Observation`, `Condition`, `MedicationStatement`, `DocumentReference`, `Immunization` a `AllergyIntolerance` — kódovaných pomocou LOINC, ICD-10, ATC a UCUM. REST API (`/v1`) a FHIR API (`/fhir/R4`) čítajú a zapisujú rovnaké zdroje s rovnakými identifikátormi; `fhir` v oboch SDK poskytuje priamy prístup k FHIR (vyhľadávanie, transakcie, `$everything`, `$summary`, `$validate`).

## Príklady

| Príklad | Zobrazuje |
|---|---|
| [quickstart-ts](https://github.com/anpheros/anpheros-sdk/tree/main/examples/quickstart-ts) | zápis a čítanie záznamu: merania, laboratórny výsledok, diagnóza, liek, časová os, FHIR vyhľadávanie, IPS, AI kontext |
| [quickstart-dart](https://github.com/anpheros/anpheros-sdk/tree/main/examples/quickstart-dart) | to isté z Dart / Flutter |
| [consent-app-ts](https://github.com/anpheros/anpheros-sdk/tree/main/examples/consent-app-ts) | webová aplikácia, ktorá žiada o súhlas (OAuth 2.1 + PKCE) a číta záznam pacienta |
| [ai-context-llm](https://github.com/anpheros/anpheros-sdk/tree/main/examples/ai-context-llm) | otázka týkajúca sa záznamu zodpovedaná modelom podľa vášho výberu (lokálny alebo hosťovaný) |
| [fhir-transaction](https://github.com/anpheros/anpheros-sdk/tree/main/examples/fhir-transaction) | FHIR R4 transakčný balík a výsledný International Patient Summary |

Príklady bežia na bezplatnej sandboxe, kde každý sandbox projekt má vlastných 30 syntetických pacientov — pozri [Získajte sandbox kľúč](#get-a-sandbox-key).

## Súvisiace repozitáre

| Repozitár | Čo to je |
|---|---|
| [fhir-api-openapi](https://github.com/anpheros/fhir-api-openapi) | OpenAPI 3.1 špecifikácia a Postman kolekcia API |
| [mcp-server](https://github.com/anpheros/mcp-server) | hostovaný FHIR MCP server pre AI agentov: konfigurácie pre Claude, Cursor, VS Code |
| [agent-skills](https://github.com/anpheros/agent-skills) | Agent Skill, Claude Code plugin, pravidlá Cursor a AGENTS.md |
| [fhir-synthetic-patients](https://github.com/anpheros/fhir-synthetic-patients) | 30 syntetických pacientov ako FHIR R4 Bundles a NDJSON |
| [ips-examples](https://github.com/anpheros/ips-examples) | dokumenty International Patient Summary vo formáte FHIR R4 |
| [fhir-validate-action](https://github.com/anpheros/fhir-validate-action) | GitHub Action, ktorá validuje FHIR R4 JSON v CI |
| [lab-results-to-fhir](https://github.com/anpheros/lab-results-to-fhir) | CLI: CSV / HL7 v2 laboratórne správy → FHIR Observations |
| [healthcare-app-starters](https://github.com/anpheros/healthcare-app-starters) | šablóny zdravotníckych aplikácií v Next.js a Flutter |

## Zhoda

Surové výsledky testov, zverejnené na kontrolu (výsledky testov, nie certifikácie): [conformance/](https://github.com/anpheros/anpheros-sdk/tree/main/conformance). Dňa 28. septembra 2026 skupina Standalone Launch testovacej súpravy Inferno SMART App Launch STU2 (v1.0.3) úspešne absolvovala 22 z 22 testov proti platforme. Spustenie EHR nie je podporované.

## Dokumentácia

- [Sprievodcovia pre vývojárov](https://developers.anpheros.com/guides/)
- [Začíname](https://developers.anpheros.com/sk/guides/getting-started)
- [FHIR sandbox](https://developers.anpheros.com/sk/guides/fhir-sandbox)
- [Healthcare API](https://developers.anpheros.com/sk/guides/healthcare-api)
- [Healthcare API platform](https://developers.anpheros.com/sk/guides/healthcare-api-platform)
- [FHIR platform](https://developers.anpheros.com/sk/guides/fhir)
- [Sprievodca SDK](https://developers.anpheros.com/sk/guides/sdks)
- [Referenčná príručka API (OpenAPI)](https://developers.anpheros.com/docs)
- [Pre AI asistentov](https://developers.anpheros.com/llms.txt)
- [Anpheros](https://anpheros.com/)

## Problémy a zabezpečenie

Nahláste chyby v issues tohto repozitára. Nikdy nezahrňte do issue API kľúče, tokeny ani údaje o pacientoch. Bezpečnostné hlásenia: contact@anpheros.com.

## Licencia

Apache License 2.0 — pozri súbor `LICENSE` v každom balíku. Copyright 2026 Anpheros.

## @anpheros/sdk

TypeScript klient pre **Anpheros Platform**: zdravotný záznam pacienta vo formáte FHIR R4, izolácia projektov, súhlas pacienta (OAuth 2.1 / SMART on FHIR), sledovanie pôvodu pri každom zápise a kontextové API s umelou inteligenciou. Beží kdekoľvek, kde existuje `fetch` (Node 18+, prehliadač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' });
```

Konanie v mene 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 sú `AnpherosError` (`status`, `type`, `message`, `field`, `requestId`). Vytváranie odosiela `Idempotency-Key`; 429/5xx sa opakujú; vypršané tokeny sa obnovia raz a volanie sa zopakuje.

## anpheros_sdk

Dart / Flutter klient pre **Anpheros Platform**: backend pre zdravotné dáta s FHIR R4 záznamom
na pacienta, izoláciou projektov, súhlasom pacienta (OAuth 2.1 / SMART on FHIR), sledovaním pôvodu pri každom
zápise a AI kontextovým API.

```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));
```

## Konanie v mene osoby (aplikácie)

```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 nesie `fhir` (jeho `/fhir/R4` referenciu); `anpheros.fhir` poskytuje priamy prístup k FHIR
(read, search, create, transaction, `$everything`, `$summary`, `$validate`).

Chyby sú `AnpherosException` s `status`, `type`, `message`, `field` a `requestId`.
Vytvorenia automaticky posielajú `Idempotency-Key`; 429/5xx sa opakujú s backoffom; expirované OAuth
tokeny sa obnovia raz a volanie sa zopakuje.