@checkmate-monitor/incident-common 0.1.0

package/CHANGELOG.md

@@ -0,0 +1,30 @@
+# @checkmate-monitor/incident-common
+
+## 0.1.0
+
+### Minor Changes
+
+- 4dd644d: Enable external application (API key) access to management endpoints
+
+  Changed `userType: "user"` to `userType: "authenticated"` for 52 endpoints across 5 packages, allowing external applications (service accounts with API keys) to call these endpoints programmatically while maintaining RBAC permission checks:
+
+  - **incident-common**: createIncident, updateIncident, addUpdate, resolveIncident, deleteIncident
+  - **maintenance-common**: createMaintenance, updateMaintenance, addUpdate, closeMaintenance, deleteMaintenance
+  - **catalog-common**: System CRUD, Group CRUD, addSystemToGroup, removeSystemFromGroup
+  - **healthcheck-common**: Configuration management, system associations, retention config, detailed history
+  - **integration-common**: Subscription management, connection management, event discovery, delivery logs
+
+  This enables automation use cases such as:
+
+  - Creating incidents from external monitoring systems (Prometheus, Grafana)
+  - Scheduling maintenances from CI/CD pipelines
+  - Managing catalog systems from infrastructure-as-code tools
+  - Configuring health checks from deployment scripts
+
+### Patch Changes
+
+- Updated dependencies [ffc28f6]
+- Updated dependencies [b55fae6]
+  - @checkmate-monitor/common@0.1.0
+  - @checkmate-monitor/signal-common@0.1.0
+  - @checkmate-monitor/frontend-api@0.0.2

package/package.json

@@ -0,0 +1,27 @@
+{
+  "name": "@checkmate-monitor/incident-common",
+  "version": "0.1.0",
+  "type": "module",
+  "exports": {
+    ".": {
+      "import": "./src/index.ts"
+    }
+  },
+  "dependencies": {
+    "@checkmate-monitor/common": "workspace:*",
+    "@checkmate-monitor/frontend-api": "workspace:*",
+    "@checkmate-monitor/signal-common": "workspace:*",
+    "@orpc/contract": "^1.13.2",
+    "zod": "^4.2.1"
+  },
+  "devDependencies": {
+    "typescript": "^5.7.2",
+    "@checkmate-monitor/tsconfig": "workspace:*",
+    "@checkmate-monitor/scripts": "workspace:*"
+  },
+  "scripts": {
+    "typecheck": "tsc --noEmit",
+    "lint": "bun run lint:code",
+    "lint:code": "eslint . --max-warnings 0"
+  }
+}

package/src/index.ts

@@ -0,0 +1,49 @@
+export { permissions, permissionList } from "./permissions";
+export {
+  incidentContract,
+  IncidentApi,
+  type IncidentContract,
+} from "./rpc-contract";
+export {
+  IncidentStatusEnum,
+  IncidentSeverityEnum,
+  IncidentSchema,
+  IncidentWithSystemsSchema,
+  IncidentUpdateSchema,
+  IncidentDetailSchema,
+  CreateIncidentInputSchema,
+  UpdateIncidentInputSchema,
+  AddIncidentUpdateInputSchema,
+  type IncidentStatus,
+  type IncidentSeverity,
+  type Incident,
+  type IncidentWithSystems,
+  type IncidentUpdate,
+  type IncidentDetail,
+  type CreateIncidentInput,
+  type UpdateIncidentInput,
+  type AddIncidentUpdateInput,
+} from "./schemas";
+export { IncidentDetailsSlot, IncidentStatusSlot } from "./slots";
+export * from "./plugin-metadata";
+export { incidentRoutes } from "./routes";
+
+// =============================================================================
+// REALTIME SIGNALS
+// =============================================================================
+
+import { createSignal } from "@checkmate-monitor/signal-common";
+import { z } from "zod";
+
+/**
+ * Broadcast when an incident is created, updated, or resolved.
+ * Frontend components listening to this signal can refetch state for affected systems.
+ */
+export const INCIDENT_UPDATED = createSignal(
+  "incident.updated",
+  z.object({
+    incidentId: z.string(),
+    systemIds: z.array(z.string()),
+    action: z.enum(["created", "updated", "resolved", "deleted"]),
+  })
+);

package/src/permissions.ts

@@ -0,0 +1,13 @@
+import { createPermission, type Permission } from "@checkmate-monitor/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);

package/src/plugin-metadata.ts

