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

[LauraBeatris]

Description

This PR adds JSDocs coverage to the latest types updates for organization domain verification via TXT records ownership

Checklist

• pnpm test runs as expected.
• pnpm build runs as expected.
• (If applicable) JSDoc comments have been added or updated for any package exports
• (If applicable) Documentation has been updated

Type of change

• 🐛 Bug fix
• 🌟 New feature
• 🔨 Breaking change
• 📖 Refactoring / dependency upgrade / documentation
• other:

Summary by CodeRabbit

• Documentation
  • Expanded and clarified JSDoc comments for organization verified-domain types and verification resources, including affiliation/ownership verification details and legacy field mapping.
  • Improved documentation for bulk domain ownership verification, clarifying per-domain partial success behavior and how results populate data vs errors.
  • Updated the documentation link rewriting so the organization-domain-verification reference resolves to the correct typedoc page.

[changeset-bot]

🦋 Changeset detected

Latest commit: 53f9993

The changes in this PR will be included in the next version bump.

This PR includes changesets to release 0 packages

When changesets are added to this PR, you'll see the packages that this PR includes changesets for and the associated semver types

Not sure what this means? Click here to learn what changesets are.

Click here if you're a maintainer who wants to add another changeset to this PR

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
clerk-js-sandbox	Ready	Preview, Comment	Jun 22, 2026 11:22pm
swingset	Ready	Preview, Comment	Jun 22, 2026 11:22pm

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Repository YAML (base), Repository UI (inherited)

Review profile: CHILL

Plan: Pro

Run ID: ba6ea42f-0fd8-47f9-b129-3d31fd5c0b7b

📥 Commits

Reviewing files that changed from the base of the PR and between 976dc37 and 53f9993.

📒 Files selected for processing (4)

• .changeset/bumpy-ways-brake.md
• .typedoc/custom-plugin.mjs
• packages/shared/src/types/organization.ts
• packages/shared/src/types/organizationDomain.ts

💤 Files with no reviewable changes (1)

• .changeset/bumpy-ways-brake.md

✅ Files skipped from review due to trivial changes (2)

• packages/shared/src/types/organization.ts
• packages/shared/src/types/organizationDomain.ts

---

📝 Walkthrough

Walkthrough

JSDoc comments for organization domain verification and ownership types are reworded across packages/shared/src/types/organizationDomain.ts and packages/shared/src/types/organization.ts to clarify affiliation verification, ownership verification semantics, and partial-success behavior. Typedoc link mappings and a patch-level changeset entry are added.

Changes

Organization Verification Documentation

Layer / File(s)	Summary
Domain verification type JSDoc packages/shared/src/types/organizationDomain.ts	JSDoc for OrganizationDomainVerification (affiliation and deprecated verification property clarification), OrganizationDomainOwnershipVerification (strategy options and field nullability), OrganizationEnrollmentMode manual_invitation link, OrganizationDomainBulkOwnershipVerificationError (per-domain failure reporting), and OrganizationDomainsBulkOwnershipVerificationResource (partial-success semantics and data/errors split) are rewritten. No type shapes or field signatures change.
Resource method JSDoc packages/shared/src/types/organizationDomain.ts, packages/shared/src/types/organization.ts	JSDoc for OrganizationDomainResource affiliation verification methods (prepareAffiliationVerification, attemptAffiliationVerification, updateEnrollmentMode) and OrganizationResource ownership verification methods (prepareOwnershipVerification, attemptOwnershipVerification) are reworded without changing signatures or fields.
Typedoc link mapping and changeset .typedoc/custom-plugin.mjs, .changeset/bumpy-ways-brake.md	LINK_REPLACEMENTS array is extended to map organization-domain-verification to /docs/reference/types/organization-domain-resource. Patch changeset entry documents the documentation updates.

Estimated code review effort

🎯 1 (Trivial) | ⏱️ ~3 minutes

Possibly related PRs

• clerk/javascript#8748: Both PRs modify packages/shared/src/types/organizationDomain.ts to expand and reword JSDoc around organization domain verification and ownership types.
• clerk/javascript#8834: Both PRs modify JSDoc comments in packages/shared/src/types/organizationDomain.ts around ownership and verification types.
• clerk/javascript#8957: Both PRs update .typedoc/custom-plugin.mjs to extend LINK_REPLACEMENTS for documentation link rewriting rules.

Suggested reviewers

• alexisintech
• wobsoriano

Poem

