@buildinternet/uploads 0.7.0 → 0.8.0

package/README.md

@@ -21,8 +21,14 @@ uploads put ./shot.png --no-optimize
 uploads put ./mobile.png --frame phone
 uploads put ./ui.png --frame browser --frame-url "https://app.example"
 uploads put ./after.png --pr 123 --comment
+uploads put ./capture-2026-…Z.png --pr 123 --name hero.png   # clean leaf, stable path
+uploads put ./shot.png --pr 123 --name hero.png --dry-run --format url  # preview URL, no upload
 uploads gallery create --title "Release screenshots"
 uploads put ./after.png --gallery gal_example
+uploads put ./shot.png --meta app=myapp --meta page=settings   # queryable custom metadata
+uploads meta get screenshots/myapp/42/shot.png
+uploads meta set screenshots/myapp/42/shot.png page=onboarding --delete device
+uploads find app=myapp page=settings                            # or: list --meta app=myapp
 uploads doctor
 ```
 
@@ -30,8 +36,8 @@ Inside this monorepo only, `pnpm uploads …` builds the package first so you pi
 up local source; product docs and PR “how to try it” examples should use the
 global `uploads` form above.
 
-Commands: `attach`, `put`, `gallery`, `comment`, `list`, `delete`, `usage`, `reconcile`,
-`purge-expired`, `setup`, `install`, `config`, `doctor`, `health`, `mcp`.
+Commands: `attach`, `put`, `gallery`, `comment`, `list`, `find`, `meta`, `delete`, `usage`,
+`reconcile`, `purge-expired`, `setup`, `install`, `config`, `doctor`, `health`, `mcp`.
 
 **Globals (before the command):** `--api-url`, `--token`, `--workspace` / `-w`,
 `--env-file`, `--json`, `--quiet`, `--version` / `-V`, `-h` / `--help`.
@@ -41,6 +47,11 @@ newer npm release is available (at most once/day, `~/.cache/uploads/`). Silence
 with `--quiet`, `--json`, `UPLOADS_NO_UPDATE=1`, or `NO_UPDATE_NOTIFIER=1`. Not used
 for `uploads mcp`.
 
+**Exit codes:** `0` ok, `2` usage/token/file, `3` auth/policy, `4` network, `1` other.
+Failures go to stderr; under `--format json|url|markdown` they also go to stdout so
+piped runs stay self-diagnosing. Prefer JSON `code` over message text. `put --dry-run`
+previews the key + public URL without uploading.
+
 `attach` is the agent-friendly default for GitHub media. It accepts one or more files,
 infers the pull request for the current branch via `gh`, uploads stable URLs, and creates
 or updates one marker-owned GitHub comment. It keeps loose `gh/...` attachments and linked public galleries in distinct sections, shows up to three available gallery images inline, and updates that same comment in place on every sync. Use `--pr`, `--issue`, and `--repo` to select
@@ -95,7 +106,7 @@ Config layers (first match wins): CLI flags → env vars → `--env-file` → `~
 
 Or with `UPLOADS_TOKEN`/`UPLOADS_WORKSPACE` in the environment or user config. Claude Code: `claude mcp add uploads -- uploads --env-file /path/to/.env mcp`.
 
