Migrating to v2

The v2.0.0 release of Suki.js includes significant improvements that enhance clinical documentation workflows and standardize healthcare integrations. This guide will walk you through the migration process step by step.

Overview of Changes

The v2.0.0 release introduces several key improvements:

Enhanced Provider Onboarding: Automatic provider registration with required provider information
LOINC Standardization: Standardized clinical note sections using LOINC codes
Expanded Theme Customization: More comprehensive UI styling options
Improved Section Editing: New dictation and copy capabilities
Better Error Handling: Enhanced validation and error reporting

This is a breaking change release. Please review all changes carefully before upgrading.

Step 1: Update Package Version

Begin by updating to the latest version of the Suki SDK:

JavaScript
React

pnpm add @suki-sdk/js@latest

Step 2: Update Provider Initialization

The initialization process now requires additional provider information for automatic onboarding.

JavaScript
React

Before (v1.x)

import { initialize } from "@suki-sdk/js";

const sdkClient = initialize({
  partnerId: "your-partner-id",
  partnerToken: "your-token",
  enableDebug: true,
  theme: {
    primaryColor: "#4287f5",
  },
});

After (v2.0)

import { initialize } from "@suki-sdk/js";

const sdkClient = initialize({
  // Required partner details
  partnerId: "your-partner-id",
  partnerToken: "your-token",
  providerName: "Dr. John Q. Doe", // NEW: Required
  providerOrgId: "organization-id", // NEW: Required

  // Optional fields
  providerSpecialty: "FAMILY_MEDICINE", // NEW: Optional
  enableDebug: true,
  logLevel: "info", // NEW: Optional
  isTestMode: false, // NEW: Optional
  theme: {
    primary: "#4287f5", // CHANGED: renamed from primaryColor
    background: "#ffffff", // NEW: Optional
    secondaryBackground: "#f5f5f5", // NEW: Optional
    foreground: "#333333", // NEW: Optional
    warning: "#ff9900", // NEW: Optional
  },
});

New Required Fields

providerName (Required)

The full name of the healthcare provider using the SDK, including first name, middle name (if applicable), and last name separated by spaces.This information enables automatic provider onboarding in the Suki system without manual registration.Example: "Dr. Jane Marie Smith"

providerOrgId (Required)

The unique identifier of the healthcare organization to which the provider belongs in your system.This ID facilitates automatic organizational mapping and ensures proper data segregation in the Suki platform. This should match the organization ID in your system’s database for consistency across platforms.Example: "northwell-1234" or "memorial-hermann-5678"

providerSpecialty (Optional)

The medical specialty of the provider, which helps tailor the SDK’s functionality to specific clinical contexts.If omitted, the system defaults to "FAMILY_MEDICINE" as the provider specialty. This information improves the relevance of automated suggestions and templates during onboarding.Refer to the Specialties documentation for a comprehensive list of supported specialties.

Step 3: Update Ambient Options Configuration

The ambient options structure has been completely redesigned to use standardized LOINC codes instead of custom note type IDs.

JavaScript
React

Before (v1.x)

sdkClient.mount({
  rootElement: document.getElementById("suki-root"),
  encounter: encounterDetails,
  ambientOptions: {
    prefill: {
      noteTypeIds: ["note-type-1", "note-type-2"],
    },
  },
});

After (v2.0)

sdkClient.mount({
  rootElement: document.getElementById("suki-root"),
  encounter: encounterDetails,
  ambientOptions: {
    sections: [
      {
        loinc: "29545-1", // Physical Examination
      },
      {
        loinc: "10164-2", // History of Present Illness
      },
      {
        loinc: "51847-2", // Assessment and Plan
        isPBNSection: true, // NEW: Problem-based charting support
      },
    ],
  },
});

The prefill.noteTypeIds approach is still supported but deprecated and will be removed in future versions. We strongly recommend migrating to the new section-based configuration using LOINC codes.Refer to the Note Sections documentation for a complete list of supported sections and corresponding LOINC codes.

Step 4: Update UI Options Configuration

The uiOptions property now provides more granular control over the SDK’s user interface elements.

JavaScript
React

Before (v1.x)

