docs(repo): Generate all params and return types (hooks work) #6901
There are no files selected for viewing
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -0,0 +1,164 @@ | ||
| // @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; | ||
| } | ||
|
|
||
| /** | ||
| * 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'); | ||
|
|
||
| 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(); | ||
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
|
|
@@ -12,6 +12,9 @@ interface ClerkAPIResponseOptions extends Omit<ClerkErrorParams, 'message' | 'co | |
| retryAfter?: number; | ||
| } | ||
|
|
||
| /** | ||
| * Interface representing a Clerk API Response Error. | ||
| */ | ||
|
Comment on lines
14
to
16
There was a problem hiding this comment. 🛠️ Refactor suggestion | 🟠 Major 🧩 Analysis chainJSDoc mismatch: refers to “Interface” but documents a class; enrich for Typedoc Replace the summary and add basic tags to align with the PR goal (Typedoc metadata). Apply this diff: -/**
- * Interface representing a Clerk API Response Error.
- */
+/**
+ * Class representing a Clerk API response error thrown when the Clerk API returns an error payload.
+ * @public
+ * @remarks Use `status`, `errors`, `clerkTraceId`, and `retryAfter` to inspect details.
+ * @see isClerkApiResponseError
+ */Additionally (outside this range), consider:
Example snippet: export class ClerkAPIResponseError extends ClerkError implements ClerkAPIResponseErrorInterface {
/** HTTP status code returned by the API. */
public status: number;
/** Unique trace identifier for support/debugging. */
public clerkTraceId?: string;
/** Retry-After value (in seconds) when rate limited or similar. */
public retryAfter?: number;
/** Parsed list of API errors. */
public errors: ClerkAPIError[];
/** Returns a stringified representation of this error. */
public toString(): string { /* unchanged body */ }
// Keeps message unformatted for backward compatibility
protected static override formatMessage(name: string, msg: string, _: string, __: string | undefined): string {
return msg;
}
}Please re-run your Typedoc flow (pnpm run typedoc:generate) to confirm the class and its members render with the updated descriptions, and that constructor params/fields appear as expected. As per coding guidelines. 🏁 Script executed: #!/bin/bash
file=$(fd clerkApiResponseError.ts)
echo "Found file: $file"
sed -n '1,30p' "$file"Length of output: 1203 🏁 Script executed: #!/bin/bash
file="packages/shared/src/errors/clerkApiResponseError.ts"
sed -n '30,100p' "$file"Length of output: 1081 Fix JSDoc header and document public API Replace at packages/shared/src/errors/clerkApiResponseError.ts (lines 15–17): -/**
- * Interface representing a Clerk API Response Error.
- */
+/**
+ * Class representing a Clerk API response error thrown when the Clerk API returns an error payload.
+ * @public
+ * @remarks Use `status`, `errors`, `clerkTraceId`, and `retryAfter` to inspect details.
+ * @see isClerkApiResponseError
+ */
🤖 Prompt for AI Agents |
||
| export class ClerkAPIResponseError extends ClerkError implements ClerkAPIResponseErrorInterface { | ||
| static name = 'ClerkAPIResponseError'; | ||
| status: number; | ||
|
|
||
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
|
|
@@ -6,7 +6,6 @@ import useSWR from 'swr'; | |
| import useSWRMutation from 'swr/mutation'; | ||
|
|
||
| import { createContextAndHook } from './hooks/createContextAndHook'; | ||
| import { useClerk } from './hooks/useClerk'; | ||
| import { useOrganization } from './hooks/useOrganization'; | ||
| import { useUser } from './hooks/useUser'; | ||
|
|
@@ -139,15 +138,27 @@ type internalStripeAppearance = { | |
| spacingUnit: string; | ||
| }; | ||
|
|
||
| /** | ||
| * @interface | ||
| */ | ||
| export type PaymentElementProviderProps = { | ||
| /** | ||
| * An optional checkout resource object. When provided, the payment element is scoped to the specific checkout session. | ||
| */ | ||
| checkout?: BillingCheckoutResource; | ||
| /** | ||
| * 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; | ||
| /** | ||
| * 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; | ||
| }; | ||
|
|
||
|
|
@@ -229,7 +240,17 @@ const PaymentElementInternalRoot = (props: PropsWithChildren) => { | |
| return <DummyStripeUtils>{props.children}</DummyStripeUtils>; | ||
| }; | ||
|
|
||
| /** | ||
| * @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, | ||
|
|
@@ -296,7 +317,13 @@ const throwLibsMissingError = () => { | |
| ); | ||
| }; | ||
|
|
||
| /** | ||
| * @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 }; | ||
|
|
@@ -307,13 +334,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; | ||
| } | ||
| | { | ||
|
|
||
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
|
|
@@ -25,9 +25,23 @@ const [SessionContext, useSessionContext] = createContextAndHook<SignedInSession | |
|
|
||
| const OptionsContext = React.createContext<ClerkOptions>({}); | ||
|
|
||
| /** | ||
| * @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; | ||
| }; | ||
|
|
||
|
|
||
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
|
|
@@ -24,6 +24,18 @@ type BillingHookConfig<TResource extends ClerkResource, TParams extends PagesOrI | |
| }; | ||
| }; | ||
|
|
||
| /** | ||
| * @interface | ||
| */ | ||
coderabbitai[bot] marked this conversation as resolved.
Show resolved
Hide resolved
|
||
| export type HookParams = PaginatedHookConfig<PagesOrInfiniteOptions> & { | ||
| /** | ||
| * Specifies whether to fetch for the current user or organization. | ||
| * | ||
| * @default 'user' | ||
| */ | ||
| for?: ForPayerType; | ||
| }; | ||
|
|
||
| /** | ||
| * A hook factory that creates paginated data fetching hooks for commerce-related resources. | ||
| * It provides a standardized way to create hooks that can fetch either user or organization resources | ||
|
|
@@ -44,10 +56,6 @@ export function createBillingPaginatedHook<TResource extends ClerkResource, TPar | |
| useFetcher, | ||
| options, | ||
| }: BillingHookConfig<TResource, TParams>) { | ||
| return function useBillingHook<T extends HookParams>( | ||
| params?: T, | ||
| ): PaginatedResources<TResource, T extends { infinite: true } ? true : false> { | ||
|
|
||
Oops, something went wrong.
Oops, something went wrong.
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Params written to wrong directory; props deletion path wrong (critical).
extractParametersSection writes -params.mdx at the package root and deletes -props.mdx there, not next to the source file. This will misplace files for nested MDX and fail to delete the actual props file. Align with extractReturnsSection by using the file’s own directory and drop the extra dirName param.
Apply these diffs:
Also applies to: 62-67, 87-90, 154-156
🤖 Prompt for AI Agents