@shipfox/api-workspaces 2.0.0

package/src/presentation/routes/invitations/create.ts

@@ -0,0 +1,60 @@
+import {AUTH_USER, getUserContext} from '@shipfox/api-auth-context';
+import {createInvitationBodySchema, invitationDtoSchema} from '@shipfox/api-workspaces-dto';
+import {ClientError, defineRoute} from '@shipfox/node-fastify';
+import {z} from 'zod';
+import {
+  MembershipRequiredError,
+  OpenInvitationExistsError,
+  WorkspaceInactiveError,
+  WorkspaceNotFoundError,
+} from '#core/errors.js';
+import {createWorkspaceInvitation} from '#core/index.js';
+import {toInvitationDto} from '#presentation/dto/index.js';
+
+export const createInvitationRoute = defineRoute({
+  method: 'POST',
+  path: '/',
+  description: 'Invite someone to join a workspace by email.',
+  auth: AUTH_USER,
+  schema: {
+    params: z.object({workspaceId: z.string().uuid()}),
+    body: createInvitationBodySchema,
+    response: {
+      201: invitationDtoSchema,
+    },
+  },
+  errorHandler: (error) => {
+    if (error instanceof WorkspaceNotFoundError) {
+      throw new ClientError('Workspace not found', 'not-found', {status: 404});
+    }
+    if (error instanceof MembershipRequiredError) {
+      throw new ClientError('Not a member of this workspace', 'forbidden', {status: 403});
+    }
+    if (error instanceof OpenInvitationExistsError) {
+      throw new ClientError(error.message, 'open-invitation-exists', {status: 409});
+    }
+    if (error instanceof WorkspaceInactiveError) {
+      throw new ClientError('Workspace is not active', 'workspace-inactive', {status: 403});
+    }
+    throw error;
+  },
+  handler: async (request, reply) => {
+    const client = getUserContext(request);
+    if (!client) {
+      throw new ClientError('Authentication required', 'unauthorized', {status: 401});
+    }
+
+    const {workspaceId} = request.params;
+    const {email} = request.body;
+    const invitation = await createWorkspaceInvitation({
+      workspaceId,
+      email,
+      invitedByUserId: client.userId,
+      invitedByDisplay: client.name ?? 'A workspace admin',
+      invitedByMemberships: client.memberships,
+    });
+
+    reply.code(201);
+    return toInvitationDto(invitation);
+  },
+});

package/src/presentation/routes/invitations/index.ts

@@ -0,0 +1,17 @@
+import type {RouteDefinition, RouteGroup} from '@shipfox/node-fastify';
+import {acceptInvitationRoute} from './accept.js';
+import {createInvitationRoute} from './create.js';
+import {listInvitationsRoute} from './list.js';
+import {previewInvitationRoute} from './preview.js';
+import {revokeInvitationRoute} from './revoke.js';
+
+export const invitationsWorkspaceScopedRoutes: RouteDefinition[] = [
+  createInvitationRoute,
+  listInvitationsRoute,
+  revokeInvitationRoute,
+];
+
+export const invitationsAcceptGroup: RouteGroup = {
+  prefix: '/invitations',
+  routes: [acceptInvitationRoute, previewInvitationRoute],
+};

package/src/presentation/routes/invitations/list.test.ts

