speckle-server/packages/server/modules/workspaces/domain/operations.ts

import { WorkspaceEvents } from '@/modules/workspacesCore/domain/events'
import {
  Workspace,
  WorkspaceAcl,
  WorkspaceDomain,
  WorkspaceJoinRequest,
  WorkspaceJoinRequestStatus,
  WorkspaceRegionAssignment,
  WorkspaceWithDomains,
  WorkspaceWithOptionalRole
} from '@/modules/workspacesCore/domain/types'
import { EventBusPayloads } from '@/modules/shared/services/eventBus'
import {
  MaybeNullOrUndefined,
  Nullable,
  NullableKeysToOptional,
  Optional,
  PartialNullable,
  StreamRoles,
  WorkspaceRoles
} from '@speckle/shared'
import { WorkspaceCreationState } from '@/modules/workspaces/domain/types'
import { WorkspaceTeam } from '@/modules/workspaces/domain/types'
import { Stream, StreamWithOptionalRole } from '@/modules/core/domain/streams/types'
import { TokenResourceIdentifier } from '@/modules/core/domain/tokens/types'
import { ServerRegion } from '@/modules/multiregion/domain/types'
import { SetOptional } from 'type-fest'
import { WorkspaceSeat, WorkspaceSeatType } from '@/modules/gatekeeper/domain/billing'

/** Workspace */

export type UpsertWorkspaceArgs = {
  workspace: Omit<
    SetOptional<
      NullableKeysToOptional<Workspace>,
      'domainBasedMembershipProtectionEnabled' | 'discoverabilityEnabled' | 'slug'
    >,
    'domains'
  >
}

export type UpsertWorkspace = (args: UpsertWorkspaceArgs) => Promise<void>

export type GetUserDiscoverableWorkspaces = (args: {
  domains: string[]
  userId: string
}) => Promise<Pick<Workspace, 'id' | 'name' | 'slug' | 'description' | 'logo'>[]>

export type GetWorkspace = (args: {
  workspaceId: string
  userId?: string
}) => Promise<WorkspaceWithOptionalRole | null>

export type GetWorkspaceBySlug = (args: {
  workspaceSlug: string
  userId?: string
}) => Promise<WorkspaceWithOptionalRole | null>

// Useful for dev purposes (e.g. CLI)
export type GetWorkspaceBySlugOrId = (args: {
  workspaceSlugOrId: string
}) => Promise<Workspace | null>

export type GetWorkspaces = (args: {
  workspaceIds?: string[]
  userId?: string
}) => Promise<WorkspaceWithOptionalRole[]>

export type GetWorkspacesBySlug = (args: {
  workspaceIds: string[]
  userId?: string
}) => Promise<WorkspaceWithOptionalRole[]>

export type StoreWorkspaceDomain = (args: {
  workspaceDomain: WorkspaceDomain
}) => Promise<void>

export type GetWorkspaceDomains = (args: {
  workspaceIds: string[]
}) => Promise<WorkspaceDomain[]>

type DeleteWorkspaceArgs = {
  workspaceId: string
}

export type CountDomainsByWorkspaceId = (args: {
  workspaceId: string
}) => Promise<number>

export type DeleteWorkspaceDomain = (args: { id: string }) => Promise<void>

export type GetWorkspaceWithDomains = (args: {
  id: string
}) => Promise<WorkspaceWithDomains | null>

export type DeleteWorkspace = (args: DeleteWorkspaceArgs) => Promise<void>

type CountWorkspacesArgs = {
  filter?: {
    search?: string
  }
}
export type QueryWorkspacesArgs = CountWorkspacesArgs & {
  limit: number
  cursor?: string
}
export type QueryWorkspaces = (args: QueryWorkspacesArgs) => Promise<Workspace[]>
export type CountWorkspaces = (args: CountWorkspacesArgs) => Promise<number>

/** Workspace Roles */

export type GetWorkspaceCollaboratorsArgs = {
  workspaceId: string
  limit: number
  cursor?: string
  filter?: {
    /**
     * Optionally filter by workspace role(s)
     */
    roles?: WorkspaceRoles[]
    /**
     * Optionally filter by user name or email
     */
    search?: string
    seatType?: WorkspaceSeatType
  }
}

export type GetWorkspaceCollaborators = (
  args: GetWorkspaceCollaboratorsArgs
) => Promise<WorkspaceTeam>

type GetWorkspaceCollaboratorsTotalCountArgs = {
  workspaceId: string
}

export type GetWorkspaceCollaboratorsTotalCount = (
  args: GetWorkspaceCollaboratorsTotalCountArgs
) => Promise<number>

type DeleteWorkspaceRoleArgs = {
  workspaceId: string
  userId: string
}

