버전 관리

핵심 요약

REST API 경로는 /api/v1을 사용하지만, 라이선스 wire 계약에는 버전 협상 기능이 아직 없습니다.

패키지를 업데이트하기 전에 SDK·백엔드 호환성 표를 확인하세요. 같은 v1 표기라도 자동 호환을 의미하지 않습니다.

정직한 답변: 협상이 없습니다

REST 표면은 /api/v1 접두어이고, 라이선스 wire는 계약 v1 — 암묵적입니다: entitlement 클레임, 헤더, 엔벨로프에 버전 필드가 존재하지 않고 sdk/license/*에 협상 로직도 없습니다 (known-limitations §3.2, NOT_IMPLEMENTED).

오늘 "v1"이 의미하는 것

호환성은 **"동일 계약 세대"**입니다 — 모든 구성 요소가 현재 형태에 동의합니다; v0이나 v2를 말하는 메커니즘은 없습니다:

구성 요소	버전	계약
@yetdapay/license-web / -server / -nuxt	0.1.0	wire v1
@yetdapay/cli (yp)	0.2.0	로컬 툴링; 아직 라이선스 wire 호출 없음
@yetdapay/sdk	0.1.0	기부/피드백 REST
yetdapay-mcp / yetdapay-mcp-gateway	0.1.0	MCP 프로토콜 2024-11-05, REST 클라이언트
백엔드	리포 SHA 버전	REST /api/v1/**; PoP wire v1 (Worker 전용)

알려진 wire-v2 후보

결정되면 토큰/계약 형식을 변경할 연기된 항목들(매트릭스 §5):

• Worker entitlement의 aud(DEFERRED — 발급도 검증도 안 함).
• Worker entitlement의 tenant_id(DEFERRED — 동일한 wire 형식 영향).
• 오류 코드 수렴(INVALID_PUBLIC_JWK, CAPABILITY_INVALID, PAYLOAD_TOO_LARGE, INVALID_STATUS) — 오늘은 문서화된 델타; 통일은 문서 수정이 아닌 wire-v2 결정입니다.

상호운용 주의 (문서화된 블로커)

SDK 기본값(activatePath: /api/license/activate, iss: devpay, 선택적 aud)은 Worker 값(/api/v1/licenses/activate, iss: devpay-lic, aud 없음)과 일치하지 않습니다. 상호 상호운용은 명시적 설정에서만 입증됩니다 — 양쪽의 createWorkerConfig() 프리셋이 지원되는 브릿지입니다 (SDK worker 프리셋과 계약 매트릭스 §3 참조).