Skip to content

⭐️⭐️⭐️ Open-source, self-hosted alternative to Linear and Plane. Project management and issue tracking where teams and AI agents work side by side to plan and ship products.

7.4 KB
Raw Blame
import type { CycleOption } from '@/lib/api/endpoints/cycles';
import type { BoardIssues } from '@/lib/api/endpoints/issues';
import { request } from '@/lib/api/core/client';
import { pageQuery, type Page, type PageParams } from '@/lib/api/core/paging';
import type { Column } from '@/lib/api/endpoints/columns';
import type { CustomField } from '@/lib/api/endpoints/customFields';
import type { IssueTemplate } from '@/lib/api/endpoints/issueTemplates';
import type { IssueType } from '@/lib/api/endpoints/issueTypes';
import type { Label, LabelGroup } from '@/lib/api/endpoints/labels';
import type { MemberRole } from '@/lib/api/endpoints/members';
import type { Permissions } from '@/lib/api/endpoints/roles';
import type { ProjectFeatures } from '@/lib/api/endpoints/settings';
import type { TeamRole } from '@/lib/api/endpoints/teams';

export interface Project {
  id: number;
  teamId: number;
  teamName: string;
  // The team's slug, or its id while it has none.
  teamRef: string;
  key: string;
  // "<teamRef>.<key>": how the API and the app's paths name the project. The key
  // alone is unique only within the team.
  ref: string;
  name: string;
  description: string;
  // Whether the team's MCP reach covers this project, and whether the team is
  // reachable over MCP at all. Both are set in the team's MCP section; a tool call
  // scoped to this project needs both.
  mcpEnabled: boolean;
  teamMcpEnabled: boolean;
  // The optional sections, toggled by an owner in Settings -> General. Read through
  // useProjectFeatures, which hides the navigation and the section itself.
  initiativesEnabled: boolean;
  dashboardsEnabled: boolean;
  documentsEnabled: boolean;
  notesEnabled: boolean;
  cyclesEnabled: boolean;
  subtasksEnabled: boolean;
  checklistsEnabled: boolean;
  issueStatsEnabled: boolean;
  // The sections this project may use at all. One missing here is not available to
  // the team: its flag above always reads false and the settings page does not offer
  // it. Everything is available on a self-hosted instance.
  availableFeatures: (keyof ProjectFeatures)[];
  // Which estimate kinds the issues carry, set in Settings -> Configuration. Read
  // through useProjectFeatures, which hides the estimate rows and their display
  // properties while a kind is off.
  pointsEstimateEnabled: boolean;
  timeEstimateEnabled: boolean;
  // Whether members log the time they spend on the issues, set in the same place.
  // Independent of the time estimate.
  timeLoggingEnabled: boolean;
  archivedAt: string | null;
  createdAt: string;
  // Latest work-item activity or comment, present on the project list response.
  lastActivityAt?: string | null;
  isFavorite?: boolean;
  isHidden?: boolean;
  // The caller's role in this project, and whether it comes from their membership or
  // only from their role in the workspace. Only present on the /projects list
  // response; absent on the create/copy responses.
  role?: MemberRole;
  via?: AccessVia;
}

export interface Assignee {
  userId: string;
  name: string;
  email: string;
  // The handle they are mentioned by, @username. Null for a member who has none.
  username: string | null;
  image: string | null;
  kind: 'member' | 'agent';
  agentKind: 'external' | 'internal' | null;
  // The user an 'owner'-scoped agent works for: delegating it to anyone else queues a
  // run its runner never receives. Null for members and team-scoped agents.
  restrictedToUserId: string | null;
  // Whether @-mentioning this agent starts a run. Null for a person.
  respondsToMention: boolean | null;
  // Whether this person may read issues and can therefore receive watcher
  // notifications without leaking work-item content.
  canReadWorkItems: boolean;
}

// The caller's own role in a project (owner/member). Returned with the project;
// the resolved permission matrix is a sibling `permissions` field. See
// usePermissions.
export interface ProjectViewer {
  role: MemberRole;
  // The caller's standing in the team that owns the project, null when they are not
  // a member of it. An owner or manager governs the project's settings alongside the
  // project's own owner; 'agent' is a bot user reading its own board, which governs
  // nothing.
  teamRole: TeamRole | 'agent' | null;
  // 'workspace' when the caller is not a member of the project and reaches it through
  // their role in the workspace that holds it.
  via: AccessVia;
}

export type AccessVia = 'member' | 'workspace';

// The board scaffold, returned by getProject: everything the work-items UI needs
// except the issues themselves (those come from getBoardIssues).
export interface ProjectScaffold {
  project: Project;
  columns: Column[];
  issueTypes: IssueType[];
  labels: Label[];
  labelGroups: LabelGroup[];
  assignees: Assignee[];
  // Every custom field of the project (all type scopes); consumers filter by
  // issueTypeId locally.
  customFields: CustomField[];
  issueTemplates: IssueTemplate[];
  viewer: ProjectViewer;
  // The caller's resolved permission matrix (owners get every flag).
  permissions: Permissions;
  // Whether this project may have public links. Off, its links are closed.
  sharingEnabled: boolean;
}

// The scaffold composed with its issues and the project's unfinished cycles, as
// the Shell assembles it and passes it down. Downstream reads project.issues off
// this composite. `plannedCycles` is empty while the Cycles section is off and on a
// public share (whose bundle carries no cycle list).
export type ProjectDetail = ProjectScaffold & BoardIssues & { plannedCycles: CycleOption[] };

// The instance upload limits. Readable by any signed-in user, because the upload UI
// states them before a file is picked; only god mode can change them.
export interface ProjectDefaults {
  mcpEnabled: boolean;
}

export const listProjects = () => request<Project[]>('/projects');

export type ProjectSort = 'key' | 'name' | 'created' | 'activity';

export interface ProjectSearchFilters {
  q?: string;
  sort?: ProjectSort;
  workspaceId?: number;
  teamId?: number;
  ids?: number[];
  favorite?: boolean;
  hidden?: boolean;
}

export const searchProjects = (filters: ProjectSearchFilters, params: PageParams) =>
  request<Page<Project>>(
    `/projects/search${pageQuery(params, {
      q: filters.q,
      sort: filters.sort,
      workspaceId: filters.workspaceId?.toString(),
      teamId: filters.teamId?.toString(),
      ids: filters.ids?.join(','),
      favorite: filters.favorite?.toString(),
      hidden: filters.hidden?.toString(),
    })}`,
  );

export type ProjectPreferencePatch = { isFavorite?: boolean; isHidden?: boolean };

export const updateProjectPreferences = (projectKey: string, patch: ProjectPreferencePatch) =>
  request<{ isFavorite: boolean; isHidden: boolean }>(`/projects/${projectKey}/preferences`, {
    method: 'PATCH',
    body: JSON.stringify(patch),
  });

// Update a project's name/description. The key is immutable, so it is not sent.
export const updateProject = (projectKey: string, patch: { name?: string; description?: string }) =>
  request<Project>(`/projects/${projectKey}`, { method: 'PATCH', body: JSON.stringify(patch) });

// The board scaffold (no issues). The issues come from getBoardIssues.
export const getProject = (projectKey: string, signal?: AbortSignal) =>
  request<ProjectScaffold>(`/projects/${encodeURIComponent(projectKey)}`, { signal });

// The board's issues and their relations.
export const getBoardIssues = (projectKey: string) =>
  request<BoardIssues>(`/projects/${projectKey}/issues/board`);