sdkClient.mount({
  rootElement: document.getElementById("suki-root"),
  encounter: encounterDetails,
  ambientOptions: { /* ... */ },
  uiOptions: {
    showCloseButton: true,
    showCreateEmptyNoteButton: true,
  },
  onClose: () => {
    console.log("SDK closed");
  },
});

After (v2.0)

sdkClient.mount({
  rootElement: document.getElementById("suki-root"),
  encounter: encounterDetails,
  ambientOptions: { /* ... */ },
  uiOptions: {
    showCloseButton: true,
    showCreateEmptyNoteButton: true,
    showStartAmbientButton: true, // NEW: Control ambient button visibility
    sectionEditing: { // NEW: Section-level editing controls
      enableDictation: true, // NEW: Voice input for sections
      enableCopy: true, // NEW: Copy functionality
    },
  },
  onClose: () => {
    console.log("SDK closed");
  },
});

UI Options Reference

Field	Description	Default	Type	Required
`showCloseButton`	Controls visibility of the close button in the header	`false`	Boolean	No
`showCreateEmptyNoteButton`	Controls visibility of the “Create Empty Note” button on the patient profile	`false`	Boolean	No
`showStartAmbientButton`	Controls visibility of the “Start Ambient” button for ambient mode initiation	`true`	Boolean	No
`sectionEditing.enableDictation`	Controls the microphone icon for voice input (activates voice-to-text feature)	`false`	Boolean	No
`sectionEditing.enableCopy`	Controls the copy icon for text copying functionality	`false`	Boolean	No

You should only provide explicit values when you need to enable specific features. For example:

// Enable only the copy feature and showStartAmbientButton
uiOptions: {
  showStartAmbientButton: true,
  sectionEditing: {
    enableCopy: true
  }
}

Step 5: Update Note Submission Handling

The note submission payload now includes LOINC codes for better standardization.

Before (v1.x)

onNoteSubmit: (note) => {
  console.log("Note ID:", note.noteId);
  note.contents.forEach((section) => {
    console.log(`Section: ${section.title} - ${section.content}`);
  });
}

After (v2.0)

onNoteSubmit: (note) => {
  console.log("Note ID:", note.noteId);
  note.contents.forEach((section) => {
    console.log(`Section: ${section.title} - ${section.content}`);
    console.log(`LOINC Code: ${section.loinc_code}`); // NEW: LOINC code included
    if (section.diagnosis) { // NEW: Enhanced diagnosis information
      console.log(`Diagnosis: ${section.diagnosis.icdDescription}`);
    }
  });
}

Example Response Structure

{
  "noteId": "82467ba8-71bc-46e2-8232-20d4d5629973",
  "contents": [
    {
      "title": "History",
      "content": "The patient is a 50-year-old female who has been experiencing fever for the last 10 days...",
      "loinc_code": "18233-4",
      "diagnosis": null
    },
    {
      "title": "Review of Systems",
      "content": "- No additional symptoms or pertinent negatives discussed during the encounter.",
      "loinc_code": "10164-2",
      "diagnosis": null
    },
    {
      "title": "Assessment and Plan",
      "content": "Viral hepatitis B with hepatic coma",
      "loinc_code": "51847-2",
      "diagnosis": {
        "icdCode": "B19.11",
        "icdDescription": "Unspecified viral hepatitis B with hepatic coma",
        "snomedCode": "26206000",
        "snomedDescription": "Hepatic coma due to viral hepatitis B",
        "hccCode": "HCC-1",
        "panelRanking": 1,
        "billable": true,
        "problemLabel": "Unspecified viral hepatitis B with hepatic coma"
      }
    }
  ]
}

Refer to NoteContent for the complete structure of the note content.

Complete Migration Example

Here’s a complete example showing the migration from v1.x to v2.0:

JavaScript
React

import { initialize } from "@suki-sdk/js";

const encounterDetails = {
  identifier: "encounter-id",
  patient: {
    identifier: "patient-id",
    name: {
      use: "official",
      family: "Doe",
      given: ["John"],
      suffix: ["MD"],
    },
    birthDate: "1990-01-01",
    gender: "Male",
  },
};

const sdkClient = initialize({
  partnerId: "your-partner-id",
  partnerToken: "your-token",
  enableDebug: true,
  theme: {
    primaryColor: "#4287f5",
  },
});

