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

.changeset/smooth-buckets-collect.md

@@ -0,0 +1,5 @@
+---
+'@clerk/shared': patch
+---
+
+Add named protect check parameter types for future sign-in and sign-up flows.

packages/shared/src/types/signInFuture.ts

@@ -131,6 +131,14 @@ export interface SignInFutureEmailCodeVerifyParams {
   code: string;
 }
 
+/** @generateWithEmptyComment */
+export interface SignInFutureSubmitProtectCheckParams {
+  /**
+   * The proof token produced by the Protect challenge SDK.
+   */
+  proofToken: string;
+}
+
 /** @generateWithEmptyComment */
 export interface SignInFutureResetPasswordSubmitParams {
   /**
@@ -569,10 +577,9 @@ export interface SignInFutureResource {
   passkey: (params?: SignInFuturePasskeyParams) => Promise<{ error: ClerkError | null }>;
 
   /**
-   * Submits a proof token to resolve a pending protect check challenge. The response may contain
-   * another `protectCheck` (a chained challenge) which must be resolved iteratively.
+   * Submits a proof token to resolve a pending protect check challenge. The response may contain another `protectCheck` (a chained challenge) which must be resolved iteratively.
    */
-  submitProtectCheck: (params: { proofToken: string }) => Promise<{ error: ClerkError | null }>;
+  submitProtectCheck: (params: SignInFutureSubmitProtectCheckParams) => Promise<{ error: ClerkError | null }>;
 
   /**
    * Converts a sign-in with `status === 'complete'` into an active session. Will cause anything observing the session state (such as the [`useUser()`](https://clerk.com/docs/reference/hooks/use-user) hook) to update automatically.

packages/shared/src/types/signUpCommon.ts

@@ -31,28 +31,29 @@ export type ProtectCheckField = 'protect_check';
 export type SignUpField = SignUpAttributeField | SignUpIdentificationField | ProtectCheckField;
 
 /**
- * An interface that represents a pending Clerk Protect mid-flow challenge. Only surfaced when Protect mid-flow challenges are
- * explicitly enabled for the instance; upgrading the SDK alone does not enable it.
+ * A pending Clerk Protect challenge that must be completed before the current sign-in or sign-up attempt can continue.
+ *
+ * This resource is only returned when Protect mid-flow challenges are enabled for the instance. When present, load the challenge SDK from `sdkUrl`, initialize it with `token` and `uiHints`, and submit the proof token returned by the SDK with `submitProtectCheck()`.
  */
 export interface ProtectCheckResource {
   /**
-   * Always `'pending'` when surfaced to clients.
+   * The current state of the Protect challenge. Protect check resources are only returned while the challenge is waiting to be completed.
    */
   status: 'pending';
   /**
-   * Opaque challenge token to pass to the Clerk Protect challenge SDK.
+   * An opaque challenge token generated by Clerk. Pass this value unchanged to the Protect challenge SDK.
    */
   token: string;
   /**
-   * URL of the Clerk Protect challenge SDK to load for this challenge.
+   * The URL of the Protect challenge SDK to load for this specific challenge.
    */
   sdkUrl: string;
   /**
-   * Unix epoch timestamp in **milliseconds** at which the challenge expires.
+   * Unix epoch timestamp, in milliseconds, when the challenge expires and can no longer be completed.
    */
   expiresAt?: number;
   /**
-   * Optional UI hints for rendering the challenge.
+   * Optional Clerk-provided presentation hints. Pass these values through to the Protect challenge SDK as-is.
    */
   uiHints?: Record<string, string>;
 }

packages/shared/src/types/signUpFuture.ts

@@ -93,6 +93,14 @@ export interface SignUpFutureCreateParams extends SignUpFutureAdditionalParams {
   web3Wallet?: string;
 }
 
+/** @generateWithEmptyComment */
+export interface SignUpFutureSubmitProtectCheckParams {
+  /**
+   * The proof token produced by the Protect challenge SDK.
+   */
+  proofToken: string;
+}
+
 /** @generateWithEmptyComment */
 export interface SignUpFutureUpdateParams extends SignUpFutureAdditionalParams {
   /**
@@ -524,10 +532,9 @@ export interface SignUpFutureResource {
   web3: (params: SignUpFutureWeb3Params) => Promise<{ error: ClerkError | null }>;
 
   /**
-   * Submits a proof token to resolve a pending protect check challenge. The response may contain
-   * another `protectCheck` (a chained challenge) which must be resolved iteratively.
+   * Submits a proof token to resolve a pending protect check challenge. The response may contain another `protectCheck` (a chained challenge) which must be resolved iteratively.
    */
-  submitProtectCheck: (params: { proofToken: string }) => Promise<{ error: ClerkError | null }>;
+  submitProtectCheck: (params: SignUpFutureSubmitProtectCheckParams) => Promise<{ error: ClerkError | null }>;
 
   /**
    * Converts a sign-up with `status === 'complete'` into an active session. Will cause anything observing the session state (such as the [`useUser()`](https://clerk.com/docs/reference/hooks/use-user) hook) to update automatically.