Merge branch 'main' into tanstack-start-apply-headers

Author: dios-david

.changeset/every-glasses-shave.md

@@ -0,0 +1,5 @@
+---
+'@clerk/react-router': patch
+---
+
+In this release the TypeScript types for `rootAuthLoader()`, `getAuth()`, and `<ClerkProvider>` were adjusted but should still work as before. Previously, these types relied on internal, unstable React Router types that changed in their recent 7.6.1 release. We simplified our TypeScript types and no longer rely on internal exports from React Router.

.changeset/true-bears-divide.md

@@ -0,0 +1,5 @@
+---
+'@clerk/backend': patch
+---
+
+Improve JSDoc comments

.typedoc/__tests__/__snapshots__/file-structure.test.ts.snap

@@ -7,6 +7,7 @@ exports[`Typedoc output > should have a deliberate file structure 1`] = `
   "types/active-session-resource.mdx",
   "types/check-authorization-fn.mdx",
   "types/check-authorization-from-session-claims.mdx",
+  "types/check-authorization-params-from-session-claims.mdx",
   "types/check-authorization-with-custom-permissions.mdx",
   "types/clerk-api-error.mdx",
   "types/clerk-host-router.mdx",
@@ -46,10 +47,13 @@ exports[`Typedoc output > should have a deliberate file structure 1`] = `
   "types/pending-session-resource.mdx",
   "types/record-to-path.mdx",
   "types/redirect-options.mdx",
+  "types/reverification-config.mdx",
   "types/saml-strategy.mdx",
   "types/sdk-metadata.mdx",
   "types/session-resource.mdx",
   "types/session-status-claim.mdx",
+  "types/session-verification-level.mdx",
+  "types/session-verification-types.mdx",
   "types/set-active-params.mdx",
   "types/set-active.mdx",
   "types/sign-in-resource.mdx",
@@ -140,10 +144,36 @@ exports[`Typedoc output > should have a deliberate file structure 1`] = `
   "clerk-react/use-sign-in.mdx",
   "clerk-react/use-sign-up.mdx",
   "clerk-react/use-user.mdx",
+  "backend/allowlist-identifier.mdx",
+  "backend/auth-object.mdx",
+  "backend/authenticate-request-options.mdx",
+  "backend/client.mdx",
+  "backend/email-address.mdx",
+  "backend/external-account.mdx",
+  "backend/identification-link.mdx",
+  "backend/invitation-status.mdx",
+  "backend/invitation.mdx",
+  "backend/organization-invitation-status.mdx",
+  "backend/organization-invitation.mdx",
+  "backend/organization-membership-public-user-data.mdx",
+  "backend/organization-membership.mdx",
+  "backend/organization-sync-target.mdx",
+  "backend/organization.mdx",
+  "backend/paginated-resource-response.mdx",
+  "backend/phone-number.mdx",
+  "backend/public-organization-data-json.mdx",
+  "backend/redirect-url.mdx",
+  "backend/saml-account.mdx",
+  "backend/saml-connection.mdx",
+  "backend/session-activity.mdx",
+  "backend/session.mdx",
+  "backend/user.mdx",
+  "backend/verification.mdx",
   "backend/verify-machine-auth-token.mdx",
   "backend/verify-token-options.mdx",
   "backend/verify-token.mdx",
   "backend/verify-webhook-options.mdx",
   "backend/verify-webhook.mdx",
+  "backend/web3-wallet.mdx",
 ]
 `;

.typedoc/custom-plugin.mjs

