miro-export 1.1.1 → 1.3.0

package/.github/workflows/build.yml

@@ -8,11 +8,11 @@ jobs:
   build:
     runs-on: ubuntu-latest
     steps:
-      - uses: actions/checkout@v4
-      - uses: pnpm/action-setup@v3
+      - uses: actions/checkout@v6
+      - uses: pnpm/action-setup@v4
         with:
           version: 8
-      - uses: actions/setup-node@v4
+      - uses: actions/setup-node@v6
         with:
           node-version: "22.x"
       - name: Install dependencies
@@ -22,7 +22,7 @@ jobs:
       - name: Build
         run: pnpm run build
       - name: Upload Artifact
-        uses: actions/upload-artifact@v4
+        uses: actions/upload-artifact@v6
         with:
           name: build
           path: build/

package/.github/workflows/publish.yml

@@ -8,11 +8,11 @@ jobs:
   publish:
     runs-on: ubuntu-latest
     steps:
-      - uses: actions/checkout@v4
-      - uses: pnpm/action-setup@v3
+      - uses: actions/checkout@v6
+      - uses: pnpm/action-setup@v4
         with:
           version: 8
-      - uses: actions/setup-node@v4
+      - uses: actions/setup-node@v6
         with:
           node-version: "22.x"
           registry-url: "https://registry.npmjs.org"

package/.github/workflows/test.yml

@@ -6,13 +6,13 @@ on:
 
 jobs:
   test:
-    runs-on: ubuntu-latest
+    runs-on: ubuntu-22.04
     steps:
-      - uses: actions/checkout@v4
-      - uses: pnpm/action-setup@v3
+      - uses: actions/checkout@v6
+      - uses: pnpm/action-setup@v4
         with:
           version: 8
-      - uses: actions/setup-node@v4
+      - uses: actions/setup-node@v6
         with:
           node-version: "22.x"
       - name: Install dependencies
@@ -21,3 +21,5 @@ jobs:
         run: pnpm run test
         env:
           TEST_BOARD_ID: ${{secrets.TEST_BOARD_ID}}
+          PRIVATE_TEST_BOARD_ID: ${{secrets.PRIVATE_TEST_BOARD_ID}}
+          BUGGY_TEST_BOARD_ID: ${{secrets.BUGGY_TEST_BOARD_ID}}

package/README.md

@@ -30,8 +30,9 @@ Options:
   -t, --token <token>                Miro token
   -b, --board-id <boardId>           The board ID
   -f, --frame-names <frameNames...>  The frame name(s), leave empty to export entire board
