feat(shared): Introduce base ClerkError and type guard helpers

.changeset/refactor-error-handling-system.md

@@ -0,0 +1,13 @@
+---
+'@clerk/shared': minor
+---
+
+Internal refactor of error handling to improve type safety and error classification.
+
+- Introduce new `ClerkError` base class for all Clerk errors
+- Rename internal error files: `apiResponseError.ts` → `clerkApiResponseError.ts`, `runtimeError.ts` → `clerkRuntimeError.ts`
+- Add `ClerkAPIError` class for individual API errors with improved type safety
+- Add type guard utilities (`isClerkError`, `isClerkRuntimeError`, `isClerkApiResponseError`) for better error handling
+- Deprecate `clerkRuntimeError` property in favor of `clerkError` for consistency
+- Add support for error codes, long messages, and documentation URLs
+

.typedoc/__tests__/__snapshots__/file-structure.test.ts.snap

@@ -147,6 +147,7 @@ exports[`Typedoc output > should have a deliberate file structure 1`] = `
   "shared/build-clerk-js-script-attributes.mdx",
   "shared/build-publishable-key.mdx",
   "shared/camel-to-snake.mdx",
+  "shared/clerk-api-error.mdx",
   "shared/clerk-js-script-url.mdx",
   "shared/clerk-runtime-error.mdx",
   "shared/create-dev-or-staging-url-cache.mdx",

.typedoc/__tests__/file-structure.test.ts

@@ -40,11 +40,7 @@ describe('Typedoc output', () => {
       ]
     `);
   });
