@scenerok/cli 2.7.0 → 2.9.0

package/dist/commands/plugin.d.ts

@@ -5,6 +5,13 @@
  *   validate run the *server's* static checks locally (no network, no auth)
  *   publish  validate, build the canonical tarball, upload, queue a build
  *   status   show one build's stage, checks and resulting version
+ *   search / show / run   the marketplace surface
+ *   vidscript            print or save a run's filled VidScript (#136)
+ *   draft / render-draft paid drafts: script + preview first, render later (#194)
+ *
+ * The agent edit loop: `plugin run … --out promo.vid` → edit `promo.vid` (your
+ * coding agent can do this) → `scenerok render promo.vid`. `plugin vidscript
+ * <runId>` reads the same script back later through `GET /api/plugins/runs/[id]`.
  *
  * `validate` and `publish` share `src/lib/plugins/cli-checks-entry.ts` with the
  * server and the `plugin-builder` service, bundled into the CLI at build time
@@ -78,12 +85,45 @@ export interface PluginRunOptions {
     set?: string[];
     maxTokens?: string | number;
     dryRun?: boolean;
+    /** Write the filled VidScript here so it can be edited and re-rendered. */
+    out?: string;
+    json?: boolean;
+    write?: Write;
+}
+export interface PluginVidscriptOptions {
+    runId: string;
+    /** Write the script to this file instead of stdout. */
+    out?: string;
+    json?: boolean;
+    write?: Write;
+}
+export interface PluginDraftOptions {
+    ref: string;
+    input?: string;
+    set?: string[];
+    maxTokens?: string | number;
+    /** Client retry key: a retried draft with the same key is free. */
+    idempotencyKey?: string;
+    /** Save the filled VidScript here so it can be edited before rendering. */
+    out?: string;
+    json?: boolean;
+    write?: Write;
+}
+export interface PluginRenderDraftOptions {
+    draftId: string;
+    /** Render this edited script instead of the one the draft produced. */
+    vidscript?: string;
     json?: boolean;
     write?: Write;
 }
 export declare function runPluginSearch(options?: PluginSearchOptions): Promise<number>;
 export declare function runPluginShow(options: PluginShowOptions): Promise<number>;
 export declare function runPluginRunCommand(options: PluginRunOptions): Promise<number>;
+export declare function runPluginVidscriptCommand(options: PluginVidscriptOptions): Promise<number>;
+/** `scenerok plugin draft` — run the plugin, pay for the script, render later. */
+export declare function runPluginDraftCommand(options: PluginDraftOptions): Promise<number>;
+/** `scenerok plugin render-draft` — render seconds only; the fee is already paid. */
+export declare function runPluginRenderDraftCommand(options: PluginRenderDraftOptions): Promise<number>;
 export declare const pluginCommand: Command;
 export {};
 //# sourceMappingURL=plugin.d.ts.map

package/dist/commands/plugin.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"plugin.d.ts","sourceRoot":"","sources":["../../src/commands/plugin.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"plugin.d.ts","sourceRoot":"","sources":["../../src/commands/plugin.ts"],"names":[],"mappings":"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"}

package/dist/commands/plugin.js

@@ -5,6 +5,13 @@
  *   validate run the *server's* static checks locally (no network, no auth)
  *   publish  validate, build the canonical tarball, upload, queue a build
  *   status   show one build's stage, checks and resulting version
+ *   search / show / run   the marketplace surface
+ *   vidscript            print or save a run's filled VidScript (#136)
+ *   draft / render-draft paid drafts: script + preview first, render later (#194)
+ *
+ * The agent edit loop: `plugin run … --out promo.vid` → edit `promo.vid` (your
+ * coding agent can do this) → `scenerok render promo.vid`. `plugin vidscript
+ * <runId>` reads the same script back later through `GET /api/plugins/runs/[id]`.
  *
  * `validate` and `publish` share `src/lib/plugins/cli-checks-entry.ts` with the
  * server and the `plugin-builder` service, bundled into the CLI at build time
@@ -18,7 +25,7 @@ import chalk from 'chalk';
 import ora from 'ora';
 import { existsSync, mkdirSync, readFileSync, readdirSync, statSync, writeFileSync } from 'node:fs';
 import { dirname, join, resolve } from 'node:path';
-import { getPlugin, getPluginBuild, runPlugin, searchPlugins, publishPluginPackage, } from '../lib/api.js';
+import { ApiError, draftPlugin, getPlugin, getPluginBuild, getPluginRun, renderPluginDraft, runPlugin, searchPlugins, publishPluginPackage, } from '../lib/api.js';
 import { getBaseUrl, isAuthenticated } from '../lib/config.js';
 import { formatApiErrorMessage } from '../lib/format-api-error.js';
 import { logError } from '../lib/logger.js';
@@ -155,6 +162,7 @@ export async function runPluginValidate(options = {}) {
         write('');
     }
     write(chalk.dim(`  ${read.files.size} files · ${formatBytes(read.bytes)} · ${elapsedMs} ms · local checks`));
+    write(chalk.dim('  Source-only: SceneRok builds every build.json entry itself and serves only those artifacts, by hash.'));
     write('');
     return report.ok ? EXIT_OK : EXIT_FAILED;
 }
@@ -211,6 +219,7 @@ export async function runPluginPublish(options = {}) {
     }
     write(chalk.green(`  ✔ Local checks passed`) +
         chalk.dim(` (${Date.now() - validateStarted} ms · ${read.files.size} files · ${formatBytes(read.bytes)})`));
+    write(chalk.dim('  Source-only: uploading source and build.json; SceneRok builds it twice and serves the built artifacts by hash.'));
     // 2. Canonical tarball + content hash (the server recomputes it).
     const checks = await loadPluginChecks();
     const tarball = checks.buildCanonicalTarGz(read.files);
@@ -500,6 +509,20 @@ function printPluginRunResult(result, write) {
             write(`Download: ${result.render.downloadUrl}`);
         write(chalk.dim(`Next: scenerok status ${result.render.renderId}`));
     }
+    if (result.runId && result.vidscript) {
+        write('');
+        write(chalk.cyan('  Edit this video:'));
+        write(`    scenerok plugin vidscript ${result.runId} --out promo.vid`);
+        write(chalk.dim('    # then change the script and render the edited copy'));
+        write('    scenerok render promo.vid --watch');
+    }
+}
+/** Save a filled VidScript so it can be edited and re-rendered. Returns the absolute path. */
+function saveVidscript(path, vidscript) {
+    const absolute = resolve(path);
+    mkdirSync(dirname(absolute), { recursive: true });
+    writeFileSync(absolute, vidscript, 'utf-8');
+    return absolute;
 }
 export async function runPluginSearch(options = {}) {
     const write = options.write ?? ((line) => console.log(line));
@@ -563,6 +586,30 @@ export async function runPluginRunCommand(options) {
             maxTokens,
             dryRun: options.dryRun,
         });
+        if (options.out) {
+            if (!result.vidscript) {
+                write(chalk.red(result.dryRun
+                    ? 'Error: a dry run creates no render, so there is no VidScript to save. Drop --dry-run.'
+                    : 'Error: this run returned no VidScript to save.'));
+                write('');
+                return EXIT_FAILED;
+            }
+            const saved = saveVidscript(options.out, result.vidscript);
+            if (options.json) {
+                write(JSON.stringify({ ...result, vidscriptPath: saved }, null, 2));
+            }
+            else {
+                write('');
+                write(chalk.green('✔ Saved VidScript') + chalk.dim(` (${result.ref.raw})`));
+                write(chalk.dim(`  ${saved}`));
+                write('');
+                write(chalk.cyan('  Next:'));
+                write(chalk.dim(`    # edit ${options.out} — ask your coding agent, or open it yourself`));
+                write(`    scenerok render ${options.out} --watch`);
+                write('');
+            }
+            return EXIT_OK;
+        }
         if (options.json)
             write(JSON.stringify(result, null, 2));
         else
@@ -576,6 +623,223 @@ export async function runPluginRunCommand(options) {
     }
 }
 // ---------------------------------------------------------------------------
