feat(gotrue): implement linkIdentityWithIdToken method

- Add linkIdentityWithIdToken method for linking identities with ID tokens
- Refactor signInWithIdToken and linkIdentityWithIdToken to share common code
- Create _signInWithIdToken helper method to eliminate code duplication
- Maintain backward compatibility with existing signInWithIdToken API
- Add proper documentation and experimental annotation

Author: grdsdev

packages/gotrue/lib/src/gotrue_client.dart

@@ -382,17 +382,14 @@ class GoTrueClient {
   /// If the ID token contains a `nonce` claim, then [nonce] must be
   /// provided to compare its hash with the value in the ID token.
   ///
-  /// [captchaToken] is the verification token received when the user
-  /// completes the captcha on the app.
-  ///
-  /// This method is experimental.
-  @experimental
-  Future<AuthResponse> signInWithIdToken({
+  /// Sign in with ID token (internal helper method).
+  Future<AuthResponse> _signInWithIdToken({
     required OAuthProvider provider,
     required String idToken,
     String? accessToken,
     String? nonce,
     String? captchaToken,
+    required bool linkIdentity,
   }) async {
     if (provider != OAuthProvider.google &&
         provider != OAuthProvider.apple &&
@@ -402,18 +399,24 @@ class GoTrueClient {
           '${OAuthProvider.google.name}, ${OAuthProvider.apple.name}, ${OAuthProvider.kakao.name} or ${OAuthProvider.keycloak.name}.');
     }
 
+    final body = {
+      'provider': provider.snakeCase,
+      'id_token': idToken,
+      'nonce': nonce,
+      'gotrue_meta_security': {'captcha_token': captchaToken},
+      'access_token': accessToken,
+    };
+
+    if (linkIdentity) {
+      body['link_identity'] = true;
+    }
+
     final response = await _fetch.request(
       '$_url/token',
       RequestMethodType.post,
       options: GotrueRequestOptions(
         headers: _headers,
-        body: {
-          'provider': provider.snakeCase,
-          'id_token': idToken,
-          'nonce': nonce,
-          'gotrue_meta_security': {'captcha_token': captchaToken},
-          'access_token': accessToken,
-        },
+        body: body,
         query: {'grant_type': 'id_token'},
       ),
     );
@@ -432,6 +435,28 @@ class GoTrueClient {
     return authResponse;
   }
 
+  /// [captchaToken] is the verification token received when the user
+  /// completes the captcha on the app.
+  ///
+  /// This method is experimental.
+  @experimental
+  Future<AuthResponse> signInWithIdToken({
+    required OAuthProvider provider,
+    required String idToken,
+    String? accessToken,
+    String? nonce,
+    String? captchaToken,
+  }) async {
+    return _signInWithIdToken(
+      provider: provider,
+      idToken: idToken,
+      accessToken: accessToken,
+      nonce: nonce,
+      captchaToken: captchaToken,
+      linkIdentity: false,
+    );
+  }
+
   /// Log in a user using magiclink or a one-time password (OTP).
   ///
   /// If the `{{ .ConfirmationURL }}` variable is specified in the email template, a magiclink will be sent.
@@ -914,6 +939,38 @@ class GoTrueClient {
     return res.user?.identities ?? [];
   }
 
+  /// Link an identity to the current user using an ID token.
+  ///
+  /// [provider] is the OAuth provider (google, apple, kakao, or keycloak)
+  ///
+  /// [idToken] is the ID token from the OAuth provider
+  ///
+  /// [accessToken] is the access token from the OAuth provider
+  ///
+  /// [nonce] is the nonce used for the OAuth flow
+  ///
+  /// [captchaToken] is the verification token received when the user
+  /// completes the captcha on the app.
+  ///
+  /// This method is experimental.
+  @experimental
+  Future<AuthResponse> linkIdentityWithIdToken({
+    required OAuthProvider provider,
+    required String idToken,
+    String? accessToken,
+    String? nonce,
+    String? captchaToken,
+  }) async {
+    return _signInWithIdToken(
+      provider: provider,
+      idToken: idToken,
+      accessToken: accessToken,
+      nonce: nonce,
+      captchaToken: captchaToken,
+      linkIdentity: true,
+    );
+  }
+
   /// Returns the URL to link the user's identity with an OAuth provider.
   Future<OAuthResponse> getLinkIdentityUrl(
     OAuthProvider provider, {