@groundfloorcloud/cli 0.2.1 → 0.2.2

package/dist/index.js

@@ -535,12 +535,14 @@ async function logoutCommand() {
 
 // src/cp.ts
 var CpError = class extends Error {
-  constructor(status, message) {
+  constructor(status, message, reason = null) {
     super(message);
     this.status = status;
+    this.reason = reason;
     this.name = "CpError";
   }
   status;
+  reason;
 };
 function formatCpErrorDetail(detail, fallback) {
   if (typeof detail === "string" && detail.trim()) return detail.trim();
@@ -560,6 +562,40 @@ function formatCpErrorDetail(detail, fallback) {
   }
   return fallback;
 }
+function parseRetryAfter(value, now = Date.now()) {
+  if (!value) return null;
+  const trimmed = value.trim();
+  if (/^\d+$/.test(trimmed)) return Number(trimmed);
+  const at = Date.parse(trimmed);
+  if (Number.isNaN(at)) return null;
+  return Math.max(0, Math.ceil((at - now) / 1e3));
+}
+function formatWait(seconds) {
+  if (seconds < 60) return `${seconds} second${seconds === 1 ? "" : "s"}`;
+  const minutes = Math.ceil(seconds / 60);
+  if (minutes < 60) return `${minutes} minute${minutes === 1 ? "" : "s"}`;
+  const hours = Math.ceil(minutes / 60);
+  return `${hours} hour${hours === 1 ? "" : "s"}`;
+}
+var REASON_HEADER = "x-groundfloor-reason";
+function formatCpErrorMessage(status, detail, retryAfterSeconds, reason = null) {
+  let message = `${status} ${detail}`;
+  const wait = retryAfterSeconds !== null ? `try again in ${formatWait(retryAfterSeconds)}` : "try again later";
+  if (status === 429 && reason === "sending_limited") {
+    message += ` (workspace sign-in email limit reached: ${wait}, or give access with a copy-link or temporary password instead)`;
+  } else if (status === 429) {
+    message += ` (rate limited: ${wait})`;
+  } else if (status === 423 && reason === "sending_paused") {
+    message += " (sign-in email is paused: only Groundfloor support can resume it; meanwhile give access with a copy-link or temporary password, or switch to your own email server)";
+  } else if (status === 423 && !/support/i.test(detail)) {
+    message += " (locked: Groundfloor has paused or frozen this; contact Groundfloor support)";
+  }
+  return message;
+}
+function reasonHeader(res) {
+  const value = res.headers?.get?.(REASON_HEADER);
+  return value ? value.trim() : null;
+}
 async function parseError(res) {
   let detail = res.statusText;
   try {
@@ -569,7 +605,12 @@ async function parseError(res) {
     }
   } catch {
   }
-  return `${res.status} ${detail}`;
+  return formatCpErrorMessage(
+    res.status,
+    detail,
+    parseRetryAfter(res.headers?.get?.("retry-after")),
+    reasonHeader(res)
+  );
 }
 async function cpGet(apiUrl, path11) {
   const token = await getValidAccessToken();
@@ -580,7 +621,7 @@ async function cpGet(apiUrl, path11) {
     }
   });
   if (!res.ok) {
-    throw new CpError(res.status, await parseError(res));
+    throw new CpError(res.status, await parseError(res), reasonHeader(res));
   }
   return await res.json();
 }
@@ -596,7 +637,7 @@ async function cpPostJson(apiUrl, path11, body) {
     body: JSON.stringify(body)
   });
   if (!res.ok) {
-    throw new CpError(res.status, await parseError(res));
+    throw new CpError(res.status, await parseError(res), reasonHeader(res));
   }
   return await res.json();
 }
@@ -607,7 +648,7 @@ async function cpDelete(apiUrl, path11) {
     headers: { Authorization: `Bearer ${token}`, Accept: "application/json" }
   });
   if (!res.ok) {
-    throw new CpError(res.status, await parseError(res));
+    throw new CpError(res.status, await parseError(res), reasonHeader(res));
   }
 }
 async function cpPutJson(apiUrl, path11, body) {
@@ -622,7 +663,7 @@ async function cpPutJson(apiUrl, path11, body) {
     body: JSON.stringify(body)
   });
   if (!res.ok) {
-    throw new CpError(res.status, await parseError(res));
+    throw new CpError(res.status, await parseError(res), reasonHeader(res));
   }
   return await res.json();
 }
@@ -638,7 +679,7 @@ async function cpPatchJson(apiUrl, path11, body) {
     body: JSON.stringify(body)
   });
   if (!res.ok) {
-    throw new CpError(res.status, await parseError(res));
+    throw new CpError(res.status, await parseError(res), reasonHeader(res));
   }
   return await res.json();
 }
