@capgo/capacitor-social-login 8.3.32 → 8.3.34

package/README.md

@@ -420,26 +420,80 @@ const res = await SocialLogin.login({
 });
 ```
 
-#### Android troubleshooting (SHA-1 and Firebase)
-
-Many Android "auth 10/16" or blank-response issues come from a mismatched SHA-1 fingerprint. Use the exact build you install on the device to register the SHA-1 in Google Cloud/Firebase:
-
-1. Build a signed APK from Android Studio (`Build` → `Generate Signed App Bundle / APK`, pick APK) using your release keystore.
-2. Extract the SHA-1 from that final APK:
-   ```bash
-   keytool -printcert -jarfile android/app/release/app-release.apk
-   ```
-3. Add that SHA-1 to your Android OAuth client in [Google Cloud Console](https://console.cloud.google.com/apis/credentials) (package name + SHA-1).
-4. Reinstall the same signed APK on device for testing:
-   ```bash
-   adb install android/app/release/app-release.apk
-   ```
-5. When consuming the plugin result, read tokens from `result.result`:
-   ```ts
-   const login = await SocialLogin.login({ provider: 'google' });
-   const idToken = login.result?.idToken; // not login.idToken
-   ```
-   For Firebase Auth, create credentials with that `idToken` (and use the Web Client ID as `webClientId` in `initialize`).
+#### Android troubleshooting (Credential Manager, SHA-1, and Firebase)
+
+On Android this plugin uses **Google Credential Manager** (`androidx.credentials` + Sign in with Google), not the legacy `GoogleSignInClient` API. Logcat errors such as `GetCredentialCustomException: [28444] Developer console is not set up correctly` come from that stack.
+
+Filter Logcat with `GoogleProvider` or `CapgoSocialLogin` after a failed login. The plugin logs your **package name**, **signing SHA-1**, and a masked **webClientId** to help compare against Google Cloud Console.
+
+##### Required Google Cloud setup (all in the same project)
+
+You need **two kinds** of OAuth 2.0 client IDs:
+
+| Client type | Used for | Where it goes |
+|-------------|----------|---------------|
+| **Web application** | Server / ID token audience | `webClientId` in `SocialLogin.initialize()` |
+| **Android** (one per signing key) | Proves your APK is allowed to call Google | Google Cloud Console only — **do not** pass this ID to `webClientId` |
+
+Common mistake: using the **Android** client ID as `webClientId`. Credential Manager requires the **Web** client ID there. The Android client only needs the correct **package name + SHA-1** registered in the console.
+
+Create one Android OAuth client for **each** certificate that signs builds you test:
+
+- **Debug** — from `./gradlew signingReport` (debug variant)
+- **Release** — from the APK/AAB you actually install (see below)
+- **Play App Signing** — from Play Console → **App integrity** → **App signing key certificate** (required for Play Store builds even if your upload key SHA-1 is already registered)
+
+The `applicationId` in `android/app/build.gradle` must match the Android OAuth client package name exactly (including any `.debug` suffix if you use one).
+
+If the OAuth consent screen is in **Testing** mode, add every Google account you test with under **Audience → Test users**. Publishing the app to Production is **not** required for `email` / `profile` scopes. **Digital Asset Links** (`assetlinks.json`) are **not** required for Sign in with Google via Credential Manager.
+
+Google Cloud changes can take **up to a few hours** to propagate; a device restart alone may not be enough.
+
+##### Error `[28444] Developer console is not set up correctly`
+
+This almost always means Google rejected the combination of **installed APK signing certificate**, **package name**, and **webClientId`. Work through this checklist:
+
+1. Confirm `webClientId` is the **Web application** client ID (ends with `.apps.googleusercontent.com`).
+2. Run the app, reproduce the failure, and read Logcat (`GoogleProvider`) for `signingSha1=` and `package=`.
+3. In [Google Cloud Console → Credentials](https://console.cloud.google.com/apis/credentials), open your **Android** OAuth client and verify that **exact** package name and SHA-1 are listed.
+4. If testing a **release** build, register the SHA-1 from that build — not only the debug keystore.
+5. If the app is distributed via **Play Store**, also register the **Play App Signing** SHA-1.
+6. Ensure Web and Android clients live in the **same** Google Cloud project.
+7. If consent screen is in Testing, confirm the Google account is a **test user**.
+8. Wait and retry after console changes.
+
+`USER_CANCELLED` after picking an account on a misconfigured debug build can still be a SHA-1 / client-ID mismatch — fix the console setup above first.
+
+##### Extract SHA-1 from the build you install
+
+Debug / local builds:
+
+```bash
+cd android && ./gradlew signingReport
+```
+
+Signed release APK:
+
+```bash
+keytool -printcert -jarfile android/app/release/app-release.apk
+```
+
+Then add that SHA-1 to an Android OAuth client (package name + SHA-1) in Google Cloud Console, reinstall the **same** signed APK, and test again:
+
+```bash
+adb install android/app/release/app-release.apk
+```
+
+##### Reading the login result (Firebase and backends)
+
+Tokens are nested under `result`:
+
+```ts
+const login = await SocialLogin.login({ provider: 'google' });
+const idToken = login.result?.idToken; // not login.idToken
+```
+
+For Firebase Auth, create credentials with that `idToken` and use the **Web** Client ID as `webClientId` in `initialize`.
 
 ### iOS configuration
 
@@ -690,6 +744,12 @@ const config: CapacitorConfig = {
 
 Then run `npx cap sync`. The plugin uses stub classes instead of the real Facebook SDK, so no Facebook dependencies or permissions are included in your build.
 
+### Google Sign-In `[28444] Developer console is not set up correctly` (Android)
+
+On Android, this error comes from **Google Credential Manager** when the installed APK's signing certificate, package name, or `webClientId` does not match Google Cloud Console.
+
+See [Android troubleshooting (Credential Manager, SHA-1, and Firebase)](#android-troubleshooting-credential-manager-sha-1-and-firebase) for the full checklist. After a failed login, filter Logcat for `GoogleProvider` — the plugin prints `package`, `signingSha1`, and `webClientId` to compare with your OAuth clients.
+
 ### Google Sign-In with Family Link Supervised Accounts
 
 **Problem**: When users try to sign in with Google accounts supervised by Family Link, login fails with:
@@ -912,6 +972,16 @@ Notes:
 - Accepts both `idToken` and `token` to match common naming (Capawesome uses `token`).
 - This does not validate the signature or issuer/audience. It only base64url-decodes the payload.
 
+**`email_verified` semantics by provider (for account linking):**
+- **Google** — ID token includes `email_verified` (boolean). When `true`, Google attests
+  the user controls that email. Verify the JWT on your backend before trusting it.
+- **Apple** — ID token includes `email_verified` (boolean). When `true`, Apple attests
+  the user controls that email (including private relay). Verify the JWT on your backend.
+- **Meta (Facebook)** — Limited Login OIDC tokens may include `email` but **do not**
+  include `email_verified`. The presence of `email` is not the same guarantee as
+  `email_verified: true` from Google or Apple. Do not link accounts by email across
+  providers using Meta claims alone; perform your own email verification if needed.
+
 | Param         | Type                                               |
 | ------------- | -------------------------------------------------- |
 | **`options`** | <code>{ idToken?: string; token?: string; }</code> |
@@ -1134,12 +1204,12 @@ Configuration for a single OAuth2 provider instance
 
 #### FacebookLoginResponse
 
-| Prop                 | Type                                                                                                                                                                                                                                                                                                                                                            | Description                                                                                                                                                                                                                                                       | Since |
-| -------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----- |
-| **`accessToken`**    | <code><a href="#accesstoken">AccessToken</a> \| null</code>                                                                                                                                                                                                                                                                                                     |                                                                                                                                                                                                                                                                   |       |
-| **`isLimitedLogin`** | <code>boolean</code>                                                                                                                                                                                                                                                                                                                                            | Whether Facebook Limited Login was used for this session. When `true`, `accessToken` is not valid for Graph API calls (Facebook error 190). Validate `idToken` on your backend instead, or call `facebook#requestTracking` and log in again after ATT is granted. | 8.4.0 |
-| **`idToken`**        | <code>string \| null</code>                                                                                                                                                                                                                                                                                                                                     |                                                                                                                                                                                                                                                                   |       |
-| **`profile`**        | <code>{ userID: string; email: string \| null; friendIDs: string[]; birthday: string \| null; ageRange: { min?: number; max?: number; } \| null; gender: string \| null; location: { id: string; name: string; } \| null; hometown: { id: string; name: string; } \| null; profileURL: string \| null; name: string \| null; imageURL: string \| null; }</code> |                                                                                                                                                                                                                                                                   |       |
+| Prop                 | Type                                                                                                                                                                                                                                                                                                                                                            | Description                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         | Since |
+| -------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----- |
+| **`accessToken`**    | <code><a href="#accesstoken">AccessToken</a> \| null</code>                                                                                                                                                                                                                                                                                                     |                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     |       |
+| **`isLimitedLogin`** | <code>boolean</code>                                                                                                                                                                                                                                                                                                                                            | Whether Facebook Limited Login was used for this session. When `true`, `accessToken` is not valid for Graph API calls (Facebook error 190). Validate `idToken` on your backend instead, or call `facebook#requestTracking` and log in again after ATT is granted.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   | 8.4.0 |
+| **`idToken`**        | <code>string \| null</code>                                                                                                                                                                                                                                                                                                                                     | OpenID Connect ID token (JWT) from Meta Limited Login (iOS native, when available). **Not equivalent to Google/Apple `email_verified`:** Meta's OIDC token may include an `email` claim (when the `email` permission is granted) but does **not** publish an `email_verified` claim like Google or Apple. Meta documents the value as the user's primary account email, not as an OIDC-verified email assertion. On Android and Web this is usually `null` (Graph API access token flow instead). Validate signature, `iss` (`https://www.facebook.com` or `https://limited.facebook.com`), `aud`, `exp`, and nonce on your backend. Do not infer `email_verified: true` from the presence of `email` alone when linking accounts across providers. |       |
+| **`profile`**        | <code>{ userID: string; email: string \| null; friendIDs: string[]; birthday: string \| null; ageRange: { min?: number; max?: number; } \| null; gender: string \| null; location: { id: string; name: string; } \| null; hometown: { id: string; name: string; } \| null; profileURL: string \| null; name: string \| null; imageURL: string \| null; }</code> |                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     |       |
 
 
 #### AccessToken
@@ -1160,12 +1230,12 @@ Configuration for a single OAuth2 provider instance
 
 #### GoogleLoginResponseOnline
 
-| Prop               | Type                                                                                                                                                               |
-| ------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
-| **`accessToken`**  | <code><a href="#accesstoken">AccessToken</a> \| null</code>                                                                                                        |
-| **`idToken`**      | <code>string \| null</code>                                                                                                                                        |
-| **`profile`**      | <code>{ email: string \| null; familyName: string \| null; givenName: string \| null; id: string \| null; name: string \| null; imageUrl: string \| null; }</code> |
-| **`responseType`** | <code>'online'</code>                                                                                                                                              |
+| Prop               | Type                                                                                                                                                               | Description                                                                                                                                                                                                                                                                                                          |
+| ------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| **`accessToken`**  | <code><a href="#accesstoken">AccessToken</a> \| null</code>                                                                                                        |                                                                                                                                                                                                                                                                                                                      |
+| **`idToken`**      | <code>string \| null</code>                                                                                                                                        | OpenID Connect ID token (JWT). Includes an `email_verified` claim when the `email` scope is granted. Use `SocialLogin.decodeIdToken({ idToken })` to read claims on the client, but always verify the token signature, `iss`, `aud`, and `exp` on your backend before trusting `email_verified` for account linking. |
+| **`profile`**      | <code>{ email: string \| null; familyName: string \| null; givenName: string \| null; id: string \| null; name: string \| null; imageUrl: string \| null; }</code> |                                                                                                                                                                                                                                                                                                                      |
+| **`responseType`** | <code>'online'</code>                                                                                                                                              |                                                                                                                                                                                                                                                                                                                      |
 
 
 #### GoogleLoginResponseOffline
@@ -1178,12 +1248,12 @@ Configuration for a single OAuth2 provider instance
 
 #### AppleProviderResponse
 
-| Prop                    | Type                                                                                                         | Description                                                                           |
-| ----------------------- | ------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------- |
-| **`accessToken`**       | <code><a href="#accesstoken">AccessToken</a> \| null</code>                                                  | Access token from Apple                                                               |
-| **`idToken`**           | <code>string \| null</code>                                                                                  | Identity token (JWT) from Apple                                                       |
-| **`profile`**           | <code>{ user: string; email: string \| null; givenName: string \| null; familyName: string \| null; }</code> | User profile information                                                              |
-| **`authorizationCode`** | <code>string</code>                                                                                          | Authorization code for proper token exchange (when useProperTokenExchange is enabled) |
+| Prop                    | Type                                                                                                         | Description                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |
+| ----------------------- | ------------------------------------------------------------------------------------------------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| **`accessToken`**       | <code><a href="#accesstoken">AccessToken</a> \| null</code>                                                  | Access token from Apple                                                                                                                                                                                                                                                                                                                                                                                                                                                     |
+| **`idToken`**           | <code>string \| null</code>                                                                                  | Identity token (JWT) from Apple. Includes standard OIDC claims such as `sub`, `email` (when granted), and `email_verified` (boolean). Apple sets `email_verified` to `true` when it attests the user controls the email (including Hide My Email relay addresses). Use `SocialLogin.decodeIdToken({ idToken })` to read claims on the client, but verify the token signature, `iss`, `aud`, and `exp` on your backend before trusting `email_verified` for account linking. |
+| **`profile`**           | <code>{ user: string; email: string \| null; givenName: string \| null; familyName: string \| null; }</code> | User profile information                                                                                                                                                                                                                                                                                                                                                                                                                                                    |
+| **`authorizationCode`** | <code>string</code>                                                                                          | Authorization code for proper token exchange (when useProperTokenExchange is enabled)                                                                                                                                                                                                                                                                                                                                                                                       |
 
 
 #### TwitterLoginResponse

package/android/src/main/java/ee/forgr/capacitor/social/login/GoogleProvider.java

@@ -5,6 +5,10 @@ import android.app.PendingIntent;
 import android.content.Context;
 import android.content.Intent;
 import android.content.IntentSender;
+import android.content.pm.PackageInfo;
+import android.content.pm.PackageManager;
+import android.content.pm.Signature;
+import android.os.Build;
 import android.util.Log;
 import androidx.annotation.NonNull;
 import androidx.concurrent.futures.CallbackToFutureAdapter;
@@ -32,6 +36,8 @@ import com.google.android.libraries.identity.googleid.GoogleIdTokenCredential;
 import com.google.common.util.concurrent.ListenableFuture;
 import ee.forgr.capacitor.social.login.helpers.SocialProvider;
 import java.io.IOException;
+import java.security.MessageDigest;
+import java.security.NoSuchAlgorithmException;
 import java.util.ArrayList;
 import java.util.HashSet;
 import java.util.List;
@@ -83,6 +89,75 @@ public class GoogleProvider implements SocialProvider {
     private GoogleProviderLoginType mode = GoogleProviderLoginType.ONLINE;
     private String hostedDomain = null;
 
+    private static String maskClientId(String clientId) {
+        if (clientId == null || clientId.isEmpty()) {
+            return "(not set)";
+        }
+        if (clientId.length() <= 16) {
+            return clientId;
+        }
+        return "..." + clientId.substring(clientId.length() - 20);
+    }
+
+    private static String getSigningCertificateSha1(Context context) {
+        try {
+            PackageManager pm = context.getPackageManager();
+            String packageName = context.getPackageName();
+            if (Build.VERSION.SDK_INT >= Build.VERSION_CODES.P) {
+                PackageInfo info = pm.getPackageInfo(packageName, PackageManager.GET_SIGNING_CERTIFICATES);
+                if (info.signingInfo != null) {
+                    Signature[] signatures = info.signingInfo.getApkContentsSigners();
+                    if (signatures != null && signatures.length > 0) {
+                        return sha1Fingerprint(signatures[0]);
+                    }
+                }
+            } else {
+                @SuppressWarnings("deprecation")
+                PackageInfo info = pm.getPackageInfo(packageName, PackageManager.GET_SIGNATURES);
+                @SuppressWarnings("deprecation")
+                Signature[] signatures = info.signatures;
+                if (signatures != null && signatures.length > 0) {
+                    return sha1Fingerprint(signatures[0]);
+                }
+            }
+        } catch (PackageManager.NameNotFoundException e) {
+            Log.w(LOG_TAG, "Could not read app signing certificate", e);
+        }
+        return null;
+    }
+
+    private static String sha1Fingerprint(Signature signature) {
+        try {
+            MessageDigest md = MessageDigest.getInstance("SHA-1");
+            byte[] digest = md.digest(signature.toByteArray());
+            StringBuilder sb = new StringBuilder();
+            for (int i = 0; i < digest.length; i++) {
+                if (i > 0) {
+                    sb.append(':');
+                }
+                sb.append(String.format("%02X", digest[i]));
+            }
+            return sb.toString();
+        } catch (NoSuchAlgorithmException e) {
+            return null;
+        }
+    }
+
+    private void logGoogleCloudDiagnostics(String phase) {
+        String sha1 = getSigningCertificateSha1(context);
+        Log.i(
+            LOG_TAG,
+            String.format(
+                "Google %s: package=%s signingSha1=%s webClientId=%s mode=%s",
+                phase,
+                context.getPackageName(),
+                sha1 != null ? sha1 : "unknown",
+                maskClientId(clientId),
+                mode != null ? mode.name() : "unknown"
+            )
+        );
+    }
+
     public enum GoogleProviderLoginType {
         ONLINE,
         OFFLINE
@@ -102,6 +177,7 @@ public class GoogleProvider implements SocialProvider {
         this.clientId = clientId;
         this.mode = mode;
         this.hostedDomain = hostedDomain;
+        logGoogleCloudDiagnostics("initialize");
 
         String data = context.getSharedPreferences(SHARED_PREFERENCE_NAME, Context.MODE_PRIVATE).getString(GOOGLE_DATA_PREFERENCE, null);
 
@@ -301,6 +377,8 @@ public class GoogleProvider implements SocialProvider {
             return;
         }
 
+        logGoogleCloudDiagnostics("login");
+
         String nonce = config.optString("nonce");
         JSONObject options = call.getObject("options", new JSObject());
         boolean bottomUi = false;
@@ -346,8 +424,19 @@ public class GoogleProvider implements SocialProvider {
         // Build credential request
         GetCredentialRequest.Builder requestBuilder = new GetCredentialRequest.Builder();
 
+        Log.i(
+            LOG_TAG,
+            String.format(
+                "Google login request: ui=%s filterByAuthorizedAccounts=%s autoSelectEnabled=%s forcePrompt=%s nonceSet=%s",
+                bottomUi ? "bottom" : "standard",
+                filterByAuthorizedAccounts,
+                autoSelectEnabled,
+                forcePrompt,
+                !nonce.isEmpty()
+            )
+        );
+
         if (bottomUi) {
-            Log.e(LOG_TAG, "use bottomUi");
             GetGoogleIdOption.Builder googleIdOptionBuilder = new GetGoogleIdOption.Builder().setServerClientId(this.clientId);
             // Handle bottom UI specific options
             if (forcePrompt) {
@@ -642,8 +731,43 @@ public class GoogleProvider implements SocialProvider {
         }
     }
 
+    private boolean isDeveloperConsoleMisconfiguration(String message) {
+        return message.contains("Developer console") || message.contains("28444") || message.contains("10:");
+    }
+
+    private void logDeveloperConsoleMisconfigurationHelp(String errorMessage) {
+        String sha1 = getSigningCertificateSha1(context);
+        Log.e(
+            LOG_TAG,
+            String.format(
+                "Google Credential Manager rejected this app (%s). package=%s signingSha1=%s webClientId=%s. " +
+                    "Checklist: (1) webClientId must be a Web OAuth client ID, not Android; " +
+                    "(2) create an Android OAuth client with this exact package + SHA-1 in the same GCP project; " +
+                    "(3) add Play App Signing SHA-1 for Play Store builds; " +
+                    "(4) add test users if OAuth consent screen is in Testing; " +
+                    "(5) allow several hours for console changes to propagate.",
+                errorMessage,
+                context.getPackageName(),
+                sha1 != null ? sha1 : "unknown",
+                maskClientId(clientId)
+            )
+        );
+    }
+
     private void handleSignInError(GetCredentialException e, PluginCall call, JSONObject config) {
-        Log.e(LOG_TAG, "Google Sign-In failed", e);
+        String errorMessage = e.getMessage() != null ? e.getMessage() : e.getClass().getSimpleName();
+        Log.e(LOG_TAG, "Google Sign-In failed: " + errorMessage, e);
+
+        if (isDeveloperConsoleMisconfiguration(errorMessage)) {
+            logDeveloperConsoleMisconfigurationHelp(errorMessage);
+            call.reject(
+                "Google Sign-In failed: Google Cloud OAuth is not configured for this installed build (" +
+                    errorMessage +
+                    "). Check Logcat tag GoogleProvider for package, signingSha1, and webClientId, then see the Android troubleshooting section in the plugin README."
+            );
+            return;
+        }
+
         boolean isBottomUi = false;
         JSONObject options = call.getObject("options", new JSObject());
         if (options.has("style")) {

package/android/src/main/java/ee/forgr/capacitor/social/login/SocialLoginPlugin.java

@@ -24,7 +24,7 @@ import org.json.JSONObject;
 @CapacitorPlugin(name = "SocialLogin")
 public class SocialLoginPlugin extends Plugin {
 
-    private final String pluginVersion = "8.3.32";
+    private final String pluginVersion = "8.3.34";
 
     public static String LOG_TAG = "CapgoSocialLogin";
     public HashMap<String, SocialProvider> socialProviderHashMap = new HashMap<>();

package/dist/docs.json

@@ -204,7 +204,7 @@
         ],
         "returns": "Promise<{ claims: Record<string, any>; }>",
         "tags": [],
-        "docs": "Decode a JWT (typically an OIDC ID token) into its claims.\n\nNotes:\n- Accepts both `idToken` and `token` to match common naming (Capawesome uses `token`).\n- This does not validate the signature or issuer/audience. It only base64url-decodes the payload.",
+        "docs": "Decode a JWT (typically an OIDC ID token) into its claims.\n\nNotes:\n- Accepts both `idToken` and `token` to match common naming (Capawesome uses `token`).\n- This does not validate the signature or issuer/audience. It only base64url-decodes the payload.\n\n**`email_verified` semantics by provider (for account linking):**\n- **Google** — ID token includes `email_verified` (boolean). When `true`, Google attests\n  the user controls that email. Verify the JWT on your backend before trusting it.\n- **Apple** — ID token includes `email_verified` (boolean). When `true`, Apple attests\n  the user controls that email (including private relay). Verify the JWT on your backend.\n- **Meta (Facebook)** — Limited Login OIDC tokens may include `email` but **do not**\n  include `email_verified`. The presence of `email` is not the same guarantee as\n  `email_verified: true` from Google or Apple. Do not link accounts by email across\n  providers using Meta claims alone; perform your own email verification if needed.",
         "complexTypes": [
           "Record"
         ],
@@ -722,8 +722,13 @@
         },
         {
           "name": "idToken",
-          "tags": [],
-          "docs": "",
+          "tags": [
+            {
+              "text": "https ://developers.facebook.com/docs/facebook-login/limited-login/token/validating/",
+              "name": "see"
+            }
+          ],
+          "docs": "OpenID Connect ID token (JWT) from Meta Limited Login (iOS native, when available).\n\n**Not equivalent to Google/Apple `email_verified`:** Meta's OIDC token may include\nan `email` claim (when the `email` permission is granted) but does **not** publish an\n`email_verified` claim like Google or Apple. Meta documents the value as the user's\nprimary account email, not as an OIDC-verified email assertion.\n\nOn Android and Web this is usually `null` (Graph API access token flow instead).\nValidate signature, `iss` (`https://www.facebook.com` or `https://limited.facebook.com`),\n`aud`, `exp`, and nonce on your backend. Do not infer `email_verified: true` from the\npresence of `email` alone when linking accounts across providers.",
           "complexTypes": [],
           "type": "string | null"
         },
@@ -833,8 +838,13 @@
         },
         {
           "name": "idToken",
-          "tags": [],
-          "docs": "",
+          "tags": [
+            {
+              "text": "https ://developers.google.com/identity/gsi/web/guides/verify-google-id-token",
+              "name": "see"
+            }
+          ],
+          "docs": "OpenID Connect ID token (JWT).\n\nIncludes an `email_verified` claim when the `email` scope is granted. Use\n`SocialLogin.decodeIdToken({ idToken })` to read claims on the client, but\nalways verify the token signature, `iss`, `aud`, and `exp` on your backend\nbefore trusting `email_verified` for account linking.",
           "complexTypes": [],
           "type": "string | null"
         },
@@ -902,11 +912,11 @@
           "name": "idToken",
           "tags": [
             {
-              "text": "Always contains the JWT with user identity information including:\n- User ID (sub claim)\n- Email (if user granted permission)\n- Name components (if user granted permission)\n- Email verification status\nThis is the primary token for user authentication and should be verified on your backend.",
-              "name": "description"
+              "text": "https ://developer.apple.com/documentation/signinwithapple/authenticating-users-with-sign-in-with-apple",
+              "name": "see"
             }
           ],
-          "docs": "Identity token (JWT) from Apple",
+          "docs": "Identity token (JWT) from Apple.\n\nIncludes standard OIDC claims such as `sub`, `email` (when granted), and\n`email_verified` (boolean). Apple sets `email_verified` to `true` when it\nattests the user controls the email (including Hide My Email relay addresses).\n\nUse `SocialLogin.decodeIdToken({ idToken })` to read claims on the client, but\nverify the token signature, `iss`, `aud`, and `exp` on your backend before\ntrusting `email_verified` for account linking.",
           "complexTypes": [],
           "type": "string | null"
         },

package/dist/esm/definitions.d.ts

@@ -573,8 +573,22 @@ export interface GoogleLoginOptions {
 }
 export interface GoogleLoginResponseOnline {
     accessToken: AccessToken | null;
+    /**
+     * OpenID Connect ID token (JWT).
+     *
+     * Includes an `email_verified` claim when the `email` scope is granted. Use
+     * `SocialLogin.decodeIdToken({ idToken })` to read claims on the client, but
+     * always verify the token signature, `iss`, `aud`, and `exp` on your backend
+     * before trusting `email_verified` for account linking.
+     *
+     * @see https://developers.google.com/identity/gsi/web/guides/verify-google-id-token
+     */
     idToken: string | null;
     profile: {
+        /**
+         * Email from the ID token payload. Does not include a separate verification flag;
+         * check `idToken` claims (`email_verified`) for whether Google attests the address.
+         */
         email: string | null;
         familyName: string | null;
         givenName: string | null;
@@ -625,13 +639,17 @@ export interface AppleProviderResponse {
      */
     accessToken: AccessToken | null;
     /**
-     * Identity token (JWT) from Apple
-     * @description Always contains the JWT with user identity information including:
-     * - User ID (sub claim)
-     * - Email (if user granted permission)
-     * - Name components (if user granted permission)
-     * - Email verification status
-     * This is the primary token for user authentication and should be verified on your backend.
+     * Identity token (JWT) from Apple.
+     *
+     * Includes standard OIDC claims such as `sub`, `email` (when granted), and
+     * `email_verified` (boolean). Apple sets `email_verified` to `true` when it
+     * attests the user controls the email (including Hide My Email relay addresses).
+     *
+     * Use `SocialLogin.decodeIdToken({ idToken })` to read claims on the client, but
+     * verify the token signature, `iss`, `aud`, and `exp` on your backend before
+     * trusting `email_verified` for account linking.
+     *
+     * @see https://developer.apple.com/documentation/signinwithapple/authenticating-users-with-sign-in-with-apple
      */
     idToken: string | null;
     /**
@@ -710,9 +728,33 @@ export interface FacebookLoginResponse {
      * @since 8.4.0
      */
     isLimitedLogin?: boolean;
+    /**
+     * OpenID Connect ID token (JWT) from Meta Limited Login (iOS native, when available).
+     *
+     * **Not equivalent to Google/Apple `email_verified`:** Meta's OIDC token may include
+     * an `email` claim (when the `email` permission is granted) but does **not** publish an
+     * `email_verified` claim like Google or Apple. Meta documents the value as the user's
+     * primary account email, not as an OIDC-verified email assertion.
+     *
+     * On Android and Web this is usually `null` (Graph API access token flow instead).
+     * Validate signature, `iss` (`https://www.facebook.com` or `https://limited.facebook.com`),
+     * `aud`, `exp`, and nonce on your backend. Do not infer `email_verified: true` from the
+     * presence of `email` alone when linking accounts across providers.
+     *
+     * @see https://developers.facebook.com/docs/facebook-login/limited-login/token/validating/
+     */
     idToken: string | null;
     profile: {
         userID: string;
+        /**
+         * Primary email from the Meta profile / Graph API (`/me?fields=email`).
+         *
+         * **Not equivalent to Google/Apple `email_verified`:** this field has no verification
+         * flag. Meta returns the account's primary email when the `email` permission is
+         * granted; it does not expose an `email_verified` boolean comparable to Google or
+         * Apple ID tokens. Treat this as an identifier hint only—verify ownership yourself
+         * (e.g. magic link) before linking Meta sign-in to Google/Apple accounts by email.
+         */
         email: string | null;
         friendIDs: string[];
         birthday: string | null;
@@ -980,6 +1022,16 @@ export interface SocialLoginPlugin {
      * Notes:
      * - Accepts both `idToken` and `token` to match common naming (Capawesome uses `token`).
      * - This does not validate the signature or issuer/audience. It only base64url-decodes the payload.
+     *
+     * **`email_verified` semantics by provider (for account linking):**
+     * - **Google** — ID token includes `email_verified` (boolean). When `true`, Google attests
+     *   the user controls that email. Verify the JWT on your backend before trusting it.
+     * - **Apple** — ID token includes `email_verified` (boolean). When `true`, Apple attests
+     *   the user controls that email (including private relay). Verify the JWT on your backend.
+     * - **Meta (Facebook)** — Limited Login OIDC tokens may include `email` but **do not**
+     *   include `email_verified`. The presence of `email` is not the same guarantee as
+     *   `email_verified: true` from Google or Apple. Do not link accounts by email across
+     *   providers using Meta claims alone; perform your own email verification if needed.
      */
     decodeIdToken(options: {
         idToken?: string;

package/dist/esm/definitions.js.map

@@ -1 +1 @@
-{"version":3,"file":"definitions.js","sourceRoot":"","sources":["../../src/definitions.ts"],"names":[],"mappings":"","sourcesContent":["/**\n * Configuration for a single OAuth2 provider instance\n */\nexport interface OAuth2ProviderConfig {\n  /**\n   * The OAuth 2.0 client identifier (App ID / Client ID).\n   *\n   * Note: this configuration object is only used by the plugin's built-in `oauth2` provider\n   * (i.e. `SocialLogin.initialize({ oauth2: { ... } })`). It does not affect Google/Apple/Facebook/Twitter.\n   * @example 'your-client-id'\n   */\n  appId?: string;\n  /**\n   * Alias for `appId` to match common OAuth/OIDC naming (`clientId`).\n   * If both are provided, `appId` takes precedence.\n   * @example 'your-client-id'\n   */\n  clientId?: string;\n  /**\n   * OpenID Connect issuer URL (enables discovery via `/.well-known/openid-configuration`).\n   * When set, you may omit explicit endpoints like `authorizationBaseUrl` and `accessTokenEndpoint`.\n   *\n   * Notes:\n   * - Explicit endpoints (authorization/token/logout) take precedence over discovered values.\n   * - Discovery is supported for `oauth2` on Web, iOS, and Android.\n   *\n   * @example 'https://accounts.example.com'\n   */\n  issuerUrl?: string;\n  /**\n   * The base URL of the authorization endpoint\n   * @example 'https://accounts.example.com/oauth2/authorize'\n   */\n  authorizationBaseUrl?: string;\n  /**\n   * Alias for `authorizationBaseUrl` (to match common OAuth/OIDC naming).\n   * @example 'https://accounts.example.com/oauth2/authorize'\n   */\n  authorizationEndpoint?: string;\n  /**\n   * OAuth 2.0 client secret for token requests (e.g., when exchanging the code).\n   * This value is sent as `client_secret` in token/refresh requests when provided.\n   */\n  clientSecret?: string;\n  /**\n   * The URL to exchange the authorization code for tokens\n   * Required for authorization code flow\n   * @example 'https://accounts.example.com/oauth2/token'\n   */\n  accessTokenEndpoint?: string;\n  /**\n   * Alias for `accessTokenEndpoint` (to match common OAuth/OIDC naming).\n   * @example 'https://accounts.example.com/oauth2/token'\n   */\n  tokenEndpoint?: string;\n  /**\n   * Redirect URL that receives the OAuth callback\n   * @example 'myapp://oauth/callback'\n   */\n  redirectUrl: string;\n  /**\n   * Optional URL to fetch user profile/resource data after authentication\n   * The access token will be sent as Bearer token in the Authorization header\n   * @example 'https://api.example.com/userinfo'\n   */\n  resourceUrl?: string;\n  /**\n   * The OAuth response type\n   * - 'code': Authorization Code flow (recommended, requires accessTokenEndpoint)\n   * - 'token': Implicit flow (less secure, tokens returned directly)\n   * @default 'code'\n   */\n  responseType?: 'code' | 'token';\n  /**\n   * Enable PKCE (Proof Key for Code Exchange)\n   * Strongly recommended for public clients (mobile/web apps)\n   * @default true\n   */\n  pkceEnabled?: boolean;\n  /**\n   * Default scopes to request during authorization\n   * @example 'openid profile email'\n   * @example ['openid','profile','email']\n   */\n  scope?: string | string[];\n  /**\n   * Alias for `scope` using common naming (`scopes`).\n   * If both are provided, `scope` takes precedence.\n   */\n  scopes?: string[];\n  /**\n   * Additional parameters to include in the authorization request\n   * @example { prompt: 'consent', login_hint: 'user@example.com' }\n   */\n  additionalParameters?: Record<string, string>;\n  /**\n   * Convenience option for OIDC `login_hint`.\n   * Equivalent to passing `additionalParameters.login_hint`.\n   */\n  loginHint?: string;\n  /**\n   * Convenience option for OAuth/OIDC `prompt`.\n   * Equivalent to passing `additionalParameters.prompt`.\n   */\n  prompt?: string;\n  /**\n   * Additional parameters to include in token requests (code exchange / refresh).\n   * Useful for providers that require non-standard parameters.\n   */\n  additionalTokenParameters?: Record<string, string>;\n  /**\n   * Additional headers to include when fetching the resource URL\n   * @example { 'X-Custom-Header': 'value' }\n   */\n  additionalResourceHeaders?: Record<string, string>;\n  /**\n   * Custom logout URL for ending the session\n   * @example 'https://accounts.example.com/logout'\n   */\n  logoutUrl?: string;\n  /**\n   * Alias for `logoutUrl` to match OIDC naming (`endSessionEndpoint`).\n   * @example 'https://accounts.example.com/logout'\n   */\n  endSessionEndpoint?: string;\n  /**\n   * OIDC post logout redirect URL (sent as `post_logout_redirect_uri` when building the end-session URL).\n   * @example 'myapp://logout/callback'\n   */\n  postLogoutRedirectUrl?: string;\n  /**\n   * Additional parameters to include in logout / end-session URL.\n   */\n  additionalLogoutParameters?: Record<string, string>;\n  /**\n   * iOS-only: Whether to prefer an ephemeral browser session for ASWebAuthenticationSession.\n   * Defaults to true to match existing behavior in this plugin.\n   */\n  iosPrefersEphemeralWebBrowserSession?: boolean;\n  /**\n   * Alias for `iosPrefersEphemeralWebBrowserSession` (to match Capawesome OAuth naming).\n   */\n  iosPrefersEphemeralSession?: boolean;\n  /**\n   * Enable debug logging\n   * @default false\n   */\n  logsEnabled?: boolean;\n}\n\nexport interface InitializeOptions {\n  /**\n   * OAuth2 provider configurations.\n   * Supports multiple providers by using a Record with provider IDs as keys.\n   * @example\n   * {\n   *   github: { appId: '...', authorizationBaseUrl: 'https://github.com/login/oauth/authorize', ... },\n   *   azure: { appId: '...', authorizationBaseUrl: 'https://login.microsoftonline.com/.../oauth2/v2.0/authorize', ... }\n   * }\n   */\n  oauth2?: Record<string, OAuth2ProviderConfig>;\n  twitter?: {\n    /**\n     * The OAuth 2.0 client identifier issued by X (Twitter) Developer Portal\n     * @example 'Y2xpZW50SWQ'\n     */\n    clientId: string;\n    /**\n     * Redirect URL that is registered inside the X Developer Portal.\n     * The plugin uses this URL on every platform to receive the authorization code.\n     * @example 'myapp://auth/x'\n     */\n    redirectUrl: string;\n    /**\n     * Default scopes appended to every login request when no custom scopes are provided.\n     * @description Defaults to the minimum required scopes for Log in with X.\n     * @default ['tweet.read','users.read']\n     */\n    defaultScopes?: string[];\n    /**\n     * Force the consent screen to show on every login attempt.\n     * Mirrors X's `force_login=true` flag.\n     * @default false\n     */\n    forceLogin?: boolean;\n    /**\n     * Optional audience value when your application has been approved for multi-tenant access.\n     */\n    audience?: string;\n  };\n  facebook?: {\n    /**\n     * Facebook App ID, provided by Facebook for web, in mobile it's set in the native files\n     * @description For business integrations, use your Business App ID from Facebook Developer Console.\n     * Business apps can access additional permissions like Instagram API, Pages API, and business management features.\n     * @see docs/facebook_business_login.md for business app setup guide\n     */\n    appId: string;\n    /**\n     * Facebook Client Token, provided by Facebook for web, in mobile it's set in the native files\n     */\n    clientToken?: string;\n    /**\n     * Locale\n     * @description The locale to use for the Facebook SDK (e.g., 'en_US', 'fr_FR', 'es_ES')\n     * @default 'en_US'\n     * @example 'fr_FR'\n     */\n    locale?: string;\n  };\n\n  google?: {\n    /**\n     * The app's client ID, found and created in the Google Developers Console.\n     * Required for iOS platform.\n     * @example xxxxxx-xxxxxxxxxxxxxxxxxx.apps.googleusercontent.com\n     * @since 3.1.0\n     */\n    iOSClientId?: string;\n    /**\n     * The app's server client ID, required for offline mode on iOS.\n     * Should be the same value as webClientId.\n     * Found and created in the Google Developers Console.\n     * @example xxxxxx-xxxxxxxxxxxxxxxxxx.apps.googleusercontent.com\n     * @since 3.1.0\n     */\n    iOSServerClientId?: string;\n    /**\n     * The app's web client ID, found and created in the Google Developers Console.\n     * Required for Android and Web platforms.\n     * @example xxxxxx-xxxxxxxxxxxxxxxxxx.apps.googleusercontent.com\n     * @since 3.1.0\n     */\n    webClientId?: string;\n    /**\n     * The login mode, can be online or offline.\n     *\n     * **Online mode (default):**\n     * - Returns user profile data and access tokens\n     * - Supports all methods: login, logout, isLoggedIn, getAuthorizationCode\n     *\n     * **Offline mode:**\n     * - Returns only serverAuthCode for backend authentication\n     * - No user profile data available\n     * - **Limitations:** The following methods are NOT supported in offline mode:\n     *   - `logout()` - Will reject with \"not implemented when using offline mode\"\n     *   - `isLoggedIn()` - Will reject with \"not implemented when using offline mode\"\n     *   - `getAuthorizationCode()` - Will reject with \"not implemented when using offline mode\"\n     *   - `refresh()` - Will reject because offline mode only returns `serverAuthCode`; token refresh must happen on your backend\n     * - Only `login()` method works in offline mode, returning serverAuthCode only\n     * - `serverAuthCode` must be exchanged on your backend for access/refresh tokens\n     * - Requires `iOSServerClientId` to be set on iOS\n     *\n     * @example 'offline'\n     * @default 'online'\n     * @since 3.1.0\n     */\n    mode?: 'online' | 'offline';\n    /**\n     * Filter visible accounts by hosted domain\n     * @description filter visible accounts by hosted domain\n     */\n    hostedDomain?: string;\n    /**\n     * Google Redirect URL, should be your backend url that is configured in your google app\n     */\n    redirectUrl?: string;\n  };\n  apple?: {\n    /**\n     * Apple Client ID, provided by Apple for web and Android\n     */\n    clientId?: string;\n    /**\n     * Apple Redirect URL, should be your backend url that is configured in your apple app\n     *\n     * **Note**: Use empty string `''` for iOS to prevent redirect.\n     * **Note**: Not required when using Broadcast Channel mode on Android.\n     */\n    redirectUrl?: string;\n    /**\n     * Use proper token exchange for Apple Sign-In\n     * @description Controls how Apple Sign-In tokens are handled and what gets returned:\n     *\n     * **When `true` (Recommended for new implementations):**\n     * - Exchanges authorization code for proper access tokens via Apple's token endpoint\n     * - `idToken`: JWT containing user identity information (email, name, user ID)\n     * - `accessToken.token`: Proper access token from Apple (short-lived, ~1 hour)\n     * - `authorizationCode`: Raw authorization code for backend token exchange\n     *\n     * **When `false` (Default - Legacy mode):**\n     * - Uses authorization code directly as access token for backward compatibility\n     * - `idToken`: JWT containing user identity information (email, name, user ID)\n     * - `accessToken.token`: The authorization code itself (not a real access token)\n     * - `authorizationCode`: undefined\n     *\n     * @default false\n     * @example\n     * // Enable proper token exchange (recommended)\n     * useProperTokenExchange: true\n     * // Result: idToken=JWT, accessToken=real_token, authorizationCode=present\n     *\n     * // Legacy mode (backward compatibility)\n     * useProperTokenExchange: false\n     * // Result: idToken=JWT, accessToken=auth_code, authorizationCode=undefined\n     */\n    useProperTokenExchange?: boolean;\n    /**\n     * Use Broadcast Channel for Android Apple Sign-In (Recommended)\n     * @description When enabled, Android uses Broadcast Channel API instead of URL redirects.\n     * This eliminates the need for redirect URL configuration and server-side setup.\n     *\n     * **Benefits:**\n     * - No redirect URL configuration required\n     * - No backend server needed for Android\n     * - Simpler setup and more reliable communication\n     * - Direct client-server communication via Broadcast Channel\n     *\n     * **When `true`:**\n     * - Uses Broadcast Channel for authentication flow\n     * - `redirectUrl` is ignored\n     * - Requires Broadcast Channel compatible backend or direct token handling\n     *\n     * **When `false` (Default - Legacy mode):**\n     * - Uses traditional URL redirect flow\n     * - Requires `redirectUrl` configuration\n     * - Requires backend server for token exchange\n     *\n     * @default false\n     * @since 7.10.0\n     * @example\n     * // Enable Broadcast Channel mode (recommended for new Android implementations)\n     * useBroadcastChannel: true\n     * // Result: Simplified setup, no redirect URL needed\n     *\n     * // Legacy mode (backward compatibility)\n     * useBroadcastChannel: false\n     * // Result: Traditional URL redirect flow with server-side setup\n     */\n    useBroadcastChannel?: boolean;\n  };\n}\n\nexport interface FacebookLoginOptions {\n  /**\n   * Permissions\n   * @description Select permissions to login with. Supports both consumer and business permissions.\n   *\n   * **Consumer Permissions:**\n   * - `email` - User's email address\n   * - `public_profile` - User's public profile info\n   * - `user_friends` - List of friends who also use your app\n   *\n   * **Business Permissions** (require business app configuration and may need App Review):\n   * - `instagram_basic` - Instagram Basic Display API access\n   * - `instagram_manage_insights` - Instagram Insights data\n   * - `instagram_manage_comments` - Manage Instagram comments\n   * - `instagram_content_publish` - Publish to Instagram\n   * - `pages_show_list` - List of Pages managed by user\n   * - `pages_read_engagement` - Read Page engagement metrics\n   * - `pages_manage_posts` - Manage Page posts\n   * - `pages_messaging` - Page messaging features\n   * - `business_management` - Manage business assets\n   * - `catalog_management` - Manage product catalogs\n   * - `ads_management` - Manage advertising accounts\n   *\n   * @example ['email', 'public_profile'] // Consumer permissions\n   * @example ['email', 'instagram_basic', 'pages_show_list'] // Business permissions\n   * @see https://developers.facebook.com/docs/permissions/reference\n   * @see docs/facebook_business_login.md for complete business integration guide\n   */\n  permissions: string[];\n  /**\n   * Is Limited Login\n   * @description use limited login for Facebook iOS only. Important: This is iOS-only and doesn't affect Android.\n   * Even if set to false, Facebook will automatically force it to true if App Tracking Transparency (ATT) permission is not granted.\n   * Developers should always be prepared to handle both limited and full login scenarios.\n   * @default false\n   */\n  limitedLogin?: boolean;\n  /**\n   * Nonce\n   * @description A custom nonce to use for the login request\n   */\n  nonce?: string;\n}\n\nexport interface TwitterLoginOptions {\n  /**\n   * Additional scopes to request during login.\n   * If omitted the plugin falls back to the default scopes configured during initialization.\n   * @example ['tweet.read','users.read','offline.access']\n   */\n  scopes?: string[];\n  /**\n   * Provide a custom OAuth state value.\n   * When not provided the plugin generates a cryptographically random value.\n   */\n  state?: string;\n  /**\n   * Provide a pre-computed PKCE code verifier (mostly used for testing).\n   * When omitted the plugin generates a secure verifier automatically.\n   */\n  codeVerifier?: string;\n  /**\n   * Override the redirect URI for a single login call.\n   * Useful when the same app supports multiple callback URLs per platform.\n   */\n  redirectUrl?: string;\n  /**\n   * Force the consent screen on every attempt, maps to `force_login=true`.\n   */\n  forceLogin?: boolean;\n}\n\nexport interface OAuth2LoginOptions {\n  /**\n   * The provider ID as configured in initialize()\n   * This is required to identify which OAuth2 provider to use\n   * @example 'github', 'azure', 'keycloak'\n   */\n  providerId: string;\n  /**\n   * Override the scopes for this login request\n   * If not provided, uses the scopes from initialization\n   */\n  scope?: string | string[];\n  /**\n   * Alias for `scope` using common naming (`scopes`).\n   * If both are provided, `scope` takes precedence.\n   */\n  scopes?: string[];\n  /**\n   * Custom state parameter for CSRF protection\n   * If not provided, a random value is generated\n   */\n  state?: string;\n  /**\n   * Override PKCE code verifier (for testing purposes)\n   * If not provided, a secure random verifier is generated\n   */\n  codeVerifier?: string;\n  /**\n   * Override redirect URL for this login request\n   */\n  redirectUrl?: string;\n  /**\n   * Additional parameters to add to the authorization URL\n   */\n  additionalParameters?: Record<string, string>;\n  /**\n   * Convenience option for OIDC `login_hint`.\n   * Equivalent to passing `additionalParameters.login_hint`.\n   */\n  loginHint?: string;\n  /**\n   * Convenience option for OAuth/OIDC `prompt`.\n   * Equivalent to passing `additionalParameters.prompt`.\n   */\n  prompt?: string;\n  /**\n   * Web-only (`oauth2` provider only): Use a full-page redirect instead of a popup window.\n   *\n   * When using `redirect`, the promise returned by `login()` will not resolve because the page navigates away.\n   * After the redirect lands back in your app, call `SocialLogin.handleRedirectCallback()` on that page to\n   * parse the result.\n   *\n   * @default 'popup'\n   */\n  flow?: 'popup' | 'redirect';\n}\n\nexport interface OAuth2LoginResponse {\n  /**\n   * The provider ID that was used for this login\n   */\n  providerId: string;\n  /**\n   * The access token received from the OAuth provider\n   */\n  accessToken: AccessToken | null;\n  /**\n   * The ID token (JWT) if provided by the OAuth server (e.g., OpenID Connect)\n   */\n  idToken: string | null;\n  /**\n   * The refresh token if provided (requires appropriate scope like offline_access)\n   */\n  refreshToken: string | null;\n  /**\n   * Resource data fetched from resourceUrl if configured\n   * Contains the raw JSON response from the resource endpoint\n   */\n  resourceData: Record<string, unknown> | null;\n  /**\n   * The scopes that were granted\n   */\n  scope: string[];\n  /**\n   * Token type (usually 'bearer')\n   */\n  tokenType: string;\n  /**\n   * Token expiration time in seconds\n   */\n  expiresIn: number | null;\n}\n\nexport interface GoogleLoginOptions {\n  /**\n   * Specifies the scopes required for accessing Google APIs\n   * The default is defined in the configuration.\n   * @example [\"profile\", \"email\"]\n   * @see [Google OAuth2 Scopes](https://developers.google.com/identity/protocols/oauth2/scopes)\n   */\n  scopes?: string[];\n  /**\n   * Nonce\n   * @description nonce\n   */\n  nonce?: string;\n  /**\n   * Force refresh token (only for Android)\n   * @description force refresh token\n   * @default false\n   * @note On Android, the OS caches access tokens, and if a token is invalid (e.g., user revoked app access), the plugin might return an invalid accessToken. Using getAuthorizationCode() is recommended to ensure the token is valid.\n   */\n  forceRefreshToken?: boolean;\n  /**\n   * Force account selection prompt (iOS)\n   * @description forces the account selection prompt to appear on iOS\n   * @default false\n   */\n  forcePrompt?: boolean;\n  /**\n   * Style\n   * @description style\n   * @default 'standard'\n   */\n  style?: 'bottom' | 'standard';\n  /**\n   * Filter by authorized accounts (Android only)\n   * @description Only show accounts that have previously been used to sign in to the app.\n   * This option is only available for the 'bottom' style.\n   * Note: For Family Link supervised accounts, this should be set to false.\n   * @default true\n   */\n  filterByAuthorizedAccounts?: boolean;\n  /**\n   * Auto select enabled (Android only)\n   * @description Automatically select the account if only one Google account is available.\n   * This option is only available for the 'bottom' style.\n   * @default false\n   */\n  autoSelectEnabled?: boolean;\n  /**\n   * Prompt parameter for Google OAuth (Web only)\n   * @description A space-delimited, case-sensitive list of prompts to present the user.\n   * If you don't specify this parameter, the user will be prompted only the first time your project requests access.\n   *\n   * **Possible values:**\n   * - `none`: Don't display any authentication or consent screens. Must not be specified with other values.\n   * - `consent`: Prompt the user for consent.\n   * - `select_account`: Prompt the user to select an account.\n   *\n   * **Examples:**\n   * - `prompt: 'consent'` - Always show consent screen\n   * - `prompt: 'select_account'` - Always show account selection\n   * - `prompt: 'consent select_account'` - Show both consent and account selection\n   *\n   * **Note:** This parameter only affects web platform behavior. Mobile platforms use their own native prompts.\n   *\n   * @example 'consent'\n   * @example 'select_account'\n   * @example 'consent select_account'\n   * @see [Google OAuth2 Prompt Parameter](https://developers.google.com/identity/protocols/oauth2/openid-connect#prompt)\n   * @since 7.12.0\n   */\n  prompt?: 'none' | 'consent' | 'select_account' | 'consent select_account' | 'select_account consent';\n}\n\nexport interface GoogleLoginResponseOnline {\n  accessToken: AccessToken | null;\n  idToken: string | null;\n  profile: {\n    email: string | null;\n    familyName: string | null;\n    givenName: string | null;\n    id: string | null;\n    name: string | null;\n    imageUrl: string | null;\n  };\n  responseType: 'online';\n}\n\nexport interface GoogleLoginResponseOffline {\n  serverAuthCode: string;\n  responseType: 'offline';\n}\n\nexport type GoogleLoginResponse = GoogleLoginResponseOnline | GoogleLoginResponseOffline;\n\nexport interface AppleProviderOptions {\n  /**\n   * Scopes\n   * @description An array of scopes to request during login\n   * @example [\"name\", \"email\"]\n   * default: [\"name\", \"email\"]\n   */\n  scopes?: string[];\n  /**\n   * Nonce\n   * @description nonce\n   */\n  nonce?: string;\n  /**\n   * State\n   * @description state\n   */\n  state?: string;\n  /**\n   * Use Broadcast Channel for authentication flow\n   * @description When enabled, uses Broadcast Channel API for communication instead of URL redirects.\n   * Only applicable on platforms that support Broadcast Channel (Android).\n   * @default false\n   */\n  useBroadcastChannel?: boolean;\n}\n\nexport interface AppleProviderResponse {\n  /**\n   * Access token from Apple\n   * @description Content depends on `useProperTokenExchange` setting:\n   * - When `useProperTokenExchange: true`: Real access token from Apple (~1 hour validity)\n   * - When `useProperTokenExchange: false`: Contains authorization code as token (legacy mode)\n   * Use `idToken` for user authentication, `accessToken` for API calls when properly exchanged.\n   */\n  accessToken: AccessToken | null;\n\n  /**\n   * Identity token (JWT) from Apple\n   * @description Always contains the JWT with user identity information including:\n   * - User ID (sub claim)\n   * - Email (if user granted permission)\n   * - Name components (if user granted permission)\n   * - Email verification status\n   * This is the primary token for user authentication and should be verified on your backend.\n   */\n  idToken: string | null;\n\n  /**\n   * User profile information\n   * @description Basic user profile data extracted from the identity token and Apple response:\n   * - `user`: Apple's user identifier (sub claim from idToken)\n   * - `email`: User's email address (if permission granted)\n   * - `givenName`: User's first name (if permission granted)\n   * - `familyName`: User's last name (if permission granted)\n   */\n  profile: {\n    user: string;\n    email: string | null;\n    givenName: string | null;\n    familyName: string | null;\n  };\n\n  /**\n   * Authorization code for proper token exchange (when useProperTokenExchange is enabled)\n   * @description Only present when `useProperTokenExchange` is `true`. This code should be exchanged\n   * for proper access tokens on your backend using Apple's token endpoint. Use this for secure\n   * server-side token validation and to obtain refresh tokens.\n   * @see https://developer.apple.com/documentation/sign_in_with_apple/tokenresponse\n   */\n  authorizationCode?: string;\n}\n\nexport type LoginOptions =\n  | {\n      provider: 'facebook';\n      options: FacebookLoginOptions;\n    }\n  | {\n      provider: 'google';\n      options: GoogleLoginOptions;\n    }\n  | {\n      provider: 'apple';\n      options: AppleProviderOptions;\n    }\n  | {\n      provider: 'twitter';\n      options: TwitterLoginOptions;\n    }\n  | {\n      provider: 'oauth2';\n      options: OAuth2LoginOptions;\n    };\n\nexport type LoginResult =\n  | {\n      provider: 'facebook';\n      result: FacebookLoginResponse;\n    }\n  | {\n      provider: 'google';\n      result: GoogleLoginResponse;\n    }\n  | {\n      provider: 'apple';\n      result: AppleProviderResponse;\n    }\n  | {\n      provider: 'twitter';\n      result: TwitterLoginResponse;\n    }\n  | {\n      provider: 'oauth2';\n      result: OAuth2LoginResponse;\n    };\n\nexport interface AccessToken {\n  applicationId?: string;\n  declinedPermissions?: string[];\n  expires?: string;\n  isExpired?: boolean;\n  lastRefresh?: string;\n  permissions?: string[];\n  token: string;\n  tokenType?: string;\n  refreshToken?: string;\n  userId?: string;\n}\n\nexport interface FacebookLoginResponse {\n  accessToken: AccessToken | null;\n  /**\n   * Whether Facebook Limited Login was used for this session.\n   * When `true`, `accessToken` is not valid for Graph API calls (Facebook error 190).\n   * Validate `idToken` on your backend instead, or call `facebook#requestTracking` and log in again after ATT is granted.\n   * @since 8.4.0\n   */\n  isLimitedLogin?: boolean;\n  idToken: string | null;\n  profile: {\n    userID: string;\n    email: string | null;\n    friendIDs: string[];\n    birthday: string | null;\n    ageRange: { min?: number; max?: number } | null;\n    gender: string | null;\n    location: { id: string; name: string } | null;\n    hometown: { id: string; name: string } | null;\n    profileURL: string | null;\n    name: string | null;\n    imageURL: string | null;\n  };\n}\n\nexport interface TwitterProfile {\n  id: string;\n  username: string;\n  name: string | null;\n  profileImageUrl: string | null;\n  verified: boolean;\n  email?: string | null;\n}\n\nexport interface TwitterLoginResponse {\n  accessToken: AccessToken | null;\n  refreshToken?: string | null;\n  scope: string[];\n  tokenType: 'bearer';\n  expiresIn?: number | null;\n  profile: TwitterProfile;\n}\n\nexport interface AuthorizationCode {\n  /**\n   * Jwt\n   * @description A JSON web token\n   */\n  jwt?: string;\n  /**\n   * Access Token\n   * @description An access token\n   */\n  accessToken?: string;\n}\n\nexport interface AuthorizationCodeOptions {\n  /**\n   * Provider\n   * @description Provider for the authorization code\n   */\n  provider: 'apple' | 'google' | 'facebook' | 'twitter' | 'oauth2';\n  /**\n   * Provider ID for OAuth2 providers (required when provider is 'oauth2')\n   * @description The ID used when configuring the OAuth2 provider in initialize()\n   */\n  providerId?: string;\n}\n\nexport interface isLoggedInOptions {\n  /**\n   * Provider\n   * @description Provider for the isLoggedIn\n   */\n  provider: 'apple' | 'google' | 'facebook' | 'twitter' | 'oauth2';\n  /**\n   * Provider ID for OAuth2 providers (required when provider is 'oauth2')\n   * @description The ID used when configuring the OAuth2 provider in initialize()\n   */\n  providerId?: string;\n}\n\n// Define the provider-specific call types\nexport type ProviderSpecificCall = 'facebook#getProfile' | 'facebook#requestTracking';\n\n// Define the options and response types for each specific call\nexport interface FacebookGetProfileOptions {\n  /**\n   * Fields to retrieve from Facebook profile\n   * @example [\"id\", \"name\", \"email\", \"picture\"]\n   */\n  fields?: string[];\n}\n\nexport interface FacebookGetProfileResponse {\n  /**\n   * Facebook profile data\n   */\n  profile: {\n    id: string | null;\n    name: string | null;\n    email: string | null;\n    first_name: string | null;\n    last_name: string | null;\n    picture?: {\n      data: {\n        height: number | null;\n        is_silhouette: boolean | null;\n        url: string | null;\n        width: number | null;\n      };\n    } | null;\n    [key: string]: any; // For additional fields that might be requested\n  };\n}\n\nexport interface OpenSecureWindowOptions {\n  /**\n   * The endpoint to open\n   */\n  authEndpoint: string;\n  /**\n   * The redirect URI to use for the openSecureWindow call.\n   * This will be checked to make sure it matches the redirect URI after the window finishes the redirection.\n   */\n  redirectUri: string;\n  /**\n   * The name of the broadcast channel to listen to, relevant only for web\n   */\n  broadcastChannelName?: string;\n}\n\nexport interface OpenSecureWindowResponse {\n  /**\n   * The result of the openSecureWindow call\n   */\n  redirectedUri: string;\n}\n\nexport type FacebookRequestTrackingOptions = Record<string, never>;\n\nexport interface FacebookRequestTrackingResponse {\n  /**\n   * App tracking authorization status\n   */\n  status: 'authorized' | 'denied' | 'notDetermined' | 'restricted';\n}\n\n// Map call strings to their options and response types\nexport type ProviderSpecificCallOptionsMap = {\n  'facebook#getProfile': FacebookGetProfileOptions;\n  'facebook#requestTracking': FacebookRequestTrackingOptions;\n};\n\nexport type ProviderSpecificCallResponseMap = {\n  'facebook#getProfile': FacebookGetProfileResponse;\n  'facebook#requestTracking': FacebookRequestTrackingResponse;\n};\n\n// Add a helper type to map providers to their response types\nexport type ProviderResponseMap = {\n  facebook: FacebookLoginResponse;\n  google: GoogleLoginResponse;\n  apple: AppleProviderResponse;\n  twitter: TwitterLoginResponse;\n  oauth2: OAuth2LoginResponse;\n};\n\n/**\n * Error codes returned by the plugin.\n * @since 8.3.x\n */\nexport type SocialLoginErrorCode = 'USER_CANCELLED';\n\n/**\n * Errors thrown by SocialLogin methods.\n *\n * When a user dismisses or cancels the provider UI (popup closed, system dialog cancelled, access denied, etc.),\n * the plugin rejects with `code === 'USER_CANCELLED'` so the caller can distinguish user intent from real failures.\n * Other errors may omit the code or use provider-specific values.\n */\nexport interface SocialLoginError extends Error {\n  code?: SocialLoginErrorCode | string;\n}\n\nexport interface SocialLoginPlugin {\n  /**\n   * Initialize the plugin\n   * @description initialize the plugin with the required options\n   */\n  initialize(options: InitializeOptions): Promise<void>;\n  /**\n   * Login with the selected provider\n   * @description login with the selected provider\n   *\n   * On user dismissal/cancellation, the Promise is rejected with `code === 'USER_CANCELLED'` (see `SocialLoginError`).\n   */\n  login<T extends LoginOptions['provider']>(\n    options: Extract<LoginOptions, { provider: T }>,\n  ): Promise<{ provider: T; result: ProviderResponseMap[T] }>;\n  /**\n   * Logout\n   * @description Logout the user from the specified provider\n   *\n   * **Google Offline Mode Limitation:**\n   * This method is NOT supported when Google is initialized with `mode: 'offline'`.\n   * It will reject with error: \"logout is not implemented when using offline mode\"\n   *\n   * @throws Error if Google provider is in offline mode\n   */\n  logout(options: {\n    provider: 'apple' | 'google' | 'facebook' | 'twitter' | 'oauth2';\n    providerId?: string;\n  }): Promise<void>;\n  /**\n   * IsLoggedIn\n   * @description Check if the user is currently logged in with the specified provider\n   *\n   * **Google Offline Mode Limitation:**\n   * This method is NOT supported when Google is initialized with `mode: 'offline'`.\n   * It will reject with error: \"isLoggedIn is not implemented when using offline mode\"\n   *\n   * @throws Error if Google provider is in offline mode\n   */\n  isLoggedIn(options: isLoggedInOptions): Promise<{ isLoggedIn: boolean }>;\n\n  /**\n   * Get the current authorization code\n   * @description Get the authorization code for server-side authentication\n   *\n   * **Google Offline Mode Limitation:**\n   * This method is NOT supported when Google is initialized with `mode: 'offline'`.\n   * It will reject with error: \"getAuthorizationCode is not implemented when using offline mode\"\n   *\n   * In offline mode, the authorization code (serverAuthCode) is already returned by the `login()` method.\n   *\n   * @throws Error if Google provider is in offline mode\n   */\n  getAuthorizationCode(options: AuthorizationCodeOptions): Promise<AuthorizationCode>;\n  /**\n   * Refresh the access token\n   * @description refresh the access token\n   *\n   * **Google Offline Mode Limitation:**\n   * This method is NOT supported when Google is initialized with `mode: 'offline'`.\n   * Offline mode only returns `serverAuthCode` for backend token exchange, so token refresh must happen on your backend.\n   * The plugin logs and rejects with a message explaining that you should send `serverAuthCode` to your backend,\n   * refresh the Google tokens there, or switch to `mode: 'online'` for client-side refresh.\n   *\n   * **Google Web Limitation:**\n   * On Web, Google `refresh()` is not implemented, even when using `mode: 'online'`.\n   * Call `login()` again on Web to obtain a fresh token instead.\n   *\n   * @throws Error if Google provider is in offline mode, or on Web where Google `refresh()` is not implemented\n   */\n  refresh(options: LoginOptions): Promise<void>;\n\n  /**\n   * OAuth2 refresh-token helper (feature parity with Capawesome OAuth).\n   *\n   * Scope:\n   * - Only applies to the built-in `oauth2` provider (not Google/Apple/Facebook/Twitter).\n   * - Requires a token endpoint (either `accessTokenEndpoint`/`tokenEndpoint` or `issuerUrl` discovery).\n   *\n   * Security note:\n   * - This does not validate JWT signatures. It only exchanges/refreshes tokens.\n   *\n   * If `refreshToken` is omitted, the plugin will attempt to use the stored refresh token (if available).\n   */\n  refreshToken(options: {\n    provider: 'oauth2';\n    providerId: string;\n    refreshToken?: string;\n    additionalParameters?: Record<string, string>;\n  }): Promise<OAuth2LoginResponse>;\n\n  /**\n   * Web-only: handle the OAuth redirect callback and return the parsed result.\n   *\n   * Notes:\n   * - This is only meaningful on Web. iOS/Android implementations will reject.\n   * - Intended for redirect-based flows (e.g. `oauth2` with `flow: 'redirect'`) where the page navigates away.\n   */\n  handleRedirectCallback(): Promise<LoginResult | null>;\n\n  /**\n   * Decode a JWT (typically an OIDC ID token) into its claims.\n   *\n   * Notes:\n   * - Accepts both `idToken` and `token` to match common naming (Capawesome uses `token`).\n   * - This does not validate the signature or issuer/audience. It only base64url-decodes the payload.\n   */\n  decodeIdToken(options: { idToken?: string; token?: string }): Promise<{ claims: Record<string, any> }>;\n\n  /**\n   * Convert an access token expiration timestamp (milliseconds since epoch) to an ISO date string.\n   *\n   * This is a pure helper (feature parity with Capawesome OAuth) and does not depend on provider state.\n   */\n  getAccessTokenExpirationDate(options: {\n    /**\n     * Access token expiration date in milliseconds since epoch.\n     * Typically: `Date.now() + expiresInSeconds * 1000`.\n     */\n    accessTokenExpirationDate: number;\n  }): Promise<{ date: string }>;\n\n  /**\n   * Check if an access token is available (non-empty).\n   *\n   * This is a pure helper (feature parity with Capawesome OAuth) and does not depend on provider state.\n   */\n  isAccessTokenAvailable(options: { accessToken: string | null }): Promise<{ isAvailable: boolean }>;\n\n  /**\n   * Check if an access token is expired.\n   *\n   * This is a pure helper (feature parity with Capawesome OAuth) and does not depend on provider state.\n   */\n  isAccessTokenExpired(options: { accessTokenExpirationDate: number }): Promise<{ isExpired: boolean }>;\n\n  /**\n   * Check if a refresh token is available (non-empty).\n   *\n   * This is a pure helper (feature parity with Capawesome OAuth) and does not depend on provider state.\n   */\n  isRefreshTokenAvailable(options: { refreshToken: string | null }): Promise<{ isAvailable: boolean }>;\n\n  /**\n   * Execute provider-specific calls\n   * @description Execute a provider-specific functionality\n   */\n  providerSpecificCall<T extends ProviderSpecificCall>(options: {\n    call: T;\n    options: ProviderSpecificCallOptionsMap[T];\n  }): Promise<ProviderSpecificCallResponseMap[T]>;\n\n  /**\n   * Get the native Capacitor plugin version\n   *\n   * @returns {Promise<{ id: string }>} an Promise with version for this device\n   * @throws An error if the something went wrong\n   */\n  getPluginVersion(): Promise<{ version: string }>;\n\n  /**\n   * Opens a secured window for OAuth2 authentication.\n   * For web, you should have the code in the redirected page to use a broadcast channel to send the redirected url to the app\n   * Something like:\n   * ```html\n   * <html>\n   * <head></head>\n   * <body>\n   * <script>\n   *   const searchParams = new URLSearchParams(location.search)\n   *   if (searchParams.has(\"code\")) {\n   *     new BroadcastChannel(\"my-channel-name\").postMessage(location.href);\n   *     window.close();\n   *   }\n   * </script>\n   * </body>\n   * </html>\n   * ```\n   * For mobile, you should have a redirect uri that opens the app, something like: `myapp://oauth_callback/`\n   * And make sure to register it in the app's info.plist:\n   * ```xml\n   * <key>CFBundleURLTypes</key>\n   * <array>\n   *    <dict>\n   *       <key>CFBundleURLSchemes</key>\n   *       <array>\n   *          <string>myapp</string>\n   *       </array>\n   *    </dict>\n   * </array>\n   * ```\n   * And in the AndroidManifest.xml file:\n   * ```xml\n   * <activity>\n   *    <intent-filter>\n   *       <action android:name=\"android.intent.action.VIEW\" />\n   *       <category android:name=\"android.intent.category.DEFAULT\" />\n   *       <category android:name=\"android.intent.category.BROWSABLE\" />\n   *       <data android:host=\"oauth_callback\" android:scheme=\"myapp\" />\n   *    </intent-filter>\n   * </activity>\n   * ```\n   * @param options - the options for the openSecureWindow call\n   */\n  openSecureWindow(options: OpenSecureWindowOptions): Promise<OpenSecureWindowResponse>;\n}\n"]}
+{"version":3,"file":"definitions.js","sourceRoot":"","sources":["../../src/definitions.ts"],"names":[],"mappings":"","sourcesContent":["/**\n * Configuration for a single OAuth2 provider instance\n */\nexport interface OAuth2ProviderConfig {\n  /**\n   * The OAuth 2.0 client identifier (App ID / Client ID).\n   *\n   * Note: this configuration object is only used by the plugin's built-in `oauth2` provider\n   * (i.e. `SocialLogin.initialize({ oauth2: { ... } })`). It does not affect Google/Apple/Facebook/Twitter.\n   * @example 'your-client-id'\n   */\n  appId?: string;\n  /**\n   * Alias for `appId` to match common OAuth/OIDC naming (`clientId`).\n   * If both are provided, `appId` takes precedence.\n   * @example 'your-client-id'\n   */\n  clientId?: string;\n  /**\n   * OpenID Connect issuer URL (enables discovery via `/.well-known/openid-configuration`).\n   * When set, you may omit explicit endpoints like `authorizationBaseUrl` and `accessTokenEndpoint`.\n   *\n   * Notes:\n   * - Explicit endpoints (authorization/token/logout) take precedence over discovered values.\n   * - Discovery is supported for `oauth2` on Web, iOS, and Android.\n   *\n   * @example 'https://accounts.example.com'\n   */\n  issuerUrl?: string;\n  /**\n   * The base URL of the authorization endpoint\n   * @example 'https://accounts.example.com/oauth2/authorize'\n   */\n  authorizationBaseUrl?: string;\n  /**\n   * Alias for `authorizationBaseUrl` (to match common OAuth/OIDC naming).\n   * @example 'https://accounts.example.com/oauth2/authorize'\n   */\n  authorizationEndpoint?: string;\n  /**\n   * OAuth 2.0 client secret for token requests (e.g., when exchanging the code).\n   * This value is sent as `client_secret` in token/refresh requests when provided.\n   */\n  clientSecret?: string;\n  /**\n   * The URL to exchange the authorization code for tokens\n   * Required for authorization code flow\n   * @example 'https://accounts.example.com/oauth2/token'\n   */\n  accessTokenEndpoint?: string;\n  /**\n   * Alias for `accessTokenEndpoint` (to match common OAuth/OIDC naming).\n   * @example 'https://accounts.example.com/oauth2/token'\n   */\n  tokenEndpoint?: string;\n  /**\n   * Redirect URL that receives the OAuth callback\n   * @example 'myapp://oauth/callback'\n   */\n  redirectUrl: string;\n  /**\n   * Optional URL to fetch user profile/resource data after authentication\n   * The access token will be sent as Bearer token in the Authorization header\n   * @example 'https://api.example.com/userinfo'\n   */\n  resourceUrl?: string;\n  /**\n   * The OAuth response type\n   * - 'code': Authorization Code flow (recommended, requires accessTokenEndpoint)\n   * - 'token': Implicit flow (less secure, tokens returned directly)\n   * @default 'code'\n   */\n  responseType?: 'code' | 'token';\n  /**\n   * Enable PKCE (Proof Key for Code Exchange)\n   * Strongly recommended for public clients (mobile/web apps)\n   * @default true\n   */\n  pkceEnabled?: boolean;\n  /**\n   * Default scopes to request during authorization\n   * @example 'openid profile email'\n   * @example ['openid','profile','email']\n   */\n  scope?: string | string[];\n  /**\n   * Alias for `scope` using common naming (`scopes`).\n   * If both are provided, `scope` takes precedence.\n   */\n  scopes?: string[];\n  /**\n   * Additional parameters to include in the authorization request\n   * @example { prompt: 'consent', login_hint: 'user@example.com' }\n   */\n  additionalParameters?: Record<string, string>;\n  /**\n   * Convenience option for OIDC `login_hint`.\n   * Equivalent to passing `additionalParameters.login_hint`.\n   */\n  loginHint?: string;\n  /**\n   * Convenience option for OAuth/OIDC `prompt`.\n   * Equivalent to passing `additionalParameters.prompt`.\n   */\n  prompt?: string;\n  /**\n   * Additional parameters to include in token requests (code exchange / refresh).\n   * Useful for providers that require non-standard parameters.\n   */\n  additionalTokenParameters?: Record<string, string>;\n  /**\n   * Additional headers to include when fetching the resource URL\n   * @example { 'X-Custom-Header': 'value' }\n   */\n  additionalResourceHeaders?: Record<string, string>;\n  /**\n   * Custom logout URL for ending the session\n   * @example 'https://accounts.example.com/logout'\n   */\n  logoutUrl?: string;\n  /**\n   * Alias for `logoutUrl` to match OIDC naming (`endSessionEndpoint`).\n   * @example 'https://accounts.example.com/logout'\n   */\n  endSessionEndpoint?: string;\n  /**\n   * OIDC post logout redirect URL (sent as `post_logout_redirect_uri` when building the end-session URL).\n   * @example 'myapp://logout/callback'\n   */\n  postLogoutRedirectUrl?: string;\n  /**\n   * Additional parameters to include in logout / end-session URL.\n   */\n  additionalLogoutParameters?: Record<string, string>;\n  /**\n   * iOS-only: Whether to prefer an ephemeral browser session for ASWebAuthenticationSession.\n   * Defaults to true to match existing behavior in this plugin.\n   */\n  iosPrefersEphemeralWebBrowserSession?: boolean;\n  /**\n   * Alias for `iosPrefersEphemeralWebBrowserSession` (to match Capawesome OAuth naming).\n   */\n  iosPrefersEphemeralSession?: boolean;\n  /**\n   * Enable debug logging\n   * @default false\n   */\n  logsEnabled?: boolean;\n}\n\nexport interface InitializeOptions {\n  /**\n   * OAuth2 provider configurations.\n   * Supports multiple providers by using a Record with provider IDs as keys.\n   * @example\n   * {\n   *   github: { appId: '...', authorizationBaseUrl: 'https://github.com/login/oauth/authorize', ... },\n   *   azure: { appId: '...', authorizationBaseUrl: 'https://login.microsoftonline.com/.../oauth2/v2.0/authorize', ... }\n   * }\n   */\n  oauth2?: Record<string, OAuth2ProviderConfig>;\n  twitter?: {\n    /**\n     * The OAuth 2.0 client identifier issued by X (Twitter) Developer Portal\n     * @example 'Y2xpZW50SWQ'\n     */\n    clientId: string;\n    /**\n     * Redirect URL that is registered inside the X Developer Portal.\n     * The plugin uses this URL on every platform to receive the authorization code.\n     * @example 'myapp://auth/x'\n     */\n    redirectUrl: string;\n    /**\n     * Default scopes appended to every login request when no custom scopes are provided.\n     * @description Defaults to the minimum required scopes for Log in with X.\n     * @default ['tweet.read','users.read']\n     */\n    defaultScopes?: string[];\n    /**\n     * Force the consent screen to show on every login attempt.\n     * Mirrors X's `force_login=true` flag.\n     * @default false\n     */\n    forceLogin?: boolean;\n    /**\n     * Optional audience value when your application has been approved for multi-tenant access.\n     */\n    audience?: string;\n  };\n  facebook?: {\n    /**\n     * Facebook App ID, provided by Facebook for web, in mobile it's set in the native files\n     * @description For business integrations, use your Business App ID from Facebook Developer Console.\n     * Business apps can access additional permissions like Instagram API, Pages API, and business management features.\n     * @see docs/facebook_business_login.md for business app setup guide\n     */\n    appId: string;\n    /**\n     * Facebook Client Token, provided by Facebook for web, in mobile it's set in the native files\n     */\n    clientToken?: string;\n    /**\n     * Locale\n     * @description The locale to use for the Facebook SDK (e.g., 'en_US', 'fr_FR', 'es_ES')\n     * @default 'en_US'\n     * @example 'fr_FR'\n     */\n    locale?: string;\n  };\n\n  google?: {\n    /**\n     * The app's client ID, found and created in the Google Developers Console.\n     * Required for iOS platform.\n     * @example xxxxxx-xxxxxxxxxxxxxxxxxx.apps.googleusercontent.com\n     * @since 3.1.0\n     */\n    iOSClientId?: string;\n    /**\n     * The app's server client ID, required for offline mode on iOS.\n     * Should be the same value as webClientId.\n     * Found and created in the Google Developers Console.\n     * @example xxxxxx-xxxxxxxxxxxxxxxxxx.apps.googleusercontent.com\n     * @since 3.1.0\n     */\n    iOSServerClientId?: string;\n    /**\n     * The app's web client ID, found and created in the Google Developers Console.\n     * Required for Android and Web platforms.\n     * @example xxxxxx-xxxxxxxxxxxxxxxxxx.apps.googleusercontent.com\n     * @since 3.1.0\n     */\n    webClientId?: string;\n    /**\n     * The login mode, can be online or offline.\n     *\n     * **Online mode (default):**\n     * - Returns user profile data and access tokens\n     * - Supports all methods: login, logout, isLoggedIn, getAuthorizationCode\n     *\n     * **Offline mode:**\n     * - Returns only serverAuthCode for backend authentication\n     * - No user profile data available\n     * - **Limitations:** The following methods are NOT supported in offline mode:\n     *   - `logout()` - Will reject with \"not implemented when using offline mode\"\n     *   - `isLoggedIn()` - Will reject with \"not implemented when using offline mode\"\n     *   - `getAuthorizationCode()` - Will reject with \"not implemented when using offline mode\"\n     *   - `refresh()` - Will reject because offline mode only returns `serverAuthCode`; token refresh must happen on your backend\n     * - Only `login()` method works in offline mode, returning serverAuthCode only\n     * - `serverAuthCode` must be exchanged on your backend for access/refresh tokens\n     * - Requires `iOSServerClientId` to be set on iOS\n     *\n     * @example 'offline'\n     * @default 'online'\n     * @since 3.1.0\n     */\n    mode?: 'online' | 'offline';\n    /**\n     * Filter visible accounts by hosted domain\n     * @description filter visible accounts by hosted domain\n     */\n    hostedDomain?: string;\n    /**\n     * Google Redirect URL, should be your backend url that is configured in your google app\n     */\n    redirectUrl?: string;\n  };\n  apple?: {\n    /**\n     * Apple Client ID, provided by Apple for web and Android\n     */\n    clientId?: string;\n    /**\n     * Apple Redirect URL, should be your backend url that is configured in your apple app\n     *\n     * **Note**: Use empty string `''` for iOS to prevent redirect.\n     * **Note**: Not required when using Broadcast Channel mode on Android.\n     */\n    redirectUrl?: string;\n    /**\n     * Use proper token exchange for Apple Sign-In\n     * @description Controls how Apple Sign-In tokens are handled and what gets returned:\n     *\n     * **When `true` (Recommended for new implementations):**\n     * - Exchanges authorization code for proper access tokens via Apple's token endpoint\n     * - `idToken`: JWT containing user identity information (email, name, user ID)\n     * - `accessToken.token`: Proper access token from Apple (short-lived, ~1 hour)\n     * - `authorizationCode`: Raw authorization code for backend token exchange\n     *\n     * **When `false` (Default - Legacy mode):**\n     * - Uses authorization code directly as access token for backward compatibility\n     * - `idToken`: JWT containing user identity information (email, name, user ID)\n     * - `accessToken.token`: The authorization code itself (not a real access token)\n     * - `authorizationCode`: undefined\n     *\n     * @default false\n     * @example\n     * // Enable proper token exchange (recommended)\n     * useProperTokenExchange: true\n     * // Result: idToken=JWT, accessToken=real_token, authorizationCode=present\n     *\n     * // Legacy mode (backward compatibility)\n     * useProperTokenExchange: false\n     * // Result: idToken=JWT, accessToken=auth_code, authorizationCode=undefined\n     */\n    useProperTokenExchange?: boolean;\n    /**\n     * Use Broadcast Channel for Android Apple Sign-In (Recommended)\n     * @description When enabled, Android uses Broadcast Channel API instead of URL redirects.\n     * This eliminates the need for redirect URL configuration and server-side setup.\n     *\n     * **Benefits:**\n     * - No redirect URL configuration required\n     * - No backend server needed for Android\n     * - Simpler setup and more reliable communication\n     * - Direct client-server communication via Broadcast Channel\n     *\n     * **When `true`:**\n     * - Uses Broadcast Channel for authentication flow\n     * - `redirectUrl` is ignored\n     * - Requires Broadcast Channel compatible backend or direct token handling\n     *\n     * **When `false` (Default - Legacy mode):**\n     * - Uses traditional URL redirect flow\n     * - Requires `redirectUrl` configuration\n     * - Requires backend server for token exchange\n     *\n     * @default false\n     * @since 7.10.0\n     * @example\n     * // Enable Broadcast Channel mode (recommended for new Android implementations)\n     * useBroadcastChannel: true\n     * // Result: Simplified setup, no redirect URL needed\n     *\n     * // Legacy mode (backward compatibility)\n     * useBroadcastChannel: false\n     * // Result: Traditional URL redirect flow with server-side setup\n     */\n    useBroadcastChannel?: boolean;\n  };\n}\n\nexport interface FacebookLoginOptions {\n  /**\n   * Permissions\n   * @description Select permissions to login with. Supports both consumer and business permissions.\n   *\n   * **Consumer Permissions:**\n   * - `email` - User's email address\n   * - `public_profile` - User's public profile info\n   * - `user_friends` - List of friends who also use your app\n   *\n   * **Business Permissions** (require business app configuration and may need App Review):\n   * - `instagram_basic` - Instagram Basic Display API access\n   * - `instagram_manage_insights` - Instagram Insights data\n   * - `instagram_manage_comments` - Manage Instagram comments\n   * - `instagram_content_publish` - Publish to Instagram\n   * - `pages_show_list` - List of Pages managed by user\n   * - `pages_read_engagement` - Read Page engagement metrics\n   * - `pages_manage_posts` - Manage Page posts\n   * - `pages_messaging` - Page messaging features\n   * - `business_management` - Manage business assets\n   * - `catalog_management` - Manage product catalogs\n   * - `ads_management` - Manage advertising accounts\n   *\n   * @example ['email', 'public_profile'] // Consumer permissions\n   * @example ['email', 'instagram_basic', 'pages_show_list'] // Business permissions\n   * @see https://developers.facebook.com/docs/permissions/reference\n   * @see docs/facebook_business_login.md for complete business integration guide\n   */\n  permissions: string[];\n  /**\n   * Is Limited Login\n   * @description use limited login for Facebook iOS only. Important: This is iOS-only and doesn't affect Android.\n   * Even if set to false, Facebook will automatically force it to true if App Tracking Transparency (ATT) permission is not granted.\n   * Developers should always be prepared to handle both limited and full login scenarios.\n   * @default false\n   */\n  limitedLogin?: boolean;\n  /**\n   * Nonce\n   * @description A custom nonce to use for the login request\n   */\n  nonce?: string;\n}\n\nexport interface TwitterLoginOptions {\n  /**\n   * Additional scopes to request during login.\n   * If omitted the plugin falls back to the default scopes configured during initialization.\n   * @example ['tweet.read','users.read','offline.access']\n   */\n  scopes?: string[];\n  /**\n   * Provide a custom OAuth state value.\n   * When not provided the plugin generates a cryptographically random value.\n   */\n  state?: string;\n  /**\n   * Provide a pre-computed PKCE code verifier (mostly used for testing).\n   * When omitted the plugin generates a secure verifier automatically.\n   */\n  codeVerifier?: string;\n  /**\n   * Override the redirect URI for a single login call.\n   * Useful when the same app supports multiple callback URLs per platform.\n   */\n  redirectUrl?: string;\n  /**\n   * Force the consent screen on every attempt, maps to `force_login=true`.\n   */\n  forceLogin?: boolean;\n}\n\nexport interface OAuth2LoginOptions {\n  /**\n   * The provider ID as configured in initialize()\n   * This is required to identify which OAuth2 provider to use\n   * @example 'github', 'azure', 'keycloak'\n   */\n  providerId: string;\n  /**\n   * Override the scopes for this login request\n   * If not provided, uses the scopes from initialization\n   */\n  scope?: string | string[];\n  /**\n   * Alias for `scope` using common naming (`scopes`).\n   * If both are provided, `scope` takes precedence.\n   */\n  scopes?: string[];\n  /**\n   * Custom state parameter for CSRF protection\n   * If not provided, a random value is generated\n   */\n  state?: string;\n  /**\n   * Override PKCE code verifier (for testing purposes)\n   * If not provided, a secure random verifier is generated\n   */\n  codeVerifier?: string;\n  /**\n   * Override redirect URL for this login request\n   */\n  redirectUrl?: string;\n  /**\n   * Additional parameters to add to the authorization URL\n   */\n  additionalParameters?: Record<string, string>;\n  /**\n   * Convenience option for OIDC `login_hint`.\n   * Equivalent to passing `additionalParameters.login_hint`.\n   */\n  loginHint?: string;\n  /**\n   * Convenience option for OAuth/OIDC `prompt`.\n   * Equivalent to passing `additionalParameters.prompt`.\n   */\n  prompt?: string;\n  /**\n   * Web-only (`oauth2` provider only): Use a full-page redirect instead of a popup window.\n   *\n   * When using `redirect`, the promise returned by `login()` will not resolve because the page navigates away.\n   * After the redirect lands back in your app, call `SocialLogin.handleRedirectCallback()` on that page to\n   * parse the result.\n   *\n   * @default 'popup'\n   */\n  flow?: 'popup' | 'redirect';\n}\n\nexport interface OAuth2LoginResponse {\n  /**\n   * The provider ID that was used for this login\n   */\n  providerId: string;\n  /**\n   * The access token received from the OAuth provider\n   */\n  accessToken: AccessToken | null;\n  /**\n   * The ID token (JWT) if provided by the OAuth server (e.g., OpenID Connect)\n   */\n  idToken: string | null;\n  /**\n   * The refresh token if provided (requires appropriate scope like offline_access)\n   */\n  refreshToken: string | null;\n  /**\n   * Resource data fetched from resourceUrl if configured\n   * Contains the raw JSON response from the resource endpoint\n   */\n  resourceData: Record<string, unknown> | null;\n  /**\n   * The scopes that were granted\n   */\n  scope: string[];\n  /**\n   * Token type (usually 'bearer')\n   */\n  tokenType: string;\n  /**\n   * Token expiration time in seconds\n   */\n  expiresIn: number | null;\n}\n\nexport interface GoogleLoginOptions {\n  /**\n   * Specifies the scopes required for accessing Google APIs\n   * The default is defined in the configuration.\n   * @example [\"profile\", \"email\"]\n   * @see [Google OAuth2 Scopes](https://developers.google.com/identity/protocols/oauth2/scopes)\n   */\n  scopes?: string[];\n  /**\n   * Nonce\n   * @description nonce\n   */\n  nonce?: string;\n  /**\n   * Force refresh token (only for Android)\n   * @description force refresh token\n   * @default false\n   * @note On Android, the OS caches access tokens, and if a token is invalid (e.g., user revoked app access), the plugin might return an invalid accessToken. Using getAuthorizationCode() is recommended to ensure the token is valid.\n   */\n  forceRefreshToken?: boolean;\n  /**\n   * Force account selection prompt (iOS)\n   * @description forces the account selection prompt to appear on iOS\n   * @default false\n   */\n  forcePrompt?: boolean;\n  /**\n   * Style\n   * @description style\n   * @default 'standard'\n   */\n  style?: 'bottom' | 'standard';\n  /**\n   * Filter by authorized accounts (Android only)\n   * @description Only show accounts that have previously been used to sign in to the app.\n   * This option is only available for the 'bottom' style.\n   * Note: For Family Link supervised accounts, this should be set to false.\n   * @default true\n   */\n  filterByAuthorizedAccounts?: boolean;\n  /**\n   * Auto select enabled (Android only)\n   * @description Automatically select the account if only one Google account is available.\n   * This option is only available for the 'bottom' style.\n   * @default false\n   */\n  autoSelectEnabled?: boolean;\n  /**\n   * Prompt parameter for Google OAuth (Web only)\n   * @description A space-delimited, case-sensitive list of prompts to present the user.\n   * If you don't specify this parameter, the user will be prompted only the first time your project requests access.\n   *\n   * **Possible values:**\n   * - `none`: Don't display any authentication or consent screens. Must not be specified with other values.\n   * - `consent`: Prompt the user for consent.\n   * - `select_account`: Prompt the user to select an account.\n   *\n   * **Examples:**\n   * - `prompt: 'consent'` - Always show consent screen\n   * - `prompt: 'select_account'` - Always show account selection\n   * - `prompt: 'consent select_account'` - Show both consent and account selection\n   *\n   * **Note:** This parameter only affects web platform behavior. Mobile platforms use their own native prompts.\n   *\n   * @example 'consent'\n   * @example 'select_account'\n   * @example 'consent select_account'\n   * @see [Google OAuth2 Prompt Parameter](https://developers.google.com/identity/protocols/oauth2/openid-connect#prompt)\n   * @since 7.12.0\n   */\n  prompt?: 'none' | 'consent' | 'select_account' | 'consent select_account' | 'select_account consent';\n}\n\nexport interface GoogleLoginResponseOnline {\n  accessToken: AccessToken | null;\n  /**\n   * OpenID Connect ID token (JWT).\n   *\n   * Includes an `email_verified` claim when the `email` scope is granted. Use\n   * `SocialLogin.decodeIdToken({ idToken })` to read claims on the client, but\n   * always verify the token signature, `iss`, `aud`, and `exp` on your backend\n   * before trusting `email_verified` for account linking.\n   *\n   * @see https://developers.google.com/identity/gsi/web/guides/verify-google-id-token\n   */\n  idToken: string | null;\n  profile: {\n    /**\n     * Email from the ID token payload. Does not include a separate verification flag;\n     * check `idToken` claims (`email_verified`) for whether Google attests the address.\n     */\n    email: string | null;\n    familyName: string | null;\n    givenName: string | null;\n    id: string | null;\n    name: string | null;\n    imageUrl: string | null;\n  };\n  responseType: 'online';\n}\n\nexport interface GoogleLoginResponseOffline {\n  serverAuthCode: string;\n  responseType: 'offline';\n}\n\nexport type GoogleLoginResponse = GoogleLoginResponseOnline | GoogleLoginResponseOffline;\n\nexport interface AppleProviderOptions {\n  /**\n   * Scopes\n   * @description An array of scopes to request during login\n   * @example [\"name\", \"email\"]\n   * default: [\"name\", \"email\"]\n   */\n  scopes?: string[];\n  /**\n   * Nonce\n   * @description nonce\n   */\n  nonce?: string;\n  /**\n   * State\n   * @description state\n   */\n  state?: string;\n  /**\n   * Use Broadcast Channel for authentication flow\n   * @description When enabled, uses Broadcast Channel API for communication instead of URL redirects.\n   * Only applicable on platforms that support Broadcast Channel (Android).\n   * @default false\n   */\n  useBroadcastChannel?: boolean;\n}\n\nexport interface AppleProviderResponse {\n  /**\n   * Access token from Apple\n   * @description Content depends on `useProperTokenExchange` setting:\n   * - When `useProperTokenExchange: true`: Real access token from Apple (~1 hour validity)\n   * - When `useProperTokenExchange: false`: Contains authorization code as token (legacy mode)\n   * Use `idToken` for user authentication, `accessToken` for API calls when properly exchanged.\n   */\n  accessToken: AccessToken | null;\n\n  /**\n   * Identity token (JWT) from Apple.\n   *\n   * Includes standard OIDC claims such as `sub`, `email` (when granted), and\n   * `email_verified` (boolean). Apple sets `email_verified` to `true` when it\n   * attests the user controls the email (including Hide My Email relay addresses).\n   *\n   * Use `SocialLogin.decodeIdToken({ idToken })` to read claims on the client, but\n   * verify the token signature, `iss`, `aud`, and `exp` on your backend before\n   * trusting `email_verified` for account linking.\n   *\n   * @see https://developer.apple.com/documentation/signinwithapple/authenticating-users-with-sign-in-with-apple\n   */\n  idToken: string | null;\n\n  /**\n   * User profile information\n   * @description Basic user profile data extracted from the identity token and Apple response:\n   * - `user`: Apple's user identifier (sub claim from idToken)\n   * - `email`: User's email address (if permission granted)\n   * - `givenName`: User's first name (if permission granted)\n   * - `familyName`: User's last name (if permission granted)\n   */\n  profile: {\n    user: string;\n    email: string | null;\n    givenName: string | null;\n    familyName: string | null;\n  };\n\n  /**\n   * Authorization code for proper token exchange (when useProperTokenExchange is enabled)\n   * @description Only present when `useProperTokenExchange` is `true`. This code should be exchanged\n   * for proper access tokens on your backend using Apple's token endpoint. Use this for secure\n   * server-side token validation and to obtain refresh tokens.\n   * @see https://developer.apple.com/documentation/sign_in_with_apple/tokenresponse\n   */\n  authorizationCode?: string;\n}\n\nexport type LoginOptions =\n  | {\n      provider: 'facebook';\n      options: FacebookLoginOptions;\n    }\n  | {\n      provider: 'google';\n      options: GoogleLoginOptions;\n    }\n  | {\n      provider: 'apple';\n      options: AppleProviderOptions;\n    }\n  | {\n      provider: 'twitter';\n      options: TwitterLoginOptions;\n    }\n  | {\n      provider: 'oauth2';\n      options: OAuth2LoginOptions;\n    };\n\nexport type LoginResult =\n  | {\n      provider: 'facebook';\n      result: FacebookLoginResponse;\n    }\n  | {\n      provider: 'google';\n      result: GoogleLoginResponse;\n    }\n  | {\n      provider: 'apple';\n      result: AppleProviderResponse;\n    }\n  | {\n      provider: 'twitter';\n      result: TwitterLoginResponse;\n    }\n  | {\n      provider: 'oauth2';\n      result: OAuth2LoginResponse;\n    };\n\nexport interface AccessToken {\n  applicationId?: string;\n  declinedPermissions?: string[];\n  expires?: string;\n  isExpired?: boolean;\n  lastRefresh?: string;\n  permissions?: string[];\n  token: string;\n  tokenType?: string;\n  refreshToken?: string;\n  userId?: string;\n}\n\nexport interface FacebookLoginResponse {\n  accessToken: AccessToken | null;\n  /**\n   * Whether Facebook Limited Login was used for this session.\n   * When `true`, `accessToken` is not valid for Graph API calls (Facebook error 190).\n   * Validate `idToken` on your backend instead, or call `facebook#requestTracking` and log in again after ATT is granted.\n   * @since 8.4.0\n   */\n  isLimitedLogin?: boolean;\n  /**\n   * OpenID Connect ID token (JWT) from Meta Limited Login (iOS native, when available).\n   *\n   * **Not equivalent to Google/Apple `email_verified`:** Meta's OIDC token may include\n   * an `email` claim (when the `email` permission is granted) but does **not** publish an\n   * `email_verified` claim like Google or Apple. Meta documents the value as the user's\n   * primary account email, not as an OIDC-verified email assertion.\n   *\n   * On Android and Web this is usually `null` (Graph API access token flow instead).\n   * Validate signature, `iss` (`https://www.facebook.com` or `https://limited.facebook.com`),\n   * `aud`, `exp`, and nonce on your backend. Do not infer `email_verified: true` from the\n   * presence of `email` alone when linking accounts across providers.\n   *\n   * @see https://developers.facebook.com/docs/facebook-login/limited-login/token/validating/\n   */\n  idToken: string | null;\n  profile: {\n    userID: string;\n    /**\n     * Primary email from the Meta profile / Graph API (`/me?fields=email`).\n     *\n     * **Not equivalent to Google/Apple `email_verified`:** this field has no verification\n     * flag. Meta returns the account's primary email when the `email` permission is\n     * granted; it does not expose an `email_verified` boolean comparable to Google or\n     * Apple ID tokens. Treat this as an identifier hint only—verify ownership yourself\n     * (e.g. magic link) before linking Meta sign-in to Google/Apple accounts by email.\n     */\n    email: string | null;\n    friendIDs: string[];\n    birthday: string | null;\n    ageRange: { min?: number; max?: number } | null;\n    gender: string | null;\n    location: { id: string; name: string } | null;\n    hometown: { id: string; name: string } | null;\n    profileURL: string | null;\n    name: string | null;\n    imageURL: string | null;\n  };\n}\n\nexport interface TwitterProfile {\n  id: string;\n  username: string;\n  name: string | null;\n  profileImageUrl: string | null;\n  verified: boolean;\n  email?: string | null;\n}\n\nexport interface TwitterLoginResponse {\n  accessToken: AccessToken | null;\n  refreshToken?: string | null;\n  scope: string[];\n  tokenType: 'bearer';\n  expiresIn?: number | null;\n  profile: TwitterProfile;\n}\n\nexport interface AuthorizationCode {\n  /**\n   * Jwt\n   * @description A JSON web token\n   */\n  jwt?: string;\n  /**\n   * Access Token\n   * @description An access token\n   */\n  accessToken?: string;\n}\n\nexport interface AuthorizationCodeOptions {\n  /**\n   * Provider\n   * @description Provider for the authorization code\n   */\n  provider: 'apple' | 'google' | 'facebook' | 'twitter' | 'oauth2';\n  /**\n   * Provider ID for OAuth2 providers (required when provider is 'oauth2')\n   * @description The ID used when configuring the OAuth2 provider in initialize()\n   */\n  providerId?: string;\n}\n\nexport interface isLoggedInOptions {\n  /**\n   * Provider\n   * @description Provider for the isLoggedIn\n   */\n  provider: 'apple' | 'google' | 'facebook' | 'twitter' | 'oauth2';\n  /**\n   * Provider ID for OAuth2 providers (required when provider is 'oauth2')\n   * @description The ID used when configuring the OAuth2 provider in initialize()\n   */\n  providerId?: string;\n}\n\n// Define the provider-specific call types\nexport type ProviderSpecificCall = 'facebook#getProfile' | 'facebook#requestTracking';\n\n// Define the options and response types for each specific call\nexport interface FacebookGetProfileOptions {\n  /**\n   * Fields to retrieve from Facebook profile\n   * @example [\"id\", \"name\", \"email\", \"picture\"]\n   */\n  fields?: string[];\n}\n\nexport interface FacebookGetProfileResponse {\n  /**\n   * Facebook profile data\n   */\n  profile: {\n    id: string | null;\n    name: string | null;\n    email: string | null;\n    first_name: string | null;\n    last_name: string | null;\n    picture?: {\n      data: {\n        height: number | null;\n        is_silhouette: boolean | null;\n        url: string | null;\n        width: number | null;\n      };\n    } | null;\n    [key: string]: any; // For additional fields that might be requested\n  };\n}\n\nexport interface OpenSecureWindowOptions {\n  /**\n   * The endpoint to open\n   */\n  authEndpoint: string;\n  /**\n   * The redirect URI to use for the openSecureWindow call.\n   * This will be checked to make sure it matches the redirect URI after the window finishes the redirection.\n   */\n  redirectUri: string;\n  /**\n   * The name of the broadcast channel to listen to, relevant only for web\n   */\n  broadcastChannelName?: string;\n}\n\nexport interface OpenSecureWindowResponse {\n  /**\n   * The result of the openSecureWindow call\n   */\n  redirectedUri: string;\n}\n\nexport type FacebookRequestTrackingOptions = Record<string, never>;\n\nexport interface FacebookRequestTrackingResponse {\n  /**\n   * App tracking authorization status\n   */\n  status: 'authorized' | 'denied' | 'notDetermined' | 'restricted';\n}\n\n// Map call strings to their options and response types\nexport type ProviderSpecificCallOptionsMap = {\n  'facebook#getProfile': FacebookGetProfileOptions;\n  'facebook#requestTracking': FacebookRequestTrackingOptions;\n};\n\nexport type ProviderSpecificCallResponseMap = {\n  'facebook#getProfile': FacebookGetProfileResponse;\n  'facebook#requestTracking': FacebookRequestTrackingResponse;\n};\n\n// Add a helper type to map providers to their response types\nexport type ProviderResponseMap = {\n  facebook: FacebookLoginResponse;\n  google: GoogleLoginResponse;\n  apple: AppleProviderResponse;\n  twitter: TwitterLoginResponse;\n  oauth2: OAuth2LoginResponse;\n};\n\n/**\n * Error codes returned by the plugin.\n * @since 8.3.x\n */\nexport type SocialLoginErrorCode = 'USER_CANCELLED';\n\n/**\n * Errors thrown by SocialLogin methods.\n *\n * When a user dismisses or cancels the provider UI (popup closed, system dialog cancelled, access denied, etc.),\n * the plugin rejects with `code === 'USER_CANCELLED'` so the caller can distinguish user intent from real failures.\n * Other errors may omit the code or use provider-specific values.\n */\nexport interface SocialLoginError extends Error {\n  code?: SocialLoginErrorCode | string;\n}\n\nexport interface SocialLoginPlugin {\n  /**\n   * Initialize the plugin\n   * @description initialize the plugin with the required options\n   */\n  initialize(options: InitializeOptions): Promise<void>;\n  /**\n   * Login with the selected provider\n   * @description login with the selected provider\n   *\n   * On user dismissal/cancellation, the Promise is rejected with `code === 'USER_CANCELLED'` (see `SocialLoginError`).\n   */\n  login<T extends LoginOptions['provider']>(\n    options: Extract<LoginOptions, { provider: T }>,\n  ): Promise<{ provider: T; result: ProviderResponseMap[T] }>;\n  /**\n   * Logout\n   * @description Logout the user from the specified provider\n   *\n   * **Google Offline Mode Limitation:**\n   * This method is NOT supported when Google is initialized with `mode: 'offline'`.\n   * It will reject with error: \"logout is not implemented when using offline mode\"\n   *\n   * @throws Error if Google provider is in offline mode\n   */\n  logout(options: {\n    provider: 'apple' | 'google' | 'facebook' | 'twitter' | 'oauth2';\n    providerId?: string;\n  }): Promise<void>;\n  /**\n   * IsLoggedIn\n   * @description Check if the user is currently logged in with the specified provider\n   *\n   * **Google Offline Mode Limitation:**\n   * This method is NOT supported when Google is initialized with `mode: 'offline'`.\n   * It will reject with error: \"isLoggedIn is not implemented when using offline mode\"\n   *\n   * @throws Error if Google provider is in offline mode\n   */\n  isLoggedIn(options: isLoggedInOptions): Promise<{ isLoggedIn: boolean }>;\n\n  /**\n   * Get the current authorization code\n   * @description Get the authorization code for server-side authentication\n   *\n   * **Google Offline Mode Limitation:**\n   * This method is NOT supported when Google is initialized with `mode: 'offline'`.\n   * It will reject with error: \"getAuthorizationCode is not implemented when using offline mode\"\n   *\n   * In offline mode, the authorization code (serverAuthCode) is already returned by the `login()` method.\n   *\n   * @throws Error if Google provider is in offline mode\n   */\n  getAuthorizationCode(options: AuthorizationCodeOptions): Promise<AuthorizationCode>;\n  /**\n   * Refresh the access token\n   * @description refresh the access token\n   *\n   * **Google Offline Mode Limitation:**\n   * This method is NOT supported when Google is initialized with `mode: 'offline'`.\n   * Offline mode only returns `serverAuthCode` for backend token exchange, so token refresh must happen on your backend.\n   * The plugin logs and rejects with a message explaining that you should send `serverAuthCode` to your backend,\n   * refresh the Google tokens there, or switch to `mode: 'online'` for client-side refresh.\n   *\n   * **Google Web Limitation:**\n   * On Web, Google `refresh()` is not implemented, even when using `mode: 'online'`.\n   * Call `login()` again on Web to obtain a fresh token instead.\n   *\n   * @throws Error if Google provider is in offline mode, or on Web where Google `refresh()` is not implemented\n   */\n  refresh(options: LoginOptions): Promise<void>;\n\n  /**\n   * OAuth2 refresh-token helper (feature parity with Capawesome OAuth).\n   *\n   * Scope:\n   * - Only applies to the built-in `oauth2` provider (not Google/Apple/Facebook/Twitter).\n   * - Requires a token endpoint (either `accessTokenEndpoint`/`tokenEndpoint` or `issuerUrl` discovery).\n   *\n   * Security note:\n   * - This does not validate JWT signatures. It only exchanges/refreshes tokens.\n   *\n   * If `refreshToken` is omitted, the plugin will attempt to use the stored refresh token (if available).\n   */\n  refreshToken(options: {\n    provider: 'oauth2';\n    providerId: string;\n    refreshToken?: string;\n    additionalParameters?: Record<string, string>;\n  }): Promise<OAuth2LoginResponse>;\n\n  /**\n   * Web-only: handle the OAuth redirect callback and return the parsed result.\n   *\n   * Notes:\n   * - This is only meaningful on Web. iOS/Android implementations will reject.\n   * - Intended for redirect-based flows (e.g. `oauth2` with `flow: 'redirect'`) where the page navigates away.\n   */\n  handleRedirectCallback(): Promise<LoginResult | null>;\n\n  /**\n   * Decode a JWT (typically an OIDC ID token) into its claims.\n   *\n   * Notes:\n   * - Accepts both `idToken` and `token` to match common naming (Capawesome uses `token`).\n   * - This does not validate the signature or issuer/audience. It only base64url-decodes the payload.\n   *\n   * **`email_verified` semantics by provider (for account linking):**\n   * - **Google** — ID token includes `email_verified` (boolean). When `true`, Google attests\n   *   the user controls that email. Verify the JWT on your backend before trusting it.\n   * - **Apple** — ID token includes `email_verified` (boolean). When `true`, Apple attests\n   *   the user controls that email (including private relay). Verify the JWT on your backend.\n   * - **Meta (Facebook)** — Limited Login OIDC tokens may include `email` but **do not**\n   *   include `email_verified`. The presence of `email` is not the same guarantee as\n   *   `email_verified: true` from Google or Apple. Do not link accounts by email across\n   *   providers using Meta claims alone; perform your own email verification if needed.\n   */\n  decodeIdToken(options: { idToken?: string; token?: string }): Promise<{ claims: Record<string, any> }>;\n\n  /**\n   * Convert an access token expiration timestamp (milliseconds since epoch) to an ISO date string.\n   *\n   * This is a pure helper (feature parity with Capawesome OAuth) and does not depend on provider state.\n   */\n  getAccessTokenExpirationDate(options: {\n    /**\n     * Access token expiration date in milliseconds since epoch.\n     * Typically: `Date.now() + expiresInSeconds * 1000`.\n     */\n    accessTokenExpirationDate: number;\n  }): Promise<{ date: string }>;\n\n  /**\n   * Check if an access token is available (non-empty).\n   *\n   * This is a pure helper (feature parity with Capawesome OAuth) and does not depend on provider state.\n   */\n  isAccessTokenAvailable(options: { accessToken: string | null }): Promise<{ isAvailable: boolean }>;\n\n  /**\n   * Check if an access token is expired.\n   *\n   * This is a pure helper (feature parity with Capawesome OAuth) and does not depend on provider state.\n   */\n  isAccessTokenExpired(options: { accessTokenExpirationDate: number }): Promise<{ isExpired: boolean }>;\n\n  /**\n   * Check if a refresh token is available (non-empty).\n   *\n   * This is a pure helper (feature parity with Capawesome OAuth) and does not depend on provider state.\n   */\n  isRefreshTokenAvailable(options: { refreshToken: string | null }): Promise<{ isAvailable: boolean }>;\n\n  /**\n   * Execute provider-specific calls\n   * @description Execute a provider-specific functionality\n   */\n  providerSpecificCall<T extends ProviderSpecificCall>(options: {\n    call: T;\n    options: ProviderSpecificCallOptionsMap[T];\n  }): Promise<ProviderSpecificCallResponseMap[T]>;\n\n  /**\n   * Get the native Capacitor plugin version\n   *\n   * @returns {Promise<{ id: string }>} an Promise with version for this device\n   * @throws An error if the something went wrong\n   */\n  getPluginVersion(): Promise<{ version: string }>;\n\n  /**\n   * Opens a secured window for OAuth2 authentication.\n   * For web, you should have the code in the redirected page to use a broadcast channel to send the redirected url to the app\n   * Something like:\n   * ```html\n   * <html>\n   * <head></head>\n   * <body>\n   * <script>\n   *   const searchParams = new URLSearchParams(location.search)\n   *   if (searchParams.has(\"code\")) {\n   *     new BroadcastChannel(\"my-channel-name\").postMessage(location.href);\n   *     window.close();\n   *   }\n   * </script>\n   * </body>\n   * </html>\n   * ```\n   * For mobile, you should have a redirect uri that opens the app, something like: `myapp://oauth_callback/`\n   * And make sure to register it in the app's info.plist:\n   * ```xml\n   * <key>CFBundleURLTypes</key>\n   * <array>\n   *    <dict>\n   *       <key>CFBundleURLSchemes</key>\n   *       <array>\n   *          <string>myapp</string>\n   *       </array>\n   *    </dict>\n   * </array>\n   * ```\n   * And in the AndroidManifest.xml file:\n   * ```xml\n   * <activity>\n   *    <intent-filter>\n   *       <action android:name=\"android.intent.action.VIEW\" />\n   *       <category android:name=\"android.intent.category.DEFAULT\" />\n   *       <category android:name=\"android.intent.category.BROWSABLE\" />\n   *       <data android:host=\"oauth_callback\" android:scheme=\"myapp\" />\n   *    </intent-filter>\n   * </activity>\n   * ```\n   * @param options - the options for the openSecureWindow call\n   */\n  openSecureWindow(options: OpenSecureWindowOptions): Promise<OpenSecureWindowResponse>;\n}\n"]}

package/ios/Sources/SocialLoginPlugin/SocialLoginPlugin.swift

@@ -16,7 +16,7 @@ import GoogleSignIn
  */
 @objc(SocialLoginPlugin)
 public class SocialLoginPlugin: CAPPlugin, CAPBridgedPlugin {
-    private let pluginVersion: String = "8.3.32"
+    private let pluginVersion: String = "8.3.34"
     public let identifier = "SocialLoginPlugin"
     public let jsName = "SocialLogin"
     private static let userCancelledCode = "USER_CANCELLED"

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@capgo/capacitor-social-login",
-  "version": "8.3.32",
+  "version": "8.3.34",
   "description": "All social logins in one plugin",
   "main": "dist/plugin.cjs.js",
   "module": "dist/esm/index.js",