@fruggr/zendesk-mcp-server 2.17.2 → 2.18.0

package/dist/index.js

@@ -812,26 +812,195 @@ const loadConfig = (argv = process.argv.slice(2)) => {
 	});
 };
 //#endregion
+//#region src/client/retry.ts
+const MAX_ATTEMPTS = 3;
+const BASE_DELAY_MS = 250;
+const MAX_DELAY_MS = 4e3;
+const REQUEST_TIMEOUT_MS = 3e4;
+const TRANSFER_TIMEOUT_MS = 12e4;
+/**
+* A deadline for one attempt. The abort surfaces as a `TimeoutError` whose `code`
+* is numeric, not a syscall string, so it classifies as `unknown`: a GET is
+* retried, a write is not — the request may have arrived before the deadline.
+*/
+const deadlineSignal = (timeoutMs) => AbortSignal.timeout(timeoutMs);
+const MAX_RETRY_AFTER_MS = 5e3;
+const POLICIES = {
+	GET: {
+		network: "any",
+		serverErrors: true
+	},
+	DELETE: {
+		network: "pre-send",
+		serverErrors: false
+	},
+	POST: {
+		network: "pre-send",
+		serverErrors: false
+	},
+	PUT: {
+		network: "pre-send",
+		serverErrors: false
+	}
+};
+const DELAY_SECONDS = /^\d+$/;
+const HTTP_DATE_START = /^[A-Za-z]/;
+const NON_ASCII = /[^ -~]/g;
+const TOKEN_SEGMENT = /\/token\/[^/]+/;
+const URL_IN_TEXT = /[a-z][a-z0-9+.-]*:\/\/\S+/gi;
+const PRE_SEND_CODES = /* @__PURE__ */ new Set([
+	"ENOTFOUND",
+	"EAI_AGAIN",
+	"ECONNREFUSED",
+	"UND_ERR_CONNECT_TIMEOUT"
+]);
+const defaultRetryDeps = {
+	sleep: (ms) => new Promise((resolve) => setTimeout(resolve, ms)),
+	random: Math.random
+};
+/** Non-ASCII bytes break `node:http` headers, so client error text stays ASCII. */
+const toAscii = (text) => text.replace(NON_ASCII, "?");
+/**
+* Identifies the request without leaking a credential: uploads carry an upload
+* token in the query string, and an attachment `content_url` carries a download
+* token as a path segment (`/attachments/token/<token>/`).
+*/
+const describeTarget = (url) => {
+	const { origin, pathname } = new URL(url);
+	return `${origin}${pathname.replace(TOKEN_SEGMENT, "/token/[redacted]")}`;
+};
+/** First `code` in the cause chain, inspecting 5 levels so a cycle cannot hang. */
+const errorCode = (err) => {
+	let current = err;
+	for (let depth = 0; depth < 5 && current !== null && typeof current === "object"; depth += 1) {
+		const { code, cause } = current;
+		if (typeof code === "string") return code;
+		current = cause;
+	}
+};
+const classifyNetworkError = (err) => PRE_SEND_CODES.has(errorCode(err)) ? "pre-send" : "unknown";
+const UNINFORMATIVE_NAMES = /* @__PURE__ */ new Set(["Error", "TypeError"]);
+/**
+* The client refuses to replay a write that may have landed — but the caller is
+* an LLM whose reflex on a failed tool call is to try again, which would undo
+* that. So a failed write says whether it may have taken effect. ASCII only,
+* same rule as the rest of the message.
+*/
+const MAY_HAVE_APPLIED_NOTE = "The write may already have been applied. Check the current state before retrying, or you may duplicate it.";
+const NEVER_SENT_NOTE = "The request never reached Zendesk, so nothing was applied. Retrying is safe.";
+const REFUSED_NOTE = "Zendesk refused the request, so nothing was applied. Retrying is safe.";
+/** Only a write can be duplicated by a replay, so only a write carries a note. */
+const writeNote = (method, note) => method === "GET" ? "" : ` ${note}`;
+/**
+* A cause message can quote the URL it failed on — Node's `fetch` refuses a URL
+* carrying credentials by printing the whole thing, query string included — which
+* would smuggle back exactly what `describeTarget` drops. Same treatment for both,
+* so one function owns what a URL may look like in our output.
+*/
+const redactUrls = (text) => text.replace(URL_IN_TEXT, (found) => {
+	try {
+		return new URL(found).origin === "null" ? "[url]" : describeTarget(found);
+	} catch {
+		return "[url]";
+	}
+});
+const failureDetail = (cause) => {
+	if (!(cause instanceof Error)) return redactUrls(String(cause));
+	const message = redactUrls(cause.message);
+	const code = errorCode(cause);
+	if (code !== void 0) return `${code}: ${message}`;
+	return UNINFORMATIVE_NAMES.has(cause.name) ? message : `${cause.name}: ${message}`;
+};
+const networkErrorMessage = (method, target, attempts, cause) => {
+	const base = `Network error on ${method} ${target} after ${attempts === 1 ? "1 attempt" : `${attempts} attempts`}: ${failureDetail(cause)}`;
+	const note = classifyNetworkError(cause) === "pre-send" ? NEVER_SENT_NOTE : MAY_HAVE_APPLIED_NOTE;
+	return toAscii(method === "GET" ? base : `${base}.${writeNote(method, note)}`);
+};
+const createZendeskNetworkError = (method, target, attempts, cause) => Object.assign(new Error(networkErrorMessage(method, target, attempts, cause), { cause }), {
+	name: "ZendeskNetworkError",
+	method,
+	target,
+	attempts
+});
+/** Exponential backoff with equal jitter: half the window fixed, half random. */
+const computeBackoffMs = (attempt, random) => {
+	const window = Math.min(BASE_DELAY_MS * 2 ** (attempt - 1), MAX_DELAY_MS);
+	return Math.round(window / 2 + window * random() / 2);
+};
+/** `Retry-After` in ms — delay-seconds or HTTP-date. */
+const parseRetryAfter = (header, now = Date.now()) => {
+	if (header === null) return void 0;
+	const value = header.trim();
+	if (DELAY_SECONDS.test(value)) return Number(value) * 1e3;
+	if (!HTTP_DATE_START.test(value)) return void 0;
+	const date = Date.parse(value);
+	if (Number.isNaN(date)) return void 0;
+	return Math.max(0, date - now);
+};
+/**
+* How long to wait before replaying this response, or undefined to accept it.
+* `Retry-After` wins over backoff wherever it appears — Zendesk sends it on a 503
+* during maintenance as well as on a 429 — and a value past the cap means the
+* response is surfaced rather than parking the call for that long.
+*/
+const retryDelayFor = (response, policy, attempt, random) => {
+	if (!(response.status === 429 || response.status >= 500 && policy.serverErrors)) return void 0;
+	const retryAfter = parseRetryAfter(response.headers.get("retry-after"));
+	if (retryAfter === void 0) return computeBackoffMs(attempt, random);
+	return retryAfter > MAX_RETRY_AFTER_MS ? void 0 : retryAfter;
+};
+/**
+* Runs `attempt` until it succeeds, hits a terminal outcome, or spends the
+* attempt budget. Returns the last response for the caller to inspect (a
+* non-ok status is still the caller's to turn into a `ZendeskApiError`), and
+* throws `ZendeskNetworkError` when no response was ever obtained.
+*/
+const fetchWithRetry = async (attempt, method, target, deps = defaultRetryDeps) => {
+	const policy = POLICIES[method];
+	for (let tries = 1;; tries += 1) {
+		const last = tries >= MAX_ATTEMPTS;
+		let response;
+		try {
+			response = await attempt();
+		} catch (err) {
+			const replayable = policy.network === "any" || classifyNetworkError(err) === policy.network;
+			if (last || !replayable) throw createZendeskNetworkError(method, target, tries, err);
+			await deps.sleep(computeBackoffMs(tries, deps.random));
+			continue;
+		}
+		if (last) return response;
+		const delayMs = retryDelayFor(response, policy, tries, deps.random);
+		if (delayMs === void 0) return response;
+		await response.text().catch(() => void 0);
+		await deps.sleep(delayMs);
+	}
+};
+//#endregion
 //#region src/client/zendesk-api.ts
 var ZendeskApiError = class ZendeskApiError extends Error {
 	status;
 	statusText;
 	body;
-	constructor(status, statusText, body) {
-		super(ZendeskApiError.buildMessage(status, statusText, body));
+	method;
+	constructor(status, statusText, body, method) {
+		super(ZendeskApiError.buildMessage(status, statusText, body, method));
 		this.status = status;
 		this.statusText = statusText;
 		this.body = body;
+		this.method = method;
 		this.name = "ZendeskApiError";
 	}
-	static buildMessage(status, statusText, body) {
+	static buildMessage(status, statusText, body, method) {
 		switch (status) {
 			case 401: return "Authentication failed. Your Zendesk token may be expired or invalid. Re-authenticate to get a new token.";
 			case 403: return "Permission denied. Your Zendesk account does not have access to this resource.";
 			case 404: return `Resource not found. Please verify the ID is correct. (${statusText})`;
 			case 422: return `Validation error: ${body}`;
-			case 429: return "Rate limit exceeded. Please wait before making more requests.";
-			default: return `Zendesk API error ${status}: ${statusText}. ${body}`;
+			case 429: return `Rate limit exceeded. Please wait before making more requests.${writeNote(method, REFUSED_NOTE)}`;
+			default: {
+				const message = `Zendesk API error ${status}: ${statusText}. ${body}`;
+				return status >= 500 ? `${message}${writeNote(method, MAY_HAVE_APPLIED_NOTE)}` : message;
+			}
 		}
 	}
 };
@@ -841,6 +1010,11 @@ const buildUrl = (base, path, params) => {
 	if (params) for (const [key, value] of Object.entries(params)) url.searchParams.set(key, value);
 	return url.toString();
 };
+const performFetch = (method, url, init, timeoutMs = REQUEST_TIMEOUT_MS) => fetchWithRetry(() => fetch(url, {
+	...init,
+	method,
+	signal: deadlineSignal(timeoutMs)
+}), method, describeTarget(url));
 const executeRequest = async (url, token, options = {}) => {
 	const { method = "GET", body } = options;
 	const headers = {
@@ -848,15 +1022,12 @@ const executeRequest = async (url, token, options = {}) => {
 		Accept: "application/json"
 	};
 	if (body) headers["Content-Type"] = "application/json";
-	const init = {
-		method,
-		headers
-	};
+	const init = { headers };
 	if (body) init.body = JSON.stringify(body);
-	const response = await fetch(url, init);
+	const response = await performFetch(method, url, init);
 	if (!response.ok) {
 		const responseBody = await response.text();
-		throw new ZendeskApiError(response.status, response.statusText, responseBody);
+		throw new ZendeskApiError(response.status, response.statusText, responseBody, method);
 	}
 	if (response.status === 204) return {};
 	return response.json();
@@ -905,10 +1076,10 @@ const fetchZendeskBinary = async (subdomain, token, contentUrl) => {
 	const expectedHost = `${subdomain}.zendesk.com`;
 	const headers = {};
 	if (new URL(contentUrl).hostname === expectedHost) headers["Authorization"] = buildAuthHeader(token);
-	const response = await fetch(contentUrl, { headers });
+	const response = await performFetch("GET", contentUrl, { headers }, TRANSFER_TIMEOUT_MS);
 	if (!response.ok) {
 		const body = await response.text();
-		throw new ZendeskApiError(response.status, response.statusText, body);
+		throw new ZendeskApiError(response.status, response.statusText, body, "GET");
 	}
 	const contentType = response.headers.get("content-type") ?? "application/octet-stream";
 	const arrayBuffer = await response.arrayBuffer();
@@ -921,30 +1092,28 @@ const zendeskUpload = async (subdomain, token, filename, data, contentType, uplo
 	const params = { filename };
 	if (uploadToken) params["token"] = uploadToken;
 	const url = buildUrl(getBaseUrl(subdomain), "/uploads", params);
-	const response = await fetch(url, {
-		method: "POST",
+	const response = await performFetch("POST", url, {
 		headers: {
 			Authorization: buildAuthHeader(token),
 			"Content-Type": contentType
 		},
 		body: data
-	});
+	}, TRANSFER_TIMEOUT_MS);
 	if (!response.ok) {
 		const responseBody = await response.text();
-		throw new ZendeskApiError(response.status, response.statusText, responseBody);
+		throw new ZendeskApiError(response.status, response.statusText, responseBody, "POST");
 	}
 	return response.json();
 };
 const helpCenterUpload = async (subdomain, token, path, formData) => {
 	const url = buildUrl(getHelpCenterBaseUrl(subdomain), path);
-	const response = await fetch(url, {
-		method: "POST",
+	const response = await performFetch("POST", url, {
 		headers: { Authorization: buildAuthHeader(token) },
 		body: formData
-	});
+	}, TRANSFER_TIMEOUT_MS);
 	if (!response.ok) {
 		const responseBody = await response.text();
-		throw new ZendeskApiError(response.status, response.statusText, responseBody);
+		throw new ZendeskApiError(response.status, response.statusText, responseBody, "POST");
 	}
 	return response.json();
 };
@@ -4593,8 +4762,10 @@ const readJsonBody = (req, maxBodyBytes) => new Promise((resolve) => {
 const respondBodyError = (req, res, failure) => {
 	const headers = failure.status === 413 ? { Connection: "close" } : {};
 	sendJsonRpcError(res, failure.status, failure.rpcCode, failure.message, headers);
-	if (failure.status === 413) if (res.writableFinished) req.destroy();
-	else res.once("finish", () => req.destroy());
+	if (failure.status === 413) {
+		if (res.writableFinished) req.destroy();
+		else res.once("finish", () => req.destroy());
+	}
 };
 const SESSION_IDLE_TIMEOUT_MS = 18e5;
 const SESSION_SWEEP_INTERVAL_MS = 6e4;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@fruggr/zendesk-mcp-server",
-  "version": "2.17.2",
+  "version": "2.18.0",
   "mcpName": "io.github.fruggr/zendesk-mcp-server",
   "description": "Deep Zendesk MCP server for your AI assistant: search, draft, update and translate Help Center articles and manage Support tickets end to end — comments, triage and image attachments.",
   "type": "module",
@@ -69,7 +69,7 @@
   "engines": {
     "node": ">=20"
   },
-  "packageManager": "pnpm@11.20.0+sha512.9a6f330a95b66446ea088faf1521405a8a01f07fde7124cc9958dfed52d4bb436737e65b08f85f37b46fcba375092558ac51262b816844b22f63406ed166bfee",
+  "packageManager": "pnpm@11.21.0+sha512.521705bce689924eac72f5a3587122f362689ef6571e55ba80076fd637c11132ecffada26fad4ea79c485bfddbfd3d5a2a5b05805a77e893de71ec8a6cca3bb1",
   "dependencies": {
     "@modelcontextprotocol/sdk": "1.30.0",
     "cheerio": "1.2.0",
@@ -89,9 +89,9 @@
   },
   "devDependencies": {
     "@biomejs/biome": "2.5.7",
-    "@semantic-release/changelog": "^6.0.3",
+    "@semantic-release/changelog": "^7.0.0",
     "@semantic-release/exec": "^7.1.0",
-    "@semantic-release/git": "^10.0.1",
+    "@semantic-release/git": "^11.0.0",
     "@semantic-release/github": "^12.0.6",
     "@semantic-release/npm": "^13.1.5",
     "@semantic-release/release-notes-generator": "^14.1.1",