@plandesk/api 0.8.0 → 0.9.0

package/dist/events.d.ts

@@ -67,7 +67,12 @@ export type SubmissionsPulledEvent = {
     type: 'submissions_pulled';
     projectId: string;
 };
-export type PlankDeskEvent = TaskUpdatedEvent | TagUpdatedEvent | CanvasUpdatedEvent | DocumentCreatedEvent | CommentCreatedEvent | CommentUpdatedEvent | FolderCreatedEvent | FolderUpdatedEvent | NoteCreatedEvent | NoteUpdatedEvent | AgentRunStartedEvent | AgentRunProgressEvent | AgentRunCompletedEvent | SubmissionsPulledEvent;
+export type GoalUpdatedEvent = {
+    type: 'goal_updated';
+    goalId: string;
+    projectId: string;
+};
+export type PlankDeskEvent = TaskUpdatedEvent | TagUpdatedEvent | CanvasUpdatedEvent | DocumentCreatedEvent | CommentCreatedEvent | CommentUpdatedEvent | FolderCreatedEvent | FolderUpdatedEvent | NoteCreatedEvent | NoteUpdatedEvent | AgentRunStartedEvent | AgentRunProgressEvent | AgentRunCompletedEvent | SubmissionsPulledEvent | GoalUpdatedEvent;
 export type EventListener = (event: PlankDeskEvent) => void;
 export type EventBus = {
     subscribe(listener: EventListener): () => void;

package/dist/index.d.ts

@@ -5,7 +5,10 @@ export { mountStatic } from './static.js';
 export { createServices, type Services, type ServicesDeps } from './services/index.js';
 export { createEventBus, type EventBus, type PlankDeskEvent } from './events.js';
 export type { ProjectService } from './services/projects.js';
+export type { GoalService, VerificationEvidence } from './services/goals.js';
+export { GoalCompletionBlockedError, GoalVerificationRequiredError, InvalidGoalTransitionError, InvalidVerificationSurfaceError, } from './services/goals.js';
 export type { TaskService } from './services/tasks.js';
+export { InvalidGoalReferenceError } from './services/tasks.js';
 export type { TagService } from './services/tags.js';
 export type { CanvasService } from './services/canvas.js';
 export type { DocumentService } from './services/documents.js';
@@ -22,6 +25,6 @@ export { InvalidCanvasError } from './services/canvas.js';
 export { InvalidAgentRunError } from './services/agent-runs.js';
 export { InvalidScaffoldError } from './services/projects.js';
 export { InvalidShareError } from './services/share.js';
-export { InvalidTriageError, SyncUnavailableError, SyncUnauthorizedError, type SyncRemote, type SyncService, } from './services/sync.js';
+export { InvalidTriageError, InvalidTriageInputError, SyncUnavailableError, SyncUnauthorizedError, type SyncRemote, type SyncService, } from './services/sync.js';
 export declare const version: () => string;
 //# sourceMappingURL=index.d.ts.map

package/dist/index.js

@@ -4,6 +4,8 @@ export { healthRouter } from './routes/health.js';
 export { mountStatic } from './static.js';
 export { createServices } from './services/index.js';
 export { createEventBus } from './events.js';
+export { GoalCompletionBlockedError, GoalVerificationRequiredError, InvalidGoalTransitionError, InvalidVerificationSurfaceError, } from './services/goals.js';
+export { InvalidGoalReferenceError } from './services/tasks.js';
 export { InvalidDocumentError } from './services/documents.js';
 export { InvalidFolderError } from './services/folders.js';
 export { InvalidNoteError } from './services/notes.js';
@@ -13,7 +15,7 @@ export { InvalidCanvasError } from './services/canvas.js';
 export { InvalidAgentRunError } from './services/agent-runs.js';
 export { InvalidScaffoldError } from './services/projects.js';
 export { InvalidShareError } from './services/share.js';
-export { InvalidTriageError, SyncUnavailableError, SyncUnauthorizedError, } from './services/sync.js';
+export { InvalidTriageError, InvalidTriageInputError, SyncUnavailableError, SyncUnauthorizedError, } from './services/sync.js';
 import { readFileSync } from 'node:fs';
 import { dirname, join } from 'node:path';
 import { fileURLToPath } from 'node:url';

package/dist/routes/agent-runs.d.ts

@@ -1,4 +1,4 @@
 import { Hono } from 'hono';
-import type { AgentRunService } from '../services/agent-runs.js';
+import { type AgentRunService } from '../services/agent-runs.js';
 export declare function createAgentRunsRouter(agentRunService: AgentRunService): Hono;
 //# sourceMappingURL=agent-runs.d.ts.map

package/dist/routes/agent-runs.js

@@ -1,4 +1,5 @@
 import { Hono } from 'hono';
+import { InvalidAgentRunError } from '../services/agent-runs.js';
 import { parsePaginationParams } from '../serialize.js';
 export function createAgentRunsRouter(agentRunService) {
     const router = new Hono();
@@ -13,6 +14,25 @@ export function createAgentRunsRouter(agentRunService) {
         }
         return c.json(runs);
     });
