@jetprint/editor-sdk 1.0.0

package/dist/types.d.ts

@@ -0,0 +1,483 @@
+import type { Component, ComputedRef, InjectionKey, Ref } from 'vue';
+import type { EditorLocale } from './locales/editor-locales';
+export type ProductItem = {
+    id?: number | string;
+    name?: string;
+    description?: string;
+    coverImg?: string;
+};
+export type BasicInfo = {
+    id?: number | string;
+    name?: string;
+    description?: string;
+    sizes?: string[];
+    colors?: string[];
+    /** 与 colors 下标对应的中文名（如 basic 接口 colorNamesZh） */
+    colorNamesZh?: string[];
+    /** 与 colors 下标对应的英文名，常与 colors 相同 */
+    colorNamesEn?: string[];
+    /** 部分详情接口字段，语义同 colorNamesZh */
+    colorsZh?: string[];
+    coverImg?: string;
+    /** 产品 SKU 编码（如 QYB37） */
+    sku?: string;
+};
+export type DiecutResource = {
+    groupId?: string;
+    groupName?: string;
+    fileName?: string;
+    url?: string;
+    type?: string;
+    width?: number;
+    height?: number;
+};
+export type DiecutItem = {
+    jsonURL?: string | null;
+    size?: string;
+    type?: string;
+    resources?: DiecutResource[] | null;
+    sizeMode?: string;
+};
+export type DiecutResponse = {
+    msg?: string;
+    code?: number;
+    data?: DiecutItem[];
+};
+/**
+ * 与刀板接口 `data[]` 单项字段一致。
+ * 已通过画布加载的模板：`jsonURL` 为解析后的 PSD/Comp JSON 对象；否则仍为接口返回的 URL 字符串。
+ */
+export type DiecutStateMapDataItem = {
+    jsonURL?: string | Record<string, unknown> | null;
+    /** 内联 jsonURL 为对象时保留原模板 URL，供还原进页写入 templateJsonByUrlKey */
+    _originalSplitTemplateJsonURL?: string;
+    size?: string;
+    type?: string;
+    resources?: DiecutResource[] | null;
+    sizeMode?: string;
+};
+export type DeformationInfo = {
+    name?: string;
+    jsonURL?: string;
+    sort?: number;
+    resources?: Array<{
+        name?: string;
+        url?: string;
+    }>;
+};
+export type DeformationGroup = {
+    size?: string;
+    sizeMode?: string;
+    infos?: DeformationInfo[] | null;
+};
+export type DeformationSizeGroup = {
+    size?: string;
+    sizeMode?: string;
+    infos?: DeformationInfo[] | null;
+};
+export type DeformationColorGroup = {
+    color?: string;
+    sizes?: DeformationSizeGroup[];
+};
+export type DeformationResponse = {
+    msg?: string;
+    code?: number;
+    data?: DeformationGroup[] | DeformationColorGroup[];
+};
+/** 编辑器界面皮肤（与图库筛选 theme 无关） */
+export type EditorUiTheme = 'default' | 'theme1';
+export declare const EDITOR_UI_THEMES: readonly EditorUiTheme[];
+export declare function isEditorUiTheme(value: string): value is EditorUiTheme;
+/** 未设置或省略 `options.uiTheme` 时视为 `theme1`；仅显式 `'default'` 为靛蓝默认主题。 */
+export declare function resolveEditorUiTheme(uiTheme: EditorUiTheme | undefined): EditorUiTheme;
+/** 阶梯价区间（白板详情） */
+export type WhiteboardPriceRangeForCart = {
+    unitPrice: number;
+    minQuantity: number;
+    maxQuantity: number;
+};
+/**
+ * 加购弹窗所需白板/产品信息（与常见 getWhiteboardDetail 返回 data 对齐；宿主可传更全字段）。
+ */
+export type WhiteboardDetailForCart = {
+    whiteboardId: string;
+    name: string;
+    coverImg?: string | null;
+    sizes?: string[] | null;
+    colors?: string[] | null;
+    colorsZh?: string[] | null;
+    colorNamesZh?: string[] | null;
+    colorNamesEn?: string[] | null;
+    colorValues?: string[] | null;
+    priceRanges?: WhiteboardPriceRangeForCart[] | null;
+    productNo?: string | null;
+    sku?: string;
+};
+export type AddToCartLineItem = {
+    size: string;
+    quantity: number;
+    color?: string;
+};
+export type AddToCartSubmitInput = {
+    formData: FormData;
+    mode: 'create' | 'edit';
+    editMeta?: {
+        psTaskId: string;
+        whiteboardId: string;
+    };
+};
+export type AddToCartSubmitResult = {
+    code?: number;
+    msg?: string;
+    addedCount?: number;
+    psTaskCode?: string;
+};
+export type AddToCartFetchDetailResult = {
+    ok: true;
+    data: WhiteboardDetailForCart;
+} | {
+    ok: false;
+    msg?: string;
+};
+export type AddToCartSubmitResponse = {
+    ok: true;
+    result?: AddToCartSubmitResult;
+} | {
+    ok: false;
+    msg?: string;
+};
+/** 宿主注入：拉白板详情 + 提交 FormData（新建/编辑加车） */
+export type EditorAddToCartAdapter = {
+    fetchDetail: (whiteboardId: string) => Promise<AddToCartFetchDetailResult>;
+    submit: (input: AddToCartSubmitInput) => Promise<AddToCartSubmitResponse>;
+    /** 后台渲染完成后，按颜色类型追加资源图（cover__{colorKey}、design__{colorKey}） */
+    appendResources?: (psTaskCode: string, formData: FormData) => Promise<void>;
+};
+export type EditorOptions = {
+    showTopbar?: boolean;
+    showSidebar?: boolean;
+    showPreview?: boolean;
+    enableGrid?: boolean;
+    usePreviewEffect?: boolean;
+    /**
+     * 为 true 时，预览区使用常驻 WebGL（Three.js + OrbitControls）展示与 renderByJsonWithThree 一致的合成图，
+     * 并跳过右上角 Worker 小图渲染（仍可走大图/下载等路径）。默认 false。
+     */
+    useLiveWebglPreview?: boolean;
+    /** 与 useLiveWebglPreview 配套：主线程 renderByJsonWithThree 内部分辨率边长，默认 640，范围建议 256～1024 */
+    liveWebglInternalRenderSize?: number;
+    showPreviewDownload?: boolean;
+    showImageButton?: boolean;
+    /** 为 true 时，顶部「图片」选文件直接加入画布，不调用图库上传（即使已注入 galleryApi） */
+    topbarImageSkipGallery?: boolean;
+    /**
+     * 进入编辑器时左侧栏默认选中的 tab id（须为内置或 customSidebarTabs 中的 id）。
+     * 若未设置或 id 无效，则沿用默认：theme1 为 productDetail（无产品列表 Tab）；有 galleryApi 时为 gallery；列表模式为 product；否则为 layer。
+     */
+    initialSidebarTab?: string;
+    /** 为 true 时顶栏隐藏颜色/尺码/文字/清空及加车/保存（宿主配合不传回调） */
+    readOnly?: boolean;
+    /** 为 true 时禁止在 Classic / Zone 模式之间切换，但保留其它编辑能力 */
+    lockTemplateModeSwitch?: boolean;
+    /**
+     * 界面主题：省略时与 `theme1` 相同（粉主色 + 藏青保存）；显式 `'default'` 为现有靛蓝/蓝配色。
+     */
+    uiTheme?: EditorUiTheme;
+    /** 为 true 时在顶栏「清空画布」右侧显示界面主题下拉，变更时向宿主 emit `update:uiTheme` */
+    showUiThemeSelect?: boolean;
+    /**
+     * theme1「上传」Tab：用户通过内置 file input 选图后，将 `File` 交给宿主上传；完成后请调用编辑器 `defineExpose` 的 `addImageFromUrl(url)` 加入画布。
+     */
+    onTheme1UploadLocalFiles?: (file: File) => void | Promise<void>;
+    /**
+     * 内置加购弹窗：注入 fetchDetail + submit 后，顶栏与 theme1 Mockup「加购」走 SDK 弹窗。
+     * 配置后不再调用 props.onAddToCart（由宿主只传 adapter + 成功/失败回调即可）。
+     */
+    addToCart?: EditorAddToCartAdapter;
+    /** 编辑任务流：如有 psTaskId，json 文件名使用 design-${psTaskId}；designName 用于弹窗展示已有设计名称 */
+    addToCartEditMeta?: {
+        psTaskId?: string;
+        designName?: string;
+    };
+    /**
+     * 价格展示用货币符号（如 ¥、$、元），由宿主传入。
+     * 未设置时内置加购弹窗默认使用 ¥。
+     */
+    currencySymbol?: string;
+    /**
+     * 顶栏左侧整块替换为传入组件（与 `#topbar-left` 插槽二选一：插槽优先）。
+     * 注入 `EDITOR_TOPBAR_CONTEXT_KEY` 可调用保存/加购等。
+     */
+    topbarLeftComponent?: Component;
+    topbarLeftProps?: Record<string, unknown>;
+    /**
+     * 顶栏右侧整块替换为传入组件（与 `#topbar-right` 插槽二选一：插槽优先）。
+     */
+    topbarRightComponent?: Component;
+    topbarRightProps?: Record<string, unknown>;
+    /**
+     * 为 true 时进入实时渲染模式：中间画布区仅显示纯 fabric canvas（无刀板选择/复制等辅助 UI），
+     * 右侧预览区替换为 liveRenderComponent（宿主传入的 ThreeRenderViewer 等 3D 实时变形渲染组件）。
+     * 默认 false。
+     */
+    isLiveRender?: boolean;
+    /** 实时渲染模式下右侧预览区使用的组件（如 ThreeRenderViewer）；需与 isLiveRender 配合使用 */
+    liveRenderComponent?: Component;
+    /** 传给 liveRenderComponent 的额外 props（fileToken / newDataList / designPic 等由 Editor 内部自动注入） */
+    liveRenderComponentProps?: Record<string, unknown>;
+    /** 为 true 时隐藏顶栏「实时渲染 / 退出渲染」切换按钮（仍可通过 options.isLiveRender 等控制模式） */
+    hideLiveRenderTopbarToggle?: boolean;
+    /** 为 false 时隐藏顶栏「快捷键」入口与自定义快捷键 Modal；默认 true */
+    showShortcutSettings?: boolean;
+};
+/** getDiecutStateMap() 的返回类型：画布状态 + 当前选中的颜色、尺码、单片/多片模式 + 刀板 data（jsonURL 已解析时内联对象） */
+export type DiecutStateMapResult = {
+    stateMap: Record<string, unknown>;
+    selectedColor: string;
+    selectedSize: string;
+    /** theme1 复选：当前勾选的颜色（含 all 占位） */
+    selectedColors?: string[];
+    /** theme1 复选：当前勾选的尺码（含 all 占位） */
+    selectedSizes?: string[];
+    /** 当前模板模式：'COMPLETE'（单片）或 'SPLIT'（多片） */
+    selectedMode: 'COMPLETE' | 'SPLIT';
+    /** fabric 逻辑画布宽度（与导出 JSON 坐标系一致） */
+    designCanvasSize: number;
+    /** fabric 逻辑画布高度；缺省还原时按 CANVAS_LOGICAL_HEIGHT(2000) 处理 */
+    designCanvasHeight?: number;
+    /** 当前 SDK 版本号 */
+    version: string;
+    /** 与 `client/whiteboard/diecut` 响应中的 `data` 字段结构一致 */
+    data: DiecutStateMapDataItem[];
+};
+/** 按颜色分组的全部模板渲染结果 */
+export type RenderAllTemplatesByColorGroup = {
+    color: string;
+    templates: Array<{
+        index: number;
+        blob: Blob;
+        name?: string;
+    }>;
+};
+/** 编辑器向内置加购弹窗暴露的能力（由 Editor 内部组装） */
+export type EditorAddToCartEditorBridge = {
+    getWhiteboardId: () => string;
+    getSelectedColor: () => string;
+    getSelectedSize: () => string;
+    getSelectedColors?: () => string[];
+    getSelectedSizes?: () => string[];
+    getSku: () => string;
+    getProductName: () => string;
+    getDiecutStateMap: () => DiecutStateMapResult;
+    renderAllTemplates: () => Promise<Array<{
+        index: number;
+        bitmap: ImageBitmap | null;
+        blob?: Blob | null;
+    }>>;
+    getCurrentPreviewImageBlob: (opts?: {
+        renderSize?: number;
+    }) => Promise<Blob | null>;
+    getPreviewImageBlobByIndex?: (index: number, opts?: {
+        renderSize?: number;
+    }) => Promise<Blob | null>;
+    collectRenderBundle: () => Promise<import('./utils/renderedImagesDB').RenderBundle>;
+    /** 渲染当前尺码下所有颜色的全部模板，按颜色分组（与保存设计后台 renderByJson 一致） */
+    renderAllTemplatesByColor?: () => Promise<RenderAllTemplatesByColorGroup[]>;
+    setSelectedColor?: (color: string) => void;
+    setSelectedSize?: (size: string) => void;
+    getColorOptions?: () => string[];
+};
+/** 内置左侧栏 tab id，自定义 tab 的 id 不得与这些冲突 */
+export declare const EDITOR_BUILTIN_SIDEBAR_TAB_IDS: readonly ["add", "addText", "gallery", "layer", "product", "productDetail", "upload"];
+/**
+ * 左侧栏扩展 Tab：传入 Vue 组件作为内容区；id 勿与内置 id（含 productDetail、addText、upload）重复。
+ */
+export type CustomSidebarTabDef = {
+    id: string;
+    label: string;
+    component: Component;
+    props?: Record<string, unknown>;
+    iconComponent?: Component;
+};
+/** inject 用：自定义侧栏面板内可获取与画布相关的能力 */
+export type EditorSidebarContext = {
+    getDiecutStateMap: () => DiecutStateMapResult;
+    /** 按图片 URL 向当前画布添加图片（与图库选图行为一致） */
+    addImageFromUrl: (url: string) => void | Promise<void>;
+};
+export declare const EDITOR_SIDEBAR_CONTEXT_KEY: InjectionKey<EditorSidebarContext>;
+/** Topbar / theme1 Mockup 顶栏自定义区 inject：保存、加购与能力位与内置按钮一致 */
+export type EditorTopbarContext = {
+    readOnly: ComputedRef<boolean>;
+    uiTheme: ComputedRef<EditorUiTheme>;
+    locale: Ref<EditorLocale>;
+    productName: ComputedRef<string>;
+    requestSaveDesign: () => void | Promise<void>;
+    requestAddToCart: () => void | Promise<void>;
+    /** 进入「全部尺码 / 颜色」分组大图预览（Next） */
+    requestNextPreview?: () => void | Promise<void>;
+    canSave: ComputedRef<boolean>;
+    canAddToCart: ComputedRef<boolean>;
+    /** 是否显示 Next（theme1 非只读，有可分组预览的尺码/颜色） */
+    canNextPreview?: ComputedRef<boolean>;
+    /** 当前是否在 theme1 全屏 Mockup 顶栏内（便于宿主区分样式） */
+    isMockup: ComputedRef<boolean>;
+    /** 当前是否处于实时渲染模式 */
+    isLiveRender: ComputedRef<boolean>;
+    /** 切换实时渲染模式 */
+    toggleLiveRender: () => void;
+    /** 是否支持实时渲染模式（宿主传入了 liveRenderComponent） */
+    canLiveRender: ComputedRef<boolean>;
+};
+export declare const EDITOR_TOPBAR_CONTEXT_KEY: InjectionKey<EditorTopbarContext>;
+export type EditorProps = {
+    product?: ProductItem | null;
+    basicInfo?: BasicInfo | null;
+    diecutData?: DiecutResponse | null;
+    deformationData?: DeformationResponse | null;
+    options?: EditorOptions;
+    productListApi?: ProductListApi;
+    productDetailApi?: ProductDetailApi;
+    productListPageSize?: number;
+    productListInitialPage?: number;
+    /** 进入页面时默认选中的产品 ID（来自 URL）。仅当该产品在第一页列表中时才选中，否则不选 */
+    initialProductId?: string | number;
+    fileBaseUrl?: string;
+    fileToken?: string | null;
+    onObjectModified?: (getDiecutStateMap: () => DiecutStateMapResult) => void;
+    onRenderAllTemplates?: (renderMethod: () => Promise<Array<{
+        index: number;
+        bitmap: ImageBitmap | null;
+    }>>) => Promise<Array<{
+        index: number;
+        bitmap: ImageBitmap | null;
+    }> | void>;
+    /** 保存设计：传入则在 Topbar 显示按钮，点击时调用 */
+    onSaveDesign?: () => void | Promise<void>;
+    /** 加入购物车：传入则在 Topbar「保存设计」左侧显示按钮，点击时调用 */
+    onAddToCart?: () => void | Promise<void>;
+    /** 内置加购成功（如顶栏提示）；仅 options.addToCart 生效时由 Editor 调用 */
+    onAddToCartSuccess?: (payload?: {
+        addedCount?: number;
+        psTaskCode?: string;
+    }) => void;
+    /** 内置加购失败或校验失败；仅 options.addToCart 生效时由 Editor 调用 */
+    onAddToCartError?: (msg?: string) => void;
+    /** 返回（如上一页）：传入则在 Topbar 显示，点击时调用 */
+    onGoHome?: () => void;
+    /** 首次模板加载完成后调用（用于从 completeJsonUrl 还原设计）；可 async，SDK 会 await */
+    onTemplateReady?: () => void | Promise<void>;
+    /**
+     * 界面语言，与主应用一致：zh-CN | en-US | ja-JP | ko-KR | vi-VN；兼容旧值 zh / en。
+     * 切换语言时可通过 @update:locale 同步宿主。
+     */
+    locale?: string;
+    /** 覆盖内置文案，key 与 sdk locales 一致 */
+    messages?: Record<string, string>;
+    /** 左侧栏额外 Tab（竖条 + 内容区由宿主传入 Vue 组件） */
+    customSidebarTabs?: CustomSidebarTabDef[];
+};
+export type ProductListResult = {
+    rows: ProductItem[];
+    total?: number;
+};
+export type ProductListApi = (page: number, pageSize: number) => Promise<ProductListResult>;
+export type ProductDetailResult = {
+    basicInfo?: BasicInfo | null;
+    diecutData?: DiecutResponse | null;
+    deformationData?: DeformationResponse | null;
+};
+export type ProductDetailApi = (productId: number | string) => Promise<ProductDetailResult>;
+export type LicenseConfig = {
+    licenseKey: string;
+    apiBaseUrl: string;
+    timeout?: number;
+    enableAutoRefresh?: boolean;
+    refreshThreshold?: number;
+    onError?: (error: string) => void;
+    onSuccess?: () => void;
+    onTokenRefresh?: (token: string) => void;
+};
+export interface GalleryMaterialItem {
+    id: string;
+    parentId: string;
+    name: string;
+    type: number;
+    fileUrl: string | null;
+    fileType?: string | null;
+    fileSize?: string | null;
+    imageWidth?: number | null;
+    imageHeight?: number | null;
+    createTime?: string;
+    children?: GalleryMaterialItem[];
+}
+export interface GalleryFilterOptionsData {
+    theme?: Array<{
+        label: string;
+        value: string;
+    }>;
+    style?: Array<{
+        label: string;
+        value: string;
+    }>;
+    process?: Array<{
+        label: string;
+        value: string;
+    }>;
+    designArea?: Array<{
+        label: string;
+        value: string;
+    }>;
+}
+export interface GalleryApi {
+    getMaterialTree: () => Promise<{
+        data?: {
+            code?: number;
+            data?: GalleryMaterialItem[];
+        };
+    }>;
+    getMaterialPage: (params: {
+        parentId: string | number;
+        pageNum: number;
+        pageSize: number;
+        name?: string;
+        orderBy?: 'updateTime_desc' | 'updateTime_asc' | 'fileSize_desc' | 'fileSize_asc';
+    }) => Promise<{
+        data?: {
+            code?: number;
+            rows?: GalleryMaterialItem[];
+            total?: number;
+        };
+    }>;
+    uploadMaterial: (file: File, parentId: string | number) => Promise<unknown>;
+    getPublicTree: () => Promise<{
+        data?: {
+            code?: number;
+            data?: GalleryMaterialItem[];
+        };
+    }>;
+    getFilterOptions: () => Promise<{
+        data?: {
+            code?: number;
+            data?: GalleryFilterOptionsData;
+        };
+    }>;
+    getPublicPage: (params: {
+        parentId: string | number;
+        pageNum: number;
+        pageSize: number;
+        name?: string;
+        theme?: string;
+        style?: string;
+        process?: string;
+        designArea?: string;
+        fileFormat?: string;
+        orderBy?: string;
+    }) => Promise<{
+        data?: {
+            code?: number;
+            rows?: GalleryMaterialItem[];
+            total?: number;
+        };
+    }>;
+}

