SDK 레퍼런스

import { Saemol } from '@saemol/sdk'

const saemol = new Saemol({
  secret: process.env.SAEMOL_SECRET!,   // 필수 — 연동 정보 카드의 연동 시크릿
})

// valid: true
{ valid: true, status: 'active', kind: 'license', plan_name: 'Pro',
  sku: 'com.myapp.pro' | null,
  devices: { registered: 2, limit: 3 | null },
  expires_at: '2026-08-05T…' | null,   // 기간제·trial 만료 (null=무기한)
  is_trial: false }

// valid: false
{ valid: false, reason: 'revoked' | 'expired' | 'suspended'
        | 'device_limit_exceeded' | 'version_not_allowed' | …,
  status?, devices?, allowed_versions?, expires_at?, is_trial? }

// 키가 조회되면 상태와 무관하게 전체 응답 (valid만 false일 수 있음)
{ valid: boolean, status: 'active' | 'expired' | 'revoked' | …,
  kind: 'subscription' | 'usage' | 'api' | …, plan_name: 'Pro' | null,
  plan_features: ['core', 'advanced'] | null, rate_limit_per_min: 60 | null,
  usage: { unit, used, limit } | null,        // kind가 usage일 때만
  current_period_end: '…' | null, expires_at: '…' | null, is_trial: boolean }

// 버전 미허용 등 거부 응답 (reason 존재 여부로 판별)
{ valid: false, reason: 'version_not_allowed', allowed_versions: ['1.0'], … }

{ accepted: true,
  allowed: boolean,          // false = 초과 정책 block → 사용 차단
  usage: { unit, used, limit, remaining },
  overage_policy: 'notify' | 'block',
  over_limit: boolean }

{ product_id, latest_version: '1.4.0' | null,
  update_available: boolean,   // currentVersion < latest
  update_required: boolean,    // currentVersion < min_version → 강제 업데이트
  min_version: '1.0.0' | null, download_url: '…' | null, release_notes: '…' | null }

// found: true — 키 소유 구매자 컨텍스트
{ found: true, entitlement_id, kind, status: 'active' | 'expired' | …,
  plan_name: 'Pro' | null, is_trial: boolean, expires_at: '…' | null,
  user: { id, name, email } }

// found: false (키 미존재 — 던지지 않고 반환)
{ found: false, reason: '…' }

const checkout = await saemol.createCheckout({
  itemCode: 'pro_monthly',
  appUserId: loggedInUser.id,
  idempotencyKey: savedPurchaseAttempt.id,
})
// checkout.url로 이동. 복귀 URL만으로 결제 완료를 판단하지 않습니다.

if (!(await saemol.canAccess({ apiKey, feature: 'export' }))) return denyAccess()
const { url } = await saemol.customerPortal() // 새몰 로그인 후 본인 서비스 관리

import { SaemolOAuth, isSubscriptionActive, hasPlanFeature } from '@saemol/sdk'

const oauth = new SaemolOAuth({
  clientId:     process.env.SAEMOL_OAUTH_CLIENT_ID!,
  clientSecret: process.env.SAEMOL_OAUTH_CLIENT_SECRET!,
  redirectUri:  'https://app.example.com/auth/callback',
})

// 1) 로그인 버튼 — state(CSRF)는 SDK가 생성해 반환
const { url, state } = oauth.createAuthorizationUrl()
session.oauthState = state
redirect(url)

// 2) 콜백 — 오류 확인·state 검증·토큰 교환·userinfo를 한 번에
const { user, tokens } = await oauth.handleCallback({
  url:           req.url,
  expectedState: session.oauthState,
})

if (!isSubscriptionActive(user)) return showPricing()
if (hasPlanFeature(user, 'advanced')) enableAdvanced()

import { SaemolApiError, SaemolNetworkError } from '@saemol/sdk'

try {
  const result = await saemol.verifyLicense({ licenseKey })
} catch (err) {
  if (err instanceof SaemolApiError)     log(err.status, err.reason, err.requestId)  // 설정 점검
  if (err instanceof SaemolNetworkError) retryLater(err.timedOut)
}

curl -X POST https://saemol.com/api/v1/licenses/verify \
  -H 'Content-Type: application/json' \
  -H 'X-Saemol-Secret: <연동 시크릿>' \
  -d '{ "license_key": "MF-XXXX-XXXX-XXXX-XXXX", "device_id": "machine-abc" }'