@checkstack/catalog-frontend 0.2.0 → 0.3.0

package/CHANGELOG.md

@@ -1,5 +1,69 @@
 # @checkstack/catalog-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 [7a23261]
+  - @checkstack/frontend-api@0.2.0
+  - @checkstack/common@0.3.0
+  - @checkstack/auth-frontend@0.3.0
+  - @checkstack/catalog-common@1.2.0
+  - @checkstack/notification-common@0.2.0
+  - @checkstack/ui@0.2.1
+
 ## 0.2.0
 
 ### Minor Changes

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@checkstack/catalog-frontend",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "type": "module",
   "main": "src/index.tsx",
   "scripts": {

package/src/api.ts

@@ -1,12 +1,4 @@
-import { createApiRef } from "@checkstack/frontend-api";
-import { CatalogApi } from "@checkstack/catalog-common";
-import type { InferClient } from "@checkstack/common";
-
 // Re-export types for convenience
 export type { System, Group, View } from "@checkstack/catalog-common";
-
-// CatalogApi client type inferred from the client definition
-export type CatalogApiClient = InferClient<typeof CatalogApi>;
-
-export const catalogApiRef =
-  createApiRef<CatalogApiClient>("plugin.catalog.api");
+// Client definition is in @checkstack/catalog-common - use with usePluginClient
+export { CatalogApi } from "@checkstack/catalog-common";

package/src/components/CatalogConfigPage.tsx

@@ -4,8 +4,9 @@ import {
   useApi,
   accessApiRef,
   ExtensionSlot,
+  usePluginClient,
 } from "@checkstack/frontend-api";
-import { catalogApiRef, System, Group } from "../api";
+import { System, CatalogApi } from "../api";
 import {
   CatalogSystemActionsSlot,
   catalogAccess,
@@ -30,25 +31,22 @@ import { SystemEditor } from "./SystemEditor";
 import { GroupEditor } from "./GroupEditor";
 
 export const CatalogConfigPage = () => {
-  const catalogApi = useApi(catalogApiRef);
+  const catalogClient = usePluginClient(CatalogApi);
   const accessApi = useApi(accessApiRef);
   const toast = useToast();
   const [searchParams, setSearchParams] = useSearchParams();
-  const { allowed: canManage, loading: accessLoading } =
-    accessApi.useAccess(catalogAccess.system.manage);
+  const { allowed: canManage, loading: accessLoading } = accessApi.useAccess(
+    catalogAccess.system.manage
+  );
 
-  const [systems, setSystems] = useState<System[]>([]);
-  const [groups, setGroups] = useState<Group[]>([]);
-  const [loading, setLoading] = useState(true);
+  const [selectedGroupId, setSelectedGroupId] = useState("");
+  const [selectedSystemToAdd, setSelectedSystemToAdd] = useState("");
 
   // Dialog state
   const [isSystemEditorOpen, setIsSystemEditorOpen] = useState(false);
   const [editingSystem, setEditingSystem] = useState<System | undefined>();
   const [isGroupEditorOpen, setIsGroupEditorOpen] = useState(false);
 
-  const [selectedGroupId, setSelectedGroupId] = useState("");
-  const [selectedSystemToAdd, setSelectedSystemToAdd] = useState("");
-
   // Confirmation modal state
   const [confirmModal, setConfirmModal] = useState<{
     isOpen: boolean;
@@ -62,31 +60,30 @@ export const CatalogConfigPage = () => {
     onConfirm: () => {},
   });
 
-  const loadData = async () => {
-    setLoading(true);
-    try {
-      const [{ systems: s }, g] = await Promise.all([
-        catalogApi.getSystems(),
-        catalogApi.getGroups(),
-      ]);
-      setSystems(s);
-      setGroups(g);
-      if (g.length > 0 && !selectedGroupId) {
-        setSelectedGroupId(g[0].id);
-      }
-    } catch (error) {
-      const message =
-        error instanceof Error ? error.message : "Failed to load catalog data";
-      toast.error(message);
-      console.error("Failed to load catalog data:", error);
-    } finally {
-      setLoading(false);
-    }
-  };
+  // Fetch systems with useQuery
+  const {
+    data: systemsData,
+    isLoading: systemsLoading,
+    refetch: refetchSystems,
+  } = catalogClient.getSystems.useQuery({});
+
+  // Fetch groups with useQuery
+  const {
+    data: groupsData,
+    isLoading: groupsLoading,
+    refetch: refetchGroups,
+  } = catalogClient.getGroups.useQuery({});
+
+  const systems = systemsData?.systems ?? [];
+  const groups = groupsData ?? [];
+  const loading = systemsLoading || groupsLoading;
 
+  // Set initial group selection
   useEffect(() => {
-    loadData();
-  }, []);
+    if (groups.length > 0 && !selectedGroupId) {
+      setSelectedGroupId(groups[0].id);
+    }
+  }, [groups, selectedGroupId]);
 
   // Handle ?action=create URL parameter (from command palette)
   useEffect(() => {
@@ -98,128 +95,168 @@ export const CatalogConfigPage = () => {
     }
   }, [searchParams, canManage, setSearchParams]);
 
-  // Unified save handler for both create and edit
+  // Mutations
+  const createSystemMutation = catalogClient.createSystem.useMutation({
+    onSuccess: () => {
+      toast.success("System created successfully");
+      setIsSystemEditorOpen(false);
+      void refetchSystems();
+    },
+    onError: (error) => {
+      toast.error(
+        error instanceof Error ? error.message : "Failed to create system"
+      );
+    },
+  });
+
+  const updateSystemMutation = catalogClient.updateSystem.useMutation({
+    onSuccess: () => {
+      toast.success("System updated successfully");
+      setIsSystemEditorOpen(false);
+      setEditingSystem(undefined);
+      void refetchSystems();
+    },
+    onError: (error) => {
+      toast.error(
+        error instanceof Error ? error.message : "Failed to update system"
+      );
+    },
+  });
+
+  const deleteSystemMutation = catalogClient.deleteSystem.useMutation({
+    onSuccess: () => {
+      toast.success("System deleted successfully");
+      setConfirmModal({ ...confirmModal, isOpen: false });
+      void refetchSystems();
+    },
+    onError: (error) => {
+      toast.error(
+        error instanceof Error ? error.message : "Failed to delete system"
+      );
+    },
+  });
+
+  const createGroupMutation = catalogClient.createGroup.useMutation({
+    onSuccess: () => {
+      toast.success("Group created successfully");
+      setIsGroupEditorOpen(false);
+      void refetchGroups();
+    },
+    onError: (error) => {
+      toast.error(
+        error instanceof Error ? error.message : "Failed to create group"
+      );
+    },
+  });
+
+  const deleteGroupMutation = catalogClient.deleteGroup.useMutation({
+    onSuccess: () => {
+      toast.success("Group deleted successfully");
+      setConfirmModal({ ...confirmModal, isOpen: false });
+      void refetchGroups();
+    },
+    onError: (error) => {
+      toast.error(
+        error instanceof Error ? error.message : "Failed to delete group"
+      );
+    },
+  });
+
+  const updateGroupMutation = catalogClient.updateGroup.useMutation({
+    onSuccess: () => {
+      toast.success("Group name updated successfully");
+      void refetchGroups();
+    },
+    onError: (error) => {
+      toast.error(
+        error instanceof Error ? error.message : "Failed to update group name"
+      );
+      throw error;
+    },
+  });
+
+  const addSystemToGroupMutation = catalogClient.addSystemToGroup.useMutation({
+    onSuccess: () => {
+      toast.success("System added to group successfully");
+      setSelectedSystemToAdd("");
+      void refetchGroups();
+    },
+    onError: (error) => {
+      toast.error(
+        error instanceof Error ? error.message : "Failed to add system to group"
+      );
+    },
+  });
+
+  const removeSystemFromGroupMutation =
+    catalogClient.removeSystemFromGroup.useMutation({
+      onSuccess: () => {
+        toast.success("System removed from group successfully");
+        void refetchGroups();
+      },
+      onError: (error) => {
+        toast.error(
+          error instanceof Error
+            ? error.message
+            : "Failed to remove system from group"
+        );
+      },
+    });
+
+  // Handlers
   const handleSaveSystem = async (data: {
     name: string;
     description?: string;
   }) => {
     if (editingSystem) {
-      // Update existing system
-      await catalogApi.updateSystem({
-        id: editingSystem.id,
-        data,
-      });
-      toast.success("System updated successfully");
-      setEditingSystem(undefined);
+      updateSystemMutation.mutate({ id: editingSystem.id, data });
     } else {
-      // Create new system
-      await catalogApi.createSystem(data);
-      toast.success("System created successfully");
+      createSystemMutation.mutate(data);
     }
-    setIsSystemEditorOpen(false);
-    await loadData();
   };
 
   const handleCreateGroup = async (data: { name: string }) => {
-    await catalogApi.createGroup(data);
-    toast.success("Group created successfully");
-    await loadData();
+    createGroupMutation.mutate(data);
   };
 
-  const handleDeleteSystem = async (id: string) => {
+  const handleDeleteSystem = (id: string) => {
     const system = systems.find((s) => s.id === id);
     setConfirmModal({
       isOpen: true,
       title: "Delete System",
       message: `Are you sure you want to delete "${system?.name}"? This will remove the system from all groups as well.`,
-      onConfirm: async () => {
-        try {
-          await catalogApi.deleteSystem(id);
-          setConfirmModal({ ...confirmModal, isOpen: false });
-          toast.success("System deleted successfully");
-          loadData();
-        } catch (error) {
-          const message =
-            error instanceof Error ? error.message : "Failed to delete system";
-          toast.error(message);
-          console.error("Failed to delete system:", error);
-        }
+      onConfirm: () => {
+        deleteSystemMutation.mutate(id);
       },
     });
   };
 
-  const handleDeleteGroup = async (id: string) => {
+  const handleDeleteGroup = (id: string) => {
     const group = groups.find((g) => g.id === id);
     setConfirmModal({
       isOpen: true,
       title: "Delete Group",
       message: `Are you sure you want to delete "${group?.name}"? This action cannot be undone.`,
-      onConfirm: async () => {
-        try {
-          await catalogApi.deleteGroup(id);
-          setConfirmModal({ ...confirmModal, isOpen: false });
-          toast.success("Group deleted successfully");
-          loadData();
-        } catch (error) {
-          const message =
-            error instanceof Error ? error.message : "Failed to delete group";
-          toast.error(message);
-          console.error("Failed to delete group:", error);
-        }
+      onConfirm: () => {
+        deleteGroupMutation.mutate(id);
       },
     });
   };
 
-  const handleAddSystemToGroup = async () => {
+  const handleAddSystemToGroup = () => {
     if (!selectedGroupId || !selectedSystemToAdd) return;
-    try {
-      await catalogApi.addSystemToGroup({
-        groupId: selectedGroupId,
-        systemId: selectedSystemToAdd,
-      });
-      setSelectedSystemToAdd("");
-      toast.success("System added to group successfully");
-      loadData();
-    } catch (error) {
-      const message =
-        error instanceof Error
-          ? error.message
-          : "Failed to add system to group";
-      toast.error(message);
-      console.error("Failed to add system to group:", error);
-    }
+    addSystemToGroupMutation.mutate({
+      groupId: selectedGroupId,
+      systemId: selectedSystemToAdd,
+    });
   };
 
-  const handleRemoveSystemFromGroup = async (
-    groupId: string,
-    systemId: string
-  ) => {
-    try {
-      await catalogApi.removeSystemFromGroup({ groupId, systemId });
-      toast.success("System removed from group successfully");
-      loadData();
-    } catch (error) {
-      const message =
-        error instanceof Error
-          ? error.message
-          : "Failed to remove system from group";
-      toast.error(message);
-      console.error("Failed to remove system from group:", error);
-    }
+  const handleRemoveSystemFromGroup = (groupId: string, systemId: string) => {
+    removeSystemFromGroupMutation.mutate({ groupId, systemId });
   };
 
-  const handleUpdateGroupName = async (id: string, newName: string) => {
-    try {
-      await catalogApi.updateGroup({ id, data: { name: newName } });
-      toast.success("Group name updated successfully");
-      loadData();
-    } catch (error) {
-      const message =
-        error instanceof Error ? error.message : "Failed to update group name";
-      toast.error(message);
-      console.error("Failed to update group name:", error);
-      throw error;
-    }
+  const handleUpdateGroupName = (id: string, newName: string) => {
+    updateGroupMutation.mutate({ id, data: { name: newName } });
   };
 
   if (loading || accessLoading) return <LoadingSpinner />;

package/src/components/CatalogPage.tsx

@@ -1,14 +1,12 @@
 import React from "react";
 import { useApi, loggerApiRef } from "@checkstack/frontend-api";
-import { catalogApiRef } from "../api";
 
 export const CatalogPage = () => {
   const logger = useApi(loggerApiRef);
-  const catalog = useApi(catalogApiRef);
 
   React.useEffect(() => {
-    logger.info("Catalog Page loaded", catalog);
-  }, [logger, catalog]);
+    logger.info("Catalog Page loaded");
+  }, [logger]);
 
   return (
     <div className="p-4 rounded-lg bg-white shadow">

package/src/components/SystemDetailPage.tsx

@@ -1,8 +1,11 @@
 import React, { useEffect, useState, useCallback } from "react";
 import { useParams, useNavigate } from "react-router-dom";
-import { useApi, rpcApiRef } from "@checkstack/frontend-api";
-import { catalogApiRef, System, Group } from "../api";
-import { ExtensionSlot } from "@checkstack/frontend-api";
+import {
+  usePluginClient,
+  ExtensionSlot,
+  useApi,
+} from "@checkstack/frontend-api";
+import { Group, CatalogApi } from "../api";
 import {
   SystemDetailsSlot,
   SystemDetailsTopSlot,
@@ -28,16 +31,13 @@ const CATALOG_PLUGIN_ID = "catalog";
 export const SystemDetailPage: React.FC = () => {
   const { systemId } = useParams<{ systemId: string }>();
   const navigate = useNavigate();
-  const catalogApi = useApi(catalogApiRef);
-  const rpcApi = useApi(rpcApiRef);
-  const notificationApi = rpcApi.forPlugin(NotificationApi);
+  const catalogClient = usePluginClient(CatalogApi);
+  const notificationClient = usePluginClient(NotificationApi);
   const toast = useToast();
   const authApi = useApi(authApiRef);
   const { data: session } = authApi.useSession();
 
-  const [system, setSystem] = useState<System | undefined>();
   const [groups, setGroups] = useState<Group[]>([]);
-  const [loading, setLoading] = useState(true);
   const [notFound, setNotFound] = useState(false);
 
   // Subscription state
@@ -49,85 +49,84 @@ export const SystemDetailPage: React.FC = () => {
     return `${CATALOG_PLUGIN_ID}.system.${systemId}`;
   }, [systemId]);
 
-  useEffect(() => {
-    if (!systemId) {
-      setNotFound(true);
-      setLoading(false);
-      return;
-    }
+  // Fetch system data with useQuery
+  const { data: systemsData, isLoading: systemsLoading } =
+    catalogClient.getSystems.useQuery({});
+
+  // Fetch groups data with useQuery
+  const { data: groupsData, isLoading: groupsLoading } =
+    catalogClient.getGroups.useQuery({});
 
-    Promise.all([catalogApi.getSystems(), catalogApi.getGroups()])
-      .then(([{ systems }, allGroups]) => {
-        const foundSystem = systems.find((s) => s.id === systemId);
+  // Find the system from the fetched data
+  const system = systemsData?.systems.find((s) => s.id === systemId);
+  const loading = systemsLoading || groupsLoading;
 
-        if (!foundSystem) {
-          setNotFound(true);
-          return;
-        }
+  // Fetch subscriptions with useQuery
+  const { data: subscriptions, refetch: refetchSubscriptions } =
+    notificationClient.getSubscriptions.useQuery({});
 
-        setSystem(foundSystem);
+  // Subscribe/unsubscribe mutations
+  const subscribeMutation = notificationClient.subscribe.useMutation({
+    onSuccess: () => {
+      setIsSubscribed(true);
+      toast.success("Subscribed to system notifications");
+      void refetchSubscriptions();
+    },
+    onError: (error) => {
+      toast.error(
+        error instanceof Error ? error.message : "Failed to subscribe"
+      );
+    },
+  });
 
-        // Find groups that contain this system
-        const systemGroups = allGroups.filter((group) =>
-          group.systemIds?.includes(systemId)
-        );
-        setGroups(systemGroups);
-      })
-      .catch((error) => {
-        console.error("Error fetching system details:", error);
-        setNotFound(true);
-      })
-      .finally(() => setLoading(false));
-  }, [systemId, catalogApi]);
+  const unsubscribeMutation = notificationClient.unsubscribe.useMutation({
+    onSuccess: () => {
+      setIsSubscribed(false);
+      toast.success("Unsubscribed from system notifications");
+      void refetchSubscriptions();
+    },
+    onError: (error) => {
+      toast.error(
+        error instanceof Error ? error.message : "Failed to unsubscribe"
+      );
+    },
+  });
 
-  // Check subscription status
+  // Update not found state
   useEffect(() => {
-    if (!systemId) return;
+    if (!systemsLoading && !system && systemId) {
+      setNotFound(true);
+    }
+  }, [system, systemsLoading, systemId]);
 
-    setSubscriptionLoading(true);
-    notificationApi
-      .getSubscriptions()
-      .then((subscriptions) => {
-        const groupId = getSystemGroupId();
-        const hasSubscription = subscriptions.some(
-          (s) => s.groupId === groupId
-        );
-        setIsSubscribed(hasSubscription);
-      })
-      .catch((error) => {
-        console.error("Failed to check subscription status:", error);
-      })
-      .finally(() => setSubscriptionLoading(false));
-  }, [systemId, notificationApi, getSystemGroupId]);
+  // Update groups that contain this system
+  useEffect(() => {
+    if (groupsData && systemId) {
+      const systemGroups = groupsData.filter((group) =>
+        group.systemIds?.includes(systemId)
+      );
+      setGroups(systemGroups);
+    }
+  }, [groupsData, systemId]);
 
-  const handleSubscribe = async () => {
-    setSubscriptionLoading(true);
-    try {
-      await notificationApi.subscribe({ groupId: getSystemGroupId() });
-      setIsSubscribed(true);
-      toast.success("Subscribed to system notifications");
-    } catch (error) {
-      const message =
-        error instanceof Error ? error.message : "Failed to subscribe";
-      toast.error(message);
-    } finally {
+  // Update subscription status from query
+  useEffect(() => {
+    if (subscriptions && systemId) {
+      const groupId = getSystemGroupId();
+      const hasSubscription = subscriptions.some((s) => s.groupId === groupId);
+      setIsSubscribed(hasSubscription);
       setSubscriptionLoading(false);
     }
+  }, [subscriptions, systemId, getSystemGroupId]);
+
+  const handleSubscribe = () => {
+    setSubscriptionLoading(true);
+    subscribeMutation.mutate({ groupId: getSystemGroupId() });
   };
 
-  const handleUnsubscribe = async () => {
+  const handleUnsubscribe = () => {
     setSubscriptionLoading(true);
-    try {
-      await notificationApi.unsubscribe({ groupId: getSystemGroupId() });
-      setIsSubscribed(false);
-      toast.success("Unsubscribed from system notifications");
-    } catch (error) {
-      const message =
-        error instanceof Error ? error.message : "Failed to unsubscribe";
-      toast.error(message);
-    } finally {
-      setSubscriptionLoading(false);
-    }
+    unsubscribeMutation.mutate({ groupId: getSystemGroupId() });
   };
 
   if (loading) {
@@ -175,7 +174,11 @@ export const SystemDetailPage: React.FC = () => {
               isSubscribed={isSubscribed}
               onSubscribe={handleSubscribe}
               onUnsubscribe={handleUnsubscribe}
-              loading={subscriptionLoading}
+              loading={
+                subscriptionLoading ||
+                subscribeMutation.isPending ||
+                unsubscribeMutation.isPending
+              }
             />
           )}
           <BackLink onClick={() => navigate("/")}>Back to Dashboard</BackLink>

package/src/index.tsx

@@ -1,14 +1,10 @@
 import {
-  rpcApiRef,
-  ApiRef,
   UserMenuItemsSlot,
   createSlotExtension,
   createFrontendPlugin,
 } from "@checkstack/frontend-api";
-import { catalogApiRef, type CatalogApiClient } from "./api";
 import {
   catalogRoutes,
-  CatalogApi,
   pluginMetadata,
   catalogAccess,
 } from "@checkstack/catalog-common";
@@ -20,16 +16,8 @@ import { SystemDetailPage } from "./components/SystemDetailPage";
 
 export const catalogPlugin = createFrontendPlugin({
   metadata: pluginMetadata,
-  apis: [
-    {
-      ref: catalogApiRef,
-      factory: (deps: { get: <T>(ref: ApiRef<T>) => T }): CatalogApiClient => {
-        const rpcApi = deps.get(rpcApiRef);
-        // CatalogApiClient is derived from the contract type
-        return rpcApi.forPlugin(CatalogApi);
-      },
-    },
-  ],
+  // No APIs needed - components use usePluginClient() directly
+  apis: [],
   routes: [
     {
       route: catalogRoutes.routes.home,