@stigmer/react 0.0.36 → 0.0.40

package/src/search/useResourceCount.ts

@@ -0,0 +1,102 @@
+"use client";
+
+import { useCallback, useEffect, useState } from "react";
+import type { ListParams, ListResult } from "@stigmer/sdk";
+import type { ResourceListScope } from "./useResourceList";
+
+export interface UseResourceCountOptions {
+  /** Text query to filter results before counting. */
+  readonly query?: string;
+  /**
+   * Controls resource visibility scope.
+   *
+   * - `"org"` — all resources owned by the given organization, regardless of visibility.
+   * - `"all"` — all resources the caller is authorized to access, across all organizations.
+   *
+   * @default "org"
+   */
+  readonly scope?: ResourceListScope;
+}
+
+export interface UseResourceCountReturn {
+  /**
+   * Total count of matching resources. `undefined` until the first
+   * successful fetch completes — distinguishes "not yet loaded" from
+   * "loaded, count is zero."
+   */
+  readonly count: number | undefined;
+  readonly isLoading: boolean;
+  readonly error: string | null;
+  readonly refetch: () => void;
+}
+
+/**
+ * Internal hook that fetches the total count of a resource type.
+ *
+ * Powers the public resource count hooks (`useAgentCount`, `useSkillCount`,
+ * `useMcpServerCount`) — not exported from the public API.
+ *
+ * Issues a minimal `list()` call with `page: { num: 1, size: 1 }` and
+ * reads only `totalCount` from the response. The single returned entry
+ * is discarded — no entries state is maintained.
+ *
+ * Unlike {@link useResourceList} which manages full pagination state
+ * (entries, page, pageSize, totalPages), this hook tracks only the
+ * scalar count, resulting in fewer state updates and re-renders.
+ */
+export function useResourceCount(
+  listFn: (params: ListParams) => Promise<ListResult>,
+  org: string | null,
+  options?: UseResourceCountOptions,
+): UseResourceCountReturn {
+  const [count, setCount] = useState<number | undefined>(undefined);
+  const [isLoading, setIsLoading] = useState(false);
+  const [error, setError] = useState<string | null>(null);
+  const [fetchKey, setFetchKey] = useState(0);
+
+  const query = options?.query;
+  const scope = options?.scope ?? "org";
+
+  const refetch = useCallback(() => setFetchKey((k) => k + 1), []);
+
+  useEffect(() => {
+    if (!org) {
+      setCount(undefined);
+      setIsLoading(false);
+      setError(null);
+      return;
+    }
+
+    const cancelled = { current: false };
+    setIsLoading(true);
+    setError(null);
+
+    const params: ListParams = {
+      org: scope === "all" ? "" : org,
+      query: query || undefined,
+      excludePublic: false,
+      page: { num: 1, size: 1 },
+    };
+
+    listFn(params).then(
+      (result) => {
+        if (cancelled.current) return;
+        setCount(result.totalCount);
+        setIsLoading(false);
+      },
+      (err) => {
+        if (cancelled.current) return;
+        setError(
+          err instanceof Error ? err.message : "Failed to load resource count",
+        );
+        setIsLoading(false);
+      },
+    );
+
+    return () => {
+      cancelled.current = true;
+    };
+  }, [listFn, org, query, scope, fetchKey]);
+
+  return { count, isLoading, error, refetch };
+}

package/src/search/useResourceList.ts

