fix(backend,shared): fix generated TypeDoc references

[SarahSoutoul]

Description

Fixes several regressions and missing links in generated TypeDoc documentation.

This PR:

• Maps the following generated types to new public documentation routes:
  • EnterpriseConnectionCustomAttribute
  • EnterpriseConnectionSamlConnectionLoginHint
  • BillingTotals
  • BillingSubscriptionItemStatus
• Exports BillingSubscriptionItemStatus from @clerk/backend and documents all supported status values.
• Restores the direct Frontend API endpoint link in the touchSession documentation.
• Clarifies the createUser() documentation for verified and reserved email addresses and phone numbers.
• Removes ambiguous or incorrect wording such as “Runs parallel to” and “When omitted or empty.”

There are no runtime behavior changes.

Companion Clerk docs PR: https://github.com/clerk/clerk/pull/3100.

Testing

• pnpm --filter @clerk/backend build
• Focused TypeDoc generation for the backend, shared, and React packages
• Verified that generated references use the new public documentation routes
• Verified that BillingSubscriptionItemStatus documents all eight supported values
• Prettier and git diff --check

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:

[vercel]

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

Project	Deployment	Actions	Updated (UTC)
clerk-js-sandbox	Ready	Preview	Aug 5, 2026 3:39pm
swingset	Ready	Preview	Aug 5, 2026 3:39pm

[changeset-bot]

🦋 Changeset detected

Latest commit: fbde2c0

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

This PR includes changesets to release 23 packages

Name	Type
@clerk/backend	Patch
@clerk/shared	Patch
@clerk/astro	Patch
@clerk/express	Patch
@clerk/fastify	Patch
@clerk/hono	Patch
@clerk/nextjs	Patch
@clerk/nuxt	Patch
@clerk/react-router	Patch
@clerk/tanstack-react-start	Patch
@clerk/testing	Patch
@clerk/chrome-extension	Patch
@clerk/clerk-js	Patch
@clerk/electron	Patch
@clerk/expo-passkeys	Patch
@clerk/expo	Patch
@clerk/headless	Patch
@clerk/localizations	Patch
@clerk/msw	Patch
@clerk/react	Patch
@clerk/ui	Patch
@clerk/vue	Patch
@clerk/swingset	Patch

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

[pkg-pr-new]

Open in StackBlitz

@clerk/astro

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

@clerk/backend

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

@clerk/chrome-extension

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

@clerk/clerk-js

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

@clerk/electron

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

@clerk/electron-passkeys

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

@clerk/eslint-plugin

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

@clerk/expo

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

@clerk/expo-google-signin

npm i https://pkg.pr.new/@clerk/expo-google-signin@9340

@clerk/expo-passkeys

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

@clerk/express

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

@clerk/fastify

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

@clerk/hono

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

@clerk/localizations

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

@clerk/nextjs

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

@clerk/nuxt

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

@clerk/react

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

@clerk/react-router

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

@clerk/shared

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

@clerk/tanstack-react-start

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

@clerk/testing

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

@clerk/ui

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

@clerk/upgrade

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

@clerk/vue

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

commit: fbde2c0

[github-actions]

API Changes Report

Generated by Break Check on 2026-08-05T15:40:48.103Z

Summary

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

🤖 This report was reviewed by claude-sonnet-4-6.

---

@clerk/backend

Current version: 3.15.1
Recommended bump: MINOR → 3.16.0

🟡 Non-breaking Changes (1)

Modified: BillingSubscriptionItemJSON.status

  status: BillingSubscriptionItemStatus;

Static analyzer: Breaking change in property BillingSubscriptionItemJSON.status: Type changed: import("@clerk/backend").~BillingSubscriptionItemStatus → import("@clerk/backend").BillingSubscriptionItemStatus

🤖 AI review (reclassified as non-breaking) (95%): The before and after types resolve to the same BillingSubscriptionItemStatus union from @clerk/backend; the ~ prefix is an internal alias notation, not a different type, so the structural shape is identical and no consumer code is affected.