@@ -15,6 +15,10 @@ const FILES_WITHOUT_HEADINGS = [
   'use-organization-list-return.mdx',
   'use-organization-list-params.mdx',
   'create-organization-params.mdx',
+  'authenticate-request-options.mdx',
+  'verify-token-options.mdx',
+  'public-organization-data-json.mdx',
+  'organization-membership-public-user-data.mdx',
 ];
 
 /**
@@ -36,6 +40,18 @@ const LINK_REPLACEMENTS = [
   ['organization-domain-resource', '/docs/references/javascript/types/organization-domain'],
   ['organization-invitation-resource', '/docs/references/javascript/types/organization-invitation'],
   ['organization-membership-request-resource', '/docs/references/javascript/types/organization-membership-request'],
+  ['session', '/docs/references/backend/types/backend-session'],
+  ['session-activity', '/docs/references/backend/types/backend-session-activity'],
+  ['organization', '/docs/references/backend/types/backend-organization'],
+  ['public-organization-data-json', '#public-organization-data-json'],
+  ['organization-membership-public-user-data', '#organization-membership-public-user-data'],
+  ['identification-link', '/docs/references/backend/types/backend-identification-link'],
+  ['verification', '/docs/references/backend/types/backend-verification'],
+  ['email-address', '/docs/references/backend/types/backend-email-address'],
+  ['external-account', '/docs/references/backend/types/backend-external-account'],
+  ['phone-number', '/docs/references/backend/types/backend-phone-number'],
+  ['saml-account', '/docs/references/backend/types/backend-saml-account'],
+  ['web3-wallet', '/docs/references/backend/types/backend-web3-wallet'],
 ];
 
 /**
@@ -84,6 +100,25 @@ function getCatchAllReplacements() {
       pattern: /\| `SignInResource` \|/,
       replace: '| [SignInResource](/docs/references/javascript/sign-in) |',
     },
+    {
+      pattern: /`OrganizationPrivateMetadata`/g,
+      replace:
+        '[`OrganizationPrivateMetadata`](/docs/references/javascript/types/metadata#organization-private-metadata)',
+    },
+    {
+      pattern: /OrganizationPublicMetadata/g,
+      replace: '[OrganizationPublicMetadata](/docs/references/javascript/types/metadata#organization-public-metadata)',
+    },
+    {
+      pattern: /`OrganizationInvitationPrivateMetadata`/g,
+      replace:
+        '[`OrganizationInvitationPrivateMetadata`](/docs/references/javascript/types/metadata#organization-invitation-private-metadata)',
+    },
+    {
+      pattern: /`OrganizationInvitationPublicMetadata`/g,
+      replace:
+        '[`OrganizationInvitationPublicMetadata`](/docs/references/javascript/types/metadata#organization-invitation-public-metadata)',
+    },
     {
       /**
        * By default, `@deprecated` is output with `**Deprecated**`. We want to add a full stop to it.
@@ -105,6 +140,15 @@ function getCatchAllReplacements() {
       pattern: /\*\*Example\*\* `([^`]+)`/g,
       replace: 'Example: `$1`.',
     },
+    {
+      /**
+       * By default, multiple `@example` are output with "**Examples** `value1` `value2`". We want to capture the values and place them inside "Examples: `value1`, `value2`."
+       */
+      pattern: /\*\*Examples\*\* ((?:`[^`]+`)(?: `[^`]+`)*)/g,
+      replace: (/** @type {string} */ _match, /** @type {string} */ capturedGroup) => {
+        return `Examples: ${capturedGroup.split(' ').join(', ')}.`;
+      },
+    },
   ];
 }
 
@@ -126,6 +170,7 @@ export function load(app) {
 
     for (const { pattern, replace } of catchAllReplacements) {
       if (output.contents) {
+        // @ts-ignore - Mixture of string and function replacements
         output.contents = output.contents.replace(pattern, replace);
       }
     }

.typedoc/custom-theme.mjs

@@ -319,6 +319,10 @@ ${tabs}
 
         return `<code>${output}</code>`;
       },
+      /**
+       * Hide "Extends" and "Extended by" sections
+       */
+      hierarchy: () => '',
     };
   }
 }

packages/backend/src/api/resources/AllowlistIdentifier.ts

@@ -1,14 +1,38 @@
 import type { AllowlistIdentifierType } from './Enums';
 import type { AllowlistIdentifierJSON } from './JSON';
 
