feat(clerk-js,types,shared): Future types for ClerkGlobalHookError

.changeset/warm-steaks-count.md

@@ -0,0 +1,5 @@
+---
+'@clerk/backend': minor
+---
+
+Export missing Billing types

packages/backend/src/index.ts

@@ -100,9 +100,13 @@ export type {
   PaginatedResponseJSON,
   TestingTokenJSON,
   WebhooksSvixJSON,
+  BillingPayerJSON,
   BillingPlanJSON,
   BillingSubscriptionJSON,
   BillingSubscriptionItemJSON,
+  BillingPaymentAttemptWebhookEventJSON,
+  BillingSubscriptionItemWebhookEventJSON,
+  BillingSubscriptionWebhookEventJSON,
 } from './api/resources/JSON';
 
 /**

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

@@ -1,6 +1,24 @@
 import { inBrowser } from '@clerk/shared/browser';
 import { ClerkWebAuthnError } from '@clerk/shared/error';
 import { Poller } from '@clerk/shared/poller';
+import type {
+  SignInFutureBackupCodeVerifyParams,
+  SignInFutureCreateParams,
+  SignInFutureEmailCodeSendParams,
+  SignInFutureEmailCodeVerifyParams,
+  SignInFutureEmailLinkSendParams,
+  SignInFutureFinalizeParams,
+  SignInFutureMFAPhoneCodeVerifyParams,
+  SignInFuturePasswordParams,
+  SignInFuturePhoneCodeSendParams,
+  SignInFuturePhoneCodeVerifyParams,
+  SignInFutureResetPasswordSubmitParams,
+  SignInFutureResource,
+  SignInFutureSSOParams,
+  SignInFutureTicketParams,
+  SignInFutureTOTPVerifyParams,
+  SignInFutureWeb3Params,
+} from '@clerk/shared/types';
 import { deepCamelToSnake, deepSnakeToCamel } from '@clerk/shared/underscore';
 import {
   isWebAuthnAutofillSupported as isWebAuthnAutofillSupportedOnWindow,
@@ -31,22 +49,6 @@ import type {
   SamlConfig,
   SignInCreateParams,
   SignInFirstFactor,
-  SignInFutureBackupCodeVerifyParams,
-  SignInFutureCreateParams,
-  SignInFutureEmailCodeSendParams,
-  SignInFutureEmailCodeVerifyParams,
-  SignInFutureEmailLinkSendParams,
-  SignInFutureFinalizeParams,
-  SignInFutureMFAPhoneCodeVerifyParams,
-  SignInFuturePasswordParams,
-  SignInFuturePhoneCodeSendParams,
-  SignInFuturePhoneCodeVerifyParams,
-  SignInFutureResetPasswordSubmitParams,
-  SignInFutureResource,
-  SignInFutureSSOParams,
-  SignInFutureTicketParams,
-  SignInFutureTOTPVerifyParams,
-  SignInFutureWeb3Params,
   SignInIdentifier,
   SignInJSON,
   SignInJSONSnapshot,

packages/react/src/hooks/useClerkSignal.ts

@@ -1,4 +1,4 @@
-import type { SignInSignalValue, SignUpSignalValue } from '@clerk/types';
+import type { SignInSignalValue, SignUpSignalValue } from '@clerk/shared/types';
 import { useCallback, useSyncExternalStore } from 'react';
 
 import { useIsomorphicClerkContext } from '../contexts/IsomorphicClerkContext';

packages/shared/package.json

@@ -70,6 +70,24 @@
         "default": "./dist/dom/index.js"
       }
     },
+    "./experimental-error": {
+      "import": {
+        "types": "./dist/experimental-error/index.d.mts",
+        "default": "./dist/experimental-error/index.mjs"
+      },
+      "require": {
+        "types": "./dist/experimental-error/index.d.ts",
+        "default": "./dist/experimental-error/index.js"
+      }
+    },
+    "./types": {
+      "import": {
+        "types": "./dist/types/index.d.mts"
+      },
+      "require": {
+        "types": "./dist/types/index.d.ts"
+      }
+    },
     "./package.json": "./package.json"
   },
   "main": "./dist/index.js",
@@ -87,6 +105,7 @@
     "deriveState",
     "dom",
     "error",
+    "experimental-error",
     "file",
     "globs",
     "handleValueOrFn",
@@ -123,7 +142,8 @@
     "eventBus",
     "netlifyCacheHandler",
     "clerkEventBus",
-    "phoneCodeChannel"
+    "phoneCodeChannel",
+    "types"
   ],
   "scripts": {
     "build": "tsup",

packages/shared/src/errors/apiResponseError.ts

@@ -6,7 +6,7 @@ import type {
 
 import { parseErrors } from './parseError';
 
-interface ClerkAPIResponseOptions {
+export interface ClerkAPIResponseOptions {
   data: ClerkAPIErrorJSON[];
   status: number;
   clerkTraceId?: string;

packages/shared/src/errors/parseError.ts

@@ -19,6 +19,7 @@ export function parseError(error: ClerkAPIErrorJSON): ClerkAPIError {
     code: error.code,
     message: error.message,
     longMessage: error.long_message,
+    clerkTraceId: error.clerk_trace_id,
     meta: {
       paramName: error?.meta?.param_name,
       sessionId: error?.meta?.session_id,

packages/shared/src/experimental-error/clerkApiError.ts

@@ -0,0 +1,31 @@
+import type { ClerkAPIErrorJSON } from '@clerk/types';
+
+import { parseError } from '../errors/parseError';
+
+export type ClerkApiErrorMeta = Record<string, unknown> | undefined;
+
+/**
+ * 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 = undefined> {
+  readonly name = 'ClerkApiError';
+  readonly code: string;
+  readonly message: string;
+  readonly longMessage: string | undefined;
+  readonly meta: Meta;
+
+  constructor(json: ClerkAPIErrorJSON) {
+    const parsedError = parseError(json);
+    this.code = parsedError.code;
+    this.message = parsedError.message;
+    this.longMessage = parsedError.longMessage;
+    this.meta = json.meta as Meta;
+  }
+}
+
+/**
+ * Type guard to check if a value is a ClerkApiError instance.
+ */
+export function isClerkApiError(error: Error): error is ClerkApiError {
+  return error instanceof ClerkApiError;
+}

