Setup

SDK 를 frontend 프로젝트에 셋업하는 단일 절차.

1. 설치

pnpm add @classum/learning-sdk
# 또는 npm / yarn

내부 registry 사용 — .npmrc 에 @classum:registry=https://registry.classum.com 필요.

2. 환경 변수

vite 기준:

# .env
VITE_API_URL=https://template-api-dev.classum.io  # dev
# VITE_API_URL=https://template-api.classum.io    # prod

3. App boot 시 한 번 설정

// src/main.tsx (또는 app entry)
import { setupServiceSdk, client } from '@classum/learning-sdk'

client.setConfig({
  baseUrl: import.meta.env.VITE_API_URL,
})

setupServiceSdk({
  // access token 읽기 — null 이면 SDK 가 Authorization 헤더 미주입.
  getAccessToken: () => sessionStorage.getItem('app.access'),

  // refresh 성공 시 SDK 가 호출. 저장 위치는 자유.
  setAccessToken: (token, expiresAtIso) => {
    sessionStorage.setItem('app.access', token)
    sessionStorage.setItem('app.expiresAt', expiresAtIso)
  },

  // 401 + refresh 도 실패 시 호출. 로그인 페이지 redirect 가 일반적.
  onAuthFailure: () => {
    location.href = '/sign-in'
  },

  // 옵션 — proactive refresh, retry, timeout 등 (기본값 사용 권장)
  getAccessTokenExpiresAt: () => sessionStorage.getItem('app.expiresAt'),
})

4. Token storage 권장

탭간 공유: 위 3 옵션 어떤 것이든 자동으로 됨. Refresh token 이 HttpOnly cookie 라 같은 root domain 의 모든 탭이 공유. 한 탭 sign-in → 다른 탭이 새로고침 시 SDK 가 자동 refresh 호출 → access token 자동 회복. + BroadcastChannel 로 메모리 access token 도 즉시 전파.

5. API 호출

import { BackOfficeTenant, ClientAuth } from '@classum/learning-sdk'

const { data: tenant } = await BackOfficeTenant.get({ path: { id: 't-id' } })

const signin = await ClientAuth.signIn({
  body: { tenantKey: 'classum', userId: 'windy', password: 'pw' },
})
hooks.setAccessToken(signin.data!.accessToken, signin.data!.accessTokenExpiresAt)

자세한 method 시그니처는 SDK Reference, endpoint 명세는 API Reference.

6. React + TanStack Query 사용 시

SDK 가 framework-agnostic — useQuery 의 queryFn 에 그대로 감싸면 됩니다.

import { useQuery } from '@tanstack/react-query'
import { BackOfficeTenant } from '@classum/learning-sdk'

function TenantList() {
  const { data, isLoading } = useQuery({
    queryKey: ['service-tenant-list', { page: 1, limit: 20 }],
    queryFn: async () => {
      const res = await BackOfficeTenant.list({ query: { page: 1, limit: 20 } })
      return res.data
    },
  })
  // ...
}

추후 @classum/learning-sdk/react entrypoint 가 useServiceQuery / ServiceAuthProvider 헬퍼 제공 예정 (별도 PR).

7. Form validation — SDK 의 zod schema 직접 사용

backend 의 zod schema 가 SDK 에 자동 inline (OpenAPI → zod). frontend 가 같은 schema 로 runtime 검증 → drift 불가능.

import { useForm } from 'react-hook-form'
import { zodResolver } from '@hookform/resolvers/zod'
import { ClientAuth, zSignInBodyDto, type SignInBodyDto } from '@classum/learning-sdk'

function SignInForm() {
  const form = useForm<SignInBodyDto>({
    resolver: zodResolver(zSignInBodyDto),
  })
  // form.handleSubmit(input => ClientAuth.signIn({ body: input }))
}

schema 이름 규칙:

• z<DtoName> — request body / response shape (예: zSignInBodyDto, zSignUpBodyDto, zForgotPasswordBodyDto)
• z<OperationId>Data — operation 의 path / query / body 를 합친 input shape (예: zClientSignInData)

SDK 0.24.0+ 부터 제공. 이전 버전은 type 만 export.

8. 서버 / SDK 버전 확인

GET /health-check 가 현재 서버 코드의 SDK 버전을 응답:

curl https://template-api-dev.classum.io/health-check
# { "status": "ok", "version": "0.24.0" }

frontend 가 pnpm i @classum/learning-sdk@0.24.0 설치 + 위 응답이 같은 0.24.0 이면 서버/클라이언트 코드 일치 확인. dev-deploy 서버는 prerelease (-rc.<N>) 표기 — pnpm i @classum/learning-sdk@rc 와 동기.