# OnairosButton — props reference (web / npm package)

This document describes the public surface of **`OnairosButton`** in the **web** SDK (`onairos` npm). The **source of truth for runtime behavior** is `src/onairosButton.jsx` (props forwarded to `src/components/UniversalOnboarding.jsx`, `src/components/TrainingScreen.jsx`, and helpers such as `src/utils/pollTrainingStatus.js`).

For **cross-platform contracts** (training polling, `autoFetch` + `backgroundLoadData` matrix, `authorizedData`, completion shape), see [`CROSS_SDK_PARITY.md`](./CROSS_SDK_PARITY.md).

---

## Migration from v7.x → v8.0.0

Two breaking changes consolidate the training props.

| Old | New |
| --- | --- |
| `enableTraining={false}` | `backgroundLoadData={true}` (host owns lifecycle) **or** `trainingScreenMode="none"` (returning users only) |
| `trainingScreenMode="real"` (was the default — fast traits-only completion) | `trainingScreenMode="fast"` |
| `trainingScreenMode="full"` | `trainingScreenMode="real"` |

`enableTraining` is removed entirely. The `'real'` value now means the slow
full-model-train mode (was `'full'`). The new default is `'fast'` (was `'real'`'s
behaviour). When `backgroundLoadData={true}` and `trainingScreenMode` is unset,
the SDK auto-resolves to `'none'` so no loading screen renders after PIN.

---

## Entry points

| Entry | Role |
|--------|------|
| **`<OnairosButton />`** | Renders the touch target; opens onboarding modals (`UniversalOnboarding` / `TrainingScreen` / explainer steps). |
| **`ref.trigger()`** | Same path as a tap (`handlePress` → modal). |
| **`initializeApiKey`** | From `src/services/apiKeyService.js` — must succeed before the button is interactive (unless `skipApiKeyInitialization` or inline `apiKey` init applies). |

---

## Result type: `onComplete(result)`

The modern callback is **`onComplete?: (result) => void`**.

| Field | Meaning |
|--------|---------|
| `token` | Bearer token for `apiUrl` and `training.statusUrl` polling |
| `apiUrl` | Backend URL for follow-up API calls |
| `approved` | String list of approved data tiers / scopes |
| `userData` | `{ email?, username?, connectedAccounts, skipped? }` |
| `apiResponse?` | Fetched traits/insights when `autoFetch` populated them |
| `platformData?` | Raw per-platform payloads |
| `authorizedData?` | Flags aligned with backend (see parity doc §2) |
| `training?` | `{ ready, statusUrl?, pollIntervalMs? }` after URL resolution |

**Legacy:** `onResolved(apiUrl, token, userData)` may still fire after `onComplete` for backward compatibility.

**`onPress`:** Fires after a successful flow when completion runs (not on the initial tap).

---

## Parity props (data / training / OAuth)

| Prop | Default | Web behavior |
|------|---------|----------------|
| `autoFetch` | `false` | After resolution, POST to resolved `apiUrl` when training is ready (or traits-only path); merges into `apiResponse`. |
| `backgroundLoadData` | `false` | Drives the `trainingScreenMode` auto-default: when `true` and `trainingScreenMode` is not set, `'none'` is used so no SDK training loading screen renders after PIN/onboarding. Polling and the resolved `apiUrl` POST are still governed by `autoFetch`; hosts that own the result fetch should set `autoFetch={false}` and use `training.statusUrl`, `apiUrl`, and `token` from `onComplete`. |
| `trainingScreenMode` | `'fast'` (or `'none'` when `backgroundLoadData=true`) | One of `'mock' \| 'fast' \| 'real' \| 'none'`. `'mock'` — 5 s fake animation, no socket. `'fast'` — real socket, completes when personality traits land (~30 s – 1 min). `'real'` — real socket, waits for full MIND1 model train (~2 – 3 min). `'none'` — `TrainingScreen` does not render; intended for already-trained users or `backgroundLoadData=true` flows. |
| `preCheck` | — | If returns `false` or throws, flow stops and `onRejection` is called. |
| `onRejection` | — | Called when `preCheck` fails. |
| `returnLink` | — | On mobile/Capacitor OAuth, used as OAuth `returnUrl` when non-empty (normalized; onairos OAuth params stripped). |
| `recommendedPlatforms` | — | Platforms listed first in onboarding UI order (then remainder). |
| `preferredPlatform` | — | Same as RN `preferredPlatform`; merged with `priorityPlatform` as `effectivePriorityPlatform`. |
| `primaryAuthOnly` | `false` | Combined with `authOnly`: immediate exit after auth when either is true. |
| `useNewWelcomeFlow` | `false` | New users skip `dataExplainer` → go to `onboarding` (Valentine/Lunar/default new-user detection unchanged). |
| `preferencesMbti` | `false` | When `true` and the user approved **`preferences`**: set `Info.Options.preferencesMbti` on `/getAPIurlMobile` and send `preferencesMbti: true` on inference POSTs (server MBTI 16-type probe; optional/absent `Input` when the preset is in the token). Backend **3.9.35+**; see `sdk-integration/MBTI_INFERENCE_INPUT_PRESET.md`. |

