@shipfox/api-workspaces 2.0.0

package/src/core/errors.ts

@@ -0,0 +1,118 @@
+export class WorkspaceNotFoundError extends Error {
+  constructor(workspaceId: string) {
+    super(`Workspace not found: ${workspaceId}`);
+    this.name = 'WorkspaceNotFoundError';
+  }
+}
+
+export class WorkspaceInactiveError extends Error {
+  constructor(workspaceId: string) {
+    super(`Workspace is not active: ${workspaceId}`);
+    this.name = 'WorkspaceInactiveError';
+  }
+}
+
+export class InvitationNotFoundError extends Error {
+  constructor(id: string) {
+    super(`Invitation not found: ${id}`);
+    this.name = 'InvitationNotFoundError';
+  }
+}
+
+export class InvitationWorkspaceMismatchError extends Error {
+  constructor() {
+    super('Invitation does not belong to this workspace');
+    this.name = 'InvitationWorkspaceMismatchError';
+  }
+}
+
+export class MembershipNotFoundError extends Error {
+  constructor(userId: string, workspaceId: string) {
+    super(`Membership not found for user ${userId} in workspace ${workspaceId}`);
+    this.name = 'MembershipNotFoundError';
+  }
+}
+
+export class UserNotFoundError extends Error {
+  constructor(idOrEmail: string) {
+    super(`User not found: ${idOrEmail}`);
+    this.name = 'UserNotFoundError';
+  }
+}
+
+export class EmailTakenError extends Error {
+  constructor(email: string) {
+    super(`Email already registered: ${email}`);
+    this.name = 'EmailTakenError';
+  }
+}
+
+export class InvalidCredentialsError extends Error {
+  constructor() {
+    super('Invalid credentials');
+    this.name = 'InvalidCredentialsError';
+  }
+}
+
+export class EmailNotVerifiedError extends Error {
+  constructor() {
+    super('Email not verified');
+    this.name = 'EmailNotVerifiedError';
+  }
+}
+
+export class TokenInvalidError extends Error {
+  constructor(reason?: string) {
+    super(reason ? `Invalid token: ${reason}` : 'Invalid token');
+    this.name = 'TokenInvalidError';
+  }
+}
+
+export class TokenExpiredError extends Error {
+  constructor() {
+    super('Token has expired');
+    this.name = 'TokenExpiredError';
+  }
+}
+
+export class TokenAlreadyUsedError extends Error {
+  constructor() {
+    super('Token has already been used');
+    this.name = 'TokenAlreadyUsedError';
+  }
+}
+
+export class MembershipRequiredError extends Error {
+  constructor(workspaceId: string) {
+    super(`Membership required for workspace: ${workspaceId}`);
+    this.name = 'MembershipRequiredError';
+  }
+}
+
+export class LastMemberError extends Error {
+  constructor(workspaceId: string) {
+    super(`Cannot remove the last member of workspace: ${workspaceId}`);
+    this.name = 'LastMemberError';
+  }
+}
+
+export class SelfRemovalNotAllowedError extends Error {
+  constructor() {
+    super('Cannot remove yourself from a workspace');
+    this.name = 'SelfRemovalNotAllowedError';
+  }
+}
+
+export class InvitationEmailMismatchError extends Error {
+  constructor() {
+    super('Invitation email does not match authenticated user');
+    this.name = 'InvitationEmailMismatchError';
+  }
+}
+
+export class OpenInvitationExistsError extends Error {
+  constructor(email: string) {
+    super(`An open invitation already exists for: ${email}`);
+    this.name = 'OpenInvitationExistsError';
+  }
+}

package/src/core/index.ts

