# 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]**._