feat: standardize error response (#18)

* feat: standardize error response

* fix: tests

* feat: creating constant error names

* feat: creating 'MissingDefault' error variantion for api keys

* feat: creating error map

* fix: wrong error code in EnvErrorMap

* test: fix tests to use error types

* fix: lint

* docs: fix typos and improve inline docs for error constants

Fix typos in EnvError.code TSDoc, update stale AuthError.code reference,
add doc comments to all exported error constants and Errors map,
and re-export error constants from package root.

---------

Co-authored-by: Tomas Pozo <tomaspozogarzon@gmail.com>

Author: kallebysantos

README.md

@@ -189,7 +189,7 @@ Extracts credentials from a Request and validates against the allow config.
 ```ts
 const { data: auth, error } = await verifyAuth(req, { allow: 'user' })
 if (error) {
-  return Response.json({ error: error.message }, { status: error.status })
+  return Response.json({ message: error.message }, { status: error.status })
 }
 ```
 
@@ -246,7 +246,10 @@ export default {
     if (url.pathname === '/todos') {
       const { data: auth, error } = await verifyAuth(req, { allow: 'user' })
       if (error)
-        return Response.json({ error: error.message }, { status: error.status })
+        return Response.json(
+          { message: error.message },
+          { status: error.status },
+        )
 
       const supabase = createContextClient(auth.token)
       const { data } = await supabase.from('todos').select()

src/core/create-admin-client.test.ts

@@ -1,6 +1,10 @@
 import { describe, expect, it } from 'vitest'
 
-import { EnvError } from '../errors.js'
+import {
+  EnvError,
+  MissingDefaultSecretKeyError,
+  MissingSecretKeyError,
+} from '../errors.js'
 import { createAdminClient } from './create-admin-client.js'
 
 const validEnv = {
@@ -46,7 +50,7 @@ describe('createAdminClient', () => {
       })
     } catch (e) {
       expect(e).toBeInstanceOf(EnvError)
-      expect((e as EnvError).code).toBe('MISSING_SECRET_KEY')
+      expect((e as EnvError).code).toBe(MissingDefaultSecretKeyError)
     }
   })
 
@@ -72,7 +76,7 @@ describe('createAdminClient', () => {
       createAdminClient(validEnv, 'nonexistent')
     } catch (e) {
       expect(e).toBeInstanceOf(EnvError)
-      expect((e as EnvError).code).toBe('MISSING_SECRET_KEY')
+      expect((e as EnvError).code).toBe(MissingSecretKeyError)
     }
   })
 

src/core/create-admin-client.ts

@@ -1,6 +1,10 @@
 import { createClient, type SupabaseClient } from '@supabase/supabase-js'
 
-import { EnvError } from '../errors.js'
+import {
+  Errors,
+  MissingDefaultSecretKeyError,
+  MissingSecretKeyError,
+} from '../errors.js'
 import type { SupabaseEnv } from '../types.js'
 import { resolveEnv } from './resolve-env.js'
 
@@ -33,11 +37,9 @@ export function createAdminClient<Database = unknown>(
   const secretKey =
     keys[name] ?? (keyName == null ? Object.values(keys)[0] : undefined)
   if (!secretKey) {
-    const msg =
-      name === 'default'
-        ? 'No default secret key found. Set SUPABASE_SECRET_KEY or include a "default" entry in SUPABASE_SECRET_KEYS.'
-        : `No "${name}" secret key found. Include a "${name}" entry in SUPABASE_SECRET_KEYS.`
-    throw new EnvError(msg, 'MISSING_SECRET_KEY')
+    throw name === 'default'
+      ? Errors[MissingDefaultSecretKeyError]()
+      : Errors[MissingSecretKeyError](name)
   }
 
   return createClient(resolved.url, secretKey, {

src/core/create-context-client.test.ts

@@ -1,6 +1,10 @@
 import { describe, expect, it } from 'vitest'
 
-import { EnvError } from '../errors.js'
+import {
+  EnvError,
+  MissingDefaultPublishableKeyError,
+  MissingPublishableKeyError,
+} from '../errors.js'
 import { createContextClient } from './create-context-client.js'
 
 const validEnv = {
@@ -46,7 +50,7 @@ describe('createContextClient', () => {
       })
     } catch (e) {
       expect(e).toBeInstanceOf(EnvError)
-      expect((e as EnvError).code).toBe('MISSING_PUBLISHABLE_KEY')
+      expect((e as EnvError).code).toBe(MissingDefaultPublishableKeyError)
     }
   })
 
@@ -74,7 +78,7 @@ describe('createContextClient', () => {
       createContextClient('test-token', validEnv, 'nonexistent')
     } catch (e) {
       expect(e).toBeInstanceOf(EnvError)
-      expect((e as EnvError).code).toBe('MISSING_PUBLISHABLE_KEY')
+      expect((e as EnvError).code).toBe(MissingPublishableKeyError)
     }
   })
 