-  -o, --output-file <filename>       A file to output the SVG to (stdout if not supplied)
-  -e, --export-format <format>       'svg' or 'json' (default: 'svg')
+  -o, --output-file <filename>       A file to output the SVG to (stdout if not specified)
+  -e, --export-format <format>       'svg' or 'json' (default: "svg")
+  -l, --load-timeout <milliseconds>  Timeout for loading the board in milliseconds (default: 15000)
   -h, --help                         display help for command
 ```
 
@@ -116,7 +117,7 @@ const svgOfFrame1 = await miroBoard.getSvg([framesWithTitleFrame1[0].id]);
 > [!WARNING]  
 > Remember to dispose the instance to make sure the browser is closed and the process
 > can exit. `await using` (as shown above) does this automatically, but is not supported
-> in all environments and may not be the optimal choise in every case. Alternatively,
+> in all environments and may not be the optimal choice in every case. Alternatively,
 > `miroBoard.dispose()` may be called at any time to dispose of the instance manually.
 
 Types for many of the common board object types has been provided in [miro-types.ts](src/miro-types.ts).

package/build/cli.js

@@ -54,69 +54,85 @@ var __disposeResources = (this && this.__disposeResources) || (function (Suppres
 import { writeFile } from "fs/promises";
 import { program } from "@commander-js/extra-typings";
 import { MiroBoard } from "./index.js";
-const { token, boardId, frameNames, outputFile, exportFormat } = program
+const { token, boardId, frameNames, outputFile, exportFormat, loadTimeout } = program
     .option("-t, --token <token>", "Miro token")
     .requiredOption("-b, --board-id <boardId>", "The board ID")
     .option("-f, --frame-names <frameNames...>", "The frame name(s), leave empty to export entire board")
-    .option("-o, --output-file <filename>", "A file to output the SVG to (stdout if not supplied)")
-    .option("-e, --export-format <format>", "'svg' or 'json' (default: 'svg')")
+    .option("-o, --output-file <filename>", "A file to output the SVG to (stdout if not specified)")
+    .option("-e, --export-format <format>", "'svg' or 'json'", "svg")
+    .option("-l, --load-timeout <milliseconds>", "Timeout for loading the board in milliseconds", (arg) => parseInt(arg, 10), 15000)
     .parse()
     .opts();
 (async () => {
-    const env_1 = { stack: [], error: void 0, hasError: false };
     try {
-        const miroBoard = __addDisposableResource(env_1, new MiroBoard({ token, boardId }), true);
-        async function getFrames(frameNames) {
-            const frames = await miroBoard.getBoardObjects({ type: "frame" }, { title: frameNames });
-            if (frames && frames.length !== frameNames.length) {
-                throw Error(`${frameNames.length - frames.length} frame(s) could not be found on the board.`);
+        const env_1 = { stack: [], error: void 0, hasError: false };
+        try {
+            const miroBoard = __addDisposableResource(env_1, new MiroBoard({
+                token,
+                boardId,
+                boardLoadTimeoutMs: loadTimeout
+            }), true);
+            async function getFrames(frameNames) {
+                const frames = await miroBoard.getBoardObjects({ type: "frame" }, { title: frameNames });
+                if (frames && frames.length !== frameNames.length) {
+                    throw Error(`${frameNames.length - frames.length} frame(s) could not be found on the board.`);
+                }
+                return frames;
             }
-            return frames;
-        }
-        async function getSvg(frames) {
-            return await miroBoard.getSvg(frames?.map(({ id }) => id).filter((id) => !!id));
-        }
-        async function getJson(frames) {
-            if (frames) {
-                const frameChildren = await miroBoard.getBoardObjects({
-                    id: frames.flatMap((frame) => frame.childrenIds)
-                });
-                const groupChildren = await miroBoard.getBoardObjects({
-                    id: frameChildren
-                        .filter((child) => child.type === "group")
-                        .flatMap((child) => child.itemsIds)
-                });
-                return JSON.stringify([...frames, ...frameChildren, ...groupChildren]);
+            async function getSvg(frames) {
+                return await miroBoard.getSvg(frames?.map(({ id }) => id).filter((id) => !!id));
             }
-            return JSON.stringify(await miroBoard.getBoardObjects({}));
-        }
-        const getFn = exportFormat === "json" ? getJson : getSvg;
-        if (outputFile?.includes("{frameName}")) {
-            if (!frameNames) {
-                throw Error("Expected frame names to be given when the output file name format expects a frame name.");
-            }
-            for (const frameName of frameNames) {
-                const output = await getFn(await getFrames([frameName]));
-                await writeFile(outputFile.replace("{frameName}", frameName), output);
+            async function getJson(frames) {
+                if (frames) {
+                    const frameChildren = await miroBoard.getBoardObjects({
+                        id: frames.flatMap((frame) => frame.childrenIds)
+                    });
+                    const groupChildren = await miroBoard.getBoardObjects({
+                        id: frameChildren
+                            .filter((child) => child.type === "group")
+                            .flatMap((child) => child.itemsIds)
+                    });
+                    return JSON.stringify([...frames, ...frameChildren, ...groupChildren]);
+                }
+                return JSON.stringify(await miroBoard.getBoardObjects({}));
             }
-        }
-        else {
-            const svg = await getFn(frameNames && (await getFrames(frameNames)));
-            if (outputFile) {
-                await writeFile(outputFile, svg);
+            const getFn = exportFormat === "json" ? getJson : getSvg;
+            if (outputFile?.includes("{frameName}")) {
+                if (!frameNames) {
+                    throw Error("Expected frame names to be given when the output file name format expects a frame name.");
+                }
+                for (const frameName of frameNames) {
+                    const output = await getFn(await getFrames([frameName]));
+                    await writeFile(outputFile.replace("{frameName}", frameName), output);
+                }
             }
             else {
-                process.stdout.write(svg);
+                const svg = await getFn(frameNames && (await getFrames(frameNames)));
+                if (outputFile) {
+                    await writeFile(outputFile, svg);
+                }
+                else {
+                    process.stdout.write(svg);
+                }
             }
         }
+        catch (e_1) {
+            env_1.error = e_1;
+            env_1.hasError = true;
+        }
+        finally {
+            const result_1 = __disposeResources(env_1);
+            if (result_1)
+                await result_1;
+        }
     }
-    catch (e_1) {
-        env_1.error = e_1;
-        env_1.hasError = true;
-    }
-    finally {
-        const result_1 = __disposeResources(env_1);
-        if (result_1)
-            await result_1;
+    catch (err) {
+        const RED = "\x1b[31m";
+        const RESET = "\x1b[0m";
+        const GRAY = "\x1b[38;5;248m";
+        console.error(`❌ ${RED}Error:${RESET} ${err instanceof Error ? err.message : err}`);
+        console.error(GRAY);
+        console.error(err);
+        console.error(RESET);
     }
 })();

package/build/index.d.ts

@@ -1,8 +1,27 @@
+import { type LaunchOptions } from "puppeteer";
 import type { BoardObject } from "./miro-types.ts";
 import type { GetBoardsFilter } from "./miro-runtime.ts";
 interface InitialMiroBoardOptions {
+    /**
+     * The Miro authentication token with access to load the board.
+     * Optional if anonymous users may access the board without
+     * logging in.
+     */
     token?: string;
+    /**
+     * The Miro board ID.
+     */
     boardId: string;
+    /**
+     * Optional custom Puppeteer launch options.
+     */
+    puppeteerOptions?: LaunchOptions;
+    /**
+     * Timeout until it is determined that the Miro board could
+     * not be loaded for some reason, in milliseconds. Default
+     * is 15 seconds (15,000 milliseconds).
+     */
+    boardLoadTimeoutMs?: number;
 }
 type AdditionalFilter<T> = Partial<T> | Partial<{
     [K in keyof T]: T[K][];
@@ -12,12 +31,19 @@ type FilteredResultsByType<F extends string | string[] | undefined, T> = F exten
 }>[] : T[];
 export declare class MiroBoard {
     private context;
+    private isDisposed;
     constructor(options: InitialMiroBoardOptions);
     private initialize;
     dispose(): Promise<void>;
     [Symbol.asyncDispose](): Promise<void>;
     private get browser();
     private get page();
+    /**
+     * Checks that all widgets have been loaded. Times out to 5 seconds due to bug
+     * in Miro where certain boards fail to load all widgets if SDK is not required
+     * for this function call.
+     */
+    private checkAllWidgetsLoaded;
     getBoardObjects<F extends GetBoardsFilter>(filter: F, additionalFilter?: AdditionalFilter<BoardObject>): Promise<FilteredResultsByType<F["type"], BoardObject>>;
     getSvg(objectsIds?: string[]): Promise<string>;
 }

package/build/index.js

@@ -1,11 +1,16 @@
 import puppeteer, { Browser, Page } from "puppeteer";
+const DEFAULT_BOARD_LOAD_TIMEOUT_MS = 15_000;
 export class MiroBoard {
     context = Promise.withResolvers();
+    isDisposed = false;
     constructor(options) {
         this.initialize(options);
     }
     async initialize(options) {
-        const browser = await puppeteer.launch({ headless: true });
+        const browser = await puppeteer.launch({
+            headless: true,
+            ...(options.puppeteerOptions ?? {})
+        });
         const page = await browser.newPage();
         if (options.token) {
             await browser.browserContexts()[0].setCookie({
@@ -23,24 +28,41 @@ export class MiroBoard {
         await page.goto(`https://miro.com/app/board/${options.boardId}/`, {
             waitUntil: "domcontentloaded"
         });
