@stigmer/react 3.5.3 → 3.7.0

package/src/schedule/useCreateSchedule.ts

@@ -0,0 +1,88 @@
+"use client";
+
+import { useCallback, useState } from "react";
+import type { ScheduleInput } from "@stigmer/sdk";
+import type { Schedule } from "@stigmer/protos/ai/stigmer/agentic/schedule/v1/api_pb";
+import { useStigmer } from "../hooks.js";
+import { toError } from "../internal/toError.js";
+
+/** Return value of {@link useCreateSchedule}. */
+export interface UseCreateScheduleReturn {
+  /**
+   * Submit a {@link ScheduleInput} to create (or upsert) a schedule.
+   *
+   * Uses `stigmer.schedule.apply()` — the idempotent upsert operation.
+   * Resolves with the server-created `Schedule` proto including
+   * populated metadata (id, slug, audit timestamps) and the
+   * platform-computed `status.next_fire_at`.
+   */
+  readonly create: (input: ScheduleInput) => Promise<Schedule>;
+  /** `true` while the apply request is in flight. */
+  readonly isCreating: boolean;
+  /** Error from the last failed create, or `null` when healthy. */
+  readonly error: Error | null;
+  /** Reset `error` to `null`. */
+  readonly clearError: () => void;
+}
+
+/**
+ * Behavior hook that wraps `schedule.apply()` with loading and error
+ * state.
+ *
+ * Creates a schedule from a {@link ScheduleInput}. Uses `apply()`
+ * (upsert) rather than `create()` so re-submissions are idempotent —
+ * matching the CLI's `stigmer apply` semantics and the established SDK
+ * mutation hook pattern (`isCreating` flag, `error` state, `clearError`
+ * reset, result returned from the promise, not stored in hook state).
+ *
+ * NOTE: this hook is for CREATION. Editing an existing schedule must
+ * NOT go through `ScheduleInput` — the input type cannot express every
+ * metadata field (tags, description), and the server replaces spec and
+ * mutable metadata wholesale on update, so a down-converting edit would
+ * silently wipe them. Edit flows use the full-proto path instead (see
+ * `useSetScheduleEnabled` for the pattern).
+ *
+ * @example
+ * ```tsx
+ * const { create, isCreating, error, clearError } = useCreateSchedule();
+ *
+ * const schedule = await create({
+ *   name: "daily-fee-reminders",
+ *   org: "acme",
+ *   cron: "0 9 * * *",
+ *   timeZone: "Asia/Kolkata",
+ *   enabled: false,
+ *   agent: {
+ *     agentRef: { org: "acme", slug: "billing-assistant" },
+ *     message: "Send today's fee reminders.",
+ *   },
+ * });
+ * // schedule.metadata?.slug → "daily-fee-reminders"
+ * ```
+ */
+export function useCreateSchedule(): UseCreateScheduleReturn {
+  const stigmer = useStigmer();
+  const [isCreating, setIsCreating] = useState(false);
+  const [error, setError] = useState<Error | null>(null);
+
+  const clearError = useCallback(() => setError(null), []);
+
+  const create = useCallback(
+    async (input: ScheduleInput): Promise<Schedule> => {
+      setIsCreating(true);
+      setError(null);
+
+      try {
+        return await stigmer.schedule.apply(input);
+      } catch (err) {
+        setError(toError(err));
+        throw err;
+      } finally {
+        setIsCreating(false);
+      }
+    },
+    [stigmer],
+  );
+
+  return { create, isCreating, error, clearError };
+}

package/src/schedule/useResumeSchedule.ts

