@buildinternet/uploads 0.4.0 → 0.6.0

package/README.md

@@ -4,15 +4,16 @@ CLI and client for **uploads.sh** — upload files, get public URLs, and produce
 
 ## CLI
 
-Binary: **`uploads`**. Install globally (or use a pinned `npx` one-shot):
+Binary: **`uploads`**. Install globally (or use an `npx` one-shot):
 
 ```bash
 npm install --global @buildinternet/uploads
-npx @buildinternet/uploads@0.1.0 --help
+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/agent.js

@@ -15,7 +15,7 @@ export function createUploadsWorkerFileTools(files, opts = {}) {
         },
         overrides: {
             uploadFile: {
-                description: "Upload a file for public hosting (e.g. GitHub embeds). Prefer keys under screenshots/.",
+                description: "Upload a non-sensitive file for public hosting (e.g. GitHub embeds). GitHub repository visibility does not restrict access; prefer keys under screenshots/.",
             },
             ...overrides,
         },

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
@@ -45,7 +49,7 @@ Commands:
   setup               Inspect/configure advanced CLI settings
   install             Install the agent skill + register the remote MCP server
   login               Exchange an enrollment code and configure credentials
-  admin               Admin enrollment management
+  admin               Admin invitation management
   config              Show path, init, or set shared config
   doctor              Health + auth + workspace checks
   health              API liveness (no auth)
@@ -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,79 @@ 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;
+    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;
 }
@@ -101,14 +174,17 @@ export interface EnrollmentExchangeResult {
     expiresAt?: string;
 }
 export interface EnrollmentCreateResult {
+    pageId: string;
     code: string;
     expiresAt: string;
     tokenExpiresAt: string;
+    emailed?: boolean;
 }
 export declare function exchangeEnrollment(apiUrl: string, code: string): Promise<EnrollmentExchangeResult>;
 export declare function createEnrollment(apiUrl: string, adminToken: string, input: {
     workspace?: string;
     label?: string;
+    email?: string;
     enrollmentSeconds?: number;
     tokenExpiresInSeconds?: number;
     scopes?: Array<"files:read" | "files:write" | "files:delete">;
@@ -124,6 +200,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

@@ -36,21 +36,24 @@ 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 || normalized === "unauthorized") {
+    if (status === 401 || code === "unauthorized" || normalized === "unauthorized") {
         return new UploadsError(error, "UNAUTHORIZED", status);
     }
-    if (status === 404 || normalized === "not found") {
+    if (status === 404 || code === "not_found" || normalized === "not found") {
         return new UploadsError(error, "NOT_FOUND", status);
     }
-    if (status === 400 && normalized === "invalid key") {
+    if (code === "invalid_key" || (status === 400 && normalized === "invalid key")) {
         return new UploadsError(error, "INVALID_KEY", status);
     }
     if (code === "key_prefix_not_allowed" || code === "key_too_deep") {
         return new UploadsError(error, "KEY_POLICY", status);
     }
-    // Prefer stable body.code — bare 429 is also used for write rate limits.
+    // Prefer stable body code — bare 429 is also used for write rate limits.
     if (status === 507 || code === "storage_quota_exceeded") {
         return new UploadsError(error, "STORAGE_QUOTA", status);
     }
@@ -59,15 +62,34 @@ function mapApiError(status, error, code) {
     }
     return new UploadsError(error, "API_ERROR", status);
 }
+/**
+ * Parse API error bodies. Prefers the nested envelope
+ * `{ error: { code, type, message, details? } }`; still accepts the legacy
+ * flat `{ error: string, code?: string }` shape.
+ */
+function extractErrorFields(body) {
+    if (typeof body === "object" && body && "error" in body) {
+        const err = body.error;
+        if (typeof err === "object" && err && "message" in err) {
+            const nested = err;
+            return {
+                message: typeof nested.message === "string" ? nested.message : "request failed",
+                code: typeof nested.code === "string" ? nested.code : undefined,
+            };
+        }
+        if (typeof err === "string") {
+            const code = "code" in body && typeof body.code === "string"
+                ? body.code
+                : undefined;
+            return { message: err, code };
+        }
+    }
+    return { message: "request failed" };
+}
 async function parseErrorResponse(res) {
     const body = await res.json().catch(() => ({}));
-    const message = typeof body === "object" && body && "error" in body && typeof body.error === "string"
-        ? body.error
-        : res.statusText || "request failed";
-    const code = typeof body === "object" && body && "code" in body && typeof body.code === "string"
-        ? body.code
-        : undefined;
-    return mapApiError(res.status, message, code);
+    const { message, code } = extractErrorFields(body);
+    return mapApiError(res.status, message || res.statusText || "request failed", code);
 }
 export function createUploadsClient(config) {
     async function request(method, path, opts) {
@@ -105,6 +127,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 ??
@@ -151,6 +176,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 });
         },

package/dist/commands/admin-enrollment.d.ts

@@ -1,4 +1,6 @@
 type FileScope = "files:read" | "files:write" | "files:delete";
+export declare function invitePageUrl(apiUrl: string, pageId: string, webUrl?: string): string;
+export declare function inviteMagicLink(pageUrl: string, code: string): string;
 export declare function parseScopes(raw: string | undefined): FileScope[] | undefined;
 export declare function runAdmin(args: string[], opts: {
     json?: boolean;