react-native-nitro-auth 0.1.6 → 0.4.0

package/README.md

@@ -27,20 +27,32 @@ Nitro Auth is designed to replace legacy modules like `@react-native-google-sign
 - **Expo Ready**: Comes with a powerful Config Plugin for zero-config setup.
 - **Cross-Platform**: Unified API for iOS, Android, and Web.
 - **Auto-Refresh**: Synchronous access to tokens with automatic silent refresh.
-- **Google One-Tap**: Modern login experience on Android using Credential Manager.
-- **Custom Storage**: Pluggable storage adapters for secure persistence (e.g., Keychain).
+- **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.
+- **Custom Storage**: Pluggable storage adapters for secure persistence (e.g. Keychain, MMKV, AsyncStorage).
 - **Refresh Interceptors**: Listen to token updates globally.
 
 ## Installation
 
 ```bash
 bun add react-native-nitro-auth react-native-nitro-modules
-bun prebuild
+# or
+npm install react-native-nitro-auth react-native-nitro-modules
+# or
+yarn add react-native-nitro-auth react-native-nitro-modules
+# or
+pnpm add react-native-nitro-auth react-native-nitro-modules
+```
+
+For Expo projects, rebuild native code after installation:
+
+```bash
+bunx expo prebuild
 ```
 
 ### Expo Setup
 
-Add the plugin to `app.json`:
+Add the plugin to `app.json` or `app.config.js`:
 
 ```json
 {
@@ -51,23 +63,70 @@ Add the plugin to `app.json`:
         {
           "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
           },
           "android": {
-            "googleClientId": "YOUR_ANDROID_CLIENT_ID.apps.googleusercontent.com"
+            "googleClientId": "YOUR_WEB_CLIENT_ID.apps.googleusercontent.com"
           }
         }
       ]
-    ]
+    ],
+    "extra": {
+      "googleWebClientId": "YOUR_WEB_CLIENT_ID.apps.googleusercontent.com"
+    }
   }
 }
 ```
 
+**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
+
+# Web Client ID (used for Android OAuth flow)
+GOOGLE_WEB_CLIENT_ID=your-web-client-id.apps.googleusercontent.com
+```
+
+Then reference them in `app.config.js`:
+
+```javascript
+import "dotenv/config";
+
+export default {
+  expo: {
+    plugins: [
+      [
+        "react-native-nitro-auth",
+        {
+          ios: {
+            googleClientId: process.env.GOOGLE_IOS_CLIENT_ID,
+            googleUrlScheme: process.env.GOOGLE_IOS_URL_SCHEME,
+            appleSignIn: true,
+          },
+          android: {
+            googleClientId: process.env.GOOGLE_WEB_CLIENT_ID,
+          },
+        },
+      ],
+    ],
+    extra: {
+      googleWebClientId: process.env.GOOGLE_WEB_CLIENT_ID,
+    },
+  },
+};
+```
+
 > [!NOTE]
-> `appleSignIn` on iOS is `false` by default to avoid unnecessary entitlements. Set it to `true` to enable Apple Sign-In.
-> `googleServerClientId` is only required if you need a `serverAuthCode` for backend integration.
+>
+> - `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.
+> - 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).
 
 ### Bare React Native
 
@@ -110,8 +169,96 @@ function LoginScreen() {
 }
 ```
 
+## Migration from @react-native-google-signin/google-signin
+
+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.
+
+### 1) Replace the dependency
+
+```bash
+bun remove @react-native-google-signin/google-signin
+bun add react-native-nitro-auth react-native-nitro-modules
+```
+
+### 2) Move configuration to the Nitro Auth plugin
+
+Nitro Auth does not use `GoogleSignin.configure(...)`. Instead, set your client IDs via the config plugin (Expo) or native config (bare).
+
+**Expo** (recommended):
+
+```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"
+    }
+  }
+}
+```
+
+**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();
+
+await login("google");
+const accessToken = await getAccessToken();
+```
+
+### 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
+
+Automatically restore the user session on app startup. This is faster than a full login and works offline if the session is cached.
+
+```tsx
+useEffect(() => {
+  AuthService.silentRestore();
+}, []);
+```
+
 ### Global Auth State Listener
 
 Subscribe to authentication changes outside of React components:
@@ -131,6 +278,95 @@ const unsubscribe = AuthService.onAuthStateChanged((user) => {
 unsubscribe();
 ```
 