@@ -0,0 +1,94 @@
+import type {FastifyInstance} from 'fastify';
+import {
+  createExpiredInvite,
+  createInvite,
+  createWorkspace,
+  createWorkspacesTestApp,
+  resetCapturedMail,
+  signupVerifyLogin,
+  uniqueEmail,
+} from '#test/routes.js';
+
+describe('GET /workspaces/:workspaceId/invitations', () => {
+  let app: FastifyInstance;
+
+  beforeAll(async () => {
+    app = await createWorkspacesTestApp();
+  });
+
+  beforeEach(() => {
+    resetCapturedMail();
+  });
+
+  afterAll(async () => {
+    await app.close();
+  });
+
+  test('returns open invitations for a workspace member', async () => {
+    const owner = await signupVerifyLogin(app, 'invite-list-owner');
+    const workspaceId = await createWorkspace(app, owner.token);
+    const inviteeEmail = uniqueEmail('invite-list');
+    const invite = await createInvite(app, {token: owner.token, workspaceId, email: inviteeEmail});
+
+    const res = await app.inject({
+      method: 'GET',
+      url: `/workspaces/${workspaceId}/invitations`,
+      headers: {authorization: `Bearer ${owner.token}`},
+    });
+
+    expect(res.statusCode).toBe(200);
+    expect(res.json().invitations).toEqual([
+      expect.objectContaining({
+        id: invite.id,
+        workspace_id: workspaceId,
+        email: inviteeEmail,
+      }),
+    ]);
+  });
+
+  test('excludes expired unaccepted invitations', async () => {
+    const owner = await signupVerifyLogin(app, 'invite-list-expired-owner');
+    const workspaceId = await createWorkspace(app, owner.token);
+    await createExpiredInvite({
+      workspaceId,
+      email: uniqueEmail('invite-list-expired'),
+      invitedByUserId: owner.userId,
+    });
+
+    const res = await app.inject({
+      method: 'GET',
+      url: `/workspaces/${workspaceId}/invitations`,
+      headers: {authorization: `Bearer ${owner.token}`},
+    });
+
+    expect(res.statusCode).toBe(200);
+    expect(res.json().invitations).toEqual([]);
+  });
+
+  test('transforms missing membership into 403', async () => {
+    const outsider = await signupVerifyLogin(app, 'invite-list-outsider');
+    const workspaceId = crypto.randomUUID();
+
+    const res = await app.inject({
+      method: 'GET',
+      url: `/workspaces/${workspaceId}/invitations`,
+      headers: {authorization: `Bearer ${outsider.token}`},
+    });
+
+    expect(res.statusCode).toBe(403);
+    expect(res.json().code).toBe('forbidden');
+  });
+
+  test('returns 403 when caller has no claim to the workspace (whether or not it exists)', async () => {
+    const owner = await signupVerifyLogin(app, 'invite-list-missing-workspace');
+
+    const res = await app.inject({
+      method: 'GET',
+      url: `/workspaces/${crypto.randomUUID()}/invitations`,
+      headers: {authorization: `Bearer ${owner.token}`},
+    });
+
+    expect(res.statusCode).toBe(403);
+    expect(res.json().code).toBe('forbidden');
+  });
+});

package/src/presentation/routes/invitations/list.ts

@@ -0,0 +1,53 @@
+import {AUTH_USER, getUserContext} from '@shipfox/api-auth-context';
+import {listInvitationsResponseSchema} from '@shipfox/api-workspaces-dto';
+import {ClientError, defineRoute} from '@shipfox/node-fastify';
+import {z} from 'zod';
+import {
+  MembershipRequiredError,
+  WorkspaceInactiveError,
+  WorkspaceNotFoundError,
+} from '#core/errors.js';
+import {listWorkspaceInvitations} from '#core/index.js';
+import {toInvitationDto} from '#presentation/dto/index.js';
+
+export const listInvitationsRoute = defineRoute({
+  method: 'GET',
+  path: '/',
+  description: 'List pending invitations for a workspace.',
+  auth: AUTH_USER,
+  schema: {
+    params: z.object({workspaceId: z.string().uuid()}),
+    response: {
+      200: listInvitationsResponseSchema,
+    },
+  },
+  errorHandler: (error) => {
+    if (error instanceof WorkspaceNotFoundError) {
+      throw new ClientError('Workspace not found', 'not-found', {status: 404});
+    }
+    if (error instanceof MembershipRequiredError) {
+      throw new ClientError('Not a member of this workspace', 'forbidden', {status: 403});
+    }
+    if (error instanceof WorkspaceInactiveError) {
+      throw new ClientError('Workspace is not active', 'workspace-inactive', {status: 403});
+    }
+    throw error;
+  },
+  handler: async (request) => {
+    const client = getUserContext(request);
+    if (!client) {
+      throw new ClientError('Authentication required', 'unauthorized', {status: 401});
+    }
+
+    const {workspaceId} = request.params;
+    const invitations = await listWorkspaceInvitations({
+      workspaceId,
+      requesterUserId: client.userId,
+      requesterMemberships: client.memberships,
+    });
+
+    return {
+      invitations: invitations.map(toInvitationDto),
+    };
+  },
+});

