@ronana/mcp 0.0.0-stage → 0.1.0

package/README.md

@@ -1,3 +1,116 @@
-# Temporary Holding Version
+# Ronana CLI and MCP
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+NOTE: MCP and the command line are in admin preview. At launch they will
+require a paid plan.
+
+WARNING: Generations spend your account credits.
+
+## Install
+
+Requires Node.js 20 or later.
+
+```text
+npm install -g @ronana/mcp
+```
+
+This installs two commands: `ronana`, the command line, and `ronana-mcp`, a
+local MCP server for AI apps.
+
+## Sign in
+
+```text
+ronana auth login
+```
+
+Ronana opens in your browser. Sign in and approve the access. You do not need
+an API key. The sign-in is stored in your system keychain and stays until you
+run `ronana auth logout`, which also revokes it.
+
+## Command line
+
+```text
+ronana auth login | status | logout
+ronana account
+ronana model list [filter] [--kind image|video]
+ronana model get google/nano-banana-2-lite/edit
+ronana upload ./photo.png                  # prints a ref_ id
+ronana generate cost   google/nano-banana-2-lite/edit --prompt "make it dusk" --image ./photo.png
+ronana generate create google/nano-banana-2-lite/edit --prompt "make it dusk" --image ./photo.png --out ./renders
+ronana generate get <id> | wait <id> [--out dir]
+ronana generate list
+```
+
+Every field from `model get` is a flag (`--aspect_ratio 16:9`, `--seed 7`).
+Repeat a flag to fill a list. `--image`, `--video` and `--audio` fill the
+model's media field, and accept a local file, an https URL, or a Ronana id.
+Local files upload first. `--input '{...}'` (or `--input @body.json`) sets the
+whole body for nested fields. `--wait` prints the result link; `--out` also
+downloads it. Add `--json` to any command for scripts. Run `ronana --help` for
+the full list.
+
+`generate create` spends credits. Each run sends its own idempotency key, so
+the same command run twice makes two generations. Pass `--idempotency-key` to
+make a retry bill once.
+
+## Use Ronana from an AI app
+
+Most AI apps connect to Ronana's remote MCP server directly. Add this URL as a
+remote MCP server or custom connector, then sign in when the app asks:
+
+```text
+https://ronana.ai/mcp
+```
+
+Open **Account > Connections** on ronana.ai to see or disconnect an app.
+
+### Local MCP server
+
+Use `ronana-mcp` for an app that only runs local MCP servers, or to let your AI
+upload files from your computer. Sign in once with `ronana auth login`, then
+add it to the app's MCP settings:
+
+```json
+{
+  "mcpServers": {
+    "ronana": {
+      "command": "npx",
+      "args": ["-y", "-p", "@ronana/mcp", "ronana-mcp"],
+      "env": { "RONANA_MCP_UPLOAD_ROOT": "/path/to/your/media" }
+    }
+  }
+}
+```
+
+The local server adds one tool, `upload_local_reference`, which uploads a file
+from inside `RONANA_MCP_UPLOAD_ROOT`. Set it to the folder that holds your
+media, never a home directory or a drive root. Files larger than 3 MB stream
+straight to storage, and Ronana checks each file before it adds it to your
+library.
+
+## Tools
+
+| Tool | Function |
+| --- | --- |
+| `list_models` | List the available models. |
+| `get_model` | Get one model's contract: its input schema. |
+| `estimate_cost` | Estimate the credit cost of a generation. Takes the same `model` and `input` as `generate`. |
+| `generate` | Start an image or video generation. |
+| `get_generation` | Get one generation and its download link. |
+| `list_generations` | List recent generations. |
+| `list_references` | List library references. |
+| `upload_reference` | Add a file to the library from a URL (up to 25 MB) or from base64 (under 3 MB). |
+| `create_upload` | Get a private upload link for a larger local file (up to 200 MB). |
+| `finish_upload` | Add a file uploaded with `create_upload` to the library. |
+| `get_account` | Get the plan and credit balance. |
+
+A generate call takes a `model` and an `input`, exactly as `get_model` shows it
+in `input_schema`. A media field takes a public https URL or a Ronana id
+(`ref_…`, `img_…`, `gen_…`). Generation tools return an id immediately. Poll
+`get_generation` until the status is `completed` or `failed`.
+
+```json
+{ "model": "google/nano-banana-2/edit", "input": { "prompt": "a lantern shop at dusk", "images": ["https://example.com/ref.png"] } }
+```
+
+Generations and uploads appear in your Ronana library. Your plan's storage
+limits and retention apply.

