docs(shared): Improve protect check parameter types and Typedoc output by SarahSoutoul · Pull Request #9116 · clerk/javascript

SarahSoutoul · 2026-07-09T09:47:24Z

Description

Improves the Typedoc/JSDoc output for the Protect check APIs on the future sign-in and sign-up flows after checking the latest Typedoc generated PR.

submitProtectCheck() previously accepted an inline object type ({ proofToken: string }), which Typedoc renders as an anonymous, undocumented parameter shape. This PR extracts that shape into named interfaces so the generated reference docs display a proper, documented parameter type:

Adds SignInFutureSubmitProtectCheckParams (signInFuture.ts)
Adds SignUpFutureSubmitProtectCheckParams (signUpFuture.ts)
Points submitProtectCheck() on both SignInFutureResource and SignUpFutureResource at the new interfaces

Also polishes the surrounding JSDoc:

Rewrites the ProtectCheckResource doc comments (signUpCommon.ts) to explain the end-to-end flow - load the SDK from sdkUrl, initialize with token and uiHints, then submit the SDK's proof token via submitProtectCheck() — and clarifies each field.
Collapses the multi-line submitProtectCheck description onto a single line so it renders correctly.

These are documentation/type-shape changes only; the runtime parameter shape ({ proofToken: string }) is unchanged, so this is fully backwards-compatible.

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

Summary by CodeRabbit

New Features
- Added named parameter types for submit-and-verify protection checks in upcoming sign-in and sign-up flows.
Documentation
- Clarified the protection-check lifecycle and refined field descriptions (including expiration timing and UI hints pass-through).
Chores
- Published a patch release for the shared package.

vercel · 2026-07-09T09:47:31Z

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

Project	Deployment	Actions	Updated (UTC)
clerk-js-sandbox	Ready	Preview, Comment	Jul 9, 2026 10:39am
swingset	Ready	Preview, Comment	Jul 9, 2026 10:39am

changeset-bot · 2026-07-09T09:47:31Z

🦋 Changeset detected

Latest commit: 9c42ca5

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

This PR includes changesets to release 23 packages

Name	Type
@clerk/shared	Patch
@clerk/astro	Patch
@clerk/backend	Patch
@clerk/chrome-extension	Patch
@clerk/clerk-js	Patch
@clerk/electron	Patch
@clerk/expo-passkeys	Patch
@clerk/expo	Patch
@clerk/express	Patch
@clerk/fastify	Patch
@clerk/headless	Patch
@clerk/hono	Patch
@clerk/localizations	Patch
@clerk/msw	Patch
@clerk/nextjs	Patch
@clerk/nuxt	Patch
@clerk/react-router	Patch
@clerk/react	Patch
@clerk/tanstack-react-start	Patch
@clerk/testing	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

coderabbitai · 2026-07-09T09:49:06Z

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 Plus

Run ID: fa190e53-0a8e-4d44-9b92-cd0d9e8a5935

📥 Commits

Reviewing files that changed from the base of the PR and between f02497b and 9c42ca5.

📒 Files selected for processing (1)

packages/shared/src/types/signUpCommon.ts

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

packages/shared/src/types/signUpCommon.ts

📝 Walkthrough

Walkthrough

Adds named proofToken parameter interfaces for sign-in and sign-up protect check submission methods, updates those method signatures to use the new types, rewords ProtectCheckResource JSDoc, and adds a patch changeset entry.

Changes

Protect Check Param Types

Layer / File(s)	Summary
Sign-in submitProtectCheck param type `packages/shared/src/types/signInFuture.ts`	Adds `SignInFutureSubmitProtectCheckParams` with required `proofToken: string`, and updates `submitProtectCheck` to use it.
Sign-up submitProtectCheck param type and docs `packages/shared/src/types/signUpFuture.ts`, `packages/shared/src/types/signUpCommon.ts`	Adds `SignUpFutureSubmitProtectCheckParams`, updates `submitProtectCheck`, and rewords `ProtectCheckResource` JSDoc for status, token, sdkUrl, expiresAt, and uiHints.
Changeset entry `.changeset/smooth-buckets-collect.md`	Adds a patch changeset for `@clerk/shared` describing the new named protect check parameter types.

