PLUG-131: Add shareDiagram API to Mermaid Chart SDK

.changeset/fluffy-birds-vanish.md

@@ -0,0 +1,5 @@
+---
+'@mermaidchart/sdk': patch
+---
+
+Added share diagram endpoint for mermaid commercial plugin

packages/sdk/src/index.test.ts

@@ -222,4 +222,54 @@ describe('MermaidChart', () => {
       ).rejects.toThrow(AICreditsLimitExceededError);
     });
   });
+
+  describe('#shareDiagram', () => {
+    beforeEach(async () => {
+      await client.setAccessToken('test-access-token');
+    });
+
+    it('should POST to the document share endpoint with the request body and return response.data', async () => {
+      const jsonResponse = {
+        shareUrl:
+          'https://test.mermaidchart.invalid/app/projects/proj-1/diagrams/doc-123/share/invite/test-token',
+        access: 'View' as const,
+      };
+
+      // eslint-disable-next-line @typescript-eslint/no-explicit-any
+      const postSpy = vi.spyOn((client as any).axios, 'post').mockResolvedValue({
+        data: jsonResponse,
+      });
+
+      const requestBody = { access: 'View' as const };
+
+      const result = await client.shareDiagram('doc-123', requestBody);
+
+      expect(postSpy).toHaveBeenCalledWith(
+        URLS.rest.documents.pick({ documentID: 'doc-123' }).share,
+        requestBody,
+      );
+      expect(result).toEqual(jsonResponse);
+    });
+
+    it('should default to an empty request body when none is provided', async () => {
+      const jsonResponse = {
+        shareUrl:
+          'https://test.mermaidchart.invalid/app/projects/proj-1/diagrams/doc-123/share/invite/test-token',
+        access: 'View' as const,
+      };
+
+      // eslint-disable-next-line @typescript-eslint/no-explicit-any
+      const postSpy = vi.spyOn((client as any).axios, 'post').mockResolvedValue({
+        data: jsonResponse,
+      });
+
+      const result = await client.shareDiagram('doc-123');
+
+      expect(postSpy).toHaveBeenCalledWith(
+        URLS.rest.documents.pick({ documentID: 'doc-123' }).share,
+        {},
+      );
+      expect(result).toEqual(jsonResponse);
+    });
+  });
 });

packages/sdk/src/index.ts

@@ -24,9 +24,13 @@ import type {
   RegenerateDiagramRequest,
   RegenerateDiagramResponse,
   AICreditsUsage,
+  ShareDiagramRequest,
+  ShareDiagramResponse,
 } from './types.js';
 import { URLS } from './urls.js';
 
+export type { ShareDiagramAccess, ShareDiagramRequest, ShareDiagramResponse } from './types.js';
+
 const defaultBaseURL = 'https://www.mermaid.ai'; // "http://127.0.0.1:5174"
 const authorizationURLTimeout = 60_000;
 
@@ -315,6 +319,24 @@ export class MermaidChart {
     return raw.data;
   }
 
+  /**
+   * Generates a copy-link style share URL for a diagram, so it can be shared
+   * with a colleague without opening the Mermaid Chart web app.
+   *
+   * @param documentID - The ID of the document to share.
+   * @param request - Optional access level to grant recipients (defaults to 'View').
+   */
+  public async shareDiagram(
+    documentID: MCDocument['documentID'],
+    request: ShareDiagramRequest = {},
+  ): Promise<ShareDiagramResponse> {
+    const response = await this.axios.post<ShareDiagramResponse>(
+      URLS.rest.documents.pick({ documentID }).share,
+      request,
+    );
+    return response.data;
+  }
+
   /**
    * Repairs a broken Mermaid diagram using AI.
    *

packages/sdk/src/types.ts

@@ -188,6 +188,22 @@ export interface DiagramChatResponse {
   documentChatThreadID?: string;
 }
 
+/**
+ * Access level to grant via a generated share link.
+ */
+export type ShareDiagramAccess = 'Edit' | 'Comment' | 'View';
+
+export interface ShareDiagramRequest {
+  access?: ShareDiagramAccess;
+  emailAddresses?: string[];
+  source?: string;
+}
+
+export interface ShareDiagramResponse {
+  shareUrl: string;
+  access: ShareDiagramAccess;
+}
+
 /**
  * Response from repairing a diagram.
  * Matches OpenAIGenerationResult from collab.

packages/sdk/src/urls.ts

@@ -23,6 +23,7 @@ export const URLS = {
         return {
           presentations: `${baseURL}/presentations`,
           self: baseURL,
+          share: `${baseURL}/share`,
           withVersion: `${baseURL}${queryParams}`,
         };
       },