@nextage/ent-embed-sdk

Client SDK ufficiale per integrare il flusso di codifica ENT in un'applicazione partner tramite popup + postMessage.

⚠️ Lo scope @nextage è provvisorio: al GA il pacchetto sarà ripubblicato come @zcs/ent-embed-sdk. Le versioni 0.x.y non offrono garanzie di stabilità API; consultate il CHANGELOG ad ogni minor.

Caratteristiche

• API canonica Promise-based: EmbedClient.open(opts): Promise<EmbedEvent>.
• Hook opzionale onEvent per telemetria / log custom.
• Validazione OWASP del canale postMessage (origin esatto, event.source === popup, type whitelist).
• Polling popup.closed per intercettare la chiusura manuale.
• Timeout configurabile (default 15 min).
• Output: ESM, CommonJS, UMD (window.EntEmbedSdk), tipi .d.ts.

Installazione

npm install @nextage/ent-embed-sdk

Via CDN (UMD)

<script src="https://unpkg.com/@nextage/ent-embed-sdk@^0/dist/ent-embed-sdk.umd.js"></script>
<script>
  // window.EntEmbedSdk.EmbedClient
</script>

Uso

TypeScript / ESM

import { EmbedClient, type EmbedEvent } from '@nextage/ent-embed-sdk';

const ev: EmbedEvent = await EmbedClient.open({
  launchUrl: launchUrlReceivedFromYourBackend, // restituito da POST /v1/embed/sessions
  entOrigin: 'https://ent.example.com',    // origin esatto, costante
  timeoutMs: 15 * 60 * 1000,
  onEvent: (e) => console.debug('[embed]', e),
});

switch (ev.type) {
  case 'result':
    console.log('Diagnoses:', ev.result.diagnoses);
    console.log('Procedures:', ev.result.procedures);
    console.log('DRG:', ev.result.drg);
    break;
  case 'cancelled':
    console.info('User cancelled', ev.reason);
    break;
  case 'terminal':
    // Sessione in stato terminale o scaduta (terminal | expired).
    console.warn('Terminal error', ev.code, ev.message);
    break;
  case 'closed':
    // Popup chiuso senza esito ('user-closed' | 'timeout' | 'manual').
    console.info('Popup closed', ev.reason);
    break;
}

Vanilla JS / CDN

<button id="open">Apri ENT</button>
<script src="https://unpkg.com/@nextage/ent-embed-sdk@^0/dist/ent-embed-sdk.umd.js"></script>
<script>
  document.getElementById('open').addEventListener('click', async () => {
    const launchUrl = await fetch('/api/ent/session', { method: 'POST' })
      .then((r) => r.json())
      .then((r) => r.launchUrl);

    const ev = await EntEmbedSdk.EmbedClient.open({
      launchUrl,
      entOrigin: 'https://ent.example.com',
    });
    console.log('event', ev);
  });
</script>

API

EmbedClient.open(options): Promise<EmbedEvent>

| Campo | Tipo | Obbligatorio | Default | Note | |---|---|---|---|---| | launchUrl | string | sì | — | URL launch_url restituito dal backend ENT. | | entOrigin | string | sì | — | Origin esatto del deployment ENT (no wildcard, no regex). | | mode | 'popup' | no | 'popup' | iframe riservato a versioni future. | | popupFeatures | string | no | popup centrato 1100×780 | Forwarded a window.open. | | timeoutMs | number | no | 900000 (15 min) | 0 o Infinity disabilita il timeout. | | onEvent | (ev) => void | no | — | Hook osservatore. Errori interni sono silenziati. |

La Promise risolve esattamente una volta con uno dei seguenti EmbedEvent:

type EmbedEvent =
  | { type: 'result';    result: EntCodingResult; raw: unknown }
  | { type: 'cancelled'; reason?: string;         raw: unknown }
  | { type: 'terminal';  code: string; message?: string; raw: unknown }
  | { type: 'closed';    reason: 'user-closed' | 'timeout' | 'manual' };

La Promise rigetta solo per errori di programmazione:

• options mancanti / wildcard origin / mode non supportato → TypeError.
• popup bloccato dal browser → Error('Popup blocked …'). In quel caso invitate l'utente a sbloccare i popup, poi richiamate EmbedClient.open da un gesto utente.

Codici terminali

Identici a quelli emessi dal backend ENT (vedi sezione Protocollo più sotto):

| ev.code | Significato | UX consigliata | |---|---|---| | embed.errors.session.terminal | Sessione in stato terminale (completed/cancelled/failed) o budget di rilanci esaurito. | "Sessione già conclusa, riapri da capo." | | embed.errors.session.expired | TTL scaduto, record purgato. | "Sessione scaduta, riapri da capo." |

Protocollo

L'SDK è un client del protocollo postMessage esposto dalla pagina embed ENT. Conoscerlo non è necessario per integrare, ma è utile per debug.

Frame in ingresso (ENT → integratore)

Tutti i messaggi hanno data.type con prefisso ent: e arrivano dall'origin esatto passato come entOrigin.

| data.type | data.payload | Mappato dall'SDK in | |---|---|---| | ent:result | { diagnoses: [...], procedures: [...], drg?: {...}, meta?: {...} } | { type: 'result', result, raw } | | ent:cancelled | { reason?: string } (opzionale) | { type: 'cancelled', reason?, raw } | | ent:terminal | { code: 'embed.errors.session.*', message?: string } | { type: 'terminal', code, message?, raw } |

Validazione applicata dall'SDK

Prima di considerare un frame attendibile, l'SDK applica i tre controlli OWASP:

1. event.origin === entOrigin (confronto esatto, nessun wildcard, nessun endsWith).
2. event.source === popup (la finestra è esattamente quella aperta dall'SDK).
3. data.type appartiene alla whitelist ent:result | ent:cancelled | ent:terminal.

Frame che falliscono uno qualsiasi dei controlli sono silenziosamente ignorati.

Eventi sintetici (non provenienti da postMessage)

| Evento | Quando | reason | |---|---|---| | { type: 'closed', reason: 'user-closed' } | L'utente chiude il popup senza completare/annullare. | user-closed | | { type: 'closed', reason: 'timeout' } | Trascorso timeoutMs senza risultato. | timeout |

Versioning e Changelog

• Semver: MAJOR.MINOR.PATCH. Durante la fase pre-GA (0.x.y) le minor possono contenere breaking changes; consultate il CHANGELOG.md prima di aggiornare.
• Range raccomandato in produzione:
  • Pre-GA (0.x): pinnate la minor → "@nextage/ent-embed-sdk": "~0.1.0" (solo patch).
  • Post-GA (1.x): pinnate la major → "@nextage/ent-embed-sdk": "^1.0.0".
• CDN: in produzione usate sempre una versione pinnata, non un range mobile:
  • ✅ https://unpkg.com/@nextage/[email protected]/dist/ent-embed-sdk.umd.js
  • ⚠️ https://unpkg.com/@nextage/ent-embed-sdk@^0/dist/ent-embed-sdk.umd.js (solo dev / esempi).
• Subresource Integrity consigliata sui tag <script> CDN (l'hash SRI è pubblicato nelle release notes a partire da 0.2.0).

Sviluppo locale

npm install
npm test              # vitest run
npm run typecheck     # tsc --noEmit
npm run build         # rollup -> dist/

Licenza

UNLICENSED — uso riservato a partner ENT/ZCS sotto contratto.