@designbasekorea/figma-license-core 0.1.0 → 0.3.0

package/docs/PLUGIN_INTEGRATION_KO.md

@@ -0,0 +1,331 @@
+# Figma 플러그인 적용 가이드 (Korean)
+
+이 문서는 `@designbasekorea/figma-license-core`를 실제 플러그인(`controller.ts`)에 붙일 때의 기준 문서입니다.
+
+## 1) 해결하는 문제
+
+- 라이선스 등록 여부 통일
+  - 키가 있는지 (`hasLicenseKey`)
+  - 실제 유효 등록인지 (`isLicenseRegistered`)
+- 유료/무료 티어별 사용 범위 통일
+  - 일일 N회, 주간 N회, 월간 N회, 무제한
+- 티어별 기능 제한 통일
+  - 예: 무료는 무제한 사용 가능하지만 일부 기능 차단
+
+## 2) 기본 연결 패턴
+
+`code.ts` 또는 `controller.ts`에서 매니저 생성:
+
+```ts
+import { createFigmaLicenseStatusManager } from '@designbasekorea/figma-license-core';
+
+const licenseManager = createFigmaLicenseStatusManager({
+  config: {
+    productId: 'korean-dummy-plugin',
+    endpoint: 'https://api.example.com/license/verify',
+    deactivateEndpoint: 'https://api.example.com/license/deactivate',
+    instanceName: 'korean-dummy-plugin',
+    storagePrefix: 'korean-dummy-plugin-license',
+    policy: {
+      freeTier: 'FREE',
+      paidTier: 'PRO',
+      usageByTier: {
+        FREE: { limit: 10, reset: 'daily' },
+        PRO: { limit: 20, reset: 'monthly' },
+      },
+      featuresByTier: {
+        FREE: { deny: ['bulk_apply', 'multi_instance_apply'] },
+      },
+    },
+  },
+});
+
+licenseManager.bindToOnMessage(async (msg) => {
+  // 기존 controller switch 로직을 fallback으로 유지
+});
+```
+
+## 2-1) 디자인베이스 계정/멤버십 기반 연결 패턴
+
+디자인베이스 LMS의 멤버십/상품 결제 권한으로 피그마 플러그인을 열려면 `DesignbaseAccountAuthClient`와
+`DesignbaseAccountLicenseTransport`를 같이 사용합니다.
+
+흐름:
+
+1. UI에서 "디자인베이스로 로그인/결제" 버튼 클릭
+2. 플러그인 main이 `authClient.start()` 호출
+3. 반환된 `authUrl`을 `figma.openExternal(authUrl)`로 열기
+4. 플러그인은 `authClient.poll(sessionId, pollToken)`을 반복 호출
+5. 사용자가 사이트에서 로그인/멤버십/결제를 완료하면 poll 결과가 `active`가 됨
+6. `authClient.saveTokens(result)` 후 `licenseCore.verifyLicense(result.licenseKey)` 호출
+
+```ts
+import {
+  DesignbaseAccountAuthClient,
+  DesignbaseAccountLicenseTransport,
+  LicenseCore,
+  FigmaStorageAdapter,
+  FigmaNotifierAdapter,
+} from '@designbasekorea/figma-license-core';
+
+const storage = new FigmaStorageAdapter(figma);
+const notifier = new FigmaNotifierAdapter(figma);
+
+const authClient = new DesignbaseAccountAuthClient({
+  baseUrl: 'https://designbase.co.kr',
+  storage,
+  storagePrefix: 'korean-dummy-plugin-account',
+});
+
+const transport = new DesignbaseAccountLicenseTransport({
+  baseUrl: 'https://designbase.co.kr',
+  storage,
+  storagePrefix: 'korean-dummy-plugin-account',
+});
+
+const licenseCore = new LicenseCore(
+  {
+    productId: 'korean-dummy-plugin',
+    endpoint: 'https://designbase.co.kr/wp-json/custom/v1/product/status',
+    instanceName: 'korean-dummy-plugin',
+    storagePrefix: 'korean-dummy-plugin-license',
+    policy: {
+      freeTier: 'FREE',
+      paidTier: 'PRO',
+      usageByTier: {
+        FREE: { limit: 10, reset: 'daily' },
+        PRO: { limit: 'unlimited', reset: 'none' },
+      },
+    },
+  },
+  { storage, transport, notifier },
+);
+
+async function startDesignbaseAccountAuth() {
+  const deviceId = await getOrCreateDeviceId();
+  const started = await authClient.start({
+    pluginCode: 'korean-dummy-plugin',
+    deviceId,
+    returnUrl: 'https://www.figma.com/community/plugin/YOUR_PLUGIN_ID',
+  });
+
+  figma.openExternal(started.authUrl);
+
+  const expiresAt = Date.now() + started.expiresIn * 1000;
+  while (Date.now() < expiresAt) {
+    await wait(started.pollInterval * 1000);
+    const result = await authClient.poll(started.sessionId, started.pollToken);
+
+    if (result.status === 'active' && result.licenseKey) {
+      await authClient.saveTokens(result);
+      await licenseCore.verifyLicense(result.licenseKey);
+      figma.notify('디자인베이스 계정 권한이 확인되었습니다.');
+      return;
+    }
+
+    if (['expired', 'access_denied'].includes(result.status)) {
+      throw new Error(result.message || '디자인베이스 인증에 실패했습니다.');
+    }
+  }
+
+  throw new Error('인증 시간이 만료되었습니다. 다시 시도해 주세요.');
+}
+
+async function getOrCreateDeviceId(): Promise<string> {
+  const stored = await figma.clientStorage.getAsync('designbase-device-id');
+  if (typeof stored === 'string' && stored) {
+    return stored;
+  }
+
+  const id = `figma-${Date.now()}-${Math.random().toString(36).slice(2)}`;
+  await figma.clientStorage.setAsync('designbase-device-id', id);
+  return id;
+}
+
+function wait(ms: number): Promise<void> {
+  return new Promise((resolve) => setTimeout(resolve, ms));
+}
+```
+
+LMS 서버 엔드포인트:
+
+- `POST /wp-json/custom/v1/figma/auth/start`
+- `POST /wp-json/custom/v1/figma/auth/poll`
+- `GET /wp-json/custom/v1/figma/auth/complete`
+- 이후 검증: `GET /wp-json/custom/v1/product/status?plugin_code=...` with `Authorization: Bearer ...`
+
+보안 기준:
+
+- `start`에서 생성되는 complete 토큰과 poll 토큰은 서로 다릅니다.
+- 서버에는 원본 토큰을 저장하지 않고 SHA-256 해시만 저장합니다.
+- 세션은 1시간 후 만료됩니다.
+- poll 토큰 없이는 계정 토큰을 받을 수 없습니다.
+- `returnUrl`은 `figma.com` 또는 `figma://`만 허용합니다.
+
+## 2-2) PageLicense UI 메시지 (figma-ui)
+
+`@designbasekorea/figma-ui`의 `PageLicense`는 `figma-license-core`와 동일한 메시지 타입을 사용합니다.
+
+UI → main 추가 메시지:
+
+- `start-designbase-auth` — WordPress 계정 로그인/멤버십 인증 시작 (`DesignbaseAccountAuthClient.start` 연동)
+- `open-external-url` — `{ url }` 외부 브라우저 열기 (`figma.openExternal` 권장)
+
+main → UI 추가 메시지:
+
+- `designbase-auth-result` — `{ success, message, ...statusFields }` 계정 인증 결과
+
+`update-plugin-status` 페이로드는 `FigmaLicenseStatusManager.postStatusUpdate()`와 동일합니다.
+
+## 2-3) YouTube 멤버십 All-Access UI
+
+상품별 가격표가 필요 없는 플러그인은 `PageLicense`를 멤버십 모드로 사용합니다. 이 모드에서는 가격, 달러 금액,
+Lifetime 결제 문구를 렌더링하지 않고 웹사이트 랜딩 페이지와 월간 키 입력만 제공합니다.
+
+```tsx
+import { PageLicense } from '@designbasekorea/figma-ui';
+
+<PageLicense
+  status="FREE"
+  mode="youtube-membership"
+  membershipUrl="https://designbase.co.kr/membership/"
+  enableAccountAuth={false}
+  onClose={() => setShowLicense(false)}
+/>;
+```
+
+활성화된 경우 공통 상태 카드가 `source`, `access scope`, `expires at`, `last checked`를 표시합니다. 키는 기본적으로
+마스킹되며, 서버가 최종 권한을 결정합니다. 플러그인 실행 시 `initialize()`가 서버 검증을 완료할 때까지 유료 상태를
+신뢰하지 않으며, 만료·철회·네트워크·요청 제한 오류는 무료 상태로 전환해 기능을 잠급니다.
+
+공통 멤버십 UI는 `LicenseOffer`, `LicenseStatusCard`로도 개별 조합할 수 있으므로, 플러그인별 화면을 만들 때 라이선스
+검증·표시 코드를 복제하지 않습니다.
+
+## 3) UI 표기 데이터
+
+`update-plugin-status` 메시지에 아래 값들이 포함됩니다.
+
+- `hasLicenseKey`
+- `isLicenseRegistered`
+- `paymentStatus`
+- `planTier`
+- `remainingUsage`
+- `usageUsed`
+- `usageReset` (`none`/`daily`/`weekly`/`monthly`)
+- `usageReason` (`USAGE_LIMIT_REACHED`/`FEATURE_NOT_ALLOWED`)
+- `licenseStatus`
+- `licenseSource`
+- `accessScope`
+- `expiresAt`
+- `lastVerifiedAt`
+- `validationMessage`
+
+UI 예시:
+
+- FREE + daily + 10회 정책: "오늘 남은 횟수 6/10"
+- FREE + weekly + 30회 정책: "이번 주 남은 횟수 18/30"
+- PRO + monthly + 20회 정책: "이번 달 남은 횟수 12/20"
+- FREE + unlimited + feature deny: "사용 횟수 제한 없음, 고급 기능 잠김"
+
+## 4) 기능별 제한 체크
+
+사용 전에 기능 접근 가능 여부 확인:
+
+```ts
+parent.postMessage({ pluginMessage: { type: 'check-feature-access', featureKey: 'bulk_apply' } }, '*');
+```
+
+응답: `feature-access-result`
+
+- `allowed === false` 이고 `reason === 'FEATURE_NOT_ALLOWED'` 이면 기능 차단
+- `allowed === false` 이고 `reason === 'USAGE_LIMIT_REACHED'` 이면 업그레이드/리셋 안내
+
+## 5) 사용량 소모 처리
+
+기능 실행 전 접근 가능 여부를 확인하고, 실제 작업을 시작하기 직전에 사용량을 소모합니다.
+`amount`가 남은 수량보다 크면 코어가 소비하지 않습니다. 소비된 시도는 작업이
+외부 API 오류로 실패하더라도 재시도로 한도를 우회하지 못하도록 사용량에 포함됩니다.
+
+```ts
+parent.postMessage({ pluginMessage: { type: 'consume-usage', amount: 1, featureKey: 'bulk_apply' } }, '*');
+```
+
+응답: `usage-consume-result`
+
+- `success`가 `true`면 소모 완료. 마지막 1회 소비도 `success: true`, `remaining: 0`입니다.
+- `success`가 `false`면 차단 상태
+
+## 6) 정책 샘플
+
+### A. 무료 일 10회, 프로 월 20회
+
+```ts
+policy: {
+  freeTier: 'FREE',
+  paidTier: 'PRO',
+  usageByTier: {
+    FREE: { limit: 10, reset: 'daily' },
+    PRO: { limit: 20, reset: 'monthly' },
+  },
+}
+```
+
+### A-1. 무료 주 30회
+
+```ts
+policy: {
+  usageByTier: {
+    FREE: { limit: 30, reset: 'weekly' },
+  },
+}
+```
+
+### B. 무료 무제한 + 일부 기능 제한
+
+```ts
+policy: {
+  freeTier: 'FREE',
+  usageByTier: {
+    FREE: { limit: 'unlimited', reset: 'none' },
+  },
+  featuresByTier: {
+    FREE: { deny: ['bulk_apply', 'advanced_batch'] },
+  },
+}
+```
+
+### C. 엔터프라이즈 완전 무제한
+
+```ts
+policy: {
+  usageByTier: {
+    ENTERPRISE: { limit: 'unlimited', reset: 'none' },
+  },
+  featuresByTier: {
+    ENTERPRISE: { defaultAllowed: true },
+  },
+}
+```
+
+## 7) 기존 controller.ts 마이그레이션 팁
+
+- 기존 `StatusManager` 인터페이스를 즉시 제거하지 말고, 1차로 호환 어댑터를 두세요.
+- `decrementUsageCount`는 내부적으로 `consumeUsage` 또는 `consume-usage`로 연결하세요.
+  기존 `incrementUsage`는 호환용 저수준 API로만 남기고 새 기능에서는 사용하지 마세요.
+- UI에서 `usageCount`만 보던 경우, 앞으로는 `remainingUsage` + `usageReset` 조합으로 표기하세요.
+
+## 8) 운영 체크리스트
+
+- 운영 환경에서 `masterCode` 제거
+- 서버에서 라이선스 최종 검증
+- 클라이언트 상태 변조 대비
+- 실패 메시지(`errorCode`)를 UI에 그대로 매핑하여 대응
+
+## 9) 여러 플러그인에 일괄 적용하는 운영 규칙
+
+- 각 플러그인에는 라이선스 검증·상태 카드·멤버십 안내 코드를 복사하지 않고 `@designbasekorea/figma-license-core`와 `@designbasekorea/figma-ui`만 의존합니다.
+- 라이브러리 변경은 Changeset으로 `figma-license-core`와 `figma-ui` 버전을 함께 올린 뒤 패키지를 배포합니다.
+- 플러그인은 테스트 단계에서 새 버전을 정확히 고정하고, Face Dummy에서 활성·만료·철회·요청 제한·네트워크 실패를 확인한 다음 다른 플러그인으로 확장합니다.
+- 운영 플러그인에 `masterCode`를 넣지 않고, WordPress 서버를 권한의 최종 원천으로 유지합니다.
+- 무료 한도와 차단 기능은 각 플러그인의 임의 상태 관리자가 아니라 `figma-license-core`의
+  `policy.usageByTier`와 `policy.featuresByTier`에서 선언합니다.

package/package.json

@@ -1,12 +1,13 @@
 {
   "name": "@designbasekorea/figma-license-core",
-  "version": "0.1.0",
+  "version": "0.3.0",
   "description": "Figma plugin license core and status manager for reusable license workflows",
   "main": "dist/index.js",
   "module": "dist/index.esm.js",
   "types": "dist/index.d.ts",
   "files": [
-    "dist"
+    "dist",
+    "docs"
   ],
   "scripts": {
     "build": "rollup -c",
@@ -20,12 +21,12 @@
   "devDependencies": {
     "@rollup/plugin-commonjs": "^25.0.4",
     "@rollup/plugin-node-resolve": "^15.2.1",
-    "@rollup/plugin-typescript": "^11.1.3",
+    "@rollup/plugin-typescript": "^12.3.0",
     "@types/jest": "^29.5.5",
     "jest": "^29.6.4",
     "jest-environment-jsdom": "^29.6.4",
     "rimraf": "^5.0.1",
-    "rollup": "^3.29.2",
+    "rollup": "^4.63.1",
     "typescript": "^5.2.2"
   },
   "publishConfig": {