salesforce-reports-mcp 0.0.0-stage → 0.3.0

package/.claude-plugin/marketplace.json

@@ -0,0 +1,13 @@
+{
+  "name": "salesforce-reports",
+  "owner": { "name": "nelsben" },
+  "description": "Salesforce reports for Claude.",
+  "plugins": [
+    {
+      "name": "salesforce-reports",
+      "source": "./",
+      "description": "Explore, design and deploy Salesforce reports with Claude.",
+      "category": "productivity"
+    }
+  ]
+}

package/.claude-plugin/plugin.json

@@ -0,0 +1,17 @@
+{
+  "name": "salesforce-reports",
+  "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",
+  "repository": "https://github.com/nelsben/salesforce-reports-mcp",
+  "license": "MIT",
+  "keywords": ["salesforce", "reports", "mcp", "analytics"],
+  "skills": "./skills",
+  "mcpServers": {
+    "salesforce-reports": {
+      "command": "npx",
+      "args": ["-y", "salesforce-reports-mcp"]
+    }
+  }
+}

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 nelsben
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,178 @@
-# Temporary Holding Version
+# salesforce-reports-mcp
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+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 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:** 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:** $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 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. 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), [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
+
+**The problem.** Reports are how a Salesforce org answers questions, and they are hard to use. A seller wants a number, not Report Builder. An analyst wants to try three versions of a report before saving one. An admin wants a report in another org or in git. As of October 2026, Salesforce's own Claude skills and its standard hosted MCP servers had no report tools, and the closest open-source servers could run or create a report, but none could change, clone or combine one, or run one that was never saved.
+
+**Three experiences.** Each is a Claude skill, and Claude picks the right one from what you say.
+
+| Skill | For | What Claude does |
+| --- | --- | --- |
+| [report-runner](skills/report-runner/SKILL.md) | A seller or manager who wants an answer | Finds the report, says in plain words what it counts, runs it, leads with the answer, offers the next slice. Never saves. |
+| [report-designer](skills/report-designer/SKILL.md) | Someone who wants a report changed or made | Drafts the report in your words, previews it on real data, changes it until you like it, saves it in one step when you ask. |
+| [report-deploy](skills/report-deploy/SKILL.md) | An admin moving a report between orgs or into git | Retrieves the report's metadata, checks it with a dry run, deploys only after you say yes. |
+
+> **You:** Start from my Pipeline by Stage report. Add Next Step and group it by owner, then save it as Pipeline by Owner.
+>
+> **Claude:** Preview, with 8 deals under two owners. Saved as a new report in your Private Reports; the original is untouched. Link.
+
+**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.** 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)).
+
+**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 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
+  subgraph Laptop["Your machine"]
+    CC["Claude Code / Desktop"]
+    LS["Local MCP server<br/>(Node)"]
+    CLI["sf CLI"]
+  end
+  subgraph Cloud["claude.ai"]
+    CAI["Claude"]
+  end
+  subgraph SF["Salesforce org"]
+    GW["Hosted MCP<br/>(Salesforce gateway)"]
+    REST["ReportsApi<br/>(Apex REST)"]
+    CORE["Reports service<br/>(Apex)"]
+    API["Reports REST API"]
+  end
+  CC -- "1. stdio" --> LS -- "REST" --> API
+  CC -- "2. skills + CLI" --> CLI -- "Apex REST" --> REST
+  CAI -- "3. MCP over OAuth" --> GW --> REST
+  REST --> CORE --> API
+```
+
+| | 1. Local MCP server | 2. In-org REST door with skills | 3. Hosted MCP door |
+| --- | --- | --- | --- |
+| **Direction** | Claude reaches into Salesforce | Salesforce offers a feature; Claude calls it | Salesforce serves Claude directly |
+| **Runs** | Node on your machine | Apex in the org | Salesforce's MCP gateway, then the same Apex |
+| **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 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 a numbered sequence diagram for each door, with every step explained.
+
+## A feature inside Salesforce
+
+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 |
+| --- | --- | --- |
+| `force-app` | The Apex service, its tests, two permission sets and a custom permission | Nothing else; complete on its own |
+| `mcp-app` | The API Catalog entry, the MCP server definition and the External Client App Claude signs in through. No code. | `force-app` |
+| `callout-app` | The per-user named credential that lets the hosted door call the org's own API as the user. No code. | `force-app`; used by the hosted door |
+
+The Apex is layered as ports and adapters ([decision 0003](docs/decisions/0003-one-apex-class-behind-both-in-org-doors.md)). One service does the work; the REST class is only an adapter, and [a test](test/apex-layers.test.ts) fails CI if the core ever names it or sets an HTTP status. Reads use `Reports.ReportManager` inside the org; only what Apex cannot do (list report types, run an unsaved report, save) calls the org's own REST API ([decision 0004](docs/decisions/0004-reportmanager-first-callout-for-the-rest.md)). There is no delete in the org ([decision 0006](docs/decisions/0006-no-delete-in-the-org.md)).
+
+## Security and identity
+
+Each door signs in differently, and each is least privilege by default.
+
+| Door | Identity | What it can do |
+| --- | --- | --- |
+| Local | The user's `sf` CLI session, refetched on expiry; never written anywhere | Whatever the user can do. `--read-only` removes every write tool; `delete_report` exists only with `--allow-delete`. |
+| REST | The caller's own Salesforce session | Reads with `Salesforce_Reports`. Saves only with `Salesforce_Reports_Write`, checked in the service, not by hiding tools ([decision 0005](docs/decisions/0005-saves-behind-a-custom-permission.md)). |
+| Hosted MCP | OAuth with PKCE through the External Client App `SalesforceReportsMcp`, scopes `mcp_api` and `refresh_token` only | The same permission sets. For the calls that need the org's REST API, a per-user JWT named credential mints a token for the signed-in user. |
+
+Sharing, folder access and field-level security apply on every door, because every call runs as the user.
+
+**The hard part, and how it was solved.** Under a hosted MCP sign-in, Apex has no session, and asking for one throws an exception no `catch` block can stop. The first version leaked a raw platform error to claude.ai. The fix came in two steps, each with a decision record:
+
+1. The hosted door got its own route, so the code knows which door called before it asks for a session, and answers a clear `CALLOUT_SESSION` instead ([decision 0007](docs/decisions/0007-callout-identity-under-hosted-mcp.md)).
+2. A probe showed that a [per-user JWT named credential](docs/probes/v0.2-phase3c.md) lets the org mint a token for the running user from a certificate it made itself. No secret is stored, no user clicks anything, and the connector's own app keeps its narrow scopes ([decision 0012](docs/decisions/0012-per-user-jwt-named-credential.md)). `npm run callout:renew` renews the certificate.
+
+No token, consumer key, org address or certificate reaches the repo, logs or error messages. The tracked metadata holds placeholders that setup scripts fill at deploy time, and a test enforces it.
+
+## How it was built
+
+The method was the same for every feature: probe the platform, decide in writing, build, then check against a real org.
+
+| Step | What it produced |
+| --- | --- |
+| **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 | 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 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 tools, the result shape, the safety rails and the limits are in [docs/reference.md](docs/reference.md).
+
+## Develop
+
+```
+npm install
+npm run build
+npm test
+npm run test:render                            # draw the report card in Chromium and compare screenshots
+npm run live -- --org <alias> --allow-delete   # end-to-end run against an org you can write to
+npm run capture -- --org <alias>               # refresh the test fixtures (anonymised)
+```
+
+`npm run live` creates several private reports named `zz-live-check-*`, deletes them, and fails if any remain. Use a sandbox or scratch org.
+
+## Roadmap
+
+- Joined reports, report charts, and subscriptions.
+
+## License
+
+MIT.

package/dist/format.js

@@ -0,0 +1,49 @@
+import { CombineError } from "./reports/combine.js";
+import { ConnectionError } from "./salesforce/connection.js";
+import { SalesforceError } from "./salesforce/client.js";
+export function ok(value) {
+    return { content: [{ type: "text", text: JSON.stringify(value) }] };
+}
+/**
+ * ok() for a tool that carries the report view: the same text result, plus the value as
+ * structuredContent for a host that draws MCP Apps. Hosts without UI read the text, as before.
+ */
+export function okView(value) {
+    return { ...ok(value), structuredContent: value };
+}
+export function fail(error) {
+    const body = describeError(error);
+    return { isError: true, content: [{ type: "text", text: JSON.stringify({ error: body }) }] };
+}
+function describeError(error) {
+    if (error instanceof SalesforceError) {
+        return { code: error.code, message: error.message, hint: hintFor(error) };
+    }
+    if (error instanceof ConnectionError) {
+        return { code: "CONNECTION", message: error.message, hint: "Check the --org alias, or log in with `sf org login web`." };
+    }
+    if (error instanceof CombineError || error instanceof InputError) {
+        return { code: "INVALID_INPUT", message: error.message };
+    }
+    return { code: "UNEXPECTED", message: error instanceof Error ? error.message : "Unexpected error." };
+}
+function hintFor(error) {
+    const text = `${error.code} ${error.message}`;
+    if (error.status === 401)
+        return "Log in again with `sf org login web`, or pass a fresh token.";
+    if (error.status === 404 || /NOT_FOUND|INVALID_ID/i.test(error.code)) {
+        return "Check the id with search_reports (reports) or list_report_types (report types).";
+    }
+    if (/column|field|grouping|aggregate|filter|operator/i.test(text)) {
+        return "Check column API names, filter operators and aggregates with describe_report_type, or the report's own columns with describe_report.";
+    }
+    if (/REQUEST_LIMIT_EXCEEDED|limit/i.test(text)) {
+        return "Salesforce allows 500 synchronous report runs per org per hour. Wait, or reduce the number of runs.";
+    }
+    if (/INSUFFICIENT_ACCESS|FORBIDDEN|permission/i.test(text)) {
+        return "The authenticated user lacks access. They need the Run Reports permission, and for saving, Create and Customize Reports.";
+    }
+    return undefined;
+}
+export class InputError extends Error {
+}

package/dist/index.js

@@ -0,0 +1,56 @@
+#!/usr/bin/env node
+import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
+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 { buildServer } from "./server.js";
+const HELP = `salesforce-reports-mcp: an MCP server for Salesforce reports (stdio)
+
+Usage: salesforce-reports-mcp [--org <alias>] [options]
+
+  --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.
+  --api-version <v>    REST API version (env SF_API_VERSION). Default ${DEFAULT_API_VERSION}.
+  --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.
+  -h, --help           Show this help.
+`;
+function flag(value, envName) {
+    return value ?? ["1", "true"].includes((process.env[envName] ?? "").toLowerCase());
+}
+async function main() {
+    const { values } = parseArgs({
+        options: {
+            org: { type: "string" },
+            "api-version": { type: "string" },
+            "read-only": { type: "boolean" },
+            "allow-delete": { type: "boolean" },
+            "max-rows": { type: "string" },
+            help: { type: "boolean", short: "h" },
+        },
+        strict: true,
+    });
+    if (values.help) {
+        process.stderr.write(HELP);
+        return;
+    }
+    const maxRowsRaw = values["max-rows"] ?? process.env.SF_REPORTS_MAX_ROWS;
+    const maxRows = maxRowsRaw ? Number.parseInt(maxRowsRaw, 10) : 200;
+    if (!Number.isInteger(maxRows) || maxRows < 1 || maxRows > 2000) {
+        throw new Error("--max-rows must be a whole number from 1 to 2000.");
+    }
+    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), {
+        readOnly: flag(values["read-only"], "SF_REPORTS_READ_ONLY"),
+        allowDelete: flag(values["allow-delete"], "SF_REPORTS_ALLOW_DELETE"),
+        maxRows,
+    });
+    await server.connect(new StdioServerTransport());
+}
+main().catch((error) => {
+    process.stderr.write(`salesforce-reports-mcp: ${error instanceof Error ? error.message : String(error)}\n`);
+    process.exit(1);
+});

package/dist/reports/api.js

@@ -0,0 +1,105 @@
+import { SalesforceError } from "../salesforce/client.js";
+const enc = encodeURIComponent;
+export function soqlString(value) {
+    return value.replace(/\\/g, "\\\\").replace(/'/g, "\\'");
+}
+/** For a `LIKE` clause: escape the quote and backslash, and the two wildcards. */
+export function soqlLike(value) {
+    return soqlString(value).replace(/([%_])/g, "\\$1");
+}
+export class ReportsApi {
+    api;
+    sleep;
+    constructor(api, sleep = (ms) => new Promise((r) => setTimeout(r, ms))) {
+        this.api = api;
+        this.sleep = sleep;
+    }
+    instanceUrl() {
+        return this.api.instanceUrl();
+    }
+    reportTypes() {
+        return this.api.request("GET", "/analytics/reportTypes");
+    }
+    describeReportType(type) {
+        return this.api.request("GET", `/analytics/reportTypes/${enc(type)}`);
+    }
+    describeReport(id) {
+        return this.api.request("GET", `/analytics/reports/${enc(id)}/describe`);
+    }
+    async run(id, options) {
+        const path = `/analytics/reports/${enc(id)}?includeDetails=${options.includeDetails}`;
+        try {
+            const raw = options.overrides
+                ? await this.api.request("POST", path, { reportMetadata: options.overrides })
+                : await this.api.request("GET", path);
+            return { raw, async: false };
+        }
+        catch (error) {
+            if (!isTimeout(error))
+                throw error;
+            return { raw: await this.runAsync(id, options.overrides), async: true };
+        }
+    }
+    query(metadata, includeDetails) {
+        return this.api.request("POST", `/analytics/reports/query?includeDetails=${includeDetails}`, { reportMetadata: metadata });
+    }
+    create(metadata) {
+        return this.api.request("POST", "/analytics/reports", { reportMetadata: metadata });
+    }
+    patch(id, metadata) {
+        return this.api.request("PATCH", `/analytics/reports/${enc(id)}`, { reportMetadata: metadata });
+    }
+    clone(id, metadata) {
+        return this.api.request("POST", `/analytics/reports?cloneId=${enc(id)}`, { reportMetadata: metadata });
+    }
+    async remove(id) {
+        await this.api.request("DELETE", `/analytics/reports/${enc(id)}`);
+    }
+    async soql(query) {
+        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;
+        if (!instanceId)
+            throw new SalesforceError(500, "NO_INSTANCE", "Salesforce did not return an async report instance.");
+        for (let attempt = 0; attempt < 30; attempt++) {
+            await this.sleep(Math.min(1000 + attempt * 500, 4000));
+            const instance = await this.api.request("GET", `/analytics/reports/${enc(id)}/instances/${enc(instanceId)}`);
+            const status = instance.attributes?.status ?? instance.status;
+            if (status === "Success")
+                return instance;
+            if (status === "Error")
+                throw new SalesforceError(500, "REPORT_RUN_FAILED", "The async report run failed in Salesforce.");
+        }
+        throw new SalesforceError(504, "REPORT_RUN_PENDING", `The async report run (${instanceId}) did not finish in time. Try again, or narrow the filters.`);
+    }
+}
+function isTimeout(error) {
+    if (!(error instanceof SalesforceError))
+        return false;
+    return (error.status === 408 ||
+        error.status === 504 ||
+        /TIMEOUT|TOO_LONG|ASYNC/i.test(error.code) ||
+        /timed out|time out|asynchronous/i.test(error.message));
+}

package/dist/reports/combine.js

@@ -0,0 +1,116 @@
+export class CombineError extends Error {
+}
+export function combineResults(mode, inputs, options = {}) {
+    if (inputs.length < 2 || inputs.length > 5)
+        throw new CombineError("combine_reports takes 2 to 5 inputs.");
+    const aliases = inputs.map((i) => i.alias);
+    if (new Set(aliases).size !== aliases.length)
+        throw new CombineError("Each input needs its own alias.");
+    const base = {
+        report: {
+            id: null,
+            name: `combined: ${aliases.join(", ")}`,
+            format: mode === "join" ? "SUMMARY" : "TABULAR",
+            reportType: "combined",
+        },
+        filters: inputs.flatMap((i) => i.result.filters.map((f) => `${i.alias}: ${f}`)),
+        notes: inputs.flatMap((i) => i.result.notes.map((n) => `${i.alias}: ${n}`)),
+    };
+    const body = mode === "join" ? join(inputs, options.joinOn) : stack(inputs);
+    return { ...base, ...body };
+}
+function stack(inputs) {
+    if (inputs.every((i) => i.result.groups)) {
+        const dims = unionBy(inputs.flatMap((i) => i.result.groups.dimensions), (d) => d.name);
+        const measures = unionBy(inputs.flatMap((i) => i.result.groups.measures), (m) => m.name);
+        const rows = [];
+        for (const { alias, result } of inputs) {
+            const g = result.groups;
+            const dimIdx = g.dimensions.map((d) => d.name);
+            const measureIdx = g.measures.map((m) => m.name);
+            for (const row of g.rows) {
+                rows.push([
+                    alias,
+                    ...dims.map((d) => pick(row, dimIdx.indexOf(d.name))),
+                    ...measures.map((m) => pick(row, measureIdx.indexOf(m.name) < 0 ? -1 : dimIdx.length + measureIdx.indexOf(m.name))),
+                ]);
+            }
+        }
+        return { groups: { dimensions: [{ name: "source", label: "Source", axis: "down" }, ...dims], measures, rows } };
+    }
+    if (inputs.every((i) => i.result.detail)) {
+        const columns = unionBy(inputs.flatMap((i) => i.result.detail.columns), (c) => c.name);
+        const rows = [];
+        for (const { alias, result } of inputs) {
+            const d = result.detail;
+            const idx = d.columns.map((c) => c.name);
+            for (const row of d.rows)
+                rows.push([alias, ...columns.map((c) => pick(row, idx.indexOf(c.name)))]);
+        }
+        const all = [{ name: "source", label: "Source", dataType: "string" }, ...columns];
+        return { detail: { columns: all, rows, rowCount: rows.length, truncated: inputs.some((i) => i.result.detail.truncated) } };
+    }
+    throw new CombineError("To stack, every input must return grouped rows, or every input must return detail rows. Group all of them the same way, or run all of them with detail.");
+}
+function join(inputs, joinOn) {
+    const plans = inputs.map(({ alias, result }) => {
+        const g = result.groups;
+        if (!g)
+            throw new CombineError(`Input "${alias}" has no groupings. Join needs grouped reports; use stack for flat tables.`);
+        const downs = g.dimensions.filter((d) => d.axis === "down");
+        const keys = joinOn ?? (downs[0] ? [downs[0].name] : []);
+        if (!keys.length)
+            throw new CombineError(`Input "${alias}" has no down grouping to join on.`);
+        const idx = keys.map((k) => g.dimensions.findIndex((d) => d.name === k));
+        const missing = keys.filter((_, n) => idx[n] < 0);
+        if (missing.length) {
+            throw new CombineError(`Input "${alias}" is not grouped by ${missing.join(", ")}. It has: ${g.dimensions.map((d) => d.name).join(", ")}.`);
+        }
+        if (g.dimensions.length > keys.length) {
+            throw new CombineError(`Input "${alias}" is grouped by more than the join key (${g.dimensions.map((d) => d.name).join(", ")}). Set joinOn to all of its groupings, or remove the extra groupings.`);
+        }
+        return { alias, g, idx };
+    });
+    const first = plans[0];
+    const keyDims = first.idx.map((i) => ({ ...first.g.dimensions[i], axis: "down" }));
+    const measures = plans.flatMap((p) => p.g.measures.map((m) => ({ name: `${p.alias}:${m.name}`, label: `${p.alias}: ${m.label}`, dataType: m.dataType })));
+    const table = new Map();
+    for (const p of plans) {
+        for (const row of p.g.rows) {
+            const labels = p.idx.map((i) => row[i] ?? null);
+            const key = labels.map((l) => String(l ?? "").trim().toLowerCase()).join("\u0000");
+            let entry = table.get(key);
+            if (!entry) {
+                entry = { labels, values: new Map() };
+                table.set(key, entry);
+            }
+            entry.values.set(p.alias, row.slice(p.g.dimensions.length));
+        }
+    }
+    const rows = [];
+    for (const entry of table.values()) {
+        const out = [...entry.labels];
+        for (const p of plans) {
+            const values = entry.values.get(p.alias);
+            for (let m = 0; m < p.g.measures.length; m++)
+                out.push(values?.[m] ?? null);
+        }
+        rows.push(out);
+    }
+    return { groups: { dimensions: keyDims, measures, rows } };
+}
+function pick(row, index) {
+    return index < 0 ? null : (row[index] ?? null);
+}
+function unionBy(items, key) {
+    const seen = new Set();
+    const out = [];
+    for (const item of items) {
+        const k = key(item);
+        if (!seen.has(k)) {
+            seen.add(k);
+            out.push(item);
+        }
+    }
+    return out;
+}