@hubfluencer/mcp 0.4.0 → 0.6.0

package/src/client.ts

@@ -6,8 +6,21 @@
  * as `Authorization: Bearer <token>`. The token is NOT a JWT — never decode it.
  */
 
-import { assertSafeFetchUrl } from "./core.js";
+import {
+	assertSafeFetchUrl,
+	backoffDelayMs,
+	DEFAULT_RETRY,
+	isRetryableNetworkError,
+	isRetryableStatus,
+} from "./core.js";
 import { readStoredCredentials } from "./credentials.js";
+import { USER_AGENT } from "./version.js";
+
+const sleep = (ms: number) => new Promise((r) => setTimeout(r, ms));
+
+/** True when a poll deadline is set and already in the past. */
+const deadlinePassed = (deadline: number | undefined): boolean =>
+	deadline !== undefined && Date.now() >= deadline;
 
 export interface HubfluencerError extends Error {
 	status: number;
@@ -15,6 +28,32 @@ export interface HubfluencerError extends Error {
 	body?: unknown;
 }
 
+/**
+ * Flattens a Phoenix changeset error map (`%{field => [msgs]}`) into one readable
+ * line: `"validation failed — email: can't be blank; name: is too short"`. Field
+ * order is stabilized (alphabetical) so the message is deterministic across
+ * retries/tests regardless of JSON key order. Each field's messages are joined
+ * with ", "; fields are joined with "; ". A non-array value is coerced to its
+ * string form so an unexpected shape still yields detail rather than "[object
+ * Object]" swallowing it. Returns null when nothing usable can be extracted.
+ */
+function composeChangesetMessage(
+	errors: Record<string, unknown>,
+): string | null {
+	const parts: string[] = [];
+	for (const field of Object.keys(errors).sort()) {
+		const val = errors[field];
+		const msgs = Array.isArray(val)
+			? val.map((m) => String(m)).filter((m) => m.length > 0)
+			: val !== undefined && val !== null && String(val).length > 0
+				? [String(val)]
+				: [];
+		if (msgs.length > 0) parts.push(`${field}: ${msgs.join(", ")}`);
+	}
+	if (parts.length === 0) return null;
+	return `validation failed — ${parts.join("; ")}`;
+}
+
 function makeError(status: number, body: unknown): HubfluencerError {
 	// The API's error envelope is not fully uniform; pull a message/code out of
 	// whatever shape we got.
@@ -44,6 +83,20 @@ function makeError(status: number, body: unknown): HubfluencerError {
 			message = (e.message as string) || message;
 		} else if (typeof b.message === "string") {
 			message = b.message;
+		} else if (b.errors && typeof b.errors === "object") {
+			// The Phoenix changeset envelope: %{errors: %{field => [msgs]}} with NO
+			// top-level error/message. Without this branch a 422 validation failure
+			// surfaces as the bare fallback ("Hubfluencer API error (HTTP 422)") with
+			// an undefined code and the per-field detail lost. Flatten it into a
+			// readable, deterministic message ("validation failed — field: msg;
+			// field2: msg") and give it a stable code an agent can branch on.
+			const composed = composeChangesetMessage(
+				b.errors as Record<string, unknown>,
+			);
+			if (composed) {
+				message = composed;
+				code = "validation_failed";
+			}
 		}
 	}
 
@@ -73,8 +126,25 @@ export interface RequestOptions {
 	/** Sent as the `Idempotency-Key` header on chargeable POSTs. */
 	idempotencyKey?: string;
 	query?: Record<string, string | number | undefined>;
+	/**
+	 * Absolute wall-clock deadline (epoch ms) that bounds this GET's *entire*
+	 * retry sequence, used on the poll path. Without it, a GET can retry up to
+	 * `DEFAULT_RETRY.attempts` times at 60s each (~180s of hard timeouts) — enough
+	 * to push a single poll iteration well past the caller's own budget and blow
+	 * the ~280s wait clamp that keeps a tool call under a 300s client timeout. With
+	 * it, each attempt's timeout is capped to the remaining budget and no further
+	 * retry is started once the deadline has passed. Ignored for non-GET methods.
+	 */
+	deadline?: number;
 }
 
+// Floor for a poll-path attempt's timeout so, even with almost no budget left, we
+// still fire one real request (giving the last poll iteration its status read) —
+// rather than a sub-second fetch that is doomed to abort. The retry-stop guards do
+// the actual overshoot-bounding; this just keeps that final attempt viable.
+const MIN_ATTEMPT_TIMEOUT_MS = 1_000;
+const DEFAULT_ATTEMPT_TIMEOUT_MS = 60_000;
+
 export class HubfluencerClient {
 	constructor(
 		private readonly baseUrl: string,
@@ -106,52 +176,121 @@ export class HubfluencerClient {
 		const headers: Record<string, string> = {
 			authorization: `Bearer ${this.token}`,
 			accept: "application/json",
+			"user-agent": USER_AGENT,
 		};
 		if (opts.body !== undefined) headers["content-type"] = "application/json";
 		if (opts.idempotencyKey) headers["idempotency-key"] = opts.idempotencyKey;
 
+		// Retry only idempotent GETs. A POST/PATCH/PUT/DELETE is never auto-retried:
+		// a blind retry of a create/render/charge could double-spend credits or fork
+		// a duplicate resource. GETs are safe to replay, so one transient blip (a
+		// dropped connection, a 502, a brief 429) backs off and retries instead of
+		// failing the whole tool call — and, crucially, the GET that every poll-loop
+		// iteration issues (fetchStatus) rides on this too.
+		const canRetry = method === "GET";
+		const attempts = canRetry ? DEFAULT_RETRY.attempts : 1;
+		// A poll-path GET carries an absolute deadline that bounds the whole retry
+		// sequence; non-GET methods never retry, so their deadline is meaningless
+		// and ignored (a create/render must not be abandoned mid-flight).
+		const deadline = canRetry ? opts.deadline : undefined;
+
 		// Bound every API call so a hung connection fails the tool cleanly
 		// instead of blocking the agent indefinitely (fetch has no default
 		// timeout). All endpoints return quickly — generation runs async server
-		// side, so 60s is generous headroom.
-		let res: Response;
-		try {
-			res = await fetch(url, {
-				method,
-				headers,
-				body: opts.body !== undefined ? JSON.stringify(opts.body) : undefined,
-				signal: AbortSignal.timeout(60_000),
-			});
-		} catch (e) {
+		// side, so 60s is generous headroom. On the poll path we additionally
+		// shrink each attempt's timeout to whatever budget remains before the
+		// deadline, so the retry sequence can't overrun the caller's wait clamp.
+		for (let attempt = 1; ; attempt++) {
+			let attemptTimeoutMs = DEFAULT_ATTEMPT_TIMEOUT_MS;
+			if (deadline !== undefined) {
+				// Cap this attempt's timeout to whatever budget remains (floored at a
+				// small minimum so we still fire one real request when nearly out of
+				// budget rather than a doomed sub-second fetch). Combined with the
+				// retry-stop guards below — no further attempt starts once the deadline
+				// has passed — this bounds the whole GET to a SINGLE ~remaining-budget
+				// attempt near the deadline instead of stacking 3×60s of timeouts past
+				// it, which would blow the caller's ~280s wait clamp.
+				const remaining = deadline - Date.now();
+				attemptTimeoutMs = Math.max(
+					MIN_ATTEMPT_TIMEOUT_MS,
+					Math.min(DEFAULT_ATTEMPT_TIMEOUT_MS, remaining),
+				);
+			}
+
+			let res: Response;
+			try {
+				res = await fetch(url, {
+					method,
+					headers,
+					body: opts.body !== undefined ? JSON.stringify(opts.body) : undefined,
+					signal: AbortSignal.timeout(attemptTimeoutMs),
+				});
+			} catch (e) {
+				// A network-layer failure or timeout on a GET with attempts left: back
+				// off and retry — but never once the poll deadline has passed (a retry
+				// then would only push the call further past its budget). Otherwise
+				// wrap and throw exactly as before.
+				if (
+					attempt < attempts &&
+					isRetryableNetworkError(e) &&
+					!deadlinePassed(deadline)
+				) {
+					await sleep(backoffDelayMs(attempt, DEFAULT_RETRY));
+					continue;
+				}
+				if (
+					e instanceof Error &&
+					(e.name === "TimeoutError" || e.name === "AbortError")
+				) {
+					// Report the ACTUAL per-attempt timeout, not a hardcoded 60s: on the
+					// poll path the deadline can clamp this attempt to whatever budget
+					// remained, so a "timed out after 60s" message would misreport a
+					// sub-60s abort and mislead debugging.
+					throw new Error(
+						`Request to ${method} ${path} timed out after ${attemptTimeoutMs}ms.`,
+					);
+				}
+				throw e instanceof Error
+					? new Error(`Network error on ${method} ${path}: ${e.message}`)
+					: e;
+			}
+
+			// A 5xx/429 on a GET with attempts left: drain the body (free the
+			// connection) and retry — unless the poll deadline has passed. The final
+			// attempt (or a passed deadline) falls through to makeError.
 			if (
-				e instanceof Error &&
-				(e.name === "TimeoutError" || e.name === "AbortError")
+				attempt < attempts &&
+				isRetryableStatus(res.status) &&
+				!deadlinePassed(deadline)
 			) {
-				throw new Error(`Request to ${method} ${path} timed out after 60s.`);
+				await res.text().catch(() => {});
+				await sleep(backoffDelayMs(attempt, DEFAULT_RETRY));
+				continue;
 			}
-			throw e instanceof Error
-				? new Error(`Network error on ${method} ${path}: ${e.message}`)
-				: e;
-		}
 
-		if (res.status === 204) return undefined as T;
+			if (res.status === 204) return undefined as T;
 
-		const text = await res.text();
-		let parsed: unknown;
-		if (text) {
-			try {
-				parsed = JSON.parse(text);
-			} catch {
-				parsed = text;
+			const text = await res.text();
+			let parsed: unknown;
+			if (text) {
+				try {
+					parsed = JSON.parse(text);
+				} catch {
+					parsed = text;
+				}
 			}
-		}
 
-		if (!res.ok) throw makeError(res.status, parsed);
-		return parsed as T;
+			if (!res.ok) throw makeError(res.status, parsed);
+			return parsed as T;
+		}
 	}
 
-	get<T = unknown>(path: string, query?: RequestOptions["query"]): Promise<T> {
-		return this.request<T>("GET", path, { query });
+	get<T = unknown>(
+		path: string,
+		query?: RequestOptions["query"],
+		deadline?: number,
+	): Promise<T> {
+		return this.request<T>("GET", path, { query, deadline });
 	}
 
 	post<T = unknown>(
@@ -181,6 +320,16 @@ export class HubfluencerClient {
 	del<T = unknown>(path: string): Promise<T> {
 		return this.request<T>("DELETE", path);
 	}
+
+	/**
+	 * The bare API origin (no trailing `/api`) — the host this client talks to.
+	 * NOTE: this is the API host, which does NOT serve the front web app's
+	 * no-login pages (e.g. `/review/<token>` lives on the web-app origin — see
+	 * `reviewWebOrigin` in perf-review-assets.ts). Don't build web-app URLs on it.
+	 */
+	get origin(): string {
+		return this.baseUrl;
+	}
 }
 
 /**
@@ -190,11 +339,10 @@ export class HubfluencerClient {
  */
 export function clientFromEnv(): HubfluencerClient {
 	const stored = readStoredCredentials();
-	const token = process.env.HUBFLUENCER_API_TOKEN || stored.token;
-	const baseUrl =
-		process.env.HUBFLUENCER_BASE_URL ||
-		stored.base_url ||
-		"https://hubfluencer.com";
+	const envToken = process.env.HUBFLUENCER_API_TOKEN;
+	const envBaseUrl = process.env.HUBFLUENCER_BASE_URL;
+	const token = envToken || stored.token;
+	const baseUrl = envBaseUrl || stored.base_url || "https://hubfluencer.com";
 
 	if (!token) {
 		throw new Error(
@@ -202,5 +350,16 @@ export function clientFromEnv(): HubfluencerClient {
 				"HUBFLUENCER_API_TOKEN (create one in the app: Settings → Access tokens).",
 		);
 	}
+	// Warn (stderr only — stdout is the MCP transport) when the token comes from the
+	// env but the base URL is inherited from the stored credentials file rather than
+	// the env: a fresh env PAT can then be silently sent to a stale/other origin (e.g.
+	// a leftover staging base_url in credentials.json). Naming the effective base lets
+	// the operator catch a wrong-origin mix before it matters.
+	if (envToken && !envBaseUrl && stored.base_url) {
+		console.error(
+			`Warning: using HUBFLUENCER_API_TOKEN from the environment but base URL ${stored.base_url} ` +
+				"from the stored credentials file. Set HUBFLUENCER_BASE_URL to override.",
+		);
+	}
 	return new HubfluencerClient(baseUrl, token);
 }