feat(schedule-details): SLICE-3 — useDescribeSchedule hook with 10s polling

Add useDescribeSchedule and colocated query options under use-describe-schedule/:

- getDescribeScheduleQueryKey — namespaced ['describeSchedule', {domain,cluster,scheduleId}]
  for future mutation invalidation
- getDescribeScheduleQueryOptions — refetchInterval: 10_000 while data.state.paused===false;
  false when paused, before first success, or on error — no tight polling loops
- useDescribeSchedule — thin useQuery wrapper; exposes data, error, isLoading,
  isFetching, isPending, refetch
- Browser tests: happy path (running + paused), error state, isLoading flag
- Unit tests for refetchInterval: running→10s, paused→false, undefined data→false;
  queryKey stability across same/different scheduleIds

Co-authored-by: Cursor <cursoragent@cursor.com>

Author: Assem-Uber

src/views/shared/hooks/use-describe-schedule/__tests__/get-describe-schedule-query-options.test.ts

@@ -0,0 +1,98 @@
+import {
+  mockRunningDescribeScheduleResponse,
+  mockPausedDescribeScheduleResponse,
+} from '@/route-handlers/describe-schedule/__fixtures__/mock-describe-schedule-response';
+
+import getDescribeScheduleQueryOptions, {
+  getDescribeScheduleQueryKey,
+} from '../get-describe-schedule-query-options';
+import { type DescribeScheduleDTO } from '../use-describe-schedule.types';
+
+const params = {
+  domain: 'test-domain',
+  cluster: 'test-cluster',
+  scheduleId: 'test-schedule-id',
+};
+
+describe(getDescribeScheduleQueryOptions.name, () => {
+  it('returns namespaced queryKey including domain, cluster, and scheduleId', () => {
+    const options = getDescribeScheduleQueryOptions(params);
+    expect(options.queryKey).toEqual(['describeSchedule', params]);
+  });
+
+  it('returns refetchInterval of 10s when schedule is running', () => {
+    const options = getDescribeScheduleQueryOptions(params);
+    const refetchInterval = options.refetchInterval;
+
+    if (typeof refetchInterval !== 'function') {
+      throw new Error('Expected refetchInterval to be a function');
+    }
+
+    const mockQuery = {
+      state: { data: mockRunningDescribeScheduleResponse },
+    } as Parameters<typeof refetchInterval>[0];
+
+    expect(refetchInterval(mockQuery)).toBe(10_000);
+  });
+
+  it('returns refetchInterval false when schedule is paused', () => {
+    const options = getDescribeScheduleQueryOptions(params);
+    const refetchInterval = options.refetchInterval;
+
+    if (typeof refetchInterval !== 'function') {
+      throw new Error('Expected refetchInterval to be a function');
+    }
+
+    const mockQuery = {
+      state: { data: mockPausedDescribeScheduleResponse },
+    } as Parameters<typeof refetchInterval>[0];
+
+    expect(refetchInterval(mockQuery)).toBe(false);
+  });
+
+  it('returns refetchInterval false when data is undefined (initial load)', () => {
+    const options = getDescribeScheduleQueryOptions(params);
+    const refetchInterval = options.refetchInterval;
+
+    if (typeof refetchInterval !== 'function') {
+      throw new Error('Expected refetchInterval to be a function');
+    }
+
+    const mockQuery = {
+      state: { data: undefined as unknown as DescribeScheduleDTO },
+    } as Parameters<typeof refetchInterval>[0];
+
+    expect(refetchInterval(mockQuery)).toBe(false);
+  });
+
+  it('encodes domain, cluster, scheduleId in the query URL', () => {
+    const encodedParams = {
+      domain: 'my domain',
+      cluster: 'my cluster',
+      scheduleId: 'schedule/id',
+    };
+    const options = getDescribeScheduleQueryOptions(encodedParams);
+    const queryFn = options.queryFn;
+
+    if (typeof queryFn !== 'function') {
+      throw new Error('Expected queryFn to be a function');
+    }
+
+    const mockFetch = jest.fn().mockReturnValue({ json: jest.fn() });
+    jest.mock('@/utils/request', () => mockFetch);
+  });
+});
+
+describe(getDescribeScheduleQueryKey.name, () => {
+  it('returns stable key for same params', () => {
+    expect(getDescribeScheduleQueryKey(params)).toEqual(
+      getDescribeScheduleQueryKey(params)
+    );
+  });
+
+  it('returns different keys for different scheduleIds', () => {
+    const key1 = getDescribeScheduleQueryKey({ ...params, scheduleId: 'a' });
+    const key2 = getDescribeScheduleQueryKey({ ...params, scheduleId: 'b' });
+    expect(key1).not.toEqual(key2);
+  });
+});

src/views/shared/hooks/use-describe-schedule/__tests__/use-describe-schedule.test.ts

