fix(shared): Update method return types

[dstaley]

Description

This PR fixes the method return types of our new custom flow APIs, which are declared in two locations. Previously, we updated the method return type on the actual implemented method to Promise<{ error: ClerkError | null }>, but neglected to update the interface types within shared/types with the new return type.

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

• Bug Fixes
  • Fixed return type definitions for custom flow API methods to properly specify error types instead of generic error handling, improving type safety and enabling better compile-time error detection.

[changeset-bot]

🦋 Changeset detected

Latest commit: fc3e088

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

This PR includes changesets to release 22 packages

Name	Type
@clerk/shared	Patch
@clerk/agent-toolkit	Patch
@clerk/astro	Patch
@clerk/backend	Patch
@clerk/chrome-extension	Patch
@clerk/clerk-js	Patch
@clerk/elements	Patch
@clerk/expo-passkeys	Patch
@clerk/clerk-expo	Patch
@clerk/express	Patch
@clerk/fastify	Patch
@clerk/nextjs	Patch
@clerk/nuxt	Patch
@clerk/react-router	Patch
@clerk/clerk-react	Patch
@clerk/remix	Patch
@clerk/tanstack-react-start	Patch
@clerk/testing	Patch
@clerk/themes	Patch
@clerk/types	Patch
@clerk/vue	Patch
@clerk/localizations	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

[vercel]

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

Project	Deployment	Preview	Comments	Updated (UTC)
clerk-js-sandbox	Ready	Preview	Comment	Nov 18, 2025 4:19pm

[coderabbitai]

Walkthrough

This PR updates method return type signatures in the Clerk shared package's custom flow APIs, replacing unknown error types with the more specific ClerkError | null type across SignInFutureResource and SignUpFutureResource interfaces, with a corresponding changeset marking the patch release.

Changes

Cohort / File(s)	Change Summary
Changeset Entry .changeset/orange-grapes-peel.md	Added patch release changeset for experimental feature indicating a fix to method return types for custom flow APIs.
Sign-In API Type Updates packages/shared/src/types/signInFuture.ts	Imported ClerkError type and updated all 20+ method signatures in SignInFutureResource to return Promise<{ error: ClerkError | null }> instead of Promise<{ error: unknown }>, covering create, password, emailCode.*, emailLink.*, phoneCode.*, resetPasswordEmailCode.*, sso, mfa.*, ticket, web3, passkey, and finalize methods.
Sign-Up API Type Updates packages/shared/src/types/signUpFuture.ts	Imported ClerkError type and updated 11 method signatures in SignUpFutureResource to return Promise<{ error: ClerkError | null }> instead of Promise<{ error: unknown }>, covering create, update, verifications.*, password, sso, ticket, web3, and finalize methods.

Estimated code review effort

🎯 2 (Simple) | ⏱️ ~12 minutes

• Homogeneous changes following a consistent pattern across multiple methods reduce review complexity
• Verify ClerkError import is correctly scoped and used appropriately in both files
• Confirm that all method signatures have been consistently updated without omissions
• Check that ClerkError | null accurately reflects the error handling contract across both resource types

Poem

🐰 With types now precise, no more the unknown,
ClerkError's specificity clearly shown!
From sign-in to sign-up, each method aligned,
Better error handling for developers to find. ✨

Pre-merge checks and finishing touches

