ask-refined-element-mcp 0.1.0

package/dist/tools.js

@@ -0,0 +1,668 @@
+/**
+ * Tool logic for the Ask Refined Element MCP server.
+ *
+ * Each exported function takes an {@link AskReClient} plus validated input and
+ * resolves to an MCP tool result ({ content, isError }). The logic is kept out
+ * of the transport wiring in server.ts so it can be unit-tested by driving a
+ * client backed by a mock fetch.
+ */
+const PREMIUM_PRICE_SATS = 100;
+/** Reusable pointer to the free payment tooling — kept in one place. */
+const LE_MCP = "github.com/refined-element/lightning-enable-mcp";
+const LE_DOCS = "docs.lightningenable.com";
+// ---------------------------------------------------------------------------
+// Result helpers
+// ---------------------------------------------------------------------------
+function ok(text) {
+    return { content: [{ type: "text", text }] };
+}
+function fail(text) {
+    return { content: [{ type: "text", text }], isError: true };
+}
+/** Turns an unexpected outcome into helpful text instead of leaking a stack trace. */
+function unexpected(outcome, action) {
+    if (outcome.kind === "network-error" || outcome.kind === "api-unavailable") {
+        return fail(outcome.message);
+    }
+    if (outcome.kind === "http-error") {
+        return fail(`The Ask Refined Element API returned HTTP ${outcome.status} while trying to ${action}${httpErrorDetail(outcome)}. This is unexpected; please try again shortly.`);
+    }
+    return fail(`Unexpected response while trying to ${action}.`);
+}
+/**
+ * Short body excerpt for an unexpected HTTP error. HTML error pages (typical
+ * for 5xx/gateway failures on this host) are summarized with a one-line hint
+ * instead of dumping markup into the agent-facing message; plain-text/JSON
+ * bodies keep the 300-char excerpt.
+ */
+function httpErrorDetail(outcome) {
+    if (!outcome.text) {
+        return "";
+    }
+    const contentType = outcome.headers.get("content-type")?.toLowerCase() ?? "";
+    const isHtml = contentType.includes("text/html") || outcome.text.trimStart().startsWith("<");
+    if (isHtml) {
+        return " — the response body was an HTML error page, not API output";
+    }
+    return ` — ${truncate(outcome.text, 300)}`;
+}
+function truncate(value, max) {
+    return value.length > max ? `${value.slice(0, max - 1)}…` : value;
+}
+export async function searchKnowledge(client, input) {
+    const query = input.query?.trim();
+    if (!query) {
+        return fail("Please provide a non-empty `query` to search the knowledge pack.");
+    }
+    const outcome = await client.searchKnowledge(query);
+    if (outcome.kind !== "ok") {
+        return unexpected(outcome, "search the knowledge pack");
+    }
+    const body = (outcome.json ?? {});
+    let results = Array.isArray(body.results) ? body.results : [];
+    // Optional client-side narrowing (the API ranks; these just filter/cap).
+    if (input.topic) {
+        results = results.filter((r) => r.topic === input.topic);
+    }
+    if (input.audience) {
+        results = results.filter((r) => r.audience === input.audience);
+    }
+    const limit = clampLimit(input.limit);
+    const total = results.length;
+    results = results.slice(0, limit);
+    if (results.length === 0) {
+        const filterNote = input.topic || input.audience
+            ? " (with the topic/audience filters applied)"
+            : "";
+        return ok(`No matches for "${query}"${filterNote}. Try broader terms, or drop the topic/audience filter. ` +
+            `The pack covers Xperience by Kentico upgrades, GEO (generative engine optimization), AI-driven development, Sentinel, and CMS architecture.`);
+    }
+    const header = `${total} match${total === 1 ? "" : "es"} for "${query}"` +
+        (total > results.length ? ` (showing the top ${results.length})` : "") +
+        ":";
+    const blocks = results.map((r, i) => formatSearchHit(r, i + 1));
+    const footer = "\nHow to go deeper: read a blog article, FAQ, case study, or service page in full with " +
+        "get_article(slug). Fetch a free checklist with get_checklist(slug). " +
+        "Retrieve a [PREMIUM] item with get_paid_playbook(slug).";
+    return ok([header, "", blocks.join("\n\n"), footer].join("\n"));
+}
+function clampLimit(limit) {
+    if (typeof limit !== "number" || Number.isNaN(limit))
+        return 5;
+    return Math.max(1, Math.min(20, Math.trunc(limit)));
+}
+function formatSearchHit(r, n) {
+    const title = r.title ?? r.slug ?? "(untitled item)";
+    const badges = [];
+    if (r.type)
+        badges.push(r.type);
+    if (r.topic)
+        badges.push(`topic: ${r.topic}`);
+    if (r.audience)
+        badges.push(`audience: ${r.audience}`);
+    const lines = [];
+    lines.push(`${n}. ${title}${r.isPremium ? "  [PREMIUM]" : ""}`);
+    if (badges.length)
+        lines.push(`   ${badges.join(" · ")}`);
+    if (r.slug)
+        lines.push(`   slug: ${r.slug}`);
+    if (r.summary)
+        lines.push(`   ${r.summary}`);
+    // Only render a tool call-to-action when there is a real slug to call with —
+    // guidance pointing at get_paid_playbook(slug: "") would just burn a round-trip.
+    if (r.isPremium) {
+        const price = r.premium?.priceSats ?? PREMIUM_PRICE_SATS;
+        if (r.slug) {
+            lines.push(`   → Premium (${price} sats). Full body via get_paid_playbook(slug: "${r.slug}").`);
+        }
+        else {
+            lines.push(`   → Premium (${price} sats).`);
+        }
+    }
+    else if (isChecklist(r) && r.slug) {
+        lines.push(`   → Free checklist. Full steps via get_checklist(slug: "${r.slug}").`);
+    }
+    else if (isArticle(r) && r.slug) {
+        lines.push(`   → Read the full article via get_article(slug: "${r.slug}").`);
+    }
+    return lines.join("\n");
+}
+function isChecklist(r) {
+    return (r.type ?? "").toLowerCase().includes("checklist");
+}
+/**
+ * An "article-like" hit: a blog article, FAQ, case study, or service page whose
+ * full body is fetched via get_article(slug). Detected by type label OR by the
+ * hit carrying a `url` (a reference to the full page) instead of an inline body.
+ */
+function isArticle(r) {
+    const t = (r.type ?? "").toLowerCase();
+    if (t.includes("article") ||
+        t.includes("blog") ||
+        t.includes("faq") ||
+        t.includes("case") ||
+        t.includes("service")) {
+        return true;
+    }
+    return Boolean(r.url);
+}
+// ---------------------------------------------------------------------------
+// Tool 2: get_checklist
+// ---------------------------------------------------------------------------
+export async function getChecklist(client, slug) {
+    const clean = slug?.trim();
+    if (!clean) {
+        return fail("Please provide a checklist `slug`, e.g. geo-readiness-checklist-basic.");
+    }
+    const outcome = await client.getChecklist(clean);
+    if (outcome.kind === "ok") {
+        // A 200 whose body is empty or not JSON must become helpful text, never a
+        // TypeError from dereferencing a null body.
+        if (outcome.json === null || typeof outcome.json !== "object") {
+            return fail(`The Ask Refined Element API returned an empty or non-JSON body (HTTP ${outcome.status}) ` +
+                `for the checklist "${clean}". This is unexpected; please try again shortly.`);
+        }
+        return ok(formatChecklist(outcome.json, clean));
+    }
+    if (outcome.kind === "http-error" && outcome.status === 402) {
+        const challenge = (outcome.json ?? {});
+        const price = challenge.priceSats ?? PREMIUM_PRICE_SATS;
+        return ok(`"${clean}" is a premium checklist (${price} sats) and is not served free here.\n\n` +
+            `Retrieve it through the L402-paid endpoint instead:\n` +
+            `  get_paid_playbook(slug: "${clean}")\n\n` +
+            `That tool returns a Lightning invoice to pay, then delivers the full checklist once the payment credential verifies.`);
+    }
+    if (outcome.kind === "http-error" && outcome.status === 404) {
+        return fail(`No free checklist found with slug "${clean}". ` +
+            `Use search_refined_element_knowledge to find valid slugs (free checklists are marked as such).`);
+    }
+    return unexpected(outcome, `fetch the checklist "${clean}"`);
+}
+function formatChecklist(body, slug) {
+    const title = body.title ?? slug;
+    const meta = [];
+    if (body.topic)
+        meta.push(`topic: ${body.topic}`);
+    if (body.audience)
+        meta.push(`audience: ${body.audience}`);
+    const lines = [title];
+    if (meta.length)
+        lines.push(meta.join(" · "));
+    if (body.summary) {
+        lines.push("");
+        lines.push(body.summary);
+    }
+    const steps = Array.isArray(body.steps) ? body.steps : [];
+    if (steps.length) {
+        lines.push("");
+        lines.push("Steps:");
+        steps.forEach((step, i) => lines.push(`${i + 1}. ${formatStep(step)}`));
+    }
+    else {
+        lines.push("");
+        lines.push("(This checklist has no steps listed.)");
+    }
+    return lines.join("\n");
+}
+function formatStep(step) {
+    if (typeof step === "string")
+        return step.trim();
+    const heading = step.title ?? step.action ?? step.step ?? "";
+    const detail = step.text ?? step.detail ?? step.description ?? "";
+    if (heading && detail)
+        return `${heading.trim()} — ${detail.trim()}`;
+    return (heading || detail).trim();
+}
+/**
+ * Header-safe charset for L402 credential parts: base64, base64url, or hex.
+ * Anything outside this set would make `fetch` throw a header TypeError.
+ */
+const CREDENTIAL_CHARSET = /^[A-Za-z0-9+/=_-]+$/;
+/**
+ * Normalizes an agent-supplied credential part: strips ALL internal whitespace
+ * and newlines (line-wrap artifacts from copying out of chat) so a visually
+ * correct macaroon/preimage still forms a valid Authorization header.
+ */
+function normalizeCredential(value) {
+    if (!value) {
+        return undefined;
+    }
+    const collapsed = value.replace(/\s+/g, "");
+    return collapsed.length > 0 ? collapsed : undefined;
+}
+/**
+ * Shared L402 credential resolution used by every L402-gated tool. Normalizes
+ * both parts, rejects a half-supplied pair BEFORE any network call, and
+ * validates the header-safe charset (a stray character would make fetch throw a
+ * header TypeError that must never masquerade as a network failure).
+ *
+ * Returns `{ credential }` (possibly `undefined` when neither part was given,
+ * i.e. the first, unauthenticated call) or `{ error }` — a ready-to-return
+ * failure ToolResult.
+ */
+function resolveL402Credential(rawMacaroon, rawPreimage, ctx) {
+    const macaroon = normalizeCredential(rawMacaroon);
+    const preimage = normalizeCredential(rawPreimage);
+    if ((macaroon && !preimage) || (!macaroon && preimage)) {
+        return {
+            error: fail("An L402 credential needs BOTH the `macaroon` (from the 402 challenge) and the payment `preimage` " +
+                `(proof you settled the invoice). ${ctx.firstCallHint}`),
+        };
+    }
+    if (!macaroon || !preimage) {
+        return {};
+    }
+    const invalidParts = [
+        CREDENTIAL_CHARSET.test(macaroon) ? null : "macaroon",
+        CREDENTIAL_CHARSET.test(preimage) ? null : "preimage",
+    ].filter((part) => part !== null);
+    if (invalidParts.length > 0) {
+        return {
+            error: fail(`Your ${invalidParts.join(" and ")} contains invalid characters — an L402 credential is ` +
+                `base64/base64url or hex only. Copy it exactly from the payment challenge (and the preimage ` +
+                `exactly as your wallet returned it), then call ${ctx.retryToolName} again.`),
+        };
+    }
+    return { credential: { macaroon, preimage } };
+}
+export async function getPaidPlaybook(client, input) {
+    const slug = input.slug?.trim();
+    if (!slug) {
+        return fail("Please provide a premium `slug`. Discover premium items with " +
+            "search_refined_element_knowledge — they are marked [PREMIUM] and include the slug to pass here.");
+    }
+    const cred = resolveL402Credential(input.macaroon, input.preimage, {
+        firstCallHint: "Call get_paid_playbook with only the slug first to obtain the challenge.",
+        retryToolName: "get_paid_playbook",
+    });
+    if (cred.error) {
+        return cred.error;
+    }
+    const hasCredential = Boolean(cred.credential);
+    const outcome = await client.getPlaybook(slug, cred.credential);
+    // Paid content delivered.
+    if (outcome.kind === "ok") {
+        // A 200 with an empty or non-JSON body must never throw — this is the paid
+        // path, and a user who just paid must get guidance, not a TypeError.
+        if (outcome.json === null || typeof outcome.json !== "object") {
+            return fail(`The Ask Refined Element API returned an empty or non-JSON body (HTTP ${outcome.status}) ` +
+                `instead of the premium item "${slug}". This is unexpected.` +
+                (hasCredential
+                    ? ` If you already paid, your macaroon and preimage remain valid — call get_paid_playbook ` +
+                        `again with the same slug, macaroon, and preimage. Do NOT pay again.`
+                    : ` Please try again shortly.`));
+        }
+        return ok(formatPlaybook(outcome.json, slug));
+    }
+    if (outcome.kind === "http-error" && outcome.status === 404) {
+        return fail(`No premium item found with slug "${slug}". ` +
+            `Use search_refined_element_knowledge to discover the current premium items — ` +
+            `they are marked [PREMIUM] and include the slug to pass here.`);
+    }
+    // 402: either the first (unauthenticated) call, or a credential that failed to verify.
+    if (outcome.kind === "http-error" && outcome.status === 402) {
+        const challenge = readChallenge(outcome);
+        const verificationFailed = hasCredential;
+        return ok(formatChallenge(slug, challenge, verificationFailed));
+    }
+    return unexpected(outcome, `fetch the premium item "${slug}"`);
+}
+function readChallenge(outcome) {
+    const body = (outcome.json ?? {});
+    // The invoice/macaroon can also arrive via the WWW-Authenticate header.
+    const wwwAuth = outcome.headers.get("www-authenticate") ?? "";
+    const macaroon = body.macaroon ?? extractL402Field(wwwAuth, "macaroon");
+    const invoice = body.invoice ?? extractL402Field(wwwAuth, "invoice");
+    return {
+        error: body.error,
+        priceSats: body.priceSats,
+        macaroon,
+        invoice,
+        endpoint: body.endpoint,
+    };
+}
+/**
+ * Pulls a field out of a `WWW-Authenticate: L402 …` header. Handles both the
+ * quoted form (macaroon="…") and the unquoted form (macaroon=…, terminated by
+ * a comma, whitespace, or the end of the header).
+ */
+function extractL402Field(header, field) {
+    const quoted = header.match(new RegExp(`(?:^|[\\s,])${field}\\s*=\\s*"([^"]*)"`, "i"));
+    if (quoted) {
+        return quoted[1];
+    }
+    const unquoted = header.match(new RegExp(`(?:^|[\\s,])${field}\\s*=\\s*([^",\\s]+)`, "i"));
+    return unquoted ? unquoted[1] : undefined;
+}
+function formatPlaybook(body, slug) {
+    const title = body.title ?? slug;
+    const meta = [];
+    if (body.topic)
+        meta.push(`topic: ${body.topic}`);
+    if (body.audience)
+        meta.push(`audience: ${body.audience}`);
+    const lines = [`${title} (premium — paid)`];
+    if (meta.length)
+        lines.push(meta.join(" · "));
+    if (body.summary) {
+        lines.push("");
+        lines.push(body.summary);
+    }
+    if (body.content) {
+        lines.push("");
+        lines.push(body.content);
+    }
+    return lines.join("\n");
+}
+/**
+ * Shared L402 challenge presenter used by every L402-gated tool so the
+ * payment-instruction formatting (the "L402 CHALLENGE" block + "HOW TO PAY AND
+ * UNLOCK" steps) is identical everywhere. Callers supply the price, the
+ * invoice/macaroon, the tool-specific opening line, the retry tool name (used
+ * for the "(no invoice returned — retry X)" placeholders), and the step-3
+ * lines describing how to call back.
+ */
+function renderL402Challenge(params) {
+    const invoice = params.invoice ?? `(no invoice returned — retry ${params.retryToolName})`;
+    const macaroon = params.macaroon ?? `(no macaroon returned — retry ${params.retryToolName})`;
+    return [
+        params.opening,
+        "",
+        "L402 CHALLENGE",
+        `  price:    ${params.price} sats`,
+        `  invoice:  ${invoice}`,
+        `  macaroon: ${macaroon}`,
+        "",
+        "HOW TO PAY AND UNLOCK",
+        `  1. Pay the Lightning invoice above. The easiest path: the free Lightning Enable MCP`,
+        `     server's pay_invoice tool (${LE_MCP}). Wallet setup is via NWC or Strike —`,
+        `     see ${LE_DOCS}. Any Lightning wallet that returns a payment preimage works.`,
+        `  2. Keep the payment preimage the wallet returns (proof of settlement).`,
+        ...params.step3,
+    ].join("\n");
+}
+function formatChallenge(slug, challenge, verificationFailed) {
+    const price = challenge.priceSats ?? PREMIUM_PRICE_SATS;
+    const opening = verificationFailed
+        ? `Payment could not be verified for "${slug}" — the macaroon/preimage did not settle the invoice. ` +
+            `Here is a fresh L402 challenge; pay this one and retry with its credential.`
+        : `"${slug}" is premium (${price} sats), gated with L402 (HTTP 402 Payment Required). ` +
+            `Pay the Lightning invoice below, then call this tool again with the macaroon and your payment preimage.`;
+    return renderL402Challenge({
+        opening,
+        price,
+        invoice: challenge.invoice,
+        macaroon: challenge.macaroon,
+        retryToolName: "get_paid_playbook",
+        step3: [
+            `  3. Call get_paid_playbook again with the SAME slug plus:`,
+            `       macaroon: the value above`,
+            `       preimage: the preimage from step 2`,
+            `     The tool sends "Authorization: L402 <macaroon>:<preimage>" and returns the full item.`,
+        ],
+    });
+}
+export async function listArticles(client, input) {
+    const limit = clampArticleLimit(input.limit);
+    const outcome = await client.listArticles(limit);
+    if (outcome.kind !== "ok") {
+        return unexpected(outcome, "list blog articles");
+    }
+    if (outcome.json === null || typeof outcome.json !== "object") {
+        return fail(`The Ask Refined Element API returned an empty or non-JSON body (HTTP ${outcome.status}) ` +
+            `while listing articles. This is unexpected; please try again shortly.`);
+    }
+    const body = outcome.json;
+    const articles = Array.isArray(body.articles) ? body.articles : [];
+    if (articles.length === 0) {
+        return ok("No blog articles are published yet. Try search_refined_element_knowledge for guidance " +
+            "items (checklists, playbooks), or check back soon.");
+    }
+    const header = `${articles.length} recent article${articles.length === 1 ? "" : "s"} from the Refined Element blog:`;
+    const blocks = articles.map((a, i) => formatArticleSummary(a, i + 1));
+    const footer = "\nRead any of these in full with get_article(slug).";
+    return ok([header, "", blocks.join("\n\n"), footer].join("\n"));
+}
+function clampArticleLimit(limit) {
+    if (typeof limit !== "number" || Number.isNaN(limit))
+        return 10;
+    return Math.max(1, Math.min(50, Math.trunc(limit)));
+}
+function formatArticleSummary(a, n) {
+    const title = a.title ?? a.slug ?? "(untitled article)";
+    const lines = [`${n}. ${title}`];
+    if (a.publishedDate)
+        lines.push(`   published: ${formatDate(a.publishedDate)}`);
+    if (a.summary)
+        lines.push(`   ${oneLine(a.summary)}`);
+    if (a.url)
+        lines.push(`   url: ${a.url}`);
+    if (a.slug)
+        lines.push(`   → Full text via get_article(slug: "${a.slug}").`);
+    return lines.join("\n");
+}
+// ---------------------------------------------------------------------------
+// Tool 5: get_article
+// ---------------------------------------------------------------------------
+export async function getArticle(client, slug) {
+    const clean = slug?.trim();
+    if (!clean) {
+        return fail("Please provide an article `slug`. Discover article slugs with list_articles or " +
+            "search_refined_element_knowledge.");
+    }
+    const outcome = await client.getArticle(clean);
+    if (outcome.kind === "ok") {
+        if (outcome.json === null || typeof outcome.json !== "object") {
+            return fail(`The Ask Refined Element API returned an empty or non-JSON body (HTTP ${outcome.status}) ` +
+                `for the article "${clean}". This is unexpected; please try again shortly.`);
+        }
+        return ok(formatArticle(outcome.json, clean));
+    }
+    if (outcome.kind === "http-error" && outcome.status === 404) {
+        return fail(`No article found with slug "${clean}". ` +
+            `Use list_articles or search_refined_element_knowledge to find valid article slugs.`);
+    }
+    return unexpected(outcome, `fetch the article "${clean}"`);
+}
+function formatArticle(body, slug) {
+    const title = body.title ?? slug;
+    const lines = [title];
+    if (body.publishedDate)
+        lines.push(`published: ${formatDate(body.publishedDate)}`);
+    if (body.summary) {
+        lines.push("");
+        lines.push(body.summary.trim());
+    }
+    const text = body.contentHtml ? htmlToText(body.contentHtml) : "";
+    if (text) {
+        lines.push("");
+        lines.push(text);
+    }
+    if (body.url) {
+        lines.push("");
+        lines.push(`Source: ${body.url}`);
+    }
+    return lines.join("\n");
+}
+export async function requestConsultation(client, input) {
+    const name = input.name?.trim();
+    const email = input.email?.trim();
+    const message = input.message?.trim();
+    const company = input.company?.trim() || undefined;
+    if (!name) {
+        return fail("Please provide your `name` so Mike knows who is reaching out.");
+    }
+    if (!email) {
+        return fail("Please provide an `email` so Mike can reply.");
+    }
+    if (!message) {
+        return fail("Please provide a `message`. Mike reads these personally — include enough context " +
+            "(what you're building, your Kentico version, timeline) for him to act on it.");
+    }
+    // Client-side email shape check to save a round-trip; the API does the real
+    // validation.
+    if (!isEmailShape(email)) {
+        return fail(`"${email}" does not look like an email address — it needs an "@" with text on both sides. ` +
+            `Fix it and try again.`);
+    }
+    const body = { name, email, message, ...(company ? { company } : {}) };
+    const priority = input.priority === true;
+    const outcome = priority
+        ? await client.submitPriorityContact(body)
+        : await client.submitContact(body);
+    if (outcome.kind === "ok") {
+        if (priority) {
+            return ok(`Priority noted — thanks, ${name}. Your message is flagged priority so Mike Rahel sees the urgency; ` +
+                `he reads every consultation request personally and will reply to ${email} directly.`);
+        }
+        return ok(`Thanks, ${name} — your message is in. Mike Rahel reads every consultation request personally, ` +
+            `so you'll hear back from him directly. The more context you gave, the faster he can help.\n\n` +
+            `Want Mike to see it flagged as urgent? Call request_consultation again with priority: true (still free).`);
+    }
+    const shaped = contactErrorOrNull(outcome);
+    if (shaped)
+        return shaped;
+    return unexpected(outcome, priority ? "send your priority consultation message" : "send your consultation message");
+}
+/**
+ * Shared shaping for the contact endpoints' error states that both lanes handle
+ * identically: 400 validation and 429 rate-limited (plus network/api-unavailable).
+ * Returns a ready-to-return failure, or `null` when the caller should handle the
+ * outcome itself (200, 402, or an unexpected status).
+ */
+function contactErrorOrNull(outcome) {
+    if (outcome.kind === "network-error" || outcome.kind === "api-unavailable") {
+        return fail(outcome.message);
+    }
+    if (outcome.kind === "http-error") {
+        if (outcome.status === 400) {
+            return fail(formatValidationError(outcome));
+        }
+        if (outcome.status === 429) {
+            return fail(formatRateLimited(outcome));
+        }
+    }
+    return null;
+}
+function formatValidationError(outcome) {
+    const detail = validationDetail(outcome);
+    return (`The Ask Refined Element API rejected your consultation request (HTTP 400 — validation)` +
+        (detail ? `: ${detail}` : ".") +
+        ` Check your name, email, and message, then try again.`);
+}
+function validationDetail(outcome) {
+    const body = outcome.json;
+    if (body && typeof body === "object") {
+        const b = body;
+        if (typeof b.message === "string" && b.message)
+            return b.message;
+        if (typeof b.error === "string" && b.error)
+            return b.error;
+        if (b.errors !== undefined) {
+            return typeof b.errors === "string" ? b.errors : JSON.stringify(b.errors);
+        }
+        return "";
+    }
+    // Non-JSON body: keep a short excerpt, but never dump an HTML error page.
+    if (outcome.text) {
+        const contentType = outcome.headers.get("content-type")?.toLowerCase() ?? "";
+        const isHtml = contentType.includes("text/html") || outcome.text.trimStart().startsWith("<");
+        if (!isHtml)
+            return truncate(outcome.text, 300);
+    }
+    return "";
+}
+function formatRateLimited(outcome) {
+    const retryAfter = outcome.headers.get("retry-after");
+    const wait = retryAfter
+        ? ` Retry after ${retryAfter} second${retryAfter === "1" ? "" : "s"}.`
+        : " Please wait a bit before retrying.";
+    return (`Too many requests — the consultation endpoint is rate-limited (HTTP 429).${wait} ` +
+        `Your message was not submitted; try again shortly.`);
+}
+/** Simple client-side email shape check (contains-@ + length). Real validation is the API's job. */
+function isEmailShape(email) {
+    if (email.length < 3 || email.length > 254)
+        return false;
+    const at = email.indexOf("@");
+    // Need an "@" with at least one char before and after it, and only one "@".
+    if (at <= 0 || at === email.length - 1)
+        return false;
+    return email.indexOf("@", at + 1) === -1;
+}
+// ---------------------------------------------------------------------------
+// Shared formatting helpers
+// ---------------------------------------------------------------------------
+/** Renders an ISO-ish date as its calendar day (YYYY-MM-DD); passes other strings through. */
+function formatDate(value) {
+    const trimmed = value.trim();
+    const match = trimmed.match(/^(\d{4}-\d{2}-\d{2})/);
+    return match ? match[1] : trimmed;
+}
+/** Collapses all internal whitespace/newlines to single spaces for one-line rendering. */
+function oneLine(value) {
+    return value.replace(/\s+/g, " ").trim();
+}
+/**
+ * Converts an HTML article body to readable plain text / lightweight Markdown:
+ * headings become `#`-prefixed lines, list items become `-` bullets, links
+ * become `text (href)`, and paragraph/`<br>` boundaries become blank lines.
+ * Everything else is stripped and common HTML entities are decoded. Anchors are
+ * resolved BEFORE headings/list items so links survive inside them.
+ */
+export function htmlToText(html) {
+    let s = html;
+    // Drop script/style blocks wholesale.
+    s = s.replace(/<(script|style)\b[\s\S]*?<\/\1>/gi, "");
+    // Links first, so their text+href survive inside headings and list items.
+    s = s.replace(/<a\b[^>]*?href=["']([^"']*)["'][^>]*>([\s\S]*?)<\/a>/gi, (_m, href, inner) => {
+        const label = stripTags(inner).trim();
+        if (!label)
+            return href;
+        return href ? `${label} (${href})` : label;
+    });
+    // Headings → Markdown atx headings.
+    s = s.replace(/<h([1-6])\b[^>]*>([\s\S]*?)<\/h\1>/gi, (_m, level, inner) => {
+        const hashes = "#".repeat(Number(level));
+        return `\n\n${hashes} ${stripTags(inner).trim()}\n\n`;
+    });
+    // List items → "- " bullets; list containers → surrounding blank lines.
+    s = s.replace(/<li\b[^>]*>([\s\S]*?)<\/li>/gi, (_m, inner) => `\n- ${stripTags(inner).trim()}`);
+    s = s.replace(/<\/(ul|ol)>/gi, "\n\n");
+    s = s.replace(/<(ul|ol)\b[^>]*>/gi, "\n");
+    // Block boundaries → blank line; <br> → newline.
+    s = s.replace(/<\/(p|div|section|article|header|footer|blockquote|tr|h[1-6])>/gi, "\n\n");
+    s = s.replace(/<br\s*\/?>/gi, "\n");
+    // Strip anything left, decode entities, tidy whitespace.
+    s = stripTags(s);
+    s = decodeEntities(s);
+    s = s.replace(/[ \t]+\n/g, "\n").replace(/\n{3,}/g, "\n\n").trim();
+    return s;
+}
+function stripTags(s) {
+    return s.replace(/<[^>]+>/g, "");
+}
+function decodeEntities(s) {
+    return s
+        .replace(/&nbsp;/gi, " ")
+        .replace(/&mdash;/gi, "—")
+        .replace(/&ndash;/gi, "–")
+        .replace(/&hellip;/gi, "…")
+        .replace(/&quot;/gi, '"')
+        .replace(/&#0*39;/g, "'")
+        .replace(/&apos;/gi, "'")
+        .replace(/&lt;/gi, "<")
+        .replace(/&gt;/gi, ">")
+        .replace(/&#x([0-9a-f]+);/gi, (_m, code) => safeCodePoint(parseInt(code, 16)))
+        .replace(/&#(\d+);/g, (_m, code) => safeCodePoint(Number(code)))
+        .replace(/&amp;/gi, "&");
+}
+function safeCodePoint(code) {
+    try {
+        return Number.isFinite(code) ? String.fromCodePoint(code) : "";
+    }
+    catch {
+        return "";
+    }
+}
+//# sourceMappingURL=tools.js.map