@contenthero/sdk 0.3.2 → 0.3.4

package/dist/client.js

@@ -6,13 +6,20 @@
  * SDK offers both a fire-and-forget `generate` and a `generateAndWait` that
  * polls to a terminal state for you.
  */
-import { errorFromResponse, GenerationFailedError, GenerationTimeoutError } from './errors.js';
+import { errorFromResponse, GenerationFailedError, GenerationInterruptedError, GenerationTimeoutError, } from './errors.js';
 const DEFAULT_BASE_URL = 'https://app.contenthero.ai';
 const TERMINAL = new Set(['completed', 'failed']);
 export class ContentHero {
     apiKey;
     baseUrl;
     fetchImpl;
+    /** Per-project last-touched timestamp (ms). Presence is lit SERVER-SIDE (every project-scoped route broadcasts
+     *  the badge), so this no longer drives per-call pings; it records which projects this client operated on so
+     *  releaseProjectActivity / flushRelease can clear their badges promptly on exit, and debounces any explicit
+     *  touchProjectActivity ping. */
+    activityPingedAt = new Map();
+    /** Min gap between explicit presence pings for the same project, so a burst does not spam. */
+    static ACTIVITY_DEBOUNCE_MS = 10_000;
     constructor(options = {}) {
         const apiKey = options.apiKey ?? readEnv('CONTENTHERO_API_KEY');
         if (!apiKey) {
@@ -26,6 +33,43 @@ export class ContentHero {
         this.baseUrl = (options.baseUrl ?? readEnv('CONTENTHERO_BASE_URL') ?? DEFAULT_BASE_URL).replace(/\/+$/, '');
         this.fetchImpl = fetchImpl;
     }
+    /**
+     * Explicitly signal PRESENCE for a project. Presence is normally lit SERVER-SIDE now (every project-scoped API
+     * route broadcasts the "Editing via MCP/CLI" badge for the resolved project), so the SDK's own methods no longer
+     * each call this. It remains for an external consumer that wants to signal presence ahead of working on a
+     * project, and it records the project for prompt release on exit. Debounced + fire-and-forget: never throws,
+     * never blocks, no-op without a projectId.
+     */
+    touchProjectActivity(projectId) {
+        if (!projectId)
+            return;
+        const now = Date.now();
+        const last = this.activityPingedAt.get(projectId) ?? 0;
+        if (now - last < ContentHero.ACTIVITY_DEBOUNCE_MS)
+            return;
+        this.activityPingedAt.set(projectId, now);
+        void this.request('POST', '/api/v1/editor/activity', { projectId }).catch(() => { });
+    }
+    /**
+     * Explicitly RELEASE presence so the badge clears promptly (no TTL lingering). Use in a `finally` when a
+     * short-lived consumer (the CLI) finishes a command. Fire-and-forget.
+     */
+    releaseProjectActivity(projectId) {
+        if (!projectId)
+            return;
+        this.activityPingedAt.delete(projectId);
+        void this.request('POST', '/api/v1/editor/activity', { projectId, release: true }).catch(() => { });
+    }
+    /**
+     * AWAIT a presence release for every project this client pinged. The CLI calls this before the process exits
+     * so the badge clears immediately (a short-lived process cannot rely on the sliding TTL). Best-effort:
+     * resolves even if the releases fail.
+     */
+    async flushRelease() {
+        const ids = [...this.activityPingedAt.keys()];
+        this.activityPingedAt.clear();
+        await Promise.all(ids.map((projectId) => this.request('POST', '/api/v1/editor/activity', { projectId, release: true }).catch(() => { })));
+    }
     /**
      * Submit a generation. Returns immediately. For image/video the result is
      * `status: 'processing'` (poll with `getGeneration` or use `generateAndWait`);
@@ -46,7 +90,10 @@ export class ContentHero {
      */
     async generateAndWait(request, options = {}) {
         const submitted = await this.generate(request);
-        return this.waitForGeneration(submitted.outputId, options);
+        const gen = await this.#waitAfterSubmit(submitted.outputId, options);
+        // Carry the placement outcome (known at submit time) through to the completed record so the caller learns
+        // where the asset landed + its id for chaining, without a separate lookup.
+        return submitted.placement ? { ...gen, placement: submitted.placement } : gen;
     }
     /**
      * Submit a Reference Board: a dense multi-panel reference sheet built from a
@@ -65,7 +112,26 @@ export class ContentHero {
      */
     async generateBoardAndWait(request, options = {}) {
         const submitted = await this.generateBoard(request);
-        return this.waitForGeneration(submitted.outputId, options);
+        return this.#waitAfterSubmit(submitted.outputId, options);
+    }
+    /**
+     * Poll a job that has ALREADY been submitted, converting any non-terminal failure into
+     * an error that still carries the outputId.
+     *
+     * Once the POST succeeds the job is running and charged, so the outputId is the only
+     * thing standing between a transient poll failure and a duplicate generation: a caller
+     * that loses it has no way to resume and will almost certainly resubmit. A genuine
+     * `GenerationFailedError` is terminal and passes through untouched.
+     */
+    async #waitAfterSubmit(outputId, options) {
+        try {
+            return await this.waitForGeneration(outputId, options);
+        }
+        catch (err) {
+            if (err instanceof GenerationFailedError || err instanceof GenerationTimeoutError)
+                throw err;
+            throw new GenerationInterruptedError(outputId, err);
+        }
     }
     /**
      * Estimate the credit cost of a generation without running it (the get_cost
@@ -92,7 +158,10 @@ export class ContentHero {
         const deadline = Date.now() + timeoutMs;
         while (true) {
             const generation = await this.getGeneration(outputId);
-            if (generation.status === 'completed')
+            // Terminal only when SETTLED: a placement-bearing generation is not "done" for a caller until its swap /
+            // cutout side-effect has landed (see Generation.settled). `settled !== false` keeps older servers (which
+            // omit the field) working as before, and a no-placement output is settled the moment it completes.
+            if (generation.status === 'completed' && generation.settled !== false)
                 return generation;
             if (generation.status === 'failed') {
                 throw new GenerationFailedError(generation.outputId, generation.error ?? 'Generation failed');
@@ -114,6 +183,25 @@ export class ContentHero {
     async transcribe(request) {
         return this.request('POST', '/api/v1/studio/transcribe', request);
     }
+    /**
+     * Transform existing audio with an audio-processing model. Two shapes:
+     *
+     * FILE mode (`sourceUrl`): process a standalone file into a new library asset. Voice isolation is
+     * synchronous and the processed URL comes back inline on `outputUrls`; enhancement is asynchronous and
+     * returns an `outputId` to poll.
+     *
+     * IN-PLACE mode (`projectId` + `clipIds` / `enhanceClips`): enhance the audio OF EXISTING CLIPS on a
+     * timeline. Returns one job per SOURCE on `outputs`, because the vendor estimates a noise profile per
+     * production, so a source's clips are concatenated and enhanced together while separate recordings stay
+     * separate jobs.
+     */
+    async editAudio(request) {
+        return this.request('POST', '/api/v1/studio/audio/edit', request);
+    }
+    /** Cost preview for `editAudio` (nothing runs, nothing is charged). */
+    async estimateEditAudioCost(request) {
+        return this.request('POST', '/api/v1/studio/audio/edit', { ...request, getCost: true });
+    }
     /** List the account's avatars (the list half of the list+get pair). */
     async listAvatars() {
         const data = await this.request('GET', '/api/v1/avatars');
@@ -124,8 +212,12 @@ export class ContentHero {
         return this.request('GET', `/api/v1/avatars/${encodeURIComponent(avatarId)}`);
     }
     /** List the account's saved voices (the list half of the list+get pair). */
-    async listVoices() {
-        const data = await this.request('GET', '/api/v1/voices');
+    async listVoices(options = {}) {
+        const q = new URLSearchParams();
+        if (options.favorited)
+            q.set('favorited', 'true');
+        const qs = q.toString();
+        const data = await this.request('GET', `/api/v1/voices${qs ? `?${qs}` : ''}`);
         return data.voices;
     }
     /** Get one voice's detail (the get half). Throws NotFoundError if absent. */
@@ -133,8 +225,50 @@ export class ContentHero {
         return this.request('GET', `/api/v1/voices/${encodeURIComponent(voiceId)}`);
     }
     /** List the account's brand kits (the list half of the list+get pair). */
-    async listBrandKits() {
-        const data = await this.request('GET', '/api/v1/brand-kits');
+    async listBrandKits(options = {}) {
+        const q = new URLSearchParams();
+        if (options.favorited)
+            q.set('favorited', 'true');
+        if (options.archived)
+            q.set('archived', 'true');
+        const qs = q.toString();
+        const data = await this.request('GET', `/api/v1/brand-kits${qs ? `?${qs}` : ''}`);
+        return data.brandKits;
+    }
+    /**
+     * Create a brand kit. Requires the `brandkit:write` scope.
+     *
+     * Three sources, and the input decides which: EMPTY (just a name), FROM A WEBSITE
+     * (`websiteUrl` + `extract: true`), or A COPY (`duplicateFrom`).
+     *
+     * ⚠️ WITH `extract` IT RETURNS IMMEDIATELY, before the kit has any content. That empty kit is the HANDLE:
+     * the thing to poll and the row the UI renders at once. Poll `extractionStatus` via `getBrandKit`.
+     */
+    async createBrandKit(input) {
+        // A copy is a create with a source, so it shares this method rather than owning a verb of its own.
+        if (input.duplicateFrom) {
+            const { duplicateFrom, name } = input;
+            const data = await this.request('POST', `/api/v1/brand-kits/${encodeURIComponent(duplicateFrom)}/duplicate`, name ? { name } : {});
+            return { brandKit: data.brandKit };
+        }
+        return this.request('POST', '/api/v1/brand-kits', input);
+    }
+    /**
+     * Re-run website extraction for an existing kit. Returns at once; poll `extractionStatus`.
+     * Requires the kit to already have a `websiteUrl`, and the `brandkit:write` scope.
+     */
+    async extractBrandKit(brandKitId) {
+        const data = await this.request('POST', `/api/v1/brand-kits/${encodeURIComponent(brandKitId)}/extract`);
+        return data.extraction;
+    }
+    /**
+     * Reorder the account's brand kits. Collection-level because ordering is a property of the SET: a per-kit
+     * position would let two kits claim one slot. Pass every id, in the order you want.
+     */
+    async reorderBrandKits(orderedIds) {
+        const data = await this.request('PATCH', '/api/v1/brand-kits', {
+            orderedIds,
+        });
         return data.brandKits;
     }
     /** Get one brand kit, fully assembled (the get half). Throws NotFoundError if absent. */
@@ -149,11 +283,6 @@ export class ContentHero {
     async updateBrandKit(brandKitId, input) {
         return this.request('PATCH', `/api/v1/brand-kits/${encodeURIComponent(brandKitId)}`, input);
     }
-    /** Archive a brand kit (reversible). Requires the `brandkit:write` scope. */
-    async archiveBrandKit(brandKitId) {
-        const data = await this.request('PATCH', `/api/v1/brand-kits/${encodeURIComponent(brandKitId)}`, { archive: true });
-        return data.brandKit;
-    }
     /** Add a curated section to a brand kit. Requires the `brandkit:write` scope. */
     async addBrandKitSection(brandKitId, input) {
         const data = await this.request('POST', `/api/v1/brand-kits/${encodeURIComponent(brandKitId)}/sections`, input);
@@ -164,11 +293,6 @@ export class ContentHero {
         const data = await this.request('PATCH', `/api/v1/brand-kits/${encodeURIComponent(brandKitId)}/sections/${encodeURIComponent(sectionId)}`, input);
         return data.section;
     }
-    /** Archive a brand-kit section (soft delete, reversible). Requires `brandkit:write`. */
-    async archiveBrandKitSection(brandKitId, sectionId) {
-        const data = await this.request('DELETE', `/api/v1/brand-kits/${encodeURIComponent(brandKitId)}/sections/${encodeURIComponent(sectionId)}`);
-        return data.section;
-    }
     // -------------------------------------------------------------------------
     // Brand knowledge (a brand kit's knowledge base)
     // -------------------------------------------------------------------------
@@ -206,9 +330,15 @@ export class ContentHero {
     async removeBrandKnowledge(brandKitId, knowledgeId) {
         return this.request('DELETE', `/api/v1/brand-kits/${encodeURIComponent(brandKitId)}/knowledge/${encodeURIComponent(knowledgeId)}`);
     }
-    /** List the account's recent studio outputs (the list half of the list+get pair). */
+    /**
+     * List the account's recent media (the list half of the list+get pair). `source`
+     * selects the library: 'creations' (default, studio outputs) or 'uploads' (the
+     * editor Uploads tab).
+     */
     async listMedia(options = {}) {
         const q = new URLSearchParams();
+        if (options.source)
+            q.set('source', options.source);
         if (options.contentType) {
             const types = Array.isArray(options.contentType) ? options.contentType : [options.contentType];
             q.set('contentType', types.join(','));
@@ -217,6 +347,10 @@ export class ContentHero {
             q.set('status', options.status);
         if (options.kind)
             q.set('kind', options.kind);
+        if (options.favorited)
+            q.set('favorited', 'true');
+        if (options.archived)
+            q.set('archived', 'true');
         if (options.limit != null)
             q.set('limit', String(options.limit));
         if (options.offset != null)
@@ -226,12 +360,71 @@ export class ContentHero {
         return data.media;
     }
     /**
-     * Get one studio output by id token (the get half). The token may be the full
-     * output id, its first 8 characters, or either with a `-N` variation suffix
-     * (1-based). Throws NotFoundError if absent.
+     * Get one media item by id token (the get half). `source` selects the library the
+     * id belongs to: 'creations' (default, a studio output; token may be the full id,
+     * its first 8 characters, or either with a `-N` variation suffix), 'uploads' (an
+     * editor Uploads-tab file; full id or short id, no variations), or 'stock' (a used
+     * stock item; full id or short id, no variations). Pass the same source the item
+     * reported in listMedia. Throws NotFoundError if absent.
+     */
+    async getMedia(idToken, options = {}) {
+        const qs = options.source ? `?source=${encodeURIComponent(options.source)}` : '';
+        return this.request('GET', `/api/v1/media/${encodeURIComponent(idToken)}${qs}`);
+    }
+    /**
+     * Semantically search the account's editable media library (creations, uploads, licensed stock, brand assets)
+     * by describing the content in natural language. Returns matching assets ranked by relevance, each with a
+     * description, tags, and, for videos, the timestamps of the scenes that matched, so a precise moment can be
+     * located. Searches only the account's own usable library, never inspiration, published posts, or knowledge.
+     */
+    async searchMedia(query, options = {}) {
+        const q = new URLSearchParams({ query });
+        if (options.kinds && options.kinds.length > 0)
+            q.set('kinds', options.kinds.join(','));
+        if (options.limit != null)
+            q.set('limit', String(options.limit));
+        const data = await this.request('GET', `/api/v1/media/search?${q.toString()}`);
+        return data.results;
+    }
+    // ─── Library folders (Unified Content Library, Phase D) ────────────────────
+    /** List the account's folders (manual + smart, with parent links) plus the built-in derived folders. */
+    async listFolders() {
+        return this.request('GET', '/api/v1/library/folders');
+    }
+    /** A folder's contents. `folderId` is a folder id or a derived key (recents|favorites|edits|canvas|posts). */
+    async getFolder(folderId) {
+        const data = await this.request('GET', `/api/v1/library/folders/${encodeURIComponent(folderId)}`);
+        return { folder: data.folder, items: data.items };
+    }
+    async createFolder(input) {
+        const data = await this.request('POST', '/api/v1/library/folders', input);
+        return data.folder;
+    }
+    async updateFolder(folderId, patch) {
+        const data = await this.request('PATCH', `/api/v1/library/folders/${encodeURIComponent(folderId)}`, patch);
+        return data.folder;
+    }
+    async deleteFolder(folderId) {
+        await this.request('DELETE', `/api/v1/library/folders/${encodeURIComponent(folderId)}`);
+    }
+    /** File an item into a manual folder (a pointer; no bytes move). */
+    async addToFolder(folderId, ref) {
+        await this.request('POST', `/api/v1/library/folders/${encodeURIComponent(folderId)}/items`, ref);
+    }
+    async removeFromFolder(folderId, ref) {
+        await this.request('DELETE', `/api/v1/library/folders/${encodeURIComponent(folderId)}/items`, ref);
+    }
+    /**
+     * Resolve a batch of media references to vision-ready URLs + light metadata (the
+     * micro drill-in behind get_context's macro screenshot). Each item is a raw
+     * `{ url }` or an `{ mediaId, variation? }`; a mediaId with no variation resolves
+     * to only the primary variation (siblings listed in `otherVariations`), never a
+     * whole generation. Returns one entry per item, in order; a bad item comes back
+     * with `ok: false` rather than failing the batch. Max 10 items per call (the SDK
+     * returns URLs; the MCP layer is what turns them into image blocks for a model).
      */
-    async getMedia(idToken) {
-        return this.request('GET', `/api/v1/media/${encodeURIComponent(idToken)}`);
+    async getMediaBatch(items) {
+        return this.request('POST', '/api/v1/media/batch', { items });
     }
     // -------------------------------------------------------------------------
     // Media upload (bring your own file or URL -> first-class media)
@@ -266,11 +459,23 @@ export class ContentHero {
             contentType: opts.contentType,
             sizeBytes,
         });
-        // The PUT goes to Supabase storage (not our API), so it uses a bare fetch
-        // with only the file's Content-Type, none of our auth headers.
+        // The PUT goes straight to object storage (not our API), so it uses a bare
+        // fetch with none of our auth headers.
+        //
+        // The headers come from the SERVER rather than being assumed here. Storage
+        // used to be Supabase, where Content-Type alone is enough; it is moving to
+        // R2, where the presigned URL signs the owner in as `x-amz-meta-user_id` and
+        // a PUT missing it is rejected with SignatureDoesNotMatch (verified: 403
+        // with Content-Type alone, 200 with both). Letting the server say what to
+        // send means this client never has to know which store it is talking to,
+        // and the migration needs no coordinated release of it.
+        //
+        // Falls back to Content-Type so an older API that does not return
+        // uploadHeaders keeps working, which is what makes the two deployable in
+        // either order.
         const put = await this.fetchImpl(created.uploadUrl, {
             method: 'PUT',
-            headers: { 'Content-Type': opts.contentType },
+            headers: created.uploadHeaders ?? { 'Content-Type': opts.contentType },
             body: data,
         });
         if (!put.ok) {
@@ -399,10 +604,6 @@ export class ContentHero {
         const data = await this.request('PATCH', `/api/v1/posts/${encodeURIComponent(postId)}`, input);
         return data.post;
     }
-    /** Archive a post (status -> 'archived'). No hard delete. */
-    async archivePost(postId) {
-        return this.updatePost(postId, { status: 'archived' });
-    }
     /**
      * List the account's pipeline stages (sorted), seeding the defaults on first
      * access. Use this to resolve a stage before placing a post; stages are
@@ -510,6 +711,8 @@ export class ContentHero {
             q.set('sort_by', options.sortBy);
         if (options.brandKitId)
             q.set('brand_kit_id', options.brandKitId);
+        if (options.favorited)
+            q.set('favorited', 'true');
         if (options.limit != null)
             q.set('limit', String(options.limit));
         if (options.offset != null)
@@ -545,6 +748,281 @@ export class ContentHero {
         const data = await this.request('GET', `/api/v1/connected-accounts/${encodeURIComponent(accountId)}`);
         return data.account;
     }
+    // -------------------------------------------------------------------------
+    // Favorites & archive (universal set/clear across asset types)
+    // -------------------------------------------------------------------------
+    /**
+     * Mark an asset as favorited. Requires the `favorites:write` scope.
+     *
+     * Pass `{ assetType, id }` for a top-level asset (post, voice, brand_kit,
+     * project, inspiration_content, gallery), or `{ id, variationIndex }` to
+     * favorite a single studio output variation slot (id is a studio output id).
+     * Idempotent.
+     */
+    async favorite(input) {
+        await this.request('POST', '/api/v1/favorite', input);
+    }
+    /**
+     * Clear the favorite flag on an asset. Requires the `favorites:write` scope.
+     * Same target shape as `favorite`. Idempotent.
+     */
+    async unfavorite(input) {
+        await this.request('POST', '/api/v1/unfavorite', input);
+    }
+    /**
+     * Archive an asset. Requires the `favorites:write` scope.
+     *
+     * Pass `{ assetType, id }` for a top-level asset (post, brand_kit,
+     * brand_kit_section, project), or `{ id, variationIndex }` to archive a single
+     * studio output variation slot. Archiving a post sets its status to 'archived'.
+     * Idempotent.
+     */
+    async archive(input) {
+        await this.request('POST', '/api/v1/archive', input);
+    }
+    /**
+     * Unarchive an asset. Requires the `favorites:write` scope. Same target shape
+     * as `archive`. Unarchiving a post restores it to 'draft'. Idempotent.
+     */
+    async unarchive(input) {
+        await this.request('POST', '/api/v1/unarchive', input);
+    }
+    // -------------------------------------------------------------------------
+    // Editor / canvas ops (programmatic parity with the manual UI + in-app agent)
+    // -------------------------------------------------------------------------
+    /**
+     * List the caller's projects (both editor + canvas) as lightweight summaries. Filter by archived /
+     * favorited state, by `kind`, or by a title search. Requires the `editor:read` scope.
+     */
+    async listProjects(input = {}) {
+        const q = new URLSearchParams();
+        if (input.filter)
+            q.set('filter', input.filter);
+        if (input.kind)
+            q.set('kind', input.kind);
+        if (input.search)
+            q.set('search', input.search);
+        const qs = q.toString();
+        const { projects } = await this.request('GET', `/api/v1/projects${qs ? `?${qs}` : ''}`);
+        return projects;
+    }
+    /**
+     * Read a single project (metadata + composition `state` + `revision`), to read-before-write. Pass the returned
+     * `revision` back as `applyEditorOps`'s `expectedRevision`. By DEFAULT `state` is a lightweight SUMMARY (per-clip
+     * / per-layer structure, heavy payloads dropped); pass `detail:'full'` for the complete composition. For a
+     * timeline, `fromFrame`/`toFrame` (+ `trackId`) scope the read to the clips overlapping that frame window; for a
+     * canvas, `slideId` scopes it to a single slide, and applies to `detail:'full'` too so asking for one slide's
+     * detail does not pay for the whole deck. A canvas summary echoes each text layer's `text` (truncated), which is
+     * what identifies it. Requires the `editor:read` scope.
+     */
+    async getProject(projectId, options = {}) {
+        const params = new URLSearchParams();
+        if (options.includeRenderUrl)
+            params.set('includeRenderUrl', 'true');
+        if (options.detail === 'full')
+            params.set('detail', 'full');
+        if (typeof options.fromFrame === 'number')
+            params.set('fromFrame', String(options.fromFrame));
+        if (typeof options.toFrame === 'number')
+            params.set('toFrame', String(options.toFrame));
+        if (options.trackId)
+            params.set('trackId', options.trackId);
+        if (options.slideId)
+            params.set('slideId', options.slideId);
+        const qs = params.toString() ? `?${params.toString()}` : '';
+        const { project } = await this.request('GET', `/api/v1/projects/${encodeURIComponent(projectId)}${qs}`);
+        return project;
+    }
+    /**
+     * Read the LIVE context of what the user is currently viewing in the open app: the active surface + focus +
+     * selection, so an agent can operate on "what the user is looking at" like the internal assistant does. Fast
+     * and structured by default. Pass `capture: true` to also ping the live tab for a fresh viewport screenshot
+     * (returned as a short-lived `snapshotUrl`) when you need the user's screen as shown. To see the COMPOSED
+     * OUTPUT itself (the rendered editor frame or canvas slide), pass `render: true` (optionally `frame` for an
+     * editor project, or `slideId` / `slideIndex` for canvas); the render returns inline as a data URL, is
+     * ephemeral, and does not need a live tab. Returns the most-recent-active session's context plus the full live
+     * participant set. Optionally scope to one project. Requires the `context:read` scope.
+     */
+    async getContext(input = {}) {
+        const params = new URLSearchParams();
+        if (input.projectId)
+            params.set('projectId', input.projectId);
+        if (input.capture)
+            params.set('capture', 'true');
+        if (input.render)
+            params.set('render', 'true');
+        if (input.mode)
+            params.set('mode', input.mode);
+        if (typeof input.frame === 'number')
+            params.set('frame', String(input.frame));
+        if (input.slideId)
+            params.set('slideId', input.slideId);
+        if (typeof input.slideIndex === 'number')
+            params.set('slideIndex', String(input.slideIndex));
+        if (typeof input.fromFrame === 'number')
+            params.set('fromFrame', String(input.fromFrame));
+        if (typeof input.toFrame === 'number')
+            params.set('toFrame', String(input.toFrame));
+        if (typeof input.count === 'number')
+            params.set('count', String(input.count));
+        if (typeof input.width === 'number')
+            params.set('width', String(input.width));
+        // Canonical URI encoding: URLSearchParams renders a space as '+', which is x-www-form-urlencoded, not the
+        // RFC-3986 query encoding; emit %20 so the URL is canonical (both decode to a space server-side).
+        const query = params.toString().replace(/\+/g, '%20');
+        const qs = query ? `?${query}` : '';
+        return this.request('GET', `/api/v1/context${qs}`);
+    }
+    /**
+     * Create an async PREVIEW render (ephemeral, never stored). Currently a short low-res COMPOSED VIDEO of an
+     * editor range, so you can assess motion, cuts, transitions, and pacing a still cannot show. Returns a job
+     * handle; poll it with `getPreview`. Requires the `context:read` scope.
+     */
+    async createPreview(input) {
+        return this.request('POST', '/api/v1/preview', input);
+    }
+    /**
+     * Poll a preview started with `createPreview`. While rendering, returns `progress`; on completion, returns a
+     * short-lived signed `url` to the ephemeral output plus the estimated cost.
+     */
+    async getPreview(job) {
+        const params = new URLSearchParams({ renderId: job.renderId, bucketName: job.bucketName });
+        return this.request('GET', `/api/v1/preview?${params.toString()}`);
+    }
+    /**
+     * Create a project. All fields optional; the server applies the same defaults as the in-app new-project
+     * flow (16:9 landscape, `editor` kind). A new canvas starts with one empty slide; a new editor starts with
+     * an empty timeline. Returns the full detail (with its id + starting revision) so you can immediately apply
+     * ops. Requires the `editor:write` scope.
+     */
+    async createProject(input = {}) {
+        const { project } = await this.request('POST', '/api/v1/projects', input);
+        return project;
+    }
+    /**
+     * Import a PowerPoint / Google Slides file (by URL) or a Canva design (by id) into a NEW canvas project
+     * with editable layers, returning the created project's full detail. The Canva source uses the caller's
+     * Canva connection (a ConflictError-like 400 with code 'canva_not_connected' if not connected). Structured
+     * import can take a while (export + convert + parse). Requires the `editor:write` scope.
+     */
+    async importProject(input) {
+        const { project } = await this.request('POST', '/api/v1/projects/import', input);
+        return project;
+    }
+    /**
+     * PERMANENTLY delete a project (irreversible hard delete, distinct from the reversible archive). The
+     * `?confirm=true` opt-in is sent for you. To reversibly hide a project instead, use `archive`. Requires
+     * the `editor:write` scope.
+     */
+    async deleteProject(projectId) {
+        await this.request('DELETE', `/api/v1/projects/${encodeURIComponent(projectId)}?confirm=true`);
+    }
+    /**
+     * Apply a batch of ops to a project's composition (canvas slides or editor timeline) and persist
+     * atomically. The project's `surface` selects the op vocabulary; the ops run through the same reducers the manual
+     * UI and in-app agent use. Requires the `editor:write` scope.
+     *
+     * Optimistic concurrency: pass `expectedRevision` (from `getProject`) to fail with a 409 ConflictError if
+     * a concurrent edit landed, instead of clobbering it. Returns the new revision and the per-op results (a
+     * bad op is reported, never throws).
+     *
+     * Each op is given a client-generated `op_id` (uuid) here if it does not already have one, so the op has a
+     * stable identity from the point of intent: resending the same batch is idempotent (the server dedupes by
+     * op_id), and a live editor sees the edit as an attributed collaborator change keyed by that id. The
+     * assigned id is echoed back on each result's `opId`.
+     */
+    async applyEditorOps(input) {
+        const ops = input.ops.map((op) => typeof op.op_id === 'string' && op.op_id ? op : { ...op, op_id: globalThis.crypto.randomUUID() });
+        return this.request('POST', '/api/v1/editor/ops', { ...input, ops });
+    }
+    /**
+     * Start an export (render) of a project's saved composition. `mp4` returns a job with status 'rendering'
+     * (poll with getExport or use exportProjectAndWait); canvas still/document formats (png/jpg/pdf/pptx) run
+     * synchronously and return 'completed' with the outputUrl. Requires the `editor:write` scope.
+     */
+    async startExport(projectId, input = {}) {
+        return this.request('POST', `/api/v1/projects/${encodeURIComponent(projectId)}/export`, input);
+    }
+    /** Poll an export job by id. Requires the `editor:read` scope. */
+    async getExport(exportId) {
+        return this.request('GET', `/api/v1/exports/${encodeURIComponent(exportId)}`);
+    }
+    /** The kind-aware catalog of export formats + their options. Requires the `editor:read` scope. */
+    async getExportFormats() {
+        return this.request('GET', '/api/v1/export-formats');
+    }
+    /**
+     * Start an export and poll until it completes. Resolves with the completed job (outputUrl set), throws
+     * `GenerationFailedError` on failure, or `GenerationTimeoutError` if it does not finish within `timeoutMs`
+     * (the server job may still complete; re-poll with getExport).
+     */
+    async exportProjectAndWait(projectId, input = {}, options = {}) {
+        const job = await this.startExport(projectId, input);
+        if (job.status === 'completed' || job.status === 'failed') {
+            if (job.status === 'failed')
+                throw new GenerationFailedError(job.exportId, job.errorMessage ?? 'Export failed');
+            return job;
+        }
+        return this.waitForExport(job.exportId, options);
+    }
+    /** Poll an export job to a terminal state. */
+    async waitForExport(exportId, options = {}) {
+        const { pollIntervalMs = 3000, timeoutMs = 600_000, signal } = options;
+        const deadline = Date.now() + timeoutMs;
+        while (true) {
+            const job = await this.getExport(exportId);
+            if (job.status === 'completed')
+                return job;
+            if (job.status === 'failed')
+                throw new GenerationFailedError(exportId, job.errorMessage ?? 'Export failed');
+            if (Date.now() >= deadline)
+                throw new GenerationTimeoutError(exportId);
+            await sleep(pollIntervalMs, signal);
+        }
+    }
+    /**
+     * The canvas layer-type catalog (types + editable props), so you know what `update_canvas` ops can
+     * create/edit. Requires the `editor:read` scope.
+     */
+    async getLayerTypes() {
+        return this.request('GET', '/api/v1/editor/layer-types');
+    }
+    /**
+     * The editor timeline clip + track-type catalog (types + editable props), so you know what
+     * `update_timeline` ops can create/edit. Requires the `editor:read` scope.
+     */
+    async getTimelineTypes() {
+        return this.request('GET', '/api/v1/editor/timeline-types');
+    }
+    /**
+     * Read an editor project's transcript mapped to its timeline clips. Returns one segment per transcribable
+     * primary-track clip, in timeline order, carrying the words spoken within it plus its current enabled/disabled
+     * state, so you can read what is said, see which parts are already cut, and target exact clipIds with
+     * update_timeline (disable_ranges / set_disabled / delete_ranges). Scope with `search` (substring) or
+     * `startMs`/`endMs` (source-media time) to fetch only the part you need. Pass `granularity: 'word'` for
+     * word-level timing (with absolute timeline frames), per-word confidence + speaker, derived silence gaps, and
+     * non-speech audio events. `paceThresholdMs` (minimum pause to report as silence) and `paddingStartMs` /
+     * `paddingEndMs` (breathing room kept around speech; negative tightens) tune the silence detection and default
+     * to the project's saved pace/padding. Requires the `editor:read` scope.
+     */
+    async getTranscript(projectId, options = {}) {
+        const params = new URLSearchParams({ projectId });
+        if (options.search)
+            params.set('search', options.search);
+        if (options.startMs !== undefined)
+            params.set('startMs', String(options.startMs));
+        if (options.endMs !== undefined)
+            params.set('endMs', String(options.endMs));
+        if (options.granularity)
+            params.set('granularity', options.granularity);
+        if (options.paceThresholdMs !== undefined)
+            params.set('paceThresholdMs', String(options.paceThresholdMs));
+        if (options.paddingStartMs !== undefined)
+            params.set('paddingStartMs', String(options.paddingStartMs));
+        if (options.paddingEndMs !== undefined)
+            params.set('paddingEndMs', String(options.paddingEndMs));
+        return this.request('GET', `/api/v1/editor/transcript?${params.toString()}`);
+    }
     /** Issue an authenticated request and map non-2xx responses to typed errors. */
     async request(method, path, body) {
         const headers = {
@@ -553,6 +1031,14 @@ export class ContentHero {
         };
         if (body !== undefined)
             headers['Content-Type'] = 'application/json';
+        // Release tracking (NOT a presence ping): presence is lit server-side, but the CLI still needs to clear its
+        // badge promptly on exit, so record any project this client mutates by id. Local only, no extra request; the
+        // activity endpoint manages its own lease and is skipped.
+        if (body && typeof body === 'object' && !Array.isArray(body) && path !== '/api/v1/editor/activity') {
+            const pid = body.projectId;
+            if (typeof pid === 'string' && pid)
+                this.activityPingedAt.set(pid, Date.now());
+        }
         const response = await this.fetchImpl(`${this.baseUrl}${path}`, {
             method,
             headers,