@tailglow/cli 0.5.1 → 0.6.0

package/src/output.js

@@ -1,3 +1,6 @@
+import { log } from "@clack/prompts";
+import { LOGIN_CONFIGS } from "./config.js";
+
 /**
  * Whether to emit machine-readable output.
  *
@@ -147,3 +150,28 @@ export function renderPagedResult(
 
   return `${table}\n\nStopped at the result cap. Continue with:\n  ${sanitizeText(resume_command)}`;
 }
+
+/**
+ * Writes human status messages with the same guide as prompts. Machine output stays byte-for-byte
+ * intact, and failures stay on stderr even when only that stream is redirected.
+ *
+ * @param {{ output: string; code: number }} result
+ * @param {{ json: boolean; message?: boolean }} view
+ * @param {{ stdout?: NodeJS.WriteStream; stderr?: NodeJS.WriteStream }} [streams]
+ */
+export function writeCommandResult(
+  { output, code },
+  { json, message = false },
+  { stdout = process.stdout, stderr = process.stderr } = {}
+) {
+  if (!output) return;
+  const stream = code === 0 ? stdout : stderr;
+  if (!json && stream.isTTY && (code !== 0 || message)) {
+    const text = output.split("\n").map(sanitizeText).join("\n");
+    const write =
+      code === LOGIN_CONFIGS.EXIT_PENDING ? log.warn : code === 0 ? log.success : log.error;
+    write(text, { output: stream });
+    return;
+  }
+  stream.write(`${output}\n`);
+}

package/src/request.js

@@ -1,6 +1,86 @@
-import { CLI_CONFIGS, resolveApiKey, resolveApiUrl } from "./config.js";
+import {
+  CLI_CONFIGS,
+  readCliVersion,
+  resolveApiUrl,
+  resolveCredential,
+  resolveSetting
+} from "./config.js";
 import { sanitizeText } from "./output.js";
 
+/**
+ * What to do next when the API refuses a `tglow login` credential, by error code. An API key's
+ * refusals already say what they mean; a CLI session's need the step that fixes them.
+ *
+ * @type {Record<string, string>}
+ */
+const LOGIN_REFUSAL_ADVICE = {
+  auth_invalid_credentials:
+    "The API did not accept the stored sign-in. If it keeps happening, run `tglow login` again.",
+  auth_mfa_required:
+    "This needs a sign-in verified with MFA. Run `tglow login` and approve it from a browser session that has completed MFA.",
+  auth_account_disabled: "The account or team is disabled. Check it in the Tailglow app.",
+  auth_missing_permissions:
+    "Your role does not allow this, or it can only be done in the Tailglow app."
+};
+
+/**
+ * Headers every request carries. The team header picks which of a person's teams a CLI session acts
+ * on; an API key belongs to one team and ignores it.
+ *
+ * @param {{ secret: string | null; team_id: string | null }} options
+ */
+export async function buildRequestHeaders({ secret, team_id }) {
+  /** @type {Record<string, string>} */
+  const headers = {
+    "Content-Type": "application/json",
+    "x-tailglow-client": "cli",
+    "x-tailglow-client-version": await readCliVersion()
+  };
+  if (secret) headers.Authorization = `Bearer ${secret}`;
+  if (team_id) headers["x-tailglow-team-id"] = team_id;
+  return headers;
+}
+
+/**
+ * One request and its parsed envelope, without deciding what a status means. `tglow login` uses it
+ * where a refusal is an answer rather than a failure.
+ *
+ * @param {{
+ *   method: string;
+ *   url: URL;
+ *   headers: Record<string, string>;
+ *   body?: Record<string, unknown>;
+ *   fetch_impl?: typeof fetch;
+ *   timeout_ms?: number;
+ * }} options
+ * @returns {Promise<{
+ *   status: number;
+ *   ok: boolean;
+ *   payload: import("./types.d.ts").ApiResponse | null;
+ * }>}
+ */
+export async function sendRequest({ method, url, headers, body, fetch_impl = fetch, timeout_ms }) {
+  const response = await fetch_impl(url, {
+    method,
+    headers,
+    body: method === "GET" || body === undefined ? undefined : JSON.stringify(body),
+    signal: timeout_ms ? AbortSignal.timeout(timeout_ms) : undefined
+  });
+
+  const text = await response.text();
+
+  /** @type {import("./types.d.ts").ApiResponse | null} */
+  let payload = null;
+  if (text.trim() !== "") {
+    try {
+      payload = readEnvelope(text);
+    } catch {
+      payload = null;
+    }
+  }
+  return { status: response.status, ok: response.ok, payload };
+}
+
 /**
  * Renders a field-level validation failure as lines instead of a wall of escaped JSON.
  *
@@ -47,9 +127,16 @@ export function formatValidationIssues(message) {
  * most on nested paths where either the parent or the child could be the miss. The address answers
  * that without the CLI having to know anything about id formats.
  *
- * @param {{ status: number; message: unknown; method: string; url: URL }} failure
+ * @param {{
+ *   status: number;
+ *   message: unknown;
+ *   method: string;
+ *   url: URL;
+ *   code?: string | null;
+ *   is_login?: boolean;
+ * }} failure
  */
