@shipfox/api-workspaces 2.0.0

package/src/core/workspaces.test.ts

@@ -0,0 +1,72 @@
+import {findMembership} from '#db/memberships.js';
+import {userFactory} from '#test/index.js';
+import {MembershipRequiredError, WorkspaceNotFoundError} from './errors.js';
+import {createWorkspaceForUser, requireWorkspaceMembership} from './workspaces.js';
+
+describe('workspaces core', () => {
+  test('createWorkspaceForUser creates a workspace and membership for the user', async () => {
+    const user = userFactory.build();
+
+    const workspace = await createWorkspaceForUser({
+      name: 'Core Workspace',
+      userId: user.userId,
+      userEmail: user.email,
+      userName: user.name,
+    });
+    const membership = await findMembership({userId: user.userId, workspaceId: workspace.id});
+
+    expect(workspace.name).toBe('Core Workspace');
+    expect(membership).toBeDefined();
+  });
+
+  test('requireWorkspaceMembership returns the workspace + role when memberships include it', async () => {
+    const user = userFactory.build();
+    const workspace = await createWorkspaceForUser({
+      name: 'Member Workspace',
+      userId: user.userId,
+      userEmail: user.email,
+      userName: user.name,
+    });
+
+    const result = await requireWorkspaceMembership({
+      workspaceId: workspace.id,
+      userId: user.userId,
+      memberships: [{workspaceId: workspace.id, role: 'admin'}],
+    });
+
+    expect(result.workspace.id).toBe(workspace.id);
+    expect(result.userId).toBe(user.userId);
+    expect(result.role).toBe('admin');
+  });
+
+  test('requireWorkspaceMembership rejects when memberships do not include the workspace', async () => {
+    const owner = userFactory.build();
+    const outsider = userFactory.build();
+    const workspace = await createWorkspaceForUser({
+      name: 'Private Workspace',
+      userId: owner.userId,
+      userEmail: owner.email,
+      userName: owner.name,
+    });
+
+    const nonMember = requireWorkspaceMembership({
+      workspaceId: workspace.id,
+      userId: outsider.userId,
+      memberships: [],
+    });
+    await expect(nonMember).rejects.toBeInstanceOf(MembershipRequiredError);
+  });
+
+  test('requireWorkspaceMembership rejects with WorkspaceNotFoundError when workspace does not exist', async () => {
+    const owner = userFactory.build();
+    const ghostId = crypto.randomUUID();
+
+    const missingWorkspace = requireWorkspaceMembership({
+      workspaceId: ghostId,
+      userId: owner.userId,
+      memberships: [{workspaceId: ghostId, role: 'admin'}],
+    });
+
+    await expect(missingWorkspace).rejects.toBeInstanceOf(WorkspaceNotFoundError);
+  });
+});

package/src/core/workspaces.ts

