Add custom errors (#18)

* Add axios-better-stacktrace

* Add SeamHttpApiError

* Add SeamHttpRequestValidationError

* Update SeamHttpApiError format

* Export api error

* Extend InvalidInputError from SeamHttpApiError

* Export invalid input error

* Add noop errorInterceptor

* Add error interceptor

* Add tests for error errorInterceptor

* Do not export client

* Throw original error if parsing fails

* Validate request id value

* Add SeamHttpUnauthorizedError

* Move errors into single file

* Make error response paring safe

* Add error type guards

* Move and export errorInterceptor

* Simplify errorInterceptor

* Simplify SeamHttpUnauthorizedError

* Fix check

Author: razor-x

package-lock.json

@@ -87,10 +87,11 @@
   },
   "dependencies": {
     "axios": "^1.5.0",
+    "axios-better-stacktrace": "^2.1.5",
     "axios-retry": "^3.8.0"
   },
   "devDependencies": {
-    "@seamapi/fake-seam-connect": "^1.41.4",
+    "@seamapi/fake-seam-connect": "^1.43.0",
     "@seamapi/types": "^1.24.0",
     "@types/eslint": "^8.44.2",
     "@types/node": "^18.11.18",

package.json

@@ -0,0 +1,11 @@
+// UPSTREAM: These types should be provided by @seamapi/types/connect.
+
+export interface ApiErrorResponse {
+  error: ApiError
+}
+
+export interface ApiError {
+  type: string
+  message: string
+  data?: unknown
+}

src/lib/seam/connect/api-error-type.ts

@@ -1,8 +1,12 @@
 import axios, { type AxiosInstance, type AxiosRequestConfig } from 'axios'
+// @ts-expect-error https://github.com/svsool/axios-better-stacktrace/issues/12
+import axiosBetterStacktrace from 'axios-better-stacktrace'
 import axiosRetry, { type AxiosRetry, exponentialDelay } from 'axios-retry'
 
 import { paramsSerializer } from 'lib/params-serializer.js'
 
+import { errorInterceptor } from './error-interceptor.js'
+
 export type Client = AxiosInstance
 
 export interface ClientOptions {
@@ -21,12 +25,16 @@ export const createClient = (options: ClientOptions): AxiosInstance => {
     ...options.axiosOptions,
   })
 
+  axiosBetterStacktrace(axios)
+
   // @ts-expect-error https://github.com/softonic/axios-retry/issues/159
   axiosRetry(client, {
     retries: 2,
     retryDelay: exponentialDelay,
     ...options.axiosRetryOptions,
   })
 
+  client.interceptors.response.use(undefined, errorInterceptor)
+
   return client
 }

src/lib/seam/connect/client.ts

@@ -0,0 +1,61 @@
+import { type AxiosError, isAxiosError } from 'axios'
+
+import type { ApiErrorResponse } from './api-error-type.js'
+import {
+  SeamHttpApiError,
+  SeamHttpInvalidInputError,
+  SeamHttpUnauthorizedError,
+} from './seam-http-error.js'
+
+export const errorInterceptor = async (err: unknown): Promise<void> => {
+  if (!isAxiosError(err)) throw err
+
+  const { response } = err
+  const status = response?.status
+  const headers = response?.headers
+  const requestId = headers?.['seam-request-id'] ?? ''
+
+  if (status == null) throw err
+
+  if (status === 401) {
+    throw new SeamHttpUnauthorizedError(requestId)
+  }
+
+  if (!isApiErrorResponse(response)) throw err
+
+  const { type } = response.data.error
+
+  const args = [response.data.error, status, requestId] as const
+
+  if (type === 'invalid_input') throw new SeamHttpInvalidInputError(...args)
+  throw new SeamHttpApiError(...args)
+}
+
+const isApiErrorResponse = (
+  response: AxiosError['response'],
+): response is NonNullable<AxiosError<ApiErrorResponse>['response']> => {
+  if (response == null) return false
+  const { headers, data } = response
+
+  if (headers == null) return false
+
+  const contentType = headers['content-type']
+  if (
+    typeof contentType === 'string' &&
+    !contentType.startsWith('application/json')
+  ) {
+    return false
+  }
+
+  if (typeof data === 'object' && data != null) {
+    return (
+      'error' in data &&
+      typeof data.error === 'object' &&
+      data.error != null &&
+      'type' in data.error &&
+      typeof data.error.type === 'string'
+    )
+  }
+
+  return false
+}

src/lib/seam/connect/error-interceptor.ts

@@ -1,4 +1,6 @@
+export * from './error-interceptor.js'
 export * from './options.js'
-export * from './routes//index.js'
+export * from './routes/index.js'
 export * from './seam-http.js'
+export * from './seam-http-error.js'
 export * from 'lib/params-serializer.js'

src/lib/seam/connect/index.ts

