@plandesk/api 0.16.0 → 0.18.0

package/dist/events.d.ts

@@ -52,6 +52,16 @@ export type NoteUpdatedEvent = {
     noteId: string;
     projectId: string;
 };
+export type ArtifactCreatedEvent = {
+    type: 'artifact_created';
+    artifactId: string;
+    projectId: string;
+};
+export type ArtifactUpdatedEvent = {
+    type: 'artifact_updated';
+    artifactId: string;
+    projectId: string;
+};
 export type AgentRunStartedEvent = {
     type: 'agent_run_started';
     runId: string;
@@ -76,7 +86,7 @@ export type GoalUpdatedEvent = {
     goalId: string;
     projectId: string;
 };
-export type PlankDeskEvent = TaskUpdatedEvent | TagUpdatedEvent | CanvasUpdatedEvent | DocumentCreatedEvent | CommentCreatedEvent | CommentUpdatedEvent | FolderCreatedEvent | FolderUpdatedEvent | NoteCreatedEvent | NoteUpdatedEvent | AgentRunStartedEvent | AgentRunProgressEvent | AgentRunCompletedEvent | SubmissionsPulledEvent | GoalUpdatedEvent;
+export type PlankDeskEvent = TaskUpdatedEvent | TagUpdatedEvent | CanvasUpdatedEvent | DocumentCreatedEvent | CommentCreatedEvent | CommentUpdatedEvent | FolderCreatedEvent | FolderUpdatedEvent | NoteCreatedEvent | NoteUpdatedEvent | ArtifactCreatedEvent | ArtifactUpdatedEvent | AgentRunStartedEvent | AgentRunProgressEvent | AgentRunCompletedEvent | SubmissionsPulledEvent | GoalUpdatedEvent;
 export type EventListener = (event: PlankDeskEvent) => void;
 export type EventBus = {
     subscribe(listener: EventListener): () => void;

package/dist/index.d.ts

@@ -14,17 +14,20 @@ export type { CanvasService } from './services/canvas.js';
 export type { DocumentService } from './services/documents.js';
 export type { FolderService } from './services/folders.js';
 export type { NoteService } from './services/notes.js';
+export type { FileService } from './services/files.js';
+export type { ArtifactService } from './services/artifacts.js';
 export type { CommentService } from './services/comments.js';
 export type { AgentRunService } from './services/agent-runs.js';
 export { InvalidDocumentError } from './services/documents.js';
 export { InvalidFolderError } from './services/folders.js';
 export { InvalidNoteError } from './services/notes.js';
+export { InvalidArtifactError } from './services/artifacts.js';
 export { InvalidTagError } from './services/tags.js';
 export { InvalidCommentError } from './services/comments.js';
 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 { InvalidShareError, type ShareService } from './services/share.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

@@ -9,6 +9,7 @@ export { InvalidGoalReferenceError } from './services/tasks.js';
 export { InvalidDocumentError } from './services/documents.js';
 export { InvalidFolderError } from './services/folders.js';
 export { InvalidNoteError } from './services/notes.js';
+export { InvalidArtifactError } from './services/artifacts.js';
 export { InvalidTagError } from './services/tags.js';
 export { InvalidCommentError } from './services/comments.js';
 export { InvalidCanvasError } from './services/canvas.js';

package/dist/routes/artifacts.d.ts

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

package/dist/routes/artifacts.js

@@ -0,0 +1,74 @@
+import { Hono } from 'hono';
+import { artifactKinds } from '@plandesk/db';
+import { InvalidArtifactError } from '../services/artifacts.js';
+function isValidKind(kind) {
+    return artifactKinds.includes(kind);
+}
+export function createArtifactsRouter(artifactService) {
+    const router = new Hono();
+    router.get('/projects/:id/artifacts', (c) => {
+        const artifacts = artifactService.listByProject(c.req.param('id'));
+        if (!artifacts) {
+            return c.json({ error: 'not_found' }, 404);
+        }
+        return c.json(artifacts);
+    });
+    router.post('/projects/:id/artifacts', async (c) => {
+        const body = await c.req.json();
+        if (typeof body.title !== 'string' || body.title.trim() === '') {
+            return c.json({ error: 'invalid_argument' }, 400);
+        }
+        if (body.kind !== undefined && !isValidKind(body.kind)) {
+            return c.json({ error: 'invalid_argument' }, 400);
+        }
+        try {
+            const artifact = artifactService.create(c.req.param('id'), {
+                title: body.title,
+                kind: body.kind,
+                content: body.content,
+            });
+            if (!artifact) {
+                return c.json({ error: 'not_found' }, 404);
+            }
+            return c.json(artifact, 201);
+        }
+        catch (error) {
+            if (error instanceof InvalidArtifactError) {
+                return c.json({ error: 'invalid_argument' }, 400);
+            }
+            throw error;
+        }
+    });
+    router.get('/artifacts/:id', (c) => {
+        const artifact = artifactService.get(c.req.param('id'));
+        if (!artifact) {
+            return c.json({ error: 'not_found' }, 404);
+        }
+        return c.json(artifact);
+    });
+    router.patch('/artifacts/:id', async (c) => {
+        const body = await c.req.json();
+        if (body.kind !== undefined && !isValidKind(body.kind)) {
+            return c.json({ error: 'invalid_argument' }, 400);
+        }
+        try {
+            const artifact = artifactService.update(c.req.param('id'), {
+                ...(body.title !== undefined ? { title: body.title } : {}),
+                ...(body.kind !== undefined ? { kind: body.kind } : {}),
+                ...(body.content !== undefined ? { content: body.content } : {}),
+            });
+            if (!artifact) {
+                return c.json({ error: 'not_found' }, 404);
+            }
+            return c.json(artifact);
+        }
+        catch (error) {
+            if (error instanceof InvalidArtifactError) {
+                return c.json({ error: 'invalid_argument' }, 400);
+            }
+            throw error;
+        }
+    });
+    return router;
+}
+//# sourceMappingURL=artifacts.js.map

package/dist/routes/files.d.ts

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

package/dist/routes/files.js

@@ -0,0 +1,66 @@
+import { Hono } from 'hono';
+const MAX_FILE_BYTES = 10 * 1024 * 1024;
+// Content-Disposition is a quoted-string (RFC 6266): escape backslash/quote
+// and strip anything outside printable ASCII so a hostile filename (CRLF,
+// control chars) can't break out of the header.
+function sanitizeFilenameForHeader(filename) {
+    return filename
+        .replace(/[^\x20-\x7E]/g, '_')
+        .replace(/\\/g, '\\\\')
+        .replace(/"/g, '\\"');
+}
+export function createFilesRouter(fileService) {
+    const router = new Hono();
+    router.post('/projects/:id/files', async (c) => {
+        const body = await c.req.json();
+        if (typeof body.filename !== 'string' || body.filename.trim() === '') {
+            return c.json({ error: 'invalid_argument' }, 400);
+        }
+        if (typeof body.mime !== 'string' || body.mime.trim() === '') {
+            return c.json({ error: 'invalid_argument' }, 400);
+        }
+        if (typeof body.content_base64 !== 'string' || body.content_base64.length === 0) {
+            return c.json({ error: 'invalid_argument' }, 400);
+        }
+        const bytes = Buffer.from(body.content_base64, 'base64');
+        if (bytes.length > MAX_FILE_BYTES) {
+            return c.json({ error: 'file_too_large' }, 413);
+        }
+        const file = await fileService.create({
+            projectId: c.req.param('id'),
+            filename: body.filename,
+            mime: body.mime,
+            bytes,
+        });
+        if (!file) {
+            return c.json({ error: 'not_found' }, 404);
+        }
+        return c.json(file, 201);
+    });
+    router.get('/files/:id', async (c) => {
+        const resolved = await fileService.get(c.req.param('id'));
+        if (!resolved) {
+            return c.json({ error: 'not_found' }, 404);
+        }
+        if ('redirectUrl' in resolved) {
+            return c.redirect(resolved.redirectUrl, 302);
+        }
+        const headers = {
+            'X-Content-Type-Options': 'nosniff',
+        };
+        // Only image/* is safe to render inline; every other mime (including
+        // text/html) is forced to download so a user-uploaded file can never
+        // execute as active content in the browser.
+        if (resolved.mime.startsWith('image/')) {
+            headers['Content-Type'] = resolved.mime;
+        }
+        else {
+            headers['Content-Type'] = 'application/octet-stream';
+            headers['Content-Disposition'] =
+                `attachment; filename="${sanitizeFilenameForHeader(resolved.filename)}"`;
+        }
+        return c.body(new Uint8Array(resolved.bytes), 200, headers);
+    });
+    return router;
+}
+//# sourceMappingURL=files.js.map

package/dist/routes/shares.d.ts

@@ -0,0 +1,4 @@
+import { Hono } from 'hono';
+import type { ShareService } from '../services/share.js';
+export declare function createSharesRouter(shareService: ShareService): Hono;
+//# sourceMappingURL=shares.d.ts.map

package/dist/routes/shares.js

@@ -0,0 +1,24 @@
+import { Hono } from 'hono';
+export function createSharesRouter(shareService) {
+    const router = new Hono();
+    // Hono doesn't match a literal `.md` suffix inside a param, so the route
+    // takes the raw segment and the handler enforces + strips the extension.
+    router.get('/share/:tokenWithExt', (c) => {
+        const raw = c.req.param('tokenWithExt');
+        if (!raw.endsWith('.md')) {
+            return c.notFound();
+        }
+        const token = raw.slice(0, -'.md'.length);
+        const origin = new URL(c.req.url).origin;
+        const result = shareService.getResourceMarkdown(token, origin);
+        if (result.status === 'not_found') {
+            return c.json({ error: 'not_found' }, 404);
+        }
+        if (result.status === 'gone') {
+            return c.json({ error: 'gone' }, 410);
+        }
+        return c.body(result.markdown, 200, { 'Content-Type': 'text/markdown; charset=utf-8' });
+    });
+    return router;
+}
+//# sourceMappingURL=shares.js.map

package/dist/serialize.d.ts

@@ -1,4 +1,4 @@
-import type { AgentRun, AgentRunEvent, Document, Comment, Edge, Folder, Goal, Note, Project, Tag, Task, TaskStatus } from '@plandesk/db';
+import type { AgentRun, AgentRunEvent, Artifact, Document, Comment, Edge, Folder, Goal, Note, Project, Tag, Task, TaskStatus } from '@plandesk/db';
 export type PaginationParams = {
     limit?: number;
     offset?: number;
@@ -89,6 +89,23 @@ export type SerializedNote = {
     updated_at: string;
 };
 export declare function serializeNote(note: Note): SerializedNote;
+export type SerializedArtifact = {
+    id: string;
+    project_id: string;
+    title: string;
+    kind: Artifact['kind'];
+    content: string;
+    created_at: string;
+    updated_at: string;
+};
+export type SerializedArtifactSummary = {
+    id: string;
+    title: string;
+    kind: Artifact['kind'];
+    updated_at: string;
+};
+export declare function serializeArtifact(artifact: Artifact): SerializedArtifact;
+export declare function serializeArtifactSummary(artifact: Artifact): SerializedArtifactSummary;
 export type SerializedComment = {
     id: string;
     target_type: Comment['targetType'];

package/dist/serialize.js

@@ -120,6 +120,25 @@ export function serializeNote(note) {
         updated_at: note.updatedAt.toISOString(),
     };
 }
+export function serializeArtifact(artifact) {
+    return {
+        id: artifact.id,
+        project_id: artifact.projectId,
+        title: artifact.title,
+        kind: artifact.kind,
+        content: artifact.content,
+        created_at: artifact.createdAt.toISOString(),
+        updated_at: artifact.updatedAt.toISOString(),
+    };
+}
+export function serializeArtifactSummary(artifact) {
+    return {
+        id: artifact.id,
+        title: artifact.title,
+        kind: artifact.kind,
+        updated_at: artifact.updatedAt.toISOString(),
+    };
+}
 export function serializeComment(comment) {
     return {
         id: comment.id,

package/dist/server.js

@@ -7,8 +7,11 @@ import { createTagsRouter } from './routes/tags.js';
 import { createCanvasRouter } from './routes/canvas.js';
 import { createCommentsRouter } from './routes/comments.js';
 import { createDocumentsRouter } from './routes/documents.js';
+import { createArtifactsRouter } from './routes/artifacts.js';
+import { createFilesRouter } from './routes/files.js';
 import { createFoldersRouter } from './routes/folders.js';
 import { createNotesRouter } from './routes/notes.js';
+import { createSharesRouter } from './routes/shares.js';
 import { createEventsRouter } from './routes/events.js';
 import { createTokensRouter } from './routes/tokens.js';
 import { createAgentRunsRouter } from './routes/agent-runs.js';
@@ -18,7 +21,7 @@ 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, goalService, taskService, tagService, canvasService, documentService, folderService, noteService, commentService, agentRunService, tokenService, syncService, } = services;
+    const { eventBus, projectService, goalService, taskService, tagService, canvasService, documentService, folderService, noteService, commentService, agentRunService, tokenService, syncService, fileService, artifactService, shareService, } = services;
     const app = new Hono();
     if (deps.authPassword !== undefined && deps.authPassword.length > 0) {
         app.use('*', createAuthMiddleware(deps.authPassword));
@@ -30,8 +33,11 @@ export function createApp(deps) {
     app.route('/api/v1', createTagsRouter(tagService));
     app.route('/api/v1', createCanvasRouter(canvasService));
     app.route('/api/v1', createDocumentsRouter(documentService));
+    app.route('/api/v1', createFilesRouter(fileService));
+    app.route('/api/v1', createArtifactsRouter(artifactService));
     app.route('/api/v1', createFoldersRouter(folderService));
     app.route('/api/v1', createNotesRouter(noteService));
+    app.route('/api/v1', createSharesRouter(shareService));
     app.route('/api/v1', createCommentsRouter(commentService));
     app.route('/api/v1', createTokensRouter(tokenService));
     app.route('/api/v1', createAgentRunsRouter(agentRunService));

package/dist/services/artifacts.d.ts

@@ -0,0 +1,28 @@
+import { type ArtifactKind, type Db } from '@plandesk/db';
+import { type SerializedArtifact, type SerializedArtifactSummary } from '../serialize.js';
+import type { EventBus } from '../events.js';
+export type ArtifactServiceDeps = {
+    db: Db;
+    eventBus: EventBus;
+};
+export type CreateArtifactInput = {
+    title: string;
+    kind?: ArtifactKind;
+    content?: string;
+};
+export type UpdateArtifactInput = {
+    title?: string;
+    kind?: ArtifactKind;
+    content?: string;
+};
+export declare class InvalidArtifactError extends Error {
+    constructor(message: string);
+}
+export declare function createArtifactService(deps: ArtifactServiceDeps): {
+    listByProject(projectId: string): SerializedArtifactSummary[] | undefined;
+    create(projectId: string, input: CreateArtifactInput): SerializedArtifact | undefined;
+    get(id: string): SerializedArtifact | undefined;
+    update(id: string, input: UpdateArtifactInput): SerializedArtifact | undefined;
+};
+export type ArtifactService = ReturnType<typeof createArtifactService>;
+//# sourceMappingURL=artifacts.d.ts.map

package/dist/services/artifacts.js

@@ -0,0 +1,71 @@
+import { createArtifact as dbCreateArtifact, getArtifact as dbGetArtifact, getProject, listArtifactsByProject as dbListArtifactsByProject, updateArtifact as dbUpdateArtifact, } from '@plandesk/db';
+import { serializeArtifact, serializeArtifactSummary, } from '../serialize.js';
+export class InvalidArtifactError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = 'InvalidArtifactError';
+    }
+}
+function assertNonEmptyTitle(title) {
+    if (title.trim() === '') {
+        throw new InvalidArtifactError('Artifact title must not be empty');
+    }
+}
+export function createArtifactService(deps) {
+    const { db, eventBus } = deps;
+    return {
+        listByProject(projectId) {
+            const project = getProject(db, projectId);
+            if (!project) {
+                return undefined;
+            }
+            return dbListArtifactsByProject(db, projectId).map(serializeArtifactSummary);
+        },
+        create(projectId, input) {
+            const project = getProject(db, projectId);
+            if (!project) {
+                return undefined;
+            }
+            assertNonEmptyTitle(input.title);
+            const artifact = dbCreateArtifact(db, {
+                projectId,
+                title: input.title,
+                kind: input.kind,
+                content: input.content,
+            });
+            eventBus.emit({
+                type: 'artifact_created',
+                artifactId: artifact.id,
+                projectId,
+            });
+            return serializeArtifact(artifact);
+        },
+        get(id) {
+            const artifact = dbGetArtifact(db, id);
+            if (!artifact) {
+                return undefined;
+            }
+            return serializeArtifact(artifact);
+        },
+        update(id, input) {
+            const existing = dbGetArtifact(db, id);
+            if (!existing) {
+                return undefined;
+            }
+            if (input.title !== undefined) {
+                assertNonEmptyTitle(input.title);
+            }
+            const artifact = dbUpdateArtifact(db, id, input);
+            if (!artifact) {
+                return undefined;
+            }
+            eventBus.emit({
+                type: 'artifact_updated',
+                artifactId: artifact.id,
+                projectId: artifact.projectId,
+            });
+            return serializeArtifact(artifact);
+        },
+    };
+}
+//# sourceMappingURL=artifacts.js.map

package/dist/services/files.d.ts

@@ -0,0 +1,25 @@
+import { type Db } from '@plandesk/db';
+import type { StorageAdapter, StorageResolveResult } from '../storage/adapter.js';
+export type FileServiceDeps = {
+    db: Db;
+    storage: StorageAdapter;
+};
+export type CreateFileInput = {
+    projectId: string;
+    filename: string;
+    mime: string;
+    bytes: Buffer;
+};
+export type CreatedFile = {
+    id: string;
+    url: string;
+    filename: string;
+    mime: string;
+    size: number;
+};
+export declare function createFileService(deps: FileServiceDeps): {
+    create(input: CreateFileInput): Promise<CreatedFile | undefined>;
+    get(id: string): Promise<StorageResolveResult | undefined>;
+};
+export type FileService = ReturnType<typeof createFileService>;
+//# sourceMappingURL=files.d.ts.map

package/dist/services/files.js

@@ -0,0 +1,31 @@
+import { getFile, getProject } from '@plandesk/db';
+export function createFileService(deps) {
+    const { db, storage } = deps;
+    return {
+        async create(input) {
+            const project = getProject(db, input.projectId);
+            if (!project) {
+                return undefined;
+            }
+            const { id, url } = await storage.put({
+                projectId: input.projectId,
+                bytes: input.bytes,
+                filename: input.filename,
+                mime: input.mime,
+            });
+            // Content-addressed dedup means the persisted row may reflect an
+            // earlier upload of the same bytes — read it back rather than echoing
+            // this call's input, so the response always matches what is stored.
+            const file = getFile(db, id);
+            if (!file) {
+                throw new Error(`Storage adapter did not persist file metadata for ${id}`);
+            }
+            return { id, url, filename: file.filename, mime: file.mime, size: file.size };
+        },
+        async get(id) {
+            const resolved = await storage.resolve(id);
+            return resolved ?? undefined;
+        },
+    };
+}
+//# sourceMappingURL=files.js.map

package/dist/services/index.d.ts

@@ -1,8 +1,11 @@
 import type { Db } from '@plandesk/db';
 import { type EventBus } from '../events.js';
+import { type StorageAdapter } from '../storage/index.js';
 import { type CanvasService } from './canvas.js';
 import { type CommentService } from './comments.js';
 import { type DocumentService } from './documents.js';
+import { type ArtifactService } from './artifacts.js';
+import { type FileService } from './files.js';
 import { type FolderService } from './folders.js';
 import { type NoteService } from './notes.js';
 import { type ProjectService } from './projects.js';
@@ -16,6 +19,7 @@ import { type SyncService } from './sync.js';
 export type ServicesDeps = {
     db: Db;
     eventBus?: EventBus;
+    storage?: StorageAdapter;
 };
 export type Services = {
     eventBus: EventBus;
@@ -32,6 +36,8 @@ export type Services = {
     tokenService: TokenService;
     shareService: ShareService;
     syncService: SyncService;
+    fileService: FileService;
+    artifactService: ArtifactService;
 };
 export declare function createServices(deps: ServicesDeps): Services;
 //# sourceMappingURL=index.d.ts.map

package/dist/services/index.js

@@ -1,7 +1,10 @@
 import { createEventBus } from '../events.js';
+import { createStorageAdapter } from '../storage/index.js';
 import { createCanvasService } from './canvas.js';
 import { createCommentService } from './comments.js';
 import { createDocumentService } from './documents.js';
+import { createArtifactService } from './artifacts.js';
+import { createFileService } from './files.js';
 import { createFolderService } from './folders.js';
 import { createNoteService } from './notes.js';
 import { createProjectService } from './projects.js';
@@ -14,6 +17,7 @@ import { createShareService } from './share.js';
 import { createSyncService } from './sync.js';
 export function createServices(deps) {
     const eventBus = deps.eventBus ?? createEventBus();
+    const storage = deps.storage ?? createStorageAdapter({ db: deps.db });
     const projectService = createProjectService({ db: deps.db, eventBus });
     const goalService = createGoalService({ db: deps.db, eventBus });
     const taskService = createTaskService({ db: deps.db, eventBus });
@@ -27,6 +31,8 @@ export function createServices(deps) {
     const tokenService = createTokenService({ db: deps.db });
     const shareService = createShareService({ db: deps.db, eventBus });
     const syncService = createSyncService({ db: deps.db, eventBus, taskService, shareService });
+    const fileService = createFileService({ db: deps.db, storage });
+    const artifactService = createArtifactService({ db: deps.db, eventBus });
     return {
         eventBus,
         projectService,
@@ -42,6 +48,8 @@ export function createServices(deps) {
         tokenService,
         shareService,
         syncService,
+        fileService,
+        artifactService,
     };
 }
 //# sourceMappingURL=index.js.map

package/dist/services/share.d.ts

@@ -28,6 +28,31 @@ export type CreateShareInput = {
     invitedEmails?: string[];
     expiresAt?: Date;
 };
+export type ShareResourceRef = {
+    kind: 'task';
+    id: string;
+} | {
+    kind: 'document';
+    id: string;
+};
+export type CreateResourceShareInput = {
+    resource: ShareResourceRef;
+    expiresAt?: Date | null;
+};
+export type ResourceShareResult = {
+    token: string;
+    url: string;
+    markdownUrl: string;
+    expiresAt: string | null;
+};
+export type ResourceMarkdownResult = {
+    status: 'ok';
+    markdown: string;
+} | {
+    status: 'not_found';
+} | {
+    status: 'gone';
+};
 export declare function createShareService(deps: ShareServiceDeps): {
     createShare(projectId: string, input: CreateShareInput): {
         share: SerializedShare;
@@ -36,6 +61,8 @@ export declare function createShareService(deps: ShareServiceDeps): {
     listShares(projectId: string): SerializedShare[] | undefined;
     revokeShare(id: string): boolean;
     buildClientView(projectId: string, shareId: string): ClientView | undefined;
+    createResourceShare(input: CreateResourceShareInput, origin: string): ResourceShareResult | undefined;
+    getResourceMarkdown(token: string, origin: string): ResourceMarkdownResult;
 };
 export type ShareService = ReturnType<typeof createShareService>;
 //# sourceMappingURL=share.d.ts.map