@shipfox/client-triggers 0.2.0

package/src/hooks/api/trigger-events.test.ts

@@ -0,0 +1,252 @@
+import {configureApiClient} from '@shipfox/client-api';
+import {
+  getTriggerEvent,
+  getTriggerEventFacets,
+  listTriggerEvents,
+  triggerEventsQueryKeys,
+} from './trigger-events.js';
+
+function jsonResponse(body: unknown, init: ResponseInit = {}): Response {
+  return new Response(JSON.stringify(body), {
+    headers: {'content-type': 'application/json'},
+    status: 200,
+    ...init,
+  });
+}
+
+function requestFrom(fetchImpl: ReturnType<typeof vi.fn>): Request {
+  return fetchImpl.mock.calls[0]?.[0] as Request;
+}
+
+describe('triggerEventsQueryKeys', () => {
+  test('list key nests under the workspace lists key', () => {
+    const workspaceId = '11111111-1111-4111-8111-111111111111';
+
+    const key = triggerEventsQueryKeys.list(workspaceId, {});
+
+    expect(key).toEqual([
+      'trigger-events',
+      'list',
+      workspaceId,
+      50,
+      {source: null, event: null, outcome: null, from: null, to: null},
+    ]);
+    expect(key.slice(0, 3)).toEqual(triggerEventsQueryKeys.lists(workspaceId));
+  });
+
+  test('keeps distinct page limits on distinct keys', () => {
+    const workspaceId = '11111111-1111-4111-8111-111111111111';
+
+    const defaultLimit = triggerEventsQueryKeys.list(workspaceId, {});
+    const compactLimit = triggerEventsQueryKeys.list(workspaceId, {}, 25);
+
+    expect(defaultLimit).not.toEqual(compactLimit);
+    expect(defaultLimit[3]).toBe(50);
+    expect(compactLimit[3]).toBe(25);
+  });
+
+  test('normalizes absent filter fields to null so empty variants share a key', () => {
+    const workspaceId = '11111111-1111-4111-8111-111111111111';
+
+    const empty = triggerEventsQueryKeys.list(workspaceId, {});
+    const allUndefined = triggerEventsQueryKeys.list(workspaceId, {
+      source: undefined,
+      event: undefined,
+      outcome: undefined,
+      from: undefined,
+      to: undefined,
+    });
+
+    expect(allUndefined).toEqual(empty);
+  });
+
+  test('treats an empty outcome array as no outcome filter', () => {
+    const workspaceId = '11111111-1111-4111-8111-111111111111';
+
+    const key = triggerEventsQueryKeys.list(workspaceId, {outcome: []});
+
+    expect(key[4]).toMatchObject({outcome: null});
+  });
+
+  test('treats empty source and event arrays as no filter', () => {
+    const workspaceId = '11111111-1111-4111-8111-111111111111';
+
+    const key = triggerEventsQueryKeys.list(workspaceId, {source: [], event: []});
+
+    expect(key[4]).toMatchObject({source: null, event: null});
+  });
+
+  test('sorts and de-duplicates outcome so filter order does not split the cache', () => {
+    const workspaceId = '11111111-1111-4111-8111-111111111111';
+
+    const a = triggerEventsQueryKeys.list(workspaceId, {outcome: ['routed', 'failed']});
+    const b = triggerEventsQueryKeys.list(workspaceId, {outcome: ['failed', 'routed', 'failed']});
+
+    expect(a).toEqual(b);
+    expect(a[4]).toMatchObject({outcome: ['failed', 'routed']});
+  });
+
+  test('sorts and de-duplicates source and event filters so order does not split the cache', () => {
+    const workspaceId = '11111111-1111-4111-8111-111111111111';
+
+    const a = triggerEventsQueryKeys.list(workspaceId, {
+      source: ['github', 'gitea'],
+      event: ['push', 'pull_request'],
+    });
+    const b = triggerEventsQueryKeys.list(workspaceId, {
+      source: ['gitea', 'github', 'gitea'],
+      event: ['pull_request', 'push', 'push'],
+    });
+
+    expect(a).toEqual(b);
+    expect(a[4]).toMatchObject({
+      source: ['gitea', 'github'],
+      event: ['pull_request', 'push'],
+    });
+  });
+
+  test('keeps distinct filters on distinct keys', () => {
+    const workspaceId = '11111111-1111-4111-8111-111111111111';
+
+    const push = triggerEventsQueryKeys.list(workspaceId, {event: ['push']});
+    const pr = triggerEventsQueryKeys.list(workspaceId, {event: ['pull_request']});
+
+    expect(push).not.toEqual(pr);
+  });
+
+  test('detail key carries the event id', () => {
+    const id = '22222222-2222-4222-8222-222222222222';
+
+    expect(triggerEventsQueryKeys.detail(id)).toEqual(['trigger-events', 'detail', id]);
+  });
+
+  test('facets key carries the workspace id', () => {
+    const workspaceId = '11111111-1111-4111-8111-111111111111';
+
+    expect(triggerEventsQueryKeys.facets(workspaceId)).toEqual([
+      'trigger-events',
+      'facets',
+      workspaceId,
+    ]);
+  });
+});
+
+describe('listTriggerEvents', () => {
+  const workspaceId = '11111111-1111-4111-8111-111111111111';
+
+  beforeEach(() => {
+    configureApiClient({baseUrl: 'https://api.example.test', fetchImpl: undefined});
+  });
+
+  test('sends workspace_id and the default limit with no filters', async () => {
+    const fetchImpl = vi.fn(async () => jsonResponse({trigger_events: [], next_cursor: null}));
+    configureApiClient({fetchImpl});
+
+    await listTriggerEvents({workspaceId});
+
+    const url = new URL(requestFrom(fetchImpl).url);
+    expect(url.pathname).toBe('/trigger-events');
+    expect(url.searchParams.get('workspace_id')).toBe(workspaceId);
+    expect(url.searchParams.get('limit')).toBe('50');
+    expect(url.searchParams.has('cursor')).toBe(false);
+    expect(url.searchParams.has('outcome')).toBe(false);
+  });
+
+  test('serializes every filter, the cursor, and a custom limit', async () => {
+    const fetchImpl = vi.fn(async () => jsonResponse({trigger_events: [], next_cursor: null}));
+    configureApiClient({fetchImpl});
+
+    await listTriggerEvents({
+      workspaceId,
+      limit: 25,
+      cursor: 'cursor-abc',
+      filters: {
+        source: ['github', 'gitea'],
+        event: ['push', 'pull_request'],
+        outcome: ['routed', 'failed'],
+        from: '2026-06-01T00:00:00.000Z',
+        to: '2026-06-22T00:00:00.000Z',
+      },
+    });
+
+    const url = new URL(requestFrom(fetchImpl).url);
+    expect(url.searchParams.get('limit')).toBe('25');
+    expect(url.searchParams.get('cursor')).toBe('cursor-abc');
+    expect(url.searchParams.get('source')).toBe('gitea,github');
+    expect(url.searchParams.get('event')).toBe('pull_request,push');
+    expect(url.searchParams.get('from')).toBe('2026-06-01T00:00:00.000Z');
+    expect(url.searchParams.get('to')).toBe('2026-06-22T00:00:00.000Z');
+    expect(url.searchParams.get('outcome')).toBe('failed,routed');
+  });
+
+  test('omits list params when the filter arrays are empty', async () => {
+    const fetchImpl = vi.fn(async () => jsonResponse({trigger_events: [], next_cursor: null}));
+    configureApiClient({fetchImpl});
+
+    await listTriggerEvents({workspaceId, filters: {source: [], event: [], outcome: []}});
+
+    const url = new URL(requestFrom(fetchImpl).url);
+    expect(url.searchParams.has('source')).toBe(false);
+    expect(url.searchParams.has('event')).toBe(false);
+    expect(url.searchParams.has('outcome')).toBe(false);
+  });
+
+  test('sorts and de-duplicates the serialized outcome param', async () => {
+    const fetchImpl = vi.fn(async () => jsonResponse({trigger_events: [], next_cursor: null}));
+    configureApiClient({fetchImpl});
+
+    await listTriggerEvents({workspaceId, filters: {outcome: ['routed', 'failed', 'routed']}});
+
+    const url = new URL(requestFrom(fetchImpl).url);
+    expect(url.searchParams.get('outcome')).toBe('failed,routed');
+  });
+
+  test('returns the parsed list response', async () => {
+    const page = {
+      trigger_events: [],
+      next_cursor: 'next-page',
+    };
+    configureApiClient({fetchImpl: vi.fn(async () => jsonResponse(page))});
+
+    const result = await listTriggerEvents({workspaceId});
+
+    expect(result).toEqual(page);
+  });
+});
+
+describe('getTriggerEvent', () => {
+  beforeEach(() => {
+    configureApiClient({baseUrl: 'https://api.example.test', fetchImpl: undefined});
+  });
+
+  test('requests the event detail by id', async () => {
+    const id = '22222222-2222-4222-8222-222222222222';
+    const fetchImpl = vi.fn(async () => jsonResponse({id, decisions: []}));
+    configureApiClient({fetchImpl});
+
+    await getTriggerEvent({id});
+
+    const url = new URL(requestFrom(fetchImpl).url);
+    expect(url.pathname).toBe(`/trigger-events/${id}`);
+    expect(requestFrom(fetchImpl).method).toBe('GET');
+  });
+});
+
+describe('getTriggerEventFacets', () => {
+  beforeEach(() => {
+    configureApiClient({baseUrl: 'https://api.example.test', fetchImpl: undefined});
+  });
+
+  test('requests the workspace facets', async () => {
+    const workspaceId = '11111111-1111-4111-8111-111111111111';
+    const fetchImpl = vi.fn(async () => jsonResponse({sources: [], events: []}));
+    configureApiClient({fetchImpl});
+
+    await getTriggerEventFacets({workspaceId});
+
+    const url = new URL(requestFrom(fetchImpl).url);
+    expect(url.pathname).toBe('/trigger-events/facets');
+    expect(url.searchParams.get('workspace_id')).toBe(workspaceId);
+    expect(requestFrom(fetchImpl).method).toBe('GET');
+  });
+});

