docs(repo): Add typedoc comments; generate typedoc output for /objects docs

.changeset/typedoc-objects-jsdoc.md

@@ -0,0 +1,13 @@
+---
+'@clerk/backend': patch
+'@clerk/clerk-js': patch
+'@clerk/expo': patch
+'@clerk/express': patch
+'@clerk/nextjs': patch
+'@clerk/react': patch
+'@clerk/shared': patch
+'@clerk/ui': patch
+'@clerk/vue': patch
+---
+
+Add and improve JSDoc comments across public types and methods to support generated reference documentation for the `/objects` docs section. Exports a few previously-internal types (`OnEventListener`, `OffEventListener`, `ClerkOptionsNavigation`) so they can be referenced from the generated docs.

.prettierignore

@@ -23,4 +23,6 @@ packages/clerk-js/src/core/resources/index.ts
 packages/shared/src/compiled
 /**/CHANGELOG.md
 renovate.json5
+# Frozen snapshots of TypeDoc-generated MDX; must match raw `extract-methods.mjs` output.
+.typedoc/__tests__/__snapshots__/
 CLAUDE.md

.typedoc/__tests__/__snapshots__/api-key-resource-methods-create.mdx

@@ -0,0 +1,21 @@
+### `create()`
+
+Creates a new API key.
+
+Returns an [`APIKeyResource`](/docs/reference/types/api-key-resource) object that includes the `secret` property.
+> [!WARNING]
+> Make sure to store the API key secret immediately after creation, as it will not be available again.
+
+```typescript
+function create(params: CreateAPIKeyParams): Promise<APIKeyResource>
+```
+
+#### `CreateAPIKeyParams`
+
+
+| Property | Type | Description |
+| ------ | ------ | ------ |
+| <a id="description"></a> `description?` | `string` | The description of the API key. |
+| <a id="name"></a> `name` | `string` | The name of the API key. |
+| <a id="secondsuntilexpiration"></a> `secondsUntilExpiration?` | `number` | The number of seconds until the API key expires. Set to `null` or omit to create a key that never expires. |
+| <a id="subject"></a> `subject?` | `string` | The user or organization ID to associate the API key with. If not provided, defaults to the [Active Organization](!active-organization), then the current User. |

.typedoc/__tests__/__snapshots__/clerk-methods-handle-email-link-verification.mdx

@@ -0,0 +1,18 @@
+### `handleEmailLinkVerification()`
+
+Completes an email link verification flow started by `Clerk.client.signIn.createEmailLinkFlow` or `Clerk.client.signUp.createEmailLinkFlow`, by processing the verification results from the redirect URL query parameters. This method should be called after the user is redirected back from visiting the verification link in their email.
+
+```typescript
+function handleEmailLinkVerification(params: { onVerifiedOnOtherDevice?: () => void; redirectUrl?: string; redirectUrlComplete?: string }, customNavigate?: (to: string) => Promise<unknown>): Promise<unknown>
+```
+
+#### Parameters
+
+
+| Parameter | Type | Description |
+| ------ | ------ | ------ |
+| `params` | <code>\{ onVerifiedOnOtherDevice?: () => void; redirectUrl?: string; redirectUrlComplete?: string; \}</code> | Allows you to define the URLs where the user should be redirected to on successful verification or pending/completed sign-up or sign-in attempts. If the email link is successfully verified on another device, there's a callback function parameter that allows custom code execution. |
+| `params.onVerifiedOnOtherDevice?` | <code>() => void</code> | Callback function to be executed after successful email link verification on another device. |
+| `params.redirectUrl?` | `string` | The full URL to navigate to after successful email link verification on the same device, but without completing sign-in or sign-up. |
+| `params.redirectUrlComplete?` | `string` | The full URL to navigate to after successful email link verification on completed sign-up or sign-in on the same device. |
+| `customNavigate?` | <code>(to: string) => Promise\<unknown\></code> | A function that overrides Clerk's default navigation behavior, allowing custom handling of navigation during sign-up and sign-in flows. |

.typedoc/__tests__/__snapshots__/clerk-methods-handle-redirect-callback.mdx

@@ -0,0 +1,15 @@
+### `handleRedirectCallback()`
+
+Completes a custom OAuth or SAML redirect flow that was started by calling [`SignIn.authenticateWithRedirect(params)`](/docs/reference/objects/sign-in) or [`SignUp.authenticateWithRedirect(params)`](/docs/reference/objects/sign-up).
+
+```typescript
+function handleRedirectCallback(params: HandleOAuthCallbackParams, customNavigate?: (to: string) => Promise<unknown>): Promise<unknown>
+```
+
+#### Parameters
+
+
+| Parameter | Type | Description |
+| ------ | ------ | ------ |
+| `params` | [`HandleOAuthCallbackParams`](/docs/reference/types/handle-o-auth-callback-params) | Additional props that define where the user will be redirected to at the end of a successful OAuth or SAML flow. |
+| `customNavigate?` | <code>(to: string) => Promise\<unknown\></code> | A function that overrides Clerk's default navigation behavior, allowing custom handling of navigation during sign-up and sign-in flows. |