@@ -0,0 +1,128 @@
+"use client";
+
+import { useCallback, useEffect, useRef, useState } from "react";
+import type { ListParams, ListResult } from "@stigmer/sdk";
+import type { SearchResult } from "@stigmer/protos/ai/stigmer/search/v1/io_pb";
+
+/**
+ * Scope controls resource listing boundaries.
+ *
+ * - `"org"` — resources owned by the active organization (public and private).
+ * - `"all"` — all resources the caller can access, across every organization.
+ */
+export type ResourceListScope = "org" | "all";
+
+export interface UseResourceListOptions {
+  /** Maximum results per page. @default 20 */
+  readonly pageSize?: number;
+  /** Page number (1-indexed). @default 1 */
+  readonly page?: number;
+  /** Text query to filter results. No debouncing is applied — the consumer controls timing. */
+  readonly query?: string;
+  /**
+   * Controls resource visibility scope.
+   *
+   * - `"org"` — all resources owned by the given organization, regardless of visibility.
+   * - `"all"` — all resources the caller is authorized to access, across all organizations.
+   *
+   * @default "org"
+   */
+  readonly scope?: ResourceListScope;
+}
+
+export interface UseResourceListReturn {
+  readonly entries: readonly SearchResult[];
+  readonly totalCount: number;
+  readonly totalPages: number;
+  readonly currentPage: number;
+  readonly isLoading: boolean;
+  readonly error: string | null;
+  readonly refetch: () => void;
+}
+
+const DEFAULT_PAGE_SIZE = 20;
+const DEFAULT_PAGE = 1;
+
+/**
+ * Internal hook that provides paginated, scope-aware resource listing.
+ *
+ * Powers the public resource list hooks (`useAgentList`, `useSkillList`,
+ * `useMcpServerList`) — not exported from the public API.
+ *
+ * Unlike {@link useResourceSearch} which manages its own debounced query
+ * state for picker/type-ahead UX, this hook accepts all parameters
+ * externally, giving the consumer full control over query timing,
+ * pagination state, and scope toggling.
+ */
+export function useResourceList(
+  listFn: (params: ListParams) => Promise<ListResult>,
+  org: string | null,
+  options?: UseResourceListOptions,
+): UseResourceListReturn {
+  const [entries, setEntries] = useState<SearchResult[]>([]);
+  const [totalCount, setTotalCount] = useState(0);
+  const [totalPages, setTotalPages] = useState(0);
+  const [isLoading, setIsLoading] = useState(false);
+  const [error, setError] = useState<string | null>(null);
+  const [fetchKey, setFetchKey] = useState(0);
+
+  const pageSize = options?.pageSize ?? DEFAULT_PAGE_SIZE;
+  const page = options?.page ?? DEFAULT_PAGE;
+  const query = options?.query;
+  const scope = options?.scope ?? "org";
+
+  const refetch = useCallback(() => setFetchKey((k) => k + 1), []);
+
+  useEffect(() => {
+    if (!org) {
+      setEntries([]);
+      setTotalCount(0);
+      setTotalPages(0);
+      setIsLoading(false);
+      setError(null);
+      return;
+    }
+
+    const cancelled = { current: false };
+    setIsLoading(true);
+    setError(null);
+
+    const params: ListParams = {
+      org: scope === "all" ? "" : org,
+      query: query || undefined,
+      excludePublic: false,
+      page: { num: page, size: pageSize },
+    };
+
+    listFn(params).then(
+      (result) => {
+        if (cancelled.current) return;
+        setEntries([...result.entries]);
+        setTotalCount(result.totalCount);
+        setTotalPages(result.totalPages);
+        setIsLoading(false);
+      },
+      (err) => {
+        if (cancelled.current) return;
+        setError(
+          err instanceof Error ? err.message : "Failed to load resources",
+        );
+        setIsLoading(false);
+      },
+    );
+
+    return () => {
+      cancelled.current = true;
+    };
+  }, [listFn, org, query, scope, page, pageSize, fetchKey]);
+
+  return {
+    entries,
+    totalCount,
+    totalPages,
+    currentPage: page,
+    isLoading,
+    error,
+    refetch,
+  };
+}

package/src/search/useResourceSearch.ts

@@ -0,0 +1,90 @@
+"use client";
+
+import { useCallback, useEffect, useRef, useState } from "react";
+import type { ListParams, ListResult } from "@stigmer/sdk";
+import type { SearchResult } from "@stigmer/protos/ai/stigmer/search/v1/io_pb";
+
+export interface UseResourceSearchOptions {
+  /** Maximum results per page. @default 30 */
+  readonly pageSize?: number;
+  /** Debounce delay for query changes in milliseconds. @default 300 */
+  readonly debounceMs?: number;
+}
+
+export interface UseResourceSearchReturn {
+  readonly results: readonly SearchResult[];
+  readonly isLoading: boolean;
+  readonly error: string | null;
+  readonly query: string;
+  readonly setQuery: (query: string) => void;
+  readonly refetch: () => void;
+}
+
+const DEFAULT_PAGE_SIZE = 30;
+const DEFAULT_DEBOUNCE_MS = 300;
+
+/**
+ * Internal hook that powers both `useMcpServerSearch` and `useSkillSearch`.
+ *
+ * Wraps a `ListParams -> ListResult` function with query state management,
+ * debounced search, loading/error tracking, and cancellation-safe fetching.
+ *
+ * Not exported from the public API — consumers use the resource-specific
+ * hooks (`useMcpServerSearch`, `useSkillSearch`) instead.
+ */
+export function useResourceSearch(
+  listFn: (params: ListParams) => Promise<ListResult>,
+  org: string,
+  options?: UseResourceSearchOptions,
+): UseResourceSearchReturn {
+  const [results, setResults] = useState<SearchResult[]>([]);
+  const [isLoading, setIsLoading] = useState(false);
+  const [error, setError] = useState<string | null>(null);
+  const [query, setQuery] = useState("");
+  const [debouncedQuery, setDebouncedQuery] = useState("");
+  const [fetchKey, setFetchKey] = useState(0);
+
+  const pageSize = options?.pageSize ?? DEFAULT_PAGE_SIZE;
+  const debounceMs = options?.debounceMs ?? DEFAULT_DEBOUNCE_MS;
+
+  // Debounce query changes
+  useEffect(() => {
+    const timer = setTimeout(() => setDebouncedQuery(query), debounceMs);
+    return () => clearTimeout(timer);
+  }, [query, debounceMs]);
+
+  const refetch = useCallback(() => setFetchKey((k) => k + 1), []);
+
+  useEffect(() => {
+    const cancelled = { current: false };
+    setIsLoading(true);
+    setError(null);
+
+    const params: ListParams = {
+      org,
+      query: debouncedQuery || undefined,
+      page: { num: 1, size: pageSize },
+    };
+
+    listFn(params).then(
+      (result) => {
+        if (cancelled.current) return;
+        setResults([...result.entries]);
+        setIsLoading(false);
+      },
+      (err) => {
+        if (cancelled.current) return;
+        setError(
+          err instanceof Error ? err.message : "Failed to load resources",
+        );
+        setIsLoading(false);
+      },
+    );
+
+    return () => {
+      cancelled.current = true;
+    };
+  }, [listFn, org, debouncedQuery, pageSize, fetchKey]);
+
+  return { results, isLoading, error, query, setQuery, refetch };
+}

