@devicecloud.dev/dcd 5.8.0 → 5.9.0-beta.1

package/dist/commands/login.js

@@ -18,9 +18,12 @@
  *  5. Meanwhile, the CLI polls POST /cli-login/claim with {state, code_verifier}.
  *     Once the api has the row, it verifies sha256(verifier) === challenge,
  *     deletes the row, and returns the session.
- *  6. CLI fetches /me/orgs with the fresh Bearer token and prompts the user to
- *     pick an org. Org selection lives here, not in the web UI — that way the
- *     CLI login and `dcd switch-org` share one picker.
+ *  6. CLI fetches /me/orgs with the fresh Bearer token and picks the org:
+ *     `--org` if given, else the only one, else a picker that starts on the
+ *     last login's org. Without a TTY nobody can answer the picker, so the
+ *     last login's org is used, or the command fails pointing at `--org`.
+ *     Org selection lives here, not in the web UI — that way the CLI login
+ *     and `dcd switch-org` share one picker.
  *
  * Why PKCE + server rendezvous (instead of a localhost loopback): Safari
  * blocks HTTPS → HTTP fetches to 127.0.0.1 as mixed content, and a loopback
@@ -33,9 +36,11 @@ import { defineCommand } from 'citty';
 import { spawn } from 'node:child_process';
 import { createHash, randomBytes } from 'node:crypto';
 import { ENVIRONMENTS, inferEnvFromApiUrl, resolveFrontendUrl } from '../config/environments.js';
+import { jsonFlag } from '../config/flags/output.flags.js';
+import { canPrompt } from '../utils/ci.js';
 import { CliError, logger } from '../utils/cli.js';
 import { readConfig, writeConfig } from '../utils/config-store.js';
-import { fetchOrgs, pickOrg } from '../utils/orgs.js';
+import { fetchOrgs, selectOrg } from '../utils/orgs.js';
 import { colors } from '../utils/styling.js';
 import { ui } from '../utils/ui.js';
 const LOGIN_TIMEOUT_MS = 10 * 60 * 1000;
