---
title: "@vonvon-kit/core"
description: "세션 상태, 단기 JWT 접근, 관리 API 헬퍼를 위한 브라우저 클라이언트입니다."
locale: "ko"
---

> Documentation Index
> Fetch the relevant documentation index at: https://vonvon.id/ko/sdks/llms.txt
> Use this file to discover all available pages before exploring further.

# @vonvon-kit/core

## 설치 및 설정

Registry 상태: UNPUBLISHED. 이 SDK는 저장소 소스 checkout에서만 설치하고 외부 package registry를 사용하지 마세요.

다른 origin의 개발자 앱에서는 issuer, clientId, 정확한 redirectUri와 함께 `mode: 'oidc'`를 구성합니다. 애플리케이션이 정확히 동일한 origin에서 Core auth endpoints를 라우팅하는 경우에만 same-origin mode를 사용합니다. Vonvon에는 publishable-key credential이 없습니다.

```ts
import { VonvonClient } from '@vonvon-kit/core'

const vonvon = new VonvonClient({
  mode: 'oidc',
  issuer: 'https://vonvon.id',
  clientId: 'client_abc123',
  redirectUri: 'https://app.example.com/auth/callback',
})

const authorization = await vonvon.createAuthorizationUrl({ returnUrl: '/dashboard' })
if (!authorization.ok) throw new Error(authorization.error.message)
window.location.assign(authorization.value)
```

## 세션 수명주기

- `load()`은 `/v1/me`를 읽어 사용자, 세션, 활성 조직을 초기화합니다.
- `signInPassword()`는 Hosted Auth 비밀번호 흐름을 통해 cookie 세션을 생성합니다.
- `getToken()`은 API 호출용 단기 JWT를 반환합니다. 백엔드에서 JWKS를 이용해 네트워크 호출 없이 검증하세요.
- `setActiveOrganization()`은 조직 컨텍스트를 전환하고 상태를 다시 로드하기 전에 token 캐시를 초기화합니다.
- `signOut()`은 브라우저 세션 cookie를 폐기합니다.

## 관리 API 헬퍼

Management API helpers는 `server-side 또는 정확한 same-origin에서만 사용할 수 있습니다`. server에서 `sk_live_*` 또는 sk\_test\_\*를 사용해 별도 client를 구성합니다. OIDC browser mode에서는 이러한 작업을 거부합니다.

```ts
const management = new VonvonClient({
  apiUrl: 'https://vonvon.id',
  secretKey: process.env.VONVON_SECRET_KEY,
})

const keys = await management.listApiKeys()
if (!keys.ok) throw new Error(keys.error.message)

const created = await management.createApiKey({ name: 'CI deploy', scopes: ['read'] })
if (!created.ok) throw new Error(created.error.message)

const revoked = await management.revokeApiKey({ id: created.value.id })
if (!revoked.ok) throw new Error(revoked.error.message)
```

## 내보내진 API

| 내보내기 | 종류 | 목적 |
| --- | --- | --- |
| `VonvonClient` | class | 최상위 브라우저 클라이언트: load, signIn, getToken, setActiveOrganization, signOut 및 관리 API 헬퍼 |
| `VonvonStore` | class | 프레임워크에 독립적인 반응형 store; 프레임워크 바인딩에서 useSyncExternalStore로 구독합니다 |
| `TokenManager` | class | 단기 JWT 캐시 및 예약 갱신 (고급 사용 및 테스트) |
| `VonvonApiClient` | class | /v1/me 및 token 엔드포인트용 HTTP 클라이언트 |
| `VonvonNetworkError` | class | 전송 실패 시 던집니다: 네트워크 오류, JSON이 아닌 응답, 구조화된 본문이 없는 5xx |
| `makeVonvonError` | function | 네트워크 왕복 없이 로컬 검증 실패에 대한 구조화된 VonvonError를 생성합니다 |
| `isVonvonErrorShape` | function | 타입 가드: 알 수 없는 값이 네트워크의 VonvonError 형태를 따르는지 확인합니다 |
| `decodeTokenClaims` | function | 만료 스케줄링 전용으로 JWT 페이로드 클레임을 디코딩합니다; 서명은 검증하지 않습니다 |
| `isTokenExpiring` | function | 토큰이 leeway 창 내에서 만료될 때 true를 반환합니다 (기본값 10초) |
| `SESSION_STATUS` | as const 튜플 | 유효한 세션 상태 값: active, pending, expired, removed, ended, revoked |
| `CLIENT_STATUS` | as const 튜플 | 유효한 클라이언트 상태 값: loading, ready, degraded, error |
| `PACKAGE` | 문자열 상수 | 패키지 이름 식별자 '@vonvon-kit/core' |

## 타입

| 유형 | 설명 |
| --- | --- |
| `VonvonUser` | 인증된 사용자의 읽기 전용 보기 (비밀값 및 해시 제외) |
| `VonvonOrganization` | 공개 조직 보기 |
| `VonvonOrganizationMembership` | 역할 및 권한이 포함된 조직 내 사용자 멤버십 |
| `VonvonSession` | 상태, 만료, 활성 조직을 포함한 세션 보기 |
| `VonvonApiKey` | 비밀값이 없는 API 키 (목록 보기) |
| `VonvonApiKeyWithSecret` | 생성 시 한 번만 반환되는 API 키; key 필드 포함 |
| `VonvonPage<T>` | cursor 기반 페이지네이션 응답 envelope |
| `CreateApiKeyInput` | createApiKey 입력 |
| `SignInPasswordInput` | signInPassword 입력 |
| `SignInResult` | signInPassword 결과: 다음 단계 또는 리디렉션 URL |
| `SessionStatus` | SESSION\_STATUS 값의 union |
| `ClientStatus` | CLIENT\_STATUS 값의 union |
| `VonvonState` | VonvonStore에서 구독하는 전체 SDK 상태 스냅샷 |
| `VonvonStateListener` | 상태 변경 리스너 callback 타입 |
| `Unsubscribe` | VonvonStore.subscribe의 반환 타입 |
| `GetTokenOptions` | getToken 옵션: skipCache, leewaySeconds, signal |
| `VonvonClientOptions` | 판별 가능한 VonvonClient constructor options입니다. same-origin은 apiUrl, secretKey, fetcher, now를 허용하고 oidc에는 issuer, clientId, redirectUri가 필요합니다. |
| `TokenResponse` | token 엔드포인트 응답 원본 형태 |
| `ClientStateResponse` | /v1/me 응답 원본 형태 |
| `DecodedTokenClaims` | decodeTokenClaims가 반환하는 JWT 페이로드 클레임 |

## 관련 문서

프레임워크 바인딩: [@vonvon-kit/react](/ko/sdks/react). 서버 검증: [@vonvon-kit/backend](/ko/sdks/backend).

Source: https://vonvon.id/ko/sdks/core/index.mdx