@shipfox/api-workspaces 2.0.0

package/src/metrics/instance.test.ts

@@ -0,0 +1,74 @@
+const metricMocks = vi.hoisted(() => {
+  const counters = new Map<string, {add: ReturnType<typeof vi.fn>}>();
+  const createCounter = vi.fn((name: string) => {
+    const counter = {add: vi.fn()};
+    counters.set(name, counter);
+    return counter;
+  });
+
+  return {counters, createCounter};
+});
+
+vi.mock('@shipfox/node-opentelemetry', () => ({
+  instanceMetrics: {
+    getMeter: () => ({
+      createCounter: metricMocks.createCounter,
+    }),
+  },
+}));
+
+function counterAdd(name: string): ReturnType<typeof vi.fn> {
+  const counter = metricMocks.counters.get(name);
+  if (!counter) throw new Error(`Missing counter: ${name}`);
+  return counter.add;
+}
+
+let metrics: typeof import('./instance.js');
+
+describe('workspace metrics', () => {
+  beforeEach(async () => {
+    vi.resetModules();
+    metricMocks.counters.clear();
+    metrics = await import('./instance.js');
+  });
+
+  it('records workspace creation', () => {
+    metrics.recordWorkspaceCreated();
+
+    expect(counterAdd('workspaces_created')).toHaveBeenCalledWith(1);
+  });
+
+  it('records membership changes with bounded action labels', () => {
+    metrics.recordWorkspaceMembershipChanged('removed');
+
+    expect(counterAdd('workspaces_membership_changed')).toHaveBeenCalledWith(1, {
+      action: 'removed',
+    });
+  });
+
+  it('records invitation creation with email request labels', () => {
+    metrics.recordWorkspaceInvitationCreated('requested');
+
+    expect(counterAdd('workspaces_invitation_created')).toHaveBeenCalledWith(1, {
+      email_requested: 'requested',
+    });
+  });
+
+  it('records invitation acceptance outcomes', () => {
+    metrics.recordWorkspaceInvitationAccepted('already_member');
+
+    expect(counterAdd('workspaces_invitation_accepted')).toHaveBeenCalledWith(1, {
+      outcome: 'already_member',
+    });
+  });
+
+  it('does not let metric failures affect callers', () => {
+    counterAdd('workspaces_membership_changed').mockImplementationOnce(() => {
+      throw new Error('metrics unavailable');
+    });
+
+    const act = () => metrics.recordWorkspaceMembershipChanged('added');
+
+    expect(act).not.toThrow();
+  });
+});

package/src/metrics/instance.ts

@@ -0,0 +1,57 @@
+import {instanceMetrics} from '@shipfox/node-opentelemetry';
+
+export type WorkspacesInvitationEmailRequested = 'requested' | 'skipped';
+export type WorkspacesMembershipChangeAction = 'added' | 'removed';
+export type WorkspacesInvitationAcceptOutcome = 'added' | 'already_member';
+
+const meter = instanceMetrics.getMeter('workspaces');
+
+const workspaceCreatedCount = meter.createCounter<Record<string, never>>('workspaces_created', {
+  description: 'Workspaces created',
+});
+
+const membershipChangedCount = meter.createCounter<{
+  action: WorkspacesMembershipChangeAction;
+}>('workspaces_membership_changed', {
+  description: 'Workspace membership changes by action',
+});
+
+const invitationCreatedCount = meter.createCounter<{
+  email_requested: WorkspacesInvitationEmailRequested;
+}>('workspaces_invitation_created', {
+  description: 'Workspace invitations created by whether an invitation email was requested',
+});
+
+const invitationAcceptedCount = meter.createCounter<{
+  outcome: WorkspacesInvitationAcceptOutcome;
+}>('workspaces_invitation_accepted', {
+  description: 'Workspace invitations accepted by membership outcome',
+});
+
+function recordMetric(record: () => void): void {
+  try {
+    record();
+  } catch {
+    // Metrics must not affect workspace mutations.
+  }
+}
+
+export function recordWorkspaceCreated(): void {
+  recordMetric(() => workspaceCreatedCount.add(1));
+}
+
+export function recordWorkspaceMembershipChanged(action: WorkspacesMembershipChangeAction): void {
+  recordMetric(() => membershipChangedCount.add(1, {action}));
+}
+
+export function recordWorkspaceInvitationCreated(
+  emailRequested: WorkspacesInvitationEmailRequested,
+): void {
+  recordMetric(() => invitationCreatedCount.add(1, {email_requested: emailRequested}));
+}
+
+export function recordWorkspaceInvitationAccepted(
+  outcome: WorkspacesInvitationAcceptOutcome,
+): void {
+  recordMetric(() => invitationAcceptedCount.add(1, {outcome}));
+}

