@checkstack/status-page-common 0.1.0

package/CHANGELOG.md

@@ -0,0 +1,79 @@
+# @checkstack/status-page-common
+
+## 0.1.0
+
+### Minor Changes
+
+- 9ab73c5: Status pages: configurable incident/maintenance updates + recently resolved/completed items.
+
+  The Incidents and Maintenance widgets gain four config options (in the builder):
+
+  - **Show updates** (default on) — render the per-item update timeline so visitors
+    can follow progress. The maintenance widget now renders its timeline too
+    (previously it fetched updates but didn't show them). Turning this off also
+    skips the per-item detail fetch (a perf win).
+  - **Max updates per item** (default 3) — show only the latest N updates,
+    most-recent first, so a chatty incident doesn't dominate the page.
+  - **Show recently resolved / completed** (default off) — include resolved
+    incidents / completed maintenances, rendered in a separate "Recently resolved"
+    / "Past maintenance" subsection below the active items.
+  - **Max age (days)** (default 7) — only include past items resolved/completed
+    within the window.
+
+  Scoping and isolation are unchanged: still only the systems the operator bound,
+  still fail-closed when none are bound, still field-allow-listed DTOs (no
+  `createdBy`). The active/past partition + max-age + cap is a pure, unit-tested
+  helper (`selectEvents`).
+
+- 5c6393f: Add operator-built public Status Pages (phase 1: secure, extensible core).
+
+  Operators compose a public status page from widgets (status banner, system
+  health, group status, 90-day uptime, incidents, scheduled maintenance) plus
+  content blocks (text/Markdown, heading, links, image, divider), each bound to the
+  resources they choose, then publish it.
+
+  Security model — "only published widgets reveal data":
+
+  - A single public endpoint, `getPublishedStatusPage(slug)`, returns the layout
+    plus each widget's already-resolved, field-ALLOW-LISTED DTO. The public surface
+    has no generic data API, so it can only ever show what was placed on the page.
+  - Three gates: edit-time (you can only bind resources you can access), publish-time
+    (an audited, deliberate exposure that re-checks the editor can read every bound
+    resource via a user-scoped client), and render-time (resolvers run as a trusted
+    service but emit only DTO fields — never internal config, ids, or `createdBy`;
+    the service re-validates each DTO against its schema, so a resolver bug fails
+    closed).
+  - The overall banner rolls up only the bound systems; private resources are never
+    exposed beyond their public-safe status; per-binding label overrides avoid
+    internal-name leaks.
+
+  Coherence + extensibility:
+
+  - Status pages are team-scopable resources (RLAC): created via the standard
+    owning-team picker + create-capability flow, resolvable by name in the Teams
+    admin.
+  - Widget types come from an extension-point registry, so any plugin can contribute
+    a widget (config schema + public DTO + `resolvePublic`); the public renderers
+    are pure, prop-only components with no data access, so third-party widgets can
+    never leak.
+  - Draft vs published layouts; per-page visibility (public / authenticated-only)
+    and theming (brand color, logo).
+
+  Dependency direction: the status-page platform owns the widget-type registry and
+  the content widgets, but the DOMAIN widgets are contributed by their owning
+  plugins via the `statusWidgetTypeExtensionPoint` — system health / uptime /
+  banner / group status by `healthcheck-backend`, incidents by `incident-backend`,
+  scheduled maintenance by `maintenance-backend`. So `status-page-backend` depends
+  only on `backend-api` / `common` / `status-page-common`; the owning plugins
+  depend on the platform, never the reverse. `catalog-common` gains
+  `assertCatalogResourcesReadable` for the publish-time access check.
+
+  Phase 1 scope: the secure core, the admin builder, and the public page (served as
+  a no-access-rule route). A fully separate public bundle, custom domains + TLS,
+  drag-reorder, live-data preview, and distribution (embeds/badges/RSS/subscriptions)
+  are the next phases.
+
+### Patch Changes
+
+- Updated dependencies [d2077bd]
+  - @checkstack/common@0.16.0

package/package.json

@@ -0,0 +1,29 @@
+{
+  "name": "@checkstack/status-page-common",
+  "version": "0.1.0",
+  "license": "Elastic-2.0",
+  "type": "module",
+  "exports": {
+    ".": {
+      "import": "./src/index.ts"
+    }
+  },
+  "dependencies": {
+    "@checkstack/common": "0.16.0",
+    "@orpc/contract": "^1.14.4",
+    "zod": "^4.2.1"
+  },
+  "devDependencies": {
+    "typescript": "^5.7.2",
+    "@checkstack/tsconfig": "0.0.7",
+    "@checkstack/scripts": "0.6.2"
+  },
+  "scripts": {
+    "typecheck": "tsgo -b",
+    "lint": "bun run lint:code",
+    "lint:code": "eslint . --max-warnings 0"
+  },
+  "checkstack": {
+    "type": "common"
+  }
+}

package/src/access.ts

@@ -0,0 +1,48 @@
+import { access, accessPair } from "@checkstack/common";
+import { pluginMetadata } from "./plugin-metadata";
+
+/**
+ * Access rules for the Status Pages plugin.
+ *
+ * Two distinct surfaces with DIFFERENT trust models:
+ *
+ * - `page.read` / `page.manage` gate the AUTHENTICATED admin builder. Pages are
+ *   team-scopable (RLAC): read is team-filtered, manage (create/edit/publish) is
+ *   admin or a team with a create-capability grant. NOT public.
+ * - `published.read` gates the PUBLIC, anonymous read of a *published* page. It
+ *   is default-granted to the anonymous role so visitors can see published
+ *   pages; an admin can revoke it from anonymous to switch OFF public status
+ *   pages platform-wide without touching the builder. Per-page visibility
+ *   (public vs authenticated-only) is enforced in the handler, on top of this.
+ */
+export const statusPageAccess = {
+  page: accessPair(
+    "page",
+    {
+      read: {
+        description: "View status page configurations",
+        isDefault: true,
+      },
+      manage: {
+        description: "Create, edit, publish, and delete status pages",
+      },
+    },
+    { pluginId: pluginMetadata.pluginId },
+  ),
+  published: access(
+    "published",
+    "read",
+    "View published status pages (public)",
+    {
+      pluginId: pluginMetadata.pluginId,
+      isDefault: true,
+      isPublic: true,
+    },
+  ),
+};
+
+export const statusPageAccessRules = [
+  statusPageAccess.page.read,
+  statusPageAccess.page.manage,
+  statusPageAccess.published,
+];

package/src/index.ts

@@ -0,0 +1,8 @@
+export * from "./plugin-metadata";
+export { statusPageAccess, statusPageAccessRules } from "./access";
+export { statusPageContract, StatusPageApi } from "./rpc-contract";
+export { statusPageRoutes, statusPublicRoutes } from "./routes";
+export * from "./schemas";
+export * from "./widget-types";
+export * from "./public-mappers";
+export * from "./select-events";

package/src/plugin-metadata.ts

@@ -0,0 +1,5 @@
+import { definePluginMetadata } from "@checkstack/common";
+
+export const pluginMetadata = definePluginMetadata({
+  pluginId: "statuspage",
+});

package/src/public-mappers.ts

@@ -0,0 +1,38 @@
+/**
+ * Generic, domain-free mappers shared by the owning plugins' status-page
+ * widgets. The createdBy-strip is the security-critical part: incident /
+ * maintenance update timelines carry `createdBy` / `createdByName` (who on the
+ * operating team posted the update) — internal identity that MUST NOT reach the
+ * public page. Kept here (no domain deps) so every owning plugin strips it the
+ * same, tested, way.
+ */
+
+export interface InternalUpdate {
+  message: string;
+  statusChange?: string;
+  createdAt: string | Date;
+  /** Internal — dropped. */
+  createdBy?: string;
+  createdByName?: string;
+  [k: string]: unknown;
+}
+
+export interface PublicUpdate {
+  message: string;
+  statusChange?: string;
+  at: string;
+}
+
+/** Strip an update to its public-safe fields (no author identity). */
+export function toPublicUpdate(update: InternalUpdate): PublicUpdate {
+  return {
+    message: update.message,
+    ...(update.statusChange === undefined
+      ? {}
+      : { statusChange: update.statusChange }),
+    at:
+      update.createdAt instanceof Date
+        ? update.createdAt.toISOString()
+        : update.createdAt,
+  };
+}

package/src/routes.ts

@@ -0,0 +1,18 @@
+import { createRoutes } from "@checkstack/common";
+
+/** Admin builder routes (authenticated). */
+export const statusPageRoutes = createRoutes("status-pages", {
+  list: "",
+  builder: "/:id",
+});
+
+/**
+ * Public page route (anonymous). Lives under a distinct `/status` prefix and
+ * carries NO access rule, so it renders for unauthenticated visitors and only
+ * ever calls the single public `getPublishedStatusPage` endpoint. (A fully
+ * separate public bundle / custom-domain host routing is the next phase; the
+ * data-isolation guarantee is enforced server-side regardless of bundle.)
+ */
+export const statusPublicRoutes = createRoutes("status", {
+  page: "/:slug",
+});

package/src/rpc-contract.ts

@@ -0,0 +1,140 @@
+import { createClientDefinition, proc } from "@checkstack/common";
+import { z } from "zod";
+import { pluginMetadata } from "./plugin-metadata";
+import { statusPageAccess } from "./access";
+import {
+  StatusPageSchema,
+  StatusPageSummarySchema,
+  StatusPageVisibilitySchema,
+  StatusPageThemeSchema,
+  StatusPageLayoutSchema,
+  StatusPageSlugSchema,
+  PublishedStatusPageSchema,
+} from "./schemas";
+import { WidgetTypeDescriptorSchema } from "./widget-types";
+
+const TitleSchema = z.string().trim().min(1).max(160);
+
+export const statusPageContract = {
+  // ----- Admin builder (authenticated, team-scoped) -----
+
+  listStatusPages: proc({
+    operationType: "query",
+    userType: "authenticated",
+    access: [statusPageAccess.page.read],
+    instanceAccess: { listKey: "pages" },
+  })
+    .input(z.object({}).optional())
+    .output(z.object({ pages: z.array(StatusPageSummarySchema) })),
+
+  getStatusPage: proc({
+    operationType: "query",
+    userType: "authenticated",
+    access: [statusPageAccess.page.read],
+    instanceAccess: { idParam: "id" },
+  })
+    .input(z.object({ id: z.string() }))
+    .output(StatusPageSchema.nullable()),
+
+  createStatusPage: proc({
+    operationType: "mutation",
+    userType: "authenticated",
+    access: [statusPageAccess.page.manage],
+    // Create-mode team ownership: middleware resolves the owning team from
+    // `teamId` (create-capability grant or global manage) and writes the owner
+    // relation keyed by `statuspage.page` / `response.id` post-handler.
+    instanceAccess: { create: { teamIdParam: "teamId", idField: "id" } },
+  })
+    .input(
+      z.object({
+        title: TitleSchema,
+        slug: StatusPageSlugSchema,
+        teamId: z.string().optional(),
+      }),
+    )
+    .output(StatusPageSchema),
+
+  updateStatusPage: proc({
+    operationType: "mutation",
+    userType: "authenticated",
+    access: [statusPageAccess.page.manage],
+    instanceAccess: { idParam: "id" },
+  })
+    .input(
+      z.object({
+        id: z.string(),
+        title: TitleSchema.optional(),
+        slug: StatusPageSlugSchema.optional(),
+        visibility: StatusPageVisibilitySchema.optional(),
+        theme: StatusPageThemeSchema.optional(),
+        draftLayout: StatusPageLayoutSchema.optional(),
+      }),
+    )
+    .output(StatusPageSchema),
+
+  /**
+   * Snapshot the draft layout into the published layout. The middleware checks
+   * `manage` on the page; the handler additionally verifies the editor can
+   * access every resource a widget binds (you cannot publish what you cannot
+   * see) and emits an audit event (the deliberate public-exposure record).
+   */
+  publishStatusPage: proc({
+    operationType: "mutation",
+    userType: "authenticated",
+    access: [statusPageAccess.page.manage],
+    instanceAccess: { idParam: "id" },
+  })
+    .input(z.object({ id: z.string() }))
+    .output(StatusPageSchema),
+
+  unpublishStatusPage: proc({
+    operationType: "mutation",
+    userType: "authenticated",
+    access: [statusPageAccess.page.manage],
+    instanceAccess: { idParam: "id" },
+  })
+    .input(z.object({ id: z.string() }))
+    .output(StatusPageSchema),
+
+  deleteStatusPage: proc({
+    operationType: "mutation",
+    userType: "authenticated",
+    access: [statusPageAccess.page.manage],
+    instanceAccess: { idParam: "id" },
+  })
+    .input(z.object({ id: z.string() }))
+    .output(z.object({ deleted: z.boolean() })),
+
+  /** Widget catalogue for the builder (built-ins + plugin-contributed types). */
+  listWidgetTypes: proc({
+    operationType: "query",
+    userType: "authenticated",
+    access: [statusPageAccess.page.read],
+    instanceAccess: { global: true },
+  })
+    .input(z.object({}).optional())
+    .output(z.object({ widgetTypes: z.array(WidgetTypeDescriptorSchema) })),
+
+  // ----- Public surface (the ONLY public data endpoint) -----
+
+  /**
+   * Resolve a PUBLISHED page for the public renderer. `userType: "public"` gated
+   * by the anonymous `published.read` grant; NOT team-scoped (team ownership
+   * governs editing, not viewing). The handler enforces published + per-page
+   * visibility, and returns ONLY the resolved, field-allow-listed widget DTOs —
+   * never a generic data API. Returns null when no published page matches.
+   */
+  getPublishedStatusPage: proc({
+    operationType: "query",
+    userType: "public",
+    access: [statusPageAccess.published],
+    instanceAccess: { global: true },
+  })
+    .input(z.object({ slug: z.string() }))
+    .output(PublishedStatusPageSchema.nullable()),
+} as const;
+
+export const StatusPageApi = createClientDefinition(
+  statusPageContract,
+  pluginMetadata,
+);

package/src/schemas.ts

@@ -0,0 +1,117 @@
+import { z } from "zod";
+import { HttpUrlSchema } from "./widget-types";
+
+/**
+ * Page visibility. `public` = anyone (gated by the anonymous `published.read`
+ * grant). `authenticated` = any logged-in user (an internal status page). Higher
+ * tiers (password / IP / SSO) are a later phase.
+ */
+export const StatusPageVisibilitySchema = z.enum(["public", "authenticated"]);
+export type StatusPageVisibility = z.infer<typeof StatusPageVisibilitySchema>;
+
+/** Per-page branding. Colors are HSL triples ("262 83% 58%") to match the design tokens. */
+export const StatusPageThemeSchema = z.object({
+  brandColorHsl: z
+    .string()
+    .regex(/^\d{1,3} \d{1,3}% \d{1,3}%$/)
+    .optional(),
+  logoUrl: HttpUrlSchema.optional(),
+  mode: z.enum(["light", "dark", "auto"]).default("auto"),
+});
+export type StatusPageTheme = z.infer<typeof StatusPageThemeSchema>;
+
+/**
+ * One block in a page layout. `config` is validated PER-TYPE by the backend
+ * widget registry (the contract keeps it opaque so new widget types need no
+ * contract change). `label` is an optional public heading for the block.
+ */
+export const StatusPageBlockSchema = z.object({
+  id: z.string().min(1),
+  type: z.string().min(1),
+  label: z.string().trim().max(160).optional(),
+  config: z.unknown(),
+});
+export type StatusPageBlock = z.infer<typeof StatusPageBlockSchema>;
+
+export const StatusPageLayoutSchema = z
+  .array(StatusPageBlockSchema)
+  .max(100)
+  .superRefine((blocks, ctx) => {
+    // Block ids are client-generated; reject duplicates so a layout can't carry
+    // two blocks with the same id (which would break React keys + per-block ops).
+    const seen = new Set<string>();
+    for (const block of blocks) {
+      if (seen.has(block.id)) {
+        ctx.addIssue({
+          code: z.ZodIssueCode.custom,
+          message: `Duplicate block id: ${block.id}`,
+        });
+      }
+      seen.add(block.id);
+    }
+  });
+export type StatusPageLayout = z.infer<typeof StatusPageLayoutSchema>;
+
+/** Slug: lowercase, url-safe; the public page lives at /status/<slug>. */
+export const StatusPageSlugSchema = z
+  .string()
+  .trim()
+  .min(1)
+  .max(63)
+  .regex(/^[a-z0-9]+(?:-[a-z0-9]+)*$/, "Use lowercase letters, numbers and dashes");
+
+/** Full admin-facing status page (the builder's working copy). */
+export const StatusPageSchema = z.object({
+  id: z.string(),
+  slug: z.string(),
+  title: z.string(),
+  visibility: StatusPageVisibilitySchema,
+  theme: StatusPageThemeSchema,
+  draftLayout: StatusPageLayoutSchema,
+  publishedLayout: StatusPageLayoutSchema.nullable(),
+  published: z.boolean(),
+  publishedAt: z.string().nullable(),
+  createdAt: z.string(),
+  updatedAt: z.string(),
+});
+export type StatusPage = z.infer<typeof StatusPageSchema>;
+
+/** Lightweight summary for the list view. */
+export const StatusPageSummarySchema = z.object({
+  id: z.string(),
+  slug: z.string(),
+  title: z.string(),
+  visibility: StatusPageVisibilitySchema,
+  published: z.boolean(),
+  publishedAt: z.string().nullable(),
+  updatedAt: z.string(),
+});
+export type StatusPageSummary = z.infer<typeof StatusPageSummarySchema>;
+
+// ===========================================================================
+// Public output (the ONLY shape the public surface ever receives)
+// ===========================================================================
+
+/**
+ * A block as rendered publicly: its type + optional label + the resolver's
+ * field-allow-listed `data` DTO. `data` is `unknown` at the contract boundary
+ * (each widget type defines its own DTO); the resolver validates against the
+ * per-type DTO schema before emitting.
+ */
+export const ResolvedBlockSchema = z.object({
+  id: z.string(),
+  type: z.string(),
+  label: z.string().optional(),
+  data: z.unknown(),
+});
+export type ResolvedBlock = z.infer<typeof ResolvedBlockSchema>;
+
+export const PublishedStatusPageSchema = z.object({
+  slug: z.string(),
+  title: z.string(),
+  theme: StatusPageThemeSchema,
+  blocks: z.array(ResolvedBlockSchema),
+  /** When the resolver assembled this snapshot (drives client cache hints). */
+  generatedAt: z.string(),
+});
+export type PublishedStatusPage = z.infer<typeof PublishedStatusPageSchema>;

package/src/select-events.test.ts

@@ -0,0 +1,74 @@
+import { describe, test, expect } from "bun:test";
+import { selectEvents } from "./select-events";
+
+interface Item {
+  id: string;
+  resolved: boolean;
+  at: string;
+}
+
+const NOW = new Date("2026-06-11T00:00:00.000Z").getTime();
+const daysAgo = (d: number) =>
+  new Date(NOW - d * 86_400_000).toISOString();
+
+const items: Item[] = [
+  { id: "a1", resolved: false, at: daysAgo(1) },
+  { id: "a2", resolved: false, at: daysAgo(3) },
+  { id: "p-recent", resolved: true, at: daysAgo(2) },
+  { id: "p-old", resolved: true, at: daysAgo(20) },
+];
+
+const base = {
+  items,
+  isPast: (i: Item) => i.resolved,
+  timestampOf: (i: Item) => i.at,
+  limit: 5,
+  now: NOW,
+};
+
+describe("selectEvents", () => {
+  test("includePast=false returns only active, newest first", () => {
+    const { active, past } = selectEvents({
+      ...base,
+      includePast: false,
+      pastMaxAgeDays: 7,
+    });
+    expect(active.map((i) => i.id)).toEqual(["a1", "a2"]);
+    expect(past).toEqual([]);
+  });
+
+  test("includePast=true keeps past within the max age, drops older", () => {
+    const { active, past } = selectEvents({
+      ...base,
+      includePast: true,
+      pastMaxAgeDays: 7,
+    });
+    expect(active.map((i) => i.id)).toEqual(["a1", "a2"]);
+    expect(past.map((i) => i.id)).toEqual(["p-recent"]); // p-old (20d) excluded
+  });
+
+  test("a wider max age includes older past items", () => {
+    const { past } = selectEvents({
+      ...base,
+      includePast: true,
+      pastMaxAgeDays: 30,
+    });
+    expect(past.map((i) => i.id)).toEqual(["p-recent", "p-old"]);
+  });
+
+  test("limit caps each group independently", () => {
+    const many: Item[] = Array.from({ length: 8 }, (_, i) => ({
+      id: `a${i}`,
+      resolved: false,
+      at: daysAgo(i),
+    }));
+    const { active } = selectEvents({
+      ...base,
+      items: many,
+      includePast: false,
+      pastMaxAgeDays: 7,
+      limit: 3,
+    });
+    expect(active).toHaveLength(3);
+  });
+});

package/src/select-events.ts

@@ -0,0 +1,56 @@
+/**
+ * Pure selection for the event-feed widgets (incidents, maintenance): split a
+ * list into ACTIVE and recently-PAST items, age-filter the past ones, sort each
+ * group newest-first, and cap both by `limit`. Domain-agnostic — the caller
+ * supplies the "is this past?" predicate and the timestamp accessor — so it is
+ * unit-tested once and reused by both backends.
+ */
+
+export interface SelectEventsArgs<T> {
+  items: T[];
+  /** True for a resolved incident / completed maintenance. */
+  isPast: (item: T) => boolean;
+  /** Timestamp used to sort (newest first) AND to age-filter past items. */
+  timestampOf: (item: T) => string | Date;
+  includePast: boolean;
+  pastMaxAgeDays: number;
+  limit: number;
+  /** `Date.now()` at the call site (injected so the logic stays pure/testable). */
+  now: number;
+}
+
+export interface SelectedEvents<T> {
+  active: T[];
+  past: T[];
+}
+
+function ms(value: string | Date): number {
+  return value instanceof Date ? value.getTime() : new Date(value).getTime();
+}
+
+export function selectEvents<T>({
+  items,
+  isPast,
+  timestampOf,
+  includePast,
+  pastMaxAgeDays,
+  limit,
+  now,
+}: SelectEventsArgs<T>): SelectedEvents<T> {
+  const byNewest = (a: T, b: T) => ms(timestampOf(b)) - ms(timestampOf(a));
+
+  const active = items
+    .filter((i) => !isPast(i))
+    .toSorted(byNewest)
+    .slice(0, limit);
+
+  if (!includePast) return { active, past: [] };
+
+  const cutoff = now - pastMaxAgeDays * 86_400_000;
+  const past = items
+    .filter((i) => isPast(i) && ms(timestampOf(i)) >= cutoff)
+    .toSorted(byNewest)
+    .slice(0, limit);
+
+  return { active, past };
+}

package/src/widget-types.ts

@@ -0,0 +1,250 @@
+import { z } from "zod";
+
+/**
+ * An http(s) URL. Status pages render these as `<a href>` / `<img src>` on a
+ * public surface, so disallow `javascript:` / `data:` / `file:` schemes that
+ * `z.string().url()` would otherwise accept (operator-side stored-XSS guard).
+ */
+export const HttpUrlSchema = z
+  .string()
+  .url()
+  .refine((v) => /^https?:\/\//i.test(v), {
+    message: "Must be an http(s) URL",
+  });
+
+/**
+ * Built-in widget catalogue for status pages. Each widget has:
+ *  - a CONFIG schema (what an operator edits + what is stored in the layout), and
+ *  - a public DTO schema (the field-ALLOW-LISTED shape the public resolver emits).
+ *
+ * The DTO is the security boundary: a resolver MUST only ever emit DTO fields,
+ * never the source resource's internal config / ids / `createdBy`. New plugins
+ * contribute additional widget types via the backend widget-type registry; these
+ * are the built-ins shipped by the platform.
+ */
+
+/**
+ * Industry-standard public status vocabulary (Statuspage/Instatus/Cachet). The
+ * INTERNAL health enum (healthy/degraded/unhealthy) is mapped onto this; the
+ * public page never exposes the internal enum.
+ */
+export const PublicStatusSchema = z.enum([
+  "operational",
+  "degraded",
+  "partial_outage",
+  "major_outage",
+  "maintenance",
+  "unknown",
+]);
+export type PublicStatus = z.infer<typeof PublicStatusSchema>;
+
+/**
+ * A bound system with an OPTIONAL public label override. Defaulting to the
+ * system's own name risks leaking an internal name (e.g. `prod-db-01.internal`);
+ * the override lets operators present a clean public label.
+ */
+export const SystemBindingSchema = z.object({
+  systemId: z.string().min(1),
+  label: z.string().trim().max(120).optional(),
+});
+export type SystemBinding = z.infer<typeof SystemBindingSchema>;
+
+// ===========================================================================
+// Config schemas (stored in the layout; admin-edited)
+// ===========================================================================
+
+export const BannerConfigSchema = z.object({
+  /** Systems whose health rolls up into the overall banner. Empty = no rollup. */
+  systemIds: z.array(z.string().min(1)).default([]),
+  /** Optional title override (else a status-derived label is shown). */
+  title: z.string().trim().max(160).optional(),
+});
+
+export const SystemHealthConfigSchema = z.object({
+  items: z.array(SystemBindingSchema).default([]),
+  /** Show a small uptime % next to each system. */
+  showUptime: z.boolean().default(false),
+});
+
+export const GroupStatusConfigSchema = z.object({
+  groupId: z.string().min(1),
+  label: z.string().trim().max(120).optional(),
+});
+
+export const UptimeConfigSchema = z.object({
+  systemId: z.string().min(1),
+  label: z.string().trim().max(120).optional(),
+  /** Days of history to show as daily bars (status-page standard is 90). */
+  days: z.number().int().min(1).max(90).default(90),
+});
+
+/**
+ * Shared config for the event-feed widgets (incidents, maintenance): whether to
+ * show the update timeline + how many, and whether to include recently
+ * resolved/completed items within a max age.
+ */
+export const EventFeedConfigSchema = z.object({
+  /** Render the per-item update timeline. */
+  showUpdates: z.boolean().default(true),
+  /** Cap the latest updates shown per item. */
+  maxUpdates: z.number().int().min(1).max(10).default(3),
+  /** Include resolved incidents / completed maintenances (not just active). */
+  includePast: z.boolean().default(false),
+  /** Only past items resolved/completed within the last N days. */
+  pastMaxAgeDays: z.number().int().min(1).max(90).default(7),
+});
+
+export const IncidentsConfigSchema = EventFeedConfigSchema.extend({
+  /** Restrict to incidents touching these systems. Empty = all visible. */
+  systemIds: z.array(z.string().min(1)).default([]),
+  limit: z.number().int().min(1).max(20).default(5),
+});
+
+export const MaintenanceConfigSchema = EventFeedConfigSchema.extend({
+  systemIds: z.array(z.string().min(1)).default([]),
+  limit: z.number().int().min(1).max(20).default(5),
+});
+
+export const TextConfigSchema = z.object({
+  /** Markdown, rendered SANITIZED on the public page (no raw HTML/JS). */
+  markdown: z.string().max(20_000).default(""),
+});
+
+export const HeadingConfigSchema = z.object({
+  text: z.string().trim().max(200).default(""),
+  level: z.number().int().min(1).max(3).default(2),
+});
+
+export const LinkSchema = z.object({
+  label: z.string().trim().min(1).max(120),
+  url: HttpUrlSchema,
+});
+export const LinksConfigSchema = z.object({
+  links: z.array(LinkSchema).max(20).default([]),
+});
+
+export const ImageConfigSchema = z.object({
+  url: HttpUrlSchema,
+  alt: z.string().trim().max(200).optional(),
+  maxHeight: z.number().int().min(16).max(400).optional(),
+});
+
+export const DividerConfigSchema = z.object({});
+
+// ===========================================================================
+// Public DTO schemas (resolver output; the field allow-list)
+// ===========================================================================
+
+export const StatusItemDtoSchema = z.object({
+  label: z.string(),
+  status: PublicStatusSchema,
+  uptimePct: z.number().optional(),
+});
+
+export const BannerDtoSchema = z.object({
+  status: PublicStatusSchema,
+  title: z.string(),
+});
+
+export const SystemHealthDtoSchema = z.object({
+  systems: z.array(StatusItemDtoSchema),
+});
+
+export const GroupStatusDtoSchema = z.object({
+  label: z.string(),
+  status: PublicStatusSchema,
+  systems: z.array(StatusItemDtoSchema),
+});
+
+export const UptimeBarSchema = z.object({
+  date: z.string(),
+  uptimePct: z.number(),
+  status: PublicStatusSchema,
+});
+export const UptimeDtoSchema = z.object({
+  label: z.string(),
+  uptimePct: z.number(),
+  bars: z.array(UptimeBarSchema),
+});
+
+/** A public-safe timeline update: NO `createdBy` (that is an internal leak). */
+export const PublicUpdateSchema = z.object({
+  message: z.string(),
+  statusChange: z.string().optional(),
+  at: z.string(),
+});
+
+export const IncidentDtoItemSchema = z.object({
+  id: z.string(),
+  title: z.string(),
+  status: z.string(),
+  severity: z.string(),
+  systems: z.array(z.string()),
+  startedAt: z.string(),
+  /** When the incident was resolved (present only for resolved incidents). */
+  resolvedAt: z.string().optional(),
+  updates: z.array(PublicUpdateSchema),
+});
+export const IncidentsDtoSchema = z.object({
+  incidents: z.array(IncidentDtoItemSchema),
+});
+
+export const MaintenanceDtoItemSchema = z.object({
+  id: z.string(),
+  title: z.string(),
+  status: z.string(),
+  startAt: z.string(),
+  endAt: z.string(),
+  systems: z.array(z.string()),
+  updates: z.array(PublicUpdateSchema),
+});
+export const MaintenanceDtoSchema = z.object({
+  maintenances: z.array(MaintenanceDtoItemSchema),
+});
+
+export const TextDtoSchema = z.object({ markdown: z.string() });
+export const HeadingDtoSchema = z.object({
+  text: z.string(),
+  level: z.number(),
+});
+export const LinksDtoSchema = LinksConfigSchema;
+export const ImageDtoSchema = ImageConfigSchema;
+export const DividerDtoSchema = z.object({});
+
+// ===========================================================================
+// Catalogue: ids + metadata the builder lists
+// ===========================================================================
+
+/** What a widget binds to (drives the builder's resource-picker + edit-time authz). */
+export const WidgetBindingKindSchema = z.enum([
+  "none",
+  "system",
+  "systems",
+  "group",
+]);
+export type WidgetBindingKind = z.infer<typeof WidgetBindingKindSchema>;
+
+export const WidgetTypeDescriptorSchema = z.object({
+  /** Qualified id, e.g. "statuspage.systemHealth". */
+  id: z.string(),
+  displayName: z.string(),
+  description: z.string(),
+  category: z.string(),
+  binding: WidgetBindingKindSchema,
+});
+export type WidgetTypeDescriptor = z.infer<typeof WidgetTypeDescriptorSchema>;
+
+/** Stable ids for the built-in widget types (qualified by the plugin id). */
+export const BUILTIN_WIDGET_IDS = {
+  banner: "statuspage.banner",
+  systemHealth: "statuspage.systemHealth",
+  groupStatus: "statuspage.groupStatus",
+  uptime: "statuspage.uptime",
+  incidents: "statuspage.incidents",
+  maintenance: "statuspage.maintenance",
+  text: "statuspage.text",
+  heading: "statuspage.heading",
+  links: "statuspage.links",
+  image: "statuspage.image",
+  divider: "statuspage.divider",
+} as const;

package/tsconfig.json

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