package/dist/utils/backgroundRenderer.d.ts

@@ -0,0 +1,64 @@
+import { type RenderBundle, type FabricScreenshotBlob } from './renderedImagesDB';
+import { getLicenseInfo } from './license/licenseStore';
+export interface BackgroundRenderJob {
+    taskId: string;
+    /** 完整渲染数据包（优先使用：后台直接调用 renderByJson 合成） */
+    renderBundle?: RenderBundle;
+    /** 旧路径：由编辑器实时渲染（renderBundle 不存在时回退） */
+    renderAllTemplates?: () => Promise<Array<{
+        index: number;
+        blob: Blob;
+    }>>;
+    /** 由调用方提供的图片上传函数，避免 SDK 依赖主项目 API */
+    uploadImages?: (taskId: string, images: Array<{
+        index: number;
+        blob: Blob;
+        fileName: string;
+    }>) => Promise<void>;
+    /** 所有模板渲染完成且 cover 图片上传完成后调用，用于上传 fabricScreenshotList */
+    onDesignScreenshotsReady?: (taskId: string, fabricScreenshots: FabricScreenshotBlob[]) => Promise<void>;
+    /**
+     * 增量上传回调。渲染过程中每产生一批图片就调用一次。
+     * - 第1张渲染完成时立即调用（batchIndex=0）
+     * - 之后每渲染完成3张调用一次
+     * - 最后不满3张的剩余图片也会调用一次
+     */
+    onBatchReady?: (taskId: string, images: Array<{
+        index: number;
+        blob: Blob;
+        fileName: string;
+    }>, batchIndex: number) => Promise<void>;
+    designName?: string;
+    /** 预先快照的 license（在组件卸载前捕获，避免渲染时 license 已被清除） */
+    licenseSnapshot?: ReturnType<typeof getLicenseInfo>;
+    /** 渲染+上传完成后回调，用于链式触发其他颜色的渲染 */
+    onComplete?: () => Promise<void>;
+    /** 图片命名参数，传入后封面图使用 {sku}-{size}-{color}-{designCode}-c-{index}.jpg 格式 */
+    imageNaming?: {
+        sku: string;
+        size: string;
+        color: string;
+        designCode: string;
+    };
+}
+/**
+ * 保存成功后立刻写入占位任务（rendering、images: []），再异步 collectRenderBundle。
+ * 避免用户先于 collect 进入「我的设计」时 IndexedDB 尚无记录，getRenderTask 为空、列表无法轮询。
+ */
+export declare function putRenderTaskPlaceholder(taskId: string): Promise<void>;
+export declare function startBackgroundRender(job: BackgroundRenderJob): Promise<void>;
+/** 将 renderBundle 内所有模板合成为 Blob 列表（不写 IndexedDB，供多颜色同步渲染） */
+export declare function renderBundleToBlobs(bundle: RenderBundle, licenseSnapshot?: ReturnType<typeof getLicenseInfo>): Promise<Array<{
+    index: number;
+    blob: Blob;
+}>>;
+export declare function resumePendingTasks(renderAllTemplatesFactory?: (taskId: string) => () => Promise<Array<{
+    index: number;
+    blob: Blob;
+}>>, uploadImages?: BackgroundRenderJob['uploadImages']): Promise<void>;
+export declare function cleanup(): Promise<void>;
+/**
+ * 包装 startBackgroundRender，返回一个 Promise，在渲染+上传+onComplete 全部完成后 resolve。
+ * 用于多颜色顺序渲染：当前颜色完成后再启动下一个颜色。
+ */
+export declare function startBackgroundRenderAsync(job: BackgroundRenderJob): Promise<void>;

