From 47d4c024f7b57eed4cc70da8b05ec109d59c7e63 Mon Sep 17 00:00:00 2001 From: Kenton Duprey Date: Tue, 16 Dec 2025 20:25:14 -0500 Subject: [PATCH 1/3] refactor(errors): Update exported error typeguard functions from error.ts, align error class naming Signed-off-by: Kenton Duprey --- packages/shared/src/error.ts | 10 +++--- packages/shared/src/errors/clerkApiError.ts | 10 +++--- .../src/errors/clerkApiResponseError.ts | 8 ++--- packages/shared/src/errors/globalHookError.ts | 4 +-- packages/shared/src/errors/helpers.ts | 31 ++----------------- 5 files changed, 17 insertions(+), 46 deletions(-) diff --git a/packages/shared/src/error.ts b/packages/shared/src/error.ts index ad8cea5ce3b..3f034067234 100644 --- a/packages/shared/src/error.ts +++ b/packages/shared/src/error.ts @@ -1,8 +1,8 @@ export { errorToJSON, parseError, parseErrors } from './errors/parseError'; -export { ClerkAPIError } from './errors/clerkApiError'; -export { ClerkAPIResponseError } from './errors/clerkApiResponseError'; -export { ClerkError } from './errors/clerkError'; +export { ClerkAPIError, isClerkAPIError } from './errors/clerkApiError'; +export { ClerkAPIResponseError, isClerkAPIResponseError } from './errors/clerkApiResponseError'; +export { ClerkError, isClerkError } from './errors/clerkError'; export { buildErrorThrower, type ErrorThrower, type ErrorThrowerOptions } from './errors/errorThrower'; @@ -10,15 +10,13 @@ export { EmailLinkError, EmailLinkErrorCode, EmailLinkErrorCodeStatus } from './ export type { MetamaskError } from './errors/metamaskError'; -export { ClerkRuntimeError } from './errors/clerkRuntimeError'; +export { ClerkRuntimeError, isClerkRuntimeError } from './errors/clerkRuntimeError'; export { ClerkWebAuthnError } from './errors/webAuthNError'; export { is4xxError, isCaptchaError, - isClerkAPIResponseError, - isClerkRuntimeError, isEmailLinkError, isKnownError, isMetamaskError, diff --git a/packages/shared/src/errors/clerkApiError.ts b/packages/shared/src/errors/clerkApiError.ts index 42fc43183ee..4daf5fa329b 100644 --- a/packages/shared/src/errors/clerkApiError.ts +++ b/packages/shared/src/errors/clerkApiError.ts @@ -1,13 +1,13 @@ import type { ClerkAPIError as ClerkAPIErrorInterface, ClerkAPIErrorJSON } from '../types'; import { createErrorTypeGuard } from './createErrorTypeGuard'; -export type ClerkApiErrorMeta = Record; +export type ClerkAPIErrorMeta = Record; /** * This error contains the specific error message, code, and any additional metadata that was returned by the Clerk API. */ -export class ClerkAPIError implements ClerkAPIErrorInterface { - static kind = 'ClerkApiError'; +export class ClerkAPIError implements ClerkAPIErrorInterface { + static kind = 'ClerkAPIError'; readonly code: string; readonly message: string; readonly longMessage: string | undefined; @@ -36,6 +36,6 @@ export class ClerkAPIError implements Cler } /** - * Type guard to check if a value is a ClerkApiError instance. + * Type guard to check if a value is a ClerkAPIError instance. */ -export const isClerkApiError = createErrorTypeGuard(ClerkAPIError); +export const isClerkAPIError = createErrorTypeGuard(ClerkAPIError); diff --git a/packages/shared/src/errors/clerkApiResponseError.ts b/packages/shared/src/errors/clerkApiResponseError.ts index 671c41bef5c..edf9dc04407 100644 --- a/packages/shared/src/errors/clerkApiResponseError.ts +++ b/packages/shared/src/errors/clerkApiResponseError.ts @@ -47,14 +47,14 @@ export class ClerkAPIResponseError extends ClerkError implements ClerkAPIRespons } /** - * Type guard to check if an error is a ClerkApiResponseError. + * Type guard to check if an error is a ClerkAPIResponseError. * Can be called as a standalone function or as a method on an error object. * * @example * // As a standalone function - * if (isClerkApiResponseError(error)) { ... } + * if (isClerkAPIResponseError(error)) { ... } * * // As a method (when attached to error object) - * if (error.isClerkApiResponseError()) { ... } + * if (error.isClerkAPIResponseError()) { ... } */ -export const isClerkApiResponseError = createErrorTypeGuard(ClerkAPIResponseError); +export const isClerkAPIResponseError = createErrorTypeGuard(ClerkAPIResponseError); diff --git a/packages/shared/src/errors/globalHookError.ts b/packages/shared/src/errors/globalHookError.ts index c4615e16234..c02c813b443 100644 --- a/packages/shared/src/errors/globalHookError.ts +++ b/packages/shared/src/errors/globalHookError.ts @@ -1,4 +1,4 @@ -import { isClerkApiResponseError } from './clerkApiResponseError'; +import { isClerkAPIResponseError } from './clerkApiResponseError'; import type { ClerkError } from './clerkError'; import { isClerkRuntimeError } from './clerkRuntimeError'; @@ -9,7 +9,7 @@ import { isClerkRuntimeError } from './clerkRuntimeError'; */ export function createClerkGlobalHookError(error: ClerkError) { const predicates = { - isClerkApiResponseError, + isClerkAPIResponseError, isClerkRuntimeError, } as const; diff --git a/packages/shared/src/errors/helpers.ts b/packages/shared/src/errors/helpers.ts index 5d28681e836..b95f55d5a8c 100644 --- a/packages/shared/src/errors/helpers.ts +++ b/packages/shared/src/errors/helpers.ts @@ -1,5 +1,7 @@ import type { ClerkAPIResponseError } from './clerkApiResponseError'; +import { isClerkAPIResponseError } from './clerkApiResponseError'; import type { ClerkRuntimeError } from './clerkRuntimeError'; +import { isClerkRuntimeError } from './clerkRuntimeError'; import type { EmailLinkError } from './emailLinkError'; import type { MetamaskError } from './metamaskError'; @@ -55,35 +57,6 @@ export function isKnownError(error: any): error is ClerkAPIResponseError | Clerk return isClerkAPIResponseError(error) || isMetamaskError(error) || isClerkRuntimeError(error); } -/** - * Checks if the provided error is a ClerkAPIResponseError. - * - * @internal - */ -export function isClerkAPIResponseError(err: any): err is ClerkAPIResponseError { - return err && 'clerkError' in err; -} - -/** - * Checks if the provided error object is an instance of ClerkRuntimeError. - * - * @param err - The error object to check. - * @returns True if the error is a ClerkRuntimeError, false otherwise. - * - * @example - * const error = new ClerkRuntimeError('An error occurred'); - * if (isClerkRuntimeError(error)) { - * // Handle ClerkRuntimeError - * console.error('ClerkRuntimeError:', error.message); - * } else { - * // Handle other errors - * console.error('Other error:', error.message); - * } - */ -export function isClerkRuntimeError(err: any): err is ClerkRuntimeError { - return 'clerkRuntimeError' in err; -} - /** * Checks if the provided error is a Clerk runtime error indicating a reverification was cancelled. * From d948e0d3cc1c50133bd824184a6a5906c0b0a80f Mon Sep 17 00:00:00 2001 From: Kenton Duprey Date: Tue, 16 Dec 2025 20:32:08 -0500 Subject: [PATCH 2/3] chore: pnpm changeset Signed-off-by: Kenton Duprey --- .changeset/sweet-singers-beg.md | 5 +++++ 1 file changed, 5 insertions(+) create mode 100644 .changeset/sweet-singers-beg.md diff --git a/.changeset/sweet-singers-beg.md b/.changeset/sweet-singers-beg.md new file mode 100644 index 00000000000..61b5eb99954 --- /dev/null +++ b/.changeset/sweet-singers-beg.md @@ -0,0 +1,5 @@ +--- +'@clerk/shared': patch +--- + +Refactor internal Clerk error handling functions From 33bcd4c527aa3f5cb26712ba1a39a434b5172dff Mon Sep 17 00:00:00 2001 From: Kenton Duprey Date: Wed, 17 Dec 2025 17:36:51 -0500 Subject: [PATCH 3/3] fix(errors): Revert static kind naming in ClerkAPIError class and add todo for core 3 breaking change Signed-off-by: Kenton Duprey --- packages/shared/src/errors/clerkApiError.ts | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/packages/shared/src/errors/clerkApiError.ts b/packages/shared/src/errors/clerkApiError.ts index 4daf5fa329b..f06339df7c7 100644 --- a/packages/shared/src/errors/clerkApiError.ts +++ b/packages/shared/src/errors/clerkApiError.ts @@ -7,7 +7,8 @@ export type ClerkAPIErrorMeta = Record; * This error contains the specific error message, code, and any additional metadata that was returned by the Clerk API. */ export class ClerkAPIError implements ClerkAPIErrorInterface { - static kind = 'ClerkAPIError'; + // TODO: Update kind to match class name in Core 3 + static kind = 'ClerkApiError'; readonly code: string; readonly message: string; readonly longMessage: string | undefined;