Merge pull request #13513 from supabase/hf/add-sso-reference-docs-js

reference-docs: add `signInWithSSO` to JS/TS reference docs

apps/docs/pages/guides/auth/sso/auth-sso-saml.mdx

@@ -185,7 +185,7 @@ supabase.auth.signInWithSSO({
 })
 ```
 
-Calling this method starts the sign-in process using the identity provider registered for the `company.com` domain name. It is not required that identity providers be assigned one or multiple domain names, in which case you can use the provider's unique ID instead.
+Calling [`signInWithSSO`](/docs/reference/javascript/auth-signinwithsso) starts the sign-in process using the identity provider registered for the `company.com` domain name. It is not required that identity providers be assigned one or multiple domain names, in which case you can use the provider's unique ID instead.
 
 ### Understanding attribute mappings
 

spec/common-client-libs-sections.json

@@ -418,6 +418,13 @@
         "product": "auth",
         "type": "function"
       },
+      {
+        "id": "sign-in-with-whatsapp-otp",
+        "title": "Sign in a user through WhatsApp",
+        "slug": "auth-signinwithwhatsappotp",
+        "product": "auth",
+        "type": "function"
+      },
       {
         "id": "sign-in-with-oauth",
         "title": "Sign in a user through OAuth",
@@ -426,9 +433,9 @@
         "type": "function"
       },
       {
-        "id": "sign-in-with-whatsapp-otp",
-        "title": "Sign in a user through WhatsApp",
-        "slug": "auth-signinwithwhatsappotp",
+        "id": "sign-in-with-sso",
+        "title": "Sign in a user through SSO",
+        "slug": "auth-signinwithsso",
         "product": "auth",
         "type": "function"
       },

spec/supabase_js_v2.yml

@@ -319,6 +319,50 @@ functions:
           })
           const oAuthToken = data.session.provider_token // use to access provider API
           ```
+  - id: sign-in-with-sso
+    title: 'signInWithSSO()'
+    $ref: '@supabase/gotrue-js.GoTrueClient.signInWithSSO'
+    notes: |
+      - Before you can call this method you need to [establish a connection](/docs/guides/auth/sso/auth-sso-saml#managing-saml-20-connections) to an identity provider. Use the [CLI commands](/docs/reference/cli/supabase-sso) to do this.
+      - If you've associated an email domain to the identity provider, you can use the `domain` property to start a sign-in flow.
+      - In case you need to use a different way to start the authentication flow with an identity provider, you can use the `providerId` property. For example:  
+          - Mapping specific user email addresses with an identity provider.
+          - Using different hints to identity the identity provider to be used by the user, like a company-specific page, IP address or other tracking information.
+    examples:
+      - id: sign-in-with-domain
+        name: Sign in with email domain
+        isSpotlight: true
+        code: |
+          ```js
+            // You can extract the user's email domain and use it to trigger the
+            // authentication flow with the correct identity provider.
+
+            const { data, error } = await supabase.auth.signInWithSSO({
+              domain: 'company.com'
+            })
+
+            if (data?.url) {
+              // redirect the user to the identity provider's authentication flow
+              window.location.href = data.url
+            }
+          ```
+      - id: sign-in-with-provider-uuid
+        name: Sign in with provider UUID
+        isSpotlight: true
+        code: |
+          ```js
+            // Useful when you need to map a user's sign in request according
+            // to different rules that can't use email domains.
+
+            const { data, error } = await supabase.auth.signInWithSSO({
+              providerId: '21648a9d-8d5a-4555-a9d1-d6375dc14e92'
+            })
+
+            if (data?.url) {
+              // redirect the user to the identity provider's authentication flow
+              window.location.href = data.url
+            }
+          ```
   - id: sign-out
     title: 'signOut()'
     $ref: '@supabase/gotrue-js.GoTrueClient.signOut'