export type DeleteWorkspaceRole = (
  args: DeleteWorkspaceRoleArgs
) => Promise<WorkspaceAcl | null>

type GetWorkspaceRolesArgs = {
  workspaceId: string
}

/** Get all roles in a given workspaces. */
export type GetWorkspaceRoles = (args: GetWorkspaceRolesArgs) => Promise<WorkspaceAcl[]>

type GetWorkspaceRoleForUserArgs = {
  userId: string
  workspaceId: string
}

/** Get role for given user in a specific workspace. */
export type GetWorkspaceRoleForUser = (
  args: GetWorkspaceRoleForUserArgs
) => Promise<WorkspaceAcl | null>

type GetWorkspaceRolesForUserArgs = {
  userId: string
}

type GetWorkspaceRolesForUserOptions = {
  /** If provided, limit results to roles in given workspaces. */
  workspaceIdFilter?: string[]
}

/** Get roles for given user across several (or all) workspaces. */
export type GetWorkspaceRolesForUser = (
  args: GetWorkspaceRolesForUserArgs,
  options?: GetWorkspaceRolesForUserOptions
) => Promise<WorkspaceAcl[]>

/** Repository-level change to workspace acl record */
export type UpsertWorkspaceRole = (args: WorkspaceAcl) => Promise<void>

/** Service-level change with protection against invalid role changes */
export type UpdateWorkspaceRole = (
  args: Pick<WorkspaceAcl, 'userId' | 'workspaceId' | 'role'> & {
    /**
     * If this gets triggered from a project role update, we don't want to override that project's role to the default one
     */
    skipProjectRoleUpdatesFor?: string[]
    /**
     * Only add or upgrade role, prevent downgrades
     */
    preventRoleDowngrade?: boolean

    updatedByUserId: string
  }
) => Promise<void>

export type GetWorkspaceRoleToDefaultProjectRoleMapping = (args: {
  workspaceId: string
}) => Promise<{
  allowed: {
    [workspaceRole in WorkspaceRoles]: StreamRoles[]
  }
  default: {
    [workspaceRole in WorkspaceRoles]: StreamRoles | null
  }
}>

export type GetWorkspaceSeatTypeToProjectRoleMapping = (args: {
  workspaceId: string
}) => Promise<{
  allowed: {
    [workspaceSeatType in WorkspaceSeatType]: StreamRoles[]
  }
  default: {
    [workspaceSeatType in WorkspaceSeatType]: StreamRoles
  }
}>

/** Workspace Projects */

type QueryAllWorkspaceProjectsArgs = {
  workspaceId: string
  /**
   * Optionally get project roles for a specific user
   */
  userId?: string
}

export type QueryAllWorkspaceProjects = (
  args: QueryAllWorkspaceProjectsArgs
) => AsyncGenerator<StreamWithOptionalRole[], void, unknown>

export type GetWorkspacesProjectsCounts = (params: {
  workspaceIds: string[]
}) => Promise<{
  [workspaceId: string]: number
}>

/** Workspace Project Roles */

type GrantWorkspaceProjectRolesArgs = {
  projectId: string
  workspaceId: string
}

export type GrantWorkspaceProjectRoles = (
  args: GrantWorkspaceProjectRolesArgs
) => Promise<void>

type UpdateWorkspaceProjectRoleArgs = {
  role: {
    projectId: string
    userId: string
    // Undefined or null role means delete role
    role?: Nullable<string>
  }
  updater: {
    userId: string
    resourceAccessRules: MaybeNullOrUndefined<TokenResourceIdentifier[]>
  }
}

export type UpdateWorkspaceProjectRole = (
  args: UpdateWorkspaceProjectRoleArgs
) => Promise<Stream | undefined>

/** Events */

export type EmitWorkspaceEvent = <
  TEvent extends WorkspaceEvents & keyof EventBusPayloads
>(args: {
  eventName: TEvent
  payload: EventBusPayloads[TEvent]
}) => Promise<void>

export type CountWorkspaceRoleWithOptionalProjectRole = (args: {
  workspaceId: string
  workspaceRole: WorkspaceRoles
  projectRole?: StreamRoles
  skipUserIds?: string[]
}) => Promise<number>

export type GetUserIdsWithRoleInWorkspace = (
  args: {
    workspaceId: string
    workspaceRole: WorkspaceRoles
  },
  options?: { limit?: number }
) => Promise<string[]>

type WorkspaceUpdateArgs = {
  workspaceId: string
  workspaceInput: PartialNullable<Omit<Workspace, 'id' | 'createdAt' | 'updatedAt'>>
}

export type UpdateWorkspace = ({
  workspaceId,
  workspaceInput
}: WorkspaceUpdateArgs) => Promise<Workspace>

