chore(shared): Add JSDocs coverage for domain verification ownership

.changeset/bumpy-ways-brake.md

@@ -0,0 +1,2 @@
+---
+---

.typedoc/custom-plugin.mjs

@@ -129,6 +129,7 @@ const LINK_REPLACEMENTS = [
   ['session-task', '/docs/reference/types/session-task'],
   ['public-user-data', '/docs/reference/types/public-user-data'],
   ['session-status', '/docs/reference/types/session-status'],
+  ['organization-domain-verification', '/docs/reference/types/organization-domain-resource'],
 ];
 
 /**

packages/shared/src/types/organization.ts

@@ -189,18 +189,13 @@ export interface OrganizationResource extends ClerkResource, BillingPayerMethods
     params?: Pick<CreateOrganizationDomainParams, 'enrollmentMode'>,
   ) => Promise<OrganizationDomainResource>;
   /**
-   * Issues a fresh TXT challenge for each of the given domains in a single
-   * request. Each resolved domain's `ownershipVerification` carries the
-   * `txtRecordName` and `txtRecordValue` the org admin must publish. A single
-   * bad domain does not fail the batch; it lands in `errors`.
+   * Starts the verification process of multiple [Verified Domains](https://clerk.com/docs/guides/organizations/add-members/verified-domains) at once by issuing a fresh TXT challenge for each of the given domains in a single request. Each resolved domain's `ownershipVerification` property carries the `txtRecordName` and `txtRecordValue` the Organization [admin](https://clerk.com/docs/guides/organizations/control-access/roles-and-permissions) must publish. A single bad domain does not fail the batch; it lands in the returned [`OrganizationDomainsBulkOwnershipVerificationResource`](https://clerk.com/docs/reference/types/organization-domains-bulk-ownership-verification-resource) object's `errors` array.
    * @returns An [`OrganizationDomainsBulkOwnershipVerificationResource`](https://clerk.com/docs/reference/types/organization-domains-bulk-ownership-verification-resource) object.
    * @param domainIds - The unique identifiers of the domains to prepare.
    */
   prepareOwnershipVerification: (domainIds: string[]) => Promise<OrganizationDomainsBulkOwnershipVerificationResource>;
   /**
-   * Resolves the published TXT record for each of the given domains in a single
-   * request to complete ownership verification. A single bad domain does not
-   * fail the batch; it lands in `errors`.
+   * Completes the verification process started by [`prepareOwnershipVerification()`](https://clerk.com/docs/reference/types/organization-resource#prepare-ownership-verification), by resolving the published TXT record for each of the given domains in a single request. A single bad domain does not fail the batch; it lands in the returned [`OrganizationDomainsBulkOwnershipVerificationResource`](https://clerk.com/docs/reference/types/organization-domains-bulk-ownership-verification-resource) object's `errors` array.
    * @returns An [`OrganizationDomainsBulkOwnershipVerificationResource`](https://clerk.com/docs/reference/types/organization-domains-bulk-ownership-verification-resource) object.
    * @param domainIds - The unique identifiers of the domains to attempt.
    */

packages/shared/src/types/organizationDomain.ts

@@ -1,43 +1,51 @@
 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).
+ * The `OrganizationDomainVerification` object holds the affiliation verification details of an Organization's [Verified Domain](https://clerk.com/docs/guides/organizations/add-members/verified-domains). Affiliation proves that the current user controls an email address that belongs to the domain.
+ *
+ * This is the object referenced by both `affiliationVerification` and the deprecated `verification` property of the `OrganizationDomainResource` object.
  */
 export interface OrganizationDomainVerification {
   /**
-   * The current status of the domain verification.
+   * The current status of the affiliation verification.
    */
   status: OrganizationDomainVerificationStatus;
   /**
-   * The strategy used to verify the domain.
+   * The strategy used to verify affiliation with the domain.
    */
   strategy: OrganizationDomainVerificationStrategy;
   /**
-   * The number of verification attempts that have been made.
+   * The number of verification attempts that have been made for the current affiliation verification.
    */
   attempts: number;
   /**
-   * The date and time when the current verification attempt expires.
+   * The date and time when the current affiliation verification attempt expires.
    */
   expiresAt: Date;
 }
 
-/** @inline */
+/**
+ * The strategy used to verify affiliation with an Organization's domain.
+ *
+ * @inline
+ */
 type OrganizationDomainVerificationStrategy = 'email_code';
 
