chore: wip

packages/core/src/providers/apple.ts

@@ -1,22 +1,19 @@
 /**
- * <div style={{backgroundColor: "#000", display: "flex", justifyContent: "space-between", color: "#fff", padding: 16}}>
- * <span>Built-in <b>Apple</b> integration.</span>
- * <a href="https://apple.com">
- *   <img style={{display: "block"}} src="https://authjs.dev/img/providers/apple-dark.svg" height="48" width="48"/>
+ * <div style={{display: "flex", justifyContent: "space-between", alignItems: "center"}}>
+ * <span style={{fontSize: "1.35rem" }}>
+ *  Built-in sign in with <b>Apple</b> integration.
+ * </span>
+ * <a href="https://apple.com" style={{backgroundColor: "black", padding: "12px", borderRadius: "100%" }}>
+ *   <img style={{display: "block"}} src="https://authjs.dev/img/providers/apple-dark.svg" width="24"/>
  * </a>
  * </div>
  *
- * ---
  * @module providers/apple
  */
 
 import type { OAuthConfig, OAuthUserConfig } from "./index.js"
 
-/**
- * See more at:
- * [Retrieve the User's Information from Apple ID Servers
-](https://developer.apple.com/documentation/sign_in_with_apple/sign_in_with_apple_rest_api/authenticating_users_with_sign_in_with_apple#3383773)
- */
+/** The returned user profile from Apple when using the profile callback. */
 export interface AppleProfile extends Record<string, any> {
   /**
    * The issuer registered claim identifies the principal that issued the identity token.
@@ -99,6 +96,44 @@ export interface AppleProfile extends Record<string, any> {
   auth_time: number
 }
 
+/**
+ * ## Setup
+ *
+ * Import the provider and configure it in your **Auth.js** initialization file:
+ *
+ * ```ts title="pages/api/auth/[...nextauth].ts"
+ * import NextAuth from "next-auth"
+ * import AppleProvider from "next-auth/providers/apple"
+ *
+ * export default NextAuth({
+ *   providers: [
+ *     AppleProvider({
+ *       clientId: process.env.GITHUB_ID,
+ *       clientSecret: process.env.GITHUB_SECRET,
+ *     }),
+ *   ],
+ * })
+ * ```
+ * 
+ * ## Resources
+ * 
+ * - Sign in with Apple [Overview](https://developer.apple.com/sign-in-with-apple/get-started/)
+ * - Sign in with Apple [REST API](https://developer.apple.com/documentation/sign_in_with_apple/sign_in_with_apple_rest_api)
+ * - [How to retrieve](https://developer.apple.com/documentation/sign_in_with_apple/sign_in_with_apple_rest_api/authenticating_users_with_sign_in_with_apple#3383773) the user's information from Apple ID servers
+ * - [Learn more about OAuth](https://authjs.dev/concepts/oauth)
+
+ * ## Notes
+ * 
+ * The Apple provider comes with a [default configuration](https://github.com/nextauthjs/next-auth/blob/main/packages/core/src/providers/apple.ts). To override the defaults for your use case, check out [customizing a built-in OAuth provider](https://authjs.dev/guides/providers/custom-provider#override-default-options).
+ *
+ * ## Help
+ *
+ * If you think you found a bug in the default configuration, you can [open an issue](https://authjs.dev/new/provider-issue).
+ *
+ * Auth.js strictly adheres to the specification and it cannot take responsibility for any deviation from
+ * the spec by the provider. You can open an issue, but if the problem is non-compliance with the spec,
+ * we might not pursue a resolution. You can ask for more help in [Discussions](https://authjs.dev/new/github-discussions).
+ */
 export default function Apple<P extends AppleProfile>(
   options: Omit<OAuthUserConfig<P>, "clientSecret"> & {
     /**

packages/core/src/providers/asgardeo.ts

@@ -1,95 +1,100 @@
 /**
- * <div style={{backgroundColor: "#24292f", display: "flex", justifyContent: "space-between", color: "#fff", padding: 16}}>
- * <span>Built-in <b>Asgardeo</b> integration.</span>
- * <a href="https://wso2.com/asgardeo/">
- *   <img style={{display: "block"}} src="https://authjs.dev/img/providers/asgardeo-dark.svg" height="48" width="48"/>
+ * <div style={{display: "flex", justifyContent: "space-between", alignItems: "center"}}>
+ * <span style={{fontSize: "1.35rem" }}>
+ *  Built-in sign in with <b>Asgardeo</b> integration.
+ * </span>
+ * <a href="https://wso2.com/asgardeo/" style={{backgroundColor: "#ECEFF1", padding: "12px", borderRadius: "100%" }}>
+ *   <img style={{display: "block"}} src="https://authjs.dev/img/providers/asgardeo-dark.svg" width="24"/>
  * </a>
  * </div>
  *
- * ---
  * @module providers/asgardeo
  */
 
 import type { OIDCConfig, OIDCUserConfig } from "./index.js"
 
-export interface AsgardeoProfile {
+/** The returned user profile from Asgardeo when using the profile callback. */
+export interface AsgardeoProfile extends Record<string, any> {
+  /**
+   * The user Asgardeo account ID
+   */
   sub: string
+  /**
+   * The user name
+   */
   given_name: string
+  /**
+   * The user email
+   */
   email: string
+  /**
+   * The user profile picture
+   */
   picture: string
 }
 
 /**
- * Add Asgardeo login to your page.
- * ## Documentation
  *
- * https://wso2.com/asgardeo/docs/guides/authentication
+ * ## Setup
  *
+ * Import the provider and configure it in your **Auth.js** initialization file:
  *
- * ## Instructions
+ * ```ts title="pages/api/auth/[...nextauth].ts"
+ * import NextAuth from "next-auth"
+ * import AsgardeoProvider from "next-auth/providers/asgardeo";
  *
- * - Log into https://console.asgardeo.io.
- * - Next, go to "Application" tab (More info: https://wso2.com/asgardeo/docs/guides/applications/register-oidc-web-app/).
- * - Register standard based - Open id connect, application.
- * - Add callback URL: http://localhost:3000/api/auth/callback/asgardeo and https://your-domain.com/api/auth/callback/asgardeo
- * - After registering the application, go to protocol tab.
- * - Check `code` grant type.
- * - Add Authorized redirect URLs & Allowed origins fields.
- * - Make Email, First Name, Photo URL user attributes mandatory from the console.
- *
- * Create a `.env` file in the project root add the following entries:
- *
- * These values can be collected from the application created.
- *
- * ```
- * ASGARDEO_CLIENT_ID=<Copy client ID from protocol tab here>
- * ASGARDEO_CLIENT_SECRET=<Copy client from protocol tab here>
- * ASGARDEO_ISSUER=<Copy the issuer url from the info tab here>
+ * export default NextAuth({
+ *  providers: [
+ *    AsgardeoProvider({
+ *      clientId: process.env.ASGARDEO_CLIENT_ID,
+ *      clientSecret: process.env.ASGARDEO_CLIENT_SECRET,
+ *      issuer: process.env.ASGARDEO_ISSUER
+ *    }),
+ *  ],
+ * })
  * ```
  *
- * In `pages/api/auth/[...nextauth].js` find or add the `Asgardeo` entries:
+ * ### Configuring Asgardeo
  *
- * ```js
- * import Asgardeo from "next-auth/providers/asgardeo";
- * ...
- * providers: [
- *   Asgardeo({
- *     clientId: process.env.ASGARDEO_CLIENT_ID,
- *     clientSecret: process.env.ASGARDEO_CLIENT_SECRET,
- *     issuer: process.env.ASGARDEO_ISSUER
- *   }),
- * ],
+ * Follow these steps:
  *
- * ...
+ * 1. Log into the [Asgardeo console](https://console.asgardeo.io)
+ * 2. Next, go to "Application" tab (more info [here](https://wso2.com/asgardeo/docs/guides/applications/register-oidc-web-app/))
+ * 3. Register a standard based, Open ID connect, application
+ * 4. Add the **callback URLs**: `http://localhost:3000/api/auth/callback/asgardeo` (development) and `https://{YOUR_DOMAIN}.com/api/auth/callback/asgardeo` (production)
+ * 5. After registering the application, go to "Protocol" tab.
+ * 6. Check `code` as the grant type.
+ * 7. Add "Authorized redirect URLs" & "Allowed origins fields"
+ * 8. Make Email, First Name, Photo URL user attributes mandatory from the console.
+ *
+ * Then, create a `.env` file in the project root add the following entries:
+ *
+ * ```
+ * ASGARDEO_CLIENT_ID="Copy client ID from protocol tab here"
+ * ASGARDEO_CLIENT_SECRET="Copy client from protocol tab here"
+ * ASGARDEO_ISSUER="Copy the issuer url from the info tab here"
  * ```
  *
  * ## Resources
  *
- * @see [Asgardeo - Authentication Guide](https://wso2.com/asgardeo/docs/guides/authentication)
- * @see [Learn more about OAuth](https://authjs.dev/concepts/oauth)
- * @see [Source code](https://github.com/nextauthjs/next-auth/blob/main/packages/core/src/providers/asgardeo.ts)
+ * - [Asgardeo - Authentication Guide](https://wso2.com/asgardeo/docs/guides/authentication)
+ * - [Learn more about OAuth](https://authjs.dev/concepts/oauth)
  *
  * ## Notes
  *
- * By default, Auth.js assumes that the Asgardeo provider is
- * based on the [OAuth 2](https://www.rfc-editor.org/rfc/rfc6749.html) specification.
- *
- * :::tip
- *
- * The Asgardeo provider comes with a [default configuration](https://github.com/nextauthjs/next-auth/blob/main/packages/core/src/providers/asgardeo.ts).
- * To override the defaults for your use case, check out [customizing a built-in OAuth provider](https://authjs.dev/guides/providers/custom-provider#override-default-options).
+ * The Asgardeo provider comes with a [default configuration](https://github.com/nextauthjs/next-auth/blob/main/packages/core/src/providers/asgardeo.ts). To override the defaults for your use case, check out [customizing a built-in OAuth provider](https://authjs.dev/guides/providers/custom-provider#override-default-options).
  *
+ * :::info
+ * By default, Auth.js assumes that the Asgardeo provider is based on the [OAuth 2](https://www.rfc-editor.org/rfc/rfc6749.html) spec
  * :::
  *
- * :::info **Disclaimer**
+ * ## Help
  *
  * If you think you found a bug in the default configuration, you can [open an issue](https://authjs.dev/new/provider-issue).
  *
  * Auth.js strictly adheres to the specification and it cannot take responsibility for any deviation from
  * the spec by the provider. You can open an issue, but if the problem is non-compliance with the spec,
  * we might not pursue a resolution. You can ask for more help in [Discussions](https://authjs.dev/new/github-discussions).
- *
- * :::
  */
 export default function Asgardeo(
   config: OIDCUserConfig<AsgardeoProfile>

packages/core/src/providers/atlassian.ts

@@ -1,12 +1,72 @@
+/**
+ * <div style={{display: "flex", justifyContent: "space-between", alignItems: "center"}}>
+ * <span style={{fontSize: "1.35rem" }}>
+ *  Built-in sign in with <b>Atlassian</b> integration.
+ * </span>
+ * <a href="https://www.atlassian.com/" style={{backgroundColor: "black", padding: "12px", borderRadius: "100%" }}>
+ *   <img style={{display: "block"}} src="https://authjs.dev/img/providers/atlassian.svg" width="24" style={{ marginTop: "-3px"}} />
+ * </a>
+ * </div>
+ *
+ * @module providers/atlassian
+ */
 import type { OAuthConfig, OAuthUserConfig } from "./index.js"
 
-interface AtlassianProfile extends Record<string, any> {
+/** The returned user profile from Atlassian when using the profile callback. */
+export interface AtlassianProfile extends Record<string, any> {
+  /**
+   * The user's atlassian account ID
+   */
   account_id: string
+  /**
+   * The user name
+   */
   name: string
+  /**
+   * The user's email
+   */
   email: string
+  /**
+   * The user's profile picture
+   */
   picture: string
 }
 
+/**
+ * ## Setup
+ *
+ * Import the provider and configure it in your **Auth.js** initialization file:
+ *
+ * ```ts title="pages/api/auth/[...nextauth].ts"
+ * import NextAuth from "next-auth"
+ * import AtlassianProvider from "next-auth/providers/atlassian"
+ *
+ * export default NextAuth({
+ *   providers: [
+ *     AtlassianProvider({
+ *       clientId: process.env.ATLASSIAN_ID,
+ *       clientSecret: process.env.ATLASSIAN_SECRET,
+ *     }),
+ *   ],
+ * })
+ * ```
+ *
+ * ## Resources
+ *
+ * - [Atlassian docs](https://developer.atlassian.com/server/jira/platform/oauth/)
+ *
+ * ## Notes
+ *
+ * The Atlassian provider comes with a [default configuration](https://github.com/nextauthjs/next-auth/blob/main/packages/core/src/providers/atlassian.ts). To override the defaults for your use case, check out [customizing a built-in OAuth provider](https://authjs.dev/guides/providers/custom-provider#override-default-options).
+ *
+ * ## Help
+ *
+ * If you think you found a bug in the default configuration, you can [open an issue](https://authjs.dev/new/provider-issue).
+ *
+ * Auth.js strictly adheres to the specification and it cannot take responsibility for any deviation from
+ * the spec by the provider. You can open an issue, but if the problem is non-compliance with the spec,
+ * we might not pursue a resolution. You can ask for more help in [Discussions](https://authjs.dev/new/github-discussions).
+ */
 export default function Atlassian<P extends AtlassianProfile>(
   options: OAuthUserConfig<P>
 ): OAuthConfig<P> {

packages/core/src/providers/auth0.ts

@@ -1,19 +1,19 @@
 /**
- * <div style={{backgroundColor: "#EB5424", display: "flex", justifyContent: "space-between", color: "#fff", padding: 16}}>
- * <span>Built-in <b>Auth0</b> integration.</span>
- * <a href="https://auth0.com">
- *   <img style={{display: "block"}} src="https://authjs.dev/img/providers/auth0-dark.svg" height="48" width="48"/>
+ * <div style={{display: "flex", justifyContent: "space-between", alignItems: "center"}}>
+ * <span style={{fontSize: "1.35rem" }}>
+ *  Built-in sign in with <b>Auth0</b> integration.
+ * </span>
+ * <a href="https://auth0.com" style={{backgroundColor: "black", padding: "12px", borderRadius: "100%" }}>
+ *   <img style={{display: "block"}} src="https://authjs.dev/img/providers/auth0-dark.svg" width="24"/>
  * </a>
  * </div>
  *
- * ---
  * @module providers/auth0
  */
-
 import type { OIDCConfig, OIDCUserConfig } from "./index.js"
 
-/** @see [User Profile Structure](https://auth0.com/docs/manage-users/user-accounts/user-profiles/user-profile-structure) */
-export interface Auth0Profile {
+/** The returned user profile from Auth0 when using the profile callback. [Reference](https://auth0.com/docs/manage-users/user-accounts/user-profiles/user-profile-structure). */
+export interface Auth0Profile extends Record<string, any> {
   /** The user's unique identifier. */
   sub: string
   /** Custom fields that store info about a user that influences the user's access, such as support plan, security roles (if not using the Authorization Core feature set), or access control groups. To learn more, read Metadata Overview. */
@@ -75,51 +75,40 @@ export interface Auth0Profile {
 }
 
 /**
- * Add Auth0 login to your page.
+ * ## Setup
  *
- * ## Example
+ * Import the provider and configure it in your **Auth.js** initialization file:
  *
- * ```ts
- * import { Auth } from "@auth/core"
- * import Auth0 from "@auth/core/providers/auth0"
+ * ```ts title="pages/api/auth/[...nextauth].ts"
+ * import NextAuth from "next-auth"
+ * import Auth0Provider from "next-auth/providers/auth0"
  *
- * const request = new Request("https://example.com")
- * const response = await Auth(request, {
- *   providers: [Auth0({ clientId: "", clientSecret: "", issuer: "" })],
+ * export default NextAuth({
+ *   providers: [
+ *     Auth0Provider({
+ *       clientId: process.env.AUTH0_ID,
+ *       clientSecret: process.env.AUTH0_SECRET,
+ *     }),
+ *   ],
  * })
  * ```
  *
- * ---
- *
  * ## Resources
  *
- * - [Authenticate - Auth0 docs](https://auth0.com/docs/authenticate)
- *
- * ---
+ * - [Auth0 docs](https://auth0.com/docs/authenticate)
  *
  * ## Notes
  *
- * By default, Auth.js assumes that the Auth0 provider is
- * based on the [OIDC](https://openid.net/specs/openid-connect-core-1_0.html) specification.
+ * The Auth0 provider comes with a [default configuration](https://github.com/nextauthjs/next-auth/blob/main/packages/core/src/providers/auth0.ts). To override the defaults for your use case, check out [customizing a built-in OAuth provider](https://authjs.dev/guides/providers/custom-provider#override-default-options).
  *
- * :::tip
- *
- * The Auth0 provider comes with a [default configuration](https://github.com/nextauthjs/next-auth/blob/main/packages/core/src/providers/auth0.ts).
- * To override the defaults for your use case, check out [customizing a built-in OAuth provider](https://authjs.dev/guides/providers/custom-provider#override-default-options).
- *
- * :::
- *
- * :::info **Disclaimer**
+ * ## Help
  *
  * If you think you found a bug in the default configuration, you can [open an issue](https://authjs.dev/new/provider-issue).
  *
  * Auth.js strictly adheres to the specification and it cannot take responsibility for any deviation from
  * the spec by the provider. You can open an issue, but if the problem is non-compliance with the spec,
  * we might not pursue a resolution. You can ask for more help in [Discussions](https://authjs.dev/new/github-discussions).
- *
- * :::
  */
-
 export default function Auth0(
   config: OIDCUserConfig<Auth0Profile>
 ): OIDCConfig<Auth0Profile> {

packages/core/src/providers/salesforce.ts

@@ -1,3 +1,48 @@
+/**
+ * Add Salesforce login to your page.
+ *
+ * ## Example
+ *
+ * ```ts
+ * import { Auth } from "@auth/core"
+ * import Salesforce from "@auth/core/providers/salesforce"
+ *
+ * const request = new Request("https://example.com")
+ * const response = await AuthHandler(request, {
+ *   providers: [Salesforce({ clientId: "", clientSecret: "" })],
+ * })
+ * ```
+ *
+ * ---
+ *
+ * ## Resources
+ *
+ * - [](https://example.com)
+ *
+ * ---
+ *
+ * ## Notes
+ *
+ * By default, Auth.js assumes that the Salesforce provider is
+ * based on the [OAuth 2](https://www.rfc-editor.org/rfc/rfc6749.html) specification.
+ *
+ * :::tip
+ *
+ * The Salesforce provider comes with a [default configuration](https://github.com/nextauthjs/next-auth/blob/main/packages/core/src/providers/.ts).
+ * To override the defaults for your use case, check out [customizing a built-in OAuth provider](https://authjs.dev/guides/providers/custom-provider#override-default-options).
+ *
+ * :::
+ *
+ * :::info **Disclaimer**
+ *
+ * If you think you found a bug in the default configuration, you can [open an issue](https://authjs.dev/new/provider-issue).
+ *
+ * Auth.js strictly adheres to the specification and it cannot take responsibility for any deviation from
+ * the spec by the provider. You can open an issue, but if the problem is non-compliance with the spec,
+ * we might not pursue a resolution. You can ask for more help in [Discussions](https://authjs.dev/new/github-discussions).
+ *
+ * :::
+ */
 import type { OAuthConfig, OAuthUserConfig } from "./index.js"
 
 export interface SalesforceProfile extends Record<string, any> {