-  it('should have a deliberate file structure', async () => {
-    const files = await scanDirectory('file');
 
-    expect(files).toMatchSnapshot();
-  });
   it('should only contain lowercase files', async () => {
     const files = await scanDirectory('file');
     const upperCaseFiles = files.filter(file => /[A-Z]/.test(file));

packages/clerk-js/src/core/resources/Verification.ts

@@ -1,6 +1,5 @@
-import { errorToJSON, parseError } from '@clerk/shared/error';
+import { ClerkAPIError, errorToJSON } from '@clerk/shared/error';
 import type {
-  ClerkAPIError,
   PasskeyVerificationResource,
   PhoneCodeChannel,
   PublicKeyCredentialCreationOptionsJSON,
@@ -58,7 +57,7 @@ export class Verification extends BaseResource implements VerificationResource {
       }
       this.attempts = data.attempts;
       this.expireAt = unixEpochToDate(data.expire_at || undefined);
-      this.error = data.error ? parseError(data.error) : null;
+      this.error = data.error ? new ClerkAPIError(data.error) : null;
       this.channel = data.channel || undefined;
     }
     return this;

packages/clerk-js/src/ui/components/SignUp/__tests__/SignUpContinue.test.tsx

@@ -1,7 +1,6 @@
 import { ClerkAPIResponseError } from '@clerk/shared/error';
 import { OAUTH_PROVIDERS } from '@clerk/shared/oauth';
 import { waitFor } from '@testing-library/react';
-import React from 'react';
 import { describe, expect, it } from 'vitest';
 
 import { bindCreateFixtures } from '@/test/create-fixtures';

packages/shared/src/__tests__/error.test.ts

@@ -39,23 +39,21 @@ describe('ClerkRuntimeError', () => {
   it('throws the correct error message', () => {
     expect(() => {
       throw clerkRuntimeError;
-    }).toThrow(/^🔒 Clerk: test\n\n\(code="test_code"\)/);
+    }).toThrow(/^Clerk: test\n\n\(code="test_code"\)/);
   });
 
   it('throws the correct error message without duplicate prefixes', () => {
     expect(() => {
-      throw new ClerkRuntimeError('🔒 Clerk: test', { code: 'test_code' });
-    }).toThrow(/^🔒 Clerk: test\n\n\(code="test_code"\)/);
+      throw new ClerkRuntimeError('Clerk: test', { code: 'test_code' });
+    }).toThrow(/^Clerk: test\n\n\(code="test_code"\)/);
   });
 
   it('properties are populated correctly', () => {
     expect(clerkRuntimeError.name).toEqual('ClerkRuntimeError');
     expect(clerkRuntimeError.code).toEqual('test_code');
-    expect(clerkRuntimeError.message).toMatch(/🔒 Clerk: test\n\n\(code="test_code"\)/);
+    expect(clerkRuntimeError.message).toMatch(/Clerk: test\n\n\(code="test_code"\)/);
     expect(clerkRuntimeError.clerkRuntimeError).toBe(true);
-    expect(clerkRuntimeError.toString()).toMatch(
-      /^\[ClerkRuntimeError\]\nMessage:🔒 Clerk: test\n\n\(code="test_code"\)/,
-    );
+    expect(clerkRuntimeError.toString()).toMatch(/^\[ClerkRuntimeError\]\nMessage:Clerk: test\n\n\(code="test_code"\)/);
   });
 
   it('helper recognises error', () => {

packages/shared/src/error.ts

@@ -1,14 +1,15 @@
 export { errorToJSON, parseError, parseErrors } from './errors/parseError';
 
-export { ClerkAPIResponseError } from './errors/apiResponseError';
+export { ClerkAPIError } from './errors/clerkApiError';
+export { ClerkAPIResponseError } from './errors/clerkApiResponseError';
 
 export { buildErrorThrower, type ErrorThrower, type ErrorThrowerOptions } from './errors/errorThrower';
 
 export { EmailLinkError, EmailLinkErrorCode, EmailLinkErrorCodeStatus } from './errors/emailLinkError';
 
 export type { MetamaskError } from './errors/metamaskError';
 
-export { ClerkRuntimeError } from './errors/runtimeError';
+export { ClerkRuntimeError } from './errors/clerkRuntimeError';
 
 export { ClerkWebAuthnError } from './errors/webAuthNError';
 

packages/shared/src/errors/clerkApiError.ts

@@ -0,0 +1,46 @@
+import type { ClerkAPIError as ClerkAPIErrorInterface, ClerkAPIErrorJSON } from '@clerk/types';
+
+import { createErrorTypeGuard } from './createErrorTypeGuard';
+
+export type ClerkApiErrorMeta = Record<string, unknown>;
+
+/**
+ * This error contains the specific error message, code, and any additional metadata that was returned by the Clerk API.
+ */
+export class ClerkAPIError<Meta extends ClerkApiErrorMeta = any> implements ClerkAPIErrorInterface {
+  readonly name = 'ClerkApiError';
+  readonly code: string;
+  readonly message: string;
+  readonly longMessage: string | undefined;
+  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 {
+      code: json.code,
+      message: json.message,
+      longMessage: json.long_message,
+      meta: {
+        paramName: json.meta?.param_name,
+        sessionId: json.meta?.session_id,
+        emailAddresses: json.meta?.email_addresses,
+        identifiers: json.meta?.identifiers,
+        zxcvbn: json.meta?.zxcvbn,
+        plan: json.meta?.plan,
+        isPlanUpgradePossible: json.meta?.is_plan_upgrade_possible,
+      } as unknown as Meta,
+    };
+  }
+}
+
+/**
+ * Type guard to check if a value is a ClerkApiError instance.
+ */
+export const isClerkApiError = createErrorTypeGuard(ClerkAPIError);

packages/shared/src/errors/clerkApiResponseError.ts

@@ -0,0 +1,61 @@
+import type { ClerkAPIErrorJSON, ClerkAPIResponseError as ClerkAPIResponseErrorInterface } from '@clerk/types';
+
+import { ClerkAPIError } from './clerkApiError';
+import type { ClerkErrorParams } from './clerkError';
+import { ClerkError } from './clerkError';
+import { createErrorTypeGuard } from './createErrorTypeGuard';
+
+interface ClerkAPIResponseOptions extends Omit<ClerkErrorParams, 'message' | 'code'> {
+  data: ClerkAPIErrorJSON[];
+  status: number;
+  clerkTraceId?: string;
+  retryAfter?: number;
+}
+
+export class ClerkAPIResponseError extends ClerkError implements ClerkAPIResponseErrorInterface {
+  static name = 'ClerkAPIResponseError';
+  status: number;
+  clerkTraceId?: string;
+  retryAfter?: number;
+  errors: ClerkAPIError[];
+
+  constructor(message: string, options: ClerkAPIResponseOptions) {
+    const { data: errorsJson, status, clerkTraceId, retryAfter } = options;
+    super({ ...options, message, code: 'api_response_error' });
+    Object.setPrototypeOf(this, ClerkAPIResponseError.prototype);
+    this.status = status;
+    this.clerkTraceId = clerkTraceId;
+    this.retryAfter = retryAfter;
+    this.errors = (errorsJson || []).map(e => new ClerkAPIError(e));
+  }
+
+  public toString() {
+    let message = `[${this.name}]\nMessage:${this.message}\nStatus:${this.status}\nSerialized errors: ${this.errors.map(
+      e => JSON.stringify(e),
+    )}`;
+
+    if (this.clerkTraceId) {
+      message += `\nClerk Trace ID: ${this.clerkTraceId}`;
+    }
+
+    return message;
+  }
+
+  // Override formatMessage to keep it unformatted for backward compatibility
+  protected static override formatMessage(name: string, msg: string, _: string, __: string | undefined) {
+    return msg;
+  }
+}
+
+/**
+ * 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)) { ... }
+ *
+ * // As a method (when attached to error object)
+ * if (error.isClerkApiResponseError()) { ... }
+ */
+export const isClerkApiResponseError = createErrorTypeGuard(ClerkAPIResponseError);

packages/shared/src/errors/clerkError.ts

@@ -0,0 +1,83 @@
+import { createErrorTypeGuard } from './createErrorTypeGuard';
+
+export interface ClerkErrorParams {
+  /**
+   * A message that describes the error. This is typically intented to be showed to the developers.
+   * It should not be shown to the user or parsed directly as the message contents are not guaranteed
+   * to be stable - use the `code` property instead.
+   */
+  message: string;
+  /**
+   * A machine-stable code that identifies the error.
+   */
+  code: string;
+  /**
+   * A user-friendly message that describes the error and can be displayed to the user.
+   * This message defaults to English but can be usually translated to the user's language
+   * by matching the `code` property to a localized message.
+   */
+  longMessage?: string;
+  /**
+   * The cause of the error, typically an `Error` instance that was caught and wrapped by the Clerk error handler.
+   */
+  cause?: Error;
+  /**
+   * A URL to the documentation for the error.
+   */
+  docsUrl?: string;
+}
+
+/**
+ * A temporary placeholder, this will eventually be replaced with a
+ * build-time flag that will actually perform DCE.
+ */
+const __DEV__ = true;
+
+export class ClerkError extends Error {
+  static name = 'ClerkError';
+  readonly clerkError = true as const;
+  readonly code: string;
+  readonly longMessage: string | undefined;
+  readonly docsUrl: string | undefined;
+  readonly cause: Error | undefined;
+
+  get name() {
+    return this.constructor.name;
+  }
+
+  constructor(opts: ClerkErrorParams) {
+    super(new.target.formatMessage(new.target.name, opts.message, opts.code, opts.docsUrl), { cause: opts.cause });
+    Object.setPrototypeOf(this, ClerkError.prototype);
+    this.code = opts.code;
+    this.docsUrl = opts.docsUrl;
+    this.longMessage = opts.longMessage;
+    this.cause = opts.cause;
+  }
+
+  public toString() {
+    return `[${this.name}]\nMessage:${this.message}`;
+  }
+
+  protected static formatMessage(name: string, msg: string, code: string, docsUrl: string | undefined) {
+    // Keeping the Clerk prefix for backward compatibility
+    // msg = `${name}: ${msg.trim()}\n\n(code="${code}")\n\n`;
+    // We can remove the Clerk prefix in the next major version
+    const prefix = 'Clerk:';
+    const regex = new RegExp(prefix.replace(' ', '\\s*'), 'i');
+    msg = msg.replace(regex, '');
+    msg = `${prefix} ${msg.trim()}\n\n(code="${code}")\n\n`;
+    if (__DEV__ && docsUrl) {
+      msg += `\n\nDocs: ${docsUrl}`;
+    }
+    return msg;
+  }
+}
+
+/**
+ * Type guard to check if a value is a ClerkError instance.
+ */
+export function isClerkError(val: unknown): val is ClerkError {
+  const typeguard = createErrorTypeGuard(ClerkError);
+  // Ths is the base error so we're being more defensive about the type guard
+  return typeguard(val) || (!!val && typeof val === 'object' && 'clerkError' in val && val.clerkError === true);
+}

packages/shared/src/errors/clerkRuntimeError.ts

@@ -0,0 +1,39 @@
+import type { ClerkErrorParams } from './clerkError';
+import { ClerkError } from './clerkError';
+import { createErrorTypeGuard } from './createErrorTypeGuard';
+
+type ClerkRuntimeErrorOptions = Omit<ClerkErrorParams, 'message'>;
+
+/**
+ * Custom error class for representing Clerk runtime errors.
+ *
+ * @class ClerkRuntimeError
+ *
+ * @example
+ *   throw new ClerkRuntimeError('An error occurred', { code: 'password_invalid' });
+ */
+export class ClerkRuntimeError extends ClerkError {
+  static name = 'ClerkRuntimeError';
+  /**
+   * @deprecated Use `clerkError` property instead. This property is maintained for backward compatibility.
+   */
+  readonly clerkRuntimeError = true as const;
+
+  constructor(message: string, options: ClerkRuntimeErrorOptions) {
+    super({ ...options, message });
+    Object.setPrototypeOf(this, ClerkRuntimeError.prototype);
+  }
+}
+
+/**
+ * Type guard to check if an error is a ClerkRuntimeError.
+ * Can be called as a standalone function or as a method on an error object.
+ *
+ * @example
+ * // As a standalone function
+ * if (isClerkRuntimeError(error)) { ... }
+ *
+ * // As a method (when attached to error object)
+ * if (error.isClerkRuntimeError()) { ... }
+ */
+export const isClerkRuntimeError = createErrorTypeGuard(ClerkRuntimeError);