feat(auth): add TypeScript types for documented JWT claims fields

packages/core/auth-js/src/lib/types.ts

@@ -1434,7 +1434,21 @@ export type RequiredClaims = {
   session_id: string
 }
 
-export type JwtPayload = RequiredClaims & {
+export interface JwtPayload extends RequiredClaims {
+  email?: string
+  phone?: string
+  user_metadata?: UserMetadata
+  app_metadata?: UserAppMetadata
+  is_anonymous?: boolean
+  is_sso_user?: boolean
+  id?: string
+  created_at?: string
+  updated_at?: string
+  confirmed_at?: string
+  email_confirmed_at?: string
+  phone_confirmed_at?: string
+  last_sign_in_at?: string
+  identities?: UserIdentity[]
   [key: string]: any
 }
 

packages/core/auth-js/test/GoTrueClient.test.ts

@@ -1613,6 +1613,35 @@ describe('getClaims', () => {
     expect(authWithSession.getUser).toHaveBeenCalled()
   })
 
+  test('getClaims returns properly typed JwtPayload with documented fields', async () => {
+    const { email, password } = mockUserCredentials()
+    const {
+      data: { user },
+      error: initialError,
+    } = await authWithSession.signUp({
+      email,
+      password,
+    })
+    expect(initialError).toBeNull()
+    expect(user).not.toBeNull()
+
+    const { data, error } = await authWithSession.getClaims()
+    expect(error).toBeNull()
+    expect(data).not.toBeNull()
+
+    const claims = data?.claims
+    expect(claims).toBeDefined()
+
+    expect(typeof claims?.email).toBe('string')
+    expect(typeof claims?.user_metadata).toBe('object')
+    expect(typeof claims?.app_metadata).toBe('object')
+    expect(typeof claims?.is_anonymous).toBe('boolean')
+    expect(typeof claims?.is_sso_user).toBe('boolean')
+    expect(typeof claims?.id).toBe('string')
+    expect(typeof claims?.created_at).toBe('string')
+    expect(typeof claims?.role).toBe('string')
+  })
+
   test('getClaims fetches JWKS to verify asymmetric jwt', async () => {
     const fetchedUrls: any[] = []
     const fetchedResponse: any[] = []