✨(api) add API route to fetch document content

This allows API users to process document content, enabling the
use of Docs as a headless CMS for instance, or any kind of document
processing. Fixes #1206.

src/frontend/servers/y-provider/__tests__/content.test.ts

@@ -0,0 +1,207 @@
+import { ServerBlockNoteEditor } from '@blocknote/server-util';
+import request from 'supertest';
+import { describe, expect, test, vi } from 'vitest';
+import * as Y from 'yjs';
+
+vi.mock('../src/env', async (importOriginal) => {
+  return {
+    ...(await importOriginal()),
+    COLLABORATION_SERVER_ORIGIN: 'http://localhost:3000',
+    Y_PROVIDER_API_KEY: 'yprovider-api-key',
+  };
+});
+
+import { initApp } from '@/servers';
+
+import {
+  Y_PROVIDER_API_KEY as apiKey,
+  COLLABORATION_SERVER_ORIGIN as origin,
+} from '../src/env';
+
+console.error = vi.fn();
+
+describe('Content API Tests', () => {
+  test('POST /api/content with incorrect API key responds with 401', async () => {
+    const app = initApp();
+
+    const response = await request(app)
+      .post('/api/content')
+      .set('origin', origin)
+      .set('authorization', 'wrong-api-key')
+      .set('content-type', 'application/json')
+      .send({
+        content: 'dGVzdA==', // base64 for "test"
+        format: 'json',
+      });
+
+    expect(response.status).toBe(401);
+    expect(response.body).toStrictEqual({
+      error: 'Unauthorized: Invalid API Key',
+    });
+  });
+
+  test('POST /api/content with incorrect Bearer token responds with 401', async () => {
+    const app = initApp();
+
+    const response = await request(app)
+      .post('/api/content')
+      .set('origin', origin)
+      .set('authorization', 'Bearer test-secret-api-key')
+      .set('content-type', 'application/json')
+      .send({
+        content: 'dGVzdA==', // base64 for "test"
+        format: 'json',
+      });
+
+    expect(response.status).toBe(401);
+    expect(response.body).toStrictEqual({
+      error: 'Unauthorized: Invalid API Key',
+    });
+  });
+
+  test('POST /api/content with missing content parameter', async () => {
+    const app = initApp();
+
+    const response = await request(app)
+      .post('/api/content')
+      .set('origin', origin)
+      .set('authorization', apiKey)
+      .set('content-type', 'application/json')
+      .send({
+        format: 'json',
+      });
+
+    expect(response.status).toBe(400);
+    expect(response.body).toStrictEqual({
+      error: 'Invalid request: missing content',
+    });
+  });
+
+  test('POST /api/content with empty content', async () => {
+    const app = initApp();
+
+    const response = await request(app)
+      .post('/api/content')
+      .set('origin', origin)
+      .set('authorization', apiKey)
+      .set('content-type', 'application/json')
+      .send({
+        content: '',
+        format: 'json',
+      });
+
+    expect(response.status).toBe(400);
+    expect(response.body).toStrictEqual({
+      error: 'Invalid request: missing content',
+    });
+  });
+
+  test('POST /api/content with missing format parameter', async () => {
+    const app = initApp();
+
+    const response = await request(app)
+      .post('/api/content')
+      .set('origin', origin)
+      .set('authorization', apiKey)
+      .set('content-type', 'application/json')
+      .send({
+        content: 'dGVzdA==',
+      });
+
+    expect(response.status).toBe(400);
+    expect(response.body).toStrictEqual({
+      error: 'Invalid format. Must be one of: json, markdown, html',
+    });
+  });
+
+  test('POST /api/content with invalid format', async () => {
+    const app = initApp();
+
+    const response = await request(app)
+      .post('/api/content')
+      .set('origin', origin)
+      .set('authorization', apiKey)
+      .set('content-type', 'application/json')
+      .send({
+        content: 'dGVzdA==',
+        format: 'invalid',
+      });
+
+    expect(response.status).toBe(400);
+    expect(response.body).toStrictEqual({
+      error: 'Invalid format. Must be one of: json, markdown, html',
+    });
+  });
+
+  test.each([
+    { authHeader: `Bearer ${apiKey}`, format: 'json' },
+    { authHeader: `Bearer ${apiKey}`, format: 'markdown' },
+    { authHeader: `Bearer ${apiKey}`, format: 'html' },
+  ])(
+    'POST /api/content with correct content and format $format with Authorization: $authHeader',
+    async ({ authHeader, format }) => {
+      const app = initApp();
+
+      // Create a simple Yjs document for testing using BlockNote
+      const editor = ServerBlockNoteEditor.create();
+      const markdownContent = '# Test Document\n\nThis is test content.';
+      const blocks = await editor.tryParseMarkdownToBlocks(markdownContent);
+      const yDocument = editor.blocksToYDoc(blocks, 'document-store');
+      const yjsUpdate = Y.encodeStateAsUpdate(yDocument);
+      const base64Content = Buffer.from(yjsUpdate).toString('base64');
+
+      const response = await request(app)
+        .post('/api/content')
+        .set('Origin', origin)
+        .set('Authorization', authHeader)
+        .set('content-type', 'application/json')
+        .send({
+          content: base64Content,
+          format: format,
+        });
+      expect(response.status).toBe(200);
+      expect(response.body).toHaveProperty('content');
+      expect(response.body).toHaveProperty('format', format);
+
+      // Verify the content based on format
+      if (format === 'json') {
+        const parsedContent = response.body.content;
+        expect(Array.isArray(parsedContent)).toBe(true);
+        expect(parsedContent.length).toBe(2);
+        expect(parsedContent[0].type).toBe('heading');
+        expect(parsedContent[1].type).toBe('paragraph');
+        expect(parsedContent[0].content[0].type).toBe('text');
+        expect(parsedContent[0].content[0].text).toBe('Test Document');
+        expect(parsedContent[1].content[0].type).toBe('text');
+        expect(parsedContent[1].content[0].text).toBe('This is test content.');
+      } else if (format === 'markdown') {
+        expect(typeof response.body.content).toBe('string');
+        expect(response.body.content.trim()).toBe(markdownContent);
+      } else if (format === 'html') {
+        expect(typeof response.body.content).toBe('string');
+        expect(response.body.content).toBe(
+          '<h1>Test Document</h1><p>This is test content.</p>',
+        );
+      }
+    },
+  );
+
+  test('POST /api/content with invalid base64 content returns 500', async () => {
+    const app = initApp();
+
+    const response = await request(app)
+      .post('/api/content')
+      .set('origin', origin)
+      .set('authorization', apiKey)
+      .set('content-type', 'application/json')
+      .send({
+        content: 'invalid-base64-content!@#',
+        format: 'json',
+      });
+
+    expect(response.status).toBe(500);
+    expect(response.body).toStrictEqual({
+      error: 'An error occurred during conversion',
+    });
+  });
+});