-function describeFailure({ status, message, method, url }) {
+function describeFailure({ status, message, method, url, code = null, is_login = false }) {
   // Parsed BEFORE sanitizing: escaping the newlines the API embedded would stop it parsing at all,
   // which is how the first attempt at this silently fell through to the raw dump.
   const issues = formatValidationIssues(String(message));
@@ -60,6 +147,9 @@ function describeFailure({ status, message, method, url }) {
     return `${status} ${text}\nNothing answers ${method} ${sanitizeText(url.pathname)}.`;
   }
 
+  const advice = is_login && code ? LOGIN_REFUSAL_ADVICE[code] : null;
+  if (advice && (status === 401 || status === 403)) return `${status} ${text}\n${advice}`;
+
   return `${status} ${text}`;
 }
 
@@ -87,23 +177,34 @@ function readEnvelope(text) {
  *   query?: Record<string, unknown>;
  *   body?: Record<string, unknown>;
  *   flags?: Record<string, unknown>;
- *   config?: Record<string, string>;
+ *   config?: import("./types.d.ts").CliConfig;
+ *   path_team_id?: string | null;
  * }} options
+ *   `path_team_id` is the team a command names in its path; it acts in that team.
  * @returns {Promise<import("./types.d.ts").ApiResponse | null>}
  */
-export async function requestApi({ method, path, query = {}, body = {}, flags = {}, config = {} }) {
+export async function requestApi({
+  method,
+  path,
+  query = {},
+  body = {},
+  flags = {},
+  config = {},
+  path_team_id = null
+}) {
   const url = new URL(path, resolveApiUrl({ flags, config }));
   for (const [key, value] of Object.entries(query)) {
     if (value === undefined || value === null) continue;
     url.searchParams.set(key, typeof value === "object" ? JSON.stringify(value) : String(value));
   }
 
+  const credential = resolveCredential({ flags, config });
+  const team_id =
+    path_team_id ?? resolveSetting("team", { flags, config }) ?? credential.login?.team_id ?? null;
+
   const response = await fetch(url, {
     method,
-    headers: {
-      Authorization: `Bearer ${resolveApiKey({ flags, config })}`,
-      "Content-Type": "application/json"
-    },
+    headers: await buildRequestHeaders({ secret: credential.secret, team_id }),
     body: method === "GET" ? undefined : JSON.stringify(body)
   });
 
@@ -122,7 +223,16 @@ export async function requestApi({ method, path, query = {}, body = {}, flags =
 
   if (!response.ok) {
     const message = payload?.error?.message || payload?.message || response.statusText;
-    throw new Error(describeFailure({ status: response.status, message, method, url }));
+    throw new Error(
+      describeFailure({
+        status: response.status,
+        message,
+        method,
+        url,
+        code: payload?.error?.code ?? null,
+        is_login: credential.source === "login"
+      })
+    );
   }
 
   // A 2xx body that is not JSON means something between here and the API answered instead: a proxy
@@ -156,7 +266,8 @@ export async function requestApi({ method, path, query = {}, body = {}, flags =
  *   path: string;
  *   query?: Record<string, unknown>;
  *   flags?: Record<string, unknown>;
- *   config?: Record<string, string>;
+ *   config?: import("./types.d.ts").CliConfig;
+ *   path_team_id?: string | null;
  *   max?: number;
  * }} options
  * @returns {Promise<{ data: unknown[]; truncated: boolean; next_cursor: string | null }>}
@@ -167,6 +278,7 @@ export async function requestAllPages({
   query = {},
   flags = {},
   config = {},
+  path_team_id = null,
   max = CLI_CONFIGS.DEFAULT_MAX_RECORDS
 }) {
   /** @type {unknown[]} */
@@ -186,7 +298,8 @@ export async function requestAllPages({
         ...(cursor ? { after: cursor } : {})
       },
       flags,
-      config
+      config,
+      path_team_id
     });
 
     const page = Array.isArray(payload?.data) ? payload.data : [];

package/src/types.d.ts

@@ -16,7 +16,45 @@ export interface ApiResponse {
   data?: unknown;
   message?: string;
   pagination?: { next_cursor?: string | null } | null;
-  error?: { message?: string } | null;
+  error?: { message?: string; code?: string } | null;
+}
+
+/**
+ * What `~/.tailglow/config.json` holds: the string settings `tglow config` manages, plus what
+ * `tglow login` stores under `login` and `pending_login`. Every reader checks the shape it needs.
+ */
+export type CliConfig = Record<string, unknown>;
+
+/** The credential `tglow login` collected. `id` is the session or key id, for `tglow logout`. */
+export interface StoredLogin {
+  type: "session" | "api_key";
+  secret: string;
+  id: string;
+  /** The API that issued the credential, and the only one it is ever sent to. */
+  api_url: string;
+  team_id: string;
+  user_id: string;
+  email: string;
+}
+
+/** A sign-in started by `tglow login` and not yet collected. */
+export interface PendingLogin {
+  id: string;
+  poll_secret: string;
+  user_code: string;
+  verification_url: string;
+  method: "account" | "api_key";
+  api_url: string;
+  /** Epoch milliseconds. Only a safety net: the server decides when a sign-in has ended. */
+  started_at: number;
+  /** API expiry in epoch milliseconds. Absent in older saved sign-ins. */
+  expires_at?: number;
+}
+
+export interface ResolvedCredential {
+  secret: string;
+  source: "flag" | "env" | "login" | "config";
+  login: StoredLogin | null;
 }
 
 /** One value an operation accepts, in whichever of the three places it belongs. */
@@ -32,6 +70,8 @@ export interface CliField {
   allowed_values: string[];
   /** The replacement to use instead, when the field is on its way out. */
   deprecated: string | null;
+  /** The keys a JSON field takes: inside the object, or inside each item of an object array. */
+  fields?: CliField[];
 }
 
 /** One API operation, addressed as `<resource> <command>`. */