Migrating from v2 to v3

The v3 cutover collapses three integration patterns into the SDK:

1. Autocorrect — useAutocorrect.js hooks are deleted in favor of isa.zyins.autocorrector.correct().
2. Autocomplete — useAutocomplete.js hooks are deleted in favor of isa.zyins.medications.autocomplete() / conditions.autocomplete() / concepts.autocomplete().
3. Datasets — response-root maps (medications_by_condition, frequency_graphs) are gone; rows carry their relationships inline.

The case study below tracks bpp2.0, the reference consumer. Your migration will look similar.

bpp2.0 case study

bpp2.0 shipped two hooks from the reference-data wire protocol:

• src/sah-ui/Input/TextField/useAutocorrect.js — n-gram typo correction.
• src/sah-ui/Input/TextField/useAutocomplete.js — priority ranking with frequency boost.

Both implemented make_key client-side and rebuilt the medications_by_condition reverse index locally.

The v3 SDK ships these algorithms as drop-in replacements: DefaultAutocorrector and DefaultAutocompleteAlgorithm. The migration is three steps:

Step 1: delete the hooks

- import { useAutocorrect }   from 'src/sah-ui/Input/TextField/useAutocorrect';
- import { useAutocomplete }  from 'src/sah-ui/Input/TextField/useAutocomplete';

Both files come out of the tree. Any local typo-map JSON they imported comes out too — the SDK pulls it from the dataset bundle.

Step 2: route correction through the SDK

- const corrected = useAutocorrect(input, { mode: 'submit' });
+ const corrected = isa.zyins.autocorrector.correct(input, { mode: 'submit' });

The mode contract is identical: 'keyup' while typing, 'submit' on commit. Whitespace handling is identical. The onApplied analytics hook that the bpp2.0 implementation exposed inline is now a constructor option on the underlying corrector — see Autocorrect.

Step 3: route autocomplete through the SDK

- const suggestions = useAutocomplete(query, candidates, { limit: 5 });
+ const suggestions = await isa.zyins.medications.autocomplete(query, { limit: 5 });

The bucket priority and frequency-boost math are pixel-identical to the bpp2.0 hook. Note the await — the SDK accessor is async by design (leaves room for server-side rerankers; the default resolves synchronously).

If you were filtering candidates yourself, pass kinds instead:

import { Isa } from 'isa-sdk';

const isa = await Isa.withBearer();
declare const query: string;
const suggestions = await isa.zyins.reference.concepts.autocomplete(query, {
  limit: 5,
  kinds: ['medication'],
});

Step 4: stop deriving from response-root maps

The bpp2.0 reducer that maintained a medicationsByCondition cache, re-keyed by make_key, deletes entirely:

- const medsForCondition = state.medicationsByCondition[makeKey(conditionName)] ?? [];
+ const cond = isa.zyins.conditions.match(conditionName);
+ const medsForCondition = cond.medications(isa.zyins.reference.Sort.MostCommonFirst);

The condition's medications are inline on the row — match() resolves the canonical concept, medications(sort) walks the inline treated_with[].

What v2 surfaces still work

• POST /v2/prequalify — Still active. Existing clients continue to work. No urgency to deprecate.
• GET /v2/reference-data — Still returns the v2 shape. Plan a cutover in your release schedule; the SDK switched to /v3/datasets already.

What disappeared

The full v3 input pipeline

The recommended input flow for a picker form on v3 is:

import {
  Isa, Sex, Height, Weight, NicotineDuration, Coverage, ProductSelection, Products,
} from 'isa-sdk';

const isa = await Isa.withBearer();

// 1. Warm the cache (once per session is plenty; SDK reuses bundle).
await isa.zyins.datasets.get();

// 2. As the user types, correct + autocomplete.
function onChange(input: string) {
  const corrected = isa.zyins.autocorrector.correct(input, { mode: 'keyup' });
  return isa.zyins.medications.autocomplete(corrected, { limit: 5 });
}

// 3. On commit, correct (submit mode) + match to a canonical concept.
function onSubmit(input: string) {
  const corrected = isa.zyins.autocorrector.correct(input, { mode: 'submit' });
  return isa.zyins.medications.match(corrected);
}

// 4. Feed the canonical name (or inputText for unknowns) into prequalify.
//    Medications live on the applicant; coverage and products are required.
const med = onSubmit('lisinopril');
const { data } = await isa.zyins.prequalify({
  applicant: {
    dob: '1962-04-18',
    sex: Sex.Male,
    height: Height.fromFeetInches(5, 10),
    weight: Weight.fromPounds(195),
    state: 'NC',
    nicotineUse: { lastUsed: NicotineDuration.Never },
    medications: [{
      name: med.name || med.inputText,
      use: 'HIGH BLOOD PRESSURE',
      firstFill: '11 MONTHS AGO',
      lastFill: '1 MONTH AGO',
    }],
  },
  coverage: Coverage.faceValue(25_000),
  products: ProductSelection.of([Products.Fex.AetnaAccendo]),
});

See Prequalify for the v3 request shape.

Cross-links

• Reference catalog — the bundle shape.
• Autocorrect — the correction adapter.
• Match — the resolution adapter.
• Autocomplete — the ranking adapter.
• Reference matching — the Concept accessors.