@checkstack/maintenance-backend 0.4.0 → 0.5.0

package/CHANGELOG.md

@@ -1,5 +1,37 @@
 # @checkstack/maintenance-backend
 
+## 0.5.0
+
+### Minor Changes
+
+- 2c0822d: ### Queue System
+
+  - Added cron pattern support to `scheduleRecurring()` - accepts either `intervalSeconds` or `cronPattern`
+  - BullMQ backend uses native cron scheduling via `pattern` option
+  - InMemoryQueue implements wall-clock cron scheduling with `cron-parser`
+
+  ### Maintenance Backend
+
+  - Auto status transitions now use cron pattern `* * * * *` for precise second-0 scheduling
+  - User notifications are now sent for auto-started and auto-completed maintenances
+  - Refactored to call `addUpdate` RPC for status changes, centralizing hook/signal/notification logic
+
+  ### UI
+
+  - DateTimePicker now resets seconds and milliseconds to 0 when time is changed
+
+### Patch Changes
+
+- 66a3963: Update database types to use SafeDatabase
+
+  - Updated all database type declarations from `NodePgDatabase` to `SafeDatabase` for compile-time safety
+
+- Updated dependencies [66a3963]
+- Updated dependencies [66a3963]
+  - @checkstack/integration-backend@0.1.6
+  - @checkstack/backend-api@0.5.0
+  - @checkstack/command-backend@0.1.6
+
 ## 0.4.0
 
 ### Minor Changes

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@checkstack/maintenance-backend",
-  "version": "0.4.0",
+  "version": "0.5.0",
   "type": "module",
   "main": "src/index.ts",
   "scripts": {

package/src/index.ts

@@ -1,5 +1,5 @@
 import * as schema from "./schema";
-import type { NodePgDatabase } from "drizzle-orm/node-postgres";
+import type { SafeDatabase } from "@checkstack/backend-api";
 import { z } from "zod";
 import {
   maintenanceAccessRules,
@@ -7,7 +7,7 @@ import {
   pluginMetadata,
   maintenanceContract,
   maintenanceRoutes,
-  MAINTENANCE_UPDATED,
+  MaintenanceApi,
 } from "@checkstack/maintenance-common";
 
 import { createBackendPlugin, coreServices } from "@checkstack/backend-api";
@@ -16,7 +16,7 @@ import { MaintenanceService } from "./service";
 import { createRouter } from "./router";
 import { CatalogApi } from "@checkstack/catalog-common";
 import { registerSearchProvider } from "@checkstack/command-backend";
-import { resolveRoute } from "@checkstack/common";
+import { resolveRoute, type InferClient } from "@checkstack/common";
 import { maintenanceHooks } from "./hooks";
 
 // =============================================================================
@@ -87,6 +87,9 @@ export default createBackendPlugin({
 
     // Store service reference for afterPluginsReady
     let maintenanceService: MaintenanceService;
+    // Store clients for afterPluginsReady
+    let catalogClient: InferClient<typeof CatalogApi>;
+    let maintenanceClient: InferClient<typeof MaintenanceApi>;
 
     env.registerInit({
       schema,
@@ -100,10 +103,11 @@ export default createBackendPlugin({
       init: async ({ logger, database, rpc, rpcClient, signalService }) => {
         logger.debug("🔧 Initializing Maintenance Backend...");
 
-        const catalogClient = rpcClient.forPlugin(CatalogApi);
+        catalogClient = rpcClient.forPlugin(CatalogApi);
+        maintenanceClient = rpcClient.forPlugin(MaintenanceApi);
 
         maintenanceService = new MaintenanceService(
-          database as NodePgDatabase<typeof schema>,
+          database as SafeDatabase<typeof schema>,
         );
         const router = createRouter(
           maintenanceService,
@@ -141,12 +145,7 @@ export default createBackendPlugin({
 
         logger.debug("✅ Maintenance Backend initialized.");
       },
-      afterPluginsReady: async ({
-        queueManager,
-        emitHook,
-        logger,
-        signalService,
-      }) => {
+      afterPluginsReady: async ({ queueManager, logger }) => {
         // Schedule the recurring status transition check job
         const queue = queueManager.getQueue<Record<string, never>>(
           STATUS_TRANSITION_QUEUE,
@@ -160,35 +159,21 @@ export default createBackendPlugin({
             // Get maintenances that need to start
             const toStart = await maintenanceService.getMaintenancesToStart();
             for (const maintenance of toStart) {
-              const updated = await maintenanceService.transitionStatus(
-                maintenance.id,
-                "in_progress",
-                "Maintenance started automatically",
-              );
-
-              if (updated) {
+              try {
+                // Call addUpdate via RPC - this handles hooks, signals, and notifications
+                await maintenanceClient.addUpdate({
+                  maintenanceId: maintenance.id,
+                  message: "Maintenance started automatically",
+                  statusChange: "in_progress",
+                });
                 logger.info(
-                  `Maintenance "${updated.title}" transitioned to in_progress`,
+                  `Maintenance "${maintenance.title}" transitioned to in_progress`,
+                );
+              } catch (error) {
+                logger.error(
+                  `Failed to transition maintenance ${maintenance.id}:`,
+                  error,
                 );
-
-                // Emit hook for integrations
-                await emitHook(maintenanceHooks.maintenanceUpdated, {
-                  maintenanceId: updated.id,
-                  systemIds: updated.systemIds,
-                  title: updated.title,
-                  description: updated.description,
-                  status: updated.status,
-                  startAt: updated.startAt.toISOString(),
-                  endAt: updated.endAt.toISOString(),
-                  action: "updated" as const,
-                });
-
-                // Send signal for real-time UI updates
-                await signalService.broadcast(MAINTENANCE_UPDATED, {
-                  maintenanceId: updated.id,
-                  systemIds: updated.systemIds,
-                  action: "updated",
-                });
               }
             }
 
@@ -196,35 +181,21 @@ export default createBackendPlugin({
             const toComplete =
               await maintenanceService.getMaintenancesToComplete();
             for (const maintenance of toComplete) {
-              const updated = await maintenanceService.transitionStatus(
-                maintenance.id,
-                "completed",
-                "Maintenance completed automatically",
-              );
-
-              if (updated) {
+              try {
+                // Call addUpdate via RPC - this handles hooks, signals, and notifications
+                await maintenanceClient.addUpdate({
+                  maintenanceId: maintenance.id,
+                  message: "Maintenance completed automatically",
+                  statusChange: "completed",
+                });
                 logger.info(
-                  `Maintenance "${updated.title}" transitioned to completed`,
+                  `Maintenance "${maintenance.title}" transitioned to completed`,
+                );
+              } catch (error) {
+                logger.error(
+                  `Failed to transition maintenance ${maintenance.id}:`,
+                  error,
                 );
-
-                // Emit hook for integrations
-                await emitHook(maintenanceHooks.maintenanceUpdated, {
-                  maintenanceId: updated.id,
-                  systemIds: updated.systemIds,
-                  title: updated.title,
-                  description: updated.description,
-                  status: updated.status,
-                  startAt: updated.startAt.toISOString(),
-                  endAt: updated.endAt.toISOString(),
-                  action: "closed" as const,
-                });
-
-                // Send signal for real-time UI updates
-                await signalService.broadcast(MAINTENANCE_UPDATED, {
-                  maintenanceId: updated.id,
-                  systemIds: updated.systemIds,
-                  action: "closed",
-                });
               }
             }
 
@@ -240,12 +211,12 @@ export default createBackendPlugin({
           },
         );
 
-        // Schedule to run every minute (60 seconds)
+        // Schedule to run every minute at second 0 (cron-based for precise timing)
         await queue.scheduleRecurring(
           {}, // Empty payload - the job just triggers a check
           {
             jobId: STATUS_TRANSITION_JOB_ID,
-            intervalSeconds: 60,
+            cronPattern: "* * * * *", // Every minute at :00 seconds
           },
         );
 

package/src/notifications.ts

@@ -0,0 +1,58 @@
+import { CatalogApi } from "@checkstack/catalog-common";
+import type { Logger } from "@checkstack/backend-api";
+import type { InferClient } from "@checkstack/common";
+import { resolveRoute } from "@checkstack/common";
+import { maintenanceRoutes } from "@checkstack/maintenance-common";
+
+/**
+ * Helper to notify subscribers of affected systems about a maintenance event.
+ * Each system triggers a separate notification call, but within each call
+ * the subscribers are deduplicated (system + its groups).
+ */
+export async function notifyAffectedSystems(props: {
+  catalogClient: InferClient<typeof CatalogApi>;
+  logger: Logger;
+  maintenanceId: string;
+  maintenanceTitle: string;
+  systemIds: string[];
+  action: "created" | "updated" | "started" | "completed";
+}): Promise<void> {
+  const {
+    catalogClient,
+    logger,
+    maintenanceId,
+    maintenanceTitle,
+    systemIds,
+    action,
+  } = props;
+
+  const actionText = {
+    created: "scheduled",
+    updated: "updated",
+    started: "started",
+    completed: "completed",
+  }[action];
+
+  const maintenanceDetailPath = resolveRoute(maintenanceRoutes.routes.detail, {
+    maintenanceId,
+  });
+
+  for (const systemId of systemIds) {
+    try {
+      await catalogClient.notifySystemSubscribers({
+        systemId,
+        title: `Maintenance ${actionText}`,
+        body: `A maintenance **"${maintenanceTitle}"** has been ${actionText} for a system you're subscribed to.`,
+        importance: "info",
+        action: { label: "View Maintenance", url: maintenanceDetailPath },
+        includeGroupSubscribers: true,
+      });
+    } catch (error) {
+      // Log but don't fail the operation - notifications are best-effort
+      logger.warn(
+        `Failed to notify subscribers for system ${systemId}:`,
+        error,
+      );
+    }
+  }
+}

package/src/router.ts

@@ -2,7 +2,6 @@ import { implement, ORPCError } from "@orpc/server";
 import {
   maintenanceContract,
   MAINTENANCE_UPDATED,
-  maintenanceRoutes,
 } from "@checkstack/maintenance-common";
 import {
   autoAuthMiddleware,
@@ -13,8 +12,8 @@ import type { SignalService } from "@checkstack/signal-common";
 import type { MaintenanceService } from "./service";
 import { CatalogApi } from "@checkstack/catalog-common";
 import type { InferClient } from "@checkstack/common";
-import { resolveRoute } from "@checkstack/common";
 import { maintenanceHooks } from "./hooks";
+import { notifyAffectedSystems } from "./notifications";
 
 export function createRouter(
   service: MaintenanceService,
@@ -26,47 +25,6 @@ export function createRouter(
     .$context<RpcContext>()
     .use(autoAuthMiddleware);
 
-  /**
-   * Helper to notify subscribers of affected systems about a maintenance event.
-   * Each system triggers a separate notification call, but within each call
-   * the subscribers are deduplicated (system + its groups).
-   */
-  const notifyAffectedSystems = async (props: {
-    maintenanceId: string;
-    maintenanceTitle: string;
-    systemIds: string[];
-    action: "created" | "updated";
-  }) => {
-    const { maintenanceId, maintenanceTitle, systemIds, action } = props;
-
-    const actionText = action === "created" ? "scheduled" : "updated";
-    const maintenanceDetailPath = resolveRoute(
-      maintenanceRoutes.routes.detail,
-      {
-        maintenanceId,
-      },
-    );
-
-    for (const systemId of systemIds) {
-      try {
-        await catalogClient.notifySystemSubscribers({
-          systemId,
-          title: `Maintenance ${actionText}`,
-          body: `A maintenance **"${maintenanceTitle}"** has been ${actionText} for a system you're subscribed to.`,
-          importance: "info",
-          action: { label: "View Maintenance", url: maintenanceDetailPath },
-          includeGroupSubscribers: true,
-        });
-      } catch (error) {
-        // Log but don't fail the operation - notifications are best-effort
-        logger.warn(
-          `Failed to notify subscribers for system ${systemId}:`,
-          error,
-        );
-      }
-    }
-  };
-
   return os.router({
     listMaintenances: os.listMaintenances.handler(async ({ input }) => {
       return { maintenances: await service.listMaintenances(input ?? {}) };
@@ -127,6 +85,8 @@ export function createRouter(
 
         // Send notifications to system subscribers
         await notifyAffectedSystems({
+          catalogClient,
+          logger,
           maintenanceId: result.id,
           maintenanceTitle: result.title,
           systemIds: result.systemIds,
@@ -165,14 +125,6 @@ export function createRouter(
           action: "updated",
         });
 
-        // Send notifications to system subscribers
-        await notifyAffectedSystems({
-          maintenanceId: result.id,
-          maintenanceTitle: result.title,
-          systemIds: result.systemIds,
-          action: "updated",
-        });
-
         return result;
       },
     ),
@@ -180,14 +132,25 @@ export function createRouter(
     addUpdate: os.addUpdate.handler(async ({ input, context }) => {
       const userId =
         context.user && "id" in context.user ? context.user.id : undefined;
+
+      // Get previous status before update for comparison
+      const previousMaintenance = input.statusChange
+        ? await service.getMaintenance(input.maintenanceId)
+        : undefined;
+      const previousStatus = previousMaintenance?.status;
+
       const result = await service.addUpdate(input, userId);
       // Get maintenance to broadcast with correct systemIds
       const maintenance = await service.getMaintenance(input.maintenanceId);
       if (maintenance) {
+        // Determine action based on status change
+        const action =
+          input.statusChange === "completed" ? "closed" : "updated";
+
         await signalService.broadcast(MAINTENANCE_UPDATED, {
           maintenanceId: input.maintenanceId,
           systemIds: maintenance.systemIds,
-          action: "updated",
+          action,
         });
 
         // Emit hook for cross-plugin coordination and integrations
@@ -199,8 +162,33 @@ export function createRouter(
           status: maintenance.status,
           startAt: maintenance.startAt.toISOString(),
           endAt: maintenance.endAt.toISOString(),
-          action: "updated",
+          action,
         });
+
+        // Send notifications when status actually changes
+        if (input.statusChange && previousStatus !== input.statusChange) {
+          // Determine notification action based on the actual status transition
+          let notificationAction: "started" | "completed" | "updated";
+          if (
+            input.statusChange === "in_progress" &&
+            previousStatus !== "in_progress"
+          ) {
+            notificationAction = "started";
+          } else if (input.statusChange === "completed") {
+            notificationAction = "completed";
+          } else {
+            notificationAction = "updated";
+          }
+
+          await notifyAffectedSystems({
+            catalogClient,
+            logger,
+            maintenanceId: input.maintenanceId,
+            maintenanceTitle: maintenance.title,
+            systemIds: maintenance.systemIds,
+            action: notificationAction,
+          });
+        }
       }
       return result;
     }),

package/src/service.ts

@@ -1,5 +1,5 @@
 import { eq, and, or, inArray } from "drizzle-orm";
-import type { NodePgDatabase } from "drizzle-orm/node-postgres";
+import type { SafeDatabase } from "@checkstack/backend-api";
 import * as schema from "./schema";
 import { maintenances, maintenanceSystems, maintenanceUpdates } from "./schema";
 import type {
@@ -12,7 +12,7 @@ import type {
   MaintenanceStatus,
 } from "@checkstack/maintenance-common";
 
-type Db = NodePgDatabase<typeof schema>;
+type Db = SafeDatabase<typeof schema>;
 
 function generateId(): string {
   return crypto.randomUUID();