@@ -64,11 +69,35 @@ export const loginCommand = defineCommand({
             default: true,
             description: 'Open the login URL in a browser (pass --no-browser to just print it)',
         },
+        org: {
+            type: 'string',
+            description: 'Organization to use, by name or id (skips the picker)',
+        },
+        json: jsonFlag,
     },
     async run({ args }) {
         const apiUrl = args['api-url'].replace(/\/$/, '');
         const frontendOverride = args['frontend-url'];
         const noBrowser = args.browser === false;
+        const json = Boolean(args.json);
+        // citty gives '' for a bare `--org`. Refuse it, and an empty `--org "$ORG"`,
+        // rather than fall back to an org the caller didn't ask for.
+        const requestedOrg = args.org?.trim();
+        if (requestedOrg === '') {
+            throw new CliError('--org needs an organization name or id.');
+        }
+        // Login is interactive, so under --json the human rows and prompts move to
+        // stderr (the user still needs the URL) and stdout gets only the result.
+        const say = (m) => {
+            if (json)
+                process.stderr.write(`${m}\n`);
+            else
+                logger.log(m);
+        };
+        const promptOutput = json ? process.stderr : undefined;
+        // Without a TTY (a script, CI, a shell an agent runs) nobody can answer a
+        // prompt, so each one below falls back to the answer Enter would give.
+        const interactive = canPrompt(promptOutput);
         // If there's an existing stored session, make the user confirm before we
         // overwrite it. Silent clobber is fine for power users but surprising if
         // someone runs `dcd login` by mistake while already authenticated. An
@@ -79,7 +108,12 @@ export const loginCommand = defineCommand({
         if (existing?.session) {
             const now = Math.floor(Date.now() / 1000);
             if (existing.session.expires_at <= now) {
-                logger.log(ui.info(`Your session for ${existing.session.user_email} has expired — signing in again.`));
+                say(ui.info(`Your session for ${existing.session.user_email} has expired — signing in again.`));
+            }
+            else if (!interactive) {
+                // The confirm below defaults to yes. The old session stays until the
+                // new login succeeds, so this replaces nothing if it never completes.
+                say(ui.info(`Already logged in as ${existing.session.user_email} — signing in again.`));
             }
             else {
                 const currentOrg = existing.current_org_name ?? existing.current_org_id;
@@ -88,9 +122,15 @@ export const loginCommand = defineCommand({
                         (currentOrg ? ` (org ${currentOrg})` : '') +
                         `. Sign out and log in again?`,
                     initialValue: true,
+                    output: promptOutput,
                 });
                 if (p.isCancel(ok) || !ok) {
-                    logger.log(ui.info('Keeping existing session.'));
+                    if (json) {
+                        logger.json({ status: 'UNCHANGED', user: existing.session.user_email });
+                    }
+                    else {
+                        logger.log(ui.info('Keeping existing session.'));
+                    }
                     return;
                 }
             }
@@ -102,7 +142,7 @@ export const loginCommand = defineCommand({
         const codeVerifier = base64url(randomBytes(32));
         const codeChallenge = base64url(createHash('sha256').update(codeVerifier, 'ascii').digest());
         const loginUrl = `${frontendUrl}/cli-login?state=${state}&code_challenge=${codeChallenge}`;
-        logger.log(ui.section('Signing in to devicecloud.dev'));
+        say(ui.section('Signing in to devicecloud.dev'));
         const rows = [];
         if (noBrowser) {
             rows.push(ui.note('Open this URL in a browser to finish login:'), colors.highlight(loginUrl));
@@ -117,7 +157,7 @@ export const loginCommand = defineCommand({
             }
         }
         rows.push(ui.note('Waiting for login to complete…'));
-        logger.log(ui.branch(rows));
+        say(ui.branch(rows));
         try {
             const payload = await pollForClaim(apiUrl, state, codeVerifier);
             if (!payload.access_token || typeof payload.access_token !== 'string') {
@@ -146,7 +186,17 @@ export const loginCommand = defineCommand({
                 ].filter(Boolean);
                 throw new CliError(`${err.message} [${parts.join(' | ')}]`);
             }
-            const chosen = await pickOrg(orgs);
+            const { org: chosen, fromLastLogin } = await selectOrg(orgs, {
+                requested: requestedOrg,
+                // Org ids are per environment (dev org 1 isn't prod org 1), so the
+                // last login's org only counts if that login was to this same API.
+                lastOrgId: existing?.api_url === apiUrl ? existing.current_org_id : undefined,
+                interactive,
+                output: promptOutput,
+            });
+            if (fromLastLogin) {
+                say(ui.info(`No terminal to pick an organization in, so using ${chosen.name} from your last login.`));
+            }
             writeConfig({
                 version: 1,
                 env,
@@ -162,6 +212,15 @@ export const loginCommand = defineCommand({
                 current_org_id: chosen.id,
                 current_org_name: chosen.name,
             });
+            if (json) {
+                logger.json({
+                    status: 'SUCCESS',
+                    user: payload.user_email,
+                    org: { id: chosen.id, name: chosen.name },
+                    env,
+                });
+                return;
+            }
             logger.log(ui.success(`Logged in as ${colors.highlight(payload.user_email)}`));
             logger.log(ui.branch([
                 ...ui.fields([['organization', colors.highlight(chosen.name)]]),
@@ -171,7 +230,7 @@ export const loginCommand = defineCommand({
             ]));
         }
         catch (error) {
-            logger.error(error, { exit: 1 });
+            logger.error(error, { exit: 1, json });
         }
     },
 });

package/dist/commands/logout.d.ts

@@ -1,2 +1,7 @@
-export declare const logoutCommand: import("citty").CommandDef<import("citty").ArgsDef>;
+export declare const logoutCommand: import("citty").CommandDef<{
+    readonly json: {
+        readonly type: "boolean";
+        readonly description: "Output the result as a single JSON object on stdout";
+    };
+}>;
 export default logoutCommand;

package/dist/commands/logout.js

@@ -4,6 +4,7 @@
  */
 import { defineCommand } from 'citty';
 import { ENVIRONMENTS } from '../config/environments.js';
+import { jsonFlag } from '../config/flags/output.flags.js';
 import { CliAuthGateway } from '../gateways/cli-auth-gateway.js';
 import { logger } from '../utils/cli.js';
 import { clearConfig, getConfigPath, readConfig } from '../utils/config-store.js';
@@ -14,16 +15,29 @@ export const logoutCommand = defineCommand({
         name: 'logout',
         description: 'Clear the stored devicecloud.dev session',
     },
-    async run() {
+    args: {
+        json: jsonFlag,
+    },
+    async run({ args }) {
+        const json = Boolean(args.json);
         const config = readConfig();
         if (!config?.session) {
-            logger.log(ui.info(`No active session found (${colors.dim(getConfigPath())}).`));
             clearConfig();
+            if (json) {
+                logger.json({ status: 'SUCCESS', loggedOut: false });
+            }
+            else {
+                logger.log(ui.info(`No active session found (${colors.dim(getConfigPath())}).`));
+            }
             return;
         }
         const { anonKey } = ENVIRONMENTS[config.env].supabase;
         await CliAuthGateway.signOut(config.supabase_url, anonKey, config.session);
         clearConfig();
+        if (json) {
+            logger.json({ status: 'SUCCESS', loggedOut: true, user: config.session.user_email });
+            return;
+        }
         logger.log(ui.success(`Logged out ${colors.dim(`(${config.session.user_email})`)}`));
     },
 });

package/dist/commands/status.js

@@ -105,13 +105,12 @@ async function statusMain({ apiKeyFlag, apiUrl, json, name, uploadId, }) {
         if (isClientApiError(lastError)) {
             const errorMessage = lastError?.message || 'Unknown error';
             if (json) {
-                // eslint-disable-next-line no-console
-                console.log(JSON.stringify({
+                logger.json({
                     status: 'FAILED',
                     error: errorMessage,
                     attempts: attemptsMade,
                     tests: [],
-                }, null, 2));
+                });
                 return;
             }
             throw new CliError(errorMessage);
@@ -128,8 +127,7 @@ async function statusMain({ apiKeyFlag, apiUrl, json, name, uploadId, }) {
             errorMessage = `Failed to get status after ${attemptsMade} attempt${attemptsMade > 1 ? 's' : ''}.\n\nInternet connectivity check failed - all test endpoints unreachable:\n${endpointDetails}\n\nPlease verify your network connection and DNS resolution.\nLast API error: ${lastError?.message || 'Unknown error'}`;
         }
         if (json) {
-            // eslint-disable-next-line no-console
-            console.log(JSON.stringify({
+            logger.json({
                 status: 'FAILED',
                 error: errorMessage,
                 attempts: attemptsMade,
@@ -139,7 +137,7 @@ async function statusMain({ apiKeyFlag, apiUrl, json, name, uploadId, }) {
                     message: connectivityCheck.message,
                 },
                 tests: [],
-            }, null, 2));
+            });
             return;
         }
         throw new CliError(errorMessage);
@@ -147,8 +145,7 @@ async function statusMain({ apiKeyFlag, apiUrl, json, name, uploadId, }) {
     try {
         if (json) {
             const { tests, ...rest } = status;
-            // eslint-disable-next-line no-console
-            console.log(JSON.stringify({ ...rest, tests }, null, 2));
+            logger.json({ ...rest, tests });
             return;
         }
         const fields = [];

package/dist/commands/switch-org.d.ts

@@ -8,5 +8,9 @@ export declare const switchOrgCommand: import("citty").CommandDef<{
         readonly required: false;
         readonly description: "Org name to switch to (omit for an interactive picker)";
     };
+    readonly json: {
+        readonly type: "boolean";
+        readonly description: "Output the result as a single JSON object on stdout";
+    };
 }>;
 export default switchOrgCommand;

package/dist/commands/switch-org.js

@@ -3,13 +3,16 @@
  *
  * With an argument (`dcd switch-org <name>`): update config immediately after
  * confirming the user is a member via GET /me/orgs.
- * Without an argument: fetch orgs and prompt the user to pick one.
+ * Without an argument: fetch orgs and prompt the user to pick one (an error
+ * instead when there's no TTY to answer the prompt).
  */
 import { defineCommand } from 'citty';
+import { jsonFlag } from '../config/flags/output.flags.js';
 import { apiKeyOverride, resolveAuth } from '../utils/auth.js';
+import { canPrompt } from '../utils/ci.js';
 import { CliError, logger } from '../utils/cli.js';
 import { readConfig, resolveApiUrl, writeConfig } from '../utils/config-store.js';
-import { fetchOrgs, pickOrg } from '../utils/orgs.js';
+import { fetchOrgs, matchOrg, pickOrg } from '../utils/orgs.js';
 import { colors } from '../utils/styling.js';
 import { ui } from '../utils/ui.js';
 export const switchOrgCommand = defineCommand({
@@ -27,6 +30,7 @@ export const switchOrgCommand = defineCommand({
             required: false,
             description: 'Org name to switch to (omit for an interactive picker)',
         },
+        json: jsonFlag,
     },
     async run({ args }) {
         const config = readConfig();
@@ -37,44 +41,43 @@ export const switchOrgCommand = defineCommand({
         // a dev Bearer token to the prod API.
         const apiUrl = resolveApiUrl(args['api-url']);
         const target = args.org;
+        const json = Boolean(args.json);
         // sessionOnly: an exported DEVICE_CLOUD_API_KEY must not shadow the
         // browser session this command requires.
         const auth = await resolveAuth({ apiKeyFlag: undefined, sessionOnly: true });
         const orgs = await fetchOrgs(apiUrl, auth.headers);
         let chosen;
         if (target) {
-            chosen = matchOrg(orgs, target);
+            chosen = matchOrg(orgs, target, '`dcd switch-org` without arguments');
         }
         else {
-            chosen = await pickOrg(orgs);
+            // Under --json the picker draws on stderr so stdout stays pure JSON.
+            const output = json ? process.stderr : undefined;
+            // Without a TTY the picker would wait forever for a keypress.
+            if (orgs.length > 1 && !canPrompt(output)) {
+                throw new CliError(`There's no terminal to pick an organization in. Run \`dcd switch-org <name>\` with one of: ${orgs.map((o) => o.name).join(', ')}`);
+            }
+            chosen = await pickOrg(orgs, { output });
         }
         writeConfig({
             ...config,
             current_org_id: chosen.id,
             current_org_name: chosen.name,
         });
-        logger.log(ui.success(`Switched to ${colors.highlight(chosen.name)}`));
         // The switch only changes the stored session; an exported key still wins.
-        if (apiKeyOverride() === 'DEVICE_CLOUD_API_KEY') {
+        const keyOverride = apiKeyOverride() === 'DEVICE_CLOUD_API_KEY';
+        if (json) {
+            logger.json({
+                status: 'SUCCESS',
+                org: { id: chosen.id, name: chosen.name, slug: chosen.slug ?? null },
+                apiKeyOverride: keyOverride,
+            });
+            return;
+        }
+        logger.log(ui.success(`Switched to ${colors.highlight(chosen.name)}`));
+        if (keyOverride) {
             logger.log(ui.warn(`${colors.highlight('DEVICE_CLOUD_API_KEY')} is set, so other dcd commands still authenticate with that API key and its org, not ${chosen.name}. Unset it to use the session.`));
         }
     },
 });
-/**
- * Match a user-supplied string to an org. Prefers case-insensitive name match.
- * Falls back to slug / id so existing scripts keep working, but error output
- * only surfaces names.
- */
-function matchOrg(orgs, target) {
-    const needle = target.toLowerCase();
-    const nameMatches = orgs.filter((o) => o.name.toLowerCase() === needle);
-    if (nameMatches.length > 1) {
-        throw new CliError(`Multiple orgs named "${target}". Run \`dcd switch-org\` without arguments to pick interactively.`);
-    }
-    const chosen = nameMatches[0] ?? orgs.find((o) => o.slug === target || o.id === target);
-    if (!chosen) {
-        throw new CliError(`No org named "${target}". Available: ${orgs.map((o) => o.name).join(', ')}`);
-    }
-    return chosen;
-}
 export default switchOrgCommand;

package/dist/commands/upgrade.d.ts

@@ -1,2 +1,7 @@
-export declare const upgradeCommand: import("citty").CommandDef<import("citty").ArgsDef>;
+export declare const upgradeCommand: import("citty").CommandDef<{
+    readonly json: {
+        readonly type: "boolean";
+        readonly description: "Output the result as a single JSON object on stdout";
+    };
+}>;
 export default upgradeCommand;

package/dist/commands/upgrade.js

@@ -12,6 +12,7 @@ import { chmodSync, createReadStream, createWriteStream, renameSync, unlinkSync,
 import { Readable } from 'node:stream';
 import { pipeline } from 'node:stream/promises';
 import { defineCommand } from 'citty';
+import { jsonFlag } from '../config/flags/output.flags.js';
 import { VersionService } from '../services/version.service.js';
 import { CliError, getCliVersion, getInstallMethod, logger, } from '../utils/cli.js';
 import { colors } from '../utils/styling.js';
@@ -31,7 +32,15 @@ export const upgradeCommand = defineCommand({
         name: 'upgrade',
         description: 'Upgrade dcd in place to the latest released version',
     },
-    async run() {
+    args: {
+        json: jsonFlag,
+    },
+    async run({ args }) {
+        const json = Boolean(args.json);
+        const out = (m) => {
+            if (!json)
+                logger.log(m);
+        };
         if (getInstallMethod() !== 'binary') {
             throw new CliError('`dcd upgrade` only applies to the standalone binary install. ' +
                 'Run: npm install -g @devicecloud.dev/dcd@latest');
@@ -45,11 +54,19 @@ export const upgradeCommand = defineCommand({
         // Reachable, but nothing published on this channel yet (e.g. a stable
         // install while only betas exist). Not an error — just nothing to do.
         if (result.version === null) {
+            if (json) {
+                logger.json({ status: 'NO_RELEASE', current, channel: result.channel });
+                return;
+            }
             logger.log(ui.info(`No newer release available on the ${result.channel} channel.`));
             return;
         }
         const latest = result.version;
         if (!versionService.isOutdated(current, latest)) {
+            if (json) {
+                logger.json({ status: 'UP_TO_DATE', current, latest, channel: result.channel });
+                return;
+            }
             logger.log(ui.success(`Already on the latest version (${colors.highlight(current)})`));
             return;
         }
@@ -69,8 +86,8 @@ export const upgradeCommand = defineCommand({
         const base = process.env.DCD_DOWNLOAD_BASE ?? DEFAULT_DOWNLOAD_BASE;
         const binaryUrl = `${base}/download/${latest}/${asset}`;
         const sumsUrl = `${base}/download/${latest}/SHA256SUMS`;
-        logger.log(ui.info(`Upgrading ${colors.highlight(current)} → ${colors.highlight(latest)}`));
-        logger.log(ui.note(`  ${binaryUrl}`));
+        out(ui.info(`Upgrading ${colors.highlight(current)} → ${colors.highlight(latest)}`));
+        out(ui.note(`  ${binaryUrl}`));
         const execPath = process.execPath;
         const tmpPath = `${execPath}.new`;
         try {
@@ -89,6 +106,10 @@ export const upgradeCommand = defineCommand({
             safeUnlink(tmpPath);
             throw new CliError(`Upgrade failed: ${e.message}. The existing binary at ${execPath} was not modified.`);
         }
+        if (json) {
+            logger.json({ status: 'UPGRADED', current, latest, channel: result.channel });
+            return;
+        }
         logger.log(ui.success(`Upgraded to ${colors.highlight(latest)}`));
     },
 });

package/dist/commands/upload.js

@@ -116,8 +116,7 @@ export const uploadCommand = defineCommand({
             });
             telemetry.recordEncryption({ binary: encryption.enabled });
             if (json) {
-                // eslint-disable-next-line no-console
-                console.log(JSON.stringify({ appBinaryId }, null, 2));
+                logger.json({ appBinaryId });
                 return;
             }
             logger.log(`\n${ui.success('Upload complete')}`);

package/dist/commands/whoami.d.ts

@@ -4,5 +4,9 @@ export declare const whoamiCommand: import("citty").CommandDef<{
         readonly type: "string";
         readonly alias: ["apiKey"];
     };
+    readonly json: {
+        readonly type: "boolean";
+        readonly description: "Output the result as a single JSON object on stdout";
+    };
 }>;
 export default whoamiCommand;

package/dist/commands/whoami.js

@@ -7,6 +7,7 @@
  */
 import { defineCommand } from 'citty';
 import { apiFlags } from '../config/flags/api.flags.js';
+import { jsonFlag } from '../config/flags/output.flags.js';
 import { apiKeyOverride } from '../utils/auth.js';
 import { logger } from '../utils/cli.js';
 import { readConfig } from '../utils/config-store.js';
@@ -22,10 +23,26 @@ export const whoamiCommand = defineCommand({
             ...apiFlags['api-key'],
             description: 'An API key as you would pass it to other commands; whoami says that it takes precedence over the stored session',
         },
+        json: jsonFlag,
     },
     run({ args }) {
         const config = readConfig();
         const keySource = apiKeyOverride(args['api-key']);
+        if (args.json) {
+            logger.json({
+                status: 'SUCCESS',
+                loggedIn: Boolean(config?.session),
+                ...(config?.session && {
+                    user: config.session.user_email,
+                    org: config.current_org_id
+                        ? { id: config.current_org_id, name: config.current_org_name ?? null }
+                        : null,
+                    env: config.env,
+                }),
+                apiKeySource: keySource ?? null,
+            });
+            return;
+        }
         const keyName = colors.highlight(keySource ?? '');
         if (!config?.session) {
             logger.log(ui.info(keySource === 'DEVICE_CLOUD_API_KEY'

package/dist/config/flags/output.flags.d.ts

@@ -1,3 +1,11 @@
+/**
+ * Generic `--json` flag for commands outside `cloud`. With it, stdout carries
+ * exactly one JSON object; failures print `{ status: 'FAILED', error }`.
+ */
+export declare const jsonFlag: {
+    readonly type: "boolean";
+    readonly description: "Output the result as a single JSON object on stdout";
+};
 /**
  * Output format and artifact download flags
  */

package/dist/config/flags/output.flags.js

@@ -1,3 +1,11 @@
+/**
+ * Generic `--json` flag for commands outside `cloud`. With it, stdout carries
+ * exactly one JSON object; failures print `{ status: 'FAILED', error }`.
+ */
+export const jsonFlag = {
+    type: 'boolean',
+    description: 'Output the result as a single JSON object on stdout',
+};
 /**
  * Output format and artifact download flags
  */

package/dist/index.js

@@ -13,7 +13,7 @@ import { upgradeCommand } from './commands/upgrade.js';
 import { uploadCommand } from './commands/upload.js';
 import { whoamiCommand } from './commands/whoami.js';
 import { telemetry } from './services/telemetry.service.js';
-import { CliError, getCliVersion, logger } from './utils/cli.js';
+import { CliError, getCliVersion, logger, wantsJson } from './utils/cli.js';
 import { withoutHiddenArgs } from './utils/help.js';
 // @clack/prompts ships the US spelling ("Canceled") for its built-in
 // spinner/prompt cancellation message; align it with the British spelling
@@ -88,9 +88,12 @@ async function run() {
         await telemetry.flush();
     }
     catch (error) {
+        // Under --json, stdout must stay a single JSON object: no help text, and
+        // the error itself is printed as `{ status: 'FAILED', error }`.
+        const json = wantsJson(rawArgs);
         // citty throws CLIError (by name — the class isn't exported) for usage
         // problems like unknown commands or missing required args.
-        if (error instanceof Error && error.name === 'CLIError') {
+        if (!json && error instanceof Error && error.name === 'CLIError') {
             await showHelp(rawArgs);
         }
         const exitCode = error instanceof CliError ? error.exitCode : 1;
@@ -98,6 +101,7 @@ async function run() {
         // synchronously, and exits with the given code.
         logger.error(error instanceof Error ? error : String(error), {
             exit: exitCode,
+            json,
         });
     }
 }

package/dist/services/report-download.service.d.ts

@@ -17,6 +17,13 @@ export interface ReportDownloadOptions extends DownloadOptions {
     junitPath?: string;
     reportType: 'allure' | 'html' | 'html-detailed' | 'junit';
 }
+/** What one download attempt did; failures are warned about, not thrown. */
+export interface DownloadResult {
+    error?: string;
+    ok: boolean;
+    path: string;
+    type: 'allure' | 'artifacts' | 'html' | 'junit';
+}
 /**
  * Service for downloading test artifacts and reports
  */
@@ -24,21 +31,21 @@ export declare class ReportDownloadService {
     /**
      * Download test artifacts as a zip file
      * @param options Download configuration
-     * @returns Promise that resolves when download is complete
+     * @returns What the download did
      */
-    downloadArtifacts(options: ArtifactsDownloadOptions): Promise<void>;
+    downloadArtifacts(options: ArtifactsDownloadOptions): Promise<DownloadResult>;
     /**
      * Handle downloading reports based on the report type specified
      * @param options Report download configuration
-     * @returns Promise that resolves when download is complete
+     * @returns What the download did, or undefined for an unknown report type
      */
-    downloadReports(options: ReportDownloadOptions): Promise<void>;
+    downloadReports(options: ReportDownloadOptions): Promise<DownloadResult | undefined>;
     /**
      * Download a specific report type
      * @param type Report type to download
      * @param filePath Path where report should be saved
      * @param options Download configuration
-     * @returns Promise that resolves when download is complete
+     * @returns What the download did
      */
     private downloadReport;
     /**