@@ -0,0 +1,67 @@
+"use client";
+
+import { useCallback, useMemo, useState } from "react";
+import type { Schedule } from "@stigmer/protos/ai/stigmer/agentic/schedule/v1/api_pb";
+import { getUserMessage } from "@stigmer/sdk";
+import { useStigmer } from "../hooks.js";
+import { toast } from "../feedback/toast.js";
+import { toError } from "../internal/toError.js";
+
+/** Return value of {@link useResumeSchedule}. */
+export interface UseResumeScheduleReturn {
+  /**
+   * Clear the platform's failure-streak pause and let the schedule fire
+   * again. Resolves with the post-resume schedule; the caller refetches
+   * or replaces its local copy from it.
+   */
+  readonly resumeSchedule: (scheduleId: string) => Promise<Schedule>;
+  /** `true` while the resume request is in flight. */
+  readonly isResuming: boolean;
+  /** Error from the last failed resume, or `null` when healthy. */
+  readonly error: Error | null;
+}
+
+/**
+ * Behavior hook that resumes a platform-paused schedule.
+ *
+ * Resume is the ONE path that clears `status.paused_reason` (and the
+ * failure streak with it) — re-applying the manifest deliberately does
+ * not, so a routine GitOps apply can never silently un-pause a failing
+ * schedule. Resuming a schedule that is not paused is a server-side
+ * no-op; resuming a disabled schedule clears the pause but the schedule
+ * stays disabled (the owner's lever is separate — see
+ * {@link useSetScheduleEnabled}).
+ *
+ * Error toasts relay the server's message verbatim: the copy is
+ * identical across editions and states the remedy.
+ */
+export function useResumeSchedule(): UseResumeScheduleReturn {
+  const stigmer = useStigmer();
+  const [isResuming, setIsResuming] = useState(false);
+  const [error, setError] = useState<Error | null>(null);
+
+  const resumeSchedule = useCallback(
+    async (scheduleId: string): Promise<Schedule> => {
+      setIsResuming(true);
+      setError(null);
+      try {
+        const resumed = await stigmer.schedule.resume(scheduleId);
+        toast.success("Schedule resumed");
+        return resumed;
+      } catch (err) {
+        const wrapped = toError(err);
+        setError(wrapped);
+        toast.error(getUserMessage(err));
+        throw wrapped;
+      } finally {
+        setIsResuming(false);
+      }
+    },
+    [stigmer],
+  );
+
+  return useMemo(
+    () => ({ resumeSchedule, isResuming, error }),
+    [resumeSchedule, isResuming, error],
+  );
+}

package/src/schedule/useSchedule.ts

@@ -0,0 +1,67 @@
+"use client";
+
+import type { Schedule } from "@stigmer/protos/ai/stigmer/agentic/schedule/v1/api_pb";
+import { isNotFound } from "@stigmer/sdk";
+import { useStigmer } from "../hooks.js";
+import { useFetch } from "../internal/useFetch.js";
+
+/** Return value of {@link useSchedule}. */
+export interface UseScheduleReturn {
+  /** The resolved schedule, or `null` while loading, on error, or when not found. */
+  readonly schedule: Schedule | null;
+  /** `true` while the initial fetch is in flight. */
+  readonly isLoading: boolean;
+  /** `true` while a background refetch is in flight. */
+  readonly isRefetching: boolean;
+  /** Error from the last failed request, or `null` when healthy. */
+  readonly error: Error | null;
+  /** Discard cached data and re-fetch the schedule from the server. */
+  readonly refetch: () => void;
+}
+
+/**
+ * Data hook that fetches a single Schedule by organization and slug.
+ *
+ * Wraps `stigmer.schedule.getByReference()` with loading, error, and
+ * not-found state management. The loaded resource carries the spec
+ * (cron, time zone, enabled, target) and the platform-written status
+ * (`next_fire_at`, `last_fire_at`, `last_execution_id`,
+ * `consecutive_failures`, `paused_reason`) — everything the detail view
+ * renders, including the disabled-vs-paused distinction (see
+ * {@link deriveScheduleState}).
+ *
+ * Pass `null` for either `org` or `slug` to skip fetching (stable
+ * no-op).
+ *
+ * **Not-found handling:** a NOT_FOUND response sets `schedule` to
+ * `null` without raising an error; `schedule === null && !isLoading
+ * && !error` means the resource does not exist.
+ *
+ * @example
+ * ```tsx
+ * const { schedule, isLoading, error, refetch } = useSchedule("isc", "daily-fee-reminders");
+ * ```
+ */
+export function useSchedule(
+  org: string | null,
+  slug: string | null,
+): UseScheduleReturn {
+  const stigmer = useStigmer();
+
+  const { data: schedule, isLoading, isRefetching, error, refetch } = useFetch(
+    org && slug
+      ? async () => {
+          try {
+            return await stigmer.schedule.getByReference({ org, slug });
+          } catch (err) {
+            if (isNotFound(err)) return null;
+            throw err;
+          }
+        }
+      : null,
+    [org, slug, stigmer],
+    null,
+  );
+
+  return { schedule, isLoading, isRefetching, error, refetch };
+}

