salesforce-reports-mcp 0.2.0 → 0.4.0

package/dist/http-auth.js

@@ -0,0 +1,310 @@
+// The HTTP door's own OAuth 2.1 server, for one owner. It issues tokens only for this server's /mcp,
+// and only after the owner types the passcode from SF_REPORTS_HTTP_PASSCODE on the /authorize page.
+// Everything lives in memory: a restart signs every client out. Importing this module does nothing.
+import { createHash, randomBytes, timingSafeEqual } from "node:crypto";
+import { InvalidClientMetadataError, InvalidGrantError, InvalidScopeError, InvalidTargetError, InvalidTokenError, } from "@modelcontextprotocol/sdk/server/auth/errors.js";
+import { requireBearerAuth } from "@modelcontextprotocol/sdk/server/auth/middleware/bearerAuth.js";
+import { getOAuthProtectedResourceMetadataUrl, mcpAuthRouter } from "@modelcontextprotocol/sdk/server/auth/router.js";
+export const PASSCODE_ENV = "SF_REPORTS_HTTP_PASSCODE";
+export const MIN_PASSCODE_LENGTH = 16;
+const ACCESS_TTL_S = 60 * 60;
+const REFRESH_TTL_S = 30 * 24 * 60 * 60;
+const CODE_TTL_MS = 5 * 60 * 1000;
+const MAX_WRONG_PASSCODES = 10;
+const WRONG_PASSCODE_WINDOW_MS = 15 * 60 * 1000;
+// Hosts that may use plain http, for a public URL and for a registered redirect URI.
+const LOOPBACK_HTTP_HOSTS = ["localhost", "127.0.0.1", "[::1]"];
+/** The issuer URL: https, or http on localhost or 127.0.0.1, with no path, query or fragment. */
+export function resolvePublicUrl(raw) {
+    let url;
+    try {
+        url = new URL(raw);
+    }
+    catch {
+        throw new Error("--public-url must be an absolute URL, such as https://reports.example.com.");
+    }
+    // The SDK allows a plain http issuer only on these two hosts.
+    const loopback = url.hostname === "localhost" || url.hostname === "127.0.0.1";
+    if (url.protocol !== "https:" && !(url.protocol === "http:" && loopback)) {
+        throw new Error("--public-url must use https, unless its host is localhost or 127.0.0.1.");
+    }
+    if (url.pathname !== "/" || url.search || url.hash || url.username || url.password) {
+        throw new Error("--public-url must be an origin only, with no path, query or fragment, such as https://reports.example.com.");
+    }
+    return url;
+}
+/** Checks the passcode without ever putting it in the message. */
+export function checkPasscode(passcode) {
+    if (!passcode)
+        throw new Error(`${PASSCODE_ENV} must be set when --public-url turns the OAuth layer on.`);
+    if (passcode.length < MIN_PASSCODE_LENGTH)
+        throw new Error(`${PASSCODE_ENV} must be at least ${MIN_PASSCODE_LENGTH} characters.`);
+    return passcode;
+}
+/** Validates the options before anything starts, so a bad start fails before Salesforce is touched. */
+export function checkOAuthOptions(options) {
+    checkPasscode(options.passcode);
+    const publicUrl = resolvePublicUrl(options.publicUrl);
+    return { publicUrl, resource: new URL("/mcp", publicUrl) };
+}
+const sha256 = (value) => createHash("sha256").update(value, "utf8").digest();
+const hashKey = (value) => sha256(value).toString("base64url");
+const newSecret = () => randomBytes(32).toString("base64url");
+// A resource compared as a string, without its fragment and one trailing slash, as the SDK's bearer check does.
+function comparable(value) {
+    const text = String(value);
+    const hash = text.indexOf("#");
+    return (hash === -1 ? text : text.slice(0, hash)).replace(/\/$/, "");
+}
+function allowedRedirect(uri) {
+    let url;
+    try {
+        url = new URL(uri);
+    }
+    catch {
+        return false;
+    }
+    if (url.hash)
+        return false;
+    return url.protocol === "https:" || (url.protocol === "http:" && LOOPBACK_HTTP_HOSTS.includes(url.hostname));
+}
+const escapeHtml = (value) => value.replace(/[&<>"']/g, (c) => ({ "&": "&amp;", "<": "&lt;", ">": "&gt;", '"': "&quot;", "'": "&#39;" })[c]);
+/** An in-memory OAuth server for one owner. Codes and tokens are kept only as SHA-256 hashes. */
+export class OwnerOAuthProvider {
+    resource;
+    now;
+    passcodeHash;
+    clients = new Map();
+    codes = new Map();
+    grants = new Map();
+    wrongPasscodes = [];
+    constructor(options) {
+        this.resource = checkOAuthOptions(options).resource;
+        this.passcodeHash = sha256(options.passcode);
+        this.now = options.now ?? Date.now;
+    }
+    clientsStore = {
+        getClient: (clientId) => this.clients.get(clientId),
+        registerClient: (client) => {
+            const full = client;
+            if (full.redirect_uris.length === 0 || !full.redirect_uris.every(allowedRedirect)) {
+                throw new InvalidClientMetadataError("Each redirect URI must use https, or http on a loopback host.");
+            }
+            this.clients.set(full.client_id, full);
+            return full;
+        },
+    };
+    async authorize(client, params, res) {
+        if (params.resource && comparable(params.resource) !== comparable(this.resource)) {
+            throw new InvalidTargetError(`This server issues tokens only for ${this.resource.href}.`);
+        }
+        const req = res.req;
+        if (req.method !== "POST") {
+            this.page(res, 200, client, params);
+            return;
+        }
+        const now = this.now();
+        this.wrongPasscodes = this.wrongPasscodes.filter((t) => now - t < WRONG_PASSCODE_WINDOW_MS);
+        if (this.wrongPasscodes.length >= MAX_WRONG_PASSCODES) {
+            this.page(res, 429, client, params, "Too many wrong passcodes. Wait 15 minutes, then try again.");
+            return;
+        }
+        const given = typeof req.body?.passcode === "string" ? req.body.passcode : "";
+        if (!timingSafeEqual(sha256(given), this.passcodeHash)) {
+            this.wrongPasscodes.push(now);
+            this.page(res, 403, client, params, "That passcode is not right.");
+            return;
+        }
+        this.prune(now);
+        const code = newSecret();
+        this.codes.set(hashKey(code), {
+            clientId: client.client_id,
+            redirectUri: params.redirectUri,
+            challenge: params.codeChallenge,
+            resource: this.resource.href,
+            scopes: params.scopes ?? [],
+            expiresAt: now + CODE_TTL_MS,
+            challenged: false,
+        });
+        const target = new URL(params.redirectUri);
+        target.searchParams.set("code", code);
+        if (params.state !== undefined)
+            target.searchParams.set("state", params.state);
+        res.redirect(302, target.href);
+    }
+    // The token handler asks for the challenge, checks the verifier, then exchanges. Asking spends the code,
+    // so a wrong verifier burns it and a second try with the same code fails.
+    async challengeForAuthorizationCode(client, authorizationCode) {
+        const key = hashKey(authorizationCode);
+        const entry = this.codes.get(key);
+        if (!entry || entry.challenged || entry.clientId !== client.client_id || entry.expiresAt <= this.now()) {
+            this.codes.delete(key);
+            throw new InvalidGrantError("The authorization code is invalid, used or expired.");
+        }
+        entry.challenged = true;
+        return entry.challenge;
+    }
+    async exchangeAuthorizationCode(client, authorizationCode, _codeVerifier, redirectUri, resource) {
+        const key = hashKey(authorizationCode);
+        const entry = this.codes.get(key);
+        this.codes.delete(key);
+        if (!entry || !entry.challenged || entry.clientId !== client.client_id || entry.expiresAt <= this.now()) {
+            throw new InvalidGrantError("The authorization code is invalid, used or expired.");
+        }
+        if (redirectUri !== undefined && redirectUri !== entry.redirectUri) {
+            throw new InvalidGrantError("redirect_uri does not match the authorization request.");
+        }
+        if (resource && comparable(resource) !== comparable(entry.resource)) {
+            throw new InvalidTargetError("resource does not match the authorization request.");
+        }
+        return this.issueTokens(client.client_id, new URL(entry.resource), entry.scopes);
+    }
+    async exchangeRefreshToken(client, refreshToken, scopes, resource) {
+        const key = hashKey(refreshToken);
+        const grant = this.grants.get(key);
+        if (!grant || grant.kind !== "refresh" || grant.clientId !== client.client_id || grant.expiresAt <= this.now()) {
+            if (grant && grant.expiresAt <= this.now())
+                this.grants.delete(key);
+            throw new InvalidGrantError("The refresh token is invalid, used or expired.");
+        }
+        if (resource && comparable(resource) !== comparable(grant.resource)) {
+            throw new InvalidTargetError("resource does not match the refresh token.");
+        }
+        if (scopes && !scopes.every((s) => grant.scopes.includes(s))) {
+            throw new InvalidScopeError("A refresh cannot widen the scopes.");
+        }
+        // Rotate: the old refresh token stops working.
+        this.grants.delete(key);
+        return this.issueTokens(client.client_id, new URL(grant.resource), scopes ?? grant.scopes);
+    }
+    async verifyAccessToken(token) {
+        const key = hashKey(token);
+        const grant = this.grants.get(key);
+        if (!grant || grant.kind !== "access")
+            throw new InvalidTokenError("The access token is not valid.");
+        if (grant.expiresAt <= this.now()) {
+            this.grants.delete(key);
+            throw new InvalidTokenError("The access token has expired.");
+        }
+        if (comparable(grant.resource) !== comparable(this.resource)) {
+            throw new InvalidTokenError("The access token was not issued for this resource.");
+        }
+        return {
+            token,
+            clientId: grant.clientId,
+            scopes: grant.scopes,
+            expiresAt: Math.floor(grant.expiresAt / 1000),
+            resource: new URL(grant.resource),
+        };
+    }
+    async revokeToken(client, request) {
+        const key = hashKey(request.token);
+        if (this.grants.get(key)?.clientId === client.client_id)
+            this.grants.delete(key);
+    }
+    /** Issues an access and refresh token pair. Only the hashes are kept. */
+    issueTokens(clientId, resource, scopes) {
+        const now = this.now();
+        this.prune(now);
+        const accessToken = newSecret();
+        const refreshToken = newSecret();
+        this.grants.set(hashKey(accessToken), { kind: "access", clientId, resource: resource.href, scopes, expiresAt: now + ACCESS_TTL_S * 1000 });
+        this.grants.set(hashKey(refreshToken), { kind: "refresh", clientId, resource: resource.href, scopes, expiresAt: now + REFRESH_TTL_S * 1000 });
+        return {
+            access_token: accessToken,
+            token_type: "Bearer",
+            expires_in: ACCESS_TTL_S,
+            refresh_token: refreshToken,
+            ...(scopes.length ? { scope: scopes.join(" ") } : {}),
+        };
+    }
+    prune(now) {
+        for (const [key, code] of this.codes)
+            if (code.expiresAt <= now)
+                this.codes.delete(key);
+        for (const [key, grant] of this.grants)
+            if (grant.expiresAt <= now)
+                this.grants.delete(key);
+    }
+    // One self-contained page: no script, no external asset. The passcode is never written back into it.
+    page(res, status, client, params, error) {
+        const name = escapeHtml(client.client_name || client.client_id);
+        const returnHost = escapeHtml(new URL(params.redirectUri).host);
+        const hidden = {
+            response_type: "code",
+            client_id: client.client_id,
+            redirect_uri: params.redirectUri,
+            code_challenge: params.codeChallenge,
+            code_challenge_method: "S256",
+            state: params.state,
+            scope: params.scopes?.length ? params.scopes.join(" ") : undefined,
+            resource: params.resource?.href,
+        };
+        const fields = Object.entries(hidden)
+            .filter((entry) => entry[1] !== undefined)
+            .map(([k, v]) => `<input type="hidden" name="${k}" value="${escapeHtml(v)}">`)
+            .join("\n      ");
+        const html = `<!doctype html>
+<html lang="en">
+<head>
+<meta charset="utf-8">
+<meta name="viewport" content="width=device-width, initial-scale=1">
+<title>Sign in to Salesforce reports</title>
+<style>
+  :root { color-scheme: light dark; }
+  body { margin: 0; font: 16px/1.5 system-ui, sans-serif; background: Canvas; color: CanvasText; }
+  main { max-width: 28rem; margin: 3rem auto; padding: 0 1rem; }
+  h1 { font-size: 1.4rem; }
+  .error { color: #b3261e; font-weight: 600; }
+  label { display: block; margin: 1.25rem 0 .25rem; font-weight: 600; }
+  input[type=password] { box-sizing: border-box; width: 100%; padding: .6rem; font: inherit; }
+  button { margin-top: 1rem; padding: .6rem 1.2rem; font: inherit; cursor: pointer; }
+  .small { font-size: .875rem; opacity: .8; }
+</style>
+</head>
+<body>
+<main>
+  <h1>Allow ${name} to use Salesforce reports?</h1>
+  <p><strong>${name}</strong> asks to connect to this server. Approving lets it run this server's tools as the Salesforce user this server is signed in as.</p>
+  <p class="small">After you approve, you go back to ${returnHost}. Only approve a client you just added yourself.</p>
+  ${error ? `<p class="error" role="alert">${escapeHtml(error)}</p>` : ""}
+  <form method="post" action="/authorize">
+      ${fields}
+    <label for="passcode">Passcode</label>
+    <input id="passcode" name="passcode" type="password" autocomplete="current-password" required autofocus>
+    <button type="submit">Approve</button>
+  </form>
+</main>
+</body>
+</html>
+`;
+        res.setHeader("Content-Security-Policy", "default-src 'none'; style-src 'unsafe-inline'; frame-ancestors 'none'; base-uri 'none'");
+        res.setHeader("X-Frame-Options", "DENY");
+        res.setHeader("Referrer-Policy", "no-referrer");
+        res.status(status).type("html").send(html);
+    }
+}
+export function createOwnerAuth(options) {
+    const { publicUrl, resource } = checkOAuthOptions(options);
+    const provider = new OwnerOAuthProvider(options);
+    // Behind a tunnel every request arrives from loopback with an X-Forwarded-For header. The SDK's limits then
+    // count all callers together, which suits one owner; skip the check that would print a stack trace for it.
+    const rateLimit = { validate: { xForwardedForHeader: false } };
+    const router = mcpAuthRouter({
+        provider,
+        issuerUrl: publicUrl,
+        resourceServerUrl: resource,
+        resourceName: "Salesforce reports",
+        authorizationOptions: { rateLimit },
+        clientRegistrationOptions: { rateLimit },
+        tokenOptions: { rateLimit },
+        revocationOptions: { rateLimit },
+    });
+    const bearer = requireBearerAuth({
+        verifier: provider,
+        resourceMetadataUrl: getOAuthProtectedResourceMetadataUrl(resource),
+        expectedResource: resource,
+    });
+    const allowedHosts = [...new Set([publicUrl.hostname, ...LOOPBACK_HTTP_HOSTS])];
+    return { provider, router, bearer, allowedHosts };
+}

package/dist/http.js

@@ -0,0 +1,94 @@
+import { randomUUID } from "node:crypto";
+import { createMcpExpressApp } from "@modelcontextprotocol/sdk/server/express.js";
+import { StreamableHTTPServerTransport } from "@modelcontextprotocol/sdk/server/streamableHttp.js";
+import { isInitializeRequest } from "@modelcontextprotocol/sdk/types.js";
+import { createOwnerAuth } from "./http-auth.js";
+export const LOOPBACK_HOSTS = ["127.0.0.1", "::1", "localhost"];
+export function assertLoopbackHost(host) {
+    if (!LOOPBACK_HOSTS.includes(host)) {
+        throw new Error(`--host ${host} is not loopback. A non-loopback host needs the OAuth layer: set --public-url and SF_REPORTS_HTTP_PASSCODE.`);
+    }
+}
+// Express request and response types are not imported here; the SDK's own types are enough.
+/* eslint-disable @typescript-eslint/no-explicit-any */
+export async function startHttpServer(options) {
+    const auth = options.oauth ? createOwnerAuth(options.oauth) : undefined;
+    if (!auth)
+        assertLoopbackHost(options.host);
+    const app = createMcpExpressApp(auth ? { host: options.host, allowedHosts: auth.allowedHosts } : { host: options.host });
+    if (auth)
+        app.use(auth.router);
+    const guard = auth ? [auth.bearer] : [];
+    const sessions = new Map();
+    const reject = (res, status, message) => {
+        res.status(status).json({ jsonrpc: "2.0", error: { code: -32000, message }, id: null });
+    };
+    app.post("/mcp", ...guard, async (req, res) => {
+        try {
+            const sessionId = req.headers["mcp-session-id"];
+            const existing = sessionId ? sessions.get(sessionId) : undefined;
+            if (existing) {
+                await existing.transport.handleRequest(req, res, req.body);
+                return;
+            }
+            if (sessionId || !isInitializeRequest(req.body)) {
+                reject(res, 400, "Bad Request: no valid session. Send an initialize request first.");
+                return;
+            }
+            const server = options.createServer();
+            const transport = new StreamableHTTPServerTransport({
+                sessionIdGenerator: () => randomUUID(),
+                onsessioninitialized: (id) => {
+                    sessions.set(id, { transport, server });
+                },
+            });
+            transport.onclose = () => {
+                if (transport.sessionId)
+                    sessions.delete(transport.sessionId);
+            };
+            await server.connect(transport);
+            await transport.handleRequest(req, res, req.body);
+        }
+        catch {
+            if (!res.headersSent)
+                reject(res, 500, "Internal server error");
+        }
+    });
+    const bySession = async (req, res) => {
+        try {
+            const sessionId = req.headers["mcp-session-id"];
+            const existing = sessionId ? sessions.get(sessionId) : undefined;
+            if (!existing) {
+                reject(res, 400, "Bad Request: unknown or missing session id.");
+                return;
+            }
+            await existing.transport.handleRequest(req, res);
+        }
+        catch {
+            if (!res.headersSent)
+                reject(res, 500, "Internal server error");
+        }
+    };
+    app.get("/mcp", ...guard, bySession);
+    app.delete("/mcp", ...guard, bySession);
+    const httpServer = await new Promise((resolve, reject2) => {
+        const s = app.listen(options.port, options.host, () => resolve(s));
+        s.on("error", reject2);
+    });
+    const port = httpServer.address().port;
+    let closing;
+    const close = () => {
+        closing ??= (async () => {
+            const open = [...sessions.values()];
+            sessions.clear();
+            await Promise.all(open.map(async ({ transport, server }) => {
+                await transport.close().catch(() => undefined);
+                await server.close().catch(() => undefined);
+            }));
+            httpServer.closeAllConnections();
+            await new Promise((resolve) => httpServer.close(() => resolve()));
+        })();
+        return closing;
+    };
+    return { port, host: options.host, close, oauth: auth?.provider };
+}

package/dist/index.js

@@ -4,10 +4,19 @@ import { parseArgs } from "node:util";
 import { ReportsApi } from "./reports/api.js";
 import { createClient, DEFAULT_API_VERSION } from "./salesforce/client.js";
 import { resolveConnection } from "./salesforce/connection.js";
+import { checkOAuthOptions, PASSCODE_ENV } from "./http-auth.js";
+import { assertLoopbackHost, startHttpServer } from "./http.js";
 import { buildServer } from "./server.js";
-const HELP = `salesforce-reports-mcp: an MCP server for Salesforce reports (stdio)
+import { dashboardFilesCommand } from "./dashboard-files.js";
+const HELP = `salesforce-reports-mcp: an MCP server for Salesforce reports (stdio, or Streamable HTTP with --http)
 
 Usage: salesforce-reports-mcp [--org <alias>] [options]
+       salesforce-reports-mcp dashboard-files --org <alias> --defs <file.json> --out <dir>
+
+  dashboard-files      Run report definitions read-only and write one result file per definition, for a Claude
+                       Dashboard. Flags: --org <alias> (required), --defs <file.json> (a JSON object mapping an id
+                       to query_report arguments), --out <dir> (required). Exit 0 when all reports were written,
+                       1 when any failed, 2 on a usage error. It starts no server.
 
   --org <alias>        Authenticate through the Salesforce CLI (env SF_ORG). Default: the sf default org.
                        Or set SF_INSTANCE_URL and SF_ACCESS_TOKEN to use a token you already hold.
@@ -15,12 +24,22 @@ Usage: salesforce-reports-mcp [--org <alias>] [options]
   --read-only          Register no write tools (env SF_REPORTS_READ_ONLY=1).
   --allow-delete       Register delete_report (env SF_REPORTS_ALLOW_DELETE=1).
   --max-rows <n>       Default cap on detail rows per result (env SF_REPORTS_MAX_ROWS). Default 200, ceiling 2000.
+  --http <port>        Serve Streamable HTTP at /mcp instead of stdio (env SF_REPORTS_HTTP_PORT). Port 0 picks a free port.
+  --host <host>        Host for --http (env SF_REPORTS_HTTP_HOST). Default 127.0.0.1. Loopback only, unless --public-url is set.
+  --public-url <url>   Turn on the OAuth layer for --http (env SF_REPORTS_PUBLIC_URL), for use behind a tunnel.
+                       The URL clients reach this server at, https unless its host is loopback; /mcp then needs
+                       a token this server issued. Needs ${PASSCODE_ENV} (env only, at least 16 characters):
+                       the owner types it on the sign-in page to approve a client.
   -h, --help           Show this help.
 `;
 function flag(value, envName) {
     return value ?? ["1", "true"].includes((process.env[envName] ?? "").toLowerCase());
 }
 async function main() {
+    if (process.argv[2] === "dashboard-files") {
+        process.exitCode = await dashboardFilesCommand(process.argv.slice(3));
+        return;
+    }
     const { values } = parseArgs({
         options: {
             org: { type: "string" },
@@ -28,6 +47,9 @@ async function main() {
             "read-only": { type: "boolean" },
             "allow-delete": { type: "boolean" },
             "max-rows": { type: "string" },
+            http: { type: "string" },
+            host: { type: "string" },
+            "public-url": { type: "string" },
             help: { type: "boolean", short: "h" },
         },
         strict: true,
@@ -41,14 +63,48 @@ async function main() {
     if (!Number.isInteger(maxRows) || maxRows < 1 || maxRows > 2000) {
         throw new Error("--max-rows must be a whole number from 1 to 2000.");
     }
+    const httpRaw = values.http ?? process.env.SF_REPORTS_HTTP_PORT;
+    const host = values.host ?? process.env.SF_REPORTS_HTTP_HOST ?? "127.0.0.1";
+    const publicUrl = values["public-url"] ?? process.env.SF_REPORTS_PUBLIC_URL;
+    let port;
+    let oauth;
+    if (httpRaw !== undefined && httpRaw !== "") {
+        port = Number(httpRaw);
+        if (!Number.isInteger(port) || port < 0 || port > 65535)
+            throw new Error("--http must be a port from 0 to 65535.");
+        if (publicUrl) {
+            // The passcode comes from the environment only, never a flag.
+            oauth = { publicUrl, passcode: process.env[PASSCODE_ENV] ?? "" };
+            checkOAuthOptions(oauth);
+        }
+        else {
+            assertLoopbackHost(host);
+        }
+    }
+    else if (values["public-url"] !== undefined) {
+        throw new Error("--public-url needs --http.");
+    }
     const connection = resolveConnection({ org: values.org });
     const client = createClient(connection, { apiVersion: values["api-version"] ?? process.env.SF_API_VERSION });
-    const server = buildServer(new ReportsApi(client), {
+    const reports = new ReportsApi(client);
+    const make = () => buildServer(reports, {
         readOnly: flag(values["read-only"], "SF_REPORTS_READ_ONLY"),
         allowDelete: flag(values["allow-delete"], "SF_REPORTS_ALLOW_DELETE"),
         maxRows,
     });
-    await server.connect(new StdioServerTransport());
+    if (port === undefined) {
+        await make().connect(new StdioServerTransport());
+        return;
+    }
+    const handle = await startHttpServer({ port, host, createServer: make, oauth });
+    const shutdown = () => {
+        void handle.close().then(() => process.exit(0));
+    };
+    process.once("SIGINT", shutdown);
+    process.once("SIGTERM", shutdown);
+    const local = `http://${host.includes(":") ? `[${host}]` : host}:${handle.port}/mcp`;
+    const signIn = handle.oauth ? ` (public at ${handle.oauth.resource.href}, OAuth sign-in on)` : "";
+    process.stderr.write(`salesforce-reports-mcp: listening on ${local}${signIn}\n`);
 }
 main().catch((error) => {
     process.stderr.write(`salesforce-reports-mcp: ${error instanceof Error ? error.message : String(error)}\n`);

package/dist/reports/api.js

@@ -59,6 +59,25 @@ export class ReportsApi {
         const out = await this.api.request("GET", `/query?q=${enc(query)}`);
         return out.records;
     }
+    // ---- dashboards. `filters` is a query string from resolveFilters, such as "?filter1=0IC…", or "". ----
+    describeDashboard(id) {
+        return this.api.request("GET", `/analytics/dashboards/${enc(id)}/describe`);
+    }
+    /** The cached results. Never refreshes. */
+    dashboardResults(id, filters = "") {
+        return this.api.request("GET", `/analytics/dashboards/${enc(id)}${filters}`);
+    }
+    dashboardStatus(id, filters = "") {
+        return this.api.request("GET", `/analytics/dashboards/${enc(id)}/status${filters}`);
+    }
+    /** Starts a refresh. The filter goes on the query string: a body is accepted and ignored. */
+    async refreshDashboard(id, filters = "") {
+        await this.api.request("PUT", `/analytics/dashboards/${enc(id)}${filters}`);
+    }
+    /** Waits between polls. Tests pass a sleep that returns at once. */
+    pause(ms) {
+        return this.sleep(ms);
+    }
     async runAsync(id, overrides) {
         const started = await this.api.request("POST", `/analytics/reports/${enc(id)}/instances?includeDetails=true`, overrides ? { reportMetadata: overrides } : undefined);
         const instanceId = started.id ?? started.attributes?.id;