package/src/metrics/service.ts

@@ -0,0 +1,26 @@
+import {getServiceMetricsProvider} from '@shipfox/node-opentelemetry';
+import {getWorkspaceServiceMetrics} from '#db/workspaces.js';
+
+export function registerWorkspacesServiceMetrics(): void {
+  const meter = getServiceMetricsProvider().getMeter('workspaces');
+
+  const activeWorkspaces = meter.createObservableGauge('workspaces_active', {
+    description: 'Workspaces currently marked active',
+  });
+  const memberships = meter.createObservableGauge('workspaces_memberships', {
+    description: 'Workspace memberships currently present',
+  });
+  const openInvitations = meter.createObservableGauge('workspaces_open_invitations', {
+    description: 'Workspace invitations currently unaccepted and unexpired',
+  });
+
+  meter.addBatchObservableCallback(
+    async (observer) => {
+      const metrics = await getWorkspaceServiceMetrics();
+      observer.observe(activeWorkspaces, metrics.activeWorkspaces);
+      observer.observe(memberships, metrics.memberships);
+      observer.observe(openInvitations, metrics.openInvitations);
+    },
+    [activeWorkspaces, memberships, openInvitations],
+  );
+}

package/src/presentation/dto/index.ts

@@ -0,0 +1,3 @@
+export {toInvitationDto} from './invitation.js';
+export {toMembershipWithUserDto, toMembershipWithWorkspaceDto} from './membership.js';
+export {toWorkspaceDto} from './workspace.js';

package/src/presentation/dto/invitation.ts

@@ -0,0 +1,16 @@
+import type {InvitationDto} from '@shipfox/api-workspaces-dto';
+import type {Invitation} from '#core/entities/invitation.js';
+
+export function toInvitationDto(invitation: Invitation): InvitationDto {
+  return {
+    id: invitation.id,
+    workspace_id: invitation.workspaceId,
+    email: invitation.email,
+    expires_at: invitation.expiresAt.toISOString(),
+    accepted_at: invitation.acceptedAt ? invitation.acceptedAt.toISOString() : null,
+    invited_by_user_id: invitation.invitedByUserId,
+    invited_by_display: invitation.invitedByDisplay,
+    created_at: invitation.createdAt.toISOString(),
+    updated_at: invitation.updatedAt.toISOString(),
+  };
+}

package/src/presentation/dto/membership.ts

@@ -0,0 +1,27 @@
+import type {MembershipWithUserDto, MembershipWithWorkspaceDto} from '@shipfox/api-workspaces-dto';
+import type {MembershipWithUser, MembershipWithWorkspace} from '#db/memberships.js';
+
+export function toMembershipWithWorkspaceDto(
+  membership: MembershipWithWorkspace,
+): MembershipWithWorkspaceDto {
+  return {
+    id: membership.id,
+    user_id: membership.userId,
+    workspace_id: membership.workspaceId,
+    workspace_name: membership.workspaceName,
+    created_at: membership.createdAt.toISOString(),
+    updated_at: membership.updatedAt.toISOString(),
+  };
+}
+
+export function toMembershipWithUserDto(membership: MembershipWithUser): MembershipWithUserDto {
+  return {
+    id: membership.id,
+    user_id: membership.userId,
+    workspace_id: membership.workspaceId,
+    user_email: membership.userEmail,
+    user_name: membership.userName,
+    created_at: membership.createdAt.toISOString(),
+    updated_at: membership.updatedAt.toISOString(),
+  };
+}

