@cyberismo/backend 1.1.2 → 1.3.0

package/src/domain/cards/index.ts

@@ -1,32 +1,20 @@
-/**
-  Cyberismo
-  Copyright © Cyberismo Ltd and contributors 2025
-  This program is free software: you can redistribute it and/or modify it under
-  the terms of the GNU Affero General Public License version 3 as published by
-  the Free Software Foundation.
-  This program is distributed in the hope that it will be useful, but WITHOUT
-  ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS
-  FOR A PARTICULAR PURPOSE. See the GNU Affero General Public License for more
-  details. You should have received a copy of the GNU Affero General Public
-  License along with this program. If not, see <https://www.gnu.org/licenses/>.
-*/
+// SPDX-FileCopyrightText: Cyberismo Ltd and contributors
+// SPDX-License-Identifier: AGPL-3.0-only
 
 import { type Context, Hono } from 'hono';
-import type { ContentfulStatusCode } from 'hono/utils/http-status';
-import { streamSSE } from 'hono/streaming';
-import { getCardDetails } from './lib.js';
 import * as cardService from './service.js';
 import { isSSGContext, ssgParams } from 'hono/ssg';
 import type { AppContext } from '../../types.js';
 import { UserRole } from '../../types.js';
-import { presenceStore } from './presence.js';
 import { requireRole } from '../../middleware/auth.js';
 import { zValidator } from '../../middleware/zvalidator.js';
 import {
+  cardKeyParamSchema,
   createLinkSchema,
   removeLinkSchema,
   updateLinkSchema,
   exportCardPdfSchema,
+  cardBatchSchema,
   type ExportCardPdfRequestBody,
 } from './schema.js';
 