Estimated code review effort: 1 (Trivial) | ~5 minutes

Possibly related PRs

clerk/javascript#8329: Adds related Protect SDK support that introduced the same submitProtectCheck flow for future sign-in/sign-up resources.
clerk/javascript#9101: Updates ProtectCheckResource JSDoc in packages/shared/src/types/signUpCommon.ts.

Suggested reviewers: alexisintech, manovotny

Poem

A rabbit hops through types anew,
Naming params, tidy and true,
proofToken tucked in interfaces neat,
No more inline objects to repeat,
A changeset hop, a docstring gleam —
Protect checks flow like a dream. 🐇✨

🚥 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 summarizes the main changes: named protect check parameter types plus documentation/Typedoc updates.
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

📝 Generate docstrings

Create stacked PR
Commit on current branch

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

pkg-pr-new · 2026-07-09T09:52:31Z

Open in StackBlitz

@clerk/astro

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

@clerk/backend

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

@clerk/chrome-extension

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

@clerk/clerk-js

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

@clerk/electron

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

@clerk/electron-passkeys

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

@clerk/eslint-plugin

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

@clerk/expo

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

@clerk/expo-passkeys

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

@clerk/express

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

@clerk/fastify

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

@clerk/hono

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

@clerk/localizations

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

@clerk/nextjs

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

@clerk/nuxt

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

@clerk/react

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

@clerk/react-router

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

@clerk/shared

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

@clerk/tanstack-react-start

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

@clerk/testing

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

@clerk/ui

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

@clerk/upgrade

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

@clerk/vue

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

commit: 9c42ca5

github-actions · 2026-07-09T09:52:33Z

API Changes Report

Generated by Break Check on 2026-07-09T10:40:28.269Z

Summary

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

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

@clerk/shared

Current version: 4.25.1
Recommended bump: MINOR → 4.26.0

Subpath `./types`

🟡 Non-breaking Changes (2)

Modified: `SignInFutureResource.submitProtectCheck`

