@duraton/react 0.1.0-beta.7

package/src/hooks/use-control-actions.ts

@@ -0,0 +1,11 @@
+import { useQuery } from "@tanstack/react-query";
+import type { ControlAction, ListControlActionsOptions } from "@duraton/sdk/client";
+import { useDuratonClient } from "../provider";
+
+export function useControlActions(opts: ListControlActionsOptions = {}) {
+  const client = useDuratonClient();
+  return useQuery<ControlAction[]>({
+    queryKey: ["control-actions", opts],
+    queryFn: () => client.runs.controlActions(opts),
+  });
+}

package/src/hooks/use-deliveries.ts

@@ -0,0 +1,56 @@
+import { keepPreviousData, skipToken, useQuery } from "@tanstack/react-query";
+import type {
+  ListWebhookDeliveriesOptions,
+  WebhookDeliveriesPage,
+  WebhookDeliveryDetail,
+  WebhookEndpoint,
+  WebhookEndpointStats,
+  WebhookReceiver,
+} from "@duraton/sdk/client";
+import { useDuratonClient } from "../provider";
+
+const POLL_MS = 5000;
+
+export function useDeliveries(opts: ListWebhookDeliveriesOptions = {}) {
+  const client = useDuratonClient();
+  return useQuery<WebhookDeliveriesPage>({
+    queryKey: ["deliveries", opts],
+    queryFn: () => client.webhooks.deliveries.list(opts),
+    refetchInterval: POLL_MS,
+    placeholderData: keepPreviousData,
+  });
+}
+
+export function useDelivery(id: string | null) {
+  const client = useDuratonClient();
+  return useQuery<WebhookDeliveryDetail>({
+    queryKey: ["delivery", id],
+    queryFn: id != null ? () => client.webhooks.deliveries.get(id) : skipToken,
+    refetchInterval: POLL_MS,
+  });
+}
+
+export function useEndpoints() {
+  const client = useDuratonClient();
+  return useQuery<WebhookEndpoint[]>({
+    queryKey: ["endpoints"],
+    queryFn: () => client.webhooks.endpoints.list(),
+  });
+}
+
+export function useReceivers() {
+  const client = useDuratonClient();
+  return useQuery<WebhookReceiver[]>({
+    queryKey: ["receivers"],
+    queryFn: () => client.webhooks.receivers.list(),
+  });
+}
+
+export function useEndpointStats(since?: string) {
+  const client = useDuratonClient();
+  return useQuery<WebhookEndpointStats[]>({
+    queryKey: ["endpoint-stats", since ?? null],
+    queryFn: () => client.webhooks.endpoints.stats(since),
+    refetchInterval: POLL_MS,
+  });
+}

package/src/hooks/use-events.ts

@@ -0,0 +1,54 @@
+import { type QueryClient, useMutation, useQuery, useQueryClient } from "@tanstack/react-query";
+import { useEffect } from "react";
+import type { DuratonClient, EventLogRecord, SendEventInput } from "@duraton/sdk/client";
+import { useDuratonClient } from "../provider";
+import { abortableDelay, RECONNECT_MS } from "../lib/stream";
+
+// MAX_EVENTS caps the in-memory list so a long-open tab on the live stream does
+// not grow without bound; older events stay queryable via events.list().
+const MAX_EVENTS = 200;
+
+export function useEvents() {
+  const client = useDuratonClient();
+  const qc = useQueryClient();
+  const query = useQuery<EventLogRecord[]>({
+    queryKey: ["events"],
+    queryFn: () => client.events.list(),
+  });
+
+  useEffect(() => {
+    const ctrl = new AbortController();
+    void tailEvents(client, qc, ctrl.signal);
+    return () => ctrl.abort();
+  }, [client, qc]);
+
+  return query;
+}
+
+async function tailEvents(client: DuratonClient, qc: QueryClient, signal: AbortSignal) {
+  while (!signal.aborted) {
+    try {
+      for await (const ev of client.events.stream({ signal })) {
+        qc.setQueryData<EventLogRecord[]>(["events"], (prev = []) =>
+          prev.some((e) => e.id === ev.id) ? prev : [ev, ...prev].slice(0, MAX_EVENTS),
+        );
+      }
+    } catch {
+      if (signal.aborted) return;
+    }
+    if (signal.aborted) return;
+    await abortableDelay(RECONNECT_MS, signal);
+  }
+}
+
+export function useTriggerEvent() {
+  const client = useDuratonClient();
+  const qc = useQueryClient();
+  return useMutation({
+    mutationFn: (input: SendEventInput) => client.events.send(input),
+    onSuccess: () => {
+      void qc.invalidateQueries({ queryKey: ["events"] });
+      void qc.invalidateQueries({ queryKey: ["runs"] });
+    },
+  });
+}

