miro-export 1.0.0 → 1.1.0

package/.github/workflows/build.yml

@@ -2,7 +2,7 @@ name: Build
 
 on:
   push:
-  pull_request:
+  workflow_dispatch:
 
 jobs:
   build:
@@ -14,7 +14,7 @@ jobs:
           version: 8
       - uses: actions/setup-node@v4
         with:
-          node-version: "20.x"
+          node-version: "22.x"
       - name: Install dependencies
         run: pnpm i --frozen-lockfile
       - name: Lint

package/.github/workflows/dependabot-merge.yml

@@ -1,19 +1,14 @@
 name: Dependabot auto-merge
 on: pull_request
 
-permissions:
-  pull-requests: write
-
 jobs:
   dependabot:
     runs-on: ubuntu-latest
+    permissions:
+      pull-requests: write
+      contents: write
     if: github.actor == 'dependabot[bot]'
     steps:
-      - name: Dependabot metadata
-        id: metadata
-        uses: dependabot/fetch-metadata@v1
-        with:
-          github-token: "${{ secrets.GITHUB_TOKEN }}"
       - name: Merge a PR
         run: gh pr merge --auto --merge "$PR_URL"
         env:

package/.github/workflows/publish.yml

@@ -14,7 +14,7 @@ jobs:
           version: 8
       - uses: actions/setup-node@v4
         with:
-          node-version: "20.x"
+          node-version: "22.x"
           registry-url: "https://registry.npmjs.org"
       - run: pnpm install --frozen-lockfile
       - run: pnpm run build

package/.github/workflows/test.yml

@@ -0,0 +1,23 @@
+name: Test
+
+on:
+  push:
+  workflow_dispatch:
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: pnpm/action-setup@v3
+        with:
+          version: 8
+      - uses: actions/setup-node@v4
+        with:
+          node-version: "22.x"
+      - name: Install dependencies
+        run: pnpm i --frozen-lockfile
+      - name: Test
+        run: pnpm run test
+        env:
+          TEST_BOARD_ID: ${{secrets.TEST_BOARD_ID}}

package/.vscode/settings.json

@@ -0,0 +1,3 @@
+{
+  "typescript.tsdk": "node_modules/typescript/lib"
+}

package/README.md

@@ -1,12 +1,18 @@
 # Miro board exporter
 
-Exports Miro frames as full-detail SVGs using a headless Puppeteer browser. Requires a personal Miro token.
+Exports Miro frames as full-detail SVGs or JSON using a headless Puppeteer browser.
 