-For HTTP clients there's also a hosted variant at `https://agents.uploads.sh/mcp` — the workspace is inferred from the bearer token, so only the URL and token are needed (`https://agents.uploads.sh/<workspace>/mcp` and the `mcp.uploads.sh` hostname also work). Tools: file operations plus `gallery_create`, `gallery_get`, `gallery_add`, `gallery_link`, and `gallery_find_by_reference`; all use the same bearer-token workspace scopes and gallery URLs come from the API — see `apps/mcp` in the repo. `uploads install` registers it with Claude Code (and installs the agent skill) in one step. Its `put` takes no content type: the stored type is sniffed server-side from the bytes and checked against the workspace allowlist, and writes are rate limited per workspace.
+For HTTP clients there's also a hosted variant at `https://agents.uploads.sh/mcp` — the workspace is inferred from the bearer token, so only the URL and token are needed (`https://agents.uploads.sh/<workspace>/mcp` and the `mcp.uploads.sh` hostname also work). Tools: file operations plus `gallery_create`, `gallery_get`, `gallery_add`, `gallery_link`, and `gallery_find_by_reference`; all use the same bearer-token workspace scopes and gallery URLs come from the API — see `apps/mcp` in the repo. `uploads install` registers the skill + hosted MCP (short progress; `--verbose` for underlying output). Its `put` takes no content type: the stored type is sniffed server-side from the bytes and checked against the workspace allowlist, and writes are rate limited per workspace.
 
 ## Programmatic use
 

package/dist/cli-args.d.ts

@@ -26,16 +26,31 @@ export declare class UsageError extends Error {
 }
 export interface CommandFlags {
     positionals: string[];
-    flags: Map<string, string | boolean>;
+    /** Repeated string flags (e.g. `--meta k=v --meta k2=v2`) collapse into a string[]. */
+    flags: Map<string, string | boolean | string[]>;
     help: boolean;
 }
 /**
  * Parse command-specific args. Supports `--flag value`, `--flag=value`, and
- * boolean `--flag` flags.
+ * boolean `--flag` flags. A flag repeated multiple times with string values
+ * (e.g. `--meta app=x --meta page=y`) collapses into a `string[]` — read it
+ * with `flagValues`, not `flagString`.
  */
 export declare function parseCommandArgs(args: string[]): CommandFlags;
+/**
+ * Single string value for a flag. A repeated single-value flag keeps the
+ * pre-repeatable-flags behavior: the last occurrence wins (e.g.
+ * `--repo a --repo b` → `"b"`). Genuinely repeatable flags should use
+ * `flagValues` instead.
+ */
 export declare function flagString(flags: CommandFlags["flags"], name: string): string | undefined;
 export declare function flagBool(flags: CommandFlags["flags"], name: string): boolean;
+/**
+ * Every string value passed for a repeatable flag (e.g. `--meta k=v`), in
+ * argument order. Empty when the flag is absent; a single occurrence yields
+ * a one-element array.
+ */
+export declare function flagValues(flags: CommandFlags["flags"], name: string): string[];
 /** Command-level workspace override (`--workspace` / `-w`). */
 export declare function commandWorkspace(flags: CommandFlags["flags"]): string | undefined;
 export declare function flagInt(flags: CommandFlags["flags"], name: string, label: string): number | undefined;

package/dist/cli-args.js

@@ -69,9 +69,29 @@ export class UsageError extends Error {
         this.name = "UsageError";
     }
 }