package/src/presentation/dto/workspace.ts

@@ -0,0 +1,13 @@
+import type {WorkspaceDto} from '@shipfox/api-workspaces-dto';
+import type {Workspace} from '#core/entities/workspace.js';
+
+export function toWorkspaceDto(workspace: Workspace): WorkspaceDto {
+  return {
+    id: workspace.id,
+    name: workspace.name,
+    status: workspace.status,
+    settings: workspace.settings,
+    created_at: workspace.createdAt.toISOString(),
+    updated_at: workspace.updatedAt.toISOString(),
+  };
+}

package/src/presentation/e2eRoutes/create-invitation.ts

@@ -0,0 +1,44 @@
+import {
+  e2eCreateInvitationBodySchema,
+  e2eCreateInvitationResponseSchema,
+} from '@shipfox/api-workspaces-dto';
+import {defineRoute} from '@shipfox/node-fastify';
+import {generateOpaqueToken, hashOpaqueToken} from '@shipfox/node-tokens';
+import {createInvitation} from '#db/invitations.js';
+import {toInvitationDto} from '#presentation/dto/index.js';
+
+const INVITATION_TTL_DAYS = 7;
+
+function daysFromNow(days: number): Date {
+  return new Date(Date.now() + days * 24 * 60 * 60 * 1000);
+}
+
+export const createE2eInvitationRoute = defineRoute({
+  method: 'POST',
+  path: '/invitations',
+  description: 'Create a workspace invitation for E2E tests.',
+  schema: {
+    body: e2eCreateInvitationBodySchema,
+    response: {
+      201: e2eCreateInvitationResponseSchema,
+    },
+  },
+  handler: async (request, reply) => {
+    const rawToken = generateOpaqueToken('invitation');
+    const invitation = await createInvitation({
+      workspaceId: request.body.workspace_id,
+      email: request.body.email,
+      hashedToken: hashOpaqueToken(rawToken),
+      expiresAt: daysFromNow(INVITATION_TTL_DAYS),
+      invitedByUserId: request.body.invited_by_user_id,
+      invitedByDisplay: request.body.invited_by_display ?? null,
+      skipEmail: true,
+    });
+
+    reply.code(201);
+    return {
+      invitation: toInvitationDto(invitation),
+      raw_token: rawToken,
+    };
+  },
+});

package/src/presentation/e2eRoutes/create-workspace.ts

@@ -0,0 +1,30 @@
+import {
+  e2eCreateWorkspaceBodySchema,
+  e2eCreateWorkspaceResponseSchema,
+} from '@shipfox/api-workspaces-dto';
+import {defineRoute} from '@shipfox/node-fastify';
+import {createWorkspaceForUser} from '#core/index.js';
+import {toWorkspaceDto} from '#presentation/dto/index.js';
+
+export const createE2eWorkspaceRoute = defineRoute({
+  method: 'POST',
+  path: '/',
+  description: 'Create a workspace for an existing user for E2E tests.',
+  schema: {
+    body: e2eCreateWorkspaceBodySchema,
+    response: {
+      201: e2eCreateWorkspaceResponseSchema,
+    },
+  },
+  handler: async (request, reply) => {
+    const workspace = await createWorkspaceForUser({
+      name: request.body.name,
+      userId: request.body.user_id,
+      userEmail: request.body.user_email,
+      userName: request.body.user_name,
+    });
+
+    reply.code(201);
+    return toWorkspaceDto(workspace);
+  },
+});

package/src/presentation/e2eRoutes/index.ts

@@ -0,0 +1,8 @@
+import type {RouteGroup} from '@shipfox/node-fastify';
+import {createE2eInvitationRoute} from './create-invitation.js';
+import {createE2eWorkspaceRoute} from './create-workspace.js';
+
+export const workspacesE2eRoutes: RouteGroup = {
+  prefix: '/workspaces',
+  routes: [createE2eWorkspaceRoute, createE2eInvitationRoute],
+};

package/src/presentation/index.ts

@@ -0,0 +1 @@
+export {workspacesRoutes as routes} from './routes/index.js';

