react-native-nitro-auth 0.5.7 → 0.5.9

package/README.md

@@ -1,213 +1,71 @@
 # react-native-nitro-auth
 
-[![npm version](https://img.shields.io/npm/v/react-native-nitro-auth?style=flat-square)](https://www.npmjs.com/package/react-native-nitro-auth)
-[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg?style=flat-square)](https://opensource.org/licenses/MIT)
-[![Nitro Modules](https://img.shields.io/badge/Powered%20by-Nitro%20Modules-blueviolet?style=flat-square)](https://nitro.margelo.com)
+Fast React Native authentication for Google Sign-In, Apple Sign-In, and Microsoft Entra ID, built on Nitro Modules and JSI.
 
-🚀 **High-performance, JSI-powered Authentication for React Native.**
+`react-native-nitro-auth` gives Expo and React Native apps one typed API for native social login, web OAuth, token refresh, incremental scopes, and auth state listeners without owning your app's long-term token storage.
 
-Nitro Auth is a modern authentication library for React Native built on top of [Nitro Modules](https://github.com/mrousavy/nitro). It provides a unified, type-safe API for Google, Apple, and Microsoft Sign-In with zero-bridge overhead.
+## Why Use It?
 
-## Why Nitro Auth?
+- One package for Google, Apple, and Microsoft authentication on React Native.
+- Native iOS and Android bridges powered by `react-native-nitro-modules`.
+- Expo config plugin for client IDs, URL schemes, entitlements, and Android resources.
+- Web implementation for Expo web with Google, Apple, and Microsoft OAuth.
+- Typed `useAuth()` hook, `AuthService`, `SocialButton`, and `AuthError`.
+- App-owned persistence model: tokens stay in memory unless your app stores a snapshot.
+- Built-in flows for silent restore, token refresh, account picker, login hints, and incremental Google scopes.
+- Consistent `AuthError` mapping for async `AuthService` failures on native and web.
 
-Nitro Auth is designed to replace legacy modules like `@react-native-google-signin/google-signin` with a modern, high-performance architecture.
+## Choose Your Path
 
-| Feature           | Legacy Modules               | Nitro Auth                                                                     |
-| :---------------- | :--------------------------- | :----------------------------------------------------------------------------- |
-| **Performance**   | Async bridge overhead (JSON) | **Direct JSI C++ (Zero-copy)**                                                 |
-| **Storage**       | Varies / Hidden defaults     | **Native: in-memory only; Web: session cache (tokens memory-only by default)** |
-| **Setup**         | Manual async initialization  | **Sync & declarative plugins**                                                 |
-| **Types**         | Manual / Brittle             | **Fully Generated (Nitrogen)**                                                 |
-| **Provider Data** | Varies                       | **Normalized auth payload**                                                    |
+| Need                                                                   | Use                                                               |
+| ---------------------------------------------------------------------- | ----------------------------------------------------------------- |
+| Google, Apple, or Microsoft sign-in in an Expo or React Native app     | `react-native-nitro-auth`                                         |
+| Generic OAuth or OIDC provider not covered by this package             | `expo-auth-session` or `react-native-app-auth`                    |
+| Firebase user management, password auth, MFA, and hosted auth platform | `@react-native-firebase/auth`, Auth0, Authgear, or your IDaaS SDK |
+| Server-side session validation                                         | Your backend; client JWT decode is display-only                   |
 
-## Features
+## Install
 
-- **Ultra-fast**: Direct C++ calls using JSI (no JSON serialization).
-- **Fully Type-Safe**: Shared types between TypeScript, C++, Swift, and Kotlin.
-- **Incremental Auth**: Request additional OAuth scopes on the fly.
-- **Expo Ready**: Comes with a powerful Config Plugin for zero-config setup.
-- **Cross-Platform**: Unified API for iOS, Android, and Web.
-- **Token Lifecycle Helpers**: `getAccessToken()` refreshes near-expiry tokens; `refreshToken()` allows explicit refresh control.
-- **Google One-Tap / Sheet**: Modern login experience on Android (Credential Manager) and iOS (Sign-In Sheet).
-- **Error Metadata**: Detailed native error messages for easier debugging.
-- **Normalized Provider Payload**: Exposes provider/user/token fields in a consistent cross-platform shape.
-- **App-Owned Persistence**: Native is stateless by default. Web keeps a non-sensitive session snapshot; apps decide long-term persistence strategy.
-
-## Design Philosophy
-
-This is an **auth-only package** - on **native** (iOS/Android) it does NOT store auth data by default.  
-On **web**, Nitro Auth stores a non-sensitive auth snapshot in `sessionStorage` by default; sensitive tokens stay memory-only unless explicitly enabled.
-
-The package provides:
-
-- Login/logout functionality for Google, Apple, and Microsoft
-- Token management (access token, refresh token, ID token)
-- Scope management (request/revoke scopes)
-- Consistent provider/user/token field exposure across iOS, Android, and Web
-
-**Storage is the responsibility of the app using this package.** Use your own storage layer (for example [react-native-nitro-storage](https://github.com/JoaoPauloCMarra/react-native-nitro-storage)) to persist app-level auth snapshots/tokens when needed.
-
-### Provider Data Availability
-
-Token/data shape is normalized, but provider SDKs do not always return all fields at login time:
-
-| Provider + Flow             | `idToken`  | `accessToken`                | `serverAuthCode`             | `expirationTime`                    |
-| --------------------------- | ---------- | ---------------------------- | ---------------------------- | ----------------------------------- |
-| Google (iOS)                | Usually ✅ | Provider-dependent           | Optional (if configured)     | Optional                            |
-| Google (Android One-Tap)    | ✅         | Usually `undefined` at login | `undefined`                  | Derived from ID token when possible |
-| Google (Android Legacy)     | ✅         | Usually `undefined` at login | ✅ (if server client is set) | Derived from ID token when possible |
-| Google (Web)                | ✅         | ✅                           | Optional (`code`)            | Usually ✅                          |
-| Microsoft (iOS/Android/Web) | ✅         | Usually ✅                   | `undefined`                  | Usually ✅                          |
-| Apple (iOS/Web)             | ✅         | `undefined`                  | `undefined`                  | `undefined`                         |
-
-> [!NOTE]
-> On Apple, email/name can be limited after first consent depending on Apple policy.
-
-## Installation
-
-```bash
+```sh
 bun add react-native-nitro-auth react-native-nitro-modules
 ```
 
-### Requirements
-
-| Dependency                   | Version      |
-| ---------------------------- | ------------ |
-| `react-native`               | `>= 0.75.0`  |
-| `react-native-nitro-modules` | `>= 0.35.0`  |
-| `react`                      | `*`          |
+For Expo projects, prebuild after adding the config plugin:
 
-For Expo projects, rebuild native code after installation:
-
-```bash
-bunx expo prebuild
+```sh
+bunx expo prebuild --clean
 ```
 
-### Testing locally (example app + Microsoft login)
-
-Fastest way to confirm the package and Microsoft login work:
-
-1. **Azure app (one-time)**  
-   In [Azure Portal](https://portal.azure.com) → **Azure Active Directory** → **App registrations** → **New registration**:
-   - Name: e.g. `Nitro Auth Example`
-   - Supported account types: **Accounts in any organizational directory and personal Microsoft accounts**
-   - Redirect URI (add after creation):
-     - **Android**: `msauth://com.auth.example/<client-id>`
-     - **iOS**: `msauth.com.auth.example://auth` (use your bundle id)
-   - Under **Authentication** → **Platform configurations** → add **Mobile and desktop applications** with the Android redirect URI above and the iOS one if testing on iOS.  
-     Copy the **Application (client) ID**.
-
-2. **Env file**  
-   From the repo root:
-
-   ```bash
-   cd apps/example
-   cp .env.example .env.local
-   ```
-
-   Edit `.env.local` and set at least:
-
-   ```bash
-   MICROSOFT_CLIENT_ID=<your-application-client-id>
-   MICROSOFT_TENANT=common
-   ```
-
-   (Google/Apple can stay placeholder if you only care about Microsoft.)
-
-3. **Run the app**  
-   From the **monorepo root**:
-
-   ```bash
-   bun install
-   bun run start
-   ```
-
-   In a second terminal:
-
-   ```bash
-   bun run example:android
-   # or
-   bun run example:ios
-   ```
+For bare React Native projects, install pods after installing the package:
 
-   Wait for the app to install and open.
-
-4. **Test Microsoft**  
-   In the app, tap **Sign in with Microsoft**. A browser or in-app tab opens; sign in with a Microsoft/personal account, then you should return to the app with the user shown (email, name, provider MICROSOFT).  
-   If you see "configuration_error", check `MICROSOFT_CLIENT_ID` and that the redirect URI in Azure matches your app (e.g. `msauth://com.auth.example/<client-id>` for the example app).
-
-> [!TIP]
-> In the example app on Android, you can toggle **Legacy Google Sign-In** to compare Credential Manager vs legacy GoogleSignIn (and to get `serverAuthCode`).
-
-### Expo Setup
-
-Add the plugin to `app.json` or `app.config.js`:
-
-```json
-{
-  "expo": {
-    "plugins": [
-      [
-        "react-native-nitro-auth",
-        {
-          "ios": {
-            "googleClientId": "YOUR_IOS_CLIENT_ID.apps.googleusercontent.com",
-            "googleServerClientId": "YOUR_WEB_CLIENT_ID.apps.googleusercontent.com",
-            "googleUrlScheme": "com.googleusercontent.apps.YOUR_IOS_CLIENT_ID",
-            "appleSignIn": true,
-            "microsoftClientId": "YOUR_AZURE_AD_CLIENT_ID",
-            "microsoftTenant": "common",
-            "microsoftB2cDomain": "your-tenant.b2clogin.com"
-          },
-          "android": {
-            "googleClientId": "YOUR_WEB_CLIENT_ID.apps.googleusercontent.com",
-            "microsoftClientId": "YOUR_AZURE_AD_CLIENT_ID",
-            "microsoftTenant": "common",
-            "microsoftB2cDomain": "your-tenant.b2clogin.com"
-          }
-        }
-      ]
-    ],
-    "extra": {
-      "googleWebClientId": "YOUR_WEB_CLIENT_ID.apps.googleusercontent.com",
-      "microsoftClientId": "YOUR_AZURE_AD_CLIENT_ID",
-      "microsoftTenant": "common",
-      "microsoftB2cDomain": "your-tenant.b2clogin.com",
-      "appleWebClientId": "com.example.web"
-    }
-  }
-}
+```sh
+cd ios && pod install
 ```
 
-**Using environment variables (recommended):**
-
-Create a `.env.local` file:
-
-```bash
-# iOS Client ID
-GOOGLE_IOS_CLIENT_ID=your-ios-client-id.apps.googleusercontent.com
-GOOGLE_IOS_URL_SCHEME=com.googleusercontent.apps.your-ios-client-id
-GOOGLE_SERVER_CLIENT_ID=your-web-client-id.apps.googleusercontent.com
+## Requirements
 
-# Web Client ID (used for Android OAuth flow)
-GOOGLE_WEB_CLIENT_ID=your-web-client-id.apps.googleusercontent.com
-
-# Microsoft/Azure AD (optional)
-MICROSOFT_CLIENT_ID=your-azure-ad-application-id
-MICROSOFT_TENANT=common
-MICROSOFT_B2C_DOMAIN=your-tenant.b2clogin.com
-
-# Apple (web only)
-APPLE_WEB_CLIENT_ID=com.example.web
-```
+| Runtime               | Requirement                              |
+| --------------------- | ---------------------------------------- |
+| React Native          | `>=0.75`                                 |
+| Nitro Modules         | `>=0.35`                                 |
+| iOS                   | 15.1+ recommended                        |
+| Android               | min SDK 24+ recommended                  |
+| Expo example baseline | Expo SDK 55, React Native 0.83, React 19 |
 
-Then reference them in `app.config.js`:
+## Expo Setup
 
-```javascript
-import "dotenv/config";
+Add the plugin to `app.json` or `app.config.js`.
 
+```js
 export default {
   expo: {
+    scheme: "myapp",
+    ios: {
+      bundleIdentifier: "com.company.myapp",
+    },
+    android: {
+      package: "com.company.myapp",
+    },
     plugins: [
       [
         "react-native-nitro-auth",
@@ -232,841 +90,372 @@ export default {
     ],
     extra: {
       googleWebClientId: process.env.GOOGLE_WEB_CLIENT_ID,
+      appleWebClientId: process.env.APPLE_WEB_CLIENT_ID,
       microsoftClientId: process.env.MICROSOFT_CLIENT_ID,
       microsoftTenant: process.env.MICROSOFT_TENANT,
       microsoftB2cDomain: process.env.MICROSOFT_B2C_DOMAIN,
-      appleWebClientId: process.env.APPLE_WEB_CLIENT_ID,
+      nitroAuthWebStorage: "memory",
+      nitroAuthPersistTokensOnWeb: false,
     },
   },
 };
 ```
 
-> [!NOTE]
->
-> - `appleSignIn` on iOS is `false` by default to avoid unnecessary entitlements. Set it to `true` to enable Apple Sign-In.
-> - For Android, use your **Web Client ID** (not Android Client ID) for proper OAuth flow.
-> - If you need `serverAuthCode`, set `googleServerClientId` to your Web Client ID.
-> - Add `googleWebClientId` to `expo.extra` for web platform support.
-> - The `serverAuthCode` is automatically included in `AuthUser` when available (requires backend integration setup in Google Cloud Console).
-> - For Microsoft Sign-In, use `common` tenant for multi-tenant apps, or specify your Azure AD tenant ID for single-tenant apps.
-> - For Azure AD B2C, set `microsoftB2cDomain` and pass the B2C tenant in `microsoftTenant`.
-
-### Google OAuth Setup
-
-1. Create OAuth client IDs in Google Cloud Console:
-   - **iOS client ID** (used by iOS)
-   - **Web client ID** (used by Android and for `serverAuthCode`)
-2. Configure your app:
-   - Expo: set `googleClientId`, `googleServerClientId`, and `googleUrlScheme`
-   - Bare iOS: add `GIDClientID`, `GIDServerClientID`, and URL scheme in `Info.plist`
-   - Bare Android: set `nitro_auth_google_client_id` to your **Web client ID**
-3. If you use `serverAuthCode`, make sure OAuth consent screen is configured in Google Cloud.
-
-### Apple Sign-In Setup
-
-1. **iOS**: enable the “Sign in with Apple” capability in Xcode and in your Apple Developer account.
-2. **Web**: create a Service ID and configure the domain + return URL in Apple Developer.
-3. Configure your app:
-   - Expo: set `appleSignIn: true` for iOS.
-   - Web: set `appleWebClientId` in `expo.extra` (or `.env`).
-
-### Microsoft Azure AD Setup
-
-To enable Microsoft Sign-In, you need to register an application in the Azure Portal:
-
-1. Go to [Azure Portal](https://portal.azure.com) > Azure Active Directory > App registrations
-2. Click "New registration"
-3. Set the redirect URIs:
-   - **iOS**: `msauth.{bundle-identifier}://auth` (e.g., `msauth.com.myapp://auth`)
-   - **Android**: `msauth://{package-name}/{client-id}` (e.g., `msauth://com.myapp/00000000-0000-0000-0000-000000000000`)
-   - **Web**: `https://your-domain.com` (the page that loads the app)
-4. Under "API permissions", add `openid`, `email`, `profile`, and `User.Read` (Microsoft Graph)
-5. Copy the Application (client) ID for use in your config
-
-**Tenant Options:**
-
-- `common` - Any Azure AD or personal Microsoft account
-- `organizations` - Any Azure AD account (work/school)
-- `consumers` - Personal Microsoft accounts only
-- `{tenant-id}` - Specific Azure AD tenant
-- **B2C**: set `microsoftB2cDomain` (e.g. `your-tenant.b2clogin.com`) and use a tenant value like `your-tenant.onmicrosoft.com/B2C_1_signin` (or pass a full `https://.../` authority URL).
-
-### Bare React Native
-
-**iOS**
-
-- Add to `Info.plist`: `GIDClientID`, `GIDServerClientID` (optional), `MSALClientID`, `MSALTenant` (optional), `MSALB2cDomain` (optional).
-- Add URL schemes in `Info.plist`:
-  - Google: `com.googleusercontent.apps.<YOUR_IOS_CLIENT_ID>`
-  - Microsoft: `msauth.<your.bundle.id>` (used for `msauth.<bundle.id>://auth`)
-- Enable the “Sign in with Apple” capability if you use Apple Sign-In.
-
-**Android**
-
-- Add string resources in `res/values/strings.xml`:
-  - `nitro_auth_google_client_id` (Web client ID)
-  - `nitro_auth_microsoft_client_id`
-  - `nitro_auth_microsoft_tenant` (optional)
-  - `nitro_auth_microsoft_b2c_domain` (optional)
-- `MicrosoftAuthActivity` is **automatically declared** by the library manifest — no manual `AndroidManifest.xml` entry is required for basic Microsoft OAuth redirect handling. If you need to customize the intent-filter (e.g., restrict the host/path to your specific package and client ID), you can override it in your app manifest:
-
-```xml
-<activity
-  android:name="com.auth.MicrosoftAuthActivity"
-  android:exported="true"
-  android:launchMode="singleTask">
-  <intent-filter>
-    <action android:name="android.intent.action.VIEW" />
-    <category android:name="android.intent.category.DEFAULT" />
-    <category android:name="android.intent.category.BROWSABLE" />
-    <data
-      android:scheme="msauth"
-      android:host="${applicationId}"
-      android:path="/YOUR_MICROSOFT_CLIENT_ID" />
-  </intent-filter>
-</activity>
-```
-
-### Web Setup
-
-Nitro Auth reads web configuration from `expo.extra`:
-
-```json
-{
-  "expo": {
-    "extra": {
-      "googleWebClientId": "YOUR_WEB_CLIENT_ID.apps.googleusercontent.com",
-      "microsoftClientId": "YOUR_AZURE_AD_CLIENT_ID",
-      "microsoftTenant": "common",
-      "microsoftB2cDomain": "your-tenant.b2clogin.com",
-      "appleWebClientId": "com.example.web",
-      "nitroAuthWebStorage": "session",
-      "nitroAuthPersistTokensOnWeb": false
-    }
-  }
-}
-```
-
-For Apple web sign-in, `appleWebClientId` must be your Apple Service ID. For Microsoft web, make sure your Azure app includes a Web redirect URI matching your site.
-
-- `nitroAuthWebStorage`: `"session"` (default), `"local"`, or `"memory"`.
-- `nitroAuthPersistTokensOnWeb`: `false` by default (recommended). Set `true` only if you need cross-reload token persistence.
+### Plugin Options
 
-## Quick Start
-
-### Using the Hook
-
-```tsx
-import { useAuth, SocialButton } from "react-native-nitro-auth";
-
-function LoginScreen() {
-  const { user, loading, error, login, logout, hasPlayServices } = useAuth();
-
-  if (user) {
-    return (
-      <View>
-        <Image source={{ uri: user.photo }} />
-        <Text>{user.name}</Text>
-        <Button title="Sign Out" onPress={logout} />
-      </View>
-    );
-  }
+| Option                       | Platform | Purpose                                                                |
+| ---------------------------- | -------- | ---------------------------------------------------------------------- |
+| `ios.googleClientId`         | iOS      | Google iOS OAuth client ID                                             |
+| `ios.googleServerClientId`   | iOS      | Google web/server client ID for server auth code flows                 |
+| `ios.googleUrlScheme`        | iOS      | Reversed iOS client ID URL scheme                                      |
+| `ios.appleSignIn`            | iOS      | Adds Apple Sign-In entitlement when `true`                             |
+| `ios.microsoftClientId`      | iOS      | Microsoft app/client ID                                                |
+| `ios.microsoftTenant`        | iOS      | Microsoft tenant, `common`, `organizations`, `consumers`, or tenant ID |
+| `ios.microsoftB2cDomain`     | iOS      | Azure AD B2C domain                                                    |
+| `android.googleClientId`     | Android  | Google web OAuth client ID                                             |
+| `android.microsoftClientId`  | Android  | Microsoft app/client ID                                                |
+| `android.microsoftTenant`    | Android  | Microsoft tenant                                                       |
+| `android.microsoftB2cDomain` | Android  | Azure AD B2C domain                                                    |
 
-  return (
-    <View>
-      {error && <Text style={{ color: "red" }}>{error.message}</Text>}
-      {!hasPlayServices && <Text>Please install Google Play Services</Text>}
+## Provider Setup
 
-      <SocialButton
-        provider="google"
-        onPress={() => login("google")}
-        disabled={loading || !hasPlayServices}
-      />
-      <SocialButton
-        provider="apple"
-        onPress={() => login("apple")}
-        disabled={loading}
-      />
-      <SocialButton
-        provider="microsoft"
-        onPress={() => login("microsoft")}
-        disabled={loading}
-      />
-    </View>
-  );
-}
-```
+### Google Sign-In
 
-### Microsoft Login Options
+Create OAuth clients in Google Cloud Console:
 
-```tsx
-// Login with specific tenant
-await login("microsoft", {
-  tenant: "your-tenant-id",
-  prompt: "select_account", // 'login' | 'consent' | 'select_account' | 'none'
-  scopes: ["openid", "email", "profile", "User.Read"],
-  loginHint: "user@example.com",
-});
-```
+- iOS client ID for your bundle identifier.
+- Web client ID for Android, web, and server auth code flows.
+- Android SHA-1/SHA-256 entries for local debug and release signing.
 
-**B2C example:**
+Use the iOS reversed client ID as `GOOGLE_IOS_URL_SCHEME`.
 
-```tsx
-await login("microsoft", {
-  tenant: "your-tenant.onmicrosoft.com/B2C_1_signin",
-  scopes: ["openid", "email", "profile", "offline_access"],
-});
-```
+### Apple Sign-In
 
-## Migration from @react-native-google-signin/google-signin
+Set `ios.appleSignIn: true` in the config plugin. Apple returns name and email only on the first authorization for a user. Store any profile fields you need in your own backend or app state.
 
-If you are using `@react-native-google-signin/google-signin`, the migration to Nitro Auth is mostly a drop-in at the API level, but the setup is different because Nitro Auth uses a config plugin and JSI.
+Apple Sign-In is supported on iOS and web. It is intentionally reported as `unsupported_provider` on Android.
 
-### 1) Replace the dependency
+### Microsoft Entra ID
 
-```bash
-bun remove @react-native-google-signin/google-signin
-bun add react-native-nitro-auth react-native-nitro-modules
-```
+Create an app registration in Microsoft Entra ID and add redirect URIs:
 
-### 2) Move configuration to the Nitro Auth plugin
+- iOS: `msauth.<bundleIdentifier>://auth`
+- Android: `msauth://<androidPackage>/<clientId>`
+- Web: your web origin, for example `https://app.example.com`
 
-Nitro Auth does not use `GoogleSignin.configure(...)`. Instead, set your client IDs via the config plugin (Expo) or native config (bare).
+Use `microsoftTenant` for `common`, `organizations`, `consumers`, a tenant ID, or a B2C policy path. Use `microsoftB2cDomain` for Azure AD B2C.
 
-**Expo** (recommended):
+## Quick Start
 
-```json
-{
-  "expo": {
-    "plugins": [
-      [
-        "react-native-nitro-auth",
-        {
-          "ios": {
-            "googleClientId": "YOUR_IOS_CLIENT_ID.apps.googleusercontent.com",
-            "googleUrlScheme": "com.googleusercontent.apps.YOUR_IOS_CLIENT_ID"
-          },
-          "android": {
-            "googleClientId": "YOUR_WEB_CLIENT_ID.apps.googleusercontent.com"
-          }
-        }
-      ]
-    ],
-    "extra": {
-      "googleWebClientId": "YOUR_WEB_CLIENT_ID.apps.googleusercontent.com"
+```tsx
+import { Button, Text, View } from "react-native";
+import { AuthError, useAuth } from "react-native-nitro-auth";
+
+export function SignInScreen() {
+  const { user, loading, login, logout, getAccessToken } = useAuth();
+
+  async function signInWithGoogle() {
+    try {
+      await login("google", {
+        scopes: ["email", "profile"],
+      });
+    } catch (e) {
+      const error = AuthError.from(e);
+      console.warn(error.code, error.underlyingMessage);
     }
   }
-}
-```
-
-**Bare React Native:**
-
-- iOS: add `GIDClientID` (and optionally `GIDServerClientID`) to `Info.plist` and set the URL scheme.
-- Android: add `nitro_auth_google_client_id` string resource in `res/values/strings.xml` (use your Web Client ID).
-
-### 3) Update API usage
-
-| @react-native-google-signin/google-signin | Nitro Auth                                                |
-| ----------------------------------------- | --------------------------------------------------------- |
-| `GoogleSignin.configure({...})`           | Configure in plugin / native config                       |
-| `GoogleSignin.signIn()`                   | `login("google")` or `<SocialButton provider="google" />` |
-| `GoogleSignin.signOut()`                  | `logout()`                                                |
-| `GoogleSignin.getTokens()`                | `getAccessToken()` or `refreshToken()`                    |
-| `GoogleSignin.hasPlayServices()`          | `hasPlayServices` from `useAuth()`                        |
-
-**Example migration:**
-
-```tsx
-// Before
-import { GoogleSignin } from "@react-native-google-signin/google-signin";
-
-await GoogleSignin.signIn();
-const tokens = await GoogleSignin.getTokens();
 
-// After
-import { useAuth } from "react-native-nitro-auth";
-
-const { login, getAccessToken } = useAuth();
+  async function readToken() {
+    const token = await getAccessToken();
+    console.log(token);
+  }
 
-await login("google");
-const accessToken = await getAccessToken();
+  return (
+    <View>
+      <Text>{user?.email ?? "Signed out"}</Text>
+      <Button
+        title={loading ? "Signing in..." : "Sign in with Google"}
+        onPress={signInWithGoogle}
+      />
+      <Button title="Get access token" onPress={readToken} />
+      <Button title="Sign out" onPress={logout} />
+    </View>
+  );
+}
 ```
 
-### 4) Remove manual init
-
-If you previously called `GoogleSignin.configure()` at app startup, remove it. Nitro Auth loads configuration from the plugin/native settings at runtime.
-
-## Advanced Features
-
-### Silent Restore
-
-Attempts to restore provider SDK sessions on app startup.
-
-- Google: restore is supported via provider SDK session state.
-- Apple: provider credentials are re-requested by OS flow.
-- Microsoft: no internal persistence; restore requires your app/backend session strategy.
+## SocialButton
 
 ```tsx
-useEffect(() => {
-  AuthService.silentRestore();
-}, []);
+import { SocialButton } from "react-native-nitro-auth";
+
+export function AuthButtons() {
+  return (
+    <>
+      <SocialButton provider="google" />
+      <SocialButton provider="apple" variant="black" />
+      <SocialButton provider="microsoft" variant="outline" />
+    </>
+  );
+}
 ```
 
-### Global Auth State Listener
+## AuthService
 
-Subscribe to authentication changes outside of React components:
+Use `AuthService` when you need auth outside React components.
 
 ```ts
 import { AuthService } from "react-native-nitro-auth";
 
+await AuthService.silentRestore();
+
 const unsubscribe = AuthService.onAuthStateChanged((user) => {
-  if (user) {
-    console.log("Logged in:", user.email);
-  } else {
-    console.log("Logged out");
-  }
+  console.log(user?.email);
+});
+
+const tokensUnsubscribe = AuthService.onTokensRefreshed((tokens) => {
+  console.log(tokens.expirationTime);
 });
 
-// Later...
 unsubscribe();
+tokensUnsubscribe();
 ```
 
-### Global Token Refresh Listener
-
-Be notified whenever tokens are refreshed automatically (or manually):
+## Login Options
 
 ```ts
-import { AuthService } from "react-native-nitro-auth";
-
-const unsubscribe = AuthService.onTokensRefreshed((tokens) => {
-  console.log("New tokens:", tokens.accessToken);
-  // Update your API client / Apollo links
+await login("google", {
+  scopes: ["email", "profile"],
+  loginHint: "user@example.com",
+  useOneTap: true,
+  useSheet: true,
+  forceAccountPicker: true,
+  useLegacyGoogleSignIn: true,
 });
-```
 
-### Incremental Authorization
-
-Request new scopes when you need them without logging the user out:
-
-```tsx
-const { requestScopes, revokeScopes, scopes } = useAuth();
-
-const handleCalendar = async () => {
-  try {
-    await requestScopes(["https://www.googleapis.com/auth/calendar.readonly"]);
-    console.log("Got calendar access!");
-  } catch (e) {
-    console.error("Scope request failed");
-  }
-};
+await login("microsoft", {
+  scopes: ["openid", "profile", "email", "offline_access", "User.Read"],
+  tenant: "organizations",
+  prompt: "select_account",
+});
 ```
 
-### App-Owned Persistence
-
-Nitro Auth is intentionally stateless in-process. Persist only what your app needs.
+| Option                  | Applies to        | Notes                                                |
+| ----------------------- | ----------------- | ---------------------------------------------------- |
+| `scopes`                | Google, Microsoft | Requested OAuth scopes                               |
+| `loginHint`             | Google, Microsoft | Prefills account selection when supported            |
+| `useOneTap`             | Android Google    | Enables Credential Manager auto-select               |
+| `useSheet`              | iOS Google        | Uses native sign-in sheet behavior                   |
+| `forceAccountPicker`    | Google            | Forces account picker                                |
+| `useLegacyGoogleSignIn` | Android Google    | Uses legacy Google Sign-In path for server auth code |
+| `tenant`                | Microsoft         | Overrides configured tenant                          |
+| `prompt`                | Microsoft         | `login`, `consent`, `select_account`, or `none`      |
 
-#### Using react-native-nitro-storage (Recommended)
+## Incremental Scopes
 
 ```ts
-import { AuthService, type AuthUser } from "react-native-nitro-auth";
-import { createStorageItem, StorageScope } from "react-native-nitro-storage";
-
-type AuthSnapshot = {
-  user: AuthUser | undefined;
-  scopes: string[];
-  updatedAt: number | undefined;
-};
-
-const authSnapshotItem = createStorageItem<AuthSnapshot>({
-  key: "auth_snapshot",
-  scope: StorageScope.Disk,
-  defaultValue: {
-    user: undefined,
-    scopes: [],
-    updatedAt: undefined,
-  },
-});
+const calendarScope = "https://www.googleapis.com/auth/calendar.readonly";
 
-// Save on auth changes (do not overwrite snapshot with empty user on app refresh)
-AuthService.onAuthStateChanged((user) => {
-  if (!user) return;
-
-  authSnapshotItem.set({
-    user,
-    scopes: AuthService.grantedScopes,
-    updatedAt: Date.now(),
-  });
-});
-
-// Keep token/expiration fields fresh in persisted snapshot
-AuthService.onTokensRefreshed((tokens) => {
-  authSnapshotItem.set((prev) => {
-    if (!prev.user) return prev;
-
-    return {
-      ...prev,
-      user: {
-        ...prev.user,
-        accessToken: tokens.accessToken ?? prev.user.accessToken,
-        idToken: tokens.idToken ?? prev.user.idToken,
-        refreshToken: tokens.refreshToken ?? prev.user.refreshToken,
-        expirationTime: tokens.expirationTime ?? prev.user.expirationTime,
-      },
-      updatedAt: Date.now(),
-    };
-  });
-});
-
-// Clear on logout
-function logout() {
-  AuthService.logout();
-  authSnapshotItem.set({
-    user: undefined,
-    scopes: [],
-    updatedAt: undefined,
-  });
-}
+await requestScopes([calendarScope]);
+await revokeScopes([calendarScope]);
 ```
 
-### Production Readiness
+On Android, incremental Google scope requests use the legacy Google Sign-In APIs because Credential Manager does not expose an equivalent existing-account scope query.
 
-Nitro Auth is suitable for production use when configured with provider-accurate expectations:
+## Storage Model
 
-- **Google Sign-In**: One-Tap + legacy on Android, native on iOS, popup on web.
-- **Apple Sign-In**: iOS + web only.
-- **Microsoft (Azure AD / B2C)**: iOS, Android, and web with PKCE/state/nonce protections.
+Native tokens are kept in memory by design. The package does not persist Microsoft refresh tokens or provider tokens to disk. Your app owns persistence and secure storage policy.
 
-Production checklist:
-
-1. Configure client IDs, URL schemes, and redirect URIs per platform/provider.
-2. Call `silentRestore()` during app startup to rehydrate provider session state when available.
-3. Persist only app-owned snapshots/tokens (for example with `react-native-nitro-storage`), then clear them on logout.
-4. On Android Google, use `useLegacyGoogleSignIn: true` when backend flows require `serverAuthCode`.
-5. Treat token fields as optional and branch by provider/flow.
-6. Keep web sensitive tokens memory-only unless you explicitly require persistent web tokens (`nitroAuthPersistTokensOnWeb: true`).
-7. Enable logging only in development, and monitor normalized error codes in production.
-
-### Logging & Debugging
-
-Enable verbose logging to see detailed OAuth flow information in the console:
+For app-managed persistence, store only the minimum state your product needs:
 
 ```ts
 import { AuthService } from "react-native-nitro-auth";
 
-AuthService.setLoggingEnabled(true);
+const snapshot = {
+  user: AuthService.currentUser,
+  scopes: AuthService.grantedScopes,
+  updatedAt: Date.now(),
+};
 ```
 
-### Sync State + Async Tokens
-
-Nitro Auth provides synchronous access to in-memory state, while token retrieval remains async:
-
-```ts
-// Quick access to what we have in memory
-const user = AuthService.currentUser;
-const scopes = AuthService.grantedScopes;
+On web, the default is also memory storage. You can opt into browser storage with:
 
-// Async access ensures fresh tokens (will refresh if expired)
-const freshToken = await AuthService.getAccessToken();
+```js
+extra: {
+  nitroAuthWebStorage: "session", // "session", "local", or "memory"
+  nitroAuthPersistTokensOnWeb: true,
+}
 ```
 
-### Standardized Error Codes
+## Error Contract
 
-All errors thrown by `AuthService` and `useAuth` are `AuthError` instances with a type-safe `code` field (always a valid `AuthErrorCode`) and an optional `underlyingMessage` with the raw provider string when it differs from the code.
+All public async APIs throw `AuthError`, including provider errors surfaced by native and web `AuthService` implementations.
 
 ```ts
-import { AuthError } from "react-native-nitro-auth";
-
 try {
-  await login("google");
+  await AuthService.login("microsoft");
 } catch (e) {
-  if (e instanceof AuthError) {
-    switch (e.code) {
-      case "cancelled":
-        // User closed the popup/picker
-        break;
-      case "network_error":
-        // Connection issues
-        break;
-      default:
-        console.error(e.code, e.underlyingMessage);
-    }
+  const error = AuthError.from(e);
+  switch (error.code) {
+    case "cancelled":
+      break;
+    case "configuration_error":
+      break;
+    case "token_error":
+      break;
+    default:
+      break;
   }
 }
 ```
 
-| Error Code             | Description                                                     |
-| ---------------------- | --------------------------------------------------------------- |
-| `cancelled`            | The user cancelled the sign-in flow or dismissed the popup      |
-| `timeout`              | The login popup/flow timed out                                  |
-| `popup_blocked`        | The browser blocked the popup window                            |
-| `network_error`        | A network or connectivity error occurred                        |
-| `configuration_error`  | Missing client IDs, invalid tenant, or misconfigured setup      |
-| `not_signed_in`        | The operation requires an authenticated user/session            |
-| `operation_in_progress`| Another auth flow of the same kind is already running           |
-| `unsupported_provider` | The provider is not supported on this platform                  |
-| `invalid_state`        | PKCE state mismatch — possible CSRF attack                      |
-| `invalid_nonce`        | Nonce mismatch in token response — possible replay attack       |
-| `token_error`          | Token exchange or storage failed                                |
-| `no_id_token`          | No `id_token` in token response                                 |
-| `parse_error`          | Failed to parse token response                                  |
-| `refresh_failed`       | Refresh token flow failed (token may be expired or revoked)     |
-| `unknown`              | An unknown or unmapped error occurred                           |
-
-### Native Error Metadata
-
-`AuthError` carries the raw provider/native message in `underlyingMessage` when the platform error didn't map to a known code:
+Known error codes:
 
 ```ts
-import { AuthError } from "react-native-nitro-auth";
-
-try {
-  await login("google");
-} catch (e) {
-  if (e instanceof AuthError) {
-    // e.code is always a valid AuthErrorCode
-    // e.underlyingMessage is the original native string (or undefined if it equalled the code)
-    console.log(e.code, e.underlyingMessage);
-  }
-}
-```
-
-The `AuthUser.underlyingError` field carries a raw warning string when the provider returns one alongside a successful result.
-
-### Troubleshooting
+type AuthErrorCode =
+  | "cancelled"
+  | "timeout"
+  | "popup_blocked"
+  | "network_error"
+  | "configuration_error"
+  | "not_signed_in"
+  | "operation_in_progress"
+  | "unsupported_provider"
+  | "invalid_state"
+  | "invalid_nonce"
+  | "token_error"
+  | "no_id_token"
+  | "parse_error"
+  | "refresh_failed"
+  | "unknown";
+```
+
+`underlyingMessage` keeps the raw native or OAuth message when it differs from the stable code.
 
-- `configuration_error`: verify client IDs, URL schemes, and redirect URIs are set for the current platform. On Android, check that the `microsoftTenant` is a non-empty valid value.
-- `invalid_state` or `invalid_nonce`: ensure the redirect URI in your provider console matches your app config exactly. These indicate a potential CSRF or replay attack — do not retry silently.
-- `refresh_failed`: the refresh token is likely expired or revoked. Clear the session and prompt the user to sign in again. On Android and web, structured error details from the provider (e.g. `invalid_grant`) are surfaced via `error.underlyingMessage`.
-- `hasPlayServices` is false: prompt the user to install/update Google Play Services or disable One-Tap.
-- Apple web login fails: confirm `appleWebClientId` is set and your domain is registered with Apple.
-- Microsoft Android redirect hangs: confirm the `msauth://` redirect URI in your Azure app matches your package name and client ID.
-
-### Automatic Token Refresh
+## API Reference
 
-The `getAccessToken()` method automatically checks if the current token is expired (or about to expire) and triggers a silent refresh if possible:
+### Exports
 
 ```ts
-const { getAccessToken } = useAuth();
-
-// This will silently refresh if needed!
-const token = await getAccessToken();
+export * from "react-native-nitro-auth";
 ```
 
-### Offline Access (Server Auth Code)
-
-If you need to access Google APIs from your backend (e.g., Google Calendar integration), you can use the `serverAuthCode`. This code is returned during login and can be exchanged for tokens on your server:
-
-```ts
-const { user } = useAuth();
-
-if (user?.serverAuthCode) {
-  // Send this to your backend!
-  await api.verifyGoogleAccess(user.serverAuthCode);
-}
-```
+Main exports:
 
-### Google One-Tap & Sheet
+- `useAuth()`
+- `AuthService`
+- `SocialButton`
+- `AuthError`
+- `isAuthErrorCode()`
+- `toAuthErrorCode()`
+- `AuthProvider`
+- `AuthUser`
+- `AuthTokens`
+- `LoginOptions`
 
-Explicitly enable the modern One-Tap flow on Android or the Sign-In Sheet on iOS:
+### useAuth()
 
 ```ts
-await login("google", {
-  useOneTap: true, // Android
-  useSheet: true, // iOS
-});
+type UseAuthReturn = {
+  user: AuthUser | undefined;
+  scopes: string[];
+  loading: boolean;
+  error: AuthError | undefined;
+  hasPlayServices: boolean;
+  login(provider: AuthProvider, options?: LoginOptions): Promise<void>;
+  logout(): void;
+  requestScopes(scopes: string[]): Promise<void>;
+  revokeScopes(scopes: string[]): Promise<void>;
+  getAccessToken(): Promise<string | undefined>;
+  refreshToken(): Promise<AuthTokens>;
+  silentRestore(): Promise<void>;
+};
 ```
 
-> [!NOTE]
-> One-Tap requires Google Play Services. You can check `hasPlayServices` from `useAuth()` and show a fallback UI if needed.
-
-### Android Legacy Google Sign-In (Server Auth Code)
-
-Credential Manager is the recommended default on Android, but it **does not return** `serverAuthCode`.
-If your backend requires `serverAuthCode`, opt into the legacy flow:
+### AuthUser
 
 ```ts
-await login("google", { useLegacyGoogleSignIn: true });
+type AuthUser = {
+  provider: "google" | "apple" | "microsoft";
+  email?: string;
+  name?: string;
+  photo?: string;
+  idToken?: string;
+  accessToken?: string;
+  refreshToken?: string;
+  serverAuthCode?: string;
+  scopes?: string[];
+  expirationTime?: number;
+  underlyingError?: string;
+};
 ```
 
-### Force Account Picker
+## Example App
 
-When connecting additional services (like Google Calendar), you may want to let users pick a different account than the one they signed in with. Use `forceAccountPicker` to clear any cached session and show the account picker:
+The example app is the fastest way to verify setup and read a complete integration.
 
-```ts
-await login("google", {
-  scopes: ["https://www.googleapis.com/auth/calendar.readonly"],
-  forceAccountPicker: true, // Always show account picker
-});
+```sh
+cp apps/example/.env.example apps/example/.env.local
+bun install
+bun example:prebuild:clean
+bun example:ios
+bun example:android
 ```
 
-This is useful for scenarios where:
+The demo includes:
 
-- Users want to connect a different Google account for calendar integration
-- You need to ensure the user can select any account they've added to their device
-- The cached session is interfering with the expected account selection UX
+- Provider cards for Google, Apple, and Microsoft.
+- Token and scope operations.
+- Silent restore and account picker actions.
+- App-owned disk snapshot example with `react-native-nitro-storage`.
+- Runtime smoke tests for the public API.
 
-On Android, `forceAccountPicker` routes through the legacy Google Sign-In chooser to guarantee the account picker appears. Credential Manager / One-Tap remains the default when the chooser is not forced.
+## Troubleshooting
 
-## API Reference
+| Symptom                               | Check                                                                            |
+| ------------------------------------- | -------------------------------------------------------------------------------- |
+| `configuration_error` on Google       | Client ID is missing or wrong for the current platform                           |
+| Google works in debug but not release | Add release SHA-1/SHA-256 fingerprints to Google Cloud Console                   |
+| Android `hasPlayServices` is false    | Use an emulator image with Google Play Services                                  |
+| Apple email/name missing              | Apple only returns these fields on first authorization                           |
+| Microsoft `invalid_state`             | Redirect URI or app resume path is wrong, or an old auth redirect completed late |
+| Microsoft `token_error`               | Check tenant, client ID, redirect URI, and requested scopes                      |
+| Web popup blocked                     | Call `login()` from a user gesture such as a button press                        |
+| `operation_in_progress`               | A provider flow is already active; wait for it to finish or sign out             |
 
-### Package Exports
+## Production Notes
 
-```ts
-import {
-  AuthService,
-  AuthError,
-  isAuthErrorCode,
-  toAuthErrorCode,
-  SocialButton,
-  useAuth,
-  type UseAuthReturn,
-  type Auth,
-  type AuthUser,
-  type AuthTokens,
-  type AuthProvider,
-  type AuthErrorCode,
-  type LoginOptions,
-} from "react-native-nitro-auth";
-```
+- Verify ID tokens on your backend. Client-side JWT parsing is for display and expiration hints only.
+- Store refresh tokens only in storage your app explicitly owns and secures.
+- Keep Google debug and release signing fingerprints in sync with your OAuth clients.
+- Add provider-specific redirect URIs for every environment.
+- Run the example app on iOS and Android before shipping provider config changes.
 
-### Core Types
-
-| Type              | Definition                                                                                                                                                                                                                                    |
-| ----------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
-| `AuthProvider`    | `"google" \| "apple" \| "microsoft"`                                                                                                                                                                                                          |
-| `AuthErrorCode`   | `"cancelled" \| "timeout" \| "popup_blocked" \| "network_error" \| "configuration_error" \| "not_signed_in" \| "operation_in_progress" \| "unsupported_provider" \| "invalid_state" \| "invalid_nonce" \| "token_error" \| "no_id_token" \| "parse_error" \| "refresh_failed" \| "unknown"` |
-| `MicrosoftPrompt` | `"login" \| "consent" \| "select_account" \| "none"`                                                                                                                                                                                          |
-
-### `AuthUser`
-
-| Field             | Type                    | Description                                                                |
-| ----------------- | ----------------------- | -------------------------------------------------------------------------- |
-| `provider`        | `AuthProvider`          | Provider that authenticated the user                                       |
-| `email`           | `string \| undefined`   | User email                                                                 |
-| `name`            | `string \| undefined`   | Display name                                                               |
-| `photo`           | `string \| undefined`   | Profile image URL (Google)                                                 |
-| `idToken`         | `string \| undefined`   | OIDC ID token                                                              |
-| `accessToken`     | `string \| undefined`   | OAuth access token                                                         |
-| `refreshToken`    | `string \| undefined`   | OAuth refresh token                                                        |
-| `serverAuthCode`  | `string \| undefined`   | Google server auth code (legacy Android flow + backend exchange scenarios) |
-| `scopes`          | `string[] \| undefined` | Granted scopes for current session                                         |
-| `expirationTime`  | `number \| undefined`   | Expiration timestamp in milliseconds since epoch                           |
-| `underlyingError` | `string \| undefined`   | Raw provider/native error message                                          |
-
-> [!NOTE]
-> On Android Google One-Tap/Credential Manager, `idToken` is typically available immediately, while `accessToken` and `expirationTime` may be `undefined` until refresh/exchange flow provides them.
-
-### `AuthTokens`
-
-| Field            | Type                  | Description                   |
-| ---------------- | --------------------- | ----------------------------- |
-| `accessToken`    | `string \| undefined` | Refreshed access token        |
-| `idToken`        | `string \| undefined` | Refreshed ID token            |
-| `refreshToken`   | `string \| undefined` | Refresh token (if available)  |
-| `expirationTime` | `number \| undefined` | Optional expiration timestamp |
-
-### `LoginOptions`
-
-| Option                  | Type              | Platform  | Description                                                                       |
-| ----------------------- | ----------------- | --------- | --------------------------------------------------------------------------------- |
-| `scopes`                | `string[]`        | All       | Requested scopes (defaults are provider-specific)                                 |
-| `loginHint`             | `string`          | All       | Prefills account identifier                                                       |
-| `useOneTap`             | `boolean`         | Android   | Use Credential Manager/One-Tap flow                                               |
-| `useSheet`              | `boolean`         | iOS       | Use native Google Sign-In sheet                                                   |
-| `forceAccountPicker`    | `boolean`         | All       | Always show account chooser; Android Google uses the legacy chooser path          |
-| `useLegacyGoogleSignIn` | `boolean`         | Android   | Use legacy Google Sign-In (required when you need `serverAuthCode`)               |
-| `tenant`                | `string`          | Microsoft | Tenant (`common`, `organizations`, `consumers`, tenant id, or full authority URL) |
-| `prompt`                | `MicrosoftPrompt` | Microsoft | Prompt behavior                                                                   |
-
-### `useAuth()`
+## Release Checks
 
-```ts
-declare function useAuth(): UseAuthReturn;
+```sh
+bun run publish-package:dry-run
 ```
 
-| Property          | Type                                                                | Description                                          |
-| ----------------- | ------------------------------------------------------------------- | ---------------------------------------------------- |
-| `user`            | `AuthUser \| undefined`                                             | Current in-memory user                               |
-| `scopes`          | `string[]`                                                          | Current granted scopes                               |
-| `loading`         | `boolean`                                                           | `true` while an auth operation is in-flight          |
-| `error`           | `AuthError \| undefined`                                            | Last operation error (typed, safe to switch on `.code`) |
-| `hasPlayServices` | `boolean`                                                           | Android Play Services availability                   |
-| `login`           | `(provider: AuthProvider, options?: LoginOptions) => Promise<void>` | Starts provider login                                |
-| `logout`          | `() => void`                                                        | Clears current session                               |
-| `requestScopes`   | `(scopes: string[]) => Promise<void>`                               | Requests additional scopes                           |
-| `revokeScopes`    | `(scopes: string[]) => Promise<void>`                               | Revokes scopes in current session                    |
-| `getAccessToken`  | `() => Promise<string \| undefined>`                                | Returns access token, auto-refreshing when supported |
-| `refreshToken`    | `() => Promise<AuthTokens>`                                         | Explicit refresh                                     |
-| `silentRestore`   | `() => Promise<void>`                                               | Restores provider SDK session (if available)         |
-
-### `AuthService`
-
-Synchronous state + async operations (useful outside React trees).
-
-#### Readonly state
-
-| Property          | Type                    | Description                        |
-| ----------------- | ----------------------- | ---------------------------------- |
-| `name`            | `string`                | Hybrid object name (`"Auth"`)      |
-| `currentUser`     | `AuthUser \| undefined` | Current user snapshot              |
-| `grantedScopes`   | `string[]`              | Current scope snapshot             |
-| `hasPlayServices` | `boolean`               | Android Play Services availability |
-
-#### Methods
-
-| Method               | Signature                                                | Description                      |
-| -------------------- | -------------------------------------------------------- | -------------------------------- |
-| `login`              | `(provider, options?) => Promise<void>`                  | Starts login                     |
-| `logout`             | `() => void`                                             | Clears session                   |
-| `requestScopes`      | `(scopes) => Promise<void>`                              | Incremental auth                 |
-| `revokeScopes`       | `(scopes) => Promise<void>`                              | Scope revoke                     |
-| `getAccessToken`     | `() => Promise<string \| undefined>`                     | Access token getter with refresh |
-| `refreshToken`       | `() => Promise<AuthTokens>`                              | Explicit token refresh           |
-| `silentRestore`      | `() => Promise<void>`                                    | Restore provider SDK session     |
-| `onAuthStateChanged` | `(callback: (user?: AuthUser) => void) => () => void`    | Auth change listener             |
-| `onTokensRefreshed`  | `(callback: (tokens: AuthTokens) => void) => () => void` | Token refresh listener           |
-| `setLoggingEnabled`  | `(enabled: boolean) => void`                             | Debug logging toggle             |
-| `dispose`            | `() => void`                                             | Disposes hybrid object           |
-| `equals`             | `(other: unknown) => boolean`                            | Hybrid object identity check     |
-
-### Storage Contract
-
-Nitro Auth does not provide persistence APIs. Persist the auth data you need in your app layer (for example with `react-native-nitro-storage`, MMKV, Keychain wrappers, or backend-issued sessions).
-There is no public `setStorageAdapter`/`setJSStorageAdapter` API in this package.
-
-### `SocialButton`
-
-| Prop           | Type                                           | Default     | Description                                 |
-| -------------- | ---------------------------------------------- | ----------- | ------------------------------------------- |
-| `provider`     | `AuthProvider`                                 | required    | Provider                                    |
-| `variant`      | `"primary" \| "outline" \| "white" \| "black"` | `"primary"` | Visual style                                |
-| `borderRadius` | `number`                                       | `8`         | Border radius                               |
-| `style`        | `ViewStyle`                                    | `undefined` | Container style override                    |
-| `textStyle`    | `TextStyle`                                    | `undefined` | Text style override                         |
-| `disabled`     | `boolean`                                      | `false`     | Disabled state                              |
-| `onPress`      | `() => void`                                   | `undefined` | Custom press handler (skips built-in login) |
-| `onSuccess`    | `(user: AuthUser) => void`                     | `undefined` | Called after successful default login       |
-| `onError`      | `(error: unknown) => void`                     | `undefined` | Called when default login fails             |
-
-### Config Plugin API (`app.json` / `app.config.js`)
-
-`plugins: [["react-native-nitro-auth", { ios: {...}, android: {...} }]]`
-
-#### iOS plugin options
-
-| Option                 | Type      | Description                                  |
-| ---------------------- | --------- | -------------------------------------------- |
-| `googleClientId`       | `string`  | Writes `GIDClientID`                         |
-| `googleServerClientId` | `string`  | Writes `GIDServerClientID`                   |
-| `googleUrlScheme`      | `string`  | Adds Google URL scheme                       |
-| `appleSignIn`          | `boolean` | Enables Apple Sign-In entitlement            |
-| `microsoftClientId`    | `string`  | Writes `MSALClientID` + MSAL redirect scheme |
-| `microsoftTenant`      | `string`  | Writes `MSALTenant`                          |
-| `microsoftB2cDomain`   | `string`  | Writes `MSALB2cDomain`                       |
-
-#### Android plugin options
-
-| Option               | Type     | Description                                                      |
-| -------------------- | -------- | ---------------------------------------------------------------- |
-| `googleClientId`     | `string` | Writes `nitro_auth_google_client_id` string                      |
-| `microsoftClientId`  | `string` | Writes `nitro_auth_microsoft_client_id` + redirect intent filter |
-| `microsoftTenant`    | `string` | Writes `nitro_auth_microsoft_tenant`                             |
-| `microsoftB2cDomain` | `string` | Writes `nitro_auth_microsoft_b2c_domain`                         |
-
-### Web runtime config (`expo.extra`)
-
-| Key                           | Type                               | Default     | Description                                               |
-| ----------------------------- | ---------------------------------- | ----------- | --------------------------------------------------------- |
-| `googleWebClientId`           | `string`                           | `undefined` | Google web OAuth client id                                |
-| `microsoftClientId`           | `string`                           | `undefined` | Microsoft app client id                                   |
-| `microsoftTenant`             | `string`                           | `"common"`  | Microsoft tenant/authority                                |
-| `microsoftB2cDomain`          | `string`                           | `undefined` | B2C domain when applicable                                |
-| `appleWebClientId`            | `string`                           | `undefined` | Apple Service ID                                          |
-| `nitroAuthWebStorage`         | `"session" \| "local" \| "memory"` | `"session"` | Storage for non-sensitive web cache                       |
-| `nitroAuthPersistTokensOnWeb` | `boolean`                          | `false`     | Persist sensitive tokens on web storage instead of memory |
-
-### `AuthError`
-
-All thrown errors from `AuthService` and `useAuth` are `AuthError` instances.
+The publish script runs frozen install, core-version verification, codegen, build, lint, typecheck, Jest, JS coverage, C++ tests, C++ coverage, Expo Doctor, package docs sync, pack dry run, and `bun publish --dry-run --ignore-scripts`.
 
-```ts
-class AuthError extends Error {
-  readonly code: AuthErrorCode;           // Always a valid AuthErrorCode — safe to switch on
-  readonly underlyingMessage?: string;    // Raw native/platform string when it differs from code
-  static from(e: unknown): AuthError;     // Wraps any value; passes AuthError instances through
-}
-
-function isAuthErrorCode(value: string): value is AuthErrorCode;
-function toAuthErrorCode(raw: string): AuthErrorCode; // Returns "unknown" for unrecognized strings
-```
+For faster local iteration before the full release dry run:
 
-| `code`                 | Meaning                                        |
-| ---------------------- | ---------------------------------------------- |
-| `cancelled`            | User cancelled the login flow                  |
-| `timeout`              | Provider popup did not complete before timeout |
-| `popup_blocked`        | Browser blocked popup opening                  |
-| `network_error`        | Network failure                                |
-| `configuration_error`  | Missing/invalid provider configuration         |
-| `not_signed_in`        | Operation requires an active authenticated user |
-| `operation_in_progress`| Another auth flow is already running           |
-| `unsupported_provider` | Provider not supported on this platform        |
-| `invalid_state`        | PKCE state mismatch (possible CSRF)            |
-| `invalid_nonce`        | Nonce mismatch in token response               |
-| `token_error`          | Token exchange failed                          |
-| `no_id_token`          | No `id_token` in token response                |
-| `parse_error`          | Failed to parse token response                 |
-| `refresh_failed`       | Refresh token flow failed                      |
-| `unknown`              | Unrecognized error                             |
-
-## Quality Gates
-
-From monorepo root:
-
-```bash
-bun run format:check
-bun run lint
-bun run typecheck
+```sh
+bun run check
+bun run test:cpp
+bun run --cwd packages/react-native-nitro-auth test:coverage -- --runInBand
+bun run --cwd packages/react-native-nitro-auth test:cpp:coverage
 ```
 
-Workspace-local commands:
-
-```bash
-# apps/example
-bun run format
-bun run lint
-bun run typecheck
+Before shipping provider or native config changes, also verify the example app:
 
-# packages/react-native-nitro-auth
-bun run format
-bun run lint
-bun run typecheck
-bun run test
+```sh
+bun run example:prebuild
+bun run example:android
+bun run example:ios
 ```
 
-## Platform Support
-
-| Feature                    | iOS | Android | Web |
-| -------------------------- | --- | ------- | --- |
-| Google Sign-In             | ✅  | ✅      | ✅  |
-| Apple Sign-In              | ✅  | ❌      | ✅  |
-| Microsoft Sign-In          | ✅  | ✅      | ✅  |
-| Custom OAuth Scopes        | ✅  | ✅      | ✅  |
-| Incremental Authorization  | ✅  | ✅      | ✅  |
-| Token Refresh              | ✅  | ✅      | ✅  |
-| Native Session Persistence | ❌  | ❌      | —   |
-| Web Auth Snapshot Cache    | —   | —       | ✅  |
-| App-Owned Persistence      | ✅  | ✅      | ✅  |
-| Auto-Refresh               | ✅  | ✅      | ✅  |
-| Native C++ Performance     | ✅  | ✅      | —   |
-
-## Architecture
-
-`react-native-nitro-auth` is built using [Nitro Modules](https://github.com/mrousavy/nitro). Unlike traditional React Native modules, Nitro uses JSI to provide:
-
-- **Zero-bridge overhead**: Calls are made directly from JS to C++.
-- **Type safety**: TypeScript types are automatically kept in sync with native C++ and Swift/Kotlin code.
-- **Synchronous access**: Properties like `currentUser` are accessible synchronously without async overhead.
-
 ## License
 
 MIT