@@ -0,0 +1,126 @@
+import type {UserContextMembership} from '@shipfox/api-auth-context';
+import type {WorkspaceRole} from '@shipfox/api-workspaces-dto';
+import {db} from '#db/db.js';
+import {
+  findMembership,
+  listMembershipsByUser,
+  listMembershipsByWorkspace,
+  type MembershipWithUser,
+  type MembershipWithWorkspace,
+  removeMembership,
+} from '#db/memberships.js';
+import {memberships} from '#db/schema/memberships.js';
+import {toWorkspace, workspaces} from '#db/schema/workspaces.js';
+import {getWorkspaceById} from '#db/workspaces.js';
+import type {Workspace} from './entities/workspace.js';
+import {
+  MembershipNotFoundError,
+  MembershipRequiredError,
+  SelfRemovalNotAllowedError,
+  WorkspaceInactiveError,
+  WorkspaceNotFoundError,
+} from './errors.js';
+
+export interface RequireWorkspaceMembershipParams {
+  workspaceId: string;
+  userId: string;
+  memberships: ReadonlyArray<UserContextMembership>;
+}
+
+export interface RequireWorkspaceMembershipResult {
+  workspace: Workspace;
+  workspaceId: string;
+  userId: string;
+  role: WorkspaceRole;
+}
+
+export async function requireWorkspaceMembership(
+  params: RequireWorkspaceMembershipParams,
+): Promise<RequireWorkspaceMembershipResult> {
+  const membership = params.memberships.find((m) => m.workspaceId === params.workspaceId);
+  if (!membership) {
+    throw new MembershipRequiredError(params.workspaceId);
+  }
+
+  const workspace = await getWorkspaceById(params.workspaceId);
+  if (!workspace) {
+    throw new WorkspaceNotFoundError(params.workspaceId);
+  }
+  if (workspace.status !== 'active') {
+    throw new WorkspaceInactiveError(params.workspaceId);
+  }
+
+  return {workspace, workspaceId: workspace.id, userId: params.userId, role: membership.role};
+}
+
+export async function createWorkspaceForUser(params: {
+  name: string;
+  userId: string;
+  userEmail?: string | undefined;
+  userName?: string | null | undefined;
+}): Promise<Workspace> {
+  return await db().transaction(async (tx) => {
+    const [workspaceRow] = await tx.insert(workspaces).values({name: params.name}).returning();
+    if (!workspaceRow) throw new Error('Insert returned no rows');
+    await tx.insert(memberships).values({
+      userId: params.userId,
+      userEmail: params.userEmail ?? `user-${params.userId}@example.local`,
+      userName: params.userName ?? null,
+      workspaceId: workspaceRow.id,
+    });
+    return toWorkspace(workspaceRow);
+  });
+}
+
+export async function getWorkspace(params: {workspaceId: string}): Promise<Workspace> {
+  const workspace = await getWorkspaceById(params.workspaceId);
+  if (!workspace) {
+    throw new WorkspaceNotFoundError(params.workspaceId);
+  }
+
+  return workspace;
+}
+
+export async function listUserWorkspaceMemberships(params: {
+  userId: string;
+}): Promise<MembershipWithWorkspace[]> {
+  return await listMembershipsByUser({userId: params.userId});
+}
+
+export async function listWorkspaceMembers(params: {
+  workspaceId: string;
+  requesterUserId: string;
+  requesterMemberships: ReadonlyArray<UserContextMembership>;
+}): Promise<MembershipWithUser[]> {
+  await requireWorkspaceMembership({
+    workspaceId: params.workspaceId,
+    userId: params.requesterUserId,
+    memberships: params.requesterMemberships,
+  });
+
+  return listMembershipsByWorkspace({workspaceId: params.workspaceId});
+}
+
+export async function removeWorkspaceMember(params: {
+  workspaceId: string;
+  requesterUserId: string;
+  requesterMemberships: ReadonlyArray<UserContextMembership>;
+  userId: string;
+}): Promise<void> {
+  await requireWorkspaceMembership({
+    workspaceId: params.workspaceId,
+    userId: params.requesterUserId,
+    memberships: params.requesterMemberships,
+  });
+
+  if (params.userId === params.requesterUserId) {
+    throw new SelfRemovalNotAllowedError();
+  }
+
+  const target = await findMembership({userId: params.userId, workspaceId: params.workspaceId});
+  if (!target) {
+    throw new MembershipNotFoundError(params.userId, params.workspaceId);
+  }
+
+  await removeMembership({userId: params.userId, workspaceId: params.workspaceId});
+}

package/src/db/db.ts

@@ -0,0 +1,24 @@
+import {drizzle, type NodePgDatabase} from '@shipfox/node-drizzle';
+import {pgClient} from '@shipfox/node-postgres';
+import {invitations} from './schema/invitations.js';
+import {memberships} from './schema/memberships.js';
+import {workspacesOutbox} from './schema/outbox.js';
+import {workspaces} from './schema/workspaces.js';
+
+export const schema = {
+  workspaces,
+  memberships,
+  invitations,
+  workspacesOutbox,
+};
+
+let _db: NodePgDatabase<typeof schema> | undefined;
+
+export function db() {
+  if (!_db) _db = drizzle(pgClient(), {schema});
+  return _db;
+}
+
+export function closeDb(): void {
+  _db = undefined;
+}

