⭐️⭐️⭐️ 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.
TypeScript agenticagileai-agentsbug-reportingbug-trackerganttissue-trackerjirajira-alternativekanbanlinearlinear-alternativeopen-sourceproduct-managementproject-managementroadmapself-hostedsprint-planningteam-collaborationtrello-alternative
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`);