⭐️⭐️⭐️ 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
// React Query hooks for everything the settings feature reads and writes: the
// project's structural entities (columns, issue types, labels and label groups,
// custom fields, issue templates), the workflow configuration, and the session
// member's own notification preferences. Structural writes go through
// useProjectMutation and invalidate the project detail; the settings and
// notification writes return the stored result and put it straight into the cache.
// This module wraps the low-level fetch client (api.ts).
import { useInfiniteQuery, useMutation, useQuery, useQueryClient } from '@tanstack/react-query';
import {
type AutoArchiveSettings,
type EstimateSettings,
type ProjectFeatures,
type SubtaskAutomationSettings,
getAutoArchive,
updateAutoArchive,
getSubtaskAutomation,
updateSubtaskAutomation,
updateEstimates,
updateProjectSettings,
} from '@/lib/api/endpoints/settings';
import {
createColumn,
updateColumn,
reorderColumns,
deleteColumn,
} from '@/lib/api/endpoints/columns';
import {
createCustomField,
updateCustomField,
deleteCustomField,
} from '@/lib/api/endpoints/customFields';
import {
getGitSettings,
updateGitSettings,
regenerateGitSecret,
listGitProviderConnections,
listAvailableGitRepositories,
connectGitRepositories,
disconnectGitRepository,
} from '@/lib/api/endpoints/git';
import {
type CreateImportJobInput,
type LinearConnectionInput,
type PlaneConnectionInput,
testLinearConnection,
testLinearStatesPreview,
type TrelloConnectionInput,
testTrelloConnection,
previewTrelloBoard,
testPlaneConnection,
testPlaneStatesPreview,
createImportJob,
listImportJobs,
pauseImportJob,
resumeImportJob,
cancelImportJob,
} from '@/lib/api/endpoints/importExport';
import {
createIssueTemplate,
updateIssueTemplate,
deleteIssueTemplate,
} from '@/lib/api/endpoints/issueTemplates';
import { createIssueType, updateIssueType, deleteIssueType } from '@/lib/api/endpoints/issueTypes';
import {
createLabel,
updateLabel,
deleteLabel,
createLabelGroup,
updateLabelGroup,
deleteLabelGroup,
} from '@/lib/api/endpoints/labels';
import {
type NotificationPreferences,
getNotificationPreferences,
setNotificationPreferences,
} from '@/lib/api/endpoints/notificationPreferences';
import { useInvalidateProject } from '@/services/projects.service';
import { qk } from '@/services/queryKeys';
// A mutation whose success invalidates the project detail (and dependent lists).
// Shared by every settings write below.
function useProjectMutation<TArgs>(
projectKey: string,
mutationFn: (args: TArgs) => Promise<unknown>,
) {
const invalidate = useInvalidateProject(projectKey);
return useMutation({ mutationFn, onSuccess: () => invalidate() });
}
export function useCreateColumn(projectKey: string) {
return useProjectMutation(projectKey, (input: Parameters<typeof createColumn>[1]) =>
createColumn(projectKey, input),
);
}
export function useUpdateColumn(projectKey: string) {
return useProjectMutation(
projectKey,
({ id, patch }: { id: number; patch: Parameters<typeof updateColumn>[2] }) =>
updateColumn(projectKey, id, patch),
);
}
export function useReorderColumns(projectKey: string) {
return useProjectMutation(projectKey, (orderedIds: number[]) =>
reorderColumns(projectKey, orderedIds),
);
}
export function useDeleteColumn(projectKey: string) {
return useProjectMutation(
projectKey,
({ id, body }: { id: number; body: Parameters<typeof deleteColumn>[2] }) =>
deleteColumn(projectKey, id, body),
);
}
export function useCreateIssueType(projectKey: string) {
return useProjectMutation(projectKey, (input: Parameters<typeof createIssueType>[1]) =>
createIssueType(projectKey, input),
);
}
export function useUpdateIssueType(projectKey: string) {
return useProjectMutation(
projectKey,
({ id, patch }: { id: number; patch: Parameters<typeof updateIssueType>[2] }) =>
updateIssueType(projectKey, id, patch),
);
}
export function useDeleteIssueType(projectKey: string) {
return useProjectMutation(projectKey, (id: number) => deleteIssueType(projectKey, id));
}
export function useCreateLabel(projectKey: string) {
return useProjectMutation(projectKey, (input: Parameters<typeof createLabel>[1]) =>
createLabel(projectKey, input),
);
}
export function useUpdateLabel(projectKey: string) {
return useProjectMutation(
projectKey,
({ id, patch }: { id: number; patch: Parameters<typeof updateLabel>[2] }) =>
updateLabel(projectKey, id, patch),
);
}
export function useDeleteLabel(projectKey: string) {
return useProjectMutation(projectKey, (id: number) => deleteLabel(projectKey, id));
}
export function useCreateLabelGroup(projectKey: string) {
return useProjectMutation(projectKey, (input: Parameters<typeof createLabelGroup>[1]) =>
createLabelGroup(projectKey, input),
);
}
export function useUpdateLabelGroup(projectKey: string) {
return useProjectMutation(
projectKey,
({ id, patch }: { id: number; patch: Parameters<typeof updateLabelGroup>[2] }) =>
updateLabelGroup(projectKey, id, patch),
);
}
export function useDeleteLabelGroup(projectKey: string) {
return useProjectMutation(projectKey, (id: number) => deleteLabelGroup(projectKey, id));
}
// Configuration section: the project's auto-archive thresholds and subtask
// automations.
export function useAutoArchiveQuery(projectKey: string) {
return useQuery({
queryKey: qk.autoArchive(projectKey),
queryFn: () => getAutoArchive(projectKey),
});
}
export function useUpdateAutoArchive(projectKey: string) {
const qc = useQueryClient();
return useMutation({
mutationFn: (input: AutoArchiveSettings) => updateAutoArchive(projectKey, input),
onSuccess: (data) => qc.setQueryData(qk.autoArchive(projectKey), data),
});
}
export function useSubtaskAutomationQuery(projectKey: string) {
return useQuery({
queryKey: qk.subtaskAutomation(projectKey),
queryFn: () => getSubtaskAutomation(projectKey),
});
}
export function useUpdateSubtaskAutomation(projectKey: string) {
const qc = useQueryClient();
return useMutation({
mutationFn: (input: SubtaskAutomationSettings) => updateSubtaskAutomation(projectKey, input),
onSuccess: (data) => qc.setQueryData(qk.subtaskAutomation(projectKey), data),
});
}
// The estimate kinds live on the project row, so the write invalidates the project
// detail the whole app reads them from rather than caching a payload of its own.
export function useUpdateEstimates(projectKey: string) {
return useProjectMutation(projectKey, (input: EstimateSettings) =>
updateEstimates(projectKey, input),
);
}
// Repository section: the inbound webhook connection and its pull request automations.
export function useGitSettingsQuery(projectKey: string) {
return useQuery({
queryKey: qk.gitSettings(projectKey),
queryFn: () => getGitSettings(projectKey),
});
}
export function useUpdateGitSettings(projectKey: string) {
const qc = useQueryClient();
return useMutation({
mutationFn: (patch: Parameters<typeof updateGitSettings>[1]) =>
updateGitSettings(projectKey, patch),
onSuccess: (data) => qc.setQueryData(qk.gitSettings(projectKey), data),
});
}
export function useRegenerateGitSecret(projectKey: string) {
const qc = useQueryClient();
return useMutation({
mutationFn: () => regenerateGitSecret(projectKey),
onSuccess: (data) => qc.setQueryData(qk.gitSettings(projectKey), data),
onSettled: () => qc.invalidateQueries({ queryKey: qk.gitConnections(projectKey) }),
});
}
export function useGitProviderConnectionsQuery(projectKey: string) {
return useQuery({
queryKey: qk.gitConnections(projectKey),
queryFn: () => listGitProviderConnections(projectKey),
});
}
export function useAvailableGitRepositoriesQuery(
projectKey: string,
connectionId: number,
search: string,
enabled: boolean,
) {
return useInfiniteQuery({
queryKey: qk.gitAvailableRepositories(projectKey, connectionId, search),
queryFn: ({ pageParam }) =>
listAvailableGitRepositories(projectKey, connectionId, { search, page: pageParam }),
initialPageParam: 1,
getNextPageParam: (page) => page.nextPage ?? undefined,
enabled,
});
}
export function useConnectGitRepositories(projectKey: string, connectionId: number) {
const qc = useQueryClient();
return useMutation({
mutationFn: (externalIds: string[]) =>
connectGitRepositories(projectKey, connectionId, externalIds),
onSettled: () => qc.invalidateQueries({ queryKey: qk.gitConnections(projectKey) }),
});
}
export function useDisconnectGitRepository(projectKey: string, connectionId: number) {
const qc = useQueryClient();
return useMutation({
mutationFn: (repositoryId: number) =>
disconnectGitRepository(projectKey, connectionId, repositoryId),
onSuccess: () => qc.invalidateQueries({ queryKey: qk.gitConnections(projectKey) }),
});
}
// Import/export section: testing a connection to a source Plane instance, a Linear
// API key or a Trello key and token, starting an import job, and tracking the ones
// already running.
export function useTestPlaneConnection(projectKey: string) {
return useMutation({
mutationFn: (input: PlaneConnectionInput) => testPlaneConnection(projectKey, input),
});
}
// Fetched automatically once a source project is picked, in the mapping review step.
export function useTestPlaneStatesPreview(
projectKey: string,
input: (PlaneConnectionInput & { planeProjectId: string }) | null,
) {
return useQuery({
queryKey: input
? qk.planePreview(projectKey, input.planeProjectId)
: qk.planePreview(projectKey, 'none'),
queryFn: () => testPlaneStatesPreview(projectKey, input!),
enabled: input != null,
});
}
export function useTestLinearConnection(projectKey: string) {
return useMutation({
mutationFn: (input: LinearConnectionInput) => testLinearConnection(projectKey, input),
});
}
// Fetched automatically once a Linear team is picked, in the mapping review step.
export function useTestLinearStatesPreview(
projectKey: string,
input: (LinearConnectionInput & { teamId: string }) | null,
) {
return useQuery({
queryKey: qk.linearPreview(projectKey, input?.teamId ?? 'none'),
queryFn: () => testLinearStatesPreview(projectKey, input!),
enabled: input != null,
});
}
export function useTestTrelloConnection(projectKey: string) {
return useMutation({
mutationFn: (input: TrelloConnectionInput) => testTrelloConnection(projectKey, input),
});
}
// Fetched automatically once a Trello board is picked, in the mapping review step.
export function useTrelloBoardPreview(
projectKey: string,
input: (TrelloConnectionInput & { boardId: string }) | null,
) {
return useQuery({
queryKey: qk.trelloPreview(projectKey, input?.boardId ?? 'none'),
queryFn: () => previewTrelloBoard(projectKey, input!),
enabled: input != null,
});
}
export function useCreateImportJob(projectKey: string) {
const qc = useQueryClient();
return useMutation({
mutationFn: (input: CreateImportJobInput) => createImportJob(projectKey, input),
onSuccess: () => qc.invalidateQueries({ queryKey: qk.importJobs(projectKey) }),
});
}
// Polled while a job is still pending or running, the same shape as
// useAgentScheduleRuns.
export function useImportJobsQuery(projectKey: string) {
return useQuery({
queryKey: qk.importJobs(projectKey),
queryFn: () => listImportJobs(projectKey),
refetchInterval: (query) =>
query.state.data?.some((job) => job.status === 'running' || job.status === 'pending')
? 2000
: false,
});
}
export function usePauseImportJob(projectKey: string) {
const qc = useQueryClient();
return useMutation({
mutationFn: (id: number) => pauseImportJob(id),
onSuccess: () => qc.invalidateQueries({ queryKey: qk.importJobs(projectKey) }),
});
}
export function useResumeImportJob(projectKey: string) {
const qc = useQueryClient();
return useMutation({
mutationFn: (id: number) => resumeImportJob(id),
onSuccess: () => qc.invalidateQueries({ queryKey: qk.importJobs(projectKey) }),
});
}
export function useCancelImportJob(projectKey: string) {
const qc = useQueryClient();
return useMutation({
mutationFn: (id: number) => cancelImportJob(id),
onSuccess: () => qc.invalidateQueries({ queryKey: qk.importJobs(projectKey) }),
});
}
// General section: which optional sections the project shows. The current state
// comes with the project payload (getProject), so a write only invalidates it —
// the navigation and the sections themselves read it from there.
export function useUpdateProjectFeatures(projectKey: string) {
const invalidate = useInvalidateProject(projectKey);
return useMutation({
mutationFn: (input: Partial<ProjectFeatures>) =>
updateProjectSettings(projectKey, { features: input }),
onSuccess: () => invalidate(),
});
}
// The session member's own notification preferences for a project. A write returns
// the normalized result, which replaces the cache directly.
export function useNotificationPreferencesQuery(projectKey: string) {
return useQuery({
queryKey: qk.notificationPreferences(projectKey),
queryFn: () => getNotificationPreferences(projectKey),
});
}
export function useUpdateNotificationPreferences(projectKey: string) {
const qc = useQueryClient();
return useMutation({
mutationFn: (input: NotificationPreferences) => setNotificationPreferences(projectKey, input),
onSuccess: (data) => qc.setQueryData(qk.notificationPreferences(projectKey), data),
});
}
// Custom fields. Writes go through the project-scoped endpoint; the shared
// invalidation also refreshes the custom-field lists the reads depend on.
export function useCreateCustomField(projectKey: string) {
return useProjectMutation(projectKey, (input: Parameters<typeof createCustomField>[1]) =>
createCustomField(projectKey, input),
);
}
export function useUpdateCustomField(projectKey: string) {
return useProjectMutation(
projectKey,
({ id, patch }: { id: number; patch: Parameters<typeof updateCustomField>[2] }) =>
updateCustomField(projectKey, id, patch),
);
}
export function useDeleteCustomField(projectKey: string) {
return useProjectMutation(projectKey, (id: number) => deleteCustomField(projectKey, id));
}
// Issue templates. The project detail carries the list, so the writes only have to
// invalidate it.
export function useCreateIssueTemplate(projectKey: string) {
return useProjectMutation(projectKey, (input: Parameters<typeof createIssueTemplate>[1]) =>
createIssueTemplate(projectKey, input),
);
}
export function useUpdateIssueTemplate(projectKey: string) {
return useProjectMutation(
projectKey,
({ id, patch }: { id: number; patch: Parameters<typeof updateIssueTemplate>[2] }) =>
updateIssueTemplate(projectKey, id, patch),
);
}
export function useDeleteIssueTemplate(projectKey: string) {
return useProjectMutation(projectKey, (id: number) => deleteIssueTemplate(projectKey, id));
}