TypeScript 类型定义

SDK 导出完整的 TypeScript 类型，所有类型从 @atomm-developer/generator-sdk 直接导入：

import type {
  // 初始化
  SdkEnv,              // 'prod' | 'pre' | 'test' | 'dev'
  SdkInitOptions,      // { appKey: string, env?: SdkEnv }

  // Auth
  AuthStatus,          // { isLogin: boolean, userInfo: UserInfo | null }
  UserInfo,            // { uid, uuid, userName, headpic, email, ... }
  AuthChangeCallback,  // (status: AuthStatus) => void

  // Cloud
  CloudSaveOptions,    // { title?, snapshot, cover?, originImage?, id? }
  CloudSaveResult,     // { id: number, isNew: boolean }
  CloudRecord,         // { id, title, cover, snapshot, originImageUrl, createdAt, updatedAt }

  // History
  HistoryListOptions,  // { page?, pageSize? }
  HistoryListResult,   // { total: number, items: HistoryItem[] }
  HistoryItem,         // { id, title, cover, createdAt, updatedAt }

  // Credits
  CreditsConsumeOptions,  // { amount: number, action: string }
  CreditsConsumeResult,   // { success: boolean, balance: number, transactionId: string }
  CreditsChangeCallback,  // (balance: number) => void

  // Billing
  UsageInfo,             // { freeRemaining, freeTotal, creditsPerUse, creditsBalance, ... }
  BillingCheckResult,    // { canProceed: boolean, reason: string }
  BillingConsumeOptions, // { externalId?: string }
  BillingConsumeResult,  // { freeRemaining: number, isCredit: boolean, isBlacklisted?: boolean }
  BillingChangeCallback, // (usage: UsageInfo) => void

  // Export
  ExportPurpose,           // 'download' | 'studio' | 'cover'
  ExportFormat,            // 'png' | 'jpeg' | 'webp' | 'svg'
  ExportData,              // { type: 'canvas'|'blob'|'dataUrl'|'url'|'svg', ... }
  ExportProvider,          // { getExportData?, getExportCanvas?, getFileName? }
  ExportDownloadOptions,   // { fileName?, format?, quality? }
  ExportDownloadResult,    // { success: boolean, fileName: string }
  ExportOpenInStudioResult, // { success: boolean }
  ExportOpenInStudioSource, // string | Blob | File
  ExportOpenInStudioOptions, // { source?, format? }

  // Template
  PanelFilter,                  // { includeFields?, excludeFields?, readonlyFields?, ... }
  PanelSchema,                  // { version?, generatorId?, groups: PanelGroup[] }
  TemplateFieldOption,          // { groupId, fieldId, path, ... }
  GeneratorTemplateDefinition,  // 标准模板 JSON 协议
  TemplateBuildOptions,         // build() 参数
  TemplateDownloadOptions,      // { fileName? }
  TemplateRuntimeSnapshot,      // { state, panelFilter }
  TemplateRuntime,              // { setState(...) }
  TemplateApplyOptions,         // { source?, onPanelFilter? }

  // withBilling
  WithBillingResult,       // { result: T, billing: BillingConsumeResult }
} from '@atomm-developer/generator-sdk'

类型详解

初始化相关

type SdkEnv = 'prod' | 'pre' | 'test' | 'dev'

interface SdkInitOptions {
  appKey: string
  env?: SdkEnv
}

Auth 相关

interface UserInfo {
  uid: number
  uuid: string
  userName: string
  headpic: string
  email: string
  phoneNumber: string
  phoneZone: string
  gender: number        // 0=未知 / 1=男 / 2=女
  signature: string
  createTime: number    // Unix 秒
}

interface AuthStatus {
  isLogin: boolean
  userInfo: UserInfo | null
}

type AuthChangeCallback = (status: AuthStatus) => void

Cloud 相关

interface CloudSaveOptions {
  title?: string
  snapshot: Record<string, unknown>
  cover?: HTMLCanvasElement | string | null
  originImage?: HTMLCanvasElement | string | null
  id?: number | null
}