+// vidscript — read back the filled script of a finished run
+// ---------------------------------------------------------------------------
+export async function runPluginVidscriptCommand(options) {
+    const write = options.write ?? ((line) => console.log(line));
+    if (!isAuthenticated()) {
+        write(chalk.yellow('Not authenticated'));
+        write(chalk.dim('Run: scenerok auth login'));
+        return EXIT_USAGE;
+    }
+    const runId = (options.runId ?? '').trim();
+    if (!runId) {
+        return fail(write, 'missing run id. Usage: scenerok plugin vidscript <runId> [--out <file.vid>]');
+    }
+    try {
+        const view = await getPluginRun(runId);
+        if (options.json) {
+            const saved = options.out && view.vidscript ? saveVidscript(options.out, view.vidscript) : null;
+            write(JSON.stringify(saved ? { ...view, vidscriptPath: saved } : view, null, 2));
+            return view.vidscript ? EXIT_OK : EXIT_FAILED;
+        }
+        if (!view.vidscript) {
+            write(chalk.yellow(`  Run ${view.run.id} has no VidScript yet (${view.run.status}).`));
+            write(chalk.dim('  The script is stored once the run has created a render.'));
+            write('');
+            return EXIT_FAILED;
+        }
+        if (options.out) {
+            const saved = saveVidscript(options.out, view.vidscript);
+            write(chalk.green('✔ Saved VidScript') + chalk.dim(` (${view.run.ref.ref})`));
+            write(chalk.dim(`  ${saved}`));
+            if (view.render)
+                write(chalk.dim(`  Original render: ${view.render.renderUrl}`));
+            write('');
+            write(chalk.cyan('  Next:'));
+            write(chalk.dim(`    # edit ${options.out} — ask your coding agent, or open it yourself`));
+            write(`    scenerok render ${options.out} --watch`);
+            write('');
+            return EXIT_OK;
+        }
+        // Raw script on stdout, so it can be piped or pasted into an agent.
+        write(view.vidscript);
+        return EXIT_OK;
+    }
+    catch (error) {
+        write(chalk.red(`  ${formatApiErrorMessage(error)}`));
+        write('');
+        return EXIT_FAILED;
+    }
+}
+// ---------------------------------------------------------------------------
+// draft / render-draft — paid drafts (#194)
+// ---------------------------------------------------------------------------
+function printDraftResult(result, write) {
+    const { estimate } = result;
+    write(chalk.green(`Draft ${result.draftId}`) +
+        chalk.dim(` · ${result.ref.raw}${result.duplicate ? ' · replayed (not charged)' : ''}`));
+    write('');
+    write(`  ${chalk.bold('Charged now')}  ${estimate.draft.totalTokens} tokens`);
+    write(chalk.dim(`    providers ${estimate.draft.providerTokens} · plugin fee ${estimate.draft.pluginFeeTokens}`));
+    write(`  ${chalk.bold('On render')}   ${estimate.render.renderTokens} tokens`);
+    write(chalk.dim(`    about ${estimate.render.renderSeconds}s of video · no plugin fee again`));
+    write(`  ${chalk.bold('Full run')}    ${estimate.totalTokens} tokens`);
+    write('');
+    const { summary } = result.preview;
+    write(chalk.dim(`  Preview: ${result.preview.durationSeconds}s · ${summary.clips} clip${summary.clips === 1 ? '' : 's'} · ` +
+        `${summary.textLayers} text layer${summary.textLayers === 1 ? '' : 's'} · ` +
+        `${summary.audioTracks} audio track${summary.audioTracks === 1 ? '' : 's'}`));
+    if (result.preview.warnings.length > 0) {
+        write(chalk.yellow(`  ${result.preview.warnings.slice(0, 3).join(' · ')}`));
+    }
+    write('');
+    write(chalk.cyan('  Next:'));
+    write('    # the filled VidScript is below (or save it with --out draft.vid)');
+    write(`    scenerok plugin render-draft ${result.draftId} --vidscript draft.vid`);
+    write(chalk.dim('    # or render it unchanged:'));
+    write(`    scenerok plugin render-draft ${result.draftId}`);
+    write('');
+}
+/** The plain-object view of an unknown JSON body. */
+function asRecord(value) {
+    return typeof value === 'object' && value !== null && !Array.isArray(value)
+        ? value
+        : {};
+}
+/**
+ * A **payable** draft 402 (#194): the VidScript is produced and stored, the
+ * provider calls are paid for, and only the plugin fee is outstanding. The retry
+ * must reuse the *same* key — a fresh key would pay for a second draft — so the
+ * key is printed as a ready-to-run command.
+ */
+function printPayableDraftHint(error, options, write) {
+    if (!(error instanceof ApiError))
+        return false;
+    const body = asRecord(error.responseBody);
+    const details = asRecord(body.details);
+    if (body.payable !== true && details.payable !== true)
+        return false;
+    const text = (value) => (typeof value === 'string' && value ? value : undefined);
+    const count = (value) => (typeof value === 'number' ? value : undefined);
+    const draftId = text(body.draftId) ?? text(details.draftId);
+    const key = text(body.idempotencyKey) ?? text(details.idempotencyKey) ?? options.idempotencyKey;
+    const fee = count(body.tokensRequired) ?? count(details.tokensRequired);
+    const balance = count(body.tokensAvailable) ?? count(details.tokensAvailable);
+    write(chalk.yellow('  Top up to finish this draft.'));
+    write(chalk.dim('  The VidScript is already produced and stored; only the plugin fee is left to charge.'));
+    if (draftId)
+        write(`  Draft: ${draftId}`);
+    if (fee !== undefined) {
+        write(`  Fee: ${fee} tokens${balance === undefined ? '' : chalk.dim(` (balance ${balance})`)}`);
+    }
+    if (key) {
+        write(chalk.cyan('  Then retry with the same key (it finishes this draft, it does not charge a new one):'));
+        const maxTokens = options.maxTokens === undefined ? '' : ` --max-tokens ${options.maxTokens}`;
+        write(`    scenerok plugin draft ${options.ref}${maxTokens} --idempotency-key ${key}${options.out ? ` --out ${options.out}` : ''}`);
+    }
+    write('');
+    return true;
+}
+/** `scenerok plugin draft` — run the plugin, pay for the script, render later. */
+export async function runPluginDraftCommand(options) {
+    const write = options.write ?? ((line) => console.log(line));
+    if (!isAuthenticated()) {
+        write(chalk.yellow('Not authenticated'));
+        write(chalk.dim('Run: scenerok auth login'));
+        return EXIT_USAGE;
+    }
+    try {
+        const inputs = loadRunInputs(options);
+        const maxTokens = parseMaxTokens(options.maxTokens);
+        const result = await draftPlugin({
+            ref: options.ref,
+            inputs,
+            maxTokens,
+            ...(options.idempotencyKey ? { idempotencyKey: options.idempotencyKey } : {}),
+        });
+        if (options.out) {
+            const saved = saveVidscript(options.out, result.vidscript);
+            if (options.json) {
+                write(JSON.stringify({ ...result, vidscriptPath: saved }, null, 2));
+                return EXIT_OK;
+            }
+            write('');
+            write(chalk.green('✔ Draft ready') + chalk.dim(` (${result.ref.raw})`));
+            write(chalk.dim(`  charged ${result.estimate.draft.totalTokens} tokens now · ` +
+                `${result.estimate.render.renderTokens} tokens when rendered`));
+            write('');
+            write(chalk.green('✔ Saved VidScript') + chalk.dim(` (${options.out})`));
+            write(chalk.dim(`  ${saved}`));
+            write('');
+            write(chalk.cyan('  Next:'));
+            write(chalk.dim(`    # edit ${options.out} — ask your coding agent, or open it yourself`));
+            write(`    scenerok plugin render-draft ${result.draftId} --vidscript ${options.out}`);
+            write('');
+            return EXIT_OK;
+        }
+        if (options.json) {
+            write(JSON.stringify(result, null, 2));
+            return EXIT_OK;
+        }
+        printDraftResult(result, write);
+        // The script on stdout, so it can be piped or saved.
+        write(result.vidscript);
+        return EXIT_OK;
+    }
+    catch (error) {
+        write(chalk.red(`  ${formatApiErrorMessage(error)}`));
+        write('');
+        printPayableDraftHint(error, options, write);
+        return EXIT_FAILED;
+    }
+}
+/** `scenerok plugin render-draft` — render seconds only; the fee is already paid. */
+export async function runPluginRenderDraftCommand(options) {
+    const write = options.write ?? ((line) => console.log(line));
+    if (!isAuthenticated()) {
+        write(chalk.yellow('Not authenticated'));
+        write(chalk.dim('Run: scenerok auth login'));
+        return EXIT_USAGE;
+    }
+    const draftId = (options.draftId ?? '').trim();
+    if (!draftId) {
+        return fail(write, 'missing draft id. Usage: scenerok plugin render-draft <draftId> [--vidscript edited.vid]');
+    }
+    try {
+        let vidscript;
+        if (options.vidscript) {
+            const path = resolve(options.vidscript);
+            if (!existsSync(path)) {
+                return fail(write, `--vidscript ${options.vidscript} does not exist`);
+            }
+            vidscript = readFileSync(path, 'utf-8');
+        }
+        const result = await renderPluginDraft(draftId, { vidscript });
+        if (options.json) {
+            write(JSON.stringify(result, null, 2));
+            return EXIT_OK;
+        }
+        write('');
+        write(chalk.green(`Render ${result.render.renderId}`) +
+            chalk.dim(` · ${result.render.status}${result.edited ? ' · edited script' : ''}`));
+        if (result.render.renderUrl)
+            write(`Page: ${result.render.renderUrl}`);
+        if (result.render.downloadUrl)
+            write(`Download: ${result.render.downloadUrl}`);
+        write(chalk.dim(`  render only: about ${result.estimate.renderSeconds}s · ${result.estimate.renderTokens} tokens. ` +
+            `The plugin fee (${result.feeTokens} tokens) was charged with the draft.`));
+        write('');
+        write(chalk.dim(`Next: scenerok status ${result.render.renderId}`));
+        return EXIT_OK;
+    }
+    catch (error) {
+        write(chalk.red(`  ${formatApiErrorMessage(error)}`));
+        write('');
+        return EXIT_FAILED;
+    }
+}
+// ---------------------------------------------------------------------------
 // command wiring
 // ---------------------------------------------------------------------------
 export const pluginCommand = new Command('plugin')