package/src/hooks/api/trigger-events.ts

@@ -0,0 +1,143 @@
+import type {
+  TriggerEventDetailResponseDto,
+  TriggerEventFacetsResponseDto,
+  TriggerEventListResponseDto,
+  TriggerEventOutcomeDto,
+} from '@shipfox/api-triggers-dto';
+import {apiRequest} from '@shipfox/client-api';
+import {keepPreviousData, useInfiniteQuery, useQuery} from '@tanstack/react-query';
+
+export interface TriggerEventFilters {
+  source?: string[] | undefined;
+  event?: string[] | undefined;
+  outcome?: TriggerEventOutcomeDto[] | undefined;
+  from?: string | undefined;
+  to?: string | undefined;
+}
+
+function normalizeStringFilter(values: readonly string[] | undefined) {
+  return values && values.length > 0 ? [...new Set(values)].sort() : null;
+}
+
+function normalizeTriggerEventFiltersForQueryKey(filters: TriggerEventFilters) {
+  return {
+    source: normalizeStringFilter(filters.source),
+    event: normalizeStringFilter(filters.event),
+    outcome: normalizeStringFilter(filters.outcome),
+    from: filters.from ?? null,
+    to: filters.to ?? null,
+  };
+}
+
+function setListParam(
+  params: URLSearchParams,
+  name: string,
+  values: readonly string[] | undefined,
+) {
+  const normalized = normalizeStringFilter(values);
+  if (normalized) params.set(name, normalized.join(','));
+}
+
+export const triggerEventsQueryKeys = {
+  all: ['trigger-events'] as const,
+  lists: (workspaceId: string) => [...triggerEventsQueryKeys.all, 'list', workspaceId] as const,
+  list: (workspaceId: string, filters: TriggerEventFilters, limit = 50) =>
+    [
+      ...triggerEventsQueryKeys.lists(workspaceId),
+      limit,
+      normalizeTriggerEventFiltersForQueryKey(filters),
+    ] as const,
+  detail: (id: string) => [...triggerEventsQueryKeys.all, 'detail', id] as const,
+  facets: (workspaceId: string) => [...triggerEventsQueryKeys.all, 'facets', workspaceId] as const,
+};
+
+export async function listTriggerEvents({
+  workspaceId,
+  filters = {},
+  limit = 50,
+  cursor,
+  signal,
+}: {
+  workspaceId: string;
+  filters?: TriggerEventFilters;
+  limit?: number;
+  cursor?: string | undefined;
+  signal?: AbortSignal;
+}) {
+  const params = new URLSearchParams({workspace_id: workspaceId, limit: String(limit)});
+  if (cursor) params.set('cursor', cursor);
+  setListParam(params, 'source', filters.source);
+  setListParam(params, 'event', filters.event);
+  if (filters.from) params.set('from', filters.from);
+  if (filters.to) params.set('to', filters.to);
+  setListParam(params, 'outcome', filters.outcome);
+
+  return await apiRequest<TriggerEventListResponseDto>(`/trigger-events?${params.toString()}`, {
+    signal,
+  });
+}
+
+export async function getTriggerEvent({id, signal}: {id: string; signal?: AbortSignal}) {
+  return await apiRequest<TriggerEventDetailResponseDto>(
+    `/trigger-events/${encodeURIComponent(id)}`,
+    {signal},
+  );
+}
+
+export function useTriggerEventsInfiniteQuery(
+  workspaceId: string | undefined,
+  filters: TriggerEventFilters = {},
+  limit = 50,
+) {
+  return useInfiniteQuery({
+    queryKey: workspaceId
+      ? triggerEventsQueryKeys.list(workspaceId, filters, limit)
+      : [...triggerEventsQueryKeys.all, 'list'],
+    enabled: Boolean(workspaceId),
+    initialPageParam: undefined as string | undefined,
+    queryFn: ({pageParam, signal}) =>
+      listTriggerEvents({
+        workspaceId: workspaceId ?? '',
+        filters,
+        limit,
+        cursor: pageParam,
+        signal,
+      }),
+    getNextPageParam: (lastPage) => lastPage.next_cursor ?? undefined,
+    placeholderData: keepPreviousData,
+  });
+}
+
+export function useTriggerEventQuery(id: string | undefined) {
+  return useQuery({
+    queryKey: id ? triggerEventsQueryKeys.detail(id) : [...triggerEventsQueryKeys.all, 'detail'],
+    enabled: Boolean(id),
+    queryFn: ({signal}) => getTriggerEvent({id: id ?? '', signal}),
+  });
+}
+
+export async function getTriggerEventFacets({
+  workspaceId,
+  signal,
+}: {
+  workspaceId: string;
+  signal?: AbortSignal;
+}) {
+  const params = new URLSearchParams({workspace_id: workspaceId});
+  return await apiRequest<TriggerEventFacetsResponseDto>(
+    `/trigger-events/facets?${params.toString()}`,
+    {signal},
+  );
+}
+
+export function useTriggerEventFacetsQuery(workspaceId: string | undefined) {
+  return useQuery({
+    queryKey: workspaceId
+      ? triggerEventsQueryKeys.facets(workspaceId)
+      : [...triggerEventsQueryKeys.all, 'facets'],
+    enabled: Boolean(workspaceId),
+    queryFn: ({signal}) => getTriggerEventFacets({workspaceId: workspaceId ?? '', signal}),
+    // Distinct values change slowly; avoid refetching on every page mount.
+    staleTime: 5 * 60 * 1000,
+  });
+}

