@volcengine/amk-editor 0.0.2-beta.1 → 0.0.3

package/dist/public-types.d.ts

@@ -5,6 +5,23 @@
  * 避免公网用户安装 amk-editor 时还需要访问内网依赖。
  */
 export type VeVeditorTheme = 'light' | 'dark';
+export type VeVeditorMediaErrorCategory = 'aborted' | 'network' | 'network_or_cors' | 'decode' | 'unsupported' | 'cors' | 'render' | 'initialization' | 'unknown';
+export interface VeVeditorMediaError {
+    name: 'VideoEditorMediaError';
+    type: 'video' | 'audio' | 'image' | string;
+    phase: 'init' | 'load' | 'decode' | 'render';
+    code: string;
+    category: VeVeditorMediaErrorCategory;
+    message: string;
+    url?: string;
+    nativeCode?: number;
+    possibleCauses: string[];
+    cause?: {
+        name?: string;
+        message: string;
+    };
+    originalEvent?: Event;
+}
 export interface VeVeditorMaterialItem {
     id?: string;
     type?: 'video' | 'audio' | 'image' | string;
@@ -104,8 +121,8 @@ export interface VeVeditorOptions<TMaterialOptions = VeVeditorMaterialOptions, T
         action?: 'delete' | 'add';
         item?: unknown;
     }) => void;
-    onNodePreviewError?: (type: 'video' | 'audio', node: unknown) => void;
-    onPreviewNodeRefresh?: (type: 'video' | 'audio', node: unknown) => void | Promise<void>;
+    onNodePreviewError?: (type: 'video' | 'audio' | 'image', node: unknown, error?: VeVeditorMediaError) => void;
+    onPreviewNodeRefresh?: (type: 'video' | 'audio' | 'image', node: unknown) => void | Promise<void>;
     onBeforeUndo?: (payload: unknown) => boolean | void;
     onBeforeRedo?: (payload: unknown) => boolean | void;
     onBeforeTimestampMount?: (params: Record<string, unknown>) => boolean | Promise<boolean>;

package/dist/refresh-play-info.d.ts

