@blitzreels/sdk 0.1.4 → 0.1.5

package/dist/index.d.ts

@@ -1,3 +1,6 @@
+import { type AiEditResource } from "./resources/ai-edit.js";
+import { type CaptionsResource } from "./resources/captions.js";
+import { type TimelineResource } from "./resources/timeline.js";
 export type HttpMethod = "GET" | "POST" | "PATCH" | "DELETE";
 export type JsonObject = Record<string, unknown>;
 export type QueryValue = string | number | boolean | null | undefined;
@@ -20,11 +23,16 @@ export type BlitzReelsErrorOptions = {
     status: number;
     requestId: string | null;
     body: unknown;
+    code?: BlitzReelsErrorCode;
+    retryable?: boolean;
 };
+export type BlitzReelsErrorCode = "api_error" | "auth_error" | "not_found" | "conflict" | "validation_error" | "rate_limited" | "timeout" | "server_error";
 export declare class BlitzReelsError extends Error {
     status: number;
     requestId: string | null;
     body: unknown;
+    code: BlitzReelsErrorCode;
+    retryable: boolean;
     constructor(options: BlitzReelsErrorOptions);
 }
 export type AuthValidation = {
@@ -43,9 +51,22 @@ export type AuthValidation = {
     };
 };
 export type ProjectContextMode = "summary" | "assets" | "timeline" | "transcript" | "full";
