diff --git a/.changeset/pretty-wasps-press.md b/.changeset/pretty-wasps-press.md new file mode 100644 index 00000000000..31625a35aea --- /dev/null +++ b/.changeset/pretty-wasps-press.md @@ -0,0 +1,8 @@ +--- +'@clerk/backend': patch +'@clerk/shared': patch +'@clerk/clerk-react': patch +'@clerk/types': patch +--- + +Improve JSDoc comments diff --git a/.typedoc/custom-plugin.mjs b/.typedoc/custom-plugin.mjs index 5d97b643497..d59f95f464e 100644 --- a/.typedoc/custom-plugin.mjs +++ b/.typedoc/custom-plugin.mjs @@ -80,6 +80,10 @@ function getCatchAllReplacements() { pattern: /\(CreateOrganizationParams\)/g, replace: '([CreateOrganizationParams](#create-organization-params))', }, + { + pattern: /\| `SignInResource` \|/, + replace: '| [SignInResource](/docs/references/javascript/sign-in) |', + }, { /** * By default, `@deprecated` is output with `**Deprecated**`. We want to add a full stop to it. diff --git a/packages/backend/src/api/endpoints/InstanceApi.ts b/packages/backend/src/api/endpoints/InstanceApi.ts index cc65a288631..089e7d4627d 100644 --- a/packages/backend/src/api/endpoints/InstanceApi.ts +++ b/packages/backend/src/api/endpoints/InstanceApi.ts @@ -52,17 +52,17 @@ type UpdateOrganizationSettingsParams = { adminDeleteEnabled?: boolean | null | undefined; domainsEnabled?: boolean | null | undefined; /** - * Specify which enrollment modes to enable for your Organization Domains. + * Specifies which [enrollment modes](https://clerk.com/docs/organizations/verified-domains#enrollment-mode) to enable for your Organization Domains. * * @remarks Supported modes are 'automatic_invitation' & 'automatic_suggestion'. */ domainsEnrollmentModes?: Array | undefined; /** - * Specify what the default organization role is for an organization creator. + * Specifies what the default organization role is for an organization creator. */ creatorRoleId?: string | null | undefined; /** - * Specify what the default organization role is for the organization domains. + * Specifies what the default organization role is for the organization domains. */ domainsDefaultRoleId?: string | null | undefined; }; diff --git a/packages/react/src/hooks/useAuth.ts b/packages/react/src/hooks/useAuth.ts index c6c908d049a..9e0caf92e44 100644 --- a/packages/react/src/hooks/useAuth.ts +++ b/packages/react/src/hooks/useAuth.ts @@ -17,16 +17,17 @@ import { invalidStateError } from '../errors/messages'; import { useAssertWrappedByClerkProvider } from './useAssertWrappedByClerkProvider'; import { createGetToken, createSignOut } from './utils'; -type Nullish = T | undefined | null; -type InitialAuthState = Record; /** * @inline */ -type UseAuthOptions = Nullish; +type UseAuthOptions = Record | PendingSessionOptions | undefined | null; /** * The `useAuth()` hook provides access to the current user's authentication state and methods to manage the active session. * + * > [!NOTE] + * > To access auth data server-side, see the [`Auth` object reference doc](https://clerk.com/docs/references/backend/types/auth-object). + * * * By default, Next.js opts all routes into static rendering. If you need to opt a route or routes into dynamic rendering because you need to access the authentication data at request time, you can create a boundary by passing the `dynamic` prop to ``. See the [guide on rendering modes](https://clerk.com/docs/references/nextjs/rendering-modes) for more information, including code examples. * @@ -34,7 +35,7 @@ type UseAuthOptions = Nullish; * @unionReturnHeadings * ["Initialization", "Signed out", "Signed in (no active organization)", "Signed in (with active organization)"] * - * @param [initialAuthStateOrOptions] - An object containing the initial authentication state. If not provided, the hook will attempt to derive the state from the context. + * @param [initialAuthStateOrOptions] - An object containing the initial authentication state or options for the `useAuth()` hook. If not provided, the hook will attempt to derive the state from the context. `treatPendingAsSignedOut` is a boolean that indicates whether pending sessions are considered as signed out or not. Defaults to `true`. * * @function * diff --git a/packages/react/src/types.ts b/packages/react/src/types.ts index 6db4b2e2c34..b24a28a4df0 100644 --- a/packages/react/src/types.ts +++ b/packages/react/src/types.ts @@ -24,7 +24,7 @@ declare global { export type IsomorphicClerkOptions = Without & { Clerk?: ClerkProp; /** - * Define the URL that `@clerk/clerk-js` should be hot-loaded from + * The URL that `@clerk/clerk-js` should be hot-loaded from. */ clerkJSUrl?: string; /** @@ -32,7 +32,7 @@ export type IsomorphicClerkOptions = Without & { */ clerkJSVariant?: 'headless' | ''; /** - * Define the npm version for `@clerk/clerk-js` + * The npm version for `@clerk/clerk-js`. */ clerkJSVersion?: string; /** diff --git a/packages/shared/src/react/hooks/useOrganization.tsx b/packages/shared/src/react/hooks/useOrganization.tsx index a68e6a4c3ef..12c1fe71d56 100644 --- a/packages/shared/src/react/hooks/useOrganization.tsx +++ b/packages/shared/src/react/hooks/useOrganization.tsx @@ -32,7 +32,7 @@ export type UseOrganizationParams = { * If set to `true`, all default properties will be used.
* Otherwise, accepts an object with the following optional properties: *
    - *
  • `enrollmentMode`: A string that filters the domains by the provided enrollment mode.
    • + *
  • `enrollmentMode`: A string that filters the domains by the provided [enrollment mode](https://clerk.com/docs/organizations/verified-domains#enrollment-mode).
    • *
  • Any of the properties described in [Shared properties](#shared-properties).
    • *
*/ @@ -69,7 +69,7 @@ export type UseOrganizationParams = { * If set to `true`, all default properties will be used.
* Otherwise, accepts an object with the following optional properties: *
    - *
  • `status`: A string that filters the subscriptions by the provided status.
    • + *
  • `orgId`: A string that filters the subscriptions by the provided organization ID.
    • *
  • Any of the properties described in [Shared properties](#shared-properties).
    • *
*/ diff --git a/packages/types/src/hooks.ts b/packages/types/src/hooks.ts index 109406f3ddb..7baac435ea4 100644 --- a/packages/types/src/hooks.ts +++ b/packages/types/src/hooks.ts @@ -180,7 +180,7 @@ export type UseSessionReturn = */ isSignedIn: undefined; /** - * Holds the current active session for the user. + * The current active session for the user. */ session: undefined; } @@ -233,7 +233,7 @@ export type UseUserReturn = */ isSignedIn: undefined; /** - * The `User` object for the current user. If the user isn't signed in, `user` will be `null`. + * The `User` object for the current user. */ user: undefined; } diff --git a/packages/types/src/localization.ts b/packages/types/src/localization.ts index f9c37da3cc4..071b3d8b382 100644 --- a/packages/types/src/localization.ts +++ b/packages/types/src/localization.ts @@ -5,7 +5,7 @@ export type LocalizationValue = string; /** * A type containing all the possible localization keys the prebuilt Clerk components support. - * Users aiming to customise a few strings can also peak at the `data-localization-key` attribute by inspecting + * Users aiming to customize a few strings can also peak at the `data-localization-key` attribute by inspecting * the DOM and updating the corresponding key. * Users aiming to completely localize the components by providing a complete translation can use * the default english resource object from {@link https://github.com/clerk/javascript Clerk's open source repo} diff --git a/packages/types/src/multiDomain.ts b/packages/types/src/multiDomain.ts index 64716362f91..7da96353d81 100644 --- a/packages/types/src/multiDomain.ts +++ b/packages/types/src/multiDomain.ts @@ -11,7 +11,7 @@ import type { ClerkOptions } from './clerk'; export type MultiDomainAndOrProxy = | { /** - * Whether the application is a satellite application. + * A boolean that indicates whether the application is a satellite application. */ isSatellite?: never; /** @@ -37,7 +37,7 @@ export type MultiDomainAndOrProxy = export type MultiDomainAndOrProxyPrimitives = | { /** - * Whether the application is a satellite application. + * A boolean that indicates whether the application is a satellite application. */ isSatellite?: never; /** diff --git a/packages/types/src/redirects.ts b/packages/types/src/redirects.ts index db7bed1d108..59f593d827c 100644 --- a/packages/types/src/redirects.ts +++ b/packages/types/src/redirects.ts @@ -9,8 +9,8 @@ export type AfterSignOutUrl = { export type AfterMultiSessionSingleSignOutUrl = { /** - * Full URL or path to navigate to after signing out the current user is complete. - * This option applies to multi-session applications. + * The full URL or path to navigate to after signing out the current user is complete. + * This option applies to [multi-session applications](https://clerk.com/docs/authentication/configuration/session-options#multi-session-applications). */ afterMultiSessionSingleSignOutUrl?: string | null; }; @@ -45,14 +45,14 @@ export type RedirectOptions = SignInForceRedirectUrl & export type AuthenticateWithRedirectParams = { /** - * Full URL or path to the route that will complete the OAuth or SAML flow. + * The full URL or path to the route that will complete the OAuth or SAML flow. * Typically, this will be a simple `/sso-callback` route that calls `Clerk.handleRedirectCallback` * or mounts the component. */ redirectUrl: string; /** - * Full URL or path to navigate to after the OAuth or SAML flow completes. + * The full URL or path to navigate to after the OAuth or SAML flow completes. */ redirectUrlComplete: string; @@ -94,7 +94,7 @@ export type RedirectUrlProp = { export type SignUpForceRedirectUrl = { /** - * If provided, this URL will always be redirected to after the user signs up. It's recommended to use the [environment variable](https://clerk.com/docs/deployments/clerk-environment-variables#sign-in-and-sign-up-redirects) instead. + * This URL will always be redirected to after the user signs up. It's recommended to use the [environment variable](https://clerk.com/docs/deployments/clerk-environment-variables#sign-in-and-sign-up-redirects) instead. */ signUpForceRedirectUrl?: string | null; }; @@ -117,7 +117,7 @@ export type SignInFallbackRedirectUrl = { export type SignInForceRedirectUrl = { /** - * If provided, this URL will always be redirected to after the user signs in. It's recommended to use the [environment variable](https://clerk.com/docs/deployments/clerk-environment-variables#sign-in-and-sign-up-redirects) instead. + * This URL will always be redirected to after the user signs in. It's recommended to use the [environment variable](https://clerk.com/docs/deployments/clerk-environment-variables#sign-in-and-sign-up-redirects) instead. */ signInForceRedirectUrl?: string | null; }; diff --git a/packages/types/src/session.ts b/packages/types/src/session.ts index 7642a9c64d3..46adb6b934f 100644 --- a/packages/types/src/session.ts +++ b/packages/types/src/session.ts @@ -33,7 +33,7 @@ import type { Autocomplete } from './utils'; */ export type PendingSessionOptions = { /** - * Determines if pending sessions are considered as signed-out state. + * A boolean that indicates whether pending sessions are considered as signed out or not. * @default true */ treatPendingAsSignedOut?: boolean; diff --git a/packages/types/src/signIn.ts b/packages/types/src/signIn.ts index b5b1a327b3b..0f8ccdbde66 100644 --- a/packages/types/src/signIn.ts +++ b/packages/types/src/signIn.ts @@ -72,7 +72,6 @@ import type { AuthenticateWithWeb3Params } from './web3Wallet'; /** * The `SignIn` object holds the state of the current sign-in and provides helper methods to navigate and complete the sign-in process. It is used to manage the sign-in lifecycle, including the first and second factor verification, and the creation of a new session. - * @interface */ export interface SignInResource extends ClerkResource { /** @@ -120,6 +119,9 @@ export interface SignInResource extends ClerkResource { createEmailLinkFlow: () => CreateEmailLinkFlowReturn; validatePassword: (password: string, callbacks?: ValidatePasswordCallbacks) => void; + /** + * @internal + */ __internal_toSnapshot: () => SignInJSONSnapshot; }