@buildinternet/uploads 0.4.0 → 0.5.0

package/README.md

@@ -4,11 +4,11 @@ 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

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.js

@@ -45,7 +45,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)

package/dist/client.d.ts

@@ -101,14 +101,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">;

package/dist/client.js

@@ -38,19 +38,19 @@ function usageBase(config) {
 }
 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 +59,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) {

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;

package/dist/commands/admin-enrollment.js

@@ -1,8 +1,12 @@
 import { createEnrollment } from "../client.js";
-import { flagInt, flagString, parseCommandArgs, UsageError } from "../cli-args.js";
-const HELP = `uploads admin enrollment create [options]
+import { flagBool, flagInt, flagString, parseCommandArgs, UsageError } from "../cli-args.js";
+const HELP = `uploads admin invite create [options]
 
-Admin-only: create a short-lived, one-time enrollment code.
+Admin-only: create a short-lived invitation for an existing workspace.
+Prints one magic link whose URL fragment carries the single-use code — treat the
+link like a password. Pass --separate-code for the legacy two-channel output (a
+non-secret page URL plus a code you share separately). The legacy
+"admin enrollment create" spelling is accepted.
 
 Options:
   --admin-token <token>  Or ADMIN_TOKEN (UPLOADS_ADMIN_TOKEN is a legacy alias)
@@ -11,9 +15,34 @@ Options:
   --expires-in <seconds> Default: server policy
   --token-expires-in <seconds>  Upload token lifetime (default: server policy)
   --scopes <list>        Comma-separated files:read,files:write,files:delete
+  --email <address>      Email the invite link to this recipient (from invites@uploads.sh)
+  --separate-code        Two-channel output: non-secret page URL + separate code
   --api-url <url>        Default: https://api.uploads.sh
+  --web-url <url>        Invite-page origin (defaults from --api-url)
 `;
 const FILE_SCOPES = new Set(["files:read", "files:write", "files:delete"]);
+export function invitePageUrl(apiUrl, pageId, webUrl) {
+    let url;
+    try {
+        url = new URL(webUrl ?? apiUrl);
+    }
+    catch {
+        throw new UsageError("invalid invite web URL");
+    }
+    if (!webUrl && url.hostname.startsWith("api."))
+        url.hostname = url.hostname.slice(4);
+    url.pathname = "/invite";
+    url.search = "";
+    url.hash = "";
+    url.searchParams.set("id", pageId);
+    return url.toString();
+}
+// Compose the self-contained magic link. The one-time code rides in the URL
+// fragment (#code=…), which browsers never send to the server, so opening the
+// page neither leaks nor consumes it — only the CLI's exchange call redeems it.
+export function inviteMagicLink(pageUrl, code) {
+    return `${pageUrl}#code=${encodeURIComponent(code)}`;
+}
 export function parseScopes(raw) {
     if (raw === undefined)
         return undefined;
@@ -34,26 +63,44 @@ export async function runAdmin(args, opts, help = false) {
         process.stderr.write(HELP);
         return 0;
     }
-    if (parsed.positionals[0] !== "enrollment" || parsed.positionals[1] !== "create")
-        throw new UsageError("expected: uploads admin enrollment create");
+    if (!["invite", "enrollment"].includes(parsed.positionals[0] ?? "") ||
+        parsed.positionals[1] !== "create")
+        throw new UsageError("expected: uploads admin invite create");
     const adminToken = flagString(parsed.flags, "--admin-token") ??
         process.env.ADMIN_TOKEN ??
         process.env.UPLOADS_ADMIN_TOKEN;
     if (!adminToken)
         throw new UsageError("ADMIN_TOKEN is required for admin enrollment creation");
     const apiUrl = flagString(parsed.flags, "--api-url") ?? opts.apiUrl ?? "https://api.uploads.sh";
+    const webUrl = flagString(parsed.flags, "--web-url");
     const workspace = flagString(parsed.flags, "--workspace") ?? "default";
     const label = flagString(parsed.flags, "--label");
+    const email = flagString(parsed.flags, "--email");
     const result = await createEnrollment(apiUrl, adminToken, {
         workspace,
         label,
+        email,
         enrollmentSeconds: flagInt(parsed.flags, "--expires-in", "--expires-in"),
         tokenExpiresInSeconds: flagInt(parsed.flags, "--token-expires-in", "--token-expires-in"),
         scopes: parseScopes(flagString(parsed.flags, "--scopes")),
     });
-    if (opts.json)
-        process.stdout.write(JSON.stringify({ workspace, label: label ?? null, ...result }, null, 2) + "\n");
+    const separateCode = flagBool(parsed.flags, "--separate-code");
+    const pageUrl = invitePageUrl(apiUrl, result.pageId, webUrl);
+    const link = separateCode ? pageUrl : inviteMagicLink(pageUrl, result.code);
+    const footer = `workspace: ${workspace}\nexpires: ${result.expiresAt}\n`;
+    if (opts.json) {
+        process.stdout.write(JSON.stringify({ workspace, label: label ?? null, url: link, ...result }, null, 2) + "\n");
+        return 0;
+    }
+    if (email && result.emailed) {
+        process.stdout.write(`Invite emailed to ${email}\n${footer}`);
+        return 0;
+    }
+    if (email && result.emailed === false)
+        process.stderr.write("warning: email delivery failed; share this link instead\n");
+    if (separateCode)
+        process.stdout.write(`Invite page: ${pageUrl}\nOne-time code (share separately): ${result.code}\n${footer}`);
     else
-        process.stdout.write(`Enrollment code (share once): ${result.code}\nworkspace: ${workspace}\nexpires: ${result.expiresAt}\n`);
+        process.stdout.write(`Invite link (contains the one-time code — treat like a password):\n${link}\n${footer}`);
     return 0;
 }