package/src/schedule/useScheduleCount.ts

@@ -0,0 +1,57 @@
+"use client";
+
+import { useMemo } from "react";
+import { useStigmer } from "../hooks.js";
+import { useResourceCount } from "../search/index.js";
+import { createScheduleListFn } from "./scheduleListFn.js";
+
+/** Options for {@link useScheduleCount}. */
+export interface UseScheduleCountOptions {
+  /** Opaque token that forces a recount when its value changes. */
+  readonly refetchToken?: unknown;
+}
+
+/** Return value of {@link useScheduleCount}. */
+export interface UseScheduleCountReturn {
+  /**
+   * Total number of schedules in the organization. `undefined` until
+   * the first successful fetch completes.
+   */
+  readonly count: number | undefined;
+  /** `true` while the count fetch is in flight. */
+  readonly isLoading: boolean;
+  /** Error from the last failed request, or `null` when healthy. */
+  readonly error: Error | null;
+  /** Discard cached data and re-fetch the count from the server. */
+  readonly refetch: () => void;
+}
+
+/**
+ * Data hook that fetches the total count of an organization's schedules.
+ *
+ * Issues a minimal direct `listSchedules` call to retrieve only the
+ * total count. Useful for the Library landing card and dashboard
+ * widgets. There is no scope option: schedules are org-only.
+ *
+ * For the full paginated schedule list, use {@link useScheduleList}
+ * instead.
+ *
+ * Pass `null` as `org` to skip fetching (stable no-op).
+ *
+ * @example
+ * ```tsx
+ * const { count, isLoading } = useScheduleCount("isc");
+ * ```
+ */
+export function useScheduleCount(
+  org: string | null,
+  options?: UseScheduleCountOptions,
+): UseScheduleCountReturn {
+  const stigmer = useStigmer();
+
+  const listFn = useMemo(() => createScheduleListFn(stigmer), [stigmer]);
+
+  return useResourceCount(listFn, org, {
+    refetchToken: options?.refetchToken,
+  });
+}

package/src/schedule/useScheduleList.ts