package/src/hooks/use-flow-state.ts

@@ -0,0 +1,17 @@
+import { keepPreviousData, useQuery } from "@tanstack/react-query";
+import type { FlowState, FlowStateOptions } from "@duraton/sdk/client";
+import { useDuratonClient } from "../provider";
+
+// Buffer counts move on their own (a debounce fires, a batch flushes) with no run
+// event to ride, so this view polls on a short cadence of its own.
+const POLL_MS = 5000;
+
+export function useFlowState(opts: FlowStateOptions = {}) {
+  const client = useDuratonClient();
+  return useQuery<FlowState>({
+    queryKey: ["flow-state", opts],
+    queryFn: () => client.flowState(opts),
+    refetchInterval: POLL_MS,
+    placeholderData: keepPreviousData,
+  });
+}

package/src/hooks/use-run-controls.ts

@@ -0,0 +1,68 @@
+import { useMutation, useQueryClient, type QueryClient } from "@tanstack/react-query";
+import type { BulkReplayFilter, BulkReplayResult, Run } from "@duraton/sdk/client";
+import { useDuratonClient } from "../provider";
+
+function invalidateRuns(qc: QueryClient) {
+  void qc.invalidateQueries({ queryKey: ["runs"] });
+  void qc.invalidateQueries({ queryKey: ["control-actions"] });
+}
+
+// In-place control (cancel/pause/resume) returns the updated run. Writing it into the
+// cache lets useRun's status-driven polling self-correct without a refetch round-trip.
+function useRunStatusMutation(mutationFn: (id: string) => Promise<Run>) {
+  const qc = useQueryClient();
+  return useMutation({
+    mutationFn,
+    onSuccess: (run) => {
+      qc.setQueryData(["run", run.id], run);
+      void qc.invalidateQueries({ queryKey: ["run-steps", run.id] });
+      invalidateRuns(qc);
+    },
+  });
+}
+
+export function useCancelRun() {
+  const client = useDuratonClient();
+  return useRunStatusMutation((id) => client.runs.cancel(id));
+}
+
+export function usePauseRun() {
+  const client = useDuratonClient();
+  return useRunStatusMutation((id) => client.runs.pause(id));
+}
+
+export function useResumeRun() {
+  const client = useDuratonClient();
+  return useRunStatusMutation((id) => client.runs.resume(id));
+}
+
+function useForkRun<TArgs>(mutationFn: (args: TArgs) => Promise<Run>) {
+  const qc = useQueryClient();
+  return useMutation<Run, Error, TArgs>({
+    mutationFn,
+    onSuccess: () => invalidateRuns(qc),
+  });
+}
+
+export function useReplayRun() {
+  const client = useDuratonClient();
+  return useForkRun(({ runId, input }: { runId: string; input?: unknown }) =>
+    client.runs.replay(runId, input),
+  );
+}
+
+export function useRetryFromStep() {
+  const client = useDuratonClient();
+  return useForkRun(({ runId, step }: { runId: string; step: string }) =>
+    client.runs.retryFromStep(runId, step),
+  );
+}
+
+export function useBulkReplay() {
+  const client = useDuratonClient();
+  const qc = useQueryClient();
+  return useMutation<BulkReplayResult, Error, BulkReplayFilter>({
+    mutationFn: (filter) => client.runs.bulkReplay(filter),
+    onSuccess: () => invalidateRuns(qc),
+  });
+}