package/dist/utils/encryptJson.d.ts

@@ -0,0 +1,31 @@
+/**
+ * 生成固定密钥
+ * 使用固定的基础字符串，确保每次生成的密钥都相同
+ * 这样加密和解密可以使用相同的密钥
+ */
+export declare function generateFixedKey(): string;
+/**
+ * 获取加密密钥
+ * 优先使用环境变量，如果没有则使用固定密钥
+ */
+export declare function getEncryptionKey(): string;
+/**
+ * 清理 JSON 数据，确保所有 blob URL 都被替换为 base64
+ * @param jsonData - 要处理的 JSON 数据
+ * @returns 处理后的 JSON 数据
+ */
+export declare function cleanBlobUrls(jsonData: unknown): unknown;
+/**
+ * 加密 JSON 数据
+ * @param jsonData - 要加密的 JSON 对象
+ * @param key - 加密密钥（可选，默认使用固定密钥）
+ * @returns 加密后的字符串（Base64 格式）
+ */
+export declare function encryptJsonData(jsonData: unknown, key?: string): string;
+/**
+ * 解密 JSON 数据
+ * @param encryptedData - 加密后的字符串
+ * @param key - 解密密钥（可选，默认使用固定密钥）
+ * @returns 解密后的 JSON 对象
+ */
+export declare function decryptJsonData<T = unknown>(encryptedData: string, key?: string): T;

