salesforce-reports-mcp 0.2.0 → 0.3.0

package/.claude-plugin/plugin.json

@@ -1,6 +1,6 @@
 {
   "name": "salesforce-reports",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "description": "Explore, design and deploy Salesforce reports with Claude: three skills and an MCP server over the Reports and Dashboards REST API.",
   "author": { "name": "nelsben" },
   "homepage": "https://github.com/nelsben/salesforce-reports-mcp",

package/README.md

@@ -1,23 +1,46 @@
 # salesforce-reports-mcp
 
-Claude finds, builds, runs and saves Salesforce reports. You ask a question in plain words and get the answer, with the report behind it.
+Claude finds, builds, runs and saves Salesforce reports, and reads your dashboards, from an MCP server on your own machine. Nothing is installed in Salesforce, no Salesforce MCP licence is needed, and no admin has to approve anything. You sign in with the Salesforce CLI you already use.
 
-This repo is working software, and a demonstration. It takes one useful job, reports, and delivers it to Claude three ways, from a server on your laptop to a feature that lives inside Salesforce. Every design choice is written down with what it costs. Built by [Ben Nelsen](https://github.com/nelsben).
+This repo is working software, and a demonstration of how to put MCP in front of Salesforce without Salesforce's own MCP. The same tools are also packaged as a feature inside the org, for people who cannot run a local server, and every design choice is written down with what it costs. Built by [Ben Nelsen](https://github.com/nelsben).
 
-> **You:** List the report types I can build on, then build me an opportunity report grouped by stage without saving it.
+> **You:** I'm a seller. How is our pipeline looking this fiscal year? Is there anything I should worry about, and can you show it to me by owner too?
 >
-> **Claude:** The org has 156 report types; here they are by category. Opportunities by stage: 8 open deals, $3,091,000. Negotiation/Review holds 3 of them and 39% of the value. Salesforce applied its default filters: close date this fiscal quarter, probability above 0. Nothing was saved. Want it across all close dates, or saved to your Private Reports?
+> **Claude:** $3.09M across 8 open opportunities, here by stage and by owner. Worries: one owner holds 91% of the dollars, one deal alone is 29% of the pipeline, nothing is closed won this fiscal year, and one deal has no amount. Salesforce applied its default probability filter. Nothing was saved; say the word and I will save it as a report.
 >
-> *claude.ai, through the MCP server hosted by Salesforce, signed in as the user ([rehearsal](docs/rehearsals/runner-hosted.md)).*
+> *Claude Desktop, through the local MCP server, signed in with the sf CLI ([rehearsal](docs/rehearsals/runner.md)).*
+
+![The report card for an unsaved opportunity report grouped by stage, drawn in light, then dark, then at phone width](docs/assets/report-view.gif)
+
+In Claude Desktop the run also draws as a card: the headline numbers, the filters Salesforce applied, the groups with a bar beside each amount, and a button that asks Claude to save it. Dashboards draw the same way, every component as its own chart.
+
+![The dashboard card for a pipeline dashboard: a metric, a gauge, a donut, bar, line, table, funnel and column charts](docs/assets/dashboard-card.png)
+
+*Drawn by the [render test](docs/decisions/0014-render-tests-through-a-test-host.md)'s host page from anonymised test data.*
+
+## Run it on your own org
+
+Two commands in Claude Code, with Node 20 and the Salesforce CLI signed in:
+
+```
+claude plugin marketplace add nelsben/salesforce-reports-mcp
+claude plugin install salesforce-reports@salesforce-reports
+```
+
+That installs the three skills and the MCP server. For Claude Desktop, [docs/claude-desktop.md](docs/claude-desktop.md) is the full recipe: the config entry with the two paths that trip people up, how to check it works, the safety flags, and what each Claude surface, including mobile, can do with a local server. [docs/install.md](docs/install.md#the-local-mcp-server) has every option.
+
+## Why I built this
+
+Most of what a company knows about its customers and its pipeline sits in Salesforce reports, and most of the people who need those answers cannot build a report. Assistants like Claude are becoming the way people ask, and the hard part is not the model: it is where the code runs, whose identity each call uses, and what it is allowed to change. I built this to work through those questions end to end for one real job, in the open, with every decision written down. The first answer is the local server, which needs nothing from Salesforce but an API session. The in-org packages show what it takes when that is not enough.
 
 ## What this repo shows
 
 | Claim | Where to look | Evidence you can check |
 | --- | --- | --- |
-| **1. Three ways to connect Salesforce and Claude**, each with its own trade-offs | [Three ways to connect](#three-ways-to-connect) | One tool contract and result shape on every door (12 tools locally, 11 in the org); a [parity check](docs/decisions/0010-verification-by-parity.md) runs the same calls through two doors against a real org and compares them |
-| **2. A useful feature added to Salesforce itself**, packaged the way an admin expects | [A feature inside Salesforce](#a-feature-inside-salesforce) | Three package directories; layered Apex with a CI test that fails if the layers leak; 65 Apex tests at 98% coverage |
+| **1. MCP on Salesforce without Salesforce MCP**, plus two in-org doors for when a local server is not an option | [Three ways to connect](#three-ways-to-connect) | One tool contract and result shape on every door (16 tools locally, 15 in the org); a [parity check](docs/decisions/0010-verification-by-parity.md) runs the same calls through two doors against a real org and compares them |
+| **2. A useful feature added to Salesforce itself**, packaged the way an admin expects | [A feature inside Salesforce](#a-feature-inside-salesforce) | Three package directories; layered Apex with a CI test that fails if the layers leak; 90 Apex tests at 99% coverage |
 | **3. Security, authentication and integration** done deliberately, per door | [Security and identity](#security-and-identity) | A different identity per door, a per-user JWT named credential with no stored secret, writes behind a custom permission, and a test that keeps org values out of the repo |
-| **4. Product and architecture judgment**, shown in the work | [How it was built](#how-it-was-built) | Personas and [experiences](docs/experiences.md), [6 probes](docs/probes/) before building, [14 decision records](docs/decisions/README.md), [live findings](docs/design.md), [7 rehearsals](docs/rehearsals/README.md) |
+| **4. Product and architecture judgment**, shown in the work | [How it was built](#how-it-was-built) | Personas and [experiences](docs/experiences.md), [7 probes](docs/probes/) before building, [19 decision records](docs/decisions/README.md), [live findings](docs/design.md), [7 rehearsals](docs/rehearsals/README.md) |
 
 ## The product
 
@@ -37,15 +60,13 @@ This repo is working software, and a demonstration. It takes one useful job, rep
 
 **Answers you can trust.** Every run returns the same compact shape: the filters that were applied, including the ones Salesforce adds on its own, the groups and totals, and notes that say when rows were cut or Salesforce ignored part of the request. The [experiences page](docs/experiences.md) has the personas and the facts that shaped them.
 
-**A report card in the chat.** In Claude Desktop, a report run on the local server also draws as a card the way Salesforce draws it: the title, the filters, the groups with totals, a link to open it in Salesforce and, for an unsaved report, a button that asks Claude to save it. It is an MCP App that loads nothing from the network. Clients that show only text, such as Claude Code, get the same result as text ([decision 0013](docs/decisions/0013-report-view-as-an-mcp-app.md)).
+**A report card in the chat.** The card at the top is an MCP App the local server carries with each run: the headline numbers, the filters, the groups with a bar beside each amount (or, for a matrix, a heat grid), the totals, a link to open it in Salesforce and, for an unsaved report, a button that asks Claude to save it. Claude's reply then leads with what the card cannot show instead of repeating it. The card loads nothing from the network, is styled with the Lightning Design System's own tokens so it reads as Salesforce ([decision 0018](docs/decisions/0018-cards-follow-the-lightning-design-system.md)), and every heat cell passes WCAG AA contrast in light and dark. Clients that show only text, such as Claude Code, get the same result as text ([decision 0013](docs/decisions/0013-report-view-as-an-mcp-app.md), [decision 0015](docs/decisions/0015-report-card-visuals.md)).
 
-![The report card for an unsaved opportunity report grouped by stage, drawn in light, then dark, then at phone width](docs/assets/report-view.gif)
-
-*Drawn by the [render test](docs/decisions/0014-render-tests-through-a-test-host.md)'s host page from anonymised test data.*
+**Dashboards, read and refreshed.** Claude can find a dashboard, describe its components and filters, read the numbers Salesforce last cached, and refresh it when the data is missing or old. A refresh counts as a write, so read-only mode leaves it out, and no tool saves a dashboard ([decision 0016](docs/decisions/0016-dashboards-read-and-refresh-only.md)). In Claude Desktop the result draws as the dashboard card above, with every component as its own chart in the dashboard's layout ([decision 0017](docs/decisions/0017-dashboard-card.md)).
 
 ## Three ways to connect
 
-The same tools reach Claude three ways. They differ in where the code runs, who hosts it and how the user signs in.
+The local server is the lead: it is the whole product for anyone on Claude Code or Claude Desktop, and it needs nothing from Salesforce beyond an API session. The same tools also reach Claude two more ways, for people who cannot run a local process: a seller on claude.ai, a Flow, an Agentforce agent. Those doors live inside the org as Apex. They differ in where the code runs, who hosts it and how the user signs in.
 
 ```mermaid
 flowchart LR
@@ -76,14 +97,14 @@ flowchart LR
 | **Installed in the org** | Nothing | `force-app` | `force-app`, `mcp-app`, optionally `callout-app` |
 | **Signs in with** | Your `sf` CLI session or a token | Your own Salesforce session | OAuth with PKCE through an External Client App |
 | **Clients** | Claude Code, Claude Desktop, any MCP client | Claude Code and any agent with a shell; Flow, Agentforce, any HTTP client | claude.ai and any remote MCP client, with nothing to host |
-| **Tools** | All 12, delete only with a flag | 11, no delete | 11, no delete |
-| **Choose it when** | One person, no org change allowed | An admin wants the feature in the org, used from scripts and agents | A team wants Claude in the browser, governed by the org |
+| **Tools** | All 16, including dashboards; delete only with a flag | 11, no delete | 11, no delete |
+| **Choose it when** | You can run a process on your machine. No org change, no Salesforce MCP | An admin wants the feature in the org, used from scripts and agents | A team wants Claude in the browser, governed by the org |
 
-Each door gets the same tool names, the same input and the same result ([decision 0001](docs/decisions/0001-one-contract-three-doors.md)). The skills bind to tool names, not to a door, so one skill works over all three. [docs/architecture.md](docs/architecture.md) has the sequence diagrams.
+Each door gets the same tool names, the same input and the same result ([decision 0001](docs/decisions/0001-one-contract-three-doors.md)). The skills bind to tool names, not to a door, so one skill works over all three. [docs/architecture.md](docs/architecture.md) has a numbered sequence diagram for each door, with every step explained.
 
 ## A feature inside Salesforce
 
-The in-org doors are a Salesforce feature an admin installs, not a script. They ship as three package directories in [salesforce/](salesforce/README.md) ([decision 0009](docs/decisions/0009-two-shipping-units.md)):
+The in-org doors are the same tools, rebuilt in Apex so they run where a local server cannot. They are a Salesforce feature an admin installs, not a script. They ship as three package directories in [salesforce/](salesforce/README.md) ([decision 0009](docs/decisions/0009-two-shipping-units.md)):
 
 | Package | Holds | Needs |
 | --- | --- | --- |
@@ -118,27 +139,21 @@ The method was the same for every feature: probe the platform, decide in writing
 
 | Step | What it produced |
 | --- | --- |
-| **Probe** before building | [6 probe write-ups](docs/probes/): can a hosted MCP server wrap Apex, can Apex call its own org's API, how big a result fits in the heap, which identity works under a hosted sign-in |
-| **Decide** in writing | [14 decision records](docs/decisions/README.md), each with what it costs and what was turned down |
+| **Probe** before building | [7 probe write-ups](docs/probes/): can a hosted MCP server wrap Apex, can Apex call its own org's API, how big a result fits in the heap, which identity works under a hosted sign-in, how dashboards refresh and filter |
+| **Decide** in writing | [19 decision records](docs/decisions/README.md), each with what it costs and what was turned down |
 | **Build** to one contract | [design.md](docs/design.md): the input and output shapes, and the live findings where Salesforce did not behave as documented |
-| **Verify** against a real org | 161 unit and server tests, 8 render tests that draw the report card in a browser, 65 Apex tests, a live end-to-end check that leaves no report behind, and a parity check across doors |
+| **Verify** against a real org | 256 unit and server tests, 24 render tests that draw the report and dashboard cards in a browser, 90 Apex tests, a live end-to-end check that leaves no report behind, and a parity check across doors; `npm run verify` runs all of it against one org and ends with one table of counts |
 | **Rehearse** the experience | [7 rehearsals](docs/rehearsals/README.md): real Claude runs of each skill on each door, with what went wrong and what changed |
 
 ## Get started
 
 | You want | Start here |
 | --- | --- |
-| Claude Code or Desktop on your own org, nothing installed in Salesforce | [Local MCP server](docs/install.md#the-local-mcp-server) |
+| Claude Desktop on your own org, nothing installed in Salesforce | [Claude Desktop guide](docs/claude-desktop.md) |
+| Claude Code or another MCP client, the same way | [Local MCP server](docs/install.md#the-local-mcp-server) |
 | The feature inside your org, called from the CLI, scripts or agents | [The REST door](docs/install.md#the-rest-door) |
 | Claude in the browser, signed in through Salesforce | [The MCP door](docs/install.md#the-mcp-door), then [the callout tools](docs/install.md#the-callout-tools-on-the-mcp-door) |
 
-The quickest try is the Claude Code plugin, which bundles the skills and the local server:
-
-```
-claude plugin marketplace add nelsben/salesforce-reports-mcp
-claude plugin install salesforce-reports@salesforce-reports
-```
-
 The tools, the result shape, the safety rails and the limits are in [docs/reference.md](docs/reference.md).
 
 ## Develop
@@ -156,7 +171,6 @@ npm run capture -- --org <alias>               # refresh the test fixtures (anon
 
 ## Roadmap
 
-- Dashboards: list, describe, refresh, and read component data.
 - Joined reports, report charts, and subscriptions.
 
 ## License

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;

package/dist/reports/dashboards.js

@@ -0,0 +1,308 @@
+import { InputError } from "../format.js";
+import { SalesforceError } from "../salesforce/client.js";
+import { soqlLike } from "./api.js";
+import { shapeResult } from "./shape.js";
+import { humanize, reportUrl } from "./summarize.js";
+/** Seconds between status polls after a refresh, and how many polls: 20 polls 3 seconds apart is 60 seconds. */
+export const REFRESH_POLL_MS = 3000;
+export const REFRESH_POLLS = 20;
+/** Default cap on detail rows per component. */
+export const COMPONENT_ROWS = 20;
+const DAY_MS = 24 * 60 * 60 * 1000;
+export function dashboardUrl(baseUrl, id) {
+    return baseUrl && id ? `${baseUrl}/lightning/r/Dashboard/${id}/view` : undefined;
+}
+/**
+ * SOQL on Dashboard. GET /analytics/dashboards lists only recently viewed dashboards, so listing goes through SOQL,
+ * which returns the dashboards the signed-in user can see. One row past the limit tells whether the list was cut.
+ */
+export function dashboardListSoql(input) {
+    const where = [];
+    if (input.query)
+        where.push(`(Title LIKE '%${soqlLike(input.query)}%' OR DeveloperName LIKE '%${soqlLike(input.query)}%')`);
+    if (input.folder)
+        where.push(`FolderName LIKE '%${soqlLike(input.folder)}%'`);
+    return `SELECT Id, Title, DeveloperName, FolderName, FolderId, Description, Type, LastModifiedDate FROM Dashboard${where.length ? ` WHERE ${where.join(" AND ")}` : ""} ORDER BY LastModifiedDate DESC LIMIT ${input.limit + 1}`;
+}
+/** The newest refresh date in a status answer, or null when no component was ever refreshed. */
+export function latestRefresh(status) {
+    const dates = (status?.componentStatus ?? []).map((c) => c.refreshDate).filter((d) => Boolean(d));
+    if (!dates.length)
+        return null;
+    return dates.reduce((a, b) => (time(b) > time(a) ? b : a));
+}
+export function optionLabel(option) {
+    if (option.alias)
+        return String(option.alias);
+    if (option.value !== null && option.value !== undefined && option.value !== "")
+        return String(option.value);
+    const start = option.startValue;
+    const end = option.endValue;
+    if (start && end)
+        return `${start} to ${end}`;
+    if (start)
+        return `${start} or more`;
+    if (end)
+        return `up to ${end}`;
+    return String(option.id);
+}
+/**
+ * Filter choices by name and option label, mapped to the option ids the data calls take. Salesforce reads the
+ * option id from `filter<n>` on the query string, n being the filter's place in describe's `filters` (only
+ * filter1 was proven, on a one-filter dashboard). The option text itself is refused with 400, so it is never sent.
+ */
+export function resolveFilters(meta, choices) {
+    const filters = (meta.filters ?? []);
+    const all = (f) => `${f.name}: all (no option chosen)`;
+    if (!choices?.length)
+        return { query: "", words: filters.map(all), applied: [] };
+    const listing = () => filters.map((f) => `${f.name} (${(f.options ?? []).map(optionLabel).join(", ")})`).join("; ");
+    if (!filters.length)
+        throw new InputError("This dashboard has no filters. Leave out `filters`.");
+    const chosen = new Map();
+    for (const choice of choices) {
+        const index = filters.findIndex((f) => same(f.name, choice.name));
+        if (index < 0)
+            throw new InputError(`No dashboard filter named "${choice.name}". This dashboard's filters: ${listing()}.`);
+        const filter = filters[index];
+        if (chosen.has(index))
+            throw new InputError(`The filter ${filter.name} is given twice. Give one option per filter.`);
+        const options = (filter.options ?? []);
+        const option = options.find((o) => o.id === choice.option || same(optionLabel(o), choice.option) || same(o.value, choice.option) || same(o.alias, choice.option));
+        if (!option)
+            throw new InputError(`${filter.name} has no option "${choice.option}". Its options: ${options.map(optionLabel).join(", ")}.`);
+        chosen.set(index, option);
+    }
+    const query = `?${[...chosen.entries()]
+        .sort(([a], [b]) => a - b)
+        .map(([i, o]) => `filter${i + 1}=${encodeURIComponent(String(o.id))}`)
+        .join("&")}`;
+    const words = filters.map((f, i) => (chosen.has(i) ? `${f.name}: ${optionLabel(chosen.get(i))}` : all(f)));
+    return { query, words, applied: words.filter((_, i) => chosen.has(i)) };
+}
+/** Whose data the dashboard shows, in words. */
+export function runningUserWords(meta) {
+    const name = meta.runningUser?.displayName;
+    switch (meta.dashboardType) {
+        case "SpecifiedUser":
+            return `${name ?? "A set user"}: the dashboard always runs as this user, so every viewer sees the same data.`;
+        case "LoggedInUser":
+            return "The viewer: each person sees the data they can see, so these results are the signed-in user's.";
+        case "MyTeamUser":
+            return "The viewer, who as a manager can also view it as someone on their team. These results are the signed-in user's.";
+        default:
+            return name ? `${name} (${meta.dashboardType ?? "unknown type"})` : "Unknown";
+    }
+}
+/** describe's components in layout order (top to bottom, then left to right), each with its grid position. */
+function inLayoutOrder(meta) {
+    const components = (meta.components ?? []);
+    const cells = (meta.layout?.components ?? []);
+    const placed = components.map((component, i) => {
+        const cell = cells[i];
+        const position = cell ? { row: cell.row, column: cell.column, rows: cell.rowspan, columns: cell.colspan } : null;
+        return { component, position, i };
+    });
+    placed.sort((a, b) => {
+        if (!a.position || !b.position)
+            return a.i - b.i;
+        return a.position.row - b.position.row || a.position.column - b.position.column || a.i - b.i;
+    });
+    return placed.map(({ component, position }) => ({ component, position }));
+}
+const AGGREGATE_WORDS = { s: "Sum of", a: "Average of", m: "Smallest", mx: "Largest", u: "Unique" };
+function measureLabel(name) {
+    if (name === "RowCount")
+        return "Record Count";
+    const prefix = /^([a-z]+)!/.exec(name)?.[1];
+    const words = prefix ? AGGREGATE_WORDS[prefix] : undefined;
+    return words ? `${words} ${humanize(name)}` : humanize(name);
+}
+export function summarizeDashboard(describe, options) {
+    const names = options.reportNames ?? new Map();
+    const nameOf = (id) => (id ? (names.get(id) ?? names.get(id.slice(0, 15)) ?? null) : null);
+    return {
+        id: describe.id,
+        name: describe.name,
+        developerName: describe.developerName ?? null,
+        description: describe.description ?? null,
+        folder: { id: describe.folderId ?? null, name: describe.folderName ?? null },
+        type: describe.dashboardType ?? null,
+        runningUser: runningUserWords(describe),
+        owner: describe.owner?.displayName ?? null,
+        url: dashboardUrl(options.baseUrl, describe.id),
+        filters: (describe.filters ?? []).map((f) => ({
+            name: f.name,
+            dataType: f.dataType ?? null,
+            options: (f.options ?? []).map(optionLabel),
+        })),
+        layout: `Components are listed in layout order: top to bottom, then left to right, on a grid ${describe.layout?.numColumns ?? 12} columns wide.`,
+        components: inLayoutOrder(describe).map(({ component: c, position }) => {
+            const props = c.properties ?? {};
+            const reportId = c.reportId ?? null;
+            return {
+                id: c.id,
+                header: c.header ?? null,
+                title: c.title ?? null,
+                footer: c.footer ?? null,
+                visualizationType: props.visualizationType ?? null,
+                report: { id: reportId, name: nameOf(reportId), url: reportUrl(options.baseUrl, reportId) },
+                groupings: (props.groupings ?? []).map((g) => g.name),
+                measures: (props.aggregates ?? []).map((a) => ({ name: a.name, label: measureLabel(a.name) })),
+                position,
+            };
+        }),
+    };
+}
+/** GET /analytics/dashboards/{id} to a DashboardResult. Each component's reportResult is shaped by shapeResult. */
+export function shapeDashboard(results, options) {
+    const meta = results.dashboardMetadata ?? {};
+    const applied = options.appliedFilters ?? [];
+    const data = new Map((results.componentData ?? []).map((d) => [d.componentId, d]));
+    const notes = [];
+    const id = meta.id ?? results.attributes?.dashboardId;
+    const components = inLayoutOrder(meta).map(({ component: c }) => {
+        const entry = data.get(c.id);
+        const status = entry?.status ?? {};
+        const props = c.properties ?? {};
+        const out = {
+            id: c.id,
+            header: c.header ?? null,
+            title: c.title ?? null,
+            footer: c.footer ?? null,
+            visualizationType: props.visualizationType ?? null,
+            status: componentStatus(entry),
+            refreshedAt: status.refreshDate ?? null,
+        };
+        if (out.status === "error") {
+            out.error = { code: String(status.errorCode ?? status.componentDataStatus ?? "UNKNOWN"), message: String(status.errorMessage ?? "Salesforce gave no message.") };
+        }
+        if (out.status === "data") {
+            const raw = entry.reportResult;
+            const result = shapeResult(raw, {
+                maxRows: options.maxRows,
+                includeDetail: raw.reportMetadata?.reportFormat === "TABULAR",
+                baseUrl: options.baseUrl,
+            });
+            // reportMetadata shows the source report's own filters, never the dashboard's.
+            if ((props.filterColumns ?? []).length)
+                result.filters.push(...applied.map((w) => `Dashboard filter ${w}`));
+            out.result = result;
+        }
+        return out;
+    });
+    const label = (c) => c.header ?? c.title ?? c.id;
+    const withData = components.filter((c) => c.status === "data");
+    const noData = components.filter((c) => c.status === "no data");
+    const forWhat = applied.length ? ` for ${applied.join(", ")}` : "";
+    if (components.length && noData.length === components.length) {
+        notes.push(`No component has data${forWhat}: the dashboard has not been refreshed${forWhat ? " with these filters" : ""}. Call refresh_dashboard with the same filters to get numbers.`);
+    }
+    else if (noData.length) {
+        notes.push(`${noData.length} of ${components.length} components have no data${forWhat} (${noData.map(label).join(", ")}). Call refresh_dashboard with the same filters to fill them.`);
+    }
+    for (const c of components.filter((x) => x.status === "error"))
+        notes.push(`${label(c)} failed in Salesforce: ${c.error.code}: ${c.error.message}`);
+    const dates = withData.map((c) => c.refreshedAt).filter((d) => Boolean(d));
+    const refreshedAt = dates.length ? dates.reduce((a, b) => (time(b) < time(a) ? b : a)) : null;
+    if (refreshedAt && withData.some((c) => data.get(c.id)?.status?.refreshStatus === "STALE")) {
+        notes.push(`Salesforce marks this data stale: the dashboard was refreshed since with other filters. These numbers are from ${refreshedAt}; call refresh_dashboard with the same filters for current ones.`);
+    }
+    if (refreshedAt) {
+        const age = options.now.getTime() - time(refreshedAt);
+        if (age > DAY_MS) {
+            const days = Math.floor(age / DAY_MS);
+            notes.push(`These numbers were refreshed ${days} day${days === 1 ? "" : "s"} ago, at ${refreshedAt}. Call refresh_dashboard for current ones.`);
+        }
+    }
+    for (const c of withData)
+        for (const n of c.result.notes)
+            notes.push(`${label(c)}: ${n}`);
+    return {
+        dashboard: {
+            id,
+            name: meta.name ?? results.attributes?.dashboardName ?? "Dashboard",
+            developerName: meta.developerName ?? null,
+            folder: { id: meta.folderId ?? null, name: meta.folderName ?? null },
+            url: dashboardUrl(options.baseUrl, id),
+        },
+        runningUser: runningUserWords(meta),
+        filters: options.filterWords,
+        refreshedAt,
+        components,
+        notes,
+    };
+}
+function componentStatus(entry) {
+    const status = entry?.status ?? {};
+    if (status.errorCode || status.componentDataStatus === "ERROR")
+        return "error";
+    if (entry?.reportResult)
+        return "data";
+    if (!entry || status.componentDataStatus === "NO_DATA" || status.componentDataStatus === "DATA")
+        return "no data";
+    return "error";
+}
+/** The once-a-minute refusal: 403 FORBIDDEN, "You can't refresh this dashboard more than once in a minute." */
+export function isRefreshLimit(error) {
+    return error instanceof SalesforceError && error.status === 403 && (error.code === "FORBIDDEN" || /minute/i.test(error.message));
+}
+/** A component is done when it is not running and has an error, or data newer than before the refresh. */
+export function refreshDone(status, before) {
+    return (status.componentStatus ?? []).every((c) => {
+        if (c.refreshStatus === "RUNNING")
+            return false;
+        if (c.errorCode || c.componentDataStatus === "ERROR")
+            return true;
+        return c.componentDataStatus === "DATA" && Boolean(c.refreshDate) && c.refreshDate !== before.get(c.componentId);
+    });
+}
+/**
+ * Starts a refresh and waits for it: PUT with the filters on the query string (a body is ignored), then the
+ * status every 3 seconds until every component is done or 60 seconds pass. Returns notes for the result.
+ * The once-a-minute 403 becomes a note; any other failure is thrown.
+ */
+export async function refreshAndWait(reports, id, filters, now) {
+    const before = new Map();
+    try {
+        for (const c of ((await reports.dashboardStatus(id, filters)).componentStatus ?? []))
+            before.set(c.componentId, c.refreshDate ?? null);
+    }
+    catch {
+        /* without the earlier dates, any data counts as new */
+    }
+    try {
+        await reports.refreshDashboard(id, filters);
+    }
+    catch (error) {
+        if (!isRefreshLimit(error))
+            throw error;
+        // A minute after this filter's last refresh when that is still ahead, else a minute from now (the last refresh
+        // may have been for other filters, which this status does not show).
+        const last = [...before.values()].filter((d) => Boolean(d)).map(time).reduce((a, b) => Math.max(a, b), 0);
+        const nowMs = now().getTime();
+        const retry = last + 60_000 > nowMs ? last + 60_000 : nowMs + 60_000;
+        const after = new Date(retry).toISOString().replace(/\.\d{3}Z$/, "Z");
+        return [
+            `Salesforce refreshes a dashboard at most once a minute, and this one was refreshed less than a minute ago, so these are the cached results. Try again after ${after}.`,
+        ];
+    }
+    for (let poll = 0; poll < REFRESH_POLLS; poll++) {
+        await reports.pause(REFRESH_POLL_MS);
+        try {
+            if (refreshDone(await reports.dashboardStatus(id, filters), before))
+                return [];
+        }
+        catch {
+            /* a failed poll is retried at the next one */
+        }
+    }
+    return [`The refresh had not finished after ${(REFRESH_POLL_MS * REFRESH_POLLS) / 1000} seconds, so some components may show older data. Call run_dashboard in a minute to read the refreshed results.`];
+}
+function same(a, b) {
+    return typeof a === "string" && typeof b === "string" && a.trim().toLowerCase() === b.trim().toLowerCase();
+}
+/** Salesforce dates end in "+0000", which is not ISO 8601; add the colon before parsing. */
+function time(date) {
+    return Date.parse(date.replace(/([+-]\d{2})(\d{2})$/, "$1:$2"));
+}