@buildinternet/uploads 0.5.0 → 0.7.0

package/README.md

@@ -13,6 +13,7 @@ npx @buildinternet/uploads --help
 
 ```bash
 uploads setup
+uploads --version
 uploads attach ./before.png ./after.png
 uploads put ./shot.png
 uploads put ./shot.png --destination screenshots
@@ -20,6 +21,8 @@ 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 gallery create --title "Release screenshots"
+uploads put ./after.png --gallery gal_example
 uploads doctor
 ```
 
@@ -27,12 +30,20 @@ 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`, `comment`, `list`, `delete`, `usage`, `reconcile`,
+Commands: `attach`, `put`, `gallery`, `comment`, `list`, `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`.
+
+**Update hints:** after a successful run the CLI may print one stderr line when a
+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`.
+
 `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 managed attachments comment. Use `--pr`, `--issue`, and `--repo` to select
+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
 the target explicitly, or `--no-comment` to upload without changing GitHub comments.
 
 **Keys / destinations:** default put uses the `screenshots` layout. Typed destinations
@@ -50,11 +61,33 @@ stripped**. Pass `--keep-exif` / `UPLOADS_KEEP_EXIF=1` to preserve image metadat
 community art from [device-frames-media](https://github.com/jonnyjackson26/device-frames-media)
 into `~/.cache/uploads/frames` (not bundled).
 
+## Public galleries
+
+Create an ordered gallery, then add existing uploads by key. The API returns the canonical
+public URL; the CLI never constructs it. **Anyone who knows that URL can view the gallery and
+its media**—GitHub or repository visibility does not restrict it. Deleting a gallery removes
+only the gallery record, not its uploaded objects or their retention policy. A workspace can hold up to 100 active galleries, each with up to 100 items and 20 external references.
+
+```bash
+uploads gallery create --title "Release screenshots"
+uploads gallery add gal_example screenshots/myapp/42/after.webp --alt "Updated dashboard"
+uploads put ./before.png --gallery gal_example
+uploads gallery show gal_example
+uploads gallery link gal_example --github buildinternet/uploads#58
+uploads gallery list --github https://github.com/buildinternet/uploads/pull/58
+```
+
+When adding several keys, `uploads gallery add` processes them sequentially and reports any
+individual failures in `--json` output. Gallery item updates use the API's current version to
+avoid overwriting concurrent changes.
+
+Link a gallery to a GitHub issue or pull request with `gallery link --github`. Run `uploads comment --pr <number>` (or use `put --comment`) to refresh that target’s one managed comment with every linked gallery and loose attachment. Coordinates and strict `https://github.com/<owner>/<repo>/issues|pull/<number>` URLs are accepted; `gallery list --github` performs the authenticated reverse lookup. Links never change gallery identity, and GitHub repository visibility does not make the public gallery private.
+
 Config layers (first match wins): CLI flags → env vars → `--env-file` → `~/.config/buildinternet/config`. See `config.example` for keys.
 
 ## MCP server
 
