chore(shared): Add JSDocs to all organization resources (#8748)

Co-authored-by: Alexis Aguilar <98043211+alexisintech@users.noreply.github.com>

Author: LauraBeatris

.changeset/good-bottles-deny.md

@@ -0,0 +1,5 @@
+---
+'@clerk/shared': patch
+---
+
+Add JSDoc comments to the Organization-related resource types (`OrganizationDomain`, `OrganizationCreationDefaults`, `OrganizationInvitation`, `OrganizationMembership`, `OrganizationMembershipRequest`, `OrganizationSettings`, and `OrganizationSuggestion`) to improve the generated Typedoc API docs

packages/shared/src/types/organizationCreationDefaults.ts

@@ -1,8 +1,18 @@
 import type { ClerkResourceJSON } from './json';
 import type { ClerkResource } from './resource';
 
+/**
+ * The type of advisory returned when computing the defaults for creating an Organization.
+ *
+ * @inline
+ */
 export type OrganizationCreationAdvisoryType = 'organization_already_exists';
 
+/**
+ * The severity of an advisory returned when computing the defaults for creating an Organization.
+ *
+ * @inline
+ */
 export type OrganizationCreationAdvisorySeverity = 'warning';
 
 export interface OrganizationCreationDefaultsJSON extends ClerkResourceJSON {
@@ -20,18 +30,47 @@ export interface OrganizationCreationDefaultsJSON extends ClerkResourceJSON {
 }
 
 /**
+ * The `OrganizationCreationDefaults` object holds the suggested default values to use when creating an Organization, along with an advisory surfacing a potential issue with the suggested defaults.
+ *
  * @interface
  */
 export interface OrganizationCreationDefaultsResource extends ClerkResource {
+  /**
+   * An advisory surfacing a potential issue with the suggested defaults, or `null` if there is none.
+   */
   advisory: {
+    /**
+     * The code identifying the advisory.
+     */
     code: OrganizationCreationAdvisoryType;
+    /**
+     * The severity of the advisory.
+     */
     severity: OrganizationCreationAdvisorySeverity;
+    /**
+     * Additional metadata providing context about the advisory.
+     */
     meta: Record<string, string>;
   } | null;
+  /**
+   * The suggested default values to pre-fill the Organization creation form with.
+   */
   form: {
+    /**
+     * The suggested Organization name.
+     */
     name: string;
+    /**
+     * The suggested URL-friendly identifier for the Organization.
+     */
     slug: string;
+    /**
+     * The suggested logo URL, or `null` if there is none.
+     */
     logo: string | null;
+    /**
+     * The blur hash of the suggested logo, used to render a placeholder while the image loads, or `null` if there is none.
+     */
     blurHash: string | null;
   };
 }

packages/shared/src/types/organizationDomain.ts

@@ -1,49 +1,138 @@
 import type { ClerkResource } from './resource';
 
+/**
+ * Holds the verification details of an Organization's [Verified Domain](https://clerk.com/docs/guides/organizations/add-members/verified-domains).
+ */
 export interface OrganizationDomainVerification {
+  /**
+   * The current status of the domain verification.
+   */
   status: OrganizationDomainVerificationStatus;
-  strategy: 'email_code'; // only available value for now
+  /**
+   * The strategy used to verify the domain.
+   */
+  strategy: OrganizationDomainVerificationStrategy;
+  /**
+   * The number of verification attempts that have been made.
+   */
   attempts: number;
+  /**
+   * The date and time when the current verification attempt expires.
+   */
   expiresAt: Date;
 }
 
+/** @inline */
+type OrganizationDomainVerificationStrategy = 'email_code';
+
 /** @inline */
 export type OrganizationDomainVerificationStatus = 'unverified' | 'verified';
 
 /** @inline */
 export type OrganizationEnrollmentMode = 'manual_invitation' | 'automatic_invitation' | 'automatic_suggestion';
 
 /**
- * The `OrganizationDomain` object is the model around an organization domain.
+ * The `OrganizationDomain` object is the model around an Organization's [Verified Domain](https://clerk.com/docs/guides/organizations/add-members/verified-domains).
  *
  * @interface
  */
 export interface OrganizationDomainResource extends ClerkResource {
+  /**
+   * The unique identifier for the Verified Domain.
+   */
   id: string;
+  /**
+   * The domain name, for example `clerk.com`.
+   */
   name: string;
+  /**
+   * The ID of the Organization that the Verified Domain belongs to.
+   */
   organizationId: string;
+  /**
+   * The enrollment mode that determines how matching users are added to the Organization.
+   *
+   * <ul>
+   *  <li>`manual_invitation`: No automatic enrollment. Users with a matching email domain are not given any [invitation](https://clerk.com/docs/guides/organizations/add-members/verified-domains#automatic-invitations) or [suggestion](https://clerk.com/docs/guides/organizations/add-members/verified-domains#automatic-suggestions); an admin must invite them manually.</li>
+   *  <li>`automatic_invitation`: Users with a matching email domain automatically receive a pending [invitation](https://clerk.com/docs/reference/types/organizationinvitation) (assigned the Organization's default role) which they can accept to join.</li>
+   *  <li>`automatic_suggestion`: Users with a matching email domain automatically receive a [suggestion](https://clerk.com/docs/guides/organizations/add-members/verified-domains#automatic-suggestions) to join, which they can request.</li>
+   * </ul>
+   */
   enrollmentMode: OrganizationEnrollmentMode;
+  /**
+   * The verification details for the domain, or `null` if the domain has not been verified.
+   */
   verification: OrganizationDomainVerification | null;
+  /**
+   * The date and time when the domain was created.
+   */
   createdAt: Date;
+  /**
+   * The date and time when the domain was last updated.
+   */
   updatedAt: Date;
+  /**
+   * The email address used to verify the affiliation with the domain, or `null` if none has been provided.
+   */
   affiliationEmailAddress: string | null;
+  /**
+   * The total number of pending [invitations](https://clerk.com/docs/reference/types/organizationinvitation) associated with this domain.
+   */
   totalPendingInvitations: number;
+  /**
+   * The total number of pending [suggestions](https://clerk.com/docs/reference/types/organizationsuggestion) associated with this domain.
+   */
   totalPendingSuggestions: number;
+  /**
+   * Begins the affiliation verification flow by sending a verification code to the provided email address.
+   *
+   * @param params - The parameters containing the affiliation email address to verify.
+   * @returns A promise that resolves to the updated `OrganizationDomain` object.
+   */
   prepareAffiliationVerification: (params: PrepareAffiliationVerificationParams) => Promise<OrganizationDomainResource>;
 
+  /**
+   * Completes the affiliation verification flow by validating the code sent to the affiliation email address.
+   *
+   * @param params - The parameters containing the verification code.
+   * @returns A promise that resolves to the updated `OrganizationDomain` object.
+   */
   attemptAffiliationVerification: (params: AttemptAffiliationVerificationParams) => Promise<OrganizationDomainResource>;
+  /**
+   * Deletes the Verified Domain.
+   *
+   * @returns A promise that resolves once the Verified Domain has been deleted.
+   */
   delete: () => Promise<void>;
+  /**
+   * Updates the enrollment mode of the Verified Domain.
+   *
+   * @param params - The parameters containing the new enrollment mode and whether to delete pending invitations or suggestions.
+   * @returns A promise that resolves to the updated `OrganizationDomain` object.
+   */
   updateEnrollmentMode: (params: UpdateEnrollmentModeParams) => Promise<OrganizationDomainResource>;
 }
 
+/** @generateWithEmptyComment */
 export type PrepareAffiliationVerificationParams = {
+  /**
+   * The email address, belonging to the domain, that the verification code is sent to.
+   */
   affiliationEmailAddress: string;
 };
 
+/** @generateWithEmptyComment */
 export type AttemptAffiliationVerificationParams = {
+  /**
+   * The verification code that was sent to the affiliation email address.
+   */
   code: string;
 };
 
+/** @generateWithEmptyComment */
 export type UpdateEnrollmentModeParams = Pick<OrganizationDomainResource, 'enrollmentMode'> & {
+  /**
+   * Whether to delete any pending [invitations](https://clerk.com/docs/reference/types/organizationinvitation) or [suggestions](https://clerk.com/docs/reference/types/organizationsuggestion) that were created by the previous enrollment mode.
+   */
   deletePending?: boolean;
 };

packages/shared/src/types/organizationInvitation.ts

@@ -3,34 +3,67 @@ import type { ClerkResource } from './resource';
 
 declare global {
   /**
-   * If you want to provide custom types for the organizationInvitation.publicMetadata
-   * object, simply redeclare this rule in the global namespace.
-   * Every OrganizationInvitation object will use the provided type.
+   * If you want to provide custom types for the `organizationInvitation.publicMetadata` object, simply redeclare this rule in the global namespace. Every `OrganizationInvitation` will use the provided type.
    */
   interface OrganizationInvitationPublicMetadata {
     [k: string]: unknown;
   }
 
+  /**
+   * If you want to provide custom types for the `organizationInvitation.privateMetadata` object, simply redeclare this rule in the global namespace. Every `OrganizationInvitation` will use the provided type.
+   */
   interface OrganizationInvitationPrivateMetadata {
     [k: string]: unknown;
   }
 }
 
 /**
- * The `OrganizationInvitation` object is the model around an Organization invitation.
+ * The `OrganizationInvitation` object is the model around [an invitation to join an Organization](https://clerk.com/docs/guides/organizations/add-members/invitations).
  *
  * @interface
  */
 export interface OrganizationInvitationResource extends ClerkResource {
+  /**
+   * The unique identifier for the invitation.
+   */
   id: string;
+  /**
+   * The email address the invitation was sent to.
+   */
   emailAddress: string;
+  /**
+   * The ID of the Organization that the invitation is for.
+   */
   organizationId: string;
+  /**
+   * Metadata that can be read from both the [Frontend API](https://clerk.com/docs/reference/frontend-api){{ target: '_blank' }} and [Backend API](https://clerk.com/docs/reference/backend-api){{ target: '_blank' }}, but can be set only from the Backend API. Once the user accepts the invitation and signs up, these metadata will end up in the user's public metadata.
+   */
   publicMetadata: OrganizationInvitationPublicMetadata;
+  /**
+   * The [Role](https://clerk.com/docs/guides/organizations/control-access/roles-and-permissions) that the invited user will be assigned once they accept the invitation.
+   */
   role: OrganizationCustomRoleKey;
+  /**
+   * The name of the [Role](https://clerk.com/docs/guides/organizations/control-access/roles-and-permissions) that the invited user will be assigned.
+   */
   roleName: string;
+  /**
+   * The current status of the invitation.
+   */
   status: OrganizationInvitationStatus;
+  /**
+   * The date when the invitation was created.
+   */
   createdAt: Date;
+  /**
+   * The date when the invitation was last updated.
+   */
   updatedAt: Date;
+  /**
+   * Revokes the invitation so it can no longer be accepted.
+   *
+   * @returns A promise that resolves to the revoked [`OrganizationInvitation`](https://clerk.com/docs/reference/types/organization-invitation) object.
+   */
   revoke: () => Promise<OrganizationInvitationResource>;
 }