import { AxiosInstance } from 'axios';

/** 登录状态变化回调 */
export declare type AuthChangeCallback = (status: AuthStatus) => void;

/**
 * Auth 模块
 * 对外暴露：getStatus / login / logout / onChange / getToken / syncToken
 */
declare class AuthModule {
    private readonly appKey;
    private readonly passportClient;
    private readonly http;
    private readonly emitter;
    private readonly studioAuthSync;
    private _status;
    private readonly _readyPromise;
    constructor(appKey: string, env: SdkEnv, http: AxiosInstance);
    /**
     * 获取当前登录状态（同步，读本地 cookie 缓存）
     */
    getStatus(): AuthStatus;
    /**
     * 获取当前 uToken
     * 未登录时返回空字符串
     */
    getToken(): string;
    /**
     * 外部传入 token，同步到本地 cookie 缓存并刷新登录状态
     */
    syncToken(token?: string | null): Promise<AuthStatus>;
    /**
     * 弹出登录弹窗
     * 登录成功后 resolve UserInfo，用户取消则 reject
     */
    login(): Promise<UserInfo>;
    /**
     * 退出登录
     */
    logout(): Promise<void>;
    /**
     * 监听登录状态变化，返回取消监听函数
     */
    onChange(callback: AuthChangeCallback): () => void;
    /**
     * 等待首次登录态恢复完成。
     * - 已登录：返回包含 userInfo 的状态
     * - 未登录 / token 失效：返回 { isLogin: false, userInfo: null }
     */
    ready(): Promise<AuthStatus>;
    /**
     * 初始化时从 cookie 恢复登录状态
     * 如果 token 存在，尝试拉取用户信息验证有效性
     */
    private _restoreFromStorage;
    /**
     * 通过 passport-client 获取用户信息（同时验证 token 有效性）
     * 接口响应格式：{ code: 0, data: { uid, userName, headpic, uuid, email, ... } }
     */
    private _fetchUserInfo;
    private _fetchUserRoles;
    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;
    /** 是否为黑名单用户（true 表示后端返回 code=20102） */
    isBlacklisted?: boolean;
}

/**
 * Billing 模块
 * 对外暴露：getUsage / getCachedUsage / check / consume / refreshCredits / onChange
 */
declare class BillingModule {
    private readonly http;
    private readonly module;
    private readonly credits;
    private readonly emitter;
    /** 缓存的免费次数信息 */
    private _isEnabled;
    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;
    /**
     * 上传封面到 OSS
     * 支持 HTMLCanvasElement / data URL / HTTP URL
     * HTTP URL（已在 OSS 或 CDN 上）时直接返回，避免重复上传
     * @param cover   封面图片来源
     * @param name    OSS 文件名（不含扩展名），同一记录复用文件名实现覆盖更新
     */
    private _uploadCover;
    /**
     * 上传原图到 OSS
     * 支持三种输入：HTMLCanvasElement / data URL / HTTP URL
     * HTTP URL（已在 OSS 上）时直接返回，避免重复上传
     */
    private _uploadOriginImage;
    /** 上传 File 到 OSS，返回 OSS URL */
    private _uploadFile;
    /** data URL → File 对象 */
    private _dataUrlToFile;
    private _isCanvasLike;
}

/** 云端记录详情 */
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>;
    /**
     * 封面图片
     * 支持 HTMLCanvasElement、data URL、HTTP/HTTPS URL；
     * Canvas/data URL 会上传到 OSS，HTTP/HTTPS URL 直接复用
     */
    cover?: HTMLCanvasElement | string | 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;
}

/**
 * 通用导出数据
 * 当画布不是 HTMLCanvasElement 时，开发者通过 getExportData 返回此类型
 */
export declare type ExportData = {
    type: 'canvas';
    canvas: HTMLCanvasElement;
} | {
    type: 'blob';
    blob: Blob;
} | {
    type: 'dataUrl';
    dataUrl: string;
} | {
    type: 'url';
    url: string;
} | {
    type: 'svg';
    svgString: string;
};

