@buildinternet/uploads 0.17.0 → 0.19.0

package/dist/cli.js

@@ -105,6 +105,7 @@ const ERROR_HINTS = {
     UPLOAD_BUDGET: QUOTA_HINT,
     KEY_POLICY: "hint: use a typed destination (`--destination screenshots|gh`) or an allowed prefix; operators set allowlists with `pnpm workspace:limits --allowed-prefixes`\n",
     UNAUTHORIZED: "hint: token rejected — run `uploads login` to sign in again, or check UPLOADS_TOKEN / --token\n",
+    INSUFFICIENT_SCOPE: "hint: re-run `uploads login` for a full-scope token (or mint one with --scopes)\n",
     BROWSER_NOT_FOUND: "hint: no local browser found; try --via remote, or install Chrome / npx playwright install chromium\n",
     RATE_LIMITED: "hint: transient rate limit — wait ~60s and retry\n",
 };

package/dist/client.d.ts

@@ -256,6 +256,8 @@ export interface UsageResult {
     storageRemainingBytes?: number;
     maxUploadsPerPeriod?: number;
     uploadsRemaining?: number;
+    /** File scopes of the presented token (servers ≥ this field's release). */
+    scopes?: Array<TokenScope>;
 }
 export interface ReconcileResult {
     workspace: string;
@@ -427,11 +429,13 @@ export declare function mintWorkspaceToken(apiUrl: string, accessToken: string,
 export declare function extractErrorFields(body: unknown, fallback?: string): {
     message: string;
     code?: string;
+    requiredScope?: string;
 };
 /** Fetch + parse an error-response body via {@link extractErrorFields}. */
 export declare function parseErrorEnvelope(res: Response, fallback?: string): Promise<{
     message: string;
     code?: string;
+    requiredScope?: string;
 }>;
 export declare function createUploadsClient(config: UploadsClientConfig): {
     put(body: Uint8Array, opts: PutOptions & {

package/dist/client.js

@@ -188,11 +188,17 @@ function usageBase(config) {
 function galleriesBase(config) {
     return `${config.apiUrl}/v1/${encodeURIComponent(config.workspace)}/galleries`;
 }
-function mapApiError(status, error, code) {
+function mapApiError(status, error, code, requiredScope) {
     const normalized = error.toLowerCase();
     if (status === 401 || code === "unauthorized" || normalized === "unauthorized") {
         return new UploadsError(error, "UNAUTHORIZED", status);
     }
+    if (code === "insufficient_scope") {
+        // The server's message is a bare "forbidden" — name the missing scope so
+        // the failure is actionable without a doctor run.
+        const message = requiredScope ? `token lacks the ${requiredScope} scope` : error;
+        return new UploadsError(message, "INSUFFICIENT_SCOPE", status);
+    }
     if (status === 404 || code === "not_found" || normalized === "not found") {
         return new UploadsError(error, "NOT_FOUND", status);
     }
@@ -226,9 +232,13 @@ export function extractErrorFields(body, fallback = "request failed") {
         const err = body.error;
         if (typeof err === "object" && err && "message" in err) {
             const nested = err;
+            const details = nested.details;
             return {
                 message: typeof nested.message === "string" ? nested.message : fallback,
                 code: typeof nested.code === "string" ? nested.code : undefined,
+                ...(typeof details?.required_scope === "string"
+                    ? { requiredScope: details.required_scope }
+                    : {}),
             };
         }
         if (typeof err === "string") {
@@ -246,8 +256,8 @@ export async function parseErrorEnvelope(res, fallback = "request failed") {
     return extractErrorFields(body, fallback);
 }
 async function parseErrorResponse(res) {
-    const { message, code } = await parseErrorEnvelope(res, res.statusText || "request failed");
-    return mapApiError(res.status, message, code);
+    const { message, code, requiredScope } = await parseErrorEnvelope(res, res.statusText || "request failed");
+    return mapApiError(res.status, message, code, requiredScope);
 }
 export function createUploadsClient(config) {
     async function request(method, path, opts) {

package/dist/commands/login.js

@@ -19,7 +19,8 @@ Options:
   --create            With --workspace: create the workspace first if your
                       account doesn't have it yet (device flow only) — lets
                       scripted/agent logins provision without a prompt
-  --scopes <list>     Comma-separated scopes (default: files:read,files:write)
+  --scopes <list>     Comma-separated scopes (default:
+                      files:read,files:write,files:delete)
   --label <text>      Token label (default: this machine's hostname)
   --auth-url <url>    Auth base (default: https://auth.uploads.sh)
   --no-open           Don't try to open a browser automatically
@@ -201,7 +202,16 @@ export async function obtainDeviceAccessToken(authUrl, opts = {}, io = defaultDe
  * it in a browser, poll for the session token, then mint a workspace token.
  */
 async function runDeviceLogin(parsed, opts, io) {
-    const scopes = parseScopes(flagString(parsed.flags, "--scopes"));
+    // Interactive login is the user's own credential: default to the full file
+    // scope set (including delete) so the CLI's own `delete` command works out
+    // of the box. Automation tokens minted elsewhere keep the server's
+    // conservative read+write default — narrowness there is a deliberate
+    // choice, not a surprise. `--scopes` still overrides.
+    const scopes = parseScopes(flagString(parsed.flags, "--scopes")) ?? [
+        "files:read",
+        "files:write",
+        "files:delete",
+    ];
     const label = flagString(parsed.flags, "--label") ?? safeHostname();
     const requestedWorkspace = flagString(parsed.flags, "--workspace");
     // Make the target explicit: a bare `uploads login` on a self-hosted install

package/dist/commands.d.ts

@@ -284,6 +284,8 @@ export interface DoctorReport {
         uploadsInPeriod?: number;
         error?: string;
     };
+    /** File scopes of the presented token (absent against pre-scopes servers). */
+    scopes?: string[];
     /** Workspace/token mismatch warning (also present in hints). */
     warning?: string;
     hints: string[];

package/dist/commands.js

@@ -2052,6 +2052,7 @@ export async function buildDoctorReport(config, client, detectRoots) {
         }
     }
     let usage;
+    let scopes;
     if (authOk) {
         try {
             const snap = await client.usage();
@@ -2061,6 +2062,10 @@ export async function buildDoctorReport(config, client, detectRoots) {
                 objects: snap.objects,
                 uploadsInPeriod: snap.uploadsInPeriod,
             };
+            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");
+            }
         }
         catch (err) {
             usage = {
@@ -2084,6 +2089,7 @@ export async function buildDoctorReport(config, client, detectRoots) {
         health,
         auth: { ok: authOk, error: authError },
         usage,
+        scopes,
         warning: mismatch,
         hints,
         browser,
@@ -2106,6 +2112,8 @@ export async function runDoctor(ctx, args, help = false) {
         `workspace: ${report.workspace}`,
         `auth:      ${report.auth.ok ? "ok" : `failed — ${report.auth.error ?? "no token"}`}`,
     ];
+    if (report.scopes)
+        lines.push(`scopes:    ${report.scopes.join(", ")}`);
     if (report.usage) {
         lines.push(report.usage.ok
             ? `usage:     ${formatByteSize(report.usage.bytes ?? 0)}, ${formatCount(report.usage.objects ?? 0)} objects, ${formatCount(report.usage.uploadsInPeriod ?? 0)} uploads this period`

package/dist/errors.d.ts

@@ -1,4 +1,4 @@
-export type UploadsErrorCode = "MISSING_TOKEN" | "NO_PUBLIC_URL" | "FILE_NOT_FOUND" | "NOT_FOUND" | "UNAUTHORIZED" | "INVALID_KEY" | "KEY_POLICY" | "STORAGE_QUOTA" | "UPLOAD_BUDGET" | "GITHUB_REQUIRED" | "API_ERROR" | "NETWORK" | "USAGE" | "BROWSER_NOT_FOUND" | "RENDER_FAILED" | "RATE_LIMITED";
+export type UploadsErrorCode = "MISSING_TOKEN" | "NO_PUBLIC_URL" | "FILE_NOT_FOUND" | "NOT_FOUND" | "UNAUTHORIZED" | "INSUFFICIENT_SCOPE" | "INVALID_KEY" | "KEY_POLICY" | "STORAGE_QUOTA" | "UPLOAD_BUDGET" | "GITHUB_REQUIRED" | "API_ERROR" | "NETWORK" | "USAGE" | "BROWSER_NOT_FOUND" | "RENDER_FAILED" | "RATE_LIMITED";
 export declare class UploadsError extends Error {
     readonly code: UploadsErrorCode;
     readonly status?: number;

package/dist/github.js

@@ -99,6 +99,11 @@ export function ghMetadataForBranch(repo, branch, now = new Date()) {
         "gh.kind": "branch",
         "gh.branch": branchLower,
         "gh.staged-at": now.toISOString().replace(/\.\d{3}Z$/, "Z"),
+        // Lifecycle tag (issue #339): flipped to "promoted" by server-side
+        // promotion, so "in-flight staged media" is a plain equality query
+        // (`meta.gh.status=staged`) — the metadata filter API can't express
+        // "gh.promoted-at absent".
+        "gh.status": "staged",
     };
 }
 /**

package/package.json

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