@@ -0,0 +1,35 @@
+export type {Invitation} from './entities/invitation.js';
+export type {Membership} from './entities/membership.js';
+export type {Workspace, WorkspaceStatus} from './entities/workspace.js';
+export {
+  InvitationEmailMismatchError,
+  InvitationNotFoundError,
+  InvitationWorkspaceMismatchError,
+  LastMemberError,
+  MembershipNotFoundError,
+  MembershipRequiredError,
+  OpenInvitationExistsError,
+  SelfRemovalNotAllowedError,
+  TokenAlreadyUsedError,
+  TokenExpiredError,
+  WorkspaceNotFoundError,
+} from './errors.js';
+export {
+  acceptWorkspaceInvitation,
+  createWorkspaceInvitation,
+  listWorkspaceInvitations,
+  type PreviewInvitationResult,
+  previewInvitation,
+  revokeWorkspaceInvitation,
+} from './invitations.js';
+export {type EnsureMembershipParams, ensureMembership} from './memberships.js';
+export {
+  createWorkspaceForUser,
+  getWorkspace,
+  listUserWorkspaceMemberships,
+  listWorkspaceMembers,
+  type RequireWorkspaceMembershipParams,
+  type RequireWorkspaceMembershipResult,
+  removeWorkspaceMember,
+  requireWorkspaceMembership,
+} from './workspaces.js';

package/src/core/invitations.test.ts

