@nabla/connect-protocol 0.1.0-test1 → 0.3.0

package/dist/commandResult.d.ts

@@ -6,12 +6,15 @@ import type { NablaConnectProtocolVersion } from "./version.js";
  * result.
  */
 export type NablaConnectCommandResultStatus = "ACCEPTED" | "REJECTED";
-export type NablaConnectCommandRejectionReason = "STALE_STATE" | "NOT_ALLOWED" | "BUSY" | "INVALID_SESSION" | "MICROPHONE_CUT_CONFIRMATION_REQUIRED" | "EXPORT_FAILED" | "INVALID_MESSAGE" | "UNSUPPORTED_VERSION";
+export type NablaConnectCommandRejectionReason = "STALE_STATE" | "NOT_ALLOWED" | "BUSY" | "INVALID_SESSION" | "EXPORT_FAILED" | "INVALID_MESSAGE"
+/** An unexpected failure while running the command. */
+ | "UNKNOWN";
 /**
  * `requestId` is `null` when the rejected message carried no usable one.
  * Consumers must tolerate additional fields.
  */
 export type NablaConnectCommandResult = {
+    /** The version pinned by the session handshake. */
     version: NablaConnectProtocolVersion;
     sessionId: string;
     requestId: string | null;

package/dist/commands.d.ts

@@ -1,13 +1,16 @@
 import type { NablaConnectCommandExportNoteEvent, NablaConnectCommandStartNoteGenerationEvent, NablaConnectCommandStartRecordingEvent, NablaConnectCommandStopRecordingEvent } from "./events.js";
-import type { NablaConnectQueryLifecycleStateMessage } from "./query.js";
+import type { NablaConnectSessionHelloMessage } from "./session.js";
 import type { NablaConnectProtocolVersion } from "./version.js";
 /**
- * `sessionId` and `requestId` are non-empty strings of at most
+ * `clientId`, `sessionId` and `requestId` are non-empty strings of at most
  * `NablaConnectBoundedIdMaxLength` characters. `expectedRevision` is a positive
  * integer: the revision of the snapshot the host acted on.
  */
 export type NablaConnectCommandBase = {
+    /** The version pinned by the session handshake. */
     version: NablaConnectProtocolVersion;
+    /** The `clientId` of the `session:hello`. The iframe ignores another one. */
+    clientId: string;
     sessionId: string;
     requestId: string;
     expectedRevision: number;
@@ -20,14 +23,9 @@ export type NablaConnectCommandStopRecordingMessage = {
     event: NablaConnectCommandStopRecordingEvent;
     data: NablaConnectCommandBase;
 };
-export type NablaConnectStartNoteGenerationOptions = {
-    microphoneCutConfirmed?: boolean;
-};
 export type NablaConnectCommandStartNoteGenerationMessage = {
     event: NablaConnectCommandStartNoteGenerationEvent;
-    data: NablaConnectCommandBase & {
-        startNoteGeneration?: NablaConnectStartNoteGenerationOptions;
-    };
+    data: NablaConnectCommandBase;
 };
 export type NablaConnectCommandExportNoteMessage = {
     event: NablaConnectCommandExportNoteEvent;
@@ -35,7 +33,8 @@ export type NablaConnectCommandExportNoteMessage = {
 };
 /** The iframe ignores unknown fields on commands. */
 export type NablaConnectInboundCommandMessage = NablaConnectCommandStartRecordingMessage | NablaConnectCommandStopRecordingMessage | NablaConnectCommandStartNoteGenerationMessage | NablaConnectCommandExportNoteMessage;
-export type NablaConnectInboundLifecycleMessage = NablaConnectQueryLifecycleStateMessage | NablaConnectInboundCommandMessage;
+/** Everything the iframe receives: the handshake, then commands. */
+export type NablaConnectInboundLifecycleMessage = NablaConnectSessionHelloMessage | NablaConnectInboundCommandMessage;
 export type NablaConnectLifecycleCommandKind = "startRecording" | "stopRecording" | "startNoteGeneration" | "exportNote";
 /** Each command with the event that carries it and the snapshot action it requires. */
 export type NablaConnectLifecycleCommands = {

package/dist/events.d.ts

@@ -1,5 +1,8 @@
 export type NablaConnectLifecycleStateChangedEvent = "com.connect.nabla:lifecycle:stateChanged";
-export type NablaConnectQueryLifecycleStateEvent = "com.connect.nabla:query:lifecycleState";
+export type NablaConnectSessionAvailableEvent = "com.connect.nabla:session:available";
+export type NablaConnectSessionHelloEvent = "com.connect.nabla:session:hello";
+export type NablaConnectSessionReadyEvent = "com.connect.nabla:session:ready";
+export type NablaConnectSessionRejectedEvent = "com.connect.nabla:session:rejected";
 export type NablaConnectCommandStartRecordingEvent = "com.connect.nabla:command:startRecording";
 export type NablaConnectCommandStopRecordingEvent = "com.connect.nabla:command:stopRecording";
 export type NablaConnectCommandStartNoteGenerationEvent = "com.connect.nabla:command:startNoteGeneration";
@@ -8,9 +11,9 @@ export type NablaConnectCommandResultEvent = "com.connect.nabla:command:result";
 export type NablaConnectExportNoteEvent = "com.connect.nabla:export:note";
 export type NablaConnectExportPatientInstructionsEvent = "com.connect.nabla:export:patientInstructions";
 /** Events the host page sends to the iframe. */
-export type NablaConnectInboundEvent = NablaConnectQueryLifecycleStateEvent | NablaConnectCommandStartRecordingEvent | NablaConnectCommandStopRecordingEvent | NablaConnectCommandStartNoteGenerationEvent | NablaConnectCommandExportNoteEvent;
+export type NablaConnectInboundEvent = NablaConnectSessionHelloEvent | NablaConnectCommandStartRecordingEvent | NablaConnectCommandStopRecordingEvent | NablaConnectCommandStartNoteGenerationEvent | NablaConnectCommandExportNoteEvent;
 /** Events the iframe sends to the host page. */
-export type NablaConnectOutboundEvent = NablaConnectLifecycleStateChangedEvent | NablaConnectCommandResultEvent | NablaConnectExportNoteEvent | NablaConnectExportPatientInstructionsEvent;
+export type NablaConnectOutboundEvent = NablaConnectSessionAvailableEvent | NablaConnectSessionReadyEvent | NablaConnectSessionRejectedEvent | NablaConnectLifecycleStateChangedEvent | NablaConnectCommandResultEvent | NablaConnectExportNoteEvent | NablaConnectExportPatientInstructionsEvent;
 /**
  * Every event name, by key. Types have no runtime value, so each consumer redeclares the
  * names it uses and pins the declaration to this type:
@@ -18,7 +21,10 @@ export type NablaConnectOutboundEvent = NablaConnectLifecycleStateChangedEvent |
  */
 export type NablaConnectEventNames = {
     lifecycleStateChanged: NablaConnectLifecycleStateChangedEvent;
-    queryLifecycleState: NablaConnectQueryLifecycleStateEvent;
+    sessionAvailable: NablaConnectSessionAvailableEvent;
+    sessionHello: NablaConnectSessionHelloEvent;
+    sessionReady: NablaConnectSessionReadyEvent;
+    sessionRejected: NablaConnectSessionRejectedEvent;
     commandStartRecording: NablaConnectCommandStartRecordingEvent;
     commandStopRecording: NablaConnectCommandStopRecordingEvent;
     commandStartNoteGeneration: NablaConnectCommandStartNoteGenerationEvent;

package/dist/export.d.ts

@@ -1,7 +1,40 @@
 import type { NablaConnectExportNoteEvent, NablaConnectExportPatientInstructionsEvent } from "./events.js";
+export type NablaConnectIcd10Entry = {
+    system: "http://hl7.org/fhir/sid/icd-10-cm";
+    code: string;
+    display: string;
+    isHcc: boolean;
+    isMcc: boolean;
+};
+export type NablaConnectSnomedEntry = {
+    system: "http://snomed.info/sct";
+    code: string;
+    display: string;
+};
+/**
+ * A subsection of a note section, with its normalized codes. `title` is `null` for a
+ * subsection without a title. The code lists are empty when no codes are available at
+ * export time.
+ */
+export type NablaConnectNoteSubsection = {
+    title: string | null;
+    text: string;
+    icd10Codes: NablaConnectIcd10Entry[];
+    snomedCodes: NablaConnectSnomedEntry[];
+};
+/** The content of a note section, discriminated by `type`. */
+export type NablaConnectNoteSectionContent = {
+    type: "TEXT";
+    text: string;
+} | {
+    type: "SUBSECTIONS";
+    subsections: NablaConnectNoteSubsection[];
+};
 export type NablaConnectExportableNoteSection = {
     category: string | null;
+    /** @deprecated The `NOTE_EXPORT` callback deprecates it: read `structuredContent`. */
     content: string;
+    structuredContent: NablaConnectNoteSectionContent;
     title: string;
 };
 export type NablaConnectExportableNote = {
@@ -9,13 +42,7 @@ export type NablaConnectExportableNote = {
     freeText: string | null;
 };
 export type NablaConnectVisitDiagnosisSystem = "http://hl7.org/fhir/sid/icd-10-cm";
-export type NablaConnectVisitDiagnosis = {
-    system: NablaConnectVisitDiagnosisSystem;
-    code: string;
-    display: string;
-    isHcc: boolean;
-    isMcc: boolean;
-};
+export type NablaConnectVisitDiagnosis = NablaConnectIcd10Entry;
 export type NablaConnectExportTranscriptItem = {
     text: string;
     speakerType: string;

package/dist/index.d.ts

@@ -3,5 +3,5 @@ export type * from "./commands.js";
 export type * from "./events.js";
 export type * from "./export.js";
 export type * from "./lifecycle.js";
-export type * from "./query.js";
+export type * from "./session.js";
 export type * from "./version.js";

package/dist/lifecycle.d.ts

@@ -10,12 +10,13 @@ export type NablaConnectNoteGenerationFailureReason = "TRANSCRIPT_TOO_SHORT" | "
  * `NablaConnectBoundedIdMaxLength` characters, `revision` a positive integer.
  */
 export type NablaConnectLifecycleSnapshot = {
+    /** The version pinned by the session handshake. */
     version: NablaConnectProtocolVersion;
     sessionId: string;
     revision: number;
     state: NablaConnectLifecycleState;
     availableActions: NablaConnectLifecycleAction[];
-    canBecomeInactive: boolean;
+    canBeClosed: boolean;
     reason: NablaConnectLifecycleSnapshotReason | null;
     failureReason: NablaConnectNoteGenerationFailureReason | null;
 };

package/dist/session.d.ts

@@ -0,0 +1,71 @@
+import type { NablaConnectSessionAvailableEvent, NablaConnectSessionHelloEvent, NablaConnectSessionReadyEvent, NablaConnectSessionRejectedEvent } from "./events.js";
+import type { NablaConnectProtocolVersion } from "./version.js";
+/**
+ * The iframe is listening. Sent once per session, before anything else. A new one on the
+ * same iframe element means the previous session is gone: the document reloaded, or the
+ * iframe opened another encounter.
+ *
+ * Setup messages are not versioned and only ever gain fields. `supportedVersions` is
+ * bounded by `NablaConnectSupportedVersionsMaxLength`.
+ *
+ * `clientId` is the client the document was loaded for, read from its URL, or `null` for a
+ * document that was loaded for none. It is a bounded id.
+ */
+export type NablaConnectSessionAvailableMessage = {
+    event: NablaConnectSessionAvailableEvent;
+    data: {
+        supportedVersions: number[];
+        clientId: string | null;
+    };
+};
+/**
+ * The host SDK offers the versions it speaks. Sent when the SDK is created and again on
+ * every `session:available`. Until the iframe answers with `session:ready`, it ignores
+ * every other inbound message.
+ *
+ * `sdkVersion` is the semver of the SDK, bounded by `NablaConnectSdkVersionMaxLength`.
+ * The iframe logs it. It is not clinical data.
+ *
+ * `clientId` is a bounded id that identifies the SDK client. The iframe only answers the
+ * client its document was loaded for, and ignores a message with another or no `clientId`.
+ */
+export type NablaConnectSessionHelloMessage = {
+    event: NablaConnectSessionHelloEvent;
+    data: {
+        supportedVersions: number[];
+        sdkVersion: string;
+        clientId: string;
+    };
+};
+/**
+ * The iframe pinned the highest version both sides support. Every later message of the
+ * session carries and is validated against it, and the first `stateChanged` follows.
+ * A repeated `session:hello` in the same session gets the same message back.
+ *
+ * `clientId` echoes the one of the `session:hello` it answers. The iframe posts to a window
+ * its host shares with other clients, so each client tells its own messages by it.
+ */
+export type NablaConnectSessionReadyMessage = {
+    event: NablaConnectSessionReadyEvent;
+    data: {
+        version: NablaConnectProtocolVersion;
+        sessionId: string;
+        clientId: string;
+    };
+};
+export type NablaConnectSessionRejectionReason = "UNSUPPORTED_VERSION";
+/**
+ * The two sides share no version, or the session already pinned one the host does not
+ * offer. The host gets no session. `supportedVersions` is what the iframe speaks. If they
+ * are all newer than the SDK's, the SDK is too old and the integrator upgrades
+ * `@nabla/connect-sdk`. If they are all older, the iframe is behind the SDK.
+ * `clientId` echoes the one of the `session:hello` it answers.
+ */
+export type NablaConnectSessionRejectedMessage = {
+    event: NablaConnectSessionRejectedEvent;
+    data: {
+        reason: NablaConnectSessionRejectionReason;
+        supportedVersions: number[];
+        clientId: string;
+    };
+};

package/dist/version.d.ts

@@ -1,7 +1,25 @@
-/** Version carried by every message of this protocol. Bumped on breaking changes only. */
+/**
+ * A protocol version the session can pin. Bumped on breaking changes only.
+ *
+ * The `session:*` setup messages are not versioned and only ever gain fields. They
+ * negotiate the version that every other message of the session carries:
+ * `session:ready` reports the one it pinned.
+ */
 export type NablaConnectProtocolVersion = 1;
 /**
- * Ids (`sessionId`, `requestId`) are non-empty strings of at most this many characters.
+ * Ids (`clientId`, `sessionId`, `requestId`) are non-empty strings of at most this many characters.
  * Types cannot express the bound: consumers must enforce it.
  */
 export type NablaConnectBoundedIdMaxLength = 64;
+/**
+ * `supportedVersions` holds at most this many positive integers. It may list versions the
+ * receiver does not know: it ignores them.
+ */
+export type NablaConnectSupportedVersionsMaxLength = 16;
+/** `sdkVersion` is a non-empty string of at most this many characters. */
+export type NablaConnectSdkVersionMaxLength = 64;
+/**
+ * The query parameter of the iframe URL that carries the `clientId` the document is loaded
+ * for. The SDK sets it. The iframe only answers the client it names.
+ */
+export type NablaConnectClientIdParam = "nablaConnectClientId";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nabla/connect-protocol",
-  "version": "0.1.0-test1",
+  "version": "0.3.0",
   "license": "UNLICENSED",
   "description": "Wire-protocol types for the Nabla Connect iframe postMessage API. Types only, no runtime.",
   "type": "module",

package/dist/query.d.ts

@@ -1,9 +0,0 @@
-import type { NablaConnectQueryLifecycleStateEvent } from "./events.js";
-import type { NablaConnectProtocolVersion } from "./version.js";
-/** Asks the iframe to send its current lifecycle snapshot. */
-export type NablaConnectQueryLifecycleStateMessage = {
-    event: NablaConnectQueryLifecycleStateEvent;
-    data: {
-        version: NablaConnectProtocolVersion;
-    };
-};