package/src/hooks/use-run-stats.ts

@@ -0,0 +1,14 @@
+import { useQuery } from "@tanstack/react-query";
+import type { RunStats, RunStatsOptions } from "@duraton/sdk/client";
+import { useDuratonClient } from "../provider";
+
+const FALLBACK_POLL_MS = 15000;
+
+export function useRunStats(options: RunStatsOptions = {}, opts?: { poll?: boolean }) {
+  const client = useDuratonClient();
+  return useQuery<RunStats>({
+    queryKey: ["run-stats", options],
+    queryFn: () => client.runs.stats(options),
+    refetchInterval: opts?.poll === false ? false : FALLBACK_POLL_MS,
+  });
+}

package/src/hooks/use-run-stream.ts

@@ -0,0 +1,74 @@
+import { type QueryClient, useQueryClient } from "@tanstack/react-query";
+import { useEffect, useState } from "react";
+import type { DuratonClient, TimelineFrame } from "@duraton/sdk/client";
+import { useDuratonClient } from "../provider";
+import { abortableDelay, RECONNECT_MS } from "../lib/stream";
+import { TERMINAL_STATUSES } from "../run-status";
+
+// Coalesce a burst of status frames into one run/steps refetch.
+const REFETCH_MS = 250;
+
+// Tails a run's SSE timeline; status frames trigger a coalesced refetch while the
+// returned frame buffer drives the live timeline panel. Keyed by runId so a run
+// switch remounts with fresh state.
+export function useRunStream(runId: string): TimelineFrame[] {
+  const client = useDuratonClient();
+  const qc = useQueryClient();
+  const [frames, setFrames] = useState<TimelineFrame[]>([]);
+
+  useEffect(() => {
+    const ctrl = new AbortController();
+    void tailRun(client, qc, runId, ctrl.signal, setFrames);
+    return () => ctrl.abort();
+  }, [client, qc, runId]);
+
+  return frames;
+}
+
+type SetFrames = (update: (prev: TimelineFrame[]) => TimelineFrame[]) => void;
+
+async function tailRun(
+  client: DuratonClient,
+  qc: QueryClient,
+  runId: string,
+  signal: AbortSignal,
+  setFrames: SetFrames,
+) {
+  let from = 0;
+  let refetchTimer: ReturnType<typeof setTimeout> | undefined;
+  signal.addEventListener("abort", () => clearTimeout(refetchTimer), { once: true });
+
+  const refetch = () => {
+    void qc.invalidateQueries({ queryKey: ["run", runId] });
+    void qc.invalidateQueries({ queryKey: ["run-steps", runId] });
+  };
+  const scheduleRefetch = () => {
+    if (refetchTimer) return;
+    refetchTimer = setTimeout(() => {
+      refetchTimer = undefined;
+      refetch();
+    }, REFETCH_MS);
+  };
+
+  while (!signal.aborted) {
+    let terminal = false;
+    try {
+      for await (const frame of client.runs.watch(runId, { from, signal })) {
+        from = frame.seq;
+        setFrames((prev) => (prev.some((f) => f.seq === frame.seq) ? prev : [...prev, frame]));
+        if (frame.kind === "log") continue;
+        scheduleRefetch();
+        if (frame.kind === "run_status" && TERMINAL_STATUSES.has(frame.status)) terminal = true;
+      }
+    } catch {
+      if (signal.aborted) return;
+    }
+    if (terminal) {
+      clearTimeout(refetchTimer);
+      refetch();
+      return;
+    }
+    if (signal.aborted) return;
+    await abortableDelay(RECONNECT_MS, signal);
+  }
+}

package/src/hooks/use-run-timeseries.ts