@@ -47,10 +35,10 @@ const router = new Hono();
  *         description: project_path not set.
  */
 router.get('/', requireRole(UserRole.Reader), async (c) => {
-  const commands = c.get('commands');
+  const ws = c.get('ws');
 
   try {
-    const response = await cardService.getProjectInfo(commands);
+    const response = await cardService.getProjectInfo(ws);
     return c.json(response);
   } catch (error) {
     return c.text(
@@ -102,10 +90,10 @@ router.post(
   requireRole(UserRole.Reader),
   zValidator('json', exportCardPdfSchema),
   async (c) => {
-    const commands = c.get('commands');
+    const ws = c.get('ws');
     const body = (await c.req.json()) as ExportCardPdfRequestBody;
     try {
-      const result = await cardService.exportCard(commands, {
+      const result = await cardService.exportCard(ws, {
         cardKey: body.cardKey,
         title: body.title,
         name: body.name,
@@ -131,64 +119,140 @@ router.post(
   },
 );
 
+/**
+ * @swagger
+ * /api/cards/batch:
+ *   post:
+ *     summary: Returns the card query results of many cards in one solve.
+ *     description: Keys the project does not hold are left out of the response. Not served on the static site.
+ *     requestBody:
+ *       content:
+ *         application/json:
+ *           schema:
+ *             type: object
+ *             properties:
+ *               keys:
+ *                 type: array
+ *                 items:
+ *                   type: string
+ *                 minItems: 1
+ *                 maxItems: 100
+ *     responses:
+ *       200:
+ *         description: Object of card key to QueryResult<'card'>.
+ *       400:
+ *         description: Missing keys or more than 100 keys.
+ */
+router.post(
+  '/batch',
+  requireRole(UserRole.Reader),
+  zValidator('json', cardBatchSchema),
+  async (c) => {
+    const { keys } = c.req.valid('json');
+    return c.json(await cardService.getCardBatch(c.get('ws'), keys));
+  },
+);
+
+const cardKeyParams = ssgParams(async (c: AppContext) => {
+  const ws = c.get('ws');
+  const opts = c.get('tree');
+  const cards = await cardService.findAllCards(ws, opts);
+  return cards.map((card) => ({ key: card.key }));
+});
+
 /**
  * @swagger
  * /api/cards/{key}:
  *   get:
- *     summary: Returns the full content of a specific card including calculations.
- *     description: The key parameter is the unique identifier ("cardKey") of the card. The response includes the content as asciidoc(editable) and parsed html, which also has macros already injected
+ *     summary: Returns the card query result of a specific card.
+ *     description: The key parameter is the unique identifier ("cardKey") of the card. The response holds the calculated card data only; use /content for the rendered content and /source for the stored card.
  *     parameters:
  *       - name: key
  *         in: path
  *         required: true
  *         description: Card key (string)
- *       - name: raw
- *         in: query
- *         required: false
- *         schema:
- *           type: boolean
- *         description: When true, returns the raw card data without triggering calculations
  *     responses:
  *       200:
- *         description: Object containing card details. See lib/api/types.ts/CardResponse for the structure.
+ *         description: The card query result. See QueryResult<'card'> in @cyberismo/model.
  *       400:
- *        description: No search key or card not found with given key
+ *        description: No search key
+ *       404:
+ *        description: Card not found with given key
  *       500:
  *         description: project_path not set.
  */
 router.get(
   '/:key',
   requireRole(UserRole.Reader),
-  ssgParams(async (c: AppContext) => {
-    const commands = c.get('commands');
-    const opts = c.get('tree');
-    const cards = await cardService.findAllCards(commands, opts);
-    return cards.map((card) => ({ key: card.key }));
-  }),
+  cardKeyParams,
+  zValidator('param', cardKeyParamSchema),
   async (c) => {
-    const key = c.req.param('key');
-    if (!key) {
-      return c.text('No search key', 400);
-    }
+    const { key } = c.req.valid('param');
+    return c.json(
+      await cardService.getCardData(c.get('ws'), key, isSSGContext(c)),
+    );
+  },
+);
 
-    const raw = c.req.query('raw');
+/**
+ * @swagger
+ * /api/cards/{key}/content:
+ *   get:
+ *     summary: Returns the content of a specific card as AsciiDoc with its macros evaluated.
+ *     parameters:
+ *       - name: key
+ *         in: path
+ *         required: true
+ *         description: Card key (string)
+ *     responses:
+ *       200:
+ *         description: Object with adocContent.
+ *       400:
+ *        description: No search key
+ *       404:
+ *        description: Card not found with given key
+ */
+router.get(
+  '/:key/content',
+  requireRole(UserRole.Reader),
+  cardKeyParams,
+  zValidator('param', cardKeyParamSchema),
+  async (c) => {
+    const { key } = c.req.valid('param');
+    return c.json(
+      await cardService.getCardContent(c.get('ws'), key, isSSGContext(c)),
+    );
+  },
+);
 
-    const result = await getCardDetails(
-      c.get('commands'),
-      key,
-      isSSGContext(c),
-      raw?.toLowerCase() === 'true' ? true : false,
+/**
+ * @swagger
+ * /api/cards/{key}/source:
+ *   get:
+ *     summary: Returns a specific card as stored, with its unevaluated content, metadata and attachments.
+ *     parameters:
+ *       - name: key
+ *         in: path
+ *         required: true
+ *         description: Card key (string)
+ *     responses:
+ *       200:
+ *         description: The stored card. See Card in @cyberismo/model.
+ *       400:
+ *        description: No search key
+ *       404:
+ *        description: Card not found with given key
+ */
+router.get(
+  '/:key/source',
+  requireRole(UserRole.Reader),
+  cardKeyParams,
+  zValidator('param', cardKeyParamSchema),
+  async (c) => {
+    const { key } = c.req.valid('param');
+    return c.json(
+      await cardService.getCardSource(c.get('ws'), key, isSSGContext(c)),
     );
-    if (result.status === 200) {
-      return c.json(result.data);
-    } else {
-      return c.json(
-        {
-          error: result.message || 'Unknown error',
-        },
-        result.status as ContentfulStatusCode,
-      );
-    }
   },
 );
 
@@ -211,16 +275,10 @@ router.get(
  *         in: body
  *         type: object
  *         required: false
- *         description: New metadata for the card. Must be an object with key-value pairs.
- *       - name: raw
- *         in: query
- *         required: false
- *         schema:
- *           type: boolean
- *         description: When true, returns the raw card data without triggering calculations
+ *         description: New metadata for the card. Must be an object with key-value pairs. Setting a custom field to null or an empty string clears it.
  *     responses:
  *       200:
- *         description: Object containing card details, same as GET. See definitions.ts/CardDetails for the structure.
+ *         description: The updated card query result, same as GET.
  *       207:
  *         description: Partial success. some updates failed, some succeeded. Returns card object with successful updates.
  *       400:
@@ -228,42 +286,27 @@ router.get(
  *       500:
  *         description: project_path not set.
  */
-router.patch('/:key', requireRole(UserRole.Editor), async (c) => {
-  const commands = c.get('commands');
-  const key = c.req.param('key');
-  if (!key) {
-    return c.text('No search key', 400);
-  }
-
-  const raw = c.req.query('raw');
+router.patch(
+  '/:key',
+  requireRole(UserRole.Editor),
+  zValidator('param', cardKeyParamSchema),
+  async (c) => {
+    const ws = c.get('ws');
+    const { key } = c.req.valid('param');
 
-  const body = await c.req.json();
+    const body = await c.req.json();
 
-  try {
-    await cardService.updateCard(commands, key, body);
-    const result = await getCardDetails(
-      c.get('commands'),
-      key,
-      isSSGContext(c),
-      raw?.toLowerCase() === 'true' ? true : false,
-    );
-    if (result.status === 200) {
-      return c.json(result.data);
-    } else {
-      return c.json(
-        {
-          error: result.message || 'Unknown error',
-        },
-        result.status as ContentfulStatusCode,
+    try {
+      await cardService.updateCard(ws, key, body);
+      return c.json(await cardService.getCardData(ws, key, isSSGContext(c)));
+    } catch (error) {
+      return c.text(
+        error instanceof Error ? error.message : 'Unknown error',
+        400,
       );
     }
-  } catch (error) {
-    return c.text(
-      error instanceof Error ? error.message : 'Unknown error',
-      400,
-    );
-  }
-});
+  },
+);
 
 /**
  * @swagger
@@ -286,14 +329,14 @@ router.patch('/:key', requireRole(UserRole.Editor), async (c) => {
  *         description: project_path not set.
  */
 router.delete('/:key', requireRole(UserRole.Editor), async (c) => {
-  const commands = c.get('commands');
+  const ws = c.get('ws');
   const key = c.req.param('key');
   if (!key) {
     return c.text('No search key', 400);
   }
 
   try {
-    await cardService.deleteCard(commands, key);
+    await cardService.deleteCard(ws, key);
     return new Response(null, { status: 204 });
   } catch (error) {
     return c.json(
@@ -341,7 +384,7 @@ router.post('/:key', requireRole(UserRole.Editor), async (c) => {
 
   try {
     const result = await cardService.createCard(
-      c.get('commands'),
+      c.get('ws'),
       body.template,
       key,
     );
@@ -385,7 +428,7 @@ router.post('/:key', requireRole(UserRole.Editor), async (c) => {
  *         description: Server error
  */
 router.post('/:key/attachments', requireRole(UserRole.Editor), async (c) => {
-  const commands = c.get('commands');
+  const ws = c.get('ws');
   const key = c.req.param('key');
 
   try {
@@ -396,7 +439,7 @@ router.post('/:key/attachments', requireRole(UserRole.Editor), async (c) => {
     }
 
     const result = await cardService.uploadAttachments(
-      commands,
+      ws,
       key,
       files as File[],
     );
@@ -442,15 +485,11 @@ router.delete(
   '/:key/attachments/:filename',
   requireRole(UserRole.Editor),
   async (c) => {
-    const commands = c.get('commands');
+    const ws = c.get('ws');
     const { key, filename } = c.req.param();
 
     try {
-      const result = await cardService.removeAttachment(
-        commands,
-        key,
-        filename,
-      );
+      const result = await cardService.removeAttachment(ws, key, filename);
       return c.json(result);
     } catch (error) {
       return c.json(
@@ -466,54 +505,6 @@ router.delete(
   },
 );
 
-/**
- * @swagger
- * /api/cards/{key}/attachments/{filename}/open:
- *   post:
- *     summary: Open an attachment using the system's default application
- *     parameters:
- *       - name: key
- *         in: path
- *         required: true
- *         schema:
- *           type: string
- *       - name: filename
- *         in: path
- *         required: true
- *         schema:
- *           type: string
- *     responses:
- *       200:
- *         description: Attachment opened successfully
- *       400:
- *         description: Invalid request
- *       500:
- *         description: Server error
- */
-router.post(
-  '/:key/attachments/:filename/open',
-  requireRole(UserRole.Reader),
-  async (c) => {
-    const commands = c.get('commands');
-    const { key, filename } = c.req.param();
-
-    try {
-      const result = await cardService.openAttachment(commands, key, filename);
-      return c.json(result);
-    } catch (error) {
-      return c.json(
-        {
-          error:
-            error instanceof Error
-              ? error.message
-              : 'Failed to open attachment',
-        },
-        500,
-      );
-    }
-  },
-);
-
 /**
  * @swagger
  * /api/cards/{key}/parse:
@@ -542,7 +533,7 @@ router.post(
  *         description: Server error
  */
 router.post('/:key/parse', requireRole(UserRole.Reader), async (c) => {
-  const commands = c.get('commands');
+  const ws = c.get('ws');
   const key = c.req.param('key');
   const { content } = await c.req.json();
 
@@ -551,7 +542,7 @@ router.post('/:key/parse', requireRole(UserRole.Reader), async (c) => {
   }
 
   try {
-    const result = await cardService.parseContent(commands, key, content);
+    const result = await cardService.parseContent(ws, key, content);
     return c.json(result);
   } catch (error) {
     return c.json(
@@ -600,13 +591,13 @@ router.post(
   requireRole(UserRole.Editor),
   zValidator('json', createLinkSchema),
   async (c) => {
-    const commands = c.get('commands');
+    const ws = c.get('ws');
     const key = c.req.param('key');
     const { toCard, linkType, description, direction } = c.req.valid('json');
 
     try {
       const result = await cardService.createLink(
-        commands,
+        ws,
         key,
         toCard,
         linkType,
@@ -662,13 +653,13 @@ router.delete(
   requireRole(UserRole.Editor),
   zValidator('json', removeLinkSchema),
   async (c) => {
-    const commands = c.get('commands');
+    const ws = c.get('ws');
     const key = c.req.param('key');
     const { toCard, linkType, description, direction } = c.req.valid('json');
 
     try {
       const result = await cardService.removeLink(
-        commands,
+        ws,
         key,
         toCard,
         linkType,
@@ -734,7 +725,7 @@ router.put(
   requireRole(UserRole.Editor),
   zValidator('json', updateLinkSchema),
   async (c) => {
-    const commands = c.get('commands');
+    const ws = c.get('ws');
     const key = c.req.param('key');
 
     const {
@@ -750,7 +741,7 @@ router.put(
 
     try {
       const result = await cardService.updateLink(
-        commands,
+        ws,
         key,
         toCard,
         linkType,
@@ -802,11 +793,11 @@ router.get(
   '/:key/a/:attachment',
   requireRole(UserRole.Reader),
   ssgParams(async (c: Context) => {
-    const commands = c.get('commands');
-    return await cardService.findRelevantAttachments(commands, c.get('tree'));
+    const ws = c.get('ws');
+    return await cardService.findRelevantAttachments(ws, c.get('tree'));
   }),
   async (c) => {
-    const commands = c.get('commands');
+    const ws = c.get('ws');
     const { key, attachment } = c.req.param();
     const filename = decodeURI(attachment);
 
@@ -816,7 +807,7 @@ router.get(
 
     try {
       const attachmentResponse = await cardService.getAttachment(
-        commands,
+        ws,
         key,
         filename,
       );
@@ -843,55 +834,4 @@ router.get(
     }
   },
 );
-/**
- * @swagger
- * /api/cards/{key}/presence:
- *   get:
- *     summary: SSE stream of users currently viewing or editing this card
- *     parameters:
- *       - name: key
- *         in: path
- *         required: true
- *         description: Card key (string)
- *       - name: mode
- *         in: query
- *         required: false
- *         schema:
- *           type: string
- *           enum: [viewing, editing]
- *         description: Whether the user is viewing or editing (default: viewing)
- *     responses:
- *       200:
- *         description: SSE stream with presence events
- */
-router.get('/:key/presence', requireRole(UserRole.Reader), (c) => {
-  const key = c.req.param('key');
-  const mode = c.req.query('mode') === 'editing' ? 'editing' : 'viewing';
-  const user = c.get('user');
-
-  if (!key) {
-    return c.text('No card key', 400);
-  }
-
-  return streamSSE(c, async (stream) => {
-    const connId = presenceStore.add(
-      key,
-      user,
-      mode,
-      (data) => void stream.writeSSE(data),
-    );
-
-    let aborted = false;
-    stream.onAbort(() => {
-      aborted = true;
-      presenceStore.remove(key, connId);
-    });
-
-    // Keep connection alive with periodic heartbeat
-    while (!aborted) {
-      await stream.write(': hb\n\n');
-      await stream.sleep(30000);
-    }
-  });
-});
 export default router;