miro-export 1.0.0 → 1.1.0

package/src/miro-types.ts

@@ -0,0 +1,298 @@
+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;

package/tests/api.test.ts

@@ -0,0 +1,68 @@
+import { describe, it, after } from "node:test";
+import assert from "node:assert";
+import { MiroBoard } from "../src";
+
+const boardId = process.env.TEST_BOARD_ID;
+
+if (!boardId) {
+  console.error("TEST_BOARD_ID environment variable is required.");
+  process.exit(1);
+}
+
+describe("Miro integration", async () => {
+  const miroBoard = new MiroBoard({ boardId });
+
+  after(async () => {
+    await miroBoard.dispose();
+  });
+
+  await it("should get all objects", async () => {
+    const objects = await miroBoard.getBoardObjects({});
+
+    assert.ok(
+      objects.find(
+        (obj) => obj.type === "sticky_note" && obj.content === "<p>Test 1</p>"
+      )
+    );
+  });
+
+  await it("should filter objects by type = 'frame'", async () => {
+    const frames = await miroBoard.getBoardObjects({ type: "frame" });
+
+    assert.ok(frames.length > 0);
+    assert.ok(frames.every((frame) => frame.type === "frame"));
+  });
+
+  await it("should filter objects by title = 'Frame 1'", async () => {
+    const objects = await miroBoard.getBoardObjects({}, { title: "Frame 1" });
+
+    assert.ok(
+      objects.find((obj) => obj.type === "frame" && obj.title === "Frame 1")
+    );
+  });
+
+  await it("should get SVG for entire board", async () => {
+    const svg = await miroBoard.getSvg();
+
+    assert.ok(svg.includes("<svg"));
+    assert.ok(svg.includes("Card text"));
+    assert.ok(svg.includes("STAR"));
+    assert.ok(svg.length > 50_000);
+  });
+
+  await it("should get SVG for specific frame", async () => {
+    const frames = await miroBoard.getBoardObjects(
+      { type: "frame" },
+      { title: "Frame 2" }
+    );
+    const frameId = frames[0].id;
+    assert.ok(frameId);
+
+    const svg = await miroBoard.getSvg([frameId]);
+
+    assert.ok(svg.includes("<svg"));
+    assert.ok(!svg.includes("Card text"));
+    assert.ok(svg.includes("STAR"));
+    assert.ok(svg.length > 10_000);
+  });
+});

package/tests/board-object-types.ts

@@ -0,0 +1,54 @@
+import { resolve } from "path";
+import { MiroBoard } from "../src";
+import * as tsj from "ts-json-schema-generator";
+import Ajv from "ajv";
+
+(async () => {
+  const config = {
+    path: resolve(import.meta.dirname, "../src/miro-types.ts"),
+    tsconfig: resolve(import.meta.dirname, "../tsconfig.json"),
+    type: "BoardObject"
+  };
+  const schema = tsj.createGenerator(config).createSchema(config.type);
+
+  const boardId = process.env.TEST_BOARD_ID;
+
+  if (!boardId) {
+    console.error("TEST_BOARD_ID environment variable is required.");
+    process.exit(1);
+  }
+
+  const miroBoard = new MiroBoard({ boardId });
+  const objects = await miroBoard.getBoardObjects({});
+  await miroBoard.dispose();
+
+  for (const object of objects) {
+    const ajv = new Ajv();
+    if (!ajv.validate(schema, object)) {
+      console.log(
+        "Failed to validate object: ",
+        JSON.stringify(
+          object,
+          process.env.CI
+            ? (key, value) => {
+                if (key === "type") {
+                  return value;
+                }
+
+                if (typeof value === "string") {
+                  return "string";
+                } else if (typeof value === "number") {
+                  return 0;
+                } else {
+                  return value;
+                }
+              }
+            : undefined,
+          2
+        )
+      );
+      console.error(ajv.errors);
+      process.exit(1);
+    }
+  }
+})();

package/tsconfig.json

@@ -1,13 +1,16 @@
 {
   "compilerOptions": {
-    "target": "ESNext",
-    "lib": ["DOM"],
-    "module": "commonjs",
-    "declaration": false,
+    "target": "ES2023",
+    "lib": ["DOM", "ESNext"],
+    "module": "NodeNext",
+    "moduleResolution": "nodenext",
+    "declaration": true,
     "outDir": "./build",
     "esModuleInterop": true,
     "forceConsistentCasingInFileNames": true,
     "strict": true,
-    "skipLibCheck": true
-  }
+    "skipLibCheck": true,
+    "verbatimModuleSyntax": true
+  },
+  "include": ["src", "src/miro-runtime.d.ts"]
 }

package/index.ts

@@ -1,124 +0,0 @@
-import { writeFile } from "fs/promises";
-import puppeteer from "puppeteer";
-import { program } from "@commander-js/extra-typings";
-
-declare global {
-  interface Window {
-    miro: {
-      board: {
-        get(opts: {
-          type: "frame"[];
-        }): Promise<{ title: string; id: string }[]>;
-        select(opts: { id: string }): Promise<void>;
-        deselect(): Promise<void>;
-      };
-    };
-    cmd: {
-      board: {
-        api: {
-          export: {
-            makeVector: () => Promise<string>;
-          };
-        };
-      };
-    };
-  }
-}
-
-const { token, boardId, frameNames, outputFile } = 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.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<void>((resolve) => {
-        const interval = setInterval(() => {
-          try {
-            if (typeof window.miro?.board !== "undefined") {
-              resolve();
-              clearInterval(interval);
-            }
-          } catch (e) {
-            // ignored
-          }
-        }, 100);
-      })
-  );
-
-  const getSvgForFrames = (frameNames: string[] | undefined) =>
-    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.`
-          );
-        }
-
-        await window.miro.board.deselect();
-
-        for (const { id } of selectedFrames) {
-          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 writeFile(outputFile.replace("{frameName}", frameName), svg);
-    }
-  } else {
-    const svg = await getSvgForFrames(frameNames);
-    if (outputFile) {
-      await writeFile(outputFile, svg);
-    } else {
-      process.stdout.write(svg);
-    }
-  }
-
-  await page.close();
-  await browser.close();
-})();