@contenthero/sdk 0.3.2 → 0.3.3

package/dist/types.d.ts

@@ -125,6 +125,14 @@ export interface GenerateRequest {
      * also know the id up front and can poll `getGeneration` immediately.
      */
     outputId?: string;
+    /** Optional: place the generated asset onto this editor project's timeline in the same call. Omit for a
+     *  standalone library output. Sync models (audio) place immediately; async models (image/video) place when
+     *  the output finalizes. */
+    projectId?: string;
+    /** Optional placement intent; omitted = playhead when `playheadFrame` is given, else append at the end. */
+    placement?: PlacementIntent;
+    /** Optional interactive-fallback playhead frame (echo one from get_context for playhead-relative placement). */
+    playheadFrame?: number;
 }
 /** The nine Reference Board types. */
 export type BoardType = 'character' | 'pose' | 'mascot' | 'creature' | 'weapon' | 'vehicle' | 'object' | 'location' | 'shot';
@@ -174,6 +182,26 @@ export interface GenerateResult {
     outputUrls?: string[];
     /** True when a client-supplied `outputId` matched an existing job (no new work was started). */
     idempotentReplay?: boolean;
+    /** Where the asset is being placed (present only when `projectId` was supplied). Lets a caller chain further
+     *  ops onto the placed clip/layer without a get_context hop, and see any placement warnings. */
+    placement?: PlacementResult;
+}
+/** The outcome of a one-call placement (present on a generate result when `projectId` was supplied). The ids are
+ *  known at submit time (deterministic), so they are usable for chaining before the async asset finishes. */
+export interface PlacementResult {
+    /** True while the async placement completes at finalize (image/video); absent for a synchronous audio place. */
+    pending?: boolean;
+    projectId: string;
+    /** The placed clip / layer id (deterministic). Chain further ops (animate, reposition, reorder) onto it. */
+    itemId?: string;
+    /** 'canvas' when placed as a layer on a slide, 'editor' when placed as a clip on a track. Mirrors
+     *  `project.kind` exactly, rather than renaming it. */
+    surface?: 'canvas' | 'editor';
+    /** Canvas only: the placed layer id (same as itemId) and the resolved target slide. */
+    layerId?: string;
+    slideId?: string;
+    /** Non-fatal placement notes (e.g. an ambiguous slide fallback). */
+    warnings?: string[];
 }
 /**
  * Result of a get_cost preflight (`estimateCost` / `estimateBoardCost`): the credit
@@ -187,6 +215,131 @@ export interface CostEstimate {
     modelId?: string;
     contentType?: 'image' | 'video' | 'audio';
 }
+/**
+ * Request for `editAudio`: transform an existing audio file into a new one with
+ * an audio-processing model (audio input -> audio output), e.g. voice isolation.
+ * The sibling of `generate` for the existing-audio -> audio shape.
+ */
+/**
+ * Where a generated/processed clip lands on an editor project's timeline. All positional fields are in
+ * SECONDS (resolved to frames server-side via the project fps). Omitted intent = the playhead when a
+ * `playheadFrame` is supplied, else append at the end of the timeline.
+ */
+export type PlacementIntent = TimelinePlacementIntent | CanvasPlacementIntent;
+/** Placement onto a VIDEO timeline: a clip on a track at a time. */
+export type TimelinePlacementIntent = 
+/** Land after the last clip on the best track of the clip's kind, or on a freshly spawned track. */
+{
+    mode: 'append';
+}
+/** Land at an explicit time. `track` selects the track: a track id, 'overlay' (a non-primary track, reused
+ *  or spawned), or 'primary' (the main track, media only); omitted uses the default track. `durationSeconds`
+ *  sets an IMAGE point clip's length (ignored for video/audio). */
+ | {
+    mode: 'at';
+    startSeconds?: number;
+    track?: string;
+    durationSeconds?: number;
+}
+/** Land at the current playhead (the interactive fallback). `durationSeconds` sets an IMAGE point clip's length. */
+ | {
+    mode: 'atPlayhead';
+    durationSeconds?: number;
+}
+/** Swap in place for an existing clip; the new clip inherits its track + start. `duration` keeps the new
+ *  clip's own length and ripples ('natural', default) or trims it to the replaced slot ('match'). */
+ | {
+    mode: 'replace';
+    itemId: string;
+    duration?: 'natural' | 'match';
+}
+/** Fill or cover a time span. `track` selects the track (id / 'overlay' / 'primary'); omitted uses the default. */
+ | {
+    mode: 'range';
+    startSeconds?: number;
+    endSeconds?: number;
+    track?: string;
+    fit?: 'cover' | 'trim' | 'overwrite';
+};
+/** Placement onto a CANVAS design: a layer on a slide at a position + size (6A A8). Flat (no `mode`); all fields
+ *  optional. Positions/sizes are design pixels. Omitting `slideId`/`slideIndex` targets the focused slide. */
+export interface CanvasPlacementIntent {
+    slideId?: string;
+    slideIndex?: number;
+    fit?: 'contain' | 'cover' | 'none';
+    anchor?: 'center' | 'top-left' | 'top' | 'top-right' | 'left' | 'right' | 'bottom-left' | 'bottom' | 'bottom-right';
+    x?: number;
+    y?: number;
+    width?: number;
+    height?: number;
+    /** Make the generated asset the slide's background rather than a free layer (placed full-bleed, promoted into
+     *  the background slot once it lands). Ignores anchor / x / y / width / height. */
+    asBackground?: boolean;
+}
+export interface EditAudioRequest {
+    /** The audio-processing model to run. */
+    modelId: string;
+    /**
+     * Public URL (or a previous output id) of the source audio to process.
+     *
+     * Required in FILE mode and must be OMITTED in in-place mode, where the sources come from the clips
+     * themselves. The two are mutually exclusive: one produces a new library asset, the other edits a timeline.
+     */
+    sourceUrl?: string;
+    /** Source audio length in seconds. Required for a cost estimate; on a real run
+     *  it refines the estimate (the authoritative charge is the processed duration). */
+    durationSeconds?: number;
+    /** Optional: place the processed audio onto this editor project's timeline in the same call. Omit for a
+     *  standalone library output (today's behavior). */
+    projectId?: string;
+    /** Optional placement intent; omitted = playhead when `playheadFrame` is given, else append at the end. */
+    placement?: PlacementIntent;
+    /** Optional interactive-fallback playhead frame (echo one from get_context for playhead-relative placement). */
+    playheadFrame?: number;
+    /**
+     * IN-PLACE mode: enhance the audio OF EXISTING CLIPS on `projectId`, rather than processing a standalone file.
+     *
+     * Requires `projectId` and `modelId: 'auphonic-enhance'`. Omitting `clipIds` while passing
+     * `enhanceClips: true` means every audible clip on the timeline, the same whole-timeline default the sibling
+     * timeline ops use. Silenced clips are excluded automatically; enhancing audio nobody can hear would spend
+     * credits and then overwrite something the user deliberately muted.
+     *
+     * ⚠️ RETURNS A LIST on `outputs`. Auphonic estimates a noise profile and picks a loudness target per
+     * PRODUCTION, so one source's clips are concatenated and enhanced as a SINGLE job. Grouping stops at the
+     * source because a profile spanning two recordings is an average of two rooms and fits neither, so a
+     * selection covering three recordings is three jobs and three outputIds.
+     */
+    clipIds?: string[];
+    /** Opt in to in-place mode without naming clips (whole timeline). Implied when `clipIds` is present. */
+    enhanceClips?: boolean;
+}
+/** One in-place enhancement job: the clips of a single source, concatenated and enhanced together. */
+export interface EnhanceClipsJob {
+    outputId: string;
+    creditsEstimate?: number;
+    /** Every clip this job's pieces will be applied to. */
+    clipIds: string[];
+    /** How many distinct windows were concatenated into this job. */
+    windows: number;
+}
+/**
+ * The result of `editAudio`, which serves two shapes.
+ *
+ * FILE mode returns the `GenerateResult` fields. IN-PLACE mode returns `outputs`, one per source, and echoes
+ * the first on `outputId` so a single-source project can be awaited without unpacking the list. `status` is
+ * `'noop'` when the selection contained no audible audio, which is deliberately distinguishable from a failure.
+ */
+export interface EditAudioResult extends Omit<GenerateResult, 'status'> {
+    status: 'processing' | 'completed' | 'noop';
+    /** In-place mode only: one job per source. */
+    outputs?: EnhanceClipsJob[];
+    /** In-place mode only: the project the pieces are applied to. */
+    projectId?: string;
+    /** In-place mode only: selected clips skipped because they are silenced. */
+    silencedClipsExcluded?: number;
+    /** Present with `status: 'noop'`, explaining why nothing ran. */
+    note?: string;
+}
 /** A generation record as returned by `getGeneration` and `generateAndWait`. */
 export interface Generation {
     outputId: string;
@@ -199,6 +352,16 @@ export interface Generation {
     error: string | null;
     createdAt: string;
     completedAt: string | null;
+    /** The terminal signal to await when a generation carries a project PLACEMENT (a fresh asset placed on a canvas
+     *  / timeline, or an in-place background removal): true once the output exists AND its placement side-effect
+     *  (the placeholder->asset swap, the cutout, a background promotion) has been applied to the project. `status`
+     *  flips to 'completed' when the asset exists and billing settles, which can precede the swap; `waitForGeneration`
+     *  keys on `settled` so "done" always implies the visible composition change is in. Absent (older servers) is
+     *  treated as settled. Outputs with no placement are settled as soon as they complete. */
+    settled?: boolean;
+    /** Where the asset was placed (present only when `projectId` was supplied to generate). Carried from the submit
+     *  response through `generateAndWait` so a caller gets the placement outcome alongside the finished asset. */
+    placement?: PlacementResult;
 }
 /** Subscription tiers the API normalizes balances against. */
 export type SubscriptionTier = 'mortal' | 'hero' | 'champion' | 'legend';
@@ -234,6 +397,11 @@ export interface Transcription {
     wordCount: number;
     /** Source audio length in seconds, when known. */
     durationSeconds: number | null;
+    /**
+     * ContentHero credits charged for the run. Zero only when the user's own ElevenLabs
+     * key covered it, in which case the provider billed them directly.
+     */
+    creditsUsed: number;
 }
 /** An avatar as returned by `listAvatars` (the list projection). */
 export interface AvatarSummary {
@@ -252,6 +420,8 @@ export interface AvatarLook {
     imageUrl: string | null;
     lookType: string | null;
     isDefault: boolean;
+    isFavorited: boolean;
+    isArchived: boolean;
 }
 /** Full avatar detail as returned by `getAvatar`. */
 export interface Avatar extends AvatarSummary {
@@ -281,6 +451,11 @@ export interface Voice extends VoiceSummary {
     description: string | null;
     useCase: string | null;
 }
+/** Options for `listVoices`. */
+export interface ListVoicesOptions {
+    /** When true, return only favorited voices. */
+    favorited?: boolean;
+}
 /** A brand kit as returned by `listBrandKits` (the list projection). */
 export interface BrandKitSummary {
     id: string;
@@ -293,6 +468,13 @@ export interface BrandKitSummary {
     isArchived: boolean;
     createdAt: string | null;
 }
+/** Options for `listBrandKits`. */
+export interface ListBrandKitsOptions {
+    /** When true, return only favorited brand kits. */
+    favorited?: boolean;
+    /** When true, return only archived brand kits (default excludes archived). */
+    archived?: boolean;
+}
 /** A brand/inspiration account linked to a brand kit. */
 export interface BrandKitAccount {
     /** The tracked-account id; feeds getInspirationAccount / getBrandAccountPerformance. */
@@ -440,6 +622,13 @@ export interface UpdateBrandKitSectionInput {
 }
 /** A studio output's media kind. */
 export type MediaType = 'image' | 'video' | 'audio' | 'transcript';
+/**
+ * Which library a media read targets. 'creations' = studio generations (with variations);
+ * 'uploads' = the editor Uploads tab (the user-level upload library); 'stock' = stock media
+ * the user has used (cached and reusable); 'all' = every library merged newest-first, each item
+ * self-describing via its `source` (list only; a `get` uses the item's specific source).
+ */
+export type MediaSource = 'creations' | 'uploads' | 'stock' | 'all';
 /** One variation (slot) of a studio output. */
 export interface MediaVariation {
     /** 1-based variation number (matches the UI and a share link's ?v=N). */
@@ -447,8 +636,29 @@ export interface MediaVariation {
     url: string | null;
     status: string;
     isFavorited: boolean;
+    isArchived: boolean;
+    /**
+     * MEASURED PIXEL GEOMETRY of this slot's image. `content` is the ARTWORK's bounds within the file (its
+     * alpha bounds), so a padded logo can be placed and aligned by what is VISIBLE rather than by its file
+     * rectangle. Absent until the asset has been measured. The same field appears on a media-batch item, so
+     * the CLI and the MCP report identical facts.
+     */
+    geometry?: {
+        width: number;
+        height: number;
+        content?: {
+            x: number;
+            y: number;
+            width: number;
+            height: number;
+        };
+    };
 }
-/** A studio output as returned by `listMedia` (the list projection). */
+/**
+ * One atomic library asset as returned by `listMedia`. The grain is a VARIATION (an individual media file),
+ * not a whole generation: a studio generation with N variations lists as N items sharing one `id` but with
+ * distinct `variant`. The universal identity is (id, variant).
+ */
 export interface MediaSummary {
     id: string;
     type: MediaType;
@@ -456,13 +666,27 @@ export interface MediaSummary {
     prompt: string | null;
     status: string;
     createdAt: string | null;
-    variationCount: number;
-    /** Resolved (non-null) variation URLs. */
-    urls: string[];
+    /**
+     * 0-based canonical slot of this variation (matches a share link's ?v=N as variant+1, and getMedia's
+     * `<id>-<N>` token as N = variant+1). Single-asset sources (uploads, stock) are always 0.
+     */
+    variant: number;
+    /** This variation's resolved URL (null only in a detail view whose slots have no media yet). */
+    url: string | null;
+    /** Total variations in the parent generation this variation belongs to (1 for uploads/stock). */
+    generationSize: number;
+    /** Whether THIS variation is favorited (studio per-slot; uploads/stock are go-forward, false). */
+    isFavorited: boolean;
     /** Asset class: 'creation' (default), 'board' (a reference board), or 'look'. */
     kind: string | null;
     /** Board type when kind is 'board' (character, weapon, location, etc.); else null. */
     boardType: string | null;
+    /** Which library this item came from ('creations' | 'uploads' | 'stock'); self-describing. */
+    source: MediaSource;
+    /** Original file name (uploads); null for studio outputs. */
+    fileName: string | null;
+    /** Duration in seconds for a single-file item (uploads video/audio); null otherwise. */
+    durationSeconds: number | null;
 }
 /** Full studio output detail as returned by `getMedia`. */
 export interface MediaItem extends MediaSummary {
@@ -474,16 +698,209 @@ export interface MediaItem extends MediaSummary {
     variations: MediaVariation[];
     /** Set when the requested token addressed a single variation; else null. */
     selectedVariation: number | null;
+    /** Output-level representative still (video poster / optimized image preview), or null. */
+    thumbnailUrl: string | null;
+}
+/**
+ * VIDEO keyframe watch (opt-in): set any of these on a video item to get low-res keyframes across the
+ * [fromSec, toSec] source-time window (whole clip by default), so you can SEE the footage — the fix for
+ * "video returns no frame yet". Frame-based, so cost is decoupled from clip length.
+ */
+export interface MediaClipWindow {
+    fromSec?: number;
+    toSec?: number;
+    /** How many keyframes (proportional default; service-capped). */
+    frames?: number;
+}
+/** One requested item for `getMediaBatch`: a raw URL, or an output id (+ variation); videos accept a window. */
+export type MediaBatchItem = ({
+    url: string;
+} | {
+    mediaId: string;
+    variation?: number;
+}) & MediaClipWindow;
+/**
+ * One resolved item from `getMediaBatch`, uniform across the url and mediaId
+ * paths. `url` is the single thing to fetch (the MCP turns it into an image
+ * block); `ok` is false with an `error` when the item could not be resolved.
+ */
+export interface ResolvedMediaBatchItem {
+    ok: boolean;
+    /** Echo of the requested item, to correlate results with inputs. */
+    input: MediaBatchItem;
+    /** The media itself (image master, or video master). */
+    url: string | null;
+    /**
+     * The still image to view for this item: the image itself for images, the
+     * poster still for a video's primary variation, null when no still is available
+     * (audio, transcript, non-primary video variation, raw video url). The MCP turns
+     * this into an image block; SDK/CLI just surface the URL.
+     */
+    imageUrl: string | null;
+    type: MediaType | null;
+    model: string | null;
+    prompt: string | null;
+    /** The output id when resolved from a mediaId; null for a raw url. */
+    mediaId: string | null;
+    /** The 1-based variation this url represents (mediaId path), else null. */
+    variation: number | null;
+    /** Sibling variation numbers not returned here (mediaId-without-variation path). */
+    otherVariations: number[];
+    /**
+     * VIDEO keyframes (present only when the item requested a window on a video): low-res frames across the
+     * source-time window, each an inline `data:image/jpeg;base64,...`. The MCP turns each into an image block.
+     */
+    keyframes?: {
+        atSec: number;
+        dataUrl: string;
+    }[];
+    /**
+     * MEASURED PIXEL GEOMETRY from the storage spine. Absent for an asset that is not ours or not yet measured.
+     *
+     * `content` is the ARTWORK's bounds within the file (its alpha bounds). For a padded logo these differ
+     * sharply from the file rectangle, and using the file rectangle is what makes a placed logo look wrong:
+     * the true aspect is the artwork's, and aligning the file edge leaves a visible gap the width of the
+     * transparent margin. This is the same measurement the editor's selection, snapping and align-to-page use.
+     */
+    geometry?: {
+        width: number;
+        height: number;
+        /** Alpha bounds in SOURCE pixels. Equals the full frame for an image with no transparent margin. */
+        content?: {
+            x: number;
+            y: number;
+            width: number;
+            height: number;
+        };
+    };
+    /**
+     * MEASURED LENGTH in seconds, for anything time-based: video, audio, and whatever comes later.
+     *
+     * Absent for an asset that is not ours or not yet measured. This was missing entirely for audio, which made
+     * `editAudio` uncallable without downloading the file first, because it REQUIRES a `durationSeconds` to
+     * price the job and no read returned one.
+     */
+    durationSeconds?: number;
+    error?: string;
+}
+/** Result of `getMediaBatch`: one resolved entry per requested item, in order. */
+export interface MediaBatchResult {
+    items: ResolvedMediaBatchItem[];
 }
 /** Options for `listMedia`. */
 export interface ListMediaOptions {
+    /** Which library to read; defaults to 'creations' (studio outputs). 'uploads' = the editor Uploads tab. */
+    source?: MediaSource;
     contentType?: MediaType | MediaType[];
     status?: string;
     /** Filter by asset class: 'creation', 'board', 'look', or 'upload'. */
     kind?: 'creation' | 'board' | 'look' | 'upload';
+    /** When true, return only outputs that have a favorited (non-archived) variation. */
+    favorited?: boolean;
+    /** When true, return only outputs that have an archived variation. */
+    archived?: boolean;
     limit?: number;
     offset?: number;
 }
+/** Media kinds that semantic library search can return / filter by. */
+export type MediaKind = 'image' | 'video' | 'audio';
+/** A scene within a video asset that matched a media search, with its own relevance. */
+export interface SearchMediaScene {
+    /** Scene start within the asset, in milliseconds. */
+    startMs: number;
+    /** Scene end within the asset, in milliseconds. */
+    endMs: number;
+    /** Cosine relevance of this scene to the query (0..1). */
+    relevance: number;
+}
+/** One asset (a single variation) returned by semantic library search. */
+export interface SearchMediaResult {
+    /** The asset's record id (source_record_id). With `variant`, uniquely identifies the atomic asset. */
+    id: string;
+    /** The variation index within the record (studio generation output index; 0 for single-asset sources). */
+    variant: number;
+    /** The asset's origin table (studio_outputs, editor_uploads, stock_assets, brand_kits). */
+    sourceTable: string;
+    kind: MediaKind | null;
+    /** A resolved, usable URL for the asset (a cached edit proxy for stock). */
+    url: string | null;
+    /** The vision description of the asset. */
+    summary: string | null;
+    tags: string[];
+    /** Best cosine relevance of this asset to the query (0..1). */
+    relevance: number;
+    /** For videos, the specific scenes that matched, best first (empty for image/audio). */
+    scenes: SearchMediaScene[];
+}
+/** Options for searchMedia. */
+export interface SearchMediaOptions {
+    /** Restrict results to these media kinds. Omit to search all kinds. */
+    kinds?: MediaKind[];
+    /** Maximum number of assets to return (default 12, max 50). */
+    limit?: number;
+}
+export type FolderType = 'manual' | 'smart';
+/** The smart-folder query spec = the same filters the library search bar produces. */
+export interface SmartFolderQuery {
+    text?: string;
+    kinds?: MediaKind[];
+    sources?: Array<'creations' | 'uploads' | 'stock'>;
+    facets?: Record<string, string>;
+    tags?: string[];
+    favoritedOnly?: boolean;
+    sort?: 'relevance' | 'recent' | 'name';
+}
+export interface Folder {
+    id: string;
+    name: string;
+    type: FolderType;
+    query: SmartFolderQuery | null;
+    parentId: string | null;
+    icon: string | null;
+    color: string | null;
+    position: number;
+    createdAt: string;
+    updatedAt: string;
+}
+/** A built-in derived folder (recents, favorites, edits, canvas, posts). */
+export interface DerivedFolder {
+    key: string;
+    name: string;
+}
+/** One item inside a folder: media (variation-atomic) or an entity (project/post, manual folders only). */
+export type FolderItem = {
+    type: 'media';
+    kind: MediaKind | null;
+    sourceTable: string;
+    sourceRecordId: string;
+    variant: number;
+    url: string | null;
+    summary: string | null;
+    isFavorited: boolean;
+    relevance?: number;
+} | {
+    type: 'project' | 'post';
+    id: string;
+    name: string;
+    subtype: string | null;
+};
+export interface CreateFolderInput {
+    name: string;
+    type?: FolderType;
+    query?: SmartFolderQuery;
+    parentId?: string | null;
+}
+export interface UpdateFolderInput {
+    name?: string;
+    parentId?: string | null;
+    query?: SmartFolderQuery | null;
+}
+/** A pointer into a manual folder, by the universal variation-atomic identity. */
+export interface FolderItemRef {
+    sourceTable: string;
+    sourceRecordId: string;
+    variant?: number;
+}
 /** Fields to start a presigned media upload (phase 1 of uploadMedia). */
 export interface CreateMediaUploadInput {
     fileName: string;
@@ -494,6 +911,16 @@ export interface CreateMediaUploadInput {
 export interface CreateMediaUploadResult {
     outputId: string;
     uploadUrl: string;
+    /**
+     * Headers to send with the PUT, exactly as given.
+     *
+     * Optional because an older API deployment does not return it; when absent, send
+     * `Content-Type` alone. Once storage is R2 the presigned URL signs the owner in as
+     * `x-amz-meta-user_id` and a PUT without it is refused, so a client that hardcodes
+     * `Content-Type` breaks. Taking the headers from the server keeps this client
+     * store-agnostic and lets the API and the SDK deploy in either order.
+     */
+    uploadHeaders?: Record<string, string>;
     storagePath: string;
     expiresAt: string;
 }
@@ -810,6 +1237,8 @@ export interface ListOutliersOptions {
     sortBy?: 'score' | 'date' | 'views';
     /** Scope to the inspiration accounts linked to this brand kit. */
     brandKitId?: string;
+    /** When true, return only content the caller has favorited. */
+    favorited?: boolean;
     limit?: number;
     offset?: number;
 }
@@ -894,4 +1323,498 @@ export interface PlatformSchema {
     /** Per-format field template: field names + default values (File handles stripped). */
     fieldTemplatesByFormat: Record<string, Record<string, unknown>>;
 }
+/** The asset types that can be favorited. */
+export type FavoriteAssetType = 'post' | 'voice' | 'brand_kit' | 'project' | 'inspiration_content' | 'gallery' | 'transition';
+/** The asset types that can be archived. */
+export type ArchiveAssetType = 'post' | 'brand_kit' | 'brand_kit_section' | 'project';
+/**
+ * The target of a favorite / unfavorite call.
+ *
+ * Provide `assetType` + `id` for a top-level asset, OR `id` + `variationIndex`
+ * (1-based) to target a single studio output variation slot, in which case the
+ * id is a studio output id and `assetType` is ignored.
+ */
+export interface FavoriteInput {
+    assetType?: FavoriteAssetType;
+    id: string;
+    /** 1-based variation slot; when set, `id` is a studio output id. */
+    variationIndex?: number;
+}
+/**
+ * The target of an archive / unarchive call.
+ *
+ * Provide `assetType` + `id` for a top-level asset, OR `id` + `variationIndex`
+ * (1-based) to target a single studio output variation slot, in which case the
+ * id is a studio output id and `assetType` is ignored.
+ */
+export interface ArchiveInput {
+    assetType?: ArchiveAssetType;
+    id: string;
+    /** 1-based variation slot; when set, `id` is a studio output id. */
+    variationIndex?: number;
+}
+/** Which write model a project's composition uses: 2D canvas layers or a 1D editor timeline. */
+export type EditorSurface = 'canvas' | 'editor';
+/** One op in the shared editor/canvas op vocabulary. Opaque here: shaped by the reducer for the
+ *  project's surface (canvas layer/slide ops, or timeline clip ops). Every op has an `op` name. */
+export interface EditorOp {
+    op: string;
+    /**
+     * Optional client-generated stable id (uuid) for this op. When omitted, `applyEditorOps` generates one
+     * for you before sending. It is the op's identity across its whole lifecycle: the server persists it, the
+     * unique-per-project constraint makes a retried op idempotent, and a live editor client uses it to ignore
+     * the broadcast echo of its own edit.
+     */
+    op_id?: string;
+    [key: string]: unknown;
+}
+/** Input to `applyEditorOps`. */
+export interface ApplyEditorOpsInput {
+    /** The project to edit. Its `surface` selects the op vocabulary (canvas layers vs timeline clips). */
+    projectId: string;
+    /** The ops to apply, in order. */
+    ops: EditorOp[];
+    /** Optimistic-concurrency token from a prior read. When omitted, the server uses the current revision. */
+    expectedRevision?: number;
+    /** A short human intent for the edit (attribution + observability). */
+    userIntent?: string;
+    /** When true, the result includes a fingerprint-validated preview still URL of the post-edit state. */
+    includeRenderUrl?: boolean;
+}
+/** The per-op outcome (surface-agnostic; created ids normalized across surfaces). */
+export interface EditorOpResult {
+    op: string;
+    /** The op's stable id (the one you sent, or the one generated for you), echoed back for every op. */
+    opId: string;
+    ok: boolean;
+    error?: string;
+    warnings?: string[];
+    createdIds?: string[];
+    /** For an async effect op (remove_background): the studio_outputs id of the dispatched job, so the caller can
+     *  wait_for_generation on it. Present only on a successfully-dispatched async op. */
+    generatingOutputId?: string;
+}
+/** Result of `applyEditorOps`: the new revision + per-op results. */
+export interface ApplyEditorOpsResult {
+    revision: number;
+    results: EditorOpResult[];
+    /** Present only when `includeRenderUrl` was set: a preview still URL of the resulting composition. */
+    renderUrl?: string | null;
+}
+/** Which surface a project is: an editor (video timeline) or a canvas (slides/layers). */
+/**
+ * Which surface a project lives on.
+ *
+ * Named `ProjectKind` for source compatibility; the field it describes is now `surface`. The API column was
+ * renamed because `canvas` and `editor` are two of the product's eleven surfaces, while `kind` now means the
+ * document shape (`tracks` | `slides`) on a project version.
+ */
+export type ProjectKind = 'editor' | 'canvas';
+export type ProjectSurface = ProjectKind;
+/** Lightweight project list item (spans both surfaces), from `listProjects`. */
+export interface ProjectSummary {
+    id: string;
+    surface: string;
+    /** @deprecated Alias for `surface`, still emitted for one release window. Prefer `surface`. */
+    kind: string;
+    title: string;
+    orientation: string;
+    width: number;
+    height: number;
+    thumbnailUrl: string | null;
+    isArchived: boolean;
+    isFavorited: boolean;
+    createdAt: string | null;
+    updatedAt: string | null;
+}
+/**
+ * A project's full detail, from `getProject` (read-before-write) and returned by `createProject`. Extends
+ * the summary with the composition `state` + `revision` (pass the revision back as `applyEditorOps`'s
+ * `expectedRevision`) plus the link fields.
+ */
+/** One clip group on the timeline: its members share a groupId, and the ordinal/name are stamped on each.
+ *  Rolled up by get_project so you can list groups + resolve members without scanning every clip. */
+export interface GroupSummary {
+    id: string;
+    /** Stable "Group N" number, assigned at creation and never renumbered. */
+    ordinal: number | null;
+    /** Optional user/agent-set name (via update_group); null means show "Group {ordinal}". */
+    name: string | null;
+    memberClipIds: string[];
+}
+export interface ProjectDetail extends ProjectSummary {
+    revision: number;
+    /** The full composition state (`{ slides }` for canvas, `{ tracks }` for the editor timeline). */
+    state: unknown;
+    /** Timeline clip groups rolled up from the clips. Empty for canvas. Use to list/target groups
+     *  (update_group to rename, update_clips with `groupId` to bulk-edit a whole group). */
+    groups: GroupSummary[];
+    assetReferences: unknown;
+    brandKitId: string | null;
+    exportedPostId: string | null;
+    exportedUrl: string | null;
+    shareId: string | null;
+    favoritedAt: string | null;
+    archivedAt: string | null;
+    /** A fingerprint-validated preview still URL. Present only when getProject is called with
+     *  `includeRenderUrl` (opt-in, since it may render). */
+    renderUrl?: string | null;
+    /**
+     * The coordinate space LAYER GEOMETRY is expressed in. This is NOT `width`/`height`.
+     *
+     * `width`/`height` are the project's OUTPUT resolution (what a render produces). Layer boxes and
+     * positions are in PREVIEW dims, the project scaled to a 960px longest edge, so a 2168x1152 project has
+     * a 960x510 layer space. The two differ by 2.26x there, and nothing in the response previously said so,
+     * which meant an external caller sizing a layer from `width`/`height` was silently wrong: an oversized
+     * box is valid input, so no error was ever raised.
+     *
+     * Use it for any absolute geometry, and pass it as layerWidth/layerHeight for a FULL-FRAME layer.
+     */
+    compositionSpace?: {
+        width: number;
+        height: number;
+    };
+}
+/** One live participant in `getContext`: who is present and on what surface/scope. */
+export interface LiveContextParticipant {
+    userId: string;
+    sessionId: string;
+    /** The surface they are on: 'canvas' | 'editor' | 'studio' | 'content' | future surfaces. */
+    surface: string;
+    projectId: string | null;
+    postId: string | null;
+    /** ISO timestamp of their last activity. */
+    updatedAt: string;
+}
+/** The result of `getContext`: the most-recent-active session's live context + the full participant set. */
+export interface LiveContextResult {
+    /**
+     * The most-recent-active session's context: a discriminated `{ surface, ...surfaceState }` object carrying
+     * the focus (e.g. `focusedSlideId`, `playheadFrame`) and current selection. A short-lived `snapshotUrl` of
+     * the live viewport is included ONLY when the read was made with `capture: true`. Null when no session is live.
+     */
+    context: Record<string, unknown> | null;
+    /** Metadata for that default participant, or null when no one is live. */
+    participant: LiveContextParticipant | null;
+    /** Every currently-live participant, most-recent first, for multi-human callers. */
+    participants: LiveContextParticipant[];
+}
+/** Options for `getContext`. */
+export interface GetContextInput {
+    /** Scope to a specific project's presence (editor/canvas). Omit for the caller's most-recent surface anywhere. */
+    projectId?: string;
+    /**
+     * Opt in to vision: also ping the live tab for a fresh viewport screenshot at read time, returned as a
+     * short-lived `snapshotUrl`. Default false = structured-only (fast, never touches the live page). To see the
+     * COMPOSED OUTPUT (not the user's screen) use `render` instead.
+     */
+    capture?: boolean;
+    /**
+     * Opt in to an inline render (never persisted), returned as image(s), so you can visually verify work while
+     * iterating. `true` renders the current focus point as a still; use `mode` + the params below for a filmstrip.
+     * Ephemeral (counts against no quota) and does not need a live tab. To watch a RAW source clip use `getMedia`
+     * with a video item; for a composed VIDEO of a range use `createPreview` / `getPreview` (a job).
+     */
+    render?: boolean;
+    /**
+     * Render tier (inferred from the params when omitted): 'still' (one composed frame/slide) or 'filmstrip' (N
+     * composed frames across an editor range).
+     */
+    mode?: 'still' | 'filmstrip';
+    /** still (editor): which timeline frame. Omit to render the current playhead frame. */
+    frame?: number;
+    /** still (canvas): which slide (id). Omit to render the focused slide. */
+    slideId?: string;
+    /** still (canvas): which slide (1-based index; alternative to `slideId`). */
+    slideIndex?: number;
+    /** filmstrip: start timeline frame of the range (edit space). Omit to start at the beginning. */
+    fromFrame?: number;
+    /** filmstrip: end timeline frame of the range. Omit to run to the end. */
+    toFrame?: number;
+    /** filmstrip: how many frames to return. Omit for a proportional default. */
+    count?: number;
+    /**
+     * still: render at an explicit DISPLAY width in pixels, so you can judge legibility at the size the output
+     * will actually be seen (a classroom tile, a thumbnail, a feed card) rather than at full resolution, where
+     * small type always looks fine. Height is derived from the composition's aspect ratio and is deliberately
+     * not a parameter. Clamped to a sane range; the size actually produced comes back on `rendered`.
+     */
+    width?: number;
+}
+/** Input to `createPreview`: currently a short COMPOSED video of an editor range (ephemeral, job-based). */
+export interface PreviewInput {
+    projectId: string;
+    /** Start timeline frame of the range (edit space). Omit to start at the beginning. */
+    fromFrame?: number;
+    /** End timeline frame. Omit to run to the end (capped to a short preview length). */
+    toFrame?: number;
+}
+/** The handle returned by `createPreview`; feed `renderId` + `bucketName` to `getPreview`. */
+export interface PreviewJob {
+    renderId: string;
+    bucketName: string;
+    fromFrame: number;
+    toFrame: number;
+    durationSeconds: number;
+}
+/** The poll result for a preview render. */
+export interface PreviewStatus {
+    status: 'rendering' | 'done' | 'failed';
+    /** 0..1 while rendering. */
+    progress?: number;
+    /** Short-lived signed URL to the ephemeral preview output (present when status = 'done'). */
+    url?: string;
+    /** Estimated Lambda cost for this render (telemetry). */
+    estimatedCostUsd?: number;
+    error?: string;
+}
+/** A resolved selected editor timeline clip, threaded so you see the selection without a `getProject` hop. */
+export interface EditorSelectedItem {
+    id: string;
+    type: string;
+    trackId?: string;
+    /** Timeline start frame (edit space). */
+    from: number;
+    durationInFrames: number;
+    /** Resolved media URL for image/video/audio clips, so you can fetch the raw clip directly. */
+    mediaUrl?: string;
+}
+/** The inline render returned when `getContext` is called with `render`. Shape depends on the tier. */
+export interface LiveContextRender {
+    /** The tier that produced this: 'still' (default) | 'filmstrip'. */
+    mode?: 'still' | 'filmstrip';
+    surface?: 'editor' | 'canvas';
+    frame?: number;
+    slideId?: string;
+    slideIndex?: number;
+    /** still: the pixel size of the returned image. Confirms what an explicit `width` request actually produced
+     *  (it is clamped), and reports the derived height. */
+    width?: number;
+    height?: number;
+    /** still: `data:image/webp;base64,...` of the composed frame/slide. */
+    dataUrl?: string;
+    fromFrame?: number;
+    toFrame?: number;
+    frames?: Array<{
+        frame?: number;
+        dataUrl: string;
+    }>;
+}
+/** Filters for `listProjects`. */
+export interface ListProjectsInput {
+    /** 'archived' -> only archived; 'favorited' -> favorited + not archived; omitted -> not archived. */
+    filter?: 'archived' | 'favorited';
+    /** Restrict to one surface. Omitted returns both. */
+    surface?: ProjectSurface;
+    /** @deprecated Alias for `surface`, accepted for one release window. `surface` wins if both are set. */
+    kind?: ProjectKind;
+    /** Case-insensitive title search. */
+    search?: string;
+}
+/** Input to `createProject`. All optional; the server applies the same defaults as the in-app new-project
+ *  flow (16:9 landscape, `editor` kind, an empty composition the app lazy-inits). */
+export interface CreateProjectInput {
+    surface?: ProjectSurface;
+    /** @deprecated Alias for `surface`, accepted for one release window. */
+    kind?: ProjectKind;
+    title?: string;
+    orientation?: string;
+    width?: number;
+    height?: number;
+    brandKitId?: string;
+}
+/** A source for `importProject`: a PowerPoint / Google Slides file URL, or a Canva design id. */
+export type ImportProjectSource = {
+    type: 'pptx';
+    fileUrl: string;
+} | {
+    type: 'canva';
+    designId: string;
+};
+/** Input to `importProject`. Creates a new canvas project from the imported deck. */
+export interface ImportProjectInput {
+    source: ImportProjectSource;
+    /** Title for the created project. Defaults to 'Imported deck'. */
+    title?: string;
+    /** Optional slide count for an early page-cap check. */
+    pageCount?: number;
+}
+/** Options for starting a project export. All optional; defaults: format 'mp4', 720p, watermark on. */
+export interface StartExportInput {
+    /** 'mp4' (both surfaces) or 'png'/'jpg' (both surfaces) or 'pdf'/'pptx' (canvas only). */
+    format?: string;
+    /** Video resolution (mp4): '480p'|'720p'|'1080p'|'2k'|'4k'. 1080p+ is plan-gated. */
+    resolution?: string;
+    /** Video quality (mp4): 'low'|'recommended'|'high'. */
+    quality?: string;
+    /** Keep the watermark. Removing it is plan-gated. Defaults true. */
+    watermark?: boolean;
+    /** Editor still (png/jpg) only: the timeline frame to render. Clamped to the composition length. Defaults 0. */
+    frame?: number;
+}
+/** An export job. `mp4` starts as 'rendering' (poll it); canvas still/doc formats return 'completed'. */
+export interface ExportJob {
+    exportId: string;
+    /** 'pending' | 'rendering' | 'transferring' | 'completed' | 'failed'. */
+    status: string;
+    /** The final file URL, present when status is 'completed'. */
+    outputUrl?: string | null;
+    errorMessage?: string | null;
+    /** 0..1 render progress. */
+    progress?: number;
+}
+/** One format in the export catalog. */
+export interface ExportFormatSpec {
+    format: string;
+    surfaces: string[];
+    /** true = async render job (poll it); false = returned completed immediately. */
+    async: boolean;
+    description: string;
+    options: string[];
+}
+/** The export-format catalog, from `getExportFormats`. */
+export interface ExportFormatCatalog {
+    formats: ExportFormatSpec[];
+    resolutions: string[];
+    qualities: string[];
+}
+/** One editable field on a layer/clip type (from the type-discovery catalogs). */
+export interface EditorTypeProp {
+    name: string;
+    /** A human-readable type hint (e.g. 'string', 'number', "'left' | 'center' | 'right'"). */
+    type: string;
+    description?: string;
+}
+/** A layer/clip type and its editable props. */
+export interface EditorTypeSpec {
+    type: string;
+    description: string;
+    props: EditorTypeProp[];
+    /** Which shared prop groups this type also accepts (keys of `sharedProps`). */
+    supports: string[];
+    /** A copy-pasteable minimal item skeleton for creating this type via add_item / insert_prebuilt_track. */
+    example?: Record<string, unknown>;
+}
+/** How to CREATE clips + tracks (the creation ops of update_timeline), documented alongside the edit ops. */
+export interface EditorCreationSpec {
+    description: string;
+    ops: {
+        op: string;
+        shape: string;
+        description: string;
+    }[];
+}
+/** A timeline track type and the clip types it holds. */
+export interface EditorTrackSpec {
+    trackType: string;
+    description: string;
+    holds: string[];
+}
+/** Shared prop groups reused across visual types (referenced by each type's `supports`). */
+export interface EditorSharedProps {
+    base: EditorTypeProp[];
+    transform: EditorTypeProp[];
+    decoration: EditorTypeProp[];
+    adjust: EditorTypeProp[];
+}
+/** The canvas layer-type catalog, from `getLayerTypes`. Makes `update_canvas` self-describing. */
+export interface LayerTypeCatalog {
+    surface: 'canvas';
+    description: string;
+    sharedProps: EditorSharedProps;
+    layerTypes: EditorTypeSpec[];
+    /** The update_canvas op vocabulary: every layer + slide op an agent can emit, with its field signature. */
+    ops?: EditorCreationSpec;
+}
+/** The editor timeline clip + track-type catalog, from `getTimelineTypes`. Makes `update_timeline`
+ *  self-describing. */
+export interface TimelineTypeCatalog {
+    surface: 'editor';
+    description: string;
+    sharedProps: EditorSharedProps;
+    clipTypes: EditorTypeSpec[];
+    trackTypes: EditorTrackSpec[];
+    /** How to CREATE clips + tracks (add_item, insert_track, insert_prebuilt_track), using each clipType `example`. */
+    creation?: EditorCreationSpec;
+    /** The EDIT ops of update_timeline (move_clip, trim_clip, disable_ranges, ...), with each field signature. */
+    editOps?: EditorCreationSpec;
+}
+/** A spoken word with source-media timing, ABSOLUTE timeline frames, and per-word metadata (granularity 'word'). */
+export interface WordTiming {
+    text: string;
+    /** Start within the SOURCE media, in ms. */
+    startMs: number;
+    /** End within the SOURCE media, in ms (exclusive). */
+    endMs: number;
+    /** Absolute timeline frame this word starts on (feed straight into update_timeline split / range ops). */
+    startFrame: number;
+    /** Absolute timeline frame this word ends on. */
+    endFrame: number;
+    /** Diarized speaker, when known. */
+    speakerId: string | null;
+    /** Normalized 0-1 confidence, when known. */
+    confidence: number | null;
+}
+/** A derived dead-air gap between words within a clip: source-media range + timeline frames + duration. */
+export interface Silence {
+    startMs: number;
+    endMs: number;
+    durationMs: number;
+    startFrame: number;
+    endFrame: number;
+}
+/** A non-speech audio event (e.g. "[chuckles]", "[sighs]") with source-media timing + timeline frames. */
+export interface AudioEvent {
+    text: string;
+    startMs: number;
+    endMs: number;
+    startFrame: number;
+    endFrame: number;
+    speakerId: string | null;
+}
+/** One timeline clip's transcript segment: the words spoken within it plus its current enabled/disabled state. */
+export interface TranscriptSegment {
+    /** The timeline clip id, targetable by update_timeline disable_ranges / set_disabled / delete_ranges. */
+    clipId: string;
+    /** Whether the clip is currently excluded from the render (disabled). */
+    disabled: boolean;
+    /** Why it was disabled ('silence' | 'manual' | 'agent'), when known. */
+    disabledReason: string | null;
+    /** The freeform note an agent left explaining this cut, when present. */
+    disabledNote: string | null;
+    /** Start of this clip's slice within its SOURCE media, in milliseconds. */
+    sourceStartMs: number;
+    /** End of this clip's slice within its SOURCE media, in milliseconds (exclusive). */
+    sourceEndMs: number;
+    /** The clip's start position on the TIMELINE, in frames (source range maps onto [fromFrame, fromFrame+durationFrames)). */
+    fromFrame: number;
+    /** The clip's length on the TIMELINE, in frames. */
+    durationFrames: number;
+    /** The words spoken within this clip, space-joined. Empty for a silence gap or untranscribed clip. */
+    text: string;
+    /** Word-level timing (granularity 'word' only), scoped to the requested window when given. */
+    words?: WordTiming[];
+    /** Derived dead-air gaps within this clip (granularity 'word' only). */
+    silences?: Silence[];
+    /** Non-speech audio events within this clip (granularity 'word' only; empty for pre-token-store media). */
+    audioEvents?: AudioEvent[];
+}
+export interface TranscriptResult {
+    projectId: string;
+    /**
+     * The project's current optimistic-concurrency revision. Pass it straight back as `applyEditorOps` /
+     * update_timeline's `expectedRevision` to make a follow-up edit fail on a concurrent change instead of
+     * clobbering it. `expectedRevision` is optional, so omit it to just apply to the current revision.
+     */
+    revision: number;
+    fps: number;
+    /** true when at least one clip's source media had a stored transcript. */
+    mediaTranscribed: boolean;
+    segmentCount: number;
+    segments: TranscriptSegment[];
+    /** The distinct diarized speakers present across the returned transcript, sorted. */
+    speakers?: string[];
+    /** Present only when nothing has been transcribed yet, explaining the empty result. */
+    note?: string;
+}
 //# sourceMappingURL=types.d.ts.map