diff --git a/.changeset/smooth-buckets-collect.md b/.changeset/smooth-buckets-collect.md new file mode 100644 index 00000000000..6ef9e7c712c --- /dev/null +++ b/.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. diff --git a/packages/clerk-js/src/core/resources/SignIn.ts b/packages/clerk-js/src/core/resources/SignIn.ts index 68b99b38dfe..65a72ef1c92 100644 --- a/packages/clerk-js/src/core/resources/SignIn.ts +++ b/packages/clerk-js/src/core/resources/SignIn.ts @@ -54,6 +54,7 @@ import type { SignInFutureResetPasswordSubmitParams, SignInFutureResource, SignInFutureSSOParams, + SignInFutureSubmitProtectCheckParams, SignInFutureTicketParams, SignInFutureTOTPVerifyParams, SignInFutureWeb3Params, @@ -850,7 +851,7 @@ class SignInFuture implements SignInFutureResource { * @param params.proofToken - The proof token produced by the Protect challenge SDK. * @returns A promise resolving to `{ error }` — `null` on success, otherwise the encountered error. */ - async submitProtectCheck(params: { proofToken: string }): Promise<{ error: ClerkError | null }> { + async submitProtectCheck(params: SignInFutureSubmitProtectCheckParams): Promise<{ error: ClerkError | null }> { return runAsyncResourceTask(this.#resource, async () => { await this.#resource.__internal_basePatch({ action: 'protect_check', diff --git a/packages/clerk-js/src/core/resources/SignUp.ts b/packages/clerk-js/src/core/resources/SignUp.ts index bf58c7e59b0..2a4ed453c3d 100644 --- a/packages/clerk-js/src/core/resources/SignUp.ts +++ b/packages/clerk-js/src/core/resources/SignUp.ts @@ -33,6 +33,7 @@ import type { SignUpFuturePhoneCodeVerifyParams, SignUpFutureResource, SignUpFutureSSOParams, + SignUpFutureSubmitProtectCheckParams, SignUpFutureTicketParams, SignUpFutureUpdateParams, SignUpFutureVerifications as SignUpFutureVerificationsType, @@ -1201,7 +1202,7 @@ class SignUpFuture implements SignUpFutureResource { * @param params.proofToken - The proof token produced by the Protect challenge SDK. * @returns A promise resolving to `{ error }` — `null` on success, otherwise the encountered error. */ - async submitProtectCheck(params: { proofToken: string }): Promise<{ error: ClerkError | null }> { + async submitProtectCheck(params: SignUpFutureSubmitProtectCheckParams): Promise<{ error: ClerkError | null }> { return runAsyncResourceTask(this.#resource, async () => { await this.#resource.__internal_basePatch({ action: 'protect_check', diff --git a/packages/shared/src/types/signInFuture.ts b/packages/shared/src/types/signInFuture.ts index 51f77bdf1ab..d46ce7e0f20 100644 --- a/packages/shared/src/types/signInFuture.ts +++ b/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. diff --git a/packages/shared/src/types/signUpCommon.ts b/packages/shared/src/types/signUpCommon.ts index b0cf235e865..699ec380869 100644 --- a/packages/shared/src/types/signUpCommon.ts +++ b/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; } diff --git a/packages/shared/src/types/signUpFuture.ts b/packages/shared/src/types/signUpFuture.ts index ae98a8fa484..eb2075bfe8e 100644 --- a/packages/shared/src/types/signUpFuture.ts +++ b/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.