Migration Guide

Step-by-step guide to migrate from SofIA SDK v0.x to v1.0

This guide covers every breaking change and deprecation between SofIA SDK v0.0.x and v1.0.0, with before/after code examples and a checklist to complete the migration.

Start by upgrading to the latest version:

npm install @omniloy/sofia-sdk@latest

Then make sure the SDK is imported once in your app’s entry file — this side-effect import is what registers the <sofia-sdk> custom element. Without it, the component never mounts:

// In your entry file (main.js, index.js, app.js, ...)
import '@omniloy/sofia-sdk';

Using React? Import the component and its styles from the /react subpath instead:

import { Omniscribe } from '@omniloy/sofia-sdk/react';
import '@omniloy/sofia-sdk/react/index.css';

Not sure whether the SDK registered? Run customElements.get('sofia-sdk') in the browser console — it should return the component definition, not undefined.

Migration overview

Area	What changed	Impact
Template prop	toolsargs → template	High — must rename
Chat-only mode	isonlychat removed	Medium — auto-detected now
Generate control	disablegenerate removed	Medium — omit template/templateid instead
Action control	disableactions removed	Low — don’t mount the component
UI customization	sofiatitle removed	Low — title is always “SofIA”
Loading state	isscreenloading removed	Low — not available in Chat UI
Transcriptor	transcriptorselectvalues removed	Low — no effect
Report rendering	renderReportContent removed	Low — not available in Chat UI
Fill callback	handleFill removed	Low — not available in Chat UI
Connection URLs	wssurl deprecated (v1.0.7); baseurl now conditional	Medium — remove wssurl; drop baseurl (v1.0.8) if your key doesn’t require it

Step-by-step migration

1. Rename toolsargs to template

The toolsargs prop has been renamed to template. The JSON Schema content is identical — only the attribute name changes.

Before (v0.x):

<sofia-sdk
  baseurl="https://api.example.com"
  apikey="your-key"
  userid="doctor-1"
  patientid="patient-1"
  toolsargs='{"$schema":"http://json-schema.org/draft-07/schema#","title":"notes","type":"object","properties":{"diagnosis":{"type":"string"}}}'
></sofia-sdk>

After (v1.0):

<sofia-sdk
  baseurl="https://api.example.com"
  apikey="your-key"
  userid="doctor-1"
  patientid="patient-1"
  template='{"$schema":"http://json-schema.org/draft-07/schema#","title":"notes","type":"object","properties":{"diagnosis":{"type":"string"}}}'
  templateid="your-template-id"
></sofia-sdk>

In v1.0, templateid is also required for report generation. Without both template and templateid, the SDK operates in chat-only mode.

2. Remove isonlychat

Chat-only mode is now automatic. If you omit both template and templateid, the SDK operates in chat-only mode without showing the generate button.

Before (v0.x):

<sofia-sdk
  isonlychat="true"
  baseurl="https://..."
  <!-- other props -->
></sofia-sdk>

After (v1.0):

<!-- Simply omit template and templateid -->
<sofia-sdk
  baseurl="https://..."
  <!-- other props -->
></sofia-sdk>

3. Remove disablegenerate

To hide the generate button, omit template and templateid instead of setting a flag.

Before (v0.x):

<sofia-sdk
  disablegenerate="true"
  toolsargs='...'
  <!-- other props -->
></sofia-sdk>

After (v1.0):

<!-- Omit template and templateid to disable generation -->
<sofia-sdk
  baseurl="https://..."
  <!-- other props, no template/templateid -->
></sofia-sdk>

4. Remove disableactions

If the component should not be rendered, don’t mount it at all instead of passing a disable flag.

Before (v0.x):

<sofia-sdk disableactions="true" ...></sofia-sdk>

After (v1.0):

// Conditionally render based on your application logic
if (shouldShowSofia) {
  document.getElementById('container').innerHTML = '<sofia-sdk ...></sofia-sdk>';
}

