@neta-art/cohub-cli 3.11.0 → 4.0.0

package/dist/commands/boards/nodes.d.ts

@@ -0,0 +1,3 @@
+import type { Command } from "commander";
+/** Connection shortcuts; Item authoring lives in ./items.ts. */
+export declare function registerBoardNodeCommands(boards: Command): void;

package/dist/commands/boards/nodes.js

@@ -0,0 +1,53 @@
+import { randomUUID } from "node:crypto";
+import { createBoardConnection } from "@neta-art/cohub/board";
+import { handleHttp } from "../../output.js";
+import { resolvedBoard, showUpdated, withJson, } from "./context.js";
+/** Connection shortcuts; Item authoring lives in ./items.ts. */
+export function registerBoardNodeCommands(boards) {
+    withJson(boards.command("connect <board> <source> <target>")
+        .description("Connect two Board items")
+        .option("--id <id>", "Connection id")
+        .option("--relation <relation>", "Relation type")
+        .option("--direction <direction>", "none, forward, backward, or both", "forward")
+        .option("--label <label>", "Connection label")
+        .option("--source-port <id>", "Source port id")
+        .option("--target-port <id>", "Target port id"))
+        .action(async (target, source, destination, options) => {
+        try {
+            const direction = options.direction ?? "forward";
+            if (!["none", "forward", "backward", "both"].includes(direction)) {
+                throw new Error("--direction must be none, forward, backward, or both");
+            }
+            const board = await resolvedBoard(boards, target);
+            const connection = createBoardConnection({
+                id: options.id ?? randomUUID(),
+                sourceNodeId: source,
+                targetNodeId: destination,
+                relation: options.relation,
+                direction: direction,
+                label: options.label,
+                sourcePortId: options.sourcePort,
+                targetPortId: options.targetPort,
+            });
+            showUpdated(await board.mutate({
+                build: () => [{ type: "connection.create", payload: { connection } }],
+            }), options);
+        }
+        catch (cause) {
+            handleHttp(cause);
+        }
+    });
+    withJson(boards.command("disconnect <board> <connection-id>")
+        .description("Remove a Board connection"))
+        .action(async (target, connectionId, options) => {
+        try {
+            const board = await resolvedBoard(boards, target);
+            showUpdated(await board.mutate({
+                build: () => [{ type: "connection.delete", payload: { connectionId } }],
+            }), options);
+        }
+        catch (cause) {
+            handleHttp(cause);
+        }
+    });
+}

package/dist/commands/boards.d.ts

@@ -1,9 +1,10 @@
 import type { BoardInspectInput, BoardTransactionInput } from "@neta-art/cohub";
 import type { Command } from "commander";
-declare const INSPECT_SECTIONS: readonly ["nodes", "connections", "effects", "sequences", "clips", "playback"];
+import { parseBoardJsonObject } from "../board-command-support.js";
+declare const INSPECT_SECTIONS: readonly ["nodes", "connections", "effects", "compositions", "playback"];
 type InspectSection = (typeof INSPECT_SECTIONS)[number];