🟢 Additions (1)

Added: BillingSubscriptionItemStatus

+ export type BillingSubscriptionItemStatus = 
+ /** The Subscription Item is in the abandoned state. */
+ 'abandoned'
+ /** The Subscription Item is active. */
+  | 'active'
+ /** The Subscription Item is canceled. */
+  | 'canceled'
+ /** The Subscription Item has ended. */
+  | 'ended'
+ /** The Subscription Item has expired. */
+  | 'expired'
+ /** The Subscription Item is incomplete. */
+  | 'incomplete'
+ /** The Subscription Item has a past-due payment. */
+  | 'past_due'
+ /** The Subscription Item is upcoming. */
+  | 'upcoming';

Added type alias BillingSubscriptionItemStatus

---

Report generated by Break Check

_{Last ran on fbde2c0.}

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

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

Review profile: CHILL

Plan: Pro Plus

Run ID: c312c896-f87c-42c1-8a3b-e3079df6b4eb

📥 Commits

Reviewing files that changed from the base of the PR and between 4717aab and fbde2c0.

📒 Files selected for processing (6)

• .changeset/clean-typedoc-links.md
• .typedoc/custom-plugin.mjs
• packages/backend/src/api/endpoints/UserApi.ts
• packages/backend/src/api/resources/JSON.ts
• packages/backend/src/index.ts
• packages/shared/src/types/clerk.ts

🔗 Linked repositories identified

CodeRabbit considers these linked repositories for cross-repo context during reviews:

• clerk/clerk_go (manual)
• clerk/dashboard (manual)
• clerk/accounts (manual)
• clerk/backoffice (manual)
• clerk/clerk (manual) → reviewed against open PR #3100 ss/add-typedoc-public-type-pages instead of the default branch
• clerk/clerk-docs (manual)
• clerk/cloudflare-workers (manual)

🚧 Files skipped from review as they are similar to previous changes (6)

• packages/backend/src/api/endpoints/UserApi.ts
• .typedoc/custom-plugin.mjs
• .changeset/clean-typedoc-links.md
• packages/backend/src/api/resources/JSON.ts
• packages/backend/src/index.ts
• packages/shared/src/types/clerk.ts

---

📝 Walkthrough

Walkthrough

The pull request updates TypeDoc link mappings and the touchSession reference link. It clarifies CreateUserParams and createUser documentation. It exports BillingSubscriptionItemStatus from the backend, documents its lifecycle states, and adds upcoming. A changeset records patch releases for @clerk/backend and @clerk/shared.

Estimated code review effort: 2 (Simple) | ~15 minutes

Possibly related PRs

• clerk/javascript#9305: Updates the same CreateUserParams and createUser documentation.

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title clearly summarizes the primary change: fixing generated TypeDoc references across the backend and shared packages.
Description check	✅ Passed	The description directly explains the TypeDoc fixes, exported type, documentation updates, testing, and absence of runtime changes.
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.

✨ Finishing Touches 💡 1

🛠️ Fix failing CI checks 💡

• Create stacked PR
• Commit on current branch

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

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

[manovotny]

@SarahSoutoul confirmed the four link targets here line up with the pages #3100 adds — each has a matching route, manifest entry, and <Typedoc src>:

• enterprise-connection-custom-attribute → backend/types/backend-enterprise-connection-custom-attribute
• enterprise-connection-saml-connection-login-hint → backend/types/backend-enterprise-connection-saml-connection-login-hint
• billing-subscription-item-status → backend/types/billing-subscription-item-status
• billing-totals → types/billing-totals

So once this and #3100 both land and the sync reruns, the generated links in clerk/clerk#3097 resolve. The billing-subscription-item-status slug sitting under backend/types/ without the backend- prefix its enterprise siblings carry is the one that looked off at a glance, but #3100 places the page there too, so they agree.