@checkstack/incident-common 0.1.0 → 0.3.0

package/CHANGELOG.md

@@ -1,5 +1,142 @@
 # @checkstack/incident-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
+
+- 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
+  - @checkstack/frontend-api@0.1.0
+  - @checkstack/signal-common@0.1.0
+
 ## 0.1.0
 
 ### Minor Changes

package/package.json

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

package/src/access.ts

@@ -0,0 +1,42 @@
+import { access, accessPair } from "@checkstack/common";
+
+/**
+ * Access rules for the Incident plugin.
+ */
+export const incidentAccess = {
+  /**
+   * Incident access with both read and manage levels.
+   * Read is public by default.
+   * Uses system-level instance access for team-based filtering.
+   */
+  incident: accessPair(
+    "incident",
+    {
+      read: "View incidents",
+      manage: "Manage incidents - create, edit, resolve, and delete",
+    },
+    {
+      idParam: "systemId",
+      readIsDefault: true,
+      readIsPublic: true,
+    }
+  ),
+
+  /**
+   * Bulk incident access for viewing incidents for multiple systems.
+   * Uses recordKey for filtering the output record by accessible system IDs.
+   */
+  bulkIncident: access("incident.incident", "read", "View incidents", {
+    recordKey: "incidents",
+    isDefault: true,
+    isPublic: true,
+  }),
+};
+
+/**
+ * All access rules for registration with the plugin system.
+ */
+export const incidentAccessRules = [
+  incidentAccess.incident.read,
+  incidentAccess.incident.manage,
+];

package/src/index.ts

@@ -1,4 +1,4 @@
-export { permissions, permissionList } from "./permissions";
+export { incidentAccess, incidentAccessRules } from "./access";
 export {
   incidentContract,
   IncidentApi,

package/src/rpc-contract.ts

@@ -1,11 +1,6 @@
-import { oc } from "@orpc/contract";
 import { z } from "zod";
-import {
-  createClientDefinition,
-  createResourceAccessList,
-  type ProcedureMetadata,
-} from "@checkstack/common";
-import { permissions } from "./permissions";
+import { createClientDefinition, proc } from "@checkstack/common";
+import { incidentAccess } from "./access";
 import { pluginMetadata } from "./plugin-metadata";
 import {
   IncidentWithSystemsSchema,
@@ -17,19 +12,13 @@ import {
   IncidentStatusEnum,
 } from "./schemas";
 
-const _base = oc.$meta<ProcedureMetadata>({});
-
-// Resource access configurations for team-based access control
-const incidentListAccess = createResourceAccessList("incident", "incidents");
-
 export const incidentContract = {
   /** List all incidents with optional filters */
-  listIncidents: _base
-    .meta({
-      userType: "public",
-      permissions: [permissions.incidentRead.id],
-      resourceAccess: [incidentListAccess],
-    })
+  listIncidents: proc({
+    operationType: "query",
+    userType: "public",
+    access: [incidentAccess.incident.read],
+  })
     .input(
       z
         .object({
@@ -42,65 +31,80 @@ export const incidentContract = {
     .output(z.object({ incidents: z.array(IncidentWithSystemsSchema) })),
 
   /** Get a single incident with all details */
-  getIncident: _base
-    .meta({
-      userType: "public",
-      permissions: [permissions.incidentRead.id],
-    })
+  getIncident: proc({
+    operationType: "query",
+    userType: "public",
+    access: [incidentAccess.incident.read],
+  })
     .input(z.object({ id: z.string() }))
     .output(IncidentDetailSchema.nullable()),
 
   /** Get active incidents for a specific system */
-  getIncidentsForSystem: _base
-    .meta({
-      userType: "public",
-      permissions: [permissions.incidentRead.id],
-    })
+  getIncidentsForSystem: proc({
+    operationType: "query",
+    userType: "public",
+    access: [incidentAccess.incident.read],
+  })
     .input(z.object({ systemId: z.string() }))
     .output(z.array(IncidentWithSystemsSchema)),
 
+  /** Get active incidents for multiple systems in a single request.
+   * Used for efficient dashboard rendering to avoid N+1 queries.
+   */
+  getBulkIncidentsForSystems: proc({
+    operationType: "query",
+    userType: "public",
+    access: [incidentAccess.bulkIncident],
+  })
+    .input(z.object({ systemIds: z.array(z.string()) }))
+    .output(
+      z.object({
+        incidents: z.record(z.string(), z.array(IncidentWithSystemsSchema)),
+      })
+    ),
+
   /** Create a new incident */
-  createIncident: _base
-    .meta({
-      userType: "authenticated",
-      permissions: [permissions.incidentManage.id],
-    })
+  createIncident: proc({
+    operationType: "mutation",
+    userType: "authenticated",
+    access: [incidentAccess.incident.manage],
+  })
     .input(CreateIncidentInputSchema)
     .output(IncidentWithSystemsSchema),
 
   /** Update an existing incident */
-  updateIncident: _base
-    .meta({
-      userType: "authenticated",
-      permissions: [permissions.incidentManage.id],
-    })
+  updateIncident: proc({
+    operationType: "mutation",
+    userType: "authenticated",
+    access: [incidentAccess.incident.manage],
+  })
     .input(UpdateIncidentInputSchema)
     .output(IncidentWithSystemsSchema),
 
   /** Add a status update to an incident */
-  addUpdate: _base
-    .meta({
-      userType: "authenticated",
-      permissions: [permissions.incidentManage.id],
-    })
+  addUpdate: proc({
+    operationType: "mutation",
+    userType: "authenticated",
+    access: [incidentAccess.incident.manage],
+  })
     .input(AddIncidentUpdateInputSchema)
     .output(IncidentUpdateSchema),
 
   /** Resolve an incident (sets status to resolved) */
-  resolveIncident: _base
-    .meta({
-      userType: "authenticated",
-      permissions: [permissions.incidentManage.id],
-    })
+  resolveIncident: proc({
+    operationType: "mutation",
+    userType: "authenticated",
+    access: [incidentAccess.incident.manage],
+  })
     .input(z.object({ id: z.string(), message: z.string().optional() }))
     .output(IncidentWithSystemsSchema),
 
   /** Delete an incident */
-  deleteIncident: _base
-    .meta({
-      userType: "authenticated",
-      permissions: [permissions.incidentManage.id],
-    })
+  deleteIncident: proc({
+    operationType: "mutation",
+    userType: "authenticated",
+    access: [incidentAccess.incident.manage],
+  })
     .input(z.object({ id: z.string() }))
     .output(z.object({ success: z.boolean() })),
 };

package/src/permissions.ts

@@ -1,13 +0,0 @@
-import { createPermission, type Permission } from "@checkstack/common";
-
-export const permissions = {
-  /** Read access to incidents - granted to all users by default */
-  incidentRead: createPermission("incident", "read", "View incidents", {
-    isAuthenticatedDefault: true,
-    isPublicDefault: true,
-  }),
-  /** Manage incidents - create, edit, resolve, and delete */
-  incidentManage: createPermission("incident", "manage", "Manage incidents"),
-} as const satisfies Record<string, Permission>;
-
-export const permissionList = Object.values(permissions);