package/src/presentation/routes/index.ts

@@ -0,0 +1,23 @@
+import type {RouteGroup} from '@shipfox/node-fastify';
+import {invitationsAcceptGroup, invitationsWorkspaceScopedRoutes} from './invitations/index.js';
+import {memberRoutes} from './members/index.js';
+import {createWorkspaceRoute, listUserWorkspacesRoute} from './workspaces/index.js';
+
+export const workspacesRoutes: RouteGroup[] = [
+  invitationsAcceptGroup,
+  {
+    prefix: '/workspaces',
+    routes: [
+      listUserWorkspacesRoute,
+      createWorkspaceRoute,
+      {
+        prefix: '/:workspaceId/members',
+        routes: memberRoutes,
+      },
+      {
+        prefix: '/:workspaceId/invitations',
+        routes: invitationsWorkspaceScopedRoutes,
+      },
+    ],
+  },
+];

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

@@ -0,0 +1,154 @@
+import type {FastifyInstance} from 'fastify';
+import {
+  createExpiredInvite,
+  createInvite,
+  createWorkspace,
+  createWorkspacesTestApp,
+  resetCapturedMail,
+  signupVerifyLogin,
+} from '#test/routes.js';
+
+describe('POST /invitations/accept', () => {
+  let app: FastifyInstance;
+
+  beforeAll(async () => {
+    app = await createWorkspacesTestApp();
+  });
+
+  beforeEach(() => {
+    resetCapturedMail();
+  });
+
+  afterAll(async () => {
+    await app.close();
+  });
+
+  test('returns 201 and creates a membership for a new member', async () => {
+    const owner = await signupVerifyLogin(app, 'accept-owner');
+    const guest = await signupVerifyLogin(app, 'accept-guest');
+    const guestName = 'Accepted Guest';
+    const guestToken = `user:${guest.userId}:${guest.email}:${encodeURIComponent(guestName)}`;
+    const workspaceId = await createWorkspace(app, owner.token);
+    const invite = await createInvite(app, {token: owner.token, workspaceId, email: guest.email});
+
+    const res = await app.inject({
+      method: 'POST',
+      url: '/invitations/accept',
+      headers: {authorization: `Bearer ${guestToken}`},
+      payload: {token: invite.rawToken},
+    });
+    const members = await app.inject({
+      method: 'GET',
+      url: `/workspaces/${workspaceId}/members`,
+      headers: {authorization: `Bearer ${owner.token}`},
+    });
+
+    expect(res.statusCode).toBe(201);
+    expect(res.json().already_member).toBe(false);
+    expect(res.json().membership).toMatchObject({
+      user_id: guest.userId,
+      workspace_id: workspaceId,
+    });
+    expect(members.statusCode).toBe(200);
+    expect(members.json().members).toEqual(
+      expect.arrayContaining([
+        expect.objectContaining({
+          user_email: guest.email,
+          user_name: guestName,
+        }),
+      ]),
+    );
+  });
+
+  test('returns 200 when the invitee is already a member', async () => {
+    const owner = await signupVerifyLogin(app, 'accept-existing-owner');
+    const workspaceId = await createWorkspace(app, owner.token);
+    const invite = await createInvite(app, {token: owner.token, workspaceId, email: owner.email});
+
+    const res = await app.inject({
+      method: 'POST',
+      url: '/invitations/accept',
+      headers: {authorization: `Bearer ${owner.token}`},
+      payload: {token: invite.rawToken},
+    });
+
+    expect(res.statusCode).toBe(200);
+    expect(res.json().already_member).toBe(true);
+  });
+
+  test('transforms invalid token into 410', async () => {
+    const guest = await signupVerifyLogin(app, 'accept-invalid');
+
+    const res = await app.inject({
+      method: 'POST',
+      url: '/invitations/accept',
+      headers: {authorization: `Bearer ${guest.token}`},
+      payload: {token: 'not-a-real-token'},
+    });
+
+    expect(res.statusCode).toBe(410);
+    expect(res.json().code).toBe('token-invalid');
+  });
+
+  test('transforms already used token into 410', async () => {
+    const owner = await signupVerifyLogin(app, 'accept-used-owner');
+    const guest = await signupVerifyLogin(app, 'accept-used-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: 'POST',
+      url: '/invitations/accept',
+      headers: {authorization: `Bearer ${guest.token}`},
+      payload: {token: invite.rawToken},
+    });
+
+    expect(res.statusCode).toBe(410);
+    expect(res.json().code).toBe('token-already-used');
+  });
+
+  test('transforms expired token into 410', async () => {
+    const owner = await signupVerifyLogin(app, 'accept-expired-owner');
+    const guest = await signupVerifyLogin(app, 'accept-expired-guest');
+    const workspaceId = await createWorkspace(app, owner.token);
+    const expiredToken = await createExpiredInvite({
+      workspaceId,
+      email: guest.email,
+      invitedByUserId: owner.userId,
+    });
+
+    const res = await app.inject({
+      method: 'POST',
+      url: '/invitations/accept',
+      headers: {authorization: `Bearer ${guest.token}`},
+      payload: {token: expiredToken},
+    });
+
+    expect(res.statusCode).toBe(410);
+    expect(res.json().code).toBe('token-expired');
+  });
+
+  test('transforms email mismatch into 403', async () => {
+    const owner = await signupVerifyLogin(app, 'accept-mismatch-owner');
+    const invited = await signupVerifyLogin(app, 'accept-mismatch-invited');
+    const other = await signupVerifyLogin(app, 'accept-mismatch-other');
+    const workspaceId = await createWorkspace(app, owner.token);
+    const invite = await createInvite(app, {token: owner.token, workspaceId, email: invited.email});
+
+    const res = await app.inject({
+      method: 'POST',
+      url: '/invitations/accept',
+      headers: {authorization: `Bearer ${other.token}`},
+      payload: {token: invite.rawToken},
+    });
+
+    expect(res.statusCode).toBe(403);
+    expect(res.json().code).toBe('forbidden');
+  });
+});

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