-`uploads mcp` serves the Model Context Protocol over stdio (newline-delimited JSON-RPC, no extra dependencies). Tools mirror the CLI commands one-to-one — `put`, `attach`, `list`, `delete`, `usage`, `reconcile`, `purge_expired`, `comment`, `health`, `doctor` — with the same config resolution and defaults, plus a per-call `workspace` argument. Interactive/credential commands (`setup`, `login`, `admin`, `config`) are not exposed. A token isn't required to start the server; auth errors surface per tool call (`health` needs no auth).
+`uploads mcp` serves the Model Context Protocol over stdio (newline-delimited JSON-RPC, no extra dependencies). Tools include file operations plus public gallery workflows: `gallery_create`, `gallery_get`, `gallery_add`, `gallery_link`, and `gallery_find_by_reference`. Gallery tools return API-provided canonical URLs and never need GitHub credentials. The remaining stdio tools are `put`, `attach`, `list`, `delete`, `usage`, `reconcile`, `purge_expired`, `comment`, `health`, and `doctor` — with the same config resolution and defaults, plus a per-call `workspace` argument. Interactive/credential commands (`setup`, `login`, `admin`, `config`) are not exposed. A token isn't required to start the server; auth errors surface per tool call (`health` needs no auth).
 
 ```json
 { "command": "uploads", "args": ["--env-file", "/path/to/.env", "mcp"] }
@@ -62,7 +95,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: put/list/delete/health, same bearer tokens as the REST 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 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.
 
 ## Programmatic use
 
@@ -76,14 +109,16 @@ Agent/MCP helpers: `@buildinternet/uploads/agent` (`createUploadsWorkerFileTools
 
 ```
 src/
-  cli.ts            Entry + help
-  commands.ts       put, list, delete, comment, …
-  commands/mcp.ts   `mcp` command entry
-  mcp/              Stdio MCP server (server.ts, tools.ts)
-  client.ts         HTTP client for the API
-  github.ts         PR/issue key paths + attachment comments
-  embed.ts          Markdown image output
-bin/uploads.js      Bin shim
+  cli.ts              Entry + help
+  package-version.ts  Shared version for --version / doctor / headers
+  update-check.ts     Optional npm update hint (stderr)
+  commands.ts         put, list, delete, comment, …
+  commands/mcp.ts     `mcp` command entry
+  mcp/                Stdio MCP server (server.ts, tools.ts)
+  client.ts           HTTP client for the API
+  github.ts           PR/issue key paths + attachment comments
+  embed.ts            Markdown image output
+bin/uploads.js        Bin shim
 ```
 
 ## Commands

package/dist/cli-args.d.ts