@@ -0,0 +1,15 @@
+import { useQuery } from "@tanstack/react-query";
+import type { RunSeries, RunTimeSeriesOptions } from "@duraton/sdk/client";
+import { useDuratonClient } from "../provider";
+
+// The namespace stream (useRunsStream) drives refetches; this slow interval is only a safety net.
+const FALLBACK_POLL_MS = 15000;
+
+export function useRunTimeSeries(opts: RunTimeSeriesOptions = {}) {
+  const client = useDuratonClient();
+  return useQuery<RunSeries>({
+    queryKey: ["run-timeseries", opts],
+    queryFn: () => client.runs.timeseries(opts),
+    refetchInterval: FALLBACK_POLL_MS,
+  });
+}

package/src/hooks/use-run.ts

@@ -0,0 +1,27 @@
+import { useQuery } from "@tanstack/react-query";
+import type { Run, Step } from "@duraton/sdk/client";
+import { useDuratonClient } from "../provider";
+import { ACTIVE_STATUSES } from "../run-status";
+
+const FALLBACK_POLL_MS = 10000;
+
+export function useRun(runId: string) {
+  const client = useDuratonClient();
+  return useQuery<Run>({
+    queryKey: ["run", runId],
+    queryFn: () => client.runs.get(runId),
+    refetchInterval: (query) => {
+      const status = query.state.data?.status;
+      return status && ACTIVE_STATUSES.has(status) ? FALLBACK_POLL_MS : false;
+    },
+  });
+}
+
+export function useRunSteps(runId: string, active: boolean) {
+  const client = useDuratonClient();
+  return useQuery<Step[]>({
+    queryKey: ["run-steps", runId],
+    queryFn: () => client.runs.steps(runId),
+    refetchInterval: active ? FALLBACK_POLL_MS : false,
+  });
+}

package/src/hooks/use-runners.ts

@@ -0,0 +1,15 @@
+import { keepPreviousData, useQuery } from "@tanstack/react-query";
+import type { Runner } from "@duraton/sdk/client";
+import { useDuratonClient } from "../provider";
+
+const POLL_MS = 15000;
+
+export function useRunners() {
+  const client = useDuratonClient();
+  return useQuery<Runner[]>({
+    queryKey: ["runners"],
+    queryFn: () => client.runners.list(),
+    refetchInterval: POLL_MS,
+    placeholderData: keepPreviousData,
+  });
+}

package/src/hooks/use-runs-stream.ts

@@ -0,0 +1,45 @@
+import { type QueryClient, useQueryClient } from "@tanstack/react-query";
+import { useEffect } from "react";
+import type { DuratonClient } from "@duraton/sdk/client";
+import { useDuratonClient } from "../provider";
+import { abortableDelay, RECONNECT_MS } from "../lib/stream";
+
+// Coalesce a burst of namespace activity into one list/stats refetch.
+const REFETCH_MS = 300;
+
+// Tails the namespace-wide run-status stream and refetches the runs list + stats
+// on any activity. Best-effort: a dropped frame self-heals on the next change.
+export function useRunsStream() {
+  const client = useDuratonClient();
+  const qc = useQueryClient();
+  useEffect(() => {
+    const ctrl = new AbortController();
+    void tailNamespace(client, qc, ctrl.signal);
+    return () => ctrl.abort();
+  }, [client, qc]);
+}
+
+async function tailNamespace(client: DuratonClient, qc: QueryClient, signal: AbortSignal) {
+  let timer: ReturnType<typeof setTimeout> | undefined;
+  const scheduleRefetch = () => {
+    if (timer) return;
+    timer = setTimeout(() => {
+      timer = undefined;
+      void qc.invalidateQueries({ queryKey: ["runs"] });
+      void qc.invalidateQueries({ queryKey: ["run-stats"] });
+    }, REFETCH_MS);
+  };
+  signal.addEventListener("abort", () => clearTimeout(timer), { once: true });
+
+  while (!signal.aborted) {
+    try {
+      for await (const frame of client.runs.watchAll({ signal })) {
+        if (frame.kind === "run_status") scheduleRefetch();
+      }
+    } catch {
+      if (signal.aborted) return;
+    }
+    if (signal.aborted) return;
+    await abortableDelay(RECONNECT_MS, signal);
+  }
+}

package/src/hooks/use-runs.ts