/** export.download() 参数 */
export declare interface ExportDownloadOptions {
    /** 文件名（可选，默认 'export-{timestamp}.{format}'） */
    fileName?: string;
    /** 导出格式（可选，默认 'png'） */
    format?: ExportFormat;
    /** JPEG/WebP 质量 0-1（可选，默认 0.92） */
    quality?: number;
}

/** export.download() 返回值 */
export declare interface ExportDownloadResult {
    success: boolean;
    fileName: string;
}

/** 支持的导出格式 */
export declare type ExportFormat = 'png' | 'jpeg' | 'webp' | 'svg';

/**
 * 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;
    /**
     * 下载图片到本地
     * 支持 png / jpeg / webp / svg 格式
     *
     * 内部流程：
     * 1. 优先调用 getExportData(purpose, format) 获取导出数据
     * 2. 若未实现则回退到 getExportCanvas(purpose) → canvas.toBlob
     * 3. 生成 Blob → 触发浏览器下载
     */
    download(options?: ExportDownloadOptions): Promise<ExportDownloadResult>;
    /**
     * 打开到 xTool Studio
     *
     * 支持两种调用方式（向后兼容）：
     * - openInStudio(source)             — 直接传图片源（URL / data URL / Blob / File）
     * - openInStudio({ source, format }) — 传 options 对象，可指定导入格式
     * - openInStudio()                   — 无参数，通过 provider 获取数据
     *
     * 当未传 source 时，根据 format 参数通过 provider 获取对应格式的数据上传到 OSS
     */
    openInStudio(sourceOrOptions?: ExportOpenInStudioSource | ExportOpenInStudioOptions): Promise<ExportOpenInStudioResult>;
    /**
     * 一次导入多张到 Studio（如多页 / 多料）。
     *
     * 取数：优先用 options.sources；否则调 provider.getExportDataList（批量），
     * 再回退到 getExportData（单张）。每张独立上传到 OSS。
     *
     * 发送：
     * - 嵌入态（在 Studio 内 iframe，window.parent !== window）：一次 postMessage
     *   携带 urls 数组，Studio 用 insertMode:'new' 给每张各开一个 Tab。
     * - 独立态（普通网页）：协议每次单 url，循环发 N 次（Studio 已运行 → 每次转成一个新 Tab）。
     *   注意浏览器对连发协议可能去重，故每次之间留间隔。
     */
    openInStudioBatch(options?: ExportOpenInStudioBatchOptions): Promise<ExportOpenInStudioBatchResult>;
    /**
     * 兼容解析 openInStudio 参数：
     * - 无参数 → { source: undefined, format: 'png' }
     * - string / Blob / File → { source, format: 'png' }
     * - { source?, format? } → 直接使用
     */
    private _normalizeStudioArgs;
    /**
     * 获取导出 Blob，统一处理 getExportData / getExportCanvas 两种路径
     */
    private _getBlob;
    /** 尝试通过 getExportData 获取导出数据 */
    private _tryGetExportData;
    /**
     * 获取多个导出 Blob（批量）。
     * 优先 provider.getExportDataList（多张）；未实现 / 返回空时回退到单张 _getBlob。
     */
    private _getBlobList;
    /** 尝试通过 getExportCanvas 获取画布 */
    private _tryGetCanvas;
    /** 确保 provider 已注册 */
    private _ensureProvider;
    /** 将 ExportData 转换为 Blob */
    private _exportDataToBlob;
    /** Canvas → Blob，正确处理各格式 */
    private _canvasToBlob;
    private _isInClient;
    private _callApp;
    /**
     * 解析 openInStudio 的输入来源：
     * - URL 直传给 Studio
     * - data URL / Blob / File 先上传 OSS
     * - 未传时通过 provider 按 format 获取数据
     */
    private _resolveStudioAsset;
    /** 推断 Studio 资产的真实扩展名：getFileName 后缀 > blob MIME > format */
    private _resolveStudioExt;
    /** 资产扩展名 → Studio 导入类型，未登记则按 2D 处理 */
    private _studioAssetType;
    /** 从文件名 / URL 取扩展名（去除查询串与锚点），无后缀返回空串 */
    private _extFromName;
    /** 获取或懒初始化 Uploader 实例 */
    private _getUploader;
    /** 上传 File 到 OSS，返回 OSS URL */
    private _uploadFile;
    /**
     * 保险层：确保 URL 末尾带有文件扩展名
     * 仅在 pathname 没有可识别后缀时才追加，不修改已有后缀
     */
    private _ensureUrlHasExtension;
    /**
     * 通过 xtool:// 协议打开 Studio
     * - iframe 模式：postMessage 给父页，无法感知结果，视为成功
     * - 独立页面模式：等待协议检测结果，成功返回 true，失败返回 false
     */
    /** payload 对象 → xtool://external 协议 URI(base64-url 同款编码) */
    private _encodeExternalUri;
    /** 构造单个资源的 xtool://external 协议 URI（含设备/模式预设 config） */
    private _buildExternalUri;
    /**
     * 构造"一次带多个资源"的协议 URI。
     * data 同时带 url(第一张,兼容只读单 url 的旧版 Studio)+ urls 数组(打了补丁的 Studio 读全部)。
     * 一次唤起 = 一次用户手势 → 不会被浏览器"user gesture required"拦。
     */
    private _buildExternalBatchUri;
    /**
     * 用隐藏 iframe 触发协议(适合"Studio 已运行、连发多次"场景):
     * 不跑安装检测、不弹"未安装"确认框,可快速重复。
     */
    private _fireProtocolUri;
    private _openStudioProtocol;
    /**
     * 批量唤起 Studio。
     * - 嵌入态（window.parent !== window）：一次 postMessage 携带 urls 数组，
     *   Studio 用 insertMode:'new' 给每张各开一个 Tab（Studio 已支持多 url）。
     * - 独立态：协议每次单 url，循环发 N 次（Studio 已运行 → 每次转成一个新 Tab）。
     */
    private _openStudioProtocolBatch;
    /** 预设 → 协议 event.config 对象（空则返回 undefined） */
    private _presetToConfig;
    /** 预设 → postMessage payload 顶层字段（ExternalAppAddToCanvasPayload 读顶层） */
    private _presetToPayload;
    /** 导出格式 → MIME 类型（仅位图格式） */
    private _formatToMimeType;
    /** 文件扩展名 → MIME 类型（含 3D 模型格式），未登记回退到通用二进制流 */
    private _extToMimeType;
    /** data URL → Blob */
    private _dataUrlToBlob;
    /** data URL → File 对象 */
    private _dataUrlToFile;
    /** Blob → File 对象 */
    private _blobToFile;
    /** 从 data URL 推断文件扩展名 */
    private _detectDataUrlExtension;
    /** 判断是否为 data URL */
    private _isDataUrl;
    /** 判断是否为可直接交给 Studio 的远程 URL */
    private _isHttpUrl;
    /** MIME 类型 → 文件扩展名 */
    private _mimeTypeToExtension;
}

