@appeeky/spec 0.0.0-stage → 0.2.0

package/dist/text.js

@@ -0,0 +1,55 @@
+/** Text helpers shared by the lint rules and the coverage report. */
+const encoder = new TextEncoder();
+/** UTF-8 byte length: the unit Apple uses for the 100-byte keyword field. */
+export function byteLength(value) {
+    return encoder.encode(value).length;
+}
+/** Character count as the stores count it (user-perceived characters, not UTF-16 units). */
+export function charLength(value) {
+    return [...value].length;
+}
+export function normalize(value) {
+    return value.normalize("NFKC").toLocaleLowerCase();
+}
+/** Lowercased words; punctuation and symbols split words, apostrophes inside a word are kept. */
+export function words(value) {
+    if (!value)
+        return [];
+    return (normalize(value)
+        .replace(/[’']/g, "'")
+        .match(/[\p{L}\p{N}]+(?:'[\p{L}\p{N}]+)*/gu) ?? []);
+}
+/** Entries of an App Store keyword field, as written (trimmed, empty ones dropped). */
+export function keywordEntries(field) {
+    if (!field)
+        return [];
+    return field
+        .split(",")
+        .map((s) => s.trim())
+        .filter(Boolean);
+}
+/** Naive English singular form, only used to flag likely plural pairs. */
+export function singular(word) {
+    if (word.length > 4 && word.endsWith("ies"))
+        return `${word.slice(0, -3)}y`;
+    if (word.length > 3 && word.endsWith("es") && /(s|x|z|ch|sh)es$/.test(word))
+        return word.slice(0, -2);
+    if (word.length > 3 && word.endsWith("s") && !word.endsWith("ss"))
+        return word.slice(0, -1);
+    return word;
+}
+export function isEnglish(locale) {
+    return locale.toLowerCase().startsWith("en");
+}
+export function unique(items) {
+    return [...new Set(items)];
+}
+/** Short English words that do not decide a search; ignored when a phrase has other words. */
+export const STOPWORDS = new Set(["a", "an", "the", "and", "or", "for", "to", "of", "in", "on", "with", "my", "your", "by", "at", "app", "apps"]);
+/** Words of a target that matter for coverage: stopwords drop out unless they are all there is. */
+export function keyWords(value) {
+    const all = words(value);
+    const kept = all.filter((w) => !STOPWORDS.has(w));
+    return kept.length > 0 ? kept : all;
+}
+//# sourceMappingURL=text.js.map

package/dist/transport.d.ts

@@ -0,0 +1,99 @@
+import type { StoreId, TransportMode } from "./schema.js";
+/**
+ * Both store CLIs expose the same named operations locally (`appstore ops call`,
+ * `gps call`) and on Appeeky's hosted gateways (`POST /v1/ops/<name>`), so a
+ * store adapter only needs `call(op, args)`.
+ */
+export interface OpsTransport {
+    readonly kind: "local" | "hosted";
+    readonly label: string;
+    call<T = unknown>(op: string, args: Record<string, unknown>, options?: {
+        write?: boolean;
+    }): Promise<T>;
+}
+export declare class TransportError extends Error {
+    readonly op?: string | undefined;
+    constructor(message: string, op?: string | undefined);
+}
+interface StoreCli {
+    bin: string;
+    npmPackage: string;
+    /** argv before the op name, e.g. `ops call` vs `call`. */
+    callArgs: string[];
+    /** Flag that picks a named account or profile. */
+    accountFlag: string;
+    hostedUrl: string;
+    writeHeader: string;
+    setupHint: string;
+}
+export declare const STORE_CLIS: Record<StoreId, StoreCli>;
+export declare function onPath(bin: string, env?: NodeJS.ProcessEnv): boolean;
+export type Runner = (command: string, args: string[], env?: Record<string, string>) => Promise<{
+    code: number;
+    stdout: string;
+    stderr: string;
+}>;
+export declare const defaultRunner: Runner;
+export interface LocalCliOptions {
+    /** Named account (`appstore --account`) or profile (`gps --profile`). */
+    account?: string;
+    /** Run the CLI through `npx` when it is not installed. */
+    useNpx?: boolean;
+    /**
+     * Run a specific executable instead of the CLI on PATH, e.g. an app that
+     * bundles the store CLI: `{ file: process.execPath, args: ["/path/to/bin.js"] }`.
+     */
+    command?: {
+        file: string;
+        args: string[];
+    };
+    /**
+     * Extra environment for the CLI, e.g. credentials:
+     * `ASC_KEY_ID`, `ASC_ISSUER_ID`, `ASC_PRIVATE_KEY` or `GPS_CREDENTIALS` (inline JSON).
+     */
+    env?: Record<string, string>;
+    label?: string;
+    runner?: Runner;
+}
+/** Runs operations through the store CLI on this machine, with the user's own key. */
+export declare class LocalCliTransport implements OpsTransport {
+    private readonly store;
+    private readonly options;
+    readonly kind: "local";
+    readonly label: string;
+    constructor(store: StoreId, options?: LocalCliOptions);
+    call<T>(op: string, args: Record<string, unknown>, options?: {
+        write?: boolean;
+    }): Promise<T>;
+}
+export type Fetcher = typeof fetch;
+/** Runs operations on Appeeky's hosted gateway with an Appeeky API key; the store key never leaves Appeeky. */
+export declare class HostedTransport implements OpsTransport {
+    private readonly store;
+    private readonly apiKey;
+    private readonly options;
+    readonly kind: "hosted";
+    readonly label: string;
+    constructor(store: StoreId, apiKey: string, options?: {
+        baseUrl?: string;
+        fetcher?: Fetcher;
+    });
+    call<T>(op: string, args: Record<string, unknown>, options?: {
+        write?: boolean;
+    }): Promise<T>;
+}
+export interface TransportOptions {
+    via: TransportMode;
+    account?: string;
+    apiKey?: string;
+    env?: NodeJS.ProcessEnv;
+    runner?: Runner;
+    fetcher?: Fetcher;
+}
+/**
+ * `auto` prefers the local CLI when it is installed (your key, nothing leaves
+ * your machine), then the hosted gateway when an Appeeky API key is set, and
+ * finally the CLI through npx.
+ */
+export declare function createTransport(store: StoreId, options: TransportOptions): OpsTransport;
+export {};

package/dist/transport.js

@@ -0,0 +1,170 @@
+import { spawn } from "node:child_process";
+import { delimiter, join } from "node:path";
+import { existsSync } from "node:fs";
+export class TransportError extends Error {
+    op;
+    constructor(message, op) {
+        super(message);
+        this.op = op;
+        this.name = "TransportError";
+    }
+}
+export const STORE_CLIS = {
+    "app-store": {
+        bin: "appstore",
+        npmPackage: "@appeeky/app-store-connect-cli",
+        callArgs: ["ops", "call"],
+        accountFlag: "--account",
+        hostedUrl: "https://asc-api.appeeky.com",
+        writeHeader: "X-ASC-Allow-Writes",
+        setupHint: "Save your App Store Connect API key once with the App Store Connect CLI: `npx -p @appeeky/app-store-connect-cli appstore accounts add my-team --key-id … --issuer-id … --private-key-path AuthKey.p8 --default` (github.com/appeeky/app-store-connect-cli). Or set APPEEKY_API_KEY to use your connection in Appeeky.",
+    },
+    "google-play": {
+        bin: "gps",
+        npmPackage: "@appeeky/google-play-store-cli",
+        callArgs: ["call"],
+        accountFlag: "--account",
+        hostedUrl: "https://gps-api.appeeky.com",
+        writeHeader: "X-GPS-Allow-Writes",
+        setupHint: "Save your Google Play service account once with the Google Play CLI: `npx -p @appeeky/google-play-store-cli gps accounts add my-co --credentials service-account.json --default` (github.com/appeeky/google-play-console-cli). Or set APPEEKY_API_KEY to use your connection in Appeeky.",
+    },
+};
+export function onPath(bin, env = process.env) {
+    const exts = process.platform === "win32" ? (env.PATHEXT ?? ".EXE;.CMD").split(";") : [""];
+    for (const dir of (env.PATH ?? "").split(delimiter)) {
+        if (!dir)
+            continue;
+        for (const ext of exts)
+            if (existsSync(join(dir, bin + ext)))
+                return true;
+    }
+    return false;
+}
+export const defaultRunner = (command, args, env) => new Promise((resolve, reject) => {
+    const child = spawn(command, args, {
+        stdio: ["ignore", "pipe", "pipe"],
+        shell: process.platform === "win32",
+        env: env ? { ...process.env, ...env } : process.env,
+    });
+    let stdout = "";
+    let stderr = "";
+    child.stdout.on("data", (d) => (stdout += d));
+    child.stderr.on("data", (d) => (stderr += d));
+    child.on("error", reject);
+    child.on("close", (code) => resolve({ code: code ?? 1, stdout, stderr }));
+});
+/** Runs operations through the store CLI on this machine, with the user's own key. */
+export class LocalCliTransport {
+    store;
+    options;
+    kind = "local";
+    label;
+    constructor(store, options = {}) {
+        this.store = store;
+        this.options = options;
+        const cli = STORE_CLIS[store];
+        this.label = options.label ?? (options.useNpx ? `npx ${cli.npmPackage}` : `local ${cli.bin} CLI`);
+    }
+    async call(op, args, options = {}) {
+        const cli = STORE_CLIS[this.store];
+        const argv = ["--json"];
+        if (this.options.account)
+            argv.push(cli.accountFlag, this.options.account);
+        if (options.write)
+            argv.push("--confirm");
+        argv.push(...cli.callArgs, op, JSON.stringify(args));
+        const [command, full] = this.options.command
+            ? [this.options.command.file, [...this.options.command.args, ...argv]]
+            : this.options.useNpx
+                ? ["npx", ["-y", "-p", cli.npmPackage, cli.bin, ...argv]]
+                : [cli.bin, argv];
+        const run = this.options.runner ?? defaultRunner;
+        let result;
+        try {
+            result = await run(command, full, this.options.env);
+        }
+        catch (err) {
+            throw new TransportError(`Could not start ${command}: ${err.message}. ${cli.setupHint}`, op);
+        }
+        if (result.code !== 0) {
+            const detail = (result.stderr || result.stdout).trim().split("\n").slice(-3).join(" ");
+            throw new TransportError(`${cli.bin} ${op} failed: ${detail || `exit ${result.code}`}`, op);
+        }
+        const text = result.stdout.trim();
+        if (!text)
+            return undefined;
+        try {
+            return JSON.parse(text);
+        }
+        catch {
+            throw new TransportError(`${cli.bin} ${op} returned output that is not JSON: ${text.slice(0, 200)}`, op);
+        }
+    }
+}
+/** Runs operations on Appeeky's hosted gateway with an Appeeky API key; the store key never leaves Appeeky. */
+export class HostedTransport {
+    store;
+    apiKey;
+    options;
+    kind = "hosted";
+    label;
+    constructor(store, apiKey, options = {}) {
+        this.store = store;
+        this.apiKey = apiKey;
+        this.options = options;
+        this.label = `hosted ${new URL(options.baseUrl ?? STORE_CLIS[store].hostedUrl).host}`;
+    }
+    async call(op, args, options = {}) {
+        const cli = STORE_CLIS[this.store];
+        const base = (this.options.baseUrl ?? cli.hostedUrl).replace(/\/$/, "");
+        const headers = {
+            Authorization: `Bearer ${this.apiKey}`,
+            "Content-Type": "application/json",
+            "User-Agent": "appeeky-spec",
+        };
+        if (options.write)
+            headers[cli.writeHeader] = "true";
+        const doFetch = this.options.fetcher ?? fetch;
+        let res;
+        try {
+            res = await doFetch(`${base}/v1/ops/${op}`, { method: "POST", headers, body: JSON.stringify(args) });
+        }
+        catch (err) {
+            throw new TransportError(`Could not reach ${base}: ${err.message}`, op);
+        }
+        const body = (await res.json().catch(() => null));
+        if (!res.ok) {
+            const message = body?.error?.message ?? `HTTP ${res.status}`;
+            throw new TransportError(`${op} failed on ${new URL(base).host}: ${message}`, op);
+        }
+        return body?.data;
+    }
+}
+/**
+ * `auto` prefers the local CLI when it is installed (your key, nothing leaves
+ * your machine), then the hosted gateway when an Appeeky API key is set, and
+ * finally the CLI through npx.
+ */
+export function createTransport(store, options) {
+    const env = options.env ?? process.env;
+    const apiKey = options.apiKey ?? env.APPEEKY_API_KEY;
+    const cli = STORE_CLIS[store];
+    const local = (useNpx) => new LocalCliTransport(store, { account: options.account, useNpx, runner: options.runner });
+    const hostedBase = store === "app-store" ? env.APPEEKY_ASC_URL : env.APPEEKY_GPS_URL;
+    const hosted = (key) => new HostedTransport(store, key, { baseUrl: hostedBase, fetcher: options.fetcher });
+    switch (options.via) {
+        case "local":
+            return local(!onPath(cli.bin, env));
+        case "hosted":
+            if (!apiKey)
+                throw new TransportError(`Set APPEEKY_API_KEY to use the hosted ${store} gateway.`);
+            return hosted(apiKey);
+        case "auto":
+            if (onPath(cli.bin, env))
+                return local(false);
+            if (apiKey)
+                return hosted(apiKey);
+            return local(true);
+    }
+}
+//# sourceMappingURL=transport.js.map

package/dist/ugc-core.js

@@ -0,0 +1 @@
+var r=class extends Error{constructor(o,n,i){super(o);this.code=n;this.status=i;this.name="MediaJobError"}code;status};var C=280;var v=e=>({prompt:e.prompt,duration:`${e.durationSec}s`,resolution:e.resolution,aspect_ratio:e.aspectRatio,generate_audio:e.audio,...e.negativePrompt?{negative_prompt:e.negativePrompt}:{},...e.seed!==void 0?{seed:e.seed}:{}}),p=(e,t,o=1)=>Array.from({length:Math.floor((t-e)/o)+1},(n,i)=>e+i*o),s=e=>({silent:e,audio:e}),l=e=>({prompt:e.prompt,image_url:e.imageUrl,duration:String(e.durationSec)}),y=(e,t=!1)=>({prompt:e.prompt,...t?{image_urls:e.imageUrls??[]}:{},num_images:e.count,aspect_ratio:e.aspectRatio,output_format:"png",...e.seed!==void 0?{seed:e.seed}:{}}),Y={"9:16":"portrait_16_9","16:9":"landscape_16_9","1:1":"square_hd","4:5":"portrait_4_3"},V=(e,t=!1)=>({prompt:e.prompt,...t?{image_urls:e.imageUrls??[]}:{},num_images:e.count,image_size:Y[e.aspectRatio],...e.seed!==void 0?{seed:e.seed}:{}}),Q=[{kind:"video",id:"veo-3.1-lite",family:"Veo",nativeAudio:!0,label:"Veo 3.1 Lite",provider:"fal",endpoint:"fal-ai/veo3.1/lite/image-to-video",mode:"image-to-video",description:"Google's cheapest Veo: animates a first frame with native speech and sound.",durations:[4,6,8],resolutions:["720p","1080p"],defaultResolution:"720p",pricePerSecond:{silent:.03,audio:.05},pricePerSecondByResolution:{"1080p":{silent:.05,audio:.08}},mapInput:e=>({...v(e),image_url:e.imageUrl})},{kind:"video",id:"veo-3.1-fast",family:"Veo",nativeAudio:!0,label:"Veo 3.1 Fast",provider:"fal",endpoint:"fal-ai/veo3.1/fast/image-to-video",mode:"image-to-video",description:"Animates a first frame; native speech + lip-sync. Cheapest talking-head option.",durations:[4,6,8],resolutions:["720p","1080p"],defaultResolution:"720p",pricePerSecond:{silent:.1,audio:.15},mapInput:e=>({...v(e),image_url:e.imageUrl})},{kind:"video",id:"veo-3.1",family:"Veo",nativeAudio:!0,label:"Veo 3.1",provider:"fal",endpoint:"fal-ai/veo3.1/image-to-video",mode:"image-to-video",description:"Highest quality image-to-video with native dialogue.",durations:[4,6,8],resolutions:["720p","1080p"],defaultResolution:"720p",pricePerSecond:{silent:.2,audio:.4},mapInput:e=>({...v(e),image_url:e.imageUrl})},{kind:"video",id:"veo-3.1-reference",family:"Veo",nativeAudio:!0,label:"Veo 3.1 Reference",provider:"fal",endpoint:"fal-ai/veo3.1/reference-to-video",mode:"reference-to-video",description:"Keeps a persona consistent from reference images (face, outfit, product).",durations:[8],resolutions:["720p","1080p"],defaultResolution:"720p",pricePerSecond:{silent:.2,audio:.4},mapInput:e=>({...v(e),image_urls:e.referenceImageUrls??[]})},{kind:"video",id:"seedance-2.0",family:"Seedance",nativeAudio:!0,label:"Seedance 2.0",provider:"fal",endpoint:"bytedance/seedance-2.0/image-to-video",mode:"image-to-video",description:"ByteDance's flagship: cinematic motion with native audio, up to 15s.",durations:p(4,15),resolutions:["480p","720p","1080p"],defaultResolution:"720p",pricePerSecond:s(.3034),pricePerSecondByResolution:{"480p":s(.135),"1080p":s(.682)},mapInput:e=>({...l(e),resolution:e.resolution,aspect_ratio:e.aspectRatio,generate_audio:e.audio})},{kind:"video",id:"seedance-2.0-fast",family:"Seedance",nativeAudio:!0,label:"Seedance 2.0 Fast",provider:"fal",endpoint:"bytedance/seedance-2.0/fast/image-to-video",mode:"image-to-video",description:"Faster, cheaper Seedance 2.0 with native audio.",durations:p(4,15),resolutions:["480p","720p"],defaultResolution:"720p",pricePerSecond:s(.2419),pricePerSecondByResolution:{"480p":s(.108)},mapInput:e=>({...l(e),resolution:e.resolution,aspect_ratio:e.aspectRatio,generate_audio:e.audio})},{kind:"video",id:"seedance-2.0-mini",family:"Seedance",nativeAudio:!0,label:"Seedance 2.0 Mini",provider:"fal",endpoint:"bytedance/seedance-2.0/mini/image-to-video",mode:"image-to-video",description:"The budget Seedance 2.0, still with native audio.",durations:p(4,15),resolutions:["480p","720p"],defaultResolution:"720p",pricePerSecond:s(.1547),pricePerSecondByResolution:{"480p":s(.0721)},mapInput:e=>({...l(e),resolution:e.resolution,aspect_ratio:e.aspectRatio,generate_audio:e.audio})},{kind:"video",id:"seedance-2.5",family:"Seedance",nativeAudio:!0,label:"Seedance 2.5",provider:"fal",endpoint:"bytedance/seedance-2.5/image-to-video",mode:"image-to-video",description:"Newest Seedance: highest fidelity and up to 30s. Follows the first frame's shape.",durations:p(4,30),resolutions:["480p","720p","1080p"],defaultResolution:"720p",pricePerSecond:s(.473),pricePerSecondByResolution:{"480p":s(.2205),"1080p":s(1.164)},mapInput:e=>({...l(e),resolution:e.resolution,generate_audio:e.audio})},{kind:"video",id:"seedance-1.5-pro",family:"Seedance",nativeAudio:!0,label:"Seedance 1.5 Pro",provider:"fal",endpoint:"fal-ai/bytedance/seedance/v1.5/pro/image-to-video",mode:"image-to-video",description:"Cheap Seedance with native audio; good for quick drafts.",durations:p(4,12),resolutions:["480p","720p","1080p"],defaultResolution:"720p",pricePerSecond:{silent:.026,audio:.0519},pricePerSecondByResolution:{"480p":{silent:.0116,audio:.0231},"1080p":{silent:.0584,audio:.1167}},mapInput:e=>({...l(e),resolution:e.resolution,aspect_ratio:e.aspectRatio,generate_audio:e.audio,...e.seed!==void 0?{seed:e.seed}:{}})},{kind:"video",id:"seedance-1.0-pro-fast",family:"Seedance",nativeAudio:!1,label:"Seedance 1.0 Pro Fast",provider:"fal",endpoint:"fal-ai/bytedance/seedance/v1/pro/fast/image-to-video",mode:"image-to-video",description:"Very cheap silent motion \u2014 b-roll, product shots, ElevenLabs lip-sync bases.",durations:p(2,12),resolutions:["480p","720p","1080p"],defaultResolution:"720p",pricePerSecond:s(.0216),pricePerSecondByResolution:{"480p":s(.0096),"1080p":s(.0486)},mapInput:e=>({...l(e),resolution:e.resolution,aspect_ratio:e.aspectRatio,...e.seed!==void 0?{seed:e.seed}:{}})},{kind:"video",id:"kling-v3-pro",family:"Kling",nativeAudio:!0,label:"Kling 3.0 Pro",provider:"fal",endpoint:"fal-ai/kling-video/v3/pro/image-to-video",mode:"image-to-video",description:"Kling's best: strong motion and faces, native audio, 3\u201315s. Follows the first frame's shape.",durations:p(3,15),resolutions:["1080p"],defaultResolution:"1080p",pricePerSecond:{silent:.112,audio:.168},mapInput:e=>({prompt:e.prompt,start_image_url:e.imageUrl,duration:String(e.durationSec),generate_audio:e.audio,...e.negativePrompt?{negative_prompt:e.negativePrompt}:{}})},{kind:"video",id:"kling-v3-standard",family:"Kling",nativeAudio:!0,label:"Kling 3.0 Standard",provider:"fal",endpoint:"fal-ai/kling-video/v3/standard/image-to-video",mode:"image-to-video",description:"Cheaper Kling 3.0 with native audio.",durations:p(3,15),resolutions:["720p"],defaultResolution:"720p",pricePerSecond:{silent:.084,audio:.126},mapInput:e=>({prompt:e.prompt,start_image_url:e.imageUrl,duration:String(e.durationSec),generate_audio:e.audio,...e.negativePrompt?{negative_prompt:e.negativePrompt}:{}})},{kind:"video",id:"kling-v2.5-turbo-pro",family:"Kling",nativeAudio:!1,label:"Kling 2.5 Turbo Pro",provider:"fal",endpoint:"fal-ai/kling-video/v2.5-turbo/pro/image-to-video",mode:"image-to-video",description:"Fast, silent Kling with very good motion; 5 or 10s.",durations:[5,10],resolutions:["1080p"],defaultResolution:"1080p",pricePerSecond:s(.07),mapInput:e=>({...l(e),...e.negativePrompt?{negative_prompt:e.negativePrompt}:{}})},{kind:"video",id:"hailuo-2.3",family:"Hailuo",nativeAudio:!1,label:"Hailuo 2.3",provider:"fal",endpoint:"fal-ai/minimax/hailuo-2.3/standard/image-to-video",mode:"image-to-video",description:"MiniMax Hailuo: lively, physical motion; silent, 6 or 10s.",durations:[6,10],resolutions:["720p"],defaultResolution:"720p",pricePerSecond:s(.056),mapInput:e=>l(e)},{kind:"video",id:"wan-3.0",family:"Wan",nativeAudio:!0,label:"Wan 3.0",provider:"fal",endpoint:"alibaba/wan-3.0/image-to-video",mode:"image-to-video",description:"Alibaba Wan 3.0 with audio, 2\u201315s.",durations:p(2,15),resolutions:["480p","720p","1080p"],defaultResolution:"720p",pricePerSecond:s(.1),pricePerSecondByResolution:{"480p":s(.05),"1080p":s(.2)},mapInput:e=>({prompt:e.prompt,start_image_url:e.imageUrl,duration:e.durationSec,resolution:e.resolution,aspect_ratio:e.aspectRatio,audio:e.audio,...e.seed!==void 0?{seed:e.seed}:{}})},{kind:"video",id:"ltx-2.3-fast",family:"LTX",nativeAudio:!0,label:"LTX 2.3 Fast",provider:"fal",endpoint:"fal-ai/ltx-2.3/image-to-video/fast",mode:"image-to-video",description:"Lightricks LTX: cheap 1080p with audio, 6\u201320s.",durations:p(6,20,2),resolutions:["1080p"],defaultResolution:"1080p",pricePerSecond:s(.06),mapInput:e=>({prompt:e.prompt,image_url:e.imageUrl,duration:e.durationSec,resolution:e.resolution,aspect_ratio:e.aspectRatio,generate_audio:e.audio})},{kind:"video",id:"sora-2",family:"Sora",nativeAudio:!0,label:"Sora 2",provider:"fal",endpoint:"fal-ai/sora-2/image-to-video",mode:"image-to-video",description:"OpenAI Sora 2: natural scenes and dialogue; always renders audio.",durations:[4,8,12],resolutions:["720p"],defaultResolution:"720p",pricePerSecond:s(.1),mapInput:e=>({prompt:e.prompt,image_url:e.imageUrl,duration:e.durationSec,resolution:"720p",aspect_ratio:e.aspectRatio})},{kind:"video",id:"sora-2-pro",family:"Sora",nativeAudio:!0,label:"Sora 2 Pro",provider:"fal",endpoint:"fal-ai/sora-2/image-to-video/pro",mode:"image-to-video",description:"Higher-fidelity Sora 2, up to 1080p; always renders audio.",durations:[4,8,12],resolutions:["720p","1080p"],defaultResolution:"720p",pricePerSecond:s(.3),pricePerSecondByResolution:{"1080p":s(.5)},mapInput:e=>({prompt:e.prompt,image_url:e.imageUrl,duration:e.durationSec,resolution:e.resolution,aspect_ratio:e.aspectRatio})},{kind:"video",id:"kling-avatar-v2",family:"Kling",nativeAudio:!0,label:"Kling AI Avatar v2",provider:"fal",endpoint:"fal-ai/kling-video/ai-avatar/v2/standard",mode:"audio-to-video",description:"Animates a still from a voice track with lip-sync. Cheapest talking clip; the default for ElevenLabs voices.",durations:[],resolutions:["720p"],defaultResolution:"720p",pricePerSecond:{silent:.0562,audio:.0562},mapInput:e=>({image_url:e.imageUrl,audio_url:e.audioUrl,prompt:e.prompt||"."})},{kind:"video",id:"kling-avatar-v2-pro",family:"Kling",nativeAudio:!0,label:"Kling AI Avatar v2 Pro",provider:"fal",endpoint:"fal-ai/kling-video/ai-avatar/v2/pro",mode:"audio-to-video",description:"Higher-fidelity Kling avatar from a still and a voice track.",durations:[],resolutions:["720p"],defaultResolution:"720p",pricePerSecond:{silent:.115,audio:.115},mapInput:e=>({image_url:e.imageUrl,audio_url:e.audioUrl,prompt:e.prompt||"."})},{kind:"video",id:"omnihuman-v1.5",family:"OmniHuman",nativeAudio:!0,label:"OmniHuman 1.5",provider:"fal",endpoint:"fal-ai/bytedance/omnihuman/v1.5",mode:"audio-to-video",description:"ByteDance OmniHuman: expressive body and face motion that follows the voice.",durations:[],resolutions:["720p"],defaultResolution:"720p",pricePerSecond:{silent:.16,audio:.16},mapInput:e=>({image_url:e.imageUrl,audio_url:e.audioUrl,prompt:e.prompt,resolution:"720p"})},{kind:"video",id:"sync-lipsync-v2",family:"Sync",nativeAudio:!0,label:"Sync Lipsync 2",provider:"fal",endpoint:"fal-ai/sync-lipsync/v2",mode:"lipsync",description:"Re-times a video's mouth to a voice track ($3/min).",durations:[],resolutions:["720p"],defaultResolution:"720p",pricePerSecond:{silent:.05,audio:.05},mapInput:e=>({video_url:e.videoUrl,audio_url:e.audioUrl,model:"lipsync-2",sync_mode:"cut_off"})},{kind:"audio",id:"elevenlabs-tts",label:"ElevenLabs Multilingual v2",provider:"fal",endpoint:"fal-ai/elevenlabs/tts/multilingual-v2",mode:"tts",description:"Natural voiceover in a preset ElevenLabs voice, with word timings for captions.",pricePerKChars:.1,maxChars:2500,mapInput:e=>({text:e.text,voice:e.voice||F,...e.speed?{speed:e.speed}:{},timestamps:!0})},{kind:"audio",id:"lyria2",label:"Lyria 2",provider:"fal",endpoint:"fal-ai/lyria2",mode:"music",description:"Google Lyria 2: a 30-second instrumental bed from a prompt.",pricePerTrack:.1,fixedSeconds:30,mapInput:e=>({prompt:e.prompt,negative_prompt:"vocals, singing, low quality"})},{kind:"audio",id:"stable-audio-25",label:"Stable Audio 2.5",provider:"fal",endpoint:"fal-ai/stable-audio-25/text-to-audio",mode:"music",description:"Stability AI Stable Audio 2.5: music of a chosen length.",pricePerTrack:.2,maxSeconds:190,mapInput:e=>({prompt:e.prompt,seconds_total:e.seconds??30})},{kind:"image",id:"nano-banana",label:"Nano Banana",family:"Nano Banana",provider:"fal",endpoint:"fal-ai/nano-banana",description:"Google Gemini 2.5 Flash Image. Fast, cheap and strong at keeping a creator's face across shots.",maxImages:4,maxReferenceImages:0,pricePerImage:.039,mapInput:e=>({prompt:e.prompt,num_images:e.count,aspect_ratio:e.aspectRatio,output_format:"png",...e.seed!==void 0?{seed:e.seed}:{}}),edit:{endpoint:"fal-ai/nano-banana/edit",maxReferenceImages:6,mapInput:e=>({prompt:e.prompt,image_urls:e.imageUrls??[],num_images:e.count,aspect_ratio:e.aspectRatio,output_format:"png",...e.seed!==void 0?{seed:e.seed}:{}})}},{kind:"image",id:"nano-banana-2",label:"Nano Banana 2",family:"Nano Banana",provider:"fal",endpoint:"fal-ai/nano-banana-2",description:"Newer Gemini image model: sharper detail and text, still keeps faces consistent.",maxImages:4,maxReferenceImages:0,pricePerImage:.08,mapInput:e=>y(e),edit:{endpoint:"fal-ai/nano-banana-2/edit",maxReferenceImages:6,mapInput:e=>y(e,!0)}},{kind:"image",id:"nano-banana-pro",label:"Nano Banana Pro",family:"Nano Banana",provider:"fal",endpoint:"fal-ai/nano-banana-pro",description:"Gemini 3 Pro Image: the most realistic stills and the best text in the frame.",maxImages:4,maxReferenceImages:0,pricePerImage:.15,mapInput:e=>y(e),edit:{endpoint:"fal-ai/nano-banana-pro/edit",maxReferenceImages:6,mapInput:e=>y(e,!0)}},{kind:"image",id:"seedream-4.5",label:"Seedream 4.5",family:"Seedream",provider:"fal",endpoint:"fal-ai/bytedance/seedream/v4.5/text-to-image",description:"ByteDance Seedream: photoreal 2K stills, up to 10 references.",maxImages:4,maxReferenceImages:0,pricePerImage:.04,mapInput:e=>V(e),edit:{endpoint:"fal-ai/bytedance/seedream/v4.5/edit",maxReferenceImages:10,mapInput:e=>V(e,!0)}},{kind:"image",id:"nano-banana-edit",label:"Nano Banana",family:"Nano Banana",hidden:!0,provider:"fal",endpoint:"fal-ai/nano-banana/edit",description:"Consistent-character stills from reference images (persona looks, scenes, product shots).",maxImages:4,maxReferenceImages:6,pricePerImage:.039,mapInput:e=>({prompt:e.prompt,image_urls:e.imageUrls??[],num_images:e.count,aspect_ratio:e.aspectRatio,output_format:"png",...e.seed!==void 0?{seed:e.seed}:{}})}];var F="Rachel",Z=new Map(Q.map(e=>[e.id,e]));function u(e){return Z.get(e)}function q(){let e=Number(process.env.MEDIA_CREDIT_MARKUP);return Number.isFinite(e)&&e>=1?e:1.5}function h(e){return e<=0?0:Math.max(1,Math.ceil(e*100*q()))}function T(e,t){let o=[...e.durations].sort((n,i)=>n-i);return o.find(n=>n>=t)??o[o.length-1]}function ee(e,t){return t&&e.pricePerSecondByResolution?.[t]||e.pricePerSecond}function I(e,t){let o=ee(e,t.resolution)[t.audio&&e.nativeAudio?"audio":"silent"];return Math.round(o*t.durationSec*1e4)/1e4}function N(e,t){return Math.round(e.pricePerImage*t*1e4)/1e4}function f(e,t){let o;try{o=new URL(e)}catch{throw new r(`${t} must be a valid URL`,"INVALID_URL",400)}if(o.protocol!=="https:")throw new r(`${t} must be an https URL`,"INVALID_URL",400);let n=o.hostname.toLowerCase();if(n==="localhost"||n.endsWith(".local")||/^(10|127|169\.254|192\.168|172\.(1[6-9]|2\d|3[01]))\./.test(n))throw new r(`${t} must be a public URL`,"INVALID_URL",400)}function $(e){let t=u(e.modelId);if(!t||t.kind!=="video")throw new r(`Unknown video model "${e.modelId}"`,"INVALID_MODEL",400);if(t.mode==="audio-to-video"||t.mode==="lipsync")return te(t,e);let o=e.prompt?.trim();if(!o)throw new r("prompt is required","MISSING_PROMPT",400);if(o.length>4e3)throw new r("prompt is too long (max 4000 chars)","PROMPT_TOO_LONG",400);let n=e.durationSec??t.durations[t.durations.length-1];if(!t.durations.includes(n))throw new r(`${t.label} takes ${t.durations.join(", ")} second clips`,"INVALID_DURATION",400);let i=e.resolution??t.defaultResolution;if(!t.resolutions.includes(i))throw new r(`${t.label} renders ${t.resolutions.join(", ")}`,"INVALID_RESOLUTION",400);let a=e.aspectRatio??"9:16";if(a!=="9:16"&&a!=="16:9")throw new r("aspectRatio must be 9:16 or 16:9","INVALID_ASPECT_RATIO",400);if(t.mode==="image-to-video"){if(!e.imageUrl)throw new r("imageUrl is required for this model","MISSING_IMAGE",400);f(e.imageUrl,"imageUrl")}else{let g=e.referenceImageUrls??[];if(g.length<1||g.length>3)throw new r("referenceImageUrls needs 1\u20133 images","INVALID_REFERENCES",400);g.forEach((A,U)=>f(A,`referenceImageUrls[${U}]`))}let d={prompt:o,imageUrl:e.imageUrl,referenceImageUrls:e.referenceImageUrls,durationSec:n,resolution:i,aspectRatio:a,audio:t.nativeAudio?e.audio??!0:!1,negativePrompt:e.negativePrompt?.trim()||void 0,seed:e.seed},b=I(t,d);return{kind:"video",model:t,request:d,costUsd:b,credits:h(b)}}function te(e,t){if(!t.audioUrl)throw new r("audioUrl is required for this model","MISSING_AUDIO",400);if(f(t.audioUrl,"audioUrl"),e.mode==="audio-to-video"){if(!t.imageUrl)throw new r("imageUrl is required for this model","MISSING_IMAGE",400);f(t.imageUrl,"imageUrl")}else{if(!t.videoUrl)throw new r("videoUrl is required for lip-sync","MISSING_VIDEO",400);f(t.videoUrl,"videoUrl")}let o=Math.ceil(t.durationSec??8);if(!Number.isFinite(o)||o<1||o>45)throw new r(`Speech must be 1\u2013${45} seconds`,"INVALID_DURATION",400);let n={prompt:(t.prompt??"").trim().slice(0,2e3),imageUrl:t.imageUrl,audioUrl:t.audioUrl,videoUrl:t.videoUrl,durationSec:o,resolution:e.defaultResolution,aspectRatio:t.aspectRatio==="16:9"?"16:9":"9:16",audio:!0},i=I(e,{durationSec:o,audio:!0});return{kind:"video",model:e,request:n,costUsd:i,credits:h(i)}}function oe(e,t){if(!t||!e.edit)return e;let{edit:o}=e;return{...e,endpoint:o.endpoint,maxReferenceImages:o.maxReferenceImages,pricePerImage:o.pricePerImage??e.pricePerImage,mapInput:o.mapInput}}function G(e){let t=u(e.modelId);if(!t||t.kind!=="image")throw new r(`Unknown image model "${e.modelId}"`,"INVALID_MODEL",400);if((e.imageUrls?.length??0)>0&&!t.edit&&t.maxReferenceImages===0)throw new r(`${t.label} can't use reference photos \u2014 pick a model that edits from references`,"INVALID_REFERENCES",400);let o=oe(t,(e.imageUrls?.length??0)>0),n=e.prompt?.trim();if(!n)throw new r("prompt is required","MISSING_PROMPT",400);let i=e.count??1;if(!Number.isInteger(i)||i<1||i>o.maxImages)throw new r(`count must be 1\u2013${o.maxImages}`,"INVALID_COUNT",400);let a=e.imageUrls??[];if(o.maxReferenceImages>0&&a.length<1)throw new r("imageUrls needs at least one reference image","MISSING_IMAGE",400);if(a.length>o.maxReferenceImages)throw new r(`imageUrls allows up to ${o.maxReferenceImages} images`,"INVALID_REFERENCES",400);a.forEach((A,U)=>f(A,`imageUrls[${U}]`));let d=e.aspectRatio??"9:16";if(!["9:16","16:9","1:1","4:5"].includes(d))throw new r("aspectRatio must be 9:16, 16:9, 1:1 or 4:5","INVALID_ASPECT_RATIO",400);let b={prompt:n,imageUrls:a,count:i,aspectRatio:d,seed:e.seed},g=N(o,i);return{kind:"image",model:o,request:b,costUsd:g,credits:h(g)}}var ne="https://queue.fal.run",m=class extends Error{constructor(o,n,i){super(o);this.status=n;this.retryable=i;this.name="FalError"}status;retryable};function ie(e){let t=(typeof e=="function"?e():e)?.trim();if(!t)throw new m("fal API key is not configured",500,!1);return t}async function w(e,t,o={}){let n=await fetch(t,{...o,headers:{Authorization:`Key ${ie(e)}`,"Content-Type":"application/json",...o.headers??{}},signal:AbortSignal.timeout(3e4)}),i=await n.text(),a=null;try{a=i?JSON.parse(i):null}catch{a=i}if(!n.ok){let d=(a&&typeof a=="object"&&"detail"in a?JSON.stringify(a.detail):typeof a=="string"?a:JSON.stringify(a))??"";throw new m(`fal ${n.status}: ${d.slice(0,300)}`,n.status,n.status===429||n.status>=500)}return a}async function re(e,t,o){let n=await w(e,`${ne}/${t}`,{method:"POST",body:JSON.stringify(o)});if(!n?.request_id||!n.status_url||!n.response_url)throw new m("fal submit returned no request id",502,!0);return{requestId:n.request_id,statusUrl:n.status_url,responseUrl:n.response_url,cancelUrl:n.cancel_url}}async function ae(e,t){let o=await w(e,t);if(o.error)return{state:"failed",error:`${o.error_type??"error"}: ${o.error}`};switch(o.status){case"IN_QUEUE":return{state:"queued",position:o.queue_position};case"IN_PROGRESS":return{state:"running"};case"COMPLETED":return{state:"completed"};default:return{state:"running"}}}async function se(e,t){return w(e,t)}var de="https://rest.fal.ai/storage/upload/initiate?storage_type=fal-cdn-v3";async function ce(e,t){let o=await w(e,de,{method:"POST",body:JSON.stringify({content_type:t.contentType,file_name:t.fileName})});if(!o?.upload_url||!o.file_url)throw new m("fal storage returned no upload URL",502,!0);let n=await fetch(o.upload_url,{method:"PUT",headers:{"Content-Type":t.contentType||"application/octet-stream"},body:new Blob([t.data],{type:t.contentType||"application/octet-stream"}),signal:AbortSignal.timeout(12e4)});if(!n.ok)throw new m(`fal storage upload failed (${n.status})`,n.status,n.status===429||n.status>=500);return o.file_url}function pe(e){return{submit:(t,o)=>re(e,t,o),status:t=>ae(e,t),result:t=>se(e,t),upload:t=>ce(e,t)}}function le(e){let t=[],o=e??{},n=o.video;n?.url&&t.push({url:n.url,contentType:n.content_type});let i=o.audio;i?.url&&t.push({url:i.url,contentType:i.content_type});let a=Array.isArray(o.images)?o.images:[];for(let d of a)d?.url&&t.push({url:d.url,contentType:d.content_type});return t}var ue=["ageAppearance","face","eyes","brows","skin","hair","bodyBuild"],me=["device","lens","distance","height","processing"],ge={device:"front-facing smartphone camera",lens:"24-28mm equivalent",distance:"arm's length",height:"slightly above eye level",processing:"subtle HDR, mild phone sharpening, no beauty filter"},fe=["face","hair","signature details","skin texture"],he=300,Se=12,c=(e,t=he)=>typeof e=="string"?e.replace(/\s+/g," ").trim().slice(0,t):"";function k(e,t=Se,o=120){return Array.isArray(e)?[...new Set(e.map(n=>c(n,o)).filter(Boolean))].slice(0,t):[]}var be={ageAppearance:"age_appearance",bodyBuild:"body_build"};function P(e){let t={};for(let i of ue){let a=c(e.identity?.[i]);a&&(t[be[i]??i]=a)}let o=c(e.appearance,600);o&&Object.keys(t).length===0&&(t.appearance=o);let n={};for(let i of me)n[i]=c(e.cameraHabits?.[i])||ge[i];return{creator:c(e.name,60)||"the creator",identity_lock:t,signature_details:k(e.signatureDetails),imperfections:k(e.imperfections),camera_habits:n,never_change:e.neverChange?.length?k(e.neverChange):fe}}function B(e){let t={},o=e.voiceProfile??{};return c(o.tone)&&(t.tone=c(o.tone)),c(o.accent)&&(t.accent=c(o.accent)),o.verbalHabits?.length&&(t.verbal_habits=o.verbalHabits),c(e.personality)&&(t.personality=c(e.personality)),t}var ve=["different face","shorter hair","missing jewelry","plastic skin","studio lighting","perfectly tidy room","extra fingers","warped label","text","watermark","UI overlays"],ye=["morphing face","melting hands","label changing between frames","camera cuts","slow motion"];function Ie(e){return(e?.signature_details??[]).map(t=>`missing ${t}`)}function S(e,t={}){return[...new Set([...ve,...t.video?ye:[],...Ie(e)])]}var xe=["identity from the creator lock (face, hair, signature details)","same camera habits","product and app screen readable","requested wardrobe only","requested location only"],we={style:"authentic user-generated content filmed on a phone",framing:"handheld, slightly imperfect framing, vertical 9:16",light:"natural light, casual real-life setting",avoid:"studio look, cinematic grading, text or logos on screen"},E={image:3800,video:3800,avatar:1200};function ke(e){let t={task:e.task};return e.creator&&(t.priority_order=xe,t.creator=e.creator),e.shot&&Object.keys(e.shot).length&&(t.shot=e.shot),e.direction&&(t.direction=e.direction),e.dialogue&&(t.dialogue=e.dialogue),e.delivery&&Object.keys(e.delivery).length&&(t.delivery=e.delivery),e.notes?.length&&(t.notes=e.notes),t.look=we,t.negative_prompt=e.negatives,t}function _(e,t){return typeof e=="string"?e.length>t?`${e.slice(0,t-1)}\u2026`:e:Array.isArray(e)?e.map(o=>_(o,t)):e&&typeof e=="object"?Object.fromEntries(Object.entries(e).map(([o,n])=>[o,_(n,t)])):e}function O(e,t){let o=ke(e),n=JSON.stringify(o);for(let a of[400,240,160,100]){if(n.length<=t)return n;let d=_(o,a);e.dialogue&&(d.dialogue=e.dialogue),n=JSON.stringify(d)}if(n.length<=t)return n;let i={...o,look:void 0,delivery:void 0};return e.creator&&(i.creator={...e.creator,imperfections:void 0,camera_habits:void 0}),JSON.stringify(_(i,100)).slice(0,t)}var Pe=(e,t=300)=>typeof e=="string"?e.replace(/\s+/g," ").trim().slice(0,t):"";function L(e,t){let o={},n=e.wardrobe||Pe(t);if(n&&(o.wardrobe=n),e.location&&(o.location=e.location),e.action&&(o.action=e.action),e.productPlacement){let i=e.productPlacement;o.product_placement={...i.visible!==void 0?{visible:i.visible}:{},...i.placement?{placement:i.placement}:{},...i.sizeInFrame?{size_in_frame:i.sizeInFrame}:{}}}return e.motionBeats?.length&&(o.motion=e.motionBeats),o}var j=e=>e?P(e):null;function J({persona:e,shot:t,direction:o}){let n=j(e);return O({task:n?`A photo of ${n.creator}: the same person as in the reference images, face, hair and build identical.`:"A candid phone photo.",creator:n,shot:L(t,e?.style?.wardrobe),direction:o||(t.action?"":"A candid everyday moment at home."),negatives:S(n)},E.image)}function K(e){let t=j(e.persona),o=e.script.replace(/\s+/g," ").trim();return O({task:o?`${t?.creator??"The person"} talks straight to the phone camera and says the dialogue line.`:`${t?.creator??"The person"} on camera, no dialogue.`,creator:t,shot:L(e.shot,e.persona?.style?.wardrobe),direction:e.direction,dialogue:o,delivery:e.persona?B(e.persona):void 0,notes:["Only describe what moves; the start frame fixes the face, room and light.","Subtle handheld shake, no background music, no subtitles."],negatives:S(t,{video:!0})},E.video)}var Ue="https://placeholder.appeeky.com/frame.png";var io=675;export{C as MAX_SCRIPT_CHARS,Ue as PLACEHOLDER_IMAGE,P as buildCreatorLock,pe as createFalClient,le as extractOutputUrls,T as fitDuration,u as getMediaModel,S as negativesFor,G as prepareImageJob,$ as prepareVideoJob,J as stillPrompt,K as talkingVideoPrompt};

package/dist/ugc-local.d.ts

@@ -0,0 +1,116 @@
+import type { AppeekyApi } from "./appeeky-api.js";
+import type { Brief } from "./ugc.js";
+/**
+ * Clips made on this machine with the user's own fal key (FAL_KEY), the same pipeline as Appeeky's
+ * hosted UGC and the desktop app's local mode: the persona's look → a still in the scene → a talking
+ * video with the script in the persona's voice. Planning, prompts and prices come from Appeeky's
+ * UGC core, bundled into dist/ugc-core.js and loaded only when this runs; fal bills the user directly.
+ *
+ * Personas come from either:
+ *   appeeky/ugc/personas/<name>.yaml   a persona kept in the repo, `looks:` pointing at its images
+ *   Appeeky UGC                         a persona made in Appeeky (APPEEKY_API_KEY), its cover as the look
+ */
+export declare const localPersonasDir: (root: string) => string;
+export declare const mediaDir: (root: string) => string;
+/** The UgcPersona fields the prompts read; everything else stays at its default. */
+export interface LocalPersona {
+    id: string;
+    name: string;
+    appearance?: string;
+    personality?: string;
+    bio?: string;
+    voice?: string;
+    lane?: string;
+    identity?: Record<string, unknown>;
+    signatureDetails?: string[];
+    imperfections?: string[];
+    cameraHabits?: Record<string, unknown>;
+    voiceProfile?: Record<string, unknown>;
+    neverChange?: string[];
+    style?: Record<string, unknown>;
+    /** Image files (relative to the persona file) or URLs that show the persona. */
+    looks: string[];
+}
+interface PreparedJob {
+    costUsd: number;
+    model: {
+        endpoint: string;
+        mapInput(request: unknown): Record<string, unknown>;
+    };
+    request: unknown;
+}
+interface Core {
+    MAX_SCRIPT_CHARS: number;
+    getMediaModel(id: string): {
+        id: string;
+        kind: string;
+        mode: string;
+        label: string;
+        nativeAudio?: boolean;
+    } | undefined;
+    fitDuration(model: unknown, seconds: number): number;
+    prepareImageJob(input: Record<string, unknown>): PreparedJob;
+    prepareVideoJob(input: Record<string, unknown>): PreparedJob;
+    createFalClient(key: string): {
+        submit(endpoint: string, input: Record<string, unknown>): Promise<{
+            statusUrl: string;
+            responseUrl: string;
+        }>;
+        status(url: string): Promise<{
+            state: string;
+            error?: string;
+        }>;
+        result(url: string): Promise<unknown>;
+        upload(file: {
+            data: Uint8Array;
+            contentType: string;
+            fileName: string;
+        }): Promise<string>;
+    };
+    extractOutputUrls(result: unknown): Array<{
+        url: string;
+        contentType?: string;
+    }>;
+    buildCreatorLock(persona: unknown): unknown;
+    negativesFor(lock: unknown, opts: {
+        video: boolean;
+    }): string[];
+    stillPrompt(input: Record<string, unknown>): string;
+    talkingVideoPrompt(input: Record<string, unknown>): string;
+    PLACEHOLDER_IMAGE: string;
+}
+/** The UGC pipeline ships inside Spec as one minified file (dist/ugc-core.js, built by scripts/vendor-ugc-core.mjs). */
+export declare const CORE_FILE = "./ugc-core.js";
+export declare function loadCore(load?: (specifier: string) => Promise<Record<string, unknown>>): Promise<Core>;
+/** A persona kept in the repo (appeeky/ugc/personas/<name>.yaml), with its looks resolved to paths or URLs. */
+export declare function readLocalPersona(root: string, name: string): Promise<LocalPersona | undefined>;
+/** A persona made in Appeeky UGC: its fields, with the cover image as its look. */
+export declare function readAppeekyPersona(api: AppeekyApi, name: string): Promise<LocalPersona | undefined>;
+interface Plan {
+    still: PreparedJob;
+    video: (stillUrl: string) => PreparedJob;
+    costUsd: number;
+    clip: {
+        durationSec: number;
+        aspectRatio: string;
+        videoModelId: string;
+    };
+}
+/** The same two steps as the hosted clip render: a still of the persona in the scene, then a talking video. */
+export declare function planLocalClip(core: Core, persona: LocalPersona, brief: Brief, refs: string[]): Plan;
+export interface LocalClipResult {
+    file: string;
+    videoUrl: string;
+    stillUrl: string;
+    costUsd: number;
+}
+/** Make the clip with the user's fal key, save it under .appeeky/media/ and record it in the brief. */
+export declare function generateLocal(core: Core, root: string, brief: Brief & {
+    file: string;
+}, persona: LocalPersona, falKey: string, options?: {
+    fetcher?: typeof fetch;
+    sleep?: (ms: number) => Promise<void>;
+    now?: Date;
+    log?: (line: string) => void;
+}): Promise<LocalClipResult>;
+export {};