@checkstack/maintenance-common 0.2.0 → 0.3.0

package/CHANGELOG.md

@@ -1,5 +1,66 @@
 # @checkstack/maintenance-common
 
+## 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/signal-common@0.1.1
+
 ## 0.2.0
 
 ### Minor Changes

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@checkstack/maintenance-common",
-  "version": "0.2.0",
+  "version": "0.3.0",
   "type": "module",
   "exports": {
     ".": {

package/src/access.ts

@@ -1,4 +1,4 @@
-import { accessPair } from "@checkstack/common";
+import { access, accessPair } from "@checkstack/common";
 
 /**
  * Access rules for the Maintenance plugin.
@@ -7,6 +7,7 @@ export const maintenanceAccess = {
   /**
    * Maintenance access with both read and manage levels.
    * Read is public by default.
+   * Uses system-level instance access for team-based filtering.
    */
   maintenance: accessPair(
     "maintenance",
@@ -16,10 +17,26 @@ export const maintenanceAccess = {
         "Manage planned maintenances - create, edit, delete, and add updates",
     },
     {
+      idParam: "systemId",
       readIsDefault: true,
       readIsPublic: true,
     }
   ),
+
+  /**
+   * Bulk maintenance access for viewing maintenances for multiple systems.
+   * Uses recordKey for filtering the output record by accessible system IDs.
+   */
+  bulkMaintenance: access(
+    "maintenance.maintenance",
+    "read",
+    "View planned maintenances",
+    {
+      recordKey: "maintenances",
+      isDefault: true,
+      isPublic: true,
+    }
+  ),
 };
 
 /**

package/src/rpc-contract.ts

@@ -1,9 +1,5 @@
-import { oc } from "@orpc/contract";
 import { z } from "zod";
-import {
-  createClientDefinition,
-  type ProcedureMetadata,
-} from "@checkstack/common";
+import { createClientDefinition, proc } from "@checkstack/common";
 import { maintenanceAccess } from "./access";
 import { pluginMetadata } from "./plugin-metadata";
 import {
@@ -16,15 +12,13 @@ import {
   MaintenanceStatusEnum,
 } from "./schemas";
 
-const _base = oc.$meta<ProcedureMetadata>({});
-
 export const maintenanceContract = {
   /** List all maintenances with optional status filter */
-  listMaintenances: _base
-    .meta({
-      userType: "public",
-      access: [maintenanceAccess.maintenance.read],
-    })
+  listMaintenances: proc({
+    operationType: "query",
+    userType: "public",
+    access: [maintenanceAccess.maintenance.read],
+  })
     .input(
       z
         .object({
@@ -36,65 +30,83 @@ export const maintenanceContract = {
     .output(z.object({ maintenances: z.array(MaintenanceWithSystemsSchema) })),
 
   /** Get a single maintenance with all details */
-  getMaintenance: _base
-    .meta({
-      userType: "public",
-      access: [maintenanceAccess.maintenance.read],
-    })
+  getMaintenance: proc({
+    operationType: "query",
+    userType: "public",
+    access: [maintenanceAccess.maintenance.read],
+  })
     .input(z.object({ id: z.string() }))
     .output(MaintenanceDetailSchema.nullable()),
 
   /** Get active or upcoming maintenances for a specific system */
-  getMaintenancesForSystem: _base
-    .meta({
-      userType: "public",
-      access: [maintenanceAccess.maintenance.read],
-    })
+  getMaintenancesForSystem: proc({
+    operationType: "query",
+    userType: "public",
+    access: [maintenanceAccess.maintenance.read],
+  })
     .input(z.object({ systemId: z.string() }))
     .output(z.array(MaintenanceWithSystemsSchema)),
 
+  /** Get active maintenances for multiple systems in a single request.
+   * Used for efficient dashboard rendering to avoid N+1 queries.
+   */
+  getBulkMaintenancesForSystems: proc({
+    operationType: "query",
+    userType: "public",
+    access: [maintenanceAccess.bulkMaintenance],
+  })
+    .input(z.object({ systemIds: z.array(z.string()) }))
+    .output(
+      z.object({
+        maintenances: z.record(
+          z.string(),
+          z.array(MaintenanceWithSystemsSchema)
+        ),
+      })
+    ),
+
   /** Create a new maintenance */
-  createMaintenance: _base
-    .meta({
-      userType: "authenticated",
-      access: [maintenanceAccess.maintenance.manage],
-    })
+  createMaintenance: proc({
+    operationType: "mutation",
+    userType: "authenticated",
+    access: [maintenanceAccess.maintenance.manage],
+  })
     .input(CreateMaintenanceInputSchema)
     .output(MaintenanceWithSystemsSchema),
 
   /** Update an existing maintenance */
-  updateMaintenance: _base
-    .meta({
-      userType: "authenticated",
-      access: [maintenanceAccess.maintenance.manage],
-    })
+  updateMaintenance: proc({
+    operationType: "mutation",
+    userType: "authenticated",
+    access: [maintenanceAccess.maintenance.manage],
+  })
     .input(UpdateMaintenanceInputSchema)
     .output(MaintenanceWithSystemsSchema),
 
   /** Add a status update to a maintenance */
-  addUpdate: _base
-    .meta({
-      userType: "authenticated",
-      access: [maintenanceAccess.maintenance.manage],
-    })
+  addUpdate: proc({
+    operationType: "mutation",
+    userType: "authenticated",
+    access: [maintenanceAccess.maintenance.manage],
+  })
     .input(AddMaintenanceUpdateInputSchema)
     .output(MaintenanceUpdateSchema),
 
   /** Close a maintenance early (sets status to completed) */
-  closeMaintenance: _base
-    .meta({
-      userType: "authenticated",
-      access: [maintenanceAccess.maintenance.manage],
-    })
+  closeMaintenance: proc({
+    operationType: "mutation",
+    userType: "authenticated",
+    access: [maintenanceAccess.maintenance.manage],
+  })
     .input(z.object({ id: z.string(), message: z.string().optional() }))
     .output(MaintenanceWithSystemsSchema),
 
   /** Delete a maintenance */
-  deleteMaintenance: _base
-    .meta({
-      userType: "authenticated",
-      access: [maintenanceAccess.maintenance.manage],
-    })
+  deleteMaintenance: proc({
+    operationType: "mutation",
+    userType: "authenticated",
+    access: [maintenanceAccess.maintenance.manage],
+  })
     .input(z.object({ id: z.string() }))
     .output(z.object({ success: z.boolean() })),
 };