feat(api): links routes

Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>

lib/api/index.js

@@ -16,6 +16,7 @@ import { router as agentsRouter, tokensRouter as agentTokensRouter } from './rou
 import { router as conversationsRouter } from './routes/conversations.js';
 import { conversationsScopedRouter as messagesByConvRouter } from './routes/messages.js';
 import { router as tagsRouter, entityScopedRouter as tagsByEntityRouter } from './routes/tags.js';
+import { router as linksRouter } from './routes/links.js';
 
 export function mountApi(app) {
   const api = Router();
@@ -39,6 +40,7 @@ export function mountApi(app) {
   api.use('/conversations', conversationsRouter);
   api.use('/conversations/:conversation_id/messages', messagesByConvRouter);
   api.use('/tags', tagsRouter);
+  api.use('/links', linksRouter);
   api.use('/:entity_type/:entity_id/tags', tagsByEntityRouter);
 
   api.use((_req, _res, next) => next(new NotFoundError('route not found')));

lib/api/routes/links.js

@@ -0,0 +1,58 @@
+import { Router } from 'express';
+import { z } from 'zod';
+import * as repo from '../../db/repos/links.js';
+import { validate } from '../validate.js';
+import { requireWrite } from '../cap.js';
+import { asyncWrap } from '../errors.js';
+
+const ENTITY_TYPES = ['space','project','task','page','ref','resource','source_doc','conversation'];
+
+const createSchema = z.object({
+  from_type: z.enum(ENTITY_TYPES),
+  from_id: z.string().uuid(),
+  to_type: z.enum(ENTITY_TYPES),
+  to_id: z.string().uuid(),
+  relation: z.string().min(1).max(64).optional()
+});
+
+const endpointParams = z.object({
+  type: z.enum(ENTITY_TYPES),
+  id: z.string().uuid()
+});
+
+const idParams = z.object({ id: z.string().uuid() });
+
+export const router = Router();
+
+router.post('/',
+  requireWrite('link'),
+  validate({ body: createSchema }),
+  asyncWrap(async (req, res) => {
+    const { from_type, from_id, to_type, to_id, relation } = req.body;
+    const row = await repo.create(from_type, from_id, to_type, to_id, relation);
+    res.status(201).json(row);
+  })
+);
+
+router.get('/from/:type/:id',
+  validate({ params: endpointParams }),
+  asyncWrap(async (req, res) => {
+    res.json(await repo.listFrom(req.params.type, req.params.id));
+  })
+);
+
+router.get('/to/:type/:id',
+  validate({ params: endpointParams }),
+  asyncWrap(async (req, res) => {
+    res.json(await repo.listTo(req.params.type, req.params.id));
+  })
+);
+
+router.delete('/:id',
+  requireWrite('link'),
+  validate({ params: idParams }),
+  asyncWrap(async (req, res) => {
+    await repo.remove(req.params.id);
+    res.status(204).end();
+  })
+);

tests/api/links.test.js

@@ -0,0 +1,89 @@
+import { describe, it, expect, beforeAll, beforeEach } from 'vitest';
+import request from 'supertest';
+import { setup } from './helpers.js';
+import * as spacesRepo from '../../lib/db/repos/spaces.js';
+import * as projectsRepo from '../../lib/db/repos/projects.js';
+import * as pagesRepo from '../../lib/db/repos/pages.js';
+
+let app, ownerHeaders, space, project, page;
+const owner = { kind: 'user', id: null };
+
+beforeAll(async () => { ({ app, ownerHeaders } = await setup()); });
+beforeEach(async () => {
+  space = await spacesRepo.create({ slug: `s-${Date.now()}-${Math.random().toString(36).slice(2,5)}`, name: 'S' }, owner);
+  project = await projectsRepo.create({ space_id: space.id, slug: 'p', name: 'P' }, owner);
+  page = await pagesRepo.create({ space_id: space.id, slug: 'pg', title: 'PG' }, owner);
+});
+
+describe('links routes', () => {
+  it('POST creates link with default relation', async () => {
+    const res = await request(app).post('/api/links').set(ownerHeaders).send({
+      from_type: 'project', from_id: project.id,
+      to_type: 'page', to_id: page.id
+    });
+    expect(res.status).toBe(201);
+    expect(res.body.relation).toBe('attached');
+    expect(res.body.from_id).toBe(project.id);
+    expect(res.body.to_id).toBe(page.id);
+  });
+
+  it('POST is idempotent on the unique tuple', async () => {
+    const a = await request(app).post('/api/links').set(ownerHeaders).send({
+      from_type: 'project', from_id: project.id,
+      to_type: 'page', to_id: page.id, relation: 'mentions'
+    });
+    const b = await request(app).post('/api/links').set(ownerHeaders).send({
+      from_type: 'project', from_id: project.id,
+      to_type: 'page', to_id: page.id, relation: 'mentions'
+    });
+    expect(a.body.id).toBe(b.body.id);
+  });
+
+  it('GET /from/:type/:id and /to/:type/:id', async () => {
+    await request(app).post('/api/links').set(ownerHeaders).send({
+      from_type: 'project', from_id: project.id,
+      to_type: 'page', to_id: page.id, relation: 'mentions'
+    });
+    const from = await request(app).get(`/api/links/from/project/${project.id}`).set(ownerHeaders);
+    expect(from.status).toBe(200);
+    expect(from.body).toHaveLength(1);
+    expect(from.body[0].to_id).toBe(page.id);
+
+    const to = await request(app).get(`/api/links/to/page/${page.id}`).set(ownerHeaders);
+    expect(to.status).toBe(200);
+    expect(to.body).toHaveLength(1);
+    expect(to.body[0].from_id).toBe(project.id);
+  });
+
+  it('DELETE /:id removes the link', async () => {
+    const created = await request(app).post('/api/links').set(ownerHeaders).send({
+      from_type: 'project', from_id: project.id,
+      to_type: 'page', to_id: page.id
+    });
+    const del = await request(app).delete(`/api/links/${created.body.id}`).set(ownerHeaders);
+    expect(del.status).toBe(204);
+    const after = await request(app).get(`/api/links/from/project/${project.id}`).set(ownerHeaders);
+    expect(after.body).toHaveLength(0);
+  });
+
+  it('POST with unknown entity_type → 400', async () => {
+    const res = await request(app).post('/api/links').set(ownerHeaders).send({
+      from_type: 'widget', from_id: project.id,
+      to_type: 'page', to_id: page.id
+    });
+    expect(res.status).toBe(400);
+  });
+
+  it('GET /from with unknown type → 400', async () => {
+    const res = await request(app).get(`/api/links/from/widget/${project.id}`).set(ownerHeaders);
+    expect(res.status).toBe(400);
+  });
+
+  it('unauthenticated → 401', async () => {
+    const res = await request(app).post('/api/links').send({
+      from_type: 'project', from_id: project.id,
+      to_type: 'page', to_id: page.id
+    });
+    expect(res.status).toBe(401);
+  });
+});