upscale4k 0.0.0-stage → 0.1.0

package/README.md

@@ -1,3 +1,230 @@
-# Temporary Holding Version
+# Upscale4K
 
-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.
+Upscale local MP4/MOV videos to 4K with [Upscale4K](https://upscale4k.io) from a terminal or an MCP agent. Node.js 20+
+is required. No install is needed:
+
+```sh
+npx upscale4k --help
+npx upscale4k login
+```
+
+Create an API key in your Upscale4K account first. Login hides typed characters,
+validates the key and API access, and saves the credential. Credentials live in
+`~/.config/upscale4k/config.json`, or `%APPDATA%\upscale4k\config.json` on Windows.
+The config has mode 600 on POSIX. `UPSCALE4K_API_KEY` overrides its credential.
+`UPSCALE4K_API_URL` overrides the default `https://upscale4k.io` API origin.
+Keep the config private. `npx upscale4k logout` removes local login; unset any
+environment credential separately.
+
+### Agents and scripts without a terminal
+
+Set `UPSCALE4K_API_KEY`. No login, config file, or general terms acceptance is
+needed. The legacy `--accept-terms` flag is accepted
+as a deprecated no-op and does not record or log acceptance. Existing configs
+containing old terms metadata remain readable; version changes do not block access.
+
+```sh
+UPSCALE4K_API_KEY=cx_live_... npx upscale4k upscale ./clip.mp4 --self-likeness no --json
+```
+
+PowerShell:
+
+```powershell
+npx upscale4k upscale "D:\videos\clip.mov" --self-likeness no
+npx upscale4k upscale "D:\videos\batch" --self-likeness yes --out "D:\results" --concurrency 3
+```
+
+Bash:
+
+```bash
+npx upscale4k upscale ./clip.mp4 --self-likeness no
+npx upscale4k upscale ./batch --self-likeness yes --out ./results --concurrency 3
+```
+
+`--self-likeness yes|no` is required for every run: declare whether the upload
+contains your own image or voice. With `yes`, the exact account consent statement
+is displayed for confirmation. Scripts may supply `--yes-self-likeness-consent`
+only after obtaining that explicit consent. Agents must ask the user; never guess.
+
+The CLI scans folders recursively. Results are adjacent to inputs by default:
+`clip.mov` becomes `clip 4K.mp4`. With `--out`, a folder's basename and structure
+are mirrored: `batch/sub/clip.mov` becomes `results/batch/sub/clip 4K.mp4`.
+Sources with the same case-insensitive stem in one output folder receive
+extension-qualified names: `clip.mp4` and `clip.mov` become `clip (mp4) 4K.mp4`
+and `clip (mov) 4K.mp4`. Extensions in these names are lowercase. This applies
+to both colocated and mirrored outputs. A lone `clip.mov` keeps `clip 4K.mp4`.
+Single-file CLI and MCP upscale requests account for supported siblings in the
+source folder, so their names agree with folder runs.
+
+For colocated outputs and grouped siblings, only each source's computed output
+name counts as an existing result; reruns skip exactly those completed sources.
+For a lone source with `--out` pointing to a different folder, its computed name,
+`<stem>.mp4` or `<stem>.mov` in the destination count (the input itself is
+excluded). Matches are case-insensitive. `.part` files do not count. Generated
+` 4K.mp4` files are excluded from directory scans and grouping. If computed output
+paths still collide, the run stops with `local_error` before contacting the API;
+rename one source before retrying.
+
+Uploads must be at most 500 MiB (500 × 1024 × 1024 bytes), have a longer side
+between 500 and 2560 pixels, and fit the account's current `/me` `max_seconds`.
+Out-of-limit files are reported and skipped; the server makes the final admission
+decision and its error is shown as is. The service also rejects videos whose average frame rate exceeds its server-side
+limit (`frame_rate_limit` at admission or `input_frame_rate_high` after upload);
+export at 30 fps or lower.
+Metadata is read with a built-in MP4/QuickTime parser; install `ffprobe` on PATH
+for files needing the fallback. Unsupported/unreadable files are reported as failures.
+
+### Not yet available
+
+Long-video upload is not yet available through the Upscale4K API: `/me` does not
+advertise `long_video`, and `/api/v1/jobs/{id}/multipart` is not served. Files
+over the account's `max_seconds` are skipped with an explanatory message.
+The client retains multipart support for compatible servers that advertise
+`long_video.eligible`: those uploads may run up to
+`long_video.max_seconds["runway-4k"]` and weigh up to `long_video.max_upload_bytes`.
+Completing the multipart upload queues the job without a separate submit call.
+If a server advertises multipart without serving its endpoint, the client reports
+the unsupported upload and preserves the saved job for inspection.
+
+Upscale4K web also does not yet send `x-upscale4k-latest` or retire clients with
+426 `upgrade_required`. The client supports both: it prints one update notice
+per client on stderr when a newer numeric version is advertised and stops a
+retired run with `npx -y upscale4k@latest` resume instructions. No header means no notice.
+
+`--wait` is the default. `--no-wait` returns submitted job IDs without downloading.
+Inspect them with:
+
+```sh
+npx upscale4k status
+npx upscale4k status JOB_ID
+npx upscale4k credits
+```
+
+For agents, `--json` emits one JSON object per event line:
+
+```sh
+npx upscale4k upscale ./batch --self-likeness no --json
+npx upscale4k upscale ./batch --self-likeness yes --yes-self-likeness-consent --no-wait --json
+```
+
+Events: `scan`, `skipped`, `created`, `uploaded`, `queued`, `progress`, `done`,
+`failed`, `summary`. Consent statements and interactive prompts use stderr.
+Failed files or an early stop set exit status 1. Already in-flight workers may
+finish after a server admission stop; no further files are started. Ctrl+C or
+MCP request cancellation stops scheduling, polling, transfers and retries;
+already-created jobs stay on the server and can be resumed. Concurrency defaults to 3
+(allowed range 1–100).
+
+Rerun the same command after a crash. `.upscale4k-state.json` in `--out` (or the
+source directory) saves source path, size, mtime, output, exact request body,
+idempotency key, creation time, job ID and the API key's first 12 characters
+(never the full key). Do not delete it during recovery.
+Create retries reuse their key; existing jobs are inspected before continuing.
+After API key rotation, an unfinished create/upload stops with `resume_ambiguous`:
+inspect/cancel the old job or rerun with the original key. Jobs already past
+uploading continue normally; legacy state without a key prefix keeps its prior behaviour.
+After 24 hours, only a confirmed failed/canceled/expired job is replaced.
+An old uploading job or unknown job ID stops with `resume_ambiguous` because
+the contract has no upload-refresh endpoint after idempotency expires. Inspect
+and cancel that old job before manually resolving its state. Legacy request bodies
+are replayed unchanged to preserve idempotency. New requests send only the explicit
+likeness choice and consent when applicable. A changed consent choice conflicts
+with a saved request instead of silently changing the upload.
+Downloads stream to `<output>.part`, restart from zero after transfer failures,
+and are renamed only on completion. Rate limits honour `Retry-After` (seconds
+or an HTTP date); transient server/network failures retry with bounded delays.
+
+Concurrent CLI runs and MCP calls sharing a state directory skip sources owned
+by another run immediately (`in_progress_elsewhere`), without failing or stopping
+the batch; other files proceed in parallel. Rerun later to pick up the result:
+the saved request and job are reused, so nothing is duplicated. Per-source leases
+refresh every 30 seconds for at most six hours; unrefreshed leases expire after
+two minutes, and dead local owners are recovered immediately. Short state-file
+transactions have no heartbeat and wait at most 60 seconds before `state_locked`.
+
+## MCP
+
+Either run `npx upscale4k login` once in a terminal, or give the server
+`UPSCALE4K_API_KEY`.
+MCP never accepts likeness consent on the user's behalf. Stdio stdout contains
+protocol messages only.
+
+Headless setup, for example Claude Code:
+
+```sh
+claude mcp add upscale4k -e UPSCALE4K_API_KEY=cx_live_... -- npx -y upscale4k mcp
+```
+
+Claude Code:
+
+```sh
+claude mcp add upscale4k -- npx -y upscale4k mcp
+```
+
+Claude Desktop config:
+
+```json
+{
+  "mcpServers": {
+    "upscale4k": { "command": "npx", "args": ["-y", "upscale4k", "mcp"] }
+  }
+}
+```
+
+Cursor `.cursor/mcp.json`:
+
+```json
+{
+  "mcpServers": {
+    "upscale4k": { "command": "npx", "args": ["-y", "upscale4k", "mcp"] }
+  }
+}
+```
+
+If your Windows MCP host cannot resolve `npx`, use `"command": "cmd"` and
+`"args": ["/c", "npx", "-y", "upscale4k", "mcp"]` instead.
+
+Five tools: `upscale_video({path,self_likeness,self_likeness_consent?,output_dir?,wait?})`,
+`get_job({job_id})`, `list_jobs({state?,limit?})`, `get_account()`, and
+`download_result({job_id,output_dir})`. Every tool returns JSON text and the same value as `structuredContent`.
+Upscale defaults to waiting and returns an array of
+`{source,output_path|job_id,state,error?}` (in `structuredContent` as `{results:[...]}`).
+A client progress token enables progress notifications. Downloading by job ID
+names the file `<original name> 4K.mp4`, or `<job_id> 4K.mp4` when the name is unknown.
+Cancelled tool handlers return an `isError` result with error code `cancelled`.
+The MCP SDK suppresses responses after protocol cancellation; SDK clients abort
+their pending call locally while the server stops work and releases its leases.
+
+`npx upscale4k status` prints the active-job count and account cap (`unlimited`
+when `max_active` is null), followed by one readable line per job. A job ID prints
+only that job's line. Add `--json` for the raw response; account fields and null
+caps remain unchanged in `credits --json` and MCP `get_account`.
+
+## Errors
+
+| Code | Action |
+| --- | --- |
+| `invalid_api_key` | Run `npx upscale4k login` with a valid, unrevoked key. |
+| `consent_required` | Ask the user about likeness and supply explicit consent when it applies. |
+| `consent_outdated` | Inspect the server response and saved job; login does not accept terms. |
+| `api_locked` | Unlock API access in your Upscale4K account, then rerun. |
+| `account_suspended` | Contact Upscale4K support. |
+| `no_credits` | Add credits and rerun; the batch stops early. |
+| `daily_limit` | Wait for the next daily allowance; the batch stops early. |
+| `active_limit` | Wait for active jobs to finish or lower concurrency. |
+| `engine_unavailable` | Check engine access and maintenance in your Upscale4K account, then retry later. |
+| `key_limit` | Revoke an unused API key in your account before creating another. |
+| `rate_limited` | Retried automatically according to `Retry-After`; rerun if exhausted. |
+| `validation_error`, `duration_limit`, `resolution_limit`, `frame_rate_limit` | Check input format, dimensions, byte size, frame rate and account duration cap. |
+| `idempotency_required`, `idempotency_mismatch` | Preserve the state file and exact request; report persistent contract errors. |
+| `not_found`, `expired` | Inspect job status and result retention. |
+| `conflict` | Inspect job state or the saved upload's consent choice. |
+| `locked_for_review` | Wait for review or contact support. |
+| `uploads_closed` | Wait until account uploads reopen. |
+| `range_not_satisfiable` | The requested download byte range is invalid; this client restarts full downloads. |
+| `resume_ambiguous` | Inspect the old job; no duplicate is created automatically. |
+| `network_error` | Check connectivity and rerun the same command to resume. |
+| `upgrade_required` | Rerun with `npx -y upscale4k@latest` to resume. |
+
+REST v1 is defined in `src/api-contract.ts`. This package is verified against a
+local fake v1 server; a live server acceptance run and npm publication are separate.

package/dist/api-client.d.ts

@@ -0,0 +1,52 @@
+import { type Account, type CanceledJob, type CreateJobBody, type CreatedJob, type Job, type JobList, type MultipartCompleted, type SubmittedJob } from "./api-contract.js";
+export declare class ApiError extends Error {
+    code: string;
+    status: number;
+    constructor(code: string, message: string, status?: number);
+}
+export declare function throwIfCancelled(signal?: AbortSignal): void;
+export declare const sleep: (ms: number, signal?: AbortSignal) => Promise<void>;
+/** True when dotted version a sorts before b; non-numeric parts never count as older. */
+export declare function versionOlder(a: string, b: string): boolean;
+interface Options {
+    baseUrl?: string;
+    attempts?: number;
+    sleep?: (ms: number, signal?: AbortSignal) => Promise<void>;
+    /** Receives the one-time update notice; stderr by default so --json stdout and MCP stdio stay clean. */
+    notice?: (message: string) => void;
+}
+export declare class ApiClient {
+    private readonly key;
+    readonly baseUrl: string;
+    private readonly attempts;
+    private readonly pause;
+    private readonly notice;
+    private readonly userAgent;
+    private noticeShown;
+    constructor(key: string, options?: Options);
+    private safe;
+    get keyPrefix(): string;
+    private requestSignal;
+    private retry;
+    /** The API names its newest CLI in x-upscale4k-latest; tell the user once per run when this one is older. */
+    private noteLatest;
+    private checked;
+    private json;
+    me(signal?: AbortSignal): Promise<Account>;
+    create(body: CreateJobBody, key: string, signal?: AbortSignal): Promise<CreatedJob>;
+    submit(id: string, signal?: AbortSignal): Promise<SubmittedJob>;
+    getJob(id: string, signal?: AbortSignal): Promise<Job>;
+    listJobs(query?: {
+        state?: string;
+        limit?: number;
+        cursor?: string;
+    }): Promise<JobList>;
+    cancel(id: string): Promise<CanceledJob>;
+    retryJob(id: string, key: string): Promise<Job>;
+    upload(created: CreatedJob, file: string, size: number, signal?: AbortSignal): Promise<void>;
+    /** Upload a long job's file in parts and complete it, which queues the job; replaying complete is safe. */
+    uploadLong(created: CreatedJob, file: string, size: number, signal?: AbortSignal, parallel?: number): Promise<MultipartCompleted>;
+    private putPart;
+    download(id: string, output: string, relativeUrl?: string | null, signal?: AbortSignal): Promise<void>;
+}
+export {};

package/dist/api-client.js

@@ -0,0 +1,258 @@
+/** Stream REST v1 transfers, retrying only safe/idempotent requests. */
+import { createReadStream, createWriteStream } from "node:fs";
+import { mkdir, rename } from "node:fs/promises";
+import { dirname } from "node:path";
+import { Readable } from "node:stream";
+import { pipeline } from "node:stream/promises";
+import { DEFAULT_API_URL, VERSION, paths, } from "./api-contract.js";
+export class ApiError extends Error {
+    code;
+    status;
+    constructor(code, message, status = 0) {
+        super(message);
+        this.code = code;
+        this.status = status;
+    }
+}
+export function throwIfCancelled(signal) {
+    if (signal?.aborted)
+        throw new ApiError("cancelled", "Upscale cancelled; rerun the same command to resume.");
+}
+export const sleep = (ms, signal) => new Promise((resolve, reject) => {
+    try {
+        throwIfCancelled(signal);
+    }
+    catch (error) {
+        reject(error);
+        return;
+    }
+    const abort = () => { clearTimeout(timer); signal?.removeEventListener("abort", abort); reject(new ApiError("cancelled", "Upscale cancelled; rerun the same command to resume.")); };
+    const timer = setTimeout(() => { signal?.removeEventListener("abort", abort); resolve(); }, ms);
+    signal?.addEventListener("abort", abort, { once: true });
+});
+/** True when dotted version a sorts before b; non-numeric parts never count as older. */
+export function versionOlder(a, b) {
+    const x = a.split(".").map(Number), y = b.split(".").map(Number);
+    for (let index = 0; index < 3; index++)
+        if (x[index] !== y[index])
+            return x[index] < y[index];
+    return false;
+}
+const writeNotice = (message) => { process.stderr.write(`${message}\n`); };
+export class ApiClient {
+    key;
+    baseUrl;
+    attempts;
+    pause;
+    notice;
+    userAgent = `upscale4k/${VERSION} node/${process.versions.node}`;
+    noticeShown = false;
+    constructor(key, options = {}) {
+        this.key = key;
+        this.baseUrl = options.baseUrl ?? process.env.UPSCALE4K_API_URL ?? DEFAULT_API_URL;
+        this.attempts = options.attempts ?? 5;
+        this.pause = options.sleep ?? sleep;
+        this.notice = options.notice ?? writeNotice;
+    }
+    safe(message) { return this.key ? message.split(this.key).join("[redacted]") : message; }
+    get keyPrefix() { return this.key.slice(0, 12); }
+    requestSignal(signal) {
+        const timeout = AbortSignal.timeout(120_000);
+        return signal ? AbortSignal.any([signal, timeout]) : timeout;
+    }
+    async retry(operation, signal) {
+        for (let attempt = 0;; attempt++) {
+            throwIfCancelled(signal);
+            try {
+                const result = await operation();
+                throwIfCancelled(signal);
+                return result;
+            }
+            catch (error) {
+                throwIfCancelled(signal);
+                const retryable = !(error instanceof ApiError) || error.code === "rate_limited" || error.status >= 500;
+                if (!retryable || attempt >= this.attempts - 1) {
+                    if (error instanceof ApiError)
+                        throw error;
+                    throw new ApiError("network_error", "Network or transfer failed; rerun to resume safely.");
+                }
+                const delay = (error instanceof RetryError ? error.delay : undefined) ?? Math.min(30_000, 500 * 2 ** attempt);
+                await this.pause(delay, signal);
+            }
+        }
+    }
+    /** The API names its newest CLI in x-upscale4k-latest; tell the user once per run when this one is older. */
+    noteLatest(response) {
+        // Server versioning contract: /api/v1/* sets x-upscale4k-latest and retires User-Agents with 426 upgrade_required.
+        // Upscale4K web does not send it yet; an absent header means no notice.
+        const latest = response.headers.get("x-upscale4k-latest");
+        if (this.noticeShown || !latest || !/^\d+\.\d+\.\d+$/.test(latest) || !versionOlder(VERSION, latest))
+            return;
+        this.noticeShown = true;
+        this.notice(`upscale4k ${latest} is available (this is ${VERSION}). Update with: npx -y upscale4k@latest`);
+    }
+    async checked(response) {
+        this.noteLatest(response);
+        if (response.ok)
+            return response;
+        const payload = await response.json().catch(() => undefined);
+        const code = payload?.error?.code ?? `http_${response.status}`;
+        const messages = {
+            engine_unavailable: "The requested Upscale4K engine is unavailable for this account or under maintenance. Check your account and try again later.",
+            key_limit: "Your Upscale4K account has reached its API key limit. Revoke an unused key before creating another.",
+        };
+        const message = this.safe(payload?.error?.message ?? messages[code] ?? `HTTP ${response.status}`);
+        const header = response.headers.get("retry-after");
+        const seconds = header === null ? NaN : Number(header);
+        const delay = Number.isFinite(seconds) ? seconds * 1000 : header ? Date.parse(header) - Date.now() : NaN;
+        if (response.status === 429 && code === "rate_limited" || response.status >= 500) {
+            throw new RetryError(code, message, response.status, Number.isFinite(delay) ? Math.max(0, delay) : undefined);
+        }
+        throw new ApiError(code, message, response.status);
+    }
+    async json(path, method = "GET", body, key, signal) {
+        return this.retry(async () => {
+            const response = await this.checked(await fetch(new URL(path, this.baseUrl), {
+                method, redirect: "error", signal: this.requestSignal(signal),
+                headers: { Authorization: `Bearer ${this.key}`, "User-Agent": this.userAgent, ...(body === undefined ? {} : { "Content-Type": "application/json" }),
+                    ...(key ? { "Idempotency-Key": key } : {}) },
+                body: body === undefined ? undefined : JSON.stringify(body),
+            }));
+            return await response.json();
+        }, signal);
+    }
+    me(signal) { return this.json(paths.me, "GET", undefined, undefined, signal); }
+    create(body, key, signal) { return this.json(paths.jobs, "POST", body, key, signal); }
+    submit(id, signal) { return this.json(paths.submit(id), "POST", undefined, undefined, signal); }
+    getJob(id, signal) { return this.json(paths.job(id), "GET", undefined, undefined, signal); }
+    listJobs(query = {}) {
+        const params = new URLSearchParams();
+        for (const [key, value] of Object.entries(query))
+            if (value !== undefined)
+                params.set(key, String(value));
+        return this.json(`${paths.jobs}?${params}`);
+    }
+    cancel(id) { return this.json(paths.cancel(id), "POST"); }
+    retryJob(id, key) { return this.json(paths.retry(id), "POST", {}, key); }
+    async upload(created, file, size, signal) {
+        await this.retry(async () => {
+            // A new stream per attempt is essential: fetch consumes the previous one.
+            const stream = createReadStream(file);
+            // Headers.set replaces any server-sent content-length whatever its case; Node 24+ rejects duplicates.
+            const headers = new Headers(created.upload_headers ?? {});
+            headers.set("Content-Length", String(size));
+            try {
+                if (!created.upload_url || created.upload_method !== "PUT")
+                    throw new ApiError("validation_error", "This job uploads in parts; use uploadLong.");
+                const response = await this.checked(await fetch(created.upload_url, {
+                    method: "PUT", redirect: "error", signal: this.requestSignal(signal),
+                    headers,
+                    body: stream, duplex: "half",
+                }));
+                await response.arrayBuffer();
+            }
+            finally {
+                stream.destroy();
+            }
+        }, signal);
+    }
+    /** Upload a long job's file in parts and complete it, which queues the job; replaying complete is safe. */
+    async uploadLong(created, file, size, signal, parallel = 4) {
+        const call = async (body) => {
+            try {
+                return await this.json(paths.multipart(created.id), "POST", body, undefined, signal);
+            }
+            catch (error) {
+                if (error instanceof ApiError && error.status === 404)
+                    throw new ApiError("not_found", "Long-video multipart upload is not yet available through the Upscale4K API. The server advertised multipart upload but its endpoint is unavailable; inspect the saved job before retrying.", 404);
+                throw error;
+            }
+        };
+        const { upload_id, part_size, completed } = await call({ action: "create" });
+        // Already assembled by an earlier run whose admission failed: only retry admission.
+        if (completed)
+            return call({ action: "complete", upload_id, parts: [] });
+        if (!Number.isSafeInteger(part_size) || part_size <= 0)
+            throw new ApiError("validation_error", "Server returned an invalid part size.");
+        const total = Math.max(1, Math.ceil(size / part_size)), etags = new Map();
+        // Sign at most 20 parts per call; each call also renews the 30-minute upload idle timer.
+        for (let first = 1; first <= total; first += 20) {
+            const batch = Array.from({ length: Math.min(20, total - first + 1) }, (_, i) => first + i);
+            const { urls } = await call({ action: "sign", upload_id, parts: batch });
+            // One failed part stops its siblings, and every transfer settles before the error leaves this call.
+            const stop = new AbortController(), partSignal = signal ? AbortSignal.any([signal, stop.signal]) : stop.signal;
+            let next = 0, failure;
+            const worker = async () => {
+                while (next < batch.length && !stop.signal.aborted) {
+                    const part = batch[next++], url = urls[String(part)];
+                    try {
+                        if (!url)
+                            throw new ApiError("validation_error", `Server did not sign part ${part}.`);
+                        const start = (part - 1) * part_size, end = Math.min(size, start + part_size) - 1;
+                        etags.set(part, await this.putPart(url, file, start, end, partSignal));
+                    }
+                    catch (error) {
+                        if (!stop.signal.aborted) {
+                            failure = error;
+                            stop.abort();
+                        }
+                    }
+                }
+            };
+            await Promise.all(Array.from({ length: Math.min(parallel, batch.length) }, worker));
+            throwIfCancelled(signal);
+            if (failure !== undefined)
+                throw failure;
+        }
+        const parts = [...etags].sort(([a], [b]) => a - b).map(([part, etag]) => ({ part, etag }));
+        return call({ action: "complete", upload_id, parts });
+    }
+    async putPart(url, file, start, end, signal) {
+        return this.retry(async () => {
+            const stream = createReadStream(file, { start, end });
+            try {
+                // The presigned part URL carries its own authorization; never send the Bearer key to storage.
+                const response = await this.checked(await fetch(url, {
+                    method: "PUT", redirect: "error", signal: this.requestSignal(signal),
+                    headers: { "Content-Length": String(end - start + 1) },
+                    body: stream, duplex: "half",
+                }));
+                await response.arrayBuffer();
+                const etag = response.headers.get("etag");
+                if (!etag)
+                    throw new Error("Storage returned no ETag");
+                return etag;
+            }
+            finally {
+                stream.destroy();
+            }
+        }, signal);
+    }
+    async download(id, output, relativeUrl = paths.download(id), signal) {
+        throwIfCancelled(signal);
+        if (relativeUrl === null)
+            throw new ApiError("expired", "This Upscale4K job has no downloadable result. Check its status and result retention before retrying.");
+        const url = new URL(relativeUrl, this.baseUrl);
+        if (url.origin !== new URL(this.baseUrl).origin || !relativeUrl.startsWith("/")) {
+            throw new ApiError("validation_error", "Download URL must be a relative API path.");
+        }
+        await mkdir(dirname(output), { recursive: true });
+        await this.retry(async () => {
+            const response = await this.checked(await fetch(url, {
+                headers: { Authorization: `Bearer ${this.key}`, "User-Agent": this.userAgent }, redirect: "error", signal: this.requestSignal(signal),
+            }));
+            if (!response.body)
+                throw new Error("Missing download body");
+            await pipeline(Readable.fromWeb(response.body), createWriteStream(`${output}.part`), { signal });
+            throwIfCancelled(signal);
+            await rename(`${output}.part`, output);
+        }, signal);
+    }
+}
+class RetryError extends ApiError {
+    delay;
+    constructor(code, message, status, delay) {
+        super(code, message, status);
+        this.delay = delay;
+    }
+}

package/dist/api-contract.d.ts

@@ -0,0 +1,120 @@
+/** Upscale4K REST v1 wire types and paths; align future server changes here. */
+export declare const DEFAULT_API_URL = "https://upscale4k.io";
+export declare const VERSION = "0.1.0";
+export declare const MAX_UPLOAD_BYTES: number;
+export declare const MIN_LONG_SIDE = 500;
+export declare const MAX_LONG_SIDE = 2560;
+export declare const paths: {
+    me: string;
+    jobs: string;
+    job: (id: string) => string;
+    submit: (id: string) => string;
+    cancel: (id: string) => string;
+    retry: (id: string) => string;
+    download: (id: string) => string;
+    multipart: (id: string) => string;
+};
+export declare const errorCodes: readonly ["invalid_api_key", "api_locked", "account_suspended", "rate_limited", "validation_error", "duration_limit", "resolution_limit", "frame_rate_limit", "no_credits", "daily_limit", "active_limit", "idempotency_required", "idempotency_mismatch", "not_found", "conflict", "expired", "locked_for_review", "uploads_closed", "consent_required", "consent_outdated", "range_not_satisfiable", "upgrade_required", "storage_unavailable", "engine_unavailable", "key_limit"];
+export type ErrorCode = typeof errorCodes[number];
+export interface ErrorEnvelope {
+    error: {
+        code: ErrorCode;
+        message: string;
+        [key: string]: unknown;
+    };
+}
+export interface Account {
+    email: string;
+    tier: string;
+    credits: {
+        free: number;
+        mine: number;
+    };
+    max_seconds: number;
+    daily_used: number;
+    daily_cap: number | null;
+    active_count: number;
+    max_active: number | null;
+    engines?: string[];
+    engines_maintenance?: string[];
+    rate_per_minute?: number;
+    api_daily_jobs?: {
+        used: number;
+        limit: number | null;
+    };
+    limits?: Pick<Account, "max_seconds" | "daily_used" | "daily_cap" | "active_count" | "max_active" | "rate_per_minute">;
+    access: {
+        unlocked: boolean;
+        reason: string | null;
+    };
+    /** Absent on servers older than long-video API support; treat that as short clips only. */
+    long_video?: {
+        enabled: boolean;
+        eligible: boolean;
+        min_seconds: number;
+        max_upload_bytes: number;
+        max_seconds: Record<string, number>;
+    };
+    consent: {
+        terms_version?: string;
+        policy_version?: string;
+        statement?: string;
+        self_likeness_statement: string;
+    };
+}
+export interface VideoInfo {
+    duration: number;
+    width: number;
+    height: number;
+}
+export interface UploadConsent {
+    selfLikeness: boolean;
+    selfLikenessConsent?: true;
+    terms?: true;
+    termsVersion?: string;
+    policyVersion?: string;
+}
+export interface CreateJobBody extends VideoInfo {
+    filename: string;
+    size: number;
+    consent: UploadConsent;
+}
+export interface CreatedJob {
+    id: string;
+    kind?: "single" | "long";
+    upload_url: string | null;
+    upload_method: "PUT" | "multipart";
+    multipart_url?: string;
+    upload_headers: Record<string, string> | null;
+    expires_in: number;
+}
+export interface MultipartCreated {
+    upload_id: string;
+    part_size: number;
+    completed?: true;
+}
+export interface MultipartCompleted {
+    ok: true;
+    state: JobState;
+}
+export declare const jobStates: readonly ["uploading", "queued", "claimed", "running", "done", "failed", "rejected", "canceled", "expired"];
+export type JobState = typeof jobStates[number];
+export interface Job {
+    id: string;
+    filename?: string;
+    state: JobState;
+    progress?: number;
+    queue_position?: number | null;
+    error?: string | ErrorEnvelope["error"] | null;
+    expires_at?: string | number | null;
+    download_url?: string | null;
+}
+export interface JobList {
+    jobs: Job[];
+    next_cursor: string | null;
+}
+export type SubmittedJob = Pick<Job, "state" | "queue_position">;
+export interface CanceledJob {
+    ok: true;
+    state: "canceled";
+}