@@ -645,7 +909,39 @@ export const pluginCommand = new Command('plugin')
 ])
     .requiredOption('--max-tokens <n>', 'Hard token cap; refused before debit if worst-case is higher')
     .option('--dry-run', 'Return estimate and bound without creating a render')
+    .option('--out <file>', 'Save the filled VidScript so you can edit and re-render it')
     .option('--json', 'Machine-readable output')
     .action(async (ref, options) => {
     process.exitCode = await runPluginRunCommand({ ...options, ref });
+}))
+    .addCommand(new Command('draft')
+    .description('Run a plugin and pay for the filled VidScript — preview it, then render')
+    .argument('<ref>', 'Pinned plugin ref')
+    .option('--input <file>', 'JSON input object')
+    .option('--set <key=value>', 'Set or override an input value (repeatable)', (value, previous = []) => [
+    ...previous,
+    value,
+])
+    .requiredOption('--max-tokens <n>', 'Hard cap for the draft (providers + plugin fee)')
+    .option('--idempotency-key <key>', 'Retry key: the same key returns the same draft for free')
+    .option('--out <file>', 'Save the filled VidScript so you can edit it before rendering')
+    .option('--json', 'Machine-readable output')
+    .action(async (ref, options) => {
+    process.exitCode = await runPluginDraftCommand({ ...options, ref });
+}))
+    .addCommand(new Command('render-draft')
+    .description('Render a paid draft (render tokens only); optionally an edited VidScript')
+    .argument('<draftId>', 'Draft id printed by `scenerok plugin draft`')
+    .option('--vidscript <file>', 'Render this edited script instead of the draft’s own')
+    .option('--json', 'Machine-readable output')
+    .action(async (draftId, options) => {
+    process.exitCode = await runPluginRenderDraftCommand({ ...options, draftId });
+}))
+    .addCommand(new Command('vidscript')
+    .description('Print or save a run’s filled VidScript; edit it, then `scenerok render` it')
+    .argument('<runId>', 'Run id printed by `scenerok plugin run`')
+    .option('--out <file>', 'Write the script to a .vid file instead of stdout')
+    .option('--json', 'Machine-readable run detail')
+    .action(async (runId, options) => {
+    process.exitCode = await runPluginVidscriptCommand({ ...options, runId });
 }));