@@ -0,0 +1,83 @@
+"use client";
+
+import type { Schedule } from "@stigmer/protos/ai/stigmer/agentic/schedule/v1/api_pb";
+import { useStigmer } from "../hooks.js";
+import { useFetch } from "../internal/useFetch.js";
+import { listSchedulesPage, type SchedulePage } from "./scheduleListFn.js";
+
+/** Options for {@link useScheduleList}. */
+export interface UseScheduleListOptions {
+  /** Maximum schedules per page. @default 20 */
+  readonly pageSize?: number;
+  /** Page number (1-indexed). @default 1 */
+  readonly page?: number;
+}
+
+/** Return value of {@link useScheduleList}. */
+export interface UseScheduleListReturn {
+  /** Full `Schedule` protos (spec + status) for the current page. */
+  readonly schedules: readonly Schedule[];
+  /** Total number of schedules in the organization. */
+  readonly totalCount: number;
+  /** Total pages available at the current page size. */
+  readonly totalPages: number;
+  /** The current page number (mirrors the `page` option). */
+  readonly currentPage: number;
+  /** `true` while the initial fetch is in flight. */
+  readonly isLoading: boolean;
+  /** `true` while a background refetch is in flight. */
+  readonly isRefetching: boolean;
+  /** Error from the last failed request, or `null` when healthy. */
+  readonly error: Error | null;
+  /** Discard cached data and re-fetch the current page from the server. */
+  readonly refetch: () => void;
+}
+
+const INITIAL_PAGE: SchedulePage = { items: [], totalCount: 0, totalPages: 0 };
+
+/**
+ * Data hook that fetches a paginated list of an organization's schedules.
+ *
+ * Backed by the direct `listSchedules` query — not the search service —
+ * so each entry is a full `Schedule` proto with the operational status
+ * fields a schedule list exists to show (`next_fire_at`, enabled/paused
+ * state, `last_fire_at`). There is no text query or visibility scope:
+ * schedules are org-only and have no server-side search.
+ *
+ * Pass `null` as `org` to skip fetching (stable no-op).
+ *
+ * @example
+ * ```tsx
+ * const { schedules, totalCount, isLoading } = useScheduleList("isc", {
+ *   page: 1,
+ *   pageSize: 20,
+ * });
+ * ```
+ */
+export function useScheduleList(
+  org: string | null,
+  options?: UseScheduleListOptions,
+): UseScheduleListReturn {
+  const stigmer = useStigmer();
+  const pageSize = options?.pageSize;
+  const page = options?.page ?? 1;
+
+  const { data, isLoading, isRefetching, error, refetch } = useFetch<SchedulePage>(
+    org
+      ? () => listSchedulesPage(stigmer, org, { num: page, size: pageSize })
+      : null,
+    [stigmer, org, page, pageSize],
+    INITIAL_PAGE,
+  );
+
+  return {
+    schedules: data.items,
+    totalCount: data.totalCount,
+    totalPages: data.totalPages,
+    currentPage: page,
+    isLoading,
+    isRefetching,
+    error,
+    refetch,
+  };
+}

package/src/schedule/useScheduleRuns.ts

@@ -0,0 +1,93 @@
+"use client";
+
+import { create } from "@bufbuild/protobuf";
+import {
+  ListScheduleRunsRequestSchema,
+  type ScheduleRun,
+} from "@stigmer/protos/ai/stigmer/agentic/schedule/v1/io_pb";
+import { useStigmer } from "../hooks.js";
+import { useFetch } from "../internal/useFetch.js";
+
+/** Options for {@link useScheduleRuns}. */
+export interface UseScheduleRunsOptions {
+  /** Maximum runs per page. @default 25 */
+  readonly pageSize?: number;
+  /** Page number (1-indexed). @default 1 */
+  readonly page?: number;
+}
+
+/** Return value of {@link useScheduleRuns}. */
+export interface UseScheduleRunsReturn {
+  /** Recorded fires for the current page, newest first. */
+  readonly runs: readonly ScheduleRun[];
+  /** Total number of recorded runs for the schedule. */
+  readonly totalCount: number;
+  /** `true` while the initial fetch is in flight. */
+  readonly isLoading: boolean;
+  /** `true` while a background refetch is in flight. */
+  readonly isRefetching: boolean;
+  /** Error from the last failed request, or `null` when healthy. */
+  readonly error: Error | null;
+  /** Discard cached data and re-fetch the current page from the server. */
+  readonly refetch: () => void;
+}
+
+interface RunsPage {
+  readonly runs: readonly ScheduleRun[];
+  readonly totalCount: number;
+}
+
+const INITIAL_PAGE: RunsPage = { runs: [], totalCount: 0 };
+
+/**
+ * Data hook that fetches a schedule's run history, newest first — the
+ * fire ledger (project DD-017 D-7).
+ *
+ * Every fire leaves a row, INCLUDING the fires that created no execution
+ * (a refused launch gate, a missing target agent), carrying the refusing
+ * gate's copy verbatim. This is the surface that finally explains
+ * `status.consecutive_failures`: the reason is one row away instead of
+ * buried in server logs. Rows for in-flight runs are enriched server-side
+ * with the execution's live phase, so outcomes never lie.
+ *
+ * Pass `null` as `scheduleId` to skip fetching (stable no-op) — the
+ * detail view does this while the schedule itself is still loading.
+ *
+ * @example
+ * ```tsx
+ * const { runs, totalCount, isLoading } = useScheduleRuns(schedule?.metadata?.id ?? null);
+ * ```
+ */
+export function useScheduleRuns(
+  scheduleId: string | null,
+  options?: UseScheduleRunsOptions,
+): UseScheduleRunsReturn {
+  const stigmer = useStigmer();
+  const pageSize = options?.pageSize ?? 25;
+  const page = options?.page ?? 1;
+
+  const { data, isLoading, isRefetching, error, refetch } = useFetch<RunsPage>(
+    scheduleId
+      ? async () => {
+          const result = await stigmer.schedule.listRuns(
+            create(ListScheduleRunsRequestSchema, {
+              scheduleId,
+              pageInfo: { num: page, size: pageSize },
+            }),
+          );
+          return { runs: result.items, totalCount: result.totalCount };
+        }
+      : null,
+    [stigmer, scheduleId, page, pageSize],
+    INITIAL_PAGE,
+  );
+
+  return {
+    runs: data.runs,
+    totalCount: data.totalCount,
+    isLoading,
+    isRefetching,
+    error,
+    refetch,
+  };
+}