package/src/session/__tests__/group-sessions.test.ts

@@ -0,0 +1,113 @@
+import { describe, it, expect } from "vitest";
+import { create } from "@bufbuild/protobuf";
+import { timestampFromDate } from "@bufbuild/protobuf/wkt";
+import { SessionSchema } from "@stigmer/protos/ai/stigmer/agentic/session/v1/api_pb";
+import {
+  ApiResourceAuditStatusSchema,
+  ApiResourceAuditSchema,
+  ApiResourceAuditInfoSchema,
+} from "@stigmer/protos/ai/stigmer/commons/apiresource/status_pb";
+import { groupSessionsByTime, type SessionGroup } from "../group-sessions";
+
+const NOW = new Date("2026-03-18T14:00:00Z");
+
+function makeSession(date: Date | null) {
+  const session = create(SessionSchema);
+  if (date) {
+    const auditInfo = create(ApiResourceAuditInfoSchema);
+    auditInfo.createdAt = timestampFromDate(date);
+    const audit = create(ApiResourceAuditSchema);
+    audit.specAudit = auditInfo;
+    const status = create(ApiResourceAuditStatusSchema);
+    status.audit = audit;
+    session.status = status;
+  }
+  return session;
+}
+
+function daysAgo(days: number): Date {
+  const d = new Date(NOW);
+  d.setDate(d.getDate() - days);
+  return d;
+}
+
+function labels(groups: readonly SessionGroup[]): string[] {
+  return groups.map((g) => g.label);
+}
+
+describe("groupSessionsByTime", () => {
+  it("returns empty array for empty input", () => {
+    expect(groupSessionsByTime([], NOW)).toEqual([]);
+  });
+
+  it("groups a session created today into 'Today'", () => {
+    const groups = groupSessionsByTime([makeSession(NOW)], NOW);
+    expect(labels(groups)).toEqual(["Today"]);
+    expect(groups[0].sessions).toHaveLength(1);
+  });
+
+  it("groups a session from yesterday into 'Yesterday'", () => {
+    const groups = groupSessionsByTime([makeSession(daysAgo(1))], NOW);
+    expect(labels(groups)).toEqual(["Yesterday"]);
+  });
+
+  it("groups a session from 3 days ago into 'Previous 7 Days'", () => {
+    const groups = groupSessionsByTime([makeSession(daysAgo(3))], NOW);
+    expect(labels(groups)).toEqual(["Previous 7 Days"]);
+  });
+
+  it("groups a session from 15 days ago into 'Previous 30 Days'", () => {
+    const groups = groupSessionsByTime([makeSession(daysAgo(15))], NOW);
+    expect(labels(groups)).toEqual(["Previous 30 Days"]);
+  });
+
+  it("groups a session from 60 days ago into 'Older'", () => {
+    const groups = groupSessionsByTime([makeSession(daysAgo(60))], NOW);
+    expect(labels(groups)).toEqual(["Older"]);
+  });
+
+  it("omits empty groups from the result", () => {
+    const groups = groupSessionsByTime(
+      [makeSession(NOW), makeSession(daysAgo(60))],
+      NOW,
+    );
+    expect(labels(groups)).toEqual(["Today", "Older"]);
+  });
+
+  it("places sessions with missing timestamps in 'Older'", () => {
+    const groups = groupSessionsByTime([makeSession(null)], NOW);
+    expect(labels(groups)).toEqual(["Older"]);
+    expect(groups[0].sessions).toHaveLength(1);
+  });
+
+  it("preserves input order within each group", () => {
+    const s1 = makeSession(NOW);
+    const s2 = makeSession(NOW);
+    const s3 = makeSession(NOW);
+
+    const groups = groupSessionsByTime([s1, s2, s3], NOW);
+    expect(groups[0].sessions[0]).toBe(s1);
+    expect(groups[0].sessions[1]).toBe(s2);
+    expect(groups[0].sessions[2]).toBe(s3);
+  });
+
+  it("distributes sessions across all five buckets", () => {
+    const sessions = [
+      makeSession(NOW),
+      makeSession(daysAgo(1)),
+      makeSession(daysAgo(4)),
+      makeSession(daysAgo(20)),
+      makeSession(daysAgo(60)),
+    ];
+
+    const groups = groupSessionsByTime(sessions, NOW);
+    expect(labels(groups)).toEqual([
+      "Today",
+      "Yesterday",
+      "Previous 7 Days",
+      "Previous 30 Days",
+      "Older",
+    ]);
+    groups.forEach((g) => expect(g.sessions).toHaveLength(1));
+  });
+});