/** export.openInStudioBatch() 参数：一次导入多张到 Studio */
declare interface ExportOpenInStudioBatchOptions {
    /** 多个图片源；不传时从 provider.getExportDataList 获取 */
    sources?: ExportOpenInStudioSource[];
    /** 导入格式（不传 sources 时生效），默认 'svg' */
    format?: ExportFormat;
    /** 设备 / 模式预设 */
    studio?: StudioOpenPreset;
}

/** export.openInStudioBatch() 返回值 */
declare interface ExportOpenInStudioBatchResult {
    success: boolean;
    /** 实际发出的资产数量 */
    count: number;
}

/**
 * export.openInStudio() 参数
 * 支持两种调用方式（向后兼容）：
 * - openInStudio(source)            — 直接传图片源
 * - openInStudio({ source, format }) — 传 options 对象
 */
export declare interface ExportOpenInStudioOptions {
    /** 图片来源：URL / data URL / Blob / File，不传时从 provider 获取 */
    source?: ExportOpenInStudioSource;
    /** 导入 Studio 的格式（不传 source 时生效），默认 'png' */
    format?: ExportFormat;
    /** 设备 / 模式预设（insertMode / presetExtId / presetMode 等），透传到协议 config / postMessage */
    studio?: StudioOpenPreset;
}