@@ -654,7 +695,7 @@ async function cpPutBytes(apiUrl, path11, body, contentType) {
     body
   });
   if (!res.ok) {
-    throw new CpError(res.status, await parseError(res));
+    throw new CpError(res.status, await parseError(res), reasonHeader(res));
   }
 }
 function queryString(params) {
@@ -710,7 +751,7 @@ async function uploadZip(apiUrl, workspaceId, coderunnerId, zip, description) {
     }
   );
   if (!res.ok) {
-    throw new CpError(res.status, await parseError(res));
+    throw new CpError(res.status, await parseError(res), reasonHeader(res));
   }
   return await res.json();
 }
@@ -748,7 +789,7 @@ async function getDeployment(apiUrl, workspaceId, coderunnerId) {
   );
   if (res.status === 204) return null;
   if (!res.ok) {
-    throw new CpError(res.status, await parseError(res));
+    throw new CpError(res.status, await parseError(res), reasonHeader(res));
   }
   return await res.json();
 }
@@ -768,7 +809,7 @@ async function getDeploymentById(apiUrl, workspaceId, coderunnerId, deploymentId
     }
   );
   if (!res.ok) {
-    throw new CpError(res.status, await parseError(res));
+    throw new CpError(res.status, await parseError(res), reasonHeader(res));
   }
   return await res.json();
 }
@@ -1034,7 +1075,7 @@ async function mintM2mToken(apiUrl, workspaceId, clientId, clientSecret) {
     }
   );
   if (!res.ok) {
-    throw new CpError(res.status, await parseError(res));
+    throw new CpError(res.status, await parseError(res), reasonHeader(res));
   }
   return await res.json();
 }
@@ -1075,7 +1116,7 @@ async function controlPlaneRequest(apiUrl, method, path11, body) {
   });
   if (res.status === 204) return void 0;
   if (!res.ok) {
-    throw new CpError(res.status, await parseError(res));
+    throw new CpError(res.status, await parseError(res), reasonHeader(res));
   }
   const text = await res.text();
   if (!text) return void 0;
@@ -3807,6 +3848,33 @@ function commanderExitCode(err) {
   return 0;
 }
 
+// src/email-delivery.ts
+var REASONS = {
+  smtp_not_configured: "no email server is set up for this workspace's sign-in email",
+  send_failed: "the email server refused or failed to send it",
+  delivery_unconfirmed: "the email server timed out; the email may still arrive",
+  not_requested: "sending was turned off for this request (send_email: false)",
+  sending_limited: "the workspace or this recipient reached the sign-in email limit (200 per hour and 1,000 per day per workspace; 5 per hour and 10 per day per recipient); try again later, or share a copy-link or temporary password instead",
+  sending_paused: "Groundfloor paused this workspace's sign-in email after too many bounces or spam reports; contact Groundfloor support, or share a copy-link or temporary password instead",
+  recipient_suppressed: "this address bounced or reported spam, so Groundfloor will not email it; check the address, or clear it from the workspace suppression list (GET/DELETE /v1/workspaces/{workspace_id}/mail/suppressions; for a spam report only Groundfloor support can also clear it at the mail provider)"
+};
+function describeEmailSkippedReason(reason) {
+  return REASONS[reason] ?? reason;
+}
+function emailDeliveryNote(data) {
+  if (!data || typeof data !== "object" || Array.isArray(data)) return null;
+  const obj = data;
+  if (!("email_sent" in obj) || obj.email_sent === true) return null;
+  const reason = typeof obj.email_skipped_reason === "string" && obj.email_skipped_reason ? obj.email_skipped_reason : null;
+  if (obj.email_sent === false) {
+    return reason ? `Note: the email was not sent (${reason}): ${describeEmailSkippedReason(reason)}.` : "Note: the email was not sent.";
+  }
+  if (obj.email_sent === null || obj.email_sent === void 0) {
+    return reason ? `Note: email delivery is unknown (${reason}): ${describeEmailSkippedReason(reason)}.` : null;
+  }
+  return null;
+}
+
 // src/commands/api.ts
 var METHODS = /* @__PURE__ */ new Set(["GET", "POST", "PUT", "PATCH", "DELETE"]);
 async function apiCommand(opts) {
@@ -3829,6 +3897,9 @@ async function apiCommand(opts) {
     return;
   }
   process.stdout.write(`${JSON.stringify(data, null, 2)}
+`);
+  const note = emailDeliveryNote(data);
+  if (note) process.stderr.write(`${note}
 `);
 }
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@groundfloorcloud/cli",
-  "version": "0.2.1",
+  "version": "0.2.2",
   "description": "Groundfloor gf CLI — sign in, deploy coderunners, publish Shell apps, and manage secrets, files, and Dataplane.",
   "type": "module",
   "bin": {