@checkstack/frontend 0.0.5 → 0.2.0

package/CHANGELOG.md

@@ -1,5 +1,153 @@
 # @checkstack/frontend
 
+## 0.2.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-frontend@0.3.0
+  - @checkstack/command-frontend@0.2.0
+  - @checkstack/ui@0.2.1
+  - @checkstack/signal-common@0.1.1
+  - @checkstack/signal-frontend@0.0.7
+
+## 0.1.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-frontend@0.2.0
+  - @checkstack/command-frontend@0.1.0
+  - @checkstack/common@0.2.0
+  - @checkstack/frontend-api@0.1.0
+  - @checkstack/signal-common@0.1.0
+  - @checkstack/ui@0.2.0
+  - @checkstack/signal-frontend@0.0.6
+
 ## 0.0.5
 
 ### Patch Changes

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@checkstack/frontend",
-  "version": "0.0.5",
+  "version": "0.2.0",
   "type": "module",
   "scripts": {
     "dev": "vite",
@@ -21,6 +21,8 @@
     "@checkstack/signal-frontend": "workspace:*",
     "@checkstack/ui": "workspace:*",
     "@orpc/client": "^1.13.2",
+    "@tanstack/react-query": "^5.64.0",
+    "@tanstack/react-query-devtools": "^5.64.0",
     "better-auth": "^1.1.8",
     "class-variance-authority": "^0.7.0",
     "clsx": "^2.1.0",

package/src/App.tsx

@@ -10,7 +10,7 @@ import {
   ApiProvider,
   ApiRegistryBuilder,
   loggerApiRef,
-  permissionApiRef,
+  accessApiRef,
   fetchApiRef,
   rpcApiRef,
   useApi,
@@ -23,22 +23,36 @@ import {
   RuntimeConfigProvider,
   useRuntimeConfigLoading,
   useRuntimeConfig,
+  OrpcQueryProvider,
 } from "@checkstack/frontend-api";
+import { QueryClient, QueryClientProvider } from "@tanstack/react-query";
+import { ReactQueryDevtools } from "@tanstack/react-query-devtools";
 import { ConsoleLoggerApi } from "./apis/logger-api";
 import { CoreFetchApi } from "./apis/fetch-api";
 import { CoreRpcApi } from "./apis/rpc-api";
 import {
-  PermissionDenied,
+  AccessDenied,
   LoadingSpinner,
   ToastProvider,
   AmbientBackground,
 } from "@checkstack/ui";
 import { SignalProvider } from "@checkstack/signal-frontend";
 import { usePluginLifecycle } from "./hooks/usePluginLifecycle";
-import {
-  useCommands,
-  useGlobalShortcuts,
-} from "@checkstack/command-frontend";
+import { useCommands, useGlobalShortcuts } from "@checkstack/command-frontend";
+
+// Create a stable query client instance
+const queryClient = new QueryClient({
+  defaultOptions: {
+    queries: {
+      // Default stale time of 30 seconds for all queries
+      staleTime: 30_000,
+      // Keep unused data in cache for 5 minutes
+      gcTime: 5 * 60 * 1000,
+      // Don't refetch on window focus by default (can be overridden per query)
+      refetchOnWindowFocus: false,
+    },
+  },
+});
 
 /**
  * Component that registers global keyboard shortcuts for all commands.
@@ -48,7 +62,7 @@ function GlobalShortcuts() {
   const { commands } = useCommands();
   const navigate = useNavigate();
 
-  // Pass "*" as permission since backend already filters by permission
+  // Pass "*" as access since backend already filters by access
   useGlobalShortcuts(commands, navigate, ["*"]);
 
   // This component renders nothing - it only registers event listeners
@@ -57,10 +71,16 @@ function GlobalShortcuts() {
 
 const RouteGuard: React.FC<{
   children: React.ReactNode;
-  permission?: string;
-}> = ({ children, permission }) => {
-  const permissionApi = useApi(permissionApiRef);
-  const { allowed, loading } = permissionApi.usePermission(permission || "");
+  accessRule?: string;
+}> = ({ children, accessRule }) => {
+  const accessApi = useApi(accessApiRef);
+  // If there's an access rule requirement, use useAccess with a minimal AccessRule-like object
+  // the route.accessRule is already the qualified access rule ID string
+  const { allowed, loading } = accessRule
+    ? accessApi.useAccess({ id: accessRule } as Parameters<
+        typeof accessApi.useAccess
+      >[0])
+    : { allowed: true, loading: false };
 
   if (loading) {
     return (
@@ -70,10 +90,8 @@ const RouteGuard: React.FC<{
     );
   }
 
-  const isAllowed = permission ? allowed : true;
-
-  if (!isAllowed) {
-    return <PermissionDenied />;
+  if (!allowed) {
+    return <AccessDenied />;
   }
 
   return <>{children}</>;
@@ -130,7 +148,7 @@ function AppContent() {
                 key={route.path}
                 path={route.path}
                 element={
-                  <RouteGuard permission={route.permission}>
+                  <RouteGuard accessRule={route.accessRule}>
                     {route.element}
                   </RouteGuard>
                 }
@@ -154,10 +172,8 @@ function AppWithApis() {
     // Initialize API Registry with core apiRefs
     const registryBuilder = new ApiRegistryBuilder()
       .register(loggerApiRef, new ConsoleLoggerApi())
-      .register(permissionApiRef, {
-        usePermission: () => ({ loading: false, allowed: true }), // Default to allow all if no auth plugin present
-        useResourcePermission: () => ({ loading: false, allowed: true }),
-        useManagePermission: () => ({ loading: false, allowed: true }),
+      .register(accessApiRef, {
+        useAccess: () => ({ loading: false, allowed: true }), // Default to allow all if no auth plugin present
       })
       .registerFactory(fetchApiRef, (_registry) => {
         return new CoreFetchApi(baseUrl);
@@ -195,13 +211,19 @@ function AppWithApis() {
   }
 
   return (
-    <ApiProvider registry={apiRegistry}>
-      <SignalProvider backendUrl={baseUrl}>
-        <ToastProvider>
-          <AppContent />
-        </ToastProvider>
-      </SignalProvider>
-    </ApiProvider>
+    <QueryClientProvider client={queryClient}>
+      <ApiProvider registry={apiRegistry}>
+        <OrpcQueryProvider>
+          <SignalProvider backendUrl={baseUrl}>
+            <ToastProvider>
+              <AppContent />
+            </ToastProvider>
+          </SignalProvider>
+        </OrpcQueryProvider>
+      </ApiProvider>
+      {/* DevTools only in development - toggle with keyboard or floating button */}
+      <ReactQueryDevtools initialIsOpen={false} buttonPosition="bottom-left" />
+    </QueryClientProvider>
   );
 }