feat(web): automations contracts, API client, atoms and hooks

Foundation for the v1 automations UI. Mirrors backend Pydantic schemas
into Zod and wires the data layer end-to-end so feature surfaces can
be built on top.

contracts/types/automation.types.ts:
- AutomationStatus, TriggerType, RunStatus enums.
- AutomationDefinition envelope (PlanStep, TriggerSpec, Execution,
  Metadata, Inputs).
- AutomationCreate/Update/Detail/Summary/List + listParams.
- TriggerCreate/Update/Detail.
- RunSummary/Detail/List + runListParams.

lib/apis/automations-api.service.ts:
- list/get/create/update/delete automations.
- add/update/remove triggers (sub-resource).
- list/get runs (read-only sub-resource).
- safeParse on every write, 204-safe deletes.

atoms/automations/:
- automationsListAtom (active search space, first page).
- 6 mutation atoms with toast + cache invalidation.

hooks/:
- use-automations.ts wraps the list atom.
- use-automation.ts: parameterized detail by id.
- use-automation-runs.ts: useAutomationRuns + useAutomationRun.

lib/query-client/cache-keys.ts: automations namespace (list, detail,
runs, run) keyed by (id, limit, offset) where relevant.

Smoke: zod round-trip OK on backend-shape payloads (Automation,
AutomationCreate, Trigger, Run); typecheck clean for new files;
biome clean.

surfsense_web/hooks/use-automation-runs.ts

@@ -0,0 +1,42 @@
+"use client";
+import { useQuery } from "@tanstack/react-query";
+import type { Run, RunListResponse } from "@/contracts/types/automation.types";
+import { automationsApiService } from "@/lib/apis/automations-api.service";
+import { cacheKeys } from "@/lib/query-client/cache-keys";
+
+const DEFAULT_LIMIT = 50;
+const DEFAULT_OFFSET = 0;
+
+export interface UseAutomationRunsOptions {
+	limit?: number;
+	offset?: number;
+	enabled?: boolean;
+}
+
+/** Paginated run history for one automation. Newest-first per backend. */
+export function useAutomationRuns(
+	automationId: number | undefined,
+	{ limit = DEFAULT_LIMIT, offset = DEFAULT_OFFSET, enabled = true }: UseAutomationRunsOptions = {}
+) {
+	return useQuery<RunListResponse, Error>({
+		queryKey: cacheKeys.automations.runs(automationId ?? 0, limit, offset),
+		queryFn: () => automationsApiService.listRuns(automationId as number, { limit, offset }),
+		enabled: enabled && !!automationId,
+		staleTime: 30_000,
+	});
+}
+
+/** Single run with the full snapshot, step results, output and artifacts. */
+export function useAutomationRun(
+	automationId: number | undefined,
+	runId: number | undefined,
+	options: { enabled?: boolean } = {}
+) {
+	const { enabled = true } = options;
+	return useQuery<Run, Error>({
+		queryKey: cacheKeys.automations.run(automationId ?? 0, runId ?? 0),
+		queryFn: () => automationsApiService.getRun(automationId as number, runId as number),
+		enabled: enabled && !!automationId && !!runId,
+		staleTime: 30_000,
+	});
+}

surfsense_web/hooks/use-automation.ts

@@ -0,0 +1,19 @@
+"use client";
+import { useQuery } from "@tanstack/react-query";
+import type { Automation } from "@/contracts/types/automation.types";
+import { automationsApiService } from "@/lib/apis/automations-api.service";
+import { cacheKeys } from "@/lib/query-client/cache-keys";
+
+/**
+ * Fetch a single automation with its definition and triggers.
+ * Lives outside the jotai atom layer because it's keyed by id, not by the
+ * "current scope" the atom layer assumes.
+ */
+export function useAutomation(automationId: number | undefined) {
+	return useQuery<Automation, Error>({
+		queryKey: cacheKeys.automations.detail(automationId ?? 0),
+		queryFn: () => automationsApiService.getAutomation(automationId as number),
+		enabled: !!automationId,
+		staleTime: 60_000,
+	});
+}

surfsense_web/hooks/use-automations.ts

@@ -0,0 +1,24 @@
+"use client";
+import { useAtomValue } from "jotai";
+import { automationsListAtom } from "@/atoms/automations/automations-query.atoms";
+
+/**
+ * List automations in the active search space (first page).
+ * Pagination knobs live in detail/list hooks below; v1 surfaces only the
+ * first page since automation counts are expected to be small.
+ */
+export function useAutomations() {
+	const { data, isLoading, error, refetch } = useAutomationsRaw();
+	return {
+		automations: data?.items ?? [],
+		total: data?.total ?? 0,
+		loading: isLoading,
+		error,
+		refresh: refetch,
+	};
+}
+
+// Exposed for callers that prefer the raw react-query result shape.
+export function useAutomationsRaw() {
+	return useAtomValue(automationsListAtom);
+}