From ad882271d32cb793553e794e5c60f95a79fb303c Mon Sep 17 00:00:00 2001 From: Laura Beatris Date: Mon, 22 Jun 2026 19:00:23 -0300 Subject: [PATCH 1/6] Add JSDocs for domain verification ownership methods --- .../shared/src/types/organizationDomain.ts | 58 +++++++++++-------- 1 file changed, 33 insertions(+), 25 deletions(-) diff --git a/packages/shared/src/types/organizationDomain.ts b/packages/shared/src/types/organizationDomain.ts index 2cb469c635c..c0a5330620d 100644 --- a/packages/shared/src/types/organizationDomain.ts +++ b/packages/shared/src/types/organizationDomain.ts @@ -1,43 +1,58 @@ 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). + * 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, and is established by sending a one-time code to that email address. + * + * This is the object referenced by both `affiliationVerification` and the deprecated `verification` property of `OrganizationDomainResource`. */ 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. The only supported strategy is `'email_code'`, where a one-time code is sent to an email address on 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 { /** @@ -49,23 +64,23 @@ export interface OrganizationDomainOwnershipVerification { */ 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. Only present immediately after calling `prepareOwnershipVerification`, 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. Only present immediately after calling `prepareOwnershipVerification`, and `null` otherwise. */ txtRecordValue: string | null; } @@ -206,9 +221,7 @@ 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. + * Describes a single domain 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 { /** @@ -222,20 +235,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 result of a bulk ownership verification flow, such as `prepareOwnershipVerification` or `attemptOwnershipVerification`, where ownership is verified for several of an Organization's 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 Verified Domains that were processed successfully. After `prepareOwnershipVerification`, 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[]; } From 976dc37e832883255ba9d1a25aa5cd4ed79622c5 Mon Sep 17 00:00:00 2001 From: Laura Beatris Date: Mon, 22 Jun 2026 19:03:21 -0300 Subject: [PATCH 2/6] Add changeset --- .changeset/bumpy-ways-brake.md | 5 +++++ packages/shared/src/types/organizationDomain.ts | 4 ++-- 2 files changed, 7 insertions(+), 2 deletions(-) create mode 100644 .changeset/bumpy-ways-brake.md diff --git a/.changeset/bumpy-ways-brake.md b/.changeset/bumpy-ways-brake.md new file mode 100644 index 00000000000..6da71530958 --- /dev/null +++ b/.changeset/bumpy-ways-brake.md @@ -0,0 +1,5 @@ +--- +'@clerk/shared': patch +--- + +Add JSDocs coverage for organization domain verification ownership types diff --git a/packages/shared/src/types/organizationDomain.ts b/packages/shared/src/types/organizationDomain.ts index c0a5330620d..2460c7690b9 100644 --- a/packages/shared/src/types/organizationDomain.ts +++ b/packages/shared/src/types/organizationDomain.ts @@ -76,11 +76,11 @@ export interface OrganizationDomainOwnershipVerification { */ verifiedAt: Date | null; /** - * The fully qualified DNS name under which the Organization admin must publish the TXT record. Only present immediately after calling `prepareOwnershipVerification`, and `null` otherwise. + * 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 Organization admin must publish in the TXT record. Only present immediately after calling `prepareOwnershipVerification`, and `null` otherwise. + * 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; } From d8edbde5c93db67735d4e98560f06a7be9a86a52 Mon Sep 17 00:00:00 2001 From: Alexis Aguilar <98043211+alexisintech@users.noreply.github.com> Date: Mon, 22 Jun 2026 16:14:40 -0700 Subject: [PATCH 3/6] docs review --- packages/shared/src/types/organization.ts | 9 +--- .../shared/src/types/organizationDomain.ts | 51 +++++++------------ 2 files changed, 21 insertions(+), 39 deletions(-) diff --git a/packages/shared/src/types/organization.ts b/packages/shared/src/types/organization.ts index 1d714628ce0..07246cb78e3 100644 --- a/packages/shared/src/types/organization.ts +++ b/packages/shared/src/types/organization.ts @@ -189,18 +189,13 @@ export interface OrganizationResource extends ClerkResource, BillingPayerMethods params?: Pick, ) => Promise; /** - * 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; /** - * 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. */ diff --git a/packages/shared/src/types/organizationDomain.ts b/packages/shared/src/types/organizationDomain.ts index 2460c7690b9..a9a0aae8a47 100644 --- a/packages/shared/src/types/organizationDomain.ts +++ b/packages/shared/src/types/organizationDomain.ts @@ -1,9 +1,9 @@ import type { ClerkResource } from './resource'; /** - * 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, and is established by sending a one-time code to that email address. + * 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 `OrganizationDomainResource`. + * This is the object referenced by both `affiliationVerification` and the deprecated `verification` property of the `OrganizationDomainResource` object. */ export interface OrganizationDomainVerification { /** @@ -11,7 +11,7 @@ export interface OrganizationDomainVerification { */ status: OrganizationDomainVerificationStatus; /** - * The strategy used to verify affiliation with the domain. The only supported strategy is `'email_code'`, where a one-time code is sent to an email address on the domain. + * The strategy used to verify affiliation with the domain. */ strategy: OrganizationDomainVerificationStrategy; /** @@ -40,13 +40,6 @@ export type OrganizationDomainVerificationStatus = 'unverified' | 'verified'; /** * The strategy used to verify ownership of an Organization's domain. - * - *
    - *
  • `txt`: Ownership is proven by publishing a DNS TXT record (see `txtRecordName` and `txtRecordValue` on `OrganizationDomainOwnershipVerification`).
    • - *
  • `legacy`: Ownership was implicitly granted to domains that predate the TXT verification flow, so no per-attempt proof exists.
    • - *
  • `manual_override`: Ownership was granted manually by a Clerk admin via the Backend API or Dashboard, bypassing the DNS challenge.
    • - *
- * * @inline */ export type OrganizationDomainOwnershipVerificationStrategy = 'txt' | 'legacy' | 'manual_override'; @@ -61,6 +54,11 @@ export interface OrganizationDomainOwnershipVerification { status: OrganizationDomainVerificationStatus; /** * The strategy used to verify ownership of the domain. + *
    + *
  • `txt`: Ownership is proven by publishing a DNS TXT record (see `txtRecordName` and `txtRecordValue` on `OrganizationDomainOwnershipVerification`).
    • + *
  • `legacy`: Ownership was implicitly granted to domains that predate the TXT verification flow, so no per-attempt proof exists.
    • + *
  • `manual_override`: Ownership was granted manually by a Clerk admin via the Backend API or Dashboard, bypassing the DNS challenge.
    • + *
*/ strategy: OrganizationDomainOwnershipVerificationStrategy; /** @@ -155,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; /** - * 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; /** * Deletes the Verified Domain. - * * @returns A promise that resolves once the Verified Domain has been deleted. */ delete: () => Promise; /** * 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; } /** @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; }; @@ -221,11 +208,11 @@ export type CreateOrganizationDomainParams = { }; /** - * Describes a single domain 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. + * 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; /** @@ -235,11 +222,11 @@ export interface OrganizationDomainBulkOwnershipVerificationError { } /** - * The result of a bulk ownership verification flow, such as `prepareOwnershipVerification` or `attemptOwnershipVerification`, where ownership is verified for several of an Organization's domains at once. Because the operation can partially succeed, each requested domain is reported in either `data` 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` that must be published to a DNS TXT record. + * 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[]; /** From ac972d5d1a0b3446f81aabfecb7632e522d05f28 Mon Sep 17 00:00:00 2001 From: Alexis Aguilar <98043211+alexisintech@users.noreply.github.com> Date: Mon, 22 Jun 2026 16:15:13 -0700 Subject: [PATCH 4/6] link update --- packages/shared/src/types/organizationDomain.ts | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/packages/shared/src/types/organizationDomain.ts b/packages/shared/src/types/organizationDomain.ts index a9a0aae8a47..45b4d6d8d16 100644 --- a/packages/shared/src/types/organizationDomain.ts +++ b/packages/shared/src/types/organizationDomain.ts @@ -112,7 +112,7 @@ export interface OrganizationDomainResource extends ClerkResource { * The enrollment mode that determines how matching users are added to the Organization. * *
    - *
  • `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.
    • + *
  • `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.
    • *
  • `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.
    • *
  • `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.
    • *
From cd2ae4cbdcbf039e99b91c8662fb973e849d0260 Mon Sep 17 00:00:00 2001 From: Alexis Aguilar <98043211+alexisintech@users.noreply.github.com> Date: Mon, 22 Jun 2026 16:15:35 -0700 Subject: [PATCH 5/6] update changeset --- .changeset/bumpy-ways-brake.md | 3 --- 1 file changed, 3 deletions(-) diff --git a/.changeset/bumpy-ways-brake.md b/.changeset/bumpy-ways-brake.md index 6da71530958..a845151cc84 100644 --- a/.changeset/bumpy-ways-brake.md +++ b/.changeset/bumpy-ways-brake.md @@ -1,5 +1,2 @@ --- -'@clerk/shared': patch --- - -Add JSDocs coverage for organization domain verification ownership types From 53f9993ed7d148c42014b8cab9ea7aa584ee3054 Mon Sep 17 00:00:00 2001 From: Alexis Aguilar <98043211+alexisintech@users.noreply.github.com> Date: Mon, 22 Jun 2026 16:19:56 -0700 Subject: [PATCH 6/6] fix link --- .typedoc/custom-plugin.mjs | 1 + 1 file changed, 1 insertion(+) diff --git a/.typedoc/custom-plugin.mjs b/.typedoc/custom-plugin.mjs index b3634d253a2..c0ee59ef438 100644 --- a/.typedoc/custom-plugin.mjs +++ b/.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'], ]; /**