🐇 A hop through the docs, a tweak here and there,
No types were harmed — just comments laid bare.
"Affiliation verified!" the rabbit did say,
With TXT records and expiresAt on display.
Clean JSDoc trails through the warren today! ✨

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title accurately describes the main change: adding JSDoc documentation coverage for domain verification ownership types and methods.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

_{✏️ Tip: You can configure your own custom pre-merge checks in the settings.}

✨ Finishing Touches

📝 Generate docstrings

• Create stacked PR
• Commit on current branch

⚔️ Resolve merge conflicts

• Resolve merge conflict in branch laura/add-jsdocs-domain-ownership

---

_{Comment @coderabbitai help to get the list of available commands.}

[pkg-pr-new]

Open in StackBlitz

@clerk/astro

npm i https://pkg.pr.new/@clerk/astro@8956

@clerk/backend

npm i https://pkg.pr.new/@clerk/backend@8956

@clerk/chrome-extension

npm i https://pkg.pr.new/@clerk/chrome-extension@8956

@clerk/clerk-js

npm i https://pkg.pr.new/@clerk/clerk-js@8956

@clerk/electron

npm i https://pkg.pr.new/@clerk/electron@8956

@clerk/electron-passkeys

npm i https://pkg.pr.new/@clerk/electron-passkeys@8956

@clerk/eslint-plugin

npm i https://pkg.pr.new/@clerk/eslint-plugin@8956

@clerk/expo

npm i https://pkg.pr.new/@clerk/expo@8956

@clerk/expo-passkeys

npm i https://pkg.pr.new/@clerk/expo-passkeys@8956

@clerk/express

npm i https://pkg.pr.new/@clerk/express@8956

@clerk/fastify

npm i https://pkg.pr.new/@clerk/fastify@8956

@clerk/hono

npm i https://pkg.pr.new/@clerk/hono@8956

@clerk/localizations

npm i https://pkg.pr.new/@clerk/localizations@8956

@clerk/nextjs

npm i https://pkg.pr.new/@clerk/nextjs@8956

@clerk/nuxt

npm i https://pkg.pr.new/@clerk/nuxt@8956

@clerk/react

npm i https://pkg.pr.new/@clerk/react@8956

@clerk/react-router

npm i https://pkg.pr.new/@clerk/react-router@8956

@clerk/shared

npm i https://pkg.pr.new/@clerk/shared@8956

@clerk/tanstack-react-start

npm i https://pkg.pr.new/@clerk/tanstack-react-start@8956

@clerk/testing

npm i https://pkg.pr.new/@clerk/testing@8956

@clerk/ui

npm i https://pkg.pr.new/@clerk/ui@8956

@clerk/upgrade

npm i https://pkg.pr.new/@clerk/upgrade@8956

@clerk/vue

npm i https://pkg.pr.new/@clerk/vue@8956

commit: cd2ae4c

[github-actions]

API Changes Report

Generated by Break Check on 2026-06-22T23:19:11.147Z

Summary

Metric	Count
Packages analyzed	19
Packages with changes	0
🔴 Breaking changes	0
🟡 Non-breaking changes	0
🟢 Additions	0

No API Changes Detected

All packages have stable APIs with no detected changes.

---

Report generated by Break Check

_{Last ran on cd2ae4c.}

[coderabbitai]

Actionable comments posted: 1

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In `@packages/shared/src/types/organizationDomain.ts`:
- Around line 67-83: The JSDoc comments for the `txtRecordName` and
`txtRecordValue` fields are making overly specific timing guarantees that the
`string | null` type signature does not enforce. Revise the JSDoc for both
fields to soften the wording and avoid implying that these values are guaranteed
to be present only immediately after calling `prepareOwnershipVerification`.
Instead, use language that acknowledges the values may or may not be populated
depending on the current state, without making specific promises about timing.
Replace phrases like "Only present immediately after" with more flexible
language that aligns with what the type signature actually guarantees.

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Repository YAML (base), Repository UI (inherited)

Review profile: CHILL

Plan: Pro

Run ID: 167d2d3c-f5b0-4c13-80ca-28885f60db34

📥 Commits

Reviewing files that changed from the base of the PR and between cb825c2 and ee8f1fc.

📒 Files selected for processing (2)

• .changeset/bumpy-ways-brake.md
• packages/shared/src/types/organizationDomain.ts

[alexisintech]

I updated the changeset to be empty as updating comments doesn't require a patch version update!

[LauraBeatris]

@alexisintech Once we release @clerk/shared as a package, wouldn't we need to build the new JSDocs so it can be referenced by the code?