miro-export 1.0.1 → 1.1.1

package/build/miro-types.d.ts

@@ -0,0 +1,188 @@
+type TextAlignment = "left" | "center" | "right";
+type TextVerticalAlignment = "top" | "middle" | "bottom";
+export type BoardObjectType = "text" | "sticky_note" | "shape" | "image" | "frame" | "preview" | "card" | "app_card" | "usm" | "kanban" | "document" | "mockup" | "curve" | "webscreen" | "table" | "svg" | "emoji" | "embed" | "connector" | "unsupported" | "table_text" | "rallycard" | "stencil" | "tag" | "code" | "red" | "stamp" | "pipmatrix" | "demo_1d_layout" | "page" | "action_button" | "external_diagram" | "slide_container" | "sdk_custom_widget" | "group" | "struct_doc" | "mindmap";
+export interface BoardItemBase {
+    id?: string;
+    type: BoardObjectType;
+}
+interface BoardObjectBase {
+    origin: "center";
+    linkedTo?: string;
+    connectorIds?: string[];
+    groupId?: string;
+    relativeTo: "canvas_center" | "parent_top_left" | "parent_center";
+    parentId?: string | null;
+    createdAt: string;
+    createdBy: string;
+    modifiedAt: string;
+    modifiedBy: string;
+}
+interface BoardObjectWithCoordinates {
+    x: number;
+    y: number;
+}
+interface BoardObjectWithDimensions {
+    width: number;
+    height: number;
+}
+export interface PreviewBoardObject extends BoardItemBase, BoardObjectBase, BoardObjectWithDimensions {
+    type: "preview";
+    url: string;
+}
+export interface FrameBoardObject extends Omit<BoardItemBase, "connectorIds">, BoardObjectBase, BoardObjectWithDimensions, BoardObjectWithCoordinates {
+    type: "frame";
+    title: string;
+    childrenIds: string[];
+    showContent: boolean;
+    style: {
+        fillColor: string;
+    };
+}
+export interface GroupBoardItem extends BoardItemBase {
+    type: "group";
+    itemsIds: string[];
+}
+export interface StickyNoteBoardObject extends BoardItemBase, BoardObjectBase, BoardObjectWithCoordinates, BoardObjectWithDimensions {
+    type: "sticky_note";
+    tagIds: string[];
+    content: string;
+    shape: string;
+    style: {
+        fillColor: string;
+        textAlign: TextAlignment;
+        textAlignVertical: TextVerticalAlignment;
+    };
+}
+export interface TextBoardObject extends BoardItemBase, BoardObjectBase, BoardObjectWithCoordinates, BoardObjectWithDimensions {
+    type: "text";
+    content: string;
+    rotation: number;
+    style: {
+        fillColor: string;
+        fillOpacity: number;
+        fontFamily: string;
+        fontSize: number;
+        textAlign: TextAlignment;
+        color: string;
+    };
+}
+export interface ImageBoardObject extends BoardItemBase, BoardObjectBase, BoardObjectWithDimensions, BoardObjectWithCoordinates {
+    type: "image";
+    rotation: number;
+    title: string;
+    url: string;
+    alt?: string;
+}
+interface TableStyle {
+    borderColor?: string;
+    backgroundColor?: string;
+    backgroundOpacity?: number;
+    textColor?: string;
+    textAlign: TextAlignment;
+    textAlignVertical: TextVerticalAlignment;
+    textBold?: boolean;
+    textItalic?: boolean;
+    textUnderline?: boolean;
+    textStrike?: boolean;
+    textHighlight: null | string;
+    fontFamily?: string;
+    fontSize?: number;
+    writingMode?: "sideways" | "horizontal";
+}
+export interface TableBoardObject extends BoardItemBase, BoardObjectWithDimensions, BoardObjectWithCoordinates {
+    type: "image";
+    rotation: number;
+    cols?: number | {
+        width: number;
+    }[];
+    rows?: number | {
+        height: number;
+    }[];
+    cells?: {
+        text: string;
+        rowspan?: number;
+        colspan?: number;
+        style: TableStyle;
+    }[][];
+    style: TableStyle;
+}
+export interface StructDocBoardObject extends BoardItemBase, BoardObjectBase, BoardObjectWithDimensions, BoardObjectWithCoordinates {
+    type: "struct_doc";
+    title: string;
+    content: string;
+}
+export interface EmbedBoardObject extends BoardItemBase, BoardObjectBase, BoardObjectWithCoordinates {
+    type: "struct_doc";
+    url: string;
+    previewUrl: string;
+    mode: "inline" | "modal";
+    width?: number;
+    height?: number;
+}
+export interface ShapeBoardObject extends BoardItemBase, BoardObjectBase, BoardObjectWithCoordinates, BoardObjectWithDimensions {
+    type: "shape";
+    content: string;
+    shape: string;
+    rotation: number;
+    style: {
+        fillColor: string;
+        fontFamily: string;
+        fontSize: number;
+        textAlign: TextAlignment;
+        textAlignVertical: TextVerticalAlignment;
+        borderStyle: "dashed" | "normal" | "dotted";
+        borderOpacity: number;
+        borderColor: string;
+        borderWidth: number;
+        fillOpacity: number;
+        color: string;
+    };
+}
+interface CardBase extends BoardObjectBase, BoardObjectWithDimensions {
+    rotation: number;
+    title: string;
+    description: string;
+    fields: {
+        fillColor?: string;
+        textColor?: string;
+        iconUrl?: string;
+        iconShape?: "round" | "square";
+        tooltip?: string;
+        value: string;
+    }[];
+    style: {
+        cardTheme: string;
+        fillBackground: boolean;
+    };
+    /** coordinates may be null if card is part of a Kanban board */
+    x: number | null;
+    y: number | null;
+}
+export interface CardBoardObject extends BoardItemBase, CardBase {
+    type: "card";
+    assignee?: {
+        userId: string;
+    };
+    dueDate?: string;
+    startDate?: string;
+    taskStatus: "to-do" | "in-progress" | "done" | "none";
+    tagIds: string[];
+}
+export interface AppCardBoardObject extends BoardItemBase, CardBase {
+    type: "app_card";
+    owned: boolean;
+    status: "disabled" | "disconnected" | "connected";
+}
+export interface TagBoardItem extends BoardItemBase {
+    type: "tag";
+    title: string;
+    color: string;
+}
+export interface KanbanBoardObject extends BoardItemBase, BoardObjectBase, BoardObjectWithCoordinates, BoardObjectWithDimensions {
+    type: "kanban";
+}
+export interface UnsupportedBoardObject extends BoardItemBase, BoardObjectBase, BoardObjectWithCoordinates, BoardObjectWithDimensions {
+    type: "unsupported";
+}
+export type BoardObject = PreviewBoardObject | FrameBoardObject | GroupBoardItem | StickyNoteBoardObject | TextBoardObject | ImageBoardObject | TableBoardObject | StructDocBoardObject | EmbedBoardObject | ShapeBoardObject | CardBoardObject | AppCardBoardObject | TagBoardItem | KanbanBoardObject | UnsupportedBoardObject;
+export {};