@@ -0,0 +1,251 @@
+import {WORKSPACES_INVITATION_SEND_REQUESTED} from '@shipfox/api-workspaces-dto';
+import type {Mailer, MailMessage} from '@shipfox/node-mailer';
+import {and, desc, eq, sql} from 'drizzle-orm';
+import {db} from '#db/db.js';
+import {createMembership} from '#db/memberships.js';
+import {workspacesOutbox} from '#db/schema/outbox.js';
+import {userFactory, workspaceFactory} from '#test/index.js';
+import {
+  InvitationEmailMismatchError,
+  OpenInvitationExistsError,
+  TokenAlreadyUsedError,
+} from './errors.js';
+import {acceptWorkspaceInvitation, createWorkspaceInvitation} from './invitations.js';
+
+const testConfig = vi.hoisted(
+  (): {
+    captured: MailMessage[];
+    mailer: Mailer;
+    clientBaseUrl: string;
+  } => {
+    const captured: MailMessage[] = [];
+    const mailer: Mailer = {
+      send: (message) => {
+        captured.push(message);
+        return Promise.resolve();
+      },
+    };
+    return {
+      captured,
+      mailer,
+      clientBaseUrl: 'https://app.example.test',
+    };
+  },
+);
+
+vi.mock('#config.js', () => ({
+  config: {
+    WORKSPACE_JWT_SECRET: 'invitation-core-test-secret',
+    WORKSPACE_JWT_EXPIRES_IN: '7d',
+    CLIENT_BASE_URL: testConfig.clientBaseUrl,
+  },
+  mailer: testConfig.mailer,
+}));
+
+const TOKEN_RE = /token=([\w\-_=]+)/;
+
+function extractToken(link: string | undefined): string {
+  const match = link?.match(TOKEN_RE);
+  if (!match?.[1]) {
+    throw new Error('Expected link to contain a token');
+  }
+  return match[1];
+}
+
+async function invitationEventsTo(email: string) {
+  return await db()
+    .select()
+    .from(workspacesOutbox)
+    .where(
+      and(
+        eq(workspacesOutbox.eventType, WORKSPACES_INVITATION_SEND_REQUESTED),
+        sql`${workspacesOutbox.payload}->>'email' = ${email}`,
+      ),
+    )
+    .orderBy(desc(workspacesOutbox.createdAt));
+}
+
+async function latestInvitationPayload(email: string) {
+  const row = (await invitationEventsTo(email))[0];
+  if (!row) throw new Error(`No invitation outbox event for ${email}`);
+  return row.payload as {
+    email: string;
+    workspaceName: string;
+    inviterName: string;
+    inviteLink: string;
+  };
+}
+
+describe('invitations core', () => {
+  let captured: MailMessage[];
+
+  beforeEach(() => {
+    captured = testConfig.captured;
+    captured.length = 0;
+  });
+
+  test('createWorkspaceInvitation creates an invitation and queues an email', async () => {
+    const inviter = userFactory.build();
+    const workspace = await workspaceFactory.create();
+    await createMembership({
+      userId: inviter.userId,
+      userEmail: inviter.email,
+      userName: inviter.name,
+      workspaceId: workspace.id,
+    });
+    const email = `invitee-${crypto.randomUUID()}@example.com`;
+
+    const invitation = await createWorkspaceInvitation({
+      workspaceId: workspace.id,
+      email,
+      invitedByUserId: inviter.userId,
+      invitedByMemberships: [{workspaceId: workspace.id, role: 'admin'}],
+    });
+
+    expect(invitation.email).toBe(email);
+    expect(captured).toHaveLength(0);
+    expect(await invitationEventsTo(email)).toHaveLength(1);
+  });
+
+  test('createWorkspaceInvitation queues the workspace name and inviter', async () => {
+    const inviter = userFactory.build();
+    const workspace = await workspaceFactory.create();
+    await createMembership({
+      userId: inviter.userId,
+      userEmail: inviter.email,
+      userName: inviter.name,
+      workspaceId: workspace.id,
+    });
+    const email = `invitee-${crypto.randomUUID()}@example.com`;
+
+    await createWorkspaceInvitation({
+      workspaceId: workspace.id,
+      email,
+      invitedByUserId: inviter.userId,
+      invitedByDisplay: 'Dana Scully',
+      invitedByMemberships: [{workspaceId: workspace.id, role: 'admin'}],
+    });
+
+    const payload = await latestInvitationPayload(email);
+    expect(captured).toHaveLength(0);
+    expect(payload).toMatchObject({
+      email,
+      workspaceName: workspace.name,
+      inviterName: 'Dana Scully',
+    });
+    expect(payload.inviteLink).toContain(`${testConfig.clientBaseUrl}/invitations/accept?token=`);
+  });
+
+  test('createWorkspaceInvitation queues the teammate fallback when no inviter display is given', async () => {
+    const inviter = userFactory.build();
+    const workspace = await workspaceFactory.create();
+    await createMembership({
+      userId: inviter.userId,
+      userEmail: inviter.email,
+      userName: inviter.name,
+      workspaceId: workspace.id,
+    });
+    const email = `invitee-${crypto.randomUUID()}@example.com`;
+
+    await createWorkspaceInvitation({
+      workspaceId: workspace.id,
+      email,
+      invitedByUserId: inviter.userId,
+      invitedByMemberships: [{workspaceId: workspace.id, role: 'admin'}],
+    });
+
+    const payload = await latestInvitationPayload(email);
+    expect(captured).toHaveLength(0);
+    expect(payload.inviterName).toBe('A teammate');
+  });
+
+  test('createWorkspaceInvitation queues fallbacks for blank display values', async () => {
+    const inviter = userFactory.build();
+    const workspace = await workspaceFactory.create({name: '   '});
+    await createMembership({
+      userId: inviter.userId,
+      userEmail: inviter.email,
+      userName: inviter.name,
+      workspaceId: workspace.id,
+    });
+    const email = `invitee-${crypto.randomUUID()}@example.com`;
+
+    await createWorkspaceInvitation({
+      workspaceId: workspace.id,
+      email,
+      invitedByUserId: inviter.userId,
+      invitedByDisplay: '   ',
+      invitedByMemberships: [{workspaceId: workspace.id, role: 'admin'}],
+    });
+
+    const payload = await latestInvitationPayload(email);
+    expect(captured).toHaveLength(0);
+    expect(payload.workspaceName).toBe('your workspace');
+    expect(payload.inviterName).toBe('A teammate');
+  });
+
+  test('createWorkspaceInvitation rejects duplicate open invitations', async () => {
+    const inviter = userFactory.build();
+    const workspace = await workspaceFactory.create();
+    await createMembership({
+      userId: inviter.userId,
+      userEmail: inviter.email,
+      userName: inviter.name,
+      workspaceId: workspace.id,
+    });
+    const email = `duplicate-${crypto.randomUUID()}@example.com`;
+    await createWorkspaceInvitation({
+      workspaceId: workspace.id,
+      email,
+      invitedByUserId: inviter.userId,
+      invitedByMemberships: [{workspaceId: workspace.id, role: 'admin'}],
+    });
+
+    const promise = createWorkspaceInvitation({
+      workspaceId: workspace.id,
+      email,
+      invitedByUserId: inviter.userId,
+      invitedByMemberships: [{workspaceId: workspace.id, role: 'admin'}],
+    });
+
+    await expect(promise).rejects.toBeInstanceOf(OpenInvitationExistsError);
+    expect(captured).toHaveLength(0);
+    expect(await invitationEventsTo(email)).toHaveLength(1);
+  });
+
+  test('acceptWorkspaceInvitation accepts once and enforces the invited email', async () => {
+    const inviter = userFactory.build();
+    const invitee = userFactory.build();
+    const workspace = await workspaceFactory.create();
+    await createMembership({
+      userId: inviter.userId,
+      userEmail: inviter.email,
+      userName: inviter.name,
+      workspaceId: workspace.id,
+    });
+    await createWorkspaceInvitation({
+      workspaceId: workspace.id,
+      email: invitee.email,
+      invitedByUserId: inviter.userId,
+      invitedByMemberships: [{workspaceId: workspace.id, role: 'admin'}],
+    });
+    const token = extractToken((await latestInvitationPayload(invitee.email)).inviteLink);
+
+    const wrongEmail = acceptWorkspaceInvitation({
+      token,
+      userId: invitee.userId,
+      email: `wrong-${crypto.randomUUID()}@example.com`,
+    });
+    await expect(wrongEmail).rejects.toBeInstanceOf(InvitationEmailMismatchError);
+
+    const result = await acceptWorkspaceInvitation({
+      token,
+      userId: invitee.userId,
+      email: invitee.email,
+    });
+    expect(result.membership.workspaceId).toBe(workspace.id);
+
+    const reused = acceptWorkspaceInvitation({token, userId: invitee.userId, email: invitee.email});
+    await expect(reused).rejects.toBeInstanceOf(TokenAlreadyUsedError);
+  });
+});