package/src/presentation/routes/invitations/preview.test.ts

@@ -0,0 +1,140 @@
+import type {FastifyInstance} from 'fastify';
+import {
+  createExpiredInvite,
+  createInvite,
+  createWorkspace,
+  createWorkspacesTestApp,
+  resetCapturedMail,
+  signupVerifyLogin,
+  uniqueEmail,
+} from '#test/routes.js';
+
+describe('GET /invitations/preview', () => {
+  let app: FastifyInstance;
+
+  beforeAll(async () => {
+    app = await createWorkspacesTestApp();
+  });
+
+  beforeEach(() => {
+    resetCapturedMail();
+  });
+
+  afterAll(async () => {
+    await app.close();
+  });
+
+  test('returns pending invitation metadata without authentication', async () => {
+    const owner = await signupVerifyLogin(app, 'invite-preview-owner');
+    const workspaceId = await createWorkspace(app, owner.token, 'Acme');
+    const inviteeEmail = uniqueEmail('invite-preview');
+    const invite = await createInvite(app, {
+      token: owner.token,
+      workspaceId,
+      email: inviteeEmail,
+    });
+
+    const res = await app.inject({
+      method: 'GET',
+      url: `/invitations/preview?token=${encodeURIComponent(invite.rawToken)}`,
+    });
+
+    expect(res.statusCode).toBe(200);
+    expect(res.json()).toEqual(
+      expect.objectContaining({
+        status: 'pending',
+        workspace_id: workspaceId,
+        workspace_name: 'Acme',
+        email: inviteeEmail,
+        invited_by_display: 'A workspace admin',
+        expires_at: expect.any(String),
+      }),
+    );
+  });
+
+  test('surfaces the inviter display name when the owner has one', async () => {
+    const owner = await signupVerifyLogin(app, 'invite-preview-named-owner', {name: 'Owner User'});
+    const workspaceId = await createWorkspace(app, owner.token, 'Named Co');
+    const invite = await createInvite(app, {
+      token: owner.token,
+      workspaceId,
+      email: uniqueEmail('invite-preview-named'),
+    });
+
+    const res = await app.inject({
+      method: 'GET',
+      url: `/invitations/preview?token=${encodeURIComponent(invite.rawToken)}`,
+    });
+
+    expect(res.statusCode).toBe(200);
+    expect(res.json()).toEqual(
+      expect.objectContaining({
+        status: 'pending',
+        invited_by_display: 'Owner User',
+      }),
+    );
+  });
+
+  test('returns invalid for unknown tokens', async () => {
+    const res = await app.inject({
+      method: 'GET',
+      url: `/invitations/preview?token=${encodeURIComponent(`missing-${crypto.randomUUID()}`)}`,
+    });
+
+    expect(res.statusCode).toBe(200);
+    expect(res.json()).toEqual({status: 'invalid'});
+  });
+
+  test('returns expired metadata for expired invitations', async () => {
+    const owner = await signupVerifyLogin(app, 'invite-preview-expired-owner');
+    const workspaceId = await createWorkspace(app, owner.token, 'Expired Co');
+    const rawToken = await createExpiredInvite({
+      workspaceId,
+      email: uniqueEmail('invite-preview-expired'),
+      invitedByUserId: owner.userId,
+    });
+
+    const res = await app.inject({
+      method: 'GET',
+      url: `/invitations/preview?token=${encodeURIComponent(rawToken)}`,
+    });
+
+    expect(res.statusCode).toBe(200);
+    expect(res.json()).toEqual(
+      expect.objectContaining({
+        status: 'expired',
+        workspace_name: 'Expired Co',
+        expires_at: expect.any(String),
+      }),
+    );
+  });
+
+  test('returns already_used after an invitation is accepted', async () => {
+    const owner = await signupVerifyLogin(app, 'invite-preview-used-owner');
+    const guest = await signupVerifyLogin(app, 'invite-preview-used-guest');
+    const workspaceId = await createWorkspace(app, owner.token, 'Used Inc');
+    const invite = await createInvite(app, {
+      token: owner.token,
+      workspaceId,
+      email: guest.email,
+    });
+    const accept = await app.inject({
+      method: 'POST',
+      url: '/invitations/accept',
+      headers: {authorization: `Bearer ${guest.token}`},
+      payload: {token: invite.rawToken},
+    });
+
+    const res = await app.inject({
+      method: 'GET',
+      url: `/invitations/preview?token=${encodeURIComponent(invite.rawToken)}`,
+    });
+
+    expect(accept.statusCode).toBe(201);
+    expect(res.statusCode).toBe(200);
+    expect(res.json()).toEqual({
+      status: 'already_used',
+      workspace_name: 'Used Inc',
+    });
+  });
+});