package/src/index.ts

@@ -0,0 +1,4 @@
+export * from './components/trigger-source-icon.js';
+export * from './hooks/api/trigger-events.js';
+export * from './pages/events-page.js';
+export * from './search.js';

package/src/pages/events-page.test.tsx

@@ -0,0 +1,100 @@
+import type {
+  TriggerEventDetailResponseDto,
+  TriggerEventListItemDto,
+  TriggerEventListResponseDto,
+} from '@shipfox/api-triggers-dto';
+import {fireEvent, render, screen, waitFor} from '@testing-library/react';
+import {
+  useTriggerEventFacetsQuery,
+  useTriggerEventQuery,
+  useTriggerEventsInfiniteQuery,
+} from '#hooks/api/trigger-events.js';
+import {EventsPage} from './events-page.js';
+
+const WORKSPACE_ID = '11111111-1111-4111-8111-111111111111';
+const EVENT_ID = '22222222-2222-4222-8222-222222222222';
+
+const useTriggerEventsInfiniteQueryMock = vi.mocked(useTriggerEventsInfiniteQuery);
+const useTriggerEventFacetsQueryMock = vi.mocked(useTriggerEventFacetsQuery);
+const useTriggerEventQueryMock = vi.mocked(useTriggerEventQuery);
+
+function makeEvent(overrides: Partial<TriggerEventListItemDto> = {}): TriggerEventListItemDto {
+  return {
+    id: EVENT_ID,
+    event_ref: 'github:delivery-179:push',
+    origin: 'integration',
+    workspace_id: WORKSPACE_ID,
+    provider: 'github',
+    source: 'github',
+    event: 'push',
+    delivery_id: 'delivery-179',
+    connection_id: '33333333-3333-4333-8333-333333333333',
+    outcome: 'routed',
+    matched_count: 1,
+    received_at: '2026-06-25T19:30:00.000Z',
+    processed_at: '2026-06-25T19:30:02.000Z',
+    created_at: '2026-06-25T19:30:00.000Z',
+    ...overrides,
+  };
+}
+
+function makeDetail(overrides: Partial<TriggerEventDetailResponseDto> = {}) {
+  return {
+    ...makeEvent(),
+    connection_name: 'ShipfoxHQ Production',
+    payload: {ref: 'refs/heads/main'},
+    decisions: [],
+    ...overrides,
+  };
+}
+
+function makeListQuery(triggerEvents: TriggerEventListItemDto[]) {
+  const page: TriggerEventListResponseDto = {
+    trigger_events: triggerEvents,
+    next_cursor: null,
+  };
+
+  return {
+    data: {pages: [page], pageParams: [undefined]},
+    isPending: false,
+    isError: false,
+    isFetching: false,
+    error: null,
+    refetch: vi.fn(),
+    hasNextPage: false,
+    isFetchingNextPage: false,
+    fetchNextPage: vi.fn(),
+  } as unknown as ReturnType<typeof useTriggerEventsInfiniteQuery>;
+}
+
+describe('EventsPage', () => {
+  beforeEach(() => {
+    useTriggerEventFacetsQueryMock.mockReturnValue({
+      data: {sources: [{value: 'github', count: 1}], events: [{value: 'push', count: 1}]},
+    } as ReturnType<typeof useTriggerEventFacetsQuery>);
+    useTriggerEventQueryMock.mockImplementation(
+      (eventId) =>
+        ({
+          data: eventId ? makeDetail({id: eventId}) : undefined,
+          isError: false,
+          refetch: vi.fn(),
+        }) as unknown as ReturnType<typeof useTriggerEventQuery>,
+    );
+  });
+
+  test('clears the selected detail when a settled refresh no longer includes the event', async () => {
+    useTriggerEventsInfiniteQueryMock.mockReturnValue(makeListQuery([makeEvent()]));
+    const {rerender} = render(
+      <EventsPage workspaceId={WORKSPACE_ID} filters={{}} onFiltersChange={vi.fn()} />,
+    );
+    fireEvent.click(await screen.findByRole('button', {name: 'Open details for github · push'}));
+    expect(screen.getByRole('button', {name: 'Back to events'})).toBeInTheDocument();
+
+    useTriggerEventsInfiniteQueryMock.mockReturnValue(makeListQuery([]));
+    rerender(<EventsPage workspaceId={WORKSPACE_ID} filters={{}} onFiltersChange={vi.fn()} />);
+
+    await waitFor(() => {
+      expect(screen.queryByRole('button', {name: 'Back to events'})).not.toBeInTheDocument();
+    });
+  });
+});