src/frontend/servers/y-provider/package.json

@@ -10,7 +10,7 @@
     "dev": "cross-env COLLABORATION_LOGGING=true && nodemon --config nodemon.json",
     "start": "node ./dist/start-server.js",
     "lint": "eslint . --ext .ts",
-    "test": "vitest --run"
+    "test": "vitest --run --disable-console-intercept"
   },
   "engines": {
     "node": ">=22"

src/frontend/servers/y-provider/src/handlers/contentHandler.ts

@@ -0,0 +1,71 @@
+import { PartialBlock } from '@blocknote/core';
+import { ServerBlockNoteEditor } from '@blocknote/server-util';
+import { Request, Response } from 'express';
+import * as Y from 'yjs';
+
+import { logger } from '@/utils';
+
+interface ErrorResponse {
+  error: string;
+}
+
+interface ContentRequest {
+  content: string;
+  format: string;
+}
+
+const editor = ServerBlockNoteEditor.create();
+
+export const contentHandler = async (
+  req: Request<object, object | ErrorResponse, ContentRequest, object>,
+  res: Response<object | ErrorResponse>,
+) => {
+  const { content, format } = req.body;
+
+  if (!content) {
+    res.status(400).json({ error: 'Invalid request: missing content' });
+    return;
+  }
+
+  if (!format || !['json', 'markdown', 'html'].includes(format)) {
+    res
+      .status(400)
+      .json({ error: 'Invalid format. Must be one of: json, markdown, html' });
+    return;
+  }
+
+  try {
+    // Decode base64 content to Uint8Array
+    const uint8Array = new Uint8Array(Buffer.from(content, 'base64'));
+
+    // Create Yjs document and apply the update
+    const yDocument = new Y.Doc();
+    Y.applyUpdate(yDocument, uint8Array);
+
+    // Convert to blocks
+    const blocks = editor.yDocToBlocks(yDocument, 'document-store');
+
+    let result: string | object | null;
+
+    if (!blocks || blocks.length === 0) {
+      result = null;
+    } else if (format === 'json') {
+      result = blocks;
+    } else if (format === 'markdown') {
+      result = await editor.blocksToMarkdownLossy(blocks as PartialBlock[]);
+    } else if (format === 'html') {
+      result = await editor.blocksToHTMLLossy(blocks as PartialBlock[]);
+    } else {
+      res.status(400).json({ error: 'Unsupported format' });
+      return;
+    }
+
+    res.status(200).json({
+      content: result,
+      format: format,
+    });
+  } catch (e) {
+    logger('content conversion failed:', e);
+    res.status(500).json({ error: 'An error occurred during conversion' });
+  }
+};

src/frontend/servers/y-provider/src/handlers/index.ts

@@ -1,4 +1,5 @@
 export * from './collaborationResetConnectionsHandler';
 export * from './collaborationWSHandler';
 export * from './convertHandler';
+export * from './contentHandler';
 export * from './getDocumentConnectionInfoHandler';

src/frontend/servers/y-provider/src/routes.ts

@@ -2,5 +2,6 @@ export const routes = {
   COLLABORATION_WS: '/collaboration/ws/',
   COLLABORATION_RESET_CONNECTIONS: '/collaboration/api/reset-connections/',
   CONVERT: '/api/convert/',
+  CONTENT: '/api/content/',
   COLLABORATION_GET_CONNECTIONS: '/collaboration/api/get-connections/',
 };

src/frontend/servers/y-provider/src/servers/appServer.ts

@@ -8,6 +8,7 @@ import expressWebsockets from 'express-ws';
 import {
   collaborationResetConnectionsHandler,
   collaborationWSHandler,
+  contentHandler,
   convertHandler,
   getDocumentConnectionInfoHandler,
 } from '@/handlers';
@@ -61,6 +62,11 @@ export const initApp = () => {
     convertHandler,
   );
 
+  /**
+   * Route to convert base64 Yjs content to different formats
+   */
+  app.post(routes.CONTENT, httpSecurity, express.json(), contentHandler);
+
   Sentry.setupExpressErrorHandler(app);
 
   app.get('/ping', (req, res) => {