-/** @inline */
+/**
+ * The current status of an Organization domain verification.
+ *
+ * @inline
+ */
 export type OrganizationDomainVerificationStatus = 'unverified' | 'verified';
 
 /**
  * The strategy used to verify ownership of an Organization's domain.
- *
  * @inline
  */
 export type OrganizationDomainOwnershipVerificationStrategy = 'txt' | 'legacy' | 'manual_override';
 
 /**
- * Holds the ownership verification details of an Organization's domain, including
- * the TXT record an admin must publish to prove ownership.
+ * Holds the ownership verification details of an Organization's [Verified Domain](https://clerk.com/docs/guides/organizations/add-members/verified-domains). Ownership proves control of the underlying DNS domain, typically by publishing a TXT record, and is required before the domain can be used for enterprise SSO.
  */
 export interface OrganizationDomainOwnershipVerification {
   /**
@@ -46,26 +54,31 @@ export interface OrganizationDomainOwnershipVerification {
   status: OrganizationDomainVerificationStatus;
   /**
    * The strategy used to verify ownership of the domain.
+   * <ul>
+   *  <li>`txt`: Ownership is proven by publishing a DNS TXT record (see `txtRecordName` and `txtRecordValue` on `OrganizationDomainOwnershipVerification`).</li>
+   *  <li>`legacy`: Ownership was implicitly granted to domains that predate the TXT verification flow, so no per-attempt proof exists.</li>
+   *  <li>`manual_override`: Ownership was granted manually by a Clerk admin via the Backend API or Dashboard, bypassing the DNS challenge.</li>
+   * </ul>
    */
   strategy: OrganizationDomainOwnershipVerificationStrategy;
   /**
-   * The number of verification attempts that have been made, or `null` if none.
+   * The number of verification attempts that have been made for the current ownership verification, or `null` when ownership was not established through a per-attempt flow (for example, the `legacy` strategy).
    */
   attempts: number | null;
   /**
-   * The date and time when the current verification attempt expires, or `null`.
+   * The date and time when the current ownership verification attempt expires, or `null` when there is no pending attempt.
    */
   expiresAt: Date | null;
   /**
-   * The date and time when ownership of the domain was verified, or `null` if it has not been verified.
+   * The date and time when ownership of the domain was verified, or `null` if ownership has not been verified yet.
    */
   verifiedAt: Date | null;
   /**
-   * The fully qualified DNS name the org admin must publish the TXT record under. Present only immediately after preparing ownership verification.
+   * The fully qualified DNS name under which the Organization admin must publish the TXT record. Populated while the TXT challenge is available, and `null` otherwise.
    */
   txtRecordName: string | null;
   /**
-   * The exact value the org admin must publish in the TXT record. Present only immediately after preparing ownership verification.
+   * The exact value the Organization admin must publish in the TXT record. Populated while the TXT challenge is available, and `null` otherwise.
    */
   txtRecordValue: string | null;
 }
@@ -99,7 +112,7 @@ export interface OrganizationDomainResource extends ClerkResource {
    * 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>`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](https://clerk.com/docs/guides/organizations/control-access/roles-and-permissions) 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/organization-invitation) (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>
@@ -140,48 +153,37 @@ export interface OrganizationDomainResource extends ClerkResource {
    */
   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.
+   * Begins the verification process of a created Organization domain by sending a verification code to the provided email address.
+   * @returns The updated [`OrganizationDomainResource`](https://clerk.com/docs/nextjs/reference/types/organization-domain-resource) 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.
+   * Completes the verification process started by [`prepareAffiliationVerification()`](https://clerk.com/docs/nextjs/reference/types/organization-domain-resource#prepare-affiliation-verification), by validating the provided verification code.
+   * @returns The updated [`OrganizationDomainResource`](https://clerk.com/docs/nextjs/reference/types/organization-domain-resource) 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.
+   * @returns The updated [`OrganizationDomainResource`](https://clerk.com/docs/nextjs/reference/types/organization-domain-resource) object.
    */
   updateEnrollmentMode: (params: UpdateEnrollmentModeParams) => Promise<OrganizationDomainResource>;
 }
 
 /** @generateWithEmptyComment */
 export type PrepareAffiliationVerificationParams = {
-  /**
-   * The email address, belonging to the domain, that the verification code is sent to.
-   */
+  /** 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.
-   */
+  /** The verification code that was sent to the affiliation email address. */
   code: string;
 };
 
@@ -206,13 +208,11 @@ export type CreateOrganizationDomainParams = {
 };
 
 /**
- * A per-domain failure entry returned by the bulk ownership verification flows,
- * carrying the id of the domain that was skipped and the API error code that
- * caused it.
+ * The `OrganizationDomainBulkOwnershipVerificationError` object is a single [Verified Domain](https://clerk.com/docs/guides/organizations/add-members/verified-domains) that could not be processed during a bulk ownership verification flow. A failed domain is reported here instead of causing the entire batch to fail.
  */
 export interface OrganizationDomainBulkOwnershipVerificationError {
   /**
-   * The unique identifier of the Verified Domain that could not be processed.
+   * The unique identifier of the domain that could not be processed.
    */
   id: string;
   /**
@@ -222,20 +222,15 @@ export interface OrganizationDomainBulkOwnershipVerificationError {
 }
 
 /**
- * The partial-success result of a bulk ownership verification flow
- * (`prepareOwnershipVerification`/`attemptOwnershipVerification`). Each
- * requested domain lands in either `data` (with its current ownership state)
- * or `errors`.
+ * The `OrganizationDomainsBulkOwnershipVerificationResource` object is the result of a bulk ownership verification flow, such as [`prepareOwnershipVerification()`](https://clerk.com/docs/reference/types/organization-resource#prepare-ownership-verification) or [`attemptOwnershipVerification()`](https://clerk.com/docs/reference/types/organization-resource#attempt-ownership-verification), where ownership is verified for several of an Organization's [Verified Domains](https://clerk.com/docs/guides/organizations/add-members/verified-domains) at once. Because the operation can partially succeed, each requested domain is reported in either `data` or `errors`.
  */
 export interface OrganizationDomainsBulkOwnershipVerificationResource {
   /**
-   * The Verified Domains that were processed successfully. After
-   * `prepareOwnershipVerification`, each domain's `ownershipVerification`
-   * carries the `txtRecordName` and `txtRecordValue` to publish.
+   * The domains that were processed successfully. After [`prepareOwnershipVerification()`](https://clerk.com/docs/reference/types/organization-resource#prepare-ownership-verification), each domain's `ownershipVerification` carries the `txtRecordName` and `txtRecordValue` that must be published to a DNS TXT record.
    */
   data: OrganizationDomainResource[];
   /**
-   * The per-domain failures that were skipped without failing the whole batch.
+   * The domains that could not be processed. Each entry identifies the domain and the reason it was skipped, while the remaining domains in the batch are still processed.
    */
   errors: OrganizationDomainBulkOwnershipVerificationError[];
 }