@howmuchhome-web/api

백엔드 API 호출을 위한 타입 안전한 HTTP 클라이언트 패키지입니다. 개요 및 사용법은 API 패키지를, 컨벤션은 API 컨벤션을 참고하세요.

데코레이터

HTTP 메서드

데코레이터	설명
`@GET(path, searchParams?)`	GET 요청
`@POST(path, searchParams?)`	POST 요청
`@PUT(path, searchParams?)`	PUT 요청
`@PATCH(path, searchParams?)`	PATCH 요청
`@DELETE(path, searchParams?)`	DELETE 요청

path는 문자열 또는 (props) => string 함수를 받습니다. searchParams는 (props, pageParam?) => Record<string, unknown> 함수를 받습니다.

동작 제어

데코레이터	설명
`@SkipAuth`	인증 헤더 없이 요청
`@SilentErrorCodeList(codes)`	지정 에러 코드를 Sentry에 전송하지 않음
`@ResponseType('blob')`	응답을 Blob으로 수신 (기본값: `'json'`)

React Query 옵션

데코레이터	설명
`@QueryOptions(options \| fn)`	`useAPIQuery` 기본 옵션 설정
`@MutationOptions(fn)`	`useAPIMutation` 기본 옵션 설정
`@InfiniteQueryOptions(fn)`	`useAPIInfiniteQuery` 기본 옵션 설정

HowmuchhomeAPI

모든 API 모듈의 베이스 클래스입니다.


class MyAPI extends HowmuchhomeAPI {
  @GET(props => `v1/resource/${props.id}`)
  getResource(props: {id: string}): Promise<Response> {
    return this.fetch(props);
  }
}

this.fetch(props)는 데코레이터에 설정된 HTTP 메서드와 경로로 요청을 전송하고 응답을 제네릭 타입으로 반환합니다.

에러 클래스

ApiServerError

모든 API 에러의 베이스 클래스입니다.


class ApiServerError<Map extends ApiServerErrorMap = ApiServerErrorMap>
  extends HowmuchhomeError

프로퍼티

프로퍼티	타입	설명
`statusCode`	`number`	HTTP 상태 코드
`errorCode`	`string`	서버 에러 코드
`path`	`string`	요청 경로
`method`	`string`	HTTP 메서드
`detail`	`unknown`	에러 상세 정보

스태틱 메서드

메서드	설명
`isApiServerError(error)`	`ApiServerError` 타입 가드
`deserializeForServerAction(error)`	서버 액션 에러 역직렬화
`isServerActionError(error)`	서버 액션 에러 여부 확인

인스턴스 메서드

메서드	설명
`isErrorOfType(code)`	특정 에러 코드 타입 가드
`is401Error()`	401 에러 여부
`is403Error()`	403 에러 여부
`is404Error()`	404 에러 여부
`is422Error()`	422 에러 여부
`is502Error()`	502 에러 여부
`serializeForServerAction()`	서버 액션용 직렬화

HTTP 상태별 에러 클래스

클래스	상태 코드
`ApiServer401Error`	401 Unauthorized
`ApiServer403Error`	403 Forbidden
`ApiServer404Error`	404 Not Found
`ApiServer405Error`	405 Method Not Allowed
`ApiServer422Error`	422 Unprocessable Entity
`ApiServer502Error`	502 Bad Gateway
`MissingAccessTokenError`	액세스 토큰 없음

유틸리티

getAPIPath

API 메서드에서 경로를 추출합니다. 테스트나 쿼리 키 생성에 사용합니다.


import {getAPIPath} from '@howmuchhome-web/api';
 
const path = getAPIPath(VoteAPI.getVoteDetail, {voteId: '123'});
// → 'v1/vote/123'

Native (Expo)

공유 API 엔드포인트 정의(packages/api/lib)와 데코레이터는 native 에서도 그대로 씁니다. 다만 native 는 서버 컴포넌트가 없어 RSC prefetch / <Hydration> 패턴을 쓰지 않고 클라이언트 전용으로만 소비합니다.

fetcher 는 native 에서 앱 시작 시 configureApiFetcher 로 주입합니다(apps/native-app/src/api/howmuchhomeApi.ts). web fetcher 는 인증/표준 헤더를 쿠키(accesstoken, is-webview, X-APP-*)에서 읽는데, native 는 쿠키가 없으므로 SecureStore 토큰(getAuthToken)과 앱 정보를 fetcher 가 기대하는 쿠키 스토어 인터페이스로 매핑해 주입합니다. host 는 meta.server('front' 여부)에 따라 분기해 web 의 process.env 를 대체합니다.

@NoPersist 데코레이터(meta.persist=false)는 web 에는 영향이 없지만, native 의 react-query MMKV 영속 캐시(persistQueryClient)에서 해당 쿼리를 제외하는 의미를 가집니다(민감/개인정보 엔드포인트에 사용). 자세한 내용은 native 데이터 페칭·상태 관리를 참고하세요.