Keep lockoutExpiresInSeconds on user_locked ClerkAPIError meta

.changeset/lockout-expires-in-seconds.md

@@ -0,0 +1,5 @@
+---
+'@clerk/shared': patch
+---
+
+Keep `meta.lockout_expires_in_seconds` on `user_locked` ClerkAPIError objects so apps can show when the lockout ends.

packages/shared/src/__tests__/lockoutExpiresMeta.spec.ts

@@ -0,0 +1,37 @@
+import { describe, expect, it } from 'vitest';
+
+import { ClerkAPIError } from '../errors/clerkApiError';
+import { errorToJSON } from '../errors/parseError';
+import type { ClerkAPIErrorJSON } from '../types/errors';
+
+describe('user_locked error meta', () => {
+  const json: ClerkAPIErrorJSON = {
+    code: 'user_locked',
+    message: 'Account locked',
+    long_message: 'Too many failed attempts. Try again later.',
+    meta: {
+      lockout_expires_in_seconds: 3599,
+    },
+  };
+
+  it('keeps lockoutExpiresInSeconds from the wire payload', () => {
+    const error = new ClerkAPIError(json);
+    expect(error.meta.lockoutExpiresInSeconds).toBe(3599);
+  });
+
+  it('survives a snapshot round trip', () => {
+    const roundTripped = new ClerkAPIError(errorToJSON(new ClerkAPIError(json)));
+    expect(roundTripped.meta.lockoutExpiresInSeconds).toBe(3599);
+    expect(errorToJSON(roundTripped).meta?.lockout_expires_in_seconds).toBe(3599);
+  });
+
+  it('leaves an error without lockout duration alone', () => {
+    const error = new ClerkAPIError({
+      code: 'form_code_incorrect',
+      message: 'Incorrect code',
+      meta: { param_name: 'code' },
+    });
+    expect(error.meta.lockoutExpiresInSeconds).toBeUndefined();
+    expect(errorToJSON(error).meta?.lockout_expires_in_seconds).toBeUndefined();
+  });
+});

packages/shared/src/errors/clerkApiError.ts

@@ -35,6 +35,7 @@ export class ClerkAPIError<Meta extends ClerkAPIErrorMeta = any> implements Cler
         linkUrl: json.meta?.link_url,
         linkText: json.meta?.link_text,
         data: json.meta?.data,
+        lockoutExpiresInSeconds: json.meta?.lockout_expires_in_seconds,
       } as unknown as Meta,
     };
     this.code = parsedError.code;

packages/shared/src/errors/parseError.ts

@@ -48,6 +48,7 @@ export function errorToJSON(error: ClerkAPIError | null): ClerkAPIErrorJSON {
       link_url: error?.meta?.linkUrl,
       link_text: error?.meta?.linkText,
       data: error?.meta?.data,
+      lockout_expires_in_seconds: error?.meta?.lockoutExpiresInSeconds,
     },
   };
 }

packages/shared/src/types/errors.ts

@@ -30,6 +30,7 @@ export interface ClerkAPIErrorJSON {
     link_url?: string;
     link_text?: string;
     data?: Record<string, string | number | boolean>;
+    lockout_expires_in_seconds?: number;
   };
 }
 
@@ -122,6 +123,11 @@ export interface ClerkAPIError {
      * sensitive.
      */
     data?: Record<string, string | number | boolean>;
+    /**
+     * Seconds until a `user_locked` account can try again. Taken from
+     * `meta.lockout_expires_in_seconds` on the API error.
+     */
+    lockoutExpiresInSeconds?: number;
   };
 }