@checkstack/slo-common 0.2.0

package/CHANGELOG.md

@@ -0,0 +1,30 @@
+# @checkstack/slo-common
+
+## 0.2.0
+
+### Minor Changes
+
+- 3c34b07: Complete SLO Reliability Engine frontend and backend
+
+  **Frontend** — 7 new visualization components:
+
+  - `StreakCounter`: Fire-themed compliance streak counter with color-coded flame and best-streak trophy
+  - `AchievementBadge`: Emoji-labeled badges for 9 achievement types with hover tooltip
+  - `AttributionChart`: Horizontal stacked bar showing error budget split (self/upstream/remaining)
+  - `DowntimeTimeline`: Dot-and-line timeline with attribution badges and timestamps
+  - `SloTrendChart`: Pure SVG availability trend line chart from daily snapshots
+  - `MilestoneFeed`: Organization-wide milestone feed on the SLO overview sidebar
+  - `DependencyExclusionConfig`: Interactive upstream dependency picker for SLO editor
+
+  **Backend** — Weekly digest scheduled integration event:
+
+  - `weekly-digest.ts`: Cron job (Monday 09:00 UTC) emitting SLO performance summary
+  - Top/worst performers, breach counts, and streak data delivered via configured notification channels
+  - New `sloWeeklyDigest` hook registered as integration event
+
+### Patch Changes
+
+- Updated dependencies [d1a2796]
+  - @checkstack/common@0.6.5
+  - @checkstack/frontend-api@0.3.9
+  - @checkstack/signal-common@0.1.9

package/package.json

@@ -0,0 +1,30 @@
+{
+  "name": "@checkstack/slo-common",
+  "version": "0.2.0",
+  "type": "module",
+  "exports": {
+    ".": {
+      "import": "./src/index.ts"
+    }
+  },
+  "dependencies": {
+    "@checkstack/common": "0.6.4",
+    "@checkstack/frontend-api": "0.3.8",
+    "@checkstack/signal-common": "0.1.8",
+    "@orpc/contract": "^1.13.14",
+    "zod": "^4.2.1"
+  },
+  "devDependencies": {
+    "typescript": "^5.7.2",
+    "@checkstack/tsconfig": "0.0.5",
+    "@checkstack/scripts": "0.1.2"
+  },
+  "scripts": {
+    "typecheck": "tsc --noEmit",
+    "lint": "bun run lint:code",
+    "lint:code": "eslint . --max-warnings 0"
+  },
+  "checkstack": {
+    "type": "common"
+  }
+}

package/src/access.ts

@@ -0,0 +1,27 @@
+import { accessPair } from "@checkstack/common";
+
+/**
+ * Access rules for the SLO plugin.
+ */
+export const sloAccess = {
+  /**
+   * SLO access with both read and manage levels.
+   * Read is public by default (anyone can view SLO status).
+   * Manage requires authentication (create, edit, delete SLOs).
+   */
+  slo: accessPair("slo", {
+    read: {
+      description: "View SLOs and error budgets",
+      isDefault: true,
+      isPublic: true,
+    },
+    manage: {
+      description: "Create, edit, and delete SLOs",
+    },
+  }),
+};
+
+/**
+ * All access rules for registration with the plugin system.
+ */
+export const sloAccessRules = [sloAccess.slo.read, sloAccess.slo.manage];

package/src/index.ts