package/dist/lib/api.d.ts

@@ -396,6 +396,43 @@ export interface PluginRunResult {
         renderUrl?: string;
         downloadUrl?: string;
     } | null;
+    /**
+     * The filled, validated VidScript the render was created from. Save it with
+     * `--out <file.vid>`, edit it, then render the edited copy with
+     * `scenerok render <file.vid>`.
+     */
+    vidscript?: string | null;
+}
+/** `GET /api/plugins/runs/[id]` — the run detail an agent edits from. */
+export interface PluginRunDetail {
+    run: {
+        id: string;
+        status: string;
+        source: string;
+        createdAt: string;
+        ref: {
+            namespace: string;
+            slug: string;
+            version: number;
+            versionLabel: string | null;
+            ref: string;
+        };
+        estimate: unknown;
+    };
+    render: {
+        renderId: number;
+        status: string;
+        progress: number;
+        outputUrl: string | null;
+        renderUrl: string;
+        downloadUrl: string | null;
+        downloadReady: boolean;
+        error: string | null;
+        completedAt: string | null;
+    } | null;
+    /** The filled VidScript to edit and re-render; null when no render was created. */
+    vidscript: string | null;
+    inputs: Record<string, unknown>;
 }
 export declare function searchPlugins(options?: {
     q?: string;
@@ -415,4 +452,148 @@ export declare function runPlugin(options: {
     maxTokens: number;
     dryRun?: boolean;
 }): Promise<PluginRunResult>;
+/** Read one run: `{ run, render, vidscript, inputs }`, owner-scoped. */
+export declare function getPluginRun(runId: string): Promise<PluginRunDetail>;
+/**
+ * A draft's estimate splits the full run cost into the part charged when the
+ * draft is produced (providers + plugin fee) and the part charged later, when
+ * it is rendered (render seconds only).
+ */
+export interface PluginDraftEstimate {
+    draft: {
+        providerTokens: number;
+        pluginFeeTokens: number;
+        totalTokens: number;
+    };
+    render: {
+        renderSeconds: number;
+        renderSecondsSource: string;
+        renderTokens: number;
+        totalTokens: number;
+    };
+    totalTokens: number;
+    worstCase: {
+        draftTokens: number;
+        renderTokens: number;
+        totalTokens: number;
+    };
+    providerLines: Array<{
+        route: string;
+        tokens: number;
+        priced: boolean;
+    }>;
+}
+/**
+ * Cheap preview data: the compiled IR the web preview player consumes, plus a
+ * summary. `estimated: true` means plugin return values inside `ir` came from
+ * the dry-run loader — timings and assets are real.
+ */
+export interface PluginDraftPreview {
+    ir: unknown | null;
+    durationSeconds: number;
+    width: number;
+    height: number;
+    fps: number;
+    renderSeconds: number;
+    warnings: string[];
+    summary: {
+        clips: number;
+        textLayers: number;
+        surfaces: number;
+        audioTracks: number;
+        groups: number;
+        markers: number;
+    };
+    estimated: true;
+}
+/** `POST /api/plugins/drafts` — the paid draft: script + preview, no render. */
+export interface PluginDraftResult {
+    mode: 'draft';
+    draftId: string;
+    /** pending | succeeded | failed */
+    status: string;
+    pluginVersionId: number;
+    ref: PluginRunResult['ref'];
+    /** The filled, validated VidScript — the edit surface. */
+    vidscript: string;
+    preview: PluginDraftPreview;
+    inputs: Record<string, unknown>;
+    estimate: PluginDraftEstimate;
+    chargedProviderTokens: number;
+    feeTokens: number;
+    duplicate: boolean;
+    next: {
+        render: string;
+        detail: string;
+    };
+}
+export interface PluginDraftRenderView {
+    renderId: number;
+    status: string;
+    progress: number;
+    outputUrl: string | null;
+    renderUrl: string;
+    downloadUrl: string | null;
+    downloadReady: boolean;
+    error: string | null;
+    completedAt: string | null;
+}
+/** `GET /api/plugins/drafts/[id]` — owner-scoped draft detail. */
+export interface PluginDraftDetail {
+    draft: {
+        id: string;
+        status: string;
+        source: string;
+        createdAt: string;
+        ref: {
+            namespace: string;
+            slug: string;
+            version: number;
+            versionLabel: string | null;
+            ref: string;
+            pluginVersionId: number;
+        };
+        estimate: unknown;
+        chargedProviderTokens: number;
+        feeTokens: number;
+        error: unknown;
+    };
+    /** The filled script; null until the draft succeeded. */
+    vidscript: string | null;
+    preview: PluginDraftPreview | null;
+    inputs: Record<string, unknown>;
+    renders: PluginDraftRenderView[];
+}
+/** `POST /api/plugins/drafts/[id]/render` — render seconds only, no fee. */
+export interface PluginDraftRenderResult {
+    mode: 'draft';
+    draftId: string;
+    pluginVersionId: number;
+    ref: string;
+    render: {
+        renderId: number;
+        status: string;
+        resolution?: string;
+        renderUrl?: string;
+        downloadUrl?: string;
+    };
+    vidscript: string;
+    edited: boolean;
+    estimate: {
+        renderSeconds: number;
+        renderTokens: number;
+    };
+    feeTokens: number;
+    feeChargedWithDraft: true;
+}
+export declare function draftPlugin(options: {
+    ref: string;
+    inputs: Record<string, unknown>;
+    maxTokens: number;
+    idempotencyKey?: string;
+}): Promise<PluginDraftResult>;
+export declare function getPluginDraft(draftId: string): Promise<PluginDraftDetail>;
+export declare function renderPluginDraft(draftId: string, options?: {
+    vidscript?: string;
+}): Promise<PluginDraftRenderResult>;
 //# sourceMappingURL=api.d.ts.map