.typedoc/__tests__/__snapshots__/clerk-methods-join-waitlist.mdx

@@ -0,0 +1,14 @@
+### `joinWaitlist()`
+
+Create a new waitlist entry programmatically. Requires that you set your app's sign-up mode to [**Waitlist**](/docs/guides/secure/restricting-access#waitlist) in the Clerk Dashboard.
+
+```typescript
+function joinWaitlist(params: JoinWaitlistParams): Promise<WaitlistResource>
+```
+
+#### `JoinWaitlistParams`
+
+
+| Property | Type | Description |
+| ------ | ------ | ------ |
+| <a id="emailaddress"></a> `emailAddress` | `string` | The email address of the user to add to the waitlist. |

.typedoc/__tests__/__snapshots__/clerk-methods-sign-out.mdx

@@ -0,0 +1,15 @@
+### `signOut()`
+
+Signs out the current user on single-session instances, or all users on multi-session instances.
+
+```typescript
+function signOut(options?: SignOutOptions): Promise<void>
+```
+
+#### `SignOutOptions`
+
+
+| Property | Type | Description |
+| ------ | ------ | ------ |
+| <a id="redirecturl"></a> `redirectUrl?` | `string` | Specify a redirect URL to navigate to after sign-out is complete. |
+| <a id="sessionid"></a> `sessionId?` | `string` | Specify a specific session to sign out. Useful for multi-session applications. |

.typedoc/__tests__/__snapshots__/clerk-properties.mdx

@@ -0,0 +1,21 @@
+| Property                                           | Type                                                                                                 | Description                                                                                                                                                                                                                                                                                                                              |
+| -------------------------------------------------- | ---------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| <a id="apikeys"></a> `apiKeys`                     | [`APIKeysNamespace`](/docs/reference/objects/api-keys)                                               | The `APIKeys` object used for managing API keys.                                                                                                                                                                                                                                                                                         |
+| <a id="billing"></a> `billing`                     | [`BillingNamespace`](/docs/reference/objects/billing)                                                | The `Billing` object used for managing billing.                                                                                                                                                                                                                                                                                          |
+| <a id="client"></a> `client`                       | <code>undefined \| [ClientResource](/docs/reference/objects/client)</code>                           | The `Client` object for the current window.                                                                                                                                                                                                                                                                                              |
+| <a id="domain"></a> `domain`                       | `string`                                                                                             | The current Clerk app's domain. Prefixed with `clerk.` on production if not already prefixed. Returns `""` when ran on the server.                                                                                                                                                                                                       |
+| <a id="instancetype"></a> `instanceType`           | <code>undefined \| "production" \| "development"</code>                                              | Indicates whether the Clerk instance is running in a production or development environment.                                                                                                                                                                                                                                              |
+| <a id="issatellite"></a> `isSatellite`             | `boolean`                                                                                            | Indicates whether the instance is a satellite app.                                                                                                                                                                                                                                                                                       |
+| <a id="issignedin"></a> `isSignedIn`               | `boolean`                                                                                            | Indicates whether the current user has a valid signed-in client session.                                                                                                                                                                                                                                                                 |
+| <a id="isstandardbrowser"></a> `isStandardBrowser` | <code>undefined \| boolean</code>                                                                    | Indicates whether the instance is being loaded in a standard browser environment. Set to `false` on native platforms where cookies cannot be set. When `undefined`, Clerk assumes a standard browser.                                                                                                                                    |
+| <a id="loaded"></a> `loaded`                       | `boolean`                                                                                            | Indicates whether the `Clerk` object is ready for use. Set to `false` when the `status` is `"loading"`. Set to `true` when the `status` is `"ready"` or `"degraded"`.                                                                                                                                                                    |
+| <a id="oauthapplication"></a> `oauthApplication`   | [`OAuthApplicationNamespace`](../o-auth-application-namespace.mdx)                                   | OAuth application helpers (e.g. consent metadata for custom consent UIs).                                                                                                                                                                                                                                                                |
+| <a id="organization"></a> `organization`           | <code>undefined \| null \| [OrganizationResource](/docs/reference/objects/organization)</code>       | A shortcut to the last active `Session.user.organizationMemberships` which holds an instance of a `Organization` object. If the session is `null` or `undefined`, the user field will match.                                                                                                                                             |
+| <a id="proxyurl"></a> `proxyUrl`                   | <code>undefined \| string</code>                                                                     | **Required for applications that run behind a reverse proxy**. Your Clerk app's proxy URL. Can be either a relative path (`/__clerk`) or a full URL (`https://<your-domain>/__clerk`).                                                                                                                                                   |
+| <a id="publishablekey"></a> `publishableKey`       | `string`                                                                                             | Your Clerk [Publishable Key](!publishable-key).                                                                                                                                                                                                                                                                                          |
+| <a id="sdkmetadata"></a> `sdkMetadata`             | <code>undefined \| \{ environment?: string; name: string; version: string; \}</code>                 | If present, contains information about the SDK that the host application is using. For example, if Clerk is loaded through `@clerk/nextjs`, this would be `{ name: '@clerk/nextjs', version: '1.0.0' }`. You don't need to set this value yourself unless you're [developing an SDK](/docs/guides/development/sdk-development/overview). |
+| <a id="session"></a> `session`                     | <code>undefined \| null \| [SignedInSessionResource](/docs/reference/objects/session)</code>         | The currently active `Session`, which is guaranteed to be one of the sessions in `Client.sessions`. If there is no active session, this field will be `null`. If the session is loading, this field will be `undefined`.                                                                                                                 |
+| <a id="status"></a> `status`                       | <code>"error" \| "degraded" \| "loading" \| "ready"</code>                                           | The status of the `Clerk` instance. Possible values are: <ul> <li>`"error"`: Set when hotloading `clerk-js` or `Clerk.load()` failed.</li> <li>`"loading"`: Set during initialization.</li> <li>`"ready"`: Set when Clerk is fully operational.</li> <li>`"degraded"`: Set when Clerk is partially operational.</li> </ul>               |
+| <a id="telemetry"></a> `telemetry`                 | <code>undefined \| \{ isDebug: boolean; isEnabled: boolean; record: void; recordLog: void; \}</code> | [Telemetry](/docs/guides/how-clerk-works/security/clerk-telemetry) configuration.                                                                                                                                                                                                                                                        |
+| <a id="user"></a> `user`                           | <code>undefined \| null \| [UserResource](/docs/reference/objects/user)</code>                       | A shortcut to `Session.user` which holds the currently active `User` object. If the session is `null` or `undefined`, the user field will match.                                                                                                                                                                                         |
+| <a id="version"></a> `version`                     | <code>undefined \| string</code>                                                                     | The Clerk SDK version number.                                                                                                                                                                                                                                                                                                            |

