@checkstack/healthcheck-frontend 0.2.0 → 0.4.0

package/CHANGELOG.md

@@ -1,5 +1,176 @@
 # @checkstack/healthcheck-frontend
 
+## 0.4.0
+
+### Minor Changes
+
+- 7a23261: ## TanStack Query Integration
+
+  Migrated all frontend components to use `usePluginClient` hook with TanStack Query integration, replacing the legacy `forPlugin()` pattern.
+
+  ### New Features
+
+  - **`usePluginClient` hook**: Provides type-safe access to plugin APIs with `.useQuery()` and `.useMutation()` methods
+  - **Automatic request deduplication**: Multiple components requesting the same data share a single network request
+  - **Built-in caching**: Configurable stale time and cache duration per query
+  - **Loading/error states**: TanStack Query provides `isLoading`, `error`, `isRefetching` states automatically
+  - **Background refetching**: Stale data is automatically refreshed when components mount
+
+  ### Contract Changes
+
+  All RPC contracts now require `operationType: "query"` or `operationType: "mutation"` metadata:
+
+  ```typescript
+  const getItems = proc()
+    .meta({ operationType: "query", access: [access.read] })
+    .output(z.array(itemSchema))
+    .query();
+
+  const createItem = proc()
+    .meta({ operationType: "mutation", access: [access.manage] })
+    .input(createItemSchema)
+    .output(itemSchema)
+    .mutation();
+  ```
+
+  ### Migration
+
+  ```typescript
+  // Before (forPlugin pattern)
+  const api = useApi(myPluginApiRef);
+  const [items, setItems] = useState<Item[]>([]);
+  useEffect(() => {
+    api.getItems().then(setItems);
+  }, [api]);
+
+  // After (usePluginClient pattern)
+  const client = usePluginClient(MyPluginApi);
+  const { data: items, isLoading } = client.getItems.useQuery({});
+  ```
+
+  ### Bug Fixes
+
+  - Fixed `rpc.test.ts` test setup for middleware type inference
+  - Fixed `SearchDialog` to use `setQuery` instead of deprecated `search` method
+  - Fixed null→undefined warnings in notification and queue frontends
+
+### Patch Changes
+
+- Updated dependencies [180be38]
+- Updated dependencies [7a23261]
+  - @checkstack/dashboard-frontend@0.2.0
+  - @checkstack/frontend-api@0.2.0
+  - @checkstack/common@0.3.0
+  - @checkstack/auth-frontend@0.3.0
+  - @checkstack/catalog-common@1.2.0
+  - @checkstack/healthcheck-common@0.4.0
+  - @checkstack/ui@0.2.1
+  - @checkstack/signal-frontend@0.0.7
+
+## 0.3.0
+
+### Minor Changes
+
+- 9faec1f: # Unified AccessRule Terminology Refactoring
+
+  This release completes a comprehensive terminology refactoring from "permission" to "accessRule" across the entire codebase, establishing a consistent and modern access control vocabulary.
+
+  ## Changes
+
+  ### Core Infrastructure (`@checkstack/common`)
+
+  - Introduced `AccessRule` interface as the primary access control type
+  - Added `accessPair()` helper for creating read/manage access rule pairs
+  - Added `access()` builder for individual access rules
+  - Replaced `Permission` type with `AccessRule` throughout
+
+  ### API Changes
+
+  - `env.registerPermissions()` → `env.registerAccessRules()`
+  - `meta.permissions` → `meta.access` in RPC contracts
+  - `usePermission()` → `useAccess()` in frontend hooks
+  - Route `permission:` field → `accessRule:` field
+
+  ### UI Changes
+
+  - "Roles & Permissions" tab → "Roles & Access Rules"
+  - "You don't have permission..." → "You don't have access..."
+  - All permission-related UI text updated
+
+  ### Documentation & Templates
+
+  - Updated 18 documentation files with AccessRule terminology
+  - Updated 7 scaffolding templates with `accessPair()` pattern
+  - All code examples use new AccessRule API
+
+  ## Migration Guide
+
+  ### Backend Plugins
+
+  ```diff
+  - import { permissionList } from "./permissions";
+  - env.registerPermissions(permissionList);
+  + import { accessRules } from "./access";
+  + env.registerAccessRules(accessRules);
+  ```
+
+  ### RPC Contracts
+
+  ```diff
+  - .meta({ userType: "user", permissions: [permissions.read.id] })
+  + .meta({ userType: "user", access: [access.read] })
+  ```
+
+  ### Frontend Hooks
+
+  ```diff
+  - const canRead = accessApi.usePermission(permissions.read.id);
+  + const canRead = accessApi.useAccess(access.read);
+  ```
+
+  ### Routes
+
+  ```diff
+  - permission: permissions.entityRead.id,
+  + accessRule: access.read,
+  ```
+
+- 827b286: Add array assertion operators for string array fields
+
+  New operators for asserting on array fields (e.g., playerNames in RCON collectors):
+
+  - **includes** - Check if array contains a specific value
+  - **notIncludes** - Check if array does NOT contain a specific value
+  - **lengthEquals** - Check if array length equals a value
+  - **lengthGreaterThan** - Check if array length is greater than a value
+  - **lengthLessThan** - Check if array length is less than a value
+  - **isEmpty** - Check if array is empty
+  - **isNotEmpty** - Check if array has at least one element
+
+  Also exports a new `arrayField()` schema factory for creating array assertion schemas.
+
+### Patch Changes
+
+- f533141: Enforce health result factory function usage via branded types
+
+  - Added `healthResultSchema()` builder that enforces the use of factory functions at compile-time
+  - Added `healthResultArray()` factory for array fields (e.g., DNS resolved values)
+  - Added branded `HealthResultField<T>` type to mark schemas created by factory functions
+  - Consolidated `ChartType` and `HealthResultMeta` into `@checkstack/common` as single source of truth
+  - Updated all 12 health check strategies and 11 collectors to use `healthResultSchema()`
+  - Using raw `z.number()` etc. inside `healthResultSchema()` now causes a TypeScript error
+
+- Updated dependencies [9faec1f]
+- Updated dependencies [95eeec7]
+- Updated dependencies [f533141]
+  - @checkstack/auth-frontend@0.2.0
+  - @checkstack/catalog-common@1.1.0
+  - @checkstack/common@0.2.0
+  - @checkstack/frontend-api@0.1.0
+  - @checkstack/healthcheck-common@0.3.0
+  - @checkstack/ui@0.2.0
+  - @checkstack/signal-frontend@0.0.6
+
 ## 0.2.0
 
 ### Minor Changes

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@checkstack/healthcheck-frontend",
-  "version": "0.2.0",
+  "version": "0.4.0",
   "type": "module",
   "main": "src/index.tsx",
   "scripts": {
@@ -12,6 +12,7 @@
     "@checkstack/auth-frontend": "workspace:*",
     "@checkstack/catalog-common": "workspace:*",
     "@checkstack/common": "workspace:*",
+    "@checkstack/dashboard-frontend": "workspace:*",
     "@checkstack/frontend-api": "workspace:*",
     "@checkstack/healthcheck-common": "workspace:*",
     "@checkstack/signal-frontend": "workspace:*",

package/src/api.ts

@@ -1,7 +1,3 @@
-import { createApiRef } from "@checkstack/frontend-api";
-import { HealthCheckApi } from "@checkstack/healthcheck-common";
-import type { InferClient } from "@checkstack/common";
-
 // Re-export types for convenience
 export type {
   HealthCheckConfiguration,
@@ -9,9 +5,5 @@ export type {
   HealthCheckRun,
   HealthCheckRunPublic,
 } from "@checkstack/healthcheck-common";
-
-// HealthCheckApiClient type inferred from the client definition
-export type HealthCheckApiClient = InferClient<typeof HealthCheckApi>;
-
-export const healthCheckApiRef =
-  createApiRef<HealthCheckApiClient>("healthcheck-api");
+// Client definition is in @checkstack/healthcheck-common - use with usePluginClient
+export { HealthCheckApi } from "@checkstack/healthcheck-common";

package/src/auto-charts/schema-parser.ts

@@ -7,8 +7,8 @@
  * Supports nested schemas under `collectors.*` for per-collector metrics.
  */
 
-import type { ChartType } from "@checkstack/healthcheck-common";
 import type {
+  ChartType,
   JsonSchemaPropertyCore,
   JsonSchemaBase,
 } from "@checkstack/common";

package/src/auto-charts/useStrategySchemas.ts

@@ -7,8 +7,8 @@
  */
 
 import { useEffect, useState } from "react";
-import { useApi } from "@checkstack/frontend-api";
-import { healthCheckApiRef } from "../api";
+import { usePluginClient } from "@checkstack/frontend-api";
+import { HealthCheckApi } from "../api";
 
 interface StrategySchemas {
   resultSchema: Record<string, unknown> | undefined;
@@ -28,59 +28,50 @@ export function useStrategySchemas(strategyId: string): {
   schemas: StrategySchemas | undefined;
   loading: boolean;
 } {
-  const api = useApi(healthCheckApiRef);
+  const healthCheckClient = usePluginClient(HealthCheckApi);
   const [schemas, setSchemas] = useState<StrategySchemas | undefined>();
   const [loading, setLoading] = useState(true);
 
+  // Fetch strategies with useQuery
+  const { data: strategies } = healthCheckClient.getStrategies.useQuery({});
+
+  // Fetch collectors with useQuery
+  const { data: collectors } = healthCheckClient.getCollectors.useQuery(
+    { strategyId },
+    { enabled: !!strategyId }
+  );
+
   useEffect(() => {
-    let cancelled = false;
-
-    async function fetchSchemas() {
-      try {
-        // Fetch strategy and collectors in parallel
-        const [strategies, collectors] = await Promise.all([
-          api.getStrategies(),
-          api.getCollectors({ strategyId }),
-        ]);
-
-        const strategy = strategies.find((s) => s.id === strategyId);
-
-        if (!cancelled && strategy) {
-          // Build collector schemas object for nesting under resultSchema.properties.collectors
-          const collectorProperties: Record<string, unknown> = {};
-          for (const collector of collectors) {
-            // Use full ID so it matches stored data keys like "healthcheck-http.request"
-            collectorProperties[collector.id] = collector.resultSchema;
-          }
-
-          // Merge collector schemas into strategy result schema
-          const mergedResultSchema = mergeCollectorSchemas(
-            strategy.resultSchema as Record<string, unknown> | undefined,
-            collectorProperties
-          );
-
-          setSchemas({
-            resultSchema: mergedResultSchema,
-            aggregatedResultSchema:
-              (strategy.aggregatedResultSchema as Record<string, unknown>) ??
-              undefined,
-          });
-        }
-      } catch (error) {
-        console.error("Failed to fetch strategy schemas:", error);
-      } finally {
-        if (!cancelled) {
-          setLoading(false);
-        }
-      }
+    if (!strategies || !collectors) {
+      return;
     }
 
-    fetchSchemas();
+    const strategy = strategies.find((s) => s.id === strategyId);
 
-    return () => {
-      cancelled = true;
-    };
-  }, [api, strategyId]);
+    if (strategy) {
+      // Build collector schemas object for nesting under resultSchema.properties.collectors
+      const collectorProperties: Record<string, unknown> = {};
+      for (const collector of collectors) {
+        // Use full ID so it matches stored data keys like "healthcheck-http.request"
+        collectorProperties[collector.id] = collector.resultSchema;
+      }
+
+      // Merge collector schemas into strategy result schema
+      const mergedResultSchema = mergeCollectorSchemas(
+        strategy.resultSchema as Record<string, unknown> | undefined,
+        collectorProperties
+      );
+
+      setSchemas({
+        resultSchema: mergedResultSchema,
+        aggregatedResultSchema:
+          (strategy.aggregatedResultSchema as Record<string, unknown>) ??
+          undefined,
+      });
+    }
+
+    setLoading(false);
+  }, [strategies, collectors, strategyId]);
 
   return { schemas, loading };
 }

package/src/components/AssertionBuilder.tsx

@@ -81,6 +81,13 @@ const OPERATORS: Record<FieldType, { value: string; label: string }[]> = {
   ],
   enum: [{ value: "equals", label: "Equals" }],
   array: [
+    { value: "includes", label: "Includes" },
+    { value: "notIncludes", label: "Not Includes" },
+    { value: "lengthEquals", label: "Length Equals" },
+    { value: "lengthGreaterThan", label: "Length Greater Than" },
+    { value: "lengthLessThan", label: "Length Less Than" },
+    { value: "isEmpty", label: "Is Empty" },
+    { value: "isNotEmpty", label: "Is Not Empty" },
     { value: "exists", label: "Exists" },
     { value: "notExists", label: "Not Exists" },
   ],
@@ -98,6 +105,7 @@ const OPERATORS: Record<FieldType, { value: string; label: string }[]> = {
 // Operators that don't need a value input
 const VALUE_LESS_OPERATORS = new Set([
   "isEmpty",
+  "isNotEmpty",
   "isTrue",
   "isFalse",
   "exists",

package/src/components/HealthCheckDiagram.tsx

@@ -44,20 +44,20 @@ export function HealthCheckDiagram({
 }
 
 /**
- * Wrapper that shows permission message when user lacks access.
+ * Wrapper that shows access message when user lacks access.
  */
-export function HealthCheckDiagramPermissionGate({
-  hasPermission,
+export function HealthCheckDiagramAccessGate({
+  hasAccess,
   children,
 }: {
-  hasPermission: boolean;
+  hasAccess: boolean;
   children: React.ReactNode;
 }) {
-  if (!hasPermission) {
+  if (!hasAccess) {
     return (
       <InfoBanner variant="info">
         Additional strategy-specific visualizations are available with the
-        &quot;Read Health Check Details&quot; permission.
+        &quot;Read Health Check Details&quot; access rule.
       </InfoBanner>
     );
   }

package/src/components/HealthCheckHistory.tsx

@@ -1,6 +1,5 @@
-import React, { useEffect, useState } from "react";
-import { useApi, type SlotContext } from "@checkstack/frontend-api";
-import { healthCheckApiRef, HealthCheckRunPublic } from "../api";
+import { usePluginClient, type SlotContext } from "@checkstack/frontend-api";
+import { HealthCheckApi } from "../api";
 import { SystemDetailsSlot } from "@checkstack/catalog-common";
 import {
   Table,
@@ -25,18 +24,15 @@ export const HealthCheckHistory: React.FC<SlotProps> = (props) => {
   const { system, configurationId, limit } = props as Props;
   const systemId = system?.id;
 
-  const healthCheckApi = useApi(healthCheckApiRef);
-  const [history, setHistory] = useState<HealthCheckRunPublic[]>([]);
-  const [loading, setLoading] = useState(true);
+  const healthCheckClient = usePluginClient(HealthCheckApi);
 
-  useEffect(() => {
-    // If it's used in a context that doesn't provide systemId or configurationId,
-    // we might want to skip or handle it.
-    healthCheckApi
-      .getHistory({ systemId, configurationId, limit })
-      .then((response) => setHistory(response.runs))
-      .finally(() => setLoading(false));
-  }, [healthCheckApi, systemId, configurationId, limit]);
+  // Fetch history with useQuery
+  const { data, isLoading: loading } = healthCheckClient.getHistory.useQuery(
+    { systemId, configurationId, limit },
+    { enabled: true }
+  );
+
+  const history = data?.runs ?? [];
 
   if (loading) return <LoadingSpinner />;
 

package/src/components/HealthCheckMenuItems.tsx

@@ -3,20 +3,17 @@ import { Link } from "react-router-dom";
 import { Activity } from "lucide-react";
 import type { UserMenuItemsContext } from "@checkstack/frontend-api";
 import { DropdownMenuItem } from "@checkstack/ui";
-import { qualifyPermissionId, resolveRoute } from "@checkstack/common";
+import { resolveRoute } from "@checkstack/common";
 import {
   healthcheckRoutes,
-  permissions,
+  healthCheckAccess,
   pluginMetadata,
 } from "@checkstack/healthcheck-common";
 
 export const HealthCheckMenuItems = ({
-  permissions: userPerms,
+  accessRules: userPerms,
 }: UserMenuItemsContext) => {
-  const qualifiedId = qualifyPermissionId(
-    pluginMetadata,
-    permissions.healthCheckRead
-  );
+  const qualifiedId = `${pluginMetadata.pluginId}.${healthCheckAccess.configuration.read.id}`;
   const canRead = userPerms.includes("*") || userPerms.includes(qualifiedId);
 
   if (!canRead) {

package/src/components/HealthCheckSystemOverview.tsx

@@ -1,9 +1,11 @@
-import React, { useState } from "react";
-import { useApi, type SlotContext } from "@checkstack/frontend-api";
+import React, { useState, useCallback } from "react";
+import { usePluginClient, type SlotContext } from "@checkstack/frontend-api";
 import { useSignal } from "@checkstack/signal-frontend";
-import { healthCheckApiRef } from "../api";
 import { SystemDetailsSlot } from "@checkstack/catalog-common";
-import { HEALTH_CHECK_RUN_COMPLETED } from "@checkstack/healthcheck-common";
+import {
+  HEALTH_CHECK_RUN_COMPLETED,
+  HealthCheckApi,
+} from "@checkstack/healthcheck-common";
 import {
   HealthBadge,
   LoadingSpinner,
@@ -16,6 +18,7 @@ import {
   Tooltip,
   Pagination,
   usePagination,
+  usePaginationSync,
   DateRangeFilter,
 } from "@checkstack/ui";
 import { formatDistanceToNow } from "date-fns";
@@ -50,7 +53,7 @@ interface ExpandedRowProps {
 }
 
 const ExpandedDetails: React.FC<ExpandedRowProps> = ({ item, systemId }) => {
-  const api = useApi(healthCheckApiRef);
+  const healthCheckClient = usePluginClient(HealthCheckApi);
 
   // Date range state for filtering
   const [dateRange, setDateRange] = useState<{
@@ -79,42 +82,33 @@ const ExpandedDetails: React.FC<ExpandedRowProps> = ({ item, systemId }) => {
     limit: 1000,
   });
 
-  // Paginated history for the table
+  // Pagination state for history table
+  const pagination = usePagination({ defaultLimit: 10 });
+
+  // Fetch paginated history with useQuery
   const {
-    items: runs,
-    loading,
-    pagination,
-  } = usePagination({
-    fetchFn: (params: {
-      limit: number;
-      offset: number;
-      systemId: string;
-      configurationId: string;
-      startDate?: Date;
-    }) =>
-      api.getHistory({
-        systemId: params.systemId,
-        configurationId: params.configurationId,
-        limit: params.limit,
-        offset: params.offset,
-        startDate: params.startDate,
-        // Don't pass endDate - backend defaults to 'now' so new runs are included
-      }),
-    getItems: (response) => response.runs,
-    getTotal: (response) => response.total,
-    extraParams: {
-      systemId,
-      configurationId: item.configurationId,
-      startDate: dateRange.startDate,
-    },
-    defaultLimit: 10,
+    data: historyData,
+    isLoading: loading,
+    refetch,
+  } = healthCheckClient.getHistory.useQuery({
+    systemId,
+    configurationId: item.configurationId,
+    limit: pagination.limit,
+    offset: pagination.offset,
+    startDate: dateRange.startDate,
+    // Don't pass endDate - backend defaults to 'now' so new runs are included
   });
 
+  // Sync total from response
+  usePaginationSync(pagination, historyData?.total);
+
+  const runs = historyData?.runs ?? [];
+
   // Listen for realtime health check updates to refresh history table
   // Charts are refreshed automatically by useHealthCheckData
   useSignal(HEALTH_CHECK_RUN_COMPLETED, ({ systemId: changedId }) => {
     if (changedId === systemId) {
-      pagination.silentRefetch();
+      void refetch();
     }
   });
 
@@ -248,100 +242,49 @@ const ExpandedDetails: React.FC<ExpandedRowProps> = ({ item, systemId }) => {
 
 export function HealthCheckSystemOverview(props: SlotProps) {
   const systemId = props.system.id;
-  const api = useApi(healthCheckApiRef);
+  const healthCheckClient = usePluginClient(HealthCheckApi);
 
-  // Fetch health check overview
-  const [overview, setOverview] = React.useState<HealthCheckOverviewItem[]>([]);
-  const [initialLoading, setInitialLoading] = React.useState(true);
   const [expandedRow, setExpandedRow] = React.useState<string | undefined>();
 
-  const fetchOverview = React.useCallback(() => {
-    api.getSystemHealthOverview({ systemId }).then((data) => {
-      setOverview(
-        data.checks.map((check) => ({
-          configurationId: check.configurationId,
-          strategyId: check.strategyId,
-          name: check.configurationName,
-          state: check.status,
-          intervalSeconds: check.intervalSeconds,
-          lastRunAt: check.recentRuns[0]?.timestamp
-            ? new Date(check.recentRuns[0].timestamp)
-            : undefined,
-          stateThresholds: check.stateThresholds,
-          recentStatusHistory: check.recentRuns.map((r) => r.status),
-        }))
-      );
-      setInitialLoading(false);
-    });
-  }, [api, systemId]);
-
-  React.useEffect(() => {
-    fetchOverview();
-  }, [fetchOverview]);
-
-  // Listen for realtime health check updates - merge into existing state to avoid remounting expanded content
-  useSignal(HEALTH_CHECK_RUN_COMPLETED, ({ systemId: changedId }) => {
-    if (changedId === systemId) {
-      // Fetch fresh data but merge it into existing state to preserve object identity
-      // for unchanged items, preventing unnecessary re-renders of expanded content
-      api.getSystemHealthOverview({ systemId }).then((data) => {
-        setOverview((prev) => {
-          // Create a map of new items for quick lookup
-          const newItemsMap = new Map(
-            data.checks.map((item) => [item.configurationId, item])
-          );
-
-          // Update existing items in place, add new ones
-          const merged = prev.map((existing) => {
-            const updated = newItemsMap.get(existing.configurationId);
-            if (updated) {
-              newItemsMap.delete(existing.configurationId);
-              // Map API response to our internal format
-              const mappedItem: HealthCheckOverviewItem = {
-                configurationId: updated.configurationId,
-                strategyId: updated.strategyId,
-                name: updated.configurationName,
-                state: updated.status,
-                intervalSeconds: updated.intervalSeconds,
-                lastRunAt: updated.recentRuns[0]?.timestamp
-                  ? new Date(updated.recentRuns[0].timestamp)
-                  : undefined,
-                stateThresholds: updated.stateThresholds,
-                recentStatusHistory: updated.recentRuns.map((r) => r.status),
-              };
-              // Return updated data but preserve reference if nothing changed
-              return JSON.stringify(existing) === JSON.stringify(mappedItem)
-                ? existing
-                : mappedItem;
-            }
-            return existing;
-          });
-
-          // Add any new items that weren't in the previous list
-          for (const newItem of newItemsMap.values()) {
-            merged.push({
-              configurationId: newItem.configurationId,
-              strategyId: newItem.strategyId,
-              name: newItem.configurationName,
-              state: newItem.status,
-              intervalSeconds: newItem.intervalSeconds,
-              lastRunAt: newItem.recentRuns[0]?.timestamp
-                ? new Date(newItem.recentRuns[0].timestamp)
-                : undefined,
-              stateThresholds: newItem.stateThresholds,
-              recentStatusHistory: newItem.recentRuns.map((r) => r.status),
-            });
-          }
-
-          // Remove items that no longer exist
-          return merged.filter((item) =>
-            data.checks.some((c) => c.configurationId === item.configurationId)
-          );
-        });
-      });
-    }
+  // Fetch health check overview using useQuery
+  const {
+    data: overviewData,
+    isLoading: initialLoading,
+    refetch,
+  } = healthCheckClient.getSystemHealthOverview.useQuery({
+    systemId,
   });
 
+  // Transform API response to component format
+  const overview: HealthCheckOverviewItem[] = React.useMemo(() => {
+    if (!overviewData) return [];
+    return overviewData.checks.map((check) => ({
+      configurationId: check.configurationId,
+      strategyId: check.strategyId,
+      name: check.configurationName,
+      state: check.status,
+      intervalSeconds: check.intervalSeconds,
+      lastRunAt: check.recentRuns[0]?.timestamp
+        ? new Date(check.recentRuns[0].timestamp)
+        : undefined,
+      stateThresholds: check.stateThresholds,
+      recentStatusHistory: check.recentRuns.map((r) => r.status),
+    }));
+  }, [overviewData]);
+
+  // Listen for realtime health check updates to refresh overview
+  useSignal(
+    HEALTH_CHECK_RUN_COMPLETED,
+    useCallback(
+      ({ systemId: changedId }) => {
+        if (changedId === systemId) {
+          void refetch();
+        }
+      },
+      [systemId, refetch]
+    )
+  );
+
   if (initialLoading) {
     return <LoadingSpinner />;
   }