@@ -0,0 +1,79 @@
+export { sloAccess, sloAccessRules } from "./access";
+export { sloContract, SloApi, type SloContract } from "./rpc-contract";
+export {
+  DependencyExclusionModeSchema,
+  AttributionTypeSchema,
+  AchievementTypeSchema,
+  BurnRateThresholdsSchema,
+  SloObjectiveSchema,
+  SloDowntimeEventSchema,
+  SloDailySnapshotSchema,
+  SloStreakSchema,
+  SloAchievementSchema,
+  SloAttributionEntrySchema,
+  SloStatusSchema,
+  CreateSloObjectiveInputSchema,
+  UpdateSloObjectiveInputSchema,
+  type DependencyExclusionMode,
+  type AttributionType,
+  type AchievementType,
+  type BurnRateThresholds,
+  type SloObjective,
+  type SloDowntimeEvent,
+  type SloDailySnapshot,
+  type SloStreak,
+  type SloAchievement,
+  type SloAttributionEntry,
+  type SloStatus,
+  type CreateSloObjectiveInput,
+  type UpdateSloObjectiveInput,
+} from "./schemas";
+export * from "./plugin-metadata";
+export { sloRoutes } from "./routes";
+
+// =============================================================================
+// REALTIME SIGNALS
+// =============================================================================
+
+import { createSignal } from "@checkstack/signal-common";
+import { z } from "zod";
+
+/**
+ * Broadcast when an SLO's status changes (budget consumed, breach started/ended).
+ * Frontend components can refetch SLO data for the affected system.
+ */
+export const SLO_STATUS_CHANGED = createSignal(
+  "slo.status.changed",
+  z.object({
+    systemId: z.string(),
+    objectiveId: z.string(),
+    budgetRemainingPercent: z.number(),
+    isBreaching: z.boolean(),
+  }),
+);
+
+/**
+ * Broadcast when a streak is updated (incremented or broken).
+ * Used to update streak counter UI in real-time.
+ */
+export const SLO_STREAK_UPDATED = createSignal(
+  "slo.streak.updated",
+  z.object({
+    systemId: z.string(),
+    objectiveId: z.string(),
+    currentStreak: z.number(),
+    broken: z.boolean(),
+  }),
+);
+
+/**
+ * Broadcast when a system unlocks a new achievement.
+ * Used to trigger celebration UI and milestone feed updates.
+ */
+export const SLO_ACHIEVEMENT_UNLOCKED = createSignal(
+  "slo.achievement.unlocked",
+  z.object({
+    systemId: z.string(),
+    achievement: z.string(),
+  }),
+);

package/src/plugin-metadata.ts

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

package/src/routes.ts

@@ -0,0 +1,30 @@
+import { createRoutes } from "@checkstack/common";
+
+/**
+ * Route definitions for the SLO plugin.
+ *
+ * @example Frontend plugin usage
+ * ```tsx
+ * import { sloRoutes } from "@checkstack/slo-common";
+ *
+ * createFrontendPlugin({
+ *   routes: [
+ *     { route: sloRoutes.routes.overview, element: <SloOverviewPage /> },
+ *   ],
+ * });
+ * ```
+ *
+ * @example Link generation
+ * ```tsx
+ * import { sloRoutes } from "@checkstack/slo-common";
+ * import { resolveRoute } from "@checkstack/common";
+ *
+ * const detailPath = resolveRoute(sloRoutes.routes.detail, { sloId });
+ * ```
+ */
+export const sloRoutes = createRoutes("slo", {
+  overview: "/",
+  config: "/config",
+  configDetail: "/config/:sloId",
+  detail: "/:sloId",
+});

package/src/rpc-contract.ts