@@ -0,0 +1,70 @@
+import {AUTH_USER, getUserContext} from '@shipfox/api-auth-context';
+import {
+  acceptInvitationBodySchema,
+  acceptInvitationResponseSchema,
+} from '@shipfox/api-workspaces-dto';
+import {ClientError, defineRoute} from '@shipfox/node-fastify';
+import {
+  InvitationEmailMismatchError,
+  TokenAlreadyUsedError,
+  TokenExpiredError,
+  TokenInvalidError,
+} from '#core/errors.js';
+import {acceptWorkspaceInvitation} from '#core/index.js';
+
+export const acceptInvitationRoute = defineRoute({
+  method: 'POST',
+  path: '/accept',
+  description: 'Accept an invitation to join a workspace.',
+  auth: AUTH_USER,
+  schema: {
+    body: acceptInvitationBodySchema,
+    response: {
+      200: acceptInvitationResponseSchema,
+      201: acceptInvitationResponseSchema,
+    },
+  },
+  errorHandler: (error) => {
+    if (error instanceof TokenInvalidError) {
+      throw new ClientError('Invitation token is invalid', 'token-invalid', {status: 410});
+    }
+    if (error instanceof TokenAlreadyUsedError) {
+      throw new ClientError('Invitation has already been accepted', 'token-already-used', {
+        status: 410,
+      });
+    }
+    if (error instanceof TokenExpiredError) {
+      throw new ClientError('Invitation has expired', 'token-expired', {status: 410});
+    }
+    if (error instanceof InvitationEmailMismatchError) {
+      throw new ClientError('Invitation email does not match authenticated user', 'forbidden', {
+        status: 403,
+      });
+    }
+    throw error;
+  },
+  handler: async (request, reply) => {
+    const client = getUserContext(request);
+    if (!client) {
+      throw new ClientError('Authentication required', 'unauthorized', {status: 401});
+    }
+
+    const {token} = request.body;
+    const result = await acceptWorkspaceInvitation({
+      token,
+      userId: client.userId,
+      email: client.email,
+      name: client.name,
+    });
+
+    reply.code(result.alreadyMember ? 200 : 201);
+    return {
+      membership: {
+        id: result.membership.id,
+        user_id: result.membership.userId,
+        workspace_id: result.membership.workspaceId,
+      },
+      already_member: result.alreadyMember,
+    };
+  },
+});

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

