@checkstack/maintenance-common 0.0.2

package/CHANGELOG.md

@@ -0,0 +1,66 @@
+# @checkstack/maintenance-common
+
+## 0.0.2
+
+### Patch Changes
+
+- d20d274: Initial release of all @checkstack packages. Rebranded from Checkmate to Checkstack with new npm organization @checkstack and domain checkstack.dev.
+- Updated dependencies [d20d274]
+  - @checkstack/common@0.0.2
+  - @checkstack/frontend-api@0.0.2
+  - @checkstack/signal-common@0.0.2
+
+## 0.1.2
+
+### Patch Changes
+
+- Updated dependencies [a65e002]
+- Updated dependencies [ae33df2]
+- Updated dependencies [32ea706]
+  - @checkstack/common@0.2.0
+  - @checkstack/frontend-api@0.1.0
+  - @checkstack/signal-common@0.1.1
+
+## 0.1.1
+
+### Patch Changes
+
+- Updated dependencies [0f8cc7d]
+  - @checkstack/frontend-api@0.0.3
+
+## 0.1.0
+
+### Minor Changes
+
+- eff5b4e: Add standalone maintenance scheduling plugin
+
+  - New `@checkstack/maintenance-common` package with Zod schemas, permissions, oRPC contract, and extension slots
+  - New `@checkstack/maintenance-backend` package with Drizzle schema, service, and oRPC router
+  - New `@checkstack/maintenance-frontend` package with admin page and system detail panel
+  - Shared `DateTimePicker` component added to `@checkstack/ui`
+  - Database migrations for maintenances, maintenance_systems, and maintenance_updates tables
+
+- 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]
+  - @checkstack/common@0.1.0
+  - @checkstack/signal-common@0.1.0
+  - @checkstack/frontend-api@0.0.2

package/package.json

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

package/src/index.ts

@@ -0,0 +1,47 @@
+export { permissions, permissionList } from "./permissions";
+export {
+  maintenanceContract,
+  MaintenanceApi,
+  type MaintenanceContract,
+} from "./rpc-contract";
+export {
+  MaintenanceStatusEnum,
+  MaintenanceSchema,
+  MaintenanceWithSystemsSchema,
+  MaintenanceUpdateSchema,
+  MaintenanceDetailSchema,
+  CreateMaintenanceInputSchema,
+  UpdateMaintenanceInputSchema,
+  AddMaintenanceUpdateInputSchema,
+  type MaintenanceStatus,
+  type Maintenance,
+  type MaintenanceWithSystems,
+  type MaintenanceUpdate,
+  type MaintenanceDetail,
+  type CreateMaintenanceInput,
+  type UpdateMaintenanceInput,
+  type AddMaintenanceUpdateInput,
+} from "./schemas";
+export { MaintenanceDetailsSlot, MaintenanceStatusSlot } from "./slots";
+export * from "./plugin-metadata";
+export { maintenanceRoutes } from "./routes";
+
+// =============================================================================
+// REALTIME SIGNALS
+// =============================================================================
+
+import { createSignal } from "@checkstack/signal-common";
+import { z } from "zod";
+
+/**
+ * Broadcast when a maintenance is created, updated, or closed.
+ * Frontend components listening to this signal can refetch state for affected systems.
+ */
+export const MAINTENANCE_UPDATED = createSignal(
+  "maintenance.updated",
+  z.object({
+    maintenanceId: z.string(),
+    systemIds: z.array(z.string()),
+    action: z.enum(["created", "updated", "closed"]),
+  })
+);

package/src/permissions.ts

@@ -0,0 +1,19 @@
+import { createPermission, type Permission } from "@checkstack/common";
+
+export const permissions = {
+  /** Read access to maintenances - granted to all authenticated users by default */
+  maintenanceRead: createPermission(
+    "maintenance",
+    "read",
+    "View planned maintenances",
+    { isAuthenticatedDefault: true, isPublicDefault: true }
+  ),
+  /** Manage maintenances - create, edit, delete, and add updates */
+  maintenanceManage: createPermission(
+    "maintenance",
+    "manage",
+    "Manage planned maintenances"
+  ),
+} as const satisfies Record<string, Permission>;
+
+export const permissionList = Object.values(permissions);