@@ -0,0 +1,9 @@
+import { definePluginMetadata } from "@checkmate-monitor/common";
+
+/**
+ * Plugin metadata for the incident plugin.
+ * Exported from the common package so both backend and frontend can reference it.
+ */
+export const pluginMetadata = definePluginMetadata({
+  pluginId: "incident",
+});

package/src/routes.ts

@@ -0,0 +1,30 @@
+import { createRoutes } from "@checkmate-monitor/common";
+
+/**
+ * Route definitions for the incident plugin.
+ * Import and use these routes in both frontend plugins and for link generation.
+ *
+ * @example Frontend plugin usage
+ * ```tsx
+ * import { incidentRoutes } from "@checkmate-monitor/incident-common";
+ *
+ * createFrontendPlugin({
+ *   routes: [
+ *     { route: incidentRoutes.routes.config, element: <ConfigPage /> },
+ *   ],
+ * });
+ * ```
+ *
+ * @example Link generation
+ * ```tsx
+ * import { incidentRoutes } from "@checkmate-monitor/incident-common";
+ * import { resolveRoute } from "@checkmate-monitor/common";
+ *
+ * const detailPath = resolveRoute(incidentRoutes.routes.detail, { incidentId });
+ * ```
+ */
+export const incidentRoutes = createRoutes("incident", {
+  config: "/config",
+  detail: "/:incidentId",
+  systemHistory: "/system/:systemId/incidents",
+});

package/src/rpc-contract.ts

@@ -0,0 +1,111 @@
+import { oc } from "@orpc/contract";
+import { z } from "zod";
+import {
+  createClientDefinition,
+  type ProcedureMetadata,
+} from "@checkmate-monitor/common";
+import { permissions } from "./permissions";
+import { pluginMetadata } from "./plugin-metadata";
+import {
+  IncidentWithSystemsSchema,
+  IncidentDetailSchema,
+  IncidentUpdateSchema,
+  CreateIncidentInputSchema,
+  UpdateIncidentInputSchema,
+  AddIncidentUpdateInputSchema,
+  IncidentStatusEnum,
+} from "./schemas";
+
+const _base = oc.$meta<ProcedureMetadata>({});
+
+export const incidentContract = {
+  /** List all incidents with optional filters */
+  listIncidents: _base
+    .meta({
+      userType: "public",
+      permissions: [permissions.incidentRead.id],
+    })
+    .input(
+      z
+        .object({
+          status: IncidentStatusEnum.optional(),
+          systemId: z.string().optional(),
+          includeResolved: z.boolean().optional().default(false),
+        })
+        .optional()
+    )
+    .output(z.array(IncidentWithSystemsSchema)),
+
+  /** Get a single incident with all details */
+  getIncident: _base
+    .meta({
+      userType: "public",
+      permissions: [permissions.incidentRead.id],
+    })
+    .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],
+    })
+    .input(z.object({ systemId: z.string() }))
+    .output(z.array(IncidentWithSystemsSchema)),
+
+  /** Create a new incident */
+  createIncident: _base
+    .meta({
+      userType: "authenticated",
+      permissions: [permissions.incidentManage.id],
+    })
+    .input(CreateIncidentInputSchema)
+    .output(IncidentWithSystemsSchema),
+
+  /** Update an existing incident */
+  updateIncident: _base
+    .meta({
+      userType: "authenticated",
+      permissions: [permissions.incidentManage.id],
+    })
+    .input(UpdateIncidentInputSchema)
+    .output(IncidentWithSystemsSchema),
+
+  /** Add a status update to an incident */
+  addUpdate: _base
+    .meta({
+      userType: "authenticated",
+      permissions: [permissions.incidentManage.id],
+    })
+    .input(AddIncidentUpdateInputSchema)
+    .output(IncidentUpdateSchema),
+
+  /** Resolve an incident (sets status to resolved) */
+  resolveIncident: _base
+    .meta({
+      userType: "authenticated",
+      permissions: [permissions.incidentManage.id],
+    })
+    .input(z.object({ id: z.string(), message: z.string().optional() }))
+    .output(IncidentWithSystemsSchema),
+
+  /** Delete an incident */
+  deleteIncident: _base
+    .meta({
+      userType: "authenticated",
+      permissions: [permissions.incidentManage.id],
+    })
+    .input(z.object({ id: z.string() }))
+    .output(z.object({ success: z.boolean() })),
+};
+
+// Export contract type
+export type IncidentContract = typeof incidentContract;
+
+// Export client definition for type-safe forPlugin usage
+// Use: const client = rpcApi.forPlugin(IncidentApi);
+export const IncidentApi = createClientDefinition(
+  incidentContract,
+  pluginMetadata
+);

