@buildinternet/uploads 0.46.3 → 0.48.0

package/dist/client.d.ts

@@ -36,6 +36,13 @@ export interface PutOptions {
      * `KEY_EXISTS`.
      */
     replace?: boolean;
+    /**
+     * Reuse this key to safely retry the same upload request (issue #829). Not
+     * generated automatically — unlike `createGallery`, a `put` is only
+     * retried by the client (see `resilientFetch`) or is server-replay-safe
+     * when the caller supplies one; omit it and no header is sent.
+     */
+    idempotencyKey?: string;
 }
 export interface ListOptions {
     prefix?: string;
@@ -44,6 +51,12 @@ export interface ListOptions {
     /** Hydrate each row's queryable D1 metadata (`?metadata=1`). */
     metadata?: boolean;
 }
+/**
+ * Default page cap for `findFilesAll` / `uploads find --all`. Search is a
+ * bounded read on the server, so following its cursor is bounded on the client
+ * too rather than draining an unknown number of pages (issue #829 §4).
+ */
+export declare const FIND_FILES_MAX_PAGES = 20;
 export interface FindFilesOptions {
     prefix?: string;
     limit?: number;
@@ -52,6 +65,13 @@ export interface FindFilesOptions {
      * At least one of non-empty `filters` or `name` is required.
      */
     name?: string;
+    /**
+     * Opaque continuation from a previous result's `cursor`. Pass it back
+     * unchanged, with the same filters/name/prefix, to fetch the next page
+     * (issue #829 §4). A cursor minted for one search path is rejected by the
+     * other, so do not hand-build one.
+     */
+    cursor?: string;
 }
 export interface FindFilesItem {
     key: string;
@@ -201,6 +221,8 @@ export interface GalleryListResult {
 export interface CreateGalleryOptions {
     title: string;
     description?: string | null;
+    /** Reuse this key to safely retry the same create request. Generated when omitted. */
+    idempotencyKey?: string;
 }
 export interface AddGalleryItemOptions {
     expectedVersion: number;
@@ -417,6 +439,23 @@ export interface UsageResult {
     storageRemainingBytes?: number;
     maxUploadsPerPeriod?: number;
     uploadsRemaining?: number;
+    /** Bytes still on hosted storage (shared-lane residue). */
+    sharedBytes?: number;
+    /** "shared" = BYO bucket active: the storage cap meters only hosted
+     * residue; the customer's own bucket is unmetered. */
+    storageBudgetBasis?: "total" | "shared";
+    /** Bearer-safe lane summary (issue #775; servers ≥ this field's release). */
+    storage?: {
+        mode: "shared" | "byo";
+        /** Demoted former-active lanes that still serve previously uploaded files. */
+        fallbackLanes: number;
+        health: {
+            ok: boolean;
+            code?: string;
+            message?: string;
+            since?: string;
+        };
+    };
     /** File scopes of the presented token (servers ≥ this field's release). */
     scopes?: Array<TokenScope>;
     /**
@@ -592,6 +631,13 @@ export declare function mintWorkspaceToken(apiUrl: string, accessToken: string,
     scopes?: Array<TokenScope>;
     label?: string;
     ttlSeconds?: number | null;
+    /**
+     * Optional retry key. Reusing it (same effective request, within 24h)
+     * replays the original response — including the one-time plaintext token —
+     * instead of minting a second token. A changed request with the same key
+     * returns 409.
+     */
+    idempotencyKey?: string;
 }): Promise<MintTokenResult>;
 /**
  * Parse API error bodies. Prefers the nested envelope
@@ -632,10 +678,24 @@ export declare function createUploadsClient(config: UploadsClientConfig): {
      * ANDed equality filter over queryable metadata and/or a case-insensitive
      * filename substring. At least one of non-empty `filters` or `opts.name`
      * is required. `filters` must be pre-validated when present (see
-     * `metadata.ts`). The canonical search route is non-paginated (server cap
-     * 100, narrowable via `limit`), so `cursor` is always null.
+     * `metadata.ts`). The page is capped server-side (100, narrowable via
+     * `limit`); when more matches exist the result carries an opaque `cursor`
+     * to pass back as `opts.cursor` for the next page, and null when the last
+     * page has been reached.
+     */
+    findFiles: (filters?: Record<string, string>, opts?: FindFilesOptions) => Promise<FindFilesResult>;
+    /**
+     * `findFiles` followed through its `cursor`, up to `maxPages` requests
+     * (default `FIND_FILES_MAX_PAGES`). Bounded on purpose: search pages are
+     * the expensive read path, so draining is capped rather than open-ended.
+     * The returned `cursor` is non-null when the cap stopped the drain early —
+     * pass it back to continue from there.
+     *
+     * `maxPages` must be a finite positive number. Anything else (`Infinity`,
+     * `NaN`, zero, a negative) falls back to the default rather than removing
+     * the bound or silently fetching nothing.
      */
-    findFiles(filters?: Record<string, string>, opts?: FindFilesOptions): Promise<FindFilesResult>;
+    findFilesAll(filters?: Record<string, string>, opts?: FindFilesOptions, maxPages?: number): Promise<FindFilesResult>;
     /** `GET /v1/:workspace/files/facets` — workspace metadata key vocabulary. */
     listMetadataKeys(): Promise<MetadataKeysResult>;
     /** `GET /v1/:workspace/files/facets?key=` — distinct values for one key. */

package/dist/client.js

@@ -4,6 +4,12 @@ import { UploadsError } from "./errors.js";
 import { buildScreenshotKey } from "./keys.js";
 import { packageVersion } from "./package-version.js";
 import { resolveEmbedUrl } from "./public-urls.js";
+/**
+ * Default page cap for `findFilesAll` / `uploads find --all`. Search is a
+ * bounded read on the server, so following its cursor is bounded on the client
+ * too rather than draining an unknown number of pages (issue #829 §4).
+ */
+export const FIND_FILES_MAX_PAGES = 20;
 // --- Request resilience (issue #809) ---------------------------------------
 //
 // Bare `fetch` has no timeout — undici's default header timeout is ~5
@@ -18,12 +24,17 @@ import { resolveEmbedUrl } from "./public-urls.js";
 // gap on the core path).
 const JSON_TIMEOUT_MS = 15_000;
 const CONTENT_TIMEOUT_MS = 60_000;
-// At most one retry. Retried on network errors, 503, and 429 — and only for
-// GET/PUT, since a `put` is byte-idempotent (same key, same bytes) but a
-// POST/DELETE/PATCH might not be, and telling "no bytes sent" apart from "the
-// mutation already landed" isn't reliable enough to risk a double-apply.
+// At most one retry. Retried on network errors, 503, and 429 — GET always.
+// POST and PUT are retryable only when the request carries an
+// Idempotency-Key (gallery-create's POST, and an upload PUT that opts in per
+// issue #829) — a bare PUT is no longer assumed byte-idempotent, since a
+// strict (non-`gh/`) key without a caller-supplied key can 409 `key_exists`
+// on replay. DELETE/PATCH remain single-attempt because telling "no bytes
+// sent" apart from "the mutation already landed" isn't reliable enough to
+// risk a double-apply.
 const MAX_ATTEMPTS = 2;
-const RETRYABLE_METHODS = new Set(["GET", "PUT"]);
+const RETRYABLE_METHODS = new Set(["GET"]);
+const IDEMPOTENCY_KEYED_METHODS = new Set(["POST", "PUT"]);
 const RETRYABLE_STATUSES = new Set([429, 503]);
 const DEFAULT_RETRY_DELAY_MS = 2_000;
 // Cap an honored X-Retry-After so a large server-suggested backoff can't
@@ -76,7 +87,10 @@ async function fetchWithTimeout(url, init, timeoutMs) {
  * `!res.ok` themselves via `parseErrorResponse`.
  */
 async function resilientFetch(method, url, init, timeoutMs) {
-    const retryable = RETRYABLE_METHODS.has(method.toUpperCase());
+    const normalizedMethod = method.toUpperCase();
+    const retryable = RETRYABLE_METHODS.has(normalizedMethod) ||
+        (IDEMPOTENCY_KEYED_METHODS.has(normalizedMethod) &&
+            new Headers(init.headers).has("Idempotency-Key"));
     for (let attempt = 1;; attempt++) {
         let res;
         let networkErr;
@@ -265,7 +279,11 @@ export function createWorkspaceInvite(apiUrl, accessToken, workspace, input) {
 export function mintWorkspaceToken(apiUrl, accessToken, input) {
     return jsonRequest(`${apiUrl.replace(/\/$/, "")}/v1/tokens`, {
         method: "POST",
-        headers: { Authorization: `Bearer ${accessToken}`, "Content-Type": "application/json" },
+        headers: {
+            Authorization: `Bearer ${accessToken}`,
+            "Content-Type": "application/json",
+            ...(input.idempotencyKey ? { "Idempotency-Key": input.idempotencyKey } : {}),
+        },
         body: JSON.stringify({
             grants: [{ workspace: input.workspace, ...(input.scopes ? { scopes: input.scopes } : {}) }],
             ...(input.label ? { label: input.label } : {}),
@@ -386,14 +404,17 @@ export function createUploadsClient(config) {
             params.set("limit", String(opts.limit));
         if (opts.cursor)
             params.set("cursor", opts.cursor);
-        if (opts.metadata)
-            params.set("metadata", "1");
+        // The canonical route hydrates D1 metadata by default (issue #613 — the
+        // session shape won the reconciliation); when the caller didn't ask for
+        // `opts.metadata` this client discards it anyway below, so `metadata=0`
+        // opts out of the hydration pass server-side instead of paying for work
+        // whose result is thrown away (issue #829 §5).
+        params.set("metadata", opts.metadata ? "1" : "0");
         const qs = params.toString();
-        // Canonical list envelope is `{files, prefixes, cursor}` with queryable
-        // metadata always hydrated (issue #613 — the session shape won the
-        // reconciliation). This client keeps its historical `{items, cursor}`
-        // contract: rename the array and honor `opts.metadata` by stripping the
-        // hydrated maps when the caller didn't ask for them.
+        // Canonical list envelope is `{files, prefixes, cursor}`. This client
+        // keeps its historical `{items, cursor}` contract: rename the array and
+        // honor `opts.metadata` by stripping the hydrated maps when the caller
+        // didn't ask for them.
         const page = await request("GET", `${canonicalFilesBase(config)}${qs ? `?${qs}` : ""}`);
         return {
             cursor: page.cursor,
@@ -407,6 +428,25 @@ export function createUploadsClient(config) {
             }),
         };
     }
+    async function findFiles(filters = {}, opts = {}) {
+        const params = new URLSearchParams();
+        for (const [k, v] of Object.entries(filters))
+            params.append(`meta.${k}`, v);
+        if (opts.name)
+            params.set("name", opts.name);
+        if (opts.prefix)
+            params.set("prefix", opts.prefix);
+        if (opts.limit != null)
+            params.set("limit", String(opts.limit));
+        if (opts.cursor)
+            params.set("cursor", opts.cursor);
+        const result = await request("GET", `${canonicalFilesBase(config)}/search?${params.toString()}`);
+        return {
+            items: result.items,
+            cursor: result.cursor ?? null,
+            truncated: result.truncated,
+        };
+    }
     async function getGallery(id) {
         return request("GET", `${galleriesBase(config)}/${encodeURIComponent(id)}`);
     }
@@ -445,6 +485,8 @@ export function createUploadsClient(config) {
             const headers = { "Content-Type": contentType };
             if (opts.replace)
                 headers["X-Uploads-Replace"] = "1";
+            if (opts.idempotencyKey)
+                headers["Idempotency-Key"] = opts.idempotencyKey;
             if (opts.provenance) {
                 for (const [k, v] of Object.entries(opts.provenance)) {
                     if (v !== undefined && v !== "")
@@ -505,21 +547,37 @@ export function createUploadsClient(config) {
          * ANDed equality filter over queryable metadata and/or a case-insensitive
          * filename substring. At least one of non-empty `filters` or `opts.name`
          * is required. `filters` must be pre-validated when present (see
-         * `metadata.ts`). The canonical search route is non-paginated (server cap
-         * 100, narrowable via `limit`), so `cursor` is always null.
+         * `metadata.ts`). The page is capped server-side (100, narrowable via
+         * `limit`); when more matches exist the result carries an opaque `cursor`
+         * to pass back as `opts.cursor` for the next page, and null when the last
+         * page has been reached.
          */
-        async findFiles(filters = {}, opts = {}) {
-            const params = new URLSearchParams();
-            for (const [k, v] of Object.entries(filters))
-                params.append(`meta.${k}`, v);
-            if (opts.name)
-                params.set("name", opts.name);
-            if (opts.prefix)
-                params.set("prefix", opts.prefix);
-            if (opts.limit != null)
-                params.set("limit", String(opts.limit));
-            const result = await request("GET", `${canonicalFilesBase(config)}/search?${params.toString()}`);
-            return { items: result.items, cursor: null, truncated: result.truncated };
+        findFiles,
+        /**
+         * `findFiles` followed through its `cursor`, up to `maxPages` requests
+         * (default `FIND_FILES_MAX_PAGES`). Bounded on purpose: search pages are
+         * the expensive read path, so draining is capped rather than open-ended.
+         * The returned `cursor` is non-null when the cap stopped the drain early —
+         * pass it back to continue from there.
+         *
+         * `maxPages` must be a finite positive number. Anything else (`Infinity`,
+         * `NaN`, zero, a negative) falls back to the default rather than removing
+         * the bound or silently fetching nothing.
+         */
+        async findFilesAll(filters = {}, opts = {}, maxPages = FIND_FILES_MAX_PAGES) {
+            const items = [];
+            let cursor = opts.cursor;
+            let truncated;
+            const pages = Number.isFinite(maxPages) && maxPages >= 1 ? Math.floor(maxPages) : FIND_FILES_MAX_PAGES;
+            for (let page = 0; page < pages; page += 1) {
+                const result = await findFiles(filters, { ...opts, cursor });
+                items.push(...result.items);
+                truncated = result.truncated;
+                cursor = result.cursor ?? undefined;
+                if (!cursor)
+                    break;
+            }
+            return { items, cursor: cursor ?? null, ...(truncated === undefined ? {} : { truncated }) };
         },
         /** `GET /v1/:workspace/files/facets` — workspace metadata key vocabulary. */
         async listMetadataKeys() {
@@ -534,9 +592,13 @@ export function createUploadsClient(config) {
             return { ...result, embedUrl: resolveEmbedUrl(result.url, result.embedUrl) };
         },
         async createGallery(opts) {
+            const { idempotencyKey = crypto.randomUUID(), ...body } = opts;
             return request("POST", galleriesBase(config), {
-                body: new TextEncoder().encode(JSON.stringify(opts)),
-                headers: { "Content-Type": "application/json" },
+                body: new TextEncoder().encode(JSON.stringify(body)),
+                headers: {
+                    "Content-Type": "application/json",
+                    "Idempotency-Key": idempotencyKey,
+                },
             });
         },
         async getGallery(id) {

package/dist/commands.d.ts

@@ -615,16 +615,18 @@ export interface DoctorReport {
     /** Workspace/token mismatch warning (also present in hints). */
     warning?: string;
     /**
-     * Bring-your-own-bucket storage status (issue #583 Phase 3). `GET
-     * /me/workspaces/:name/storage` is session-gated (Better Auth cookie or
-     * bearer via the AUTH service — see `session-auth.ts`); the CLI only ever
-     * holds a minted `up_<workspace>_…` workspace token, never a session
-     * bearer, so doctor cannot reach that route today. Until a token-authed
-     * read path exists, this is an honest "can't check from here" rather than
-     * a fabricated mode.
+     * Storage-lane summary (issue #775): the usage endpoint carries a
+     * bearer-safe `storage` object (mode + fallback-lane count + health), so
+     * doctor reports it from the same call it already makes. `checked` is
+     * false when usage failed or the server predates the field — then `note`
+     * falls back to the honest "can't check from here" line (the full
+     * projection on `GET /me/workspaces/:name/storage` stays session-gated).
      */
     storage: {
-        checked: false;
+        checked: boolean;
+        mode?: "shared" | "byo";
+        fallbackLanes?: number;
+        healthy?: boolean;
         note: string;
     };
     hints: string[];

package/dist/commands.js

@@ -2574,8 +2574,10 @@ Default prefix: UPLOADS_DEFAULT_PREFIX (screenshots if unset).
 
 --meta <k=v> (repeatable, ANDed) and/or --name <term> switch to the search
 endpoint — returned items include their matched metadata. Combines with
---prefix, not with --pr/--issue/--all. --name is a case-insensitive
-substring match on object keys. See also: uploads find.
+--prefix, not with --pr/--issue. --name is a case-insensitive
+substring match on object keys. Search pages are continued with --cursor
+(opaque, from the previous page); --all follows it for up to 20 pages and
+prints the next cursor if more remain. See also: uploads find.
 
 Examples:
   uploads list --prefix screenshots/
@@ -2592,18 +2594,21 @@ function writeTruncatedNotice(truncated, quiet, detail) {
 }
 /** `--meta` / `--name` search path, shared by `runList` and `runFind`. */
 async function runFindFiles(ctx, filters, flags, name) {
-    if (flagString(flags, "--cursor") !== undefined) {
-        throw new UsageError("--cursor is not supported with metadata or name filters");
-    }
     const prefix = flagString(flags, "--prefix");
     const limit = flagInt(flags, "--limit", "--limit");
+    const cursor = flagString(flags, "--cursor");
     const nameTerm = name ?? flagString(flags, "--name");
     if (Object.keys(filters).length === 0 && !nameTerm) {
         throw new UsageError("find requires at least one k=v pair, --meta k=v, or --name <term>", {
             example: "uploads find path=/settings state=after",
         });
     }
-    const result = await ctx.client.findFiles(filters, { prefix, limit, name: nameTerm });
+    // `--all` follows the search cursor, but only up to FIND_FILES_MAX_PAGES —
+    // never an unbounded drain. `--cursor` resumes a specific page by hand.
+    const searchOpts = { prefix, limit, name: nameTerm, cursor };
+    const result = flagBool(flags, "--all")
+        ? await ctx.client.findFilesAll(filters, searchOpts)
+        : await ctx.client.findFiles(filters, searchOpts);
     if (ctx.json)
         await writeJson(result);
     else {
@@ -2617,6 +2622,9 @@ async function runFindFiles(ctx, filters, flags, name) {
             await writeStdout(`${item.key}${item.url ? `  ${item.url}` : ""}${meta ? `  ${meta}` : ""}\n`);
         }
         writeTruncatedNotice(result.truncated, ctx.quiet, "more matches may exist beyond this page");
+        // Human mode surfaces the continuation the same way `uploads list` does.
+        if (result.cursor)
+            process.stderr.write(`cursor: ${result.cursor}\n`);
     }
     return 0;
 }
@@ -2632,9 +2640,6 @@ export async function runList(ctx, args, help = false, run = execRunner) {
         if (ghTargetFromFlags(parsed.flags, run)) {
             throw new UsageError("--meta/--name cannot be combined with --pr/--issue");
         }
-        if (flagBool(parsed.flags, "--all")) {
-            throw new UsageError("--meta/--name cannot be combined with --all");
-        }
         return runFindFiles(ctx, metaPairs.length > 0 ? parseMetaFlags(metaPairs) : {}, parsed.flags, nameFlag);
     }
     const defaults = resolvePutDefaults({ envFile: ctx.envFile });
@@ -2694,11 +2699,16 @@ export async function runList(ctx, args, help = false, run = execRunner) {
     return 0;
 }
 // --- find ---
-const FIND_HELP = `uploads find [k=v...] [--meta k=v]... [--name <term>] [--prefix <p>] [--limit <n>] [--workspace <name>]
+const FIND_HELP = `uploads find [k=v...] [--meta k=v]... [--name <term>] [--prefix <p>] [--limit <n>] [--cursor <c>] [--all] [--workspace <name>]
 
 Find objects by queryable metadata (ANDed equality) and/or a case-insensitive
 filename substring. Same output as \`uploads list --meta\` / \`--name\`.
 
+Results are paged. When more matches exist the next page's opaque cursor is
+printed to stderr (and carried in --json as \`cursor\`); pass it back with
+--cursor. --all follows the cursor for you, up to 20 pages, then prints the
+cursor to resume from.
+
 Pairs are positional k=v, or spelled --meta k=v. A bare positional without
 \`=\` is treated as --name (e.g. \`uploads find hero\`). At least one of a
 meta pair or a name term is required.
@@ -2709,6 +2719,7 @@ Examples:
   uploads find --meta path=/settings
   uploads find hero
   uploads find --name hero --meta app=web
+  uploads find app=web --all --json
 `;
 export async function runFind(ctx, args, help = false) {
     const parsed = parseCommandArgs(args);
@@ -3472,6 +3483,10 @@ export async function buildDoctorReport(config, client, detectRoots) {
         }
     }
     let usage;
+    let storage = {
+        checked: false,
+        note: "not checked from the CLI — this server doesn't report a storage summary on the usage endpoint; sign in on the web (Account → workspace → Settings) to view mode and verification status",
+    };
     let scopes;
     if (authOk) {
         try {
@@ -3482,6 +3497,23 @@ export async function buildDoctorReport(config, client, detectRoots) {
                 objects: snap.objects,
                 uploadsInPeriod: snap.uploadsInPeriod,
             };
+            if (snap.storage) {
+                const laneNote = snap.storage.fallbackLanes > 0
+                    ? ` (${snap.storage.fallbackLanes} previous lane${snap.storage.fallbackLanes === 1 ? "" : "s"} still serving old files)`
+                    : "";
+                const healthNote = snap.storage.health.ok
+                    ? ""
+                    : " — not working; rotate credentials on the web settings page";
+                storage = {
+                    checked: true,
+                    mode: snap.storage.mode,
+                    fallbackLanes: snap.storage.fallbackLanes,
+                    healthy: snap.storage.health.ok,
+                    note: (snap.storage.mode === "byo" ? "your bucket" : "hosted storage") +
+                        laneNote +
+                        healthNote,
+                };
+            }
             scopes = snap.scopes;
             if (scopes && !scopes.includes("files:delete")) {
                 hints.push("token lacks files:delete (`uploads delete` will be forbidden) — re-run `uploads login` for a full-scope token");
@@ -3511,10 +3543,7 @@ export async function buildDoctorReport(config, client, detectRoots) {
         usage,
         scopes,
         warning: mismatch,
-        storage: {
-            checked: false,
-            note: "not checked from the CLI — storage settings (shared vs. bring-your-own-bucket) live behind a signed-in session; sign in on the web (Account → workspace → Settings) to view mode and verification status",
-        },
+        storage,
         hints,
         browser,
     };

package/dist/format-usage.d.ts

@@ -9,6 +9,11 @@ export type UsageSnapshotLike = {
     storageRemainingBytes?: number;
     maxUploadsPerPeriod?: number;
     uploadsRemaining?: number;
+    /** Bytes still on hosted storage (shared-lane residue). */
+    sharedBytes?: number;
+    /** "shared" = BYO bucket active: the storage cap meters only hosted
+     * residue; bytes in the customer's own bucket are unmetered. */
+    storageBudgetBasis?: "total" | "shared";
     /** Catalog plan id when the API reports it (`free` | `pro`). */
     plan?: string;
 };

package/dist/format-usage.js

@@ -11,9 +11,14 @@ import { formatByteSize, formatMarketedBytes } from "./format-bytes.js";
 import { BRAND } from "./cli-brand.js";
 /** True when the API reported any cumulative workspace quota. */
 export function isUsageMetered(result) {
-    return (usagePct(result.bytes, result.maxStorageBytes) !== null ||
+    return (usagePct(storageMeteredBytes(result), result.maxStorageBytes) !== null ||
         usagePct(result.uploadsInPeriod, result.maxUploadsPerPeriod) !== null);
 }
+/** The usage number the storage cap actually meters — hosted residue only
+ * when a BYO bucket is active (`storageBudgetBasis: "shared"`). */
+function storageMeteredBytes(result) {
+    return result.storageBudgetBasis === "shared" ? (result.sharedBytes ?? 0) : result.bytes;
+}
 /** 0–100, one decimal. Missing/invalid caps → no bar. Matches web `usagePct`. */
 export function usagePct(value, max) {
     if (typeof max !== "number" || !(max > 0) || !Number.isFinite(value))
@@ -112,21 +117,26 @@ export function formatUsageHuman(result, opts = {}) {
     const label = planLabel(result.plan);
     if (label)
         lines.push(`plan:      ${label}`);
-    const storagePct = usagePct(result.bytes, result.maxStorageBytes);
+    const byoActive = result.storageBudgetBasis === "shared";
+    const meteredBytes = storageMeteredBytes(result);
+    const storagePct = usagePct(meteredBytes, result.maxStorageBytes);
     if (storagePct !== null && result.maxStorageBytes != null) {
         // Caps (and remaining-against-cap) use SI marketed formatting so Free's
         // 250_000_000 reads as "250 MB", not binary "238.4 MB". Used bytes share
         // the same base on this line so the three numbers stay coherent.
-        const detail = `${formatMarketedBytes(result.bytes)} / ${formatMarketedBytes(result.maxStorageBytes)}` +
+        const detail = `${formatMarketedBytes(meteredBytes)} / ${formatMarketedBytes(result.maxStorageBytes)}` +
             (result.storageRemainingBytes != null
                 ? ` (${formatMarketedBytes(result.storageRemainingBytes)} free)`
                 : "");
         const bar = formatProgressBar(storagePct, { width, color });
-        lines.push(`storage:   ${bar}  ${detail}`);
+        lines.push(`storage:   ${bar}  ${detail}${byoActive ? " on hosted storage" : ""}`);
     }
     else {
         lines.push(`storage:   ${formatByteSize(result.bytes)}`);
     }
+    if (byoActive) {
+        lines.push("note:      your own bucket is unmetered — the storage quota only counts files on hosted storage");
+    }
     lines.push(`objects:   ${formatCount(result.objects)}`);
     const uploadsPct = usagePct(result.uploadsInPeriod, result.maxUploadsPerPeriod);
     if (uploadsPct !== null && result.maxUploadsPerPeriod != null) {

package/dist/mcp/tools.js

@@ -1298,7 +1298,7 @@ export function createUploadsMcpTools(opts) {
             title: "Find files",
             annotations: mcpRead,
             securitySchemes: mcpOAuthRead,
-            description: "Find objects whose queryable custom metadata matches ALL of `filters` (ANDed equality) and/or whose key contains `name` (case-insensitive substring). At least one of `filters` or `name` is required. Returns each match's key, public URL, full metadata map, and optional `truncated`. Same as `uploads find k=v...` / `uploads find --name <term>`.",
+            description: "Find objects whose queryable custom metadata matches ALL of `filters` (ANDed equality) and/or whose key contains `name` (case-insensitive substring). At least one of `filters` or `name` is required. Returns each match's key, public URL, full metadata map, optional `truncated`, and a `cursor` to pass back for the next page (null when there are none; set `all` to follow it for you). Same as `uploads find k=v...` / `uploads find --name <term>`.",
             inputSchema: {
                 type: "object",
                 properties: {
@@ -1315,6 +1315,14 @@ export function createUploadsMcpTools(opts) {
                         description: "Key prefix filter, combinable with filters/name.",
                     },
                     limit: { type: "number", description: "Page size (default 50, max 500)." },
+                    cursor: {
+                        type: "string",
+                        description: "Opaque continuation from a previous call's `cursor`. Pass it back unchanged with the same filters/name to get the next page; a null `cursor` means there are no more pages.",
+                    },
+                    all: {
+                        type: "boolean",
+                        description: "Follow the cursor and return every page, up to a bounded number of requests. A non-null `cursor` in the result means that bound was reached before the end — pass it back to continue.",
+                    },
                     workspace: workspaceProp,
                 },
                 additionalProperties: false,
@@ -1329,11 +1337,17 @@ export function createUploadsMcpTools(opts) {
                 if (hasMeta)
                     validateMetaMap(filters);
                 const { client } = await clientFor(args);
-                return client.findFiles(filters, {
+                const opts = {
                     name,
                     prefix: optString(args, "prefix"),
                     limit: optPosInt(args, "limit"),
-                });
+                    cursor: optString(args, "cursor"),
+                };
+                // `all` drains through findFilesAll, which caps its own page count —
+                // unlike `list`'s `all`, this never runs unbounded.
+                return optBool(args, "all")
+                    ? client.findFilesAll(filters, opts)
+                    : client.findFiles(filters, opts);
             },
         },
         {

package/package.json

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