packages/shared/src/experimental-error/clerkApiErrorResponse.ts

@@ -0,0 +1,50 @@
+/* eslint-disable jsdoc/require-jsdoc */
+import type { ClerkApiErrorResponseJSON } from '@clerk/types';
+
+import { ClerkApiError } from './clerkApiError';
+import { ClerkError } from './clerkError';
+
+type ClerkApiResponseErrorParams = ClerkApiErrorResponseJSON & {
+  retryAfter?: number;
+};
+
+/**
+ * A ClerkError subclass that represents the shell response of a Clerk API error.
+ * This error contains an array of ClerkApiError instances, each representing a specific error that occurred.
+ */
+export class ClerkApiResponseError<E extends ClerkApiError = ClerkApiError> extends ClerkError {
+  readonly name = 'ClerkApiResponseError';
+  readonly retryAfter?: number;
+  readonly errors: E[];
+  readonly clerkTraceId: string | undefined;
+
+  constructor(data: ClerkApiResponseErrorParams) {
+    const errorMesages = data.errors.map(e => e.message).join(', ');
+    const message = `Api errors occurred: ${errorMesages}. Check the \`errors\` property for more details about the specific errors.`;
+    super({ message, code: 'clerk_api_error' });
+    this.errors = data.errors.map(e => new ClerkApiError(e)) as E[];
+    this.clerkTraceId = data.clerk_trace_id;
+    this.retryAfter = data.retryAfter;
+  }
+}
+
+/**
+ * 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 function isClerkApiResponseError(error: Error): error is ClerkApiResponseError;
+export function isClerkApiResponseError(this: Error): this is ClerkApiResponseError;
+export function isClerkApiResponseError(this: Error | void, error?: Error): error is ClerkApiResponseError {
+  const target = error ?? this;
+  if (!target) {
+    throw new TypeError('isClerkApiResponseError requires an error object');
+  }
+  return target instanceof ClerkApiResponseError;
+}

packages/shared/src/experimental-error/clerkError.ts

@@ -0,0 +1,64 @@
+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 {
+  readonly clerkError = true as const;
+  readonly name: string = 'ClerkError';
+  readonly code: string;
+  readonly longMessage: string | undefined;
+  readonly docsUrl: string | undefined;
+  readonly cause: Error | undefined;
+
+  constructor(opts: ClerkErrorParams) {
+    const formatMessage = (msg: string, code: string, docsUrl: string | undefined) => {
+      msg = `${this.name}: ${msg.trim()}\n\n(code="${code}")\n\n`;
+      if (__DEV__) {
+        msg += `\n\nDocs: ${docsUrl}`;
+      }
+      return msg;
+    };
+
+    super(formatMessage(opts.message, opts.code, opts.docsUrl), { cause: opts.cause });
+    Object.setPrototypeOf(this, ClerkError.prototype);
+
+    this.code = opts.code;
+    this.docsUrl = opts.docsUrl;
+  }
+}
+
+/**
+ * Type guard to check if a value is a ClerkError instance.
+ */
+export function isClerkError(val: unknown): val is ClerkError {
+  return !!val && typeof val === 'object' && 'clerkError' in val && val.clerkError === true;
+}

