@atomm-developer/generator-sdk 1.0.4 → 1.0.6

package/dist/index.d.ts

@@ -5,7 +5,7 @@ export declare type AuthChangeCallback = (status: AuthStatus) => void;
 
 /**
  * Auth 模块
- * 对外暴露：getStatus / login / logout / onChange / getToken
+ * 对外暴露：getStatus / login / logout / onChange / getToken / syncToken
  */
 declare class AuthModule {
     private readonly appKey;
@@ -23,6 +23,10 @@ declare class AuthModule {
      * 未登录时返回空字符串
      */
     getToken(): string;
+    /**
+     * 外部传入 token，同步到本地缓存并刷新登录状态
+     */
+    syncToken(token: string): Promise<AuthStatus>;
     /**
      * 弹出登录弹窗
      * 登录成功后 resolve UserInfo，用户取消则 reject
@@ -298,12 +302,35 @@ declare class CreditsModule {
     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}.png'） */
+    /** 文件名（可选，默认 'export-{timestamp}.{format}'） */
     fileName?: string;
     /** 导出格式（可选，默认 'png'） */
-    format?: 'png' | 'svg';
+    format?: ExportFormat;
+    /** JPEG/WebP 质量 0-1（可选，默认 0.92） */
+    quality?: number;
 }
 
 /** export.download() 返回值 */
@@ -312,6 +339,9 @@ export declare interface ExportDownloadResult {
     fileName: string;
 }
 
+/** 支持的导出格式 */
+export declare type ExportFormat = 'png' | 'jpeg' | 'webp' | 'svg';
+
 /**
  * Export 模块
  * 对外暴露：register / download / openInStudio
@@ -330,26 +360,51 @@ declare class ExportModule {
     register(provider: ExportProvider): void;
     /**
      * 下载图片到本地
-     * 内部流程：getExportCanvas('download') → toBlob → 触发浏览器下载
+     * 支持 png / jpeg / webp / svg 格式
+     *
+     * 内部流程：
+     * 1. 优先调用 getExportData(purpose, format) 获取导出数据
+     * 2. 若未实现则回退到 getExportCanvas(purpose) → canvas.toBlob
+     * 3. 生成 Blob → 触发浏览器下载
      */
     download(options?: ExportDownloadOptions): Promise<ExportDownloadResult>;
     /**
      * 打开到 xTool Studio
-     * 内部流程：
-     * - 传入图片 URL：直接拉起 Studio
-     * - 传入图片数据：上传 OSS → 调用 xtool:// 协议
-     * - 未传参数：getExportCanvas('studio') → toDataURL → 上传 OSS → 调用 xtool:// 协议
+     *
+     * 支持两种调用方式（向后兼容）：
+     * - openInStudio(source)             — 直接传图片源（URL / data URL / Blob / File）
+     * - openInStudio({ source, format }) — 传 options 对象，可指定导入格式
+     * - openInStudio()                   — 无参数，通过 provider 获取数据
+     *
+     * 当未传 source 时，根据 format 参数通过 provider 获取对应格式的数据上传到 OSS
+     */
+    openInStudio(sourceOrOptions?: ExportOpenInStudioSource | ExportOpenInStudioOptions): Promise<ExportOpenInStudioResult>;
+    /**
+     * 兼容解析 openInStudio 参数：
+     * - 无参数 → { source: undefined, format: 'png' }
+     * - string / Blob / File → { source, format: 'png' }
+     * - { source?, format? } → 直接使用
      */
-    openInStudio(source?: ExportOpenInStudioSource): Promise<ExportOpenInStudioResult>;
+    private _normalizeStudioArgs;
     /**
-     * 获取导出 Canvas 并校验
+     * 获取导出 Blob，统一处理 getExportData / getExportCanvas 两种路径
      */
-    private _getCanvas;
+    private _getBlob;
+    /** 尝试通过 getExportData 获取导出数据 */
+    private _tryGetExportData;
+    /** 尝试通过 getExportCanvas 获取画布 */
+    private _tryGetCanvas;
+    /** 确保 provider 已注册 */
+    private _ensureProvider;
+    /** 将 ExportData 转换为 Blob */
+    private _exportDataToBlob;
+    /** Canvas → Blob，正确处理各格式 */
+    private _canvasToBlob;
     /**
      * 解析 openInStudio 的输入来源：
      * - URL 直传给 Studio
      * - data URL / Blob / File 先上传 OSS
-     * - 未传时回退到 provider canvas
+     * - 未传时通过 provider 按 format 获取数据
      */
     private _resolveStudioAsset;
     /** 获取或懒初始化 Uploader 实例 */
@@ -358,10 +413,16 @@ declare class ExportModule {
     private _uploadFile;
     /** 通过 xtool:// 协议打开 Studio */
     private _openStudioProtocol;
+    /** 导出格式 → MIME 类型（仅位图格式） */
+    private _formatToMimeType;
+    /** data URL → Blob */
+    private _dataUrlToBlob;
     /** data URL → File 对象 */
     private _dataUrlToFile;
     /** Blob → File 对象 */
     private _blobToFile;
+    /** 从 data URL 推断文件扩展名 */
+    private _detectDataUrlExtension;
     /** 判断是否为 data URL */
     private _isDataUrl;
     /** 判断是否为可直接交给 Studio 的远程 URL */
@@ -370,24 +431,48 @@ declare class ExportModule {
     private _mimeTypeToExtension;
 }
 
+/**
+ * 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;
+}
+
 /** export.openInStudio() 返回值 */
 export declare interface ExportOpenInStudioResult {
     success: boolean;
 }
 
-/** export.openInStudio() 输入源 */
+/** 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 {
     /**
-     * 获取导出用的 Canvas
-     * @param purpose 用途：download=下载 studio=打开到Studio cover=封面
+     * 获取导出数据（灵活方式，优先级高于 getExportCanvas）
+     * 适用于非 canvas 场景：SVG 编辑器、DOM 截图、纯数据生成等
      */
-    getExportCanvas: (purpose: ExportPurpose) => HTMLCanvasElement | Promise<HTMLCanvasElement | null> | null;
+    getExportData?: (purpose: ExportPurpose, format: ExportFormat) => ExportData | Promise<ExportData | null> | null;
+    /**
+     * 获取导出用的 Canvas（传统方式）
+     * 当 getExportData 未实现或返回 null 时回退到此方法
+     */
+    getExportCanvas?: (purpose: ExportPurpose) => HTMLCanvasElement | Promise<HTMLCanvasElement | null> | null;
     /** 自定义文件名生成器（可选） */
     getFileName?: (purpose: ExportPurpose) => string;
 }
@@ -396,6 +481,8 @@ export declare interface ExportProvider {
 export declare type ExportPurpose = 'download' | 'studio' | 'cover';
 
 export declare class GeneratorSDK {
+    /** 最近一次初始化使用的 appKey，供全局场景读取 */
+    private static lastInitializedAppKey;
     /** 登录/退出/用户信息 */
     readonly auth: AuthModule;
     /** 云保存/恢复/删除 */
@@ -413,6 +500,10 @@ export declare class GeneratorSDK {
     private readonly appKey;
     private readonly env;
     private constructor();
+    /**
+     * 返回当前 SDK 实例绑定的 appKey
+     */
+    getAppKey(): string;
     /**
      * 初始化 SDK，返回 SDK 实例
      *
@@ -424,6 +515,10 @@ export declare class GeneratorSDK {
      * ```
      */
     static init(options: SdkInitOptions): GeneratorSDK;
+    /**
+     * 返回最近一次初始化使用的 appKey
+     */
+    static getAppKey(): string | null;
     /**
      * 清除实例缓存（测试场景使用）
      */

package/dist/index.es.js

@@ -1,4 +1,4 @@
-import { G, S, T, w } from "./index-qYdFih-w.js";
+import { G, S, T, w } from "./index-DP-Q2Dkh.js";
 export {
   G as GeneratorSDK,
   S as SdkError,