@plandesk/api 0.6.0 → 0.8.0

package/dist/services/folders.js

@@ -0,0 +1,107 @@
+import { createFolder as dbCreateFolder, deleteFolder as dbDeleteFolder, getFolder as dbGetFolder, getProject, listFolders as dbListFolders, moveDocumentsToFolder, reparentChildFolders, updateFolder as dbUpdateFolder, } from '@plandesk/db';
+import { serializeFolder } from '../serialize.js';
+export class InvalidFolderError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = 'InvalidFolderError';
+    }
+}
+function assertNonEmptyName(name) {
+    if (name.trim() === '') {
+        throw new InvalidFolderError('Folder name must not be empty');
+    }
+}
+function assertParentInProject(db, projectId, parentFolderId) {
+    const parent = dbGetFolder(db, parentFolderId);
+    if (!parent || parent.projectId !== projectId) {
+        throw new InvalidFolderError('Parent folder does not belong to project');
+    }
+}
+function assertNoCycle(db, folderId, newParentFolderId) {
+    const visited = new Set();
+    let current = newParentFolderId;
+    while (current !== null) {
+        if (current === folderId) {
+            throw new InvalidFolderError('Re-parenting would create a folder cycle');
+        }
+        if (visited.has(current)) {
+            return;
+        }
+        visited.add(current);
+        current = dbGetFolder(db, current)?.parentFolderId ?? null;
+    }
+}
+export function createFolderService(deps) {
+    const { db, eventBus } = deps;
+    return {
+        list(projectId) {
+            const project = getProject(db, projectId);
+            if (!project) {
+                return undefined;
+            }
+            return dbListFolders(db, projectId).map(serializeFolder);
+        },
+        create(projectId, input) {
+            const project = getProject(db, projectId);
+            if (!project) {
+                return undefined;
+            }
+            assertNonEmptyName(input.name);
+            if (input.parentFolderId !== undefined && input.parentFolderId !== null) {
+                assertParentInProject(db, projectId, input.parentFolderId);
+            }
+            const folder = dbCreateFolder(db, {
+                projectId,
+                name: input.name,
+                parentFolderId: input.parentFolderId,
+            });
+            eventBus.emit({ type: 'folder_created', folderId: folder.id, projectId });
+            return serializeFolder(folder);
+        },
+        get(id) {
+            const folder = dbGetFolder(db, id);
+            if (!folder) {
+                return undefined;
+            }
+            return serializeFolder(folder);
+        },
+        update(id, input) {
+            const existing = dbGetFolder(db, id);
+            if (!existing) {
+                return undefined;
+            }
+            if (input.name !== undefined) {
+                assertNonEmptyName(input.name);
+            }
+            if (input.parentFolderId !== undefined && input.parentFolderId !== null) {
+                if (input.parentFolderId === id) {
+                    throw new InvalidFolderError('Folder cannot be its own parent');
+                }
+                assertParentInProject(db, existing.projectId, input.parentFolderId);
+                assertNoCycle(db, id, input.parentFolderId);
+            }
+            const folder = dbUpdateFolder(db, id, input);
+            if (!folder) {
+                return undefined;
+            }
+            eventBus.emit({ type: 'folder_updated', folderId: folder.id, projectId: folder.projectId });
+            return serializeFolder(folder);
+        },
+        delete(id) {
+            const existing = dbGetFolder(db, id);
+            if (!existing) {
+                return false;
+            }
+            // Never orphan: children folders and contained documents move to the
+            // deleted folder's parent (or root when the folder was at root).
+            db.transaction((tx) => {
+                reparentChildFolders(tx, id, existing.parentFolderId);
+                moveDocumentsToFolder(tx, id, existing.parentFolderId);
+                dbDeleteFolder(tx, id);
+            });
+            eventBus.emit({ type: 'folder_updated', folderId: id, projectId: existing.projectId });
+            return true;
+        },
+    };
+}
+//# sourceMappingURL=folders.js.map

package/dist/services/index.d.ts