/** export.openInStudio() 返回值 */
export declare interface ExportOpenInStudioResult {
    success: boolean;
}

/** export.openInStudio() 直接传入的图片源（向后兼容） */
export declare type ExportOpenInStudioSource = string | Blob | File;

/**
 * 导出能力提供者
 * 开发者实现此接口并通过 sdk.export.register() 注册
 *
 * 提供两种方式（优先级：getExportData > getExportCanvas）：
 * - getExportData：灵活方式，适合非 canvas 场景（SVG/DOM/纯数据）
 * - getExportCanvas：传统方式，直接返回 HTMLCanvasElement
 *
 * 至少实现其中一个，否则调用 download/openInStudio 时会抛出错误
 */
export declare interface ExportProvider {
    /**
     * 获取导出数据（灵活方式，优先级高于 getExportCanvas）
     * 适用于非 canvas 场景：SVG 编辑器、DOM 截图、纯数据生成等
     */
    getExportData?: (purpose: ExportPurpose, format: ExportFormat) => ExportData | Promise<ExportData | null> | null;
    /**
     * 获取多个导出数据（批量）。
     * 实现后，openInStudioBatch 会用它一次拿到 N 张（如多页 / 多料），
     * 每张作为独立资产上传 + 导入 Studio。未实现时回退到 getExportData（单张）。
     */
    getExportDataList?: (purpose: ExportPurpose, format: ExportFormat) => ExportData[] | Promise<ExportData[] | null> | null;
    /**
     * 获取导出用的 Canvas（传统方式）
     * 当 getExportData 未实现或返回 null 时回退到此方法
     */
    getExportCanvas?: (purpose: ExportPurpose) => HTMLCanvasElement | Promise<HTMLCanvasElement | null> | null;
    /** 自定义文件名生成器（可选） */
    getFileName?: (purpose: ExportPurpose) => string;
}

/** 导出画布用途 */
export declare type ExportPurpose = 'download' | 'studio' | 'cover';

export declare class GeneratorSDK {
    /** 最近一次初始化使用的 appKey，供全局场景读取 */
    private static lastInitializedAppKey;
    /** 登录/退出/用户信息 */
    readonly auth: AuthModule;
    /** 云保存/恢复/删除 */
    readonly cloud: CloudModule;
    /** 历史记录列表/详情/删除 */
    readonly history: HistoryModule;
    /** 积分余额/扣除（底层能力） */
    readonly credits: CreditsModule;
    /** 统一计费（免费次数 + 积分，推荐使用） */
    readonly billing: BillingModule;
    /** 导出（下载 + 打开到 Studio） */
    readonly export: ExportModule;
    /** 模板协议与导入导出 */
    readonly template: TemplateModule;
    /** 当前语言环境（一次性读取） */
    readonly language: LanguageModule;
    private readonly appKey;
    private readonly env;
    private constructor();
    /**
     * 返回当前 SDK 实例绑定的 appKey
     */
    getAppKey(): string;
    /**
     * 返回当前 SDK 实例绑定的环境标识
     */
    getEnv(): SdkEnv;
    /**
     * 初始化 SDK，返回 SDK 实例
     *
     * 同一 appKey 多次调用返回同一实例，不会重复初始化
     *
     * @example
     * ```js
     * const sdk = GeneratorSDK.init({ appKey: 'app_xxx' })
     * ```
     */
    static init(options: SdkInitOptions): GeneratorSDK;
    /**
     * 返回最近一次初始化使用的 appKey
     */
    static getAppKey(): string | null;
    /**
     * 清除实例缓存（测试场景使用）
     */
    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;
}

