Skip to main content

​
Overview

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.

​
Changes Snapshot

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)

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

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

​
After (v2.0)

JavaScript
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

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"
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"
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)

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

​
After (v2.0)

JavaScript
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)

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

​
After (v2.0)

JavaScript
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

Use the UI configuration options to control the visibility and functionality of various interface elements like buttons and editing features.
You should only provide explicit values when you need to enable specific features. For example:
JavaScript
// 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)

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

​
After (v2.0)

JavaScript
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

JSON
{
  "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

The following breaking changes require immediate attention when migrating from v1.x to v2.0. Each change is designed to improve functionality, standardization, and developer experience.

​
Provider Information

​
providerName
string
required
The provider’s full name. This field is now required during SDK initialization to enable automatic provider onboarding to the Suki system.Migration Impact: Previously optional, now required in InitializationConfig.
​
providerOrgId
string
required
The unique identifier for the provider’s organization. This field is now required during SDK initialization.Migration Impact: Previously optional, now required in InitializationConfig. This enables seamless provider registration without manual onboarding steps.

​
AmbientOptions Structure

The ambientOptions structure has been completely redesigned in v2.0. The previous prefill.noteTypeIds approach is deprecated.
​
sections
array
required
An array of section objects that define which note sections to generate. Each section is identified by a LOINC code for improved standardization and interoperability with healthcare systems.v1.x Deprecated Approach:
TypeScript
ambientOptions: {
  prefill: {
    noteTypeIds: ['soap', 'hpi']
  }
}
v2.0 Required Approach:
TypeScript
ambientOptions: {
  sections: [
    { loinc: '48765-2' }, // Allergies
    { loinc: '10164-2' }  // History of Present Illness
  ]
}
Migration Impact: You must replace all noteTypeIds references with LOINC-based section configurations. Refer to the Note Sections documentation for complete LOINC code mappings.

​
Theme Configuration

​
primary
string
Renamed from primaryColor. Defines the primary brand color for the SDK interface.Migration Impact: Update all primaryColor references to primary in your theme configuration.
​
background
string
New property. Defines the main background color for the SDK interface.Migration Impact: This is a new optional property that enhances UI customization capabilities.
​
secondaryBackground
string
New property. Defines the secondary background color for panels and cards within the SDK interface.Migration Impact: This is a new optional property that provides more granular control over the visual hierarchy.
​
foreground
string
New property. Defines the primary text color for the SDK interface.Migration Impact: This is a new optional property that ensures text readability across different background colors.
​
warning
string
New property. Defines the color used for warning messages and alerts.Migration Impact: This is a new optional property that improves the visibility of important notifications.

​
Mount Configuration

​
ambientOptions
AmbientOptions
required
Configuration options for ambient mode functionality. This field is now required when mounting the SDK.Migration Impact: Previously optional in v1.x, now required in v2.0. You must provide ambientOptions with at least one section defined when calling mount().Example:
TypeScript
await sukiSDK.mount({
  target: document.getElementById('suki-container'),
  ambientOptions: {
    sections: [
      { loinc: '48765-2' }
    ]
  }
});

​
Common Migration Errors

  • missing-partner-details: Provider information is incomplete
  • no-partner-token: Authentication token is missing
  • no-init: SDK not properly initialized
  • no-ambient: Ambient mode not available
  • ambient-in-progress: Another ambient session is active
  • already-started: Ambient session already running
  • 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