> ## Documentation Index
> Fetch the complete documentation index at: https://omniloy.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# 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:

```bash theme={null}
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:

```javascript theme={null}
// 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:

```tsx theme={null}
import { Omniscribe } from '@omniloy/sofia-sdk/react';
import '@omniloy/sofia-sdk/react/index.css';
```

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

## 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):**

```html theme={null}
<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):**

```html theme={null}
<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>
```

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

### 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):**

```html theme={null}
<sofia-sdk
  isonlychat="true"
  baseurl="https://..."
  <!-- other props -->
></sofia-sdk>
```

**After (v1.0):**

```html theme={null}
<!-- 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):**

```html theme={null}
<sofia-sdk
  disablegenerate="true"
  toolsargs='...'
  <!-- other props -->
></sofia-sdk>
```

**After (v1.0):**

```html theme={null}
<!-- 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):**

```html theme={null}
<sofia-sdk disableactions="true" ...></sofia-sdk>
```

**After (v1.0):**

```javascript theme={null}
// 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:**

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

**React:**

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

**Angular:**

```typescript theme={null}
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:**

```html theme={null}
<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):**

```html theme={null}
<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

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

## 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