package/src/core/invitations.ts

@@ -0,0 +1,191 @@
+import type {UserContextMembership} from '@shipfox/api-auth-context';
+import {generateOpaqueToken, hashOpaqueToken} from '@shipfox/node-tokens';
+import {config} from '#config.js';
+import {
+  type AcceptInvitationResult,
+  acceptInvitation,
+  createInvitation,
+  findInvitationById,
+  findInvitationByToken,
+  listOpenInvitationsByWorkspace,
+  revokeInvitation,
+} from '#db/invitations.js';
+import {getWorkspaceById} from '#db/workspaces.js';
+import type {Invitation} from './entities/invitation.js';
+import {
+  InvitationEmailMismatchError,
+  InvitationNotFoundError,
+  InvitationWorkspaceMismatchError,
+  TokenAlreadyUsedError,
+  TokenExpiredError,
+  TokenInvalidError,
+} from './errors.js';
+import {requireWorkspaceMembership} from './workspaces.js';
+
+const INVITATION_TTL_DAYS = 7;
+
+function daysFromNow(days: number): Date {
+  return new Date(Date.now() + days * 24 * 60 * 60 * 1000);
+}
+
+function nonBlankOrFallback(value: string | null | undefined, fallback: string): string {
+  const trimmed = value?.trim();
+  return trimmed ? trimmed : fallback;
+}
+
+export async function createWorkspaceInvitation(params: {
+  workspaceId: string;
+  email: string;
+  invitedByUserId: string;
+  invitedByDisplay?: string | null;
+  invitedByMemberships: ReadonlyArray<UserContextMembership>;
+}): Promise<Invitation> {
+  const {workspace} = await requireWorkspaceMembership({
+    workspaceId: params.workspaceId,
+    userId: params.invitedByUserId,
+    memberships: params.invitedByMemberships,
+  });
+
+  const rawToken = generateOpaqueToken('invitation');
+  const invitation = await createInvitation({
+    workspaceId: params.workspaceId,
+    email: params.email,
+    hashedToken: hashOpaqueToken(rawToken),
+    expiresAt: daysFromNow(INVITATION_TTL_DAYS),
+    invitedByUserId: params.invitedByUserId,
+    invitedByDisplay: params.invitedByDisplay ?? null,
+    sendEmail: {
+      workspaceName: nonBlankOrFallback(workspace.name, 'your workspace'),
+      inviterName: nonBlankOrFallback(params.invitedByDisplay, 'A teammate'),
+      inviteLink: `${config.CLIENT_BASE_URL}/invitations/accept?token=${rawToken}`,
+    },
+  });
+
+  return invitation;
+}
+
+export async function peekInvitationByRawToken(params: {
+  token: string;
+}): Promise<Invitation | undefined> {
+  return await findInvitationByToken({hashedToken: hashOpaqueToken(params.token)});
+}
+
+export type PreviewInvitationResult =
+  | {
+      status: 'pending';
+      workspaceId: string;
+      workspaceName: string;
+      email: string;
+      invitedByDisplay: string | null;
+      expiresAt: Date;
+    }
+  | {status: 'expired'; workspaceName: string; expiresAt: Date}
+  | {status: 'already_used'; workspaceName: string}
+  | {status: 'invalid'};
+
+export async function previewInvitation(params: {token: string}): Promise<PreviewInvitationResult> {
+  const invitation = await peekInvitationByRawToken({token: params.token});
+  if (!invitation) {
+    return {status: 'invalid'};
+  }
+
+  const workspace = await getWorkspaceById(invitation.workspaceId);
+  if (!workspace) {
+    // Workspace cascade-deleted — the invitation row is orphaned. Treat as invalid.
+    return {status: 'invalid'};
+  }
+
+  if (invitation.acceptedAt !== null) {
+    return {status: 'already_used', workspaceName: workspace.name};
+  }
+
+  if (invitation.expiresAt.getTime() <= Date.now()) {
+    return {
+      status: 'expired',
+      workspaceName: workspace.name,
+      expiresAt: invitation.expiresAt,
+    };
+  }
+
+  return {
+    status: 'pending',
+    workspaceId: workspace.id,
+    workspaceName: workspace.name,
+    email: invitation.email,
+    invitedByDisplay: invitation.invitedByDisplay,
+    expiresAt: invitation.expiresAt,
+  };
+}
+
+export async function acceptWorkspaceInvitation(params: {
+  token: string;
+  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');
+  }
+
+  if (invitation.acceptedAt !== null) {
+    throw new TokenAlreadyUsedError();
+  }
+
+  if (invitation.expiresAt.getTime() <= Date.now()) {
+    throw new TokenExpiredError();
+  }
+
+  if (params.email !== invitation.email) {
+    throw new InvitationEmailMismatchError();
+  }
+
+  const result = await acceptInvitation({
+    invitationId: invitation.id,
+    acceptedByUserId: params.userId,
+    acceptedByUserName: params.name,
+  });
+  if (!result) {
+    throw new TokenInvalidError('Invitation is no longer valid');
+  }
+
+  return result;
+}
+
+export async function listWorkspaceInvitations(params: {
+  workspaceId: string;
+  requesterUserId: string;
+  requesterMemberships: ReadonlyArray<UserContextMembership>;
+}): Promise<Invitation[]> {
+  await requireWorkspaceMembership({
+    workspaceId: params.workspaceId,
+    userId: params.requesterUserId,
+    memberships: params.requesterMemberships,
+  });
+
+  return listOpenInvitationsByWorkspace({workspaceId: params.workspaceId});
+}
+
+export async function revokeWorkspaceInvitation(params: {
+  workspaceId: string;
+  requesterUserId: string;
+  requesterMemberships: ReadonlyArray<UserContextMembership>;
+  invitationId: string;
+}): Promise<void> {
+  await requireWorkspaceMembership({
+    workspaceId: params.workspaceId,
+    userId: params.requesterUserId,
+    memberships: params.requesterMemberships,
+  });
+
+  const invitation = await findInvitationById({id: params.invitationId});
+  if (!invitation) {
+    throw new InvitationNotFoundError(params.invitationId);
+  }
+
+  if (invitation.workspaceId !== params.workspaceId) {
+    throw new InvitationWorkspaceMismatchError();
+  }
+
+  await revokeInvitation({invitationId: params.invitationId});
+}