5. Remove remaining deprecated props

Remove these props entirely — they have no effect in v1.0:

Prop	Reason
sofiatitle	Title is always “SofIA”
isscreenloading	Not available in Chat-based UI
transcriptorselectvalues	No effect
renderReportContent	Custom rendering not available in Chat UI
handleFill	Not available in Chat UI

6. Update callback assignments (framework-specific)

The handleReport, setIsOpen, and setGetLastReport callbacks remain unchanged. However, verify your bindings are correct:

Vanilla JS:

document.addEventListener('DOMContentLoaded', () => {
  const sofia = document.querySelector('sofia-sdk');
  sofia.handleReport = (report) => {
    console.log('Report:', report);
  };
});

React:

useEffect(() => {
  if (sofiaRef.current) {
    sofiaRef.current.handleReport = handleReport;
    sofiaRef.current.setIsOpen = setIsOpen;
  }
}, [handleReport, setIsOpen]);

Angular:

ngAfterViewInit() {
  this.sofia.nativeElement.handleReport = this.handleReport.bind(this);
  this.sofia.nativeElement.setIsOpen = this.setIsOpen.bind(this);
}

7. Remove wssurl (v1.0.7+) and simplify baseurl (v1.0.8+)

As of v1.0.7, wssurl is deprecated and ignored — the transcription WebSocket URL is delivered by the settings API. Remove it. For newer keys, the SDK (v1.0.8) resolves the endpoint automatically, so you can also drop baseurl (Omniloy tells you whether your key needs it).

Before:

<sofia-sdk
  baseurl="https://api.example.com"
  wssurl="wss://ws.example.com"
  apikey="your-key"
  userid="doctor-1"
  patientid="patient-1"
></sofia-sdk>

After (newer key):

<sofia-sdk
  apikey="your-key"
  userid="doctor-1"
  patientid="patient-1"
></sofia-sdk>

Does your key still require baseurl? Keep it, but still remove wssurl.

Migration checklist

Use this checklist to verify your migration is complete:

• Renamed all toolsargs attributes to template
• Added templateid wherever template is used
• Removed isonlychat — chat-only mode is automatic when template/templateid are omitted
• Removed disablegenerate — omit template/templateid instead
• Removed disableactions — conditionally mount/unmount the component
• Removed sofiatitle, isscreenloading, transcriptorselectvalues
• Removed renderReportContent and handleFill callbacks
• Removed wssurl — deprecated and ignored since v1.0.7
• Dropped baseurl if your key doesn’t require it; kept it otherwise
• Verified handleReport callback still works correctly
• Tested with debug="true" to confirm no deprecation warnings in console
• Validated in all target browsers

Enable debug="true" during migration. The SDK logs deprecation warnings for any v0.x props still in use, prefixed with [Sofia SDK] DEPRECATED:.

Breaking changes summary

Props removed in v1.0

These props were deprecated in v0.0.10 and are removed in v1.0. If still passed, they have no functional effect but emit deprecation warnings when debug="true" is enabled.

New requirements in v1.0

• templateid is now required alongside template for report generation
• The generate button only appears when both template and templateid are provided
• template must be a valid JSON Schema Draft-07 with $schema, type, and properties

Connection props (changed in v1.0.7)

• apikey — required connection prop (unchanged)
• wssurl — deprecated and ignored since v1.0.7; the transcriber URL now comes from the settings API — remove it

Connection props (changed in v1.0.8)

• baseurl — now conditional: optional for newer keys (endpoint auto-resolved), still required otherwise

No changes

These props work exactly the same in v1.0:

• userid, patientid — required session identifiers
• patientdata — optional patient context
• language — localization ("es" or "en")
• debug — enables verbose logging
• isopen — controls widget visibility
• handleReport — report delivery callback
• setIsOpen — visibility state callback
• setGetLastReport — last report retrieval