packages/shared/src/experimental-error/clerkRuntimeError.ts

@@ -0,0 +1,32 @@
+/* eslint-disable jsdoc/require-jsdoc */
+import type { ClerkErrorParams } from './clerkError';
+import { ClerkError } from './clerkError';
+
+export class ClerkRuntimeError extends ClerkError {
+  readonly name = 'ClerkRuntimeError';
+
+  constructor(params: ClerkErrorParams) {
+    super(params);
+  }
+}
+
+/**
+ * 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 function isClerkRuntimeError(error: Error): error is ClerkRuntimeError;
+export function isClerkRuntimeError(this: Error): this is ClerkRuntimeError;
+export function isClerkRuntimeError(this: Error | void, error?: Error): error is ClerkRuntimeError {
+  const target = error ?? this;
+  if (!target) {
+    throw new TypeError('isClerkRuntimeError requires an error object');
+  }
+  return target instanceof ClerkRuntimeError;
+}

packages/shared/src/experimental-error/globalHookError.ts

@@ -0,0 +1,23 @@
+import { isClerkApiResponseError } from './clerkApiErrorResponse';
+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/experimental-error/index.ts

@@ -0,0 +1,7 @@
+export { ClerkApiError, isClerkApiError } from './clerkApiError';
+export type { ClerkApiErrorMeta } from './clerkApiError';
+export { ClerkApiResponseError, isClerkApiResponseError } from './clerkApiErrorResponse';
+export { ClerkError, isClerkError, type ClerkErrorParams } from './clerkError';
+export { ClerkRuntimeError, isClerkRuntimeError } from './clerkRuntimeError';
+export { createClerkGlobalHookError } from './globalHookError';
+export type { ClerkGlobalHookError } from './globalHookError';

packages/shared/src/types/index.ts

@@ -0,0 +1,31 @@
+export type {
+  Errors,
+  FieldError,
+  FieldErrors,
+  NullableSignInSignal,
+  NullableSignUpSignal,
+  SignInSignal,
+  SignInSignalValue,
+  SignUpSignal,
+  SignUpSignalValue,
+  State,
+} from './state';
+
+export type {
+  SignInFutureBackupCodeVerifyParams,
+  SignInFutureCreateParams,
+  SignInFutureEmailCodeSendParams,
+  SignInFutureEmailCodeVerifyParams,
+  SignInFutureEmailLinkSendParams,
+  SignInFutureFinalizeParams,
+  SignInFutureMFAPhoneCodeVerifyParams,
+  SignInFuturePasswordParams,
+  SignInFuturePhoneCodeSendParams,
+  SignInFuturePhoneCodeVerifyParams,
+  SignInFutureResetPasswordSubmitParams,
+  SignInFutureResource,
+  SignInFutureSSOParams,
+  SignInFutureTicketParams,
+  SignInFutureTOTPVerifyParams,
+  SignInFutureWeb3Params,
+} from './signInResource';