@vee3/upload 0.2.0 → 0.2.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vee3/upload",
-  "version": "0.2.0",
+  "version": "0.2.1",
   "description": "Upload local files to Vee3.",
   "homepage": "https://vee3.io",
   "type": "module",

package/src/api.js

@@ -1,3 +1,5 @@
+import { UploadError, describeNetworkError } from "./errors.js";
+
 export const DEFAULT_API_BASE_URL = "https://api.vee3.io";
 
 async function formatApiError(response) {
@@ -15,19 +17,26 @@ async function formatApiError(response) {
 }
 
 export async function resolveUpload({ apiBaseUrl, uploadCode, contentType }) {
-  const response = await fetch(`${apiBaseUrl.replace(/\/$/, "")}/v1/agent-uploads/resolve`, {
-    method: "POST",
-    headers: {
-      "Content-Type": "application/json"
-    },
-    body: JSON.stringify({
-      upload_code: uploadCode,
-      content_type: contentType
-    })
-  });
+  const requestUrl = `${apiBaseUrl.replace(/\/$/, "")}/v1/agent-uploads/resolve`;
+
+  let response;
+  try {
+    response = await fetch(requestUrl, {
+      method: "POST",
+      headers: {
+        "Content-Type": "application/json"
+      },
+      body: JSON.stringify({
+        upload_code: uploadCode,
+        content_type: contentType
+      })
+    });
+  } catch (error) {
+    throw new UploadError(describeNetworkError(error, `the Vee3 API at ${apiBaseUrl}`));
+  }
 
   if (!response.ok) {
-    throw new Error(await formatApiError(response));
+    throw new UploadError(await formatApiError(response));
   }
 
   return await response.json();

package/src/errors.js

@@ -0,0 +1,51 @@
+export class UsageError extends Error {
+  constructor(message) {
+    super(message);
+    this.name = "UsageError";
+  }
+}
+
+export class UploadError extends Error {
+  constructor(message) {
+    super(message);
+    this.name = "UploadError";
+  }
+}
+
+const TLS_VERIFICATION_CODES = new Set([
+  "UNABLE_TO_VERIFY_LEAF_SIGNATURE",
+  "SELF_SIGNED_CERT_IN_CHAIN",
+  "DEPTH_ZERO_SELF_SIGNED_CERT",
+  "CERT_HAS_EXPIRED",
+  "ERR_TLS_CERT_ALTNAME_INVALID"
+]);
+
+/**
+ * Turns a low-level fetch failure into a message a user can act on. Node's
+ * fetch throws a generic "fetch failed" TypeError and hides the real reason in
+ * error.cause, so we surface the underlying code here.
+ */
+export function describeNetworkError(error, targetDescription) {
+  const cause = error?.cause ?? error;
+  const code = cause?.code;
+
+  if (code === "ECONNREFUSED") {
+    return `Could not connect to ${targetDescription}. Make sure it is running and the address is correct.`;
+  }
+  if (code === "ENOTFOUND") {
+    return `Could not find ${targetDescription}. Check the address and your network connection.`;
+  }
+  if (code === "ETIMEDOUT" || code === "UND_ERR_CONNECT_TIMEOUT") {
+    return `Connection to ${targetDescription} timed out.`;
+  }
+  if (code && TLS_VERIFICATION_CODES.has(code)) {
+    return (
+      `Could not verify the TLS certificate for ${targetDescription}. ` +
+      "This usually means a proxy or antivirus is inspecting HTTPS traffic. " +
+      "Use Node 22.15 or newer, or set NODE_EXTRA_CA_CERTS to your root certificate."
+    );
+  }
+
+  const detail = cause?.message ?? error?.message ?? String(error);
+  return `Request to ${targetDescription} failed: ${detail}`;
+}

package/src/format.js

@@ -0,0 +1,17 @@
+const BYTE_UNITS = ["B", "KB", "MB", "GB", "TB"];
+
+export function formatBytes(byteCount) {
+  if (!Number.isFinite(byteCount) || byteCount <= 0) {
+    return "0 B";
+  }
+
+  let unitIndex = 0;
+  let value = byteCount;
+  while (value >= 1024 && unitIndex < BYTE_UNITS.length - 1) {
+    value /= 1024;
+    unitIndex += 1;
+  }
+
+  const decimals = unitIndex === 0 ? 0 : 1;
+  return `${value.toFixed(decimals)} ${BYTE_UNITS[unitIndex]}`;
+}

package/src/index.js

@@ -1,17 +1,18 @@
 #!/usr/bin/env node
 
 import { stat } from "node:fs/promises";
+import { basename } from "node:path";
 import { DEFAULT_API_BASE_URL, resolveUpload } from "./api.js";
 import { detectContentType } from "./detectContentType.js";
+import { UploadError, UsageError } from "./errors.js";
+import { formatBytes } from "./format.js";
 import { ensureSystemCertificateTrust } from "./systemCertificates.js";
 import { uploadFileToSignedUrl } from "./uploadFile.js";
 
 ensureSystemCertificateTrust();
 
 function printUsage() {
-  console.error(
-    "Usage: vee3-upload <upload_code> <file_path> [--api-base-url https://api.vee3.io] [--json]"
-  );
+  console.error("Usage: vee3-upload <upload_code> <file_path>");
 }
 
 function parseArguments(argumentsList) {
@@ -24,7 +25,7 @@ function parseArguments(argumentsList) {
     if (argument === "--api-base-url") {
       const nextArgument = argumentsList[index + 1];
       if (!nextArgument) {
-        throw new Error("--api-base-url requires a value");
+        throw new UsageError("--api-base-url requires a value");
       }
       apiBaseUrl = nextArgument;
       index += 1;
@@ -38,7 +39,7 @@ function parseArguments(argumentsList) {
   }
 
   if (positionalArguments.length !== 2) {
-    throw new Error("Expected upload_code and file_path");
+    throw new UsageError("Expected upload_code and file_path");
   }
 
   return {
@@ -49,16 +50,30 @@ function parseArguments(argumentsList) {
   };
 }
 
+async function readFileStat(filePath) {
+  try {
+    return await stat(filePath);
+  } catch (error) {
+    if (error?.code === "ENOENT") {
+      throw new UploadError(`File not found: ${filePath}`);
+    }
+    throw new UploadError(`Could not read file: ${filePath} (${error.message})`);
+  }
+}
+
 async function main() {
   const { uploadCode, filePath, apiBaseUrl, outputJson } = parseArguments(
     process.argv.slice(2)
   );
-  const fileStat = await stat(filePath);
+
+  const fileStat = await readFileStat(filePath);
   if (!fileStat.isFile()) {
-    throw new Error(`File path is not a file: ${filePath}`);
+    throw new UploadError(`Not a file: ${filePath}`);
   }
 
   const contentType = await detectContentType(filePath);
+
+  console.error("Resolving upload code...");
   const resolvedUpload = await resolveUpload({
     apiBaseUrl,
     uploadCode,
@@ -66,11 +81,14 @@ async function main() {
   });
 
   if (fileStat.size > resolvedUpload.max_bytes) {
-    throw new Error(
-      `File is too large: ${fileStat.size} bytes exceeds ${resolvedUpload.max_bytes} bytes`
+    throw new UploadError(
+      `File is too large: ${formatBytes(fileStat.size)} exceeds the ${formatBytes(
+        resolvedUpload.max_bytes
+      )} limit.`
     );
   }
 
+  console.error(`Uploading ${basename(filePath)} (${formatBytes(fileStat.size)})...`);
   await uploadFileToSignedUrl({
     uploadUrl: resolvedUpload.upload_url,
     filePath,
@@ -93,7 +111,11 @@ async function main() {
 }
 
 main().catch((error) => {
-  printUsage();
-  console.error(error instanceof Error ? error.message : String(error));
+  if (error instanceof UsageError) {
+    printUsage();
+    console.error(error.message);
+  } else {
+    console.error(error instanceof Error ? error.message : String(error));
+  }
   process.exit(1);
 });

package/src/progress.js

@@ -0,0 +1,59 @@
+import { formatBytes } from "./format.js";
+
+const TTY_RENDER_INTERVAL_MS = 150;
+const NON_TTY_MILESTONE_STEP = 20;
+
+/**
+ * Reports upload progress to stderr so that stdout stays clean for the
+ * upload_id. In an interactive terminal it redraws a single line; in
+ * non-interactive contexts (such as agent logs) it prints discrete milestone
+ * lines to avoid carriage-return spam.
+ */
+export function createUploadProgressReporter(totalBytes) {
+  const isInteractive = Boolean(process.stderr.isTTY);
+  let lastRenderTime = 0;
+  let lastMilestone = 0;
+
+  function computePercent(uploadedBytes) {
+    if (totalBytes <= 0) {
+      return 100;
+    }
+    return Math.min(100, Math.floor((uploadedBytes / totalBytes) * 100));
+  }
+
+  function report(uploadedBytes) {
+    const percent = computePercent(uploadedBytes);
+
+    if (isInteractive) {
+      const now = Date.now();
+      const isComplete = uploadedBytes >= totalBytes;
+      if (!isComplete && now - lastRenderTime < TTY_RENDER_INTERVAL_MS) {
+        return;
+      }
+      lastRenderTime = now;
+      process.stderr.write(
+        `\rUploading ${percent}% (${formatBytes(uploadedBytes)} / ${formatBytes(totalBytes)})`
+      );
+      return;
+    }
+
+    const milestone = Math.floor(percent / NON_TTY_MILESTONE_STEP) * NON_TTY_MILESTONE_STEP;
+    if (milestone <= lastMilestone || milestone >= 100) {
+      return;
+    }
+    lastMilestone = milestone;
+    process.stderr.write(
+      `Uploading ${milestone}% (${formatBytes(uploadedBytes)} / ${formatBytes(totalBytes)})\n`
+    );
+  }
+
+  function finish() {
+    if (isInteractive) {
+      process.stderr.write(`\rUploaded ${formatBytes(totalBytes)} (100%)\n`);
+      return;
+    }
+    process.stderr.write(`Uploaded ${formatBytes(totalBytes)} (100%)\n`);
+  }
+
+  return { report, finish };
+}

package/src/uploadFile.js

@@ -1,4 +1,7 @@
 import { createReadStream } from "node:fs";
+import { Transform } from "node:stream";
+import { UploadError, describeNetworkError } from "./errors.js";
+import { createUploadProgressReporter } from "./progress.js";
 
 export async function uploadFileToSignedUrl({
   uploadUrl,
@@ -6,20 +9,44 @@ export async function uploadFileToSignedUrl({
   fileSizeBytes,
   requiredHeaders
 }) {
+  const progressReporter = createUploadProgressReporter(fileSizeBytes);
+  let uploadedBytes = 0;
+
+  const progressStream = new Transform({
+    transform(chunk, _encoding, callback) {
+      uploadedBytes += chunk.length;
+      progressReporter.report(uploadedBytes);
+      callback(null, chunk);
+    }
+  });
+
+  const fileStream = createReadStream(filePath);
+  fileStream.on("error", (error) => {
+    progressStream.destroy(error);
+  });
+  fileStream.pipe(progressStream);
+
   const headers = {
     ...requiredHeaders,
     "Content-Length": String(fileSizeBytes)
   };
 
-  const response = await fetch(uploadUrl, {
-    method: "PUT",
-    headers,
-    body: createReadStream(filePath),
-    duplex: "half"
-  });
+  let response;
+  try {
+    response = await fetch(uploadUrl, {
+      method: "PUT",
+      headers,
+      body: progressStream,
+      duplex: "half"
+    });
+  } catch (error) {
+    throw new UploadError(describeNetworkError(error, "Vee3 storage"));
+  }
 
   if (!response.ok) {
-    const responseText = await response.text();
-    throw new Error(responseText || `Upload failed with HTTP ${response.status}`);
+    const responseText = (await response.text()).trim();
+    throw new UploadError(responseText || `Upload failed with HTTP ${response.status}`);
   }
+
+  progressReporter.finish();
 }