/**
 * Workspace regions
 */

export type GetAvailableRegions = (params: {
  workspaceId: string
}) => Promise<ServerRegion[]>

export type AssignWorkspaceRegion = (params: {
  workspaceId: string
  regionKey: string
}) => Promise<void>

export type GetDefaultRegion = (params: {
  workspaceId: string
}) => Promise<Optional<ServerRegion>>

export type UpsertRegionAssignment = (params: {
  workspaceId: string
  regionKey: string
}) => Promise<WorkspaceRegionAssignment>

export type GetWorkspaceCreationState = (params: {
  workspaceId: string
}) => Promise<WorkspaceCreationState | null>

export type UpsertWorkspaceCreationState = (params: {
  workspaceCreationState: WorkspaceCreationState
}) => Promise<void>

export type UpdateWorkspaceJoinRequestStatus = (params: {
  workspaceId: string
  userId: string
  status: WorkspaceJoinRequestStatus
}) => Promise<number[]>

export type CreateWorkspaceJoinRequest = (params: {
  workspaceJoinRequest: Omit<WorkspaceJoinRequest, 'createdAt' | 'updatedAt'>
}) => Promise<WorkspaceJoinRequest>

export type SendWorkspaceJoinRequestReceivedEmail = (params: {
  workspace: Pick<Workspace, 'id' | 'name' | 'slug'>
  requester: { id: string; name: string; email: string }
}) => Promise<void>

export type SendWorkspaceJoinRequestApprovedEmail = (params: {
  workspace: Pick<Workspace, 'id' | 'name' | 'slug'>
  requester: { id: string; name: string; email: string }
}) => Promise<void>

export type SendWorkspaceJoinRequestDeniedEmail = (params: {
  workspace: Pick<Workspace, 'id' | 'name' | 'slug'>
  requester: { id: string; name: string; email: string }
}) => Promise<void>

export type GetWorkspaceJoinRequest = (
  params: Pick<WorkspaceJoinRequest, 'userId' | 'workspaceId'> &
    Partial<Pick<WorkspaceJoinRequest, 'status'>>
) => Promise<WorkspaceJoinRequest | undefined>

export type ApproveWorkspaceJoinRequest = (
  params: Pick<WorkspaceJoinRequest, 'workspaceId' | 'userId'> & {
    approvedByUserId: string
  }
) => Promise<boolean>

export type DenyWorkspaceJoinRequest = (
  params: Pick<WorkspaceJoinRequest, 'workspaceId' | 'userId'>
) => Promise<boolean>

/**
 * Project regions
 */

/**
 * Updates project region and moves all regional data to target regional db
 */
export type UpdateProjectRegion = (params: {
  projectId: string
  regionKey: string
}) => Promise<Stream>

/**
 * Given a count of objects successfully copied to another region, confirm that these counts
 * match the current state of the source project in its original region.
 */
export type ValidateProjectRegionCopy = (params: {
  projectId: string
  copiedRowCount: {
    models: number
    versions: number
    objects: number
    automations: number
    comments: number
    webhooks: number
  }
}) => Promise<boolean>

export type CopyWorkspace = (params: { workspaceId: string }) => Promise<string>
export type CopyProjects = (params: { projectIds: string[] }) => Promise<string[]>
export type CopyProjectModels = (params: {
  projectIds: string[]
}) => Promise<Record<string, number>>
export type CopyProjectVersions = (params: {
  projectIds: string[]
}) => Promise<Record<string, number>>
export type CopyProjectObjects = (params: {
  projectIds: string[]
}) => Promise<Record<string, number>>
export type CopyProjectAutomations = (params: {
  projectIds: string[]
}) => Promise<Record<string, number>>

export type AssignWorkspaceSeat = (
  params: Pick<WorkspaceSeat, 'userId' | 'workspaceId'> & {
    type: WorkspaceSeatType
    assignedByUserId: string
  }
) => Promise<WorkspaceSeat>

export type EnsureValidWorkspaceRoleSeat = (params: {
  workspaceId: string
  userId: string
  role: WorkspaceRoles
  updatedByUserId: string
}) => Promise<WorkspaceSeat>

export type CopyProjectComments = (params: {
  projectIds: string[]
}) => Promise<Record<string, number>>
export type CopyProjectWebhooks = (params: {
  projectIds: string[]
}) => Promise<Record<string, number>>
export type CopyProjectBlobs = (params: {
  projectIds: string[]
}) => Promise<Record<string, number>>

export type SetUserActiveWorkspace = (args: {
  userId: string
  workspaceSlug: string | null
  /** Is the user in a "personal project" outside of a workspace? */
  isProjectsActive?: boolean
}) => Promise<void>