Entitlement

이 페이지의 API·SDK·catalog 계약은 Billing Authority를 채택한 제품에 적용됩니다. 다른 실행 구조는 아키텍처 경계를 따릅니다.

Entitlement는 제품이 기능 접근을 판단할 때 신뢰하는 유일한 결제 관련 결과입니다. 제품은 PG 상태, subscription status, 결제 시각을 자체 해석하지 않습니다.

서비스 서버 예시

예정 소비 계약

SDK 0.1.1의 기존 배포 기록과 staging 실행은 확인됐습니다. 제품별 production 조회 API는 미확인입니다. 실제 채택은 현재 제공 상태와 대상 런타임의 운영 검증 기록을 확인한 뒤 진행하십시오.

import { createControlPlaneServiceClient } from '@leysys/control-plane-client'

const entitlements = createControlPlaneServiceClient({
  baseUrl: process.env.LEYSYS_CONTROL_PLANE_URL!,
  serviceToken: process.env.LEYSYS_CONTROL_PLANE_SERVICE_TOKEN!,
})

const snapshot = await entitlements.getEntitlements({
  accountId: leysysAccountId,
  productKey: 'ad-project',
})

const mayPrint = snapshot.scopes.includes('forms:print')

Service token은 제품의 server runtime에만 둡니다. 브라우저 bundle, 모바일 앱, VITE_*, NUXT_PUBLIC_*, 저장소 파일에 넣지 않습니다.

ad-project 최초 scope

다음 네 개가 최초 정본입니다. 비슷한 이름을 제품에서 새로 만들지 않습니다.

Scope	의미
ads:hidden	광고 숨김
forms:save	양식 저장
forms:pdf	PDF 출력 생성
forms:print	인쇄 기능

Fail closed

다음 경우 해당 기능을 허용하지 않습니다.

• scope가 없음
• entitlement가 만료·정지됨
• 서명이 검증되지 않거나 응답 형식이 잘못됨
• account 또는 productKey가 요청 맥락과 다름
• control plane 조회가 실패하고 승인된 짧은 캐시도 없음

가용성을 이유로 제품이 로컬 paid=true 같은 별도 정본을 만들면 안 됩니다. 캐시가 필요하면 snapshot의 만료·버전 계약을 control plane이 정의해야 합니다.

권한 정의 변경

scope 추가·삭제·의미 변경은 product catalog migration, 호환성 분석, 서비스별 사용처 검사, entitlement fixture를 함께 변경하는 계약 작업입니다. provider webhook mapping만 바꿔서 권한을 변경하지 않습니다.