@xid-kit/core

세션 상태, 단기 JWT 접근, 관리 API 헬퍼를 위한 브라우저 클라이언트입니다.

설치 및 설정

apiUrl을 XID 인스턴스 origin (호스팅 또는 셀프 호스팅)으로 지정하세요. SDK는 클라이언트 비밀값을 저장하지 않으며 refresh token 자료를 브라우저 스크립트에 노출하지 않습니다.

import { XidClient } from '@xid-kit/core'

const xid = new XidClient({ apiUrl: 'https://xid.dev' })
await xid.load()
const token = await xid.getToken()

세션 수명주기

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

관리 API 헬퍼

현재 버전은 API 키 관리만 래핑합니다. 다른 모든 관리 API 리소스는 Authorization: Bearer sk_live_xxx를 사용한 직접 /v1/ REST 호출이 필요합니다.

const keys = await xid.listApiKeys()
const created = await xid.createApiKey({ name: 'CI deploy', scopes: ['read'] })
await xid.revokeApiKey(created.id)

내보내진 API

내보내기	종류	목적
`XidClient`	class	최상위 브라우저 클라이언트: load, signIn, getToken, setActiveOrganization, signOut 및 관리 API 헬퍼
`XidStore`	class	프레임워크에 독립적인 반응형 store; 프레임워크 바인딩에서 useSyncExternalStore로 구독합니다
`TokenManager`	class	단기 JWT 캐시 및 예약 갱신 (고급 사용 및 테스트)
`XidApiClient`	class	/v1/me 및 token 엔드포인트용 HTTP 클라이언트
`XidNetworkError`	class	전송 실패 시 던집니다: 네트워크 오류, JSON이 아닌 응답, 구조화된 본문이 없는 5xx
`makeXidError`	function	네트워크 왕복 없이 로컬 검증 실패에 대한 구조화된 XidError를 생성합니다
`isXidErrorShape`	function	타입 가드: 알 수 없는 값이 네트워크의 XidError 형태를 따르는지 확인합니다
`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`	문자열 상수	패키지 이름 식별자 ‘@xid-kit/core’

타입

유형	설명
`XidUser`	인증된 사용자의 읽기 전용 보기 (비밀값 및 해시 제외)
`XidOrganization`	공개 조직 보기
`XidOrganizationMembership`	역할 및 권한이 포함된 조직 내 사용자 멤버십
`XidSession`	상태, 만료, 활성 조직을 포함한 세션 보기
`XidApiKey`	비밀값이 없는 API 키 (목록 보기)
`XidApiKeyWithSecret`	생성 시 한 번만 반환되는 API 키; key 필드 포함
`XidPage<T>`	cursor 기반 페이지네이션 응답 envelope
`CreateApiKeyInput`	createApiKey 입력
`SignInPasswordInput`	signInPassword 입력
`SignInResult`	signInPassword 결과: 다음 단계 또는 리디렉션 URL
`SessionStatus`	SESSION_STATUS 값의 union
`ClientStatus`	CLIENT_STATUS 값의 union
`XidState`	XidStore에서 구독하는 전체 SDK 상태 스냅샷
`XidStateListener`	상태 변경 리스너 callback 타입
`Unsubscribe`	XidStore.subscribe의 반환 타입
`GetTokenOptions`	getToken 옵션: template, skipCache, leewaySeconds, signal
`XidClientOptions`	XidClient 생성자 옵션: apiUrl, fetcher, now
`TokenResponse`	token 엔드포인트 응답 원본 형태
`ClientStateResponse`	/v1/me 응답 원본 형태
`DecodedTokenClaims`	decodeTokenClaims가 반환하는 JWT 페이로드 클레임