@@ -0,0 +1,17 @@
+import { keepPreviousData, useQuery } from "@tanstack/react-query";
+import type { ListRunsOptions, RunsPage } from "@duraton/sdk/client";
+import { useDuratonClient } from "../provider";
+
+// The namespace stream (useRunsStream) drives refetches; this slow interval is only a
+// safety net so the list still self-heals if the stream drops.
+const FALLBACK_POLL_MS = 15000;
+
+export function useRuns(options: ListRunsOptions = {}) {
+  const client = useDuratonClient();
+  return useQuery<RunsPage>({
+    queryKey: ["runs", options],
+    queryFn: () => client.runs.list(options),
+    refetchInterval: FALLBACK_POLL_MS,
+    placeholderData: keepPreviousData,
+  });
+}

package/src/hooks/use-webhook-config.ts

@@ -0,0 +1,92 @@
+import { useMutation, useQueryClient } from "@tanstack/react-query";
+import type {
+  EndpointInput,
+  EndpointPatch,
+  ReceiverInput,
+  ReceiverPatch,
+} from "@duraton/sdk/client";
+import { useDuratonClient } from "../provider";
+
+// Pure mutation hooks: cache invalidation only. Consumers add toast/navigation via
+// mutate(vars, { onSuccess, onError }).
+
+function useEndpointInvalidation() {
+  const qc = useQueryClient();
+  return () => {
+    void qc.invalidateQueries({ queryKey: ["endpoints"] });
+    void qc.invalidateQueries({ queryKey: ["endpoint-stats"] });
+  };
+}
+
+export function useCreateEndpoint() {
+  const client = useDuratonClient();
+  const invalidate = useEndpointInvalidation();
+  return useMutation({
+    mutationFn: (input: EndpointInput) => client.webhooks.endpoints.create(input),
+    onSuccess: invalidate,
+  });
+}
+
+export function useUpdateEndpoint() {
+  const client = useDuratonClient();
+  const invalidate = useEndpointInvalidation();
+  return useMutation({
+    mutationFn: ({ id, patch }: { id: string; patch: EndpointPatch }) =>
+      client.webhooks.endpoints.update(id, patch),
+    onSuccess: invalidate,
+  });
+}
+
+export function useDeleteEndpoint() {
+  const client = useDuratonClient();
+  const invalidate = useEndpointInvalidation();
+  return useMutation({
+    mutationFn: (id: string) => client.webhooks.endpoints.delete(id),
+    onSuccess: invalidate,
+  });
+}
+
+function useReceiverInvalidation() {
+  const qc = useQueryClient();
+  return () => void qc.invalidateQueries({ queryKey: ["receivers"] });
+}
+
+export function useCreateReceiver() {
+  const client = useDuratonClient();
+  const invalidate = useReceiverInvalidation();
+  return useMutation({
+    mutationFn: (input: ReceiverInput) => client.webhooks.receivers.create(input),
+    onSuccess: invalidate,
+  });
+}
+
+export function useUpdateReceiver() {
+  const client = useDuratonClient();
+  const invalidate = useReceiverInvalidation();
+  return useMutation({
+    mutationFn: ({ id, patch }: { id: string; patch: ReceiverPatch }) =>
+      client.webhooks.receivers.update(id, patch),
+    onSuccess: invalidate,
+  });
+}
+
+export function useDeleteReceiver() {
+  const client = useDuratonClient();
+  const invalidate = useReceiverInvalidation();
+  return useMutation({
+    mutationFn: (id: string) => client.webhooks.receivers.delete(id),
+    onSuccess: invalidate,
+  });
+}
+
+export function useRedeliverDelivery() {
+  const client = useDuratonClient();
+  const qc = useQueryClient();
+  return useMutation({
+    mutationFn: (id: string) => client.webhooks.deliveries.redeliver(id),
+    onSuccess: (_void, id) => {
+      void qc.invalidateQueries({ queryKey: ["deliveries"] });
+      void qc.invalidateQueries({ queryKey: ["delivery", id] });
+    },
+  });
+}

package/src/hooks/use-workflows.ts