+### Global Token Refresh Listener
+
+Be notified whenever tokens are refreshed automatically (or manually):
+
+```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
+});
+```
+
+### 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");
+  }
+};
+```
+
+### Pluggable Storage Adapters
+
+Nitro Auth persists the session automatically. By default, it uses simple file-based storage on native and `localStorage` on web.
+
+#### 1) JS Storage (AsyncStorage, MMKV, etc.)
+
+Easily swap the default storage with your preferred library from the JS layer:
+
+```ts
+import { AuthService, type JSStorageAdapter } from "react-native-nitro-auth";
+import { MMKV } from "react-native-mmkv";
+
+const storage = new MMKV();
+
+const mmkvAdapter: JSStorageAdapter = {
+  save: (key, value) => storage.set(key, value),
+  load: (key) => storage.getString(key),
+  remove: (key) => storage.delete(key),
+};
+
+// Set it once at app startup
+AuthService.setJSStorageAdapter(mmkvAdapter);
+```
+
+#### 2) Native Storage (Keychain, etc.)
+
+For maximum security, you can implement a native HybridObject (C++, Swift, or Kotlin) and pass it to Nitro. This runs directly in memory at the C++ layer.
+
+```ts
+import { AuthService } from "react-native-nitro-auth";
+// Import your native Nitro module
+import { KeychainStorage } from "./native/KeychainStorage";
+
+AuthService.setStorageAdapter(KeychainStorage);
+```
+
+### Logging & Debugging
+
+Enable verbose logging to see detailed OAuth flow information in the console:
+
+```ts
+import { AuthService } from "react-native-nitro-auth";
+
+AuthService.setLoggingEnabled(true);
+```
+
+### Sync Access to Tokens
+
+Nitro Auth provides synchronous access to the current state, while still supporting silent refresh:
+
+```ts
+// Quick access to what we have in memory
+const user = AuthService.currentUser;
+const scopes = AuthService.grantedScopes;
+
+// Async access ensures fresh tokens (will refresh if expired)
+const freshToken = await AuthService.getAccessToken();
+```
+
 ### Standardized Error Codes
 
 Handle failures reliably with predictable error strings:
@@ -139,20 +375,42 @@ Handle failures reliably with predictable error strings:
 try {
   await login("google");
 } catch (e) {
-  if (e.message === "cancelled") {
+  const error = e as Error;
+  if (error.message === "cancelled") {
     // User closed the popup/picker
-  } else if (e.message === "network_error") {
+  } else if (error.message === "network_error") {
     // Connection issues
   }
 }
 ```
 
-| Code                   | Description                                    |
+| Error Code             | Description                                    |
 | ---------------------- | ---------------------------------------------- |
 | `cancelled`            | The user cancelled the sign-in flow            |
 | `network_error`        | A network error occurred                       |
 | `configuration_error`  | Missing client IDs or invalid setup            |
 | `unsupported_provider` | The provider is not supported on this platform |
+| `unknown`              | An unknown error occurred                      |
+
+### Native Error Metadata
+
+For more detailed debugging, Nitro Auth captures the raw native error message. You can access it from the authenticated user or cast the error:
+
+```ts
+// From authenticated user (on success)
+const { user } = useAuth();
+if (user?.underlyingError) {
+  console.warn("Auth warning:", user.underlyingError);
+}
+
+// From error (on failure)
+try {
+  await login("google");
+} catch (e) {
+  const error = e as Error & { underlyingError?: string };
+  console.log("Native error:", error.underlyingError);
+}
+```
 
 ### Automatic Token Refresh
 
@@ -177,6 +435,9 @@ await requestScopes(["https://www.googleapis.com/auth/calendar.readonly"]);
 
 // Check granted scopes
 console.log("Granted:", scopes);