package/src/schedule/useSetScheduleEnabled.ts

@@ -0,0 +1,84 @@
+"use client";
+
+import { useCallback, useMemo, useState } from "react";
+import { clone } from "@bufbuild/protobuf";
+import {
+  ScheduleSchema,
+  type Schedule,
+} from "@stigmer/protos/ai/stigmer/agentic/schedule/v1/api_pb";
+import { getUserMessage, manifestDocumentForResource } from "@stigmer/sdk";
+import { useStigmer } from "../hooks.js";
+import { toast } from "../feedback/toast.js";
+import { toError } from "../internal/toError.js";
+
+/** Return value of {@link useSetScheduleEnabled}. */
+export interface UseSetScheduleEnabledReturn {
+  /**
+   * Flip the owner's `spec.enabled` switch. Takes the full fetched
+   * schedule (not just an id) because the write re-applies the whole
+   * resource. Resolves with the post-apply schedule; the caller
+   * refetches or replaces its local copy from it.
+   */
+  readonly setEnabled: (schedule: Schedule, enabled: boolean) => Promise<Schedule>;
+  /** `true` while the apply is in flight. */
+  readonly isPending: boolean;
+  /** Error from the last failed apply, or `null` when healthy. */
+  readonly error: Error | null;
+}
+
+/**
+ * Behavior hook that flips a schedule's owner-controlled `enabled` flag.
+ *
+ * The write path is deliberate: clone the fetched proto, flip one
+ * field, and re-apply the WHOLE resource through the manifest engine
+ * (`stigmer.manifest.apply`) — never down-convert to the curated
+ * `ScheduleInput` shape. The server replaces spec and mutable metadata
+ * wholesale on update, and `ScheduleInput` cannot express every
+ * metadata field (tags, description), so the input route would silently
+ * wipe them. The full-proto route is lossless by construction; the
+ * server ignores client-provided status, and re-applying never clears a
+ * platform pause (Resume is the one clearing path — see
+ * {@link useResumeSchedule}).
+ */
+export function useSetScheduleEnabled(): UseSetScheduleEnabledReturn {
+  const stigmer = useStigmer();
+  const [isPending, setIsPending] = useState(false);
+  const [error, setError] = useState<Error | null>(null);
+
+  const setEnabled = useCallback(
+    async (schedule: Schedule, enabled: boolean): Promise<Schedule> => {
+      if (!schedule.spec) {
+        throw new Error(
+          "Cannot toggle this schedule: it has no spec. Pass a schedule " +
+            "as returned by the server (get/getByReference).",
+        );
+      }
+
+      setIsPending(true);
+      setError(null);
+      try {
+        const updated = clone(ScheduleSchema, schedule);
+        updated.spec!.enabled = enabled;
+
+        const applied = await stigmer.manifest.apply(
+          manifestDocumentForResource(updated),
+        );
+        toast.success(enabled ? "Schedule enabled" : "Schedule disabled");
+        return applied.message as Schedule;
+      } catch (err) {
+        const wrapped = toError(err);
+        setError(wrapped);
+        toast.error(getUserMessage(err));
+        throw wrapped;
+      } finally {
+        setIsPending(false);
+      }
+    },
+    [stigmer],
+  );
+
+  return useMemo(
+    () => ({ setEnabled, isPending, error }),
+    [setEnabled, isPending, error],
+  );
+}

