@nabla/connect-protocol 0.1.0-test1 → 0.2.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,5 +1,5 @@
 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
@@ -7,6 +7,7 @@ import type { NablaConnectProtocolVersion } from "./version.js";
  * integer: the revision of the snapshot the host acted on.
  */
 export type NablaConnectCommandBase = {
+    /** The version pinned by the session handshake. */
     version: NablaConnectProtocolVersion;
     sessionId: string;
     requestId: string;
@@ -20,14 +21,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 +31,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/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,57 @@
+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`.
+ */
+export type NablaConnectSessionAvailableMessage = {
+    event: NablaConnectSessionAvailableEvent;
+    data: {
+        supportedVersions: number[];
+    };
+};
+/**
+ * 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.
+ */
+export type NablaConnectSessionHelloMessage = {
+    event: NablaConnectSessionHelloEvent;
+    data: {
+        supportedVersions: number[];
+        sdkVersion: 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.
+ */
+export type NablaConnectSessionReadyMessage = {
+    event: NablaConnectSessionReadyEvent;
+    data: {
+        version: NablaConnectProtocolVersion;
+        sessionId: 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.
+ */
+export type NablaConnectSessionRejectedMessage = {
+    event: NablaConnectSessionRejectedEvent;
+    data: {
+        reason: NablaConnectSessionRejectionReason;
+        supportedVersions: number[];
+    };
+};

package/dist/version.d.ts

@@ -1,7 +1,20 @@
-/** 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.
  * 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;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@nabla/connect-protocol",
-  "version": "0.1.0-test1",
+  "version": "0.2.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;
-    };
-};