-## Getting the Miro token
+- [Authentication](#authentication)
+- [CLI](#cli)
+- [Programmatic usage](#programmatic-usage)
 
-Log in to Miro using your regular web browser, and then copy the value of the "token" cookie from developer tools. This is the token that this tool requires.
+## Authentication
 
-## Usage
+If accessing a private board, a personal token is required. To get a token, log in to Miro using a regular web browser, and then copy the value of the "token" cookie from developer tools. This is the token that should be used. If the board can be accessed without an account using a public link, the token is optional.
+
+## CLI
+
+### Usage
 
 ```
 Options:
@@ -14,10 +20,11 @@ Options:
   -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')
   -h, --help                         display help for command
 ```
 
-## Examples
+### Examples
 
 ```sh
 # export "Frame 2" to the file "My Frame 2.svg"
@@ -28,8 +35,74 @@ miro-export -t XYZ -b uMoVLkx8gIc=
 
 # export "Frame 2" and "Frame 3" to "Frame 2.svg" and "Frame 3.svg" respectively
 miro-export -t XYZ -b uMoVLkx8gIc= -f "Frame 2" "Frame 3" -o "{frameName}.svg"
+
+# export JSON representation of "Frame 2"
+miro-export -t XYZ -b uMoVLkx8gIc= -f "Frame 2" -e json
+```
+
+### Capturing multiple frames at once
+
+It is possible to give multiple frames to the `-f` switch, e.g., `-f "Frame 2" "Frame 3"`. However, for SVG export, this will capture all content that is within the outer bounding box when all frames have been selected, so content between the frames will be captured as well. If you want separate SVGs for each frame (and thus avoiding capturing content in between), use the output file switch with `{frameName}` in the file name, e.g., `-o "Export - {frameName}.svg"`. It is not possible to export separate SVGs without the output file specified (i.e., to stdout).
+
+### JSON export
+
+The JSON export format is a Miro-internal representation of all the board objects. It is not a documented format, but it is quite easy to understand. The exported format is always an array of objects that have the field `type` as a discriminator. Depending on the type, fields change. Some of the types have been documented as TypeScript interfaces at [miro-types.ts](src/miro-types.ts). For example, a `sticky_note` object could look like this:
+
+```json
+{
+  "type": "sticky_note",
+  "shape": "square",
+  "content": "<p>Test content</p>",
+  "style": {
+    "fillColor": "cyan",
+    "textAlign": "center",
+    "textAlignVertical": "middle"
+  },
+  "tagIds": [],
+  "id": "3458764564249021457",
+  "parentId": "3458764564247784511",
+  "origin": "center",
+  "relativeTo": "parent_top_left",
+  "createdAt": "2023-09-11T12:45:00.041Z",
+  "createdBy": "3458764537906310005",
+  "modifiedAt": "2023-09-11T12:46:01.041Z",
+  "modifiedBy": "3458764537906310005",
+  "connectorIds": [],
+  "x": 129.29101113436059,
+  "y": 201.25587788616645,
+  "width": 101.46000000000001,
+  "height": 125.12
+}
+```
+
+## Programmatic usage
+
+```ts
+import { MiroBoard } from "miro-export";
+
+await using miroBoard = new MiroBoard({
+  boardId: "uMoVLkx8gIc=", // required
+  token: "..." // optional
+});
+
+// get all board objects of type frame and with title "Frame 1"
+const framesWithTitleFrame1 = miroBoard.getBoardObjects(
+  { type: "frame" }, // required (but empty object is OK too), limited field support
+  { title: "Frame 1" } // optional additional filters
+);
+
+// get SVG of the first frame found above
+const svgOfFrame1 = miroBoard.getSvg([framesWithTitleFrame1[0].id]);
+
+// if you can't use "await using" for disposal, you can also dispose manually:
+// await miroBoard.dispose()
+// this can also be used to close the browser at the middle of the current scope
 ```
 
-## Capturing multiple frames at once
+> [!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,
+> `miroBoard.dispose()` may be called at any time to dispose of the instance manually.
 
-It is possible to supply multiple frames to the `-f` switch, e.g., `-f "Frame 2" "Frame 3"`. However, this will capture all content that is within the outer bounding box when all frames have been selected, so content between the frames will be captured as well. If you want separate SVGs for each frame, use the output file switch with `{frameName}` in the file name, e.g., `-o "Export - {frameName}.svg"`. It is not possible to export separate SVGs without the output file specified (i.e., to stdout).
+Types for many of the common board object types has been provided in [miro-types.ts](src/miro-types.ts).

package/build/cli.d.ts

@@ -0,0 +1 @@
+export {};

package/build/cli.js

@@ -0,0 +1,121 @@
+var __addDisposableResource = (this && this.__addDisposableResource) || function (env, value, async) {
+    if (value !== null && value !== void 0) {
+        if (typeof value !== "object" && typeof value !== "function") throw new TypeError("Object expected.");
+        var dispose, inner;
+        if (async) {
+            if (!Symbol.asyncDispose) throw new TypeError("Symbol.asyncDispose is not defined.");
+            dispose = value[Symbol.asyncDispose];
+        }
+        if (dispose === void 0) {
+            if (!Symbol.dispose) throw new TypeError("Symbol.dispose is not defined.");
+            dispose = value[Symbol.dispose];
+            if (async) inner = dispose;
+        }
+        if (typeof dispose !== "function") throw new TypeError("Object not disposable.");
+        if (inner) dispose = function() { try { inner.call(this); } catch (e) { return Promise.reject(e); } };
+        env.stack.push({ value: value, dispose: dispose, async: async });
+    }
+    else if (async) {
+        env.stack.push({ async: true });
+    }
+    return value;
+};
+var __disposeResources = (this && this.__disposeResources) || (function (SuppressedError) {
+    return function (env) {
+        function fail(e) {
+            env.error = env.hasError ? new SuppressedError(e, env.error, "An error was suppressed during disposal.") : e;
+            env.hasError = true;
+        }
+        var r, s = 0;
+        function next() {
+            while (r = env.stack.pop()) {
+                try {
+                    if (!r.async && s === 1) return s = 0, env.stack.push(r), Promise.resolve().then(next);
+                    if (r.dispose) {
+                        var result = r.dispose.call(r.value);
+                        if (r.async) return s |= 2, Promise.resolve(result).then(next, function(e) { fail(e); return next(); });
+                    }
+                    else s |= 1;
+                }
+                catch (e) {
+                    fail(e);
+                }
+            }
+            if (s === 1) return env.hasError ? Promise.reject(env.error) : Promise.resolve();
+            if (env.hasError) throw env.error;
+        }
+        return next();
+    };
+})(typeof SuppressedError === "function" ? SuppressedError : function (error, suppressed, message) {
+    var e = new Error(message);
+    return e.name = "SuppressedError", e.error = error, e.suppressed = suppressed, e;
+});
+import { writeFile } from "fs/promises";
+import { program } from "@commander-js/extra-typings";
+import { MiroBoard } from "./index.js";
+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();
+(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.`);
+            }
+            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]);
+            }
+            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);
+            }
+        }
+        else {
+            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;
+    }
+})();

package/build/index.d.ts

@@ -0,0 +1,24 @@
+import type { BoardObject } from "./miro-types.ts";
+import type { GetBoardsFilter } from "./miro-runtime.ts";
+interface InitialMiroBoardOptions {
+    token?: string;
+    boardId: string;
+}
+type AdditionalFilter<T> = Partial<T> | Partial<{
+    [K in keyof T]: T[K][];
+}>;
+type FilteredResultsByType<F extends string | string[] | undefined, T> = F extends string ? Extract<BoardObject, {
+    type: F;
+}>[] : T[];
+export declare class MiroBoard {
+    private context;
+    constructor(options: InitialMiroBoardOptions);
+    private initialize;
+    dispose(): Promise<void>;
+    [Symbol.asyncDispose](): Promise<void>;
+    private get browser();
+    private get page();
+    getBoardObjects<F extends GetBoardsFilter>(filter: F, additionalFilter?: AdditionalFilter<BoardObject>): Promise<FilteredResultsByType<F["type"], BoardObject>>;
+    getSvg(objectsIds?: string[]): Promise<string>;
+}
+export {};

package/build/index.js

@@ -1,76 +1,95 @@
 #!/usr/bin/env node
-"use strict";
-var __importDefault = (this && this.__importDefault) || function (mod) {
-    return (mod && mod.__esModule) ? mod : { "default": mod };
-};
-Object.defineProperty(exports, "__esModule", { value: true });
-const promises_1 = require("fs/promises");
-const puppeteer_1 = __importDefault(require("puppeteer"));
-const extra_typings_1 = require("@commander-js/extra-typings");
-const { token, boardId, frameNames, outputFile } = extra_typings_1.program
-    .requiredOption("-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)")
-    .parse()
-    .opts();
-(async () => {
-    const browser = await puppeteer_1.default.launch({ headless: true });
-    const page = await browser.newPage();
-    await page.setCookie({
-        name: "token",
-        value: token,
-        domain: "miro.com"
-    });
-    await page.setViewport({ width: 1080, height: 1024 });
-    await page.goto(`https://miro.com/app/board/${boardId}/`, {
-        waitUntil: "domcontentloaded"
-    });
-    await page.evaluate(() => new Promise((resolve) => {
-        const interval = setInterval(() => {
-            try {
-                if (typeof window.miro?.board !== "undefined") {
+import puppeteer, { Browser, Page } from "puppeteer";
+export class MiroBoard {
+    context = Promise.withResolvers();
+    constructor(options) {
+        this.initialize(options);
+    }
+    async initialize(options) {
+        const browser = await puppeteer.launch({ headless: true });
+        const page = await browser.newPage();
+        if (options.token) {
+            await browser.browserContexts()[0].setCookie({
+                name: "token",
+                value: options.token,
+                domain: "miro.com",
+                path: "/",
+                expires: -1,
+                sameParty: false,
+                httpOnly: false,
+                secure: false
+            });
+        }
+        await page.setViewport({ width: 1080, height: 1024 });
+        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;
                     resolve();
-                    clearInterval(interval);
                 }
-            }
-            catch (e) {
-                // ignored
-            }
-        }, 100);
-    }));
-    const getSvgForFrames = (frameNames) => page.evaluate(async (frameNames) => {
-        if (frameNames) {
-            const frames = await window.miro.board.get({ type: ["frame"] });
-            const selectedFrames = frames.filter((frame) => frameNames.includes(frame.title));
-            if (selectedFrames.length !== frameNames.length) {
-                throw Error(`${frameNames.length - selectedFrames.length} frame(s) could not be found on the board.`);
-            }
+            });
+        }));
+        this.context.resolve({ browser, page });
+    }
+    async dispose() {
+        await (await this.browser).close();
+    }
+    async [Symbol.asyncDispose]() {
+        await this.dispose();
+    }
+    get browser() {
+        return this.context.promise.then(({ browser }) => browser);
+    }
+    get page() {
+        return this.context.promise.then(({ page }) => page);
+    }
+    async getBoardObjects(filter, additionalFilter) {
+        return (await this.page).evaluate(async (filter, additionalFilter) => {
+            // @ts-expect-error - https://github.com/evanw/esbuild/issues/2605#issuecomment-2050808084
+            window.__name = (func) => func;
+            const objectFilterMatches = (filter, target) => {
+                for (const key in filter) {
+                    if (!(key in target)) {
+                        return false;
+                    }
+                    const targetValue = target[key];
+                    if (Array.isArray(filter[key])) {
+                        if (!filter[key].includes(targetValue)) {
+                            return false;
+                        }
+                    }
+                    else if (targetValue !== filter[key]) {
+                        return false;
+                    }
+                }
+                return true;
+            };
+            const objects = await window.miro.board.get(filter);
+            const filteredObjects = additionalFilter
+                ? objects.filter((object) => objectFilterMatches(additionalFilter, object))
+                : objects;
+            return filteredObjects;
+        }, filter, additionalFilter);
+    }
+    async getSvg(objectsIds) {
+        return (await this.page).evaluate(async (objectsIds) => {
             await window.miro.board.deselect();
-            for (const { id } of selectedFrames) {
-                await window.miro.board.select({ id });
+            if (objectsIds) {
+                for (const id of objectsIds) {
+                    await window.miro.board.select({ id });
+                }
             }
-        }
-        return await window.cmd.board.api.export.makeVector();
-    }, frameNames);
-    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 svg = await getSvgForFrames([frameName]);
-            await (0, promises_1.writeFile)(outputFile.replace("{frameName}", frameName), svg);
-        }
-    }
-    else {
-        const svg = await getSvgForFrames(frameNames);
-        if (outputFile) {
-            await (0, promises_1.writeFile)(outputFile, svg);
-        }
-        else {
-            process.stdout.write(svg);
-        }
+            return await window.cmd.board.api.export.makeVector();
+        }, objectsIds);
     }
-    await page.close();
-    await browser.close();
-})();
+}