API 클라이언트

import { createClient, PickgolaApiError } from '@devercorp/pickgola-sdk';

const client = createClient({
  baseUrl: 'https://api.pickgola.com',
  onUnauthorized: () => {
    // 토큰 재발급까지 실패했을 때 (예: 로그인 화면으로 이동)
  },
});

모든 요청은 쿠키를 함께 보냅니다(credentials: 'include'). 응답이 401이면 /v1/auth/refresh로 한 번 재발급을 시도한 뒤 원래 요청을 다시 보냅니다. 동시에 여러 요청이 401을 받아도 재발급은 한 번만 일어납니다.

메서드

메서드	API
client.health()	GET /health
client.auth.signup(input)	POST /v1/auth/signup
client.auth.login(input)	POST /v1/auth/login
client.auth.refresh()	POST /v1/auth/refresh
client.auth.logout()	POST /v1/auth/logout
client.auth.me()	GET /v1/auth/me
client.users.updateMe(input)	PATCH /v1/users/me
client.users.addProfile(input)	POST /v1/users/me/profiles

이메일 인증·비밀번호·로그인 기기·탈퇴는 계정 보안, 서비스별 API는 아래 묶음에 있습니다.

묶음	문서
client.uploads, client.notifications, client.payments	업로드·알림·결제
client.day	데이벤트
client.studio	픽골라 스튜디오
client.admin	운영

요청 본문과 응답 타입은 OpenAPI 문서에서 만들어지므로, 편집기 자동 완성으로 필드를 확인할 수 있습니다. 아직 메서드로 감싸지 않은 API는 client.request(method, path, body)로 호출합니다.

오류 처리

실패한 요청은 PickgolaApiError를 던집니다. status에 HTTP 상태 코드가, message에 서버가 보낸 한국어 메시지가 들어 있습니다. 화면 분기가 필요한 오류는 code가 붙습니다.

code	뜻
ORG_REQUIRED	스튜디오 광고주 조직이 없음
CREATOR_REQUIRED	스튜디오 크리에이터 프로필이 없음
CREDITS_REQUIRED	크레딧 부족
CONSENT_BLOCKED	크리에이터 자산 동의 범위 밖의 제안
WITHDRAW_BLOCKED	진행 중인 일이 있어 탈퇴 불가 (body.blockers)

try {
  await client.auth.login({ email, password });
} catch (error) {
  if (error instanceof PickgolaApiError && error.status === 401) {
    showError(error.message); // "이메일 또는 비밀번호가 올바르지 않습니다."
  }
}

타입 다시 만들기

API가 바뀌면 pickgola-api에서 npm run openapi로 openapi.json을 만든 뒤, 이 저장소에서 타입을 다시 생성합니다.

npm run generate   # ../pickgola-api/openapi.json → packages/sdk/src/generated/schema.ts
npm run build