SDK 初始化

基本用法

import { GeneratorSDK } from '@atomm-developer/generator-sdk'

const sdk = GeneratorSDK.init({
  appKey: 'your_generator_id',  // 必填，当前生成器的唯一 id，可由开发者自行定义
  env: 'prod',             // 可选，默认 'prod'
})

读取当前 AppKey

const sdk = GeneratorSDK.init({
  appKey: 'your_app_key',
  env: 'prod',
})

sdk.getAppKey()              // 当前实例绑定的 appKey
GeneratorSDK.getAppKey()     // 最近一次初始化使用的 appKey

初始化参数

参数	类型	必填	默认值	说明
appKey	string	是	—	当前生成器的唯一 id，用于标识该生成器，可由开发者自行定义
env	'prod' | 'pre' | 'test' | 'dev'	否	'prod'	运行环境

各环境 API BaseURL

环境	BaseURL
prod	https://api.xtool.com
pre	https://api-pre.xtool.com
test	https://api-test.xtool.com
dev	https://api-dev.makeblock.com

重要特性

• 全局单例：同一 appKey + env 组合多次调用 init() 返回同一实例，不会重复初始化
• 自动恢复登录：初始化时自动从共享域 utoken Cookie 读取已缓存的 token 并异步验证有效性
• 缓存键格式：{appKey}::{env}
• appKey 校验：未传 appKey 时直接抛出 Error('[GeneratorSDK] appKey is required')

⚠️ Vue 3 使用注意事项

为什么会有这个限制？

SDK 的内部依赖使用了 TypeScript 私有字段（通过 WeakMap 实现）。Vue 3 的响应式系统会使用 Proxy 包裹对象，这会导致 WeakMap 的引用检查失败，从而抛出错误。

解决方案 1：使用 markRaw（推荐）

如果必须在组件的响应式数据中存储 SDK，使用 markRaw 标记为非响应式：

<script setup>
import { markRaw, ref } from 'vue'
import { GeneratorSDK } from '@atomm-developer/generator-sdk'

const sdk = markRaw(GeneratorSDK.init({ appKey: 'xxx' }))  // ✅ 使用 markRaw
const authStatus = ref(null)

sdk.auth.onChange((status) => {
  authStatus.value = status
})
</script>

解决方案 2：使用模块级变量（最佳）

将 SDK 实例放在模块级别，不在组件内部：

// src/sdk.ts
import { GeneratorSDK } from '@atomm-developer/generator-sdk'

export const sdk = GeneratorSDK.init({ appKey: 'xxx' })  // ✅ 模块级变量

<!-- src/App.vue -->
<script setup>
import { ref } from 'vue'
import { sdk } from './sdk'  // ✅ 导入模块级变量

const authStatus = ref(null)

sdk.auth.onChange((status) => {
  authStatus.value = status
})
</script>

解决方案 3：Options API 中的使用

<script>
import { markRaw } from 'vue'
import { GeneratorSDK } from '@atomm-developer/generator-sdk'

export default {
  data() {
    return {
      sdk: markRaw(GeneratorSDK.init({ appKey: 'xxx' })),  // ✅ 使用 markRaw
      authStatus: null
    }
  },
  mounted() {
    this.sdk.auth.onChange((status) => {
      this.authStatus = status
    })
  }
}
</script>

❌ 错误示例

<script setup>
import { ref } from 'vue'
import { GeneratorSDK } from '@atomm-developer/generator-sdk'

const sdk = ref(GeneratorSDK.init({ appKey: 'xxx' }))  // ❌ 会报错！
// Vue 会用 Proxy 包裹 SDK，导致内部依赖报错
</script>

初始化后的推荐操作

const sdk = GeneratorSDK.init({ appKey: 'app_xxx', env: 'test' })

// 1. 注册导出 provider（如果需要导出功能）
// 支持两种方式：getExportData（适合 SVG/非 canvas）或 getExportCanvas（canvas 场景）
sdk.export.register({
  getExportCanvas: (purpose) => document.getElementById('myCanvas') as HTMLCanvasElement,
})

// 2. 监听登录状态变化
sdk.auth.onChange((status) => {
  if (status.isLogin) {
    console.log('用户已登录:', status.userInfo?.userName)
  } else {
    console.log('用户未登录')
  }
})

// 3. 加载 Billing 信息
const usage = await sdk.billing.getUsage()
console.log('免费次数:', usage.freeRemaining, '/', usage.freeTotal)

// 4. 监听计费变化
sdk.billing.onChange((usage) => updateBillingUI(usage))