package/src/presentation/routes/invitations/preview.ts

@@ -0,0 +1,46 @@
+import {
+  previewInvitationQuerySchema,
+  previewInvitationResponseSchema,
+} from '@shipfox/api-workspaces-dto';
+import {defineRoute} from '@shipfox/node-fastify';
+import {previewInvitation} from '#core/index.js';
+
+export const previewInvitationRoute = defineRoute({
+  method: 'GET',
+  path: '/preview',
+  description: 'Preview an invitation by opaque token (public, no auth).',
+  schema: {
+    querystring: previewInvitationQuerySchema,
+    response: {
+      200: previewInvitationResponseSchema,
+    },
+  },
+  handler: async (request) => {
+    const result = await previewInvitation({token: request.query.token});
+
+    switch (result.status) {
+      case 'pending':
+        return {
+          status: 'pending' as const,
+          workspace_id: result.workspaceId,
+          workspace_name: result.workspaceName,
+          email: result.email,
+          invited_by_display: result.invitedByDisplay,
+          expires_at: result.expiresAt.toISOString(),
+        };
+      case 'expired':
+        return {
+          status: 'expired' as const,
+          workspace_name: result.workspaceName,
+          expires_at: result.expiresAt.toISOString(),
+        };
+      case 'already_used':
+        return {
+          status: 'already_used' as const,
+          workspace_name: result.workspaceName,
+        };
+      case 'invalid':
+        return {status: 'invalid' as const};
+    }
+  },
+});

package/src/presentation/routes/invitations/revoke.test.ts

