onairos/docs/ONAIROS_BUTTON_PROPS.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

# 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/`.