src/core/create-context-client.ts

@@ -1,6 +1,10 @@
 import { createClient, type SupabaseClient } from '@supabase/supabase-js'
 
-import { EnvError } from '../errors.js'
+import {
+  Errors,
+  MissingDefaultPublishableKeyError,
+  MissingPublishableKeyError,
+} from '../errors.js'
 import type { SupabaseEnv } from '../types.js'
 import { resolveEnv } from './resolve-env.js'
 
@@ -37,11 +41,9 @@ export function createContextClient<Database = unknown>(
   const anonKey =
     keys[name] ?? (keyName == null ? Object.values(keys)[0] : undefined)
   if (!anonKey) {
-    const msg =
-      name === 'default'
-        ? 'No default publishable key found. Set SUPABASE_PUBLISHABLE_KEY or include a "default" entry in SUPABASE_PUBLISHABLE_KEYS.'
-        : `No "${name}" publishable key found. Include a "${name}" entry in SUPABASE_PUBLISHABLE_KEYS.`
-    throw new EnvError(msg, 'MISSING_PUBLISHABLE_KEY')
+    throw name === 'default'
+      ? Errors[MissingDefaultPublishableKeyError]()
+      : Errors[MissingPublishableKeyError](name)
   }
 
   return createClient(resolved.url, anonKey, {

src/core/resolve-env.test.ts

@@ -1,6 +1,7 @@
 import { afterEach, describe, expect, it, vi } from 'vitest'
 
 import { resolveEnv } from './resolve-env.js'
+import { MissingSupabaseURLError } from '../errors.js'
 
 describe('resolveEnv', () => {
   afterEach(() => {
@@ -10,7 +11,7 @@ describe('resolveEnv', () => {
   it('returns error when SUPABASE_URL is missing', () => {
     const result = resolveEnv()
     expect(result.error).not.toBeNull()
-    expect(result.error!.code).toBe('MISSING_SUPABASE_URL')
+    expect(result.error!.code).toBe(MissingSupabaseURLError)
   })
 
   it('reads SUPABASE_URL from process.env', () => {

src/core/resolve-env.ts

@@ -1,4 +1,4 @@
-import { EnvError } from '../errors.js'
+import { EnvError, Errors, MissingSupabaseURLError } from '../errors.js'
 import type { JsonWebKeySet, SupabaseEnv } from '../types.js'
 
 /**
@@ -104,10 +104,7 @@ export function resolveEnv(
   if (!url) {
     return {
       data: null,
-      error: new EnvError(
-        'SUPABASE_URL is required but not set',
-        'MISSING_SUPABASE_URL',
-      ),
+      error: Errors[MissingSupabaseURLError](),
     }
   }
 

src/core/verify-auth.ts

@@ -41,7 +41,7 @@ interface VerifyAuthOptions {
  * })
  *
  * if (error) {
- *   return Response.json({ error: error.message }, { status: error.status })
+ *   return Response.json({ message: error.message }, { status: error.status })
  * }
  *
  * console.log(auth.userClaims!.id) // "d0f1a2b3-..."

src/core/verify-credentials.test.ts

@@ -3,6 +3,7 @@ import { beforeAll, describe, expect, it } from 'vitest'
 
 import type { Credentials, JsonWebKeySet, SupabaseEnv } from '../types.js'
 import { verifyCredentials } from './verify-credentials.js'
+import { InvalidCredentialsError } from '../errors.js'
 
 function makeEnv(overrides?: Partial<SupabaseEnv>): Partial<SupabaseEnv> {
   return {
@@ -50,7 +51,7 @@ describe('verifyCredentials', () => {
         env: makeEnv(),
       })
       expect(result.error).not.toBeNull()
-      expect(result.error!.code).toBe('INVALID_CREDENTIALS')
+      expect(result.error!.code).toBe(InvalidCredentialsError)
     })
 
     it('only matches default key when bare public is used', async () => {
@@ -66,7 +67,7 @@ describe('verifyCredentials', () => {
         env,
       })
       expect(result.error).not.toBeNull()
-      expect(result.error!.code).toBe('INVALID_CREDENTIALS')
+      expect(result.error!.code).toBe(InvalidCredentialsError)
     })
 
     it('matches named key with colon syntax and returns keyName', async () => {
@@ -101,7 +102,7 @@ describe('verifyCredentials', () => {
         env,
       })
       expect(result.error).not.toBeNull()
-      expect(result.error!.code).toBe('INVALID_CREDENTIALS')
+      expect(result.error!.code).toBe(InvalidCredentialsError)
     })
 
     it('rejects wrong named key type', async () => {
@@ -117,7 +118,7 @@ describe('verifyCredentials', () => {
         env,
       })
       expect(result.error).not.toBeNull()
-      expect(result.error!.code).toBe('INVALID_CREDENTIALS')
+      expect(result.error!.code).toBe(InvalidCredentialsError)
     })
 
     it('matches any key with wildcard syntax', async () => {
@@ -179,7 +180,7 @@ describe('verifyCredentials', () => {
         env: makeEnv(),
       })
       expect(result.error).not.toBeNull()
-      expect(result.error!.code).toBe('INVALID_CREDENTIALS')
+      expect(result.error!.code).toBe(InvalidCredentialsError)
     })
 
     it('only matches default key when bare secret is used', async () => {
@@ -192,7 +193,7 @@ describe('verifyCredentials', () => {
         env,
       })
       expect(result.error).not.toBeNull()
-      expect(result.error!.code).toBe('INVALID_CREDENTIALS')
+      expect(result.error!.code).toBe(InvalidCredentialsError)
     })
 
     it('matches secret named key with colon syntax and returns keyName', async () => {
@@ -218,7 +219,7 @@ describe('verifyCredentials', () => {
         env,
       })
       expect(result.error).not.toBeNull()
-      expect(result.error!.code).toBe('INVALID_CREDENTIALS')
+      expect(result.error!.code).toBe(InvalidCredentialsError)
     })
 
     it('rejects wrong secret named key type', async () => {
@@ -231,7 +232,7 @@ describe('verifyCredentials', () => {
         env,
       })
       expect(result.error).not.toBeNull()
-      expect(result.error!.code).toBe('INVALID_CREDENTIALS')
+      expect(result.error!.code).toBe(InvalidCredentialsError)
     })
 
     it('matches any key with wildcard syntax', async () => {
@@ -309,7 +310,7 @@ describe('verifyCredentials', () => {
         env: makeEnv({ jwks }),
       })
       expect(result.error).not.toBeNull()
-      expect(result.error!.code).toBe('INVALID_CREDENTIALS')
+      expect(result.error!.code).toBe(InvalidCredentialsError)
     })
 
     it('fails with no token', async () => {
@@ -319,7 +320,7 @@ describe('verifyCredentials', () => {
         env: makeEnv({ jwks }),
       })
       expect(result.error).not.toBeNull()
-      expect(result.error!.code).toBe('INVALID_CREDENTIALS')
+      expect(result.error!.code).toBe(InvalidCredentialsError)
     })
 
     it('fails with expired JWT', async () => {
@@ -341,7 +342,7 @@ describe('verifyCredentials', () => {
         env: makeEnv({ jwks: expiredJwks }),
       })
       expect(result.error).not.toBeNull()
-      expect(result.error!.code).toBe('INVALID_CREDENTIALS')
+      expect(result.error!.code).toBe(InvalidCredentialsError)
     })
   })
 
@@ -386,7 +387,7 @@ describe('verifyCredentials', () => {
         env,
       })
       expect(result.error).not.toBeNull()
-      expect(result.error!.code).toBe('INVALID_CREDENTIALS')
+      expect(result.error!.code).toBe(InvalidCredentialsError)
     })
   })
 

src/core/verify-credentials.ts

@@ -1,6 +1,6 @@
 import { createLocalJWKSet, jwtVerify } from 'jose'
 
-import { AuthError } from '../errors.js'
+import { AuthError, Errors, InvalidCredentialsError } from '../errors.js'
 import type {
   Allow,
   AllowWithKey,
@@ -203,7 +203,7 @@ async function tryMode(
  *   allow: ['user', 'public'],
  * })
  * if (error) {
- *   return Response.json({ error: error.message }, { status: error.status })
+ *   return Response.json({ message: error.message }, { status: error.status })
  * }
  * ```
  */
@@ -232,6 +232,6 @@ export async function verifyCredentials(
 
   return {
     data: null,
-    error: new AuthError('Invalid credentials', 'INVALID_CREDENTIALS', 401),
+    error: Errors[InvalidCredentialsError](),
   }
 }