+/**
+ * The Backend `AllowlistIdentifier` object represents an identifier that has been added to the allowlist of your application. The Backend `AllowlistIdentifier` object is used in the [Backend API](https://clerk.com/docs/reference/backend-api/tag/Allow-list-Block-list#operation/ListAllowlistIdentifiers) and is not directly accessible from the Frontend API.
+ */
 export class AllowlistIdentifier {
   constructor(
+    /**
+     * A unique ID for the allowlist identifier.
+     */
     readonly id: string,
+    /**
+     * The [identifier](https://clerk.com/docs/authentication/configuration/sign-up-sign-in-options#identifiers) that was added to the allowlist.
+     */
     readonly identifier: string,
+    /**
+     * The type of the allowlist identifier.
+     */
     readonly identifierType: AllowlistIdentifierType,
+    /**
+     * The date when the allowlist identifier was first created.
+     */
     readonly createdAt: number,
+    /**
+     * The date when the allowlist identifier was last updated.
+     */
     readonly updatedAt: number,
+    /**
+     * The ID of the instance that this allowlist identifier belongs to.
+     */
     readonly instanceId?: string,
+    /**
+     * The ID of the invitation sent to the identifier.
+     */
     readonly invitationId?: string,
   ) {}
 

packages/backend/src/api/resources/Client.ts

@@ -1,15 +1,42 @@
 import type { ClientJSON } from './JSON';
 import { Session } from './Session';
 
+/**
+ * The Backend `Client` object is similar to the [`Client`](https://clerk.com/docs/references/javascript/client) object as it holds information about the authenticated sessions in the current device. However, the Backend `Client` object is different from the `Client` object in that it is used in the [Backend API](https://clerk.com/docs/reference/backend-api/tag/Clients#operation/GetClient) and is not directly accessible from the Frontend API.
+ */
 export class Client {
   constructor(
+    /**
+     * The unique identifier for the `Client`.
+     */
     readonly id: string,
+    /**
+     * An array of [Session](https://clerk.com/docs/references/backend/types/backend-session){{ target: '_blank' }} IDs associated with the `Client`.
+     */
     readonly sessionIds: string[],
+    /**
+     * An array of [Session](https://clerk.com/docs/references/backend/types/backend-session){{ target: '_blank' }} objects associated with the `Client`.
+     */
     readonly sessions: Session[],
+    /**
+     * The ID of the [`SignIn`](https://clerk.com/docs/references/javascript/sign-in){{ target: '_blank' }}.
+     */
     readonly signInId: string | null,
+    /**
+     * The ID of the [`SignUp`](https://clerk.com/docs/references/javascript/sign-up){{ target: '_blank' }}.
+     */
     readonly signUpId: string | null,
+    /**
+     * The ID of the last active [Session](https://clerk.com/docs/references/backend/types/backend-session).
+     */
     readonly lastActiveSessionId: string | null,
+    /**
+     * The date when the `Client` was first created.
+     */
     readonly createdAt: number,
+    /**
+     * The date when the `Client` was last updated.
+     */
     readonly updatedAt: number,
   ) {}
 

packages/backend/src/api/resources/Deserializer.ts

@@ -39,10 +39,27 @@ import { ObjectType } from './JSON';
 import { WaitlistEntry } from './WaitlistEntry';
 
 type ResourceResponse<T> = {
+  /**
+   * An array that contains the fetched data.
+   */
   data: T;
 };
 
+/**
+ * An interface that describes the response of a method that returns a paginated list of resources.
+ *
+ * If the promise resolves, you will get back the [properties](#properties) listed below. `data` will be an array of the resource type you requested. You can use the `totalCount` property to determine how many total items exist remotely.
+ *
+ * Some methods that return this type allow pagination with the `limit` and `offset` parameters, in which case the first 10 items will be returned by default. For methods such as [`getAllowlistIdentifierList()`](https://clerk.com/docs/references/backend/allowlist/get-allowlist-identifier-list), which do not take a `limit` or `offset`, all items will be returned.
+ *
+ * If the promise is rejected, you will receive a `ClerkAPIResponseError` or network error.
+ *
+ * @interface
+ */
 export type PaginatedResourceResponse<T> = ResourceResponse<T> & {
+  /**
+   * The total count of data that exist remotely.
+   */
   totalCount: number;
 };
 

packages/backend/src/api/resources/EmailAddress.ts

@@ -2,11 +2,30 @@ import { IdentificationLink } from './IdentificationLink';
 import type { EmailAddressJSON } from './JSON';
 import { Verification } from './Verification';
 
+/**
+ * The Backend `EmailAddress` object is a model around an email address. Email addresses are one of the [identifiers](https://clerk.com/docs/authentication/configuration/sign-up-sign-in-options#identifiers) used to provide identification for users.
+ *
+ * Email addresses must be **verified** to ensure that they are assigned to their rightful owners. The `EmailAddress` object holds all necessary state around the verification process.
+ *
+ * For implementation examples for adding and verifying email addresses, see the [email link custom flow](https://clerk.com/docs/custom-flows/email-links) and [email code custom flow](https://clerk.com/docs/custom-flows/add-email) guides.
+ */
 export class EmailAddress {
   constructor(
+    /**
+     * The unique identifier for the email address.
+     */
     readonly id: string,
+    /**
+     * The value of the email address.
+     */
     readonly emailAddress: string,
+    /**
+     * An object holding information on the verification of the email address.
+     */
     readonly verification: Verification | null,
+    /**
+     * An array of objects containing information about any identifications that might be linked to the email address.
+     */
     readonly linkedTo: IdentificationLink[],
   ) {}
 

packages/backend/src/api/resources/Enums.ts

@@ -21,6 +21,9 @@ export type OAuthProvider =
 
 export type OAuthStrategy = `oauth_${OAuthProvider}`;
 
+/**
+ * @inline
+ */
 export type OrganizationInvitationStatus = 'pending' | 'accepted' | 'revoked' | 'expired';
 
 export type OrganizationDomainVerificationStatus = 'unverified' | 'verified';
@@ -35,6 +38,9 @@ export type SignInStatus = 'needs_identifier' | 'needs_factor_one' | 'needs_fact
 
 export type SignUpVerificationNextAction = 'needs_prepare' | 'needs_attempt' | '';
 
+/**
+ * @inline
+ */
 export type InvitationStatus = 'pending' | 'accepted' | 'revoked' | 'expired';
 
 export const DomainsEnrollmentModes = {
@@ -51,8 +57,17 @@ export const ActorTokenStatus = {
 } as const;
 export type ActorTokenStatus = (typeof ActorTokenStatus)[keyof typeof ActorTokenStatus];
 
+/**
+ * @inline
+ */
 export type AllowlistIdentifierType = 'email_address' | 'phone_number' | 'web3_wallet';
 
+/**
+ * @inline
+ */
 export type BlocklistIdentifierType = AllowlistIdentifierType;
 
+/**
+ * @inline
+ */
 export type WaitlistEntryStatus = 'pending' | 'invited' | 'completed' | 'rejected';