+    router.post('/agent-runs/:id/progress', async (c) => {
+        const body = await c.req.json();
+        if (typeof body.message !== 'string' || body.message.trim() === '') {
+            return c.json({ error: 'invalid_argument' }, 400);
+        }
+        try {
+            const event = agentRunService.recordProgress(c.req.param('id'), body.message);
+            if (!event) {
+                return c.json({ error: 'not_found' }, 404);
+            }
+            return c.json(event, 201);
+        }
+        catch (error) {
+            if (error instanceof InvalidAgentRunError) {
+                return c.json({ error: 'invalid_argument' }, 400);
+            }
+            throw error;
+        }
+    });
     return router;
 }
 //# sourceMappingURL=agent-runs.js.map

package/dist/routes/goals.d.ts

@@ -0,0 +1,4 @@
+import { Hono } from 'hono';
+import { type GoalService } from '../services/goals.js';
+export declare function createGoalsRouter(goalService: GoalService): Hono;
+//# sourceMappingURL=goals.d.ts.map

package/dist/routes/goals.js

@@ -0,0 +1,138 @@
+import { Hono } from 'hono';
+import { InvalidGoalStatusError, isGoalStatus } from '@plandesk/db';
+import { GoalCompletionBlockedError, GoalVerificationRequiredError, InvalidGoalTransitionError, InvalidVerificationSurfaceError, } from '../services/goals.js';
+function mapGoalInput(body) {
+    return {
+        ...(body.objective !== undefined ? { objective: body.objective } : {}),
+        ...(body.verification_surface !== undefined
+            ? { verificationSurface: body.verification_surface }
+            : {}),
+        ...(body.constraints !== undefined ? { constraints: body.constraints } : {}),
+        ...(body.boundaries !== undefined ? { boundaries: body.boundaries } : {}),
+        ...(body.iteration_policy !== undefined ? { iterationPolicy: body.iteration_policy } : {}),
+        ...(body.stop_condition !== undefined ? { stopCondition: body.stop_condition } : {}),
+        ...(body.budget !== undefined ? { budget: body.budget } : {}),
+    };
+}
+function handleGoalError(c, error) {
+    if (error instanceof InvalidGoalStatusError || error instanceof InvalidGoalTransitionError) {
+        return c.json({ error: 'invalid_argument' }, 400);
+    }
+    if (error instanceof InvalidVerificationSurfaceError) {
+        return c.json({ error: 'invalid_argument' }, 400);
+    }
+    if (error instanceof GoalVerificationRequiredError) {
+        return c.json({
+            error: 'verification_required',
+            required_kind: error.requiredKind,
+        }, 400);
+    }
+    if (error instanceof GoalCompletionBlockedError) {
+        return c.json({
+            error: 'blocked_by_incomplete_tasks',
+            incomplete_task_ids: error.incompleteTaskIds,
+        }, 400);
+    }
+    throw error;
+}
+export function createGoalsRouter(goalService) {
+    const router = new Hono();
+    router.post('/projects/:id/goals', async (c) => {
+        const body = await c.req.json();
+        if (typeof body.objective !== 'string' || body.objective.trim() === '') {
+            return c.json({ error: 'invalid_argument' }, 400);
+        }
+        if (body.status !== undefined && !isGoalStatus(body.status)) {
+            return c.json({ error: 'invalid_argument' }, 400);
+        }
+        try {
+            const goal = goalService.create(c.req.param('id'), {
+                objective: body.objective,
+                ...(body.status !== undefined ? { status: body.status } : {}),
+                ...mapGoalInput(body),
+            });
+            if (!goal) {
+                return c.json({ error: 'not_found' }, 404);
+            }
+            return c.json(goal, 201);
+        }
+        catch (error) {
+            return handleGoalError(c, error);
+        }
+    });
+    router.get('/projects/:id/goals', (c) => {
+        const goals = goalService.listByProject(c.req.param('id'));
+        if (!goals) {
+            return c.json({ error: 'not_found' }, 404);
+        }
+        return c.json(goals);
+    });
+    router.get('/goals/:id', (c) => {
+        const goal = goalService.get(c.req.param('id'));
+        if (!goal) {
+            return c.json({ error: 'not_found' }, 404);
+        }
+        return c.json(goal);
+    });
+    router.patch('/goals/:id', async (c) => {
+        const body = await c.req.json();
+        if (body.objective !== undefined && body.objective.trim() === '') {
+            return c.json({ error: 'invalid_argument' }, 400);
+        }
+        try {
+            const goal = goalService.update(c.req.param('id'), mapGoalInput(body));
+            if (!goal) {
+                return c.json({ error: 'not_found' }, 404);
+            }
+            return c.json(goal);
+        }
+        catch (error) {
+            return handleGoalError(c, error);
+        }
+    });
+    router.post('/goals/:id/pause', (c) => {
+        try {
+            const goal = goalService.pause(c.req.param('id'));
+            if (!goal) {
+                return c.json({ error: 'not_found' }, 404);
+            }
+            return c.json(goal);
+        }
+        catch (error) {
+            return handleGoalError(c, error);
+        }
+    });
+    router.post('/goals/:id/resume', (c) => {
+        try {
+            const goal = goalService.resume(c.req.param('id'));
+            if (!goal) {
+                return c.json({ error: 'not_found' }, 404);
+            }
+            return c.json(goal);
+        }
+        catch (error) {
+            return handleGoalError(c, error);
+        }
+    });
+    router.post('/goals/:id/complete', async (c) => {
+        let body = {};
+        try {
+            body = await c.req.json();
+        }
+        catch {
+            // empty body is valid when the goal has no verification_surface
+        }
+        try {
+            const goal = goalService.complete(c.req.param('id'), body.evidence);
+            if (!goal) {
+                return c.json({ error: 'not_found' }, 404);
+            }
+            return c.json(goal);
+        }
+        catch (error) {
+            return handleGoalError(c, error);
+        }
+    });
+    return router;
+}
+//# sourceMappingURL=goals.js.map

