chore(backend): Add JSDoc comments to resources

.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';

.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';

.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';

.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';

.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';

.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';

.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';

.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';