package/src/pages/events-page.tsx

@@ -0,0 +1,79 @@
+import type {TriggerEventListItemDto} from '@shipfox/api-triggers-dto';
+import {RelativeTimeProvider} from '@shipfox/react-ui/relative-time';
+import {Header, Text} from '@shipfox/react-ui/typography';
+import {cn} from '@shipfox/react-ui/utils';
+import {useEffect, useMemo, useState} from 'react';
+import {EventsList} from '#components/events-list.js';
+import {TriggerEventDetail} from '#components/trigger-event-detail.js';
+import {
+  type TriggerEventFilters,
+  useTriggerEventFacetsQuery,
+  useTriggerEventsInfiniteQuery,
+} from '#hooks/api/trigger-events.js';
+
+export interface EventsPageProps {
+  workspaceId: string;
+  filters: TriggerEventFilters;
+  onFiltersChange: (patch: Partial<TriggerEventFilters>) => void;
+}
+
+/**
+ * Workspace-scoped Events list. Router-agnostic: filters and their setter come in as props
+ * (the settings wrapper binds them to the URL), so a story can drive it with local state.
+ */
+export function EventsPage({workspaceId, filters, onFiltersChange}: EventsPageProps) {
+  const query = useTriggerEventsInfiniteQuery(workspaceId, filters);
+  const facetsQuery = useTriggerEventFacetsQuery(workspaceId);
+  const [selectedEventId, setSelectedEventId] = useState<string | undefined>();
+
+  const events = useMemo<TriggerEventListItemDto[]>(
+    () => query.data?.pages.flatMap((page) => page.trigger_events) ?? [],
+    [query.data],
+  );
+
+  useEffect(() => {
+    if (!selectedEventId || query.isPending || query.isFetching || query.isError) return;
+    if (!events.some((event) => event.id === selectedEventId)) setSelectedEventId(undefined);
+  }, [events, query.isError, query.isFetching, query.isPending, selectedEventId]);
+
+  return (
+    <RelativeTimeProvider>
+      <section className="flex min-w-0 flex-col gap-16" aria-labelledby="trigger-events-heading">
+        <div className="flex flex-col gap-4">
+          <Header id="trigger-events-heading" variant="h3">
+            Events
+          </Header>
+          <Text size="sm" className="text-foreground-neutral-muted">
+            A workspace-wide audit log of trigger events received from integrations, schedules, and
+            manual trigger calls.
+          </Text>
+        </div>
+
+        <div className="grid min-h-0 gap-16 min-[900px]:grid-cols-[minmax(0,1fr)_minmax(360px,420px)]">
+          <div className={cn('min-w-0', selectedEventId && 'max-[899px]:hidden')}>
+            <EventsList
+              events={events}
+              query={query}
+              facets={facetsQuery.data}
+              filters={filters}
+              onFiltersChange={onFiltersChange}
+              workspaceId={workspaceId}
+              hasNextPage={query.hasNextPage}
+              isFetchingNextPage={query.isFetchingNextPage}
+              onLoadMore={() => {
+                void query.fetchNextPage();
+              }}
+              selectedEventId={selectedEventId}
+              onSelectEvent={setSelectedEventId}
+            />
+          </div>
+          <TriggerEventDetail
+            workspaceId={workspaceId}
+            eventId={selectedEventId}
+            onBack={() => setSelectedEventId(undefined)}
+          />
+        </div>
+      </section>
+    </RelativeTimeProvider>
+  );
+}