package/src/schedule/useTriggerSchedule.ts

@@ -0,0 +1,90 @@
+"use client";
+
+import { useCallback, useMemo, useState } from "react";
+import {
+  ScheduleRunOutcome,
+  type ScheduleTriggerResult,
+} from "@stigmer/protos/ai/stigmer/agentic/schedule/v1/io_pb";
+import { getUserMessage } from "@stigmer/sdk";
+import { useStigmer } from "../hooks.js";
+import { toast } from "../feedback/toast.js";
+import { toError } from "../internal/toError.js";
+
+/** Return value of {@link useTriggerSchedule}. */
+export interface UseTriggerScheduleReturn {
+  /**
+   * Fire the schedule once, now — a real agent execution, outside the
+   * cron cadence. Resolves with the {@link ScheduleTriggerResult}: the
+   * run's REAL outcome (started with an execution id, or refused with the
+   * gate's copy), so a caller can navigate to the execution or surface
+   * the refusal. Refetch the schedule afterwards to pick up the freshly
+   * stamped `status.last_fire_at` / `status.last_execution_id`.
+   */
+  readonly triggerSchedule: (scheduleId: string) => Promise<ScheduleTriggerResult>;
+  /** `true` while the trigger request is in flight. */
+  readonly isTriggering: boolean;
+  /** Error from the last failed or refused trigger, or `null` when healthy. */
+  readonly error: Error | null;
+}
+
+/**
+ * Behavior hook that fires a schedule once, immediately, and reports the
+ * run's real outcome (project DD-017 D-5/D-6).
+ *
+ * The trigger is a two-level contract, and this hook honors both levels:
+ *
+ * - A **gRPC error** means the trigger itself was refused — a disabled
+ *   schedule answers `FAILED_PRECONDITION` with copy that names the
+ *   remedy ("enable it before triggering"). The error toast relays that
+ *   copy verbatim (byte-identical across editions) and the promise
+ *   rejects.
+ * - A **success** means the fire happened. The result's `outcome` then
+ *   says what the RUN did: `STARTED` (an execution was created — a
+ *   success toast), or `REFUSED` / `TARGET_MISSING` (a launch gate said
+ *   no — an error toast carrying the gate's `refusalReason` verbatim).
+ *   The promise RESOLVES in every one of these cases: a refused run is a
+ *   successful trigger honestly reported, and the caller decides what to
+ *   do with it (navigate to the execution, show the reason).
+ *
+ * Triggering starts a real, billable execution — gate the call behind a
+ * confirmation (the detail view uses `ConfirmDialog`).
+ */
+export function useTriggerSchedule(): UseTriggerScheduleReturn {
+  const stigmer = useStigmer();
+  const [isTriggering, setIsTriggering] = useState(false);
+  const [error, setError] = useState<Error | null>(null);
+
+  const triggerSchedule = useCallback(
+    async (scheduleId: string): Promise<ScheduleTriggerResult> => {
+      setIsTriggering(true);
+      setError(null);
+      try {
+        const result = await stigmer.schedule.trigger(scheduleId);
+        if (result.outcome === ScheduleRunOutcome.STARTED) {
+          toast.success("Run started");
+        } else {
+          // The fire happened but the run was refused — surface the
+          // gate's own copy, never a generic message. The promise still
+          // resolves; the caller renders the reason inline too.
+          toast.error(
+            result.refusalReason || "The run was refused by a launch gate",
+          );
+        }
+        return result;
+      } catch (err) {
+        const wrapped = toError(err);
+        setError(wrapped);
+        toast.error(getUserMessage(err));
+        throw wrapped;
+      } finally {
+        setIsTriggering(false);
+      }
+    },
+    [stigmer],
+  );
+
+  return useMemo(
+    () => ({ triggerSchedule, isTriggering, error }),
+    [triggerSchedule, isTriggering, error],
+  );
+}