package/dist/routes/projects.d.ts

@@ -1,5 +1,5 @@
 import { Hono } from 'hono';
 import type { ProjectService } from '../services/projects.js';
-import type { TaskService } from '../services/tasks.js';
+import { type TaskService } from '../services/tasks.js';
 export declare function createProjectsRouter(projectService: ProjectService, taskService: TaskService): Hono;
 //# sourceMappingURL=projects.d.ts.map

package/dist/routes/projects.js

@@ -1,5 +1,6 @@
 import { Hono } from 'hono';
 import { InvalidTaskStatusError, isTaskStatus } from '@plandesk/db';
+import { InvalidGoalReferenceError } from '../services/tasks.js';
 import { InvalidTagError } from '../services/tags.js';
 import { isStringArray } from './tasks.js';
 import { parsePaginationParams } from '../serialize.js';
@@ -81,6 +82,7 @@ export function createProjectsRouter(projectService, taskService) {
                 ...(body.y !== undefined ? { y: body.y } : {}),
                 ...(body.assignee !== undefined ? { assignee: body.assignee } : {}),
                 ...(dueDate !== undefined ? { dueDate } : {}),
+                ...(body.goal_id !== undefined ? { goalId: body.goal_id } : {}),
                 ...(body.tags !== undefined ? { tags: body.tags } : {}),
             });
             if (!task) {
@@ -89,7 +91,9 @@ export function createProjectsRouter(projectService, taskService) {
             return c.json(task, 201);
         }
         catch (error) {
-            if (error instanceof InvalidTaskStatusError || error instanceof InvalidTagError) {
+            if (error instanceof InvalidTaskStatusError ||
+                error instanceof InvalidTagError ||
+                error instanceof InvalidGoalReferenceError) {
                 return c.json({ error: 'invalid_argument' }, 400);
             }
             throw error;
@@ -118,6 +122,13 @@ export function createProjectsRouter(projectService, taskService) {
             throw error;
         }
     });
+    router.get('/projects/:id/next-task', (c) => {
+        const result = taskService.nextActionable(c.req.param('id'));
+        if (!result) {
+            return c.json({ error: 'not_found' }, 404);
+        }
+        return c.json(result);
+    });
     return router;
 }
 //# sourceMappingURL=projects.js.map

package/dist/routes/submissions.d.ts

@@ -0,0 +1,5 @@
+import { Hono } from 'hono';
+import { type SyncService } from '../services/sync.js';
+import type { ProjectService } from '../services/projects.js';
+export declare function createSubmissionsRouter(syncService: SyncService, projectService: ProjectService): Hono;
+//# sourceMappingURL=submissions.d.ts.map