+export type ProjectContextCollectionBounds = {
+    name: string;
+    offset: number;
+    limit: number;
+    total: number;
+    returned: number;
+    hasMore: boolean;
+    truncated: boolean;
+};
+export type ProjectContextBounds = {
+    collections: ProjectContextCollectionBounds[];
+};
 export type ProjectContext = {
     mode: ProjectContextMode;
     data: unknown;
+    bounds: ProjectContextBounds;
 };
 export type Project = {
     id: string;
@@ -171,6 +192,7 @@ export type MediaAttachResult = {
         message: string | null;
         animation_applied: string | null;
         layer_index: number | null;
+        warnings?: string[];
     }>;
     summary: {
         total: number;
@@ -178,6 +200,7 @@ export type MediaAttachResult = {
         already_in_timeline: number;
         failed: number;
     };
+    warnings?: string[];
     message: string;
 };
 export type MediaShortSuggestionList = {
@@ -376,6 +399,7 @@ export type UpdateMediaOverlayResult = {
     updated: JsonObject;
     animationApplied: string | null;
     keyframeCount: number;
+    warnings?: string[];
     message: string;
 };
 export type TimelineEditResult = {
@@ -402,6 +426,51 @@ export type TimelineDeleteOptions = {
     timelineItemIds: string[];
     autoPack: boolean | undefined;
 };
+export type TimelineSplitOptions = {
+    projectId: string;
+    timelineItemId: string;
+    splitAtSeconds: number;
+    snapToFrame: boolean | undefined;
+};
+export type TimelineTrimOptions = {
+    projectId: string;
+    timelineItemId: string;
+    trimStartDeltaSeconds: number | undefined;
+    trimEndDeltaSeconds: number | undefined;
+    snapToFrame: boolean | undefined;
+};
+export type TimelineBatchMoveOptions = {
+    projectId: string;
+    items: Array<{
+        timelineItemId: string;
+        newStartSeconds: number;
+        newLayerIndex: number | undefined;
+    }>;
+};
+export type TimelineBatchTrimOptions = {
+    projectId: string;
+    items: Array<{
+        timelineItemId: string;
+        trimStartDeltaSeconds: number | undefined;
+        trimEndDeltaSeconds: number | undefined;
+    }>;
+    snapToFrame: boolean | undefined;
+};
+export type TimelineBatchTransformOptions = {
+    projectId: string;
+    items: Array<Omit<TimelineTransformOptions, "projectId">>;
+};
+export type TimelineCutOptions = {
+    projectId: string;
+    timelineItemId: string;
+    cuts: Array<{
+        startSeconds: number;
+        endSeconds: number;
+        trimFollowingSeconds: number | undefined;
+    }>;
+    snapToFrame: boolean | undefined;
+    ripple: boolean | undefined;
+};
 export type TimelineItemDeleteResult = {
     success: boolean;
     deleted_item_id: string;
@@ -468,6 +537,33 @@ export type CaptionThemeList = {
     total: number;
 };
 export type CaptionTheme = JsonObject;
+export type CaptionPresetList = {
+    presets: JsonObject[];
+    total: number;
+};
+export type CaptionLookList = {
+    looks: JsonObject[];
+    total: number;
+};
+export type CaptionStyle = {
+    success: boolean;
+    settings: JsonObject;
+    hint: string | undefined;
+};
+export type UpdateCaptionStyleOptions = {
+    projectId: string;
+    lookId: string | undefined;
+    presetId: string | undefined;
+    clearWordOverrides: boolean | undefined;
+    style: JsonObject;
+};
+export type CaptionStyleUpdateResult = {
+    success: boolean;
+    updated_properties: string[];
+    look_id: string | null | undefined;
+    preset_id: string | null | undefined;
+    message: string | undefined;
+};
 export type CaptionThemePreview = {
     preview_url: string;
     expires_at: string;
@@ -479,12 +575,198 @@ export type ExportStartResult = {
     job_id: string;
     status: string;
 };
+export type AiEditStyleId = "mirage-black" | "clean-founder";
+export type AiEditQualityTarget = "fast" | "premium" | "frontier";
+export type AiEditControllerKind = "api" | "cli" | "codex" | "claude_code" | "platform" | "unknown";
+export type AiEditRunStatus = "queued" | "understanding" | "planning" | "applying" | "rendering" | "critiquing" | "repairing" | "completed" | "failed" | "needs_review";
+export type AiEditStylesList = {
+    styles: Array<{
+        id: AiEditStyleId;
+        name: string;
+        description: string;
+        preview_image_path: string;
+        manual_skill: {
+            type: "local_skill";
+            path: string;
+            style_json_path: string;
+        };
+        spec: JsonObject;
+    }>;
+    total: number;
+};
+export type AiEditRunEnvelope = {
+    run: {
+        id: string;
+        project_id: string;
+        organization_id: string;
+        user_id: string;
+        api_key_id: string | null;
+        execution_mode: "external_controller" | "hosted_agent";
+        credit_mode: "external" | "platform_credits" | "byok";
+        controller_kind: AiEditControllerKind;
+        status: AiEditRunStatus;
+        style_id: AiEditStyleId;
+        quality_target: AiEditQualityTarget;
+        run_config: JsonObject;
+        budget_receipt: JsonObject;
+        summary: string | null;
+        failure_message: string | null;
+        completed_at: string | null;
+        created_at: string;
+        updated_at: string;
+    };
+    context: JsonObject;
+};
+export type AiEditRunLog = {
+    id: string;
+    run_id: string;
+    organization_id: string;
+    project_id: string;
+    kind: string;
+    status: string;
+    input: JsonObject;
+    output: JsonObject;
+    error_message: string | null;
+    created_at: string;
+};
+export type AiEditRunArtifact = {
+    id: string;
+    run_id: string;
+    organization_id: string;
+    project_id: string;
+    artifact_type: string;
+    time_seconds: number | null;
+    url: string | null;
+    storage_key: string | null;
+    metadata: JsonObject;
+    created_at: string;
+};
+export type AiEditRunLogsOptions = {
+    runId: string;
+    limit: number | undefined;
+    offset: number | undefined;
+};
+export type AiEditRunLogsEnvelope = {
+    run_id: string;
+    project_id: string;
+    logs: AiEditRunLog[];
+    artifacts: AiEditRunArtifact[];
+    bounds: {
+        logs: {
+            offset: number;
+            limit: number;
+            returned: number;
+            truncated: boolean;
+        };
+    };
+};
+export type AiEditAppendRunLogOptions = {
+    runId: string;
+    kind: string;
+    status: "queued" | "running" | "completed" | "failed" | "skipped";
+    message: string;
+    metadata: JsonObject;
+    dryRun: boolean | undefined;
+};
+export type AiEditAppendRunLogResult = {
+    success: true;
+    dry_run: boolean;
+    run_id: string;
+    log: AiEditRunLog | null;
+};
+export type AiEditCreateRunOptions = {
+    projectId: string;
+    styleId: AiEditStyleId;
+    qualityTarget: AiEditQualityTarget | undefined;
+    controllerKind: AiEditControllerKind | undefined;
+    dryRun: boolean | undefined;
+};
+export type AiEditApplyStyleOptions = {
+    runId: string;
+    dryRun: boolean | undefined;
+    titleText: string | null | undefined;
+};
+export type AiEditApplyStyleResult = {
+    success: true;
+    dry_run: boolean;
+    run_id: string;
+    project_id: string;
+    style_id: AiEditStyleId;
+    receipts: Array<{
+        action: string;
+        target_id: string;
+        dry_run: boolean;
+        changes: JsonObject;
+    }>;
+    txid: number | null;
+};
+export type AiEditSnapshotTime = "start" | "hook" | "middle" | "end";
+export type AiEditRenderSnapshotsOptions = {
+    runId: string;
+    dryRun: boolean | undefined;
+    times: Array<number | AiEditSnapshotTime> | undefined;
+    targetWidth: number | undefined;
+    imageFormat: "jpeg" | "png" | undefined;
+};
+export type AiEditSnapshotsResult = {
+    success: true;
+    dry_run: boolean;
+    run_id: string;
+    project_id: string;
+    snapshots: Array<{
+        artifact_id: string | null;
+        preview_url: string | null;
+        storage_key: string | null;
+        frame: number | null;
+        time_seconds: number;
+        width: number | null;
+        height: number | null;
+        image_format: "jpeg" | "png";
+    }>;
+};
+export type AiEditValidateOptions = {
+    runId: string;
+    dryRun: boolean | undefined;
+};
+export type AiEditValidationResult = {
+    success: true;
+    dry_run: boolean;
+    run_id: string;
+    project_id: string;
+    passed: boolean;
+    checks: Array<{
+        rule: string;
+        passed: boolean;
+        message: string;
+    }>;
+};
+export type AiEditCompleteOptions = {
+    runId: string;
+    status: "completed" | "needs_review" | "failed";
+    summary: string;
+    dryRun: boolean | undefined;
+};
+export type AiEditCompleteResult = {
+    success: true;
+    dry_run: boolean;
+    run_id: string;
+    status: "completed" | "needs_review" | "failed";
+    summary: string;
+};
 export type ExportStatus = {
     export_id: string;
     status: string;
     download_url: string | null;
     short_download_url: string | null;
     thumbnail_url: string | null;
+    thumbnail: {
+        url: string | null;
+        frame: number | null;
+        frame_seconds: number | null;
+        selection_mode: string | null;
+        rationale: string | null;
+    } | null;
+    platform_metadata: JsonObject | null;
     expires_at: string | null;
     file_size_bytes: number | null;
     duration_seconds: number | null;
@@ -520,6 +802,19 @@ export type SnapshotBatchOptions = {
 export type InspectProjectOptions = {
     projectId: string;
     mode: ProjectContextMode;
+    assetLimit?: number;
+    assetOffset?: number;
+    timelineLimit?: number;
+    timelineOffset?: number;
+    transcriptLimit?: number;
+    transcriptOffset?: number;
+    captionWordLimit?: number;
+    captionWordOffset?: number;
+};
+export type ProjectTimelineOptions = {
+    projectId: string;
+    limit?: number;
+    offset?: number;
 };
 export type ListProjectsOptions = {
     limit: number | undefined;
@@ -605,6 +900,7 @@ export type AttachMediaToProjectOptions = {
     positionY: number | undefined;
     widthPx: number | undefined;
     heightPx: number | undefined;
+    keepAspectRatio: boolean | undefined;
     scale: number | undefined;
     opacity: number | undefined;
     animationPreset: MediaAnimationPreset | undefined;
@@ -851,7 +1147,9 @@ export type UpdateMediaOverlayOptions = {
     positionY: number | undefined;
     widthPx: number | undefined;
     heightPx: number | undefined;
+    keepAspectRatio: boolean | undefined;
     scale: number | undefined;
+    opacity: number | undefined;
     animationPreset: MediaAnimationPreset | undefined;
     removeAnimations: boolean | undefined;
     blurredBackground: boolean | undefined;
@@ -894,7 +1192,11 @@ export type SetCaptionWordEmphasisOptions = CaptionWordSelectorOptions & {
 };
 export type DeleteCaptionWordsOptions = {
     projectId: string;
-    wordIds: string[];
+    wordIds: string[] | undefined;
+    timelineItemId: string | undefined;
+    all: boolean | undefined;
+    fromSeconds: number | undefined;
+    toSeconds: number | undefined;
 };
 export type MergeCaptionWordsOptions = {
     projectId: string;
@@ -923,6 +1225,7 @@ export type StartExportOptions = {
     projectId: string;
     resolution: string | undefined;
     format: string | undefined;
+    coverFrameSeconds?: number | null;
 };
 export type WaitExportOptions = {
     exportId: string;
@@ -933,6 +1236,7 @@ export type SilencePlanOptions = {
     projectId: string;
     timelineItemId: string | undefined;
     allMediaItems: boolean | undefined;
+    strategy: "audio" | "caption-gaps" | undefined;
     paddingMs: number | undefined;
     silenceThresholdDb: number | undefined;
     minSilenceDurationSeconds: number | undefined;
@@ -942,6 +1246,11 @@ export type SilencePlanOptions = {
 export type SilenceApplyOptions = SilencePlanOptions & {
     deleteSilentClips: boolean | undefined;
     manualSegmentOverrides: Record<string, "keep" | "cut"> | undefined;
+    segments: Array<{
+        timelineItemId: string | undefined;
+        startSeconds: number;
+        endSeconds: number;
+    }> | undefined;
     previewConfirmed: true;
 };
 export type MistakePlanOptions = {
@@ -1032,21 +1341,11 @@ export declare class BlitzReelsClient {
             success: true;
         }>;
         inspect: (options: InspectProjectOptions) => Promise<ProjectContext>;
-        timeline: (options: {
-            projectId: string;
-        }) => Promise<ProjectContext>;
+        timeline: (options: ProjectTimelineOptions) => Promise<ProjectContext>;
         renderSnapshot: (options: SnapshotOptions) => Promise<PreviewFrame>;
         renderSnapshots: (options: SnapshotBatchOptions) => Promise<PreviewFrames>;
     };
-    timeline: {
-        transform: (options: TimelineTransformOptions) => Promise<TimelineEditResult>;
-        move: (options: TimelineMoveOptions) => Promise<TimelineEditResult>;
-        delete: (options: TimelineDeleteOptions) => Promise<TimelineEditResult>;
-        deleteItem: (options: {
-            projectId: string;
-            timelineItemId: string;
-        }) => Promise<TimelineItemDeleteResult>;
-    };
+    timeline: TimelineResource;
     effects: {
         zoom: {
             add: (options: AddEffectOptions<ZoomEffectSettings>) => Promise<EffectMutationResult>;
@@ -1158,34 +1457,8 @@ export declare class BlitzReelsClient {
         plan: (options: MistakePlanOptions) => Promise<unknown>;
         apply: (options: MistakeApplyOptions) => Promise<unknown>;
     };
-    captions: {
-        listWords: (options: ListCaptionWordsOptions) => Promise<CaptionWordsList>;
-        updateWordText: (options: UpdateCaptionWordTextOptions) => Promise<CaptionWordTextResult>;
-        batchUpdateWordText: (options: BatchUpdateCaptionWordTextOptions) => Promise<CaptionWordBatchTextResult>;
-        setWordStyle: (options: SetCaptionWordStyleOptions) => Promise<CaptionWordCountResult>;
-        setWordEmphasis: (options: SetCaptionWordEmphasisOptions) => Promise<CaptionWordCountResult>;
-        deleteWords: (options: DeleteCaptionWordsOptions) => Promise<CaptionWordMutationResult>;
-        delete: (options: CaptionTrackSelectorOptions) => Promise<CaptionTrackMutationResult>;
-        hide: (options: CaptionTrackSelectorOptions) => Promise<CaptionTrackMutationResult>;
-        show: (options: CaptionTrackSelectorOptions) => Promise<CaptionTrackMutationResult>;
-        mergeWords: (options: MergeCaptionWordsOptions) => Promise<CaptionWordMutationResult>;
-        splitWord: (options: SplitCaptionWordOptions) => Promise<CaptionWordMutationResult>;
-        listThemes: () => Promise<CaptionThemeList>;
-        updateTheme: (options: UpdateCaptionThemeOptions) => Promise<CaptionTheme>;
-        setDefaultTheme: (options: {
-            themeId: string;
-        }) => Promise<{
-            success: boolean;
-        }>;
-        setProjectTheme: (options: {
-            projectId: string;
-            themeId: string;
-        }) => Promise<{
-            success: boolean;
-            theme_id: string;
-        }>;
-        previewTheme: (options: PreviewCaptionThemeOptions) => Promise<CaptionThemePreview>;
-    };
+    aiEdit: AiEditResource;
+    captions: CaptionsResource;
     exports: {
         start: (options: StartExportOptions) => Promise<ExportStartResult>;
         get: (options: {