+
+// Revoke specific scopes
+await revokeScopes(["https://www.googleapis.com/auth/calendar.readonly"]);
 ```
 
 ### Offline Access (Server Auth Code)
@@ -194,24 +455,38 @@ if (user?.serverAuthCode) {
 
 ### Custom Storage Adapter
 
-By default, Nitro Auth uses standard local storage. You can provide a custom adapter for better security (e.g., using `react-native-keychain`):
+By default, Nitro Auth uses standard local storage. You can provide a custom adapter for better security.
+
+> [!IMPORTANT]
+> `AuthStorageAdapter` must be implemented as a **native Nitro HybridObject** in C++, Swift, or Kotlin. Plain JavaScript objects are not supported due to Nitro's type system. See [Nitro Hybrid Objects documentation](https://nitro.margelo.com/docs/hybrid-objects) for implementation details.
+
+**Example (Swift):**
+
+```swift
+class HybridKeychainStorage: HybridAuthStorageAdapterSpec {
+  func save(key: String, value: String) {
+    // Save to Keychain
+  }
+
+  func load(key: String) -> String? {
+    // Load from Keychain
+  }
+
+  func remove(key: String) {
+    // Remove from Keychain
+  }
+}
+```
+
+**Usage (TypeScript):**
 
 ```ts
+import { NitroModules } from "react-native-nitro-modules";
 import { AuthService, AuthStorageAdapter } from "react-native-nitro-auth";
 
-const myStorage: AuthStorageAdapter = {
-  save: (key, value) => {
-    /* Save to Keychain */
-  },
-  load: (key) => {
-    /* Load from Keychain */
-  },
-  remove: (key) => {
-    /* Clear from Keychain */
-  },
-};
-
-AuthService.setStorageAdapter(myStorage);
+const keychainStorage =
+  NitroModules.createHybridObject<AuthStorageAdapter>("KeychainStorage");
+AuthService.setStorageAdapter(keychainStorage);
 ```
 
 ### Token Refresh Listeners
@@ -221,20 +496,39 @@ Perfect for updating your API client (e.g., Axios/Fetch) whenever tokens are ref
 ```ts
 AuthService.onTokensRefreshed((tokens) => {
   console.log("Tokens were updated!", tokens.accessToken);
-  apiClient.defaults.headers.common[
-    "Authorization"
-  ] = `Bearer ${tokens.accessToken}`;
+  apiClient.defaults.headers.common["Authorization"] =
+    `Bearer ${tokens.accessToken}`;
 });
 ```
 
-### Google One-Tap (Android)
+### Google One-Tap & Sheet
 
-Explicitly enable the modern One-Tap flow on Android:
+Explicitly enable the modern One-Tap flow on Android or the Sign-In Sheet on iOS:
 
 ```ts