✅ Passed checks (3 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: updating method return types in the shared package for custom flow APIs to use ClerkError instead of unknown.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.

✨ Finishing touches

• 📝 Generate docstrings

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Post copyable unit tests in a comment
• Commit unit tests in branch ds.fix/signals-return-types

Tip

📝 Customizable high-level summaries are now available in beta!

You can now customize how CodeRabbit generates the high-level summary in your pull requests — including its content, structure, tone, and formatting.

• Provide your own instructions using the high_level_summary_instructions setting.
• Format the summary however you like (bullet lists, tables, multi-section layouts, contributor stats, etc.).
• Use high_level_summary_in_walkthrough to move the summary from the description to the walkthrough section.

Example instruction:

"Divide the high-level summary into five sections:

1. 📝 Description — Summarize the main change in 50–60 words, explaining what was done.
2. 📓 References — List relevant issues, discussions, documentation, or related PRs.
3. 📦 Dependencies & Requirements — Mention any new/updated dependencies, environment variable changes, or configuration updates.
4. 📊 Contributor Summary — Include a Markdown table showing contributions:
   | Contributor | Lines Added | Lines Removed | Files Changed |
5. ✔️ Additional Notes — Add any extra reviewer context.
   Keep each section concise (under 200 words) and use bullet or numbered lists for clarity."

Note: This feature is currently in beta for Pro-tier users, and pricing will be announced later.

---

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

[coderabbitai]

Actionable comments posted: 0

🧹 Nitpick comments (1)

packages/shared/src/types/signInFuture.ts (1)

1-1: SignInFuture methods now consistently return Promise<{ error: ClerkError | null }>

The added ClerkError import and the updated signatures for all SignInFutureResource methods that expose an error (create, password, all emailCode / emailLink / phoneCode / resetPasswordEmailCode helpers, sso, mfa.*, ticket, web3, passkey, finalize) are consistent and align this shared type with the implementation and with SignUpFutureResource. This removes the previous unknown error typing and gives consumers a concrete, uniform ClerkError | null surface without introducing any apparent inconsistencies in this file.

As a low-priority follow-up (not needed for this PR), you might consider extending or linking the JSDoc to briefly describe or reference the ClerkError shape so integrators know what to inspect on error.

Also applies to: 344-488

📜 Review details

Configuration used: Path: .coderabbit.yaml

Review profile: CHILL

Plan: Pro

Disabled knowledge base sources:

• Linear integration is disabled by default for public repositories

You can enable these sources in your CodeRabbit configuration.

📥 Commits

Reviewing files that changed from the base of the PR and between 5966383 and fc3e088.

📒 Files selected for processing (3)

• .changeset/orange-grapes-peel.md (1 hunks)
• packages/shared/src/types/signInFuture.ts (7 hunks)
• packages/shared/src/types/signUpFuture.ts (3 hunks)

⏰ Context from checks skipped due to timeout of 90000ms. You can increase the timeout in your CodeRabbit configuration to a maximum of 15 minutes (900000ms). (5)

• GitHub Check: Formatting | Dedupe | Changeset
• GitHub Check: Build Packages
• GitHub Check: Analyze (javascript-typescript)
• GitHub Check: semgrep-cloud-platform/scan
• GitHub Check: semgrep-cloud-platform/scan

🔇 Additional comments (2)

.changeset/orange-grapes-peel.md (1)

1-5: Changeset entry is properly formatted.

The YAML frontmatter, package specification, and description are all correct. The patch version bump is appropriate for a type signature fix that corrects API return types without introducing new functionality.

Please verify that:

1. The related type files (SignInFutureResource and SignUpFutureResource interfaces) have been updated to return Promise<{ error: ClerkError | null }> as described in the PR summary.
2. JSDoc comments in the type definition files have been added or updated, if applicable.
3. Tests and builds pass (pnpm test and pnpm build).

Since the actual type file changes are not provided in this review, I recommend running verification scripts to confirm the type updates are consistent across the codebase.

packages/shared/src/types/signUpFuture.ts (1)

1-1: SignUpFuture error typing now consistently reflects ClerkError

The new ClerkError import and the updated SignUpFutureResource method signatures all align on Promise<{ error: ClerkError | null }>, which matches the described runtime behavior and removes the vague unknown typing. The changes look internally consistent across create, update, verifications.*, password, sso, ticket, web3, and finalize, with no remaining { error: unknown } in this interface.

Also applies to: 402-458

[pkg-pr-new]

Open in StackBlitz

@clerk/agent-toolkit

npm i https://pkg.pr.new/@clerk/agent-toolkit@7250

@clerk/astro

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

@clerk/backend

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

@clerk/chrome-extension

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

@clerk/clerk-js

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

@clerk/dev-cli

npm i https://pkg.pr.new/@clerk/dev-cli@7250

@clerk/elements

npm i https://pkg.pr.new/@clerk/elements@7250

@clerk/clerk-expo

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

@clerk/expo-passkeys

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

@clerk/express

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

@clerk/fastify

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

@clerk/localizations

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

@clerk/nextjs

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

@clerk/nuxt

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

@clerk/clerk-react

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

@clerk/react-router

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

@clerk/remix

npm i https://pkg.pr.new/@clerk/remix@7250

@clerk/shared

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

@clerk/tanstack-react-start

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

@clerk/testing

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

@clerk/themes

npm i https://pkg.pr.new/@clerk/themes@7250

@clerk/types

npm i https://pkg.pr.new/@clerk/types@7250

@clerk/upgrade

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

@clerk/vue

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

commit: fc3e088