package/dist/cli.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};

package/dist/cli.js

@@ -0,0 +1,286 @@
+#!/usr/bin/env node
+// `ronana`: the command line for Ronana. A thin client over the same remote MCP
+// tools an agent uses, so every request runs the server's own validation,
+// pricing, credit gates and rate limits. Nothing here prices or bills.
+//
+//   ronana auth login | logout | status
+//   ronana account
+//   ronana model list [filter] [--kind image|video]
+//   ronana model get <model>
+//   ronana upload <file | https-url>
+//   ronana generate create <model> --prompt "…" [--<field> value …] [--wait] [--out dir]
+//   ronana generate cost <model> [same flags as create]
+//   ronana generate get | wait <id> [--out dir]
+//   ronana generate list [--limit n]
+import { randomUUID } from "node:crypto";
+import { createWriteStream } from "node:fs";
+import { mkdir } from "node:fs/promises";
+import { basename, extname, join, resolve } from "node:path";
+import { Readable } from "node:stream";
+import { pipeline } from "node:stream/promises";
+import { login, logout, readCredentials } from "./oauth.js";
+import { callTool, remoteClient, ToolError, uploadFile } from "./remote.js";
+import { buildInput, flag, has, parseArgs, replaceLocalMedia, typeOf } from "./input.js";
+const HELP = `Usage: ronana <command>
+
+  auth login                    Sign in with your browser (--base-url, --no-browser)
+  auth logout                   Sign out and revoke the token
+  auth status                   Show the signed-in server
+  account                       Plan and credit balance
+  model list [filter]           Models you can run (--kind image|video)
+  model get <model>             A model's fields, media inputs and priced fields
+  upload <file|https-url>       Add a reference to your library, print its id
+  generate create <model>       Start a generation (costs credits)
+  generate cost <model>         Credits a generation would cost (free)
+  generate get <id>             Status and download links
+  generate wait <id>            Wait for a generation to finish
+  generate list                 Recent generations (--limit n)
+
+Generate flags:
+  --<field> <value>             Any field from \`model get\`. Repeat for lists.
+  --image/--video/--audio <v>   A file, https URL or ref_/img_/gen_ id
+  --input <json|@file.json>     The whole input body (flags override it)
+  --wait                        Wait for the result and print its link
+  --out <dir>                   Wait, then download the outputs into <dir>
+  --wait-timeout <sec>          Default 600
+  --idempotency-key <key>       Resend safely: same key bills once
+
+Global: --json for machine-readable output, --help.
+`;
+// ── output ───────────────────────────────────────────────────────────────────
+let JSON_OUT = false;
+const print = (line = "") => process.stdout.write(`${line}\n`);
+const note = (line) => { if (!JSON_OUT)
+    process.stderr.write(`${line}\n`); };
+const emit = (data, human) => JSON_OUT ? print(JSON.stringify(data, null, 2)) : human();
+function describeField(name, schema, required) {
+    const type = typeOf(schema);
+    const parts = [type === "array" ? `${typeOf(schema.items ?? {})}[]` : type];
+    const choices = schema.enum ?? schema.items?.enum;
+    if (choices)
+        parts.push(choices.map(String).join("|"));
+    if (schema.minimum !== undefined || schema.maximum !== undefined)
+        parts.push(`${schema.minimum ?? ""}..${schema.maximum ?? ""}`);
+    if (schema.default !== undefined)
+        parts.push(`default ${JSON.stringify(schema.default)}`);
+    return `  --${name.padEnd(22)} ${parts.join("  ")}${required ? "  (required)" : ""}`;
+}
+const TERMINAL = new Set(["completed", "failed", "canceled"]);
+function seconds(args, name, fallback) {
+    const raw = flag(args, name);
+    const value = raw === undefined ? fallback : Number(raw);
+    if (!Number.isFinite(value) || value <= 0)
+        throw new Error(`--${name.replaceAll("_", "-")} must be a positive number of seconds.`);
+    return value;
+}
+async function waitFor(remote, id, args) {
+    const timeoutMs = seconds(args, "wait_timeout", 600) * 1000;
+    const intervalMs = Math.max(1, seconds(args, "wait_interval", 3)) * 1000;
+    const deadline = Date.now() + timeoutMs;
+    let last = "";
+    for (;;) {
+        let gen;
+        try {
+            gen = await callTool(remote, "get_generation", { id });
+        }
+        catch (error) {
+            // A server answer (not found, no access) is final; anything else is the
+            // connection, and the generation carries on without us.
+            if (error instanceof ToolError)
+                throw error;
+            throw new Error(`${error instanceof Error ? error.message : String(error)}
+${id} is still running. Resume with \`ronana generate wait ${id}\`.`);
+        }
+        if (gen.status !== last) {
+            note(`${id}: ${gen.status}`);
+            last = gen.status;
+        }
+        if (TERMINAL.has(gen.status))
+            return gen;
+        if (Date.now() > deadline)
+            throw new Error(`Still ${gen.status} after ${timeoutMs / 1000}s. Check later with \`ronana generate wait ${id}\`.`);
+        await new Promise((r) => setTimeout(r, intervalMs));
+    }
+}
+const EXT_BY_TYPE = {
+    "image/png": ".png", "image/jpeg": ".jpg", "image/webp": ".webp", "image/gif": ".gif",
+    "video/mp4": ".mp4", "video/webm": ".webm", "video/quicktime": ".mov",
+};
+async function download(gen, dir) {
+    await mkdir(dir, { recursive: true });
+    const saved = [];
+    for (const output of gen.outputs) {
+        if (!output.url)
+            continue;
+        const response = await fetch(output.url);
+        if (!response.ok || !response.body)
+            throw new Error(`Download of ${output.id} failed (${response.status}).`);
+        const type = response.headers.get("content-type")?.split(";")[0] ?? "";
+        const urlExt = extname(new URL(output.url).pathname).toLowerCase();
+        const ext = EXT_BY_TYPE[type] ?? (/^\.[a-z0-9]{1,5}$/.test(urlExt) ? urlExt : "");
+        // The name comes from server data: keep it a plain file name inside `dir`.
+        const file = join(dir, `${output.id.replace(/[^A-Za-z0-9_-]/g, "_")}${ext}`);
+        await pipeline(Readable.fromWeb(response.body), createWriteStream(file));
+        saved.push(file);
+    }
+    return saved;
+}
+async function finish(gen, args) {
+    const out = flag(args, "out");
+    const files = gen.status === "completed" && out ? await download(gen, out) : [];
+    emit({ ...gen, ...(out ? { files } : {}) }, () => {
+        if (gen.status === "completed") {
+            if (files.length)
+                files.forEach((f) => print(f));
+            else
+                gen.outputs.forEach((o) => o.url && print(o.url));
+        }
+        else if (gen.status === "failed") {
+            print(`Failed: ${gen.error?.message ?? gen.error?.reason ?? "unknown error"}`);
+            print(gen.charged ? "Credits were kept (the provider billed this attempt)." : "Credits were refunded.");
+        }
+        else {
+            print(`${gen.id}: ${gen.status}`);
+        }
+    });
+    if (gen.status === "failed" || gen.status === "canceled")
+        process.exitCode = 1;
+}
+// ── commands ─────────────────────────────────────────────────────────────────
+async function withRemote(fn) {
+    const remote = await remoteClient();
+    try {
+        return await fn(remote);
+    }
+    finally {
+        await remote.close().catch(() => null);
+    }
+}
+async function generateCommand(sub, args) {
+    const [target] = args.positional;
+    if (sub === "list") {
+        const limit = Number(flag(args, "limit") ?? 25);
+        const rows = await withRemote((r) => callTool(r, "list_generations", { limit }));
+        return emit(rows, () => rows.forEach((g) => print(`${g.id.padEnd(28)} ${g.status.padEnd(11)} ${g.created_at}`)));
+    }
+    if (!target)
+        throw new Error(`Usage: ronana generate ${sub ?? "create"} <${sub === "get" || sub === "wait" ? "id" : "model"}>`);
+    if (sub === "get") {
+        const gen = await withRemote((r) => callTool(r, "get_generation", { id: target }));
+        return finish(gen, args);
+    }
+    if (sub === "wait")
+        return withRemote(async (r) => finish(await waitFor(r, target, args), args));
+    if (sub !== "create" && sub !== "cost")
+        throw new Error("Use generate create | cost | get | wait | list.");
+    await withRemote(async (remote) => {
+        const contract = await callTool(remote, "get_model", { id: target });
+        const input = await buildInput(contract, args);
+        await replaceLocalMedia(contract, input, async (path) => {
+            note(`Uploading ${basename(path)}…`);
+            return (await uploadFile(remote, path)).id;
+        });
+        if (sub === "cost") {
+            const quote = await callTool(remote, "estimate_cost", { model: contract.id, input });
+            return emit(quote, () => print(quote.available === false ? "This request cannot be priced." : `${quote.credits} credits`));
+        }
+        /* Always send a key. The server otherwise derives one from the JSON-RPC
+           id, which restarts at the same value in every CLI process, so the same
+           command run twice in ten minutes would return the first generation. */
+        const idempotency_key = flag(args, "idempotency_key") ?? randomUUID();
+        const queued = await callTool(remote, "generate", { model: contract.id, input, idempotency_key });
+        if (!has(args, "wait") && !has(args, "out")) {
+            return emit(queued, () => { print(queued.id); note(`Check it with \`ronana generate wait ${queued.id}\`.`); });
+        }
+        note(`Queued ${queued.id}.`);
+        await finish(await waitFor(remote, queued.id, args), args);
+    });
+}
+async function modelCommand(sub, args) {
+    if (sub === "list" || sub === undefined) {
+        const kind = flag(args, "kind");
+        const filter = args.positional[0]?.toLowerCase();
+        const models = (await withRemote((r) => callTool(r, "list_models", kind ? { kind } : {})))
+            .filter((m) => !filter || m.id.toLowerCase().includes(filter) || m.name.toLowerCase().includes(filter));
+        return emit(models, () => models.forEach((m) => print(`${m.id.padEnd(52)} ${m.kind.padEnd(6)} ${m.name}`)));
+    }
+    if (sub !== "get")
+        throw new Error("Use model list | get.");
+    const id = args.positional[0];
+    if (!id)
+        throw new Error("Usage: ronana model get <model>");
+    const contract = await withRemote((r) => callTool(r, "get_model", { id }));
+    emit(contract, () => {
+        print(`${contract.name}  (${contract.kind})`);
+        print(contract.id);
+        print();
+        const required = new Set(contract.input_schema.required ?? []);
+        for (const [name, schema] of Object.entries(contract.input_schema.properties ?? {}))
+            print(describeField(name, schema, required.has(name)));
+        if (contract.media_fields.length) {
+            print();
+            print(`Media (file, https URL or id): ${contract.media_fields.map((m) => `${m.field} [${m.kind}]`).join(", ")}`);
+        }
+        if (contract.priced_fields.length)
+            print(`Priced by: ${contract.priced_fields.join(", ")}`);
+    });
+}
+async function main() {
+    const [command, sub, ...rest] = process.argv.slice(2);
+    const takesSub = command === "auth" || command === "model" || command === "generate";
+    const args = parseArgs(takesSub ? rest : [sub, ...rest].filter((v) => v !== undefined));
+    JSON_OUT = has(args, "json");
+    if (!command || ["help", "--help", "-h"].includes(command) || has(args, "help"))
+        return void process.stdout.write(HELP);
+    switch (command) {
+        case "auth":
+        case "login":
+        case "logout":
+        case "status": {
+            const action = command === "auth" ? sub : command;
+            if (action === "login") {
+                await login(flag(args, "base_url") ?? process.env.RONANA_BASE_URL, !has(args, "no_browser"));
+                return print(`Signed in to ${readCredentials().baseUrl}.`);
+            }
+            if (action === "logout") {
+                await logout();
+                return print("Signed out.");
+            }
+            if (action === "status") {
+                const credentials = readCredentials();
+                return emit({ signed_in: !!credentials, base_url: credentials?.baseUrl ?? null }, () => print(credentials ? `Signed in to ${credentials.baseUrl}.` : "Not signed in."));
+            }
+            throw new Error("Use auth login | logout | status.");
+        }
+        case "account": {
+            const account = await withRemote((r) => callTool(r, "get_account"));
+            return emit(account, () => print(`${account.credits} credits · ${account.tier} plan`));
+        }
+        case "model":
+        case "models": return modelCommand(command === "models" ? "list" : sub, args);
+        case "upload": {
+            const source = args.positional[0];
+            if (!source)
+                throw new Error("Usage: ronana upload <file | https-url>");
+            const ref = await withRemote((r) => /^https:\/\//i.test(source)
+                ? callTool(r, "upload_reference", { url: source, filename: basename(new URL(source).pathname) || "upload" })
+                : uploadFile(r, resolve(source)));
+            return emit(ref, () => print(ref.id));
+        }
+        case "generate": return generateCommand(sub, args);
+        default: throw new Error(`Unknown command "${command}". Run \`ronana --help\`.`);
+    }
+}
+main().catch((error) => {
+    if (error instanceof ToolError) {
+        const { code, message, url, billing } = error.error;
+        if (JSON_OUT)
+            process.stdout.write(`${JSON.stringify({ ok: false, error: error.error }, null, 2)}\n`);
+        else
+            process.stderr.write(`${code ? `${code}: ` : ""}${message}${billing?.url ?? url ? `\n${billing?.url ?? url}` : ""}\n`);
+    }
+    else {
+        process.stderr.write(`${error instanceof Error ? error.message : String(error)}\n`);
+    }
+    process.exitCode = 1;
+});

