@designbasekorea/figma-license-core

Figma 플러그인의 라이선스 상태/사용량 정책/기능 제한을 공통으로 처리하는 패키지입니다.

핵심 기능

• 라이선스 상태 판별
  • hasLicenseKey: 라이선스 키가 저장되어 있는지
  • isLicenseRegistered: 실제 유효 등록(PAID + key) 상태인지
• 티어별 사용량 정책
• 일간 리셋 (daily), 주간 리셋 (weekly), 월간 리셋 (monthly), 리셋 없음 (none)
  • limit: number | 'unlimited'
• 티어별 기능 제한
  • allow/deny 기반 기능 접근 제어
• Figma 메시지 연동
  • 기본: initialize, verify-license, deactivate-license
  • 추가: check-feature-access, consume-usage

빠른 시작

import { createFigmaLicenseStatusManager } from '@designbasekorea/figma-license-core';

const statusManager = createFigmaLicenseStatusManager({
  config: {
    productId: 'korean-dummy-plugin',
    endpoint: 'https://api.example.com/license/verify',
    deactivateEndpoint: 'https://api.example.com/license/deactivate',
    instanceName: figma.root?.name || 'korean-dummy-plugin',
    storagePrefix: 'korean-dummy-plugin-license',
    policy: {
      defaultTier: 'FREE',
      freeTier: 'FREE',
      paidTier: 'PRO',
      usageByTier: {
        FREE: { limit: 10, reset: 'daily' },
        PRO: { limit: 20, reset: 'monthly' },
        ENTERPRISE: { limit: 'unlimited', reset: 'none' },
      },
      featuresByTier: {
        FREE: { deny: ['bulk_apply', 'advanced_batch'] },
        PRO: { deny: [] },
        ENTERPRISE: { defaultAllowed: true },
      },
    },
  },
});

statusManager.bindToOnMessage(async (msg) => {
  if ((msg as { type?: string }).type === 'process') {
    // 기존 플러그인 로직
  }
});

await statusManager.initialize();

메시지 계약

UI -> Main

• initialize
• verify-license (licenseKey 포함)
• deactivate-license
• check-feature-access (featureKey 선택)
• consume-usage (amount, featureKey 선택)

amount가 남은 수량보다 크면 소비되지 않습니다. 마지막 1회를 소비한 응답도 success: true, remaining: 0으로 반환되므로 실행 성공 여부와 다음 차단 상태를 혼동하지 않습니다.

플러그인 공통 사용 규칙

모든 플러그인은 기능 실행 직전에 같은 순서를 사용합니다.

const access = await statusManager.canUseFeature('bulk_apply', 1);
if (!access.allowed) {
  // access.reason === 'FEATURE_NOT_ALLOWED' 또는 'USAGE_LIMIT_REACHED'
  return;
}

const result = await statusManager.consumeUsage(1, 'bulk_apply');
if (!result.consumed) {
  return;
}

await runBulkApply();

UI 메시지를 사용하는 경우에는 check-feature-access로 미리 확인한 뒤 consume-usage를 실행 직전에 전송합니다. 서버에서 최종 권한을 판정하는 제품은 동일한 feature key를 서버와 코어 설정에 사용해야 합니다.

Main -> UI

• update-plugin-status
• license-verification-result
• license-deactivation-result
• feature-access-result
• usage-consume-result

에러 코드

• ACTIVATION_LIMIT_REACHED
• INVALID_LICENSE
• PRODUCT_MISMATCH
• NETWORK_ERROR
• STORAGE_ERROR
• SERVER_ERROR
• UNKNOWN_ERROR

운영 권장사항

• 운영 배포에서는 masterCode를 사용하지 마세요.
• 최종 권한 판정은 서버 검증 결과 기준으로 처리하세요.
• 클라이언트 상태(paymentStatus, usageCount)는 변조 가능하다고 가정하세요.
• 모든 플러그인의 리셋 단위·무료 한도·차단 기능은 policy에서만 선언하고, 플러그인별 임의 카운터를 추가하지 마세요.

문서

• 상세 적용 가이드: docs/PLUGIN_INTEGRATION_KO.md