package/src/search.test.ts

@@ -0,0 +1,66 @@
+import {validateTriggerEventsSearch} from './search.js';
+
+describe('validateTriggerEventsSearch', () => {
+  test('passes through a full valid search', () => {
+    const search = validateTriggerEventsSearch({
+      source: ['github', 'gitea'],
+      event: ['push', 'pull_request'],
+      outcome: ['routed', 'failed'],
+      from: '2026-06-01T00:00:00.000Z',
+      to: '2026-06-22T00:00:00.000Z',
+    });
+
+    expect(search).toEqual({
+      source: ['github', 'gitea'],
+      event: ['push', 'pull_request'],
+      outcome: ['routed', 'failed'],
+      from: '2026-06-01T00:00:00.000Z',
+      to: '2026-06-22T00:00:00.000Z',
+    });
+  });
+
+  test('returns an empty search for empty input', () => {
+    expect(validateTriggerEventsSearch({})).toEqual({});
+  });
+
+  test('keeps a valid single-outcome filter', () => {
+    expect(validateTriggerEventsSearch({outcome: ['discarded']}).outcome).toEqual(['discarded']);
+  });
+
+  test('normalizes scalar filter params from existing URLs', () => {
+    const search = validateTriggerEventsSearch({
+      source: 'github',
+      event: 'push',
+      outcome: 'discarded',
+    });
+
+    expect(search.source).toEqual(['github']);
+    expect(search.event).toEqual(['push']);
+    expect(search.outcome).toEqual(['discarded']);
+  });
+
+  test('drops an outcome array containing an unknown value', () => {
+    expect(validateTriggerEventsSearch({outcome: ['routed', 'bogus']}).outcome).toBeUndefined();
+  });
+
+  test('drops a non-string source rather than throwing', () => {
+    expect(validateTriggerEventsSearch({source: 123}).source).toBeUndefined();
+  });
+
+  test('drops a non-ISO date so it never reaches the read API', () => {
+    const search = validateTriggerEventsSearch({from: '2026-06-01', to: 'yesterday'});
+
+    expect(search.from).toBeUndefined();
+    expect(search.to).toBeUndefined();
+  });
+
+  test('keeps a valid ISO datetime window', () => {
+    const search = validateTriggerEventsSearch({
+      from: '2026-06-01T00:00:00.000Z',
+      to: '2026-06-22T23:59:59.999Z',
+    });
+
+    expect(search.from).toBe('2026-06-01T00:00:00.000Z');
+    expect(search.to).toBe('2026-06-22T23:59:59.999Z');
+  });
+});