.typedoc/__tests__/__snapshots__/clerk.mdx

@@ -0,0 +1 @@
+The `Clerk` class serves as the central interface for working with Clerk's authentication and user management functionality in your application. As a top-level class in the Clerk SDK, it provides access to key methods and properties for managing users, sessions, API keys, billing, organizations, and more.

.typedoc/__tests__/__snapshots__/session-resource-methods-check-authorization.mdx

@@ -0,0 +1,7 @@
+### `checkAuthorization()`
+
+Checks if the user is [authorized for the specified Role, Permission, Feature, or Plan](/docs/guides/secure/authorization-checks) or requires the user to [reverify their credentials](/docs/guides/secure/reverification) if their last verification is older than allowed.
+
+```typescript
+function checkAuthorization(isAuthorizedParams: CheckAuthorizationParams): boolean
+```

.typedoc/__tests__/__snapshots__/sign-in-future-resource-methods-email-code-send-code.mdx

@@ -0,0 +1,15 @@
+### `emailCode.sendCode()`
+
+Sends an email code to sign-in.
+
+```typescript
+function sendCode(params?: SignInFutureEmailCodeSendParams): Promise<{ error: null | ClerkError }>
+```
+
+#### `SignInFutureEmailCodeSendParams`
+
+
+| Property | Type | Description |
+| ------ | ------ | ------ |
+| `emailAddress?` | `string` | The user's email address. Only supported if [Email address](/docs/guides/configure/auth-strategies/sign-up-sign-in-options#email) is enabled. Provide either `emailAddress` or `emailAddressId`, not both. Omit both when a sign-in already exists. |
+| `emailAddressId?` | `string` | The ID for the user's email address that will receive an email with the one-time authentication code. Provide either `emailAddress` or `emailAddressId`, not both. Omit both when a sign-in already exists. |

.typedoc/__tests__/__snapshots__/sign-in-future-resource-methods-email-link.mdx

@@ -0,0 +1,6 @@
+### `emailLink`
+
+
+| Property | Type | Description |
+| ------ | ------ | ------ |
+| `verification` | <code>null \| \{ createdSessionId: string; status: "expired" \| "failed" \| "verified" \| "client_mismatch"; verifiedFromTheSameClient: boolean; \}</code> | The verification status of the email link. This property is populated by reading query parameters from the URL after the user visits the email link. Returns `null` if no verification status is available. |