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.

14.8 KB
Raw Blame
// 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));
}