@atomm-developer/generator-sdk 1.0.3

package/dist/index.d.ts

@@ -0,0 +1,672 @@
+import { AxiosInstance } from 'axios';
+
+/** 登录状态变化回调 */
+export declare type AuthChangeCallback = (status: AuthStatus) => void;
+
+/**
+ * Auth 模块
+ * 对外暴露：getStatus / login / logout / onChange / getToken
+ */
+declare class AuthModule {
+    private readonly appKey;
+    private readonly passportClient;
+    private readonly http;
+    private readonly emitter;
+    private _status;
+    constructor(appKey: string, env: SdkEnv, http: AxiosInstance);
+    /**
+     * 获取当前登录状态（同步，读本地缓存）
+     */
+    getStatus(): AuthStatus;
+    /**
+     * 获取当前 uToken
+     * 未登录时返回空字符串
+     */
+    getToken(): string;
+    /**
+     * 弹出登录弹窗
+     * 登录成功后 resolve UserInfo，用户取消则 reject
+     */
+    login(): Promise<UserInfo>;
+    /**
+     * 退出登录
+     */
+    logout(): Promise<void>;
+    /**
+     * 监听登录状态变化，返回取消监听函数
+     */
+    onChange(callback: AuthChangeCallback): () => void;
+    /**
+     * 初始化时从 localStorage 恢复登录状态
+     * 如果 token 存在，尝试拉取用户信息验证有效性
+     */
+    private _restoreFromStorage;
+    /**
+     * 通过 passport-client 获取用户信息（同时验证 token 有效性）
+     * 接口响应格式：{ code: 0, data: { uid, userName, headpic, uuid, email, ... } }
+     */
+    private _fetchUserInfo;
+    private _setLoginStatus;
+    private _clearLoginStatus;
+}
+
+/** 登录状态 */
+export declare interface AuthStatus {
+    isLogin: boolean;
+    userInfo: UserInfo | null;
+}
+
+/** 额度变化回调 */
+export declare type BillingChangeCallback = (usage: UsageInfo) => void;
+
+/** billing.check() 校验结果 */
+export declare interface BillingCheckResult {
+    /** 是否可以继续操作 */
+    canProceed: boolean;
+    /** 原因：free_period=免费时段 free_count=免费次数 credits=扣积分 insufficient=积分不足 */
+    reason: 'free_period' | 'free_count' | 'credits' | 'insufficient';
+}
+
+/** billing.consume() 参数 */
+export declare interface BillingConsumeOptions {
+    /** 业务幂等 ID，防止重复扣费（可选） */
+    externalId?: string;
+}
+
+/** billing.consume() 返回值 */
+export declare interface BillingConsumeResult {
+    /** 剩余免费次数 */
+    freeRemaining: number;
+    /** 本次是否扣了积分（false 表示扣的免费次数或处于免费时段） */
+    isCredit: boolean;
+}
+
+/**
+ * Billing 模块
+ * 对外暴露：getUsage / getCachedUsage / check / consume / refreshCredits / onChange
+ */
+declare class BillingModule {
+    private readonly http;
+    private readonly module;
+    private readonly credits;
+    private readonly emitter;
+    /** 缓存的免费次数信息 */
+    private _freeRemaining;
+    private _freeTotal;
+    private _creditsPerUse;
+    /** 免费时段截止时间戳 */
+    private _freePeriodEnd;
+    /** 是否已首次加载过 */
+    private _loaded;
+    constructor(appKey: string, http: AxiosInstance, credits: CreditsModule);
+    /**
+     * 获取使用额度（发起网络请求，刷新缓存）
+     * 并行拉取免费次数和积分余额
+     */
+    getUsage(): Promise<UsageInfo>;
+    /**
+     * 获取缓存的使用额度（同步，无网络请求）
+     * 首次调用 getUsage() 前返回 null
+     */
+    getCachedUsage(): UsageInfo | null;
+    /**
+     * 校验当前是否可执行付费操作（同步，基于缓存判断）
+     * 不弹窗、不扣费，纯校验
+     */
+    check(): BillingCheckResult;
+    /**
+     * 消耗一次（调后端 POST /ai/v5/artimind/free_trial）
+     * 后端自动判断扣免费次数还是积分
+     *
+     * 免费时段内不发请求，直接返回成功
+     *
+     * external_id 优先使用调用方传入的值（便于业务幂等），
+     * 未传则 SDK 内部自动生成 UUID，确保每次请求都有唯一幂等键
+     */
+    consume(options?: BillingConsumeOptions): Promise<BillingConsumeResult>;
+    /**
+     * 手动刷新积分余额
+     * consume() 中 isCredit=true 时会自动调用，一般不需手动调
+     */
+    refreshCredits(): Promise<void>;
+    /**
+     * 监听额度变化（consume 成功、refreshCredits 后触发）
+     * 返回取消监听函数
+     */
+    onChange(callback: BillingChangeCallback): () => void;
+    private _isInFreePeriod;
+    private _buildUsageInfo;
+}
+
+/**
+ * Cloud 模块
+ * 对外暴露：save / restore / delete
+ */
+declare class CloudModule {
+    private readonly appKey;
+    private readonly env;
+    private readonly http;
+    private uploader;
+    constructor(appKey: string, env: SdkEnv, http: AxiosInstance);
+    /**
+     * 保存当前状态到云端（自动判断新建或更新）
+     *
+     * 封面和原图由 SDK 客户端上传 OSS，后端只接收 URL，
+     * 与 Header.vue saveGeneratorData() 处理逻辑保持一致
+     */
+    save(options: CloudSaveOptions): Promise<CloudSaveResult>;
+    /**
+     * 恢复云端数据（根据 id 获取完整记录含 snapshot）
+     *
+     * 对应现有接口：GET /ai/v5/artimind/generator/:id
+     */
+    restore(id: number): Promise<CloudRecord>;
+    /**
+     * 删除云端记录
+     *
+     * 对应现有接口：DELETE /ai/v5/artimind/generator/:id
+     */
+    delete(id: number): Promise<void>;
+    /**
+     * 将后端原始结构转换为 SDK 公开的 CloudRecord 结构
+     * info 字段中 originImageUrl 提取到顶层，snapshot 为其余字段
+     */
+    private _normalizeRecord;
+    /** 获取或懒初始化 Uploader 实例 */
+    private getUploader;
+    /**
+     * 将 HTMLCanvasElement 导出为 PNG 并上传到 OSS
+     * @param canvas  画布元素
+     * @param name    OSS 文件名（不含扩展名），同一记录复用文件名实现覆盖更新
+     */
+    private _uploadCanvas;
+    /**
+     * 上传原图到 OSS
+     * 支持三种输入：HTMLCanvasElement / data URL / HTTP URL
+     * HTTP URL（已在 OSS 上）时直接返回，避免重复上传
+     */
+    private _uploadOriginImage;
+    /** 上传 File 到 OSS，返回 OSS URL */
+    private _uploadFile;
+    /** data URL → File 对象 */
+    private _dataUrlToFile;
+}
+
+/** 云端记录详情 */
+export declare interface CloudRecord {
+    id: number;
+    title: string;
+    cover: string;
+    snapshot: Record<string, unknown>;
+    /** 原始素材图片的 OSS URL，可直接用于 img.src */
+    originImageUrl: string;
+    createdAt: number;
+    updatedAt: number;
+}
+
+/** cloud.save() 参数 */
+export declare interface CloudSaveOptions {
+    /** 记录标题，默认 'Draft' */
+    title?: string;
+    /**
+     * 应用状态快照
+     * 必须是可 JSON 序列化的纯对象（不含函数、DOM、循环引用）
+     */
+    snapshot: Record<string, unknown>;
+    /**
+     * 封面画布元素
+     * SDK 内部自动调用 toDataURL 并上传 OSS，后端只存 URL
+     */
+    cover?: HTMLCanvasElement | null;
+    /**
+     * 原始素材图片
+     * 可传 HTMLCanvasElement（自动导出）、data URL 或 HTTP URL
+     */
+    originImage?: HTMLCanvasElement | string | null;
+    /**
+     * 记录 ID
+     * 传入时执行更新，不传时新建记录
+     */
+    id?: number | null;
+}
+
+/** cloud.save() 返回值 */
+export declare interface CloudSaveResult {
+    /** 记录 ID */
+    id: number;
+    /** 是否是新建（false 表示更新） */
+    isNew: boolean;
+}
+
+/** 积分变化回调 */
+export declare type CreditsChangeCallback = (balance: number) => void;
+
+/** credits.consume() 参数 */
+export declare interface CreditsConsumeOptions {
+    /** 扣除积分数量 */
+    amount: number;
+    /**
+     * 业务标识
+     * 需在开发者控制台预先申请，后端据此校验权限
+     */
+    action: string;
+}
+
+/** credits.consume() 返回值 */
+export declare interface CreditsConsumeResult {
+    success: boolean;
+    /** 扣除后剩余积分 */
+    balance: number;
+    /** 流水号 */
+    transactionId: string;
+}
+
+/**
+ * Credits 模块
+ * 对外暴露：getBalance / consume / onChange
+ */
+declare class CreditsModule {
+    private readonly http;
+    private readonly emitter;
+    private _balance;
+    constructor(http: AxiosInstance);
+    /**
+     * 获取当前用户积分余额
+     *
+     * 对应现有接口：GET /ai/v1/credit/getBalance
+     * 返回格式：{ code: 0, data: { quota: number }, message: string }
+     */
+    getBalance(): Promise<{
+        quota: number;
+    }>;
+    /**
+     * 扣除积分
+     * 用于 AI 生成等消耗性操作，action 需提前在开发者控制台申请
+     *
+     * 注意：此接口需后端配合新增，现有项目中暂无积分扣除 API
+     * 临时方案：调用 /sdk/v1/credits/consume（后端按需新增）
+     */
+    consume(options: CreditsConsumeOptions): Promise<CreditsConsumeResult>;
+    /**
+     * 监听积分变化（getBalance/consume 成功后自动触发）
+     * 返回取消监听函数
+     */
+    onChange(callback: CreditsChangeCallback): () => void;
+    /**
+     * 获取本地缓存的积分余额（同步，最后一次 getBalance/consume 的结果）
+     */
+    getCachedBalance(): number;
+}
+
+/** export.download() 参数 */
+export declare interface ExportDownloadOptions {
+    /** 文件名（可选，默认 'export-{timestamp}.png'） */
+    fileName?: string;
+    /** 导出格式（可选，默认 'png'） */
+    format?: 'png' | 'svg';
+}
+
+/** export.download() 返回值 */
+export declare interface ExportDownloadResult {
+    success: boolean;
+    fileName: string;
+}
+
+/**
+ * Export 模块
+ * 对外暴露：register / download / openInStudio
+ */
+declare class ExportModule {
+    private readonly appKey;
+    private readonly env;
+    private readonly http;
+    private provider;
+    private uploader;
+    constructor(appKey: string, env: SdkEnv, http: AxiosInstance);
+    /**
+     * 注册导出能力提供者
+     * 开发者实现 ExportProvider 接口，在初始化时调用一次
+     */
+    register(provider: ExportProvider): void;
+    /**
+     * 下载图片到本地
+     * 内部流程：getExportCanvas('download') → toBlob → 触发浏览器下载
+     */
+    download(options?: ExportDownloadOptions): Promise<ExportDownloadResult>;
+    /**
+     * 打开到 xTool Studio
+     * 内部流程：
+     * - 传入图片 URL：直接拉起 Studio
+     * - 传入图片数据：上传 OSS → 调用 xtool:// 协议
+     * - 未传参数：getExportCanvas('studio') → toDataURL → 上传 OSS → 调用 xtool:// 协议
+     */
+    openInStudio(source?: ExportOpenInStudioSource): Promise<ExportOpenInStudioResult>;
+    /**
+     * 获取导出 Canvas 并校验
+     */
+    private _getCanvas;
+    /**
+     * 解析 openInStudio 的输入来源：
+     * - URL 直传给 Studio
+     * - data URL / Blob / File 先上传 OSS
+     * - 未传时回退到 provider canvas
+     */
+    private _resolveStudioAsset;
+    /** 获取或懒初始化 Uploader 实例 */
+    private _getUploader;
+    /** 上传 File 到 OSS，返回 OSS URL */
+    private _uploadFile;
+    /** 通过 xtool:// 协议打开 Studio */
+    private _openStudioProtocol;
+    /** data URL → File 对象 */
+    private _dataUrlToFile;
+    /** Blob → File 对象 */
+    private _blobToFile;
+    /** 判断是否为 data URL */
+    private _isDataUrl;
+    /** 判断是否为可直接交给 Studio 的远程 URL */
+    private _isHttpUrl;
+    /** MIME 类型 → 文件扩展名 */
+    private _mimeTypeToExtension;
+}
+
+/** export.openInStudio() 返回值 */
+export declare interface ExportOpenInStudioResult {
+    success: boolean;
+}
+
+/** export.openInStudio() 输入源 */
+export declare type ExportOpenInStudioSource = string | Blob | File;
+
+/**
+ * 导出能力提供者
+ * 开发者实现此接口并通过 sdk.export.register() 注册
+ */
+export declare interface ExportProvider {
+    /**
+     * 获取导出用的 Canvas
+     * @param purpose 用途：download=下载 studio=打开到Studio cover=封面
+     */
+    getExportCanvas: (purpose: ExportPurpose) => HTMLCanvasElement | Promise<HTMLCanvasElement | null> | null;
+    /** 自定义文件名生成器（可选） */
+    getFileName?: (purpose: ExportPurpose) => string;
+}
+
+/** 导出画布用途 */
+export declare type ExportPurpose = 'download' | 'studio' | 'cover';
+
+export declare class GeneratorSDK {
+    /** 登录/退出/用户信息 */
+    readonly auth: AuthModule;
+    /** 云保存/恢复/删除 */
+    readonly cloud: CloudModule;
+    /** 历史记录列表/详情/删除 */
+    readonly history: HistoryModule;
+    /** 积分余额/扣除（底层能力） */
+    readonly credits: CreditsModule;
+    /** 统一计费（免费次数 + 积分，推荐使用） */
+    readonly billing: BillingModule;
+    /** 导出（下载 + 打开到 Studio） */
+    readonly export: ExportModule;
+    /** 模板协议与导入导出 */
+    readonly template: TemplateModule;
+    private readonly appKey;
+    private readonly env;
+    private constructor();
+    /**
+     * 初始化 SDK，返回 SDK 实例
+     *
+     * 同一 appKey 多次调用返回同一实例，不会重复初始化
+     *
+     * @example
+     * ```js
+     * const sdk = GeneratorSDK.init({ appKey: 'app_xxx' })
+     * ```
+     */
+    static init(options: SdkInitOptions): GeneratorSDK;
+    /**
+     * 清除实例缓存（测试场景使用）
+     */
+    static _clearCache(): void;
+}
+
+/** 标准模板定义协议 */
+export declare 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>;
+}
+
+/** 历史记录列表项（不含 snapshot） */
+export declare interface HistoryItem {
+    id: number;
+    title: string;
+    cover: string;
+    createdAt: number;
+    updatedAt: number;
+}
+
+/** history.getList() 参数 */
+export declare interface HistoryListOptions {
+    /** 页码，默认 1 */
+    page?: number;
+    /** 每页条数，默认 20，最大 50 */
+    pageSize?: number;
+}
+
+/** history.getList() 返回值 */
+export declare interface HistoryListResult {
+    total: number;
+    items: HistoryItem[];
+}
+
+/**
+ * History 模块
+ * 对外暴露：getList / getDetail / delete
+ */
+declare class HistoryModule {
+    private readonly appKey;
+    private readonly http;
+    constructor(appKey: string, http: AxiosInstance);
+    /**
+     * 获取当前用户在此应用下的历史记录列表（分页，仅元数据，不含 snapshot）
+     *
+     * 对应现有接口：POST /ai/v5/artimind/generator/type
+     * category 传入 appKey，实现多应用数据隔离
+     */
+    getList(options?: HistoryListOptions): Promise<HistoryListResult>;
+    /**
+     * 获取单条历史记录详情（含完整 snapshot）
+     *
+     * 对应现有接口：GET /ai/v5/artimind/generator/:id
+     */
+    getDetail(id: number): Promise<CloudRecord>;
+    /**
+     * 删除历史记录
+     *
+     * 对应现有接口：DELETE /ai/v5/artimind/generator/:id
+     */
+    delete(id: number): Promise<void>;
+    /** 将后端原始结构转换为 SDK 公开的 CloudRecord 结构 */
+    private _normalizeRecord;
+}
+
+/** Runtime 参数字段 */
+export declare interface PanelField {
+    id: string;
+    label?: string;
+    type?: string;
+    bind?: {
+        path?: string;
+    };
+    readonly?: boolean;
+    [key: string]: unknown;
+}
+
+/** Runtime 参数裁剪规则 */
+export declare interface PanelFilter {
+    includeGroups?: string[];
+    includeFields?: string[];
+    excludeGroups?: string[];
+    excludeFields?: string[];
+    readonlyFields?: string[];
+}
+
+/** Runtime 参数分组 */
+export declare interface PanelGroup {
+    id: string;
+    title?: string;
+    fields: PanelField[];
+    [key: string]: unknown;
+}
+
+/** Runtime 参数 schema */
+export declare interface PanelSchema {
+    version?: string;
+    generatorId?: string;
+    groups: PanelGroup[];
+    [key: string]: unknown;
+}
+
+/**
+ * Atomm Generator SDK 全部公开类型定义
+ */
+/** SDK 支持的运行环境 */
+export declare type SdkEnv = 'prod' | 'pre' | 'test' | 'dev';
+
+/** SDK 业务错误 */
+export declare class SdkError extends Error {
+    readonly code: number;
+    constructor(code: number, message: string);
+}
+
+/** GeneratorSDK.init() 配置项 */
+export declare interface SdkInitOptions {
+    /** 开发者控制台获取的应用标识（必填） */
+    appKey: string;
+    /** 运行环境，默认 'prod' */
+    env?: SdkEnv;
+}
+
+/** 模板应用参数 */
+export declare interface TemplateApplyOptions {
+    source?: string;
+    onPanelFilter?: (panelFilter: PanelFilter) => void | Promise<void>;
+}
+
+/** 构建模板参数 */
+export declare interface TemplateBuildOptions {
+    generatorId: string;
+    appKey?: string;
+    state: Record<string, unknown>;
+    panelSchema: PanelSchema;
+    selectedFieldPaths: string[];
+    templateMeta?: Record<string, unknown>;
+    metadata?: Record<string, unknown>;
+}
+
+/** 模板下载参数 */
+export declare interface TemplateDownloadOptions {
+    fileName?: string;
+}
+
+/** 模板作者可勾选字段 */
+export declare interface TemplateFieldOption {
+    groupId: string;
+    groupTitle?: string;
+    fieldId: string;
+    fieldLabel?: string;
+    path: string;
+}
+
+/**
+ * Template 模块
+ * 负责模板协议构建、校验、下载与 runtime 应用
+ */
+export declare class TemplateModule {
+    getFieldOptions(args: {
+        panelSchema: PanelSchema;
+    }): TemplateFieldOption[];
+    build(args: TemplateBuildOptions): GeneratorTemplateDefinition;
+    serialize(template: GeneratorTemplateDefinition): string;
+    parse(text: string): GeneratorTemplateDefinition;
+    download(template: GeneratorTemplateDefinition, options?: TemplateDownloadOptions): void;
+    toRuntimeSnapshot(template: GeneratorTemplateDefinition): TemplateRuntimeSnapshot;
+    applyToRuntime(runtime: TemplateRuntime, template: GeneratorTemplateDefinition, options?: TemplateApplyOptions): Promise<void>;
+}
+
+/** 最小 runtime 约束 */
+export declare interface TemplateRuntime {
+    setState: (nextState: Record<string, unknown>, options?: {
+        source?: string;
+        silent?: boolean;
+    }) => void | Promise<void>;
+}
+
+/** 模板转 runtime 快照后的结果 */
+export declare interface TemplateRuntimeSnapshot {
+    state: Record<string, unknown>;
+    panelFilter: PanelFilter;
+}
+
+/** 使用额度信息（整合免费次数 + 积分余额 + 免费时段） */
+export declare interface UsageInfo {
+    /** 剩余免费次数 */
+    freeRemaining: number;
+    /** 免费总次数 */
+    freeTotal: number;
+    /** 免费次数用完后每次操作所需积分 */
+    creditsPerUse: number;
+    /** 当前积分余额 */
+    creditsBalance: number;
+    /** 是否在免费时段内（成功操作后短时间内可免费重复操作） */
+    inFreePeriod: boolean;
+    /** 免费时段剩余秒数 */
+    freePeriodRemaining: number;
+}
+
+/** 用户信息 */
+export declare interface UserInfo {
+    uid: number;
+    uuid: string;
+    /** 用户名（对应接口 userName 字段） */
+    userName: string;
+    headpic: string;
+    email: string;
+    phoneNumber: string;
+    phoneZone: string;
+    /** 性别：0 未知 / 1 男 / 2 女 */
+    gender: number;
+    /** 个性签名 */
+    signature: string;
+    /** 账号创建时间（Unix 秒） */
+    createTime: number;
+}
+
+/**
+ * 将异步操作与计费流程组合
+ *
+ * 执行顺序：
+ * 1. billing.check() — 积分不足时直接 reject（code: BILLING_INSUFFICIENT）
+ * 2. action() — 执行实际操作
+ * 3. billing.consume() — 操作成功后扣费
+ *
+ * @param billing SDK billing 模块实例
+ * @param action 要执行的异步操作
+ * @param options consume 参数（可选）
+ */
+export declare const withBilling: <T>(billing: BillingModule, action: () => Promise<T>, options?: BillingConsumeOptions) => Promise<WithBillingResult<T>>;
+
+/** withBilling() 组合返回值 */
+export declare interface WithBillingResult<T> {
+    result: T;
+    billing: BillingConsumeResult;
+}
+
+export { }

package/dist/index.es.js

@@ -0,0 +1,7 @@
+import { G, S, T, w } from "./index-qYdFih-w.js";
+export {
+  G as GeneratorSDK,
+  S as SdkError,
+  T as TemplateModule,
+  w as withBilling
+};