package/src/plugin-metadata.ts

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

package/src/routes.ts

@@ -0,0 +1,31 @@
+import { createRoutes } from "@checkstack/common";
+
+/**
+ * Route definitions for the maintenance plugin.
+ * Import and use these routes in both frontend plugins and for link generation.
+ *
+ * @example Frontend plugin usage
+ * ```tsx
+ * import { maintenanceRoutes } from "@checkstack/maintenance-common";
+ *
+ * createFrontendPlugin({
+ *   routes: [
+ *     { route: maintenanceRoutes.routes.config, element: <ConfigPage /> },
+ *   ],
+ * });
+ * ```
+ *
+ * @example Link generation
+ * ```tsx
+ * import { maintenanceRoutes } from "@checkstack/maintenance-common";
+ * import { usePluginRoute } from "@checkstack/frontend-api";
+ *
+ * const getRoute = usePluginRoute();
+ * <Link to={getRoute(maintenanceRoutes.routes.config)}>Maintenances</Link>
+ * ```
+ */
+export const maintenanceRoutes = createRoutes("maintenance", {
+  config: "/config",
+  systemHistory: "/system/:systemId/history",
+  detail: "/:maintenanceId",
+});

package/src/rpc-contract.ts

@@ -0,0 +1,110 @@
+import { oc } from "@orpc/contract";
+import { z } from "zod";
+import {
+  createClientDefinition,
+  type ProcedureMetadata,
+} from "@checkstack/common";
+import { permissions } from "./permissions";
+import { pluginMetadata } from "./plugin-metadata";
+import {
+  MaintenanceWithSystemsSchema,
+  MaintenanceDetailSchema,
+  MaintenanceUpdateSchema,
+  CreateMaintenanceInputSchema,
+  UpdateMaintenanceInputSchema,
+  AddMaintenanceUpdateInputSchema,
+  MaintenanceStatusEnum,
+} from "./schemas";
+
+const _base = oc.$meta<ProcedureMetadata>({});
+
+export const maintenanceContract = {
+  /** List all maintenances with optional status filter */
+  listMaintenances: _base
+    .meta({
+      userType: "public",
+      permissions: [permissions.maintenanceRead.id],
+    })
+    .input(
+      z
+        .object({
+          status: MaintenanceStatusEnum.optional(),
+          systemId: z.string().optional(),
+        })
+        .optional()
+    )
+    .output(z.array(MaintenanceWithSystemsSchema)),
+
+  /** Get a single maintenance with all details */
+  getMaintenance: _base
+    .meta({
+      userType: "public",
+      permissions: [permissions.maintenanceRead.id],
+    })
+    .input(z.object({ id: z.string() }))
+    .output(MaintenanceDetailSchema.nullable()),
+
+  /** Get active or upcoming maintenances for a specific system */
+  getMaintenancesForSystem: _base
+    .meta({
+      userType: "public",
+      permissions: [permissions.maintenanceRead.id],
+    })
+    .input(z.object({ systemId: z.string() }))
+    .output(z.array(MaintenanceWithSystemsSchema)),
+
+  /** Create a new maintenance */
+  createMaintenance: _base
+    .meta({
+      userType: "authenticated",
+      permissions: [permissions.maintenanceManage.id],
+    })
+    .input(CreateMaintenanceInputSchema)
+    .output(MaintenanceWithSystemsSchema),
+
+  /** Update an existing maintenance */
+  updateMaintenance: _base
+    .meta({
+      userType: "authenticated",
+      permissions: [permissions.maintenanceManage.id],
+    })
+    .input(UpdateMaintenanceInputSchema)
+    .output(MaintenanceWithSystemsSchema),
+
+  /** Add a status update to a maintenance */
+  addUpdate: _base
+    .meta({
+      userType: "authenticated",
+      permissions: [permissions.maintenanceManage.id],
+    })
+    .input(AddMaintenanceUpdateInputSchema)
+    .output(MaintenanceUpdateSchema),
+
+  /** Close a maintenance early (sets status to completed) */
+  closeMaintenance: _base
+    .meta({
+      userType: "authenticated",
+      permissions: [permissions.maintenanceManage.id],
+    })
+    .input(z.object({ id: z.string(), message: z.string().optional() }))
+    .output(MaintenanceWithSystemsSchema),
+
+  /** Delete a maintenance */
+  deleteMaintenance: _base
+    .meta({
+      userType: "authenticated",
+      permissions: [permissions.maintenanceManage.id],
+    })
+    .input(z.object({ id: z.string() }))
+    .output(z.object({ success: z.boolean() })),
+};
+
+// Export contract type
+export type MaintenanceContract = typeof maintenanceContract;
+
+// Export client definition for type-safe forPlugin usage
+// Use: const client = rpcApi.forPlugin(MaintenanceApi);
+export const MaintenanceApi = createClientDefinition(
+  maintenanceContract,
+  pluginMetadata
+);