package/dist/routes/submissions.js

@@ -0,0 +1,58 @@
+import { Hono } from 'hono';
+import { shareSubmissionStatuses } from '@plandesk/db';
+import { InvalidTriageError, SyncUnauthorizedError, SyncUnavailableError, } from '../services/sync.js';
+function isSubmissionStatus(value) {
+    return shareSubmissionStatuses.includes(value);
+}
+export function createSubmissionsRouter(syncService, projectService) {
+    const router = new Hono();
+    router.get('/projects/:id/submissions', (c) => {
+        const projectId = c.req.param('id');
+        if (!projectService.get(projectId)) {
+            return c.json({ error: 'not_found' }, 404);
+        }
+        const statusParam = c.req.query('status') ?? 'pending';
+        if (!isSubmissionStatus(statusParam)) {
+            return c.json({ error: 'invalid_argument' }, 400);
+        }
+        return c.json(syncService.listTriage(projectId, statusParam));
+    });
+    router.post('/submissions/:id/triage', async (c) => {
+        const submissionId = c.req.param('id');
+        const body = await c.req.json();
+        if (body.action !== 'accept' && body.action !== 'reject') {
+            return c.json({ error: 'invalid_argument' }, 400);
+        }
+        const submission = syncService.getSubmission(submissionId);
+        if (submission === undefined) {
+            return c.json({ error: 'not_found' }, 404);
+        }
+        const remote = syncService.getRemote(submission.project_id);
+        if (remote === undefined) {
+            return c.json({ error: 'not_published' }, 400);
+        }
+        try {
+            // Triage never creates a `todo` task — the scope->todo release is the human's own
+            // board action, enforced in syncService.triage(). A merge (link_task_id) links to
+            // an existing task instead of creating one; the two are mutually exclusive, so
+            // only one is forwarded.
+            const linkTaskId = body.action === 'accept' ? body.link_task_id : undefined;
+            const result = await syncService.triage(submissionId, body.action, remote, body.action === 'accept' && linkTaskId === undefined ? body.as_task : undefined, linkTaskId);
+            return c.json(result);
+        }
+        catch (error) {
+            if (error instanceof InvalidTriageError) {
+                return c.json({ error: 'not_found' }, 404);
+            }
+            if (error instanceof SyncUnauthorizedError) {
+                return c.json({ error: 'sync_unauthorized' }, 400);
+            }
+            if (error instanceof SyncUnavailableError) {
+                return c.json({ error: 'sync_unavailable' }, 502);
+            }
+            throw error;
+        }
+    });
+    return router;
+}
+//# sourceMappingURL=submissions.js.map

package/dist/serialize.d.ts