package/dist/client.d.ts

@@ -0,0 +1,61 @@
+import type { ApiErrorBody, ApiPublicModel, GenerationState } from "./types.js";
+export declare class RonanaApiError extends Error {
+    readonly code: string;
+    readonly status: number;
+    readonly body: ApiErrorBody["error"] | null;
+    constructor(code: string, message: string, status: number, body: ApiErrorBody["error"] | null);
+    /** A sentence a person or an agent can act on. The `action` field is the
+     *  server's own decision about which door to open, so this never guesses. */
+    get guidance(): string;
+}
+export interface ClientOptions {
+    apiKey: string;
+    baseUrl: string;
+}
+/** Read the configuration from the environment. Throws with a clear message
+ *  when the key is missing, because that is the one mistake every new user
+ *  makes. */
+export declare function clientOptionsFromEnv(env?: NodeJS.ProcessEnv): ClientOptions;
+export declare class RonanaClient {
+    private readonly options;
+    constructor(options: ClientOptions);
+    private request;
+    listModels(): Promise<{
+        models: ApiPublicModel[];
+        tier: string;
+    }>;
+    account(): Promise<unknown>;
+    quote(input: Record<string, unknown>): Promise<{
+        available: boolean;
+        credits: number;
+    }>;
+    submitVideo(body: Record<string, unknown>): Promise<{
+        id: string;
+        status: string;
+    }>;
+    submitImage(body: Record<string, unknown>): Promise<{
+        id: string;
+        status: string;
+    }>;
+    generation(id: string): Promise<GenerationState>;
+    /** Upload a file inline. Use this up to 4 MB; larger files need the presigned
+     *  flow below, because a serverless function body cannot exceed 4.5 MB. */
+    uploadInline(bytes: Uint8Array, filename: string): Promise<{
+        ref: {
+            id: string;
+        };
+        reused?: boolean;
+    }>;
+    /** Upload a file larger than 4 MB: sign, PUT straight to storage, finalize.
+     *
+     *  CAUTION: The PUT must send exactly the content type and the content length
+     *  that were signed. Any other value fails the storage signature check. */
+    uploadPresigned(bytes: Uint8Array, filename: string, contentType: string): Promise<{
+        ref: {
+            id: string;
+        };
+        reused?: boolean;
+    }>;
+}
+/** The most bytes an inline upload may carry. Above this, use the signed flow. */
+export declare const INLINE_UPLOAD_MAX_BYTES: number;