package/src/db/index.ts

@@ -0,0 +1,43 @@
+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 {
+  acceptInvitation,
+  createInvitation,
+  findInvitationByToken,
+  listOpenInvitationsByWorkspace,
+  revokeInvitation,
+} from './invitations.js';
+export type {
+  CreateMembershipParams,
+  MembershipWithUser,
+  MembershipWithWorkspace,
+  RemoveMembershipParams,
+} from './memberships.js';
+export {
+  createMembership,
+  findMembership,
+  listMembershipsByUser,
+  listMembershipsByWorkspace,
+  removeMembership,
+} from './memberships.js';
+export {workspacesOutbox} from './schema/outbox.js';
+export type {
+  CreateWorkspaceParams,
+  UpdateWorkspaceParams,
+  WorkspaceServiceMetrics,
+} from './workspaces.js';
+export {
+  createWorkspace,
+  getWorkspaceById,
+  getWorkspaceServiceMetrics,
+  updateWorkspace,
+} from './workspaces.js';
+
+export const migrationsPath = resolve(dirname(fileURLToPath(import.meta.url)), '../../drizzle');

package/src/db/invitations.test.ts

@@ -0,0 +1,204 @@
+import {hashOpaqueToken} from '@shipfox/node-tokens';
+import {eq, sql} from 'drizzle-orm';
+import {OpenInvitationExistsError} from '#core/errors.js';
+import {db} from './db.js';
+import {
+  acceptInvitation,
+  createInvitation,
+  findInvitationByToken,
+  listOpenInvitationsByWorkspace,
+  revokeInvitation,
+} from './invitations.js';
+import {invitations} from './schema/invitations.js';
+import {createWorkspace} from './workspaces.js';
+
+function emailFor(suffix: string): string {
+  return `${suffix}-${crypto.randomUUID()}@example.com`;
+}
+
+async function createUser(params: {email: string; hashedPassword?: string; name?: string}) {
+  await Promise.resolve();
+  return {userId: crypto.randomUUID(), email: params.email, name: null};
+}
+
+describe('invitations db', () => {
+  test('creates an invitation', async () => {
+    const inviter = await createUser({email: emailFor('inviter'), hashedPassword: 'h'});
+    const workspace = await createWorkspace({name: `Workspace ${crypto.randomUUID()}`});
+
+    const invitation = await createInvitation({
+      workspaceId: workspace.id,
+      email: emailFor('guest'),
+      hashedToken: hashOpaqueToken('inv-1'),
+      expiresAt: new Date(Date.now() + 86_400_000),
+      invitedByUserId: inviter.userId,
+      skipEmail: true,
+    });
+
+    expect(invitation.workspaceId).toBe(workspace.id);
+    expect(invitation.acceptedAt).toBeNull();
+  });
+
+  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()}`});
+    const guest = emailFor('guest');
+    await createInvitation({
+      workspaceId: workspace.id,
+      email: guest,
+      hashedToken: hashOpaqueToken('first'),
+      expiresAt: new Date(Date.now() + 86_400_000),
+      invitedByUserId: inviter.userId,
+      skipEmail: true,
+    });
+
+    await expect(
+      createInvitation({
+        workspaceId: workspace.id,
+        email: guest,
+        hashedToken: hashOpaqueToken('second'),
+        expiresAt: new Date(Date.now() + 86_400_000),
+        invitedByUserId: inviter.userId,
+        skipEmail: true,
+      }),
+    ).rejects.toBeInstanceOf(OpenInvitationExistsError);
+  });
+
+  test('on create, expired invites for same (workspace, email) are deleted first', async () => {
+    const inviter = await createUser({email: emailFor('inviter'), hashedPassword: 'h'});
+    const workspace = await createWorkspace({name: `Workspace ${crypto.randomUUID()}`});
+    const guest = emailFor('guest');
+    const expiredToken = hashOpaqueToken('expired-inv');
+    await db().insert(invitations).values({
+      workspaceId: workspace.id,
+      email: guest,
+      hashedToken: expiredToken,
+      expiresAt: sql`now() - interval '1 day'`,
+      invitedByUserId: inviter.userId,
+    });
+
+    const fresh = await createInvitation({
+      workspaceId: workspace.id,
+      email: guest,
+      hashedToken: hashOpaqueToken('fresh-inv'),
+      expiresAt: new Date(Date.now() + 86_400_000),
+      invitedByUserId: inviter.userId,
+      skipEmail: true,
+    });
+
+    expect(fresh.id).toBeDefined();
+    const stillThere = await db()
+      .select()
+      .from(invitations)
+      .where(eq(invitations.hashedToken, expiredToken));
+    expect(stillThere).toHaveLength(0);
+  });
+
+  test('acceptInvitation creates membership + marks accepted (transactional)', 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()}`});
+    const inv = await createInvitation({
+      workspaceId: workspace.id,
+      email: accepter.email,
+      hashedToken: hashOpaqueToken('inv-accept'),
+      expiresAt: new Date(Date.now() + 86_400_000),
+      invitedByUserId: inviter.userId,
+      skipEmail: true,
+    });
+
+    const result = await acceptInvitation({
+      invitationId: inv.id,
+      acceptedByUserId: accepter.userId,
+    });
+
+    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);
+  });
+
+  test('acceptInvitation is idempotent when caller is already a 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()}`});
+    const {createMembership} = await import('./memberships.js');
+    const existing = await createMembership({userId: member.userId, workspaceId: workspace.id});
+    const inv = await createInvitation({
+      workspaceId: workspace.id,
+      email: member.email,
+      hashedToken: hashOpaqueToken('inv-idem'),
+      expiresAt: new Date(Date.now() + 86_400_000),
+      invitedByUserId: inviter.userId,
+      skipEmail: true,
+    });
+
+    const result = await acceptInvitation({invitationId: inv.id, acceptedByUserId: member.userId});
+
+    expect(result?.alreadyMember).toBe(true);
+    expect(result?.membership.id).toBe(existing.id);
+  });
+
+  test('acceptInvitation returns undefined when expired', 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()}`});
+    const expiredToken = hashOpaqueToken('expired-accept');
+    const [inserted] = await db()
+      .insert(invitations)
+      .values({
+        workspaceId: workspace.id,
+        email: accepter.email,
+        hashedToken: expiredToken,
+        expiresAt: sql`now() - interval '1 second'`,
+        invitedByUserId: inviter.userId,
+      })
+      .returning();
+    if (!inserted) throw new Error('insert failed');
+
+    const result = await acceptInvitation({
+      invitationId: inserted.id,
+      acceptedByUserId: accepter.userId,
+    });
+
+    expect(result).toBeUndefined();
+  });
+
+  test('lists only open invitations and revokes them', async () => {
+    const inviter = await createUser({email: emailFor('inviter'), hashedPassword: 'h'});
+    const workspace = await createWorkspace({name: `Workspace ${crypto.randomUUID()}`});
+    const inv = await createInvitation({
+      workspaceId: workspace.id,
+      email: emailFor('guest'),
+      hashedToken: hashOpaqueToken('inv-list'),
+      expiresAt: new Date(Date.now() + 86_400_000),
+      invitedByUserId: inviter.userId,
+      skipEmail: true,
+    });
+
+    const before = await listOpenInvitationsByWorkspace({workspaceId: workspace.id});
+    await revokeInvitation({invitationId: inv.id});
+    const after = await listOpenInvitationsByWorkspace({workspaceId: workspace.id});
+
+    expect(before.some((i) => i.id === inv.id)).toBe(true);
+    expect(after.some((i) => i.id === inv.id)).toBe(false);
+  });
+
+  test('findInvitationByToken returns matching row', async () => {
+    const inviter = await createUser({email: emailFor('inviter'), hashedPassword: 'h'});
+    const workspace = await createWorkspace({name: `Workspace ${crypto.randomUUID()}`});
+    const tokenHash = hashOpaqueToken('inv-find');
+    const inv = await createInvitation({
+      workspaceId: workspace.id,
+      email: emailFor('guest'),
+      hashedToken: tokenHash,
+      expiresAt: new Date(Date.now() + 86_400_000),
+      invitedByUserId: inviter.userId,
+      skipEmail: true,
+    });
+
+    const found = await findInvitationByToken({hashedToken: tokenHash});
+
+    expect(found?.id).toBe(inv.id);
+  });
+});

package/src/db/invitations.ts

@@ -0,0 +1,235 @@
+import {
+  WORKSPACES_INVITATION_SEND_REQUESTED,
+  type WorkspacesEventMap,
+} from '@shipfox/api-workspaces-dto';
+import {writeOutboxEvent} from '@shipfox/node-outbox';
+import {and, eq, gt, isNull, lt, sql} from 'drizzle-orm';
+import type {Invitation} from '#core/entities/invitation.js';
+import type {Membership} from '#core/entities/membership.js';
+import {OpenInvitationExistsError} from '#core/errors.js';
+import {
+  recordWorkspaceInvitationAccepted,
+  recordWorkspaceInvitationCreated,
+  recordWorkspaceMembershipChanged,
+} from '#metrics/instance.js';
+import {db} from './db.js';
+import {membershipValues} from './memberships.js';
+import {invitations, toInvitation} from './schema/invitations.js';
+import {memberships, toMembership} from './schema/memberships.js';
+import {workspacesOutbox} from './schema/outbox.js';
+
+interface CreateInvitationBaseParams {
+  workspaceId: string;
+  email: string;
+  hashedToken: string;
+  expiresAt: Date;
+  invitedByUserId: string;
+  invitedByDisplay?: string | null;
+}
+
+export type CreateInvitationParams = CreateInvitationBaseParams &
+  (
+    | {
+        sendEmail: {
+          workspaceName: string;
+          inviterName: string;
+          inviteLink: string;
+        };
+        skipEmail?: never;
+      }
+    | {sendEmail?: never; skipEmail: true}
+  );
+
+export async function createInvitation(params: CreateInvitationParams): Promise<Invitation> {
+  const result = await db().transaction(async (tx) => {
+    await tx
+      .delete(invitations)
+      .where(
+        and(
+          eq(invitations.workspaceId, params.workspaceId),
+          eq(invitations.email, params.email),
+          isNull(invitations.acceptedAt),
+          lt(invitations.expiresAt, sql`now()`),
+        ),
+      );
+
+    const open = await tx
+      .select()
+      .from(invitations)
+      .where(
+        and(
+          eq(invitations.workspaceId, params.workspaceId),
+          eq(invitations.email, params.email),
+          isNull(invitations.acceptedAt),
+        ),
+      )
+      .limit(1);
+
+    if (open.length > 0) {
+      throw new OpenInvitationExistsError(params.email);
+    }
+
+    const rows = await tx
+      .insert(invitations)
+      .values({
+        workspaceId: params.workspaceId,
+        email: params.email,
+        hashedToken: params.hashedToken,
+        expiresAt: params.expiresAt,
+        invitedByUserId: params.invitedByUserId,
+        invitedByDisplay: params.invitedByDisplay ?? null,
+      })
+      .returning();
+
+    const row = rows[0];
+    if (!row) throw new Error('Insert returned no rows');
+    if (params.sendEmail) {
+      await writeOutboxEvent<WorkspacesEventMap>(tx, workspacesOutbox, {
+        type: WORKSPACES_INVITATION_SEND_REQUESTED,
+        payload: {
+          email: params.email,
+          ...params.sendEmail,
+        },
+      });
+    }
+    return {
+      invitation: toInvitation(row),
+      emailRequested: params.sendEmail ? ('requested' as const) : ('skipped' as const),
+    };
+  });
+
+  recordWorkspaceInvitationCreated(result.emailRequested);
+  return result.invitation;
+}
+
+export async function findInvitationByToken(params: {
+  hashedToken: string;
+}): Promise<Invitation | undefined> {
+  const rows = await db()
+    .select()
+    .from(invitations)
+    .where(eq(invitations.hashedToken, params.hashedToken))
+    .limit(1);
+
+  const row = rows[0];
+  if (!row) return undefined;
+  return toInvitation(row);
+}
+
+export async function findInvitationById(params: {id: string}): Promise<Invitation | undefined> {
+  const rows = await db().select().from(invitations).where(eq(invitations.id, params.id)).limit(1);
+
+  const row = rows[0];
+  if (!row) return undefined;
+  return toInvitation(row);
+}
+
+export async function listOpenInvitationsByWorkspace(params: {
+  workspaceId: string;
+}): Promise<Invitation[]> {
+  const rows = await db()
+    .select()
+    .from(invitations)
+    .where(
+      and(
+        eq(invitations.workspaceId, params.workspaceId),
+        isNull(invitations.acceptedAt),
+        gt(invitations.expiresAt, sql`now()`),
+      ),
+    );
+
+  return rows.map(toInvitation);
+}
+
+export async function revokeInvitation(params: {invitationId: string}): Promise<void> {
+  await db().delete(invitations).where(eq(invitations.id, params.invitationId));
+}
+
+export interface AcceptInvitationParams {
+  invitationId: string;
+  acceptedByUserId: string;
+  acceptedByUserName?: string | null | undefined;
+}
+
+export interface AcceptInvitationResult {
+  invitation: Invitation;
+  membership: Membership;
+  alreadyMember: boolean;
+}
+
+export async function acceptInvitation(
+  params: AcceptInvitationParams,
+): Promise<AcceptInvitationResult | undefined> {
+  const result = await db().transaction(async (tx) => {
+    const inv = await tx
+      .select()
+      .from(invitations)
+      .where(
+        and(
+          eq(invitations.id, params.invitationId),
+          isNull(invitations.acceptedAt),
+          gt(invitations.expiresAt, sql`now()`),
+        ),
+      )
+      .limit(1);
+
+    const invRow = inv[0];
+    if (!invRow) return undefined;
+
+    const existing = await tx
+      .select()
+      .from(memberships)
+      .where(
+        and(
+          eq(memberships.userId, params.acceptedByUserId),
+          eq(memberships.workspaceId, invRow.workspaceId),
+        ),
+      )
+      .limit(1);
+
+    let membership: Membership;
+    let alreadyMember = false;
+    const existingRow = existing[0];
+
+    if (existingRow) {
+      alreadyMember = true;
+      membership = toMembership(existingRow);
+    } else {
+      const created = await tx
+        .insert(memberships)
+        .values(
+          membershipValues({
+            userId: params.acceptedByUserId,
+            userEmail: invRow.email,
+            userName: params.acceptedByUserName ?? null,
+            workspaceId: invRow.workspaceId,
+          }),
+        )
+        .returning();
+      const createdRow = created[0];
+      if (!createdRow) throw new Error('Insert returned no rows');
+      membership = toMembership(createdRow);
+    }
+
+    const updated = await tx
+      .update(invitations)
+      .set({
+        acceptedAt: sql`now()`,
+        acceptedByUserId: params.acceptedByUserId,
+        updatedAt: sql`now()`,
+      })
+      .where(eq(invitations.id, params.invitationId))
+      .returning();
+
+    const updatedRow = updated[0];
+    if (!updatedRow) throw new Error('Update returned no rows');
+
+    return {invitation: toInvitation(updatedRow), membership, alreadyMember};
+  });
+
+  if (result && !result.alreadyMember) recordWorkspaceMembershipChanged('added');
+  if (result) {
+    recordWorkspaceInvitationAccepted(result.alreadyMember ? 'already_member' : 'added');
+  }
+  return result;
+}