@plandesk/api 0.9.0 → 0.11.0

package/dist/events.d.ts

@@ -15,14 +15,18 @@ export type DocumentCreatedEvent = {
 export type CommentCreatedEvent = {
     type: 'comment_created';
     commentId: string;
-    documentId: string;
     projectId: string;
+    target_type: string;
+    target_id: string;
+    documentId?: string;
 };
 export type CommentUpdatedEvent = {
     type: 'comment_updated';
     commentId: string;
-    documentId: string;
     projectId: string;
+    target_type: string;
+    target_id: string;
+    documentId?: string;
 };
 export type FolderCreatedEvent = {
     type: 'folder_created';

package/dist/routes/comments.js

@@ -1,19 +1,70 @@
 import { Hono } from 'hono';
-import { InvalidCommentError } from '../services/comments.js';
+import { InvalidCommentError, } from '../services/comments.js';
 function parseIncludeResolved(value) {
     return value === 'true';
 }
+async function handleCreateComment(c, commentService, target) {
+    const body = await c.req.json();
+    if (typeof body.body !== 'string') {
+        return c.json({ error: 'invalid_argument' }, 400);
+    }
+    try {
+        const comment = commentService.create(target, {
+            body: body.body,
+            passage: body.passage,
+            anchor: body.anchor,
+        });
+        if (!comment) {
+            return c.json({ error: 'not_found' }, 404);
+        }
+        return c.json(comment, 201);
+    }
+    catch (error) {
+        if (error instanceof InvalidCommentError) {
+            return c.json({ error: 'invalid_argument' }, 400);
+        }
+        throw error;
+    }
+}
+function handleListComments(c, commentService, target) {
+    const includeResolved = parseIncludeResolved(c.req.query('include_resolved'));
+    const comments = commentService.listByTarget(target, { includeResolved });
+    if (!comments) {
+        return c.json({ error: 'not_found' }, 404);
+    }
+    return c.json(comments);
+}
 export function createCommentsRouter(commentService) {
     const router = new Hono();
-    router.post('/documents/:id/comments', async (c) => {
+    router.post('/documents/:id/comments', (c) => handleCreateComment(c, commentService, { type: 'document', id: c.req.param('id') }));
+    router.get('/documents/:id/comments', (c) => handleListComments(c, commentService, { type: 'document', id: c.req.param('id') }));
+    router.post('/tasks/:id/comments', (c) => handleCreateComment(c, commentService, { type: 'task', id: c.req.param('id') }));
+    router.get('/tasks/:id/comments', (c) => handleListComments(c, commentService, { type: 'task', id: c.req.param('id') }));
+    router.post('/notes/:id/comments', (c) => handleCreateComment(c, commentService, { type: 'note', id: c.req.param('id') }));
+    router.get('/notes/:id/comments', (c) => handleListComments(c, commentService, { type: 'note', id: c.req.param('id') }));
+    router.post('/submissions/:id/comments', (c) => handleCreateComment(c, commentService, { type: 'submission', id: c.req.param('id') }));
+    router.get('/submissions/:id/comments', (c) => handleListComments(c, commentService, { type: 'submission', id: c.req.param('id') }));
+    router.get('/projects/:id/comments', (c) => {
+        const includeResolved = parseIncludeResolved(c.req.query('include_resolved'));
+        const comments = commentService.listByProject(c.req.param('id'), { includeResolved });
+        if (!comments) {
+            return c.json({ error: 'not_found' }, 404);
+        }
+        return c.json(comments);
+    });
+    // Artifact comments are project-scoped. The file identity (content-hash+path,
+    // which may contain slashes) travels in the JSON body / query, not a path
+    // segment, so it never collides with routing.
+    router.post('/projects/:id/artifact-comments', async (c) => {
         const body = await c.req.json();
-        if (typeof body.body !== 'string') {
+        if (typeof body.body !== 'string' || typeof body.artifact_id !== 'string') {
             return c.json({ error: 'invalid_argument' }, 400);
         }
         try {
-            const comment = commentService.create(c.req.param('id'), {
+            const comment = commentService.createForArtifact(c.req.param('id'), body.artifact_id, {
                 body: body.body,
                 passage: body.passage,
+                anchor: body.anchor,
             });
             if (!comment) {
                 return c.json({ error: 'not_found' }, 404);
@@ -27,17 +78,15 @@ export function createCommentsRouter(commentService) {
             throw error;
         }
     });
-    router.get('/documents/:id/comments', (c) => {
-        const includeResolved = parseIncludeResolved(c.req.query('include_resolved'));
-        const comments = commentService.listByDocument(c.req.param('id'), { includeResolved });
-        if (!comments) {
-            return c.json({ error: 'not_found' }, 404);
+    router.get('/projects/:id/artifact-comments', (c) => {
+        const artifactId = c.req.query('artifact_id');
+        if (artifactId === undefined || artifactId === '') {
+            return c.json({ error: 'invalid_argument' }, 400);
         }
-        return c.json(comments);
-    });
-    router.get('/projects/:id/comments', (c) => {
         const includeResolved = parseIncludeResolved(c.req.query('include_resolved'));
-        const comments = commentService.listByProject(c.req.param('id'), { includeResolved });
+        const comments = commentService.listForArtifact(c.req.param('id'), artifactId, {
+            includeResolved,
+        });
         if (!comments) {
             return c.json({ error: 'not_found' }, 404);
         }

package/dist/serialize.d.ts

@@ -1,4 +1,4 @@
-import type { AgentRun, AgentRunEvent, Document, DocumentComment, Edge, Folder, Goal, Note, Project, Tag, Task, TaskStatus } from '@plandesk/db';
+import type { AgentRun, AgentRunEvent, Document, Comment, Edge, Folder, Goal, Note, Project, Tag, Task, TaskStatus } from '@plandesk/db';
 export type PaginationParams = {
     limit?: number;
     offset?: number;
@@ -91,13 +91,16 @@ export type SerializedNote = {
 export declare function serializeNote(note: Note): SerializedNote;
 export type SerializedComment = {
     id: string;
-    document_id: string;
+    target_type: Comment['targetType'];
+    target_id: string;
+    document_id: string | null;
     passage: string | null;
+    anchor: string | null;
     body: string;
     resolved: boolean;
     created_at: string;
 };
-export declare function serializeComment(comment: DocumentComment): SerializedComment;
+export declare function serializeComment(comment: Comment): SerializedComment;
 export declare function buildDocumentTree(documents: Document[]): SerializedDocumentTree[];
 export type SerializedFolder = {
     id: string;

package/dist/serialize.js

@@ -123,8 +123,11 @@ export function serializeNote(note) {
 export function serializeComment(comment) {
     return {
         id: comment.id,
-        document_id: comment.documentId,
+        target_type: comment.targetType,
+        target_id: comment.targetId,
+        document_id: comment.targetType === 'document' ? comment.targetId : null,
         passage: comment.passage,
+        anchor: comment.anchor,
         body: comment.body,
         resolved: comment.resolved,
         created_at: comment.createdAt.toISOString(),

package/dist/services/comments.d.ts

@@ -1,13 +1,18 @@
-import { type Db } from '@plandesk/db';
+import { type CommentTargetType, type Db } from '@plandesk/db';
 import type { EventBus } from '../events.js';
 import { type SerializedComment } from '../serialize.js';
 export type CommentServiceDeps = {
     db: Db;
     eventBus: EventBus;
 };
+export type CommentTarget = {
+    type: CommentTargetType;
+    id: string;
+};
 export type CreateCommentInput = {
     body: string;
     passage?: string | null;
+    anchor?: string | null;
 };
 export type UpdateCommentInput = {
     body?: string;
@@ -17,7 +22,15 @@ export declare class InvalidCommentError extends Error {
     constructor(message: string);
 }
 export declare function createCommentService(deps: CommentServiceDeps): {
-    create(documentId: string, input: CreateCommentInput): SerializedComment | undefined;
+    create(target: CommentTarget, input: CreateCommentInput): SerializedComment | undefined;
+    createForArtifact(projectId: string, artifactId: string, input: CreateCommentInput): SerializedComment | undefined;
+    listForArtifact(projectId: string, artifactId: string, options?: {
+        includeResolved?: boolean;
+    }): SerializedComment[] | undefined;
+    listByTarget(target: CommentTarget, options?: {
+        includeResolved?: boolean;
+    }): SerializedComment[] | undefined;
+    resolveTargetProjectId(target: CommentTarget): string | undefined;
     listByDocument(documentId: string, options?: {
         includeResolved?: boolean;
     }): SerializedComment[] | undefined;

package/dist/services/comments.js

@@ -1,4 +1,4 @@
-import { createDocumentComment, deleteDocumentComment as dbDeleteDocumentComment, getDocument as dbGetDocument, getDocumentComment as dbGetDocumentComment, getProject, listCommentsByDocument as dbListCommentsByDocument, listCommentsByProject as dbListCommentsByProject, updateDocumentComment as dbUpdateDocumentComment, } from '@plandesk/db';
+import { createComment, deleteComment as dbDeleteComment, getComment as dbGetComment, getDocument as dbGetDocument, getNote as dbGetNote, getProject, getSubmission, getTask, listCommentsByProject as dbListCommentsByProject, listCommentsByTarget as dbListCommentsByTarget, updateComment as dbUpdateComment, } from '@plandesk/db';
 import { serializeComment } from '../serialize.js';
 export class InvalidCommentError extends Error {
     constructor(message) {
@@ -11,34 +11,104 @@ function assertNonEmptyBody(body) {
         throw new InvalidCommentError('Comment body must not be empty');
     }
 }
+function targetProjectId(db, target) {
+    switch (target.type) {
+        case 'document':
+            return dbGetDocument(db, target.id)?.projectId;
+        case 'task':
+            return getTask(db, target.id)?.projectId;
+        case 'note':
+            return dbGetNote(db, target.id)?.projectId;
+        case 'submission':
+            return getSubmission(db, target.id)?.projectId;
+        case 'artifact':
+            // An artifact is a file on disk, not a DB entity — its project is
+            // supplied by the caller (the connected repo's project), not resolved
+            // from the target id. Artifact comments go through createForArtifact.
+            return undefined;
+    }
+}
+function emitCommentCreated(eventBus, commentId, projectId, target) {
+    eventBus.emit({
+        type: 'comment_created',
+        commentId,
+        projectId,
+        target_type: target.type,
+        target_id: target.id,
+        ...(target.type === 'document' ? { documentId: target.id } : {}),
+    });
+}
+function emitCommentUpdated(eventBus, commentId, projectId, target) {
+    eventBus.emit({
+        type: 'comment_updated',
+        commentId,
+        projectId,
+        target_type: target.type,
+        target_id: target.id,
+        ...(target.type === 'document' ? { documentId: target.id } : {}),
+    });
+}
 export function createCommentService(deps) {
     const { db, eventBus } = deps;
     return {
-        create(documentId, input) {
-            const document = dbGetDocument(db, documentId);
-            if (!document) {
+        create(target, input) {
+            const projectId = targetProjectId(db, target);
+            if (!projectId) {
                 return undefined;
             }
             assertNonEmptyBody(input.body);
-            const comment = createDocumentComment(db, {
-                documentId,
+            const comment = createComment(db, {
+                projectId,
+                targetType: target.type,
+                targetId: target.id,
                 body: input.body,
                 passage: input.passage,
+                anchor: input.anchor,
             });
-            eventBus.emit({
-                type: 'comment_created',
-                commentId: comment.id,
-                documentId,
-                projectId: document.projectId,
+            emitCommentCreated(eventBus, comment.id, projectId, target);
+            return serializeComment(comment);
+        },
+        // Artifact comments are project-scoped: the caller supplies the project
+        // (the connected repo's), and the file identity is the target id. Slashes
+        // in the file identity mean it travels in the body/query, never a path seg.
+        createForArtifact(projectId, artifactId, input) {
+            if (!getProject(db, projectId)) {
+                return undefined;
+            }
+            if (artifactId.trim() === '') {
+                throw new InvalidCommentError('Artifact id must not be empty');
+            }
+            assertNonEmptyBody(input.body);
+            const target = { type: 'artifact', id: artifactId };
+            const comment = createComment(db, {
+                projectId,
+                targetType: 'artifact',
+                targetId: artifactId,
+                body: input.body,
+                passage: input.passage,
+                anchor: input.anchor,
             });
+            emitCommentCreated(eventBus, comment.id, projectId, target);
             return serializeComment(comment);
         },
-        listByDocument(documentId, options) {
-            const document = dbGetDocument(db, documentId);
-            if (!document) {
+        listForArtifact(projectId, artifactId, options) {
+            if (!getProject(db, projectId)) {
+                return undefined;
+            }
+            return dbListCommentsByTarget(db, 'artifact', artifactId, options).map(serializeComment);
+        },
+        listByTarget(target, options) {
+            const projectId = targetProjectId(db, target);
+            if (!projectId) {
                 return undefined;
             }
-            return dbListCommentsByDocument(db, documentId, options).map(serializeComment);
+            return dbListCommentsByTarget(db, target.type, target.id, options).map(serializeComment);
+        },
+        resolveTargetProjectId(target) {
+            return targetProjectId(db, target);
+        },
+        listByDocument(documentId, options) {
+            return this.listByTarget({ type: 'document', id: documentId }, options);
         },
         listByProject(projectId, options) {
             const project = getProject(db, projectId);
@@ -48,47 +118,49 @@ export function createCommentService(deps) {
             return dbListCommentsByProject(db, projectId, options).map(serializeComment);
         },
         update(id, input) {
-            const existing = dbGetDocumentComment(db, id);
+            const existing = dbGetComment(db, id);
             if (!existing) {
                 return undefined;
             }
             if (input.body !== undefined) {
                 assertNonEmptyBody(input.body);
             }
-            const comment = dbUpdateDocumentComment(db, id, input);
+            const comment = dbUpdateComment(db, id, input);
             if (!comment) {
                 return undefined;
             }
-            const document = dbGetDocument(db, comment.documentId);
-            if (!document) {
+            const projectId = targetProjectId(db, {
+                type: comment.targetType,
+                id: comment.targetId,
+            });
+            if (!projectId) {
                 return undefined;
             }
-            eventBus.emit({
-                type: 'comment_updated',
-                commentId: id,
-                documentId: comment.documentId,
-                projectId: document.projectId,
+            emitCommentUpdated(eventBus, id, projectId, {
+                type: comment.targetType,
+                id: comment.targetId,
             });
             return serializeComment(comment);
         },
         delete(id) {
-            const existing = dbGetDocumentComment(db, id);
+            const existing = dbGetComment(db, id);
             if (!existing) {
                 return false;
             }
-            const document = dbGetDocument(db, existing.documentId);
-            if (!document) {
+            const projectId = targetProjectId(db, {
+                type: existing.targetType,
+                id: existing.targetId,
+            });
+            if (!projectId) {
                 return false;
             }
-            const deleted = dbDeleteDocumentComment(db, id);
+            const deleted = dbDeleteComment(db, id);
             if (!deleted) {
                 return false;
             }
-            eventBus.emit({
-                type: 'comment_updated',
-                commentId: id,
-                documentId: existing.documentId,
-                projectId: document.projectId,
+            emitCommentUpdated(eventBus, id, projectId, {
+                type: existing.targetType,
+                id: existing.targetId,
             });
             return true;
         },

package/dist/services/documents.js

@@ -1,4 +1,4 @@
-import { createDocument as dbCreateDocument, deleteCommentsByDocumentId, deleteDocument as dbDeleteDocument, detachDocumentChildren, getDocument as dbGetDocument, getDocumentByTask as dbGetDocumentByTask, getFolderByProjectAndId, getProject, getTask, listDocuments as dbListDocuments, listFolders as dbListFolders, updateDocument as dbUpdateDocument, } from '@plandesk/db';
+import { createDocument as dbCreateDocument, deleteCommentsByTarget, deleteDocument as dbDeleteDocument, detachDocumentChildren, getDocument as dbGetDocument, getDocumentByTask as dbGetDocumentByTask, getFolderByProjectAndId, getProject, getTask, listDocuments as dbListDocuments, listFolders as dbListFolders, updateDocument as dbUpdateDocument, } from '@plandesk/db';
 import { buildDocumentTree, buildFolderTree, serializeDocument, } from '../serialize.js';
 export class InvalidDocumentError extends Error {
     constructor(message) {
@@ -128,7 +128,7 @@ export function createDocumentService(deps) {
             }
             db.transaction((tx) => {
                 detachDocumentChildren(tx, id);
-                deleteCommentsByDocumentId(tx, id);
+                deleteCommentsByTarget(tx, 'document', id);
                 dbDeleteDocument(tx, id);
             });
             eventBus.emit({ type: 'canvas_updated', projectId: existing.projectId });

package/dist/services/notes.js

@@ -1,4 +1,4 @@
-import { createNote as dbCreateNote, deleteNote as dbDeleteNote, getNote as dbGetNote, getProject, listNotes as dbListNotes, updateNote as dbUpdateNote, } from '@plandesk/db';
+import { createNote as dbCreateNote, deleteCommentsByTarget, deleteNote as dbDeleteNote, getNote as dbGetNote, getProject, listNotes as dbListNotes, updateNote as dbUpdateNote, } from '@plandesk/db';
 import { serializeNote } from '../serialize.js';
 export class InvalidNoteError extends Error {
     constructor(message) {
@@ -66,6 +66,7 @@ export function createNoteService(deps) {
             if (!deleted) {
                 return false;
             }
+            deleteCommentsByTarget(db, 'note', id);
             eventBus.emit({ type: 'note_updated', noteId: id, projectId: existing.projectId });
             return true;
         },

package/dist/services/tasks.js

@@ -1,4 +1,4 @@
-import { createTag, createTask, deleteEdgesByTaskId, deleteTask as dbDeleteTask, deleteTaskTagsByTaskId, getOrCreateDefaultGoal, getProject, listGoals, getTagByName, getTask, InvalidTaskStatusError, isTaskStatus, listEdges, listTagsByTaskForProject, listTagsForTask, listTasks, nullDocumentsLinkedTask, setTaskTags, taskIdsWithAnyTagName, updateTask, } from '@plandesk/db';
+import { createTag, createTask, deleteCommentsByTarget, deleteEdgesByTaskId, deleteTask as dbDeleteTask, deleteTaskTagsByTaskId, getOrCreateDefaultGoal, getProject, listGoals, getTagByName, getTask, InvalidTaskStatusError, isTaskStatus, listEdges, listTagsByTaskForProject, listTagsForTask, listTasks, nullDocumentsLinkedTask, setTaskTags, taskIdsWithAnyTagName, updateTask, } from '@plandesk/db';
 import { serializeTask } from '../serialize.js';
 import { normalizeTagName } from './tags.js';
 export class InvalidGoalReferenceError extends Error {
@@ -132,6 +132,7 @@ export function createTaskService(deps) {
             }
             const projectId = task.projectId;
             db.transaction((tx) => {
+                deleteCommentsByTarget(tx, 'task', id);
                 deleteEdgesByTaskId(tx, id);
                 nullDocumentsLinkedTask(tx, id);
                 deleteTaskTagsByTaskId(tx, id);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@plandesk/api",
-  "version": "0.9.0",
+  "version": "0.11.0",
   "type": "module",
   "exports": {
     ".": {
@@ -18,7 +18,7 @@
   "devDependencies": {
     "typescript": "^6.0.3",
     "vitest": "^3.2.6",
-    "@plandesk/db": "0.7.0",
+    "@plandesk/db": "0.9.0",
     "@plandesk/sync-server": "0.5.0"
   },
   "dependencies": {