@@ -0,0 +1,64 @@
+import type { ApiError } from './api-error-type.js'
+
+export class SeamHttpApiError extends Error {
+  code: string
+  statusCode: number
+  requestId: string
+  data?: unknown
+
+  constructor(error: ApiError, statusCode: number, requestId: string) {
+    const { type, message, data } = error
+    super(message)
+    this.name = this.constructor.name
+    Error.captureStackTrace(this, this.constructor)
+    this.code = type
+    this.statusCode = statusCode
+    this.requestId = requestId
+    if (data != null) this.data = data
+  }
+}
+
+export const isSeamHttpApiError = (
+  error: unknown,
+): error is SeamHttpApiError => {
+  return error instanceof SeamHttpApiError
+}
+
+export class SeamHttpUnauthorizedError extends SeamHttpApiError {
+  override code: 'unauthorized'
+  override statusCode: 401
+
+  constructor(requestId: string) {
+    const type = 'unauthorized'
+    const status = 401
+    super({ type, message: 'Unauthorized' }, status, requestId)
+    this.name = this.constructor.name
+    Error.captureStackTrace(this, this.constructor)
+    this.code = type
+    this.statusCode = status
+    this.requestId = requestId
+  }
+}
+
+export const isSeamHttpUnauthorizedError = (
+  error: unknown,
+): error is SeamHttpUnauthorizedError => {
+  return error instanceof SeamHttpUnauthorizedError
+}
+
+export class SeamHttpInvalidInputError extends SeamHttpApiError {
+  override code: 'invalid_input'
+
+  constructor(error: ApiError, statusCode: number, requestId: string) {
+    super(error, statusCode, requestId)
+    this.name = this.constructor.name
+    Error.captureStackTrace(this, this.constructor)
+    this.code = 'invalid_input'
+  }
+}
+
+export const isSeamHttpInvalidInputError = (
+  error: unknown,
+): error is SeamHttpInvalidInputError => {
+  return error instanceof SeamHttpInvalidInputError
+}

src/lib/seam/connect/seam-http-error.ts

@@ -0,0 +1,95 @@
+import test from 'ava'
+import { AxiosError } from 'axios'
+import { getTestServer } from 'fixtures/seam/connect/api.js'
+
+import {
+  SeamHttp,
+  SeamHttpApiError,
+  SeamHttpInvalidInputError,
+  SeamHttpUnauthorizedError,
+} from '@seamapi/http/connect'
+
+test('SeamHttp: throws AxiosError on non-standard response', async (t) => {
+  const { seed, endpoint, db } = await getTestServer(t)
+
+  db.simulateWorkspaceOutage(seed.seed_workspace_1, {
+    routes: ['/devices/list'],
+  })
+
+  const seam = SeamHttp.fromApiKey(seed.seam_apikey1_token, {
+    endpoint,
+    axiosRetryOptions: {
+      retries: 0,
+    },
+  })
+
+  const err = await t.throwsAsync(async () => await seam.devices.list(), {
+    instanceOf: AxiosError,
+  })
+
+  t.is(err?.response?.status, 503)
+})
+
+test('SeamHttp: throws SeamHttpUnauthorizedError if unauthorized', async (t) => {
+  const { endpoint } = await getTestServer(t)
+
+  const seam = SeamHttp.fromApiKey('seam_invalid_api_key', {
+    endpoint,
+    axiosRetryOptions: {
+      retries: 0,
+    },
+  })
+
+  const err = await t.throwsAsync(async () => await seam.devices.list(), {
+    instanceOf: SeamHttpUnauthorizedError,
+  })
+
+  t.is(err?.statusCode, 401)
+  t.is(err?.code, 'unauthorized')
+  t.true(err?.requestId?.startsWith('request'))
+})
+
+test('SeamHttp: throws SeamHttpApiError on standard error response', async (t) => {
+  const { seed, endpoint } = await getTestServer(t)
+
+  const seam = SeamHttp.fromApiKey(seed.seam_apikey1_token, {
+    endpoint,
+    axiosRetryOptions: {
+      retries: 0,
+    },
+  })
+
+  const err = await t.throwsAsync(
+    async () => await seam.devices.get({ device_id: 'unknown-device' }),
+    {
+      instanceOf: SeamHttpApiError,
+    },
+  )
+
+  t.is(err?.statusCode, 404)
+  t.is(err?.code, 'device_not_found')
+  t.true(err?.requestId?.startsWith('request'))
+})
+
+test('SeamHttp: throws SeamHttpInvalidInputError on invalid input', async (t) => {
+  const { seed, endpoint } = await getTestServer(t)
+
+  const seam = SeamHttp.fromApiKey(seed.seam_apikey1_token, {
+    endpoint,
+    axiosRetryOptions: {
+      retries: 0,
+    },
+  })
+
+  const err = await t.throwsAsync(
+    async () =>
+      await seam.devices.client.post('/devices/list', { device_ids: 4242 }),
+    {
+      instanceOf: SeamHttpInvalidInputError,
+    },
+  )
+
+  t.is(err?.statusCode, 400)
+  t.is(err?.code, 'invalid_input')
+  t.true(err?.requestId?.startsWith('request'))
+})

test/seam/connect/http-error.test.ts

@@ -9,7 +9,7 @@ test('SeamHttp: retries 503 status errors twice by default ', async (t) => {
   const expectedRetryCount = 2
 
   db.simulateWorkspaceOutage(seed.seed_workspace_1, {
-    routes: ['/devices/get'],
+    routes: ['/devices/list'],
   })
 
   t.plan(expectedRetryCount + 2)
@@ -24,16 +24,11 @@ test('SeamHttp: retries 503 status errors twice by default ', async (t) => {
   })
 
   const err = await t.throwsAsync(
-    async () =>
-      // UPSTREAM: This test should use seam.devices.get({ device_id: '...' }).
-      // Only idempotent methods, e.g., GET not POST, are retried by default.
-      // The SDK should use GET over POST once that method is supported upstream.
-      // https://github.com/seamapi/nextlove/issues/117
-      await seam.client.get('/devices/get', {
-        params: {
-          device_id: seed.august_device_1,
-        },
-      }),
+    // UPSTREAM: This test should use seam.devices.list().
+    // Only idempotent methods, e.g., GET not POST, are retried by default.
+    // The SDK should use GET over POST once that method is supported upstream.
+    // https://github.com/seamapi/nextlove/issues/117
+    async () => await seam.client.get('/devices/list'),
     { instanceOf: AxiosError },
   )