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: 
pnpm add @suki-sdk/js@latest

​
Step 2: Update Provider Initialization

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

​
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

​
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.

​
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.

​
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

FieldDescriptionDefaultTypeRequired
showCloseButtonControls visibility of the close button in the headerfalseBooleanNo
showCreateEmptyNoteButtonControls visibility of the “Create Empty Note” button on the patient profilefalseBooleanNo
showStartAmbientButtonControls visibility of the “Start Ambient” button for ambient mode initiationtrueBooleanNo
sectionEditing.enableDictationControls the microphone icon for voice input (activates voice-to-text feature)falseBooleanNo
sectionEditing.enableCopyControls the copy icon for text copying functionalityfalseBooleanNo
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: 
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

​
Common Migration Errors

​
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