@@ -1,4 +1,4 @@
-import type { AgentRun, AgentRunEvent, Document, DocumentComment, Edge, Folder, Note, Project, Tag, Task, TaskStatus } from '@plandesk/db';
+import type { AgentRun, AgentRunEvent, Document, DocumentComment, Edge, Folder, Goal, Note, Project, Tag, Task, TaskStatus } from '@plandesk/db';
 export type PaginationParams = {
     limit?: number;
     offset?: number;
@@ -29,10 +29,31 @@ export type SerializedTag = {
     created_at: string;
 };
 export declare function serializeTag(tag: Tag): SerializedTag;
+export declare function serializeGoal(goal: Goal): {
+    id: string;
+    project_id: string;
+    objective: string;
+    status: "active" | "paused" | "complete" | "blocked";
+    verification_surface: string | null;
+    constraints: string | null;
+    boundaries: string | null;
+    iteration_policy: string | null;
+    stop_condition: string | null;
+    budget: string | null;
+    last_verification: {
+        at: string;
+        green: boolean;
+        kind: string | null;
+        detail?: string;
+    } | null;
+    created_at: string;
+    updated_at: string;
+};
 export declare function serializeTask(task: Task, tags?: Tag[]): {
     tags?: SerializedTag[] | undefined;
     id: string;
     project_id: string;
+    goal_id: string;
     label: string;
     status: "scope" | "todo" | "in_progress" | "done" | "backlog";
     description: string | null;

package/dist/serialize.js

@@ -45,10 +45,45 @@ export function serializeTag(tag) {
         created_at: tag.createdAt.toISOString(),
     };
 }
+function parseLastVerification(raw) {
+    if (raw === null) {
+        return null;
+    }
+    try {
+        const parsed = JSON.parse(raw);
+        if (typeof parsed.at === 'string' &&
+            typeof parsed.green === 'boolean' &&
+            (parsed.kind === null || typeof parsed.kind === 'string')) {
+            return parsed;
+        }
+        return null;
+    }
+    catch {
+        return null;
+    }
+}
+export function serializeGoal(goal) {
+    return {
+        id: goal.id,
+        project_id: goal.projectId,
+        objective: goal.objective,
+        status: goal.status,
+        verification_surface: goal.verificationSurface,
+        constraints: goal.constraints,
+        boundaries: goal.boundaries,
+        iteration_policy: goal.iterationPolicy,
+        stop_condition: goal.stopCondition,
+        budget: goal.budget,
+        last_verification: parseLastVerification(goal.lastVerification),
+        created_at: goal.createdAt.toISOString(),
+        updated_at: goal.updatedAt.toISOString(),
+    };
+}
 export function serializeTask(task, tags) {
     return {
         id: task.id,
         project_id: task.projectId,
+        goal_id: task.goalId,
         label: task.label,
         status: task.status,
         description: task.description,

package/dist/server.js

@@ -12,17 +12,20 @@ import { createNotesRouter } from './routes/notes.js';
 import { createEventsRouter } from './routes/events.js';
 import { createTokensRouter } from './routes/tokens.js';
 import { createAgentRunsRouter } from './routes/agent-runs.js';
+import { createGoalsRouter } from './routes/goals.js';
+import { createSubmissionsRouter } from './routes/submissions.js';
 import { mountStatic } from './static.js';
 import { createServices } from './services/index.js';
 export function createApp(deps) {
     const services = deps.services ?? createServices({ db: deps.db, eventBus: deps.eventBus });
-    const { eventBus, projectService, taskService, tagService, canvasService, documentService, folderService, noteService, commentService, agentRunService, tokenService, } = services;
+    const { eventBus, projectService, goalService, taskService, tagService, canvasService, documentService, folderService, noteService, commentService, agentRunService, tokenService, syncService, } = services;
     const app = new Hono();
     if (deps.authPassword !== undefined && deps.authPassword.length > 0) {
         app.use('*', createAuthMiddleware(deps.authPassword));
     }
     app.route('/api/v1', healthRouter);
     app.route('/api/v1', createProjectsRouter(projectService, taskService));
+    app.route('/api/v1', createGoalsRouter(goalService));
     app.route('/api/v1', createTasksRouter(taskService));
     app.route('/api/v1', createTagsRouter(tagService));
     app.route('/api/v1', createCanvasRouter(canvasService));
@@ -32,6 +35,7 @@ export function createApp(deps) {
     app.route('/api/v1', createCommentsRouter(commentService));
     app.route('/api/v1', createTokensRouter(tokenService));
     app.route('/api/v1', createAgentRunsRouter(agentRunService));
+    app.route('/api/v1', createSubmissionsRouter(syncService, projectService));
     app.route('/api/v1', createEventsRouter(eventBus));
     mountStatic(app);
     if (deps.mcp) {

package/dist/services/canvas.d.ts

@@ -33,6 +33,7 @@ export declare function createCanvasService(deps: CanvasServiceDeps): {
             tags?: import("../serialize.js").SerializedTag[] | undefined;
             id: string;
             project_id: string;
+            goal_id: string;
             label: string;
             status: "scope" | "todo" | "in_progress" | "done" | "backlog";
             description: string | null;
@@ -75,6 +76,7 @@ export declare function createCanvasService(deps: CanvasServiceDeps): {
             tags?: import("../serialize.js").SerializedTag[] | undefined;
             id: string;
             project_id: string;
+            goal_id: string;
             label: string;
             status: "scope" | "todo" | "in_progress" | "done" | "backlog";
             description: string | null;

package/dist/services/canvas.js

@@ -1,4 +1,4 @@
-import { createEdge, createTask, deleteEdge as dbDeleteEdge, getEdgeByProjectAndId, getProject, getTask, listEdges, listTasks, updateEdge, updateProject, updateTask, } from '@plandesk/db';
+import { createEdge, createTask, getOrCreateDefaultGoal, deleteEdge as dbDeleteEdge, getEdgeByProjectAndId, getProject, getTask, listEdges, listTasks, updateEdge, updateProject, updateTask, } from '@plandesk/db';
 import { serializeEdge, serializeTask } from '../serialize.js';
 export class InvalidCanvasError extends Error {
     constructor(message) {
@@ -93,6 +93,7 @@ export function createCanvasService(deps) {
                     }
                     const created = createTask(tx, {
                         projectId,
+                        goalId: getOrCreateDefaultGoal(tx, projectId).id,
                         id: node.id,
                         label: node.label,
                         status: 'todo',