Encounter
Represents a clinical encounter with patient information.
type Encounter = {
identifier?: string;
patient: Patient;
};
Property | Type | Required | Description |
---|
identifier | string | - | Unique identifier for the encounter |
patient | Patient | ✓ | Patient information for the encounter |
Patient
Patient demographic and identification information.
type Patient = {
identifier: string;
kind?: string;
name: {
use: string;
family: string;
given: string[];
suffix: string[];
};
birthDate: string;
gender: "MALE" | "FEMALE" | "UNKNOWN";
};
Property | Type | Required | Description |
---|
birthDate | string | ✓ | Date of birth in YYYY-MM-DD format |
gender | "MALE" | "FEMALE" | "UNKNOWN" | ✓ | Patient’s gender. Use “UNKNOWN” if gender information is not available |
identifier | string | ✓ | Unique identifier for the patient |
kind | string | - | Kind of patient (e.g., “human”, “animal”) |
name | object | ✓ | Patient name information |
name.family | string | ✓ | Family name (last name) |
name.given | string[] | ✓ | Given names (first names) |
name.suffix | string[] | ✓ | Name suffixes |
name.use | string | ✓ | Use of the name (e.g., “usual”, “official”, “nickname”) |
InitOptions
Configuration options for initializing the SDK.
type InitOptions = PartnerDetails & {
enableDebug?: boolean;
logLevel?: LogLevel;
isTestMode?: boolean;
theme?: ThemeOptions;
};
Property | Type | Default | Description |
---|
enableDebug | boolean | false | Whether to enable debug mode. This will log additional information to the console |
logLevel | LogLevel | - | The log level to use when debug mode is enabled. Controls which messages are output to the console |
isTestMode | boolean | false | Whether to connect to stage environment. This will use stage endpoints |
theme | ThemeOptions | - | The theme configuration for the SDK |
Extends: PartnerDetails
PartnerDetails
Partner authentication and provider information required for SDK initialization.
type PartnerDetails = {
partnerId: string;
partnerToken: string;
providerName: string;
providerOrgId: string;
providerSpecialty?: string;
providerId?: string;
};
Property | Type | Required | Description |
---|
partnerId | string | ✓ | The unique identifier of the partner to use when authenticating with the Suki Platform |
partnerToken | string | ✓ | The idToken of the user/provider to use when authenticating with the Suki Platform |
providerName | string | ✓ | The full name of the user/provider. First name, middle name and last name separated by a space |
providerOrgId | string | ✓ | The unique identifier of the organization in the partner system to which the provider belongs |
providerSpecialty | string | - | The specialty of the provider, if applicable. Defaults to FAMILY_MEDICINE |
providerId | string | - | The unique identifier of the provider in the partner system |
ThemeOptions
Theme configuration options for customizing the SDK appearance.
type ThemeOptions = {
primary?: string;
background?: string;
secondaryBackground?: string;
foreground?: string;
warning?: string;
};
Property | Type | Default | Description |
---|
primary | string | rgb(46, 98, 98) | The primary color of the theme in rgb |
background | string | rgb(255, 255, 255) | The primary background color of the theme in rgb |
secondaryBackground | string | rgb(233, 233, 240) | The secondary background color of the theme in rgb |
foreground | string | rgb(0, 0, 0) | The foreground/text color of the theme in rgb |
warning | string | rgb(255, 184, 0) | The warning color used for alerts and notifications in rgb |
MountOptions
Configuration options for mounting the SDK to a DOM element.
type MountOptions = {
rootElement: HTMLElement;
encounter: Encounter;
uiOptions?: UIOptions;
ambientOptions?: AmbientOptions;
};
Property | Type | Required | Description |
---|
ambientOptions | AmbientOptions | - | Ambient session configuration options |
encounter | Encounter | ✓ | The encounter data to pre-populate the SDK |
rootElement | HTMLElement | ✓ | The DOM element to mount the SDK into. Should be an empty container element |
uiOptions | UIOptions | - | UI configuration options |
UIOptions
User interface configuration options for the SDK.
type UIOptions = {
showCloseButton?: boolean;
showCreateEmptyNoteButton?: boolean;
sectionEditing?: SectionEditingOptions;
showStartAmbientButton?: boolean;
};
Property | Type | Required | Default | Description |
---|
sectionEditing | SectionEditingOptions | - | all enabled | Configuration for section editing features |
showCloseButton | boolean | - | - | Whether to show the close button in the SDK header |
showCreateEmptyNoteButton | boolean | - | - | Whether to show the create empty note button in the patient profile |
showStartAmbientButton | boolean | - | - | Whether to show the start ambient button in the patient profile |
SectionEditingOptions
Configuration for section editing features within the SDK.
type SectionEditingOptions = {
enableDictation?: boolean;
enableCopy?: boolean;
};
Property | Type | Required | Default | Description |
---|
enableCopy | boolean | - | true | Whether to enable copying the section contents |
enableDictation | boolean | - | true | Whether to enable dictation feature for the sections |
AmbientOptions
Configuration options for ambient session functionality.
type AmbientOptions = {
prefill?: {
noteTypeIds?: string[];
};
sections?: Section[];
};
Property | Type | Required | Description |
---|
prefill | object | - | Prefill configuration for ambient sessions |
prefill.noteTypeIds | string[] | - | List of note type IDs to prefill when starting an ambient session |
sections | Section[] | - | Array of clinical note sections to generate suggestions for |
Section
Defines a clinical note section using LOINC codes for ambient sessions.
type Section = {
loinc: string;
isPBNSection?: boolean;
};
Property | Type | Required | Description |
---|
isPBNSection | boolean | - | Marks this section as the single PBN (Problem-Based Note) section. Only one section may be marked as PBN. If omitted on all sections, Assessment & Plan (LOINC 51847-2 ) will be used as default |
loinc | string | ✓ | Standard LOINC code identifying the section type |
LogLevel
Available log levels for controlling debug output verbosity.
type LogLevel = "debug" | "info" | "warn" | "error" | "log";
debug
- Log all messages including detailed debug information
warn
- Log warnings and above (warn, error, log)
info
- Log informational messages and above (info, warn, error, log)
error
- Log errors and above (error, log)
log
- Log only explicit log messages
The logger respects both the enableDebug
flag and logLevel
setting.
Messages are only output when debug mode is enabled AND the message level
meets or exceeds the configured log level.
EmitterEvents
Events that can be emitted by the SDK for monitoring session state and handling responses.
type EmitterEvents = {
ready: never;
"init:change": boolean;
close: never;
"ambient:update": {
ambientId: string;
isAmbientInProgress: boolean;
isAmbientPaused: boolean;
};
"note-submission:success": {
noteId: string;
contents: Array<{ title: string; content: NoteContent }>;
};
error: SukiError;
};
Event | Data Type | Description |
---|
ambient:update | object | Emitted when ambient session state changes |
close | - | Emitted when the SDK is closed |
error | SukiError | Emitted when an error occurs |
init:change | boolean | Emitted when initialization state changes |
note-submission:success | object | Emitted when a note is successfully submitted |
ready | - | Emitted when the SDK is ready for use |
NoteContent
The content structure for clinical notes, including optional diagnosis and LOINC code.
type NoteContent = {
title: string;
content: string;
diagnosis?: Diagnosis;
loinc_code?: string;
};
Property | Type | Description |
---|
title | string | The title of the section |
content | string | Content of the section in plain text |
diagnosis | Diagnosis | Array of clinical note sections to generate suggestions for |
loinc_code | string | LOINC code of the section |
Diagnosis
The structure for clinical diagnosis information, including ICD and SNOMED codes.
type Diagnosis = {
icdCode: string;
icdDescription: string;
snomedCode: string;
snomedDescription: string;
hccCode: string;
panelRanking: number;
billable: boolean;
problemLabel: string;
suggestionType: "DEFAULT" | "ED" | "PL";
};
Property | Type | Description |
---|
icdCode | string | The ICD code for the diagnosis |
icdDescription | string | The description of the ICD code |
snomedCode | string | The SNOMED code for the diagnosis |
snomedDescription | string | The description of the SNOMED code |
hccCode | string | The HCC code for the diagnosis |
panelRanking | number | The ranking of the diagnosis in the panel |
billable | boolean | Whether the diagnosis is billable |
problemLabel | string | The label for the problem associated with the diagnosis |
suggestionType | "DEFAULT" , "ED" , "PL" | The type of suggestion |
SukiError
Error object structure for SDK errors.
type SukiError = {
code: ErrorCode;
details: ErrorDetail;
};
Property | Type | Description |
---|
code | ErrorCode | Unique error code identifier |
details | ErrorDetail | Detailed error information including name, message, and reason |
ErrorCode
Unique identifiers for different types of SDK errors.
Code | Name | Category | Description |
---|
SUKI0001 | init:sdk-init-failed | Initialization | SDK initialization failed |
SUKI0002 | init:auth-failed | Authentication | User authentication failed |
SUKI0003 | init:mount-failed | Initialization | SDK mounting to DOM failed |
SUKI0004 | init:messenger-failed | Initialization | Internal messaging system failed |
SUKI0005 | init:invalid-options | Initialization | Invalid initialization options provided |
SUKI0006 | navigate:failed | Navigation | Navigation within SDK failed |
SUKI0007 | create-appointment:failed | Encounter | Failed to create appointment/encounter |
SUKI0008 | get-appointment:failed | Encounter | Failed to retrieve appointment/encounter |
SUKI0009 | create-patient:failed | Patient | Failed to create patient record |
SUKI0010 | update-patient:failed | Patient | Failed to update patient information |
SUKI0011 | get-patient:failed | Patient | Failed to retrieve patient information |
SUKI0012 | note-submission:failed | Notes | Failed to submit clinical note |
SUKI0013 | ambient-fail | Ambient | Ambient session operation failed |
SUKI0014 | encounter-fail | Encounter | General encounter operation failed |
SUKI0015 | token-update-fail | Authentication | Failed to update partner token |
SUKI0016 | unsupported-loinc-codes | Configuration | Provided LOINC codes are not supported |
SUKI0017 | no-supported-loinc-codes | Configuration | No supported LOINC codes found in configuration |
SUKI0018 | multiple-pbn-sections | Configuration | Multiple sections marked as PBN (Problem-Based Note) |
ErrorDetail
Detailed information about a specific error.
type ErrorDetail = {
name: `init:sdk-init-failed` | `init:auth-failed` ...;
message: string;
reason?: ErrorReasons;
}
Property | Type | Required | Description |
---|
message | string | ✓ | Human-readable description of the error |
name | string | ✓ | Unique name for the error (corresponds to error code) |
reason | ErrorReasons | - | Additional context about why the error occurred |
ErrorReasons
Specific reasons that provide additional context for why an error occurred.
type ErrorReasons =
| "lib-error"
| "no-init"
| "no-partner-token"
| "missing-partner-details"
| "no-init-or-auth"
| "service-error"
| "already-started"
| "no-ambient"
| "ambient-in-progress"
| "invalid-encounter"
| "unsupported-loinc-codes"
| "no-supported-loinc-codes"
| "multiple-pbn-sections";
Reason | Category | Description |
---|
already-started | State | Operation attempted when already in progress |
ambient-in-progress | Ambient | Cannot perform action while ambient session is active |
invalid-encounter | Data | Provided encounter data is invalid or malformed |
lib-error | System | Internal library or system error |
missing-partner-details | Configuration | Required partner authentication details are missing |
multiple-pbn-sections | Configuration | Multiple sections marked as PBN when only one is allowed |
no-ambient | State | No ambient session available for operation |
no-init | State | SDK not initialized before operation attempted |
no-init-or-auth | Authentication | SDK not initialized or user not authenticated |
no-partner-token | Authentication | Partner token is missing or invalid |
no-supported-loinc-codes | Configuration | No supported LOINC codes found |
service-error | Network | External service or API error |
unsupported-loinc-codes | Configuration | Provided LOINC codes are not supported |