Merge pull request #11 from Mermaid-Chart/feat/add-setDocument-to-sdk

feat: add `setDocument(document)` API function

Author: aloisklink

openapi.yml

@@ -78,6 +78,12 @@ components:
           format: uuid
           description: |
             The id of this diagram, required for `setDocument()`.
+        code:
+          type: string
+          description: |
+            The Mermaid
+            [`application/vnd.mermaid`](https://www.iana.org/assignments/media-types/application/vnd.mermaid)
+            code for this diagram.
       required:
         - documentID
         - id
@@ -246,6 +252,42 @@ paths:
                 $ref: '#/components/schemas/MCDocument'
         '404':
           description: File Not Found
+    put:
+      tags:
+        - document
+      summary: Update the given document.
+      operationId: setDocument
+      parameters:
+        - name: documentID
+          in: path
+          required: true
+          description: The ID of the document to update.
+          schema:
+            type: string
+      requestBody:
+        description: Document and diagram settings to update.
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: '#/components/schemas/MCDocument'
+      security:
+        - mermaidchart_auth: []
+      responses:
+        '200':
+          description: |
+            Update status.
+          content:
+            application/json:
+              schema:
+                type: object
+                # TODO: update this once MC-1060 is fixed.
+                # properties:
+                #   result:
+                #     type: string
+                #     enum:
+                #       - ok
+                #       - failed
     delete:
       tags:
         - document

packages/sdk/CHANGELOG.md

@@ -10,11 +10,13 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - Compile an ESM version of this codebase for Node.JS v18.
 - Add `MermaidChart#getDiagram(diagramID)` function to get a diagram.
 - Add `MermaidChart#createDocument(projectID)` function to create a digram in a project.
+- Add `MermaidChart#setDocument(document)` function to update a diagram.
 - Add `MermaidChart#deleteDocument(documentID)` function to delete a diagram.
 
 ### Fixed
 
 - Fix `MCDocument` `major`/`minor` type to `number`.
+- Add `code` field to `MCDocument` type
 
 ### Fixed
 

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

@@ -74,6 +74,43 @@ describe('createDocument', () => {
   });
 });
 
+describe('setDocument', () => {
+  it('should set document', async() => {
+    const newDocument = await client.createDocument(testProjectId);
+    documentsToDelete.add(newDocument.documentID);
+
+    const code = `flowchart LR
+    A(Generated by<br><code>@mermaidchart/sdk</code><br>E2E tests)`;
+
+    await client.setDocument({
+      documentID: newDocument.documentID,
+      id: newDocument.id, // diagram ID
+      title: "@mermaidchart/sdk E2E test diagram",
+      code,
+    });
+
+    const updatedDoc = await client.getDocument({
+      documentID: newDocument.documentID,
+    });
+    expect(updatedDoc).toMatchObject({
+      title: "@mermaidchart/sdk E2E test diagram",
+      code,
+    });
+  });
+
+  // TODO: this function never seems to return an error, see MC-1060
+  it.skip('should throw an error on invalid data', async() => {
+    const newDocument = await client.createDocument(testProjectId);
+    documentsToDelete.add(newDocument.documentID);
+
+    await expect(client.setDocument({
+      documentID: newDocument.documentID,
+      // @ts-expect-error not setting diagram `id` should throw an error
+      id: null,
+    })).rejects.toThrowError("400"); // should throw HTTP 400 error
+  });
+});
+
 describe('deleteDocument', () => {
   it('should delete document', async() => {
     const newDocument = await client.createDocument(testProjectId);

packages/sdk/src/index.ts

@@ -204,6 +204,26 @@ export class MermaidChart {
     return data;
   }
 
+  /**
+   * Update the given document.
+   *
+   * @param document The document to update.
+   */
+  public async setDocument(
+    document: Pick<MCDocument, 'id' | 'documentID'> & Partial<MCDocument>,
+  ) {
+    const {data} = await this.axios.put<{result: "ok"} | {result: "failed", error: any}>(
+      URLS.rest.documents.pick(document).self,
+      document,
+    );
+
+    if (data.result === "failed") {
+      throw new Error(
+        `setDocument(${JSON.stringify({documentID: document.documentID})} failed due to ${JSON.stringify(data.error)}`
+      );
+    }
+  }
+
   /**
    * Delete the given document.
    * @param documentID The ID of the document to delete.

packages/sdk/src/types.ts

@@ -51,6 +51,12 @@ export interface DiagramDocument {
   documentID: string;
   major: number;
   minor: number;
+  /**
+   * The Mermaid
+   * [`application/vnd.mermaid`](https://www.iana.org/assignments/media-types/application/vnd.mermaid)
+   * code for this diagram.
+   */
+  code?: string;
 }
 
 export interface AuthorizationData {