- submitProtectCheck: (params: {
-     proofToken: string;
-   }) => Promise<{
+ submitProtectCheck: (params: SignInFutureSubmitProtectCheckParams) => Promise<{
      error: ClerkError | null;
    }>;

Static analyzer: Breaking change in property SignInFutureResource.submitProtectCheck: Type changed: (params:{proofToken:string;})=>!Promise:interface<{error:import("@clerk/shared").~ClerkError|null;}> → (params:import("@clerk/shared").SignInFutureSubmitProtectCheckParams)=>!Promise:interface<{error:import("@clerk/shared"…

🤖 AI review (reclassified as non-breaking) (97%): The new parameter type SignInFutureSubmitProtectCheckParams is structurally identical to the old inline type { proofToken: string } — it has exactly one required property proofToken: string — so no existing well-typed caller is affected.

Modified: `SignUpFutureResource.submitProtectCheck`

- submitProtectCheck: (params: {
-     proofToken: string;
-   }) => Promise<{
+ submitProtectCheck: (params: SignUpFutureSubmitProtectCheckParams) => Promise<{
      error: ClerkError | null;
    }>;

Static analyzer: Breaking change in property SignUpFutureResource.submitProtectCheck: Type changed: (params:{proofToken:string;})=>!Promise:interface<{error:import("@clerk/shared").~ClerkError|null;}> → (params:import("@clerk/shared").SignUpFutureSubmitProtectCheckParams)=>!Promise:interface<{error:import("@clerk/shared"…

🤖 AI review (reclassified as non-breaking) (97%): The new parameter type SignUpFutureSubmitProtectCheckParams is structurally identical to the old inline type { proofToken: string } — it has exactly one required property proofToken: string — so no existing well-typed caller is affected.

🟢 Additions (4)

Added: `SignInFutureSubmitProtectCheckParams`

+ interface SignInFutureSubmitProtectCheckParams

Added interface SignInFutureSubmitProtectCheckParams

Added: `SignInFutureSubmitProtectCheckParams.proofToken`

+ proofToken: string;

Added property SignInFutureSubmitProtectCheckParams.proofToken

Added: `SignUpFutureSubmitProtectCheckParams`

+ interface SignUpFutureSubmitProtectCheckParams

Added interface SignUpFutureSubmitProtectCheckParams

Added: `SignUpFutureSubmitProtectCheckParams.proofToken`

+ proofToken: string;

Added property SignUpFutureSubmitProtectCheckParams.proofToken

Report generated by Break Check

_{Last ran on 9c42ca5.}

wobsoriano

looks good, let me know if this is readhy to merge

SarahSoutoul added 2 commits July 9, 2026 11:17

Fix display of parameters of submitProtectCheck

0e6917d

Improve parameters descriptions

f02497b

SarahSoutoul self-assigned this Jul 9, 2026

Improve formatting

9c42ca5

vercel Bot deployed to Preview – clerk-js-sandbox July 9, 2026 10:37 View deployment

vercel Bot deployed to Preview – swingset July 9, 2026 10:39 View deployment

SarahSoutoul requested review from manovotny and wobsoriano July 9, 2026 16:36

wobsoriano approved these changes Jul 9, 2026

View reviewed changes

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Uh oh!

docs(shared): Improve protect check parameter types and Typedoc output#9116

docs(shared): Improve protect check parameter types and Typedoc output#9116
SarahSoutoul wants to merge 3 commits into
mainfrom
ss/improve-protect-check-typedoc-output

SarahSoutoul commented Jul 9, 2026 •

edited by coderabbitai Bot

Loading

Uh oh!

vercel Bot commented Jul 9, 2026 •

edited

Loading

Uh oh!

changeset-bot Bot commented Jul 9, 2026 •

edited

Loading

Uh oh!

coderabbitai Bot commented Jul 9, 2026 •

edited

Loading

Walkthrough

Changes

Uh oh!

pkg-pr-new Bot commented Jul 9, 2026 •

edited

Loading

Uh oh!

github-actions Bot commented Jul 9, 2026 •

edited

Loading

Uh oh!

wobsoriano left a comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

Uh oh!

Conversation

SarahSoutoul commented Jul 9, 2026 • edited by coderabbitai Bot Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Description

Checklist

Type of change

Summary by CodeRabbit

Summary by CodeRabbit

Uh oh!

vercel Bot commented Jul 9, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

changeset-bot Bot commented Jul 9, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

🦋 Changeset detected

Uh oh!

coderabbitai Bot commented Jul 9, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Walkthrough

Changes

Uh oh!

pkg-pr-new Bot commented Jul 9, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

github-actions Bot commented Jul 9, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

API Changes Report

Summary

@clerk/shared

Subpath ./types

🟡 Non-breaking Changes (2)

Modified: SignInFutureResource.submitProtectCheck

Modified: SignUpFutureResource.submitProtectCheck

🟢 Additions (4)

Added: SignInFutureSubmitProtectCheckParams

Added: SignInFutureSubmitProtectCheckParams.proofToken

Added: SignUpFutureSubmitProtectCheckParams

Added: SignUpFutureSubmitProtectCheckParams.proofToken

Uh oh!

wobsoriano left a comment

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

SarahSoutoul commented Jul 9, 2026 •

edited by coderabbitai Bot

Loading

vercel Bot commented Jul 9, 2026 •

edited

Loading

changeset-bot Bot commented Jul 9, 2026 •

edited

Loading

coderabbitai Bot commented Jul 9, 2026 •

edited

Loading

pkg-pr-new Bot commented Jul 9, 2026 •

edited

Loading

github-actions Bot commented Jul 9, 2026 •

edited

Loading

Subpath `./types`

Modified: `SignInFutureResource.submitProtectCheck`

Modified: `SignUpFutureResource.submitProtectCheck`

Added: `SignInFutureSubmitProtectCheckParams`

Added: `SignInFutureSubmitProtectCheckParams.proofToken`

Added: `SignUpFutureSubmitProtectCheckParams`

Added: `SignUpFutureSubmitProtectCheckParams.proofToken`