onairos/docs/SDK_PARITY_ROLLUP_2026_04_24_to_05_02.md

The Onairos Library is a collection of functions that enable Applications to connect and communicate data with Onairos Identities via User Authorization. Integration for developers is seamless, simple and effective for all applications. LLM SDK capabiliti

# SDK spec & parity rollup (Apr 24 – May 2, 2026)

**Purpose:** Single place for **documentation** and **non-web SDK parity** (mobile, native hosts, server wrappers). Aligns with `CHANGELOG.md` and recent `main` commits (`8.0.0` → `8.1.9`).

**Detailed HTTP/training contracts:** still authoritative in **`docs/DEVELOPER_SDK_CHANGES.md`**.

---

## 1. Release map (what actually changed for integrators)

| Version | Runtime / API surface | Package / install only |
|--------|------------------------|-------------------------|
| **8.0.0** | **Breaking:** training props consolidated (`enableTraining` removed; `trainingScreenMode` values). `closeOnConsent`, `backgroundLoadData`, inference retry on `pending`. CDN-only assets (`files` trimmed). | Turbopack-safe ESM entry usage via exports |
| **8.0.1** | Same entry files; bundler targets `onairos.esm.turbopack.js` for AMD/Turbopack parse issues | — |
| **8.1.0** | **`webpageName`** forwarded to **`/persona/train`** and start-training sockets; **`appId`** from JWT / `webpageName` in those payloads | — |
| **8.1.4** | Inyo / insufficient-data path; universal onboarding after platform reconnect (bugfix) | — |
| **8.1.5** | **Data request UI/UX:** Raw Memories + **`allowedPlatforms`** rules; platform chips; Netflix/Spotify name normalization. **Email:** iOS/Safari OTP autofill (no new public prop names; same `requestData`, `allowedPlatforms`, `rawMemoriesOnly`, `rawMemoriesConfig`) | — |
| **8.1.6** | *None* (same `import`/`require` dist paths) | pnpm: testing libs → `devDependencies`; `socket.io-client` not duplicated as peer; `ajv` out of peers; `tailwindcss` optional peer |
| **8.1.8** | **Data request:** internal trim in `DataRequest` (no new public props) | — |
| **8.1.9** | *None* for `import` / `require` paths (same as 8.1.8) | `exports`: `./package.json`, full `.` conditions (RN, `module`, `browser`, `default`); Laravel → `onairos-laravel.js`; verify on pack |

**Unreleased / shipped in same window on `main` (see `CHANGELOG` “Unreleased” + Apr 24 commits):** background training handoff, `pollTrainingStatus` / `normalizeTrainingFromResolution` exports, `GET …/training/status` polling contract, `window.onairosBaseUrl`, Google auth success timing. Treat as **web SDK contract** to mirror in other clients.

---

## 2. Public props & objects (parity checklist)

### 2.1 Breaking (from **8.0.0**) — must mirror in every SDK

- **`enableTraining`:** removed.
- **`trainingScreenMode`:** `'mock' | 'fast' | 'real' | 'none'` (replaces old meanings — see **`docs/ONAIROS_BUTTON_PROPS.md`** migration table).

### 2.2 Data request — **`requestData` host flags** (8.1.5 semantic rules)

Same prop names as before; behaviour tightened:

| Concept | Developer expectation |
|--------|------------------------|
| Raw Memories row | Only if host asked for raw (`requestData.rawMemories`, or `rawMemoriesOnly` / `rawMemoriesConfig`), user has connected raw pipeline, and allowlist rules satisfied when **`allowedPlatforms`** is set. |
| **`allowedPlatforms`** non-empty | Must include ≥1 **raw-capable** platform (ChatGPT, Claude, Gemini, Grok, Netflix, Spotify, Sephora) or Raw Memories stays hidden. |
| Connected row | Shows **connected ∩ allowlist** plus **missing allowlist** chips (dashed); chips call **`onConnectMoreApps`**. |
| **`allowedPlatforms` empty / omitted** | No platform filter for that row (unchanged empty semantics). |

### 2.3 Training / persona — HTTP & payloads (**8.1.0**)

| Item | Spec |
|------|------|
| **`/persona/train`** | Include **`webpageName`** (and **`appId`** when derived from JWT / webpage) per backend allowlists. |
| Start-training socket payloads | Same **`appId` / `webpageName`** plumbing as web. |

### 2.4 Training polling — **`pollTrainingStatus`** (Apr 24 alignment)

| Item | Spec |
|------|------|
| Canonical URL | Prefer **`GET …/training/status`** with Bearer; use **`training.statusUrl`** from authorize when provided. |
| Ready condition | `success !== false` and `trainingStatus.isCurrentlyTraining === false` (plus legacy path unchanged). |
| Intervals | Honor **`polling.recommendedIntervalMs`** when present. |
| **429** | Backoff via **`Retry-After`** / JSON hints. |

Other SDKs should expose the same polling helpers or document equivalent loops.

### 2.5 Inference (**8.0.0** contract fragment)

- Retry when HTTP **200** but **`InferenceResult.status === 'pending'`** (`model_not_ready`), aligned with **202 `TRAITS_REGENERATING`** semantics.

---

## 3. Package / installation (integrators — not duplicated inside non-JS SDKs)

- **8.1.6:** Consumers using **pnpm**: declare **`react` / `react-dom`**; **`tailwindcss`** optional if using only bundled CSS; no **`ajv`** peer from Onairos.
- **8.1.9:** Strict **`exports`**: subpath **`onairos/package.json`** supported; **`onairos/laravel`** resolves to **`dist/onairos-laravel.js`**; Metro/React Native use **`react-native`** export when resolving **`"."`**.
- **Next.js 16 + Turbopack:** keep **`onairos`** as direct **`dependency`** and **`transpilePackages: ['onairos']`**; fix **`turbopack.root`** in monorepos if resolution fails (see Next docs).

---

## 4. Parity checklist (other SDK teams)

- [ ] Training props match **8.0.0** (`trainingScreenMode`, no `enableTraining`).
- [ ] **`webpageName` / `appId`** on **`/persona/train`** + start-training payloads (**8.1.0**).
- [ ] Data-request UX rules for **raw** + **`allowedPlatforms`** (**8.1.5**).
- [ ] Raw memories handoff: gate on **`authorizedData.rawMemories`**, optional **`rawMemoriesPolicy`**, **`traitIntent` from handoff** (**8.3.15** — **`docs/RAW_MEMORIES_SDK_UPDATE.md`**).
- [ ] OTP / verification UX if applicable (Safari one-time-code behaviour on web).
- [ ] **`pollTrainingStatus`** semantics + **`/training/status`** (**Apr 24 / Unreleased** section + **`DEVELOPER_SDK_CHANGES.md`**).
- [ ] Inference **`pending`** retry behaviour (**8.0.0**).
- [ ] Document install quirks only where relevant (**pnpm** peers — **8.1.6**; **Laravel** filename — **8.1.9**).

---

## 5. Source of truth order

1. **`CHANGELOG.md`** — version-by-version narrative.
2. This document — **rollup + parity**.
3. **`docs/DEVELOPER_SDK_CHANGES.md`** — training authorize response, polling, security fields.
4. **`docs/ONAIROS_BUTTON_PROPS.md`** — prop migration (**8.0.0**).

_Last aligned with `main` through **8.1.9** plus changelog entries under **[Unreleased]**._