@shotstack/shotstack-studio 2.12.1 → 2.13.0

package/dist/index.d.ts

@@ -110,6 +110,14 @@ declare type ClipReference = ClipLocation & {
     clip: Clip;
 };
 
+/**
+ * Result of command execution.
+ */
+export declare interface CommandResult {
+    status: "success" | "noop";
+    message?: string;
+}
+
 export declare class Controls {
     private edit;
     private seekDistance;
@@ -200,17 +208,27 @@ export declare class Edit {
     } | null;
     /**
      * Patch fields on a clip identified by stable ID.
+     *
+     * Resolves with the command outcome: `success` when the clip was updated, or `noop`
+     * (with a `message`) when no clip matches `clipId`.
      */
-    updateClipById(clipId: string, updates: Partial<Clip>): Promise<void>;
+    updateClipById(clipId: string, updates: Partial<Clip>): Promise<CommandResult>;
     /**
      * Remove a clip identified by stable ID.
+     *
+     * Resolves with the command outcome: `success` when the clip was removed, or `noop`
+     * (with a `message`) when no clip matches `clipId` or the deletion was refused —
+     * the timeline always keeps at least one clip.
      */
-    deleteClipById(clipId: string): Promise<void>;
+    deleteClipById(clipId: string): Promise<CommandResult>;
     /**
      * Move a clip identified by stable ID to a different track and/or start time.
+     *
+     * Resolves with the command outcome: `success` when the clip was moved, or `noop`
+     * (with a `message`) when no clip matches `clipId`.
      */
-    moveClipById(clipId: string, toTrackIndex: number, newStart?: Seconds): Promise<void>;
-    addClip(trackIdx: number, clip: Clip): Promise<void>;
+    moveClipById(clipId: string, toTrackIndex: number, newStart?: Seconds): Promise<CommandResult>;
+    addClip(trackIdx: number, clip: Clip): Promise<CommandResult>;
     addSvgClip(svgMarkup: string, opts?: {
         trackIndex?: number;
         start?: Seconds;
@@ -235,8 +253,15 @@ export declare class Edit {
      * Whether the clip at `(trackIdx, clipIdx)` can be deleted.
      */
     canDeleteClip(trackIdx: number, clipIdx: number): boolean;
-    deleteClip(trackIdx: number, clipIdx: number): Promise<void>;
-    addTrack(trackIdx: number, track: Track): Promise<void>;
+    /**
+     * Delete the clip at `(trackIdx, clipIdx)`, along with any luma matte attached to it.
+     *
+     * Resolves with the command outcome for the requested clip: `success` when it was
+     * removed, or `noop` (with a `message`) when there is no clip at that position or the
+     * deletion was refused — the timeline always keeps at least one clip.
+     */
+    deleteClip(trackIdx: number, clipIdx: number): Promise<CommandResult>;
+    addTrack(trackIdx: number, track: Track): Promise<CommandResult>;
     /**
      * Add a font to the timeline.
      */
@@ -253,9 +278,28 @@ export declare class Edit {
      */
     private autoLinkCaptionSources;
     getTrack(trackIdx: number): Track | null;
-    deleteTrack(trackIdx: number): void;
-    undo(): Promise<void>;
-    redo(): Promise<void>;
+    /**
+     * Delete the track at `trackIdx` and all of its clips.
+     *
+     * Resolves with the command outcome: `success` when the track was removed, or `noop`
+     * (with a `message`) when the deletion was refused — the timeline always keeps at
+     * least one track.
+     */
+    deleteTrack(trackIdx: number): Promise<CommandResult>;
+    /**
+     * Undo the most recent command.
+     *
+     * Resolves with the outcome: `success` when a command was undone, or `noop` (with a
+     * `message`) when the history is empty or the command cannot be undone.
+     */
+    undo(): Promise<CommandResult>;
+    /**
+     * Re-apply the most recently undone command.
+     *
+     * Resolves with the outcome: `success` when a command was re-applied, or `noop` (with
+     * a `message`) when there is nothing to redo.
+     */
+    redo(): Promise<CommandResult>;
     /** True when there is a command to undo (the history pointer is not before the first command). */
     get canUndo(): boolean;
     /** True when there is a command ahead to redo (the history pointer is not at the latest command). */
@@ -264,7 +308,13 @@ export declare class Edit {
      * Add a command to history without executing it.
      */
     private addCommandToHistory;
-    updateClip(trackIdx: number, clipIdx: number, updates: Partial<Clip>): Promise<void>;
+    /**
+     * Merge `updates` into the clip at `(trackIdx, clipIdx)`.
+     *
+     * Resolves with the command outcome: `success` when the clip was updated, or `noop`
+     * (with a `message`) when there is no clip at that position.
+     */
+    updateClip(trackIdx: number, clipIdx: number, updates: Partial<Clip>): Promise<CommandResult>;
     /**
      * HEAD-check every external http(s) URL in a payload
      */
@@ -315,16 +365,16 @@ export declare class Edit {
     private unloadClipAssets;
     private movePlayerToTrackContainer;
     private addPlayer;
-    setOutputSize(width: number, height: number): Promise<void>;
-    setOutputFps(fps: number): Promise<void>;
+    setOutputSize(width: number, height: number): Promise<CommandResult>;
+    setOutputFps(fps: number): Promise<CommandResult>;
     getOutputFps(): number;
-    setOutputFormat(format: string): Promise<void>;
+    setOutputFormat(format: string): Promise<CommandResult>;
     getOutputFormat(): string;
-    setOutputDestinations(destinations: Destination[]): Promise<void>;
+    setOutputDestinations(destinations: Destination[]): Promise<CommandResult>;
     getOutputDestinations(): Destination[];
-    setOutputResolution(resolution: string): Promise<void>;
+    setOutputResolution(resolution: string): Promise<CommandResult>;
     getOutputResolution(): string | undefined;
-    setOutputAspectRatio(aspectRatio: string): Promise<void>;
+    setOutputAspectRatio(aspectRatio: string): Promise<CommandResult>;
     /**
      * Capture the rendered output frame as a base64 data URL.
      *
@@ -367,9 +417,16 @@ export declare class Edit {
         aspectRatio?: string;
     }): Promise<void>;
     getOutputAspectRatio(): string | undefined;
-    setTimelineBackground(color: string): Promise<void>;
+    setTimelineBackground(color: string): Promise<CommandResult>;
     private setTimelineBackgroundInternal;
     getTimelineBackground(): string;
+    /**
+     * Re-detect merge field placeholders across the document and re-resolve the canvas.
+     * Use after registering or updating fields directly on the merge field service (rather
+     * than through a clip-level command): clips that already contain `{{ FIELD }}`
+     * placeholders pick up their resolved values immediately, without a reload.
+     */
+    refreshMergeFields(): void;
     /**
      * Find the content clip that best matches a luma (by temporal overlap).
      */

package/dist/internal.d.ts

@@ -16,6 +16,14 @@ declare type ClipReference = ClipLocation & {
     clip: Clip;
 };
 
+/**
+ * Result of command execution.
+ */
+declare interface CommandResult {
+    status: "success" | "noop";
+    message?: string;
+}
+
 declare type Destination = components["schemas"]["Destinations"];
 
 export declare class Edit {
@@ -89,17 +97,27 @@ export declare class Edit {
     } | null;
     /**
      * Patch fields on a clip identified by stable ID.
+     *
+     * Resolves with the command outcome: `success` when the clip was updated, or `noop`
+     * (with a `message`) when no clip matches `clipId`.
      */
-    updateClipById(clipId: string, updates: Partial<Clip>): Promise<void>;
+    updateClipById(clipId: string, updates: Partial<Clip>): Promise<CommandResult>;
     /**
      * Remove a clip identified by stable ID.
+     *
+     * Resolves with the command outcome: `success` when the clip was removed, or `noop`
+     * (with a `message`) when no clip matches `clipId` or the deletion was refused —
+     * the timeline always keeps at least one clip.
      */
-    deleteClipById(clipId: string): Promise<void>;
+    deleteClipById(clipId: string): Promise<CommandResult>;
     /**
      * Move a clip identified by stable ID to a different track and/or start time.
+     *
+     * Resolves with the command outcome: `success` when the clip was moved, or `noop`
+     * (with a `message`) when no clip matches `clipId`.
      */
-    moveClipById(clipId: string, toTrackIndex: number, newStart?: Seconds): Promise<void>;
-    addClip(trackIdx: number, clip: Clip): Promise<void>;
+    moveClipById(clipId: string, toTrackIndex: number, newStart?: Seconds): Promise<CommandResult>;
+    addClip(trackIdx: number, clip: Clip): Promise<CommandResult>;
     addSvgClip(svgMarkup: string, opts?: {
         trackIndex?: number;
         start?: Seconds;
@@ -124,8 +142,15 @@ export declare class Edit {
      * Whether the clip at `(trackIdx, clipIdx)` can be deleted.
      */
     canDeleteClip(trackIdx: number, clipIdx: number): boolean;
-    deleteClip(trackIdx: number, clipIdx: number): Promise<void>;
-    addTrack(trackIdx: number, track: Track): Promise<void>;
+    /**
+     * Delete the clip at `(trackIdx, clipIdx)`, along with any luma matte attached to it.
+     *
+     * Resolves with the command outcome for the requested clip: `success` when it was
+     * removed, or `noop` (with a `message`) when there is no clip at that position or the
+     * deletion was refused — the timeline always keeps at least one clip.
+     */
+    deleteClip(trackIdx: number, clipIdx: number): Promise<CommandResult>;
+    addTrack(trackIdx: number, track: Track): Promise<CommandResult>;
     /**
      * Add a font to the timeline.
      */
@@ -142,9 +167,28 @@ export declare class Edit {
      */
     private autoLinkCaptionSources;
     getTrack(trackIdx: number): Track | null;
-    deleteTrack(trackIdx: number): void;
-    undo(): Promise<void>;
-    redo(): Promise<void>;
+    /**
+     * Delete the track at `trackIdx` and all of its clips.
+     *
+     * Resolves with the command outcome: `success` when the track was removed, or `noop`
+     * (with a `message`) when the deletion was refused — the timeline always keeps at
+     * least one track.
+     */
+    deleteTrack(trackIdx: number): Promise<CommandResult>;
+    /**
+     * Undo the most recent command.
+     *
+     * Resolves with the outcome: `success` when a command was undone, or `noop` (with a
+     * `message`) when the history is empty or the command cannot be undone.
+     */
+    undo(): Promise<CommandResult>;
+    /**
+     * Re-apply the most recently undone command.
+     *
+     * Resolves with the outcome: `success` when a command was re-applied, or `noop` (with
+     * a `message`) when there is nothing to redo.
+     */
+    redo(): Promise<CommandResult>;
     /** True when there is a command to undo (the history pointer is not before the first command). */
     get canUndo(): boolean;
     /** True when there is a command ahead to redo (the history pointer is not at the latest command). */
@@ -153,7 +197,13 @@ export declare class Edit {
      * Add a command to history without executing it.
      */
     private addCommandToHistory;
-    updateClip(trackIdx: number, clipIdx: number, updates: Partial<Clip>): Promise<void>;
+    /**
+     * Merge `updates` into the clip at `(trackIdx, clipIdx)`.
+     *
+     * Resolves with the command outcome: `success` when the clip was updated, or `noop`
+     * (with a `message`) when there is no clip at that position.
+     */
+    updateClip(trackIdx: number, clipIdx: number, updates: Partial<Clip>): Promise<CommandResult>;
     /**
      * HEAD-check every external http(s) URL in a payload
      */
@@ -204,16 +254,16 @@ export declare class Edit {
     private unloadClipAssets;
     private movePlayerToTrackContainer;
     private addPlayer;
-    setOutputSize(width: number, height: number): Promise<void>;
-    setOutputFps(fps: number): Promise<void>;
+    setOutputSize(width: number, height: number): Promise<CommandResult>;
+    setOutputFps(fps: number): Promise<CommandResult>;
     getOutputFps(): number;
-    setOutputFormat(format: string): Promise<void>;
+    setOutputFormat(format: string): Promise<CommandResult>;
     getOutputFormat(): string;
-    setOutputDestinations(destinations: Destination[]): Promise<void>;
+    setOutputDestinations(destinations: Destination[]): Promise<CommandResult>;
     getOutputDestinations(): Destination[];
-    setOutputResolution(resolution: string): Promise<void>;
+    setOutputResolution(resolution: string): Promise<CommandResult>;
     getOutputResolution(): string | undefined;
-    setOutputAspectRatio(aspectRatio: string): Promise<void>;
+    setOutputAspectRatio(aspectRatio: string): Promise<CommandResult>;
     /**
      * Capture the rendered output frame as a base64 data URL.
      *
@@ -256,9 +306,16 @@ export declare class Edit {
         aspectRatio?: string;
     }): Promise<void>;
     getOutputAspectRatio(): string | undefined;
-    setTimelineBackground(color: string): Promise<void>;
+    setTimelineBackground(color: string): Promise<CommandResult>;
     private setTimelineBackgroundInternal;
     getTimelineBackground(): string;
+    /**
+     * Re-detect merge field placeholders across the document and re-resolve the canvas.
+     * Use after registering or updating fields directly on the merge field service (rather
+     * than through a clip-level command): clips that already contain `{{ FIELD }}`
+     * placeholders pick up their resolved values immediately, without a reload.
+     */
+    refreshMergeFields(): void;
     /**
      * Find the content clip that best matches a luma (by temporal overlap).
      */
@@ -542,11 +599,11 @@ export declare class ShotstackEdit extends Edit {
     /**
      * Apply a merge field to a clip property.
      */
-    applyMergeField(clipId: string, propertyPath: string, fieldName: string, value: string, originalValue?: string): Promise<void>;
+    applyMergeField(clipId: string, propertyPath: string, fieldName: string, value: string, originalValue?: string): Promise<CommandResult>;
     /**
      * Remove a merge field from a clip property, restoring the original value.
      */
-    removeMergeField(clipId: string, propertyPath: string, restoreValue: string): Promise<void>;
+    removeMergeField(clipId: string, propertyPath: string, restoreValue: string): Promise<CommandResult>;
     /**
      * Get the merge field name for a clip property, if any.
      */