@@ -3,9 +3,11 @@ import { type EventBus } from '../events.js';
 import { type CanvasService } from './canvas.js';
 import { type CommentService } from './comments.js';
 import { type DocumentService } from './documents.js';
+import { type FolderService } from './folders.js';
 import { type NoteService } from './notes.js';
 import { type ProjectService } from './projects.js';
 import { type AgentRunService } from './agent-runs.js';
+import { type TagService } from './tags.js';
 import { type TaskService } from './tasks.js';
 import { type TokenService } from './tokens.js';
 import { type ShareService } from './share.js';
@@ -18,8 +20,10 @@ export type Services = {
     eventBus: EventBus;
     projectService: ProjectService;
     taskService: TaskService;
+    tagService: TagService;
     canvasService: CanvasService;
     documentService: DocumentService;
+    folderService: FolderService;
     noteService: NoteService;
     commentService: CommentService;
     agentRunService: AgentRunService;

package/dist/services/index.js

@@ -2,9 +2,11 @@ import { createEventBus } from '../events.js';
 import { createCanvasService } from './canvas.js';
 import { createCommentService } from './comments.js';
 import { createDocumentService } from './documents.js';
+import { createFolderService } from './folders.js';
 import { createNoteService } from './notes.js';
 import { createProjectService } from './projects.js';
 import { createAgentRunService } from './agent-runs.js';
+import { createTagService } from './tags.js';
 import { createTaskService } from './tasks.js';
 import { createTokenService } from './tokens.js';
 import { createShareService } from './share.js';
@@ -13,8 +15,10 @@ export function createServices(deps) {
     const eventBus = deps.eventBus ?? createEventBus();
     const projectService = createProjectService({ db: deps.db, eventBus });
     const taskService = createTaskService({ db: deps.db, eventBus });
+    const tagService = createTagService({ db: deps.db, eventBus });
     const canvasService = createCanvasService({ db: deps.db, eventBus });
     const documentService = createDocumentService({ db: deps.db, eventBus });
+    const folderService = createFolderService({ db: deps.db, eventBus });
     const noteService = createNoteService({ db: deps.db, eventBus });
     const commentService = createCommentService({ db: deps.db, eventBus });
     const agentRunService = createAgentRunService({ db: deps.db, eventBus });
@@ -25,8 +29,10 @@ export function createServices(deps) {
         eventBus,
         projectService,
         taskService,
+        tagService,
         canvasService,
         documentService,
+        folderService,
         noteService,
         commentService,
         agentRunService,

package/dist/services/projects.js

@@ -1,4 +1,4 @@
-import { clearDocumentParentRefsByProject, createDocument, createEdge, createProject as dbCreateProject, createTask, deleteAgentRun, deleteAgentRunEventsByRunId, deleteCommentsByProjectId, deleteDocumentsByProjectId, deleteNotesByProjectId, deleteEdgesByProjectId, deleteShareSubmissionsByProjectId, deleteSharesByProjectId, deleteSyncRemoteByProjectId, deleteSyncStateByProjectId, deleteProject as dbDeleteProject, deleteTasksByProjectId, getProject as dbGetProject, InvalidTaskStatusError, isTaskStatus, listAgentRuns, listProjects as dbListProjects, listTasks, updateProject as dbUpdateProject, } from '@plandesk/db';
+import { clearDocumentParentRefsByProject, clearFolderParentRefsByProject, createDocument, createEdge, createProject as dbCreateProject, createTask, deleteAgentRun, deleteAgentRunEventsByRunId, deleteCommentsByProjectId, deleteDocumentsByProjectId, deleteFoldersByProjectId, deleteNotesByProjectId, deleteEdgesByProjectId, deleteShareSubmissionsByProjectId, deleteSharesByProjectId, deleteTagsByProjectId, deleteSyncRemoteByProjectId, deleteSyncStateByProjectId, deleteProject as dbDeleteProject, deleteTasksByProjectId, getProject as dbGetProject, InvalidTaskStatusError, isTaskStatus, listAgentRuns, listProjects as dbListProjects, listTasks, updateProject as dbUpdateProject, } from '@plandesk/db';
 import { emptyTaskStatusSummary, serializeDocument, serializeEdge, serializeProject, serializeProjectDetail, serializeTask, } from '../serialize.js';
 export class InvalidScaffoldError extends Error {
     constructor(message) {
@@ -89,7 +89,10 @@ export function createProjectService(deps) {
                 clearDocumentParentRefsByProject(tx, id);
                 deleteCommentsByProjectId(tx, id);
                 deleteDocumentsByProjectId(tx, id);
+                clearFolderParentRefsByProject(tx, id);
+                deleteFoldersByProjectId(tx, id);
                 deleteNotesByProjectId(tx, id);
+                deleteTagsByProjectId(tx, id);
                 deleteTasksByProjectId(tx, id);
                 deleteShareSubmissionsByProjectId(tx, id);
                 deleteSyncStateByProjectId(tx, id);
@@ -164,7 +167,7 @@ export function createProjectService(deps) {
             }
             return {
                 project: serializeProject(project),
-                tasks: taskRows.map(serializeTask),
+                tasks: taskRows.map((task) => serializeTask(task)),
                 edges: edgeRows.map(serializeEdge),
                 documents: documentRows.map(serializeDocument),
                 key_to_id: Object.fromEntries(keyToId),

package/dist/services/tags.d.ts

@@ -0,0 +1,27 @@
+import { type Db } from '@plandesk/db';
+import type { EventBus } from '../events.js';
+import { type SerializedTag } from '../serialize.js';
+export type TagServiceDeps = {
+    db: Db;
+    eventBus: EventBus;
+};
+export type CreateTagInput = {
+    name: string;
+    color?: string | null;
+};
+export type UpdateTagInput = {
+    name?: string;
+    color?: string | null;
+};
+export declare class InvalidTagError extends Error {
+    constructor(message: string);
+}
+export declare function normalizeTagName(name: string): string;
+export declare function createTagService(deps: TagServiceDeps): {
+    list(projectId: string): SerializedTag[] | undefined;
+    create(projectId: string, input: CreateTagInput): SerializedTag | undefined;
+    update(id: string, input: UpdateTagInput): SerializedTag | undefined;
+    delete(id: string): boolean;
+};
+export type TagService = ReturnType<typeof createTagService>;
+//# sourceMappingURL=tags.d.ts.map

package/dist/services/tags.js

@@ -0,0 +1,79 @@
+import { createTag as dbCreateTag, deleteTag as dbDeleteTag, getProject, getTag as dbGetTag, getTagByName, listTags as dbListTags, updateTag as dbUpdateTag, } from '@plandesk/db';
+import { serializeTag } from '../serialize.js';
+export class InvalidTagError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = 'InvalidTagError';
+    }
+}
+export function normalizeTagName(name) {
+    const trimmed = name.trim();
+    if (trimmed === '') {
+        throw new InvalidTagError('Tag name must not be empty');
+    }
+    return trimmed;
+}
+export function createTagService(deps) {
+    const { db, eventBus } = deps;
+    return {
+        list(projectId) {
+            const project = getProject(db, projectId);
+            if (!project) {
+                return undefined;
+            }
+            return dbListTags(db, projectId).map(serializeTag);
+        },
+        create(projectId, input) {
+            const project = getProject(db, projectId);
+            if (!project) {
+                return undefined;
+            }
+            const name = normalizeTagName(input.name);
+            if (getTagByName(db, projectId, name)) {
+                throw new InvalidTagError(`Tag already exists: ${name}`);
+            }
+            const tag = dbCreateTag(db, { projectId, name, color: input.color });
+            eventBus.emit({ type: 'tag_updated', projectId });
+            return serializeTag(tag);
+        },
+        // Renaming propagates everywhere automatically: tasks reference the single
+        // tag row through the join table.
+        update(id, input) {
+            const existing = dbGetTag(db, id);
+            if (!existing) {
+                return undefined;
+            }
+            let name;
+            if (input.name !== undefined) {
+                name = normalizeTagName(input.name);
+                const conflict = getTagByName(db, existing.projectId, name);
+                if (conflict && conflict.id !== id) {
+                    throw new InvalidTagError(`Tag already exists: ${name}`);
+                }
+            }
+            const tag = dbUpdateTag(db, id, {
+                ...(name !== undefined ? { name } : {}),
+                ...(input.color !== undefined ? { color: input.color } : {}),
+            });
+            if (!tag) {
+                return undefined;
+            }
+            eventBus.emit({ type: 'tag_updated', projectId: tag.projectId });
+            return serializeTag(tag);
+        },
+        // Deleting a tag removes it from all its tasks (cascade on the join table).
+        delete(id) {
+            const existing = dbGetTag(db, id);
+            if (!existing) {
+                return false;
+            }
+            const deleted = dbDeleteTag(db, id);
+            if (!deleted) {
+                return false;
+            }
+            eventBus.emit({ type: 'tag_updated', projectId: existing.projectId });
+            return true;
+        },
+    };
+}
+//# sourceMappingURL=tags.js.map

package/dist/services/tasks.d.ts

@@ -23,6 +23,7 @@ export type CreateTaskInput = {
     y?: number;
     assignee?: string | null;
     dueDate?: Date | null;
+    tags?: string[];
 };
 export type UpdateTaskInput = {
     label?: string;
@@ -30,12 +31,29 @@ export type UpdateTaskInput = {
     description?: string | null;
     x?: number;
     y?: number;
+    tags?: string[];
 };
 export type ListTasksFilter = {
     status?: string;
+    tags?: string[];
 };
 export declare function createTaskService(deps: TaskServiceDeps): {
+    get(id: string): {
+        tags?: import("../serialize.js").SerializedTag[] | undefined;
+        id: string;
+        project_id: string;
+        label: string;
+        status: "scope" | "todo" | "in_progress" | "done" | "backlog";
+        description: string | null;
+        x: number;
+        y: number;
+        assignee: string | null;
+        due_date: string | null;
+        created_at: string;
+        updated_at: string;
+    } | undefined;
     listByProject(projectId: string, filter?: ListTasksFilter, pagination?: PaginationParams): {
+        tags?: import("../serialize.js").SerializedTag[] | undefined;
         id: string;
         project_id: string;
         label: string;
@@ -49,6 +67,7 @@ export declare function createTaskService(deps: TaskServiceDeps): {
         updated_at: string;
     }[] | undefined;
     create(projectId: string, input: CreateTaskInput): {
+        tags?: import("../serialize.js").SerializedTag[] | undefined;
         id: string;
         project_id: string;
         label: string;
@@ -62,6 +81,7 @@ export declare function createTaskService(deps: TaskServiceDeps): {
         updated_at: string;
     } | undefined;
     update(id: string, input: UpdateTaskInput): {
+        tags?: import("../serialize.js").SerializedTag[] | undefined;
         id: string;
         project_id: string;
         label: string;
@@ -75,7 +95,9 @@ export declare function createTaskService(deps: TaskServiceDeps): {
         updated_at: string;
     } | undefined;
     delete(id: string): boolean;
-    nextActionable(projectId: string): NextActionableResult | undefined;
+    nextActionable(projectId: string, filter?: {
+        tags?: string[];
+    }): NextActionableResult | undefined;
 };
 export type TaskService = ReturnType<typeof createTaskService>;
 export {};

package/dist/services/tasks.js

@@ -1,5 +1,6 @@
-import { createTask, deleteEdgesByTaskId, deleteTask as dbDeleteTask, getProject, getTask, InvalidTaskStatusError, isTaskStatus, listEdges, listTasks, nullDocumentsLinkedTask, updateTask, } from '@plandesk/db';
+import { createTag, createTask, deleteEdgesByTaskId, deleteTask as dbDeleteTask, deleteTaskTagsByTaskId, getProject, 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';
 // depends_on: prerequisite = to, dependent = from. All other labels: prerequisite = from, dependent = to.
 function prerequisiteAndDependent(edge) {
     if (edge.fromTaskId === edge.toTaskId) {
@@ -10,9 +11,31 @@ function prerequisiteAndDependent(edge) {
     }
     return { prerequisite: edge.fromTaskId, dependent: edge.toTaskId };
 }
+// Resolves tag names to ids, auto-creating tags that do not exist yet.
+function resolveTagIdsByName(db, projectId, names) {
+    const seen = new Set();
+    const ids = [];
+    for (const raw of names) {
+        const name = normalizeTagName(raw);
+        if (seen.has(name)) {
+            continue;
+        }
+        seen.add(name);
+        const tag = getTagByName(db, projectId, name) ?? createTag(db, { projectId, name });
+        ids.push(tag.id);
+    }
+    return ids;
+}
 export function createTaskService(deps) {
     const { db, eventBus } = deps;
     return {
+        get(id) {
+            const task = getTask(db, id);
+            if (!task) {
+                return undefined;
+            }
+            return serializeTask(task, listTagsForTask(db, id));
+        },
         listByProject(projectId, filter = {}, pagination = {}) {
             if (filter.status !== undefined && !isTaskStatus(filter.status)) {
                 throw new InvalidTaskStatusError(filter.status);
@@ -22,10 +45,13 @@ export function createTaskService(deps) {
                 return undefined;
             }
             const statusFilter = filter.status;
-            const tasks = statusFilter !== undefined
-                ? listTasks(db, projectId, { status: statusFilter, ...pagination })
-                : listTasks(db, projectId, pagination);
-            return tasks.map(serializeTask);
+            const tasks = listTasks(db, projectId, {
+                ...(statusFilter !== undefined ? { status: statusFilter } : {}),
+                ...(filter.tags !== undefined ? { tagNames: filter.tags.map(normalizeTagName) } : {}),
+                ...pagination,
+            });
+            const tagsByTask = listTagsByTaskForProject(db, projectId);
+            return tasks.map((task) => serializeTask(task, tagsByTask.get(task.id) ?? []));
         },
         create(projectId, input) {
             if (input.status !== undefined && !isTaskStatus(input.status)) {
@@ -35,22 +61,28 @@ export function createTaskService(deps) {
             if (!project) {
                 return undefined;
             }
-            const task = createTask(db, {
-                projectId,
-                label: input.label,
-                status: input.status,
-                description: input.description,
-                x: input.x,
-                y: input.y,
-                assignee: input.assignee,
-                dueDate: input.dueDate,
+            const { task, tags } = db.transaction((tx) => {
+                const row = createTask(tx, {
+                    projectId,
+                    label: input.label,
+                    status: input.status,
+                    description: input.description,
+                    x: input.x,
+                    y: input.y,
+                    assignee: input.assignee,
+                    dueDate: input.dueDate,
+                });
+                if (input.tags !== undefined) {
+                    setTaskTags(tx, row.id, resolveTagIdsByName(tx, projectId, input.tags));
+                }
+                return { task: row, tags: listTagsForTask(tx, row.id) };
             });
             eventBus.emit({
                 type: 'task_updated',
                 taskId: task.id,
                 projectId,
             });
-            return serializeTask(task);
+            return serializeTask(task, tags);
         },
         update(id, input) {
             if (input.status !== undefined && !isTaskStatus(input.status)) {
@@ -60,16 +92,26 @@ export function createTaskService(deps) {
             if (!existing) {
                 return undefined;
             }
-            const task = updateTask(db, id, input);
-            if (!task) {
+            const { tags: tagNames, ...columns } = input;
+            const result = db.transaction((tx) => {
+                const row = updateTask(tx, id, columns);
+                if (!row) {
+                    return undefined;
+                }
+                if (tagNames !== undefined) {
+                    setTaskTags(tx, id, resolveTagIdsByName(tx, existing.projectId, tagNames));
+                }
+                return { task: row, tags: listTagsForTask(tx, id) };
+            });
+            if (!result) {
                 return undefined;
             }
             eventBus.emit({
                 type: 'task_updated',
-                taskId: task.id,
-                projectId: task.projectId,
+                taskId: result.task.id,
+                projectId: result.task.projectId,
             });
-            return serializeTask(task);
+            return serializeTask(result.task, result.tags);
         },
         delete(id) {
             const task = getTask(db, id);
@@ -80,12 +122,16 @@ export function createTaskService(deps) {
             db.transaction((tx) => {
                 deleteEdgesByTaskId(tx, id);
                 nullDocumentsLinkedTask(tx, id);
+                deleteTaskTagsByTaskId(tx, id);
                 dbDeleteTask(tx, id);
             });
             eventBus.emit({ type: 'canvas_updated', projectId });
             return true;
         },
-        nextActionable(projectId) {
+        // filter.tags (OR semantics): only tasks carrying ANY of the given tag names
+        // are candidates for next_task / blocked; prerequisite completion is still
+        // evaluated against all tasks in the project.
+        nextActionable(projectId, filter = {}) {
             const project = getProject(db, projectId);
             if (!project) {
                 return undefined;
@@ -93,6 +139,11 @@ export function createTaskService(deps) {
             const tasks = listTasks(db, projectId).sort((a, b) => a.createdAt.getTime() - b.createdAt.getTime());
             const edges = listEdges(db, projectId);
             const taskById = new Map(tasks.map((task) => [task.id, task]));
+            const tagsByTask = listTagsByTaskForProject(db, projectId);
+            const tagMatches = filter.tags !== undefined && filter.tags.length > 0
+                ? taskIdsWithAnyTagName(db, projectId, filter.tags.map(normalizeTagName))
+                : undefined;
+            const serialize = (task) => serializeTask(task, tagsByTask.get(task.id) ?? []);
             const prerequisites = new Map();
             for (const edge of edges) {
                 const pair = prerequisiteAndDependent(edge);
@@ -109,7 +160,7 @@ export function createTaskService(deps) {
             if (tasks.length === 0) {
                 return { next_task: null, reason: 'no_tasks', blocked: [] };
             }
-            const todoTasks = tasks.filter((task) => task.status === 'todo');
+            const todoTasks = tasks.filter((task) => task.status === 'todo' && (tagMatches === undefined || tagMatches.has(task.id)));
             if (todoTasks.length === 0) {
                 return { next_task: null, reason: 'no_todo_tasks', blocked: [] };
             }
@@ -134,19 +185,19 @@ export function createTaskService(deps) {
                 return [...prereqs]
                     .map((id) => taskById.get(id))
                     .filter((task) => task !== undefined && task.status !== 'done')
-                    .map(serializeTask);
+                    .map(serialize);
             };
             const blocked = [];
             let nextTask = null;
             for (const task of todoTasks) {
                 if (isActionable(task.id)) {
                     if (nextTask === null) {
-                        nextTask = serializeTask(task);
+                        nextTask = serialize(task);
                     }
                 }
                 else {
                     blocked.push({
-                        task: serializeTask(task),
+                        task: serialize(task),
                         waiting_on: unfinishedPrereqs(task.id),
                     });
                 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@plandesk/api",
-  "version": "0.6.0",
+  "version": "0.8.0",
   "type": "module",
   "exports": {
     ".": {
@@ -18,8 +18,8 @@
   "devDependencies": {
     "typescript": "^6.0.3",
     "vitest": "^3.2.6",
-    "@plandesk/db": "0.5.0",
-    "@plandesk/sync-server": "0.4.2"
+    "@plandesk/db": "0.6.0",
+    "@plandesk/sync-server": "0.5.0"
   },
   "dependencies": {
     "@hono/node-server": "^2.0.4",