@@ -0,0 +1,99 @@
+import type {FastifyInstance} from 'fastify';
+import {
+  createInvite,
+  createWorkspace,
+  createWorkspacesTestApp,
+  resetCapturedMail,
+  signupVerifyLogin,
+  uniqueEmail,
+} from '#test/routes.js';
+
+describe('DELETE /workspaces/:workspaceId/invitations/:invitationId', () => {
+  let app: FastifyInstance;
+
+  beforeAll(async () => {
+    app = await createWorkspacesTestApp();
+  });
+
+  beforeEach(() => {
+    resetCapturedMail();
+  });
+
+  afterAll(async () => {
+    await app.close();
+  });
+
+  test('returns 204 and removes an open invitation', async () => {
+    const owner = await signupVerifyLogin(app, 'invite-revoke-owner');
+    const workspaceId = await createWorkspace(app, owner.token);
+    const invite = await createInvite(app, {
+      token: owner.token,
+      workspaceId,
+      email: uniqueEmail('invite-revoke'),
+    });
+
+    const revoke = await app.inject({
+      method: 'DELETE',
+      url: `/workspaces/${workspaceId}/invitations/${invite.id}`,
+      headers: {authorization: `Bearer ${owner.token}`},
+    });
+    const list = await app.inject({
+      method: 'GET',
+      url: `/workspaces/${workspaceId}/invitations`,
+      headers: {authorization: `Bearer ${owner.token}`},
+    });
+
+    expect(revoke.statusCode).toBe(204);
+    expect(list.statusCode).toBe(200);
+    expect(list.json().invitations).toHaveLength(0);
+  });
+
+  test('transforms missing invitation into 404', async () => {
+    const owner = await signupVerifyLogin(app, 'invite-revoke-missing');
+    const workspaceId = await createWorkspace(app, owner.token);
+
+    const res = await app.inject({
+      method: 'DELETE',
+      url: `/workspaces/${workspaceId}/invitations/${crypto.randomUUID()}`,
+      headers: {authorization: `Bearer ${owner.token}`},
+    });
+
+    expect(res.statusCode).toBe(404);
+    expect(res.json().code).toBe('not-found');
+  });
+
+  test('transforms invitation workspace mismatch into 403', async () => {
+    const owner = await signupVerifyLogin(app, 'invite-revoke-mismatch');
+    const firstWorkspaceId = await createWorkspace(app, owner.token);
+    const secondWorkspaceId = await createWorkspace(app, owner.token);
+    const invite = await createInvite(app, {
+      token: owner.token,
+      workspaceId: firstWorkspaceId,
+      email: uniqueEmail('mismatch-invitee'),
+    });
+
+    const res = await app.inject({
+      method: 'DELETE',
+      url: `/workspaces/${secondWorkspaceId}/invitations/${invite.id}`,
+      headers: {authorization: `Bearer ${owner.token}`},
+    });
+
+    expect(res.statusCode).toBe(403);
+    expect(res.json().code).toBe('forbidden');
+  });
+
+  test('transforms missing membership into 403', async () => {
+    const outsider = await signupVerifyLogin(app, 'invite-revoke-outsider');
+    const workspaceId = crypto.randomUUID();
+    const invitationId = crypto.randomUUID();
+
+    const res = await app.inject({
+      method: 'DELETE',
+      url: `/workspaces/${workspaceId}/invitations/${invitationId}`,
+      headers: {authorization: `Bearer ${outsider.token}`},
+    });
+
+    expect(res.statusCode).toBe(403);
+    expect(res.json().code).toBe('forbidden');
+  });
+});

package/src/presentation/routes/invitations/revoke.ts

@@ -0,0 +1,64 @@
+import {AUTH_USER, getUserContext} from '@shipfox/api-auth-context';
+import {ClientError, defineRoute} from '@shipfox/node-fastify';
+import {z} from 'zod';
+import {
+  InvitationNotFoundError,
+  InvitationWorkspaceMismatchError,
+  MembershipRequiredError,
+  WorkspaceInactiveError,
+  WorkspaceNotFoundError,
+} from '#core/errors.js';
+import {revokeWorkspaceInvitation} from '#core/index.js';
+
+export const revokeInvitationRoute = defineRoute({
+  method: 'DELETE',
+  path: '/:invitationId',
+  description: 'Cancel a pending invitation.',
+  auth: AUTH_USER,
+  schema: {
+    params: z.object({
+      workspaceId: z.string().uuid(),
+      invitationId: z.string().uuid(),
+    }),
+    response: {
+      204: z.void(),
+    },
+  },
+  errorHandler: (error) => {
+    if (error instanceof WorkspaceNotFoundError) {
+      throw new ClientError('Workspace not found', 'not-found', {status: 404});
+    }
+    if (error instanceof MembershipRequiredError) {
+      throw new ClientError('Not a member of this workspace', 'forbidden', {status: 403});
+    }
+    if (error instanceof InvitationNotFoundError) {
+      throw new ClientError('Invitation not found', 'not-found', {status: 404});
+    }
+    if (error instanceof InvitationWorkspaceMismatchError) {
+      throw new ClientError('Invitation does not belong to this workspace', 'forbidden', {
+        status: 403,
+      });
+    }
+    if (error instanceof WorkspaceInactiveError) {
+      throw new ClientError('Workspace is not active', 'workspace-inactive', {status: 403});
+    }
+    throw error;
+  },
+  handler: async (request, reply) => {
+    const client = getUserContext(request);
+    if (!client) {
+      throw new ClientError('Authentication required', 'unauthorized', {status: 401});
+    }
+
+    const {workspaceId, invitationId} = request.params;
+
+    await revokeWorkspaceInvitation({
+      workspaceId,
+      invitationId,
+      requesterUserId: client.userId,
+      requesterMemberships: client.memberships,
+    });
+
+    reply.code(204);
+  },
+});