package/dist/commands.js

@@ -25,6 +25,10 @@ upload as-is, or --keep-exif when image metadata matters for the discussion.
 Optional --frame wraps the image in a device/browser chrome before optimize
 (default off). See: uploads put --help frames
 
+Uploads are public. --pr/--issue keys include the repo, number, and filename and
+remain public even for private/internal GitHub repositories. Upload only media
+that is safe at a predictable public URL.
+
 Options:
   --key <key>           Object key (default: <prefix>/<repo>/<ref>/<name>-<hash>.<ext>)
   --destination <id>    Typed root: screenshots | gh | f (sets --prefix)
@@ -166,6 +170,10 @@ const ATTACH_HELP = `uploads attach <file...> [options]
 Upload one or more stable PR/issue attachments and maintain a single GitHub
 comment. With no target, uses the pull request for the current branch.
 
+Attachments are public and their repo/number/filename keys are predictable.
+Private/internal GitHub repository visibility does not restrict access; upload
+only media that is safe at a public URL.
+
 Still images are optimized to WebP by default (same as put). Use --no-optimize
 to upload originals. Optional --frame wraps images in device/browser chrome.
 

package/dist/mcp/tools.js

@@ -138,7 +138,7 @@ export function createUploadsMcpTools(opts) {
     return [
         {
             name: "put",
-            description: "Upload a file to uploads.sh and get a public URL plus GitHub-ready embed markdown (the returned `markdown` is ready to paste into a PR or issue). Pass `file` (a local path) or `contentBase64` + `filename` for in-memory content; with `pr`/`issue` the key is stable (same filename → same URL) and `comment` syncs the managed attachments comment.",
+            description: "Upload a file to uploads.sh and get a public URL plus GitHub-ready embed markdown (the returned `markdown` is ready to paste into a PR or issue). Pass `file` (a local path) or `contentBase64` + `filename` for in-memory content; with `pr`/`issue` the key is stable (same filename → same URL) and `comment` syncs the managed attachments comment. All uploads are public; pr/issue keys are predictable and remain public for private/internal GitHub repositories, so upload only non-sensitive media.",
             inputSchema: {
                 type: "object",
                 properties: {
@@ -302,7 +302,7 @@ export function createUploadsMcpTools(opts) {
         },
         {
             name: "attach",
-            description: "Upload one or more files as stable PR/issue attachments and maintain a single managed GitHub comment listing them (each upload's `markdown` is ready to paste into GitHub). With no pr/issue, targets the pull request for the current branch.",
+            description: "Upload one or more files as stable PR/issue attachments and maintain a single managed GitHub comment listing them (each upload's `markdown` is ready to paste into GitHub). With no pr/issue, targets the pull request for the current branch. Attachments are public and their repo/number/filename keys are predictable even for private/internal GitHub repositories; upload only non-sensitive media.",
             inputSchema: {
                 type: "object",
                 properties: {

package/package.json

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