docs(auth): add Flutter signInWithIdToken example for Facebook auth (supabase#38265)

* docs(auth): add Flutter signInWithIdToken example for Facebook auth

Add documentation section showing how to integrate Facebook authentication
in Flutter using the signInWithIdToken method with the Facebook SDK.
Includes dependency setup, basic implementation, and error handling.

* fix style

* docs(dart): add Facebook signInWithIdToken example

Add native Facebook sign-in example to the Dart client reference
documentation. Includes integration with flutter_facebook_auth package
and proper error handling for the signInWithIdToken method.

* docs(dart): simplify provider parameter description

Remove specific provider enumeration from parameter description
to keep it more generic and maintainable.

* Add signInWithIdToken to spelling allow list

* Update auth-facebook.mdx

Co-authored-by: Chris Chinchilla <[email protected]>

* Update apps/docs/content/guides/auth/social-login/auth-facebook.mdx

Co-authored-by: github-actions[bot] <41898282+github-actions[bot]@users.noreply.github.com>

* Update apps/docs/content/guides/auth/social-login/auth-facebook.mdx

Co-authored-by: github-actions[bot] <41898282+github-actions[bot]@users.noreply.github.com>

---------

Co-authored-by: Chris Chinchilla <[email protected]>
Co-authored-by: github-actions[bot] <41898282+github-actions[bot]@users.noreply.github.com>

Author: 3 people

apps/docs/content/guides/auth/social-login/auth-facebook.mdx

@@ -121,6 +121,55 @@ Future<void> signInWithFacebook() async {
 }
 ```
 
+### Alternative: Using Facebook SDK with signInWithIdToken
+
+For more control over the Facebook authentication flow, you can use the Facebook SDK directly and then authenticate with Supabase using [`signInWithIdToken()`](/docs/reference/dart/auth-signinwithidtoken):
+
+First, add the Facebook SDK dependency to your `pubspec.yaml`:
+
+```yaml
+dependencies:
+  flutter_facebook_auth: ^7.0.1
+```
+
+Then implement the Facebook authentication:
+
+```dart
+import 'package:flutter_facebook_auth/flutter_facebook_auth.dart';
+import 'package:supabase_flutter/supabase_flutter.dart';
+
+Future<void> signInWithFacebook() async {
+  try {
+    final LoginResult result = await FacebookAuth.instance.login(
+      permissions: ['public_profile', 'email'],
+    );
+
+    if (result.status == LoginStatus.success) {
+      final accessToken = result.accessToken!.tokenString;
+
+      await Supabase.instance.client.auth.signInWithIdToken(
+        provider: OAuthProvider.facebook,
+        idToken: accessToken,
+      );
+
+      // Authentication successful
+    } else {
+      // Handle login cancellation or failure
+      throw Exception('Facebook login failed: ${result.status}');
+    }
+  } catch (e) {
+    // Handle errors
+    throw Exception('Facebook authentication error: ${e.toString()}');
+  }
+}
+```
+
+<Admonition type="note">
+
+Make sure to configure your Facebook app properly and add the required permissions in the Facebook Developer Console. The `signInWithIdToken` method requires the Facebook access token to be valid and properly scoped.
+
+</Admonition>
+
 </TabPanel>
 <TabPanel id="swift" label="Swift">
 

apps/docs/spec/supabase_dart_v2.yml

@@ -558,12 +558,12 @@ functions:
   - id: sign-in-with-id-token
     title: 'signInWithIdToken()'
     description: |
-      Allows you to perform native Google and Apple sign in by combining it with [google_sign_in](https://pub.dev/packages/google_sign_in) or [sign_in_with_apple](https://pub.dev/packages/sign_in_with_apple) packages.
+      Allows you to perform native Google, Apple, and Facebook sign in by combining it with [google_sign_in](https://pub.dev/packages/google_sign_in), [sign_in_with_apple](https://pub.dev/packages/sign_in_with_apple), or [flutter_facebook_auth](https://pub.dev/packages/flutter_facebook_auth) packages.
     params:
       - name: provider
         isOptional: false
         type: OAuthProvider
-        description: The provider to perform the sign in with. Currently, `OAuthProvider.google` and `OAuthProvider.apple` are supported.
+        description: The provider to perform the sign in with.
       - name: idToken
         isOptional: false
         type: String
@@ -719,6 +719,36 @@ functions:
             nonce: rawNonce,
           );
           ```
+      - id: sign-in-with-facebook
+        name: Native Facebook Sign in
+        description: |
+          You can perform native Facebook sign in using [flutter_facebook_auth](https://pub.dev/packages/flutter_facebook_auth).
+          
+          First, set up your Facebook app in the [Facebook Developer Console](https://developers.facebook.com) and configure it in your Supabase dashboard under `Authentication -> Providers -> Facebook`.
+        code: |
+          ```dart
+          import 'package:flutter_facebook_auth/flutter_facebook_auth.dart';
+          import 'package:supabase_flutter/supabase_flutter.dart';
+
+          Future<void> signInWithFacebook() async {
+            final LoginResult result = await FacebookAuth.instance.login(
+              permissions: ['public_profile', 'email'],
+            );
+
+            if (result.status == LoginStatus.success) {
+              final accessToken = result.accessToken!.tokenString;
+
+              final response = await supabase.auth.signInWithIdToken(
+                provider: OAuthProvider.facebook,
+                idToken: accessToken,
+              );
+            } else {
+              throw const AuthException(
+                'Facebook login failed: ${result.status}',
+              );
+            }
+          }
+          ```
   - id: sign-in-with-oauth
     title: 'signInWithOAuth()'
     description: |

supa-mdx-lint/Rule003Spelling.toml

@@ -336,6 +336,7 @@ allow_list = [
     "psql",
     "scrypt",
     "sessionStorage",
+    "signInWithIdToken",
     "stdin",
     "stdout",
     "[Ss]ubnet(s)?",