package/src/presentation/routes/members/index.ts

@@ -0,0 +1,5 @@
+import type {RouteDefinition} from '@shipfox/node-fastify';
+import {listMembersRoute} from './list.js';
+import {removeMemberRoute} from './remove.js';
+
+export const memberRoutes: RouteDefinition[] = [listMembersRoute, removeMemberRoute];

package/src/presentation/routes/members/list.test.ts

@@ -0,0 +1,95 @@
+import type {FastifyInstance} from 'fastify';
+import {createWorkspace as createWorkspaceRow} from '#db/workspaces.js';
+import {
+  createInvite,
+  createWorkspace,
+  createWorkspacesTestApp,
+  resetCapturedMail,
+  signupVerifyLogin,
+} from '#test/routes.js';
+
+describe('GET /workspaces/:workspaceId/members', () => {
+  let app: FastifyInstance;
+
+  beforeAll(async () => {
+    app = await createWorkspacesTestApp();
+  });
+
+  beforeEach(() => {
+    resetCapturedMail();
+  });
+
+  afterAll(async () => {
+    await app.close();
+  });
+
+  test('returns members for a workspace member', async () => {
+    const owner = await signupVerifyLogin(app, 'members-list-owner');
+    const guest = await signupVerifyLogin(app, 'members-list-guest');
+    const workspaceId = await createWorkspace(app, owner.token);
+    const invite = await createInvite(app, {token: owner.token, workspaceId, email: guest.email});
+    await app.inject({
+      method: 'POST',
+      url: '/invitations/accept',
+      headers: {authorization: `Bearer ${guest.token}`},
+      payload: {token: invite.rawToken},
+    });
+
+    const res = await app.inject({
+      method: 'GET',
+      url: `/workspaces/${workspaceId}/members`,
+      headers: {authorization: `Bearer ${owner.token}`},
+    });
+
+    expect(res.statusCode).toBe(200);
+    expect(
+      res
+        .json()
+        .members.map((member: {user_email: string}) => member.user_email)
+        .sort(),
+    ).toEqual([guest.email, owner.email].sort());
+  });
+
+  test('authorizes from a static membership claim without a membership row', async () => {
+    const userId = crypto.randomUUID();
+    const email = `members-list-claim-${crypto.randomUUID()}@example.com`;
+    const workspace = await createWorkspaceRow({name: `Workspace ${crypto.randomUUID()}`});
+    const token = `claim:${userId}:${email}:${workspace.id}`;
+
+    const res = await app.inject({
+      method: 'GET',
+      url: `/workspaces/${workspace.id}/members`,
+      headers: {authorization: `Bearer ${token}`},
+    });
+
+    expect(res.statusCode).toBe(200);
+    expect(res.json().members).toEqual([]);
+  });
+
+  test('transforms missing membership into 403', async () => {
+    const outsider = await signupVerifyLogin(app, 'members-list-outsider');
+    const workspaceId = crypto.randomUUID();
+
+    const res = await app.inject({
+      method: 'GET',
+      url: `/workspaces/${workspaceId}/members`,
+      headers: {authorization: `Bearer ${outsider.token}`},
+    });
+
+    expect(res.statusCode).toBe(403);
+    expect(res.json().code).toBe('forbidden');
+  });
+
+  test('returns 403 when caller has no claim to the workspace (whether or not it exists)', async () => {
+    const owner = await signupVerifyLogin(app, 'members-list-missing-workspace');
+
+    const res = await app.inject({
+      method: 'GET',
+      url: `/workspaces/${crypto.randomUUID()}/members`,
+      headers: {authorization: `Bearer ${owner.token}`},
+    });
+
+    expect(res.statusCode).toBe(403);
+    expect(res.json().code).toBe('forbidden');
+  });
+});