export declare class LanguageModule {
    private readonly env;
    constructor(env: SdkEnv);
    /**
     * 返回当前语言短码（17 种之一）
     *
     * 解析优先级：URL ?lang > URL 路径前缀 /de/ > cookie i18n_redirected
     * > localStorage LANG_KEY > env 默认（prod_cn→zh，其余→en）
     */
    getCurrentLocale(): SupportedLanguageCode;
    /**
     * 返回所有受支持的语言（短码 + 展示名），共 17 种
     *
     * 用于接入方自行渲染语言选择 UI 等场景。返回副本，外部修改不影响 SDK 内部数据。
     */
    getSupportedLocales(): SupportedLocale[];
}

/** 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' | 'prod_cn' | '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;
}

/**
 * Studio 设备 / 模式 / 材料预设。
 * 协议唤起时挂到 event.config；内嵌 postMessage 时挂到 payload 顶层。
 * 设备级 preset（presetExtId / presetMode / presetMaterial*）仅 insertMode='new' / 'direct' 生效。
 */
declare interface StudioOpenPreset {
    /** 插入方式：'new' = 新 Tab（多料各自独立画布要用它），默认按调用方传入 */
    insertMode?: 'ask' | 'current' | 'new' | 'direct';
    /** 插入画布方式：'new' = 新画布 */
    canvasMode?: 'current' | 'new';
    /** 预设设备 extId，如 'DQ003' */
    presetExtId?: string;
    /** 预设加工模式，如 'MULTI_MATERIAL' */
    presetMode?: string;
    /** 预设材料 ID */
    presetMaterialId?: string | number;
    /** 预设材料类型，默认 'official' */
    presetMaterialType?: 'official' | 'customize';
}

/** SDK 支持的语言短码（与 xtool config/i18n.ts、generator-workbench 一致，共 17 种） */
declare const SUPPORTED_LOCALES: readonly [{
    readonly code: "zh";
    readonly name: "简体中文";
}, {
    readonly code: "en";
    readonly name: "English";
}, {
    readonly code: "zh-hant";
    readonly name: "繁體中文";
}, {
    readonly code: "de";
    readonly name: "Deutsch";
}, {
    readonly code: "es";
    readonly name: "Español";
}, {
    readonly code: "fr";
    readonly name: "Français";
}, {
    readonly code: "it";
    readonly name: "Italiano";
}, {
    readonly code: "ja";
    readonly name: "日本語";
}, {
    readonly code: "ko";
    readonly name: "한국어";
}, {
    readonly code: "ru";
    readonly name: "Русский";
}, {
    readonly code: "uk";
    readonly name: "Українська";
}, {
    readonly code: "sl";
    readonly name: "Slovenščina";
}, {
    readonly code: "th";
    readonly name: "ไทย";
}, {
    readonly code: "pl";
    readonly name: "Polski";
}, {
    readonly code: "cs";
    readonly name: "Čeština";
}, {
    readonly code: "id";
    readonly name: "Bahasa Indonesia";
}, {
    readonly code: "vi";
    readonly name: "Tiếng Việt";
}];

/** 受支持的语言短码联合类型 */
export declare type SupportedLanguageCode = (typeof SUPPORTED_LOCALES)[number]['code'];

/** 单个受支持语言：短码 + 展示名 */
export declare interface SupportedLocale {
    code: SupportedLanguageCode;
    name: string;
}

/** 模板应用参数 */
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 {
    /** 当前模块是否启用计费 */
    isEnabled: boolean;
    /** 剩余免费次数 */
    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;
    /** 用户角色列表 */
    roleList: UserRole[];
    /** 是否为社区管理员 */
    isCommunityAdmin: boolean;
}

/** 用户信息 */
declare interface UserRole {
    code: string;
    [key: string]: unknown;
}

/**
 * 将异步操作与计费流程组合
 *
 * 执行顺序：
 * 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 { }