@nabla/connect-protocol 0.0.0-stage → 0.2.0

package/LICENSE

@@ -0,0 +1,5 @@
+Copyright (c) Nabla. All rights reserved.
+
+This software is proprietary and confidential. No license is granted to use,
+copy, modify, or distribute it, except to customers who received it from Nabla
+under a written agreement.

package/dist/commandResult.d.ts

@@ -0,0 +1,27 @@
+import type { NablaConnectCommandResultEvent } from "./events.js";
+import type { NablaConnectProtocolVersion } from "./version.js";
+/**
+ * Each command gets exactly one result. `ACCEPTED` means the iframe ran the
+ * action. Its progress is reported by later state changes, not by another
+ * result.
+ */
+export type NablaConnectCommandResultStatus = "ACCEPTED" | "REJECTED";
+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;
+    status: NablaConnectCommandResultStatus;
+    reason: NablaConnectCommandRejectionReason | null;
+};
+export type NablaConnectCommandResultMessage = {
+    event: NablaConnectCommandResultEvent;
+    data: NablaConnectCommandResult;
+};

package/dist/commands.d.ts

@@ -0,0 +1,55 @@
+import type { NablaConnectCommandExportNoteEvent, NablaConnectCommandStartNoteGenerationEvent, NablaConnectCommandStartRecordingEvent, NablaConnectCommandStopRecordingEvent } from "./events.js";
+import type { NablaConnectSessionHelloMessage } from "./session.js";
+import type { NablaConnectProtocolVersion } from "./version.js";
+/**
+ * `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;
+    sessionId: string;
+    requestId: string;
+    expectedRevision: number;
+};
+export type NablaConnectCommandStartRecordingMessage = {
+    event: NablaConnectCommandStartRecordingEvent;
+    data: NablaConnectCommandBase;
+};
+export type NablaConnectCommandStopRecordingMessage = {
+    event: NablaConnectCommandStopRecordingEvent;
+    data: NablaConnectCommandBase;
+};
+export type NablaConnectCommandStartNoteGenerationMessage = {
+    event: NablaConnectCommandStartNoteGenerationEvent;
+    data: NablaConnectCommandBase;
+};
+export type NablaConnectCommandExportNoteMessage = {
+    event: NablaConnectCommandExportNoteEvent;
+    data: NablaConnectCommandBase;
+};
+/** The iframe ignores unknown fields on commands. */
+export type NablaConnectInboundCommandMessage = NablaConnectCommandStartRecordingMessage | NablaConnectCommandStopRecordingMessage | NablaConnectCommandStartNoteGenerationMessage | NablaConnectCommandExportNoteMessage;
+/** 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 = {
+    startRecording: {
+        event: NablaConnectCommandStartRecordingEvent;
+        action: "START_RECORDING";
+    };
+    stopRecording: {
+        event: NablaConnectCommandStopRecordingEvent;
+        action: "STOP_RECORDING";
+    };
+    startNoteGeneration: {
+        event: NablaConnectCommandStartNoteGenerationEvent;
+        action: "GENERATE_NOTE";
+    };
+    exportNote: {
+        event: NablaConnectCommandExportNoteEvent;
+        action: "EXPORT_NOTE";
+    };
+};

package/dist/events.d.ts

@@ -0,0 +1,35 @@
+export type NablaConnectLifecycleStateChangedEvent = "com.connect.nabla:lifecycle:stateChanged";
+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";
+export type NablaConnectCommandExportNoteEvent = "com.connect.nabla:command:exportNote";
+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 = NablaConnectSessionHelloEvent | NablaConnectCommandStartRecordingEvent | NablaConnectCommandStopRecordingEvent | NablaConnectCommandStartNoteGenerationEvent | NablaConnectCommandExportNoteEvent;
+/** Events the iframe sends to the host page. */
+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:
+ * `const EVENTS = { ... } as const satisfies NablaConnectEventNames`.
+ */
+export type NablaConnectEventNames = {
+    lifecycleStateChanged: NablaConnectLifecycleStateChangedEvent;
+    sessionAvailable: NablaConnectSessionAvailableEvent;
+    sessionHello: NablaConnectSessionHelloEvent;
+    sessionReady: NablaConnectSessionReadyEvent;
+    sessionRejected: NablaConnectSessionRejectedEvent;
+    commandStartRecording: NablaConnectCommandStartRecordingEvent;
+    commandStopRecording: NablaConnectCommandStopRecordingEvent;
+    commandStartNoteGeneration: NablaConnectCommandStartNoteGenerationEvent;
+    commandExportNote: NablaConnectCommandExportNoteEvent;
+    commandResult: NablaConnectCommandResultEvent;
+    exportNote: NablaConnectExportNoteEvent;
+    exportPatientInstructions: NablaConnectExportPatientInstructionsEvent;
+};