-        await page.evaluate(() => new Promise((resolve) => {
-            if (window.miro) {
-                resolve();
-            }
-            let miroValue;
-            Object.defineProperty(window, "miro", {
-                get() {
-                    return miroValue;
-                },
-                set(value) {
-                    miroValue = value;
+        try {
+            await page.evaluate((timeoutDuration) => new Promise((resolve, reject) => {
+                if (window.cmd?.board?.api) {
                     resolve();
                 }
-            });
-        }));
+                const timeout = setTimeout(() => {
+                    reject(new Error(`Miro board could not be loaded: application instance not available after ${timeoutDuration} ms. Check your network connection, access token and board access.`));
+                }, timeoutDuration);
+                const interval = setInterval(() => {
+                    if (document.querySelector('[data-testid="signup-popup-container"]')) {
+                        clearInterval(interval);
+                        clearTimeout(timeout);
+                        reject(new Error(`Miro board requires authentication. Check board access settings to allow anonymous access or supply a token.`));
+                    }
+                    else if (window.cmd?.board?.api) {
+                        clearTimeout(timeout);
+                        clearInterval(interval);
+                        resolve();
+                    }
+                }, 250);
+            }), options.boardLoadTimeoutMs ?? DEFAULT_BOARD_LOAD_TIMEOUT_MS);
+        }
+        catch (err) {
+            await browser.close();
+            this.context.reject(err);
+            this.isDisposed = true;
+            return;
+        }
         this.context.resolve({ browser, page });
     }
     async dispose() {
+        if (this.isDisposed) {
+            return;
+        }
+        this.isDisposed = true;
         await (await this.browser).close();
     }
     async [Symbol.asyncDispose]() {
@@ -52,7 +74,34 @@ export class MiroBoard {
     get page() {
         return this.context.promise.then(({ page }) => page);
     }
+    /**
+     * Checks that all widgets have been loaded. Times out to 5 seconds due to bug
+     * in Miro where certain boards fail to load all widgets if SDK is not required
+     * for this function call.
+     */
+    async checkAllWidgetsLoaded(mustHaveSdk = false) {
+        await (await this.page).evaluate((mustHaveSdk, timeoutDuration) => new Promise((resolve, reject) => {
+            const startTime = Date.now();
+            const interval = setInterval(() => {
+                if (window.cmd?.board?.api?.isAllWidgetsLoaded() &&
+                    (!mustHaveSdk || window.miro)) {
+                    clearInterval(interval);
+                    resolve();
+                }
+                if (Date.now() - startTime >= timeoutDuration) {
+                    clearInterval(interval);
+                    if (mustHaveSdk) {
+                        reject(new Error(`Miro SDK failed to load in ${timeoutDuration} ms. This is likely caused by a Miro-internal issue. Check that the board is accessible using an incognito browser window.`));
+                    }
+                    else {
+                        resolve();
+                    }
+                }
+            }, 150);
+        }), mustHaveSdk, 3_000);
+    }
     async getBoardObjects(filter, additionalFilter) {
+        await this.checkAllWidgetsLoaded(true);
         return (await this.page).evaluate(async (filter, additionalFilter) => {
             // @ts-expect-error - https://github.com/evanw/esbuild/issues/2605#issuecomment-2050808084
             window.__name = (func) => func;
@@ -81,8 +130,9 @@ export class MiroBoard {
         }, filter, additionalFilter);
     }
     async getSvg(objectsIds) {
+        await this.checkAllWidgetsLoaded(objectsIds !== undefined);
         return (await this.page).evaluate(async (objectsIds) => {
-            await window.miro.board.deselect();
+            window.cmd.board.api.clearSelection();
             if (objectsIds) {
                 for (const id of objectsIds) {
                     await window.miro.board.select({ id });

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "miro-export",
-  "version": "1.1.1",
+  "version": "1.3.0",
   "author": "jolle <npm-contact@jolle.io>",
   "license": "MIT",
   "type": "module",
@@ -23,25 +23,25 @@
     "miro-export": "./build/cli.js"
   },
   "devDependencies": {
-    "@eslint/eslintrc": "^3.2.0",
-    "@eslint/js": "^9.17.0",
-    "@stylistic/eslint-plugin-ts": "^2.12.1",
-    "@types/node": "^22.10.2",
+    "@eslint/eslintrc": "^3.3.3",
+    "@eslint/js": "^9.39.2",
+    "@stylistic/eslint-plugin-ts": "^4.4.1",
+    "@types/node": "^25.0.3",
     "ajv": "^8.17.1",
-    "eslint": "^9.17.0",
-    "eslint-config-prettier": "^9.1.0",
-    "eslint-plugin-prettier": "^5.2.1",
+    "eslint": "^9.39.2",
+    "eslint-config-prettier": "^10.1.8",
+    "eslint-plugin-prettier": "^5.5.4",
     "eslint-plugin-promise": "^7.2.1",
-    "prettier": "^3.4.2",
-    "ts-json-schema-generator": "^2.3.0",
-    "tsx": "^4.19.2",
-    "typescript": "^5.7.2",
-    "typescript-eslint": "^8.18.1"
+    "prettier": "^3.7.4",
+    "ts-json-schema-generator": "^2.4.0",
+    "tsx": "^4.21.0",
+    "typescript": "^5.9.3",
+    "typescript-eslint": "^8.50.1"
   },
   "dependencies": {
-    "@commander-js/extra-typings": "^12.1.0",
-    "commander": "^12.1.0",
-    "puppeteer": "^23.11.1"
+    "@commander-js/extra-typings": "^14.0.0",
+    "commander": "^14.0.2",
+    "puppeteer": "^24.34.0"
   },
   "engines": {
     "node": ">=22.0.0"

package/src/cli.ts

@@ -3,84 +3,107 @@ import { program } from "@commander-js/extra-typings";
 import { MiroBoard } from "./index.js";
 import type { FrameBoardObject } from "./miro-types.ts";
 
-const { token, boardId, frameNames, outputFile, exportFormat } = program
-  .option("-t, --token <token>", "Miro token")
-  .requiredOption("-b, --board-id <boardId>", "The board ID")
-  .option(
-    "-f, --frame-names <frameNames...>",
-    "The frame name(s), leave empty to export entire board"
-  )
-  .option(
-    "-o, --output-file <filename>",
-    "A file to output the SVG to (stdout if not supplied)"
-  )
-  .option("-e, --export-format <format>", "'svg' or 'json' (default: 'svg')")
-  .parse()
-  .opts();
+const { token, boardId, frameNames, outputFile, exportFormat, loadTimeout } =
+  program
+    .option("-t, --token <token>", "Miro token")
+    .requiredOption("-b, --board-id <boardId>", "The board ID")
+    .option(
+      "-f, --frame-names <frameNames...>",
+      "The frame name(s), leave empty to export entire board"
+    )
+    .option(
+      "-o, --output-file <filename>",
+      "A file to output the SVG to (stdout if not specified)"
+    )
+    .option("-e, --export-format <format>", "'svg' or 'json'", "svg")
+    .option(
+      "-l, --load-timeout <milliseconds>",
+      "Timeout for loading the board in milliseconds",
+      (arg) => parseInt(arg, 10),
+      15000
+    )
+    .parse()
+    .opts();
 
 (async () => {
-  await using miroBoard = new MiroBoard({ token, boardId });
+  try {
+    await using miroBoard = new MiroBoard({
+      token,
+      boardId,
+      boardLoadTimeoutMs: loadTimeout
+    });
 
-  async function getFrames(frameNames: string[]) {
-    const frames = await miroBoard.getBoardObjects(
-      { type: "frame" as const },
-      { title: frameNames }
-    );
+    async function getFrames(frameNames: string[]) {
+      const frames = await miroBoard.getBoardObjects(
+        { type: "frame" as const },
+        { title: frameNames }
+      );
+
+      if (frames && frames.length !== frameNames.length) {
+        throw Error(
+          `${
+            frameNames.length - frames.length
+          } frame(s) could not be found on the board.`
+        );
+      }
+
+      return frames;
+    }
 
-    if (frames && frames.length !== frameNames.length) {
-      throw Error(
-        `${
-          frameNames.length - frames.length
-        } frame(s) could not be found on the board.`
+    async function getSvg(frames?: FrameBoardObject[]) {
+      return await miroBoard.getSvg(
+        frames?.map(({ id }) => id).filter((id): id is string => !!id)
       );
     }
 
-    return frames;
-  }
+    async function getJson(frames?: FrameBoardObject[]) {
+      if (frames) {
+        const frameChildren = await miroBoard.getBoardObjects({
+          id: frames.flatMap((frame) => frame.childrenIds)
+        });
 
-  async function getSvg(frames?: FrameBoardObject[]) {
-    return await miroBoard.getSvg(
-      frames?.map(({ id }) => id).filter((id): id is string => !!id)
-    );
-  }
+        const groupChildren = await miroBoard.getBoardObjects({
+          id: frameChildren
+            .filter((child) => child.type === "group")
+            .flatMap((child) => child.itemsIds)
+        });
 
-  async function getJson(frames?: FrameBoardObject[]) {
-    if (frames) {
-      const frameChildren = await miroBoard.getBoardObjects({
-        id: frames.flatMap((frame) => frame.childrenIds)
-      });
+        return JSON.stringify([...frames, ...frameChildren, ...groupChildren]);
+      }
 
-      const groupChildren = await miroBoard.getBoardObjects({
-        id: frameChildren
-          .filter((child) => child.type === "group")
-          .flatMap((child) => child.itemsIds)
-      });
-
-      return JSON.stringify([...frames, ...frameChildren, ...groupChildren]);
+      return JSON.stringify(await miroBoard.getBoardObjects({}));
     }
 
-    return JSON.stringify(await miroBoard.getBoardObjects({}));
-  }
+    const getFn = exportFormat === "json" ? getJson : getSvg;
 
-  const getFn = exportFormat === "json" ? getJson : getSvg;
+    if (outputFile?.includes("{frameName}")) {
+      if (!frameNames) {
+        throw Error(
+          "Expected frame names to be given when the output file name format expects a frame name."
+        );
+      }
 
-  if (outputFile?.includes("{frameName}")) {
-    if (!frameNames) {
-      throw Error(
-        "Expected frame names to be given when the output file name format expects a frame name."
-      );
-    }
-
-    for (const frameName of frameNames) {
-      const output = await getFn(await getFrames([frameName]));
-      await writeFile(outputFile.replace("{frameName}", frameName), output);
-    }
-  } else {
-    const svg = await getFn(frameNames && (await getFrames(frameNames)));
-    if (outputFile) {
-      await writeFile(outputFile, svg);
+      for (const frameName of frameNames) {
+        const output = await getFn(await getFrames([frameName]));
+        await writeFile(outputFile.replace("{frameName}", frameName), output);
+      }
     } else {
-      process.stdout.write(svg);
+      const svg = await getFn(frameNames && (await getFrames(frameNames)));
+      if (outputFile) {
+        await writeFile(outputFile, svg);
+      } else {
+        process.stdout.write(svg);
+      }
     }
+  } catch (err) {
+    const RED = "\x1b[31m";
+    const RESET = "\x1b[0m";
+    const GRAY = "\x1b[38;5;248m";
+    console.error(
+      `❌ ${RED}Error:${RESET} ${err instanceof Error ? err.message : err}`
+    );
+    console.error(GRAY);
+    console.error(err);
+    console.error(RESET);
   }
 })();

package/src/index.ts

@@ -1,12 +1,32 @@
-import puppeteer, { Browser, Page } from "puppeteer";
+import puppeteer, { Browser, Page, type LaunchOptions } from "puppeteer";
 import type { BoardObject } from "./miro-types.ts";
 import type { GetBoardsFilter } from "./miro-runtime.ts";
 
 interface InitialMiroBoardOptions {
+  /**
+   * The Miro authentication token with access to load the board.
+   * Optional if anonymous users may access the board without
+   * logging in.
+   */
   token?: string;
+  /**
+   * The Miro board ID.
+   */
   boardId: string;
+  /**
+   * Optional custom Puppeteer launch options.
+   */
+  puppeteerOptions?: LaunchOptions;
+  /**
+   * Timeout until it is determined that the Miro board could
+   * not be loaded for some reason, in milliseconds. Default
+   * is 15 seconds (15,000 milliseconds).
+   */
+  boardLoadTimeoutMs?: number;
 }
 
+const DEFAULT_BOARD_LOAD_TIMEOUT_MS = 15_000;
+
 type AdditionalFilter<T> = Partial<T> | Partial<{ [K in keyof T]: T[K][] }>;
 
 type FilteredResultsByType<
@@ -16,13 +36,17 @@ type FilteredResultsByType<
 
 export class MiroBoard {
   private context = Promise.withResolvers<{ browser: Browser; page: Page }>();
+  private isDisposed = false;
 
   constructor(options: InitialMiroBoardOptions) {
     this.initialize(options);
   }
 
   private async initialize(options: InitialMiroBoardOptions) {
-    const browser = await puppeteer.launch({ headless: true });
+    const browser = await puppeteer.launch({
+      headless: true,
+      ...(options.puppeteerOptions ?? {})
+    });
     const page = await browser.newPage();
 
     if (options.token) {
@@ -44,30 +68,57 @@ export class MiroBoard {
       waitUntil: "domcontentloaded"
     });
 
-    await page.evaluate(
-      () =>
-        new Promise<void>((resolve) => {
-          if (window.miro) {
-            resolve();
-          }
-
-          let miroValue: (typeof window)["miro"];
-          Object.defineProperty(window, "miro", {
-            get() {
-              return miroValue;
-            },
-            set(value) {
-              miroValue = value;
+    try {
+      await page.evaluate(
+        (timeoutDuration) =>
+          new Promise<void>((resolve, reject) => {
+            if (window.cmd?.board?.api) {
               resolve();
             }
-          });
-        })
-    );
+
+            const timeout = setTimeout(() => {
+              reject(
+                new Error(
+                  `Miro board could not be loaded: application instance not available after ${timeoutDuration} ms. Check your network connection, access token and board access.`
+                )
+              );
+            }, timeoutDuration);
+
+            const interval = setInterval(() => {
+              if (
+                document.querySelector('[data-testid="signup-popup-container"]')
+              ) {
+                clearInterval(interval);
+                clearTimeout(timeout);
+                reject(
+                  new Error(
+                    `Miro board requires authentication. Check board access settings to allow anonymous access or supply a token.`
+                  )
+                );
+              } else if (window.cmd?.board?.api) {
+                clearTimeout(timeout);
+                clearInterval(interval);
+                resolve();
+              }
+            }, 250);
+          }),
+        options.boardLoadTimeoutMs ?? DEFAULT_BOARD_LOAD_TIMEOUT_MS
+      );
+    } catch (err) {
+      await browser.close();
+      this.context.reject(err);
+      this.isDisposed = true;
+      return;
+    }
 
     this.context.resolve({ browser, page });
   }
 
   async dispose() {
+    if (this.isDisposed) {
+      return;
+    }
+    this.isDisposed = true;
     await (await this.browser).close();
   }
 
@@ -83,10 +134,52 @@ export class MiroBoard {
     return this.context.promise.then(({ page }) => page);
   }
 
+  /**
+   * Checks that all widgets have been loaded. Times out to 5 seconds due to bug
+   * in Miro where certain boards fail to load all widgets if SDK is not required
+   * for this function call.
+   */
+  private async checkAllWidgetsLoaded(mustHaveSdk: boolean = false) {
+    await (
+      await this.page
+    ).evaluate(
+      (mustHaveSdk, timeoutDuration) =>
+        new Promise<void>((resolve, reject) => {
+          const startTime = Date.now();
+          const interval = setInterval(() => {
+            if (
+              window.cmd?.board?.api?.isAllWidgetsLoaded() &&
+              (!mustHaveSdk || window.miro)
+            ) {
+              clearInterval(interval);
+              resolve();
+            }
+
+            if (Date.now() - startTime >= timeoutDuration) {
+              clearInterval(interval);
+              if (mustHaveSdk) {
+                reject(
+                  new Error(
+                    `Miro SDK failed to load in ${timeoutDuration} ms. This is likely caused by a Miro-internal issue. Check that the board is accessible using an incognito browser window.`
+                  )
+                );
+              } else {
+                resolve();
+              }
+            }
+          }, 150);
+        }),
+      mustHaveSdk,
+      3_000
+    );
+  }
+
   async getBoardObjects<F extends GetBoardsFilter>(
     filter: F,
     additionalFilter?: AdditionalFilter<BoardObject>
   ): Promise<FilteredResultsByType<F["type"], BoardObject>> {
+    await this.checkAllWidgetsLoaded(true);
+
     return (await this.page).evaluate(
       async (filter, additionalFilter) => {
         // @ts-expect-error - https://github.com/evanw/esbuild/issues/2605#issuecomment-2050808084
@@ -130,8 +223,10 @@ export class MiroBoard {
   }
 
   async getSvg(objectsIds?: string[]) {
+    await this.checkAllWidgetsLoaded(objectsIds !== undefined);
+
     return (await this.page).evaluate(async (objectsIds) => {
-      await window.miro.board.deselect();
+      window.cmd.board.api.clearSelection();
 
       if (objectsIds) {
         for (const id of objectsIds) {

package/src/miro-runtime.d.ts

@@ -21,6 +21,8 @@ declare global {
           export: {
             makeVector: () => Promise<string>;
           };
+          clearSelection: () => void;
+          isAllWidgetsLoaded: () => boolean;
         };
       };
     };

package/src/miro-types.ts

@@ -69,15 +69,14 @@ interface BoardObjectWithDimensions {
 }
 
 export interface PreviewBoardObject
-  extends BoardItemBase,
-    BoardObjectBase,
-    BoardObjectWithDimensions {
+  extends BoardItemBase, BoardObjectBase, BoardObjectWithDimensions {
   type: "preview";
   url: string;
 }
 
 export interface FrameBoardObject
-  extends Omit<BoardItemBase, "connectorIds">,
+  extends
+    Omit<BoardItemBase, "connectorIds">,
     BoardObjectBase,
     BoardObjectWithDimensions,
     BoardObjectWithCoordinates {
@@ -96,7 +95,8 @@ export interface GroupBoardItem extends BoardItemBase {
 }
 
 export interface StickyNoteBoardObject
-  extends BoardItemBase,
+  extends
+    BoardItemBase,
     BoardObjectBase,
     BoardObjectWithCoordinates,
     BoardObjectWithDimensions {
@@ -112,7 +112,8 @@ export interface StickyNoteBoardObject
 }
 
 export interface TextBoardObject
-  extends BoardItemBase,
+  extends
+    BoardItemBase,
     BoardObjectBase,
     BoardObjectWithCoordinates,
     BoardObjectWithDimensions {
@@ -130,7 +131,8 @@ export interface TextBoardObject
 }
 
 export interface ImageBoardObject
-  extends BoardItemBase,
+  extends
+    BoardItemBase,
     BoardObjectBase,
     BoardObjectWithDimensions,
     BoardObjectWithCoordinates {
@@ -159,9 +161,7 @@ interface TableStyle {
 }
 
 export interface TableBoardObject
-  extends BoardItemBase,
-    BoardObjectWithDimensions,
-    BoardObjectWithCoordinates {
+  extends BoardItemBase, BoardObjectWithDimensions, BoardObjectWithCoordinates {
   type: "image";
   rotation: number;
   cols?: number | { width: number }[];
@@ -176,7 +176,8 @@ export interface TableBoardObject
 }
 
 export interface StructDocBoardObject
-  extends BoardItemBase,
+  extends
+    BoardItemBase,
     BoardObjectBase,
     BoardObjectWithDimensions,
     BoardObjectWithCoordinates {
@@ -186,9 +187,7 @@ export interface StructDocBoardObject
 }
 
 export interface EmbedBoardObject
-  extends BoardItemBase,
-    BoardObjectBase,
-    BoardObjectWithCoordinates {
+  extends BoardItemBase, BoardObjectBase, BoardObjectWithCoordinates {
   type: "struct_doc";
   url: string;
   previewUrl: string;
@@ -198,7 +197,8 @@ export interface EmbedBoardObject
 }
 
 export interface ShapeBoardObject
-  extends BoardItemBase,
+  extends
+    BoardItemBase,
     BoardObjectBase,
     BoardObjectWithCoordinates,
     BoardObjectWithDimensions {
@@ -265,7 +265,8 @@ export interface TagBoardItem extends BoardItemBase {
 }
 
 export interface KanbanBoardObject
-  extends BoardItemBase,
+  extends
+    BoardItemBase,
     BoardObjectBase,
     BoardObjectWithCoordinates,
     BoardObjectWithDimensions {
@@ -273,7 +274,8 @@ export interface KanbanBoardObject
 }
 
 export interface UnsupportedBoardObject
-  extends BoardItemBase,
+  extends
+    BoardItemBase,
     BoardObjectBase,
     BoardObjectWithCoordinates,
     BoardObjectWithDimensions {

package/tests/api.test.ts

@@ -3,12 +3,24 @@ import assert from "node:assert";
 import { MiroBoard } from "../src";
 
 const boardId = process.env.TEST_BOARD_ID;
+const inaccessibleBoardId = process.env.PRIVATE_TEST_BOARD_ID;
+const buggyBoardId = process.env.BUGGY_TEST_BOARD_ID;
 
 if (!boardId) {
   console.error("TEST_BOARD_ID environment variable is required.");
   process.exit(1);
 }
 
+if (!inaccessibleBoardId) {
+  console.error("PRIVATE_TEST_BOARD_ID environment variable is required.");
+  process.exit(1);
+}
+
+if (!buggyBoardId) {
+  console.error("BUGGY_TEST_BOARD_ID environment variable is required.");
+  process.exit(1);
+}
+
 describe("Miro integration", async () => {
   const miroBoard = new MiroBoard({ boardId });
 
@@ -66,3 +78,32 @@ describe("Miro integration", async () => {
     assert.ok(svg.length > 10_000);
   });
 });
+
+await it("should throw error for a non-public board", async () => {
+  try {
+    const miroBoard = new MiroBoard({ boardId: inaccessibleBoardId });
+    await miroBoard.getBoardObjects({});
+    assert.fail();
+  } catch (err) {
+    assert.ok(err instanceof Error);
+    assert.equal(
+      err.message,
+      "Miro board requires authentication. Check board access settings to allow anonymous access or supply a token."
+    );
+  }
+});
+
+await it("should be able to export SVG of a buggy Miro board", async () => {
+  // this is a flaky issue on Miro; around 10% of the time the board loads fine
+  // so let's repeat this test a couple of times just to be sure
+  const results = await Promise.all(
+    Array.from({ length: 10 }).map(async () => {
+      const miroBoard = new MiroBoard({ boardId: buggyBoardId });
+      const svg = await miroBoard.getSvg();
+      const hasSvgContents = svg.includes("What should we do next?");
+      await miroBoard.dispose();
+      return hasSvgContents;
+    })
+  );
+  assert.deepStrictEqual(results, Array.from({ length: 10 }).fill(true));
+});