package/src/core/memberships.test.ts

@@ -0,0 +1,77 @@
+import {listMembershipsByWorkspace} from '#db/memberships.js';
+import {userFactory, workspaceFactory} from '#test/index.js';
+import {WorkspaceNotFoundError} from './errors.js';
+import {ensureMembership} from './memberships.js';
+
+describe('ensureMembership', () => {
+  test('creates a membership', async () => {
+    const user = userFactory.build();
+    const workspace = await workspaceFactory.create();
+
+    const membership = await ensureMembership({
+      userId: user.userId,
+      userEmail: user.email,
+      userName: user.name,
+      workspaceId: workspace.id,
+    });
+
+    expect(membership).toMatchObject({
+      userId: user.userId,
+      userEmail: user.email,
+      userName: user.name,
+      workspaceId: workspace.id,
+    });
+  });
+
+  test('rejects a missing workspace with WorkspaceNotFoundError', async () => {
+    const user = userFactory.build();
+
+    const membership = ensureMembership({
+      userId: user.userId,
+      userEmail: user.email,
+      userName: user.name,
+      workspaceId: crypto.randomUUID(),
+    });
+
+    await expect(membership).rejects.toBeInstanceOf(WorkspaceNotFoundError);
+  });
+
+  test('returns the existing membership without refreshing its profile snapshot', async () => {
+    const user = userFactory.build();
+    const workspace = await workspaceFactory.create();
+    const first = await ensureMembership({
+      userId: user.userId,
+      userEmail: user.email,
+      userName: 'Original Name',
+      workspaceId: workspace.id,
+    });
+    const second = await ensureMembership({
+      userId: user.userId,
+      userEmail: `replacement-${crypto.randomUUID()}@example.com`,
+      userName: 'Replacement Name',
+      workspaceId: workspace.id,
+    });
+
+    expect(second).toEqual(first);
+  });
+
+  test('uses the database constraint to converge concurrent calls on one membership', async () => {
+    const user = userFactory.build();
+    const workspace = await workspaceFactory.create();
+
+    const results = await Promise.all(
+      Array.from({length: 8}, () =>
+        ensureMembership({
+          userId: user.userId,
+          userEmail: user.email,
+          userName: user.name,
+          workspaceId: workspace.id,
+        }),
+      ),
+    );
+    const memberships = await listMembershipsByWorkspace({workspaceId: workspace.id});
+
+    expect(new Set(results.map((membership) => membership.id)).size).toBe(1);
+    expect(memberships).toHaveLength(1);
+  });
+});

package/src/core/memberships.ts

@@ -0,0 +1,17 @@
+import {
+  type EnsureMembershipParams,
+  ensureMembership as ensureDbMembership,
+} from '#db/memberships.js';
+import type {Membership} from './entities/membership.js';
+import {getWorkspace} from './workspaces.js';
+
+export type {EnsureMembershipParams} from '#db/memberships.js';
+
+/**
+ * Ensures an external identity has a workspace membership without refreshing
+ * the profile snapshot stored on an existing membership.
+ */
+export async function ensureMembership(params: EnsureMembershipParams): Promise<Membership> {
+  await getWorkspace({workspaceId: params.workspaceId});
+  return await ensureDbMembership(params);
+}