package/dist/export.d.ts

@@ -0,0 +1,40 @@
+import type { NablaConnectExportNoteEvent, NablaConnectExportPatientInstructionsEvent } from "./events.js";
+export type NablaConnectExportableNoteSection = {
+    category: string | null;
+    content: string;
+    title: string;
+};
+export type NablaConnectExportableNote = {
+    sections: NablaConnectExportableNoteSection[];
+    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 NablaConnectExportTranscriptItem = {
+    text: string;
+    speakerType: string;
+    locale?: string | null;
+    startOffsetMs: number;
+    endOffsetMs: number;
+};
+export type NablaConnectExportNoteMessage = {
+    event: NablaConnectExportNoteEvent;
+    data: {
+        note: NablaConnectExportableNote;
+        transcript?: NablaConnectExportTranscriptItem[];
+        visitDiagnoses?: NablaConnectVisitDiagnosis[];
+    };
+};
+export type NablaConnectExportPatientInstructionsMessage = {
+    event: NablaConnectExportPatientInstructionsEvent;
+    data: {
+        patientInstructions: string;
+    };
+};
+export type NablaConnectExportMessage = NablaConnectExportNoteMessage | NablaConnectExportPatientInstructionsMessage;

package/dist/index.d.ts

@@ -0,0 +1,7 @@
+export type * from "./commandResult.js";
+export type * from "./commands.js";
+export type * from "./events.js";
+export type * from "./export.js";
+export type * from "./lifecycle.js";
+export type * from "./session.js";
+export type * from "./version.js";

package/dist/lifecycle.d.ts

@@ -0,0 +1,28 @@
+import type { NablaConnectLifecycleStateChangedEvent } from "./events.js";
+import type { NablaConnectProtocolVersion } from "./version.js";
+export type NablaConnectLifecycleState = "NOT_STARTED" | "RECORDING_STARTING" | "RECORDING_STARTED" | "RECORDING_STOPPING" | "NOTE_GENERATING" | "NOTE_READY" | "PAUSED";
+export type NablaConnectLifecycleAction = "START_RECORDING" | "STOP_RECORDING" | "GENERATE_NOTE" | "EXPORT_NOTE";
+export type NablaConnectLifecycleSnapshotReason = "COMMAND" | "NOTE_GENERATION_FAILED";
+export type NablaConnectNoteGenerationFailureReason = "TRANSCRIPT_TOO_SHORT" | "NO_MEDICAL_DATA" | "RATE_LIMITED" | "UNKNOWN";
+/**
+ * Consumers must tolerate additional fields: the iframe may ship them before the
+ * consumer knows them. `sessionId` is a non-empty string of at most
+ * `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[];
+    canBeClosed: boolean;
+    reason: NablaConnectLifecycleSnapshotReason | null;
+    failureReason: NablaConnectNoteGenerationFailureReason | null;
+};
+export type NablaConnectLifecycleStateChangedMessage = {
+    event: NablaConnectLifecycleStateChangedEvent;
+    data: {
+        snapshot: NablaConnectLifecycleSnapshot;
+    };
+};

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

@@ -0,0 +1,20 @@
+/**
+ * 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,26 @@
 {
   "name": "@nabla/connect-protocol",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.2.0",
+  "license": "UNLICENSED",
+  "description": "Wire-protocol types for the Nabla Connect iframe postMessage API. Types only, no runtime.",
+  "type": "module",
+  "sideEffects": false,
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts"
+    },
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "dist"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/nabla/connect-sdk.git",
+    "directory": "packages/protocol"
+  }
+}

package/README.md

@@ -1,3 +0,0 @@
-# Temporary Holding Version
-
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.