package/src/schemas.ts

@@ -0,0 +1,96 @@
+import { z } from "zod";
+
+/**
+ * Maintenance status enum values
+ */
+export const MaintenanceStatusEnum = z.enum([
+  "scheduled",
+  "in_progress",
+  "completed",
+  "cancelled",
+]);
+export type MaintenanceStatus = z.infer<typeof MaintenanceStatusEnum>;
+
+/**
+ * Core maintenance entity schema
+ */
+export const MaintenanceSchema = z.object({
+  id: z.string(),
+  title: z.string(),
+  description: z.string().optional(),
+  status: MaintenanceStatusEnum,
+  startAt: z.date(),
+  endAt: z.date(),
+  createdAt: z.date(),
+  updatedAt: z.date(),
+});
+export type Maintenance = z.infer<typeof MaintenanceSchema>;
+
+/**
+ * Maintenance with related systems
+ */
+export const MaintenanceWithSystemsSchema = MaintenanceSchema.extend({
+  systemIds: z.array(z.string()),
+});
+export type MaintenanceWithSystems = z.infer<
+  typeof MaintenanceWithSystemsSchema
+>;
+
+/**
+ * Maintenance update schema - status updates posted to a maintenance
+ */
+export const MaintenanceUpdateSchema = z.object({
+  id: z.string(),
+  maintenanceId: z.string(),
+  message: z.string(),
+  statusChange: MaintenanceStatusEnum.optional(),
+  createdAt: z.date(),
+  createdBy: z.string().optional(),
+});
+export type MaintenanceUpdate = z.infer<typeof MaintenanceUpdateSchema>;
+
+/**
+ * Full maintenance detail with systems and updates
+ */
+export const MaintenanceDetailSchema = MaintenanceWithSystemsSchema.extend({
+  updates: z.array(MaintenanceUpdateSchema),
+});
+export type MaintenanceDetail = z.infer<typeof MaintenanceDetailSchema>;
+
+// Input schemas for mutations
+export const CreateMaintenanceInputSchema = z
+  .object({
+    title: z.string().min(1, "Title is required"),
+    description: z.string().optional(),
+    startAt: z.date(),
+    endAt: z.date(),
+    systemIds: z.array(z.string()).min(1, "At least one system is required"),
+  })
+  .refine((data) => data.endAt > data.startAt, {
+    message: "End date must be after start date",
+    path: ["endAt"],
+  });
+export type CreateMaintenanceInput = z.infer<
+  typeof CreateMaintenanceInputSchema
+>;
+
+export const UpdateMaintenanceInputSchema = z.object({
+  id: z.string(),
+  title: z.string().min(1).optional(),
+  description: z.string().nullable().optional(),
+  startAt: z.date().optional(),
+  endAt: z.date().optional(),
+  systemIds: z.array(z.string()).min(1).optional(),
+});
+export type UpdateMaintenanceInput = z.infer<
+  typeof UpdateMaintenanceInputSchema
+>;
+
+export const AddMaintenanceUpdateInputSchema = z.object({
+  maintenanceId: z.string(),
+  message: z.string().min(1, "Message is required"),
+  statusChange: MaintenanceStatusEnum.optional(),
+});
+export type AddMaintenanceUpdateInput = z.infer<
+  typeof AddMaintenanceUpdateInputSchema
+>;

package/src/slots.ts

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

package/tsconfig.json

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