docs(backend,shared): Generate typedoc output for backend docs#8853
Conversation
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
🦋 Changeset detectedLatest commit: e65134a The changes in this PR will be included in the next version bump. This PR includes changesets to release 0 packagesWhen changesets are added to this PR, you'll see the packages that this PR includes changesets for and the associated semver types Not sure what this means? Click here to learn what changesets are. Click here if you're a maintainer who wants to add another changeset to this PR |
|
The latest updates on your projects. Learn more about Vercel for GitHub.
|
|
Note Reviews pausedIt looks like this branch is under active development. To avoid overwhelming you with review comments due to an influx of new commits, CodeRabbit has automatically paused this review. You can configure this behavior by changing the Use the following commands to manage reviews:
Use the checkboxes below for quick actions:
📝 WalkthroughWalkthroughAdds TypeDoc-backed backend docs by exporting endpoint parameter types, routing backend pages, extending TypeDoc rendering for inline properties and backend method pages, and refreshing related snapshots, config, and documentation comments. ChangesBackend TypeDoc documentation generation
Estimated code review effort🎯 4 (Complex) | ⏱️ ~60 minutes Possibly related PRs
Suggested reviewers
Poem
🚥 Pre-merge checks | ✅ 5✅ Passed checks (5 passed)
Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out. Comment |
@clerk/astro
@clerk/backend
@clerk/chrome-extension
@clerk/clerk-js
@clerk/electron
@clerk/electron-passkeys
@clerk/eslint-plugin
@clerk/expo
@clerk/expo-passkeys
@clerk/express
@clerk/fastify
@clerk/hono
@clerk/localizations
@clerk/nextjs
@clerk/nuxt
@clerk/react
@clerk/react-router
@clerk/shared
@clerk/tanstack-react-start
@clerk/testing
@clerk/ui
@clerk/upgrade
@clerk/vue
commit: |
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
… MDX pages
- JSDoc all 24 public OrganizationAPI methods + their parameter types.
- Register `organization-api` in `.typedoc/reference-objects.mjs` `BACKEND_API_CONFIG`.
- Disambiguate the colliding `GetOrganization{Membership,Invitation}ListParams`
exports (user-scoped on `UserApi`, org-scoped on `OrganizationApi`) via an
explicit `export type { ... } from './UserApi'` in `endpoints/index.ts`.
UserApi's variants remain the canonical public exports; OrganizationApi's
exports stay reachable for direct imports and for typedoc.
- `.typedoc/extract-methods.mjs`:
- Resolve nested rows when a param type is `Array<{...}>` (e.g.
`CreateBulkOrganizationInvitationParams`) by unwrapping the array element
in `resolveDeclarationWithObjectMembers`.
- Append `?` to nested `params.field` rows for optional child properties,
matching the inline-`{ ... }` flatten behavior in `custom-theme.mjs`.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
…collision
ESLint's `import/export` rule flagged the `export *` from both UserApi and
OrganizationApi as a duplicate-export conflict on `GetOrganizationMembershipListParams`
and `GetOrganizationInvitationListParams`, and the earlier explicit `export type
{ ... } from './UserApi'` disambiguator only added a third source of the names.
Replace `export * from './OrganizationApi'` with an explicit enumeration that omits
the two colliders, so only UserApi's user-scoped variants reach the public barrel.
OrganizationApi's org-scoped variants stay exported from the file itself, reachable
via direct import and resolvable by typedoc on the class methods.
Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
|
@alexisintech Have just committed a small docs review - organization for the Organization stuff. It fixes two things:
See before 
See after 
Have noticed a few odd things but wanted to get your opinion first, so will post a separate comment for those on |
The `./src/api/endpoints/**/*.ts` glob in `packages/backend/typedoc.json` was silently expanding to zero files in CI (Linux + Node 24.15) while expanding correctly locally (macOS), producing `[warning] The glob ... did not match any files` and skipping backend extraction entirely. Replace the glob with an explicit file list to sidestep the environment-sensitive expansion. Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
| "./src/api/endpoints/M2MTokenApi.ts", | ||
| "./src/api/endpoints/MachineApi.ts", | ||
| "./src/api/endpoints/OAuthApplicationsApi.ts", | ||
| "./src/api/endpoints/OrganizationApi.ts", |
There was a problem hiding this comment.
@alexisintech Adding both UserApi.ts and OrganizationApi.ts as Typedoc entrypoints produces standalone page collisions for shared param type names like GetOrganizationMembershipListParams and GetOrganizationInvitationListParams.
The generated output currently includes both the canonical file and a -1 variant, for example:
We could add a small post-processing step for these known endpoint param collisions so the generated files get stable scoped names (for example user-... vs organization-...) instead of leaking TypeDoc -1 suffixes into the public docs output?
So after Typedoc runs:
-
Detect the colliding generated pages
-
Rename them to stable names like:
user-get-organization-membership-list-params.mdx organization-get-organization-membership-list-params.mdx -
Rewrite generated links to use those names
There was a problem hiding this comment.
yes this was a big issue I kept trying to find the solution for and this is what me and my AFF came to - we don't actually use these files at all so while yes, we could add logic to handle these file names, it wouldn't be for anything. I'd rather not add unnecessary tech debt!
API Changes Report
Summary
@clerk/sharedCurrent version: 4.23.0 Subpath
|
…s flattening in generated table
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 15
Caution
Some comments are outside the diff and can’t be posted inline due to platform limitations.
⚠️ Outside diff range comments (8)
.typedoc/extract-methods.mjs (1)
1339-1357: 🎯 Functional Correctness | 🟡 Minor | ⚡ Quick winForward
methodFormatinto nested@extractMethodsnamespaces.extractCallableMembersFromDeclarationnow threadsmethodFormat, but this namespace branch still callsprocessExtractMethodsNamespace(childDecl, ctx, outDir)without it, so nested extracted methods keep the default reference-style titles and parameter headings.🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the rest with a brief reason, keep changes minimal, and validate. In @.typedoc/extract-methods.mjs around lines 1339 - 1357, extractCallableMembersFromDeclaration is not forwarding methodFormat into nested `@extractMethods` namespaces, so nested content falls back to the default reference formatting. Update the hasExtractMethodsModifier branch to pass methodFormat through to processExtractMethodsNamespace, and make sure that helper accepts and forwards it consistently when recursing. This keeps nested extracted methods using the same title and parameter heading style as the parent call path.packages/backend/src/api/resources/CommerceSubscriptionItem.ts (1)
57-92: 🎯 Functional Correctness | 🟠 Major | ⚡ Quick winAdd explicit return type annotation to
fromJSON.The
fromJSONstatic method is a public API but lacks an explicit return type annotation. It should returnBillingSubscriptionItem.Based on learnings, in TypeScript files within the clerk/javascript repository, enforce explicit return type annotations for exported functions and public APIs.
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the rest with a brief reason, keep changes minimal, and validate. In `@packages/backend/src/api/resources/CommerceSubscriptionItem.ts` around lines 57 - 92, The static fromJSON method in BillingSubscriptionItem is a public API but currently relies on type inference; add an explicit return type annotation of BillingSubscriptionItem to the method signature. Update the fromJSON declaration in CommerceSubscriptionItem so the return type is spelled out directly, keeping the existing conversion logic and helper formatAmountJSON unchanged.Source: Learnings
packages/backend/src/api/resources/CommercePlan.ts (1)
47-81: 🎯 Functional Correctness | 🟠 Major | ⚡ Quick winAdd explicit return type annotation to
fromJSON.The
fromJSONstatic method is a public API but lacks an explicit return type annotation. It should returnBillingPlan.Based on learnings, in TypeScript files within the clerk/javascript repository, enforce explicit return type annotations for exported functions and public APIs.
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the rest with a brief reason, keep changes minimal, and validate. In `@packages/backend/src/api/resources/CommercePlan.ts` around lines 47 - 81, The static API method BillingPlan.fromJSON is missing an explicit return type annotation. Update the method signature to declare it returns BillingPlan, keeping the existing construction logic unchanged, and apply the same explicit return-type pattern to any other public/exported APIs in this area if needed.Source: Learnings
packages/backend/src/api/endpoints/BillingApi.ts (1)
45-51: 🎯 Functional Correctness | 🟠 Major | ⚡ Quick winAdd explicit return type annotations to public API methods.
All public methods in
BillingAPIare missing explicit return type annotations. Based on the retrieved learning and coding guidelines, exported functions and public APIs must have explicit return types for API clarity and type safety.Current inferred return types:
getPlanList:Promise<PaginatedResourceResponse<BillingPlan[]>>cancelSubscriptionItem:Promise<BillingSubscriptionItem>extendSubscriptionItemFreeTrial:Promise<BillingSubscriptionItem>getOrganizationBillingSubscription:Promise<BillingSubscription>getUserBillingSubscription:Promise<BillingSubscription>Based on learnings, in TypeScript files within the clerk/javascript repository, enforce explicit return type annotations for exported functions and public APIs.
Also applies to: 60-67, 76-86, 93-99, 106-112
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the rest with a brief reason, keep changes minimal, and validate. In `@packages/backend/src/api/endpoints/BillingApi.ts` around lines 45 - 51, Add explicit return type annotations to every public method in BillingAPI so the API surface is clear and type-safe. Update getPlanList, cancelSubscriptionItem, extendSubscriptionItemFreeTrial, getOrganizationBillingSubscription, and getUserBillingSubscription to use their inferred Promise-based return types directly on the method signatures. Keep the implementation unchanged and make sure the annotations are applied consistently across the BillingAPI class.Source: Learnings
packages/backend/src/api/resources/CommerceSubscription.ts (1)
40-65: 🎯 Functional Correctness | 🟠 Major | ⚡ Quick winAdd explicit return type annotation to
fromJSON.The
fromJSONstatic method is a public API but lacks an explicit return type annotation. It should returnBillingSubscription.Based on learnings, in TypeScript files within the clerk/javascript repository, enforce explicit return type annotations for exported functions and public APIs.
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the rest with a brief reason, keep changes minimal, and validate. In `@packages/backend/src/api/resources/CommerceSubscription.ts` around lines 40 - 65, The static public API `BillingSubscription.fromJSON` is missing an explicit return type annotation. Update the `fromJSON` method on `BillingSubscription` to declare its return type as `BillingSubscription`, while keeping the existing construction logic intact. This should align with the repository’s TypeScript convention for exported/public APIs and make the intent of `fromJSON` explicit.Source: Learnings
packages/backend/src/api/resources/Feature.ts (1)
22-24: 🎯 Functional Correctness | 🟠 Major | ⚡ Quick winAdd explicit return type annotation to
fromJSON.The
fromJSONstatic method is a public API but lacks an explicit return type annotation. It should returnFeature.Based on learnings, in TypeScript files within the clerk/javascript repository, enforce explicit return type annotations for exported functions and public APIs.
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the rest with a brief reason, keep changes minimal, and validate. In `@packages/backend/src/api/resources/Feature.ts` around lines 22 - 24, The public static factory method Feature.fromJSON currently relies on type inference instead of an explicit return type. Add an explicit Feature return annotation to fromJSON so the public API contract is clear and consistent with the repository’s TypeScript guidance for exported/public methods.Source: Learnings
packages/backend/src/api/endpoints/RedirectUrlApi.ts (1)
20-26: 🎯 Functional Correctness | 🟠 Major | ⚡ Quick winAdd explicit return type annotations to public API methods.
All public methods in
RedirectUrlAPIare missing explicit return type annotations. Based on the retrieved learning and coding guidelines, exported functions and public APIs must have explicit return types.Current inferred return types:
getRedirectUrlList:Promise<PaginatedResourceResponse<RedirectUrl[]>>getRedirectUrl:Promise<RedirectUrl>createRedirectUrl:Promise<RedirectUrl>deleteRedirectUrl:Promise<RedirectUrl>Based on learnings, in TypeScript files within the clerk/javascript repository, enforce explicit return type annotations for exported functions and public APIs.
Also applies to: 32-38, 44-50, 57-63
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the rest with a brief reason, keep changes minimal, and validate. In `@packages/backend/src/api/endpoints/RedirectUrlApi.ts` around lines 20 - 26, All public methods in RedirectUrlAPI need explicit return type annotations instead of relying on inference. Update getRedirectUrlList, getRedirectUrl, createRedirectUrl, and deleteRedirectUrl in RedirectUrlApi to declare their Promise-based return types directly, matching the current inferred types, so the public API surface is explicit and consistent with the repository guidelines.Source: Learnings
packages/backend/src/api/endpoints/SignInTokenApi.ts (1)
21-27: 🎯 Functional Correctness | 🟠 Major | ⚡ Quick winAdd explicit return type annotations to public API methods.
Both public methods in
SignInTokenAPIare missing explicit return type annotations. Based on the retrieved learning and coding guidelines, exported functions and public APIs must have explicit return types.Current inferred return types:
createSignInToken:Promise<SignInToken>revokeSignInToken:Promise<SignInToken>Based on learnings, in TypeScript files within the clerk/javascript repository, enforce explicit return type annotations for exported functions and public APIs.
Also applies to: 34-40
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the rest with a brief reason, keep changes minimal, and validate. In `@packages/backend/src/api/endpoints/SignInTokenApi.ts` around lines 21 - 27, The public methods in SignInTokenAPI are relying on inferred return types, but exported/public APIs here must have explicit annotations. Add explicit Promise<SignInToken> return types to createSignInToken and revokeSignInToken so the class methods in SignInTokenApi are clearly typed regardless of inference.Source: Learnings
🧹 Nitpick comments (9)
packages/backend/src/api/endpoints/AgentTaskApi.ts (1)
39-39: 📐 Maintainability & Code Quality | 🔵 Trivial | ⚡ Quick winAdd explicit return type annotations to public methods.
createandrevokeare public APIs without explicit return types. Based on learnings, explicit return type annotations are enforced for exported functions and public APIs in this repository.Also applies to: 55-55
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the rest with a brief reason, keep changes minimal, and validate. In `@packages/backend/src/api/endpoints/AgentTaskApi.ts` at line 39, Add explicit return type annotations to the public API methods in AgentTaskApi, since create and revoke are exported/public methods and the repository requires them. Update the method signatures for create and revoke to declare their return types explicitly, matching the actual resolved values those methods already return.Source: Learnings
packages/backend/src/api/endpoints/TestingTokenApi.ts (1)
12-12: 📐 Maintainability & Code Quality | 🔵 Trivial | ⚡ Quick winAdd explicit return type annotation to
createTestingToken.This public API method lacks an explicit return type. Based on learnings, explicit return type annotations are enforced for exported functions and public APIs in this repository.
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the rest with a brief reason, keep changes minimal, and validate. In `@packages/backend/src/api/endpoints/TestingTokenApi.ts` at line 12, `createTestingToken` is a public API method without an explicit return type annotation; update the `TestingTokenApi.createTestingToken` signature to declare its return type explicitly, matching the repository’s requirement for public/exported APIs, while keeping the method behavior unchanged.Source: Learnings
packages/backend/src/api/resources/OrganizationDomain.ts (1)
38-51: 📐 Maintainability & Code Quality | 🔵 Trivial | ⚡ Quick winAdd explicit return type to
fromJSON.The
fromJSONstatic method lacks an explicit return type annotation, violating the explicit return type guideline for public APIs.- static fromJSON(data: OrganizationDomainJSON) { + static fromJSON(data: OrganizationDomainJSON): OrganizationDomain { return new OrganizationDomain(🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the rest with a brief reason, keep changes minimal, and validate. In `@packages/backend/src/api/resources/OrganizationDomain.ts` around lines 38 - 51, The static OrganizationDomain.fromJSON method is missing an explicit return type, so add a concrete return annotation to match the public API typing guideline. Update fromJSON in OrganizationDomain to declare its returned type as OrganizationDomain and keep the existing construction logic unchanged.Source: Coding guidelines
packages/backend/src/api/resources/Session.ts (1)
53-54: 📐 Maintainability & Code Quality | 🔵 Trivial | 💤 Low valueStandardize
lastActiveAtdescription to "Unix timestamp" for consistency.Other timestamp fields (
expireAt,abandonAt,createdAt,updatedAt) explicitly state "The Unix timestamp when...".lastActiveAtsays "The time the session was last active" which is less precise and inconsistent in generated docs.- /** The time the session was last active on the [`Client`](https://clerk.com/docs/reference/backend/types/backend-client). */ + /** The Unix timestamp when the session was last active on the [`Client`](https://clerk.com/docs/reference/backend/types/backend-client). */🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the rest with a brief reason, keep changes minimal, and validate. In `@packages/backend/src/api/resources/Session.ts` around lines 53 - 54, Update the `Session` type documentation for `lastActiveAt` to match the wording used by the other timestamp fields. In the `Session` interface/type, revise the `lastActiveAt` comment so it explicitly describes it as a Unix timestamp (using the same “The Unix timestamp when...” style as `expireAt`, `abandonAt`, `createdAt`, and `updatedAt`) for consistent generated docs.packages/backend/src/api/endpoints/SessionApi.ts (2)
106-114: 📐 Maintainability & Code Quality | 🔵 Trivial | 💤 Low value
getTokendescription implies template is required.The description says "generates a JWT using a specified template" but
templateis optional. When no template is provided, a session token is returned instead of a JWT. Consider making the conditional nature clearer.- * Gets a session token or generates a JWT using a specified template that is defined in the [**JWT templates**](https://dashboard.clerk.com/~/jwt-templates) page in the Clerk Dashboard. + * Gets a session token, or generates a JWT if a template is specified. Templates are defined in the [**JWT templates**](https://dashboard.clerk.com/~/jwt-templates) page in the Clerk Dashboard.🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the rest with a brief reason, keep changes minimal, and validate. In `@packages/backend/src/api/endpoints/SessionApi.ts` around lines 106 - 114, The `getToken` docs in `SessionApi` imply `template` is always required, but the method actually accepts it optionally and falls back to returning a session token when it is omitted. Update the JSDoc for `getToken` to clearly state the conditional behavior of `template`, and make the `@param template` and summary wording match the method’s optional flow so callers understand when a JWT is generated versus when a session token is returned.
134-146: 📐 Maintainability & Code Quality | 🔵 Trivial | 💤 Low value
refreshSessionoverloads have inconsistent JSDoc coverage.Only the first overload (
format: 'token') has JSDoc. The second overload (format: 'cookie') at line 147 and the implementation signature at line 149 lack documentation. Consumers see different docs depending on which overload matches. Consider adding consistent JSDoc to all overloads, or moving docs to the implementation signature.public async refreshSession( sessionId: string, params: RefreshTokenParams & { /** The format of the token to refresh. */ format: 'token'; }, ): Promise<Token>; + /** + * Refreshes the given session. + * `@param` sessionId - The ID of the session to refresh. + * `@param` params - The parameters to refresh the session. + * `@returns` The refreshed cookies. + */ public async refreshSession(sessionId: string, params: RefreshTokenParams & { format: 'cookie' }): Promise<Cookies>; public async refreshSession(sessionId: string, params: RefreshTokenParams): Promise<Token>;🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the rest with a brief reason, keep changes minimal, and validate. In `@packages/backend/src/api/endpoints/SessionApi.ts` around lines 134 - 146, The SessionApi.refreshSession overloads have uneven documentation coverage, so update the overload block to use consistent JSDoc across both signatures and the implementation. Add matching docs for the refreshSession signature with format: 'cookie', or move the shared JSDoc to the implementation signature so both overloads present the same consumer-facing documentation.packages/backend/src/api/resources/ExternalAccount.ts (1)
35-36: 📐 Maintainability & Code Quality | 🔵 Trivial | ⚡ Quick winAdd
{{ target: '_blank' }}to Backend API link for consistency.The
publicMetadatadescription links to the Backend API without{{ target: '_blank' }}, unlike the same field inUser.tsand other resources. This inconsistency will cause the generated docs to open this link differently.- /** Metadata that can be read from the Frontend API and Backend API and can be set only from the [Backend API](https://clerk.com/docs/reference/backend-api). */ + /** Metadata that can be read from the Frontend API and Backend API and can be set only from the [Backend API](https://clerk.com/docs/reference/backend-api){{ target: '_blank' }}. */🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the rest with a brief reason, keep changes minimal, and validate. In `@packages/backend/src/api/resources/ExternalAccount.ts` around lines 35 - 36, The publicMetadata docs in ExternalAccount are inconsistent with other resources because the Backend API link in the JSDoc comment is missing the target setting. Update the publicMetadata description to match the link style used in User.ts and related resource docs by adding the target='_blank' attribute to the Backend API reference, keeping the change within the ExternalAccount resource comment.packages/backend/src/api/endpoints/OrganizationApi.ts (1)
289-699: 📐 Maintainability & Code Quality | 🔵 TrivialThese JSDoc changes likely need Docs-team review before merge.
This file now rewrites a large chunk of the generated backend reference surface, so wording/link changes here are customer-facing. As per path instructions, changes to public/reference-facing JSDoc in
packages/**that may affect generated Clerk Docs content should get a Docs-team review note.🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the rest with a brief reason, keep changes minimal, and validate. In `@packages/backend/src/api/endpoints/OrganizationApi.ts` around lines 289 - 699, The JSDoc updates in OrganizationAPI are customer-facing and affect generated reference docs, so add the required Docs-team review note before merging. Update the public documentation comments in OrganizationAPI to explicitly flag the reference-surface changes for Docs review, keeping the note near the affected JSDoc blocks such as getOrganizationList, updateOrganizationMetadata, and replaceOrganizationMetadata so it’s easy to spot even if the generated content changes later.Source: Path instructions
packages/backend/src/api/resources/OAuthApplication.ts (1)
8-46: 📐 Maintainability & Code Quality | 🔵 Trivial | 💤 Low valueRemove "new" from resource property descriptions.
The constructor describes an existing
OAuthApplicationresource returned by the API, yet several JSDoc comments refer to "the new OAuth application" (e.g.,name,scopes,redirectUris). This wording belongs on creation parameters, not on the resource itself.- /** The name of the new OAuth application. */ + /** The name of the OAuth application. */ - /** Scopes for the new OAuth application. */ + /** Scopes for the OAuth application. */ - /** An array of redirect URIs of the new OAuth application. */ + /** An array of redirect URIs of the OAuth application. */🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the rest with a brief reason, keep changes minimal, and validate. In `@packages/backend/src/api/resources/OAuthApplication.ts` around lines 8 - 46, The JSDoc on OAuthApplication is describing an existing API resource, but several property comments still say “new OAuth application”; update the descriptions for fields like name, scopes, and redirectUris in OAuthApplication so they describe the returned resource rather than creation input, and keep the wording consistent across the class/constructor property docs.
🤖 Prompt for all review comments with AI agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
Inline comments:
In @.typedoc/custom-plugin.mjs:
- Around line 503-507: The reference-handling branch in
collectPropertiesFromType is reading only target.children, which misses members
defined on type aliases. Update the logic for the type.type === 'reference' path
to first inspect target.children, and if that is empty then fall back to
target.type.declaration.children before combining with argChildren. Keep the
change scoped to collectPropertiesFromType and the target resolution via
type.reflection/reflectionsByName so alias-backed fields like limit and offset
are included.
In `@packages/backend/src/api/endpoints/AgentTaskApi.ts`:
- Line 19: The JSDoc description for the AgentTaskApi permissions field contains
a typo: “support value” should be “supported value.” Update the comment on the
permissions description in AgentTaskApi so it reads naturally and matches the
intended wording.
In `@packages/backend/src/api/endpoints/AllowlistIdentifierApi.ts`:
- Around line 12-16: The AllowlistIdentifierApi contract is inconsistent because
`notify` is documented as defaulting to true but is currently required in
`AllowlistIdentifierCreateParams`. Update `AllowlistIdentifierCreateParams` in
`AllowlistIdentifierApi` so the type matches the actual behavior by making
`notify` optional if the implementation applies a default, or remove the default
language from the JSDoc if callers must always pass it. Keep the
public/reference-facing documentation aligned with the actual API behavior.
In `@packages/backend/src/api/endpoints/APIKeysApi.ts`:
- Around line 27-28: The exported claims type is using `any`, which weakens the
public API type safety. Update the `claims` alias in `APIKeysApi` to use the
shared JSON-compatible type (or `Record<string, unknown>` if that is the project
standard), and keep it aligned with the corresponding resource model so both
definitions match. Also apply the same change to the other `claims` declaration
referenced in the diff, preserving the public surface without `any`.
In `@packages/backend/src/api/endpoints/ClientApi.ts`:
- Around line 28-31: Update the JSDoc for getClient in ClientApi so it describes
fetching a single client by clientId instead of mentioning a list or sorting;
remove the plural “clients are returned sorted…” language and replace it with a
concise single-client description that matches the getClient method and its
existing `@param` clientId tag.
In `@packages/backend/src/api/endpoints/EmailAddressApi.ts`:
- Around line 70-74: Update the JSDoc for the public delete method in
EmailAddressApi so the documented return type matches the actual DeletedObject
result instead of EmailAddress. Keep the existing delete intent text, but fix
the `@returns` reference on the delete operation to point to the deleted object
shape used by the method implementation and generated backend docs.
In `@packages/backend/src/api/endpoints/InvitationApi.ts`:
- Around line 119-127: The JSDoc on InvitationApi’s revocation method has a
duplicated article in the customer-facing description. Update the comment for
the revoke invitation API so the sentence reads naturally without the extra “an”
in the public docs text, keeping the rest of the method documentation unchanged.
In `@packages/backend/src/api/endpoints/OrganizationApi.ts`:
- Around line 427-439: The JSDoc for replaceOrganizationMetadata currently
documents unsafeMetadata even though the API surface only accepts publicMetadata
and privateMetadata. Update the comment on
OrganizationApi.replaceOrganizationMetadata to remove the unsupported field and
keep the description aligned with MetadataParams and the request body so the
generated public docs are accurate.
- Around line 451-460: The deleteOrganization() method is missing the same ID
validation used by the neighboring ID-based methods, so it should call
requireId(organizationId) before constructing the request path. Update
deleteOrganization() in OrganizationApi to guard the input first, then pass the
validated ID into joinPaths(basePath, organizationId) so empty or falsy IDs fail
locally instead of falling through to the collection route.
In `@packages/backend/src/api/endpoints/PhoneNumberApi.ts`:
- Around line 74-78: The JSDoc for the delete method on PhoneNumberApi currently
documents the wrong return type as PhoneNumber, but the implementation returns
DeletedObject. Update the public-facing documentation on the delete phone number
API method to describe DeletedObject instead, keeping the method name and return
description aligned so generated docs reflect the actual contract.
In `@packages/backend/src/api/endpoints/UserApi.ts`:
- Around line 419-421: Fix the customer-facing JSDoc typos in UserApi’s public
methods so generated docs read correctly. Update each affected `@returns` block
to replace the repeated “than contains” phrasing with the correct wording, and
correct the “will result it in being consumed” typo in the referenced UserApi
method docs. Check the documented methods in UserApi, especially the return
descriptions around the listed occurrences, and keep the wording polished and
consistent across all public/reference-facing comments.
- Around line 403-410: Add the same type-level marker used by the other exported
param aliases to ReplaceUserEmailAddressParams and ReplaceUserPhoneNumberParams
in UserApi, so these public API types are treated consistently in generated
docs. Update each alias with the marker annotation pattern already present
elsewhere in this file for exported param types, keeping the identifiers
ReplaceUserEmailAddressParams and ReplaceUserPhoneNumberParams aligned with the
reference-output behavior.
- Around line 232-276: The CreateUserParams type currently loses the
password-hash pairing constraint because `(UserPasswordHashingParams | object)`
collapses to a plain object, allowing `passwordDigest` without `passwordHasher`.
Update the exported type in `CreateUserParams` to use a dedicated union that
preserves the dependency between these fields, so the hashing params stay
coupled when present. Keep the fix localized to the type definition and ensure
the `UserPasswordHashingParams` relationship remains enforced for callers of the
create-user API.
In `@packages/backend/src/api/endpoints/WaitlistEntryApi.ts`:
- Around line 24-29: The JSDoc for WaitlistEntryCreateParams.notify is carrying
over allowlist wording, which is inaccurate for the waitlist API. Update the
comment in WaitlistEntryCreateParams so it references waitlist entry creation
from emailAddress and uses customer-facing text aligned with the waitlist flow,
replacing any mention of allowlist or identifier with the correct waitlist
terminology.
In `@packages/backend/src/api/resources/User.ts`:
- Around line 31-32: The JSDoc for the User resource’s locked field is incorrect
because it repeats the banned description; update the comment on the locked
property in User.ts to describe lock status instead, using the locked symbol and
matching wording like “Whether the user is locked or not.”
---
Outside diff comments:
In @.typedoc/extract-methods.mjs:
- Around line 1339-1357: extractCallableMembersFromDeclaration is not forwarding
methodFormat into nested `@extractMethods` namespaces, so nested content falls
back to the default reference formatting. Update the hasExtractMethodsModifier
branch to pass methodFormat through to processExtractMethodsNamespace, and make
sure that helper accepts and forwards it consistently when recursing. This keeps
nested extracted methods using the same title and parameter heading style as the
parent call path.
In `@packages/backend/src/api/endpoints/BillingApi.ts`:
- Around line 45-51: Add explicit return type annotations to every public method
in BillingAPI so the API surface is clear and type-safe. Update getPlanList,
cancelSubscriptionItem, extendSubscriptionItemFreeTrial,
getOrganizationBillingSubscription, and getUserBillingSubscription to use their
inferred Promise-based return types directly on the method signatures. Keep the
implementation unchanged and make sure the annotations are applied consistently
across the BillingAPI class.
In `@packages/backend/src/api/endpoints/RedirectUrlApi.ts`:
- Around line 20-26: All public methods in RedirectUrlAPI need explicit return
type annotations instead of relying on inference. Update getRedirectUrlList,
getRedirectUrl, createRedirectUrl, and deleteRedirectUrl in RedirectUrlApi to
declare their Promise-based return types directly, matching the current inferred
types, so the public API surface is explicit and consistent with the repository
guidelines.
In `@packages/backend/src/api/endpoints/SignInTokenApi.ts`:
- Around line 21-27: The public methods in SignInTokenAPI are relying on
inferred return types, but exported/public APIs here must have explicit
annotations. Add explicit Promise<SignInToken> return types to createSignInToken
and revokeSignInToken so the class methods in SignInTokenApi are clearly typed
regardless of inference.
In `@packages/backend/src/api/resources/CommercePlan.ts`:
- Around line 47-81: The static API method BillingPlan.fromJSON is missing an
explicit return type annotation. Update the method signature to declare it
returns BillingPlan, keeping the existing construction logic unchanged, and
apply the same explicit return-type pattern to any other public/exported APIs in
this area if needed.
In `@packages/backend/src/api/resources/CommerceSubscription.ts`:
- Around line 40-65: The static public API `BillingSubscription.fromJSON` is
missing an explicit return type annotation. Update the `fromJSON` method on
`BillingSubscription` to declare its return type as `BillingSubscription`, while
keeping the existing construction logic intact. This should align with the
repository’s TypeScript convention for exported/public APIs and make the intent
of `fromJSON` explicit.
In `@packages/backend/src/api/resources/CommerceSubscriptionItem.ts`:
- Around line 57-92: The static fromJSON method in BillingSubscriptionItem is a
public API but currently relies on type inference; add an explicit return type
annotation of BillingSubscriptionItem to the method signature. Update the
fromJSON declaration in CommerceSubscriptionItem so the return type is spelled
out directly, keeping the existing conversion logic and helper formatAmountJSON
unchanged.
In `@packages/backend/src/api/resources/Feature.ts`:
- Around line 22-24: The public static factory method Feature.fromJSON currently
relies on type inference instead of an explicit return type. Add an explicit
Feature return annotation to fromJSON so the public API contract is clear and
consistent with the repository’s TypeScript guidance for exported/public
methods.
---
Nitpick comments:
In `@packages/backend/src/api/endpoints/AgentTaskApi.ts`:
- Line 39: Add explicit return type annotations to the public API methods in
AgentTaskApi, since create and revoke are exported/public methods and the
repository requires them. Update the method signatures for create and revoke to
declare their return types explicitly, matching the actual resolved values those
methods already return.
In `@packages/backend/src/api/endpoints/OrganizationApi.ts`:
- Around line 289-699: The JSDoc updates in OrganizationAPI are customer-facing
and affect generated reference docs, so add the required Docs-team review note
before merging. Update the public documentation comments in OrganizationAPI to
explicitly flag the reference-surface changes for Docs review, keeping the note
near the affected JSDoc blocks such as getOrganizationList,
updateOrganizationMetadata, and replaceOrganizationMetadata so it’s easy to spot
even if the generated content changes later.
In `@packages/backend/src/api/endpoints/SessionApi.ts`:
- Around line 106-114: The `getToken` docs in `SessionApi` imply `template` is
always required, but the method actually accepts it optionally and falls back to
returning a session token when it is omitted. Update the JSDoc for `getToken` to
clearly state the conditional behavior of `template`, and make the `@param
template` and summary wording match the method’s optional flow so callers
understand when a JWT is generated versus when a session token is returned.
- Around line 134-146: The SessionApi.refreshSession overloads have uneven
documentation coverage, so update the overload block to use consistent JSDoc
across both signatures and the implementation. Add matching docs for the
refreshSession signature with format: 'cookie', or move the shared JSDoc to the
implementation signature so both overloads present the same consumer-facing
documentation.
In `@packages/backend/src/api/endpoints/TestingTokenApi.ts`:
- Line 12: `createTestingToken` is a public API method without an explicit
return type annotation; update the `TestingTokenApi.createTestingToken`
signature to declare its return type explicitly, matching the repository’s
requirement for public/exported APIs, while keeping the method behavior
unchanged.
In `@packages/backend/src/api/resources/ExternalAccount.ts`:
- Around line 35-36: The publicMetadata docs in ExternalAccount are inconsistent
with other resources because the Backend API link in the JSDoc comment is
missing the target setting. Update the publicMetadata description to match the
link style used in User.ts and related resource docs by adding the
target='_blank' attribute to the Backend API reference, keeping the change
within the ExternalAccount resource comment.
In `@packages/backend/src/api/resources/OAuthApplication.ts`:
- Around line 8-46: The JSDoc on OAuthApplication is describing an existing API
resource, but several property comments still say “new OAuth application”;
update the descriptions for fields like name, scopes, and redirectUris in
OAuthApplication so they describe the returned resource rather than creation
input, and keep the wording consistent across the class/constructor property
docs.
In `@packages/backend/src/api/resources/OrganizationDomain.ts`:
- Around line 38-51: The static OrganizationDomain.fromJSON method is missing an
explicit return type, so add a concrete return annotation to match the public
API typing guideline. Update fromJSON in OrganizationDomain to declare its
returned type as OrganizationDomain and keep the existing construction logic
unchanged.
In `@packages/backend/src/api/resources/Session.ts`:
- Around line 53-54: Update the `Session` type documentation for `lastActiveAt`
to match the wording used by the other timestamp fields. In the `Session`
interface/type, revise the `lastActiveAt` comment so it explicitly describes it
as a Unix timestamp (using the same “The Unix timestamp when...” style as
`expireAt`, `abandonAt`, `createdAt`, and `updatedAt`) for consistent generated
docs.
🪄 Autofix (Beta)
Fix all unresolved CodeRabbit comments on this PR:
- Push a commit to this branch (recommended)
- Create a new PR with the fixes
ℹ️ Review info
⚙️ Run configuration
Configuration used: Repository YAML (base), Repository UI (inherited)
Review profile: CHILL
Plan: Pro Plus
Run ID: ec92a174-670a-4383-9d5d-1c14fb650fd8
📒 Files selected for processing (79)
.changeset/docs-backend-typedoc.md.typedoc/__tests__/__snapshots__/clerk-properties.mdx.typedoc/__tests__/__snapshots__/sign-in-future-resource-methods-email-link.mdx.typedoc/__tests__/file-structure.test.ts.typedoc/custom-plugin.mjs.typedoc/custom-theme.mjs.typedoc/extract-methods.mjs.typedoc/reference-objects.mjspackages/backend/src/api/endpoints/APIKeysApi.tspackages/backend/src/api/endpoints/AgentTaskApi.tspackages/backend/src/api/endpoints/AllowlistIdentifierApi.tspackages/backend/src/api/endpoints/BillingApi.tspackages/backend/src/api/endpoints/ClientApi.tspackages/backend/src/api/endpoints/DomainApi.tspackages/backend/src/api/endpoints/EmailAddressApi.tspackages/backend/src/api/endpoints/EnterpriseConnectionApi.tspackages/backend/src/api/endpoints/InvitationApi.tspackages/backend/src/api/endpoints/M2MTokenApi.tspackages/backend/src/api/endpoints/MachineApi.tspackages/backend/src/api/endpoints/OAuthApplicationsApi.tspackages/backend/src/api/endpoints/OrganizationApi.tspackages/backend/src/api/endpoints/PhoneNumberApi.tspackages/backend/src/api/endpoints/RedirectUrlApi.tspackages/backend/src/api/endpoints/SessionApi.tspackages/backend/src/api/endpoints/SignInTokenApi.tspackages/backend/src/api/endpoints/TestingTokenApi.tspackages/backend/src/api/endpoints/UserApi.tspackages/backend/src/api/endpoints/WaitlistEntryApi.tspackages/backend/src/api/endpoints/index.tspackages/backend/src/api/resources/APIKey.tspackages/backend/src/api/resources/AgentTask.tspackages/backend/src/api/resources/AllowlistIdentifier.tspackages/backend/src/api/resources/Client.tspackages/backend/src/api/resources/CommercePlan.tspackages/backend/src/api/resources/CommerceSubscription.tspackages/backend/src/api/resources/CommerceSubscriptionItem.tspackages/backend/src/api/resources/DeletedObject.tspackages/backend/src/api/resources/Domain.tspackages/backend/src/api/resources/EmailAddress.tspackages/backend/src/api/resources/EnterpriseAccount.tspackages/backend/src/api/resources/EnterpriseConnection.tspackages/backend/src/api/resources/Enums.tspackages/backend/src/api/resources/ExternalAccount.tspackages/backend/src/api/resources/Feature.tspackages/backend/src/api/resources/IdentificationLink.tspackages/backend/src/api/resources/Invitation.tspackages/backend/src/api/resources/JSON.tspackages/backend/src/api/resources/M2MToken.tspackages/backend/src/api/resources/Machine.tspackages/backend/src/api/resources/MachineScope.tspackages/backend/src/api/resources/MachineSecretKey.tspackages/backend/src/api/resources/OAuthApplication.tspackages/backend/src/api/resources/OauthAccessToken.tspackages/backend/src/api/resources/Organization.tspackages/backend/src/api/resources/OrganizationDomain.tspackages/backend/src/api/resources/OrganizationInvitation.tspackages/backend/src/api/resources/OrganizationMembership.tspackages/backend/src/api/resources/Permission.tspackages/backend/src/api/resources/PhoneNumber.tspackages/backend/src/api/resources/RedirectUrl.tspackages/backend/src/api/resources/Role.tspackages/backend/src/api/resources/RoleSet.tspackages/backend/src/api/resources/SamlConnection.tspackages/backend/src/api/resources/Session.tspackages/backend/src/api/resources/SignInTokens.tspackages/backend/src/api/resources/TestingToken.tspackages/backend/src/api/resources/User.tspackages/backend/src/api/resources/Verification.tspackages/backend/src/api/resources/WaitlistEntry.tspackages/backend/src/api/resources/Web3Wallet.tspackages/backend/src/api/resources/index.tspackages/backend/typedoc.jsonpackages/shared/src/react/billing/payment-element.tsxpackages/shared/src/types/billing.tspackages/shared/src/types/clerk.tspackages/shared/src/types/organization.tspackages/shared/src/types/organizationDomain.tspackages/shared/src/types/pagination.tstypedoc.config.mjs
💤 Files with no reviewable changes (1)
- packages/backend/src/api/resources/MachineSecretKey.ts
| if (type.type === 'reference') { | ||
| const target = type.reflection ?? reflectionsByName.get(type.name); | ||
| const targetChildren = target?.children ?? []; | ||
| const argChildren = (type.typeArguments ?? []).flatMap(t => collectPropertiesFromType(t, reflectionsByName)); | ||
| return [...targetChildren, ...argChildren]; |
There was a problem hiding this comment.
🎯 Functional Correctness | 🟠 Major | ⚡ Quick win
🧩 Analysis chain
🌐 Web query:
In TypeDoc 0.28.5, where are object-literal members of a type alias like type Foo = { a: string } & Tstored:reflection.childrenorreflection.type.declaration.children?
💡 Result:
In TypeDoc 0.28.5, the object-literal members coming from a type alias like type Foo<T> = { a: string } & T end up stored under reflection.type.declaration.children (i.e., as children of the internal DeclarationReflection that belongs to the alias’s type), not under reflection.children. TypeDoc’s DeclarationReflection.getProperties() first checks this.children and, if that’s empty, falls back to this.type.declaration.children when this.type.type === "reflection" [1]. The ReflectionType model represents an object-literal-ish type by holding a declaration: DeclarationReflection [2], and it renders its members by iterating this.declaration.children [2]. Thus, for type aliases whose object literal is represented as a ReflectionType, the members are placed on reflection.type.declaration.children [2][1].
Citations:
- 1: https://github.com/TypeStrong/typedoc/blob/2d23fc06f2d71ce682ccd79a6f3f136d85ca81f3/src/lib/models/DeclarationReflection.ts
- 2: https://github.com/TypeStrong/typedoc/blob/ea16fb7cc48e3cbdaca006e866c5dbaf45a19dfa/src/lib/models/types.ts
🏁 Script executed:
#!/bin/bash
set -euo pipefail
# Inspect the plugin around the referenced lines.
file=".typedoc/custom-plugin.mjs"
wc -l "$file"
sed -n '470,540p' "$file"
# Find the helper and any handling of reflection/type.declaration.
rg -n "collectPropertiesFromType|type\.declaration|reflection\.children|children \?\?" "$file"
# Inspect nearby TypeDoc-related usage in the repo, if any.
rg -n "expandProperties|ClerkPaginationRequest|ClerkPaginationParams|typedoc" .Repository: clerk/javascript
Length of output: 2017
Pull alias-backed members from the alias type .typedoc/custom-plugin.mjs:503-507 uses target?.children ?? [], but TypeDoc stores object-literal members for type aliases on target.type.declaration.children. Since children is usually an empty array, the fallback never runs and wrapper fields like limit / offset are omitted. Use an emptiness check before falling back to target.type.
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
In @.typedoc/custom-plugin.mjs around lines 503 - 507, The reference-handling
branch in collectPropertiesFromType is reading only target.children, which
misses members defined on type aliases. Update the logic for the type.type ===
'reference' path to first inspect target.children, and if that is empty then
fall back to target.type.declaration.children before combining with argChildren.
Keep the change scoped to collectPropertiesFromType and the target resolution
via type.reflection/reflectionsByName so alias-backed fields like limit and
offset are included.
| /** Custom claims to store additional information about the API key. */ | ||
| claims?: Record<string, any> | null; |
There was a problem hiding this comment.
📐 Maintainability & Code Quality | 🟡 Minor | ⚡ Quick win
Avoid any in the exported claims shape.
These aliases are now public surface, so Record<string, any> throws away consumer type-safety. Prefer the shared JSON type here, or at least Record<string, unknown>, and keep it aligned with the resource model. As per coding guidelines, "No any types without justification in code review".
Also applies to: 53-54
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
In `@packages/backend/src/api/endpoints/APIKeysApi.ts` around lines 27 - 28, The
exported claims type is using `any`, which weakens the public API type safety.
Update the `claims` alias in `APIKeysApi` to use the shared JSON-compatible type
(or `Record<string, unknown>` if that is the project standard), and keep it
aligned with the corresponding resource model so both definitions match. Also
apply the same change to the other `claims` declaration referenced in the diff,
preserving the public surface without `any`.
Source: Coding guidelines
| /** @generateWithEmptyComment */ | ||
| export type CreateUserParams = { | ||
| /** The ID of the user as used in your external systems or your previous authentication solution. Must be unique across your instance. */ | ||
| externalId?: string; | ||
| /** The email address(es) to assign to the user. Must be unique across your instance. The first email address will be set as the users primary email address. */ | ||
| emailAddress?: string[]; | ||
| /** The phone number(s) to assign to the user. Must be unique across your instance. The first phone number will be set as the users primary phone number. */ | ||
| phoneNumber?: string[]; | ||
| /** The username to assign to the user. Must be unique across your instance. */ | ||
| username?: string; | ||
| /** The plaintext password to give the user. Must be at least 8 characters long, and can't be in any list of hacked passwords. */ | ||
| password?: string; | ||
| /** The first name to assign to the user. */ | ||
| firstName?: string; | ||
| /** The last name to assign to the user. */ | ||
| lastName?: string; | ||
| /** The locale of the user in BCP-47 format. */ | ||
| /** The locale of the user in BCP-47 format (e.g. `'en-US'`, `'fr-FR'`). */ | ||
| locale?: string; | ||
| /** When set to `true`, all password checks are skipped. It is recommended to use this method only when migrating plaintext passwords to Clerk. Upon migration the user base should be prompted to pick stronger password. */ | ||
| skipPasswordChecks?: boolean; | ||
| /** When set to `true`, password is not required anymore when creating the user and can be omitted. This is useful when you are trying to create a user that doesn't have a password, in an instance that is using passwords. **You cannot use this flag if password is the only way for a user to sign into your instance.** */ | ||
| skipPasswordRequirement?: boolean; | ||
| /** When set to `true`, all legal checks are skipped. It is not recommended to skip legal checks unless you are migrating a user to Clerk. */ | ||
| skipLegalChecks?: boolean; | ||
| /** A custom timestamp denoting when the user accepted legal requirements, specified in RFC3339 format (e.g. `'2012-10-20T07:15:20.902Z'`). */ | ||
| legalAcceptedAt?: Date; | ||
| /** | ||
| * If TOTP is enabled on the instance, you can provide the secret to enable it on the newly created user without the need to reset it. Currently, the supported options are: | ||
| * <ul> | ||
| * <li>Period: 30 seconds</li> | ||
| * <li>Code length: 6 digits</li> | ||
| * <li>Algorithm: SHA1</li> | ||
| * </ul> | ||
| */ | ||
| totpSecret?: string; | ||
| /** If backup codes are enabled on the instance, you can provide them to enable it on the newly created user without the need to reset them. You must provide the backup codes in plain format or the corresponding bcrypt digest. */ | ||
| backupCodes?: string[]; | ||
| /** A custom timestamp denoting when the user signed up to the application, specified in RFC3339 format (e.g. `'2012-10-20T07:15:20.902Z'`). */ | ||
| createdAt?: Date; | ||
| /** When set to `true`, the user is created already banned and cannot sign in. Requires the same plan support as the ban user endpoint. */ | ||
| /** When set to `true`, the user is created already banned and cannot sign in. */ | ||
| banned?: boolean; | ||
| /** When set to `true`, the user is created already locked. Requires the user lockout feature to be enabled on the instance. */ | ||
| /** When set to `true`, the user is created already locked. Requires the [user lockout feature](https://clerk.com/docs/guides/secure/user-lockout#lock-a-user-programmatically) to be enabled on the instance. */ | ||
| locked?: boolean; | ||
| } & UserMetadataParams & | ||
| (UserPasswordHashingParams | object); |
There was a problem hiding this comment.
🎯 Functional Correctness | 🟠 Major | ⚡ Quick win
🧩 Analysis chain
🏁 Script executed:
sed -n '1,220p' packages/backend/src/api/endpoints/UserApi.tsRepository: clerk/javascript
Length of output: 2017
Restore the password-hash pairing constraint on these exported params types.
(UserPasswordHashingParams | object) collapses to the plain object branch, so passwordDigest can be passed without passwordHasher. Use a dedicated union that keeps those fields coupled if both are required.
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
In `@packages/backend/src/api/endpoints/UserApi.ts` around lines 232 - 276, The
CreateUserParams type currently loses the password-hash pairing constraint
because `(UserPasswordHashingParams | object)` collapses to a plain object,
allowing `passwordDigest` without `passwordHasher`. Update the exported type in
`CreateUserParams` to use a dedicated union that preserves the dependency
between these fields, so the hashing params stay coupled when present. Keep the
fix localized to the type definition and ensure the `UserPasswordHashingParams`
relationship remains enforced for callers of the create-user API.
Source: Path instructions
Document the method for source readers and exclude it from the generated backend docs via @internal (excludeInternal is enabled in typedoc.config).
There was a problem hiding this comment.
Actionable comments posted: 1
🧹 Nitpick comments (1)
packages/backend/src/api/endpoints/InstanceApi.ts (1)
68-68: 📐 Maintainability & Code Quality | 🔵 Trivial | ⚡ Quick winAdd explicit return types to these public methods.
These endpoint methods are part of the public API surface, so relying on inference here makes the contract easier to drift during future refactors.
Suggested change
- public async get() { + public async get(): Promise<Instance> { @@ - public async update(params: UpdateParams) { + public async update(params: UpdateParams): Promise<void> { @@ - public async updateRestrictions(params: UpdateRestrictionsParams) { + public async updateRestrictions(params: UpdateRestrictionsParams): Promise<InstanceRestrictions> { @@ - public async getOrganizationSettings() { + public async getOrganizationSettings(): Promise<OrganizationSettings> { @@ - public async updateOrganizationSettings(params: UpdateOrganizationSettingsParams) { + public async updateOrganizationSettings( + params: UpdateOrganizationSettingsParams, + ): Promise<OrganizationSettings> {As per coding guidelines,
Always define explicit return types for functions, especially public APIs; based on learnings,enforce explicit return type annotations for exported functions and public APIs.Also applies to: 78-78, 90-90, 101-101, 112-112
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the rest with a brief reason, keep changes minimal, and validate. In `@packages/backend/src/api/endpoints/InstanceApi.ts` at line 68, Add explicit return type annotations to each public endpoint method in InstanceApi so the API contract is stable and doesn’t rely on inference. Update the signatures of get, create, update, delete, and any other public methods in this class to declare their return types directly, keeping the existing behavior unchanged while making the public surface explicit.Sources: Coding guidelines, Learnings
🤖 Prompt for all review comments with AI agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
Inline comments:
In `@packages/backend/src/api/endpoints/InstanceApi.ts`:
- Around line 55-56: The request type for verified-domain enrollment modes is
too broad because domainsEnrollmentModes in InstanceApi still uses
Array<string>, which allows unsupported values. Update this field to use the
existing DomainsEnrollmentModes union (and any corresponding array form used
elsewhere in the backend) so the exported API type matches the supported
verified-domain modes and stays consistent with the other enrollment mode
definitions.
---
Nitpick comments:
In `@packages/backend/src/api/endpoints/InstanceApi.ts`:
- Line 68: Add explicit return type annotations to each public endpoint method
in InstanceApi so the API contract is stable and doesn’t rely on inference.
Update the signatures of get, create, update, delete, and any other public
methods in this class to declare their return types directly, keeping the
existing behavior unchanged while making the public surface explicit.
🪄 Autofix (Beta)
Fix all unresolved CodeRabbit comments on this PR:
- Push a commit to this branch (recommended)
- Create a new PR with the fixes
ℹ️ Review info
⚙️ Run configuration
Configuration used: Repository YAML (base), Repository UI (inherited)
Review profile: CHILL
Plan: Pro Plus
Run ID: a1430cc4-c329-4c62-a167-f78ae9ae20df
📒 Files selected for processing (6)
.typedoc/__tests__/file-structure.test.ts.typedoc/reference-objects.mjspackages/backend/src/api/endpoints/InstanceApi.tspackages/backend/src/api/resources/Instance.tspackages/backend/src/api/resources/InstanceRestrictions.tspackages/backend/src/api/resources/OrganizationSettings.ts
✅ Files skipped from review due to trivial changes (4)
- packages/backend/src/api/resources/InstanceRestrictions.ts
- packages/backend/src/api/resources/OrganizationSettings.ts
- .typedoc/tests/file-structure.test.ts
- packages/backend/src/api/resources/Instance.ts
🚧 Files skipped from review as they are similar to previous changes (1)
- .typedoc/reference-objects.mjs
| /** Specifies which [enrollment modes](https://clerk.com/docs/guides/organizations/add-members/verified-domains#enable-verified-domains) to enable for your Organization's [Verified Domains](https://clerk.com/docs/guides/organizations/add-members/verified-domains). Supported modes are `'automatic_invitation'` & `'automatic_suggestion'`. */ | ||
| domainsEnrollmentModes?: Array<string> | undefined; |
There was a problem hiding this comment.
🗄️ Data Integrity & Integration | 🟡 Minor | ⚡ Quick win
🧩 Analysis chain
🏁 Script executed:
#!/bin/bash
set -euo pipefail
echo "== InstanceApi excerpt =="
sed -n '1,140p' packages/backend/src/api/endpoints/InstanceApi.ts
echo
echo "== Search for domainsEnrollmentModes and related types =="
rg -n "domainsEnrollmentModes|automatic_invitation|automatic_suggestion|OrganizationDomainEnrollmentMode|EnrollmentMode" packages/backend/src packages -g '!**/dist/**' -g '!**/build/**'Repository: clerk/javascript
Length of output: 22028
🏁 Script executed:
#!/bin/bash
set -euo pipefail
# Focused search for the endpoint and any runtime validation/schema around it.
rg -n "domainsEnrollmentModes|Verified Domains|automatic_invitation|automatic_suggestion" packages/backend/src -g '!**/dist/**' -g '!**/build/**'
echo
echo "== Nearby file list =="
git ls-files packages/backend/src/api/endpoints | sed -n '1,120p'Repository: clerk/javascript
Length of output: 7373
🏁 Script executed:
#!/bin/bash
set -euo pipefail
file=packages/backend/src/api/endpoints/InstanceApi.ts
echo "== line count =="
wc -l "$file"
echo
echo "== lines 1-120 =="
sed -n '1,120p' "$file"
echo
echo "== direct symbol search in this file =="
rg -n "UpdateOrganizationSettingsParams|domainsEnrollmentModes|type .*Enrollment|export type" "$file"Repository: clerk/javascript
Length of output: 7696
Use the existing DomainsEnrollmentModes union here. Array<string> still accepts unsupported values, and this exported request type should match the supported verified-domain modes used elsewhere in the backend.
🤖 Prompt for AI Agents
Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.
In `@packages/backend/src/api/endpoints/InstanceApi.ts` around lines 55 - 56, The
request type for verified-domain enrollment modes is too broad because
domainsEnrollmentModes in InstanceApi still uses Array<string>, which allows
unsupported values. Update this field to use the existing DomainsEnrollmentModes
union (and any corresponding array form used elsewhere in the backend) so the
exported API type matches the supported verified-domain modes and stays
consistent with the other enrollment mode definitions.
Source: Coding guidelines
|
@alexisintech Left a docs review - Instance API with the following changes:
These two also don't seem to be leading to the correct place (#role-limits and #permission-limits don't exist). 
|
my AI hallucinated when filling the links LOL I've removed them! we don't currently mention role or permission limits in the docs so there's nothing to link to |
Do we not want to link them to: https://clerk.com/docs/guides/organizations/control-access/roles-and-permissions? @alexisintech To follow what's in other JSdocs 
|
…collision with InstanceApi Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
3 participants
Summary
packages/backend/src/api/endpoints/**/*.packages/backend/src/api/resources/**/*model classes (e.g.User,Session,Organization,OrganizationInvitation,Verification,AllowlistIdentifier,Role,Permission,BillingPlan,BillingSubscription{,Item},EnterpriseAccount,ExternalAccount,OAuthApplication,WaitlistEntry, …). Recurring patterns:The date when …→The Unix timestamp when …on everycreatedAt/updatedAt/expiresAt/lastActiveAt/ etc.A boolean indicating whether …→Whether ….{{ target: '_blank' }}to Backend API links and converts bare mentions of Roles / Permissions / Organizations / Sessions into proper doc links.M2MToken,Machine,MachineScopego from a one-line description stub to a full properties table.@expandPropertiesmodifier tag (handled by.typedoc/custom-plugin.mjs, registered intypedoc.config.mjs) so generic-instantiation aliases likeUserListParams = ClerkPaginationRequest<{...}>render as a single merged properties table instead of an empty page. typedoc-plugin-markdown otherwise has no rendering branch for top-levelReferenceTypes. Tag applied toClerkPaginationRequestandClerkPaginationParams.extract-methods.mjspipeline via a newBACKEND_API_CONFIGin.typedoc/reference-objects.mjs. Each endpoint class registered here gets abackend/<kebab-name>/folder containing<name>.mdx(main page) andmethods/<method>.mdx(one file per public method, with description + TypeScript signature + parameters).extract-methods.mjsnow supports two output styles via amethodFormatoption plumbed from the config:reference(existing reference-object pages — Clerk, UserResource, etc.):### foo()title +#### Parametersheading. Designed for pages aggregating many methods.page(new, used byBACKEND_API_CONFIG): no method-name title,## Parametersheading. Designed for one-method-per-docs-page consumption.getPrimaryCallSignatureskips@deprecatedoverloads (preferring the canonical signature when multiple are exposed).parametersMarkdownTableoverlays@paramblock tags fromsig.commentonto each parameter when their own comment is missing — fixes overloaded methods where the implementation's JSDoc carries the descriptions but typedoc only wires them onto the hidden implementation signature, leaving overloads with no per-parameter descriptions.nestedParameterRowsFromDocumentedPropertiesstrips line breaks in the description column, so JSDoc descriptions containing<ul>blocks no longer shatter the markdown table.resolveDeclarationWithObjectMembersnow unwrapsArrayType.elementTypesoparams: Array<{...}>(e.g.CreateBulkOrganizationInvitationParams) flattens into nestedparams.*rows instead of dumping the inline shape into the Type column.formatNestedParamNameColumnnow appends?to nested rows when the child property is optional (read fromchild.flags?.isOptional) — matches the inline-{ ... }flatten behavior inclerkParametersTable.flattenParams. Retroactively adds?markers to previously-incorrect rows likeupdate-user.mdx'sparams.backupCodes?,params.firstName?, etc.custom-theme.mjsreferenceTypepartial: when a property's type is an@inlineclass or interface, render it inline as\{ key: type; … \}at use sites (previously left as a bare type name with no fields). Pairs with newappendInlineObjectChildPropertyRowsin thepropertiesTablepartial, which emits nestedparent.childrows for properties whose type unwraps to an@inlineinterface — including the union-arm case (PublicOrganizationDataJSON | null) where TypeDoc has already inlined the reference into aReflectionType. Picks up the same expansion behavior forsdkMetadata.*,telemetry.*,nextPayment.*,actor.*, and similar union/inline cases across the Clerk, Session, and Billing pages.packages/backend/typedoc.json: enumerates eachsrc/api/endpoints/*.tsfile explicitly as a typedoc entry point (previously only theresources/index was listed), so the endpoint classes are picked up by the generator.packages/shared/src/types/{billing,clerk,organization,organizationDomain,pagination}.tsandpackages/shared/src/react/billing/payment-element.tsx(mostlyWhether …rephrasings, link-href tweaks, and an@interfacetag onWithOptionalOrgTypeso it gets a properties-style page)..typedoc/__tests__/file-structure.test.tsextends the allowed nested-folders snapshot to include the newbackend/*-api/backend/*-api/methodspaths; updated 2 extract-methods snapshots (clerk-properties.mdx,sign-in-future-resource-methods-email-link.mdx) for the new@inlineparent.child row expansion..changeset/docs-backend-typedoc.md) — no user-facing package change.Summary by CodeRabbit
tokenconstructor field forM2MToken.