@checkstack/maintenance-frontend 0.1.0 → 0.3.0

package/CHANGELOG.md

@@ -1,5 +1,153 @@
 # @checkstack/maintenance-frontend
 
+## 0.3.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/maintenance-common@0.3.0
+  - @checkstack/ui@0.2.1
+  - @checkstack/signal-frontend@0.0.7
+
+## 0.2.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,
+  ```
+
+### Patch Changes
+
+- 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/maintenance-common@0.2.0
+  - @checkstack/ui@0.2.0
+  - @checkstack/signal-frontend@0.0.6
+
 ## 0.1.0
 
 ### Minor Changes

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@checkstack/maintenance-frontend",
-  "version": "0.1.0",
+  "version": "0.3.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/maintenance-common": "workspace:*",
     "@checkstack/signal-frontend": "workspace:*",

package/src/api.ts

@@ -1,10 +1,9 @@
-import { createApiRef } from "@checkstack/frontend-api";
-import { MaintenanceApi } from "@checkstack/maintenance-common";
-import type { InferClient } from "@checkstack/common";
-
-// MaintenanceApiClient type inferred from the client definition
-export type MaintenanceApiClient = InferClient<typeof MaintenanceApi>;
-
-export const maintenanceApiRef = createApiRef<MaintenanceApiClient>(
-  "plugin.maintenance.api"
-);
+// Re-export types for convenience
+export type {
+  MaintenanceWithSystems,
+  MaintenanceDetail,
+  MaintenanceUpdate,
+  MaintenanceStatus,
+} from "@checkstack/maintenance-common";
+// Client definition is in @checkstack/maintenance-common - use with usePluginClient
+export { MaintenanceApi } from "@checkstack/maintenance-common";

package/src/components/MaintenanceEditor.tsx

@@ -1,6 +1,6 @@
-import React, { useState, useEffect, useCallback } from "react";
-import { useApi } from "@checkstack/frontend-api";
-import { maintenanceApiRef } from "../api";
+import React, { useState, useEffect } from "react";
+import { usePluginClient } from "@checkstack/frontend-api";
+import { MaintenanceApi } from "../api";
 import type {
   MaintenanceWithSystems,
   MaintenanceUpdate,
@@ -42,7 +42,7 @@ export const MaintenanceEditor: React.FC<Props> = ({
   systems,
   onSave,
 }) => {
-  const api = useApi(maintenanceApiRef);
+  const maintenanceClient = usePluginClient(MaintenanceApi);
   const toast = useToast();
 
   // Maintenance fields
@@ -53,29 +53,45 @@ export const MaintenanceEditor: React.FC<Props> = ({
   const [selectedSystemIds, setSelectedSystemIds] = useState<Set<string>>(
     new Set()
   );
-  const [saving, setSaving] = useState(false);
 
   // Status update fields
   const [updates, setUpdates] = useState<MaintenanceUpdate[]>([]);
-  const [loadingUpdates, setLoadingUpdates] = useState(false);
   const [showUpdateForm, setShowUpdateForm] = useState(false);
 
-  const loadMaintenanceDetails = useCallback(
-    async (id: string) => {
-      setLoadingUpdates(true);
-      try {
-        const detail = await api.getMaintenance({ id });
-        if (detail) {
-          setUpdates(detail.updates);
-        }
-      } catch (error) {
-        console.error("Failed to load maintenance details:", error);
-      } finally {
-        setLoadingUpdates(false);
-      }
+  // Query for maintenance details (only when editing)
+  const { data: maintenanceDetail, refetch: refetchDetail } =
+    maintenanceClient.getMaintenance.useQuery(
+      { id: maintenance?.id ?? "" },
+      { enabled: !!maintenance?.id && open }
+    );
+
+  // Mutations
+  const createMutation = maintenanceClient.createMaintenance.useMutation({
+    onSuccess: () => {
+      toast.success("Maintenance created");
+      onSave();
     },
-    [api]
-  );
+    onError: (error) => {
+      toast.error(error instanceof Error ? error.message : "Failed to save");
+    },
+  });
+
+  const updateMutation = maintenanceClient.updateMaintenance.useMutation({
+    onSuccess: () => {
+      toast.success("Maintenance updated");
+      onSave();
+    },
+    onError: (error) => {
+      toast.error(error instanceof Error ? error.message : "Failed to save");
+    },
+  });
+
+  // Sync updates from query
+  useEffect(() => {
+    if (maintenanceDetail) {
+      setUpdates(maintenanceDetail.updates);
+    }
+  }, [maintenanceDetail]);
 
   // Reset form when maintenance changes
   useEffect(() => {
@@ -85,8 +101,6 @@ export const MaintenanceEditor: React.FC<Props> = ({
       setStartAt(new Date(maintenance.startAt));
       setEndAt(new Date(maintenance.endAt));
       setSelectedSystemIds(new Set(maintenance.systemIds));
-      // Load full maintenance with updates
-      loadMaintenanceDetails(maintenance.id);
     } else {
       // Default to 1 hour from now to 2 hours from now
       const now = new Date();
@@ -100,7 +114,7 @@ export const MaintenanceEditor: React.FC<Props> = ({
       setUpdates([]);
       setShowUpdateForm(false);
     }
-  }, [maintenance, open, loadMaintenanceDetails]);
+  }, [maintenance, open]);
 
   const handleSystemToggle = (systemId: string) => {
     setSelectedSystemIds((prev) => {
@@ -114,7 +128,7 @@ export const MaintenanceEditor: React.FC<Props> = ({
     });
   };
 
-  const handleSubmit = async () => {
+  const handleSubmit = () => {
     if (!title.trim()) {
       toast.error("Title is required");
       return;
@@ -128,46 +142,38 @@ export const MaintenanceEditor: React.FC<Props> = ({
       return;
     }
 
-    setSaving(true);
-    try {
-      if (maintenance) {
-        await api.updateMaintenance({
-          id: maintenance.id,
-          title,
-          description: description || undefined,
-          startAt,
-          endAt,
-          systemIds: [...selectedSystemIds],
-        });
-        toast.success("Maintenance updated");
-      } else {
-        await api.createMaintenance({
-          title,
-          description,
-          startAt,
-          endAt,
-          systemIds: [...selectedSystemIds],
-        });
-        toast.success("Maintenance created");
-      }
-      onSave();
-    } catch (error) {
-      const message = error instanceof Error ? error.message : "Failed to save";
-      toast.error(message);
-    } finally {
-      setSaving(false);
+    if (maintenance) {
+      updateMutation.mutate({
+        id: maintenance.id,
+        title,
+        description: description || undefined,
+        startAt,
+        endAt,
+        systemIds: [...selectedSystemIds],
+      });
+    } else {
+      createMutation.mutate({
+        title,
+        description,
+        startAt,
+        endAt,
+        systemIds: [...selectedSystemIds],
+      });
     }
   };
 
   const handleUpdateSuccess = () => {
     if (maintenance) {
-      loadMaintenanceDetails(maintenance.id);
+      void refetchDetail();
     }
     setShowUpdateForm(false);
     // Notify parent to refresh list (status may have changed)
     onSave();
   };
 
+  const saving = createMutation.isPending || updateMutation.isPending;
+  const loadingUpdates = false; // Now handled by useQuery
+
   return (
     <Dialog open={open} onOpenChange={onOpenChange}>
       <DialogContent size="xl">

package/src/components/MaintenanceMenuItems.tsx

@@ -3,20 +3,17 @@ import { Link } from "react-router-dom";
 import { Wrench } 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 {
   maintenanceRoutes,
-  permissions,
+  maintenanceAccess,
   pluginMetadata,
 } from "@checkstack/maintenance-common";
 
 export const MaintenanceMenuItems = ({
-  permissions: userPerms,
+  accessRules: userPerms,
 }: UserMenuItemsContext) => {
-  const qualifiedId = qualifyPermissionId(
-    pluginMetadata,
-    permissions.maintenanceManage
-  );
+  const qualifiedId = `${pluginMetadata.pluginId}.${maintenanceAccess.maintenance.manage.id}`;
   const canManage = userPerms.includes("*") || userPerms.includes(qualifiedId);
 
   if (!canManage) {

package/src/components/MaintenanceUpdateForm.tsx

@@ -1,6 +1,6 @@
 import React, { useState } from "react";
-import { useApi } from "@checkstack/frontend-api";
-import { maintenanceApiRef } from "../api";
+import { usePluginClient } from "@checkstack/frontend-api";
+import { MaintenanceApi } from "../api";
 import type { MaintenanceStatus } from "@checkstack/maintenance-common";
 import {
   Button,
@@ -30,37 +30,37 @@ export const MaintenanceUpdateForm: React.FC<MaintenanceUpdateFormProps> = ({
   onSuccess,
   onCancel,
 }) => {
-  const api = useApi(maintenanceApiRef);
+  const maintenanceClient = usePluginClient(MaintenanceApi);
   const toast = useToast();
 
   const [message, setMessage] = useState("");
   const [statusChange, setStatusChange] = useState<MaintenanceStatus | "">("");
-  const [isPosting, setIsPosting] = useState(false);
 
-  const handleSubmit = async () => {
-    if (!message.trim()) {
-      toast.error("Update message is required");
-      return;
-    }
-
-    setIsPosting(true);
-    try {
-      await api.addUpdate({
-        maintenanceId,
-        message,
-        statusChange: statusChange || undefined,
-      });
+  const addUpdateMutation = maintenanceClient.addUpdate.useMutation({
+    onSuccess: () => {
       toast.success("Update posted");
       setMessage("");
       setStatusChange("");
       onSuccess();
-    } catch (error) {
-      const errorMessage =
-        error instanceof Error ? error.message : "Failed to post update";
-      toast.error(errorMessage);
-    } finally {
-      setIsPosting(false);
+    },
+    onError: (error) => {
+      toast.error(
+        error instanceof Error ? error.message : "Failed to post update"
+      );
+    },
+  });
+
+  const handleSubmit = () => {
+    if (!message.trim()) {
+      toast.error("Update message is required");
+      return;
     }
+
+    addUpdateMutation.mutate({
+      maintenanceId,
+      message,
+      statusChange: statusChange || undefined,
+    });
   };
 
   return (
@@ -106,9 +106,9 @@ export const MaintenanceUpdateForm: React.FC<MaintenanceUpdateFormProps> = ({
         <Button
           size="sm"
           onClick={handleSubmit}
-          disabled={isPosting || !message.trim()}
+          disabled={addUpdateMutation.isPending || !message.trim()}
         >
-          {isPosting ? (
+          {addUpdateMutation.isPending ? (
             <>
               <Loader2 className="h-4 w-4 mr-1 animate-spin" />
               Posting...

package/src/components/SystemMaintenanceBadge.tsx

@@ -1,49 +1,64 @@
-import React, { useEffect, useState, useCallback } from "react";
-import { useApi, type SlotContext } from "@checkstack/frontend-api";
+import React from "react";
+import { usePluginClient, type SlotContext } from "@checkstack/frontend-api";
 import { useSignal } from "@checkstack/signal-frontend";
 import { SystemStateBadgesSlot } from "@checkstack/catalog-common";
-import { maintenanceApiRef } from "../api";
+import { MaintenanceApi } from "../api";
 import {
   MAINTENANCE_UPDATED,
   type MaintenanceWithSystems,
 } from "@checkstack/maintenance-common";
 import { Badge } from "@checkstack/ui";
+import { useSystemBadgeDataOptional } from "@checkstack/dashboard-frontend";
 
 type Props = SlotContext<typeof SystemStateBadgesSlot>;
 
+/**
+ * Checks if any maintenance is currently in progress.
+ */
+function hasActiveMaintenance(maintenances: MaintenanceWithSystems[]): boolean {
+  return maintenances.some((m) => m.status === "in_progress");
+}
+
 /**
  * Displays a maintenance badge for a system when it has an active maintenance.
  * Shows nothing if no active maintenance.
+ *
+ * When rendered within SystemBadgeDataProvider, uses bulk-fetched data.
+ * Otherwise, falls back to individual fetch.
+ *
  * Listens for realtime updates via signals.
  */
 export const SystemMaintenanceBadge: React.FC<Props> = ({ system }) => {
-  const api = useApi(maintenanceApiRef);
-  const [hasActiveMaintenance, setHasActiveMaintenance] = useState(false);
-
-  const refetch = useCallback(() => {
-    if (!system?.id) return;
-
-    api
-      .getMaintenancesForSystem({ systemId: system.id })
-      .then((maintenances: MaintenanceWithSystems[]) => {
-        const active = maintenances.some((m) => m.status === "in_progress");
-        setHasActiveMaintenance(active);
-      })
-      .catch(console.error);
-  }, [system?.id, api]);
-
-  // Initial fetch
-  useEffect(() => {
-    refetch();
-  }, [refetch]);
-
-  // Listen for realtime maintenance updates
+  const maintenanceClient = usePluginClient(MaintenanceApi);
+  const badgeData = useSystemBadgeDataOptional();
+
+  // Try to get data from provider first
+  const providerData = badgeData?.getSystemBadgeData(system?.id ?? "");
+  const providerHasActive = providerData
+    ? hasActiveMaintenance(providerData.maintenances)
+    : false;
+
+  // Query for maintenances if not using provider
+  const { data: maintenances, refetch } =
+    maintenanceClient.getMaintenancesForSystem.useQuery(
+      { systemId: system?.id ?? "" },
+      { enabled: !badgeData && !!system?.id }
+    );
+
+  const localHasActive = maintenances
+    ? hasActiveMaintenance(maintenances)
+    : false;
+
+  // Listen for realtime maintenance updates (only in fallback mode)
   useSignal(MAINTENANCE_UPDATED, ({ systemIds }) => {
-    if (system?.id && systemIds.includes(system.id)) {
-      refetch();
+    if (!badgeData && system?.id && systemIds.includes(system.id)) {
+      void refetch();
     }
   });
 
-  if (!hasActiveMaintenance) return;
+  // Use provider data if available, otherwise use local state
+  const hasActive = badgeData ? providerHasActive : localHasActive;
+
+  if (!hasActive) return;
   return <Badge variant="warning">Under Maintenance</Badge>;
 };

package/src/components/SystemMaintenancePanel.tsx

@@ -1,14 +1,13 @@
-import React, { useEffect, useState, useCallback } from "react";
+import React from "react";
 import { Link } from "react-router-dom";
-import { useApi, type SlotContext } from "@checkstack/frontend-api";
+import { usePluginClient, type SlotContext } from "@checkstack/frontend-api";
 import { useSignal } from "@checkstack/signal-frontend";
 import { resolveRoute } from "@checkstack/common";
 import { SystemDetailsSlot } from "@checkstack/catalog-common";
-import { maintenanceApiRef } from "../api";
+import { MaintenanceApi } from "../api";
 import {
   maintenanceRoutes,
   MAINTENANCE_UPDATED,
-  type MaintenanceWithSystems,
 } from "@checkstack/maintenance-common";
 import {
   Card,
@@ -29,31 +28,22 @@ type Props = SlotContext<typeof SystemDetailsSlot>;
  * Listens for realtime updates via signals.
  */
 export const SystemMaintenancePanel: React.FC<Props> = ({ system }) => {
-  const api = useApi(maintenanceApiRef);
-  const [maintenances, setMaintenances] = useState<MaintenanceWithSystems[]>(
-    []
-  );
-  const [loading, setLoading] = useState(true);
-
-  const refetch = useCallback(() => {
-    if (!system?.id) return;
+  const maintenanceClient = usePluginClient(MaintenanceApi);
 
-    api
-      .getMaintenancesForSystem({ systemId: system.id })
-      .then(setMaintenances)
-      .catch(console.error)
-      .finally(() => setLoading(false));
-  }, [system?.id, api]);
-
-  // Initial fetch
-  useEffect(() => {
-    refetch();
-  }, [refetch]);
+  // Fetch maintenances with useQuery
+  const {
+    data: maintenances = [],
+    isLoading: loading,
+    refetch,
+  } = maintenanceClient.getMaintenancesForSystem.useQuery(
+    { systemId: system?.id ?? "" },
+    { enabled: !!system?.id }
+  );
 
   // Listen for realtime maintenance updates
   useSignal(MAINTENANCE_UPDATED, ({ systemIds }) => {
     if (system?.id && systemIds.includes(system.id)) {
-      refetch();
+      void refetch();
     }
   });
 

package/src/index.tsx

@@ -1,16 +1,12 @@
 import {
   createFrontendPlugin,
   createSlotExtension,
-  rpcApiRef,
-  type ApiRef,
   UserMenuItemsSlot,
 } from "@checkstack/frontend-api";
-import { maintenanceApiRef, type MaintenanceApiClient } from "./api";
 import {
   maintenanceRoutes,
-  MaintenanceApi,
   pluginMetadata,
-  permissions,
+  maintenanceAccess,
 } from "@checkstack/maintenance-common";
 import {
   SystemDetailsTopSlot,
@@ -30,7 +26,7 @@ export default createFrontendPlugin({
       route: maintenanceRoutes.routes.config,
       element: <MaintenanceConfigPage />,
       title: "Maintenances",
-      permission: permissions.maintenanceManage,
+      accessRule: maintenanceAccess.maintenance.manage,
     },
     {
       route: maintenanceRoutes.routes.systemHistory,
@@ -43,17 +39,8 @@ export default createFrontendPlugin({
       title: "Maintenance Details",
     },
   ],
-  apis: [
-    {
-      ref: maintenanceApiRef,
-      factory: (deps: {
-        get: <T>(ref: ApiRef<T>) => T;
-      }): MaintenanceApiClient => {
-        const rpcApi = deps.get(rpcApiRef);
-        return rpcApi.forPlugin(MaintenanceApi);
-      },
-    },
-  ],
+  // No APIs needed - components use usePluginClient() directly
+  apis: [],
   extensions: [
     createSlotExtension(UserMenuItemsSlot, {
       id: "maintenance.user-menu.items",

package/src/pages/MaintenanceConfigPage.tsx

@@ -1,17 +1,18 @@
-import React, { useEffect, useState, useMemo } from "react";
+import React, { useEffect, useState } from "react";
 import { useSearchParams } from "react-router-dom";
 import {
+  usePluginClient,
+  accessApiRef,
   useApi,
-  rpcApiRef,
-  permissionApiRef,
   wrapInSuspense,
 } from "@checkstack/frontend-api";
-import { maintenanceApiRef } from "../api";
+import { MaintenanceApi } from "../api";
 import type {
   MaintenanceWithSystems,
   MaintenanceStatus,
 } from "@checkstack/maintenance-common";
-import { CatalogApi, type System } from "@checkstack/catalog-common";
+import { maintenanceAccess } from "@checkstack/maintenance-common";
+import { CatalogApi } from "@checkstack/catalog-common";
 import {
   Card,
   CardHeader,
@@ -49,22 +50,16 @@ import { MaintenanceEditor } from "../components/MaintenanceEditor";
 import { getMaintenanceStatusBadge } from "../utils/badges";
 
 const MaintenanceConfigPageContent: React.FC = () => {
-  const api = useApi(maintenanceApiRef);
-  const rpcApi = useApi(rpcApiRef);
-  const permissionApi = useApi(permissionApiRef);
+  const maintenanceClient = usePluginClient(MaintenanceApi);
+  const catalogClient = usePluginClient(CatalogApi);
+  const accessApi = useApi(accessApiRef);
   const [searchParams, setSearchParams] = useSearchParams();
-
-  const catalogApi = useMemo(() => rpcApi.forPlugin(CatalogApi), [rpcApi]);
   const toast = useToast();
 
-  const { allowed: canManage, loading: permissionLoading } =
-    permissionApi.useResourcePermission("maintenance", "manage");
-
-  const [maintenances, setMaintenances] = useState<MaintenanceWithSystems[]>(
-    []
+  const { allowed: canManage, loading: accessLoading } = accessApi.useAccess(
+    maintenanceAccess.maintenance.manage
   );
-  const [systems, setSystems] = useState<System[]>([]);
-  const [loading, setLoading] = useState(true);
+
   const [statusFilter, setStatusFilter] = useState<MaintenanceStatus | "all">(
     "all"
   );
@@ -77,35 +72,26 @@ const MaintenanceConfigPageContent: React.FC = () => {
 
   // Delete confirmation state
   const [deleteId, setDeleteId] = useState<string | undefined>();
-  const [isDeleting, setIsDeleting] = useState(false);
 
   // Complete confirmation state
   const [completeId, setCompleteId] = useState<string | undefined>();
-  const [isCompleting, setIsCompleting] = useState(false);
 
-  const loadData = async () => {
-    setLoading(true);
-    try {
-      const [{ maintenances: maintenanceList }, { systems: systemList }] =
-        await Promise.all([
-          api.listMaintenances(
-            statusFilter === "all" ? undefined : { status: statusFilter }
-          ),
-          catalogApi.getSystems(),
-        ]);
-      setMaintenances(maintenanceList);
-      setSystems(systemList);
-    } catch (error) {
-      const message = error instanceof Error ? error.message : "Failed to load";
-      toast.error(message);
-    } finally {
-      setLoading(false);
-    }
-  };
+  // Fetch maintenances with useQuery
+  const {
+    data: maintenancesData,
+    isLoading: maintenancesLoading,
+    refetch: refetchMaintenances,
+  } = maintenanceClient.listMaintenances.useQuery(
+    statusFilter === "all" ? {} : { status: statusFilter }
+  );
 
-  useEffect(() => {
-    loadData();
-  }, [statusFilter]);
+  // Fetch systems with useQuery
+  const { data: systemsData, isLoading: systemsLoading } =
+    catalogClient.getSystems.useQuery({});
+
+  const maintenances = maintenancesData?.maintenances ?? [];
+  const systems = systemsData?.systems ?? [];
+  const loading = maintenancesLoading || systemsLoading;
 
   // Handle ?action=create URL parameter (from command palette)
   useEffect(() => {
@@ -118,6 +104,31 @@ const MaintenanceConfigPageContent: React.FC = () => {
     }
   }, [searchParams, canManage, setSearchParams]);
 
+  // Mutations
+  const deleteMutation = maintenanceClient.deleteMaintenance.useMutation({
+    onSuccess: () => {
+      toast.success("Maintenance deleted");
+      void refetchMaintenances();
+      setDeleteId(undefined);
+    },
+    onError: (error) => {
+      toast.error(error instanceof Error ? error.message : "Failed to delete");
+    },
+  });
+
+  const completeMutation = maintenanceClient.closeMaintenance.useMutation({
+    onSuccess: () => {
+      toast.success("Maintenance completed");
+      void refetchMaintenances();
+      setCompleteId(undefined);
+    },
+    onError: (error) => {
+      toast.error(
+        error instanceof Error ? error.message : "Failed to complete"
+      );
+    },
+  });
+
   const handleCreate = () => {
     setEditingMaintenance(undefined);
     setEditorOpen(true);
@@ -128,45 +139,19 @@ const MaintenanceConfigPageContent: React.FC = () => {
     setEditorOpen(true);
   };
 
-  const handleDelete = async () => {
+  const handleDelete = () => {
     if (!deleteId) return;
-
-    setIsDeleting(true);
-    try {
-      await api.deleteMaintenance({ id: deleteId });
-      toast.success("Maintenance deleted");
-      loadData();
-    } catch (error) {
-      const message =
-        error instanceof Error ? error.message : "Failed to delete";
-      toast.error(message);
-    } finally {
-      setIsDeleting(false);
-      setDeleteId(undefined);
-    }
+    deleteMutation.mutate({ id: deleteId });
   };
 
-  const handleComplete = async () => {
+  const handleComplete = () => {
     if (!completeId) return;
-
-    setIsCompleting(true);
-    try {
-      await api.closeMaintenance({ id: completeId });
-      toast.success("Maintenance completed");
-      loadData();
-    } catch (error) {
-      const message =
-        error instanceof Error ? error.message : "Failed to complete";
-      toast.error(message);
-    } finally {
-      setIsCompleting(false);
-      setCompleteId(undefined);
-    }
+    completeMutation.mutate({ id: completeId });
   };
 
   const handleSave = () => {
     setEditorOpen(false);
-    loadData();
+    void refetchMaintenances();
   };
 
   const getSystemNames = (systemIds: string[]): string => {
@@ -186,7 +171,7 @@ const MaintenanceConfigPageContent: React.FC = () => {
     <PageLayout
       title="Planned Maintenances"
       subtitle="Manage scheduled maintenance windows for systems"
-      loading={permissionLoading}
+      loading={accessLoading}
       allowed={canManage}
       actions={
         <Button onClick={handleCreate}>
@@ -326,7 +311,7 @@ const MaintenanceConfigPageContent: React.FC = () => {
         confirmText="Delete"
         variant="danger"
         onConfirm={handleDelete}
-        isLoading={isDeleting}
+        isLoading={deleteMutation.isPending}
       />
 
       <ConfirmationModal
@@ -337,7 +322,7 @@ const MaintenanceConfigPageContent: React.FC = () => {
         confirmText="Complete"
         variant="info"
         onConfirm={handleComplete}
-        isLoading={isCompleting}
+        isLoading={completeMutation.isPending}
       />
     </PageLayout>
   );

package/src/pages/MaintenanceDetailPage.tsx

@@ -1,4 +1,4 @@
-import React, { useEffect, useState, useMemo, useCallback } from "react";
+import React, { useState } from "react";
 import {
   useParams,
   Link,
@@ -6,20 +6,18 @@ import {
   useSearchParams,
 } from "react-router-dom";
 import {
-  useApi,
-  rpcApiRef,
+  usePluginClient,
   wrapInSuspense,
-  permissionApiRef,
+  accessApiRef,
+  useApi,
 } from "@checkstack/frontend-api";
 import { resolveRoute } from "@checkstack/common";
-import { maintenanceApiRef } from "../api";
-import { maintenanceRoutes } from "@checkstack/maintenance-common";
-import type { MaintenanceDetail } from "@checkstack/maintenance-common";
+import { MaintenanceApi } from "../api";
 import {
-  catalogRoutes,
-  CatalogApi,
-  type System,
-} from "@checkstack/catalog-common";
+  maintenanceRoutes,
+  maintenanceAccess,
+} from "@checkstack/maintenance-common";
+import { catalogRoutes, CatalogApi } from "@checkstack/catalog-common";
 import {
   Card,
   CardHeader,
@@ -51,62 +49,55 @@ const MaintenanceDetailPageContent: React.FC = () => {
   const { maintenanceId } = useParams<{ maintenanceId: string }>();
   const navigate = useNavigate();
   const [searchParams] = useSearchParams();
-  const api = useApi(maintenanceApiRef);
-  const rpcApi = useApi(rpcApiRef);
-  const permissionApi = useApi(permissionApiRef);
+  const maintenanceClient = usePluginClient(MaintenanceApi);
+  const catalogClient = usePluginClient(CatalogApi);
+  const accessApi = useApi(accessApiRef);
   const toast = useToast();
 
-  const catalogApi = useMemo(() => rpcApi.forPlugin(CatalogApi), [rpcApi]);
-
-  const { allowed: canManage } = permissionApi.useResourcePermission(
-    "maintenance",
-    "manage"
+  const { allowed: canManage } = accessApi.useAccess(
+    maintenanceAccess.maintenance.manage
   );
 
-  const [maintenance, setMaintenance] = useState<MaintenanceDetail>();
-  const [systems, setSystems] = useState<System[]>([]);
-  const [loading, setLoading] = useState(true);
   const [showUpdateForm, setShowUpdateForm] = useState(false);
 
-  const loadData = useCallback(async () => {
-    if (!maintenanceId) return;
+  // Fetch maintenance with useQuery
+  const {
+    data: maintenance,
+    isLoading: maintenanceLoading,
+    refetch: refetchMaintenance,
+  } = maintenanceClient.getMaintenance.useQuery(
+    { id: maintenanceId ?? "" },
+    { enabled: !!maintenanceId }
+  );
 
-    setLoading(true);
-    try {
-      const [maintenanceData, { systems: systemList }] = await Promise.all([
-        api.getMaintenance({ id: maintenanceId }),
-        catalogApi.getSystems(),
-      ]);
-      setMaintenance(maintenanceData ?? undefined);
-      setSystems(systemList);
-    } catch (error) {
-      console.error("Failed to load maintenance details:", error);
-    } finally {
-      setLoading(false);
-    }
-  }, [maintenanceId, api, catalogApi]);
+  // Fetch systems with useQuery
+  const { data: systemsData, isLoading: systemsLoading } =
+    catalogClient.getSystems.useQuery({});
 
-  useEffect(() => {
-    loadData();
-  }, [loadData]);
+  const systems = systemsData?.systems ?? [];
+  const loading = maintenanceLoading || systemsLoading;
+
+  // Complete mutation
+  const completeMutation = maintenanceClient.closeMaintenance.useMutation({
+    onSuccess: () => {
+      toast.success("Maintenance completed");
+      void refetchMaintenance();
+    },
+    onError: (error) => {
+      toast.error(
+        error instanceof Error ? error.message : "Failed to complete"
+      );
+    },
+  });
 
   const handleUpdateSuccess = () => {
     setShowUpdateForm(false);
-    loadData();
+    void refetchMaintenance();
   };
 
-  const handleComplete = async () => {
+  const handleComplete = () => {
     if (!maintenanceId) return;
-
-    try {
-      await api.closeMaintenance({ id: maintenanceId });
-      toast.success("Maintenance completed");
-      await loadData();
-    } catch (error) {
-      const message =
-        error instanceof Error ? error.message : "Failed to complete";
-      toast.error(message);
-    }
+    completeMutation.mutate({ id: maintenanceId });
   };
 
   const getSystemName = (systemId: string): string => {
@@ -180,7 +171,12 @@ const MaintenanceDetailPageContent: React.FC = () => {
               <div className="flex items-center gap-2">
                 {getMaintenanceStatusBadge(maintenance.status)}
                 {canComplete && (
-                  <Button variant="outline" size="sm" onClick={handleComplete}>
+                  <Button
+                    variant="outline"
+                    size="sm"
+                    onClick={handleComplete}
+                    disabled={completeMutation.isPending}
+                  >
                     <CheckCircle2 className="h-4 w-4 mr-1" />
                     Complete
                   </Button>

package/src/pages/SystemMaintenanceHistoryPage.tsx

@@ -1,13 +1,10 @@
-import React, { useEffect, useState, useMemo } from "react";
+import React from "react";
 import { useParams, useNavigate } from "react-router-dom";
-import { useApi, rpcApiRef, wrapInSuspense } from "@checkstack/frontend-api";
+import { usePluginClient, wrapInSuspense } from "@checkstack/frontend-api";
 import { resolveRoute } from "@checkstack/common";
-import { maintenanceApiRef } from "../api";
+import { MaintenanceApi } from "../api";
 import { maintenanceRoutes } from "@checkstack/maintenance-common";
-import type {
-  MaintenanceWithSystems,
-  MaintenanceStatus,
-} from "@checkstack/maintenance-common";
+import type { MaintenanceStatus } from "@checkstack/maintenance-common";
 import { catalogRoutes, CatalogApi } from "@checkstack/catalog-common";
 import {
   Card,
@@ -32,40 +29,25 @@ import { format } from "date-fns";
 const SystemMaintenanceHistoryPageContent: React.FC = () => {
   const { systemId } = useParams<{ systemId: string }>();
   const navigate = useNavigate();
-  const api = useApi(maintenanceApiRef);
-  const rpcApi = useApi(rpcApiRef);
+  const maintenanceClient = usePluginClient(MaintenanceApi);
+  const catalogClient = usePluginClient(CatalogApi);
 
-  const catalogApi = useMemo(() => rpcApi.forPlugin(CatalogApi), [rpcApi]);
-
-  const [maintenances, setMaintenances] = useState<MaintenanceWithSystems[]>(
-    []
-  );
-  const [systemName, setSystemName] = useState<string>("");
-  const [loading, setLoading] = useState(true);
-
-  useEffect(() => {
-    if (!systemId) return;
+  // Fetch maintenances with useQuery
+  const { data: maintenancesData, isLoading: maintenancesLoading } =
+    maintenanceClient.listMaintenances.useQuery(
+      { systemId },
+      { enabled: !!systemId }
+    );
 
-    const loadData = async () => {
-      setLoading(true);
-      try {
-        const [{ maintenances: maintenanceList }, { systems: systemList }] =
-          await Promise.all([
-            api.listMaintenances({ systemId }),
-            catalogApi.getSystems(),
-          ]);
-        setMaintenances(maintenanceList);
-        const system = systemList.find((s) => s.id === systemId);
-        setSystemName(system?.name ?? "Unknown System");
-      } catch (error) {
-        console.error("Failed to load maintenance history:", error);
-      } finally {
-        setLoading(false);
-      }
-    };
+  // Fetch systems with useQuery
+  const { data: systemsData, isLoading: systemsLoading } =
+    catalogClient.getSystems.useQuery({});
 
-    loadData();
-  }, [systemId, api, catalogApi]);
+  const maintenances = maintenancesData?.maintenances ?? [];
+  const systems = systemsData?.systems ?? [];
+  const system = systems.find((s) => s.id === systemId);
+  const systemName = system?.name ?? "Unknown System";
+  const loading = maintenancesLoading || systemsLoading;
 
   const getStatusBadge = (status: MaintenanceStatus) => {
     switch (status) {