-await login("google", { useOneTap: true });
+await login("google", {
+  useOneTap: true, // Android
+  useSheet: true, // iOS
+});
 ```
 
+### Force Account Picker
+
+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:
+
+```ts
+await login("google", {
+  scopes: ["https://www.googleapis.com/auth/calendar.readonly"],
+  forceAccountPicker: true, // Always show account picker
+});
+```
+
+This is useful for scenarios where:
+
+- 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
+
 ## API Reference
 
 ### useAuth Hook
@@ -248,18 +542,36 @@ await login("google", { useOneTap: true });
 | `hasPlayServices` | `boolean`                         | (Android) True if Play Services available              |
 | `login`           | `(provider, options?) => Promise` | Start login flow                                       |
 | `logout`          | `() => void`                      | Clear session (synchronous)                            |
+| `silentRestore`   | `() => Promise<void>`             | Restore session automatically on startup               |
 | `requestScopes`   | `(scopes) => Promise`             | Request additional OAuth scopes                        |
+| `revokeScopes`    | `(scopes) => Promise`             | Revoke previously granted scopes                       |
 | `getAccessToken`  | `() => Promise<string?>`          | Get current access token (auto-refreshes)              |
 | `refreshToken`    | `() => Promise<AuthTokens>`       | Explicitly refresh and return new tokens               |
 
+### LoginOptions
+
+| Option               | Type       | Platform | Description                                     |
+| -------------------- | ---------- | -------- | ----------------------------------------------- |
+| `scopes`             | `string[]` | All      | Required OAuth scopes (default: email, profile) |
+| `loginHint`          | `string`   | All      | Pre-fill email address in the login picker      |
+| `useOneTap`          | `boolean`  | Android  | Enable Google One-Tap (Credential Manager)      |
+| `useSheet`           | `boolean`  | iOS      | Enable iOS Google Sign-In Sheet                 |
+| `forceAccountPicker` | `boolean`  | All      | Always show the account selection screen        |
+| `webClientId`        | `string`   | Web      | Override the default Google Web Client ID       |
+
 ### SocialButton Props
 
-| Prop        | Type                                           | Default     | Description                      |
-| ----------- | ---------------------------------------------- | ----------- | -------------------------------- |
-| `provider`  | `"google" \| "apple"`                          | required    | Authentication provider          |
-| `variant`   | `"primary" \| "outline" \| "white" \| "black"` | `"primary"` | Button style variant             |
-| `onSuccess` | `(user: AuthUser) => void`                     | —           | Called with user data on success |
-| `onError`   | `(error: Error) => void`                       | —           | Called on failure                |
+| Prop           | Type                                           | Default     | Description                                   |
+| -------------- | ---------------------------------------------- | ----------- | --------------------------------------------- |
+| `provider`     | `"google" \| "apple"`                          | required    | Authentication provider                       |
+| `variant`      | `"primary" \| "outline" \| "white" \| "black"` | `"primary"` | Button style variant                          |
+| `onPress`      | `() => void`                                   | —           | Custom handler (disables default login)       |
+| `onSuccess`    | `(user: AuthUser) => void`                     | —           | Called with user data on success (auto-login) |
+| `onError`      | `(error: unknown) => void`                     | —           | Called on failure (auto-login)                |
+| `disabled`     | `boolean`                                      | `false`     | Disable button interaction                    |
+| `style`        | `ViewStyle`                                    | —           | Custom container styles                       |
+| `textStyle`    | `TextStyle`                                    | —           | Custom text styles                            |
+| `borderRadius` | `number`                                       | `8`         | Button border radius                          |
 
 ## Platform Support
 

package/android/build.gradle

@@ -93,7 +93,7 @@ dependencies {
   implementation project(":react-native-nitro-modules")
   
   // Google Sign-In SDK (full scope support)
-  implementation "com.google.android.gms:play-services-auth:21.2.0"
+  implementation "com.google.android.gms:play-services-auth:21.5.0"
   
   // Activity result APIs
   implementation "androidx.activity:activity-ktx:1.9.3"

package/android/src/main/cpp/PlatformAuth+Android.cpp

@@ -41,11 +41,13 @@ std::shared_ptr<Promise<AuthUser>> PlatformAuth::login(AuthProvider provider, co
     std::vector<std::string> scopes = {"email", "profile"};
     std::optional<std::string> loginHint;
     bool useOneTap = false;
+    bool forceAccountPicker = false;
 
     if (options) {
         if (options->scopes) scopes = *options->scopes;
         loginHint = options->loginHint;
         useOneTap = options->useOneTap.value_or(false);
+        forceAccountPicker = options->forceAccountPicker.value_or(false);
     }
 
     JNIEnv* env = Environment::current();
@@ -58,14 +60,15 @@ std::shared_ptr<Promise<AuthUser>> PlatformAuth::login(AuthProvider provider, co
     jstring jLoginHint = loginHint.has_value() ? make_jstring(loginHint.value()).get() : nullptr;
     jclass adapterClass = env->FindClass("com/auth/AuthAdapter");
     jmethodID loginMethod = env->GetStaticMethodID(adapterClass, "loginSync", 
-        "(Landroid/content/Context;Ljava/lang/String;Ljava/lang/String;[Ljava/lang/String;Ljava/lang/String;Z)V");
+        "(Landroid/content/Context;Ljava/lang/String;Ljava/lang/String;[Ljava/lang/String;Ljava/lang/String;ZZ)V");
     env->CallStaticVoidMethod(adapterClass, loginMethod, 
         contextPtr, 
         make_jstring(providerStr).get(),
         nullptr,
         jScopes,
         jLoginHint,
-        (jboolean)useOneTap);
+        (jboolean)useOneTap,
+        (jboolean)forceAccountPicker);
     
     return promise;
 }
@@ -225,13 +228,14 @@ extern "C" JNIEXPORT void JNICALL Java_com_auth_AuthAdapter_nativeOnLoginSuccess
         jmethodID longValueMethod = env->GetMethodID(longClass, "longValue", "()J");
         user.expirationTime = (double)env->CallLongMethod(expirationTime, longValueMethod);
     }
+    
     if (loginPromise) loginPromise->resolve(user);
     if (scopesPromise) scopesPromise->resolve(user);
     if (silentPromise) silentPromise->resolve(user);
 }
 
 extern "C" JNIEXPORT void JNICALL Java_com_auth_AuthAdapter_nativeOnLoginError(
-    JNIEnv* env, jclass, jstring error) {
+    JNIEnv* env, jclass, jstring error, jstring underlyingError) {
     
     std::shared_ptr<Promise<AuthUser>> loginPromise;
     std::shared_ptr<Promise<AuthUser>> scopesPromise;
@@ -249,12 +253,19 @@ extern "C" JNIEXPORT void JNICALL Java_com_auth_AuthAdapter_nativeOnLoginError(
     const char* errorCStr = env->GetStringUTFChars(error, nullptr);
     std::string errorStr(errorCStr);
     env->ReleaseStringUTFChars(error, errorCStr);
+    
+    std::string finalError = errorStr;
+    if (underlyingError) {
+        const char* uCStr = env->GetStringUTFChars(underlyingError, nullptr);
+        finalError = std::string(uCStr);
+        env->ReleaseStringUTFChars(underlyingError, uCStr);
+    }
 
-    if (loginPromise) loginPromise->reject(std::make_exception_ptr(std::runtime_error(errorStr)));
-    if (scopesPromise) scopesPromise->reject(std::make_exception_ptr(std::runtime_error(errorStr)));
+    if (loginPromise) loginPromise->reject(std::make_exception_ptr(std::runtime_error(finalError)));
+    if (scopesPromise) scopesPromise->reject(std::make_exception_ptr(std::runtime_error(finalError)));
     if (silentPromise) {
         if (errorStr == "No session") silentPromise->resolve(std::nullopt);
-        else silentPromise->reject(std::make_exception_ptr(std::runtime_error(errorStr)));
+        else silentPromise->reject(std::make_exception_ptr(std::runtime_error(finalError)));
     }
 }
 
@@ -290,7 +301,7 @@ extern "C" JNIEXPORT void JNICALL Java_com_auth_AuthAdapter_nativeOnRefreshSucce
 }
 
 extern "C" JNIEXPORT void JNICALL Java_com_auth_AuthAdapter_nativeOnRefreshError(
-    JNIEnv* env, jclass, jstring error) {
+    JNIEnv* env, jclass, jstring error, jstring underlyingError) {
     
     std::shared_ptr<Promise<AuthTokens>> refreshPromise;
     {
@@ -299,10 +310,17 @@ extern "C" JNIEXPORT void JNICALL Java_com_auth_AuthAdapter_nativeOnRefreshError
         gRefreshPromise = nullptr;
     }
     if (refreshPromise) {
+        std::string finalError;
         const char* errorCStr = env->GetStringUTFChars(error, nullptr);
-        std::string errorStr(errorCStr);
+        finalError = std::string(errorCStr);
         env->ReleaseStringUTFChars(error, errorCStr);
-        refreshPromise->reject(std::make_exception_ptr(std::runtime_error(errorStr)));
+        
+        if (underlyingError) {
+            const char* uCStr = env->GetStringUTFChars(underlyingError, nullptr);
+            finalError = std::string(uCStr);
+            env->ReleaseStringUTFChars(underlyingError, uCStr);
+        }
+        refreshPromise->reject(std::make_exception_ptr(std::runtime_error(finalError)));
     }
 }