package/dist/client.js

@@ -0,0 +1,128 @@
+// The HTTP client for the RonanaLive public API.
+//
+// THE LOAD-BEARING RULE OF THIS PACKAGE: it is a thin HTTP client of
+// `/api/v1/*`. It imports no database, no credit module, and no ORM. If it ever
+// imported the application's database layer, somebody would eventually run this
+// package against production.
+//
+// Everything it needs is two environment variables:
+//   RONANA_API_KEY   the key, `rk_…`, minted at /developers/keys
+//   RONANA_BASE_URL  the origin, default https://ronana.ai
+export class RonanaApiError extends Error {
+    code;
+    status;
+    body;
+    constructor(code, message, status, body) {
+        super(message);
+        this.code = code;
+        this.status = status;
+        this.body = body;
+        this.name = "RonanaApiError";
+    }
+    /** A sentence a person or an agent can act on. The `action` field is the
+     *  server's own decision about which door to open, so this never guesses. */
+    get guidance() {
+        const billing = this.body?.billing;
+        if (!billing)
+            return this.message;
+        switch (billing.action) {
+            case "buy_credits": return `${this.message} Buy more credits at ${billing.url}.`;
+            case "upgrade_plan": return `${this.message} Move to a larger plan at ${billing.url}.`;
+            case "either": return `${this.message} Buy credits or move to a larger plan at ${billing.url}.`;
+            case "verify_email": return `${this.message} Verify the account email at ${billing.url}.`;
+            case "wait": return `${this.message} Wait, then try again.`;
+            case "contact_support": return `${this.message} Contact support.`;
+            default: return this.message;
+        }
+    }
+}
+/** Read the configuration from the environment. Throws with a clear message
+ *  when the key is missing, because that is the one mistake every new user
+ *  makes. */
+export function clientOptionsFromEnv(env = process.env) {
+    const apiKey = env.RONANA_API_KEY?.trim();
+    if (!apiKey) {
+        throw new Error("RONANA_API_KEY is not set. Create a key at https://ronana.ai/developers/keys, " +
+            "then put it in your MCP client configuration as RONANA_API_KEY.");
+    }
+    const baseUrl = (env.RONANA_BASE_URL?.trim() || "https://ronana.ai").replace(/\/+$/, "");
+    return { apiKey, baseUrl };
+}
+export class RonanaClient {
+    options;
+    constructor(options) {
+        this.options = options;
+    }
+    async request(method, path, body) {
+        const res = await fetch(`${this.options.baseUrl}${path}`, {
+            method,
+            headers: {
+                authorization: `Bearer ${this.options.apiKey}`,
+                ...(body === undefined ? {} : { "content-type": "application/json" }),
+            },
+            ...(body === undefined ? {} : { body: JSON.stringify(body) }),
+        });
+        const text = await res.text();
+        const parsed = text ? JSON.parse(text) : null;
+        if (!res.ok) {
+            const envelope = parsed?.error ?? null;
+            throw new RonanaApiError(envelope?.code ?? "UNKNOWN", envelope?.message ?? `Request failed with status ${res.status}.`, res.status, envelope);
+        }
+        return parsed;
+    }
+    listModels() {
+        return this.request("GET", "/api/v1/models");
+    }
+    account() {
+        return this.request("GET", "/api/v1/me");
+    }
+    quote(input) {
+        return this.request("POST", "/api/v1/pricing/quote", input);
+    }
+    submitVideo(body) {
+        return this.request("POST", "/api/v1/generations", body);
+    }
+    submitImage(body) {
+        return this.request("POST", "/api/v1/images", body);
+    }
+    generation(id) {
+        return this.request("GET", `/api/v1/generations/${encodeURIComponent(id)}`);
+    }
+    /** Upload a file inline. Use this up to 4 MB; larger files need the presigned
+     *  flow below, because a serverless function body cannot exceed 4.5 MB. */
+    async uploadInline(bytes, filename) {
+        const res = await fetch(`${this.options.baseUrl}/api/v1/refs`, {
+            method: "POST",
+            headers: {
+                authorization: `Bearer ${this.options.apiKey}`,
+                "content-type": "application/octet-stream",
+                "x-filename": encodeURIComponent(filename),
+            },
+            body: bytes,
+        });
+        const text = await res.text();
+        const parsed = text ? JSON.parse(text) : null;
+        if (!res.ok) {
+            const envelope = parsed?.error ?? null;
+            throw new RonanaApiError(envelope?.code ?? "UNKNOWN", envelope?.message ?? "Upload failed.", res.status, envelope);
+        }
+        return parsed;
+    }
+    /** Upload a file larger than 4 MB: sign, PUT straight to storage, finalize.
+     *
+     *  CAUTION: The PUT must send exactly the content type and the content length
+     *  that were signed. Any other value fails the storage signature check. */
+    async uploadPresigned(bytes, filename, contentType) {
+        const signed = await this.request("POST", "/api/v1/refs/upload-url", { filename, contentType, size: bytes.byteLength });
+        const put = await fetch(signed.uploadUrl, {
+            method: "PUT",
+            headers: { "content-type": signed.contentType, "content-length": String(bytes.byteLength) },
+            body: bytes,
+        });
+        if (!put.ok)
+            throw new Error(`The upload to storage failed with status ${put.status}.`);
+        return this.request("POST", "/api/v1/refs", { tmpKey: signed.tmpKey, filename });
+    }
+}
+/** The most bytes an inline upload may carry. Above this, use the signed flow. */
+export const INLINE_UPLOAD_MAX_BYTES = 4 * 1024 * 1024;