@@ -0,0 +1,99 @@
+import type {FastifyInstance} from 'fastify';
+import {
+  capturedMail,
+  createInvite,
+  createWorkspace,
+  createWorkspacesTestApp,
+  invitationOutboxEventsTo,
+  resetCapturedMail,
+  signupVerifyLogin,
+  uniqueEmail,
+} from '#test/routes.js';
+
+describe('POST /workspaces/:workspaceId/invitations', () => {
+  let app: FastifyInstance;
+
+  beforeAll(async () => {
+    app = await createWorkspacesTestApp();
+  });
+
+  beforeEach(() => {
+    resetCapturedMail();
+  });
+
+  afterAll(async () => {
+    await app.close();
+  });
+
+  test('returns 201 with an invitation for a workspace member', async () => {
+    const owner = await signupVerifyLogin(app, 'invite-create-owner');
+    const workspaceId = await createWorkspace(app, owner.token);
+    const inviteeEmail = uniqueEmail('invite-create');
+
+    const res = await app.inject({
+      method: 'POST',
+      url: `/workspaces/${workspaceId}/invitations`,
+      headers: {authorization: `Bearer ${owner.token}`},
+      payload: {email: inviteeEmail.toUpperCase()},
+    });
+
+    expect(res.statusCode).toBe(201);
+    expect(res.json()).toMatchObject({
+      workspace_id: workspaceId,
+      email: inviteeEmail,
+      accepted_at: null,
+      invited_by_user_id: owner.userId,
+    });
+    expect(await invitationOutboxEventsTo(inviteeEmail)).toHaveLength(1);
+    expect(capturedMail()).toHaveLength(0);
+  });
+
+  test('transforms duplicate open invitation into 409', async () => {
+    const owner = await signupVerifyLogin(app, 'invite-create-duplicate');
+    const workspaceId = await createWorkspace(app, owner.token);
+    const inviteeEmail = uniqueEmail('duplicate-invite');
+    await createInvite(app, {token: owner.token, workspaceId, email: inviteeEmail});
+
+    const res = await app.inject({
+      method: 'POST',
+      url: `/workspaces/${workspaceId}/invitations`,
+      headers: {authorization: `Bearer ${owner.token}`},
+      payload: {email: inviteeEmail},
+    });
+
+    expect(res.statusCode).toBe(409);
+    expect(res.json().code).toBe('open-invitation-exists');
+    expect(await invitationOutboxEventsTo(inviteeEmail)).toHaveLength(1);
+  });
+
+  test('transforms missing membership into 403', async () => {
+    const outsider = await signupVerifyLogin(app, 'invite-create-outsider');
+    const workspaceId = crypto.randomUUID();
+    const inviteeEmail = uniqueEmail('forbidden-invite');
+
+    const res = await app.inject({
+      method: 'POST',
+      url: `/workspaces/${workspaceId}/invitations`,
+      headers: {authorization: `Bearer ${outsider.token}`},
+      payload: {email: inviteeEmail},
+    });
+
+    expect(res.statusCode).toBe(403);
+    expect(res.json().code).toBe('forbidden');
+    expect(await invitationOutboxEventsTo(inviteeEmail)).toHaveLength(0);
+  });
+
+  test('returns 403 when caller has no claim to the workspace (whether or not it exists)', async () => {
+    const owner = await signupVerifyLogin(app, 'invite-create-missing-workspace');
+
+    const res = await app.inject({
+      method: 'POST',
+      url: `/workspaces/${crypto.randomUUID()}/invitations`,
+      headers: {authorization: `Bearer ${owner.token}`},
+      payload: {email: uniqueEmail('missing-workspace-invite')},
+    });
+
+    expect(res.statusCode).toBe(403);
+    expect(res.json().code).toBe('forbidden');
+  });
+});