interface CloudSaveResult {
  id: number
  isNew: boolean
}

interface CloudRecord {
  id: number
  title: string
  cover: string
  snapshot: Record<string, unknown>
  originImageUrl: string | null
  createdAt: number
  updatedAt: number
}

History 相关

interface HistoryListOptions {
  page?: number
  pageSize?: number
}

interface HistoryListResult {
  total: number
  items: HistoryItem[]
}

interface HistoryItem {
  id: number
  title: string
  cover: string
  createdAt: number
  updatedAt: number
}

Credits 相关

interface CreditsConsumeOptions {
  amount: number
  action: string
}

interface CreditsConsumeResult {
  success: boolean
  balance: number
  transactionId: string
}

type CreditsChangeCallback = (balance: number) => void

Billing 相关

interface UsageInfo {
  isEnabled: boolean
  freeRemaining: number
  freeTotal: number
  creditsPerUse: number
  creditsBalance: number
  inFreePeriod: boolean
  freePeriodRemaining: number
}

interface BillingCheckResult {
  canProceed: boolean
  reason: 'free_period' | 'free_count' | 'credits' | 'insufficient'
}

interface BillingConsumeOptions {
  externalId?: string
}

interface BillingConsumeResult {
  freeRemaining: number
  isCredit: boolean
  isBlacklisted?: boolean
}

type BillingChangeCallback = (usage: UsageInfo) => void

Export 相关

type ExportPurpose = 'download' | 'studio' | 'cover'

type ExportFormat = 'png' | 'jpeg' | 'webp' | 'svg'

type ExportData =
  | { type: 'canvas'; canvas: HTMLCanvasElement }
  | { type: 'blob'; blob: Blob }
  | { type: 'dataUrl'; dataUrl: string }
  | { type: 'url'; url: string }
  | { type: 'svg'; svgString: string }

interface ExportProvider {
  getExportData?: (
    purpose: ExportPurpose,
    format: ExportFormat,
  ) => ExportData | Promise<ExportData | null> | null

  getExportCanvas?: (
    purpose: ExportPurpose,
  ) => HTMLCanvasElement | Promise<HTMLCanvasElement | null> | null

  getFileName?: (purpose: ExportPurpose) => string
}

interface ExportDownloadOptions {
  fileName?: string
  format?: ExportFormat    // 'png' | 'jpeg' | 'webp' | 'svg'
  quality?: number         // JPEG/WebP quality 0-1
}

interface ExportDownloadResult {
  success: boolean
  fileName: string
}

interface ExportOpenInStudioResult {
  success: boolean
}

type ExportOpenInStudioSource =
  | string
  | Blob
  | File

interface ExportOpenInStudioOptions {
  source?: ExportOpenInStudioSource
  format?: ExportFormat    // default 'png'
}

Template 相关

interface PanelFilter {
  includeGroups?: string[]
  includeFields?: string[]
  excludeGroups?: string[]
  excludeFields?: string[]
  readonlyFields?: string[]
}

interface TemplateFieldOption {
  groupId: string
  groupTitle?: string
  fieldId: string
  fieldLabel?: string
  path: string
}

interface GeneratorTemplateDefinition {
  type: 'generator-template'
  version: '1.0.0'
  generatorId: string
  appKey?: string
  templateMeta?: Record<string, unknown>
  defaults: Record<string, unknown>
  panelFilter: PanelFilter
  adjustableFields: TemplateFieldOption[]
  metadata?: Record<string, unknown>
}

interface TemplateBuildOptions {
  generatorId: string
  appKey?: string
  state: Record<string, unknown>
  panelSchema: PanelSchema
  selectedFieldPaths: string[]
  templateMeta?: Record<string, unknown>
  metadata?: Record<string, unknown>
}

interface TemplateRuntimeSnapshot {
  state: Record<string, unknown>
  panelFilter: PanelFilter
}

interface TemplateApplyOptions {
  source?: string
  onPanelFilter?: (panelFilter: PanelFilter) => void | Promise<void>
}

withBilling 相关

interface WithBillingResult<T> {
  result: T
  billing: BillingConsumeResult
}