Migrating to v2

Complete guide to migrate from Suki.js v1 to v2 with enhanced provider onboarding, LOINC standardization, and improved UI customization.

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

pnpm

pnpm add @suki-sdk/js@latest

pnpm

pnpm add @suki-sdk/js@latest

pnpm

pnpm add @suki-sdk/react@latest

Step 2: Update Provider Initialization

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

JavaScript

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
  },
});

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
  },
});

Before (v1.x)

import { SukiProvider, useSuki } from "@suki-sdk/react";

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

function App() {
  const { init, isInitialized } = useSuki();

  useEffect(() => {
    if (!isInitialized) {
      init(initOptions);
    }
  }, [init, isInitialized]);

  return <div>Your app content</div>;
}

After (v2.0)

import { SukiProvider, useSuki } from "@suki-sdk/react";

const initOptions = {
  // 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
  },
};

function App() {
  const { init, isInitialized } = useSuki();

  useEffect(() => {
    if (!isInitialized) {
      init(initOptions);
    }
  }, [init, isInitialized]);

  return <div>Your app content</div>;
}

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

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
      },
    ],
  },
});

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
      },
    ],
  },
});

Before (v1.x)

<SukiAssistant
  encounter={encounter}
  ambientOptions={{
    prefill: {
      noteTypeIds: ["note-type-1", "note-type-2"],
    },
  }}
  onNoteSubmit={(note) => {
    console.log("Note submitted:", note);
  }}
/>

After (v2.0)

<SukiAssistant
  encounter={encounter}
  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
      },
    ],
  }}
  onNoteSubmit={(note) => {
    console.log("Note submitted:", note);
  }}
/>

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

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");
  },
});

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");
  },
});

Before (v1.x)

<SukiAssistant
  encounter={encounter}
  ambientOptions={{ /* ... */ }}
  uiOptions={{
    showCloseButton: true,
    showCreateEmptyNoteButton: true,
  }}
  onClose={() => {
    console.log("SDK closed");
  }}
/>

After (v2.0)

<SukiAssistant
  encounter={encounter}
  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

Before (v1.x)

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");
      },
    });
  }
});

Before (v1.x)

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");
      },
    });
  }
});

Before (v1.x)

import React, { useEffect } from "react";
import { SukiAssistant, SukiProvider, useSuki } from "@suki-sdk/react";

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

const encounter = {
  identifier: "encounter-123",
  patient: {
    identifier: "patient-456",
    name: {
      use: "usual",
      family: "Smith",
      given: ["John"],
      suffix: [],
    },
    birthDate: "1980-01-15",
    gender: "male",
  },
};

function App() {
  const { init, isInitialized } = useSuki();

  useEffect(() => {
    if (!isInitialized) {
      init(initOptions);
    }
  }, [init, isInitialized]);

  return (
    <SukiAssistant
      encounter={encounter}
      ambientOptions={{
        prefill: {
          noteTypeIds: ["note-type-1", "note-type-2"],
        },
      }}
      onNoteSubmit={(note) => {
        console.log("Note submitted:", note.noteId);
      }}
      uiOptions={{
        showCloseButton: true,
        showCreateEmptyNoteButton: true,
      }}
      onClose={() => {
        console.log("SDK closed");
      }}
    />
  );
}

function AppWithProvider() {
  return (
    <SukiProvider>
      <App />
    </SukiProvider>
  );
}

export default AppWithProvider;

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

Assistant

Responses are generated using AI and may contain mistakes.