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',
+  'use-subscription-return.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,9 @@ 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'],
+  ['use-reverification-options', '#use-reverification-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 +79,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,181 @@
+// @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
+ * @param {string} dirName - The directory containing the files
+ * @returns {boolean} True if a file was created
+ */
+function extractParametersSection(filePath, dirName) {
+  const content = fs.readFileSync(filePath, 'utf-8');
+  const fileName = path.basename(filePath, '.mdx');
+
+  // 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();
+
+  // Write to new file
+  const newFilePath = path.join(dirName, targetFileName);
+  fs.writeFileSync(newFilePath, paramsContent, 'utf-8');
+
+  const processedParams = replaceGenericTypesInParamsTable(fs.readFileSync(newFilePath, 'utf-8'));
+  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, dir)) {
+        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 && rm -rf .typedoc/docs && mv .typedoc/temp-docs .typedoc/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;
 };