Add the getDiagram(diagramID) API function to the SDK

openapi.yml

@@ -54,9 +54,9 @@ components:
         projectID:
           type: string
         major:
-          type: string
+          type: integer
         minor:
-          type: string
+          type: integer
         title:
           type: string
       required:
@@ -160,6 +160,43 @@ paths:
             application/json:
               schema:
                 $ref: '#/components/schemas/Document'
+
+  /rest-api/documents/{documentID}:
+    get:
+      tags:
+        - document
+      summary: Gets the given diagram
+      operationId: getDocument
+      parameters:
+        - name: documentID
+          in: path
+          required: true
+          description: The ID of the document to get diagram data for
+          schema:
+            type: string
+        - name: version
+          in: query
+          required: false
+          description: |
+            The version of the document to get diagram data for.
+
+            If not set, defaults to the highest version.
+          schema:
+            type: string
+          example: v0.1
+      security:
+        - mermaidchart_auth:
+          - read
+      responses:
+        '200':
+          description: OK
+          content:
+            application/json:
+              schema:
+                $ref: '#/components/schemas/Document'
+        '404':
+          description: File Not Found
+
   /raw/{documentID}:
     get:
       tags:

packages/sdk/CHANGELOG.md

@@ -8,6 +8,11 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 ### Added
 
 - Compile an ESM version of this codebase for Node.JS v18.
+- Add `MermaidChart#getDiagram(diagramID)` function to get a diagram.
+
+### Fixed
+
+- Fix `MCDocument` `major`/`minor` type to `number`.
 
 ## [0.1.1] - 2023-09-08
 

packages/sdk/src/index.e2e.test.ts

@@ -5,6 +5,7 @@ import { MermaidChart } from './index.js';
 import { beforeAll, describe, expect, it } from 'vitest';
 
 import process from 'node:process';
+import { AxiosError } from 'axios';
 
 let client: MermaidChart;
 
@@ -32,3 +33,43 @@ describe('getUser', () => {
     expect(user).toHaveProperty('emailAddress');
   });
 });
+
+const documentMatcher = expect.objectContaining({
+  documentID: expect.any(String),
+  major: expect.any(Number),
+  minor: expect.any(Number),
+});
+
+describe("getDocument", () => {
+  it("should get publicly shared diagram", async() => {
+    const latestDocument = await client.getDocument({
+      // owned by [email protected]
+      documentID: '8bce727b-69b7-4f6e-a434-d578e2b363ff',
+    });
+
+    expect(latestDocument).toStrictEqual(documentMatcher);
+
+    const earliestDocument = await client.getDocument({
+      // owned by [email protected]
+      documentID: '8bce727b-69b7-4f6e-a434-d578e2b363ff',
+      major: 0,
+      minor: 1,
+    });
+
+    expect(earliestDocument).toStrictEqual(documentMatcher);
+  });
+
+  it("should throw 404 on unknown document", async() => {
+    let error: AxiosError | undefined = undefined;
+    try {
+      await client.getDocument({
+        documentID: '00000000-0000-0000-0000-0000deaddead',
+      });
+    } catch (err) {
+      error = err as AxiosError;
+    }
+
+    expect(error).toBeInstanceOf(AxiosError);
+    expect(error?.response?.status).toBe(404);
+  });
+});

packages/sdk/src/index.ts

@@ -180,6 +180,13 @@ export class MermaidChart {
     return url;
   }
 
+  public async getDocument(
+    document: Pick<MCDocument, 'documentID'> | Pick<MCDocument, 'documentID' | 'major' | 'minor'>,
+  ) {
+    const {data} =  await this.axios.get<MCDocument>(URLS.rest.documents.pick(document).self);
+    return data;
+  }
+
   public async getRawDocument(
     document: Pick<MCDocument, 'documentID' | 'major' | 'minor'>,
     theme: 'light' | 'dark',

packages/sdk/src/types.ts

@@ -31,8 +31,8 @@ export interface MCProject {
 export interface MCDocument {
   documentID: string;
   projectID: string;
-  major: string;
-  minor: string;
+  major: number;
+  minor: number;
   title: string;
 }
 

packages/sdk/src/urls.ts

@@ -6,6 +6,25 @@ export const URLS = {
     token: `/oauth/token`,
   },
   rest: {
+    documents: {
+      pick: (opts: Pick<MCDocument, 'documentID'> | Pick<MCDocument, 'documentID' | 'major' | 'minor'>) => {
+        const {documentID} = opts;
+        let queryParams = "";
+
+        if ('major' in opts) {
+          const {major, minor} = opts;
+
+          queryParams = `v${major ?? 0}.${minor ?? 1}`;
+        }
+
+        const baseURL = `/rest-api/documents/${documentID}`;
+        return {
+          presentations: `${baseURL}/presentations`,
+          self: baseURL,
+          withVersion: `${baseURL}${queryParams}`
+        };
+      }
+    },
     users: {
       self: `/rest-api/users/me`,
     },