@@ -0,0 +1,194 @@
+import { z } from "zod";
+import { createClientDefinition, proc } from "@checkstack/common";
+import { sloAccess } from "./access";
+import { pluginMetadata } from "./plugin-metadata";
+import {
+  SloObjectiveSchema,
+  SloStatusSchema,
+  SloDowntimeEventSchema,
+  SloDailySnapshotSchema,
+  SloStreakSchema,
+  SloAchievementSchema,
+  CreateSloObjectiveInputSchema,
+  UpdateSloObjectiveInputSchema,
+} from "./schemas";
+
+export const sloContract = {
+  // ==========================================================================
+  // SLO OBJECTIVE MANAGEMENT
+  // ==========================================================================
+
+  /** List all SLO objectives with their computed status */
+  listObjectives: proc({
+    operationType: "query",
+    userType: "public",
+    access: [sloAccess.slo.read],
+  }).output(
+    z.object({
+      objectives: z.array(
+        z.object({
+          objective: SloObjectiveSchema,
+          status: SloStatusSchema,
+        }),
+      ),
+    }),
+  ),
+
+  /** Get a single SLO objective with full status and attribution */
+  getObjective: proc({
+    operationType: "query",
+    userType: "public",
+    access: [sloAccess.slo.read],
+  })
+    .input(z.object({ id: z.string() }))
+    .output(
+      z
+        .object({
+          objective: SloObjectiveSchema,
+          status: SloStatusSchema,
+        })
+        .nullable(),
+    ),
+
+  /** Get SLOs for a specific system (for badge display) */
+  getObjectivesForSystem: proc({
+    operationType: "query",
+    userType: "public",
+    access: [sloAccess.slo.read],
+  })
+    .input(z.object({ systemId: z.string() }))
+    .output(
+      z.array(
+        z.object({
+          objective: SloObjectiveSchema,
+          status: SloStatusSchema,
+        }),
+      ),
+    ),
+
+  /** Bulk fetch SLO statuses for multiple systems (dashboard, avoid N+1) */
+  getBulkObjectivesForSystems: proc({
+    operationType: "query",
+    userType: "public",
+    access: [sloAccess.slo.read],
+    instanceAccess: { recordKey: "systems" },
+  })
+    .input(z.object({ systemIds: z.array(z.string()) }))
+    .output(
+      z.object({
+        systems: z.record(
+          z.string(),
+          z.array(
+            z.object({
+              objective: SloObjectiveSchema,
+              status: SloStatusSchema,
+            }),
+          ),
+        ),
+      }),
+    ),
+
+  /** Create a new SLO objective */
+  createObjective: proc({
+    operationType: "mutation",
+    userType: "authenticated",
+    access: [sloAccess.slo.manage],
+  })
+    .input(CreateSloObjectiveInputSchema)
+    .output(SloObjectiveSchema),
+
+  /** Update an existing SLO objective */
+  updateObjective: proc({
+    operationType: "mutation",
+    userType: "authenticated",
+    access: [sloAccess.slo.manage],
+  })
+    .input(UpdateSloObjectiveInputSchema)
+    .output(SloObjectiveSchema),
+
+  /** Delete an SLO objective and all associated data */
+  deleteObjective: proc({
+    operationType: "mutation",
+    userType: "authenticated",
+    access: [sloAccess.slo.manage],
+  })
+    .input(z.object({ id: z.string() }))
+    .output(z.object({ success: z.boolean() })),
+
+  // ==========================================================================
+  // DOWNTIME EVENTS & DAILY SNAPSHOTS
+  // ==========================================================================
+
+  /** Get recent downtime events for an SLO objective */
+  getDowntimeEvents: proc({
+    operationType: "query",
+    userType: "public",
+    access: [sloAccess.slo.read],
+  })
+    .input(
+      z.object({
+        objectiveId: z.string(),
+        limit: z.number().optional().default(50),
+      }),
+    )
+    .output(z.object({ events: z.array(SloDowntimeEventSchema) })),
+
+  /** Get daily SLO trend data for a time range */
+  getDailySnapshots: proc({
+    operationType: "query",
+    userType: "public",
+    access: [sloAccess.slo.read],
+  })
+    .input(
+      z.object({
+        objectiveId: z.string(),
+        startDate: z.date(),
+        endDate: z.date(),
+      }),
+    )
+    .output(z.object({ snapshots: z.array(SloDailySnapshotSchema) })),
+
+  // ==========================================================================
+  // STREAKS & ACHIEVEMENTS
+  // ==========================================================================
+
+  /** Get streaks for all SLO objectives */
+  getStreaks: proc({
+    operationType: "query",
+    userType: "public",
+    access: [sloAccess.slo.read],
+  }).output(z.object({ streaks: z.array(SloStreakSchema) })),
+
+  /** Get achievements for a specific system */
+  getAchievements: proc({
+    operationType: "query",
+    userType: "public",
+    access: [sloAccess.slo.read],
+  })
+    .input(z.object({ systemId: z.string() }))
+    .output(z.object({ achievements: z.array(SloAchievementSchema) })),
+
+  /** Get recent milestones across all systems (for milestone feed) */
+  getRecentMilestones: proc({
+    operationType: "query",
+    userType: "public",
+    access: [sloAccess.slo.read],
+  })
+    .input(z.object({ limit: z.number().optional().default(20) }))
+    .output(
+      z.object({
+        milestones: z.array(
+          z.object({
+            systemId: z.string(),
+            systemName: z.string().optional(),
+            achievement: z.string(),
+            unlockedAt: z.date(),
+          }),
+        ),
+      }),
+    ),
+};
+
+export type SloContract = typeof sloContract;
+
+export const SloApi = createClientDefinition(sloContract, pluginMetadata);