---

## Pre-authenticated entry (skip the in-modal email/ID login)

For white-label / low-friction integrations, the host app can supply identity up front so
the user never sees the Onairos email/ID login step. This reduces the number of places a
user has to enter credentials and improves conversion.

| Prop | Type | Behavior |
|------|------|----------|
| `preAuthToken` | `string \| null` | A valid Onairos JWT minted by the host (or your backend on the user's behalf). When set, the SDK **skips login entirely** and routes straight to permissions/onboarding. The token is persisted to `localStorage` (`onairos_user_token`) and used to fetch the user's identity + connected platforms. Use this when your app already knows who the user is. |
| `preVerifiedEmail` | `string \| null` | A host-verified email address. The SDK pre-fills/short-circuits the email step so the user continues without re-entering or re-verifying their email. Use this when you have a verified email but not a full token. (`preverifiedEmail` / `preVerifiedEamil` are accepted aliases.) |

```jsx
// Full pre-auth: user goes straight to connecting apps + consent.
<OnairosButton
  webpageName="My App"
  requestData={["personalization"]}
  preAuthToken={hostMintedJwt}
  onComplete={handleComplete}
/>

// Email-only pre-auth: skip email entry/verification, keep the rest of the flow.
<OnairosButton
  webpageName="My App"
  requestData={["personalization"]}
  preVerifiedEmail="user@example.com"
  onComplete={handleComplete}
/>
```

**Notes**
- If `preAuthToken` is invalid/expired, the SDK falls through to the normal login flow.
- If the user explicitly dismisses the modal during a `preAuthToken` flow, it will not auto-reopen.
- Pair with `autoFetch` / `backgroundLoadData` to control whether the SDK fetches results or hands `apiUrl` + `token` back to you.

---

## Consent UI (DataRequest)

The consent sheet is intentionally minimal to reduce friction:

| Item | UI | Emitted `approved` scopes |
|------|----|---------------------------|
| **Basic Profile** | Always included (shown as a quiet line, not a checkbox) | `basic` |
| **Personalization** | The single checkbox (pre-selected). Combines the former *Preferences* + *Interests* toggles | `preferences`, `personality` |
| **Raw Memories** | Optional second checkbox — only shown when a raw-capable source is connected and the developer offers it | `rawMemories` |

So a typical app shows **one checkbox**, and **two at most** (when Raw Memories is available).
Collapsing the UI does **not** drop scopes: `requestData` is matched against each option's
underlying scopes, and an enabled combined toggle still emits every scope it represents.

| Prop | Default | Behavior |
|------|---------|----------|
| `privacyPolicyUrl` | `'https://privacy.onairos.io'` | URL opened by the info (ⓘ) control on the onboarding header and the consent sheet. Set to your own policy for white-label, or `null`/empty to hide the link. |

---

## Other props (summary)

Styling, `AppName`, `requestData`, `allowedPlatforms`, `dataUsageDescription`, `fastTraits`, `inferenceData`, `debug`, `testMode`, `skipApiKeyInitialization`, `apiKey`, `authOnly`, `priorityPlatform`, `enableLogging`, etc. follow existing web wiring in `onairosButton.jsx` and `UniversalOnboarding.jsx`.

---

## Implementation map (web files)

| Concern | File |
|---------|------|
| Button, resolution, `authorizedData` / `training` on result | `src/onairosButton.jsx` |
| Platform list, OAuth return URL, explainer | `src/components/UniversalOnboarding.jsx` |
| Training UI + `trainingScreenMode === 'mock'` | `src/components/TrainingScreen.jsx` |
| Status URL polling (RN parity) | `src/utils/pollTrainingStatus.js` (also exportable from package `src/index.js`) |

---

## Change log

- **2026-06-17** — Documented pre-authenticated entry (`preAuthToken` / `preVerifiedEmail`); simplified consent UI to one checkbox (two with Raw Memories) by combining Preferences + Interests into **Personalization**; added `privacyPolicyUrl` and onboarding header copy that explains connector data usage.
- **2026-04-22** — Web parity props and docs; moved from `sdk-integration/` to `docs/`.