package/src/schemas.ts

@@ -0,0 +1,95 @@
+import { z } from "zod";
+
+/**
+ * Incident status enum values.
+ * Represents the lifecycle stages of an incident.
+ */
+export const IncidentStatusEnum = z.enum([
+  "investigating",
+  "identified",
+  "fixing",
+  "monitoring",
+  "resolved",
+]);
+export type IncidentStatus = z.infer<typeof IncidentStatusEnum>;
+
+/**
+ * Incident severity enum values.
+ * Represents the impact level of an incident.
+ */
+export const IncidentSeverityEnum = z.enum(["minor", "major", "critical"]);
+export type IncidentSeverity = z.infer<typeof IncidentSeverityEnum>;
+
+/**
+ * Core incident entity schema
+ */
+export const IncidentSchema = z.object({
+  id: z.string(),
+  title: z.string(),
+  description: z.string().optional(),
+  status: IncidentStatusEnum,
+  severity: IncidentSeverityEnum,
+  createdAt: z.date(),
+  updatedAt: z.date(),
+});
+export type Incident = z.infer<typeof IncidentSchema>;
+
+/**
+ * Incident with related systems
+ */
+export const IncidentWithSystemsSchema = IncidentSchema.extend({
+  systemIds: z.array(z.string()),
+});
+export type IncidentWithSystems = z.infer<typeof IncidentWithSystemsSchema>;
+
+/**
+ * Incident update schema - status updates posted to an incident
+ */
+export const IncidentUpdateSchema = z.object({
+  id: z.string(),
+  incidentId: z.string(),
+  message: z.string(),
+  statusChange: IncidentStatusEnum.optional(),
+  createdAt: z.date(),
+  createdBy: z.string().optional(),
+});
+export type IncidentUpdate = z.infer<typeof IncidentUpdateSchema>;
+
+/**
+ * Full incident detail with systems and updates
+ */
+export const IncidentDetailSchema = IncidentWithSystemsSchema.extend({
+  updates: z.array(IncidentUpdateSchema),
+});
+export type IncidentDetail = z.infer<typeof IncidentDetailSchema>;
+
+// Input schemas for mutations
+export const CreateIncidentInputSchema = z.object({
+  title: z.string().min(1, "Title is required"),
+  description: z.string().optional(),
+  severity: IncidentSeverityEnum,
+  systemIds: z.array(z.string()).min(1, "At least one system is required"),
+  initialMessage: z
+    .string()
+    .optional()
+    .describe("Optional initial status update message"),
+});
+export type CreateIncidentInput = z.infer<typeof CreateIncidentInputSchema>;
+
+export const UpdateIncidentInputSchema = z.object({
+  id: z.string(),
+  title: z.string().min(1).optional(),
+  description: z.string().nullable().optional(),
+  severity: IncidentSeverityEnum.optional(),
+  systemIds: z.array(z.string()).min(1).optional(),
+});
+export type UpdateIncidentInput = z.infer<typeof UpdateIncidentInputSchema>;
+
+export const AddIncidentUpdateInputSchema = z.object({
+  incidentId: z.string(),
+  message: z.string().min(1, "Message is required"),
+  statusChange: IncidentStatusEnum.optional(),
+});
+export type AddIncidentUpdateInput = z.infer<
+  typeof AddIncidentUpdateInputSchema
+>;

package/src/slots.ts

@@ -0,0 +1,18 @@
+import { createSlot } from "@checkmate-monitor/frontend-api";
+import type { IncidentWithSystems } from "./schemas";
+
+/**
+ * Slot for extending incident detail views.
+ * Plugins can add additional content or actions to incident details.
+ */
+export const IncidentDetailsSlot = createSlot<{
+  incident: IncidentWithSystems;
+}>("plugin.incident.details");
+
+/**
+ * Slot for adding custom status indicators to incidents.
+ * Can be used to show external integrations, alerts, etc.
+ */
+export const IncidentStatusSlot = createSlot<{
+  incident: IncidentWithSystems;
+}>("plugin.incident.status");

package/tsconfig.json

@@ -0,0 +1,6 @@
+{
+  "extends": "@checkmate-monitor/tsconfig/common.json",
+  "include": [
+    "src"
+  ]
+}