-export declare function parseJsonObject(text: string, source?: string): Record<string, unknown>;
-export declare function readJsonObject(source: string): Promise<Record<string, unknown>>;
+export declare const parseJsonObject: typeof parseBoardJsonObject;
+export declare function readJsonObject(source: string, maxBytes?: number): Promise<Record<string, unknown>>;
 export declare function parseInspectSections(value?: string): InspectSection[] | undefined;
 export declare function parseViewport(value?: string): BoardInspectInput["viewport"];
 export declare function createTransactionInput(input: Record<string, unknown>, options: {

package/dist/commands/boards.js

@@ -1,36 +1,14 @@
 import { randomUUID } from "node:crypto";
-import { readFile, writeFile } from "node:fs/promises";
+import { BOARD_CREATE_INPUT_MAX_BYTES, BOARD_TRANSACTION_INPUT_MAX_BYTES, parseBoardJsonObject, readBoardJsonObject, resolveBoardId, writeBoardOutput, } from "../board-command-support.js";
 import { BOARD_EXPORT_FORMATS, formatFromPath, runBoardExport } from "../board-export.js";
+import { registerBoardDomainCommands } from "./board-domain.js";
 import { createClient, createRealtimeClient } from "../client.js";
 import { error, handleHttp, json as outJson, jsonRequested, ok, table } from "../output.js";
 import { resolveSpace } from "../space.js";
-const INSPECT_SECTIONS = ["nodes", "connections", "effects", "sequences", "clips", "playback"];
-function isObject(value) {
-    return Boolean(value) && typeof value === "object" && !Array.isArray(value);
-}
-export function parseJsonObject(text, source = "input") {
-    if (!text.trim())
-        throw new Error(`${source} is empty`);
-    let value;
-    try {
-        value = JSON.parse(text);
-    }
-    catch (cause) {
-        throw new Error(`${source} must contain valid JSON`, { cause });
-    }
-    if (!isObject(value))
-        throw new Error(`${source} must contain a JSON object`);
-    return value;
-}
-async function readStdin() {
-    const chunks = [];
-    for await (const chunk of process.stdin)
-        chunks.push(Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk));
-    return Buffer.concat(chunks).toString("utf8");
-}
-export async function readJsonObject(source) {
-    const text = source === "-" ? await readStdin() : await readFile(source, "utf8");
-    return parseJsonObject(text, source === "-" ? "stdin" : source);
+const INSPECT_SECTIONS = ["nodes", "connections", "effects", "compositions", "playback"];
+export const parseJsonObject = parseBoardJsonObject;
+export async function readJsonObject(source, maxBytes = BOARD_TRANSACTION_INPUT_MAX_BYTES) {
+    return readBoardJsonObject(source, maxBytes);
 }
 function parseNumber(value, name, options = {}) {
     if (!value.trim())
@@ -102,8 +80,7 @@ function showBoard(result) {
             nodes: result.nodes.length,
             connections: result.connections.length,
             effects: result.effects.length,
-            sequences: result.sequences.length,
-            clips: result.clips.length,
+            compositions: result.compositions.length,
         },
     ], [
         { key: "id", label: "ID" },
@@ -112,8 +89,28 @@ function showBoard(result) {
         { key: "nodes", label: "Nodes" },
         { key: "connections", label: "Connections" },
         { key: "effects", label: "Effects" },
-        { key: "sequences", label: "Sequences" },
-        { key: "clips", label: "Clips" },
+        { key: "compositions", label: "Compositions" },
+    ]);
+}
+function showSummary(result) {
+    const background = result.board.metadata.appearance;
+    table([{
+            id: result.board.id,
+            title: result.board.title,
+            version: result.board.version,
+            ...result.counts,
+            background: background?.background?.kind ?? "default",
+            updatedAt: result.board.updatedAt,
+        }], [
+        { key: "id", label: "ID" },
+        { key: "title", label: "TITLE" },
+        { key: "version", label: "VERSION" },
+        { key: "nodes", label: "NODES" },
+        { key: "connections", label: "CONNECTIONS" },
+        { key: "effects", label: "EFFECTS" },
+        { key: "compositions", label: "COMPOSITIONS" },
+        { key: "background", label: "BACKGROUND" },
+        { key: "updatedAt", label: "UPDATED" },
     ]);
 }
 function showValidation(result) {
@@ -136,7 +133,7 @@ function showValidation(result) {
 function showPlayback(result) {
     table([result], [
         { key: "playbackId", label: "Playback ID" },
-        { key: "sequenceId", label: "Sequence" },
+        { key: "compositionId", label: "Composition" },
         { key: "status", label: "Status" },
         { key: "position", label: "Position" },
         { key: "timeScale", label: "Time Scale" },
@@ -145,24 +142,45 @@ function showPlayback(result) {
 function withJson(command) {
     return command.option("--json", "Output as JSON");
 }
+function capabilityUnits(schema) {
+    const params = schema?.params;
+    if (!params || typeof params !== "object" || Array.isArray(params))
+        return "";
+    return Object.entries(params).flatMap(([field, value]) => {
+        if (!value || typeof value !== "object" || Array.isArray(value))
+            return [];
+        const meta = value;
+        const detail = [meta.coordinateSpace, meta.unit]
+            .filter((item) => typeof item === "string")
+            .join("/");
+        return detail ? [`${field}:${detail}`] : [];
+    }).join(", ");
+}
 function registerTransactionCommand(boards, name) {
-    withJson(boards.command(`${name} <board-id>`)
+    withJson(boards.command(`${name} <board>`)
         .description(name === "validate" ? "Validate a transaction" : "Apply a transaction")
         .requiredOption("-i, --input <file>", "Transaction JSON file; use - for stdin")
         .option("--tx-id <id>", "Override txId; generated when omitted")
-        .option("--base-version <version>", "Override baseVersion"))
-        .action(async (boardId, options) => {
+        .option("--base-version <version>", "Override baseVersion")
+        .addHelpText("after", `
+Input example:
+  {"baseVersion":12,"operations":[{"type":"board.patch","payload":{"patch":{"title":"Launch plan"}}}]}
+
+Prefer semantic commands such as boards background, nodes, effects, or compositions for common edits.`))
+        .action(async (target, options) => {
         try {
-            const transaction = createTransactionInput(await readJsonObject(options.input), options);
-            const board = createClient().space(resolveSpace(boards)).board(boardId);
+            const transaction = createTransactionInput(await readJsonObject(options.input, BOARD_TRANSACTION_INPUT_MAX_BYTES), options);
+            const spaceId = resolveSpace(boards);
+            const boardId = await resolveBoardId(spaceId, target);
+            const board = createClient().space(spaceId).board(boardId);
             const result = await board[name](transaction);
             if (jsonRequested(options))
                 return outJson(result);
             if (name === "validate")
                 showValidation(result);
             else {
-                ok(`Board updated to version ${result.board.version}`);
-                showBoard(result);
+                const receipt = result;
+                ok(`Board updated to version ${receipt.board.version}`);
             }
         }
         catch (cause) {
@@ -240,7 +258,8 @@ function registerExportCommand(boards) {
         .option("--background <mode>", "paper or transparent", "paper")
         .option("--format <format>", `Override format (${BOARD_EXPORT_FORMATS.join(", ")})`)
         .option("--quality <q>", "JPEG/WebP quality from 0 to 1", "0.92")
-        .option("--no-images", "Skip image downloads and draw placeholders"))
+        .option("--no-images", "Skip image downloads and draw placeholders")
+        .option("--force", "Replace an existing output file"))
         .action(async (board, options) => {
         try {
             const out = options.out;
@@ -263,7 +282,7 @@ function registerExportCommand(boards) {
             if (!result) {
                 return error("Nothing to export", "The selected region contains no items.");
             }
-            await writeFile(out, result.bytes);
+            await writeBoardOutput(out, result.bytes, Boolean(options.force));
             if (jsonRequested(options)) {
                 return outJson({
                     path: out,
@@ -293,14 +312,26 @@ export function registerBoards(program) {
     withJson(boards.command("create <path>")
         .description("Create a Board")
         .option("--title <title>", "Board title")
-        .option("-i, --input <file>", "Board content JSON file; use - for stdin"))
+        .option("--mutation-id <id>", "Stable id for safe retries")
+        .option("-i, --input <file>", "BoardCreateInput fields; use - for stdin")
+        .addHelpText("after", `
+For normal use, create an empty Board and add content with boards nodes, effects, and compositions.
+--input is intended for bulk creation and accepts BoardCreateInput fields except path and title.`))
         .action(async (path, options) => {
         try {
-            const content = options.input ? await readJsonObject(options.input) : {};
+            const content = options.input
+                ? await readJsonObject(options.input, BOARD_CREATE_INPUT_MAX_BYTES)
+                : {};
             if ("path" in content || "title" in content) {
                 throw new Error("create input must not contain path or title; use the command argument and --title");
             }
-            const input = { ...content, path, ...(options.title ? { title: options.title } : {}) };
+            const input = {
+                ...content,
+                path,
+                mutationId: options.mutationId ??
+                    (typeof content.mutationId === "string" ? content.mutationId : randomUUID()),
+                ...(options.title ? { title: options.title } : {}),
+            };
             const result = await createClient().space(resolveSpace(boards)).boards.create(input);
             if (jsonRequested(options))
                 return outJson(result);
@@ -311,14 +342,20 @@ export function registerBoards(program) {
             handleHttp(cause);
         }
     });
-    withJson(boards.command("inspect <board-id>")
+    withJson(boards.command("inspect <board>")
         .alias("get")
         .description("Inspect a Board")
-        .option("--include <sections>", "Comma-separated nodes,connections,effects,sequences,clips,playback")
+        .option("--include <sections>", "Comma-separated nodes,connections,effects,compositions,playback")
         .option("--viewport <rect>", "Viewport as x,y,width,height"))
-        .action(async (boardId, options) => {
+        .action(async (target, options) => {
         try {
-            const result = await createClient().space(resolveSpace(boards)).board(boardId).inspect({
+            const spaceId = resolveSpace(boards);
+            const boardId = await resolveBoardId(spaceId, target);
+            const board = createClient().space(spaceId).board(boardId);
+            if (!jsonRequested(options) && !options.include && !options.viewport) {
+                return showSummary(await board.summary());
+            }
+            const result = await board.inspect({
                 include: parseInspectSections(options.include),
                 viewport: parseViewport(options.viewport),
             });
@@ -330,21 +367,25 @@ export function registerBoards(program) {
             handleHttp(cause);
         }
     });
-    withJson(boards.command("capabilities <board-id>")
+    withJson(boards.command("capabilities <board>")
         .description("Show supported capabilities"))
-        .action(async (boardId, options) => {
+        .action(async (target, options) => {
         try {
-            const result = await createClient().space(resolveSpace(boards)).board(boardId).capabilities();
+            const spaceId = resolveSpace(boards);
+            const boardId = await resolveBoardId(spaceId, target);
+            const result = await createClient().space(spaceId).board(boardId).capabilities();
             if (jsonRequested(options))
                 return outJson(result);
             table(result.capabilities.map((capability) => ({
                 ...capability,
                 renderers: capability.renderers?.join(", ") ?? "",
+                coordinates: capabilityUnits(capability.schema),
             })), [
                 { key: "kind", label: "Kind" },
                 { key: "id", label: "ID" },
                 { key: "version", label: "Version" },
                 { key: "renderers", label: "Renderers" },
+                { key: "coordinates", label: "Coordinates / units" },
                 { key: "digest", label: "Digest" },
             ]);
             const nodes = result.nodes;
@@ -371,19 +412,22 @@ export function registerBoards(program) {
     });
     registerTransactionCommand(boards, "validate");
     registerTransactionCommand(boards, "apply");
+    registerBoardDomainCommands(boards);
     registerExportCommand(boards);
-    withJson(boards.command("play <board-id> <sequence-id>")
+    withJson(boards.command("play <board> <composition-id>")
         .description("Start shared playback")
         .option("--position <time>", "Initial position in milliseconds")
         .option("--time-scale <scale>", "Playback speed from 0 to 4")
         .option("--seed <seed>", "Deterministic playback seed")
         .option("--command-id <id>", "Idempotency command ID"))
-        .action(async (boardId, sequenceId, options) => {
+        .action(async (target, compositionId, options) => {
         try {
-            const result = await createClient().space(resolveSpace(boards)).board(boardId).play({
+            const spaceId = resolveSpace(boards);
+            const boardId = await resolveBoardId(spaceId, target);
+            const result = await createClient().space(spaceId).board(boardId).play({
                 commandId: commandId(options),
                 type: "play",
-                sequenceId,
+                compositionId,
                 shared: true,
                 ...(options.position === undefined ? {} : { position: parseNumber(options.position, "position", { min: 0 }) }),
                 ...(options.timeScale === undefined ? {} : { timeScale: parseNumber(options.timeScale, "timeScale", { min: Number.EPSILON, max: 4 }) }),
@@ -397,9 +441,11 @@ export function registerBoards(program) {
             handleHttp(cause);
         }
     });
-    const playbackAction = (type) => async (boardId, playbackId, options) => {
+    const playbackAction = (type) => async (target, playbackId, options) => {
         try {
-            const board = createClient().space(resolveSpace(boards)).board(boardId);
+            const spaceId = resolveSpace(boards);
+            const boardId = await resolveBoardId(spaceId, target);
+            const board = createClient().space(spaceId).board(boardId);
             const id = commandId(options);
             const result = type === "pause"
                 ? await board.pause({ commandId: id, type: "pause", playbackId })
@@ -412,16 +458,18 @@ export function registerBoards(program) {
             handleHttp(cause);
         }
     };
-    withJson(boards.command("pause <board-id> <playback-id>")
+    withJson(boards.command("pause <board> <playback-id>")
         .description("Pause playback")
         .option("--command-id <id>", "Idempotency command ID"))
         .action(playbackAction("pause"));
-    withJson(boards.command("seek <board-id> <playback-id> <position>")
+    withJson(boards.command("seek <board> <playback-id> <position>")
         .description("Seek playback")
         .option("--command-id <id>", "Idempotency command ID"))
-        .action(async (boardId, playbackId, position, options) => {
+        .action(async (target, playbackId, position, options) => {
         try {
-            const result = await createClient().space(resolveSpace(boards)).board(boardId).seek({
+            const spaceId = resolveSpace(boards);
+            const boardId = await resolveBoardId(spaceId, target);
+            const result = await createClient().space(spaceId).board(boardId).seek({
                 commandId: commandId(options),
                 type: "seek",
                 playbackId,
@@ -435,18 +483,32 @@ export function registerBoards(program) {
             handleHttp(cause);
         }
     });
-    withJson(boards.command("stop <board-id> <playback-id>")
+    withJson(boards.command("stop <board> <playback-id>")
         .description("Stop playback")
         .option("--command-id <id>", "Idempotency command ID"))
         .action(playbackAction("stop"));
-    withJson(boards.command("watch <board-id>")
+    withJson(boards.command("watch <board>")
         .description("Stream Board events"))
-        .action((boardId, options) => {
+        .action(async (target, options) => {
         try {
-            const board = createRealtimeClient().space(resolveSpace(boards)).board(boardId);
+            const spaceId = resolveSpace(boards);
+            const boardId = await resolveBoardId(spaceId, target);
+            const client = createRealtimeClient();
+            const board = client.space(spaceId).board(boardId);
             if (!jsonRequested(options))
                 process.stderr.write(`Listening for Board ${boardId} events...\n`);
-            board.subscribe({
+            const offConnection = client.onConnection((state) => {
+                if (jsonRequested(options)) {
+                    process.stdout.write(`${JSON.stringify({ type: "connection", ...state })}\n`);
+                }
+                else {
+                    const detail = state.state === "reconnecting" && state.attempt
+                        ? ` (attempt ${state.attempt})`
+                        : "";
+                    process.stderr.write(`${state.state}${detail}\n`);
+                }
+            });
+            const offBoard = board.subscribe({
                 event(event) {
                     if (jsonRequested(options)) {
                         process.stdout.write(`${JSON.stringify(event)}\n`);
@@ -456,13 +518,18 @@ export function registerBoards(program) {
                         process.stdout.write(`version ${event.payload.version}  transaction ${event.payload.txId}  operations ${event.payload.operations.length}\n`);
                     }
                     else if (event.type === "board.playback.changed") {
-                        process.stdout.write(`${event.payload.status}  sequence ${event.payload.sequenceId}  position ${event.payload.position}\n`);
+                        process.stdout.write(`${event.payload.status}  composition ${event.payload.compositionId}  position ${event.payload.position}\n`);
                     }
                     else {
                         process.stdout.write(`awareness ${event.payload.actorName}  ${event.payload.update.type}\n`);
                     }
                 },
             });
+            process.once("SIGINT", () => {
+                offBoard();
+                offConnection();
+                process.exit(0);
+            });
         }
         catch (cause) {
             handleHttp(cause);

package/dist/commands/works.js

@@ -259,7 +259,7 @@ export function registerWorks(program) {
         .option("--status <status>", "Work status: published, disabled")
         .option("--visibility <visibility>", "Work visibility: public, space")
         .option("--work-scope <scope>", "Scope granted to the work runtime (space.view, session.view, file.view, taskrun.view)", collectOption, [])
-        .option("--viewer-scope <scope>", "Scope viewers may request (session.prompt.readonly, session.prompt.fullaccess, generation.create, user.space.list, user.session.list, user.usage.read)", collectOption, [])
+        .option("--viewer-scope <scope>", "Scope viewers may request (taskrun.view, session.prompt.readonly, session.prompt.fullaccess, generation.create, user.space.list, user.session.list, user.usage.read)", collectOption, [])
         .option("--meta <json>", "Work metadata as a JSON object")
         .option("--hide-cohub-bar", "Hide the Cohub footer bar on the public work page")
         .option("--show-cohub-bar", "Show the Cohub footer bar on the public work page")
@@ -338,7 +338,7 @@ export function registerWorks(program) {
         .option("--status <status>", "Work status: published, disabled")
         .option("--visibility <visibility>", "Work visibility: public, space")
         .option("--work-scope <scope>", "Scope granted to the work runtime (space.view, session.view, file.view, taskrun.view)", collectOption, [])
-        .option("--viewer-scope <scope>", "Scope viewers may request (session.prompt.readonly, session.prompt.fullaccess, generation.create, user.space.list, user.session.list, user.usage.read)", collectOption, [])
+        .option("--viewer-scope <scope>", "Scope viewers may request (taskrun.view, session.prompt.readonly, session.prompt.fullaccess, generation.create, user.space.list, user.session.list, user.usage.read)", collectOption, [])
         .option("--clear-work-scopes", "Clear work runtime scopes")
         .option("--clear-viewer-scopes", "Clear viewer-requestable scopes")
         .option("--meta <json>", "Work metadata as a JSON object")

package/dist/safe-remote-image.d.ts

@@ -0,0 +1,24 @@
+export declare const REMOTE_IMAGE_MAX_BYTES: number;
+export declare const REMOTE_IMAGE_TIMEOUT_MS = 15000;
+type ResolvedAddress = {
+    address: string;
+    family: 4 | 6;
+};
+type Lookup = (hostname: string) => Promise<readonly ResolvedAddress[]>;
+type RemoteResponse = {
+    status: number;
+    headers: Headers;
+    bytes: Uint8Array;
+};
+type Requester = (url: URL, address: ResolvedAddress, timeoutMs: number, maxBytes: number) => Promise<RemoteResponse>;
+export type RemoteImageDownloadOptions = {
+    lookup?: Lookup;
+    requester?: Requester;
+    maxBytes?: number;
+    timeoutMs?: number;
+};
+export declare function downloadPublicImage(input: string, options?: RemoteImageDownloadOptions): Promise<{
+    bytes: Uint8Array;
+    mimeType: string;
+}>;
+export {};

package/dist/safe-remote-image.js

@@ -0,0 +1,160 @@
+import dns from "node:dns/promises";
+import http from "node:http";
+import https from "node:https";
+import { isIP } from "node:net";
+import { isPublicBoardRemoteAddress, normalizeBoardRemoteUrl, } from "@neta-art/cohub/board";
+export const REMOTE_IMAGE_MAX_BYTES = 16 * 1024 * 1024;
+export const REMOTE_IMAGE_TIMEOUT_MS = 15_000;
+const MAX_REDIRECTS = 3;
+const IMAGE_MIME_TYPES = new Set([
+    "image/avif",
+    "image/gif",
+    "image/jpeg",
+    "image/png",
+    "image/webp",
+]);
+const REDIRECT_STATUSES = new Set([301, 302, 303, 307, 308]);
+async function defaultLookup(hostname) {
+    const records = await dns.lookup(hostname, { all: true, verbatim: true });
+    return records.map((record) => ({
+        address: record.address,
+        family: record.family,
+    }));
+}
+function responseHeaders(input) {
+    const headers = new Headers();
+    for (const [key, value] of Object.entries(input)) {
+        if (Array.isArray(value)) {
+            for (const item of value)
+                headers.append(key, item);
+        }
+        else if (value !== undefined) {
+            headers.set(key, value);
+        }
+    }
+    return headers;
+}
+function requestPinned(url, address, timeoutMs, maxBytes) {
+    return new Promise((resolve, reject) => {
+        const client = url.protocol === "https:" ? https : http;
+        const request = client.request(url, {
+            agent: false,
+            headers: { Accept: "image/avif,image/webp,image/png,image/jpeg,image/gif" },
+            lookup: (_hostname, _options, callback) => {
+                callback(null, address.address, address.family);
+            },
+        }, (response) => {
+            const status = response.statusCode ?? 0;
+            const headers = responseHeaders(response.headers);
+            if (REDIRECT_STATUSES.has(status)) {
+                response.resume();
+                resolve({ status, headers, bytes: new Uint8Array() });
+                return;
+            }
+            const declaredLength = Number(headers.get("content-length") ?? 0);
+            if (Number.isFinite(declaredLength) && declaredLength > maxBytes) {
+                response.destroy();
+                reject(new Error(`Image exceeds the ${maxBytes} byte download limit`));
+                return;
+            }
+            const chunks = [];
+            let total = 0;
+            response.on("data", (chunk) => {
+                total += chunk.byteLength;
+                if (total > maxBytes) {
+                    response.destroy(new Error(`Image exceeds the ${maxBytes} byte download limit`));
+                    return;
+                }
+                chunks.push(chunk);
+            });
+            response.once("error", reject);
+            response.once("end", () => {
+                const bytes = new Uint8Array(total);
+                let offset = 0;
+                for (const chunk of chunks) {
+                    bytes.set(chunk, offset);
+                    offset += chunk.byteLength;
+                }
+                resolve({ status, headers, bytes });
+            });
+        });
+        request.setTimeout(timeoutMs, () => {
+            request.destroy(new Error(`Image download timed out after ${timeoutMs}ms`));
+        });
+        request.once("error", reject);
+        request.end();
+    });
+}
+function remainingMs(deadline) {
+    const remaining = deadline - Date.now();
+    if (remaining <= 0)
+        throw new Error("Image download timed out");
+    return remaining;
+}
+async function withDeadline(promise, deadline) {
+    const timeoutMs = remainingMs(deadline);
+    let timer;
+    try {
+        return await Promise.race([
+            promise,
+            new Promise((_, reject) => {
+                timer = setTimeout(() => reject(new Error(`Image download timed out after ${timeoutMs}ms`)), timeoutMs);
+            }),
+        ]);
+    }
+    finally {
+        if (timer)
+            clearTimeout(timer);
+    }
+}
+async function resolvePublicUrl(value, lookup, deadline) {
+    const normalized = normalizeBoardRemoteUrl(value);
+    if (!normalized)
+        throw new Error("Image URL must be a public HTTP(S) URL");
+    const url = new URL(normalized);
+    const hostname = url.hostname.replace(/^\[|\]$/g, "");
+    const addresses = isIP(hostname)
+        ? [{ address: hostname, family: isIP(hostname) }]
+        : await withDeadline(lookup(hostname), deadline);
+    if (addresses.length === 0 ||
+        addresses.some((entry) => !isPublicBoardRemoteAddress(entry.address))) {
+        throw new Error("Image URL resolves to a private address");
+    }
+    return { url, address: addresses[0] };
+}
+export async function downloadPublicImage(input, options = {}) {
+    const lookup = options.lookup ?? defaultLookup;
+    const requester = options.requester ?? requestPinned;
+    const maxBytes = options.maxBytes ?? REMOTE_IMAGE_MAX_BYTES;
+    const deadline = Date.now() + (options.timeoutMs ?? REMOTE_IMAGE_TIMEOUT_MS);
+    let current = input;
+    for (let redirect = 0; redirect <= MAX_REDIRECTS; redirect += 1) {
+        const { url, address } = await resolvePublicUrl(current, lookup, deadline);
+        const response = await withDeadline(requester(url, address, remainingMs(deadline), maxBytes), deadline);
+        if (REDIRECT_STATUSES.has(response.status)) {
+            const location = response.headers.get("location");
+            if (!location)
+                throw new Error("Image redirect is missing a location");
+            if (redirect === MAX_REDIRECTS)
+                throw new Error("Too many image redirects");
+            current = new URL(location, url).toString();
+            continue;
+        }
+        if (response.status < 200 || response.status >= 300) {
+            throw new Error(`HTTP ${response.status}`);
+        }
+        if (response.bytes.byteLength > maxBytes) {
+            throw new Error(`Image exceeds the ${maxBytes} byte download limit`);
+        }
+        const mimeType = response.headers
+            .get("content-type")
+            ?.split(";", 1)[0]
+            ?.trim()
+            .toLowerCase();
+        if (!mimeType || !IMAGE_MIME_TYPES.has(mimeType)) {
+            throw new Error("Remote background must be a supported raster image");
+        }
+        return { bytes: response.bytes, mimeType };
+    }
+    throw new Error("Too many image redirects");
+}