docs(repo): Generate all params and return types (hooks work)

.changeset/violet-boxes-watch.md

@@ -0,0 +1,6 @@
+---
+'@clerk/shared': minor
+'@clerk/types': minor
+---
+
+Ensure all hooks use typedoc for clerk docs

.typedoc/custom-plugin.mjs

@@ -10,7 +10,6 @@ const FILES_WITHOUT_HEADINGS = [
  'use-organization-params.mdx',
  'paginated-resources.mdx',
  'pages-or-infinite-options.mdx',
- 'pages-or-infinite-options.mdx',
  'paginated-hook-config.mdx',
  'use-organization-list-return.mdx',
  'use-organization-list-params.mdx',
@@ -19,6 +18,21 @@ const FILES_WITHOUT_HEADINGS = [
  'verify-token-options.mdx',
  'public-organization-data-json.mdx',
  'organization-membership-public-user-data.mdx',
+ 'use-checkout-return.mdx',
+ 'use-checkout-options.mdx',
+ 'use-payment-element-return.mdx',
+ 'use-payment-methods-return.mdx',
+ 'use-payment-attempts-return.mdx',
+ 'use-plans-return.mdx',
+ 'use-statements-return.mdx',
+ 'hook-params.mdx',
+ 'use-subscription-params.mdx',
+ 'subscription-result.mdx',
+ 'needs-reverification-parameters.mdx',
+ 'use-reverification-options.mdx',
+ 'use-reverification-params.mdx',
+ 'payment-element-provider-props.mdx',
+ 'payment-element-props.mdx',
 ];
 
 /**
@@ -29,6 +43,8 @@ const LINK_REPLACEMENTS = [
  ['set-active-params', '/docs/reference/javascript/types/set-active-params'],
  ['clerk-paginated-response', '/docs/reference/javascript/types/clerk-paginated-response'],
  ['paginated-resources', '#paginated-resources'],
+ ['use-checkout-options', '#use-checkout-options'],
+ ['needs-reverification-parameters', '#needs-reverification-parameters'],
  ['create-organization-params', '#create-organization-params'],
  ['session-resource', '/docs/reference/javascript/session'],
  ['signed-in-session-resource', '/docs/reference/javascript/session'],
@@ -62,13 +78,18 @@ const LINK_REPLACEMENTS = [
  ['billing-payer-resource', '/docs/reference/javascript/types/billing-payer-resource'],
  ['billing-plan-resource', '/docs/reference/javascript/types/billing-plan-resource'],
  ['billing-checkout-totals', '/docs/reference/javascript/types/billing-checkout-totals'],
+ ['billing-checkout-resource', '/docs/reference/javascript/types/billing-checkout-resource'],
  ['billing-money-amount', '/docs/reference/javascript/types/billing-money-amount'],
  ['billing-subscription-item-resource', '/docs/reference/javascript/types/billing-subscription-item-resource'],
  ['feature-resource', '/docs/reference/javascript/types/feature-resource'],
  ['billing-statement-group', '/docs/reference/javascript/types/billing-statement-group'],
+ ['billing-statement-resource', '/docs/reference/javascript/types/billing-statement-resource'],
+ ['billing-subscription-resource', '/docs/reference/javascript/types/billing-subscription-resource'],
+ ['clerk-api-response-error', '/docs/reference/javascript/types/clerk-api-response-error'],
  ['billing-statement-totals', '/docs/reference/javascript/types/billing-statement-totals'],
  ['billing-payment-resource', '/docs/reference/javascript/types/billing-payment-resource'],
  ['deleted-object-resource', '/docs/reference/javascript/types/deleted-object-resource'],
+ ['use-checkout-return', '/docs/reference/hooks/use-checkout#returns'],
 ];
 
 /**

.typedoc/extract-returns-and-params.mjs

@@ -0,0 +1,179 @@
+// @ts-check
+import fs from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = path.dirname(__filename);
+
+/**
+ * Extracts the "## Returns" section from a markdown file and writes it to a separate file.
+ * @param {string} filePath - The path to the markdown file
+ * @returns {boolean} True if a file was created
+ */
+function extractReturnsSection(filePath) {
+ const content = fs.readFileSync(filePath, 'utf-8');
+
+ // Find the "## Returns" section
+ const returnsStart = content.indexOf('## Returns');
+
+ if (returnsStart === -1) {
+ return false; // No Returns section found
+ }
+
+ // Find the next heading after "## Returns" (or end of file)
+ const afterReturns = content.slice(returnsStart + 10); // Skip past "## Returns"
+ const nextHeadingMatch = afterReturns.match(/\n## /);
+ const returnsEnd =
+ nextHeadingMatch && typeof nextHeadingMatch.index === 'number'
+ ? returnsStart + 10 + nextHeadingMatch.index
+ : content.length;
+
+ // Extract the Returns section and trim trailing whitespace
+ const returnsContent = content.slice(returnsStart, returnsEnd).trimEnd();
+
+ // Generate the new filename: use-auth.mdx -> use-auth-return.mdx
+ const fileName = path.basename(filePath, '.mdx');
+ const dirName = path.dirname(filePath);
+ const newFilePath = path.join(dirName, `${fileName}-return.mdx`);
+
+ // Write the extracted Returns section to the new file
+ fs.writeFileSync(newFilePath, returnsContent, 'utf-8');
+
+ console.log(`[extract-returns] Created ${path.relative(process.cwd(), newFilePath)}`);
+ return true;
+}
+
+/**
+ * Replaces generic type names in the parameters table with expanded types.
+ * @param {string} content
+ * @returns {string}
+ */
+function replaceGenericTypesInParamsTable(content) {
+ // Replace Fetcher in the parameters table
+ content = content.replace(
+ /(\|\s*`fetcher`\s*\|\s*)`Fetcher`(\s*\|)/g,
+ '$1`Fetcher extends (...args: any[]) => Promise<any>`$2',
+ );
+ return content;
+}
+
+/**
+ * Extracts the "## Parameters" section from a markdown file and writes it to a separate file.
+ * @param {string} filePath - The path to the markdown file
+ * @returns {boolean} True if a file was created
+ */
+function extractParametersSection(filePath) {
+ const content = fs.readFileSync(filePath, 'utf-8');
+ const fileName = path.basename(filePath, '.mdx');
+ const dirName = path.dirname(filePath);
+
+ // Always use -params suffix
+ const suffix = '-params';
+ const targetFileName = `${fileName}${suffix}.mdx`;
+ const propsFileName = `${fileName}-props.mdx`;
+
+ // Delete any existing -props file (TypeDoc-generated)
+ const propsFilePath = path.join(dirName, propsFileName);
+ if (fs.existsSync(propsFilePath)) {
+ fs.unlinkSync(propsFilePath);
+ console.log(`[extract-returns] Deleted ${path.relative(process.cwd(), propsFilePath)}`);
+ }
+
+ // Find the "## Parameters" section
+ const paramsStart = content.indexOf('## Parameters');
+
+ if (paramsStart === -1) {
+ return false; // No Parameters section found
+ }
+
+ // Find the next heading after "## Parameters" (or end of file)
+ const afterParams = content.slice(paramsStart + 13); // Skip past "## Parameters"
+ const nextHeadingMatch = afterParams.match(/\n## /);
+ const paramsEnd =
+ nextHeadingMatch && typeof nextHeadingMatch.index === 'number'
+ ? paramsStart + 13 + nextHeadingMatch.index
+ : content.length;
+
+ // Extract the Parameters section and trim trailing whitespace
+ const paramsContent = content.slice(paramsStart, paramsEnd).trimEnd();
+ const processedParams = replaceGenericTypesInParamsTable(paramsContent);
+
+ // Write to new file
+ const newFilePath = path.join(dirName, targetFileName);
+ fs.writeFileSync(newFilePath, processedParams, 'utf-8');
+
+ console.log(`[extract-returns] Created ${path.relative(process.cwd(), newFilePath)}`);
+ return true;
+}
+
+/**
+ * Recursively reads all .mdx files in a directory, excluding generated files
+ * @param {string} dir - The directory to read
+ * @returns {string[]} Array of file paths
+ */
+function getAllMdxFiles(dir) {
+ /** @type {string[]} */
+ const files = [];
+
+ if (!fs.existsSync(dir)) {
+ return files;
+ }
+
+ const entries = fs.readdirSync(dir, { withFileTypes: true });
+
+ for (const entry of entries) {
+ const fullPath = path.join(dir, entry.name);
+
+ if (entry.isDirectory()) {
+ files.push(...getAllMdxFiles(fullPath));
+ } else if (entry.isFile() && entry.name.endsWith('.mdx')) {
+ // Exclude generated files
+ const isGenerated =
+ entry.name.endsWith('-return.mdx') || entry.name.endsWith('-params.mdx') || entry.name.endsWith('-props.mdx');
+ if (!isGenerated) {
+ files.push(fullPath);
+ }
+ }
+ }
+
+ return files;
+}
+
+/**
+ * Main function to process all clerk-react files
+ */
+function main() {
+ const packages = ['clerk-react'];
+ const dirs = packages.map(folder => path.join(__dirname, 'temp-docs', folder));
+
+ for (const dir of dirs) {
+ if (!fs.existsSync(dir)) {
+ console.log(`[extract-returns] ${dir} directory not found, skipping extraction`);
+ continue;
+ }
+
+ const mdxFiles = getAllMdxFiles(dir);
+ console.log(`[extract-returns] Processing ${mdxFiles.length} files in ${dir}/`);
+
+ let returnsCount = 0;
+ let paramsCount = 0;
+
+ for (const filePath of mdxFiles) {
+ // Extract Returns sections
+ if (extractReturnsSection(filePath)) {
+ returnsCount++;
+ }
+
+ // Extract Parameters sections
+ if (extractParametersSection(filePath)) {
+ paramsCount++;
+ }
+ }
+
+ console.log(`[extract-returns] Extracted ${returnsCount} Returns sections`);
+ console.log(`[extract-returns] Extracted ${paramsCount} Parameters sections`);
+ }
+}
+
+main();

package.json

@@ -56,7 +56,7 @@
  "test:typedoc": "pnpm typedoc:generate && cd ./.typedoc && vitest run",
  "turbo:clean": "turbo daemon clean",
  "typedoc:generate": "pnpm build:declarations && pnpm typedoc:generate:skip-build",
- "typedoc:generate:skip-build": "typedoc --tsconfig tsconfig.typedoc.json && rm -rf .typedoc/docs && mv .typedoc/temp-docs.typedoc/docs",
+ "typedoc:generate:skip-build": "typedoc --tsconfig tsconfig.typedoc.json && node .typedoc/extract-returns-and-params.mjs && rimraf .typedoc/docs && cpy '.typedoc/temp-docs/**' '.typedoc/docs' && rimraf .typedoc/temp-docs",
  "version-packages": "changeset version && pnpm install --lockfile-only --engine-strict=false",
  "version-packages:canary": "./scripts/canary.mjs",
  "version-packages:snapshot": "./scripts/snapshot.mjs",

packages/shared/src/errors/clerkApiResponseError.ts

@@ -11,6 +11,9 @@ interface ClerkAPIResponseOptions extends Omit<ClerkErrorParams, 'message' | 'co
  retryAfter?: number;
 }
 
+/**
+ * Class representing a Clerk API Response Error.
+ */
 export class ClerkAPIResponseError extends ClerkError implements ClerkAPIResponseErrorInterface {
  static kind = 'ClerkAPIResponseError';
  status: number;

packages/shared/src/react/commerce.tsx

@@ -156,15 +156,27 @@ type internalStripeAppearance = {
  spacingUnit: string;
 };
 
-type PaymentElementProviderProps = {
+/**
+ * @interface
+ */
+export type PaymentElementProviderProps = {
+ /**
+ * An optional checkout resource object. When provided, the payment element is scoped to the specific checkout session.
+ */
  checkout?: BillingCheckoutResource | ReturnType<typeof useCheckout>['checkout'];
+ /**
+ * An optional object to customize the appearance of the Stripe Payment Element. This allows you to match the form's styling to your application's theme.
+ */
  stripeAppearance?: internalStripeAppearance;
  /**
- * Default to `user` if not provided.
+ * Specifies whether to fetch for the current user or organization.
  *
  * @default 'user'
  */
  for?: ForPayerType;
+ /**
+ * An optional description to display to the user within the payment element UI.
+ */
  paymentDescription?: string;
 };
 
@@ -248,7 +260,17 @@ const PaymentElementInternalRoot = (props: PropsWithChildren) => {
  return <DummyStripeUtils>{props.children}</DummyStripeUtils>;
 };
 
-const PaymentElement = ({ fallback }: { fallback?: ReactNode }) => {
+/**
+ * @interface
+ */
+export type PaymentElementProps = {
+ /**
+ * Optional fallback content, such as a loading skeleton, to display while the payment form is being initialized.
+ */
+ fallback?: ReactNode;
+};
+
+const PaymentElement = ({ fallback }: PaymentElementProps) => {
  const {
  setIsPaymentElementReady,
  paymentMethodOrder,
@@ -315,7 +337,13 @@ const throwLibsMissingError = () => {
  );
 };
 
-type UsePaymentElementReturn = {
+/**
+ * @interface
+ */
+export type UsePaymentElementReturn = {
+ /**
+ * A function that submits the payment form data to the payment provider. It returns a promise that resolves with either a `data` object containing a payment token on success, or an `error` object on failure.
+ */
  submit: () => Promise<
  | {
  data: { gateway: 'stripe'; paymentToken: string };
@@ -326,13 +354,25 @@ type UsePaymentElementReturn = {
  error: PaymentElementError;
  }
  >;
+ /**
+ * A function that resets the payment form to its initial, empty state.
+ */
  reset: () => Promise<void>;
+ /**
+ * A boolean that indicates if the payment form UI has been rendered and is ready for user input. This is useful for disabling a submit button until the form is interactive.
+ */
  isFormReady: boolean;
 } & (
  | {
+ /**
+ * An object containing information about the initialized payment provider. It is `undefined` until `isProviderReady` is `true`.
+ */
  provider: {
  name: 'stripe';
  };
+ /**
+ * A boolean that indicates if the underlying payment provider (e.g. Stripe) has been fully initialized.
+ */
  isProviderReady: true;
  }
  | {

packages/shared/src/react/contexts.tsx

@@ -25,9 +25,23 @@ const [SessionContext, useSessionContext] = createContextAndHook<SignedInSession
 
 const OptionsContext = React.createContext<ClerkOptions>({});
 
-type UseCheckoutOptions = {
+/**
+ * @interface
+ */
+export type UseCheckoutOptions = {
+ /**
+ * Specifies if the checkout is for an organization.
+ *
+ * @default 'user'
+ */
  for?: ForPayerType;
+ /**
+ * The billing period for the plan.
+ */
  planPeriod: BillingSubscriptionPlanPeriod;
+ /**
+ * The ID of the subscription plan to check out (e.g. `cplan_xxx`).
+ */
  planId: string;
 };
 

.changeset/violet-boxes-watch.md

@@ -0,0 +1,6 @@
+---
+'@clerk/shared': minor
+'@clerk/types': minor
+---
+
+Ensure all hooks use typedoc for clerk docs

.typedoc/custom-plugin.mjs

@@ -10,7 +10,6 @@ const FILES_WITHOUT_HEADINGS = [
  'use-organization-params.mdx',
  'paginated-resources.mdx',
  'pages-or-infinite-options.mdx',
- 'pages-or-infinite-options.mdx',
  'paginated-hook-config.mdx',
  'use-organization-list-return.mdx',
  'use-organization-list-params.mdx',
@@ -19,6 +18,21 @@ const FILES_WITHOUT_HEADINGS = [
  'verify-token-options.mdx',
  'public-organization-data-json.mdx',
  'organization-membership-public-user-data.mdx',
+ 'use-checkout-return.mdx',
+ 'use-checkout-options.mdx',
+ 'use-payment-element-return.mdx',
+ 'use-payment-methods-return.mdx',
+ 'use-payment-attempts-return.mdx',
+ 'use-plans-return.mdx',
+ 'use-statements-return.mdx',
+ 'hook-params.mdx',
+ 'use-subscription-params.mdx',
+ 'subscription-result.mdx',
+ 'needs-reverification-parameters.mdx',
+ 'use-reverification-options.mdx',
+ 'use-reverification-params.mdx',
+ 'payment-element-provider-props.mdx',
+ 'payment-element-props.mdx',
 ];
 
 /**
@@ -29,6 +43,8 @@ const LINK_REPLACEMENTS = [
  ['set-active-params', '/docs/reference/javascript/types/set-active-params'],
  ['clerk-paginated-response', '/docs/reference/javascript/types/clerk-paginated-response'],
  ['paginated-resources', '#paginated-resources'],
+ ['use-checkout-options', '#use-checkout-options'],
+ ['needs-reverification-parameters', '#needs-reverification-parameters'],
  ['create-organization-params', '#create-organization-params'],
  ['session-resource', '/docs/reference/javascript/session'],
  ['signed-in-session-resource', '/docs/reference/javascript/session'],
@@ -62,13 +78,18 @@ const LINK_REPLACEMENTS = [
  ['billing-payer-resource', '/docs/reference/javascript/types/billing-payer-resource'],
  ['billing-plan-resource', '/docs/reference/javascript/types/billing-plan-resource'],
  ['billing-checkout-totals', '/docs/reference/javascript/types/billing-checkout-totals'],
+ ['billing-checkout-resource', '/docs/reference/javascript/types/billing-checkout-resource'],
  ['billing-money-amount', '/docs/reference/javascript/types/billing-money-amount'],
  ['billing-subscription-item-resource', '/docs/reference/javascript/types/billing-subscription-item-resource'],
  ['feature-resource', '/docs/reference/javascript/types/feature-resource'],
  ['billing-statement-group', '/docs/reference/javascript/types/billing-statement-group'],
+ ['billing-statement-resource', '/docs/reference/javascript/types/billing-statement-resource'],
+ ['billing-subscription-resource', '/docs/reference/javascript/types/billing-subscription-resource'],
+ ['clerk-api-response-error', '/docs/reference/javascript/types/clerk-api-response-error'],
  ['billing-statement-totals', '/docs/reference/javascript/types/billing-statement-totals'],
  ['billing-payment-resource', '/docs/reference/javascript/types/billing-payment-resource'],
  ['deleted-object-resource', '/docs/reference/javascript/types/deleted-object-resource'],
+ ['use-checkout-return', '/docs/reference/hooks/use-checkout#returns'],
 ];
 
 /**

.typedoc/extract-returns-and-params.mjs

@@ -0,0 +1,179 @@
+// @ts-check
+import fs from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = path.dirname(__filename);
+
+/**
+ * Extracts the "## Returns" section from a markdown file and writes it to a separate file.
+ * @param {string} filePath - The path to the markdown file
+ * @returns {boolean} True if a file was created
+ */
+function extractReturnsSection(filePath) {
+ const content = fs.readFileSync(filePath, 'utf-8');
+
+ // Find the "## Returns" section
+ const returnsStart = content.indexOf('## Returns');
+
+ if (returnsStart === -1) {
+ return false; // No Returns section found
+ }
+
+ // Find the next heading after "## Returns" (or end of file)
+ const afterReturns = content.slice(returnsStart + 10); // Skip past "## Returns"
+ const nextHeadingMatch = afterReturns.match(/\n## /);
+ const returnsEnd =
+ nextHeadingMatch && typeof nextHeadingMatch.index === 'number'
+ ? returnsStart + 10 + nextHeadingMatch.index
+ : content.length;
+
+ // Extract the Returns section and trim trailing whitespace
+ const returnsContent = content.slice(returnsStart, returnsEnd).trimEnd();
+
+ // Generate the new filename: use-auth.mdx -> use-auth-return.mdx
+ const fileName = path.basename(filePath, '.mdx');
+ const dirName = path.dirname(filePath);
+ const newFilePath = path.join(dirName, `${fileName}-return.mdx`);
+
+ // Write the extracted Returns section to the new file
+ fs.writeFileSync(newFilePath, returnsContent, 'utf-8');
+
+ console.log(`[extract-returns] Created ${path.relative(process.cwd(), newFilePath)}`);
+ return true;
+}
+
+/**
+ * Replaces generic type names in the parameters table with expanded types.
+ * @param {string} content
+ * @returns {string}
+ */
+function replaceGenericTypesInParamsTable(content) {
+ // Replace Fetcher in the parameters table
+ content = content.replace(
+ /(\|\s*`fetcher`\s*\|\s*)`Fetcher`(\s*\|)/g,
+ '$1`Fetcher extends (...args: any[]) => Promise<any>`$2',
+ );
+ return content;
+}
+
+/**
+ * Extracts the "## Parameters" section from a markdown file and writes it to a separate file.
+ * @param {string} filePath - The path to the markdown file
+ * @returns {boolean} True if a file was created
+ */
+function extractParametersSection(filePath) {
+ const content = fs.readFileSync(filePath, 'utf-8');
+ const fileName = path.basename(filePath, '.mdx');
+ const dirName = path.dirname(filePath);
+
+ // Always use -params suffix
+ const suffix = '-params';
+ const targetFileName = `${fileName}${suffix}.mdx`;
+ const propsFileName = `${fileName}-props.mdx`;
+
+ // Delete any existing -props file (TypeDoc-generated)
+ const propsFilePath = path.join(dirName, propsFileName);
+ if (fs.existsSync(propsFilePath)) {
+ fs.unlinkSync(propsFilePath);
+ console.log(`[extract-returns] Deleted ${path.relative(process.cwd(), propsFilePath)}`);
+ }
+
+ // Find the "## Parameters" section
+ const paramsStart = content.indexOf('## Parameters');
+
+ if (paramsStart === -1) {
+ return false; // No Parameters section found
+ }
+
+ // Find the next heading after "## Parameters" (or end of file)
+ const afterParams = content.slice(paramsStart + 13); // Skip past "## Parameters"
+ const nextHeadingMatch = afterParams.match(/\n## /);
+ const paramsEnd =
+ nextHeadingMatch && typeof nextHeadingMatch.index === 'number'
+ ? paramsStart + 13 + nextHeadingMatch.index
+ : content.length;
+
+ // Extract the Parameters section and trim trailing whitespace
+ const paramsContent = content.slice(paramsStart, paramsEnd).trimEnd();
+ const processedParams = replaceGenericTypesInParamsTable(paramsContent);
+
+ // Write to new file
+ const newFilePath = path.join(dirName, targetFileName);
+ fs.writeFileSync(newFilePath, processedParams, 'utf-8');
+
+ console.log(`[extract-returns] Created ${path.relative(process.cwd(), newFilePath)}`);
+ return true;
+}
+
+/**
+ * Recursively reads all .mdx files in a directory, excluding generated files
+ * @param {string} dir - The directory to read
+ * @returns {string[]} Array of file paths
+ */
+function getAllMdxFiles(dir) {
+ /** @type {string[]} */
+ const files = [];
+
+ if (!fs.existsSync(dir)) {
+ return files;
+ }
+
+ const entries = fs.readdirSync(dir, { withFileTypes: true });
+
+ for (const entry of entries) {
+ const fullPath = path.join(dir, entry.name);
+
+ if (entry.isDirectory()) {
+ files.push(...getAllMdxFiles(fullPath));
+ } else if (entry.isFile() && entry.name.endsWith('.mdx')) {
+ // Exclude generated files
+ const isGenerated =
+ entry.name.endsWith('-return.mdx') || entry.name.endsWith('-params.mdx') || entry.name.endsWith('-props.mdx');
+ if (!isGenerated) {
+ files.push(fullPath);
+ }
+ }
+ }
+
+ return files;
+}
+
+/**
+ * Main function to process all clerk-react files
+ */
+function main() {
+ const packages = ['clerk-react'];
+ const dirs = packages.map(folder => path.join(__dirname, 'temp-docs', folder));
+
+ for (const dir of dirs) {
+ if (!fs.existsSync(dir)) {
+ console.log(`[extract-returns] ${dir} directory not found, skipping extraction`);
+ continue;
+ }
+
+ const mdxFiles = getAllMdxFiles(dir);
+ console.log(`[extract-returns] Processing ${mdxFiles.length} files in ${dir}/`);
+
+ let returnsCount = 0;
+ let paramsCount = 0;
+
+ for (const filePath of mdxFiles) {
+ // Extract Returns sections
+ if (extractReturnsSection(filePath)) {
+ returnsCount++;
+ }
+
+ // Extract Parameters sections
+ if (extractParametersSection(filePath)) {
+ paramsCount++;
+ }
+ }
+
+ console.log(`[extract-returns] Extracted ${returnsCount} Returns sections`);
+ console.log(`[extract-returns] Extracted ${paramsCount} Parameters sections`);
+ }
+}
+
+main();

package.json

@@ -56,7 +56,7 @@
  "test:typedoc": "pnpm typedoc:generate && cd ./.typedoc && vitest run",
  "turbo:clean": "turbo daemon clean",
  "typedoc:generate": "pnpm build:declarations && pnpm typedoc:generate:skip-build",
- "typedoc:generate:skip-build": "typedoc --tsconfig tsconfig.typedoc.json && rm -rf .typedoc/docs && mv .typedoc/temp-docs.typedoc/docs",
+ "typedoc:generate:skip-build": "typedoc --tsconfig tsconfig.typedoc.json && node .typedoc/extract-returns-and-params.mjs && rimraf .typedoc/docs && cpy '.typedoc/temp-docs/**' '.typedoc/docs' && rimraf .typedoc/temp-docs",
  "version-packages": "changeset version && pnpm install --lockfile-only --engine-strict=false",
  "version-packages:canary": "./scripts/canary.mjs",
  "version-packages:snapshot": "./scripts/snapshot.mjs",

packages/shared/src/errors/clerkApiResponseError.ts

@@ -11,6 +11,9 @@ interface ClerkAPIResponseOptions extends Omit<ClerkErrorParams, 'message' | 'co
  retryAfter?: number;
 }
 
+/**
+ * Class representing a Clerk API Response Error.
+ */
 export class ClerkAPIResponseError extends ClerkError implements ClerkAPIResponseErrorInterface {
  static kind = 'ClerkAPIResponseError';
  status: number;

packages/shared/src/react/commerce.tsx

@@ -156,15 +156,27 @@ type internalStripeAppearance = {
  spacingUnit: string;
 };
 
-type PaymentElementProviderProps = {
+/**
+ * @interface
+ */
+export type PaymentElementProviderProps = {
+ /**
+ * An optional checkout resource object. When provided, the payment element is scoped to the specific checkout session.
+ */
  checkout?: BillingCheckoutResource | ReturnType<typeof useCheckout>['checkout'];
+ /**
+ * An optional object to customize the appearance of the Stripe Payment Element. This allows you to match the form's styling to your application's theme.
+ */
  stripeAppearance?: internalStripeAppearance;
  /**
- * Default to `user` if not provided.
+ * Specifies whether to fetch for the current user or organization.
  *
  * @default 'user'
  */
  for?: ForPayerType;
+ /**
+ * An optional description to display to the user within the payment element UI.
+ */
  paymentDescription?: string;
 };
 
@@ -248,7 +260,17 @@ const PaymentElementInternalRoot = (props: PropsWithChildren) => {
  return <DummyStripeUtils>{props.children}</DummyStripeUtils>;
 };
 
-const PaymentElement = ({ fallback }: { fallback?: ReactNode }) => {
+/**
+ * @interface
+ */
+export type PaymentElementProps = {
+ /**
+ * Optional fallback content, such as a loading skeleton, to display while the payment form is being initialized.
+ */
+ fallback?: ReactNode;
+};
+
+const PaymentElement = ({ fallback }: PaymentElementProps) => {
  const {
  setIsPaymentElementReady,
  paymentMethodOrder,
@@ -315,7 +337,13 @@ const throwLibsMissingError = () => {
  );
 };
 
-type UsePaymentElementReturn = {
+/**
+ * @interface
+ */
+export type UsePaymentElementReturn = {
+ /**
+ * A function that submits the payment form data to the payment provider. It returns a promise that resolves with either a `data` object containing a payment token on success, or an `error` object on failure.
+ */
  submit: () => Promise<
  | {
  data: { gateway: 'stripe'; paymentToken: string };
@@ -326,13 +354,25 @@ type UsePaymentElementReturn = {
  error: PaymentElementError;
  }
  >;
+ /**
+ * A function that resets the payment form to its initial, empty state.
+ */
  reset: () => Promise<void>;
+ /**
+ * A boolean that indicates if the payment form UI has been rendered and is ready for user input. This is useful for disabling a submit button until the form is interactive.
+ */
  isFormReady: boolean;
 } & (
  | {
+ /**
+ * An object containing information about the initialized payment provider. It is `undefined` until `isProviderReady` is `true`.
+ */
  provider: {
  name: 'stripe';
  };
+ /**
+ * A boolean that indicates if the underlying payment provider (e.g. Stripe) has been fully initialized.
+ */
  isProviderReady: true;
  }
  | {

packages/shared/src/react/contexts.tsx

@@ -25,9 +25,23 @@ const [SessionContext, useSessionContext] = createContextAndHook<SignedInSession
 
 const OptionsContext = React.createContext<ClerkOptions>({});
 
-type UseCheckoutOptions = {
+/**
+ * @interface
+ */
+export type UseCheckoutOptions = {
+ /**
+ * Specifies if the checkout is for an organization.
+ *
+ * @default 'user'
+ */
  for?: ForPayerType;
+ /**
+ * The billing period for the plan.
+ */
  planPeriod: BillingSubscriptionPlanPeriod;
+ /**
+ * The ID of the subscription plan to check out (e.g. `cplan_xxx`).
+ */
  planId: string;
 };
 

.changeset/violet-boxes-watch.md

@@ -0,0 +1,6 @@
+---
+'@clerk/shared': minor
+'@clerk/types': minor
+---
+
+Ensure all hooks use typedoc for clerk docs

.typedoc/custom-plugin.mjs

@@ -10,7 +10,6 @@ const FILES_WITHOUT_HEADINGS = [
  'use-organization-params.mdx',
  'paginated-resources.mdx',
  'pages-or-infinite-options.mdx',
- 'pages-or-infinite-options.mdx',
  'paginated-hook-config.mdx',
  'use-organization-list-return.mdx',
  'use-organization-list-params.mdx',
@@ -19,6 +18,21 @@ const FILES_WITHOUT_HEADINGS = [
  'verify-token-options.mdx',
  'public-organization-data-json.mdx',
  'organization-membership-public-user-data.mdx',
+ 'use-checkout-return.mdx',
+ 'use-checkout-options.mdx',
+ 'use-payment-element-return.mdx',
+ 'use-payment-methods-return.mdx',
+ 'use-payment-attempts-return.mdx',
+ 'use-plans-return.mdx',
+ 'use-statements-return.mdx',
+ 'hook-params.mdx',
+ 'use-subscription-params.mdx',
+ 'subscription-result.mdx',
+ 'needs-reverification-parameters.mdx',
+ 'use-reverification-options.mdx',
+ 'use-reverification-params.mdx',
+ 'payment-element-provider-props.mdx',
+ 'payment-element-props.mdx',
 ];
 
 /**
@@ -29,6 +43,8 @@ const LINK_REPLACEMENTS = [
  ['set-active-params', '/docs/reference/javascript/types/set-active-params'],
  ['clerk-paginated-response', '/docs/reference/javascript/types/clerk-paginated-response'],
  ['paginated-resources', '#paginated-resources'],
+ ['use-checkout-options', '#use-checkout-options'],
+ ['needs-reverification-parameters', '#needs-reverification-parameters'],
  ['create-organization-params', '#create-organization-params'],
  ['session-resource', '/docs/reference/javascript/session'],
  ['signed-in-session-resource', '/docs/reference/javascript/session'],
@@ -62,13 +78,18 @@ const LINK_REPLACEMENTS = [
  ['billing-payer-resource', '/docs/reference/javascript/types/billing-payer-resource'],
  ['billing-plan-resource', '/docs/reference/javascript/types/billing-plan-resource'],
  ['billing-checkout-totals', '/docs/reference/javascript/types/billing-checkout-totals'],
+ ['billing-checkout-resource', '/docs/reference/javascript/types/billing-checkout-resource'],
  ['billing-money-amount', '/docs/reference/javascript/types/billing-money-amount'],
  ['billing-subscription-item-resource', '/docs/reference/javascript/types/billing-subscription-item-resource'],
  ['feature-resource', '/docs/reference/javascript/types/feature-resource'],
  ['billing-statement-group', '/docs/reference/javascript/types/billing-statement-group'],
+ ['billing-statement-resource', '/docs/reference/javascript/types/billing-statement-resource'],
+ ['billing-subscription-resource', '/docs/reference/javascript/types/billing-subscription-resource'],
+ ['clerk-api-response-error', '/docs/reference/javascript/types/clerk-api-response-error'],
  ['billing-statement-totals', '/docs/reference/javascript/types/billing-statement-totals'],
  ['billing-payment-resource', '/docs/reference/javascript/types/billing-payment-resource'],
  ['deleted-object-resource', '/docs/reference/javascript/types/deleted-object-resource'],
+ ['use-checkout-return', '/docs/reference/hooks/use-checkout#returns'],
 ];
 
 /**

.typedoc/extract-returns-and-params.mjs

@@ -0,0 +1,179 @@
+// @ts-check
+import fs from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = path.dirname(__filename);
+
+/**
+ * Extracts the "## Returns" section from a markdown file and writes it to a separate file.
+ * @param {string} filePath - The path to the markdown file
+ * @returns {boolean} True if a file was created
+ */
+function extractReturnsSection(filePath) {
+ const content = fs.readFileSync(filePath, 'utf-8');
+
+ // Find the "## Returns" section
+ const returnsStart = content.indexOf('## Returns');
+
+ if (returnsStart === -1) {
+ return false; // No Returns section found
+ }
+
+ // Find the next heading after "## Returns" (or end of file)
+ const afterReturns = content.slice(returnsStart + 10); // Skip past "## Returns"
+ const nextHeadingMatch = afterReturns.match(/\n## /);
+ const returnsEnd =
+ nextHeadingMatch && typeof nextHeadingMatch.index === 'number'
+ ? returnsStart + 10 + nextHeadingMatch.index
+ : content.length;
+
+ // Extract the Returns section and trim trailing whitespace
+ const returnsContent = content.slice(returnsStart, returnsEnd).trimEnd();
+
+ // Generate the new filename: use-auth.mdx -> use-auth-return.mdx
+ const fileName = path.basename(filePath, '.mdx');
+ const dirName = path.dirname(filePath);
+ const newFilePath = path.join(dirName, `${fileName}-return.mdx`);
+
+ // Write the extracted Returns section to the new file
+ fs.writeFileSync(newFilePath, returnsContent, 'utf-8');
+
+ console.log(`[extract-returns] Created ${path.relative(process.cwd(), newFilePath)}`);
+ return true;
+}
+
+/**
+ * Replaces generic type names in the parameters table with expanded types.
+ * @param {string} content
+ * @returns {string}
+ */
+function replaceGenericTypesInParamsTable(content) {
+ // Replace Fetcher in the parameters table
+ content = content.replace(
+ /(\|\s*`fetcher`\s*\|\s*)`Fetcher`(\s*\|)/g,
+ '$1`Fetcher extends (...args: any[]) => Promise<any>`$2',
+ );
+ return content;
+}
+
+/**
+ * Extracts the "## Parameters" section from a markdown file and writes it to a separate file.
+ * @param {string} filePath - The path to the markdown file
+ * @returns {boolean} True if a file was created
+ */
+function extractParametersSection(filePath) {
+ const content = fs.readFileSync(filePath, 'utf-8');
+ const fileName = path.basename(filePath, '.mdx');
+ const dirName = path.dirname(filePath);
+
+ // Always use -params suffix
+ const suffix = '-params';
+ const targetFileName = `${fileName}${suffix}.mdx`;
+ const propsFileName = `${fileName}-props.mdx`;
+
+ // Delete any existing -props file (TypeDoc-generated)
+ const propsFilePath = path.join(dirName, propsFileName);
+ if (fs.existsSync(propsFilePath)) {
+ fs.unlinkSync(propsFilePath);
+ console.log(`[extract-returns] Deleted ${path.relative(process.cwd(), propsFilePath)}`);
+ }
+
+ // Find the "## Parameters" section
+ const paramsStart = content.indexOf('## Parameters');
+
+ if (paramsStart === -1) {
+ return false; // No Parameters section found
+ }
+
+ // Find the next heading after "## Parameters" (or end of file)
+ const afterParams = content.slice(paramsStart + 13); // Skip past "## Parameters"
+ const nextHeadingMatch = afterParams.match(/\n## /);
+ const paramsEnd =
+ nextHeadingMatch && typeof nextHeadingMatch.index === 'number'
+ ? paramsStart + 13 + nextHeadingMatch.index
+ : content.length;
+
+ // Extract the Parameters section and trim trailing whitespace
+ const paramsContent = content.slice(paramsStart, paramsEnd).trimEnd();
+ const processedParams = replaceGenericTypesInParamsTable(paramsContent);
+
+ // Write to new file
+ const newFilePath = path.join(dirName, targetFileName);
+ fs.writeFileSync(newFilePath, processedParams, 'utf-8');
+
+ console.log(`[extract-returns] Created ${path.relative(process.cwd(), newFilePath)}`);
+ return true;
+}
+
+/**
+ * Recursively reads all .mdx files in a directory, excluding generated files
+ * @param {string} dir - The directory to read
+ * @returns {string[]} Array of file paths
+ */
+function getAllMdxFiles(dir) {
+ /** @type {string[]} */
+ const files = [];
+
+ if (!fs.existsSync(dir)) {
+ return files;
+ }
+
+ const entries = fs.readdirSync(dir, { withFileTypes: true });
+
+ for (const entry of entries) {
+ const fullPath = path.join(dir, entry.name);
+
+ if (entry.isDirectory()) {
+ files.push(...getAllMdxFiles(fullPath));
+ } else if (entry.isFile() && entry.name.endsWith('.mdx')) {
+ // Exclude generated files
+ const isGenerated =
+ entry.name.endsWith('-return.mdx') || entry.name.endsWith('-params.mdx') || entry.name.endsWith('-props.mdx');
+ if (!isGenerated) {
+ files.push(fullPath);
+ }
+ }
+ }
+
+ return files;
+}
+
+/**
+ * Main function to process all clerk-react files
+ */
+function main() {
+ const packages = ['clerk-react'];
+ const dirs = packages.map(folder => path.join(__dirname, 'temp-docs', folder));
+
+ for (const dir of dirs) {
+ if (!fs.existsSync(dir)) {
+ console.log(`[extract-returns] ${dir} directory not found, skipping extraction`);
+ continue;
+ }
+
+ const mdxFiles = getAllMdxFiles(dir);
+ console.log(`[extract-returns] Processing ${mdxFiles.length} files in ${dir}/`);
+
+ let returnsCount = 0;
+ let paramsCount = 0;
+
+ for (const filePath of mdxFiles) {
+ // Extract Returns sections
+ if (extractReturnsSection(filePath)) {
+ returnsCount++;
+ }
+
+ // Extract Parameters sections
+ if (extractParametersSection(filePath)) {
+ paramsCount++;
+ }
+ }
+
+ console.log(`[extract-returns] Extracted ${returnsCount} Returns sections`);
+ console.log(`[extract-returns] Extracted ${paramsCount} Parameters sections`);
+ }
+}
+
+main();

package.json

@@ -56,7 +56,7 @@
  "test:typedoc": "pnpm typedoc:generate && cd ./.typedoc && vitest run",
  "turbo:clean": "turbo daemon clean",
  "typedoc:generate": "pnpm build:declarations && pnpm typedoc:generate:skip-build",
- "typedoc:generate:skip-build": "typedoc --tsconfig tsconfig.typedoc.json && rm -rf .typedoc/docs && mv .typedoc/temp-docs.typedoc/docs",
+ "typedoc:generate:skip-build": "typedoc --tsconfig tsconfig.typedoc.json && node .typedoc/extract-returns-and-params.mjs && rimraf .typedoc/docs && cpy '.typedoc/temp-docs/**' '.typedoc/docs' && rimraf .typedoc/temp-docs",
  "version-packages": "changeset version && pnpm install --lockfile-only --engine-strict=false",
  "version-packages:canary": "./scripts/canary.mjs",
  "version-packages:snapshot": "./scripts/snapshot.mjs",

packages/shared/src/errors/clerkApiResponseError.ts

@@ -11,6 +11,9 @@ interface ClerkAPIResponseOptions extends Omit<ClerkErrorParams, 'message' | 'co
  retryAfter?: number;
 }
 
+/**
+ * Class representing a Clerk API Response Error.
+ */
 export class ClerkAPIResponseError extends ClerkError implements ClerkAPIResponseErrorInterface {
  static kind = 'ClerkAPIResponseError';
  status: number;

packages/shared/src/react/commerce.tsx

@@ -156,15 +156,27 @@ type internalStripeAppearance = {
  spacingUnit: string;
 };
 
-type PaymentElementProviderProps = {
+/**
+ * @interface
+ */
+export type PaymentElementProviderProps = {
+ /**
+ * An optional checkout resource object. When provided, the payment element is scoped to the specific checkout session.
+ */
  checkout?: BillingCheckoutResource | ReturnType<typeof useCheckout>['checkout'];
+ /**
+ * An optional object to customize the appearance of the Stripe Payment Element. This allows you to match the form's styling to your application's theme.
+ */
  stripeAppearance?: internalStripeAppearance;
  /**
- * Default to `user` if not provided.
+ * Specifies whether to fetch for the current user or organization.
  *
  * @default 'user'
  */
  for?: ForPayerType;
+ /**
+ * An optional description to display to the user within the payment element UI.
+ */
  paymentDescription?: string;
 };
 
@@ -248,7 +260,17 @@ const PaymentElementInternalRoot = (props: PropsWithChildren) => {
  return <DummyStripeUtils>{props.children}</DummyStripeUtils>;
 };
 
-const PaymentElement = ({ fallback }: { fallback?: ReactNode }) => {
+/**
+ * @interface
+ */
+export type PaymentElementProps = {
+ /**
+ * Optional fallback content, such as a loading skeleton, to display while the payment form is being initialized.
+ */
+ fallback?: ReactNode;
+};
+
+const PaymentElement = ({ fallback }: PaymentElementProps) => {
  const {
  setIsPaymentElementReady,
  paymentMethodOrder,
@@ -315,7 +337,13 @@ const throwLibsMissingError = () => {
  );
 };
 
-type UsePaymentElementReturn = {
+/**
+ * @interface
+ */
+export type UsePaymentElementReturn = {
+ /**
+ * A function that submits the payment form data to the payment provider. It returns a promise that resolves with either a `data` object containing a payment token on success, or an `error` object on failure.
+ */
  submit: () => Promise<
  | {
  data: { gateway: 'stripe'; paymentToken: string };
@@ -326,13 +354,25 @@ type UsePaymentElementReturn = {
  error: PaymentElementError;
  }
  >;
+ /**
+ * A function that resets the payment form to its initial, empty state.
+ */
  reset: () => Promise<void>;
+ /**
+ * A boolean that indicates if the payment form UI has been rendered and is ready for user input. This is useful for disabling a submit button until the form is interactive.
+ */
  isFormReady: boolean;
 } & (
  | {
+ /**
+ * An object containing information about the initialized payment provider. It is `undefined` until `isProviderReady` is `true`.
+ */
  provider: {
  name: 'stripe';
  };
+ /**
+ * A boolean that indicates if the underlying payment provider (e.g. Stripe) has been fully initialized.
+ */
  isProviderReady: true;
  }
  | {

packages/shared/src/react/contexts.tsx

@@ -25,9 +25,23 @@ const [SessionContext, useSessionContext] = createContextAndHook<SignedInSession
 
 const OptionsContext = React.createContext<ClerkOptions>({});
 
-type UseCheckoutOptions = {
+/**
+ * @interface
+ */
+export type UseCheckoutOptions = {
+ /**
+ * Specifies if the checkout is for an organization.
+ *
+ * @default 'user'
+ */
  for?: ForPayerType;
+ /**
+ * The billing period for the plan.
+ */
  planPeriod: BillingSubscriptionPlanPeriod;
+ /**
+ * The ID of the subscription plan to check out (e.g. `cplan_xxx`).
+ */
  planId: string;
 };
 

.changeset/violet-boxes-watch.md

@@ -0,0 +1,6 @@
+---
+'@clerk/shared': minor
+'@clerk/types': minor
+---
+
+Ensure all hooks use typedoc for clerk docs

.typedoc/custom-plugin.mjs

@@ -10,7 +10,6 @@ const FILES_WITHOUT_HEADINGS = [
  'use-organization-params.mdx',
  'paginated-resources.mdx',
  'pages-or-infinite-options.mdx',
- 'pages-or-infinite-options.mdx',
  'paginated-hook-config.mdx',
  'use-organization-list-return.mdx',
  'use-organization-list-params.mdx',
@@ -19,6 +18,21 @@ const FILES_WITHOUT_HEADINGS = [
  'verify-token-options.mdx',
  'public-organization-data-json.mdx',
  'organization-membership-public-user-data.mdx',
+ 'use-checkout-return.mdx',
+ 'use-checkout-options.mdx',
+ 'use-payment-element-return.mdx',
+ 'use-payment-methods-return.mdx',
+ 'use-payment-attempts-return.mdx',
+ 'use-plans-return.mdx',
+ 'use-statements-return.mdx',
+ 'hook-params.mdx',
+ 'use-subscription-params.mdx',
+ 'subscription-result.mdx',
+ 'needs-reverification-parameters.mdx',
+ 'use-reverification-options.mdx',
+ 'use-reverification-params.mdx',
+ 'payment-element-provider-props.mdx',
+ 'payment-element-props.mdx',
 ];
 
 /**
@@ -29,6 +43,8 @@ const LINK_REPLACEMENTS = [
  ['set-active-params', '/docs/reference/javascript/types/set-active-params'],
  ['clerk-paginated-response', '/docs/reference/javascript/types/clerk-paginated-response'],
  ['paginated-resources', '#paginated-resources'],
+ ['use-checkout-options', '#use-checkout-options'],
+ ['needs-reverification-parameters', '#needs-reverification-parameters'],
  ['create-organization-params', '#create-organization-params'],
  ['session-resource', '/docs/reference/javascript/session'],
  ['signed-in-session-resource', '/docs/reference/javascript/session'],
@@ -62,13 +78,18 @@ const LINK_REPLACEMENTS = [
  ['billing-payer-resource', '/docs/reference/javascript/types/billing-payer-resource'],
  ['billing-plan-resource', '/docs/reference/javascript/types/billing-plan-resource'],
  ['billing-checkout-totals', '/docs/reference/javascript/types/billing-checkout-totals'],
+ ['billing-checkout-resource', '/docs/reference/javascript/types/billing-checkout-resource'],
  ['billing-money-amount', '/docs/reference/javascript/types/billing-money-amount'],
  ['billing-subscription-item-resource', '/docs/reference/javascript/types/billing-subscription-item-resource'],
  ['feature-resource', '/docs/reference/javascript/types/feature-resource'],
  ['billing-statement-group', '/docs/reference/javascript/types/billing-statement-group'],
+ ['billing-statement-resource', '/docs/reference/javascript/types/billing-statement-resource'],
+ ['billing-subscription-resource', '/docs/reference/javascript/types/billing-subscription-resource'],
+ ['clerk-api-response-error', '/docs/reference/javascript/types/clerk-api-response-error'],
  ['billing-statement-totals', '/docs/reference/javascript/types/billing-statement-totals'],
  ['billing-payment-resource', '/docs/reference/javascript/types/billing-payment-resource'],
  ['deleted-object-resource', '/docs/reference/javascript/types/deleted-object-resource'],
+ ['use-checkout-return', '/docs/reference/hooks/use-checkout#returns'],
 ];
 
 /**

.typedoc/extract-returns-and-params.mjs

@@ -0,0 +1,179 @@
+// @ts-check
+import fs from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = path.dirname(__filename);
+
+/**
+ * Extracts the "## Returns" section from a markdown file and writes it to a separate file.
+ * @param {string} filePath - The path to the markdown file
+ * @returns {boolean} True if a file was created
+ */
+function extractReturnsSection(filePath) {
+ const content = fs.readFileSync(filePath, 'utf-8');
+
+ // Find the "## Returns" section
+ const returnsStart = content.indexOf('## Returns');
+
+ if (returnsStart === -1) {
+ return false; // No Returns section found
+ }
+
+ // Find the next heading after "## Returns" (or end of file)
+ const afterReturns = content.slice(returnsStart + 10); // Skip past "## Returns"
+ const nextHeadingMatch = afterReturns.match(/\n## /);
+ const returnsEnd =
+ nextHeadingMatch && typeof nextHeadingMatch.index === 'number'
+ ? returnsStart + 10 + nextHeadingMatch.index
+ : content.length;
+
+ // Extract the Returns section and trim trailing whitespace
+ const returnsContent = content.slice(returnsStart, returnsEnd).trimEnd();
+
+ // Generate the new filename: use-auth.mdx -> use-auth-return.mdx
+ const fileName = path.basename(filePath, '.mdx');
+ const dirName = path.dirname(filePath);
+ const newFilePath = path.join(dirName, `${fileName}-return.mdx`);
+
+ // Write the extracted Returns section to the new file
+ fs.writeFileSync(newFilePath, returnsContent, 'utf-8');
+
+ console.log(`[extract-returns] Created ${path.relative(process.cwd(), newFilePath)}`);
+ return true;
+}
+
+/**
+ * Replaces generic type names in the parameters table with expanded types.
+ * @param {string} content
+ * @returns {string}
+ */
+function replaceGenericTypesInParamsTable(content) {
+ // Replace Fetcher in the parameters table
+ content = content.replace(
+ /(\|\s*`fetcher`\s*\|\s*)`Fetcher`(\s*\|)/g,
+ '$1`Fetcher extends (...args: any[]) => Promise<any>`$2',
+ );
+ return content;
+}
+
+/**
+ * Extracts the "## Parameters" section from a markdown file and writes it to a separate file.
+ * @param {string} filePath - The path to the markdown file
+ * @returns {boolean} True if a file was created
+ */
+function extractParametersSection(filePath) {
+ const content = fs.readFileSync(filePath, 'utf-8');
+ const fileName = path.basename(filePath, '.mdx');
+ const dirName = path.dirname(filePath);
+
+ // Always use -params suffix
+ const suffix = '-params';
+ const targetFileName = `${fileName}${suffix}.mdx`;
+ const propsFileName = `${fileName}-props.mdx`;
+
+ // Delete any existing -props file (TypeDoc-generated)
+ const propsFilePath = path.join(dirName, propsFileName);
+ if (fs.existsSync(propsFilePath)) {
+ fs.unlinkSync(propsFilePath);
+ console.log(`[extract-returns] Deleted ${path.relative(process.cwd(), propsFilePath)}`);
+ }
+
+ // Find the "## Parameters" section
+ const paramsStart = content.indexOf('## Parameters');
+
+ if (paramsStart === -1) {
+ return false; // No Parameters section found
+ }
+
+ // Find the next heading after "## Parameters" (or end of file)
+ const afterParams = content.slice(paramsStart + 13); // Skip past "## Parameters"
+ const nextHeadingMatch = afterParams.match(/\n## /);
+ const paramsEnd =
+ nextHeadingMatch && typeof nextHeadingMatch.index === 'number'
+ ? paramsStart + 13 + nextHeadingMatch.index
+ : content.length;
+
+ // Extract the Parameters section and trim trailing whitespace
+ const paramsContent = content.slice(paramsStart, paramsEnd).trimEnd();
+ const processedParams = replaceGenericTypesInParamsTable(paramsContent);
+
+ // Write to new file
+ const newFilePath = path.join(dirName, targetFileName);
+ fs.writeFileSync(newFilePath, processedParams, 'utf-8');
+
+ console.log(`[extract-returns] Created ${path.relative(process.cwd(), newFilePath)}`);
+ return true;
+}
+
+/**
+ * Recursively reads all .mdx files in a directory, excluding generated files
+ * @param {string} dir - The directory to read
+ * @returns {string[]} Array of file paths
+ */
+function getAllMdxFiles(dir) {
+ /** @type {string[]} */
+ const files = [];
+
+ if (!fs.existsSync(dir)) {
+ return files;
+ }
+
+ const entries = fs.readdirSync(dir, { withFileTypes: true });
+
+ for (const entry of entries) {
+ const fullPath = path.join(dir, entry.name);
+
+ if (entry.isDirectory()) {
+ files.push(...getAllMdxFiles(fullPath));
+ } else if (entry.isFile() && entry.name.endsWith('.mdx')) {
+ // Exclude generated files
+ const isGenerated =
+ entry.name.endsWith('-return.mdx') || entry.name.endsWith('-params.mdx') || entry.name.endsWith('-props.mdx');
+ if (!isGenerated) {
+ files.push(fullPath);
+ }
+ }
+ }
+
+ return files;
+}
+
+/**
+ * Main function to process all clerk-react files
+ */
+function main() {
+ const packages = ['clerk-react'];
+ const dirs = packages.map(folder => path.join(__dirname, 'temp-docs', folder));
+
+ for (const dir of dirs) {
+ if (!fs.existsSync(dir)) {
+ console.log(`[extract-returns] ${dir} directory not found, skipping extraction`);
+ continue;
+ }
+
+ const mdxFiles = getAllMdxFiles(dir);
+ console.log(`[extract-returns] Processing ${mdxFiles.length} files in ${dir}/`);
+
+ let returnsCount = 0;
+ let paramsCount = 0;
+
+ for (const filePath of mdxFiles) {
+ // Extract Returns sections
+ if (extractReturnsSection(filePath)) {
+ returnsCount++;
+ }
+
+ // Extract Parameters sections
+ if (extractParametersSection(filePath)) {
+ paramsCount++;
+ }
+ }
+
+ console.log(`[extract-returns] Extracted ${returnsCount} Returns sections`);
+ console.log(`[extract-returns] Extracted ${paramsCount} Parameters sections`);
+ }
+}
+
+main();

package.json

@@ -56,7 +56,7 @@
  "test:typedoc": "pnpm typedoc:generate && cd ./.typedoc && vitest run",
  "turbo:clean": "turbo daemon clean",
  "typedoc:generate": "pnpm build:declarations && pnpm typedoc:generate:skip-build",
- "typedoc:generate:skip-build": "typedoc --tsconfig tsconfig.typedoc.json && rm -rf .typedoc/docs && mv .typedoc/temp-docs.typedoc/docs",
+ "typedoc:generate:skip-build": "typedoc --tsconfig tsconfig.typedoc.json && node .typedoc/extract-returns-and-params.mjs && rimraf .typedoc/docs && cpy '.typedoc/temp-docs/**' '.typedoc/docs' && rimraf .typedoc/temp-docs",
  "version-packages": "changeset version && pnpm install --lockfile-only --engine-strict=false",
  "version-packages:canary": "./scripts/canary.mjs",
  "version-packages:snapshot": "./scripts/snapshot.mjs",

packages/shared/src/errors/clerkApiResponseError.ts

@@ -11,6 +11,9 @@ interface ClerkAPIResponseOptions extends Omit<ClerkErrorParams, 'message' | 'co
  retryAfter?: number;
 }
 
+/**
+ * Class representing a Clerk API Response Error.
+ */
 export class ClerkAPIResponseError extends ClerkError implements ClerkAPIResponseErrorInterface {
  static kind = 'ClerkAPIResponseError';
  status: number;

packages/shared/src/react/commerce.tsx

@@ -156,15 +156,27 @@ type internalStripeAppearance = {
  spacingUnit: string;
 };
 
-type PaymentElementProviderProps = {
+/**
+ * @interface
+ */
+export type PaymentElementProviderProps = {
+ /**
+ * An optional checkout resource object. When provided, the payment element is scoped to the specific checkout session.
+ */
  checkout?: BillingCheckoutResource | ReturnType<typeof useCheckout>['checkout'];
+ /**
+ * An optional object to customize the appearance of the Stripe Payment Element. This allows you to match the form's styling to your application's theme.
+ */
  stripeAppearance?: internalStripeAppearance;
  /**
- * Default to `user` if not provided.
+ * Specifies whether to fetch for the current user or organization.
  *
  * @default 'user'
  */
  for?: ForPayerType;
+ /**
+ * An optional description to display to the user within the payment element UI.
+ */
  paymentDescription?: string;
 };
 
@@ -248,7 +260,17 @@ const PaymentElementInternalRoot = (props: PropsWithChildren) => {
  return <DummyStripeUtils>{props.children}</DummyStripeUtils>;
 };
 
-const PaymentElement = ({ fallback }: { fallback?: ReactNode }) => {
+/**
+ * @interface
+ */
+export type PaymentElementProps = {
+ /**
+ * Optional fallback content, such as a loading skeleton, to display while the payment form is being initialized.
+ */
+ fallback?: ReactNode;
+};
+
+const PaymentElement = ({ fallback }: PaymentElementProps) => {
  const {
  setIsPaymentElementReady,
  paymentMethodOrder,
@@ -315,7 +337,13 @@ const throwLibsMissingError = () => {
  );
 };
 
-type UsePaymentElementReturn = {
+/**
+ * @interface
+ */
+export type UsePaymentElementReturn = {
+ /**
+ * A function that submits the payment form data to the payment provider. It returns a promise that resolves with either a `data` object containing a payment token on success, or an `error` object on failure.
+ */
  submit: () => Promise<
  | {
  data: { gateway: 'stripe'; paymentToken: string };
@@ -326,13 +354,25 @@ type UsePaymentElementReturn = {
  error: PaymentElementError;
  }
  >;
+ /**
+ * A function that resets the payment form to its initial, empty state.
+ */
  reset: () => Promise<void>;
+ /**
+ * A boolean that indicates if the payment form UI has been rendered and is ready for user input. This is useful for disabling a submit button until the form is interactive.
+ */
  isFormReady: boolean;
 } & (
  | {
+ /**
+ * An object containing information about the initialized payment provider. It is `undefined` until `isProviderReady` is `true`.
+ */
  provider: {
  name: 'stripe';
  };
+ /**
+ * A boolean that indicates if the underlying payment provider (e.g. Stripe) has been fully initialized.
+ */
  isProviderReady: true;
  }
  | {

packages/shared/src/react/contexts.tsx

@@ -25,9 +25,23 @@ const [SessionContext, useSessionContext] = createContextAndHook<SignedInSession
 
 const OptionsContext = React.createContext<ClerkOptions>({});
 
-type UseCheckoutOptions = {
+/**
+ * @interface
+ */
+export type UseCheckoutOptions = {
+ /**
+ * Specifies if the checkout is for an organization.
+ *
+ * @default 'user'
+ */
  for?: ForPayerType;
+ /**
+ * The billing period for the plan.
+ */
  planPeriod: BillingSubscriptionPlanPeriod;
+ /**
+ * The ID of the subscription plan to check out (e.g. `cplan_xxx`).
+ */
  planId: string;
 };
 

.changeset/violet-boxes-watch.md

@@ -0,0 +1,6 @@
+---
+'@clerk/shared': minor
+'@clerk/types': minor
+---
+
+Ensure all hooks use typedoc for clerk docs

.typedoc/custom-plugin.mjs

@@ -10,7 +10,6 @@ const FILES_WITHOUT_HEADINGS = [
  'use-organization-params.mdx',
  'paginated-resources.mdx',
  'pages-or-infinite-options.mdx',
- 'pages-or-infinite-options.mdx',
  'paginated-hook-config.mdx',
  'use-organization-list-return.mdx',
  'use-organization-list-params.mdx',
@@ -19,6 +18,21 @@ const FILES_WITHOUT_HEADINGS = [
  'verify-token-options.mdx',
  'public-organization-data-json.mdx',
  'organization-membership-public-user-data.mdx',
+ 'use-checkout-return.mdx',
+ 'use-checkout-options.mdx',
+ 'use-payment-element-return.mdx',
+ 'use-payment-methods-return.mdx',
+ 'use-payment-attempts-return.mdx',
+ 'use-plans-return.mdx',
+ 'use-statements-return.mdx',
+ 'hook-params.mdx',
+ 'use-subscription-params.mdx',
+ 'subscription-result.mdx',
+ 'needs-reverification-parameters.mdx',
+ 'use-reverification-options.mdx',
+ 'use-reverification-params.mdx',
+ 'payment-element-provider-props.mdx',
+ 'payment-element-props.mdx',
 ];
 
 /**
@@ -29,6 +43,8 @@ const LINK_REPLACEMENTS = [
  ['set-active-params', '/docs/reference/javascript/types/set-active-params'],
  ['clerk-paginated-response', '/docs/reference/javascript/types/clerk-paginated-response'],
  ['paginated-resources', '#paginated-resources'],
+ ['use-checkout-options', '#use-checkout-options'],
+ ['needs-reverification-parameters', '#needs-reverification-parameters'],
  ['create-organization-params', '#create-organization-params'],
  ['session-resource', '/docs/reference/javascript/session'],
  ['signed-in-session-resource', '/docs/reference/javascript/session'],
@@ -62,13 +78,18 @@ const LINK_REPLACEMENTS = [
  ['billing-payer-resource', '/docs/reference/javascript/types/billing-payer-resource'],
  ['billing-plan-resource', '/docs/reference/javascript/types/billing-plan-resource'],
  ['billing-checkout-totals', '/docs/reference/javascript/types/billing-checkout-totals'],
+ ['billing-checkout-resource', '/docs/reference/javascript/types/billing-checkout-resource'],
  ['billing-money-amount', '/docs/reference/javascript/types/billing-money-amount'],
  ['billing-subscription-item-resource', '/docs/reference/javascript/types/billing-subscription-item-resource'],
  ['feature-resource', '/docs/reference/javascript/types/feature-resource'],
  ['billing-statement-group', '/docs/reference/javascript/types/billing-statement-group'],
+ ['billing-statement-resource', '/docs/reference/javascript/types/billing-statement-resource'],
+ ['billing-subscription-resource', '/docs/reference/javascript/types/billing-subscription-resource'],
+ ['clerk-api-response-error', '/docs/reference/javascript/types/clerk-api-response-error'],
  ['billing-statement-totals', '/docs/reference/javascript/types/billing-statement-totals'],
  ['billing-payment-resource', '/docs/reference/javascript/types/billing-payment-resource'],
  ['deleted-object-resource', '/docs/reference/javascript/types/deleted-object-resource'],
+ ['use-checkout-return', '/docs/reference/hooks/use-checkout#returns'],
 ];
 
 /**

.typedoc/extract-returns-and-params.mjs

@@ -0,0 +1,179 @@
+// @ts-check
+import fs from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = path.dirname(__filename);
+
+/**
+ * Extracts the "## Returns" section from a markdown file and writes it to a separate file.
+ * @param {string} filePath - The path to the markdown file
+ * @returns {boolean} True if a file was created
+ */
+function extractReturnsSection(filePath) {
+ const content = fs.readFileSync(filePath, 'utf-8');
+
+ // Find the "## Returns" section
+ const returnsStart = content.indexOf('## Returns');
+
+ if (returnsStart === -1) {
+ return false; // No Returns section found
+ }
+
+ // Find the next heading after "## Returns" (or end of file)
+ const afterReturns = content.slice(returnsStart + 10); // Skip past "## Returns"
+ const nextHeadingMatch = afterReturns.match(/\n## /);
+ const returnsEnd =
+ nextHeadingMatch && typeof nextHeadingMatch.index === 'number'
+ ? returnsStart + 10 + nextHeadingMatch.index
+ : content.length;
+
+ // Extract the Returns section and trim trailing whitespace
+ const returnsContent = content.slice(returnsStart, returnsEnd).trimEnd();
+
+ // Generate the new filename: use-auth.mdx -> use-auth-return.mdx
+ const fileName = path.basename(filePath, '.mdx');
+ const dirName = path.dirname(filePath);
+ const newFilePath = path.join(dirName, `${fileName}-return.mdx`);
+
+ // Write the extracted Returns section to the new file
+ fs.writeFileSync(newFilePath, returnsContent, 'utf-8');
+
+ console.log(`[extract-returns] Created ${path.relative(process.cwd(), newFilePath)}`);
+ return true;
+}
+
+/**
+ * Replaces generic type names in the parameters table with expanded types.
+ * @param {string} content
+ * @returns {string}
+ */
+function replaceGenericTypesInParamsTable(content) {
+ // Replace Fetcher in the parameters table
+ content = content.replace(
+ /(\|\s*`fetcher`\s*\|\s*)`Fetcher`(\s*\|)/g,
+ '$1`Fetcher extends (...args: any[]) => Promise<any>`$2',
+ );
+ return content;
+}
+
+/**
+ * Extracts the "## Parameters" section from a markdown file and writes it to a separate file.
+ * @param {string} filePath - The path to the markdown file
+ * @returns {boolean} True if a file was created
+ */
+function extractParametersSection(filePath) {
+ const content = fs.readFileSync(filePath, 'utf-8');
+ const fileName = path.basename(filePath, '.mdx');
+ const dirName = path.dirname(filePath);
+
+ // Always use -params suffix
+ const suffix = '-params';
+ const targetFileName = `${fileName}${suffix}.mdx`;
+ const propsFileName = `${fileName}-props.mdx`;
+
+ // Delete any existing -props file (TypeDoc-generated)
+ const propsFilePath = path.join(dirName, propsFileName);
+ if (fs.existsSync(propsFilePath)) {
+ fs.unlinkSync(propsFilePath);
+ console.log(`[extract-returns] Deleted ${path.relative(process.cwd(), propsFilePath)}`);
+ }
+
+ // Find the "## Parameters" section
+ const paramsStart = content.indexOf('## Parameters');
+
+ if (paramsStart === -1) {
+ return false; // No Parameters section found
+ }
+
+ // Find the next heading after "## Parameters" (or end of file)
+ const afterParams = content.slice(paramsStart + 13); // Skip past "## Parameters"
+ const nextHeadingMatch = afterParams.match(/\n## /);
+ const paramsEnd =
+ nextHeadingMatch && typeof nextHeadingMatch.index === 'number'
+ ? paramsStart + 13 + nextHeadingMatch.index
+ : content.length;
+
+ // Extract the Parameters section and trim trailing whitespace
+ const paramsContent = content.slice(paramsStart, paramsEnd).trimEnd();
+ const processedParams = replaceGenericTypesInParamsTable(paramsContent);
+
+ // Write to new file
+ const newFilePath = path.join(dirName, targetFileName);
+ fs.writeFileSync(newFilePath, processedParams, 'utf-8');
+
+ console.log(`[extract-returns] Created ${path.relative(process.cwd(), newFilePath)}`);
+ return true;
+}
+
+/**
+ * Recursively reads all .mdx files in a directory, excluding generated files
+ * @param {string} dir - The directory to read
+ * @returns {string[]} Array of file paths
+ */
+function getAllMdxFiles(dir) {
+ /** @type {string[]} */
+ const files = [];
+
+ if (!fs.existsSync(dir)) {
+ return files;
+ }
+
+ const entries = fs.readdirSync(dir, { withFileTypes: true });
+
+ for (const entry of entries) {
+ const fullPath = path.join(dir, entry.name);
+
+ if (entry.isDirectory()) {
+ files.push(...getAllMdxFiles(fullPath));
+ } else if (entry.isFile() && entry.name.endsWith('.mdx')) {
+ // Exclude generated files
+ const isGenerated =
+ entry.name.endsWith('-return.mdx') || entry.name.endsWith('-params.mdx') || entry.name.endsWith('-props.mdx');
+ if (!isGenerated) {
+ files.push(fullPath);
+ }
+ }
+ }
+
+ return files;
+}
+
+/**
+ * Main function to process all clerk-react files
+ */
+function main() {
+ const packages = ['clerk-react'];
+ const dirs = packages.map(folder => path.join(__dirname, 'temp-docs', folder));
+
+ for (const dir of dirs) {
+ if (!fs.existsSync(dir)) {
+ console.log(`[extract-returns] ${dir} directory not found, skipping extraction`);
+ continue;
+ }
+
+ const mdxFiles = getAllMdxFiles(dir);
+ console.log(`[extract-returns] Processing ${mdxFiles.length} files in ${dir}/`);
+
+ let returnsCount = 0;
+ let paramsCount = 0;
+
+ for (const filePath of mdxFiles) {
+ // Extract Returns sections
+ if (extractReturnsSection(filePath)) {
+ returnsCount++;
+ }
+
+ // Extract Parameters sections
+ if (extractParametersSection(filePath)) {
+ paramsCount++;
+ }
+ }
+
+ console.log(`[extract-returns] Extracted ${returnsCount} Returns sections`);
+ console.log(`[extract-returns] Extracted ${paramsCount} Parameters sections`);
+ }
+}
+
+main();

package.json

@@ -56,7 +56,7 @@
  "test:typedoc": "pnpm typedoc:generate && cd ./.typedoc && vitest run",
  "turbo:clean": "turbo daemon clean",
  "typedoc:generate": "pnpm build:declarations && pnpm typedoc:generate:skip-build",
- "typedoc:generate:skip-build": "typedoc --tsconfig tsconfig.typedoc.json && rm -rf .typedoc/docs && mv .typedoc/temp-docs.typedoc/docs",
+ "typedoc:generate:skip-build": "typedoc --tsconfig tsconfig.typedoc.json && node .typedoc/extract-returns-and-params.mjs && rimraf .typedoc/docs && cpy '.typedoc/temp-docs/**' '.typedoc/docs' && rimraf .typedoc/temp-docs",
  "version-packages": "changeset version && pnpm install --lockfile-only --engine-strict=false",
  "version-packages:canary": "./scripts/canary.mjs",
  "version-packages:snapshot": "./scripts/snapshot.mjs",

packages/shared/src/errors/clerkApiResponseError.ts

@@ -11,6 +11,9 @@ interface ClerkAPIResponseOptions extends Omit<ClerkErrorParams, 'message' | 'co
  retryAfter?: number;
 }
 
+/**
+ * Class representing a Clerk API Response Error.
+ */
 export class ClerkAPIResponseError extends ClerkError implements ClerkAPIResponseErrorInterface {
  static kind = 'ClerkAPIResponseError';
  status: number;

packages/shared/src/react/commerce.tsx

@@ -156,15 +156,27 @@ type internalStripeAppearance = {
  spacingUnit: string;
 };
 
-type PaymentElementProviderProps = {
+/**
+ * @interface
+ */
+export type PaymentElementProviderProps = {
+ /**
+ * An optional checkout resource object. When provided, the payment element is scoped to the specific checkout session.
+ */
  checkout?: BillingCheckoutResource | ReturnType<typeof useCheckout>['checkout'];
+ /**
+ * An optional object to customize the appearance of the Stripe Payment Element. This allows you to match the form's styling to your application's theme.
+ */
  stripeAppearance?: internalStripeAppearance;
  /**
- * Default to `user` if not provided.
+ * Specifies whether to fetch for the current user or organization.
  *
  * @default 'user'
  */
  for?: ForPayerType;
+ /**
+ * An optional description to display to the user within the payment element UI.
+ */
  paymentDescription?: string;
 };
 
@@ -248,7 +260,17 @@ const PaymentElementInternalRoot = (props: PropsWithChildren) => {
  return <DummyStripeUtils>{props.children}</DummyStripeUtils>;
 };
 
-const PaymentElement = ({ fallback }: { fallback?: ReactNode }) => {
+/**
+ * @interface
+ */
+export type PaymentElementProps = {
+ /**
+ * Optional fallback content, such as a loading skeleton, to display while the payment form is being initialized.
+ */
+ fallback?: ReactNode;
+};
+
+const PaymentElement = ({ fallback }: PaymentElementProps) => {
  const {
  setIsPaymentElementReady,
  paymentMethodOrder,
@@ -315,7 +337,13 @@ const throwLibsMissingError = () => {
  );
 };
 
-type UsePaymentElementReturn = {
+/**
+ * @interface
+ */
+export type UsePaymentElementReturn = {
+ /**
+ * A function that submits the payment form data to the payment provider. It returns a promise that resolves with either a `data` object containing a payment token on success, or an `error` object on failure.
+ */
  submit: () => Promise<
  | {
  data: { gateway: 'stripe'; paymentToken: string };
@@ -326,13 +354,25 @@ type UsePaymentElementReturn = {
  error: PaymentElementError;
  }
  >;
+ /**
+ * A function that resets the payment form to its initial, empty state.
+ */
  reset: () => Promise<void>;
+ /**
+ * A boolean that indicates if the payment form UI has been rendered and is ready for user input. This is useful for disabling a submit button until the form is interactive.
+ */
  isFormReady: boolean;
 } & (
  | {
+ /**
+ * An object containing information about the initialized payment provider. It is `undefined` until `isProviderReady` is `true`.
+ */
  provider: {
  name: 'stripe';
  };
+ /**
+ * A boolean that indicates if the underlying payment provider (e.g. Stripe) has been fully initialized.
+ */
  isProviderReady: true;
  }
  | {

packages/shared/src/react/contexts.tsx

@@ -25,9 +25,23 @@ const [SessionContext, useSessionContext] = createContextAndHook<SignedInSession
 
 const OptionsContext = React.createContext<ClerkOptions>({});
 
-type UseCheckoutOptions = {
+/**
+ * @interface
+ */
+export type UseCheckoutOptions = {
+ /**
+ * Specifies if the checkout is for an organization.
+ *
+ * @default 'user'
+ */
  for?: ForPayerType;
+ /**
+ * The billing period for the plan.
+ */
  planPeriod: BillingSubscriptionPlanPeriod;
+ /**
+ * The ID of the subscription plan to check out (e.g. `cplan_xxx`).
+ */
  planId: string;
 };
 

.changeset/violet-boxes-watch.md

@@ -0,0 +1,6 @@
+---
+'@clerk/shared': minor
+'@clerk/types': minor
+---
+
+Ensure all hooks use typedoc for clerk docs

.typedoc/custom-plugin.mjs

@@ -10,7 +10,6 @@ const FILES_WITHOUT_HEADINGS = [
  'use-organization-params.mdx',
  'paginated-resources.mdx',
  'pages-or-infinite-options.mdx',
- 'pages-or-infinite-options.mdx',
  'paginated-hook-config.mdx',
  'use-organization-list-return.mdx',
  'use-organization-list-params.mdx',
@@ -19,6 +18,21 @@ const FILES_WITHOUT_HEADINGS = [
  'verify-token-options.mdx',
  'public-organization-data-json.mdx',
  'organization-membership-public-user-data.mdx',
+ 'use-checkout-return.mdx',
+ 'use-checkout-options.mdx',
+ 'use-payment-element-return.mdx',
+ 'use-payment-methods-return.mdx',
+ 'use-payment-attempts-return.mdx',
+ 'use-plans-return.mdx',
+ 'use-statements-return.mdx',
+ 'hook-params.mdx',
+ 'use-subscription-params.mdx',
+ 'subscription-result.mdx',
+ 'needs-reverification-parameters.mdx',
+ 'use-reverification-options.mdx',
+ 'use-reverification-params.mdx',
+ 'payment-element-provider-props.mdx',
+ 'payment-element-props.mdx',
 ];
 
 /**
@@ -29,6 +43,8 @@ const LINK_REPLACEMENTS = [
  ['set-active-params', '/docs/reference/javascript/types/set-active-params'],
  ['clerk-paginated-response', '/docs/reference/javascript/types/clerk-paginated-response'],
  ['paginated-resources', '#paginated-resources'],
+ ['use-checkout-options', '#use-checkout-options'],
+ ['needs-reverification-parameters', '#needs-reverification-parameters'],
  ['create-organization-params', '#create-organization-params'],
  ['session-resource', '/docs/reference/javascript/session'],
  ['signed-in-session-resource', '/docs/reference/javascript/session'],
@@ -62,13 +78,18 @@ const LINK_REPLACEMENTS = [
  ['billing-payer-resource', '/docs/reference/javascript/types/billing-payer-resource'],
  ['billing-plan-resource', '/docs/reference/javascript/types/billing-plan-resource'],
  ['billing-checkout-totals', '/docs/reference/javascript/types/billing-checkout-totals'],
+ ['billing-checkout-resource', '/docs/reference/javascript/types/billing-checkout-resource'],
  ['billing-money-amount', '/docs/reference/javascript/types/billing-money-amount'],
  ['billing-subscription-item-resource', '/docs/reference/javascript/types/billing-subscription-item-resource'],
  ['feature-resource', '/docs/reference/javascript/types/feature-resource'],
  ['billing-statement-group', '/docs/reference/javascript/types/billing-statement-group'],
+ ['billing-statement-resource', '/docs/reference/javascript/types/billing-statement-resource'],
+ ['billing-subscription-resource', '/docs/reference/javascript/types/billing-subscription-resource'],
+ ['clerk-api-response-error', '/docs/reference/javascript/types/clerk-api-response-error'],
  ['billing-statement-totals', '/docs/reference/javascript/types/billing-statement-totals'],
  ['billing-payment-resource', '/docs/reference/javascript/types/billing-payment-resource'],
  ['deleted-object-resource', '/docs/reference/javascript/types/deleted-object-resource'],
+ ['use-checkout-return', '/docs/reference/hooks/use-checkout#returns'],
 ];
 
 /**

.typedoc/extract-returns-and-params.mjs

@@ -0,0 +1,179 @@
+// @ts-check
+import fs from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = path.dirname(__filename);
+
+/**
+ * Extracts the "## Returns" section from a markdown file and writes it to a separate file.
+ * @param {string} filePath - The path to the markdown file
+ * @returns {boolean} True if a file was created
+ */
+function extractReturnsSection(filePath) {
+ const content = fs.readFileSync(filePath, 'utf-8');
+
+ // Find the "## Returns" section
+ const returnsStart = content.indexOf('## Returns');
+
+ if (returnsStart === -1) {
+ return false; // No Returns section found
+ }
+
+ // Find the next heading after "## Returns" (or end of file)
+ const afterReturns = content.slice(returnsStart + 10); // Skip past "## Returns"
+ const nextHeadingMatch = afterReturns.match(/\n## /);
+ const returnsEnd =
+ nextHeadingMatch && typeof nextHeadingMatch.index === 'number'
+ ? returnsStart + 10 + nextHeadingMatch.index
+ : content.length;
+
+ // Extract the Returns section and trim trailing whitespace
+ const returnsContent = content.slice(returnsStart, returnsEnd).trimEnd();
+
+ // Generate the new filename: use-auth.mdx -> use-auth-return.mdx
+ const fileName = path.basename(filePath, '.mdx');
+ const dirName = path.dirname(filePath);
+ const newFilePath = path.join(dirName, `${fileName}-return.mdx`);
+
+ // Write the extracted Returns section to the new file
+ fs.writeFileSync(newFilePath, returnsContent, 'utf-8');
+
+ console.log(`[extract-returns] Created ${path.relative(process.cwd(), newFilePath)}`);
+ return true;
+}
+
+/**
+ * Replaces generic type names in the parameters table with expanded types.
+ * @param {string} content
+ * @returns {string}
+ */
+function replaceGenericTypesInParamsTable(content) {
+ // Replace Fetcher in the parameters table
+ content = content.replace(
+ /(\|\s*`fetcher`\s*\|\s*)`Fetcher`(\s*\|)/g,
+ '$1`Fetcher extends (...args: any[]) => Promise<any>`$2',
+ );
+ return content;
+}
+
+/**
+ * Extracts the "## Parameters" section from a markdown file and writes it to a separate file.
+ * @param {string} filePath - The path to the markdown file
+ * @returns {boolean} True if a file was created
+ */
+function extractParametersSection(filePath) {
+ const content = fs.readFileSync(filePath, 'utf-8');
+ const fileName = path.basename(filePath, '.mdx');
+ const dirName = path.dirname(filePath);
+
+ // Always use -params suffix
+ const suffix = '-params';
+ const targetFileName = `${fileName}${suffix}.mdx`;
+ const propsFileName = `${fileName}-props.mdx`;
+
+ // Delete any existing -props file (TypeDoc-generated)
+ const propsFilePath = path.join(dirName, propsFileName);
+ if (fs.existsSync(propsFilePath)) {
+ fs.unlinkSync(propsFilePath);
+ console.log(`[extract-returns] Deleted ${path.relative(process.cwd(), propsFilePath)}`);
+ }
+
+ // Find the "## Parameters" section
+ const paramsStart = content.indexOf('## Parameters');
+
+ if (paramsStart === -1) {
+ return false; // No Parameters section found
+ }
+
+ // Find the next heading after "## Parameters" (or end of file)
+ const afterParams = content.slice(paramsStart + 13); // Skip past "## Parameters"
+ const nextHeadingMatch = afterParams.match(/\n## /);
+ const paramsEnd =
+ nextHeadingMatch && typeof nextHeadingMatch.index === 'number'
+ ? paramsStart + 13 + nextHeadingMatch.index
+ : content.length;
+
+ // Extract the Parameters section and trim trailing whitespace
+ const paramsContent = content.slice(paramsStart, paramsEnd).trimEnd();
+ const processedParams = replaceGenericTypesInParamsTable(paramsContent);
+
+ // Write to new file
+ const newFilePath = path.join(dirName, targetFileName);
+ fs.writeFileSync(newFilePath, processedParams, 'utf-8');
+
+ console.log(`[extract-returns] Created ${path.relative(process.cwd(), newFilePath)}`);
+ return true;
+}
+
+/**
+ * Recursively reads all .mdx files in a directory, excluding generated files
+ * @param {string} dir - The directory to read
+ * @returns {string[]} Array of file paths
+ */
+function getAllMdxFiles(dir) {
+ /** @type {string[]} */
+ const files = [];
+
+ if (!fs.existsSync(dir)) {
+ return files;
+ }
+
+ const entries = fs.readdirSync(dir, { withFileTypes: true });
+
+ for (const entry of entries) {
+ const fullPath = path.join(dir, entry.name);
+
+ if (entry.isDirectory()) {
+ files.push(...getAllMdxFiles(fullPath));
+ } else if (entry.isFile() && entry.name.endsWith('.mdx')) {
+ // Exclude generated files
+ const isGenerated =
+ entry.name.endsWith('-return.mdx') || entry.name.endsWith('-params.mdx') || entry.name.endsWith('-props.mdx');
+ if (!isGenerated) {
+ files.push(fullPath);
+ }
+ }
+ }
+
+ return files;
+}
+
+/**
+ * Main function to process all clerk-react files
+ */
+function main() {
+ const packages = ['clerk-react'];
+ const dirs = packages.map(folder => path.join(__dirname, 'temp-docs', folder));
+
+ for (const dir of dirs) {
+ if (!fs.existsSync(dir)) {
+ console.log(`[extract-returns] ${dir} directory not found, skipping extraction`);
+ continue;
+ }
+
+ const mdxFiles = getAllMdxFiles(dir);
+ console.log(`[extract-returns] Processing ${mdxFiles.length} files in ${dir}/`);
+
+ let returnsCount = 0;
+ let paramsCount = 0;
+
+ for (const filePath of mdxFiles) {
+ // Extract Returns sections
+ if (extractReturnsSection(filePath)) {
+ returnsCount++;
+ }
+
+ // Extract Parameters sections
+ if (extractParametersSection(filePath)) {
+ paramsCount++;
+ }
+ }
+
+ console.log(`[extract-returns] Extracted ${returnsCount} Returns sections`);
+ console.log(`[extract-returns] Extracted ${paramsCount} Parameters sections`);
+ }
+}
+
+main();

package.json

@@ -56,7 +56,7 @@
  "test:typedoc": "pnpm typedoc:generate && cd ./.typedoc && vitest run",
  "turbo:clean": "turbo daemon clean",
  "typedoc:generate": "pnpm build:declarations && pnpm typedoc:generate:skip-build",
- "typedoc:generate:skip-build": "typedoc --tsconfig tsconfig.typedoc.json && rm -rf .typedoc/docs && mv .typedoc/temp-docs.typedoc/docs",
+ "typedoc:generate:skip-build": "typedoc --tsconfig tsconfig.typedoc.json && node .typedoc/extract-returns-and-params.mjs && rimraf .typedoc/docs && cpy '.typedoc/temp-docs/**' '.typedoc/docs' && rimraf .typedoc/temp-docs",
  "version-packages": "changeset version && pnpm install --lockfile-only --engine-strict=false",
  "version-packages:canary": "./scripts/canary.mjs",
  "version-packages:snapshot": "./scripts/snapshot.mjs",

packages/shared/src/errors/clerkApiResponseError.ts

@@ -11,6 +11,9 @@ interface ClerkAPIResponseOptions extends Omit<ClerkErrorParams, 'message' | 'co
  retryAfter?: number;
 }
 
+/**
+ * Class representing a Clerk API Response Error.
+ */
 export class ClerkAPIResponseError extends ClerkError implements ClerkAPIResponseErrorInterface {
  static kind = 'ClerkAPIResponseError';
  status: number;

packages/shared/src/react/commerce.tsx

@@ -156,15 +156,27 @@ type internalStripeAppearance = {
  spacingUnit: string;
 };
 
-type PaymentElementProviderProps = {
+/**
+ * @interface
+ */
+export type PaymentElementProviderProps = {
+ /**
+ * An optional checkout resource object. When provided, the payment element is scoped to the specific checkout session.
+ */
  checkout?: BillingCheckoutResource | ReturnType<typeof useCheckout>['checkout'];
+ /**
+ * An optional object to customize the appearance of the Stripe Payment Element. This allows you to match the form's styling to your application's theme.
+ */
  stripeAppearance?: internalStripeAppearance;
  /**
- * Default to `user` if not provided.
+ * Specifies whether to fetch for the current user or organization.
  *
  * @default 'user'
  */
  for?: ForPayerType;
+ /**
+ * An optional description to display to the user within the payment element UI.
+ */
  paymentDescription?: string;
 };
 
@@ -248,7 +260,17 @@ const PaymentElementInternalRoot = (props: PropsWithChildren) => {
  return <DummyStripeUtils>{props.children}</DummyStripeUtils>;
 };
 
-const PaymentElement = ({ fallback }: { fallback?: ReactNode }) => {
+/**
+ * @interface
+ */
+export type PaymentElementProps = {
+ /**
+ * Optional fallback content, such as a loading skeleton, to display while the payment form is being initialized.
+ */
+ fallback?: ReactNode;
+};
+
+const PaymentElement = ({ fallback }: PaymentElementProps) => {
  const {
  setIsPaymentElementReady,
  paymentMethodOrder,
@@ -315,7 +337,13 @@ const throwLibsMissingError = () => {
  );
 };
 
-type UsePaymentElementReturn = {
+/**
+ * @interface
+ */
+export type UsePaymentElementReturn = {
+ /**
+ * A function that submits the payment form data to the payment provider. It returns a promise that resolves with either a `data` object containing a payment token on success, or an `error` object on failure.
+ */
  submit: () => Promise<
  | {
  data: { gateway: 'stripe'; paymentToken: string };
@@ -326,13 +354,25 @@ type UsePaymentElementReturn = {
  error: PaymentElementError;
  }
  >;
+ /**
+ * A function that resets the payment form to its initial, empty state.
+ */
  reset: () => Promise<void>;
+ /**
+ * A boolean that indicates if the payment form UI has been rendered and is ready for user input. This is useful for disabling a submit button until the form is interactive.
+ */
  isFormReady: boolean;
 } & (
  | {
+ /**
+ * An object containing information about the initialized payment provider. It is `undefined` until `isProviderReady` is `true`.
+ */
  provider: {
  name: 'stripe';
  };
+ /**
+ * A boolean that indicates if the underlying payment provider (e.g. Stripe) has been fully initialized.
+ */
  isProviderReady: true;
  }
  | {

packages/shared/src/react/contexts.tsx

@@ -25,9 +25,23 @@ const [SessionContext, useSessionContext] = createContextAndHook<SignedInSession
 
 const OptionsContext = React.createContext<ClerkOptions>({});
 
-type UseCheckoutOptions = {
+/**
+ * @interface
+ */
+export type UseCheckoutOptions = {
+ /**
+ * Specifies if the checkout is for an organization.
+ *
+ * @default 'user'
+ */
  for?: ForPayerType;
+ /**
+ * The billing period for the plan.
+ */
  planPeriod: BillingSubscriptionPlanPeriod;
+ /**
+ * The ID of the subscription plan to check out (e.g. `cplan_xxx`).
+ */
  planId: string;
 };
 

.changeset/violet-boxes-watch.md

@@ -0,0 +1,6 @@
+---
+'@clerk/shared': minor
+'@clerk/types': minor
+---
+
+Ensure all hooks use typedoc for clerk docs

.typedoc/custom-plugin.mjs

@@ -10,7 +10,6 @@ const FILES_WITHOUT_HEADINGS = [
  'use-organization-params.mdx',
  'paginated-resources.mdx',
  'pages-or-infinite-options.mdx',
- 'pages-or-infinite-options.mdx',
  'paginated-hook-config.mdx',
  'use-organization-list-return.mdx',
  'use-organization-list-params.mdx',
@@ -19,6 +18,21 @@ const FILES_WITHOUT_HEADINGS = [
  'verify-token-options.mdx',
  'public-organization-data-json.mdx',
  'organization-membership-public-user-data.mdx',
+ 'use-checkout-return.mdx',
+ 'use-checkout-options.mdx',
+ 'use-payment-element-return.mdx',
+ 'use-payment-methods-return.mdx',
+ 'use-payment-attempts-return.mdx',
+ 'use-plans-return.mdx',
+ 'use-statements-return.mdx',
+ 'hook-params.mdx',
+ 'use-subscription-params.mdx',
+ 'subscription-result.mdx',
+ 'needs-reverification-parameters.mdx',
+ 'use-reverification-options.mdx',
+ 'use-reverification-params.mdx',
+ 'payment-element-provider-props.mdx',
+ 'payment-element-props.mdx',
 ];
 
 /**
@@ -29,6 +43,8 @@ const LINK_REPLACEMENTS = [
  ['set-active-params', '/docs/reference/javascript/types/set-active-params'],
  ['clerk-paginated-response', '/docs/reference/javascript/types/clerk-paginated-response'],
  ['paginated-resources', '#paginated-resources'],
+ ['use-checkout-options', '#use-checkout-options'],
+ ['needs-reverification-parameters', '#needs-reverification-parameters'],
  ['create-organization-params', '#create-organization-params'],
  ['session-resource', '/docs/reference/javascript/session'],
  ['signed-in-session-resource', '/docs/reference/javascript/session'],
@@ -62,13 +78,18 @@ const LINK_REPLACEMENTS = [
  ['billing-payer-resource', '/docs/reference/javascript/types/billing-payer-resource'],
  ['billing-plan-resource', '/docs/reference/javascript/types/billing-plan-resource'],
  ['billing-checkout-totals', '/docs/reference/javascript/types/billing-checkout-totals'],
+ ['billing-checkout-resource', '/docs/reference/javascript/types/billing-checkout-resource'],
  ['billing-money-amount', '/docs/reference/javascript/types/billing-money-amount'],
  ['billing-subscription-item-resource', '/docs/reference/javascript/types/billing-subscription-item-resource'],
  ['feature-resource', '/docs/reference/javascript/types/feature-resource'],
  ['billing-statement-group', '/docs/reference/javascript/types/billing-statement-group'],
+ ['billing-statement-resource', '/docs/reference/javascript/types/billing-statement-resource'],
+ ['billing-subscription-resource', '/docs/reference/javascript/types/billing-subscription-resource'],
+ ['clerk-api-response-error', '/docs/reference/javascript/types/clerk-api-response-error'],
  ['billing-statement-totals', '/docs/reference/javascript/types/billing-statement-totals'],
  ['billing-payment-resource', '/docs/reference/javascript/types/billing-payment-resource'],
  ['deleted-object-resource', '/docs/reference/javascript/types/deleted-object-resource'],
+ ['use-checkout-return', '/docs/reference/hooks/use-checkout#returns'],
 ];
 
 /**

.typedoc/extract-returns-and-params.mjs

@@ -0,0 +1,179 @@
+// @ts-check
+import fs from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = path.dirname(__filename);
+
+/**
+ * Extracts the "## Returns" section from a markdown file and writes it to a separate file.
+ * @param {string} filePath - The path to the markdown file
+ * @returns {boolean} True if a file was created
+ */
+function extractReturnsSection(filePath) {
+ const content = fs.readFileSync(filePath, 'utf-8');
+
+ // Find the "## Returns" section
+ const returnsStart = content.indexOf('## Returns');
+
+ if (returnsStart === -1) {
+ return false; // No Returns section found
+ }
+
+ // Find the next heading after "## Returns" (or end of file)
+ const afterReturns = content.slice(returnsStart + 10); // Skip past "## Returns"
+ const nextHeadingMatch = afterReturns.match(/\n## /);
+ const returnsEnd =
+ nextHeadingMatch && typeof nextHeadingMatch.index === 'number'
+ ? returnsStart + 10 + nextHeadingMatch.index
+ : content.length;
+
+ // Extract the Returns section and trim trailing whitespace
+ const returnsContent = content.slice(returnsStart, returnsEnd).trimEnd();
+
+ // Generate the new filename: use-auth.mdx -> use-auth-return.mdx
+ const fileName = path.basename(filePath, '.mdx');
+ const dirName = path.dirname(filePath);
+ const newFilePath = path.join(dirName, `${fileName}-return.mdx`);
+
+ // Write the extracted Returns section to the new file
+ fs.writeFileSync(newFilePath, returnsContent, 'utf-8');
+
+ console.log(`[extract-returns] Created ${path.relative(process.cwd(), newFilePath)}`);
+ return true;
+}
+
+/**
+ * Replaces generic type names in the parameters table with expanded types.
+ * @param {string} content
+ * @returns {string}
+ */
+function replaceGenericTypesInParamsTable(content) {
+ // Replace Fetcher in the parameters table
+ content = content.replace(
+ /(\|\s*`fetcher`\s*\|\s*)`Fetcher`(\s*\|)/g,
+ '$1`Fetcher extends (...args: any[]) => Promise<any>`$2',
+ );
+ return content;
+}
+
+/**
+ * Extracts the "## Parameters" section from a markdown file and writes it to a separate file.
+ * @param {string} filePath - The path to the markdown file
+ * @returns {boolean} True if a file was created
+ */
+function extractParametersSection(filePath) {
+ const content = fs.readFileSync(filePath, 'utf-8');
+ const fileName = path.basename(filePath, '.mdx');
+ const dirName = path.dirname(filePath);
+
+ // Always use -params suffix
+ const suffix = '-params';
+ const targetFileName = `${fileName}${suffix}.mdx`;
+ const propsFileName = `${fileName}-props.mdx`;
+
+ // Delete any existing -props file (TypeDoc-generated)
+ const propsFilePath = path.join(dirName, propsFileName);
+ if (fs.existsSync(propsFilePath)) {
+ fs.unlinkSync(propsFilePath);
+ console.log(`[extract-returns] Deleted ${path.relative(process.cwd(), propsFilePath)}`);
+ }
+
+ // Find the "## Parameters" section
+ const paramsStart = content.indexOf('## Parameters');
+
+ if (paramsStart === -1) {
+ return false; // No Parameters section found
+ }
+
+ // Find the next heading after "## Parameters" (or end of file)
+ const afterParams = content.slice(paramsStart + 13); // Skip past "## Parameters"
+ const nextHeadingMatch = afterParams.match(/\n## /);
+ const paramsEnd =
+ nextHeadingMatch && typeof nextHeadingMatch.index === 'number'
+ ? paramsStart + 13 + nextHeadingMatch.index
+ : content.length;
+
+ // Extract the Parameters section and trim trailing whitespace
+ const paramsContent = content.slice(paramsStart, paramsEnd).trimEnd();
+ const processedParams = replaceGenericTypesInParamsTable(paramsContent);
+
+ // Write to new file
+ const newFilePath = path.join(dirName, targetFileName);
+ fs.writeFileSync(newFilePath, processedParams, 'utf-8');
+
+ console.log(`[extract-returns] Created ${path.relative(process.cwd(), newFilePath)}`);
+ return true;
+}
+
+/**
+ * Recursively reads all .mdx files in a directory, excluding generated files
+ * @param {string} dir - The directory to read
+ * @returns {string[]} Array of file paths
+ */
+function getAllMdxFiles(dir) {
+ /** @type {string[]} */
+ const files = [];
+
+ if (!fs.existsSync(dir)) {
+ return files;
+ }
+
+ const entries = fs.readdirSync(dir, { withFileTypes: true });
+
+ for (const entry of entries) {
+ const fullPath = path.join(dir, entry.name);
+
+ if (entry.isDirectory()) {
+ files.push(...getAllMdxFiles(fullPath));
+ } else if (entry.isFile() && entry.name.endsWith('.mdx')) {
+ // Exclude generated files
+ const isGenerated =
+ entry.name.endsWith('-return.mdx') || entry.name.endsWith('-params.mdx') || entry.name.endsWith('-props.mdx');
+ if (!isGenerated) {
+ files.push(fullPath);
+ }
+ }
+ }
+
+ return files;
+}
+
+/**
+ * Main function to process all clerk-react files
+ */
+function main() {
+ const packages = ['clerk-react'];
+ const dirs = packages.map(folder => path.join(__dirname, 'temp-docs', folder));
+
+ for (const dir of dirs) {
+ if (!fs.existsSync(dir)) {
+ console.log(`[extract-returns] ${dir} directory not found, skipping extraction`);
+ continue;
+ }
+
+ const mdxFiles = getAllMdxFiles(dir);
+ console.log(`[extract-returns] Processing ${mdxFiles.length} files in ${dir}/`);
+
+ let returnsCount = 0;
+ let paramsCount = 0;
+
+ for (const filePath of mdxFiles) {
+ // Extract Returns sections
+ if (extractReturnsSection(filePath)) {
+ returnsCount++;
+ }
+
+ // Extract Parameters sections
+ if (extractParametersSection(filePath)) {
+ paramsCount++;
+ }
+ }
+
+ console.log(`[extract-returns] Extracted ${returnsCount} Returns sections`);
+ console.log(`[extract-returns] Extracted ${paramsCount} Parameters sections`);
+ }
+}
+
+main();

package.json

@@ -56,7 +56,7 @@
  "test:typedoc": "pnpm typedoc:generate && cd ./.typedoc && vitest run",
  "turbo:clean": "turbo daemon clean",
  "typedoc:generate": "pnpm build:declarations && pnpm typedoc:generate:skip-build",
- "typedoc:generate:skip-build": "typedoc --tsconfig tsconfig.typedoc.json && rm -rf .typedoc/docs && mv .typedoc/temp-docs.typedoc/docs",
+ "typedoc:generate:skip-build": "typedoc --tsconfig tsconfig.typedoc.json && node .typedoc/extract-returns-and-params.mjs && rimraf .typedoc/docs && cpy '.typedoc/temp-docs/**' '.typedoc/docs' && rimraf .typedoc/temp-docs",
  "version-packages": "changeset version && pnpm install --lockfile-only --engine-strict=false",
  "version-packages:canary": "./scripts/canary.mjs",
  "version-packages:snapshot": "./scripts/snapshot.mjs",

packages/shared/src/errors/clerkApiResponseError.ts

@@ -11,6 +11,9 @@ interface ClerkAPIResponseOptions extends Omit<ClerkErrorParams, 'message' | 'co
  retryAfter?: number;
 }
 
+/**
+ * Class representing a Clerk API Response Error.
+ */
 export class ClerkAPIResponseError extends ClerkError implements ClerkAPIResponseErrorInterface {
  static kind = 'ClerkAPIResponseError';
  status: number;

packages/shared/src/react/commerce.tsx

@@ -156,15 +156,27 @@ type internalStripeAppearance = {
  spacingUnit: string;
 };
 
-type PaymentElementProviderProps = {
+/**
+ * @interface
+ */
+export type PaymentElementProviderProps = {
+ /**
+ * An optional checkout resource object. When provided, the payment element is scoped to the specific checkout session.
+ */
  checkout?: BillingCheckoutResource | ReturnType<typeof useCheckout>['checkout'];
+ /**
+ * An optional object to customize the appearance of the Stripe Payment Element. This allows you to match the form's styling to your application's theme.
+ */
  stripeAppearance?: internalStripeAppearance;
  /**
- * Default to `user` if not provided.
+ * Specifies whether to fetch for the current user or organization.
  *
  * @default 'user'
  */
  for?: ForPayerType;
+ /**
+ * An optional description to display to the user within the payment element UI.
+ */
  paymentDescription?: string;
 };
 
@@ -248,7 +260,17 @@ const PaymentElementInternalRoot = (props: PropsWithChildren) => {
  return <DummyStripeUtils>{props.children}</DummyStripeUtils>;
 };
 
-const PaymentElement = ({ fallback }: { fallback?: ReactNode }) => {
+/**
+ * @interface
+ */
+export type PaymentElementProps = {
+ /**
+ * Optional fallback content, such as a loading skeleton, to display while the payment form is being initialized.
+ */
+ fallback?: ReactNode;
+};
+
+const PaymentElement = ({ fallback }: PaymentElementProps) => {
  const {
  setIsPaymentElementReady,
  paymentMethodOrder,
@@ -315,7 +337,13 @@ const throwLibsMissingError = () => {
  );
 };
 
-type UsePaymentElementReturn = {
+/**
+ * @interface
+ */
+export type UsePaymentElementReturn = {
+ /**
+ * A function that submits the payment form data to the payment provider. It returns a promise that resolves with either a `data` object containing a payment token on success, or an `error` object on failure.
+ */
  submit: () => Promise<
  | {
  data: { gateway: 'stripe'; paymentToken: string };
@@ -326,13 +354,25 @@ type UsePaymentElementReturn = {
  error: PaymentElementError;
  }
  >;
+ /**
+ * A function that resets the payment form to its initial, empty state.
+ */
  reset: () => Promise<void>;
+ /**
+ * A boolean that indicates if the payment form UI has been rendered and is ready for user input. This is useful for disabling a submit button until the form is interactive.
+ */
  isFormReady: boolean;
 } & (
  | {
+ /**
+ * An object containing information about the initialized payment provider. It is `undefined` until `isProviderReady` is `true`.
+ */
  provider: {
  name: 'stripe';
  };
+ /**
+ * A boolean that indicates if the underlying payment provider (e.g. Stripe) has been fully initialized.
+ */
  isProviderReady: true;
  }
  | {

packages/shared/src/react/contexts.tsx

@@ -25,9 +25,23 @@ const [SessionContext, useSessionContext] = createContextAndHook<SignedInSession
 
 const OptionsContext = React.createContext<ClerkOptions>({});
 
-type UseCheckoutOptions = {
+/**
+ * @interface
+ */
+export type UseCheckoutOptions = {
+ /**
+ * Specifies if the checkout is for an organization.
+ *
+ * @default 'user'
+ */
  for?: ForPayerType;
+ /**
+ * The billing period for the plan.
+ */
  planPeriod: BillingSubscriptionPlanPeriod;
+ /**
+ * The ID of the subscription plan to check out (e.g. `cplan_xxx`).
+ */
  planId: string;
 };
 

.changeset/violet-boxes-watch.md

@@ -0,0 +1,6 @@
+---
+'@clerk/shared': minor
+'@clerk/types': minor
+---
+
+Ensure all hooks use typedoc for clerk docs

.typedoc/custom-plugin.mjs

@@ -10,7 +10,6 @@ const FILES_WITHOUT_HEADINGS = [
  'use-organization-params.mdx',
  'paginated-resources.mdx',
  'pages-or-infinite-options.mdx',
- 'pages-or-infinite-options.mdx',
  'paginated-hook-config.mdx',
  'use-organization-list-return.mdx',
  'use-organization-list-params.mdx',
@@ -19,6 +18,21 @@ const FILES_WITHOUT_HEADINGS = [
  'verify-token-options.mdx',
  'public-organization-data-json.mdx',
  'organization-membership-public-user-data.mdx',
+ 'use-checkout-return.mdx',
+ 'use-checkout-options.mdx',
+ 'use-payment-element-return.mdx',
+ 'use-payment-methods-return.mdx',
+ 'use-payment-attempts-return.mdx',
+ 'use-plans-return.mdx',
+ 'use-statements-return.mdx',
+ 'hook-params.mdx',
+ 'use-subscription-params.mdx',
+ 'subscription-result.mdx',
+ 'needs-reverification-parameters.mdx',
+ 'use-reverification-options.mdx',
+ 'use-reverification-params.mdx',
+ 'payment-element-provider-props.mdx',
+ 'payment-element-props.mdx',
 ];
 
 /**
@@ -29,6 +43,8 @@ const LINK_REPLACEMENTS = [
  ['set-active-params', '/docs/reference/javascript/types/set-active-params'],
  ['clerk-paginated-response', '/docs/reference/javascript/types/clerk-paginated-response'],
  ['paginated-resources', '#paginated-resources'],
+ ['use-checkout-options', '#use-checkout-options'],
+ ['needs-reverification-parameters', '#needs-reverification-parameters'],
  ['create-organization-params', '#create-organization-params'],
  ['session-resource', '/docs/reference/javascript/session'],
  ['signed-in-session-resource', '/docs/reference/javascript/session'],
@@ -62,13 +78,18 @@ const LINK_REPLACEMENTS = [
  ['billing-payer-resource', '/docs/reference/javascript/types/billing-payer-resource'],
  ['billing-plan-resource', '/docs/reference/javascript/types/billing-plan-resource'],
  ['billing-checkout-totals', '/docs/reference/javascript/types/billing-checkout-totals'],
+ ['billing-checkout-resource', '/docs/reference/javascript/types/billing-checkout-resource'],
  ['billing-money-amount', '/docs/reference/javascript/types/billing-money-amount'],
  ['billing-subscription-item-resource', '/docs/reference/javascript/types/billing-subscription-item-resource'],
  ['feature-resource', '/docs/reference/javascript/types/feature-resource'],
  ['billing-statement-group', '/docs/reference/javascript/types/billing-statement-group'],
+ ['billing-statement-resource', '/docs/reference/javascript/types/billing-statement-resource'],
+ ['billing-subscription-resource', '/docs/reference/javascript/types/billing-subscription-resource'],
+ ['clerk-api-response-error', '/docs/reference/javascript/types/clerk-api-response-error'],
  ['billing-statement-totals', '/docs/reference/javascript/types/billing-statement-totals'],
  ['billing-payment-resource', '/docs/reference/javascript/types/billing-payment-resource'],
  ['deleted-object-resource', '/docs/reference/javascript/types/deleted-object-resource'],
+ ['use-checkout-return', '/docs/reference/hooks/use-checkout#returns'],
 ];
 
 /**

.typedoc/extract-returns-and-params.mjs

@@ -0,0 +1,179 @@
+// @ts-check
+import fs from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const __filename = fileURLToPath(import.meta.url);
+const __dirname = path.dirname(__filename);
+
+/**
+ * Extracts the "## Returns" section from a markdown file and writes it to a separate file.
+ * @param {string} filePath - The path to the markdown file
+ * @returns {boolean} True if a file was created
+ */
+function extractReturnsSection(filePath) {
+ const content = fs.readFileSync(filePath, 'utf-8');
+
+ // Find the "## Returns" section
+ const returnsStart = content.indexOf('## Returns');
+
+ if (returnsStart === -1) {
+ return false; // No Returns section found
+ }
+
+ // Find the next heading after "## Returns" (or end of file)
+ const afterReturns = content.slice(returnsStart + 10); // Skip past "## Returns"
+ const nextHeadingMatch = afterReturns.match(/\n## /);
+ const returnsEnd =
+ nextHeadingMatch && typeof nextHeadingMatch.index === 'number'
+ ? returnsStart + 10 + nextHeadingMatch.index
+ : content.length;
+
+ // Extract the Returns section and trim trailing whitespace
+ const returnsContent = content.slice(returnsStart, returnsEnd).trimEnd();
+
+ // Generate the new filename: use-auth.mdx -> use-auth-return.mdx
+ const fileName = path.basename(filePath, '.mdx');
+ const dirName = path.dirname(filePath);
+ const newFilePath = path.join(dirName, `${fileName}-return.mdx`);
+
+ // Write the extracted Returns section to the new file
+ fs.writeFileSync(newFilePath, returnsContent, 'utf-8');
+
+ console.log(`[extract-returns] Created ${path.relative(process.cwd(), newFilePath)}`);
+ return true;
+}
+
+/**
+ * Replaces generic type names in the parameters table with expanded types.
+ * @param {string} content
+ * @returns {string}
+ */
+function replaceGenericTypesInParamsTable(content) {
+ // Replace Fetcher in the parameters table
+ content = content.replace(
+ /(\|\s*`fetcher`\s*\|\s*)`Fetcher`(\s*\|)/g,
+ '$1`Fetcher extends (...args: any[]) => Promise<any>`$2',
+ );
+ return content;
+}
+
+/**
+ * Extracts the "## Parameters" section from a markdown file and writes it to a separate file.
+ * @param {string} filePath - The path to the markdown file
+ * @returns {boolean} True if a file was created
+ */
+function extractParametersSection(filePath) {
+ const content = fs.readFileSync(filePath, 'utf-8');
+ const fileName = path.basename(filePath, '.mdx');
+ const dirName = path.dirname(filePath);
+
+ // Always use -params suffix
+ const suffix = '-params';
+ const targetFileName = `${fileName}${suffix}.mdx`;
+ const propsFileName = `${fileName}-props.mdx`;
+
+ // Delete any existing -props file (TypeDoc-generated)
+ const propsFilePath = path.join(dirName, propsFileName);
+ if (fs.existsSync(propsFilePath)) {
+ fs.unlinkSync(propsFilePath);
+ console.log(`[extract-returns] Deleted ${path.relative(process.cwd(), propsFilePath)}`);
+ }
+
+ // Find the "## Parameters" section
+ const paramsStart = content.indexOf('## Parameters');
+
+ if (paramsStart === -1) {
+ return false; // No Parameters section found
+ }
+
+ // Find the next heading after "## Parameters" (or end of file)
+ const afterParams = content.slice(paramsStart + 13); // Skip past "## Parameters"
+ const nextHeadingMatch = afterParams.match(/\n## /);
+ const paramsEnd =
+ nextHeadingMatch && typeof nextHeadingMatch.index === 'number'
+ ? paramsStart + 13 + nextHeadingMatch.index
+ : content.length;
+
+ // Extract the Parameters section and trim trailing whitespace
+ const paramsContent = content.slice(paramsStart, paramsEnd).trimEnd();
+ const processedParams = replaceGenericTypesInParamsTable(paramsContent);
+
+ // Write to new file
+ const newFilePath = path.join(dirName, targetFileName);
+ fs.writeFileSync(newFilePath, processedParams, 'utf-8');
+
+ console.log(`[extract-returns] Created ${path.relative(process.cwd(), newFilePath)}`);
+ return true;
+}
+
+/**
+ * Recursively reads all .mdx files in a directory, excluding generated files
+ * @param {string} dir - The directory to read
+ * @returns {string[]} Array of file paths
+ */
+function getAllMdxFiles(dir) {
+ /** @type {string[]} */
+ const files = [];
+
+ if (!fs.existsSync(dir)) {
+ return files;
+ }
+
+ const entries = fs.readdirSync(dir, { withFileTypes: true });
+
+ for (const entry of entries) {
+ const fullPath = path.join(dir, entry.name);
+
+ if (entry.isDirectory()) {
+ files.push(...getAllMdxFiles(fullPath));
+ } else if (entry.isFile() && entry.name.endsWith('.mdx')) {
+ // Exclude generated files
+ const isGenerated =
+ entry.name.endsWith('-return.mdx') || entry.name.endsWith('-params.mdx') || entry.name.endsWith('-props.mdx');
+ if (!isGenerated) {
+ files.push(fullPath);
+ }
+ }
+ }
+
+ return files;
+}
+
+/**
+ * Main function to process all clerk-react files
+ */
+function main() {
+ const packages = ['clerk-react'];
+ const dirs = packages.map(folder => path.join(__dirname, 'temp-docs', folder));
+
+ for (const dir of dirs) {
+ if (!fs.existsSync(dir)) {
+ console.log(`[extract-returns] ${dir} directory not found, skipping extraction`);
+ continue;
+ }
+
+ const mdxFiles = getAllMdxFiles(dir);
+ console.log(`[extract-returns] Processing ${mdxFiles.length} files in ${dir}/`);
+
+ let returnsCount = 0;
+ let paramsCount = 0;
+
+ for (const filePath of mdxFiles) {
+ // Extract Returns sections
+ if (extractReturnsSection(filePath)) {
+ returnsCount++;
+ }
+
+ // Extract Parameters sections
+ if (extractParametersSection(filePath)) {
+ paramsCount++;
+ }
+ }
+
+ console.log(`[extract-returns] Extracted ${returnsCount} Returns sections`);
+ console.log(`[extract-returns] Extracted ${paramsCount} Parameters sections`);
+ }
+}
+
+main();

package.json

@@ -56,7 +56,7 @@
  "test:typedoc": "pnpm typedoc:generate && cd ./.typedoc && vitest run",
  "turbo:clean": "turbo daemon clean",
  "typedoc:generate": "pnpm build:declarations && pnpm typedoc:generate:skip-build",
- "typedoc:generate:skip-build": "typedoc --tsconfig tsconfig.typedoc.json && rm -rf .typedoc/docs && mv .typedoc/temp-docs.typedoc/docs",
+ "typedoc:generate:skip-build": "typedoc --tsconfig tsconfig.typedoc.json && node .typedoc/extract-returns-and-params.mjs && rimraf .typedoc/docs && cpy '.typedoc/temp-docs/**' '.typedoc/docs' && rimraf .typedoc/temp-docs",
  "version-packages": "changeset version && pnpm install --lockfile-only --engine-strict=false",
  "version-packages:canary": "./scripts/canary.mjs",
  "version-packages:snapshot": "./scripts/snapshot.mjs",

packages/shared/src/errors/clerkApiResponseError.ts

@@ -11,6 +11,9 @@ interface ClerkAPIResponseOptions extends Omit<ClerkErrorParams, 'message' | 'co
  retryAfter?: number;
 }
 
+/**
+ * Class representing a Clerk API Response Error.
+ */
 export class ClerkAPIResponseError extends ClerkError implements ClerkAPIResponseErrorInterface {
  static kind = 'ClerkAPIResponseError';
  status: number;

packages/shared/src/react/commerce.tsx

@@ -156,15 +156,27 @@ type internalStripeAppearance = {
  spacingUnit: string;
 };
 
-type PaymentElementProviderProps = {
+/**
+ * @interface
+ */
+export type PaymentElementProviderProps = {
+ /**
+ * An optional checkout resource object. When provided, the payment element is scoped to the specific checkout session.
+ */
  checkout?: BillingCheckoutResource | ReturnType<typeof useCheckout>['checkout'];
+ /**
+ * An optional object to customize the appearance of the Stripe Payment Element. This allows you to match the form's styling to your application's theme.
+ */
  stripeAppearance?: internalStripeAppearance;
  /**
- * Default to `user` if not provided.
+ * Specifies whether to fetch for the current user or organization.
  *
  * @default 'user'
  */
  for?: ForPayerType;
+ /**
+ * An optional description to display to the user within the payment element UI.
+ */
  paymentDescription?: string;
 };
 
@@ -248,7 +260,17 @@ const PaymentElementInternalRoot = (props: PropsWithChildren) => {
  return <DummyStripeUtils>{props.children}</DummyStripeUtils>;
 };
 
-const PaymentElement = ({ fallback }: { fallback?: ReactNode }) => {
+/**
+ * @interface
+ */
+export type PaymentElementProps = {
+ /**
+ * Optional fallback content, such as a loading skeleton, to display while the payment form is being initialized.
+ */
+ fallback?: ReactNode;
+};
+
+const PaymentElement = ({ fallback }: PaymentElementProps) => {
  const {
  setIsPaymentElementReady,
  paymentMethodOrder,
@@ -315,7 +337,13 @@ const throwLibsMissingError = () => {
  );
 };
 
-type UsePaymentElementReturn = {
+/**
+ * @interface
+ */
+export type UsePaymentElementReturn = {
+ /**
+ * A function that submits the payment form data to the payment provider. It returns a promise that resolves with either a `data` object containing a payment token on success, or an `error` object on failure.
+ */
  submit: () => Promise<
  | {
  data: { gateway: 'stripe'; paymentToken: string };
@@ -326,13 +354,25 @@ type UsePaymentElementReturn = {
  error: PaymentElementError;
  }
  >;
+ /**
+ * A function that resets the payment form to its initial, empty state.
+ */
  reset: () => Promise<void>;
+ /**
+ * A boolean that indicates if the payment form UI has been rendered and is ready for user input. This is useful for disabling a submit button until the form is interactive.
+ */
  isFormReady: boolean;
 } & (
  | {
+ /**
+ * An object containing information about the initialized payment provider. It is `undefined` until `isProviderReady` is `true`.
+ */
  provider: {
  name: 'stripe';
  };
+ /**
+ * A boolean that indicates if the underlying payment provider (e.g. Stripe) has been fully initialized.
+ */
  isProviderReady: true;
  }
  | {

packages/shared/src/react/contexts.tsx

@@ -25,9 +25,23 @@ const [SessionContext, useSessionContext] = createContextAndHook<SignedInSession
 
 const OptionsContext = React.createContext<ClerkOptions>({});
 
-type UseCheckoutOptions = {
+/**
+ * @interface
+ */
+export type UseCheckoutOptions = {
+ /**
+ * Specifies if the checkout is for an organization.
+ *
+ * @default 'user'
+ */
  for?: ForPayerType;
+ /**
+ * The billing period for the plan.
+ */
  planPeriod: BillingSubscriptionPlanPeriod;
+ /**
+ * The ID of the subscription plan to check out (e.g. `cplan_xxx`).
+ */
  planId: string;
 };