@buildinternet/uploads 0.7.0 → 0.8.0

package/dist/mcp/server.d.ts

@@ -1,4 +1,4 @@
-export { optPosInt, optString, usage, type ToolArgs } from "./args.js";
+export { METADATA_DESCRIPTION, metadataProp, optPosInt, optString, optStringArray, optStringRecord, usage, type ToolArgs, } from "./args.js";
 export interface McpTool {
     name: string;
     description: string;

package/dist/mcp/server.js

@@ -8,7 +8,7 @@
  * stdio transport lives in ./stdio.ts; logs must never go to stdout.
  */
 import { UploadsError } from "../errors.js";
-export { optPosInt, optString, usage } from "./args.js";
+export { METADATA_DESCRIPTION, metadataProp, optPosInt, optString, optStringArray, optStringRecord, usage, } from "./args.js";
 const SUPPORTED_PROTOCOL_VERSIONS = new Set(["2025-06-18", "2025-03-26", "2024-11-05"]);
 const LATEST_PROTOCOL_VERSION = "2025-06-18";
 function response(id, result) {

package/dist/mcp/tools.js

@@ -5,19 +5,20 @@
  * per-call `workspace` argument behaves like the CLI's --workspace flag, and
  * a missing token surfaces as a tool error rather than a startup failure.
  */
-import { readFileSync } from "node:fs";
 import { basename } from "node:path";
 import { createUploadsClient } from "../client.js";
-import { buildDoctorReport, makeGhTarget, prepareImageForUpload, syncAttachmentsComment, } from "../commands.js";
+import { buildDoctorReport, makeGhTarget, prepareImageForUpload, readFileArg, syncAttachmentsComment, } from "../commands.js";
 import { resolveFrameId } from "../frame.js";
 import { resolveConfig, resolvePutDefaults, } from "../config.js";
 import { buildMarkdown } from "../embed.js";
+import { urlForGithubEmbed } from "../public-urls.js";
 import { resolvePutPrefix } from "../destinations.js";
-import { ghAttachmentKey, ghKeyPrefix } from "../github.js";
+import { ghAttachmentKey, ghKeyPrefix, ghMetadataFromTarget } from "../github.js";
+import { validateMetaMap } from "../metadata.js";
 import { rewriteKeyExtension } from "../optimize.js";
 import { buildCliProvenance } from "../provenance.js";
 import { execRunner, resolveCurrentPullRequest, resolveRepo, } from "../github-gh.js";
-import { optPosInt, optString, usage } from "./args.js";
+import { METADATA_DESCRIPTION, metadataProp, optPosInt, optString, optStringArray, optStringRecord, usage, } from "./args.js";
 function optBool(args, name) {
     const v = args[name];
     if (v === undefined || v === null)
@@ -26,15 +27,6 @@ function optBool(args, name) {
         usage(`${name} must be a boolean`);
     return v;
 }
-function optStringArray(args, name) {
-    const v = args[name];
-    if (v === undefined || v === null)
-        return undefined;
-    if (!Array.isArray(v) || v.some((item) => typeof item !== "string")) {
-        usage(`${name} must be an array of strings`);
-    }
-    return v;
-}
 function mcpOptimizeOptions(args, defaults) {
     const quality = optPosInt(args, "optimizeQuality");
     if (quality !== undefined && quality > 100)
@@ -276,7 +268,7 @@ export function createUploadsMcpTools(opts) {
         },
         {
             name: "put",
-            description: "Upload a file to uploads.sh and get a public URL plus GitHub-ready embed markdown (the returned `markdown` is ready to paste into a PR or issue). Pass `file` (a local path) or `contentBase64` + `filename` for in-memory content; with `pr`/`issue` the key is stable (same filename → same URL) and `comment` syncs the managed attachments comment. All uploads are public; pr/issue keys are predictable and remain public for private/internal GitHub repositories, so upload only non-sensitive media.",
+            description: "Upload a file to uploads.sh and get a public URL plus GitHub-ready embed markdown. Returns `url` (durable CDN) and `embedUrl` (same object, freshness-oriented host for GitHub Camo — prefer this in PR/issue markdown). The returned `markdown` already uses embedUrl when available. Pass `file` or `contentBase64` + `filename`; with `pr`/`issue` the key is stable and `comment` syncs the managed attachments comment. All uploads are public; pr/issue keys are predictable, so upload only non-sensitive media.",
             inputSchema: {
                 type: "object",
                 properties: {
@@ -290,7 +282,7 @@ export function createUploadsMcpTools(opts) {
                     },
                     filename: {
                         type: "string",
-                        description: "Filename for contentBase64 content (drives the key and content type).",
+                        description: "Filename for contentBase64 content (drives the key and content type). With `file`, overrides the key's leaf (clean name) while keeping the pr/default path.",
                     },
                     key: {
                         type: "string",
@@ -345,6 +337,11 @@ export function createUploadsMcpTools(opts) {
                         type: "boolean",
                         description: "With pr/issue: create or update the managed attachments comment via local gh auth (best-effort).",
                     },
+                    dryRun: {
+                        type: "boolean",
+                        description: "Resolve key + public URL without uploading. Not with comment.",
+                    },
+                    metadata: metadataProp,
                     workspace: workspaceProp,
                 },
                 additionalProperties: false,
@@ -361,12 +358,15 @@ export function createUploadsMcpTools(opts) {
                 }
                 const target = ghTargetFromArgs(args, run);
                 const wantComment = optBool(args, "comment");
+                const dryRun = optBool(args, "dryRun");
                 const keyArg = optString(args, "key");
                 const destArg = optString(args, "destination");
                 const prefixArg = optString(args, "prefix");
                 const refArg = optString(args, "ref");
                 if (wantComment && !target)
                     usage("comment requires pr or issue");
+                if (dryRun && wantComment)
+                    usage("dryRun cannot be combined with comment");
                 if (target) {
                     if (keyArg)
                         usage("key cannot be combined with pr/issue");
@@ -375,6 +375,12 @@ export function createUploadsMcpTools(opts) {
                     if (prefixArg)
                         usage("prefix cannot be combined with pr/issue");
                 }
+                // Validate up front (fail fast, before reading/optimizing the file).
+                // undefined leaves existing metadata untouched; an object (even {})
+                // fully replaces it — see metadataProp's description.
+                const metadata = optStringRecord(args, "metadata");
+                if (metadata)
+                    validateMetaMap(metadata);
                 let resolvedPrefix;
                 try {
                     resolvedPrefix = resolvePutPrefix({
@@ -389,7 +395,7 @@ export function createUploadsMcpTools(opts) {
                 }
                 const { client } = clientFor(args);
                 const bytes = file !== undefined
-                    ? new Uint8Array(readFileSync(file))
+                    ? readFileArg(file)
                     : new Uint8Array(Buffer.from(contentBase64, "base64"));
                 const sourceName = file !== undefined ? (filenameArg ?? basename(file)) : filenameArg;
                 const defaults = resolvePutDefaults({ envFile: globals.envFile });
@@ -412,6 +418,7 @@ export function createUploadsMcpTools(opts) {
                     ref: refArg ?? defaults.ref,
                     contentType: prepared.optimized ? prepared.contentType : optString(args, "contentType"),
                     deriveRepoFromGit: !noGit,
+                    dryRun,
                     provenance: buildCliProvenance({
                         sourceName,
                         client: "uploads-mcp",
@@ -419,8 +426,9 @@ export function createUploadsMcpTools(opts) {
                         frameId: prepared.frame?.framed ? prepared.frame.frameId : undefined,
                         keepExif: optimizeOpts.keepExif === true,
                     }),
+                    metadata,
                 });
-                const markdown = buildMarkdown(result.url, {
+                const markdown = buildMarkdown(urlForGithubEmbed(result.url, result.embedUrl), {
                     alt: optString(args, "alt") ?? sourceName,
                     width: optPosInt(args, "width") ?? defaults.width,
                 });
@@ -435,12 +443,18 @@ export function createUploadsMcpTools(opts) {
                     const { comment, commentError } = await syncComment(client, target);
                     return { ...result, markdown, optimize, frame: prepared.frame, comment, commentError };
                 }
-                return { ...result, markdown, optimize, frame: prepared.frame };
+                return {
+                    ...result,
+                    markdown,
+                    optimize,
+                    frame: prepared.frame,
+                    ...(dryRun ? { dryRun: true } : {}),
+                };
             },
         },
         {
             name: "attach",
-            description: "Upload one or more files as stable PR/issue attachments and maintain a single managed GitHub comment listing them (each upload's `markdown` is ready to paste into GitHub). With no pr/issue, targets the pull request for the current branch. Attachments are public and their repo/number/filename keys are predictable even for private/internal GitHub repositories; upload only non-sensitive media.",
+            description: "Upload one or more files as stable PR/issue attachments and maintain a single managed GitHub comment listing them. Each upload returns `url`, `embedUrl` (when dual-host applies), and `markdown` (uses embedUrl for GitHub). With no pr/issue, targets the pull request for the current branch. Attachments are public and keys are predictable; upload only non-sensitive media.",
             inputSchema: {
                 type: "object",
                 properties: {
@@ -475,6 +489,11 @@ export function createUploadsMcpTools(opts) {
                         description: "Keep EXIF/XMP/ICC when optimizing (default: strip for privacy on public embeds).",
                     },
                     ...frameProps,
+                    metadata: {
+                        ...metadataProp,
+                        description: "Extra queryable metadata (key→value), merged with the automatic gh.repo/gh.kind/gh.number/gh.ref pairs — a gh.* pair here loses to the resolved target's own gh.* value. " +
+                            METADATA_DESCRIPTION,
+                    },
                     workspace: workspaceProp,
                 },
                 required: ["files"],
@@ -492,10 +511,23 @@ export function createUploadsMcpTools(opts) {
                 const defaults = resolvePutDefaults({ envFile: globals.envFile });
                 const frameOpts = mcpFrameOptions(args);
                 const optimizeOpts = mcpOptimizeOptions(args, defaults);
+                // User-supplied extras first, then the resolved target's gh.* —
+                // explicit target pairs always win over a same-named metadata extra
+                // (mirrors runAttach in ../commands.js). Validate the merged map (not
+                // just the extras) so the 24-key/8KB caps are enforced client-side —
+                // extras alone might pass while extras + the 4 gh.* pairs exceed the
+                // cap, which would otherwise only be caught server-side after upload.
+                const metaExtras = optStringRecord(args, "metadata") ?? {};
+                const metadata = { ...metaExtras, ...ghMetadataFromTarget(target) };
+                if (Object.keys(metadata).length > 0)
+                    validateMetaMap(metadata);
                 const uploads = [];
                 for (const file of files) {
                     const sourceName = basename(file);
-                    const prepared = await prepareImageForUpload(new Uint8Array(readFileSync(file)), sourceName, { ...frameOpts, optimize: optimizeOpts });
+                    const prepared = await prepareImageForUpload(readFileArg(file), sourceName, {
+                        ...frameOpts,
+                        optimize: optimizeOpts,
+                    });
                     const result = await client.put(prepared.bytes, {
                         filename: prepared.filename,
                         key: ghAttachmentKey(target, prepared.filename),
@@ -507,10 +539,13 @@ export function createUploadsMcpTools(opts) {
                             frameId: prepared.frame?.framed ? prepared.frame.frameId : undefined,
                             keepExif: optimizeOpts.keepExif === true,
                         }),
+                        metadata,
                     });
                     uploads.push({
                         ...result,
-                        markdown: buildMarkdown(result.url, { alt: sourceName }),
+                        markdown: buildMarkdown(urlForGithubEmbed(result.url, result.embedUrl), {
+                            alt: sourceName,
+                        }),
                         frame: prepared.frame,
                         optimize: {
                             optimized: prepared.optimized,
@@ -591,6 +626,71 @@ export function createUploadsMcpTools(opts) {
                 return client.delete(key);
             },
         },
+        {
+            name: "set_metadata",
+            description: "Merge-set and/or delete an object's queryable custom metadata (D1-backed key-value pairs; distinct from the R2 provenance headers put on upload). `set` pairs win over `delete` when a key appears in both. " +
+                METADATA_DESCRIPTION +
+                " Requires at least one of `set` or `delete`. Same as `uploads meta set`.",
+            inputSchema: {
+                type: "object",
+                properties: {
+                    key: { type: "string", description: "Object key to update." },
+                    set: { ...metadataProp, description: "Keys to set/overwrite. " + METADATA_DESCRIPTION },
+                    delete: {
+                        type: "array",
+                        items: { type: "string" },
+                        description: "Keys to remove.",
+                    },
+                    workspace: workspaceProp,
+                },
+                required: ["key"],
+                additionalProperties: false,
+            },
+            async handler(args) {
+                const key = optString(args, "key");
+                if (!key)
+                    usage("key is required");
+                const set = optStringRecord(args, "set");
+                const del = optStringArray(args, "delete");
+                if ((!set || Object.keys(set).length === 0) && (!del || del.length === 0)) {
+                    usage("set_metadata requires set and/or delete");
+                }
+                if (set)
+                    validateMetaMap(set);
+                const { client } = clientFor(args);
+                return client.patchMetadata(key, { set, delete: del });
+            },
+        },
+        {
+            name: "find_files",
+            description: "Find objects in the workspace whose queryable custom metadata matches ALL of `filters` (ANDed equality). Returns each match's key, public URL, and full metadata map. Same as `uploads find k=v...` / `uploads list --meta k=v`.",
+            inputSchema: {
+                type: "object",
+                properties: {
+                    filters: {
+                        ...metadataProp,
+                        description: "Metadata equality filters (at least one pair). " + METADATA_DESCRIPTION,
+                    },
+                    prefix: { type: "string", description: "Key prefix filter, combinable with filters." },
+                    limit: { type: "number", description: "Page size (default 50, max 500)." },
+                    workspace: workspaceProp,
+                },
+                required: ["filters"],
+                additionalProperties: false,
+            },
+            async handler(args) {
+                const filters = optStringRecord(args, "filters");
+                if (!filters || Object.keys(filters).length === 0) {
+                    usage("filters must have at least one key");
+                }
+                validateMetaMap(filters);
+                const { client } = clientFor(args);
+                return client.findFiles(filters, {
+                    prefix: optString(args, "prefix"),
+                    limit: optPosInt(args, "limit"),
+                });
+            },
+        },
         {
             name: "usage",
             description: "Workspace storage and monthly upload counters (and remaining headroom when budgets are configured). Same as `uploads usage`.",

package/dist/metadata.d.ts

@@ -0,0 +1,32 @@
+/** Lowercase key, optionally dot-namespaced (e.g. `gh.repo`). Mirrors META_KEY_RE server-side. */
+export declare const META_KEY_RE: RegExp;
+/** Max value length in characters (mirrors META_VALUE_MAX server-side). */
+export declare const META_VALUE_MAX = 512;
+/** Cap on keys per request (mirrors META_MAX_KEYS server-side). */
+export declare const META_MAX_KEYS = 24;
+/** Cap on total UTF-8 key+value bytes per request (mirrors META_MAX_TOTAL_BYTES server-side). */
+export declare const META_MAX_TOTAL_BYTES = 8192;
+/** Throws `UsageError` with a readable message if `key`/`value` violate the metadata rules. */
+export declare function validateMetaEntry(key: string, value: string): void;
+/**
+ * Split `k=v` on the FIRST "=" (so values may themselves contain "="), then
+ * validate the pair. Throws `UsageError` on malformed input.
+ */
+export declare function parseMetaPair(raw: string): [string, string];
+/**
+ * Parse and validate a batch of `k=v` pairs (e.g. every `--meta` occurrence,
+ * or `meta set`'s positional pairs) into a map. Fails fast on the first
+ * invalid pair or when the batch exceeds `META_MAX_KEYS` or
+ * `META_MAX_TOTAL_BYTES`. Later duplicate keys in the same batch win
+ * (last write).
+ */
+export declare function parseMetaFlags(pairs: string[]): Record<string, string>;
+/**
+ * Validates a pre-parsed key→value metadata map (e.g. an MCP tool's object
+ * argument) against the same rules as {@link parseMetaFlags} — the same
+ * per-entry validation (`validateMetaEntry`, which `parseMetaPair` also
+ * uses), the same key-count cap, and the same aggregate byte cap — without
+ * round-tripping through "k=v" string reconstruction and re-parsing first.
+ * Throws `UsageError`.
+ */
+export declare function validateMetaMap(meta: Record<string, string>): void;

package/dist/metadata.js

@@ -0,0 +1,102 @@
+/**
+ * Client-side validation for `--meta k=v` / `meta set` pairs, mirroring the
+ * server rules in `apps/api/src/file-metadata.ts` (`.context/2026-07-13-file-metadata-design.md`).
+ * Validating here lets the CLI fail fast with a readable message instead of a
+ * round-trip 400 — the server remains the source of truth and re-validates on
+ * every write.
+ */
+import { UsageError } from "./cli-args.js";
+/** Lowercase key, optionally dot-namespaced (e.g. `gh.repo`). Mirrors META_KEY_RE server-side. */
+export const META_KEY_RE = /^[a-z][a-z0-9._-]{0,63}$/;
+/** Max value length in characters (mirrors META_VALUE_MAX server-side). */
+export const META_VALUE_MAX = 512;
+/** Cap on keys per request (mirrors META_MAX_KEYS server-side). */
+export const META_MAX_KEYS = 24;
+/** Cap on total UTF-8 key+value bytes per request (mirrors META_MAX_TOTAL_BYTES server-side). */
+export const META_MAX_TOTAL_BYTES = 8192;
+// Printable ASCII only — same rule as the server's file-metadata.ts.
+const VALUE_SAFE_RE = /^[\x20-\x7E]+$/;
+const encoder = new TextEncoder();
+/**
+ * Server-computed/server-reserved keys the API rejects as custom metadata:
+ * `content-sha256` (server-computed provenance) and `visibility` (names the
+ * R2-backed public/private gate, not a piece of D1 custom metadata — mirrors
+ * apps/api/src/file-metadata.ts's RESERVED_META_KEYS). `gh.*` is NOT reserved
+ * here: it's system-managed by convention (attach flow), not blocked — the
+ * server happily accepts user-supplied `gh.*` extras via `--meta`.
+ */
+const RESERVED_META_KEYS = new Set(["content-sha256", "visibility"]);
+/** Throws `UsageError` with a readable message if `key`/`value` violate the metadata rules. */
+export function validateMetaEntry(key, value) {
+    if (!META_KEY_RE.test(key)) {
+        throw new UsageError(`invalid metadata key: "${key}" (must match ^[a-z][a-z0-9._-]{0,63}$)`);
+    }
+    if (RESERVED_META_KEYS.has(key)) {
+        throw new UsageError(`invalid metadata key: "${key}" is reserved (server-computed)`);
+    }
+    if (value.length < 1 || value.length > META_VALUE_MAX || !VALUE_SAFE_RE.test(value)) {
+        throw new UsageError(`invalid metadata value for key "${key}": must be 1-${META_VALUE_MAX} printable ASCII characters`);
+    }
+}
+/**
+ * Split `k=v` on the FIRST "=" (so values may themselves contain "="), then
+ * validate the pair. Throws `UsageError` on malformed input.
+ */
+export function parseMetaPair(raw) {
+    const eq = raw.indexOf("=");
+    if (eq === -1) {
+        throw new UsageError(`invalid --meta value: "${raw}" (expected key=value)`);
+    }
+    const key = raw.slice(0, eq);
+    const value = raw.slice(eq + 1);
+    validateMetaEntry(key, value);
+    return [key, value];
+}
+/** Throws `UsageError` if the aggregate UTF-8 key+value bytes of `entries` exceed `META_MAX_TOTAL_BYTES`. */
+function enforceMetaByteCap(entries) {
+    let totalBytes = 0;
+    for (const [key, value] of entries) {
+        totalBytes += encoder.encode(key).byteLength + encoder.encode(value).byteLength;
+    }
+    if (totalBytes > META_MAX_TOTAL_BYTES) {
+        throw new UsageError(`metadata too large: ${totalBytes} bytes of keys+values exceeds the ${META_MAX_TOTAL_BYTES}-byte limit per request`);
+    }
+}
+/**
+ * Parse and validate a batch of `k=v` pairs (e.g. every `--meta` occurrence,
+ * or `meta set`'s positional pairs) into a map. Fails fast on the first
+ * invalid pair or when the batch exceeds `META_MAX_KEYS` or
+ * `META_MAX_TOTAL_BYTES`. Later duplicate keys in the same batch win
+ * (last write).
+ */
+export function parseMetaFlags(pairs) {
+    if (pairs.length > META_MAX_KEYS) {
+        throw new UsageError(`too many --meta pairs: at most ${META_MAX_KEYS} per request`);
+    }
+    const result = {};
+    for (const pair of pairs) {
+        const [key, value] = parseMetaPair(pair);
+        result[key] = value;
+    }
+    // Aggregate byte cap over the deduplicated map — same accounting as the
+    // server (sum of UTF-8 key+value bytes, META_MAX_TOTAL_BYTES).
+    enforceMetaByteCap(Object.entries(result));
+    return result;
+}
+/**
+ * Validates a pre-parsed key→value metadata map (e.g. an MCP tool's object
+ * argument) against the same rules as {@link parseMetaFlags} — the same
+ * per-entry validation (`validateMetaEntry`, which `parseMetaPair` also
+ * uses), the same key-count cap, and the same aggregate byte cap — without
+ * round-tripping through "k=v" string reconstruction and re-parsing first.
+ * Throws `UsageError`.
+ */
+export function validateMetaMap(meta) {
+    const entries = Object.entries(meta);
+    if (entries.length > META_MAX_KEYS) {
+        throw new UsageError(`too many --meta pairs: at most ${META_MAX_KEYS} per request`);
+    }
+    for (const [key, value] of entries)
+        validateMetaEntry(key, value);
+    enforceMetaByteCap(entries);
+}

package/dist/public-urls.d.ts

@@ -0,0 +1,18 @@
+/**
+ * Client-side dual-host helpers (published package; no @uploads/storage dep).
+ * Keep behavior aligned with packages/storage.
+ *
+ * `UPLOADS_EMBED_PUBLIC_BASE_URL`: unset = default twin; empty = disable; URL = override.
+ */
+export declare const DEFAULT_EMBED_PUBLIC_BASE_URL = "https://embed.uploads.sh";
+export type ClientEmbedUrlOptions = {
+    embedBaseUrl?: string | null;
+    publicBaseUrl?: string | null;
+};
+export declare function embedBaseUrlFromEnv(env?: NodeJS.ProcessEnv): string | null | undefined;
+export declare function resolveEmbedBaseUrl(publicBaseUrl?: string | null, embedBaseUrl?: string | null): string | null;
+export declare function embedUrlFromPublic(publicObjectUrl: string | null | undefined, opts?: ClientEmbedUrlOptions): string | null;
+/** Prefer API `embedUrl`; otherwise derive (incl. env override). */
+export declare function resolveEmbedUrl(publicObjectUrl: string | null | undefined, apiEmbedUrl?: string | null, opts?: ClientEmbedUrlOptions): string | null;
+/** Prefer embed host for GitHub markdown; fall back to stable public URL. */
+export declare function urlForGithubEmbed(publicObjectUrl: string | null | undefined, apiEmbedUrl?: string | null, opts?: ClientEmbedUrlOptions): string | null;

package/dist/public-urls.js

@@ -0,0 +1,68 @@
+/**
+ * Client-side dual-host helpers (published package; no @uploads/storage dep).
+ * Keep behavior aligned with packages/storage.
+ *
+ * `UPLOADS_EMBED_PUBLIC_BASE_URL`: unset = default twin; empty = disable; URL = override.
+ */
+export const DEFAULT_EMBED_PUBLIC_BASE_URL = "https://embed.uploads.sh";
+const DEFAULT_EMBEDDABLE_HOSTS = new Set(["storage.uploads.sh", "store.uploads.sh"]);
+export function embedBaseUrlFromEnv(env = process.env) {
+    if (!Object.prototype.hasOwnProperty.call(env, "UPLOADS_EMBED_PUBLIC_BASE_URL")) {
+        return undefined;
+    }
+    return env.UPLOADS_EMBED_PUBLIC_BASE_URL ?? "";
+}
+export function resolveEmbedBaseUrl(publicBaseUrl, embedBaseUrl) {
+    if (embedBaseUrl != null) {
+        const trimmed = embedBaseUrl.trim();
+        return trimmed ? trimmed.replace(/\/$/, "") : null;
+    }
+    if (!publicBaseUrl)
+        return null;
+    try {
+        const host = new URL(publicBaseUrl).hostname.toLowerCase();
+        if (DEFAULT_EMBEDDABLE_HOSTS.has(host))
+            return DEFAULT_EMBED_PUBLIC_BASE_URL;
+    }
+    catch {
+        return null;
+    }
+    return null;
+}
+export function embedUrlFromPublic(publicObjectUrl, opts = {}) {
+    if (!publicObjectUrl)
+        return null;
+    let publicBaseUrl = opts.publicBaseUrl ?? null;
+    if (!publicBaseUrl) {
+        try {
+            const u = new URL(publicObjectUrl);
+            if (DEFAULT_EMBEDDABLE_HOSTS.has(u.hostname.toLowerCase())) {
+                publicBaseUrl = `${u.protocol}//${u.host}`;
+            }
+        }
+        catch {
+            return null;
+        }
+    }
+    const embedBase = resolveEmbedBaseUrl(publicBaseUrl, opts.embedBaseUrl);
+    if (!embedBase || !publicBaseUrl)
+        return null;
+    const stableBase = publicBaseUrl.replace(/\/$/, "");
+    if (publicObjectUrl === stableBase || publicObjectUrl.startsWith(`${stableBase}/`)) {
+        return `${embedBase}${publicObjectUrl.slice(stableBase.length)}`;
+    }
+    return null;
+}
+/** Prefer API `embedUrl`; otherwise derive (incl. env override). */
+export function resolveEmbedUrl(publicObjectUrl, apiEmbedUrl, opts = {}) {
+    if (apiEmbedUrl)
+        return apiEmbedUrl;
+    const embedBaseUrl = opts.embedBaseUrl !== undefined ? opts.embedBaseUrl : embedBaseUrlFromEnv();
+    return embedUrlFromPublic(publicObjectUrl, { ...opts, embedBaseUrl });
+}
+/** Prefer embed host for GitHub markdown; fall back to stable public URL. */
+export function urlForGithubEmbed(publicObjectUrl, apiEmbedUrl, opts = {}) {
+    if (!publicObjectUrl)
+        return null;
+    return resolveEmbedUrl(publicObjectUrl, apiEmbedUrl, opts) ?? publicObjectUrl;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@buildinternet/uploads",
-  "version": "0.7.0",
+  "version": "0.8.0",
   "description": "CLI and client for uploads.sh — workspace-scoped image hosting for GitHub embeds",
   "type": "module",
   "sideEffects": false,