@volcengine/amk-editor 0.0.2-beta.0 → 0.0.2

package/dist/local-upload-modal.d.ts

@@ -6,7 +6,7 @@ export interface CreateLocalUploadModalOptions {
     onConfirm: (files: File[]) => void;
 }
 export interface LocalUploadModalController {
-    open: (files: File[]) => void;
+    open: (files?: File[]) => void;
     close: () => void;
     destroy: () => void;
 }

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

@@ -16,14 +16,21 @@ export type SystemMaterialItem = Omit<Partial<MaterialItem>, 'source_material_id
     type: NonNullable<MaterialItem['type']>;
     name?: string;
 };
+/** 可由外部工具栏复用的素材导入入口。 */
+export type AmkMaterialImportType = 'local' | 'url' | 'system';
+/** Optional callbacks scoped to one externally triggered material import. */
+export interface AmkMaterialImportRequestOptions {
+    /** Called with persisted materials only for this request. */
+    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 {
@@ -46,6 +53,11 @@ export interface MaterialConfig {
      * 返回 `undefined` / `null` / `[]` 视为取消或未选择，不提示失败。
      */
     onUploadFromSystem?: () => Promise<SystemMaterialItem[] | undefined | null> | SystemMaterialItem[] | undefined | null;
+    /**
+     * 素材成功入库后回调（已合并 Editing API 返回的 `material_id`）。
+     * 本地 / URL / 资产库三条导入链路都会走到这里；失败或用户取消不会触发。
+     */
+    onMaterialsImported?: (materials: MaterialItem[]) => void | Promise<void>;
     /**
      * 刷新播放信息。未配置时用素材库已有字段；
      * 配置后：入参为待刷新素材列表（按服务端 material_id 区分，支持批量），
@@ -58,7 +70,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: {
@@ -67,10 +80,24 @@ export interface MaterialConfig {
         material: MaterialItem;
     }) => Promise<PersistExtractUrlsResult | string[]> | PersistExtractUrlsResult | string[];
 }
+export interface AmkEditorHeaderTitleUpdateSuccess {
+    readonly projectId: string;
+    /** Project title persisted successfully by the Editing API. */
+    readonly title: string;
+}
 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.
+     */
+    mount?: HTMLElement;
     onBack?: () => void;
     onClose?: () => void;
+    /** Fired only after the project title is persisted successfully. */
+    onTitleUpdateSuccess?: (change: AmkEditorHeaderTitleUpdateSuccess) => void;
 }
 export interface AmkEditorExportConfig {
     /**
@@ -90,13 +117,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;
     /**
@@ -181,16 +209,14 @@ type AmkResourceOptionTypes = {
 };
 type AmkInheritedVeVeditorOptions = Omit<VeVeditorOptions<MaterialConfig, VeVeditorI18nOptions, AmkResourceOptionTypes>, 'initialData' | 'recording' | 'onSketchItemsChange' | 'onNodePreviewError' | 'onPreviewNodeRefresh' | 'onBeforeUndo' | 'onBeforeRedo' | 'onBeforeTimestampMount' | 'onBeforeKeyframeMount' | 'onTrackChanged' | 'onRecordingUpload' | 'decode'>;
 export type AmkEditorDecodeOptions = VeVeditorDecodeOptions;
-/** 客户业务代理的浏览器侧鉴权配置。SDK 不约定鉴权协议，仅透传接入方返回的请求头。 */
-export interface AmkEditorAuthConfig {
-    getHeaders: () => Record<string, string> | undefined | Promise<Record<string, string> | undefined>;
-}
+/** 每次 AMK 请求前动态获取、原样透传给 endpoint 的业务请求头。 */
+export type AmkEditorGetHeaders = () => Readonly<Record<string, string>> | undefined | Promise<Readonly<Record<string, string>> | undefined>;
 export interface AmkEditorOptions extends AmkInheritedVeVeditorOptions {
     projectId: string;
     /** AMK Editing API 的业务代理地址。 */
     endpoint: string;
-    /** 可选：返回访问客户业务代理所需的自定义请求头。 */
-    auth?: AmkEditorAuthConfig;
+    /** 每次请求前调用；返回值不解析、不改写，仅透传给 endpoint。 */
+    getHeaders?: AmkEditorGetHeaders;
     header?: AmkEditorHeaderConfig;
     export?: AmkEditorExportConfig;
     getLicenseUrl?: string | (() => string | Promise<string>);