package/build/miro-types.js

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

package/eslint.config.mjs

@@ -0,0 +1,35 @@
+import tseslint from "typescript-eslint";
+import promise from "eslint-plugin-promise";
+import tsParser from "@typescript-eslint/parser";
+import js from "@eslint/js";
+import prettierRecommended from "eslint-plugin-prettier/recommended";
+import stylisticTs from "@stylistic/eslint-plugin-ts";
+
+export default [
+  js.configs.recommended,
+  ...tseslint.configs.recommended,
+  promise.configs["flat/recommended"],
+  prettierRecommended,
+  {
+    ignores: ["**/build"],
+
+    plugins: {
+      "@stylistic/ts": stylisticTs
+    },
+
+    languageOptions: {
+      parser: tsParser,
+      ecmaVersion: 6,
+      sourceType: "module"
+    },
+
+    rules: {
+      "@typescript-eslint/naming-convention": "warn",
+      "@stylistic/ts/semi": "warn",
+      curly: "warn",
+      eqeqeq: "warn",
+      "no-throw-literal": "warn",
+      semi: "off"
+    }
+  }
+];

package/package.json

@@ -1,8 +1,9 @@
 {
   "name": "miro-export",
-  "version": "1.0.1",
+  "version": "1.1.1",
   "author": "jolle <npm-contact@jolle.io>",
   "license": "MIT",
+  "type": "module",
   "description": "Export Miro boards and/or frames as SVG or JSON",
   "keywords": [
     "miro",
@@ -18,24 +19,38 @@
   },
   "homepage": "https://github.com/jolle/miro-export",
   "main": "./build/index.js",
-  "bin": "./build/index.js",
+  "bin": {
+    "miro-export": "./build/cli.js"
+  },
   "devDependencies": {
-    "@types/node": "^20.11.19",
-    "eslint": "^8.56.0",
+    "@eslint/eslintrc": "^3.2.0",
+    "@eslint/js": "^9.17.0",
+    "@stylistic/eslint-plugin-ts": "^2.12.1",
+    "@types/node": "^22.10.2",
+    "ajv": "^8.17.1",
+    "eslint": "^9.17.0",
     "eslint-config-prettier": "^9.1.0",
-    "eslint-plugin-prettier": "^5.1.3",
-    "eslint-plugin-promise": "^6.1.1",
-    "prettier": "^3.2.5",
-    "typescript": "^5.3.3",
-    "typescript-eslint": "^7.0.1"
+    "eslint-plugin-prettier": "^5.2.1",
+    "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"
   },
   "dependencies": {
-    "@commander-js/extra-typings": "^12.0.0",
-    "commander": "^12.0.0",
-    "puppeteer": "^22.1.0"
+    "@commander-js/extra-typings": "^12.1.0",
+    "commander": "^12.1.0",
+    "puppeteer": "^23.11.1"
+  },
+  "engines": {
+    "node": ">=22.0.0"
   },
   "scripts": {
-    "lint": "eslint *.ts && prettier -c *.ts",
-    "build": "tsc && echo \"#!/usr/bin/env node\n$(cat ./build/index.js)\" > ./build/index.js"
+    "lint": "eslint src/*.ts && prettier -c src/*.ts",
+    "build": "tsc && echo \"#!/usr/bin/env node\n$(cat ./build/cli.js)\" > ./build/cli.js",
+    "test": "npm run test:board-object-types && npm run test:api",
+    "test:board-object-types": "tsx tests/board-object-types.ts",
+    "test:api": "tsx tests/api.test.ts"
   }
 }

