@checkstack/frontend-api 0.0.4 → 0.2.0

package/CHANGELOG.md

@@ -1,5 +1,138 @@
 # @checkstack/frontend-api
 
+## 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/common@0.3.0
+
+## 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 [f533141]
+  - @checkstack/common@0.2.0
+
 ## 0.0.4
 
 ### Patch Changes

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@checkstack/frontend-api",
-  "version": "0.0.4",
+  "version": "0.2.0",
   "type": "module",
   "main": "./src/index.ts",
   "scripts": {
@@ -13,7 +13,10 @@
   },
   "dependencies": {
     "@checkstack/common": "workspace:*",
-    "@orpc/client": "^1.13.2"
+    "@orpc/client": "^1.13.2",
+    "@orpc/react-query": "1.13.4",
+    "@orpc/tanstack-query": "^1.13.2",
+    "@tanstack/react-query": "^5.64.0"
   },
   "devDependencies": {
     "@types/bun": "^1.3.5",

package/src/core-apis.ts

@@ -1,8 +1,4 @@
-import {
-  PermissionAction,
-  ClientDefinition,
-  InferClient,
-} from "@checkstack/common";
+import { AccessRule, ClientDefinition, InferClient } from "@checkstack/common";
 import { createApiRef } from "./api-ref";
 
 export interface LoggerApi {
@@ -22,16 +18,30 @@ export interface FetchApi {
 export const loggerApiRef = createApiRef<LoggerApi>("core.logger");
 export const fetchApiRef = createApiRef<FetchApi>("core.fetch");
 
-export interface PermissionApi {
-  usePermission(permission: string): { loading: boolean; allowed: boolean };
-  useResourcePermission(
-    resource: string,
-    action: PermissionAction
-  ): { loading: boolean; allowed: boolean };
-  useManagePermission(resource: string): { loading: boolean; allowed: boolean };
+/**
+ * Unified access API for checking user access via AccessRules.
+ *
+ * Uses the same AccessRule objects from plugin common packages
+ * that are used in backend contracts.
+ */
+export interface AccessApi {
+  /**
+   * Check if the current user has access based on an AccessRule.
+   *
+   * @example
+   * ```tsx
+   * import { catalogAccess } from "@checkstack/catalog-common";
+   *
+   * const { allowed, loading } = accessApi.useAccess(catalogAccess.system.manage);
+   * if (allowed) {
+   *   // User can manage systems
+   * }
+   * ```
+   */
+  useAccess(accessRule: AccessRule): { loading: boolean; allowed: boolean };
 }
 
-export const permissionApiRef = createApiRef<PermissionApi>("core.permission");
+export const accessApiRef = createApiRef<AccessApi>("core.access");
 
 export interface RpcApi {
   client: unknown;

package/src/index.ts

@@ -8,3 +8,4 @@ export * from "./utils";
 export * from "./slots";
 export * from "./use-plugin-route";
 export * from "./runtime-config";
+export * from "./orpc-query";

package/src/orpc-query.tsx

@@ -0,0 +1,341 @@
+import { createContext, useContext, useMemo, type ReactNode } from "react";
+import {
+  createRouterUtils,
+  type RouterUtils,
+  type ProcedureUtils,
+} from "@orpc/react-query";
+import type { NestedClient, ClientContext } from "@orpc/client";
+import {
+  useQuery,
+  useMutation,
+  type UseQueryResult,
+  type UseMutationResult,
+  type UseQueryOptions,
+  type UseMutationOptions,
+} from "@tanstack/react-query";
+import { useApi } from "./api-context";
+import { rpcApiRef } from "./core-apis";
+import type { ClientDefinition, InferClient } from "@checkstack/common";
+import type { ContractProcedure, AnyContractRouter } from "@orpc/contract";
+
+// =============================================================================
+// TYPES
+// =============================================================================
+
+type OrpcUtils = RouterUtils<NestedClient<ClientContext>>;
+
+// =============================================================================
+// CONTEXT
+// =============================================================================
+
+const OrpcQueryContext = createContext<OrpcUtils | undefined>(undefined);
+
+// =============================================================================
+// PROVIDER
+// =============================================================================
+
+interface OrpcQueryProviderProps {
+  children: ReactNode;
+}
+
+/**
+ * Provides oRPC React Query utilities to the application.
+ * Must be inside ApiProvider and QueryClientProvider.
+ */
+export const OrpcQueryProvider: React.FC<OrpcQueryProviderProps> = ({
+  children,
+}) => {
+  const rpcApi = useApi(rpcApiRef);
+
+  const orpcUtils = useMemo(() => {
+    return createRouterUtils(rpcApi.client as NestedClient<ClientContext>);
+  }, [rpcApi.client]);
+
+  return (
+    <OrpcQueryContext.Provider value={orpcUtils}>
+      {children}
+    </OrpcQueryContext.Provider>
+  );
+};
+
+// =============================================================================
+// INTERNAL
+// =============================================================================
+
+function useOrpcUtils(): OrpcUtils {
+  const context = useContext(OrpcQueryContext);
+  if (!context) {
+    throw new Error(
+      "usePluginClient must be used within OrpcQueryProvider. " +
+        "Wrap your app with <OrpcQueryProvider>."
+    );
+  }
+  return context;
+}
+
+// =============================================================================
+// TYPE HELPERS FOR STRICT operationType INFERENCE
+// =============================================================================
+
+/**
+ * Query procedure hook interface - only exposes useQuery.
+ * Input is optional when the procedure has no input schema.
+ */
+interface QueryProcedure<TInput, TOutput> {
+  useQuery: (
+    input?: TInput,
+    options?: Omit<UseQueryOptions<TOutput, Error>, "queryKey" | "queryFn">
+  ) => UseQueryResult<TOutput, Error>;
+}
+
+/**
+ * Mutation procedure hook interface - only exposes useMutation.
+ * Mutations don't take input directly - it's passed to mutate/mutateAsync.
+ */
+interface MutationProcedure<TInput, TOutput> {
+  useMutation: (
+    options?: Omit<
+      UseMutationOptions<TOutput, Error, TInput>,
+      "mutationFn" | "mutationKey"
+    >
+  ) => UseMutationResult<TOutput, Error, TInput>;
+}
+
+/**
+ * Maps a contract procedure to the appropriate hook type based on operationType.
+ * Extracts input/output types from ContractProcedure's schema types.
+ */
+type WrappedProcedure<TContractProcedure, _TClientProcedure> =
+  TContractProcedure extends ContractProcedure<
+    infer TInputSchema,
+    infer TOutputSchema,
+    infer _TErrors,
+    infer TMeta
+  >
+    ? TMeta extends { operationType: "mutation" }
+      ? MutationProcedure<
+          InferSchemaInputType<TInputSchema>,
+          InferSchemaOutputType<TOutputSchema>
+        >
+      : QueryProcedure<
+          InferSchemaInputType<TInputSchema>,
+          InferSchemaOutputType<TOutputSchema>
+        >
+    : never;
+
+/**
+ * Extract input type from Zod schema.
+ * Zod schemas have { _input: T } for input inference.
+ * Returns empty object when no input schema is defined (unknown input),
+ * allowing useQuery({}) calls for parameterless procedures.
+ */
+type InferSchemaInputType<T> = T extends { _input: infer I }
+  ? unknown extends I
+    ? Record<string, never>
+    : I
+  : Record<string, never>;
+
+/**
+ * Extract output type from Zod schema.
+ * Zod schemas have { _output: T } for output inference.
+ */
+type InferSchemaOutputType<T> = T extends { _output: infer O } ? O : unknown;
+
+/**
+ * Check if a contract type is a procedure (not a nested router).
+ */
+type IsContractProcedure<T> = T extends ContractProcedure<
+  infer _TInput,
+  infer _TOutput,
+  infer _TErrors,
+  infer _TMeta
+>
+  ? true
+  : false;
+
+/**
+ * Maps a contract router to wrapped procedures based on operationType.
+ * Recursively handles nested routers.
+ */
+type WrappedClient<TContract extends AnyContractRouter, TClient> = {
+  [K in keyof TClient & keyof TContract]: IsContractProcedure<
+    TContract[K]
+  > extends true
+    ? WrappedProcedure<TContract[K], TClient[K]>
+    : TClient[K] extends object
+    ? TContract[K] extends AnyContractRouter
+      ? WrappedClient<TContract[K], TClient[K]>
+      : never
+    : never;
+};
+
+// =============================================================================
+// HOOK: usePluginClient
+// =============================================================================
+
+/**
+ * Access a plugin's RPC client with TanStack Query integration.
+ *
+ * Each procedure exposes only the appropriate hook based on its operationType:
+ * - `operationType: "query"` → `.useQuery(input, options)`
+ * - `operationType: "mutation"` → `.useMutation(options)`
+ *
+ * @example
+ * ```tsx
+ * const catalog = usePluginClient(CatalogApi);
+ *
+ * // Queries (only useQuery available)
+ * const { data, isLoading } = catalog.getEntities.useQuery({});
+ *
+ * // Mutations (only useMutation available)
+ * const deleteMutation = catalog.deleteSystem.useMutation({
+ *   onSuccess: () => toast.success("Deleted!"),
+ * });
+ *
+ * const handleDelete = () => {
+ *   deleteMutation.mutate({ systemId });
+ * };
+ * ```
+ */
+export function usePluginClient<T extends ClientDefinition>(
+  definition: T
+): WrappedClient<NonNullable<T["__contractType"]>, InferClient<T>> {
+  const orpcUtils = useOrpcUtils();
+
+  const pluginUtils = (orpcUtils as Record<string, unknown>)[
+    definition.pluginId
+  ] as Record<string, unknown> | undefined;
+
+  if (!pluginUtils) {
+    throw new Error(
+      `Plugin "${definition.pluginId}" not found. ` +
+        `Ensure the plugin is registered and the backend is running.`
+    );
+  }
+
+  // Get contract for operationType checking
+  const contract = definition.contract as Record<string, unknown>;
+
+  return useMemo(() => {
+    return wrapPluginUtils(pluginUtils, contract);
+  }, [pluginUtils, contract]) as WrappedClient<
+    NonNullable<T["__contractType"]>,
+    InferClient<T>
+  >;
+}
+
+// =============================================================================
+// WRAPPER IMPLEMENTATION
+// =============================================================================
+
+function wrapPluginUtils(
+  utils: Record<string, unknown>,
+  contract: Record<string, unknown>
+): Record<string, unknown> {
+  const wrapped: Record<string, unknown> = {};
+
+  // Iterate over CONTRACT keys (procedure names like "getTheme", "getSystems")
+  // not the internal oRPC utility methods ("key", "call", "queryOptions" etc.)
+  for (const key of Object.keys(contract)) {
+    // Skip oRPC internal metadata keys
+    if (key.startsWith("~")) continue;
+
+    const procedureUtils = utils[key] as
+      | ProcedureUtils<ClientContext, unknown, unknown, Error>
+      | Record<string, unknown>
+      | undefined;
+
+    const contractProcedure = contract[key] as
+      | Record<string, unknown>
+      | undefined;
+
+    if (!procedureUtils || typeof procedureUtils !== "object") {
+      // Procedure might not be available in utils
+      continue;
+    }
+
+    // Check if this is a procedure (has queryOptions or mutationOptions method)
+    if (
+      typeof (
+        procedureUtils as ProcedureUtils<ClientContext, unknown, unknown, Error>
+      ).queryOptions === "function" ||
+      typeof (
+        procedureUtils as ProcedureUtils<ClientContext, unknown, unknown, Error>
+      ).mutationOptions === "function"
+    ) {
+      // Get operationType from contract metadata
+      const operationType = getOperationType(contractProcedure, key);
+      wrapped[key] = createProcedureHook(
+        procedureUtils as ProcedureUtils<
+          ClientContext,
+          unknown,
+          unknown,
+          Error
+        >,
+        operationType
+      );
+    } else {
+      // Nested namespace - recurse
+      wrapped[key] = wrapPluginUtils(
+        procedureUtils as Record<string, unknown>,
+        (contractProcedure || {}) as Record<string, unknown>
+      );
+    }
+  }
+
+  return wrapped;
+}
+
+/**
+ * Extract operationType from contract procedure metadata.
+ * Throws if operationType is not defined (required in all contracts).
+ */
+function getOperationType(
+  contractProcedure: Record<string, unknown> | undefined,
+  procedureName?: string
+): "query" | "mutation" {
+  const orpcMeta = contractProcedure?.["~orpc"] as
+    | { meta?: { operationType?: "query" | "mutation" } }
+    | undefined;
+
+  const operationType = orpcMeta?.meta?.operationType;
+
+  if (!operationType) {
+    throw new Error(
+      `Procedure ${
+        procedureName ? `"${procedureName}" ` : ""
+      }is missing required "operationType" in contract metadata. ` +
+        `Add operationType: "query" or operationType: "mutation" to the procedure's .meta() call.`
+    );
+  }
+
+  return operationType;
+}
+
+/**
+ * Creates the appropriate hook wrapper based on operationType.
+ */
+function createProcedureHook<TInput, TOutput>(
+  proc: ProcedureUtils<ClientContext, TInput, TOutput, Error>,
+  operationType: "query" | "mutation"
+): QueryProcedure<TInput, TOutput> | MutationProcedure<TInput, TOutput> {
+  if (operationType === "mutation") {
+    return {
+      useMutation: (options) => {
+        const mutationOpts = proc.mutationOptions(options);
+        return useMutation(mutationOpts);
+      },
+    };
+  }
+
+  return {
+    useQuery: (input, options) => {
+      // Get base query options from oRPC
+      const queryOpts = proc.queryOptions({
+        input: input as TInput,
+      });
+      // Spread caller options AFTER to ensure they take precedence (e.g., enabled: false)
+      return useQuery({ ...queryOpts, ...options });
+    },
+  };
+}

package/src/plugin-registry.ts

@@ -14,7 +14,7 @@ interface ResolvedRoute {
   pluginId: string;
   element?: React.ReactNode;
   title?: string;
-  permission?: string;
+  accessRule?: string;
 }
 
 class PluginRegistry {
@@ -61,7 +61,7 @@ class PluginRegistry {
         pluginId: route.route.pluginId,
         element: route.element,
         title: route.title,
-        permission: route.permission?.id,
+        accessRule: route.accessRule?.id,
       };
 
       // Add to route map for resolution
@@ -175,7 +175,7 @@ class PluginRegistry {
           path: fullPath,
           element: route.element,
           title: route.title,
-          permission: route.permission?.id,
+          accessRule: route.accessRule?.id,
         };
       });
     });

package/src/plugin.ts

@@ -4,7 +4,7 @@ import type { SlotDefinition } from "./slots";
 import type {
   RouteDefinition,
   PluginMetadata,
-  Permission,
+  AccessRule,
 } from "@checkstack/common";
 
 /**
@@ -51,8 +51,8 @@ export interface PluginRoute {
   /** Page title */
   title?: string;
 
-  /** Permission required to access this route (use permission object from common package) */
-  permission?: Permission;
+  /** Access rule required to access this route (use access object from common package) */
+  accessRule?: AccessRule;
 }
 
 /**

package/src/runtime-config.tsx

@@ -15,6 +15,18 @@ interface RuntimeConfigContextValue {
   error: Error | undefined;
 }
 
+// Module-level cache for synchronous access from non-React code
+let cachedConfig: RuntimeConfig | undefined;
+
+/**
+ * Get the cached runtime config synchronously.
+ * Returns undefined if config hasn't been loaded yet.
+ * Use this for class-based APIs that can't use hooks.
+ */
+export function getCachedRuntimeConfig(): RuntimeConfig | undefined {
+  return cachedConfig;
+}
+
 const RuntimeConfigContext = createContext<RuntimeConfigContextValue>({
   config: undefined,
   isLoading: true,
@@ -50,11 +62,14 @@ export const RuntimeConfigProvider: React.FC<RuntimeConfigProviderProps> = ({
           throw new Error(`Failed to fetch config: ${response.status}`);
         }
         const data = (await response.json()) as RuntimeConfig;
+        cachedConfig = data; // Populate module-level cache
         setConfig(data);
       } catch (error_) {
         console.error("RuntimeConfigProvider: Failed to load config", error_);
         // Fallback to localhost for development
-        setConfig({ baseUrl: "http://localhost:3000" });
+        const fallback = { baseUrl: "http://localhost:3000" };
+        cachedConfig = fallback; // Populate cache even on error
+        setConfig(fallback);
         setError(error_ instanceof Error ? error_ : new Error(String(error_)));
       } finally {
         setIsLoading(false);

package/src/slots.ts

@@ -44,10 +44,10 @@ export const NavbarRightSlot = createSlot("core.layout.navbar.right");
 
 /**
  * Context for user menu item slots.
- * Provides the user's permissions array and authentication info for synchronous checks.
+ * Provides the user's access rules array and authentication info for synchronous checks.
  */
 export interface UserMenuItemsContext {
-  permissions: string[];
+  accessRules: string[];
   hasCredentialAccount: boolean;
 }