@@ -0,0 +1,14 @@
+import { useQuery } from "@tanstack/react-query";
+import type { WorkflowDef } from "@duraton/sdk/client";
+import { useDuratonClient } from "../provider";
+
+const POLL_MS = 5000;
+
+export function useWorkflows() {
+  const client = useDuratonClient();
+  return useQuery<WorkflowDef[]>({
+    queryKey: ["workflows"],
+    queryFn: () => client.workflows.list(),
+    refetchInterval: POLL_MS,
+  });
+}

package/src/hooks.test.tsx

@@ -0,0 +1,87 @@
+import { describe, expect, it } from "vitest";
+import { renderHook, waitFor } from "@testing-library/react";
+import type { RunStatus, TimelineFrame } from "@duraton/sdk/client";
+import { useDuratonClient } from "./provider";
+import { useRuns } from "./hooks/use-runs";
+import { useRunStream } from "./hooks/use-run-stream";
+import { useWorkflows } from "./hooks/use-workflows";
+import { fakeClient, makeRun, wrapper } from "./test-utils";
+
+function runStatus(seq: number, status: RunStatus): TimelineFrame {
+  return { kind: "run_status", seq, ts: "t", runId: "run_1", status };
+}
+
+function logLine(seq: number): TimelineFrame {
+  return {
+    kind: "log",
+    seq,
+    ts: "t",
+    runId: "run_1",
+    level: "info",
+    message: "x",
+    scope: "@root",
+    attempt: 1,
+  };
+}
+
+describe("useDuratonClient", () => {
+  it("throws when used outside a DuratonProvider", () => {
+    expect(() => renderHook(() => useDuratonClient())).toThrow(/DuratonProvider/);
+  });
+
+  it("returns the injected client inside the provider", () => {
+    const client = fakeClient();
+    const { result } = renderHook(() => useDuratonClient(), { wrapper: wrapper(client) });
+    expect(result.current).toBe(client);
+  });
+});
+
+describe("useRuns", () => {
+  it("returns the run list from the client", async () => {
+    const client = fakeClient({ runs: [makeRun({ id: "r1" }), makeRun({ id: "r2" })] });
+    const { result } = renderHook(() => useRuns(), { wrapper: wrapper(client) });
+    await waitFor(() => expect(result.current.isSuccess).toBe(true));
+    expect(result.current.data?.runs.map((r) => r.id)).toEqual(["r1", "r2"]);
+  });
+});
+
+describe("useWorkflows", () => {
+  it("returns the workflow list from the client", async () => {
+    const client = fakeClient({
+      workflows: [
+        {
+          name: "wf",
+          app: "default",
+          maxAttempts: 3,
+          backoff: "1s",
+          scheduled: false,
+          registeredAt: "t",
+          updatedAt: "t",
+        },
+      ],
+    });
+    const { result } = renderHook(() => useWorkflows(), { wrapper: wrapper(client) });
+    await waitFor(() => expect(result.current.isSuccess).toBe(true));
+    expect(result.current.data?.[0]?.name).toBe("wf");
+  });
+});
+
+describe("useRunStream", () => {
+  it("collects timeline frames and stops on a terminal status", async () => {
+    const client = fakeClient({
+      frames: [runStatus(1, "running"), logLine(2), runStatus(3, "succeeded")],
+    });
+    const { result } = renderHook(() => useRunStream("run_1"), { wrapper: wrapper(client) });
+    await waitFor(() => expect(result.current.length).toBe(3));
+    expect(result.current.map((f) => f.seq)).toEqual([1, 2, 3]);
+  });
+
+  it("dedupes frames that repeat a seq", async () => {
+    const client = fakeClient({
+      frames: [runStatus(1, "running"), runStatus(1, "running"), runStatus(2, "succeeded")],
+    });
+    const { result } = renderHook(() => useRunStream("run_1"), { wrapper: wrapper(client) });
+    await waitFor(() => expect(result.current.length).toBe(2));
+    expect(result.current.map((f) => f.seq)).toEqual([1, 2]);
+  });
+});