package/dist/input.d.ts

@@ -0,0 +1,39 @@
+export interface Args {
+    positional: string[];
+    flags: Map<string, string[]>;
+}
+export declare function parseArgs(argv: string[]): Args;
+export declare const flag: (args: Args, name: string) => string | undefined;
+export declare const has: (args: Args, name: string) => boolean;
+export declare const takeFlag: (args: Args, name: string) => string | undefined;
+export interface JsonSchema {
+    type?: string | string[];
+    enum?: unknown[];
+    default?: unknown;
+    description?: string;
+    items?: JsonSchema;
+    properties?: Record<string, JsonSchema>;
+    required?: string[];
+    minimum?: number;
+    maximum?: number;
+}
+export interface ModelContract {
+    id: string;
+    kind: "image" | "video";
+    name: string;
+    input_schema: JsonSchema;
+    media_fields: {
+        field: string;
+        kind: string;
+        mask?: boolean;
+    }[];
+    priced_fields: string[];
+}
+export declare const typeOf: (schema: JsonSchema) => string;
+/** A URL (the server says which schemes it accepts) or a Ronana id. */
+export declare const isRemoteValue: (v: string) => boolean;
+export declare function buildInput(contract: ModelContract, args: Args): Promise<Record<string, unknown>>;
+/** Replace every local file named in a media field with an uploaded ref id.
+ *  Only media fields are looked at, so a prompt that happens to match a file
+ *  name is never uploaded. A file named twice uploads once. */
+export declare function replaceLocalMedia(contract: ModelContract, input: Record<string, unknown>, upload: (path: string) => Promise<string>): Promise<void>;