package/dist/utils/environment.d.ts

@@ -0,0 +1,29 @@
+/**
+ * 环境检测工具
+ */
+export declare class Environment {
+    /**
+     * 是否在浏览器环境
+     */
+    static isBrowser(): boolean;
+    /**
+     * 是否在 Worker 环境
+     */
+    static isWorker(): boolean;
+    /**
+     * 是否支持 localStorage
+     */
+    static hasLocalStorage(): boolean;
+    /**
+     * 是否支持 Canvas
+     */
+    static hasCanvas(): boolean;
+    /**
+     * 获取当前域名
+     */
+    static getDomain(): string;
+    /**
+     * 获取当前源（origin）
+     */
+    static getOrigin(): string;
+}

package/dist/utils/errorHandler.d.ts

@@ -0,0 +1,27 @@
+export declare enum ErrorLevel {
+    INFO = "info",
+    WARN = "warn",
+    ERROR = "error"
+}
+export interface ErrorOptions {
+    level?: ErrorLevel;
+    context?: string;
+    metadata?: Record<string, any>;
+}
+/**
+ * 统一的错误处理工具
+ */
+export declare class ErrorHandler {
+    /**
+     * 处理错误
+     */
+    static handle(error: any, options?: ErrorOptions): string;
+    /**
+     * 提取错误信息
+     */
+    private static extractErrorMessage;
+    /**
+     * 创建错误对象
+     */
+    static createError(message: string, originalError?: any): Error;
+}