package/src/schemas.ts

@@ -0,0 +1,225 @@
+import { z } from "zod";
+
+// =============================================================================
+// ENUMS
+// =============================================================================
+
+/**
+ * Dependency exclusion mode for SLO error budget calculation.
+ * - strict: Count ALL downtime regardless of cause
+ * - self-only: Only count self-caused downtime (upstream-attributed downtime is excluded)
+ */
+export const DependencyExclusionModeSchema = z.enum([
+  "strict",
+  "self-only",
+]);
+export type DependencyExclusionMode = z.infer<
+  typeof DependencyExclusionModeSchema
+>;
+
+/**
+ * Attribution type for a downtime event.
+ * - self: Downtime is caused by the system itself
+ * - upstream: Downtime is attributed to an upstream dependency failure
+ */
+export const AttributionTypeSchema = z.enum(["self", "upstream"]);
+export type AttributionType = z.infer<typeof AttributionTypeSchema>;
+
+/**
+ * Achievement types that can be unlocked by systems.
+ */
+export const AchievementTypeSchema = z.enum([
+  "first_steps",
+  "iron_uptime",
+  "diamond_uptime",
+  "budget_miser",
+  "clean_sheet",
+  "nines_club",
+  "cascade_breaker",
+  "full_coverage",
+  "rapid_recovery",
+]);
+export type AchievementType = z.infer<typeof AchievementTypeSchema>;
+
+// =============================================================================
+// CONFIGURABLE THRESHOLDS
+// =============================================================================
+
+/**
+ * Burn rate alert thresholds, configurable per SLO objective.
+ */
+export const BurnRateThresholdsSchema = z.object({
+  warningPercent: z.number().min(0).max(100).default(50),
+  criticalPercent: z.number().min(0).max(100).default(80),
+  fastBurnMultiplier: z.number().min(1).default(5),
+});
+export type BurnRateThresholds = z.infer<typeof BurnRateThresholdsSchema>;
+
+// =============================================================================
+// CORE ENTITIES
+// =============================================================================
+
+/**
+ * SLO objective definition.
+ * Represents a reliability target for a system (or a specific health check on a system).
+ * Multiple SLOs can be defined per system. When healthCheckConfigurationId is null,
+ * the SLO applies to the system's aggregate availability across all health checks.
+ */
+export const SloObjectiveSchema = z.object({
+  id: z.string(),
+  systemId: z.string(),
+  healthCheckConfigurationId: z.string().nullable(),
+  target: z.number().min(0).max(100),
+  windowDays: z.number().int().positive(),
+  dependencyExclusion: DependencyExclusionModeSchema,
+  excludedDependencyIds: z.array(z.string()).optional(),
+  burnRateThresholds: BurnRateThresholdsSchema,
+  createdAt: z.date(),
+  updatedAt: z.date(),
+});
+export type SloObjective = z.infer<typeof SloObjectiveSchema>;
+
+/**
+ * Event-sourced downtime record, written in real-time on SYSTEM_STATUS_CHANGED.
+ * Events are immutable after creation — when attribution changes mid-outage,
+ * the open event is closed and a new one starts (event splitting).
+ */
+export const SloDowntimeEventSchema = z.object({
+  id: z.string(),
+  objectiveId: z.string(),
+  systemId: z.string(),
+  startTime: z.date(),
+  endTime: z.date().nullable(),
+  durationSeconds: z.number().nullable(),
+  attributionType: AttributionTypeSchema,
+  upstreamSystemId: z.string().nullable(),
+  upstreamSystemName: z.string().nullable(),
+});
+export type SloDowntimeEvent = z.infer<typeof SloDowntimeEventSchema>;
+
+/**
+ * Daily SLO snapshot for trend charts.
+ * Persisted by a daily cron job at UTC midnight.
+ */
+export const SloDailySnapshotSchema = z.object({
+  id: z.string(),
+  objectiveId: z.string(),
+  date: z.date(),
+  availabilityPercent: z.number(),
+  budgetConsumedMinutes: z.number(),
+  budgetRemainingPercent: z.number(),
+  burnRate: z.number().nullable(),
+  streakDays: z.number(),
+});
+export type SloDailySnapshot = z.infer<typeof SloDailySnapshotSchema>;
+
+/**
+ * Streak tracking for an SLO objective.
+ * One streak record per objective (1:1).
+ */
+export const SloStreakSchema = z.object({
+  objectiveId: z.string(),
+  systemId: z.string(),
+  currentStreak: z.number(),
+  bestStreak: z.number(),
+  streakStart: z.date().nullable(),
+  bestStreakEnd: z.date().nullable(),
+});
+export type SloStreak = z.infer<typeof SloStreakSchema>;
+
+/**
+ * Achievement unlocked by a system.
+ * System-centric only — no user attribution.
+ */
+export const SloAchievementSchema = z.object({
+  id: z.string(),
+  systemId: z.string(),
+  achievement: AchievementTypeSchema,
+  unlockedAt: z.date(),
+});
+export type SloAchievement = z.infer<typeof SloAchievementSchema>;
+
+// =============================================================================
+// COMPUTED STATUS (returned by API, not persisted)
+// =============================================================================
+
+/**
+ * Attribution breakdown entry for a single source (self or an upstream dependency).
+ */
+export const SloAttributionEntrySchema = z.object({
+  sourceType: AttributionTypeSchema,
+  systemId: z.string().optional(),
+  systemName: z.string().optional(),
+  minutes: z.number(),
+});
+export type SloAttributionEntry = z.infer<typeof SloAttributionEntrySchema>;
+
+/**
+ * Computed SLO status for display, aggregated from downtime events.
+ * Returned by the API, not persisted directly.
+ */
+export const SloStatusSchema = z.object({
+  objectiveId: z.string(),
+  systemId: z.string(),
+  target: z.number(),
+  windowDays: z.number(),
+  healthCheckConfigurationId: z.string().nullable(),
+  healthCheckConfigurationName: z.string().nullable(),
+  currentAvailability: z.number().nullable(),
+  strictAvailability: z.number().nullable(),
+  errorBudgetTotalMinutes: z.number(),
+  errorBudgetConsumedMinutes: z.number(),
+  errorBudgetConsumedStrictMinutes: z.number(),
+  errorBudgetRemainingMinutes: z.number(),
+  errorBudgetRemainingPercent: z.number(),
+  burnRate: z.number().nullable(),
+  dependencyExclusion: DependencyExclusionModeSchema,
+  isBreaching: z.boolean(),
+  hasOpenDowntime: z.boolean(),
+  attribution: z.array(SloAttributionEntrySchema),
+});
+export type SloStatus = z.infer<typeof SloStatusSchema>;
+
+// =============================================================================
+// INPUT SCHEMAS
+// =============================================================================
+
+/**
+ * Input for creating a new SLO objective.
+ */
+export const CreateSloObjectiveInputSchema = z.object({
+  systemId: z.string().min(1, "System is required"),
+  healthCheckConfigurationId: z.string().optional(),
+  target: z
+    .number()
+    .min(0, "Target must be >= 0")
+    .max(100, "Target must be <= 100"),
+  windowDays: z.number().int().positive("Window must be at least 1 day"),
+  dependencyExclusion: DependencyExclusionModeSchema.optional().default(
+    "strict",
+  ),
+  excludedDependencyIds: z.array(z.string()).optional().default([]),
+  burnRateThresholds: BurnRateThresholdsSchema.optional().default({
+    warningPercent: 50,
+    criticalPercent: 80,
+    fastBurnMultiplier: 5,
+  }),
+});
+export type CreateSloObjectiveInput = z.infer<
+  typeof CreateSloObjectiveInputSchema
+>;
+
+/**
+ * Input for updating an existing SLO objective.
+ */
+export const UpdateSloObjectiveInputSchema = z.object({
+  id: z.string(),
+  target: z.number().min(0).max(100).optional(),
+  windowDays: z.number().int().positive().optional(),
+  dependencyExclusion: DependencyExclusionModeSchema.optional(),
+  excludedDependencyIds: z.array(z.string()).optional(),
+  burnRateThresholds: BurnRateThresholdsSchema.optional(),
+});
+export type UpdateSloObjectiveInput = z.infer<
+  typeof UpdateSloObjectiveInputSchema
+>;

package/tsconfig.json

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