# SDK

> I client Dart / Flutter (anpheros_sdk) e TypeScript (@anpheros/sdk): stessa struttura, create idempotenti, retry, refresh token e flusso di consenso.

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

> Librerie client ufficiali per un'API FHIR R4 per la sanità con un sandbox FHIR gratuito: pazienti, osservazioni, risultati di laboratorio, condizioni, farmaci, International Patient Summary, consenso del paziente e contesto AI, in TypeScript e Dart / Flutter.

**Anpheros è un'infrastruttura interoperabile di dati medici per la creazione di applicazioni sanitarie, software medici e servizi AI.** Ogni paziente ha un record HL7 FHIR R4 che controlla; applicazioni, cliniche, laboratori e agenti AI lo leggono e scrivono tramite l'API della Piattaforma Anpheros — con il consenso del paziente (OAuth 2.1 / SMART on FHIR), provenienza su ogni scrittura e un log di accesso visibile al paziente. Questo repository contiene le librerie client ufficiali ed esempi eseguibili.

| Lingua | Pacchetto | Installazione | Sorgente |
|---|---|---|---|
| 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+, browser, 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) |

## Avvio rapido in 2 minuti

1. **Ottieni una chiave sandbox gratuita:** accedi alla [dashboard](https://platform.anpheros.com/dashboard/) e premi **Get a sandbox key** (`sk_test_…`). La tua sandbox contiene 30 pazienti sintetici.
2. **Verifica il funzionamento:**

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

3. **Installa un SDK e leggi un record:** `npm install @anpheros/sdk` o `dart pub add anpheros_sdk`, quindi esegui il codice sotto [Connect](#connect), oppure clona [quickstart-ts](https://github.com/anpheros/anpheros-sdk/tree/main/examples/quickstart-ts).

## A chi è rivolto

Sviluppatori che creano app per la salute di pazienti e familiari, backend per app mediche, integrazioni per cliniche e laboratori, e assistenti o agenti AI che necessitano del contesto medico strutturato di un paziente — senza dover progettare da zero un database medico, un sistema di consenso e un audit trail.

## Ottieni una chiave sandbox

La sandbox è gratuita e self-service. Accedi con Google sulla [dashboard](https://platform.anpheros.com/dashboard/) e premi **Ottieni una chiave sandbox**: otterrai istantaneamente un progetto sandbox e una chiave. Ogni progetto sandbox include 30 pazienti sintetici — sei mesi di condizioni, farmaci, allergie, risultati di laboratorio e parametri vitali — che puoi modificare liberamente e reimpostare in qualsiasi momento. Le chiavi sandbox (`sk_test_…`) non accedono mai a dati di pazienti reali.

Quando vai in produzione, la produzione è riservata a organizzazioni verificate con un accordo di elaborazione dati, e la produzione inizia da €99 al mese con il primo mese gratuito ([prezzi](https://developers.anpheros.com/it/guides/pricing)).

## Connetti

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

Le API key appartengono ai server. Un'app che agisce per conto di una persona utilizza invece OAuth: entrambi gli SDK implementano il flusso di consenso (codice di autorizzazione + PKCE) e i token di aggiornamento automaticamente.

## Cosa coprono gli SDK

Entrambi coprono l'intera superficie pubblica (`/v1`, `/fhir/R4`, `/oauth/token`, `/oauth/revoke`) con la
stessa struttura: `patients`, `observations`, `conditions`, `medications`, `documents`, `timeline`,
`provenance`, `context`, `grants`, `terminology` e `fhir` grezzo. Un test fallisce la
build quando una route pubblica è mancante da uno degli SDK o quando un SDK chiama una route che il server
non possiede.

Entrambi gli SDK: `Idempotency-Key` automatico sulle creazioni, tentativi con backoff su 429/5xx, un refresh del token su 401, errori tipizzati con l'ID della richiesta, helper PKCE e il flusso di consenso.

## Dati medici e FHIR

Il record è composto da risorse FHIR R4 standard — 26 tipi, tra cui `Observation`, `Condition`, `MedicationStatement`, `DocumentReference`, `Immunization` e `AllergyIntolerance` — codificate con LOINC, ICD-10, ATC e UCUM. L'API REST (`/v1`) e l'API FHIR (`/fhir/R4`) leggono e scrivono le stesse risorse con gli stessi ID; `fhir` in entrambi gli SDK fornisce accesso FHIR grezzo (ricerca, transazioni, `$everything`, `$summary`, `$validate`).

## Esempi

| Esempio | Mostra |
|---|---|
| [quickstart-ts](https://github.com/anpheros/anpheros-sdk/tree/main/examples/quickstart-ts) | scrittura e lettura di un record: misurazioni, risultati di laboratorio, diagnosi, farmaci, timeline, ricerca FHIR, IPS, contesto AI |
| [quickstart-dart](https://github.com/anpheros/anpheros-sdk/tree/main/examples/quickstart-dart) | lo stesso da Dart / Flutter |
| [consent-app-ts](https://github.com/anpheros/anpheros-sdk/tree/main/examples/consent-app-ts) | un'app web che richiede il consenso (OAuth 2.1 + PKCE) e legge il record della persona |
| [ai-context-llm](https://github.com/anpheros/anpheros-sdk/tree/main/examples/ai-context-llm) | una domanda su un record a cui risponde un modello a tua scelta (locale o ospitato) |
| [fhir-transaction](https://github.com/anpheros/anpheros-sdk/tree/main/examples/fhir-transaction) | un bundle di transazione FHIR R4 e l'International Patient Summary risultante |

Gli esempi vengono eseguiti contro il sandbox gratuito, dove ogni progetto sandbox ha i propri 30 pazienti sintetici — vedi [Ottieni una chiave sandbox](#get-a-sandbox-key).

## Repository Correlati

| Repository | Descrizione |
|---|---|
| [fhir-api-openapi](https://github.com/anpheros/fhir-api-openapi) | Specifica OpenAPI 3.1 e collezione Postman dell'API |
| [mcp-server](https://github.com/anpheros/mcp-server) | Il server FHIR MCP ospitato per agenti AI: configurazioni per Claude, Cursor, VS Code |
| [agent-skills](https://github.com/anpheros/agent-skills) | Agent Skill, plugin Claude Code, regole Cursor e AGENTS.md |
| [fhir-synthetic-patients](https://github.com/anpheros/fhir-synthetic-patients) | I 30 pazienti sintetici come FHIR R4 Bundles e NDJSON |
| [ips-examples](https://github.com/anpheros/ips-examples) | Documenti International Patient Summary in FHIR R4 |
| [fhir-validate-action](https://github.com/anpheros/fhir-validate-action) | GitHub Action che valida FHIR R4 JSON in CI |
| [lab-results-to-fhir](https://github.com/anpheros/lab-results-to-fhir) | CLI: report di laboratorio CSV / HL7 v2 → FHIR Observations |
| [healthcare-app-starters](https://github.com/anpheros/healthcare-app-starters) | Template per app sanitarie Next.js e Flutter |

## Conformance

Risultati dei test grezzi, pubblicati in modo che possano essere verificati (risultati dei test, non certificazioni): [conformance/](https://github.com/anpheros/anpheros-sdk/tree/main/conformance). Il 28 settembre 2026 il gruppo Standalone Launch del kit di test Inferno SMART App Launch STU2 (v1.0.3) ha superato 22 test su 22 contro la piattaforma. Il lancio EHR non è supportato.

## Documentazione

- [Guide per sviluppatori](https://developers.anpheros.com/guides/)
- [Guida introduttiva](https://developers.anpheros.com/it/guides/getting-started)
- [Sandbox FHIR](https://developers.anpheros.com/it/guides/fhir-sandbox)
- [API per la sanità](https://developers.anpheros.com/it/guides/healthcare-api)
- [Piattaforma API per la sanità](https://developers.anpheros.com/it/guides/healthcare-api-platform)
- [Piattaforma FHIR](https://developers.anpheros.com/it/guides/fhir)
- [Guida SDK](https://developers.anpheros.com/it/guides/sdks)
- [Riferimento API (OpenAPI)](https://developers.anpheros.com/docs)
- [Per assistenti AI](https://developers.anpheros.com/llms.txt)
- [Anpheros](https://anpheros.com/)

## Problemi e sicurezza

Segnala bug nella sezione issues di questo repository. Non includere mai chiavi API, token o dati dei pazienti in una issue. Segnalazioni di sicurezza: contact@anpheros.com.

## Licenza

Apache License 2.0 — vedere il file `LICENSE` di ciascun pacchetto. Copyright 2026 Anpheros.

## @anpheros/sdk

Client TypeScript per **Anpheros Platform**: un record sanitario FHIR R4 per paziente, isolamento dei progetti, consenso del paziente (OAuth 2.1 / SMART on FHIR), provenienza su ogni scrittura e un'API di contesto AI. Funziona ovunque esista `fetch` (Node 18+, browser, 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' });
```

Agire per conto di una persona:

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

Gli errori sono `AnpherosError` (`status`, `type`, `message`, `field`, `requestId`). Le creazioni inviano un `Idempotency-Key`; 429/5xx vengono ritentati; i token scaduti vengono aggiornati una volta e la chiamata ritentata.

## anpheros_sdk

Client Dart / Flutter per la **Piattaforma Anpheros**: un backend di dati sanitari con un record FHIR R4
per paziente, isolamento dei progetti, consenso del paziente (OAuth 2.1 / SMART on FHIR), provenienza su ogni
scrittura e un'API di contesto 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));
```

## Agire per conto di una persona (app)

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

Ogni oggetto porta `fhir` (il suo riferimento `/fhir/R4`); `anpheros.fhir` fornisce accesso FHIR grezzo
(read, search, create, transaction, `$everything`, `$summary`, `$validate`).

Gli errori sono `AnpherosException` con `status`, `type`, `message`, `field` e `requestId`.
Le creazioni inviano automaticamente un `Idempotency-Key`; 429/5xx vengono ritentate con backoff; i token OAuth scaduti
vengono aggiornati una volta e la chiamata ritentata.