feat(clerk-js): Type errors.global as ClerkGlobalHookError

.changeset/moody-parks-scream.md

@@ -0,0 +1,6 @@
+---
+'@clerk/clerk-js': minor
+'@clerk/shared': minor
+---
+
+[Experimental] Add types for errors used in new custom flow APIs

packages/clerk-js/src/core/events.ts

@@ -1,3 +1,4 @@
+import type { ClerkError } from '@clerk/shared/error';
 import { createEventBus } from '@clerk/shared/eventBus';
 import type { TokenResource } from '@clerk/shared/types';
 
@@ -15,7 +16,7 @@ export const events = {
 
 type TokenUpdatePayload = { token: TokenResource | null };
 export type ResourceUpdatePayload = { resource: BaseResource };
-export type ResourceErrorPayload = { resource: BaseResource; error: unknown };
+export type ResourceErrorPayload = { resource: BaseResource; error: ClerkError | null };
 export type ResourceFetchPayload = { resource: BaseResource; status: 'idle' | 'fetching' };
 
 type InternalEvents = {

packages/clerk-js/src/core/signals.ts

@@ -1,4 +1,4 @@
-import { isClerkAPIResponseError } from '@clerk/shared/error';
+import { type ClerkError, createClerkGlobalHookError, isClerkAPIResponseError } from '@clerk/shared/error';
 import type { Errors, SignInSignal, SignUpSignal } from '@clerk/shared/types';
 import { snakeToCamel } from '@clerk/shared/underscore';
 import { computed, signal } from 'alien-signals';
@@ -7,7 +7,7 @@ import type { SignIn } from './resources/SignIn';
 import type { SignUp } from './resources/SignUp';
 
 export const signInResourceSignal = signal<{ resource: SignIn | null }>({ resource: null });
-export const signInErrorSignal = signal<{ error: unknown }>({ error: null });
+export const signInErrorSignal = signal<{ error: ClerkError | null }>({ error: null });
 export const signInFetchSignal = signal<{ status: 'idle' | 'fetching' }>({ status: 'idle' });
 
 export const signInComputedSignal: SignInSignal = computed(() => {
@@ -21,7 +21,7 @@ export const signInComputedSignal: SignInSignal = computed(() => {
 });
 
 export const signUpResourceSignal = signal<{ resource: SignUp | null }>({ resource: null });
-export const signUpErrorSignal = signal<{ error: unknown }>({ error: null });
+export const signUpErrorSignal = signal<{ error: ClerkError | null }>({ error: null });
 export const signUpFetchSignal = signal<{ status: 'idle' | 'fetching' }>({ status: 'idle' });
 
 export const signUpComputedSignal: SignUpSignal = computed(() => {
@@ -38,7 +38,7 @@ export const signUpComputedSignal: SignUpSignal = computed(() => {
  * Converts an error to a parsed errors object that reports the specific fields that the error pertains to. Will put
  * generic non-API errors into the global array.
  */
-function errorsToParsedErrors(error: unknown): Errors {
+function errorsToParsedErrors(error: ClerkError | null): Errors {
  const parsedErrors: Errors = {
  fields: {
  firstName: null,
@@ -62,29 +62,32 @@ function errorsToParsedErrors(error: unknown): Errors {
 
  if (!isClerkAPIResponseError(error)) {
  parsedErrors.raw = [error];
- parsedErrors.global = [error];
+ parsedErrors.global = [createClerkGlobalHookError(error)];
  return parsedErrors;
  }
 
- error.errors.forEach(error => {
- if (parsedErrors.raw) {
- parsedErrors.raw.push(error);
- } else {
- parsedErrors.raw = [error];
- }
-
- if ('meta' in error && error.meta && 'paramName' in error.meta) {
- const name = snakeToCamel(error.meta.paramName);
- parsedErrors.fields[name as keyof typeof parsedErrors.fields] = error;
- return;
- }
-
- if (parsedErrors.global) {
- parsedErrors.global.push(error);
- } else {
- parsedErrors.global = [error];
- }
- });
+ const hasFieldErrors = error.errors.some(error => 'meta' in error && error.meta && 'paramName' in error.meta);
+ if (hasFieldErrors) {
+ error.errors.forEach(error => {
+ if (parsedErrors.raw) {
+ parsedErrors.raw.push(error);
+ } else {
+ parsedErrors.raw = [error];
+ }
+ if ('meta' in error && error.meta && 'paramName' in error.meta) {
+ const name = snakeToCamel(error.meta.paramName);
+ parsedErrors.fields[name as keyof typeof parsedErrors.fields] = error;
+ }
+ // Note that this assumes a given ClerkAPIResponseError will only have either field errors or global errors, but
+ // not both. If a global error is present, it will be discarded.
+ });
+
+ return parsedErrors;
+ }
+
+ // At this point, we know that `error` is a ClerkAPIResponseError and that it has no field errors.
+ parsedErrors.raw = [error];
+ parsedErrors.global = [createClerkGlobalHookError(error)];
 
  return parsedErrors;
 }

packages/clerk-js/src/core/state.ts

@@ -1,3 +1,4 @@
+import type { ClerkError } from '@clerk/shared/error';
 import type { State as StateInterface } from '@clerk/shared/types';
 import { computed, effect } from 'alien-signals';
 
@@ -36,7 +37,7 @@ export class State implements StateInterface {
  eventBus.on('resource:fetch', this.onResourceFetch);
  }
 
- private onResourceError = (payload: { resource: BaseResource; error: unknown }) => {
+ private onResourceError = (payload: { resource: BaseResource; error: ClerkError | null }) => {
  if (payload.resource instanceof SignIn) {
  this.signInErrorSignal({ error: payload.error });
  }

packages/shared/src/error.ts

@@ -2,6 +2,7 @@ export { errorToJSON, parseError, parseErrors } from './errors/parseError';
 
 export { ClerkAPIError } from './errors/clerkApiError';
 export { ClerkAPIResponseError } from './errors/clerkApiResponseError';
+export { ClerkError } from './errors/clerkError';
 
 export { buildErrorThrower, type ErrorThrower, type ErrorThrowerOptions } from './errors/errorThrower';
 
@@ -27,3 +28,5 @@ export {
  isUnauthorizedError,
  isUserLockedError,
 } from './errors/helpers';
+
+export { createClerkGlobalHookError } from './errors/globalHookError';

packages/shared/src/errors/clerkApiError.ts

@@ -14,15 +14,7 @@ export class ClerkAPIError<Meta extends ClerkApiErrorMeta = any> implements Cler
  readonly meta: Meta;
 
  constructor(json: ClerkAPIErrorJSON) {
- const parsedError = this.parseJsonError(json);
- this.code = parsedError.code;
- this.message = parsedError.message;
- this.longMessage = parsedError.longMessage;
- this.meta = parsedError.meta;
- }
-
- private parseJsonError(json: ClerkAPIErrorJSON) {
- return {
+ const parsedError = {
  code: json.code,
  message: json.message,
  longMessage: json.long_message,
@@ -36,6 +28,10 @@ export class ClerkAPIError<Meta extends ClerkApiErrorMeta = any> implements Cler
  isPlanUpgradePossible: json.meta?.is_plan_upgrade_possible,
  } as unknown as Meta,
  };
+ this.code = parsedError.code;
+ this.message = parsedError.message;
+ this.longMessage = parsedError.longMessage;
+ this.meta = parsedError.meta;
  }
 }
 

packages/shared/src/errors/globalHookError.ts

@@ -0,0 +1,23 @@
+import { isClerkApiResponseError } from './clerkApiResponseError';
+import type { ClerkError } from './clerkError';
+import { isClerkRuntimeError } from './clerkRuntimeError';
+
+/**
+ * Creates a ClerkGlobalHookError object from a ClerkError instance.
+ * It's a wrapper for all the different instances of Clerk errors that can
+ * be returned when using Clerk hooks.
+ */
+export function createClerkGlobalHookError(error: ClerkError) {
+ const predicates = {
+ isClerkApiResponseError,
+ isClerkRuntimeError,
+ } as const;
+
+ for (const [name, fn] of Object.entries(predicates)) {
+ Object.assign(error, { [name]: fn });
+ }
+
+ return error as ClerkError & typeof predicates;
+}
+
+export type ClerkGlobalHookError = ReturnType<typeof createClerkGlobalHookError>;

packages/shared/src/types/state.ts

@@ -1,3 +1,4 @@
+import type { ClerkGlobalHookError } from '../errors/globalHookError';
 import type { SignInFutureResource } from './signInFuture';
 import type { SignUpFutureResource } from './signUpFuture';
 
@@ -79,8 +80,9 @@ export interface Errors {
  raw: unknown[] | null;
  /**
  * Parsed errors that are not related to any specific field.
+ * Does not include any errors that could be parsed as a field error
  */
- global: unknown[] | null; // does not include any errors that could be parsed as a field error
+ global: ClerkGlobalHookError[] | null;
 }
 
 /**
@@ -143,6 +145,7 @@ export interface State {
  * An alias for `effect()` from `alien-signals`, which can be used to subscribe to changes from Signals.
  *
  * @see https://github.com/stackblitz/alien-signals#usage
+ *
  * @experimental This experimental API is subject to change.
  */
  __internal_effect: (callback: () => void) => () => void;
@@ -152,6 +155,7 @@ export interface State {
  * its dependencies change.
  *
  * @see https://github.com/stackblitz/alien-signals#usage
+ *
  * @experimental This experimental API is subject to change.
  */
  __internal_computed: <T>(getter: (previousValue?: T) => T) => () => T;

.changeset/moody-parks-scream.md

@@ -0,0 +1,6 @@
+---
+'@clerk/clerk-js': minor
+'@clerk/shared': minor
+---
+
+[Experimental] Add types for errors used in new custom flow APIs

packages/clerk-js/src/core/events.ts

@@ -1,3 +1,4 @@
+import type { ClerkError } from '@clerk/shared/error';
 import { createEventBus } from '@clerk/shared/eventBus';
 import type { TokenResource } from '@clerk/shared/types';
 
@@ -15,7 +16,7 @@ export const events = {
 
 type TokenUpdatePayload = { token: TokenResource | null };
 export type ResourceUpdatePayload = { resource: BaseResource };
-export type ResourceErrorPayload = { resource: BaseResource; error: unknown };
+export type ResourceErrorPayload = { resource: BaseResource; error: ClerkError | null };
 export type ResourceFetchPayload = { resource: BaseResource; status: 'idle' | 'fetching' };
 
 type InternalEvents = {

packages/clerk-js/src/core/signals.ts

@@ -1,4 +1,4 @@
-import { isClerkAPIResponseError } from '@clerk/shared/error';
+import { type ClerkError, createClerkGlobalHookError, isClerkAPIResponseError } from '@clerk/shared/error';
 import type { Errors, SignInSignal, SignUpSignal } from '@clerk/shared/types';
 import { snakeToCamel } from '@clerk/shared/underscore';
 import { computed, signal } from 'alien-signals';
@@ -7,7 +7,7 @@ import type { SignIn } from './resources/SignIn';
 import type { SignUp } from './resources/SignUp';
 
 export const signInResourceSignal = signal<{ resource: SignIn | null }>({ resource: null });
-export const signInErrorSignal = signal<{ error: unknown }>({ error: null });
+export const signInErrorSignal = signal<{ error: ClerkError | null }>({ error: null });
 export const signInFetchSignal = signal<{ status: 'idle' | 'fetching' }>({ status: 'idle' });
 
 export const signInComputedSignal: SignInSignal = computed(() => {
@@ -21,7 +21,7 @@ export const signInComputedSignal: SignInSignal = computed(() => {
 });
 
 export const signUpResourceSignal = signal<{ resource: SignUp | null }>({ resource: null });
-export const signUpErrorSignal = signal<{ error: unknown }>({ error: null });
+export const signUpErrorSignal = signal<{ error: ClerkError | null }>({ error: null });
 export const signUpFetchSignal = signal<{ status: 'idle' | 'fetching' }>({ status: 'idle' });
 
 export const signUpComputedSignal: SignUpSignal = computed(() => {
@@ -38,7 +38,7 @@ export const signUpComputedSignal: SignUpSignal = computed(() => {
  * Converts an error to a parsed errors object that reports the specific fields that the error pertains to. Will put
  * generic non-API errors into the global array.
  */
-function errorsToParsedErrors(error: unknown): Errors {
+function errorsToParsedErrors(error: ClerkError | null): Errors {
  const parsedErrors: Errors = {
  fields: {
  firstName: null,
@@ -62,29 +62,32 @@ function errorsToParsedErrors(error: unknown): Errors {
 
  if (!isClerkAPIResponseError(error)) {
  parsedErrors.raw = [error];
- parsedErrors.global = [error];
+ parsedErrors.global = [createClerkGlobalHookError(error)];
  return parsedErrors;
  }
 
- error.errors.forEach(error => {
- if (parsedErrors.raw) {
- parsedErrors.raw.push(error);
- } else {
- parsedErrors.raw = [error];
- }
-
- if ('meta' in error && error.meta && 'paramName' in error.meta) {
- const name = snakeToCamel(error.meta.paramName);
- parsedErrors.fields[name as keyof typeof parsedErrors.fields] = error;
- return;
- }
-
- if (parsedErrors.global) {
- parsedErrors.global.push(error);
- } else {
- parsedErrors.global = [error];
- }
- });
+ const hasFieldErrors = error.errors.some(error => 'meta' in error && error.meta && 'paramName' in error.meta);
+ if (hasFieldErrors) {
+ error.errors.forEach(error => {
+ if (parsedErrors.raw) {
+ parsedErrors.raw.push(error);
+ } else {
+ parsedErrors.raw = [error];
+ }
+ if ('meta' in error && error.meta && 'paramName' in error.meta) {
+ const name = snakeToCamel(error.meta.paramName);
+ parsedErrors.fields[name as keyof typeof parsedErrors.fields] = error;
+ }
+ // Note that this assumes a given ClerkAPIResponseError will only have either field errors or global errors, but
+ // not both. If a global error is present, it will be discarded.
+ });
+
+ return parsedErrors;
+ }
+
+ // At this point, we know that `error` is a ClerkAPIResponseError and that it has no field errors.
+ parsedErrors.raw = [error];
+ parsedErrors.global = [createClerkGlobalHookError(error)];
 
  return parsedErrors;
 }

packages/clerk-js/src/core/state.ts

@@ -1,3 +1,4 @@
+import type { ClerkError } from '@clerk/shared/error';
 import type { State as StateInterface } from '@clerk/shared/types';
 import { computed, effect } from 'alien-signals';
 
@@ -36,7 +37,7 @@ export class State implements StateInterface {
  eventBus.on('resource:fetch', this.onResourceFetch);
  }
 
- private onResourceError = (payload: { resource: BaseResource; error: unknown }) => {
+ private onResourceError = (payload: { resource: BaseResource; error: ClerkError | null }) => {
  if (payload.resource instanceof SignIn) {
  this.signInErrorSignal({ error: payload.error });
  }

packages/shared/src/error.ts

@@ -2,6 +2,7 @@ export { errorToJSON, parseError, parseErrors } from './errors/parseError';
 
 export { ClerkAPIError } from './errors/clerkApiError';
 export { ClerkAPIResponseError } from './errors/clerkApiResponseError';
+export { ClerkError } from './errors/clerkError';
 
 export { buildErrorThrower, type ErrorThrower, type ErrorThrowerOptions } from './errors/errorThrower';
 
@@ -27,3 +28,5 @@ export {
  isUnauthorizedError,
  isUserLockedError,
 } from './errors/helpers';
+
+export { createClerkGlobalHookError } from './errors/globalHookError';

packages/shared/src/errors/clerkApiError.ts

@@ -14,15 +14,7 @@ export class ClerkAPIError<Meta extends ClerkApiErrorMeta = any> implements Cler
  readonly meta: Meta;
 
  constructor(json: ClerkAPIErrorJSON) {
- const parsedError = this.parseJsonError(json);
- this.code = parsedError.code;
- this.message = parsedError.message;
- this.longMessage = parsedError.longMessage;
- this.meta = parsedError.meta;
- }
-
- private parseJsonError(json: ClerkAPIErrorJSON) {
- return {
+ const parsedError = {
  code: json.code,
  message: json.message,
  longMessage: json.long_message,
@@ -36,6 +28,10 @@ export class ClerkAPIError<Meta extends ClerkApiErrorMeta = any> implements Cler
  isPlanUpgradePossible: json.meta?.is_plan_upgrade_possible,
  } as unknown as Meta,
  };
+ this.code = parsedError.code;
+ this.message = parsedError.message;
+ this.longMessage = parsedError.longMessage;
+ this.meta = parsedError.meta;
  }
 }
 

packages/shared/src/errors/globalHookError.ts

@@ -0,0 +1,23 @@
+import { isClerkApiResponseError } from './clerkApiResponseError';
+import type { ClerkError } from './clerkError';
+import { isClerkRuntimeError } from './clerkRuntimeError';
+
+/**
+ * Creates a ClerkGlobalHookError object from a ClerkError instance.
+ * It's a wrapper for all the different instances of Clerk errors that can
+ * be returned when using Clerk hooks.
+ */
+export function createClerkGlobalHookError(error: ClerkError) {
+ const predicates = {
+ isClerkApiResponseError,
+ isClerkRuntimeError,
+ } as const;
+
+ for (const [name, fn] of Object.entries(predicates)) {
+ Object.assign(error, { [name]: fn });
+ }
+
+ return error as ClerkError & typeof predicates;
+}
+
+export type ClerkGlobalHookError = ReturnType<typeof createClerkGlobalHookError>;

packages/shared/src/types/state.ts

@@ -1,3 +1,4 @@
+import type { ClerkGlobalHookError } from '../errors/globalHookError';
 import type { SignInFutureResource } from './signInFuture';
 import type { SignUpFutureResource } from './signUpFuture';
 
@@ -79,8 +80,9 @@ export interface Errors {
  raw: unknown[] | null;
  /**
  * Parsed errors that are not related to any specific field.
+ * Does not include any errors that could be parsed as a field error
  */
- global: unknown[] | null; // does not include any errors that could be parsed as a field error
+ global: ClerkGlobalHookError[] | null;
 }
 
 /**
@@ -143,6 +145,7 @@ export interface State {
  * An alias for `effect()` from `alien-signals`, which can be used to subscribe to changes from Signals.
  *
  * @see https://github.com/stackblitz/alien-signals#usage
+ *
  * @experimental This experimental API is subject to change.
  */
  __internal_effect: (callback: () => void) => () => void;
@@ -152,6 +155,7 @@ export interface State {
  * its dependencies change.
  *
  * @see https://github.com/stackblitz/alien-signals#usage
+ *
  * @experimental This experimental API is subject to change.
  */
  __internal_computed: <T>(getter: (previousValue?: T) => T) => () => T;

.changeset/moody-parks-scream.md

@@ -0,0 +1,6 @@
+---
+'@clerk/clerk-js': minor
+'@clerk/shared': minor
+---
+
+[Experimental] Add types for errors used in new custom flow APIs

packages/clerk-js/src/core/events.ts

@@ -1,3 +1,4 @@
+import type { ClerkError } from '@clerk/shared/error';
 import { createEventBus } from '@clerk/shared/eventBus';
 import type { TokenResource } from '@clerk/shared/types';
 
@@ -15,7 +16,7 @@ export const events = {
 
 type TokenUpdatePayload = { token: TokenResource | null };
 export type ResourceUpdatePayload = { resource: BaseResource };
-export type ResourceErrorPayload = { resource: BaseResource; error: unknown };
+export type ResourceErrorPayload = { resource: BaseResource; error: ClerkError | null };
 export type ResourceFetchPayload = { resource: BaseResource; status: 'idle' | 'fetching' };
 
 type InternalEvents = {

packages/clerk-js/src/core/signals.ts

@@ -1,4 +1,4 @@
-import { isClerkAPIResponseError } from '@clerk/shared/error';
+import { type ClerkError, createClerkGlobalHookError, isClerkAPIResponseError } from '@clerk/shared/error';
 import type { Errors, SignInSignal, SignUpSignal } from '@clerk/shared/types';
 import { snakeToCamel } from '@clerk/shared/underscore';
 import { computed, signal } from 'alien-signals';
@@ -7,7 +7,7 @@ import type { SignIn } from './resources/SignIn';
 import type { SignUp } from './resources/SignUp';
 
 export const signInResourceSignal = signal<{ resource: SignIn | null }>({ resource: null });
-export const signInErrorSignal = signal<{ error: unknown }>({ error: null });
+export const signInErrorSignal = signal<{ error: ClerkError | null }>({ error: null });
 export const signInFetchSignal = signal<{ status: 'idle' | 'fetching' }>({ status: 'idle' });
 
 export const signInComputedSignal: SignInSignal = computed(() => {
@@ -21,7 +21,7 @@ export const signInComputedSignal: SignInSignal = computed(() => {
 });
 
 export const signUpResourceSignal = signal<{ resource: SignUp | null }>({ resource: null });
-export const signUpErrorSignal = signal<{ error: unknown }>({ error: null });
+export const signUpErrorSignal = signal<{ error: ClerkError | null }>({ error: null });
 export const signUpFetchSignal = signal<{ status: 'idle' | 'fetching' }>({ status: 'idle' });
 
 export const signUpComputedSignal: SignUpSignal = computed(() => {
@@ -38,7 +38,7 @@ export const signUpComputedSignal: SignUpSignal = computed(() => {
  * Converts an error to a parsed errors object that reports the specific fields that the error pertains to. Will put
  * generic non-API errors into the global array.
  */
-function errorsToParsedErrors(error: unknown): Errors {
+function errorsToParsedErrors(error: ClerkError | null): Errors {
  const parsedErrors: Errors = {
  fields: {
  firstName: null,
@@ -62,29 +62,32 @@ function errorsToParsedErrors(error: unknown): Errors {
 
  if (!isClerkAPIResponseError(error)) {
  parsedErrors.raw = [error];
- parsedErrors.global = [error];
+ parsedErrors.global = [createClerkGlobalHookError(error)];
  return parsedErrors;
  }
 
- error.errors.forEach(error => {
- if (parsedErrors.raw) {
- parsedErrors.raw.push(error);
- } else {
- parsedErrors.raw = [error];
- }
-
- if ('meta' in error && error.meta && 'paramName' in error.meta) {
- const name = snakeToCamel(error.meta.paramName);
- parsedErrors.fields[name as keyof typeof parsedErrors.fields] = error;
- return;
- }
-
- if (parsedErrors.global) {
- parsedErrors.global.push(error);
- } else {
- parsedErrors.global = [error];
- }
- });
+ const hasFieldErrors = error.errors.some(error => 'meta' in error && error.meta && 'paramName' in error.meta);
+ if (hasFieldErrors) {
+ error.errors.forEach(error => {
+ if (parsedErrors.raw) {
+ parsedErrors.raw.push(error);
+ } else {
+ parsedErrors.raw = [error];
+ }
+ if ('meta' in error && error.meta && 'paramName' in error.meta) {
+ const name = snakeToCamel(error.meta.paramName);
+ parsedErrors.fields[name as keyof typeof parsedErrors.fields] = error;
+ }
+ // Note that this assumes a given ClerkAPIResponseError will only have either field errors or global errors, but
+ // not both. If a global error is present, it will be discarded.
+ });
+
+ return parsedErrors;
+ }
+
+ // At this point, we know that `error` is a ClerkAPIResponseError and that it has no field errors.
+ parsedErrors.raw = [error];
+ parsedErrors.global = [createClerkGlobalHookError(error)];
 
  return parsedErrors;
 }

packages/clerk-js/src/core/state.ts

@@ -1,3 +1,4 @@
+import type { ClerkError } from '@clerk/shared/error';
 import type { State as StateInterface } from '@clerk/shared/types';
 import { computed, effect } from 'alien-signals';
 
@@ -36,7 +37,7 @@ export class State implements StateInterface {
  eventBus.on('resource:fetch', this.onResourceFetch);
  }
 
- private onResourceError = (payload: { resource: BaseResource; error: unknown }) => {
+ private onResourceError = (payload: { resource: BaseResource; error: ClerkError | null }) => {
  if (payload.resource instanceof SignIn) {
  this.signInErrorSignal({ error: payload.error });
  }

packages/shared/src/error.ts

@@ -2,6 +2,7 @@ export { errorToJSON, parseError, parseErrors } from './errors/parseError';
 
 export { ClerkAPIError } from './errors/clerkApiError';
 export { ClerkAPIResponseError } from './errors/clerkApiResponseError';
+export { ClerkError } from './errors/clerkError';
 
 export { buildErrorThrower, type ErrorThrower, type ErrorThrowerOptions } from './errors/errorThrower';
 
@@ -27,3 +28,5 @@ export {
  isUnauthorizedError,
  isUserLockedError,
 } from './errors/helpers';
+
+export { createClerkGlobalHookError } from './errors/globalHookError';

packages/shared/src/errors/clerkApiError.ts

@@ -14,15 +14,7 @@ export class ClerkAPIError<Meta extends ClerkApiErrorMeta = any> implements Cler
  readonly meta: Meta;
 
  constructor(json: ClerkAPIErrorJSON) {
- const parsedError = this.parseJsonError(json);
- this.code = parsedError.code;
- this.message = parsedError.message;
- this.longMessage = parsedError.longMessage;
- this.meta = parsedError.meta;
- }
-
- private parseJsonError(json: ClerkAPIErrorJSON) {
- return {
+ const parsedError = {
  code: json.code,
  message: json.message,
  longMessage: json.long_message,
@@ -36,6 +28,10 @@ export class ClerkAPIError<Meta extends ClerkApiErrorMeta = any> implements Cler
  isPlanUpgradePossible: json.meta?.is_plan_upgrade_possible,
  } as unknown as Meta,
  };
+ this.code = parsedError.code;
+ this.message = parsedError.message;
+ this.longMessage = parsedError.longMessage;
+ this.meta = parsedError.meta;
  }
 }
 

packages/shared/src/errors/globalHookError.ts

@@ -0,0 +1,23 @@
+import { isClerkApiResponseError } from './clerkApiResponseError';
+import type { ClerkError } from './clerkError';
+import { isClerkRuntimeError } from './clerkRuntimeError';
+
+/**
+ * Creates a ClerkGlobalHookError object from a ClerkError instance.
+ * It's a wrapper for all the different instances of Clerk errors that can
+ * be returned when using Clerk hooks.
+ */
+export function createClerkGlobalHookError(error: ClerkError) {
+ const predicates = {
+ isClerkApiResponseError,
+ isClerkRuntimeError,
+ } as const;
+
+ for (const [name, fn] of Object.entries(predicates)) {
+ Object.assign(error, { [name]: fn });
+ }
+
+ return error as ClerkError & typeof predicates;
+}
+
+export type ClerkGlobalHookError = ReturnType<typeof createClerkGlobalHookError>;

packages/shared/src/types/state.ts

@@ -1,3 +1,4 @@
+import type { ClerkGlobalHookError } from '../errors/globalHookError';
 import type { SignInFutureResource } from './signInFuture';
 import type { SignUpFutureResource } from './signUpFuture';
 
@@ -79,8 +80,9 @@ export interface Errors {
  raw: unknown[] | null;
  /**
  * Parsed errors that are not related to any specific field.
+ * Does not include any errors that could be parsed as a field error
  */
- global: unknown[] | null; // does not include any errors that could be parsed as a field error
+ global: ClerkGlobalHookError[] | null;
 }
 
 /**
@@ -143,6 +145,7 @@ export interface State {
  * An alias for `effect()` from `alien-signals`, which can be used to subscribe to changes from Signals.
  *
  * @see https://github.com/stackblitz/alien-signals#usage
+ *
  * @experimental This experimental API is subject to change.
  */
  __internal_effect: (callback: () => void) => () => void;
@@ -152,6 +155,7 @@ export interface State {
  * its dependencies change.
  *
  * @see https://github.com/stackblitz/alien-signals#usage
+ *
  * @experimental This experimental API is subject to change.
  */
  __internal_computed: <T>(getter: (previousValue?: T) => T) => () => T;

.changeset/moody-parks-scream.md

@@ -0,0 +1,6 @@
+---
+'@clerk/clerk-js': minor
+'@clerk/shared': minor
+---
+
+[Experimental] Add types for errors used in new custom flow APIs

packages/clerk-js/src/core/events.ts

@@ -1,3 +1,4 @@
+import type { ClerkError } from '@clerk/shared/error';
 import { createEventBus } from '@clerk/shared/eventBus';
 import type { TokenResource } from '@clerk/shared/types';
 
@@ -15,7 +16,7 @@ export const events = {
 
 type TokenUpdatePayload = { token: TokenResource | null };
 export type ResourceUpdatePayload = { resource: BaseResource };
-export type ResourceErrorPayload = { resource: BaseResource; error: unknown };
+export type ResourceErrorPayload = { resource: BaseResource; error: ClerkError | null };
 export type ResourceFetchPayload = { resource: BaseResource; status: 'idle' | 'fetching' };
 
 type InternalEvents = {

packages/clerk-js/src/core/signals.ts

@@ -1,4 +1,4 @@
-import { isClerkAPIResponseError } from '@clerk/shared/error';
+import { type ClerkError, createClerkGlobalHookError, isClerkAPIResponseError } from '@clerk/shared/error';
 import type { Errors, SignInSignal, SignUpSignal } from '@clerk/shared/types';
 import { snakeToCamel } from '@clerk/shared/underscore';
 import { computed, signal } from 'alien-signals';
@@ -7,7 +7,7 @@ import type { SignIn } from './resources/SignIn';
 import type { SignUp } from './resources/SignUp';
 
 export const signInResourceSignal = signal<{ resource: SignIn | null }>({ resource: null });
-export const signInErrorSignal = signal<{ error: unknown }>({ error: null });
+export const signInErrorSignal = signal<{ error: ClerkError | null }>({ error: null });
 export const signInFetchSignal = signal<{ status: 'idle' | 'fetching' }>({ status: 'idle' });
 
 export const signInComputedSignal: SignInSignal = computed(() => {
@@ -21,7 +21,7 @@ export const signInComputedSignal: SignInSignal = computed(() => {
 });
 
 export const signUpResourceSignal = signal<{ resource: SignUp | null }>({ resource: null });
-export const signUpErrorSignal = signal<{ error: unknown }>({ error: null });
+export const signUpErrorSignal = signal<{ error: ClerkError | null }>({ error: null });
 export const signUpFetchSignal = signal<{ status: 'idle' | 'fetching' }>({ status: 'idle' });
 
 export const signUpComputedSignal: SignUpSignal = computed(() => {
@@ -38,7 +38,7 @@ export const signUpComputedSignal: SignUpSignal = computed(() => {
  * Converts an error to a parsed errors object that reports the specific fields that the error pertains to. Will put
  * generic non-API errors into the global array.
  */
-function errorsToParsedErrors(error: unknown): Errors {
+function errorsToParsedErrors(error: ClerkError | null): Errors {
  const parsedErrors: Errors = {
  fields: {
  firstName: null,
@@ -62,29 +62,32 @@ function errorsToParsedErrors(error: unknown): Errors {
 
  if (!isClerkAPIResponseError(error)) {
  parsedErrors.raw = [error];
- parsedErrors.global = [error];
+ parsedErrors.global = [createClerkGlobalHookError(error)];
  return parsedErrors;
  }
 
- error.errors.forEach(error => {
- if (parsedErrors.raw) {
- parsedErrors.raw.push(error);
- } else {
- parsedErrors.raw = [error];
- }
-
- if ('meta' in error && error.meta && 'paramName' in error.meta) {
- const name = snakeToCamel(error.meta.paramName);
- parsedErrors.fields[name as keyof typeof parsedErrors.fields] = error;
- return;
- }
-
- if (parsedErrors.global) {
- parsedErrors.global.push(error);
- } else {
- parsedErrors.global = [error];
- }
- });
+ const hasFieldErrors = error.errors.some(error => 'meta' in error && error.meta && 'paramName' in error.meta);
+ if (hasFieldErrors) {
+ error.errors.forEach(error => {
+ if (parsedErrors.raw) {
+ parsedErrors.raw.push(error);
+ } else {
+ parsedErrors.raw = [error];
+ }
+ if ('meta' in error && error.meta && 'paramName' in error.meta) {
+ const name = snakeToCamel(error.meta.paramName);
+ parsedErrors.fields[name as keyof typeof parsedErrors.fields] = error;
+ }
+ // Note that this assumes a given ClerkAPIResponseError will only have either field errors or global errors, but
+ // not both. If a global error is present, it will be discarded.
+ });
+
+ return parsedErrors;
+ }
+
+ // At this point, we know that `error` is a ClerkAPIResponseError and that it has no field errors.
+ parsedErrors.raw = [error];
+ parsedErrors.global = [createClerkGlobalHookError(error)];
 
  return parsedErrors;
 }

packages/clerk-js/src/core/state.ts

@@ -1,3 +1,4 @@
+import type { ClerkError } from '@clerk/shared/error';
 import type { State as StateInterface } from '@clerk/shared/types';
 import { computed, effect } from 'alien-signals';
 
@@ -36,7 +37,7 @@ export class State implements StateInterface {
  eventBus.on('resource:fetch', this.onResourceFetch);
  }
 
- private onResourceError = (payload: { resource: BaseResource; error: unknown }) => {
+ private onResourceError = (payload: { resource: BaseResource; error: ClerkError | null }) => {
  if (payload.resource instanceof SignIn) {
  this.signInErrorSignal({ error: payload.error });
  }

packages/shared/src/error.ts

@@ -2,6 +2,7 @@ export { errorToJSON, parseError, parseErrors } from './errors/parseError';
 
 export { ClerkAPIError } from './errors/clerkApiError';
 export { ClerkAPIResponseError } from './errors/clerkApiResponseError';
+export { ClerkError } from './errors/clerkError';
 
 export { buildErrorThrower, type ErrorThrower, type ErrorThrowerOptions } from './errors/errorThrower';
 
@@ -27,3 +28,5 @@ export {
  isUnauthorizedError,
  isUserLockedError,
 } from './errors/helpers';
+
+export { createClerkGlobalHookError } from './errors/globalHookError';

packages/shared/src/errors/clerkApiError.ts

@@ -14,15 +14,7 @@ export class ClerkAPIError<Meta extends ClerkApiErrorMeta = any> implements Cler
  readonly meta: Meta;
 
  constructor(json: ClerkAPIErrorJSON) {
- const parsedError = this.parseJsonError(json);
- this.code = parsedError.code;
- this.message = parsedError.message;
- this.longMessage = parsedError.longMessage;
- this.meta = parsedError.meta;
- }
-
- private parseJsonError(json: ClerkAPIErrorJSON) {
- return {
+ const parsedError = {
  code: json.code,
  message: json.message,
  longMessage: json.long_message,
@@ -36,6 +28,10 @@ export class ClerkAPIError<Meta extends ClerkApiErrorMeta = any> implements Cler
  isPlanUpgradePossible: json.meta?.is_plan_upgrade_possible,
  } as unknown as Meta,
  };
+ this.code = parsedError.code;
+ this.message = parsedError.message;
+ this.longMessage = parsedError.longMessage;
+ this.meta = parsedError.meta;
  }
 }
 

packages/shared/src/errors/globalHookError.ts

@@ -0,0 +1,23 @@
+import { isClerkApiResponseError } from './clerkApiResponseError';
+import type { ClerkError } from './clerkError';
+import { isClerkRuntimeError } from './clerkRuntimeError';
+
+/**
+ * Creates a ClerkGlobalHookError object from a ClerkError instance.
+ * It's a wrapper for all the different instances of Clerk errors that can
+ * be returned when using Clerk hooks.
+ */
+export function createClerkGlobalHookError(error: ClerkError) {
+ const predicates = {
+ isClerkApiResponseError,
+ isClerkRuntimeError,
+ } as const;
+
+ for (const [name, fn] of Object.entries(predicates)) {
+ Object.assign(error, { [name]: fn });
+ }
+
+ return error as ClerkError & typeof predicates;
+}
+
+export type ClerkGlobalHookError = ReturnType<typeof createClerkGlobalHookError>;

packages/shared/src/types/state.ts

@@ -1,3 +1,4 @@
+import type { ClerkGlobalHookError } from '../errors/globalHookError';
 import type { SignInFutureResource } from './signInFuture';
 import type { SignUpFutureResource } from './signUpFuture';
 
@@ -79,8 +80,9 @@ export interface Errors {
  raw: unknown[] | null;
  /**
  * Parsed errors that are not related to any specific field.
+ * Does not include any errors that could be parsed as a field error
  */
- global: unknown[] | null; // does not include any errors that could be parsed as a field error
+ global: ClerkGlobalHookError[] | null;
 }
 
 /**
@@ -143,6 +145,7 @@ export interface State {
  * An alias for `effect()` from `alien-signals`, which can be used to subscribe to changes from Signals.
  *
  * @see https://github.com/stackblitz/alien-signals#usage
+ *
  * @experimental This experimental API is subject to change.
  */
  __internal_effect: (callback: () => void) => () => void;
@@ -152,6 +155,7 @@ export interface State {
  * its dependencies change.
  *
  * @see https://github.com/stackblitz/alien-signals#usage
+ *
  * @experimental This experimental API is subject to change.
  */
  __internal_computed: <T>(getter: (previousValue?: T) => T) => () => T;

.changeset/moody-parks-scream.md

@@ -0,0 +1,6 @@
+---
+'@clerk/clerk-js': minor
+'@clerk/shared': minor
+---
+
+[Experimental] Add types for errors used in new custom flow APIs

packages/clerk-js/src/core/events.ts

@@ -1,3 +1,4 @@
+import type { ClerkError } from '@clerk/shared/error';
 import { createEventBus } from '@clerk/shared/eventBus';
 import type { TokenResource } from '@clerk/shared/types';
 
@@ -15,7 +16,7 @@ export const events = {
 
 type TokenUpdatePayload = { token: TokenResource | null };
 export type ResourceUpdatePayload = { resource: BaseResource };
-export type ResourceErrorPayload = { resource: BaseResource; error: unknown };
+export type ResourceErrorPayload = { resource: BaseResource; error: ClerkError | null };
 export type ResourceFetchPayload = { resource: BaseResource; status: 'idle' | 'fetching' };
 
 type InternalEvents = {

packages/clerk-js/src/core/signals.ts

@@ -1,4 +1,4 @@
-import { isClerkAPIResponseError } from '@clerk/shared/error';
+import { type ClerkError, createClerkGlobalHookError, isClerkAPIResponseError } from '@clerk/shared/error';
 import type { Errors, SignInSignal, SignUpSignal } from '@clerk/shared/types';
 import { snakeToCamel } from '@clerk/shared/underscore';
 import { computed, signal } from 'alien-signals';
@@ -7,7 +7,7 @@ import type { SignIn } from './resources/SignIn';
 import type { SignUp } from './resources/SignUp';
 
 export const signInResourceSignal = signal<{ resource: SignIn | null }>({ resource: null });
-export const signInErrorSignal = signal<{ error: unknown }>({ error: null });
+export const signInErrorSignal = signal<{ error: ClerkError | null }>({ error: null });
 export const signInFetchSignal = signal<{ status: 'idle' | 'fetching' }>({ status: 'idle' });
 
 export const signInComputedSignal: SignInSignal = computed(() => {
@@ -21,7 +21,7 @@ export const signInComputedSignal: SignInSignal = computed(() => {
 });
 
 export const signUpResourceSignal = signal<{ resource: SignUp | null }>({ resource: null });
-export const signUpErrorSignal = signal<{ error: unknown }>({ error: null });
+export const signUpErrorSignal = signal<{ error: ClerkError | null }>({ error: null });
 export const signUpFetchSignal = signal<{ status: 'idle' | 'fetching' }>({ status: 'idle' });
 
 export const signUpComputedSignal: SignUpSignal = computed(() => {
@@ -38,7 +38,7 @@ export const signUpComputedSignal: SignUpSignal = computed(() => {
  * Converts an error to a parsed errors object that reports the specific fields that the error pertains to. Will put
  * generic non-API errors into the global array.
  */
-function errorsToParsedErrors(error: unknown): Errors {
+function errorsToParsedErrors(error: ClerkError | null): Errors {
  const parsedErrors: Errors = {
  fields: {
  firstName: null,
@@ -62,29 +62,32 @@ function errorsToParsedErrors(error: unknown): Errors {
 
  if (!isClerkAPIResponseError(error)) {
  parsedErrors.raw = [error];
- parsedErrors.global = [error];
+ parsedErrors.global = [createClerkGlobalHookError(error)];
  return parsedErrors;
  }
 
- error.errors.forEach(error => {
- if (parsedErrors.raw) {
- parsedErrors.raw.push(error);
- } else {
- parsedErrors.raw = [error];
- }
-
- if ('meta' in error && error.meta && 'paramName' in error.meta) {
- const name = snakeToCamel(error.meta.paramName);
- parsedErrors.fields[name as keyof typeof parsedErrors.fields] = error;
- return;
- }
-
- if (parsedErrors.global) {
- parsedErrors.global.push(error);
- } else {
- parsedErrors.global = [error];
- }
- });
+ const hasFieldErrors = error.errors.some(error => 'meta' in error && error.meta && 'paramName' in error.meta);
+ if (hasFieldErrors) {
+ error.errors.forEach(error => {
+ if (parsedErrors.raw) {
+ parsedErrors.raw.push(error);
+ } else {
+ parsedErrors.raw = [error];
+ }
+ if ('meta' in error && error.meta && 'paramName' in error.meta) {
+ const name = snakeToCamel(error.meta.paramName);
+ parsedErrors.fields[name as keyof typeof parsedErrors.fields] = error;
+ }
+ // Note that this assumes a given ClerkAPIResponseError will only have either field errors or global errors, but
+ // not both. If a global error is present, it will be discarded.
+ });
+
+ return parsedErrors;
+ }
+
+ // At this point, we know that `error` is a ClerkAPIResponseError and that it has no field errors.
+ parsedErrors.raw = [error];
+ parsedErrors.global = [createClerkGlobalHookError(error)];
 
  return parsedErrors;
 }

packages/clerk-js/src/core/state.ts

@@ -1,3 +1,4 @@
+import type { ClerkError } from '@clerk/shared/error';
 import type { State as StateInterface } from '@clerk/shared/types';
 import { computed, effect } from 'alien-signals';
 
@@ -36,7 +37,7 @@ export class State implements StateInterface {
  eventBus.on('resource:fetch', this.onResourceFetch);
  }
 
- private onResourceError = (payload: { resource: BaseResource; error: unknown }) => {
+ private onResourceError = (payload: { resource: BaseResource; error: ClerkError | null }) => {
  if (payload.resource instanceof SignIn) {
  this.signInErrorSignal({ error: payload.error });
  }

packages/shared/src/error.ts

@@ -2,6 +2,7 @@ export { errorToJSON, parseError, parseErrors } from './errors/parseError';
 
 export { ClerkAPIError } from './errors/clerkApiError';
 export { ClerkAPIResponseError } from './errors/clerkApiResponseError';
+export { ClerkError } from './errors/clerkError';
 
 export { buildErrorThrower, type ErrorThrower, type ErrorThrowerOptions } from './errors/errorThrower';
 
@@ -27,3 +28,5 @@ export {
  isUnauthorizedError,
  isUserLockedError,
 } from './errors/helpers';
+
+export { createClerkGlobalHookError } from './errors/globalHookError';

packages/shared/src/errors/clerkApiError.ts

@@ -14,15 +14,7 @@ export class ClerkAPIError<Meta extends ClerkApiErrorMeta = any> implements Cler
  readonly meta: Meta;
 
  constructor(json: ClerkAPIErrorJSON) {
- const parsedError = this.parseJsonError(json);
- this.code = parsedError.code;
- this.message = parsedError.message;
- this.longMessage = parsedError.longMessage;
- this.meta = parsedError.meta;
- }
-
- private parseJsonError(json: ClerkAPIErrorJSON) {
- return {
+ const parsedError = {
  code: json.code,
  message: json.message,
  longMessage: json.long_message,
@@ -36,6 +28,10 @@ export class ClerkAPIError<Meta extends ClerkApiErrorMeta = any> implements Cler
  isPlanUpgradePossible: json.meta?.is_plan_upgrade_possible,
  } as unknown as Meta,
  };
+ this.code = parsedError.code;
+ this.message = parsedError.message;
+ this.longMessage = parsedError.longMessage;
+ this.meta = parsedError.meta;
  }
 }
 

packages/shared/src/errors/globalHookError.ts

@@ -0,0 +1,23 @@
+import { isClerkApiResponseError } from './clerkApiResponseError';
+import type { ClerkError } from './clerkError';
+import { isClerkRuntimeError } from './clerkRuntimeError';
+
+/**
+ * Creates a ClerkGlobalHookError object from a ClerkError instance.
+ * It's a wrapper for all the different instances of Clerk errors that can
+ * be returned when using Clerk hooks.
+ */
+export function createClerkGlobalHookError(error: ClerkError) {
+ const predicates = {
+ isClerkApiResponseError,
+ isClerkRuntimeError,
+ } as const;
+
+ for (const [name, fn] of Object.entries(predicates)) {
+ Object.assign(error, { [name]: fn });
+ }
+
+ return error as ClerkError & typeof predicates;
+}
+
+export type ClerkGlobalHookError = ReturnType<typeof createClerkGlobalHookError>;

packages/shared/src/types/state.ts

@@ -1,3 +1,4 @@
+import type { ClerkGlobalHookError } from '../errors/globalHookError';
 import type { SignInFutureResource } from './signInFuture';
 import type { SignUpFutureResource } from './signUpFuture';
 
@@ -79,8 +80,9 @@ export interface Errors {
  raw: unknown[] | null;
  /**
  * Parsed errors that are not related to any specific field.
+ * Does not include any errors that could be parsed as a field error
  */
- global: unknown[] | null; // does not include any errors that could be parsed as a field error
+ global: ClerkGlobalHookError[] | null;
 }
 
 /**
@@ -143,6 +145,7 @@ export interface State {
  * An alias for `effect()` from `alien-signals`, which can be used to subscribe to changes from Signals.
  *
  * @see https://github.com/stackblitz/alien-signals#usage
+ *
  * @experimental This experimental API is subject to change.
  */
  __internal_effect: (callback: () => void) => () => void;
@@ -152,6 +155,7 @@ export interface State {
  * its dependencies change.
  *
  * @see https://github.com/stackblitz/alien-signals#usage
+ *
  * @experimental This experimental API is subject to change.
  */
  __internal_computed: <T>(getter: (previousValue?: T) => T) => () => T;

.changeset/moody-parks-scream.md

@@ -0,0 +1,6 @@
+---
+'@clerk/clerk-js': minor
+'@clerk/shared': minor
+---
+
+[Experimental] Add types for errors used in new custom flow APIs

packages/clerk-js/src/core/events.ts

@@ -1,3 +1,4 @@
+import type { ClerkError } from '@clerk/shared/error';
 import { createEventBus } from '@clerk/shared/eventBus';
 import type { TokenResource } from '@clerk/shared/types';
 
@@ -15,7 +16,7 @@ export const events = {
 
 type TokenUpdatePayload = { token: TokenResource | null };
 export type ResourceUpdatePayload = { resource: BaseResource };
-export type ResourceErrorPayload = { resource: BaseResource; error: unknown };
+export type ResourceErrorPayload = { resource: BaseResource; error: ClerkError | null };
 export type ResourceFetchPayload = { resource: BaseResource; status: 'idle' | 'fetching' };
 
 type InternalEvents = {

packages/clerk-js/src/core/signals.ts

@@ -1,4 +1,4 @@
-import { isClerkAPIResponseError } from '@clerk/shared/error';
+import { type ClerkError, createClerkGlobalHookError, isClerkAPIResponseError } from '@clerk/shared/error';
 import type { Errors, SignInSignal, SignUpSignal } from '@clerk/shared/types';
 import { snakeToCamel } from '@clerk/shared/underscore';
 import { computed, signal } from 'alien-signals';
@@ -7,7 +7,7 @@ import type { SignIn } from './resources/SignIn';
 import type { SignUp } from './resources/SignUp';
 
 export const signInResourceSignal = signal<{ resource: SignIn | null }>({ resource: null });
-export const signInErrorSignal = signal<{ error: unknown }>({ error: null });
+export const signInErrorSignal = signal<{ error: ClerkError | null }>({ error: null });
 export const signInFetchSignal = signal<{ status: 'idle' | 'fetching' }>({ status: 'idle' });
 
 export const signInComputedSignal: SignInSignal = computed(() => {
@@ -21,7 +21,7 @@ export const signInComputedSignal: SignInSignal = computed(() => {
 });
 
 export const signUpResourceSignal = signal<{ resource: SignUp | null }>({ resource: null });
-export const signUpErrorSignal = signal<{ error: unknown }>({ error: null });
+export const signUpErrorSignal = signal<{ error: ClerkError | null }>({ error: null });
 export const signUpFetchSignal = signal<{ status: 'idle' | 'fetching' }>({ status: 'idle' });
 
 export const signUpComputedSignal: SignUpSignal = computed(() => {
@@ -38,7 +38,7 @@ export const signUpComputedSignal: SignUpSignal = computed(() => {
  * Converts an error to a parsed errors object that reports the specific fields that the error pertains to. Will put
  * generic non-API errors into the global array.
  */
-function errorsToParsedErrors(error: unknown): Errors {
+function errorsToParsedErrors(error: ClerkError | null): Errors {
  const parsedErrors: Errors = {
  fields: {
  firstName: null,
@@ -62,29 +62,32 @@ function errorsToParsedErrors(error: unknown): Errors {
 
  if (!isClerkAPIResponseError(error)) {
  parsedErrors.raw = [error];
- parsedErrors.global = [error];
+ parsedErrors.global = [createClerkGlobalHookError(error)];
  return parsedErrors;
  }
 
- error.errors.forEach(error => {
- if (parsedErrors.raw) {
- parsedErrors.raw.push(error);
- } else {
- parsedErrors.raw = [error];
- }
-
- if ('meta' in error && error.meta && 'paramName' in error.meta) {
- const name = snakeToCamel(error.meta.paramName);
- parsedErrors.fields[name as keyof typeof parsedErrors.fields] = error;
- return;
- }
-
- if (parsedErrors.global) {
- parsedErrors.global.push(error);
- } else {
- parsedErrors.global = [error];
- }
- });
+ const hasFieldErrors = error.errors.some(error => 'meta' in error && error.meta && 'paramName' in error.meta);
+ if (hasFieldErrors) {
+ error.errors.forEach(error => {
+ if (parsedErrors.raw) {
+ parsedErrors.raw.push(error);
+ } else {
+ parsedErrors.raw = [error];
+ }
+ if ('meta' in error && error.meta && 'paramName' in error.meta) {
+ const name = snakeToCamel(error.meta.paramName);
+ parsedErrors.fields[name as keyof typeof parsedErrors.fields] = error;
+ }
+ // Note that this assumes a given ClerkAPIResponseError will only have either field errors or global errors, but
+ // not both. If a global error is present, it will be discarded.
+ });
+
+ return parsedErrors;
+ }
+
+ // At this point, we know that `error` is a ClerkAPIResponseError and that it has no field errors.
+ parsedErrors.raw = [error];
+ parsedErrors.global = [createClerkGlobalHookError(error)];
 
  return parsedErrors;
 }

packages/clerk-js/src/core/state.ts

@@ -1,3 +1,4 @@
+import type { ClerkError } from '@clerk/shared/error';
 import type { State as StateInterface } from '@clerk/shared/types';
 import { computed, effect } from 'alien-signals';
 
@@ -36,7 +37,7 @@ export class State implements StateInterface {
  eventBus.on('resource:fetch', this.onResourceFetch);
  }
 
- private onResourceError = (payload: { resource: BaseResource; error: unknown }) => {
+ private onResourceError = (payload: { resource: BaseResource; error: ClerkError | null }) => {
  if (payload.resource instanceof SignIn) {
  this.signInErrorSignal({ error: payload.error });
  }

packages/shared/src/error.ts

@@ -2,6 +2,7 @@ export { errorToJSON, parseError, parseErrors } from './errors/parseError';
 
 export { ClerkAPIError } from './errors/clerkApiError';
 export { ClerkAPIResponseError } from './errors/clerkApiResponseError';
+export { ClerkError } from './errors/clerkError';
 
 export { buildErrorThrower, type ErrorThrower, type ErrorThrowerOptions } from './errors/errorThrower';
 
@@ -27,3 +28,5 @@ export {
  isUnauthorizedError,
  isUserLockedError,
 } from './errors/helpers';
+
+export { createClerkGlobalHookError } from './errors/globalHookError';

packages/shared/src/errors/clerkApiError.ts

@@ -14,15 +14,7 @@ export class ClerkAPIError<Meta extends ClerkApiErrorMeta = any> implements Cler
  readonly meta: Meta;
 
  constructor(json: ClerkAPIErrorJSON) {
- const parsedError = this.parseJsonError(json);
- this.code = parsedError.code;
- this.message = parsedError.message;
- this.longMessage = parsedError.longMessage;
- this.meta = parsedError.meta;
- }
-
- private parseJsonError(json: ClerkAPIErrorJSON) {
- return {
+ const parsedError = {
  code: json.code,
  message: json.message,
  longMessage: json.long_message,
@@ -36,6 +28,10 @@ export class ClerkAPIError<Meta extends ClerkApiErrorMeta = any> implements Cler
  isPlanUpgradePossible: json.meta?.is_plan_upgrade_possible,
  } as unknown as Meta,
  };
+ this.code = parsedError.code;
+ this.message = parsedError.message;
+ this.longMessage = parsedError.longMessage;
+ this.meta = parsedError.meta;
  }
 }
 

packages/shared/src/errors/globalHookError.ts

@@ -0,0 +1,23 @@
+import { isClerkApiResponseError } from './clerkApiResponseError';
+import type { ClerkError } from './clerkError';
+import { isClerkRuntimeError } from './clerkRuntimeError';
+
+/**
+ * Creates a ClerkGlobalHookError object from a ClerkError instance.
+ * It's a wrapper for all the different instances of Clerk errors that can
+ * be returned when using Clerk hooks.
+ */
+export function createClerkGlobalHookError(error: ClerkError) {
+ const predicates = {
+ isClerkApiResponseError,
+ isClerkRuntimeError,
+ } as const;
+
+ for (const [name, fn] of Object.entries(predicates)) {
+ Object.assign(error, { [name]: fn });
+ }
+
+ return error as ClerkError & typeof predicates;
+}
+
+export type ClerkGlobalHookError = ReturnType<typeof createClerkGlobalHookError>;

packages/shared/src/types/state.ts

@@ -1,3 +1,4 @@
+import type { ClerkGlobalHookError } from '../errors/globalHookError';
 import type { SignInFutureResource } from './signInFuture';
 import type { SignUpFutureResource } from './signUpFuture';
 
@@ -79,8 +80,9 @@ export interface Errors {
  raw: unknown[] | null;
  /**
  * Parsed errors that are not related to any specific field.
+ * Does not include any errors that could be parsed as a field error
  */
- global: unknown[] | null; // does not include any errors that could be parsed as a field error
+ global: ClerkGlobalHookError[] | null;
 }
 
 /**
@@ -143,6 +145,7 @@ export interface State {
  * An alias for `effect()` from `alien-signals`, which can be used to subscribe to changes from Signals.
  *
  * @see https://github.com/stackblitz/alien-signals#usage
+ *
  * @experimental This experimental API is subject to change.
  */
  __internal_effect: (callback: () => void) => () => void;
@@ -152,6 +155,7 @@ export interface State {
  * its dependencies change.
  *
  * @see https://github.com/stackblitz/alien-signals#usage
+ *
  * @experimental This experimental API is subject to change.
  */
  __internal_computed: <T>(getter: (previousValue?: T) => T) => () => T;

.changeset/moody-parks-scream.md

@@ -0,0 +1,6 @@
+---
+'@clerk/clerk-js': minor
+'@clerk/shared': minor
+---
+
+[Experimental] Add types for errors used in new custom flow APIs

packages/clerk-js/src/core/events.ts

@@ -1,3 +1,4 @@
+import type { ClerkError } from '@clerk/shared/error';
 import { createEventBus } from '@clerk/shared/eventBus';
 import type { TokenResource } from '@clerk/shared/types';
 
@@ -15,7 +16,7 @@ export const events = {
 
 type TokenUpdatePayload = { token: TokenResource | null };
 export type ResourceUpdatePayload = { resource: BaseResource };
-export type ResourceErrorPayload = { resource: BaseResource; error: unknown };
+export type ResourceErrorPayload = { resource: BaseResource; error: ClerkError | null };
 export type ResourceFetchPayload = { resource: BaseResource; status: 'idle' | 'fetching' };
 
 type InternalEvents = {

packages/clerk-js/src/core/signals.ts

@@ -1,4 +1,4 @@
-import { isClerkAPIResponseError } from '@clerk/shared/error';
+import { type ClerkError, createClerkGlobalHookError, isClerkAPIResponseError } from '@clerk/shared/error';
 import type { Errors, SignInSignal, SignUpSignal } from '@clerk/shared/types';
 import { snakeToCamel } from '@clerk/shared/underscore';
 import { computed, signal } from 'alien-signals';
@@ -7,7 +7,7 @@ import type { SignIn } from './resources/SignIn';
 import type { SignUp } from './resources/SignUp';
 
 export const signInResourceSignal = signal<{ resource: SignIn | null }>({ resource: null });
-export const signInErrorSignal = signal<{ error: unknown }>({ error: null });
+export const signInErrorSignal = signal<{ error: ClerkError | null }>({ error: null });
 export const signInFetchSignal = signal<{ status: 'idle' | 'fetching' }>({ status: 'idle' });
 
 export const signInComputedSignal: SignInSignal = computed(() => {
@@ -21,7 +21,7 @@ export const signInComputedSignal: SignInSignal = computed(() => {
 });
 
 export const signUpResourceSignal = signal<{ resource: SignUp | null }>({ resource: null });
-export const signUpErrorSignal = signal<{ error: unknown }>({ error: null });
+export const signUpErrorSignal = signal<{ error: ClerkError | null }>({ error: null });
 export const signUpFetchSignal = signal<{ status: 'idle' | 'fetching' }>({ status: 'idle' });
 
 export const signUpComputedSignal: SignUpSignal = computed(() => {
@@ -38,7 +38,7 @@ export const signUpComputedSignal: SignUpSignal = computed(() => {
  * Converts an error to a parsed errors object that reports the specific fields that the error pertains to. Will put
  * generic non-API errors into the global array.
  */
-function errorsToParsedErrors(error: unknown): Errors {
+function errorsToParsedErrors(error: ClerkError | null): Errors {
  const parsedErrors: Errors = {
  fields: {
  firstName: null,
@@ -62,29 +62,32 @@ function errorsToParsedErrors(error: unknown): Errors {
 
  if (!isClerkAPIResponseError(error)) {
  parsedErrors.raw = [error];
- parsedErrors.global = [error];
+ parsedErrors.global = [createClerkGlobalHookError(error)];
  return parsedErrors;
  }
 
- error.errors.forEach(error => {
- if (parsedErrors.raw) {
- parsedErrors.raw.push(error);
- } else {
- parsedErrors.raw = [error];
- }
-
- if ('meta' in error && error.meta && 'paramName' in error.meta) {
- const name = snakeToCamel(error.meta.paramName);
- parsedErrors.fields[name as keyof typeof parsedErrors.fields] = error;
- return;
- }
-
- if (parsedErrors.global) {
- parsedErrors.global.push(error);
- } else {
- parsedErrors.global = [error];
- }
- });
+ const hasFieldErrors = error.errors.some(error => 'meta' in error && error.meta && 'paramName' in error.meta);
+ if (hasFieldErrors) {
+ error.errors.forEach(error => {
+ if (parsedErrors.raw) {
+ parsedErrors.raw.push(error);
+ } else {
+ parsedErrors.raw = [error];
+ }
+ if ('meta' in error && error.meta && 'paramName' in error.meta) {
+ const name = snakeToCamel(error.meta.paramName);
+ parsedErrors.fields[name as keyof typeof parsedErrors.fields] = error;
+ }
+ // Note that this assumes a given ClerkAPIResponseError will only have either field errors or global errors, but
+ // not both. If a global error is present, it will be discarded.
+ });
+
+ return parsedErrors;
+ }
+
+ // At this point, we know that `error` is a ClerkAPIResponseError and that it has no field errors.
+ parsedErrors.raw = [error];
+ parsedErrors.global = [createClerkGlobalHookError(error)];
 
  return parsedErrors;
 }

packages/clerk-js/src/core/state.ts

@@ -1,3 +1,4 @@
+import type { ClerkError } from '@clerk/shared/error';
 import type { State as StateInterface } from '@clerk/shared/types';
 import { computed, effect } from 'alien-signals';
 
@@ -36,7 +37,7 @@ export class State implements StateInterface {
  eventBus.on('resource:fetch', this.onResourceFetch);
  }
 
- private onResourceError = (payload: { resource: BaseResource; error: unknown }) => {
+ private onResourceError = (payload: { resource: BaseResource; error: ClerkError | null }) => {
  if (payload.resource instanceof SignIn) {
  this.signInErrorSignal({ error: payload.error });
  }

packages/shared/src/error.ts

@@ -2,6 +2,7 @@ export { errorToJSON, parseError, parseErrors } from './errors/parseError';
 
 export { ClerkAPIError } from './errors/clerkApiError';
 export { ClerkAPIResponseError } from './errors/clerkApiResponseError';
+export { ClerkError } from './errors/clerkError';
 
 export { buildErrorThrower, type ErrorThrower, type ErrorThrowerOptions } from './errors/errorThrower';
 
@@ -27,3 +28,5 @@ export {
  isUnauthorizedError,
  isUserLockedError,
 } from './errors/helpers';
+
+export { createClerkGlobalHookError } from './errors/globalHookError';

packages/shared/src/errors/clerkApiError.ts

@@ -14,15 +14,7 @@ export class ClerkAPIError<Meta extends ClerkApiErrorMeta = any> implements Cler
  readonly meta: Meta;
 
  constructor(json: ClerkAPIErrorJSON) {
- const parsedError = this.parseJsonError(json);
- this.code = parsedError.code;
- this.message = parsedError.message;
- this.longMessage = parsedError.longMessage;
- this.meta = parsedError.meta;
- }
-
- private parseJsonError(json: ClerkAPIErrorJSON) {
- return {
+ const parsedError = {
  code: json.code,
  message: json.message,
  longMessage: json.long_message,
@@ -36,6 +28,10 @@ export class ClerkAPIError<Meta extends ClerkApiErrorMeta = any> implements Cler
  isPlanUpgradePossible: json.meta?.is_plan_upgrade_possible,
  } as unknown as Meta,
  };
+ this.code = parsedError.code;
+ this.message = parsedError.message;
+ this.longMessage = parsedError.longMessage;
+ this.meta = parsedError.meta;
  }
 }
 

packages/shared/src/errors/globalHookError.ts

@@ -0,0 +1,23 @@
+import { isClerkApiResponseError } from './clerkApiResponseError';
+import type { ClerkError } from './clerkError';
+import { isClerkRuntimeError } from './clerkRuntimeError';
+
+/**
+ * Creates a ClerkGlobalHookError object from a ClerkError instance.
+ * It's a wrapper for all the different instances of Clerk errors that can
+ * be returned when using Clerk hooks.
+ */
+export function createClerkGlobalHookError(error: ClerkError) {
+ const predicates = {
+ isClerkApiResponseError,
+ isClerkRuntimeError,
+ } as const;
+
+ for (const [name, fn] of Object.entries(predicates)) {
+ Object.assign(error, { [name]: fn });
+ }
+
+ return error as ClerkError & typeof predicates;
+}
+
+export type ClerkGlobalHookError = ReturnType<typeof createClerkGlobalHookError>;

packages/shared/src/types/state.ts

@@ -1,3 +1,4 @@
+import type { ClerkGlobalHookError } from '../errors/globalHookError';
 import type { SignInFutureResource } from './signInFuture';
 import type { SignUpFutureResource } from './signUpFuture';
 
@@ -79,8 +80,9 @@ export interface Errors {
  raw: unknown[] | null;
  /**
  * Parsed errors that are not related to any specific field.
+ * Does not include any errors that could be parsed as a field error
  */
- global: unknown[] | null; // does not include any errors that could be parsed as a field error
+ global: ClerkGlobalHookError[] | null;
 }
 
 /**
@@ -143,6 +145,7 @@ export interface State {
  * An alias for `effect()` from `alien-signals`, which can be used to subscribe to changes from Signals.
  *
  * @see https://github.com/stackblitz/alien-signals#usage
+ *
  * @experimental This experimental API is subject to change.
  */
  __internal_effect: (callback: () => void) => () => void;
@@ -152,6 +155,7 @@ export interface State {
  * its dependencies change.
  *
  * @see https://github.com/stackblitz/alien-signals#usage
+ *
  * @experimental This experimental API is subject to change.
  */
  __internal_computed: <T>(getter: (previousValue?: T) => T) => () => T;

.changeset/moody-parks-scream.md

@@ -0,0 +1,6 @@
+---
+'@clerk/clerk-js': minor
+'@clerk/shared': minor
+---
+
+[Experimental] Add types for errors used in new custom flow APIs

packages/clerk-js/src/core/events.ts

@@ -1,3 +1,4 @@
+import type { ClerkError } from '@clerk/shared/error';
 import { createEventBus } from '@clerk/shared/eventBus';
 import type { TokenResource } from '@clerk/shared/types';
 
@@ -15,7 +16,7 @@ export const events = {
 
 type TokenUpdatePayload = { token: TokenResource | null };
 export type ResourceUpdatePayload = { resource: BaseResource };
-export type ResourceErrorPayload = { resource: BaseResource; error: unknown };
+export type ResourceErrorPayload = { resource: BaseResource; error: ClerkError | null };
 export type ResourceFetchPayload = { resource: BaseResource; status: 'idle' | 'fetching' };
 
 type InternalEvents = {

packages/clerk-js/src/core/signals.ts

@@ -1,4 +1,4 @@
-import { isClerkAPIResponseError } from '@clerk/shared/error';
+import { type ClerkError, createClerkGlobalHookError, isClerkAPIResponseError } from '@clerk/shared/error';
 import type { Errors, SignInSignal, SignUpSignal } from '@clerk/shared/types';
 import { snakeToCamel } from '@clerk/shared/underscore';
 import { computed, signal } from 'alien-signals';
@@ -7,7 +7,7 @@ import type { SignIn } from './resources/SignIn';
 import type { SignUp } from './resources/SignUp';
 
 export const signInResourceSignal = signal<{ resource: SignIn | null }>({ resource: null });
-export const signInErrorSignal = signal<{ error: unknown }>({ error: null });
+export const signInErrorSignal = signal<{ error: ClerkError | null }>({ error: null });
 export const signInFetchSignal = signal<{ status: 'idle' | 'fetching' }>({ status: 'idle' });
 
 export const signInComputedSignal: SignInSignal = computed(() => {
@@ -21,7 +21,7 @@ export const signInComputedSignal: SignInSignal = computed(() => {
 });
 
 export const signUpResourceSignal = signal<{ resource: SignUp | null }>({ resource: null });
-export const signUpErrorSignal = signal<{ error: unknown }>({ error: null });
+export const signUpErrorSignal = signal<{ error: ClerkError | null }>({ error: null });
 export const signUpFetchSignal = signal<{ status: 'idle' | 'fetching' }>({ status: 'idle' });
 
 export const signUpComputedSignal: SignUpSignal = computed(() => {
@@ -38,7 +38,7 @@ export const signUpComputedSignal: SignUpSignal = computed(() => {
  * Converts an error to a parsed errors object that reports the specific fields that the error pertains to. Will put
  * generic non-API errors into the global array.
  */
-function errorsToParsedErrors(error: unknown): Errors {
+function errorsToParsedErrors(error: ClerkError | null): Errors {
  const parsedErrors: Errors = {
  fields: {
  firstName: null,
@@ -62,29 +62,32 @@ function errorsToParsedErrors(error: unknown): Errors {
 
  if (!isClerkAPIResponseError(error)) {
  parsedErrors.raw = [error];
- parsedErrors.global = [error];
+ parsedErrors.global = [createClerkGlobalHookError(error)];
  return parsedErrors;
  }
 
- error.errors.forEach(error => {
- if (parsedErrors.raw) {
- parsedErrors.raw.push(error);
- } else {
- parsedErrors.raw = [error];
- }
-
- if ('meta' in error && error.meta && 'paramName' in error.meta) {
- const name = snakeToCamel(error.meta.paramName);
- parsedErrors.fields[name as keyof typeof parsedErrors.fields] = error;
- return;
- }
-
- if (parsedErrors.global) {
- parsedErrors.global.push(error);
- } else {
- parsedErrors.global = [error];
- }
- });
+ const hasFieldErrors = error.errors.some(error => 'meta' in error && error.meta && 'paramName' in error.meta);
+ if (hasFieldErrors) {
+ error.errors.forEach(error => {
+ if (parsedErrors.raw) {
+ parsedErrors.raw.push(error);
+ } else {
+ parsedErrors.raw = [error];
+ }
+ if ('meta' in error && error.meta && 'paramName' in error.meta) {
+ const name = snakeToCamel(error.meta.paramName);
+ parsedErrors.fields[name as keyof typeof parsedErrors.fields] = error;
+ }
+ // Note that this assumes a given ClerkAPIResponseError will only have either field errors or global errors, but
+ // not both. If a global error is present, it will be discarded.
+ });
+
+ return parsedErrors;
+ }
+
+ // At this point, we know that `error` is a ClerkAPIResponseError and that it has no field errors.
+ parsedErrors.raw = [error];
+ parsedErrors.global = [createClerkGlobalHookError(error)];
 
  return parsedErrors;
 }

packages/clerk-js/src/core/state.ts

@@ -1,3 +1,4 @@
+import type { ClerkError } from '@clerk/shared/error';
 import type { State as StateInterface } from '@clerk/shared/types';
 import { computed, effect } from 'alien-signals';
 
@@ -36,7 +37,7 @@ export class State implements StateInterface {
  eventBus.on('resource:fetch', this.onResourceFetch);
  }
 
- private onResourceError = (payload: { resource: BaseResource; error: unknown }) => {
+ private onResourceError = (payload: { resource: BaseResource; error: ClerkError | null }) => {
  if (payload.resource instanceof SignIn) {
  this.signInErrorSignal({ error: payload.error });
  }

packages/shared/src/error.ts

@@ -2,6 +2,7 @@ export { errorToJSON, parseError, parseErrors } from './errors/parseError';
 
 export { ClerkAPIError } from './errors/clerkApiError';
 export { ClerkAPIResponseError } from './errors/clerkApiResponseError';
+export { ClerkError } from './errors/clerkError';
 
 export { buildErrorThrower, type ErrorThrower, type ErrorThrowerOptions } from './errors/errorThrower';
 
@@ -27,3 +28,5 @@ export {
  isUnauthorizedError,
  isUserLockedError,
 } from './errors/helpers';
+
+export { createClerkGlobalHookError } from './errors/globalHookError';

packages/shared/src/errors/clerkApiError.ts

@@ -14,15 +14,7 @@ export class ClerkAPIError<Meta extends ClerkApiErrorMeta = any> implements Cler
  readonly meta: Meta;
 
  constructor(json: ClerkAPIErrorJSON) {
- const parsedError = this.parseJsonError(json);
- this.code = parsedError.code;
- this.message = parsedError.message;
- this.longMessage = parsedError.longMessage;
- this.meta = parsedError.meta;
- }
-
- private parseJsonError(json: ClerkAPIErrorJSON) {
- return {
+ const parsedError = {
  code: json.code,
  message: json.message,
  longMessage: json.long_message,
@@ -36,6 +28,10 @@ export class ClerkAPIError<Meta extends ClerkApiErrorMeta = any> implements Cler
  isPlanUpgradePossible: json.meta?.is_plan_upgrade_possible,
  } as unknown as Meta,
  };
+ this.code = parsedError.code;
+ this.message = parsedError.message;
+ this.longMessage = parsedError.longMessage;
+ this.meta = parsedError.meta;
  }
 }
 

packages/shared/src/errors/globalHookError.ts

@@ -0,0 +1,23 @@
+import { isClerkApiResponseError } from './clerkApiResponseError';
+import type { ClerkError } from './clerkError';
+import { isClerkRuntimeError } from './clerkRuntimeError';
+
+/**
+ * Creates a ClerkGlobalHookError object from a ClerkError instance.
+ * It's a wrapper for all the different instances of Clerk errors that can
+ * be returned when using Clerk hooks.
+ */
+export function createClerkGlobalHookError(error: ClerkError) {
+ const predicates = {
+ isClerkApiResponseError,
+ isClerkRuntimeError,
+ } as const;
+
+ for (const [name, fn] of Object.entries(predicates)) {
+ Object.assign(error, { [name]: fn });
+ }
+
+ return error as ClerkError & typeof predicates;
+}
+
+export type ClerkGlobalHookError = ReturnType<typeof createClerkGlobalHookError>;

packages/shared/src/types/state.ts

@@ -1,3 +1,4 @@
+import type { ClerkGlobalHookError } from '../errors/globalHookError';
 import type { SignInFutureResource } from './signInFuture';
 import type { SignUpFutureResource } from './signUpFuture';
 
@@ -79,8 +80,9 @@ export interface Errors {
  raw: unknown[] | null;
  /**
  * Parsed errors that are not related to any specific field.
+ * Does not include any errors that could be parsed as a field error
  */
- global: unknown[] | null; // does not include any errors that could be parsed as a field error
+ global: ClerkGlobalHookError[] | null;
 }
 
 /**
@@ -143,6 +145,7 @@ export interface State {
  * An alias for `effect()` from `alien-signals`, which can be used to subscribe to changes from Signals.
  *
  * @see https://github.com/stackblitz/alien-signals#usage
+ *
  * @experimental This experimental API is subject to change.
  */
  __internal_effect: (callback: () => void) => () => void;
@@ -152,6 +155,7 @@ export interface State {
  * its dependencies change.
  *
  * @see https://github.com/stackblitz/alien-signals#usage
+ *
  * @experimental This experimental API is subject to change.
  */
  __internal_computed: <T>(getter: (previousValue?: T) => T) => () => T;