+/** Records a flag occurrence, turning a repeated string flag into an array. */
+function setFlag(flags, name, value) {
+    const existing = flags.get(name);
+    if (existing === undefined) {
+        flags.set(name, value);
+        return;
+    }
+    if (Array.isArray(existing)) {
+        if (typeof value === "string")
+            existing.push(value);
+        return;
+    }
+    if (typeof existing === "string" && typeof value === "string") {
+        flags.set(name, [existing, value]);
+        return;
+    }
+    flags.set(name, value);
+}
 /**
  * Parse command-specific args. Supports `--flag value`, `--flag=value`, and
- * boolean `--flag` flags.
+ * boolean `--flag` flags. A flag repeated multiple times with string values
+ * (e.g. `--meta app=x --meta page=y`) collapses into a `string[]` — read it
+ * with `flagValues`, not `flagString`.
  */
 export function parseCommandArgs(args) {
     const positionals = [];
@@ -88,18 +108,18 @@ export function parseCommandArgs(args) {
         if (arg.startsWith("--")) {
             const eq = arg.indexOf("=");
             if (eq !== -1) {
-                flags.set(arg.slice(0, eq), arg.slice(eq + 1));
+                setFlag(flags, arg.slice(0, eq), arg.slice(eq + 1));
                 i++;
                 continue;
             }
             const name = arg;
             const next = args[i + 1];
             if (next && !next.startsWith("-")) {
-                flags.set(name, next);
+                setFlag(flags, name, next);
                 i += 2;
                 continue;
             }
-            flags.set(name, true);
+            setFlag(flags, name, true);
             i++;
             continue;
         }
@@ -108,13 +128,38 @@ export function parseCommandArgs(args) {
     }
     return { positionals, flags, help };
 }
+/**
+ * Single string value for a flag. A repeated single-value flag keeps the
+ * pre-repeatable-flags behavior: the last occurrence wins (e.g.
+ * `--repo a --repo b` → `"b"`). Genuinely repeatable flags should use
+ * `flagValues` instead.
+ */
 export function flagString(flags, name) {
     const value = flags.get(name);
-    return typeof value === "string" ? value : undefined;
+    if (typeof value === "string")
+        return value;
+    if (Array.isArray(value) && value.length > 0)
+        return value[value.length - 1];
+    return undefined;
 }
 export function flagBool(flags, name) {
     return flags.get(name) === true;
 }
+/**
+ * Every string value passed for a repeatable flag (e.g. `--meta k=v`), in
+ * argument order. Empty when the flag is absent; a single occurrence yields
+ * a one-element array.
+ */
+export function flagValues(flags, name) {
+    const value = flags.get(name);
+    if (value === undefined)
+        return [];
+    if (Array.isArray(value))
+        return value;
+    if (typeof value === "string")
+        return [value];
+    return [];
+}
 /** Command-level workspace override (`--workspace` / `-w`). */
 export function commandWorkspace(flags) {
     return flagString(flags, "--workspace") ?? flagString(flags, "-w");

package/dist/cli.d.ts

@@ -1 +1,6 @@
+/** Effective stdout format, so failures surface where the caller reads output. */
+type OutputFormat = "json" | "url" | "markdown" | "human";
+/** Global `--json` wins; else put-style `--format`. Drives where failures print. */
+export declare function outputFormat(argv: string[]): OutputFormat;
 export declare function runCli(argv: string[]): Promise<number>;
+export {};

package/dist/cli.js

@@ -1,11 +1,12 @@
 import { createUploadsClient } from "./client.js";
 import { resolveApiUrl, resolveConfig } from "./config.js";
 import { UploadsError } from "./errors.js";
-import { commandWorkspace, isHelpFlag, parseArgv, parseCommandArgs, UsageError, } from "./cli-args.js";
-import { runPut, runAttach, runList, runDelete, runHealth, runDoctor, runComment, runUsage, runReconcile, runPurgeExpired, runGallery, } from "./commands.js";
+import { commandWorkspace, flagString, isHelpFlag, parseArgv, parseCommandArgs, UsageError, } from "./cli-args.js";
+import { runPut, runAttach, runList, runFind, runMeta, runDelete, runHealth, runDoctor, runComment, runUsage, runReconcile, runPurgeExpired, runGallery, } from "./commands.js";
 import { runConfig } from "./commands/config.js";
 import { runSetup } from "./commands/setup.js";
 import { runLogin } from "./commands/login.js";
+import { runInvite } from "./commands/invite.js";
 import { runAdmin } from "./commands/admin-enrollment.js";
 import { runMcp } from "./commands/mcp.js";
 import { runInstall } from "./commands/install.js";
@@ -41,7 +42,9 @@ Commands:
   put <file>          Upload (+ URL + markdown for GitHub)
   gallery             Create and organize public media galleries
   comment             Create/update a PR/issue attachments comment (via gh)
-  list                List objects
+  list                List objects (--meta k=v filters by queryable metadata)
+  find k=v...         List objects matching metadata (alias for list --meta)
+  meta                Get/set an object's queryable metadata
   delete <key>        Delete object
   usage               Workspace storage / upload counters
   reconcile           Rebuild usage ledger from storage
@@ -49,7 +52,8 @@ Commands:
   setup               Inspect/configure advanced CLI settings
   install             Install the agent skill + register the remote MCP server
   login               Sign in via browser (or an enrollment code) and save credentials
-  admin               Admin invitation management
+  invite              Invite a teammate to a workspace (workspace admin; device login)
+  admin               Site-operator invitation management (ADMIN_TOKEN)
   config              Show path, init, or set shared config
   doctor              Health + auth + workspace checks
   health              API liveness (no auth)
@@ -99,6 +103,7 @@ function exitCode(err) {
         switch (err.code) {
             case "MISSING_TOKEN":
             case "USAGE":
+            case "FILE_NOT_FOUND":
                 return 2;
             case "UNAUTHORIZED":
             case "NOT_FOUND":
@@ -114,32 +119,58 @@ function exitCode(err) {
     }
     return 1;
 }
-function errorOut(err, json) {
+/** Global `--json` wins; else put-style `--format`. Drives where failures print. */
+export function outputFormat(argv) {
+    const flags = parseCommandArgs(argv.slice(2)).flags;
+    if (flags.has("--json"))
+        return "json";
+    const value = flagString(flags, "--format");
+    if (value === "json" || value === "url" || value === "markdown")
+        return value;
+    return "human";
+}
+const QUOTA_HINT = "hint: run `uploads usage` then delete objects or raise limits (`pnpm workspace:limits`)\n";
+const ERROR_HINTS = {
+    STORAGE_QUOTA: QUOTA_HINT,
+    UPLOAD_BUDGET: QUOTA_HINT,
+    KEY_POLICY: "hint: use a typed destination (`--destination screenshots|gh`) or an allowed prefix; operators set allowlists with `pnpm workspace:limits --allowed-prefixes`\n",
+    UNAUTHORIZED: "hint: token rejected — run `uploads login` to sign in again, or check UPLOADS_TOKEN / --token\n",
+};
+function errorOut(err, format) {
     const payload = err instanceof UploadsError
         ? { error: err.message, code: err.code, status: err.status }
         : err instanceof UsageError
             ? { error: err.message, code: "USAGE" }
             : { error: err instanceof Error ? err.message : String(err) };
-    if (json)
+    if (format === "json") {
         process.stdout.write(JSON.stringify(payload, null, 2) + "\n");
-    else {
-        const msg = payload.error;
-        if (msg.includes("\n"))
-            process.stderr.write(`${msg}\n`);
-        else
-            process.stderr.write(`error: ${msg}\n`);
-        if (err instanceof UploadsError) {
-            if (err.code === "STORAGE_QUOTA" || err.code === "UPLOAD_BUDGET") {
-                process.stderr.write("hint: run `uploads usage` then delete objects or raise limits (`pnpm workspace:limits`)\n");
-            }
-            else if (err.code === "KEY_POLICY") {
-                process.stderr.write("hint: use a typed destination (`--destination screenshots|gh`) or an allowed prefix; operators set allowlists with `pnpm workspace:limits --allowed-prefixes`\n");
-            }
-            else if (err.status === 413 || err.message.toLowerCase().includes("too large")) {
-                process.stderr.write("hint: file exceeds workspace size policy (images vs video may differ); compress or raise --max-upload-bytes / --max-video-bytes\n");
-            }
+        return;
+    }
+    const msg = payload.error;
+    // No token: onboarding nudge (no "error:" prefix). Exit stays non-zero; JSON keeps MISSING_TOKEN.
+    if (err instanceof UploadsError && err.code === "MISSING_TOKEN") {
+        process.stderr.write(`${msg}\n`);
+        if (format === "url" || format === "markdown") {
+            process.stdout.write("not signed in — run uploads login\n");
+        }
+        return;
+    }
+    if (msg.includes("\n"))
+        process.stderr.write(`${msg}\n`);
+    else
+        process.stderr.write(`error: ${msg}\n`);
+    if (err instanceof UploadsError) {
+        const hint = ERROR_HINTS[err.code];
+        if (hint)
+            process.stderr.write(hint);
+        else if (err.status === 413 || err.message.toLowerCase().includes("too large")) {
+            process.stderr.write("hint: file exceeds workspace size policy (images vs video may differ); compress or raise --max-upload-bytes / --max-video-bytes\n");
         }
     }
+    // Scripted formats often drop stderr — mirror a one-line reason on stdout.
+    if (format === "url" || format === "markdown") {
+        process.stdout.write(`error: ${msg.replace(/\s*\n\s*/g, " ")}\n`);
+    }
 }
 /** Point agents at layered --help instead of dumping the full root manual. */
 function usageHint(argv) {
@@ -180,6 +211,9 @@ export async function runCli(argv) {
             case "login":
                 code = await runLogin(cmdArgs, { json, apiUrl: resolveApiUrl(parsed.globals) }, showHelp);
                 break;
+            case "invite":
+                code = await runInvite(cmdArgs, { json, apiUrl: resolveApiUrl(parsed.globals) }, showHelp);
+                break;
             case "admin":
                 code = await runAdmin(cmdArgs, { json, apiUrl: resolveApiUrl(parsed.globals) }, showHelp);
                 break;
@@ -193,6 +227,8 @@ export async function runCli(argv) {
             case "put":
             case "gallery":
             case "list":
+            case "find":
+            case "meta":
             case "delete":
             case "usage":
             case "reconcile":
@@ -216,6 +252,12 @@ export async function runCli(argv) {
                     case "list":
                         code = await runList(ctx, cmdArgs, showHelp);
                         break;
+                    case "find":
+                        code = await runFind(ctx, cmdArgs, showHelp);
+                        break;
+                    case "meta":
+                        code = await runMeta(ctx, cmdArgs, showHelp);
+                        break;
                     case "delete":
                         code = await runDelete(ctx, cmdArgs, showHelp);
                         break;
@@ -245,8 +287,9 @@ export async function runCli(argv) {
         return code;
     }
     catch (err) {
-        errorOut(err, argv.includes("--json"));
-        if (err instanceof UsageError && !argv.includes("--json"))
+        const format = outputFormat(argv);
+        errorOut(err, format);
+        if (err instanceof UsageError && format !== "json")
             usageHint(argv);
         return exitCode(err);
     }

package/dist/client.d.ts

@@ -17,16 +17,47 @@ export interface PutOptions {
     deriveRepoFromGit?: boolean;
     /** Stored as R2 custom metadata; echoed on put/head. */
     provenance?: ProvenanceInput;
+    /**
+     * Queryable custom metadata (D1 `file_metadata`), sent alongside provenance
+     * as more `X-Uploads-Meta-<key>` headers — the server routes each key to R2
+     * (provenance) or D1 (everything else) by name. See `metadata.ts` for the
+     * client-side validation callers should run before this.
+     */
+    metadata?: Record<string, string>;
+    /** Validate key + resolve public URL without writing. `size` is local bytes only. */
+    dryRun?: boolean;
 }
 export interface ListOptions {
     prefix?: string;
     limit?: number;
     cursor?: string;
 }
+export interface FindFilesOptions {
+    prefix?: string;
+    limit?: number;
+}
+export interface FindFilesItem {
+    key: string;
+    url: string | null;
+    metadata: Record<string, string>;
+}
+export interface FindFilesResult {
+    items: FindFilesItem[];
+    cursor: string | null;
+}
+export interface GetMetadataResult {
+    metadata: Record<string, string>;
+}
+export interface PatchMetadataOptions {
+    set?: Record<string, string>;
+    delete?: string[];
+}
 export interface PutResult {
     workspace: string;
     key: string;
     url: string;
+    /** Same object on the embed host when dual-host applies; prefer for GitHub markdown. */
+    embedUrl: string | null;
     size: number;
     contentType: string;
     metadata?: Record<string, string>;
@@ -34,6 +65,7 @@ export interface PutResult {
 export interface ListItem {
     key: string;
     url: string | null;
+    embedUrl?: string | null;
     size?: number;
     uploaded?: string;
 }
@@ -44,6 +76,7 @@ export interface ListResult {
 export interface HeadResult {
     key: string;
     url: string | null;
+    embedUrl?: string | null;
     size: number;
     contentType: string;
     uploaded?: string;
@@ -63,6 +96,8 @@ export interface GalleryItem {
     createdAt: string;
     status: "available" | "missing";
     url: string | null;
+    /** Dual-host embed URL when available. */
+    embedUrl?: string | null;
     /** Standalone web page for this item (gallery URL + item id). Absent on older API deployments. */
     pageUrl?: string;
     contentType: string | null;
@@ -193,6 +228,13 @@ export declare function createEnrollment(apiUrl: string, adminToken: string, inp
 }): Promise<EnrollmentCreateResult>;
 /** Static OAuth client id allowlisted by the auth worker's `validateClient`. */
 export declare const DEVICE_CLIENT_ID = "uploads-cli";
+/**
+ * User-Agent for device-flow requests. Stored on the Better Auth session row
+ * when `/device/token` creates the session, so the web account UI can tell a
+ * completed `uploads login` apart from a browser tab. Keep the
+ * `@buildinternet/uploads` prefix in sync with apps/web `CLI_USER_AGENT_RE`.
+ */
+export declare function cliUserAgent(purpose?: string): string;
 export interface DeviceCodeResponse {
     device_code: string;
     user_code: string;
@@ -247,6 +289,24 @@ export interface MintTokenResult {
     label: string | null;
     expiresAt: string | null;
 }
+/**
+ * POST /me/workspaces/:name/invites — org invitation for a workspace.
+ * Requires a Better Auth session bearer (device flow), not a workspace token.
+ * Caller must be org admin|owner. `acceptUrl` is always returned so
+ * self-hosted deploys without email can still share the link.
+ */
+export declare function createWorkspaceInvite(apiUrl: string, accessToken: string, workspace: string, input: {
+    email: string;
+    role?: "member" | "admin";
+}): Promise<{
+    invitation: {
+        id: string;
+        email: string;
+        role: string;
+        status: string;
+    };
+    acceptUrl?: string;
+}>;
 /**
  * POST /v1/tokens — mint a `up_<workspace>_…` workspace token from a device-flow
  * session (presented as a bearer). v1 sends exactly one grant.
@@ -267,6 +327,15 @@ export declare function createUploadsClient(config: UploadsClientConfig): {
         cursor?: string;
     }): Promise<ListItem[]>;
     delete(key: string): Promise<DeleteResult>;
+    /** `GET /v1/:workspace/files/:key?metadata=1` — the object's queryable metadata. */
+    getMetadata(key: string): Promise<GetMetadataResult>;
+    /** `PATCH /v1/:workspace/files/:key` — merge `set`/`delete`; returns the merged map. */
+    patchMetadata(key: string, opts: PatchMetadataOptions): Promise<GetMetadataResult>;
+    /**
+     * `GET /v1/:workspace/files?meta.<k>=<v>&…` — ANDed equality filter over
+     * queryable metadata. `filters` must be pre-validated (see `metadata.ts`).
+     */
+    findFiles(filters: Record<string, string>, opts?: FindFilesOptions): Promise<FindFilesResult>;
     head(key: string): Promise<HeadResult>;
     createGallery(opts: CreateGalleryOptions): Promise<Gallery>;
     getGallery(id: string): Promise<Gallery>;

package/dist/client.js

@@ -1,6 +1,8 @@
 import { inferContentType } from "./embed.js";
 import { UploadsError } from "./errors.js";
 import { buildScreenshotKey } from "./keys.js";
+import { packageVersion } from "./package-version.js";
+import { resolveEmbedUrl } from "./public-urls.js";
 async function jsonRequest(url, init) {
     let res;
     try {
@@ -36,11 +38,23 @@ export function createEnrollment(apiUrl, adminToken, input) {
 // below are what the worker expects.
 /** Static OAuth client id allowlisted by the auth worker's `validateClient`. */
 export const DEVICE_CLIENT_ID = "uploads-cli";
+/**
+ * User-Agent for device-flow requests. Stored on the Better Auth session row
+ * when `/device/token` creates the session, so the web account UI can tell a
+ * completed `uploads login` apart from a browser tab. Keep the
+ * `@buildinternet/uploads` prefix in sync with apps/web `CLI_USER_AGENT_RE`.
+ */
+export function cliUserAgent(purpose = "device-login") {
+    return `@buildinternet/uploads/${packageVersion()} (${purpose})`;
+}
 /** POST /api/auth/device/code — start a device flow. Throws on a non-2xx. */
 export function requestDeviceCode(authUrl, clientId = DEVICE_CLIENT_ID) {
     return jsonRequest(`${authUrl.replace(/\/$/, "")}/api/auth/device/code`, {
         method: "POST",
-        headers: { "Content-Type": "application/json" },
+        headers: {
+            "Content-Type": "application/json",
+            "User-Agent": cliUserAgent("device-code"),
+        },
         body: JSON.stringify({ client_id: clientId }),
     });
 }
@@ -49,7 +63,12 @@ export async function requestDeviceToken(authUrl, input) {
     try {
         res = await fetch(`${authUrl.replace(/\/$/, "")}/api/auth/device/token`, {
             method: "POST",
-            headers: { "Content-Type": "application/json" },
+            headers: {
+                "Content-Type": "application/json",
+                // Session user_agent is taken from this request when the token is
+                // exchanged — identify as the CLI so /account can surface it.
+                "User-Agent": cliUserAgent("device-token"),
+            },
             body: JSON.stringify({
                 grant_type: "urn:ietf:params:oauth:grant-type:device_code",
                 device_code: input.deviceCode,
@@ -93,6 +112,22 @@ export function listMintWorkspaces(apiUrl, accessToken) {
         headers: { Authorization: `Bearer ${accessToken}` },
     });
 }
+/**
+ * POST /me/workspaces/:name/invites — org invitation for a workspace.
+ * Requires a Better Auth session bearer (device flow), not a workspace token.
+ * Caller must be org admin|owner. `acceptUrl` is always returned so
+ * self-hosted deploys without email can still share the link.
+ */
+export function createWorkspaceInvite(apiUrl, accessToken, workspace, input) {
+    return jsonRequest(`${apiUrl.replace(/\/$/, "")}/me/workspaces/${encodeURIComponent(workspace)}/invites`, {
+        method: "POST",
+        headers: {
+            Authorization: `Bearer ${accessToken}`,
+            "Content-Type": "application/json",
+        },
+        body: JSON.stringify({ email: input.email, role: input.role ?? "member" }),
+    });
+}
 /**
  * POST /v1/tokens — mint a `up_<workspace>_…` workspace token from a device-flow
  * session (presented as a bearer). v1 sends exactly one grant.
@@ -206,7 +241,14 @@ export function createUploadsClient(config) {
         if (opts.cursor)
             params.set("cursor", opts.cursor);
         const qs = params.toString();
-        return request("GET", `${filesBase(config)}${qs ? `?${qs}` : ""}`);
+        const page = await request("GET", `${filesBase(config)}${qs ? `?${qs}` : ""}`);
+        return {
+            ...page,
+            items: page.items.map((item) => ({
+                ...item,
+                embedUrl: resolveEmbedUrl(item.url, item.embedUrl),
+            })),
+        };
     }
     async function getGallery(id) {
         return request("GET", `${galleriesBase(config)}/${encodeURIComponent(id)}`);
@@ -223,6 +265,20 @@ export function createUploadsClient(config) {
                     deriveRepoFromGit: opts.deriveRepoFromGit,
                 }));
             const contentType = opts.contentType ?? inferContentType(opts.filename);
+            if (opts.dryRun) {
+                const preview = await request("PUT", `${filesBase(config)}/${encodeKeyPath(key)}?dryRun=1`);
+                if (preview.url == null) {
+                    throw new UploadsError("workspace has no publicBaseUrl (cannot resolve a public URL)", "NO_PUBLIC_URL");
+                }
+                return {
+                    workspace: preview.workspace,
+                    key: preview.key,
+                    url: preview.url,
+                    embedUrl: resolveEmbedUrl(preview.url, preview.embedUrl),
+                    size: body.byteLength,
+                    contentType,
+                };
+            }
             const headers = { "Content-Type": contentType };
             if (opts.provenance) {
                 for (const [k, v] of Object.entries(opts.provenance)) {
@@ -230,6 +286,14 @@ export function createUploadsClient(config) {
                         headers[`X-Uploads-Meta-${k}`] = v;
                 }
             }
+            // Same header prefix as provenance above; the server splits allowlisted
+            // provenance keys (R2) from everything else (D1 file_metadata) by name.
+            if (opts.metadata) {
+                for (const [k, v] of Object.entries(opts.metadata)) {
+                    if (v !== undefined && v !== "")
+                        headers[`X-Uploads-Meta-${k}`] = v;
+                }
+            }
             const result = await request("PUT", `${filesBase(config)}/${encodeKeyPath(key)}`, {
                 body,
                 headers,
@@ -237,7 +301,11 @@ export function createUploadsClient(config) {
             if (result.url == null) {
                 throw new UploadsError("upload succeeded but workspace has no publicBaseUrl", "NO_PUBLIC_URL", 201);
             }
-            return { ...result, url: result.url };
+            return {
+                ...result,
+                url: result.url,
+                embedUrl: resolveEmbedUrl(result.url, result.embedUrl),
+            };
         },
         list,
         /** Follow cursors (optionally starting from one) and return every remaining item. */
@@ -254,8 +322,34 @@ export function createUploadsClient(config) {
         async delete(key) {
             return request("DELETE", `${filesBase(config)}/${encodeKeyPath(key)}`);
         },
+        /** `GET /v1/:workspace/files/:key?metadata=1` — the object's queryable metadata. */
+        async getMetadata(key) {
+            return request("GET", `${filesBase(config)}/${encodeKeyPath(key)}?metadata=1`);
+        },
+        /** `PATCH /v1/:workspace/files/:key` — merge `set`/`delete`; returns the merged map. */
+        async patchMetadata(key, opts) {
+            return request("PATCH", `${filesBase(config)}/${encodeKeyPath(key)}`, {
+                body: new TextEncoder().encode(JSON.stringify(opts)),
+                headers: { "Content-Type": "application/json" },
+            });
+        },
+        /**
+         * `GET /v1/:workspace/files?meta.<k>=<v>&…` — ANDed equality filter over
+         * queryable metadata. `filters` must be pre-validated (see `metadata.ts`).
+         */
+        async findFiles(filters, opts = {}) {
+            const params = new URLSearchParams();
+            for (const [k, v] of Object.entries(filters))
+                params.append(`meta.${k}`, v);
+            if (opts.prefix)
+                params.set("prefix", opts.prefix);
+            if (opts.limit != null)
+                params.set("limit", String(opts.limit));
+            return request("GET", `${filesBase(config)}?${params.toString()}`);
+        },
         async head(key) {
-            return request("GET", `${filesBase(config)}/${encodeKeyPath(key)}`);
+            const result = await request("GET", `${filesBase(config)}/${encodeKeyPath(key)}`);
+            return { ...result, embedUrl: resolveEmbedUrl(result.url, result.embedUrl) };
         },
         async createGallery(opts) {
             return request("POST", galleriesBase(config), {