package/dist/utils/fileToken.d.ts

@@ -0,0 +1,18 @@
+export declare function getFileToken(): string | null;
+export declare function isFileTokenExpired(bufferMs?: number): boolean;
+export declare function clearFileToken(): void;
+type FileTokenFetchers = {
+    fetchFileToken: () => Promise<any>;
+    fetchFileTokenRefresh?: () => Promise<any>;
+};
+export declare function setFileTokenFetchers(fetchers: FileTokenFetchers | null): void;
+export declare function setExternalFileToken(token: string | null): void;
+export declare function getExternalFileToken(): string | null;
+export declare function getFileTokenFetchers(): FileTokenFetchers | null;
+export declare function ensureFileToken(): Promise<string | null>;
+export declare function appendFileTokenToUrl(url: string, token?: string | null): string;
+export declare function appendFileTokenIfPresent(url: string): string;
+export declare function stripFileTokenParam(url: string): string;
+export declare function withFileToken(url: string): Promise<string>;
+export declare function fetchWithFileToken(url: string, options?: RequestInit): Promise<Response>;
+export {};

package/dist/utils/http.d.ts

@@ -0,0 +1,31 @@
+export interface HttpOptions {
+    method?: 'GET' | 'POST' | 'PUT' | 'DELETE';
+    headers?: Record<string, string>;
+    body?: any;
+    timeout?: number;
+}
+export interface HttpResponse<T = any> {
+    success: boolean;
+    data?: T;
+    error?: string;
+}
+/**
+ * 统一的 HTTP 请求工具
+ */
+export declare class HttpClient {
+    baseUrl: string;
+    private defaultTimeout;
+    constructor(baseUrl: string, timeout?: number);
+    /**
+     * 发送 HTTP 请求
+     */
+    request<T = any>(endpoint: string, options?: HttpOptions): Promise<HttpResponse<T>>;
+    /**
+     * POST 请求
+     */
+    post<T = any>(endpoint: string, body?: any, options?: Omit<HttpOptions, 'method' | 'body'>): Promise<HttpResponse<T>>;
+    /**
+     * GET 请求
+     */
+    get<T = any>(endpoint: string, options?: Omit<HttpOptions, 'method'>): Promise<HttpResponse<T>>;
+}