const unsubscribeInit = sdkClient.on("init:change", (isInitialized) => {
  if (isInitialized) {
    sdkClient.mount({
      rootElement: document.getElementById("suki-root"),
      encounter: encounterDetails,
      ambientOptions: {
        prefill: {
          noteTypeIds: ["note-type-1", "note-type-2"],
        },
      },
      uiOptions: {
        showCloseButton: true,
        showCreateEmptyNoteButton: true,
      },
      onNoteSubmit: (note) => {
        console.log("Note submitted:", note.noteId);
      },
      onClose: () => {
        console.log("SDK closed");
      },
    });
  }
});

Breaking Changes Summary

Required Provider Information

providerName and providerOrgId are now required fields in initialization
These fields enable automatic provider onboarding to the Suki system without manual registration

AmbientOptions Structure

Complete restructuring from prefill.noteTypeIds to a section-based configuration using LOINC codes
This change improves standardization and interoperability with healthcare systems
The old approach is deprecated but still supported temporarily

Theme Property Names

primaryColor renamed to primary
Added new theme properties: background, secondaryBackground, foreground, and warning
Enables more comprehensive UI customization

Required Mount Options

ambientOptions is now required when mounting the SDK (was optional in v1.x)
Ensures proper configuration of ambient mode capabilities

Common Migration Errors

Initialization Errors

missing-partner-details: Provider information is incomplete
no-partner-token: Authentication token is missing
no-init: SDK not properly initialized

Ambient Mode Errors

no-ambient: Ambient mode not available
ambient-in-progress: Another ambient session is active
already-started: Ambient session already running

LOINC Code Errors

unsupported-loinc-codes: One or more LOINC codes are not supported
no-supported-loinc-codes: No valid LOINC codes provided

Validation Checklist

After migration, verify the following:

All required provider information is supplied in initialization
AmbientOptions uses the new section-based configuration with LOINC codes
Theme configuration uses the new property names
Section editing features are configured as needed
All UI options are properly configured
Note submission handlers account for new LOINC code fields

Next Steps

Note Sections

Learn about supported LOINC codes and section configurations

Specialties

View the complete list of supported medical specialties

Error Handling

Implement proper error handling for your integration

Basic Usage

See complete examples of the v2.0 implementation

Documentation

Guides

API Reference

Examples

Product Updates

FAQs

Migrating to v2

Overview of Changes

Step 1: Update Package Version

Step 2: Update Provider Initialization

Before (v1.x)

After (v2.0)

New Required Fields

Step 3: Update Ambient Options Configuration

Before (v1.x)

After (v2.0)

Step 4: Update UI Options Configuration

Before (v1.x)

After (v2.0)

UI Options Reference

Step 5: Update Note Submission Handling

Before (v1.x)

After (v2.0)

Example Response Structure

Complete Migration Example

Breaking Changes Summary

Common Migration Errors

Validation Checklist

Next Steps

Note Sections

Specialties

Error Handling

Basic Usage

Documentation

Guides

API Reference

Examples

Product Updates

FAQs

​Overview of Changes

​Step 1: Update Package Version

​Step 2: Update Provider Initialization

​Before (v1.x)

​After (v2.0)

​New Required Fields

​Step 3: Update Ambient Options Configuration

​Before (v1.x)

​After (v2.0)

​Step 4: Update UI Options Configuration

​Before (v1.x)

​After (v2.0)

​UI Options Reference

​Step 5: Update Note Submission Handling

​Before (v1.x)

​After (v2.0)

​Example Response Structure

​Complete Migration Example

​Breaking Changes Summary

​Common Migration Errors

​Validation Checklist

​Next Steps

Note Sections

Specialties

Error Handling

Basic Usage

Overview of Changes

Step 1: Update Package Version

Step 2: Update Provider Initialization

Before (v1.x)

After (v2.0)

New Required Fields

Step 3: Update Ambient Options Configuration

Before (v1.x)

After (v2.0)

Step 4: Update UI Options Configuration

Before (v1.x)

After (v2.0)

UI Options Reference

Step 5: Update Note Submission Handling

Before (v1.x)

After (v2.0)

Example Response Structure

Complete Migration Example

Breaking Changes Summary

Common Migration Errors

Validation Checklist

Next Steps