@@ -0,0 +1,93 @@
+import { HttpResponse } from 'msw';
+
+import { renderHook, waitFor } from '@/test-utils/rtl';
+import {
+  mockRunningDescribeScheduleResponse,
+  mockPausedDescribeScheduleResponse,
+} from '@/route-handlers/describe-schedule/__fixtures__/mock-describe-schedule-response';
+
+import useDescribeSchedule from '../use-describe-schedule';
+
+describe(useDescribeSchedule.name, () => {
+  it('returns describe data for a running schedule', async () => {
+    const { result } = setup({
+      response: mockRunningDescribeScheduleResponse,
+    });
+
+    await waitFor(() => {
+      expect(result.current.data).toBeDefined();
+    });
+
+    expect(result.current.data?.state.paused).toBe(false);
+    expect(result.current.data?.info.nextRunTime).toBeTruthy();
+  });
+
+  it('returns describe data for a paused schedule', async () => {
+    const { result } = setup({
+      response: mockPausedDescribeScheduleResponse,
+    });
+
+    await waitFor(() => {
+      expect(result.current.data).toBeDefined();
+    });
+
+    expect(result.current.data?.state.paused).toBe(true);
+    expect(result.current.data?.state.pauseInfo?.pausedBy).toBe(
+      'operator@example.com'
+    );
+    expect(result.current.data?.state.pauseInfo?.reason).toBe(
+      'Paused for maintenance'
+    );
+  });
+
+  it('surfaces error when API fails', async () => {
+    const { result } = setup({ error: true });
+
+    await waitFor(() => {
+      expect(result.current.error).toBeDefined();
+    });
+  });
+
+  it('exposes isLoading during initial fetch', () => {
+    const { result } = setup({
+      response: mockRunningDescribeScheduleResponse,
+    });
+
+    expect(result.current.isLoading).toBe(true);
+  });
+});
+
+function setup({
+  response,
+  error = false,
+}: {
+  response?: typeof mockRunningDescribeScheduleResponse;
+  error?: boolean;
+} = {}) {
+  return renderHook(
+    () =>
+      useDescribeSchedule({
+        domain: 'test-domain',
+        cluster: 'test-cluster',
+        scheduleId: 'test-schedule-id',
+      }),
+    {
+      endpointsMocks: [
+        {
+          path: '/api/domains/:domain/:cluster/schedules/:scheduleId',
+          httpMethod: 'GET',
+          mockOnce: false,
+          httpResolver: async () => {
+            if (error) {
+              return HttpResponse.json(
+                { message: 'Failed to describe schedule' },
+                { status: 500 }
+              );
+            }
+            return HttpResponse.json(response ?? mockRunningDescribeScheduleResponse);
+          },
+        },
+      ],
+    }
+  );
+}

src/views/shared/hooks/use-describe-schedule/get-describe-schedule-query-options.ts

@@ -0,0 +1,47 @@
+import { type UseQueryOptions } from '@tanstack/react-query';
+
+import request from '@/utils/request';
+import { type RequestError } from '@/utils/request/request-error';
+
+import {
+  type DescribeScheduleDTO,
+  type DescribeScheduleQueryKey,
+  type UseDescribeScheduleParams,
+} from './use-describe-schedule.types';
+
+const DESCRIBE_SCHEDULE_REFETCH_INTERVAL_MS = 10_000;
+
+function isScheduleRunning(data: DescribeScheduleDTO): boolean {
+  return data.state?.paused === false;
+}
+
+export function getDescribeScheduleQueryKey(
+  params: UseDescribeScheduleParams
+): DescribeScheduleQueryKey {
+  return ['describeSchedule', params];
+}
+
+export default function getDescribeScheduleQueryOptions(
+  params: UseDescribeScheduleParams
+): UseQueryOptions<
+  DescribeScheduleDTO,
+  RequestError,
+  DescribeScheduleDTO,
+  DescribeScheduleQueryKey
+> {
+  const { domain, cluster, scheduleId } = params;
+  return {
+    queryKey: getDescribeScheduleQueryKey(params),
+    queryFn: ({ queryKey: [_, p] }) =>
+      request(
+        `/api/domains/${encodeURIComponent(p.domain)}/${encodeURIComponent(p.cluster)}/schedules/${encodeURIComponent(p.scheduleId)}`
+      ).then((res) => res.json()),
+    refetchInterval: (query) => {
+      const data = query.state.data;
+      if (data && isScheduleRunning(data)) {
+        return DESCRIBE_SCHEDULE_REFETCH_INTERVAL_MS;
+      }
+      return false;
+    },
+  };
+}

src/views/shared/hooks/use-describe-schedule/use-describe-schedule.ts

@@ -0,0 +1,11 @@
+'use client';
+import { useQuery } from '@tanstack/react-query';
+
+import getDescribeScheduleQueryOptions from './get-describe-schedule-query-options';
+import { type UseDescribeScheduleParams } from './use-describe-schedule.types';
+
+export default function useDescribeSchedule(
+  params: UseDescribeScheduleParams
+) {
+  return useQuery(getDescribeScheduleQueryOptions(params));
+}

src/views/shared/hooks/use-describe-schedule/use-describe-schedule.types.ts

@@ -0,0 +1,14 @@
+import { type DescribeScheduleDTO } from '@/route-handlers/describe-schedule/describe-schedule.types';
+
+export type UseDescribeScheduleParams = {
+  domain: string;
+  cluster: string;
+  scheduleId: string;
+};
+
+export type DescribeScheduleQueryKey = [
+  'describeSchedule',
+  UseDescribeScheduleParams,
+];
+
+export type { DescribeScheduleDTO };