package/src/cli.ts

@@ -0,0 +1,86 @@
+import { writeFile } from "fs/promises";
+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();
+
+(async () => {
+  await using miroBoard = new MiroBoard({ token, boardId });
+
+  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;
+  }
+
+  async function getSvg(frames?: FrameBoardObject[]) {
+    return await miroBoard.getSvg(
+      frames?.map(({ id }) => id).filter((id): id is string => !!id)
+    );
+  }
+
+  async function getJson(frames?: FrameBoardObject[]) {
+    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);
+    }
+  }
+})();

package/src/index.ts

@@ -0,0 +1,145 @@
+import puppeteer, { Browser, Page } from "puppeteer";
+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[]; // TODO: F extends string[]
+
+export class MiroBoard {
+  private context = Promise.withResolvers<{ browser: Browser; page: Page }>();
+
+  constructor(options: InitialMiroBoardOptions) {
+    this.initialize(options);
+  }
+
+  private async initialize(options: InitialMiroBoardOptions) {
+    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<void>((resolve) => {
+          if (window.miro) {
+            resolve();
+          }
+
+          let miroValue: (typeof window)["miro"];
+          Object.defineProperty(window, "miro", {
+            get() {
+              return miroValue;
+            },
+            set(value) {
+              miroValue = value;
+              resolve();
+            }
+          });
+        })
+    );
+
+    this.context.resolve({ browser, page });
+  }
+
+  async dispose() {
+    await (await this.browser).close();
+  }
+
+  async [Symbol.asyncDispose]() {
+    await this.dispose();
+  }
+
+  private get browser() {
+    return this.context.promise.then(({ browser }) => browser);
+  }
+
+  private get page() {
+    return this.context.promise.then(({ page }) => page);
+  }
+
+  async getBoardObjects<F extends GetBoardsFilter>(
+    filter: F,
+    additionalFilter?: AdditionalFilter<BoardObject>
+  ): Promise<FilteredResultsByType<F["type"], BoardObject>> {
+    return (await this.page).evaluate(
+      async (filter, additionalFilter) => {
+        // @ts-expect-error - https://github.com/evanw/esbuild/issues/2605#issuecomment-2050808084
+        window.__name = (func: unknown) => func;
+
+        const objectFilterMatches = (
+          filter: AdditionalFilter<Record<string, unknown>>,
+          target: object
+        ) => {
+          for (const key in filter) {
+            if (!(key in target)) {
+              return false;
+            }
+
+            const targetValue = target[key as keyof typeof target];
+            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 as FilteredResultsByType<F["type"], BoardObject>;
+      },
+      filter,
+      additionalFilter
+    );
+  }
+
+  async getSvg(objectsIds?: string[]) {
+    return (await this.page).evaluate(async (objectsIds) => {
+      await window.miro.board.deselect();
+
+      if (objectsIds) {
+        for (const id of objectsIds) {
+          await window.miro.board.select({ id });
+        }
+      }
+
+      return await window.cmd.board.api.export.makeVector();
+    }, objectsIds);
+  }
+}

package/src/miro-runtime.d.ts

@@ -0,0 +1,28 @@
+import { BoardObject, BoardObjectType } from "./miro-types";
+
+interface GetBoardsFilter {
+  type?: BoardObjectType[] | BoardObjectType;
+  id?: string[] | string;
+  tags?: string[] | string;
+}
+
+declare global {
+  interface Window {
+    miro: {
+      board: {
+        get(opts: GetBoardsFilter): Promise<BoardObject[]>;
+        select(opts: { id: string }): Promise<void>;
+        deselect(): Promise<void>;
+      };
+    };
+    cmd: {
+      board: {
+        api: {
+          export: {
+            makeVector: () => Promise<string>;
+          };
+        };
+      };
+    };
+  }
+}