@shipfox/api-workspaces 5.0.0 → 6.0.0

package/src/core/invitations.ts

@@ -1,17 +1,18 @@
 import type {UserContextMembership} from '@shipfox/api-auth-context';
+import {emailSchema} from '@shipfox/api-common-dto';
 import {generateOpaqueToken, hashOpaqueToken} from '@shipfox/node-tokens';
 import {config} from '#config.js';
 import {
-  type AcceptInvitationResult,
-  acceptInvitation,
   createInvitation,
   findInvitationById,
   findInvitationByToken,
   listOpenInvitationsByWorkspace,
+  reconcileInvitationAcceptance,
   revokeInvitation,
 } from '#db/invitations.js';
 import {getWorkspaceById} from '#db/workspaces.js';
 import type {Invitation} from './entities/invitation.js';
+import type {Membership} from './entities/membership.js';
 import {
   InvitationEmailMismatchError,
   InvitationNotFoundError,
@@ -40,6 +41,7 @@ export async function createWorkspaceInvitation(params: {
   invitedByDisplay?: string | null;
   invitedByMemberships: ReadonlyArray<UserContextMembership>;
 }): Promise<Invitation> {
+  const email = emailSchema.parse(params.email);
   const {workspace} = await requireWorkspaceMembership({
     workspaceId: params.workspaceId,
     userId: params.invitedByUserId,
@@ -49,7 +51,7 @@ export async function createWorkspaceInvitation(params: {
   const rawToken = generateOpaqueToken('invitation');
   const invitation = await createInvitation({
     workspaceId: params.workspaceId,
-    email: params.email,
+    email,
     hashedToken: hashOpaqueToken(rawToken),
     expiresAt: daysFromNow(INVITATION_TTL_DAYS),
     invitedByUserId: params.invitedByUserId,
@@ -83,6 +85,12 @@ export type PreviewInvitationResult =
   | {status: 'already_used'; workspaceName: string}
   | {status: 'invalid'};
 
+export interface AcceptedWorkspaceInvitation {
+  invitation: Invitation;
+  membership: Membership;
+  alreadyMember: boolean;
+}
+
 export async function previewInvitation(params: {token: string}): Promise<PreviewInvitationResult> {
   const invitation = await peekInvitationByRawToken({token: params.token});
   if (!invitation) {
@@ -95,6 +103,10 @@ export async function previewInvitation(params: {token: string}): Promise<Previe
     return {status: 'invalid'};
   }
 
+  if (invitation.revokedAt !== null) {
+    return {status: 'invalid'};
+  }
+
   if (invitation.acceptedAt !== null) {
     return {status: 'already_used', workspaceName: workspace.name};
   }
@@ -122,33 +134,76 @@ export async function acceptWorkspaceInvitation(params: {
   userId: string;
   email: string;
   name?: string | null | undefined;
-}): Promise<AcceptInvitationResult> {
-  const invitation = await peekInvitationByRawToken({token: params.token});
-  if (!invitation) {
-    throw new TokenInvalidError('Invitation token is invalid');
+}): Promise<AcceptedWorkspaceInvitation> {
+  const result = await reconcileWorkspaceInvitationAcceptance({
+    token: params.token,
+    email: params.email,
+    userId: params.userId,
+    name: params.name,
+  });
+  if (result.status === 'accepted') {
+    return {
+      invitation: result.invitation,
+      membership: result.membership,
+      alreadyMember: result.alreadyMember,
+    };
   }
-
-  if (invitation.acceptedAt !== null) {
+  if (result.status === 'already_accepted' || result.status === 'consumed_by_another_user') {
     throw new TokenAlreadyUsedError();
   }
-
-  if (invitation.expiresAt.getTime() <= Date.now()) {
+  if (result.status === 'expired') {
     throw new TokenExpiredError();
   }
-
-  if (params.email !== invitation.email) {
+  if (result.status === 'email_mismatch') {
     throw new InvitationEmailMismatchError();
   }
+  throw new TokenInvalidError(
+    result.status === 'revoked' ? 'Invitation token has been revoked' : 'Invitation is invalid',
+  );
+}
 
-  const result = await acceptInvitation({
+export type WorkspaceInvitationReconciliation =
+  | {
+      status: 'accepted' | 'already_accepted';
+      invitation: Invitation;
+      membership: Membership;
+      alreadyMember: boolean;
+    }
+  | {
+      status: 'invalid' | 'expired' | 'revoked' | 'consumed_by_another_user' | 'email_mismatch';
+    };
+
+export async function reconcileWorkspaceInvitationAcceptance(params: {
+  token: string;
+  userId: string;
+  email: string;
+  name?: string | null | undefined;
+}): Promise<WorkspaceInvitationReconciliation> {
+  const invitation = await peekInvitationByRawToken({token: params.token});
+  if (!invitation) return {status: 'invalid'};
+
+  const result = await reconcileInvitationAcceptance({
     invitationId: invitation.id,
     acceptedByUserId: params.userId,
+    email: emailSchema.parse(params.email),
     acceptedByUserName: params.name,
   });
-  if (!result) {
-    throw new TokenInvalidError('Invitation is no longer valid');
+  if (result.status === 'accepted') {
+    return {
+      status: result.status,
+      invitation: result.invitation,
+      membership: result.membership,
+      alreadyMember: result.alreadyMember,
+    };
+  }
+  if (result.status === 'already_accepted') {
+    return {
+      status: result.status,
+      invitation: result.invitation,
+      membership: result.membership,
+      alreadyMember: true,
+    };
   }
-
   return result;
 }
 

package/src/core/workspaces.test.ts

@@ -1,4 +1,8 @@
+import {WORKSPACES_WORKSPACE_CREATED} from '@shipfox/api-workspaces-dto';
+import {sql} from 'drizzle-orm';
+import {db} from '#db/db.js';
 import {findMembership} from '#db/memberships.js';
+import {workspacesOutbox} from '#db/schema/outbox.js';
 import {userFactory} from '#test/index.js';
 import {MembershipRequiredError, WorkspaceNotFoundError} from './errors.js';
 import {createWorkspaceForUser, requireWorkspaceMembership} from './workspaces.js';
@@ -19,6 +23,30 @@ describe('workspaces core', () => {
     expect(membership).toBeDefined();
   });
 
+  test('createWorkspaceForUser emits a workspace created event in the transaction', async () => {
+    const user = userFactory.build();
+
+    const workspace = await createWorkspaceForUser({
+      name: 'Evented Workspace',
+      userId: user.userId,
+      userEmail: user.email,
+      userName: user.name,
+    });
+    const [event] = await db()
+      .select()
+      .from(workspacesOutbox)
+      .where(sql`${workspacesOutbox.payload}->>'workspaceId' = ${workspace.id}`);
+
+    expect(event).toMatchObject({
+      eventType: WORKSPACES_WORKSPACE_CREATED,
+      payload: {
+        workspaceId: workspace.id,
+        name: workspace.name,
+        creatorUserId: user.userId,
+      },
+    });
+  });
+
   test('requireWorkspaceMembership returns the workspace + role when memberships include it', async () => {
     const user = userFactory.build();
     const workspace = await createWorkspaceForUser({

package/src/core/workspaces.ts

@@ -1,5 +1,10 @@
 import type {UserContextMembership} from '@shipfox/api-auth-context';
-import type {WorkspaceRole} from '@shipfox/api-workspaces-dto';
+import {
+  WORKSPACES_WORKSPACE_CREATED,
+  type WorkspaceRole,
+  type WorkspacesEventMap,
+} from '@shipfox/api-workspaces-dto';
+import {writeOutboxEvent} from '@shipfox/node-outbox';
 import {db} from '#db/db.js';
 import {
   findMembership,
@@ -10,6 +15,7 @@ import {
   removeMembership,
 } from '#db/memberships.js';
 import {memberships} from '#db/schema/memberships.js';
+import {workspacesOutbox} from '#db/schema/outbox.js';
 import {toWorkspace, workspaces} from '#db/schema/workspaces.js';
 import {getWorkspaceById} from '#db/workspaces.js';
 import type {Workspace} from './entities/workspace.js';
@@ -68,7 +74,18 @@ export async function createWorkspaceForUser(params: {
       userName: params.userName ?? null,
       workspaceId: workspaceRow.id,
     });
-    return toWorkspace(workspaceRow);
+    const workspace = toWorkspace(workspaceRow);
+
+    await writeOutboxEvent<WorkspacesEventMap>(tx, workspacesOutbox, {
+      type: WORKSPACES_WORKSPACE_CREATED,
+      payload: {
+        workspaceId: workspace.id,
+        name: workspace.name,
+        creatorUserId: params.userId,
+      },
+    });
+
+    return workspace;
   });
 }
 

package/src/db/index.ts

@@ -2,13 +2,8 @@ import {dirname, resolve} from 'node:path';
 import {fileURLToPath} from 'node:url';
 
 export {closeDb, db, schema} from './db.js';
-export type {
-  AcceptInvitationParams,
-  AcceptInvitationResult,
-  CreateInvitationParams,
-} from './invitations.js';
+export type {CreateInvitationParams} from './invitations.js';
 export {
-  acceptInvitation,
   createInvitation,
   findInvitationByToken,
   listOpenInvitationsByWorkspace,

package/src/db/invitations.test.ts

@@ -1,15 +1,18 @@
+import {WORKSPACES_MEMBER_INVITED, WORKSPACES_MEMBER_JOINED} from '@shipfox/api-workspaces-dto';
 import {hashOpaqueToken} from '@shipfox/node-tokens';
-import {eq, sql} from 'drizzle-orm';
+import {and, eq, sql} from 'drizzle-orm';
 import {OpenInvitationExistsError} from '#core/errors.js';
 import {db} from './db.js';
 import {
-  acceptInvitation,
   createInvitation,
   findInvitationByToken,
   listOpenInvitationsByWorkspace,
+  reconcileInvitationAcceptance,
   revokeInvitation,
 } from './invitations.js';
 import {invitations} from './schema/invitations.js';
+import {memberships} from './schema/memberships.js';
+import {workspacesOutbox} from './schema/outbox.js';
 import {createWorkspace} from './workspaces.js';
 
 function emailFor(suffix: string): string {
@@ -39,6 +42,39 @@ describe('invitations db', () => {
     expect(invitation.acceptedAt).toBeNull();
   });
 
+  test('writes the member invited event when email delivery is skipped', async () => {
+    const inviter = await createUser({email: emailFor('inviter')});
+    const workspace = await createWorkspace({name: `Workspace ${crypto.randomUUID()}`});
+    const invitedEmail = emailFor('guest');
+
+    await createInvitation({
+      workspaceId: workspace.id,
+      email: invitedEmail,
+      hashedToken: hashOpaqueToken('inv-event'),
+      expiresAt: new Date(Date.now() + 86_400_000),
+      invitedByUserId: inviter.userId,
+      skipEmail: true,
+    });
+
+    const events = await db()
+      .select()
+      .from(workspacesOutbox)
+      .where(
+        and(
+          eq(workspacesOutbox.eventType, WORKSPACES_MEMBER_INVITED),
+          sql`${workspacesOutbox.payload}->>'workspaceId' = ${workspace.id}`,
+        ),
+      );
+
+    expect(events).toHaveLength(1);
+    expect(events[0]?.payload).toEqual({
+      workspaceId: workspace.id,
+      invitedEmail,
+      inviterUserId: inviter.userId,
+      role: 'admin',
+    });
+  });
+
   test('rejects when an unexpired open invite already exists', async () => {
     const inviter = await createUser({email: emailFor('inviter'), hashedPassword: 'h'});
     const workspace = await createWorkspace({name: `Workspace ${crypto.randomUUID()}`});
@@ -94,7 +130,7 @@ describe('invitations db', () => {
     expect(stillThere).toHaveLength(0);
   });
 
-  test('acceptInvitation creates membership + marks accepted (transactional)', async () => {
+  test('reconcileInvitationAcceptance creates membership + marks accepted transactionally', async () => {
     const inviter = await createUser({email: emailFor('inviter'), hashedPassword: 'h'});
     const accepter = await createUser({email: emailFor('accepter'), hashedPassword: 'h'});
     const workspace = await createWorkspace({name: `Workspace ${crypto.randomUUID()}`});
@@ -107,18 +143,40 @@ describe('invitations db', () => {
       skipEmail: true,
     });
 
-    const result = await acceptInvitation({
+    const result = await reconcileInvitationAcceptance({
       invitationId: inv.id,
       acceptedByUserId: accepter.userId,
+      email: accepter.email,
     });
 
-    expect(result?.invitation.acceptedAt).toBeInstanceOf(Date);
-    expect(result?.invitation.acceptedByUserId).toBe(accepter.userId);
-    expect(result?.membership.userId).toBe(accepter.userId);
-    expect(result?.alreadyMember).toBe(false);
+    expect(result.status).toBe('accepted');
+    if (result.status === 'accepted') {
+      expect(result.invitation.acceptedAt).toBeInstanceOf(Date);
+      expect(result.invitation.acceptedByUserId).toBe(accepter.userId);
+      expect(result.membership.userId).toBe(accepter.userId);
+      expect(result.alreadyMember).toBe(false);
+    }
+
+    const events = await db()
+      .select()
+      .from(workspacesOutbox)
+      .where(
+        and(
+          eq(workspacesOutbox.eventType, WORKSPACES_MEMBER_JOINED),
+          sql`${workspacesOutbox.payload}->>'workspaceId' = ${workspace.id}`,
+        ),
+      );
+
+    expect(events).toHaveLength(1);
+    expect(events[0]?.payload).toEqual({
+      workspaceId: workspace.id,
+      userId: accepter.userId,
+      email: accepter.email,
+      viaInvitation: true,
+    });
   });
 
-  test('acceptInvitation is idempotent when caller is already a member', async () => {
+  test('reconcileInvitationAcceptance accepts an existing member', async () => {
     const inviter = await createUser({email: emailFor('inviter'), hashedPassword: 'h'});
     const member = await createUser({email: emailFor('member'), hashedPassword: 'h'});
     const workspace = await createWorkspace({name: `Workspace ${crypto.randomUUID()}`});
@@ -133,13 +191,148 @@ describe('invitations db', () => {
       skipEmail: true,
     });
 
-    const result = await acceptInvitation({invitationId: inv.id, acceptedByUserId: member.userId});
+    const result = await reconcileInvitationAcceptance({
+      invitationId: inv.id,
+      acceptedByUserId: member.userId,
+      email: member.email,
+    });
+
+    expect(result.status).toBe('accepted');
+    if (result.status === 'accepted') {
+      expect(result.alreadyMember).toBe(true);
+      expect(result.membership.id).toBe(existing.id);
+    }
+  });
+
+  test('reconciles a retry after the initial acceptance commits', async () => {
+    const inviter = await createUser({email: emailFor('inviter')});
+    const accepter = await createUser({email: emailFor('accepter')});
+    const workspace = await createWorkspace({name: `Workspace ${crypto.randomUUID()}`});
+    const invitation = await createInvitation({
+      workspaceId: workspace.id,
+      email: accepter.email,
+      hashedToken: hashOpaqueToken(`retry-${crypto.randomUUID()}`),
+      expiresAt: new Date(Date.now() + 86_400_000),
+      invitedByUserId: inviter.userId,
+      skipEmail: true,
+    });
+
+    await reconcileInvitationAcceptance({
+      invitationId: invitation.id,
+      acceptedByUserId: accepter.userId,
+      email: accepter.email,
+    });
+    const retry = await reconcileInvitationAcceptance({
+      invitationId: invitation.id,
+      acceptedByUserId: accepter.userId,
+      email: accepter.email,
+    });
+
+    expect(retry.status).toBe('already_accepted');
+    if (retry.status === 'already_accepted') {
+      expect(retry.membership.userId).toBe(accepter.userId);
+    }
+  });
+
+  test('reconciles an accepted invitation after expiry and email changes', async () => {
+    const inviter = await createUser({email: emailFor('inviter')});
+    const accepter = await createUser({email: emailFor('accepter')});
+    const workspace = await createWorkspace({name: `Workspace ${crypto.randomUUID()}`});
+    const invitation = await createInvitation({
+      workspaceId: workspace.id,
+      email: accepter.email,
+      hashedToken: hashOpaqueToken(`accepted-expired-${crypto.randomUUID()}`),
+      expiresAt: new Date(Date.now() + 86_400_000),
+      invitedByUserId: inviter.userId,
+      skipEmail: true,
+    });
+    await reconcileInvitationAcceptance({
+      invitationId: invitation.id,
+      acceptedByUserId: accepter.userId,
+      email: accepter.email,
+    });
+    await db()
+      .update(invitations)
+      .set({expiresAt: new Date(Date.now() - 1_000)})
+      .where(eq(invitations.id, invitation.id));
+
+    const retry = await reconcileInvitationAcceptance({
+      invitationId: invitation.id,
+      acceptedByUserId: accepter.userId,
+      email: emailFor('different-address'),
+    });
+
+    expect(retry.status).toBe('already_accepted');
+  });
+
+  test('serializes concurrent acceptance and rejects the other user', async () => {
+    const inviter = await createUser({email: emailFor('inviter')});
+    const firstUser = await createUser({email: emailFor('first')});
+    const secondUser = await createUser({email: emailFor('second')});
+    const workspace = await createWorkspace({name: `Workspace ${crypto.randomUUID()}`});
+    const invitationEmail = emailFor('guest');
+    const invitation = await createInvitation({
+      workspaceId: workspace.id,
+      email: invitationEmail,
+      hashedToken: hashOpaqueToken(`race-${crypto.randomUUID()}`),
+      expiresAt: new Date(Date.now() + 86_400_000),
+      invitedByUserId: inviter.userId,
+      skipEmail: true,
+    });
+
+    const results = await Promise.all([
+      reconcileInvitationAcceptance({
+        invitationId: invitation.id,
+        acceptedByUserId: firstUser.userId,
+        email: invitationEmail,
+      }),
+      reconcileInvitationAcceptance({
+        invitationId: invitation.id,
+        acceptedByUserId: secondUser.userId,
+        email: invitationEmail,
+      }),
+    ]);
+
+    expect(results.map((result) => result.status).sort()).toEqual([
+      'accepted',
+      'consumed_by_another_user',
+    ]);
+    const accepted = results.find((result) => result.status === 'accepted');
+    const membershipsForWorkspace = await db()
+      .select()
+      .from(memberships)
+      .where(eq(memberships.workspaceId, workspace.id));
+    expect(accepted?.status).toBe('accepted');
+    expect(membershipsForWorkspace).toHaveLength(1);
+    expect(membershipsForWorkspace[0]?.userId).toBe(
+      accepted?.status === 'accepted' ? accepted.invitation.acceptedByUserId : undefined,
+    );
+  });
+
+  test('returns revoked without granting membership', async () => {
+    const inviter = await createUser({email: emailFor('inviter')});
+    const accepter = await createUser({email: emailFor('accepter')});
+    const workspace = await createWorkspace({name: `Workspace ${crypto.randomUUID()}`});
+    const invitation = await createInvitation({
+      workspaceId: workspace.id,
+      email: accepter.email,
+      hashedToken: hashOpaqueToken(`revoked-${crypto.randomUUID()}`),
+      expiresAt: new Date(Date.now() + 86_400_000),
+      invitedByUserId: inviter.userId,
+      skipEmail: true,
+    });
+    await revokeInvitation({invitationId: invitation.id});
+
+    const result = await reconcileInvitationAcceptance({
+      invitationId: invitation.id,
+      acceptedByUserId: accepter.userId,
+      email: accepter.email,
+    });
 
-    expect(result?.alreadyMember).toBe(true);
-    expect(result?.membership.id).toBe(existing.id);
+    expect(result).toEqual({status: 'revoked'});
   });
 
-  test('acceptInvitation returns undefined when expired', async () => {
+  test('reconcileInvitationAcceptance returns expired before granting membership', async () => {
     const inviter = await createUser({email: emailFor('inviter'), hashedPassword: 'h'});
     const accepter = await createUser({email: emailFor('accepter'), hashedPassword: 'h'});
     const workspace = await createWorkspace({name: `Workspace ${crypto.randomUUID()}`});
@@ -156,12 +349,13 @@ describe('invitations db', () => {
       .returning();
     if (!inserted) throw new Error('insert failed');
 
-    const result = await acceptInvitation({
+    const result = await reconcileInvitationAcceptance({
       invitationId: inserted.id,
       acceptedByUserId: accepter.userId,
+      email: accepter.email,
     });
 
-    expect(result).toBeUndefined();
+    expect(result).toEqual({status: 'expired'});
   });
 
   test('lists only open invitations and revokes them', async () => {
@@ -184,6 +378,34 @@ describe('invitations db', () => {
     expect(after.some((i) => i.id === inv.id)).toBe(false);
   });
 
+  test('does not revoke an accepted invitation receipt', async () => {
+    const inviter = await createUser({email: emailFor('inviter')});
+    const accepter = await createUser({email: emailFor('accepter')});
+    const workspace = await createWorkspace({name: `Workspace ${crypto.randomUUID()}`});
+    const invitation = await createInvitation({
+      workspaceId: workspace.id,
+      email: accepter.email,
+      hashedToken: hashOpaqueToken(`accepted-revoke-${crypto.randomUUID()}`),
+      expiresAt: new Date(Date.now() + 86_400_000),
+      invitedByUserId: inviter.userId,
+      skipEmail: true,
+    });
+    await reconcileInvitationAcceptance({
+      invitationId: invitation.id,
+      acceptedByUserId: accepter.userId,
+      email: accepter.email,
+    });
+
+    await revokeInvitation({invitationId: invitation.id});
+    const retry = await reconcileInvitationAcceptance({
+      invitationId: invitation.id,
+      acceptedByUserId: accepter.userId,
+      email: accepter.email,
+    });
+
+    expect(retry.status).toBe('already_accepted');
+  });
+
   test('findInvitationByToken returns matching row', async () => {
     const inviter = await createUser({email: emailFor('inviter'), hashedPassword: 'h'});
     const workspace = await createWorkspace({name: `Workspace ${crypto.randomUUID()}`});