fix: add JSDoc docstrings from OpenAPI spec to all resource methods#1565
Merged
gjtorikian merged 5 commits intomainfrom Apr 21, 2026
Merged
fix: add JSDoc docstrings from OpenAPI spec to all resource methods#1565gjtorikian merged 5 commits intomainfrom
gjtorikian merged 5 commits intomainfrom
Conversation
|
Caution Review failedThe pull request is closed. ℹ️ Recent review info⚙️ Run configurationConfiguration used: Organization UI Review profile: ASSERTIVE Plan: Pro Plus Run ID: 📒 Files selected for processing (2)
Disabled knowledge base sources:
📝 WalkthroughWalkthroughAdded JSDoc comments across many modules and expanded several TypeScript interfaces with additional fields and optional filters; a few interfaces gained new properties (e.g., Invitation, PasswordReset, Directory, ListMembershipsForResourceOptions). No runtime logic or public method signatures were changed. Changes
Possibly related PRs
Suggested reviewers
🚥 Pre-merge checks | ✅ 4 | ❌ 1❌ Failed checks (1 warning)
✅ Passed checks (4 passed)
✏️ Tip: You can configure your own custom pre-merge checks in the settings. ✨ Finishing Touches📝 Generate docstrings
🧪 Generate unit tests (beta)
Comment |
Contributor
Greptile SummaryThis PR adds comprehensive JSDoc docstrings (sourced from the OpenAPI spec) to public API methods and TypeScript interfaces across 34 files, covering user management, SSO, directory sync, organizations, authorization, and more. It also introduces several new optional filter fields ( Confidence Score: 5/5Safe to merge — all remaining findings are minor documentation gaps (P2) with no functional impact. All changes are additive JSDoc comments and a small number of new optional interface fields. No runtime logic is modified, no security boundaries are touched, and the two flagged gaps ( No files require special attention beyond the two minor doc gaps noted in inline comments. Important Files Changed
Flowchart%%{init: {'theme': 'neutral'}}%%
flowchart TD
A[OpenAPI Spec] -->|JSDoc sourced from| B[Method JSDoc\nin .ts class files]
A -->|Field descriptions sourced from| C[Interface JSDoc\nin .interface.ts files]
B --> B1[user-management.ts]
B --> B2[sso.ts]
B --> B3[directory-sync.ts]
B --> B4[organizations.ts]
B --> B5[authorization.ts]
B --> B6[Other modules...]
C --> C1[invitation.interface.ts\nnew: acceptedAt, revokedAt, acceptedUserId]
C --> C2[password-reset.interface.ts\nnew: passwordResetToken, passwordResetUrl]
C --> C3[organization.interface.ts\ndeprecated: allowProfilesOutsideOrganization]
C --> C4[list-*-options.interface.ts\nnew optional filters]
Reviews (4): Last reviewed commit: "more bot feedback" | Re-trigger Greptile |
![greptile-apps[bot]](https://avatars.githubusercontent.com/in/867647?s=60&v=4){kind=small}
![coderabbitai[bot]](https://avatars.githubusercontent.com/in/347564?s=60&v=4){kind=small}
There was a problem hiding this comment.
Actionable comments posted: 6
🤖 Prompt for all review comments with AI agents
Verify each finding against the current code and only fix it if needed.
Inline comments:
In `@src/multi-factor-auth/multi-factor-auth.ts`:
- Around line 128-135: The JSDoc incorrectly documents a non-existent id
parameter for the verifyChallenge function; update the comment block for
verifyChallenge to remove the `@param` id entry and instead document the actual
parameter(s) the function accepts (e.g., `@param` options with shape/fields such
as code, challengeId or whichever keys verifyChallenge expects), and ensure the
`@returns` description still matches AuthenticationChallengeVerifyResponse; locate
the verifyChallenge function in multi-factor-auth.ts and align the JSDoc
parameter names and descriptions to the function signature.
- Around line 105-113: The JSDoc for the Challenge Factor block is out of sync
with the method signature: update the docblock for the challengeFactor method so
parameter names match the function signature (replace the incorrect `@param` id
with `@param` options and document options.id inside it), or if the method should
accept an id parameter, change the method signature to include id; ensure the
JSDoc describes the same symbols used by the challengeFactor function and
mentions options.id, expected shape, return type AuthenticationChallenge and
thrown NotFoundException.
In `@src/organizations/interfaces/organization.interface.ts`:
- Around line 13-16: Update the JSDoc for the deprecated Organization boolean
(the read-only legacy field that indicates whether profiles are allowed outside
managed domains in the Organization interface) to include a clearer deprecation
message: state that the field is read-only, removed from create/update
operations, point readers to V8_MIGRATION_GUIDE.md for migration details, and
advise which current setting or policy to use instead (refer to the organization
domain management / organization policy fields) so maintainers know what
replaces this field.
In `@src/user-management/interfaces/invitation.interface.ts`:
- Line 9: Extract the repeated union into a shared exported type alias named
InvitationState and replace the inline union on the state property with that
alias; specifically, add "export type InvitationState = 'pending' | 'accepted' |
'expired' | 'revoked';" in this file and update the state declaration (currently
"state: 'pending' | 'accepted' | 'expired' | 'revoked';") to "state:
InvitationState;" so all interfaces (e.g., the invitation interface(s) in this
file) reference the single source of truth and avoid drift.
In `@src/user-management/user-management.ts`:
- Around line 852-857: The JSDoc for resetPassword is incorrect: it describes
token creation but the function actually confirms/resets a password (POST
/user_management/password_reset/confirm). Update the comment on the
resetPassword function to state that it confirms a password reset using a
one-time token, adjust `@param` to include token and newPassword (or the actual
payload shape used by resetPassword), and change `@returns` to reflect the actual
response (e.g., success boolean or updated User object) so SDK consumers get
accurate documentation.
In `@src/widgets/widgets.ts`:
- Around line 18-19: Update the JSDoc for the widget token method so the
documented param shape and return type match the implementation: change the
`@param` description for payload to explicitly state the object shape (e.g.,
payload - { organizationId: string }) and change the `@returns` from
Promise<WidgetSessionTokenResponse> to Promise<GetTokenResponse>, ensuring the
JSDoc names/types match the actual method return type (GetTokenResponse) and the
payload property used by the function.
🪄 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: Organization UI
Review profile: ASSERTIVE
Plan: Pro Plus
Run ID: 5553e085-4696-4ff8-b6b9-a7acf17dc33d
📒 Files selected for processing (34)
src/admin-portal/admin-portal.tssrc/api-keys/api-keys.tssrc/api-keys/interfaces/api-key.interface.tssrc/audit-logs/audit-logs.tssrc/authorization/authorization.tssrc/authorization/interfaces/authorization-resource.interface.tssrc/authorization/interfaces/list-memberships-for-resource-options.interface.tssrc/authorization/interfaces/role-assignment.interface.tssrc/directory-sync/directory-sync.tssrc/directory-sync/interfaces/directory.interface.tssrc/directory-sync/interfaces/list-directories-options.interface.tssrc/events/events.tssrc/feature-flags/feature-flags.tssrc/feature-flags/interfaces/feature-flag.interface.tssrc/multi-factor-auth/multi-factor-auth.tssrc/organization-domains/interfaces/organization-domain.interface.tssrc/organization-domains/organization-domains.tssrc/organizations/interfaces/list-organizations-options.interface.tssrc/organizations/interfaces/organization.interface.tssrc/organizations/organizations.tssrc/sso/interfaces/connection.interface.tssrc/sso/interfaces/list-connections-options.interface.tssrc/sso/interfaces/profile.interface.tssrc/sso/sso.tssrc/user-management/interfaces/email-verification.interface.tssrc/user-management/interfaces/invitation.interface.tssrc/user-management/interfaces/list-invitations-options.interface.tssrc/user-management/interfaces/list-users-options.interface.tssrc/user-management/interfaces/magic-auth.interface.tssrc/user-management/interfaces/organization-membership.interface.tssrc/user-management/interfaces/password-reset.interface.tssrc/user-management/interfaces/user.interface.tssrc/user-management/user-management.tssrc/widgets/widgets.ts
Comment on lines
+13
to
+16
| /** | ||
| * Whether the Organization allows profiles outside of its managed domains. | ||
| * @deprecated | ||
| */ |
There was a problem hiding this comment.
🧹 Nitpick | 🔵 Trivial
Consider enhancing the deprecation message.
The @deprecated tag is appropriate for this read-only legacy field, which is still deserialized from API responses for backward compatibility but removed from create/update operations (as shown in V8_MIGRATION_GUIDE.md). Consider adding guidance in the JSDoc about what to use instead.
📝 Optional enhancement to deprecation message
- /**
- * Whether the Organization allows profiles outside of its managed domains.
- * `@deprecated`
- */
+ /**
+ * Whether the Organization allows profiles outside of its managed domains.
+ * `@deprecated` This field is read-only and has been removed from create/update operations. Use API settings to configure this behavior instead.
+ */
allowProfilesOutsideOrganization: boolean;📝 Committable suggestion
‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.
Suggested change
| /** | |
| * Whether the Organization allows profiles outside of its managed domains. | |
| * @deprecated | |
| */ | |
| /** | |
| * Whether the Organization allows profiles outside of its managed domains. | |
| * `@deprecated` This field is read-only and has been removed from create/update operations. Use API settings to configure this behavior instead. | |
| */ | |
| allowProfilesOutsideOrganization: boolean; |
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed.
In `@src/organizations/interfaces/organization.interface.ts` around lines 13 - 16,
Update the JSDoc for the deprecated Organization boolean (the read-only legacy
field that indicates whether profiles are allowed outside managed domains in the
Organization interface) to include a clearer deprecation message: state that the
field is read-only, removed from create/update operations, point readers to
V8_MIGRATION_GUIDE.md for migration details, and advise which current setting or
policy to use instead (refer to the organization domain management /
organization policy fields) so maintainers know what replaces this field.
| /** The email address of the recipient. */ | ||
| email: string; | ||
| /** The state of the invitation. */ | ||
| state: 'pending' | 'accepted' | 'expired' | 'revoked'; |
There was a problem hiding this comment.
🧹 Nitpick | 🔵 Trivial
Consider extracting a shared InvitationState type alias to avoid drift.
'pending' | 'accepted' | 'expired' | 'revoked' is repeated across multiple interfaces in this file. Centralizing it would reduce maintenance risk.
♻️ Proposed refactor
+export type InvitationState = 'pending' | 'accepted' | 'expired' | 'revoked';
+
export interface Invitation {
@@
- state: 'pending' | 'accepted' | 'expired' | 'revoked';
+ state: InvitationState;
@@
export interface InvitationEvent {
@@
- state: 'pending' | 'accepted' | 'expired' | 'revoked';
+ state: InvitationState;
@@
export interface InvitationResponse {
@@
- state: 'pending' | 'accepted' | 'expired' | 'revoked';
+ state: InvitationState;
@@
export interface InvitationEventResponse {
@@
- state: 'pending' | 'accepted' | 'expired' | 'revoked';
+ state: InvitationState;
}🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed.
In `@src/user-management/interfaces/invitation.interface.ts` at line 9, Extract
the repeated union into a shared exported type alias named InvitationState and
replace the inline union on the state property with that alias; specifically,
add "export type InvitationState = 'pending' | 'accepted' | 'expired' |
'revoked';" in this file and update the state declaration (currently "state:
'pending' | 'accepted' | 'expired' | 'revoked';") to "state: InvitationState;"
so all interfaces (e.g., the invitation interface(s) in this file) reference the
single source of truth and avoid drift.
Comment on lines
+18
to
+19
| * @param payload - Object containing organizationId. | ||
| * @returns {Promise<WidgetSessionTokenResponse>} |
There was a problem hiding this comment.
Fix JSDoc type/name mismatch and narrow payload description.
Line 19 documents Promise<WidgetSessionTokenResponse>, but the method returns Promise<GetTokenResponse> (Line 24). Line 18 also under-documents payload relative to the method description on Line 17.
✏️ Proposed doc fix
- * `@param` payload - Object containing organizationId.
- * `@returns` {Promise<WidgetSessionTokenResponse>}
+ * `@param` payload - Object containing the token generation fields (for example, organization, user, and scopes).
+ * `@returns` {Promise<GetTokenResponse>}📝 Committable suggestion
‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.
Suggested change
| * @param payload - Object containing organizationId. | |
| * @returns {Promise<WidgetSessionTokenResponse>} | |
| * `@param` payload - Object containing the token generation fields (for example, organization, user, and scopes). | |
| * `@returns` {Promise<GetTokenResponse>} |
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed.
In `@src/widgets/widgets.ts` around lines 18 - 19, Update the JSDoc for the widget
token method so the documented param shape and return type match the
implementation: change the `@param` description for payload to explicitly state
the object shape (e.g., payload - { organizationId: string }) and change the
`@returns` from Promise<WidgetSessionTokenResponse> to Promise<GetTokenResponse>,
ensuring the JSDoc names/types match the actual method return type
(GetTokenResponse) and the payload property used by the function.
There was a problem hiding this comment.
Actionable comments posted: 9
♻️ Duplicate comments (1)
src/widgets/widgets.ts (1)
17-19:⚠️ Potential issue | 🟡 MinorAlign
@param payloaddescription with actual token fields.
@param payloadis still under-specified (“organizationId” only) while the method/type describe org/user/scopes token inputs. Please update the param description to matchGetTokenOptionsintent.Proposed doc-only fix
- * `@param` payload - Object containing organizationId. + * `@param` payload - Object containing token generation fields (for example, organization, user, and scopes).🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed. In `@src/widgets/widgets.ts` around lines 17 - 19, Update the JSDoc for the widget token generator to accurately describe the full payload shape (replace the current "organizationId" only description). In the comment above the function/type (referencing GetTokenOptions and the method returning GetTokenResponse, e.g., generateWidgetToken or getToken), document all expected fields such as organizationId, userId (or user), scopes (array of scope strings), and any optional fields like expiresAt or metadata as defined by GetTokenOptions; keep types and optional/required status consistent with the TypeScript definitions so the doc matches the actual input contract.
🤖 Prompt for all review comments with AI agents
Verify each finding against the current code and only fix it if needed.
Inline comments:
In `@src/multi-factor-auth/multi-factor-auth.ts`:
- Around line 71-78: The JSDoc for the "Enroll Factor" method is documenting
`@returns` {Promise<AuthenticationFactorEnrolled>} but the actual TypeScript
method signature returns Promise<FactorWithSecrets>; update the JSDoc return
annotation to `@returns` {Promise<FactorWithSecrets>} (or the correct exported TS
type name) to match the method signature (reference the enroll method that
returns Promise<FactorWithSecrets>).
- Around line 179-186: The JSDoc for the "List authentication factors" method
doesn't match the TypeScript signature: update the `@returns` JSDoc on the method
in src/multi-factor-auth/multi-factor-auth.ts (the documented "List
authentication factors" method) to match the actual TypeScript return type
Promise<AutoPaginatable<UMFactor, PaginationOptions>> instead of
Promise<AutoPaginatable<AuthenticationFactor>>, ensuring both generic parameters
(UMFactor and PaginationOptions) are included and the type names exactly match
the TS signature.
- Around line 54-62: Update the JSDoc for the "Get Factor" method so its
`@returns` matches the TypeScript signature: change the documented return from
Promise<AuthenticationFactor> to Promise<Factor> (the same type used in the
method signature in multi-factor-auth.ts), ensuring the JSDoc and the
function/method (the Get Factor method) stay consistent.
- Around line 105-113: Update the JSDoc for the "Challenge Factor" method so the
`@returns` type matches the TypeScript signature: change the documented return
from Promise<AuthenticationChallenge> to Promise<Challenge> (the method that
currently returns Promise<Challenge>). Ensure the JSDoc uses the exact
TypeScript type name "Challenge" so the comment aligns with the function
signature.
- Around line 149-156: The JSDoc `@returns` type is out of sync with the
function's TypeScript signature: the method currently returns Promise<{
authenticationFactor: UMFactorWithSecrets; authenticationChallenge: Challenge;
}>, but the JSDoc claims Promise<UserAuthenticationFactorEnrollResponse>; fix by
either updating the JSDoc `@returns` to describe the actual inline shape
(Promise<{authenticationFactor: UMFactorWithSecrets; authenticationChallenge:
Challenge;}>) or define a named type alias/interface (e.g.,
UserAuthenticationFactorEnrollResponse = { authenticationFactor:
UMFactorWithSecrets; authenticationChallenge: Challenge }) and use that type
both in the function signature and the `@returns` tag for consistency; locate the
method that enrolls an authentication factor and adjust the JSDoc or the
signature accordingly.
- Around line 126-135: The JSDoc return type is out of sync with the TypeScript
signature: update the `@returns` tag in the JSDoc for the verifyChallenge method
to reference the actual TypeScript return type (Promise<VerifyResponse>) so it
matches the method signature (Promise<VerifyResponse>); ensure the JSDoc uses
the exact type name VerifyResponse used in the function signature.
In `@src/user-management/user-management.ts`:
- Around line 232-234: Update the JSDoc for getUserByExternalId so the `@example`
is not placed immediately after the `@param`; either inline the example within the
parameter description or move the example into its own `@example` block
(preferably using a fenced typescript code block) so tooling can parse it
correctly, and apply the same change to the other similar JSDoc comment in this
file to keep formatting consistent.
- Line 294: Update the minimal single-line JSDoc for the authentication methods
(e.g., authenticateWithMagicAuth) to match the style of other documented methods
like createMagicAuth: add `@param` entries for each argument (code,
pendingAuthenticationToken, session, clientId, and any other parameters used by
the related auth functions), an `@returns` describing the resolved value (or
session/token object), and `@throws` (or `@throws` {Error}) documenting possible
error conditions; ensure each auth helper mentioned in the review (the function
at authenticateWithMagicAuth and the other auth-related functions referenced in
the comment) has the expanded multi-tag JSDoc so SDK consumers can see parameter
types, return shape, and error cases.
- Line 861: The JSDoc `@throws` line that currently reads "@throws 403 response
from the API." should be changed to the standardized pattern used elsewhere in
this file (e.g. "@throws {ExceptionName} [403]"); locate the exact tag by
searching for the literal "@throws 403 response from the API." and replace it
with the same exception identifier used by other `@throws` tags in this module
(for example "@throws {ApiError} [403]" or the specific error class used in
other docs) so the format and exception name match the rest of the file.
---
Duplicate comments:
In `@src/widgets/widgets.ts`:
- Around line 17-19: Update the JSDoc for the widget token generator to
accurately describe the full payload shape (replace the current "organizationId"
only description). In the comment above the function/type (referencing
GetTokenOptions and the method returning GetTokenResponse, e.g.,
generateWidgetToken or getToken), document all expected fields such as
organizationId, userId (or user), scopes (array of scope strings), and any
optional fields like expiresAt or metadata as defined by GetTokenOptions; keep
types and optional/required status consistent with the TypeScript definitions so
the doc matches the actual input contract.
🪄 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: Organization UI
Review profile: ASSERTIVE
Plan: Pro Plus
Run ID: e5099089-945c-45cf-9baa-ee15d1e3c865
📒 Files selected for processing (3)
src/multi-factor-auth/multi-factor-auth.tssrc/user-management/user-management.tssrc/widgets/widgets.ts
| return deserializeUser(data); | ||
| } | ||
|
|
||
| /** Authenticate with magic auth. */ |
There was a problem hiding this comment.
🧹 Nitpick | 🔵 Trivial
Consider expanding JSDoc for authentication methods.
These authentication methods have minimal single-line JSDoc comments, while most other methods in this file include comprehensive documentation with @param, @returns, and @throws tags. Given that authentication is a critical flow and these methods have multiple parameters, more detailed documentation would help SDK consumers.
For example, authenticateWithMagicAuth could benefit from documenting its parameters (code, pendingAuthenticationToken, session, clientId) and potential error responses, similar to how createMagicAuth (lines 774-783) is documented.
Also applies to: 319-319, 473-473, 498-498, 523-523
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed.
In `@src/user-management/user-management.ts` at line 294, Update the minimal
single-line JSDoc for the authentication methods (e.g.,
authenticateWithMagicAuth) to match the style of other documented methods like
createMagicAuth: add `@param` entries for each argument (code,
pendingAuthenticationToken, session, clientId, and any other parameters used by
the related auth functions), an `@returns` describing the resolved value (or
session/token object), and `@throws` (or `@throws` {Error}) documenting possible
error conditions; ensure each auth helper mentioned in the review (the function
at authenticateWithMagicAuth and the other auth-related functions referenced in
the comment) has the expanded multi-tag JSDoc so SDK consumers can see parameter
types, return shape, and error cases.
| * user's email, if it hasn't been verified yet. | ||
| * @param payload - Object containing the reset token and new password. | ||
| * @returns {Promise<{ user: User; }>} | ||
| * @throws 403 response from the API. |
There was a problem hiding this comment.
🧹 Nitpick | 🔵 Trivial
Standardize the @throws tag format.
Line 861 uses a different format (@throws 403 response from the API.) compared to other error documentation in this method and throughout the file, which use the pattern @throws {ExceptionName} [status code]. This inconsistency can make the documentation harder to parse.
📝 Suggested fix for consistency
- * `@throws` 403 response from the API.
+ * `@throws` {ForbiddenException} 403📝 Committable suggestion
‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.
Suggested change
| * @throws 403 response from the API. | |
| * `@throws` {ForbiddenException} 403 |
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed.
In `@src/user-management/user-management.ts` at line 861, The JSDoc `@throws` line
that currently reads "@throws 403 response from the API." should be changed to
the standardized pattern used elsewhere in this file (e.g. "@throws
{ExceptionName} [403]"); locate the exact tag by searching for the literal
"@throws 403 response from the API." and replace it with the same exception
identifier used by other `@throws` tags in this module (for example "@throws
{ApiError} [403]" or the specific error class used in other docs) so the format
and exception name match the rest of the file.
There was a problem hiding this comment.
Actionable comments posted: 9
🤖 Prompt for all review comments with AI agents
Verify each finding against the current code and only fix it if needed.
Inline comments:
In `@src/authorization/authorization.ts`:
- Around line 981-991: Update the JSDoc for the "List organization memberships
for resource" method to make the required permissionSlug parameter explicit:
mention that the options parameter is of type ListMembershipsForResourceOptions
and that it must include a permissionSlug string (describe expected
format/meaning), and update the `@param` line to document permissionSlug as a
mandatory field; locate the comment block above the method implementation (the
block starting "List organization memberships for resource") and adjust the
description and `@param` text accordingly so callers understand permissionSlug is
required.
- Around line 1023-1048: The JSDoc for the method that lists memberships by
external ID (listMembershipsForResourceByExternalId / the method in this block)
omits that permissionSlug is required; update the comment to include a `@param`
permissionSlug entry describing that it is required (e.g., "permissionSlug - The
slug of the permission to check on the resource; required."), give an example
value, and mention it in the summary so callers know this parameter is mandatory
at runtime even though TypeScript enforces it.
In `@src/directory-sync/directory-sync.ts`:
- Around line 168-175: The JSDoc for the "Get a Directory User" method is
missing the `@param` for the required user parameter; add an `@param` user line that
describes the parameter (its expected type and meaning, e.g., user identifier or
user object) and, if applicable, include the generic type information
(TCustomAttributes) so IDEs show proper hints for
DirectoryUserWithGroups<TCustomAttributes>; update the JSDoc block that
documents the return and exceptions to also include this new `@param` entry next
to the existing `@returns` and `@throws` lines.
- Around line 186-193: The JSDoc for the "Get a Directory Group" function is
missing documentation for the parameter named group; add an `@param` line
describing the group parameter (its name, type and purpose) to the existing
JSDoc block so IDEs show proper hints — target the JSDoc immediately above the
function that uses the group parameter (the function that retrieves a Directory
Group, referenced by the existing comment "Get a Directory Group" and the
parameter name group).
In `@src/feature-flags/feature-flags.ts`:
- Around line 20-29: Update the JSDoc for the "List feature flags" method to
match the actual return type: change the `@returns` generic from
AutoPaginatable<FeatureFlag, PaginationOptions> to AutoPaginatable<FeatureFlag>
(or alternatively update the method signature to return
AutoPaginatable<FeatureFlag, PaginationOptions> if that was intended); edit the
JSDoc block above the "List feature flags" method (the comment starting "List
feature flags") so the `@returns` line references AutoPaginatable<FeatureFlag> to
match the method's actual return type.
- Around line 141-153: Update the JSDoc for listOrganizationFeatureFlags: change
the `@param` to document the single options parameter (e.g., "options - Pagination
and filter options for the organization") instead of a top-level organizationId,
and change the `@returns` annotation to Promise<AutoPaginatable<FeatureFlag>> (or
AutoPaginatable<Flag> → AutoPaginatable<FeatureFlag>) to match the function
signature; ensure the description and example mention organizationId as part of
options if needed and update any type names in the JSDoc to exactly match
FeatureFlag and listOrganizationFeatureFlags.
- Around line 113-135: Add a missing `@param` for the options argument and
normalize the non-standard 403 `@throws` text for both addFlagTarget and the
corresponding removeFlagTarget docblocks: document the options param as "@param
{AddFlagTargetOptions} options - contains slug and targetId" (or matching type
for removeFlagTarget) and replace "403 response from the API." with the
consistent form used elsewhere (e.g. "@throws {ForbiddenException} 403") so the
docblocks for addFlagTarget and removeFlagTarget match the project's JSDoc
style.
- Around line 177-189: Update the JSDoc for listUserFeatureFlags to match its
actual signature: replace the incorrect top-level `@param` userId description with
an `@param` options entry describing pagination/filter options, ensure the example
reflects passing options (if applicable), and change the `@returns` annotation
from AutoPaginatable<Flag> to AutoPaginatable<FeatureFlag>; reference the
listUserFeatureFlags function and the types FeatureFlag and
AutoPaginatable<FeatureFlag> when making the edits.
In `@src/sso/sso.ts`:
- Around line 277-284: The JSDoc for getProfile is missing documentation for its
options parameter; update the comment block above the getProfile method to
include a `@param` entry for the options object (GetProfileOptions) and describe
the accessToken field (e.g., "@param {{ accessToken: string }} options - object
containing the accessToken to exchange for a Profile"), referencing the
getProfile function and the { accessToken }: GetProfileOptions parameter so
IDE/tooling can surface correct hints.
🪄 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: Organization UI
Review profile: ASSERTIVE
Plan: Pro Plus
Run ID: 45ee649b-377e-4f49-908a-db860b3b75b5
📒 Files selected for processing (10)
src/api-keys/api-keys.tssrc/audit-logs/audit-logs.tssrc/authorization/authorization.tssrc/directory-sync/directory-sync.tssrc/feature-flags/feature-flags.tssrc/multi-factor-auth/multi-factor-auth.tssrc/organization-domains/organization-domains.tssrc/organizations/organizations.tssrc/sso/sso.tssrc/user-management/user-management.ts
Comment on lines
+981
to
+991
| /** | ||
| * List organization memberships for resource | ||
| * | ||
| * Returns all organization memberships that have a specific permission on a resource instance. This is useful for answering "Who can access this resource?". | ||
| * @param options - Pagination and filter options. | ||
| * @returns {Promise<AutoPaginatable<BaseOrganizationMembership, PaginationOptions>>} | ||
| * @throws {BadRequestException} 400 | ||
| * @throws 403 response from the API. | ||
| * @throws {NotFoundException} 404 | ||
| * @throws {UnprocessableEntityException} 422 | ||
| */ |
There was a problem hiding this comment.
🧹 Nitpick | 🔵 Trivial
Consider documenting the required permissionSlug parameter more explicitly.
The JSDoc generically describes "Pagination and filter options", but ListMembershipsForResourceOptions now requires permissionSlug as a mandatory field. More explicit documentation would improve the developer experience.
📝 Optional enhancement
/**
* List organization memberships for resource
*
* Returns all organization memberships that have a specific permission on a resource instance. This is useful for answering "Who can access this resource?".
- * `@param` options - Pagination and filter options.
+ * `@param` options - Options for listing memberships.
+ * `@param` options.resourceId - The ID of the resource.
+ * `@param` options.permissionSlug - Required. The permission slug to filter by. Only users with this permission on the resource are returned.
+ * `@param` options.assignment - Optional. Filter by assignment type ('direct' or 'indirect').
* `@returns` {Promise<AutoPaginatable<BaseOrganizationMembership, PaginationOptions>>}🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed.
In `@src/authorization/authorization.ts` around lines 981 - 991, Update the JSDoc
for the "List organization memberships for resource" method to make the required
permissionSlug parameter explicit: mention that the options parameter is of type
ListMembershipsForResourceOptions and that it must include a permissionSlug
string (describe expected format/meaning), and update the `@param` line to
document permissionSlug as a mandatory field; locate the comment block above the
method implementation (the block starting "List organization memberships for
resource") and adjust the description and `@param` text accordingly so callers
understand permissionSlug is required.
Comment on lines
+1023
to
+1048
| /** | ||
| * List memberships for a resource by external ID | ||
| * | ||
| * Returns all organization memberships that have a specific permission on a resource, using the resource's external ID. This is useful for answering "Who can access this resource?" when you only have the external ID. | ||
| * @param organizationId - The ID of the organization that owns the resource. | ||
| * | ||
| * @example | ||
| * "org_01EHZNVPK3SFK441A1RGBFSHRT" | ||
| * | ||
| * @param resourceTypeSlug - The slug of the resource type this resource belongs to. | ||
| * | ||
| * @example | ||
| * "project" | ||
| * | ||
| * @param externalId - An identifier you provide to reference the resource in your system. | ||
| * | ||
| * @example | ||
| * "proj-456" | ||
| * | ||
| * @param options - Pagination and filter options. | ||
| * @returns {Promise<AutoPaginatable<UserOrganizationMembershipBaseListData>>} | ||
| * @throws {BadRequestException} 400 | ||
| * @throws 403 response from the API. | ||
| * @throws {NotFoundException} 404 | ||
| * @throws {UnprocessableEntityException} 422 | ||
| */ |
There was a problem hiding this comment.
🧹 Nitpick | 🔵 Trivial
Consider documenting required parameters more explicitly.
Similar to listMembershipsForResource, this method also requires permissionSlug. More explicit documentation of required fields in the JSDoc would improve the developer experience, though TypeScript types will enforce this at compile time.
📝 Optional enhancement
/**
* List memberships for a resource by external ID
*
* Returns all organization memberships that have a specific permission on a resource, using the resource's external ID. This is useful for answering "Who can access this resource?" when you only have the external ID.
* `@param` organizationId - The ID of the organization that owns the resource.
*
* `@example`
* "org_01EHZNVPK3SFK441A1RGBFSHRT"
*
* `@param` resourceTypeSlug - The slug of the resource type this resource belongs to.
*
* `@example`
* "project"
*
* `@param` externalId - An identifier you provide to reference the resource in your system.
*
* `@example`
* "proj-456"
*
- * `@param` options - Pagination and filter options.
+ * `@param` options - Options for listing memberships.
+ * `@param` options.permissionSlug - Required. The permission slug to filter by.
+ * `@param` options.assignment - Optional. Filter by assignment type ('direct' or 'indirect').
* `@returns` {Promise<AutoPaginatable<UserOrganizationMembershipBaseListData>>}🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed.
In `@src/authorization/authorization.ts` around lines 1023 - 1048, The JSDoc for
the method that lists memberships by external ID
(listMembershipsForResourceByExternalId / the method in this block) omits that
permissionSlug is required; update the comment to include a `@param`
permissionSlug entry describing that it is required (e.g., "permissionSlug - The
slug of the permission to check on the resource; required."), give an example
value, and mention it in the summary so callers know this parameter is mandatory
at runtime even though TypeScript enforces it.
Comment on lines
+113
to
+135
| /** | ||
| * Add a feature flag target | ||
| * | ||
| * Enables a feature flag for a specific target in the current environment. Currently, supported targets include users and organizations. | ||
| * @returns {Promise<void>} | ||
| * @throws {BadRequestException} 400 | ||
| * @throws 403 response from the API. | ||
| * @throws {NotFoundException} 404 | ||
| */ | ||
| async addFlagTarget(options: AddFlagTargetOptions): Promise<void> { | ||
| const { slug, targetId } = options; | ||
| await this.workos.post(`/feature-flags/${slug}/targets/${targetId}`, {}); | ||
| } | ||
|
|
||
| /** | ||
| * Remove a feature flag target | ||
| * | ||
| * Removes a target from the feature flag's target list in the current environment. Currently, supported targets include users and organizations. | ||
| * @returns {Promise<void>} | ||
| * @throws {BadRequestException} 400 | ||
| * @throws 403 response from the API. | ||
| * @throws {NotFoundException} 404 | ||
| */ |
There was a problem hiding this comment.
Document options param and normalize 403 @throws entries.
Both docblocks are missing @param options, and Lines 119/133 use a non-standard @throws format (@throws 403 response from the API.). Please make these consistent with the rest of the file.
Proposed doc fix
/**
* Add a feature flag target
*
* Enables a feature flag for a specific target in the current environment. Currently, supported targets include users and organizations.
+ * `@param` options - Feature flag target options including `slug` and `targetId`.
* `@returns` {Promise<void>}
* `@throws` {BadRequestException} 400
- * `@throws` 403 response from the API.
+ * `@throws` {ForbiddenException} 403
* `@throws` {NotFoundException} 404
*/
/**
* Remove a feature flag target
*
* Removes a target from the feature flag's target list in the current environment. Currently, supported targets include users and organizations.
+ * `@param` options - Feature flag target options including `slug` and `targetId`.
* `@returns` {Promise<void>}
* `@throws` {BadRequestException} 400
- * `@throws` 403 response from the API.
+ * `@throws` {ForbiddenException} 403
* `@throws` {NotFoundException} 404
*/🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed.
In `@src/feature-flags/feature-flags.ts` around lines 113 - 135, Add a missing
`@param` for the options argument and normalize the non-standard 403 `@throws` text
for both addFlagTarget and the corresponding removeFlagTarget docblocks:
document the options param as "@param {AddFlagTargetOptions} options - contains
slug and targetId" (or matching type for removeFlagTarget) and replace "403
response from the API." with the consistent form used elsewhere (e.g. "@throws
{ForbiddenException} 403") so the docblocks for addFlagTarget and
removeFlagTarget match the project's JSDoc style.
Comment on lines
+277
to
+284
| /** | ||
| * Get a User Profile | ||
| * | ||
| * Exchange an access token for a user's [Profile](https://workos.com/docs/reference/sso/profile). Because this profile is returned in the [Get a Profile and Token endpoint](https://workos.com/docs/reference/sso/profile/get-profile-and-token) your application usually does not need to call this endpoint. It is available for any authentication flows that require an additional endpoint to retrieve a user's profile. | ||
| * @returns {Promise<Profile<CustomAttributesType>>} | ||
| * @throws {UnauthorizedException} 401 | ||
| * @throws {NotFoundException} 404 | ||
| */ |
There was a problem hiding this comment.
Missing @param documentation for method parameter.
The getProfile method accepts an options parameter (line 285-287: { accessToken }: GetProfileOptions), but the JSDoc doesn't document it. This produces incomplete IDE hints.
📝 Suggested fix
/**
* Get a User Profile
*
* Exchange an access token for a user's [Profile](https://workos.com/docs/reference/sso/profile). Because this profile is returned in the [Get a Profile and Token endpoint](https://workos.com/docs/reference/sso/profile/get-profile-and-token) your application usually does not need to call this endpoint. It is available for any authentication flows that require an additional endpoint to retrieve a user's profile.
+ * `@param` options - Object containing accessToken.
+ * `@param` options.accessToken - The access token to exchange for a profile.
* `@returns` {Promise<Profile<CustomAttributesType>>}
* `@throws` {UnauthorizedException} 401
* `@throws` {NotFoundException} 404
*/📝 Committable suggestion
‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.
Suggested change
| /** | |
| * Get a User Profile | |
| * | |
| * Exchange an access token for a user's [Profile](https://workos.com/docs/reference/sso/profile). Because this profile is returned in the [Get a Profile and Token endpoint](https://workos.com/docs/reference/sso/profile/get-profile-and-token) your application usually does not need to call this endpoint. It is available for any authentication flows that require an additional endpoint to retrieve a user's profile. | |
| * @returns {Promise<Profile<CustomAttributesType>>} | |
| * @throws {UnauthorizedException} 401 | |
| * @throws {NotFoundException} 404 | |
| */ | |
| /** | |
| * Get a User Profile | |
| * | |
| * Exchange an access token for a user's [Profile](https://workos.com/docs/reference/sso/profile). Because this profile is returned in the [Get a Profile and Token endpoint](https://workos.com/docs/reference/sso/profile/get-profile-and-token) your application usually does not need to call this endpoint. It is available for any authentication flows that require an additional endpoint to retrieve a user's profile. | |
| * `@param` options - Object containing accessToken. | |
| * `@param` options.accessToken - The access token to exchange for a profile. | |
| * `@returns` {Promise<Profile<CustomAttributesType>>} | |
| * `@throws` {UnauthorizedException} 401 | |
| * `@throws` {NotFoundException} 404 | |
| */ |
🤖 Prompt for AI Agents
Verify each finding against the current code and only fix it if needed.
In `@src/sso/sso.ts` around lines 277 - 284, The JSDoc for getProfile is missing
documentation for its options parameter; update the comment block above the
getProfile method to include a `@param` entry for the options object
(GetProfileOptions) and describe the accessToken field (e.g., "@param {{
accessToken: string }} options - object containing the accessToken to exchange
for a Profile"), referencing the getProfile function and the { accessToken }:
GetProfileOptions parameter so IDE/tooling can surface correct hints.
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
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
1 participant
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.
Description
Plucked out of #1536
Summary by CodeRabbit
New Features
Documentation
Deprecation