@@ -5,6 +5,8 @@ export interface GlobalFlags {
     envFile?: string;
     json?: boolean;
     quiet?: boolean;
+    /** `--version` / `-V` — print package version and exit. */
+    version?: boolean;
 }
 export interface ParsedArgv {
     globals: GlobalFlags;

package/dist/cli-args.js

@@ -28,6 +28,11 @@ export function parseArgv(argv) {
             i++;
             continue;
         }
+        if (arg === "--version" || arg === "-V") {
+            globals.version = true;
+            i++;
+            continue;
+        }
         if (VALUE_GLOBALS.has(arg)) {
             const value = args[i + 1];
             if (!value || value.startsWith("-")) {

package/dist/cli.js

@@ -2,13 +2,15 @@ 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, } from "./commands.js";
+import { runPut, runAttach, runList, 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 { runAdmin } from "./commands/admin-enrollment.js";
 import { runMcp } from "./commands/mcp.js";
 import { runInstall } from "./commands/install.js";
+import { packageVersion } from "./package-version.js";
+import { maybeHintUpdate } from "./update-check.js";
 const ROOT_HELP = `uploads — CLI for uploads.sh (GitHub image embeds)
 
 Usage:
@@ -31,11 +33,13 @@ Other globals (before command):
   --token <token>     or UPLOADS_TOKEN
   --env-file <path>
   --json              JSON on stdout
-  --quiet
+  --quiet             Suppress stderr progress and update hints
+  --version, -V       Print package version and exit
 
 Commands:
   attach <file...>     Attach media to the current PR (stable URLs + managed comment)
   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
   delete <key>        Delete object
@@ -44,7 +48,7 @@ Commands:
   purge-expired       Delete objects past retentionDays
   setup               Inspect/configure advanced CLI settings
   install             Install the agent skill + register the remote MCP server
-  login               Exchange an enrollment code and configure credentials
+  login               Sign in via browser (or an enrollment code) and save credentials
   admin               Admin invitation management
   config              Show path, init, or set shared config
   doctor              Health + auth + workspace checks
@@ -55,12 +59,16 @@ Put/list defaults (config file or env):
   UPLOADS_DEFAULT_PREFIX, UPLOADS_DEFAULT_REPO, UPLOADS_DEFAULT_REF
   UPLOADS_DEFAULT_WIDTH, UPLOADS_NO_GIT
 
+Update hints (stderr, once/day): silence with --quiet / UPLOADS_NO_UPDATE=1 / NO_UPDATE_NOTIFIER=1
+
 Examples:
   uploads setup
   uploads setup --token up_default_… --repo myorg/myapp
   uploads attach ./before.png ./after.png
   uploads put ./shot.png --ref 42
+  uploads gallery create --title "Release screenshots"
   uploads doctor
+  uploads --version
 
 Agent/MCP: \`uploads install\` sets up the agent skill and the hosted MCP server
 (https://agents.uploads.sh/mcp, workspace inferred from the token). Run
@@ -133,33 +141,57 @@ function errorOut(err, json) {
         }
     }
 }
+/** Point agents at layered --help instead of dumping the full root manual. */
+function usageHint(argv) {
+    try {
+        const cmd = parseArgv(argv).command;
+        process.stderr.write(cmd ? `hint: uploads ${cmd} --help\n` : "hint: uploads --help\n");
+    }
+    catch {
+        process.stderr.write("hint: uploads --help\n");
+    }
+}
 export async function runCli(argv) {
     try {
         const parsed = parseArgv(argv);
         const json = parsed.globals.json ?? false;
+        const quiet = parsed.globals.quiet ?? false;
+        if (parsed.globals.version) {
+            process.stdout.write(`${packageVersion()}\n`);
+            return 0;
+        }
         if (!parsed.command) {
             process.stderr.write(ROOT_HELP);
             return parsed.help ? 0 : 2;
         }
         const cmdArgs = parsed.rest.slice(1);
         const showHelp = parsed.help || cmdArgs.some(isHelpFlag);
+        let code;
         switch (parsed.command) {
             case "health":
-                return runHealth({ apiUrl: resolveApiUrl(parsed.globals), json }, cmdArgs, showHelp);
+                code = await runHealth({ apiUrl: resolveApiUrl(parsed.globals), json }, cmdArgs, showHelp);
+                break;
             case "config":
-                return runConfig(cmdArgs, { json, envFile: parsed.globals.envFile }, showHelp);
+                code = await runConfig(cmdArgs, { json, envFile: parsed.globals.envFile }, showHelp);
+                break;
             case "setup":
-                return runSetup(cmdArgs, { json, envFile: parsed.globals.envFile }, showHelp);
+                code = await runSetup(cmdArgs, { json, envFile: parsed.globals.envFile }, showHelp);
+                break;
             case "login":
-                return runLogin(cmdArgs, { json, apiUrl: resolveApiUrl(parsed.globals) }, showHelp);
+                code = await runLogin(cmdArgs, { json, apiUrl: resolveApiUrl(parsed.globals) }, showHelp);
+                break;
             case "admin":
-                return runAdmin(cmdArgs, { json, apiUrl: resolveApiUrl(parsed.globals) }, showHelp);
+                code = await runAdmin(cmdArgs, { json, apiUrl: resolveApiUrl(parsed.globals) }, showHelp);
+                break;
             case "mcp":
-                return runMcp(cmdArgs, { globals: parsed.globals }, showHelp);
+                code = await runMcp(cmdArgs, { globals: parsed.globals }, showHelp);
+                break;
             case "install":
-                return runInstall(cmdArgs, { globals: parsed.globals, json }, showHelp);
+                code = await runInstall(cmdArgs, { globals: parsed.globals, json }, showHelp);
+                break;
             case "attach":
             case "put":
+            case "gallery":
             case "list":
             case "delete":
             case "usage":
@@ -170,34 +202,52 @@ export async function runCli(argv) {
                 const ctx = createContext(parsed.globals, !showHelp, cmdArgs);
                 switch (parsed.command) {
                     case "attach":
-                        return runAttach(ctx, cmdArgs, showHelp);
+                        code = await runAttach(ctx, cmdArgs, showHelp);
+                        break;
                     case "put":
-                        return runPut(ctx, cmdArgs, showHelp);
+                        code = await runPut(ctx, cmdArgs, showHelp);
+                        break;
+                    case "gallery":
+                        code = await runGallery(ctx, cmdArgs, showHelp);
+                        break;
                     case "comment":
-                        return runComment(ctx, cmdArgs, showHelp);
+                        code = await runComment(ctx, cmdArgs, showHelp);
+                        break;
                     case "list":
-                        return runList(ctx, cmdArgs, showHelp);
+                        code = await runList(ctx, cmdArgs, showHelp);
+                        break;
                     case "delete":
-                        return runDelete(ctx, cmdArgs, showHelp);
+                        code = await runDelete(ctx, cmdArgs, showHelp);
+                        break;
                     case "usage":
-                        return runUsage(ctx, cmdArgs, showHelp);
+                        code = await runUsage(ctx, cmdArgs, showHelp);
+                        break;
                     case "reconcile":
-                        return runReconcile(ctx, cmdArgs, showHelp);
+                        code = await runReconcile(ctx, cmdArgs, showHelp);
+                        break;
                     case "purge-expired":
-                        return runPurgeExpired(ctx, cmdArgs, showHelp);
+                        code = await runPurgeExpired(ctx, cmdArgs, showHelp);
+                        break;
                     case "doctor":
-                        return runDoctor(ctx, cmdArgs, showHelp);
+                        code = await runDoctor(ctx, cmdArgs, showHelp);
+                        break;
                 }
+                break;
             }
             default:
                 process.stderr.write(`unknown command: ${parsed.command}\n\n${ROOT_HELP}`);
                 return 2;
         }
+        // Best-effort; skipped for mcp, --quiet/--json, and opt-out env vars.
+        if (code === 0 && !showHelp) {
+            await maybeHintUpdate({ quiet: quiet || json, command: parsed.command });
+        }
+        return code;
     }
     catch (err) {
         errorOut(err, argv.includes("--json"));
         if (err instanceof UsageError && !argv.includes("--json"))
-            process.stderr.write(`\n${ROOT_HELP}`);
+            usageHint(argv);
         return exitCode(err);
     }
 }

package/dist/client.d.ts

@@ -53,6 +53,81 @@ export interface DeleteResult {
     key: string;
     deleted: boolean;
 }
+/** A workspace-owned, publicly visible ordered media gallery. */
+export interface GalleryItem {
+    id: string;
+    objectKey: string;
+    position: number;
+    caption: string | null;
+    altText: string | null;
+    createdAt: string;
+    status: "available" | "missing";
+    url: string | null;
+    /** Standalone web page for this item (gallery URL + item id). Absent on older API deployments. */
+    pageUrl?: string;
+    contentType: string | null;
+    size: number | null;
+}
+export interface Gallery {
+    id: string;
+    /** Canonical public URL returned by the API; clients must not construct it. */
+    url: string;
+    workspace: string;
+    title: string;
+    description: string | null;
+    visibility: "public";
+    coverItemId: string | null;
+    version: number;
+    createdAt: string;
+    updatedAt: string;
+    items: GalleryItem[];
+}
+export type GallerySummary = Omit<Gallery, "items">;
+export interface GalleryListOptions {
+    limit?: number;
+    cursor?: string;
+}
+export interface GalleryListResult {
+    galleries: GallerySummary[];
+    nextCursor: string | null;
+}
+export interface CreateGalleryOptions {
+    title: string;
+    description?: string | null;
+}
+export interface AddGalleryItemOptions {
+    expectedVersion: number;
+    caption?: string | null;
+    altText?: string | null;
+}
+export interface DeleteGalleryOptions {
+    expectedVersion: number;
+}
+export interface GalleryExternalReference {
+    id: string;
+    provider: "github";
+    resourceType: "item";
+    coordinate: string;
+    canonicalUrl: string | null;
+    createdAt: string;
+}
+export interface GalleryExternalReferenceListResult {
+    references: GalleryExternalReference[];
+}
+export interface LinkGalleryExternalReferenceOptions {
+    expectedVersion: number;
+    provider: "github";
+    coordinate: string;
+}
+export interface UnlinkGalleryExternalReferenceOptions {
+    expectedVersion: number;
+}
+export interface FindGalleriesByReferenceOptions {
+    provider: "github";
+    coordinate: string;
+    limit?: number;
+    cursor?: string;
+}
 export interface HealthResult {
     ok: boolean;
 }
@@ -116,6 +191,72 @@ export declare function createEnrollment(apiUrl: string, adminToken: string, inp
     tokenExpiresInSeconds?: number;
     scopes?: Array<"files:read" | "files:write" | "files:delete">;
 }): Promise<EnrollmentCreateResult>;
+/** Static OAuth client id allowlisted by the auth worker's `validateClient`. */
+export declare const DEVICE_CLIENT_ID = "uploads-cli";
+export interface DeviceCodeResponse {
+    device_code: string;
+    user_code: string;
+    verification_uri: string;
+    verification_uri_complete?: string;
+    expires_in: number;
+    interval: number;
+}
+/** POST /api/auth/device/code — start a device flow. Throws on a non-2xx. */
+export declare function requestDeviceCode(authUrl: string, clientId?: string): Promise<DeviceCodeResponse>;
+/**
+ * One poll of POST /api/auth/device/token. Unlike most calls, the "not ready
+ * yet" outcomes (`authorization_pending`, `slow_down`) are EXPECTED 400s, so
+ * this returns a discriminated result instead of throwing — the caller's poll
+ * loop branches on `status`.
+ */
+export type DeviceTokenResult = {
+    status: "ok";
+    accessToken: string;
+    tokenType: string;
+    expiresIn: number;
+    scope: string;
+} | {
+    status: "pending";
+} | {
+    status: "slow_down";
+} | {
+    status: "expired";
+} | {
+    status: "denied";
+} | {
+    status: "error";
+    error: string;
+    description?: string;
+};
+export declare function requestDeviceToken(authUrl: string, input: {
+    deviceCode: string;
+    clientId?: string;
+}): Promise<DeviceTokenResult>;
+export interface MintWorkspaceSummary {
+    workspace: string;
+    role: string;
+}
+/** GET /v1/tokens — workspaces the signed-in user can mint tokens for. */
+export declare function listMintWorkspaces(apiUrl: string, accessToken: string): Promise<{
+    workspaces: MintWorkspaceSummary[];
+}>;
+export interface MintTokenResult {
+    token: string;
+    workspace: string;
+    scopes: Array<"files:read" | "files:write" | "files:delete">;
+    label: string | null;
+    expiresAt: string | null;
+}
+/**
+ * POST /v1/tokens — mint a `up_<workspace>_…` workspace token from a device-flow
+ * session (presented as a bearer). v1 sends exactly one grant.
+ */
+export declare function mintWorkspaceToken(apiUrl: string, accessToken: string, input: {
+    workspace: string;
+    scopes?: Array<"files:read" | "files:write" | "files:delete">;
+    label?: string;
+    ttlSeconds?: number;
+}): Promise<MintTokenResult>;
 export declare function createUploadsClient(config: UploadsClientConfig): {
     put(body: Uint8Array, opts: PutOptions & {
         filename: string;
@@ -127,6 +268,21 @@ export declare function createUploadsClient(config: UploadsClientConfig): {
     }): Promise<ListItem[]>;
     delete(key: string): Promise<DeleteResult>;
     head(key: string): Promise<HeadResult>;
+    createGallery(opts: CreateGalleryOptions): Promise<Gallery>;
+    getGallery(id: string): Promise<Gallery>;
+    listGalleries(opts?: GalleryListOptions): Promise<GalleryListResult>;
+    deleteGallery(id: string, opts: DeleteGalleryOptions): Promise<{
+        deleted: boolean;
+        id: string;
+    }>;
+    addGalleryItem(id: string, objectKey: string, opts: AddGalleryItemOptions): Promise<GalleryItem>;
+    listGalleryExternalReferences(id: string): Promise<GalleryExternalReferenceListResult>;
+    linkGalleryExternalReference(id: string, opts: LinkGalleryExternalReferenceOptions): Promise<GalleryExternalReference>;
+    unlinkGalleryExternalReference(id: string, referenceId: string, opts: UnlinkGalleryExternalReferenceOptions): Promise<{
+        deleted: boolean;
+        id: string;
+    }>;
+    findGalleriesByReference(opts: FindGalleriesByReferenceOptions): Promise<GalleryListResult>;
     health(): Promise<HealthResult>;
     /** Workspace storage / upload counters (+ limits when configured). */
     usage(): Promise<UsageResult>;

package/dist/client.js

@@ -27,6 +27,87 @@ export function createEnrollment(apiUrl, adminToken, input) {
         body: JSON.stringify(input),
     });
 }
+// --- Device authorization (RFC 8628) — the `uploads login` device flow ---
+//
+// The CLI speaks the auth worker's OAuth-shaped endpoints directly with plain
+// `fetch` (no better-auth client dependency in the published package, per plan
+// D5). Better Auth's `device.code`/`device.token` endpoints take
+// `application/json` bodies, NOT the RFC's form-encoding — the JSON shapes
+// below are what the worker expects.
+/** Static OAuth client id allowlisted by the auth worker's `validateClient`. */
+export const DEVICE_CLIENT_ID = "uploads-cli";
+/** 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" },
+        body: JSON.stringify({ client_id: clientId }),
+    });
+}
+export async function requestDeviceToken(authUrl, input) {
+    let res;
+    try {
+        res = await fetch(`${authUrl.replace(/\/$/, "")}/api/auth/device/token`, {
+            method: "POST",
+            headers: { "Content-Type": "application/json" },
+            body: JSON.stringify({
+                grant_type: "urn:ietf:params:oauth:grant-type:device_code",
+                device_code: input.deviceCode,
+                client_id: input.clientId ?? DEVICE_CLIENT_ID,
+            }),
+        });
+    }
+    catch (err) {
+        throw new UploadsError(err instanceof Error ? err.message : "network request failed", "NETWORK");
+    }
+    const body = (await res.json().catch(() => null));
+    if (res.ok && body?.access_token) {
+        return {
+            status: "ok",
+            accessToken: body.access_token,
+            tokenType: body.token_type ?? "Bearer",
+            expiresIn: typeof body.expires_in === "number" ? body.expires_in : 0,
+            scope: body.scope ?? "",
+        };
+    }
+    switch (body?.error) {
+        case "authorization_pending":
+            return { status: "pending" };
+        case "slow_down":
+            return { status: "slow_down" };
+        case "expired_token":
+            return { status: "expired" };
+        case "access_denied":
+            return { status: "denied" };
+        default:
+            return {
+                status: "error",
+                error: body?.error ?? "unknown",
+                description: body?.error_description,
+            };
+    }
+}
+/** GET /v1/tokens — workspaces the signed-in user can mint tokens for. */
+export function listMintWorkspaces(apiUrl, accessToken) {
+    return jsonRequest(`${apiUrl.replace(/\/$/, "")}/v1/tokens`, {
+        headers: { Authorization: `Bearer ${accessToken}` },
+    });
+}
+/**
+ * POST /v1/tokens — mint a `up_<workspace>_…` workspace token from a device-flow
+ * session (presented as a bearer). v1 sends exactly one grant.
+ */
+export function mintWorkspaceToken(apiUrl, accessToken, input) {
+    return jsonRequest(`${apiUrl.replace(/\/$/, "")}/v1/tokens`, {
+        method: "POST",
+        headers: { Authorization: `Bearer ${accessToken}`, "Content-Type": "application/json" },
+        body: JSON.stringify({
+            grants: [{ workspace: input.workspace, ...(input.scopes ? { scopes: input.scopes } : {}) }],
+            ...(input.label ? { label: input.label } : {}),
+            ...(input.ttlSeconds ? { ttlSeconds: input.ttlSeconds } : {}),
+        }),
+    });
+}
 function encodeKeyPath(key) {
     return key.split("/").map(encodeURIComponent).join("/");
 }
@@ -36,6 +117,9 @@ function filesBase(config) {
 function usageBase(config) {
     return `${config.apiUrl}/v1/${encodeURIComponent(config.workspace)}/usage`;
 }
+function galleriesBase(config) {
+    return `${config.apiUrl}/v1/${encodeURIComponent(config.workspace)}/galleries`;
+}
 function mapApiError(status, error, code) {
     const normalized = error.toLowerCase();
     if (status === 401 || code === "unauthorized" || normalized === "unauthorized") {
@@ -124,6 +208,9 @@ export function createUploadsClient(config) {
         const qs = params.toString();
         return request("GET", `${filesBase(config)}${qs ? `?${qs}` : ""}`);
     }
+    async function getGallery(id) {
+        return request("GET", `${galleriesBase(config)}/${encodeURIComponent(id)}`);
+    }
     return {
         async put(body, opts) {
             const key = opts.key ??
@@ -170,6 +257,63 @@ export function createUploadsClient(config) {
         async head(key) {
             return request("GET", `${filesBase(config)}/${encodeKeyPath(key)}`);
         },
+        async createGallery(opts) {
+            return request("POST", galleriesBase(config), {
+                body: new TextEncoder().encode(JSON.stringify(opts)),
+                headers: { "Content-Type": "application/json" },
+            });
+        },
+        async getGallery(id) {
+            return getGallery(id);
+        },
+        async listGalleries(opts = {}) {
+            const params = new URLSearchParams();
+            if (opts.limit != null)
+                params.set("limit", String(opts.limit));
+            if (opts.cursor)
+                params.set("cursor", opts.cursor);
+            const qs = params.toString();
+            return request("GET", `${galleriesBase(config)}${qs ? `?${qs}` : ""}`);
+        },
+        async deleteGallery(id, opts) {
+            return request("DELETE", `${galleriesBase(config)}/${encodeURIComponent(id)}`, {
+                body: new TextEncoder().encode(JSON.stringify(opts)),
+                headers: { "Content-Type": "application/json" },
+            });
+        },
+        async addGalleryItem(id, objectKey, opts) {
+            return request("POST", `${galleriesBase(config)}/${encodeURIComponent(id)}/items`, {
+                body: new TextEncoder().encode(JSON.stringify({ objectKey, ...opts })),
+                headers: { "Content-Type": "application/json" },
+            });
+        },
+        async listGalleryExternalReferences(id) {
+            return request("GET", galleriesBase(config) + "/" + encodeURIComponent(id) + "/external-references");
+        },
+        async linkGalleryExternalReference(id, opts) {
+            return request("POST", galleriesBase(config) + "/" + encodeURIComponent(id) + "/external-references", {
+                body: new TextEncoder().encode(JSON.stringify(opts)),
+                headers: { "Content-Type": "application/json" },
+            });
+        },
+        async unlinkGalleryExternalReference(id, referenceId, opts) {
+            return request("DELETE", galleriesBase(config) +
+                "/" +
+                encodeURIComponent(id) +
+                "/external-references/" +
+                encodeURIComponent(referenceId), {
+                body: new TextEncoder().encode(JSON.stringify(opts)),
+                headers: { "Content-Type": "application/json" },
+            });
+        },
+        async findGalleriesByReference(opts) {
+            const params = new URLSearchParams({ provider: opts.provider, coordinate: opts.coordinate });
+            if (opts.limit != null)
+                params.set("limit", String(opts.limit));
+            if (opts.cursor)
+                params.set("cursor", opts.cursor);
+            return request("GET", galleriesBase(config) + "/by-reference?" + params);
+        },
         async health() {
             return request("GET", `${config.apiUrl}/health`, { auth: false });
         },