@@ -1,7 +1,9 @@
 import type { MaterialItem } from './types';
 /**
  * 业务方回写的播放信息补丁；未返回的字段保持原样。
- * 按 SDK 内部 material_id 匹配目标素材；可更新 url / poster / sprite / source_material_id 等。
+ * 优先按 SDK 内部 material_id 匹配，随后按业务 source_material_id 兜底；
+ * 两个标识都没有的补丁才按数组下标兜底。
+ * 可更新 url / poster / sprite / source_material_id 等。
  * material_id 为 SDK 内部字段，补丁中的同名字段会被忽略。
  */
 export type MaterialPlayInfoPatch = Partial<MaterialItem> & {

package/dist/task-polling.d.ts

@@ -4,6 +4,6 @@ export type TaskPollingController = {
 };
 export declare function startTaskPolling(options: {
     poll: () => Promise<boolean>;
-    onError?: (error: unknown) => void;
+    onError?: (error: unknown) => void | Promise<void>;
     getDelayMs?: (attempt: number) => number;
 }): TaskPollingController;

package/dist/task-query-status.d.ts

@@ -0,0 +1,10 @@
+/**
+ * 查询任务信息 API 的官方响应状态。
+ * @see https://docs.volcengine.com/docs/6448/2278532?lang=zh
+ */
+export type AmkTaskQueryStatus = 'running' | 'completed' | 'failed';
+/**
+ * `success` 表示查询请求本身是否成功；查询成功后才读取任务 `status`。
+ * 非官方响应同样按失败收口，避免未知响应被无限轮询。
+ */
+export declare function resolveAmkTaskQueryStatus(payload: unknown): AmkTaskQueryStatus;

package/dist/tos-upload.d.ts

@@ -31,12 +31,23 @@ interface RefreshTosMaterialUrlsOptions {
     storage: AmkEditorStorageConfig;
     createClient?: UploadFilesToTosOptions['createClient'];
 }
+/** TOS 素材的稳定标识已包含 bucket 与 object key，无需额外持久化内部字段。 */
+export declare function parseTosResourceUrl(value: unknown): {
+    bucket: string;
+    key: string;
+} | null;
 /** 使用宿主下发的临时 STS 将本地文件直传客户 TOS，并转换为编辑器素材。 */
 export declare function uploadFilesToTos(options: UploadFilesToTosOptions): Promise<MaterialItem[]>;
 /** 为已持久化的私有 TOS 素材重新生成播放签名，供初始化和按需刷新使用。 */
 export declare function refreshTosMaterialUrls(options: RefreshTosMaterialUrlsOptions): Promise<Array<Partial<MaterialItem> & {
     material_id: string;
 }>>;
+/** 将任意任务产物中的 tos:// 地址批量签成浏览器可访问的 HTTP URL。 */
+export declare function signTosResourceUrls(options: {
+    urls: unknown[];
+    storage: AmkEditorStorageConfig;
+    createClient?: UploadFilesToTosOptions['createClient'];
+}): Promise<unknown[]>;
 /** 为资产库导入的 TOS 素材签发播放 URL；稳定身份仍保留在 source_material_id。 */
 export declare function signTosImportedMaterialUrls(options: {
     materials: MaterialItem[];

package/dist/types.d.ts

@@ -24,13 +24,13 @@ export interface AmkMaterialImportRequestOptions {
     onMaterialsImported?: (materials: MaterialItem[]) => void | Promise<void>;
 }
 /**
- * 抽帧产物存储 key 的推荐命名，仅用于提供接入提示，不属于强制素材 Schema。
- * 业务可以直接使用这两个字段，也可以把 key 放进任意自定义字段或嵌套对象。
+ * 抽帧产物的稳定存储身份。TOS 产物会保存完整 `tos://bucket/key`，
+ * SDK 用它在签名 URL 过期后重新签发；非 TOS 业务仍可使用自定义字段。
  */
 export interface RecommendedExtractStorageFields {
-    /** 推荐字段：封面图业务存储 key；业务也可以使用自定义字段。 */
+    /** 封面图稳定身份；内置 TOS 链路保存 `tos://bucket/key`。 */
     poster_storage_key?: string;
-    /** 推荐字段：与 sprite.storeurls 对应的业务存储 key；也可自定义。 */
+    /** 与 sprite.storeurls 等长的稳定身份数组；内置 TOS 链路保存 tos:// 地址。 */
     sprite_storage_keys?: string[];
 }
 export interface PersistExtractUrlsResult {
@@ -60,7 +60,8 @@ export interface MaterialConfig {
     onMaterialsImported?: (materials: MaterialItem[]) => void | Promise<void>;
     /**
      * 刷新播放信息。未配置时用素材库已有字段；
-     * 配置后：入参为待刷新素材列表（按服务端 material_id 区分，支持批量），
+     * 配置后：入参为待刷新素材列表，支持批量；返回补丁优先按 material_id 匹配，
+     * source_material_id 次之，两者都未返回时才按数组顺序兜底，
      * 返回单条或数组补丁覆盖原素材的播放字段（url / poster / sprite / source_material_id 等）。
      * 补丁不得改写 material_id（服务端字段，业务传了也不入库）。
      */
@@ -70,7 +71,8 @@ export interface MaterialConfig {
      * SDK 会先用临时链上屏/落盘，再后台调用本回调换链；失败则保留临时链。
      * 未配置则只落盘临时链；若带 auth_key 且过期，SDK 会自动重抽。
      * 推荐返回 urls + materialPatch，把刷新 URL 所需的 storage key 或其他业务字段写入素材。
-     * SDK 不限定 materialPatch 的字段名；poster_storage_key / sprite_storage_keys 仅为推荐命名。
+     * SDK 不限制其他 materialPatch 字段；poster_storage_key / sprite_storage_keys
+     * 中的 `tos://` 地址会作为后续自动重签依据。
      * 兼容只返回 string[]，但该形式无法附带业务字段。
      */
     onPersistExtractUrls?: (params: {
@@ -86,6 +88,8 @@ export interface AmkEditorHeaderTitleUpdateSuccess {
 }
 export interface AmkEditorHeaderConfig {
     show?: boolean;
+    /** 是否展示导出任务列表入口，默认开启。 */
+    exportTaskList?: boolean;
     /**
      * When set, the header is rendered into this element instead of inside the
      * editor root. Use this to place a full-width header above a host split layout.
@@ -114,13 +118,14 @@ export interface AmkEditorUploadSTSCredentials {
 }
 /**
  * 产物 / 主动上传的存储目标。
- * `media_output_destination` 用于 TOS 直传的 Bucket 定位；当前不会自动写入 AMK tools 请求体。
+ * `media_output_destination` 用于 TOS 直传的 Bucket 定位，并默认写入会产生媒体产物的 AMK tools 请求体。
  * @see https://docs.volcengine.com/docs/6448/2386113
  */
 export interface AmkEditorStorageConfig {
     /**
-     * 处理产物存储目标。支持 `vod://<空间名>` 或 `tos://<桶名>`。
-     * 配置后任务结果中的 url 为对应资源地址，而不是临时下载链。
+     * 处理产物存储目标。支持 `vod://<空间名>` 或 `tos://<桶名>/<可选子目录>`。
+     * 配置后任务结果中的 url 为对应资源地址，而不是临时下载链；当返回
+     * `tos://bucket/key` 且同时配置 getUploadSTS 时，SDK 会自动签成 HTTP 播放地址。
      */
     media_output_destination?: string;
     /**