package/src/search.ts

@@ -0,0 +1,38 @@
+import {triggerEventOutcomeSchema} from '@shipfox/api-triggers-dto';
+import {z} from 'zod';
+
+const stringListSearchSchema = z
+  .preprocess((value) => (typeof value === 'string' ? [value] : value), z.array(z.string()))
+  .optional()
+  .catch(undefined);
+
+const outcomeListSearchSchema = z
+  .preprocess(
+    (value) => (typeof value === 'string' ? [value] : value),
+    z.array(triggerEventOutcomeSchema),
+  )
+  .optional()
+  .catch(undefined);
+
+/**
+ * URL search params for the Events page. Reuses the DTO outcome enum so the page and the
+ * read API share one source of truth, and matches the `TriggerEventFilters` shape the data
+ * hook consumes. Every field uses `.catch(undefined)` so a hand-edited or stale URL drops
+ * the bad param rather than throwing inside the router's `validateSearch`.
+ */
+export const triggerEventsSearchSchema = z.object({
+  source: stringListSearchSchema,
+  event: stringListSearchSchema,
+  outcome: outcomeListSearchSchema,
+  // The read API requires ISO datetimes (`z.string().datetime()`); validate the same here so
+  // a hand-edited or stale URL with a non-ISO date drops the param rather than forwarding it
+  // and turning the first fetch into a full-page load error.
+  from: z.string().datetime().optional().catch(undefined),
+  to: z.string().datetime().optional().catch(undefined),
+});
+
+export type TriggerEventsSearch = z.infer<typeof triggerEventsSearchSchema>;
+
+export function validateTriggerEventsSearch(search: Record<string, unknown>): TriggerEventsSearch {
+  return triggerEventsSearchSchema.parse(search);
+}