@openlup/platform 0.29.0 → 0.30.0

package/src/operations/adminAlertsView.ts

@@ -0,0 +1,238 @@
+import type {
+  AdminAlert,
+  AdminAlertHealth,
+  AdminAlertLane,
+  AdminAlertSeverity,
+  AdminAlertsHeartbeat,
+  AdminAlertsOverviewResponse,
+  AdminAlertsSummary,
+} from "./contracts/adminAlertsContracts.js";
+import { DEFAULT_PAGING_MIN_SEVERITY, shouldPage } from "./alertPagingPolicy.js";
+
+/**
+ * Pure projection of platform_alerts rows onto the admin shell's badges.
+ *
+ * All filtering lives here rather than in SQL so the `now` boundary is injectable
+ * and every rule is unit-testable without a database.
+ */
+
+/** Raw ledger row as selected from public.platform_alerts. */
+export type PlatformAlertLedgerRow = {
+  id: string;
+  dedupe_key: string;
+  owner: string;
+  severity: string;
+  status: string;
+  title: string;
+  message: string | null;
+  support_code: string | null;
+  runbook_url: string | null;
+  first_seen_at: string;
+  last_seen_at: string;
+  snoozed_until: string | null;
+};
+
+export type WatchdogHeartbeatRow = {
+  last_success_at: string | null;
+} | null;
+
+/**
+ * Generic scheduled-job alerts inherit `owner` from the job catalog entry, so a
+ * commerce-owned job leaks engineer-only noise ("this cron failed") into what
+ * should be an operator's queue. They still count toward platform health.
+ */
+export const GENERIC_JOB_DEDUPE_PREFIXES = [
+  "job_failed:",
+  "job_missed:",
+  "job_never_succeeded:",
+  "job_stuck_running:",
+  "job_ledger_missing:",
+] as const;
+
+/**
+ * How old a watchdog heartbeat may be before the health pill stops trusting it.
+ *
+ * The development-preview reference uses a conservative six-hour stale window
+ * independent from any scheduler cadence. It is a policy default, not a
+ * scheduling SLA; adopters must review it against their expected maximum
+ * heartbeat delay and queue jitter.
+ */
+export const WATCHDOG_STALE_AFTER_SECONDS = 6 * 60 * 60;
+
+const SEVERITY_RANK: Record<AdminAlertSeverity, number> = { p0: 0, p1: 1, p2: 2, p3: 3 };
+
+/**
+ * Derived from the paging policy's DEFAULT floor, not from the live threshold:
+ * this is a pure projection with no access to PLATFORM_ALERT_PAGING_MIN_SEVERITY,
+ * so an operator who overrides that variable makes panel and pager disagree
+ * again. Threading the parsed floor through the admin BFF is wave-3 work.
+ */
+function isPageableSeverity(severity: AdminAlertSeverity): boolean {
+  return shouldPage(severity, DEFAULT_PAGING_MIN_SEVERITY);
+}
+
+export function isGenericJobAlert(dedupeKey: string): boolean {
+  return GENERIC_JOB_DEDUPE_PREFIXES.some((prefix) => dedupeKey.startsWith(prefix));
+}
+
+/**
+ * Display bucket. `commerce` means "a business operator can act on this".
+ *
+ * `commerce/platform` is deliberately excluded: despite the prefix it owns
+ * engineering-run plumbing (outbox-dispatch, outbox-prune, abandoned-cart,
+ * review-request, reorder-reminder).
+ */
+export function classifyLane(owner: string, dedupeKey: string): AdminAlertLane {
+  if (isGenericJobAlert(dedupeKey)) return "platform";
+  if (!owner.startsWith("commerce/")) return "platform";
+  if (owner === "commerce/platform") return "platform";
+  return "commerce";
+}
+
+export function isSnoozed(snoozedUntil: string | null, now: Date): boolean {
+  if (!snoozedUntil) return false;
+  const until = Date.parse(snoozedUntil);
+  return Number.isFinite(until) && until > now.getTime();
+}
+
+/**
+ * Unknown severities are treated as p0 — mirrors alertPagingPolicy's fail-safe,
+ * where an unrecognised severity always pages rather than silently disappearing.
+ */
+function normalizeSeverity(severity: string): AdminAlertSeverity {
+  return severity in SEVERITY_RANK ? (severity as AdminAlertSeverity) : "p0";
+}
+
+function normalizeIso(value: string): string {
+  const parsed = Date.parse(value);
+  return Number.isFinite(parsed) ? new Date(parsed).toISOString() : value;
+}
+
+/** Unresolved ledger state, including a controlled snoozed exception. */
+function isOpen(row: PlatformAlertLedgerRow): boolean {
+  if (row.status !== "open" && row.status !== "acknowledged") return false;
+  return true;
+}
+
+/** Live enough to affect the health badge and paging. */
+function isLive(row: PlatformAlertLedgerRow, now: Date): boolean {
+  return isOpen(row) && !isSnoozed(row.snoozed_until, now);
+}
+
+/**
+ * Pageable means "this would wake someone up": live and above the paging floor.
+ * Acknowledged rows stay pageable on purpose — acknowledged is not resolved, the
+ * system is still broken.
+ */
+export function isPageable(row: PlatformAlertLedgerRow, now: Date): boolean {
+  return isLive(row, now) && isPageableSeverity(normalizeSeverity(row.severity));
+}
+
+export function toAdminAlert(row: PlatformAlertLedgerRow, now: Date): AdminAlert {
+  return {
+    id: row.id,
+    dedupeKey: row.dedupe_key,
+    lane: classifyLane(row.owner, row.dedupe_key),
+    owner: row.owner,
+    severity: normalizeSeverity(row.severity),
+    status: row.status === "acknowledged" ? "acknowledged" : "open",
+    pageable: isPageable(row, now),
+    title: row.title,
+    message: row.message ?? "",
+    supportCode: row.support_code,
+    runbookUrl: row.runbook_url,
+    firstSeenAt: normalizeIso(row.first_seen_at),
+    lastSeenAt: normalizeIso(row.last_seen_at),
+    snoozedUntil: row.snoozed_until ? normalizeIso(row.snoozed_until) : null,
+  };
+}
+
+export function worstSeverity(alerts: readonly AdminAlert[]): AdminAlertSeverity | null {
+  let worst: AdminAlertSeverity | null = null;
+  for (const alert of alerts) {
+    if (!worst || SEVERITY_RANK[alert.severity] < SEVERITY_RANK[worst]) worst = alert.severity;
+  }
+  return worst;
+}
+
+/**
+ * `commercePageableCount` and `platformPageableCount` partition the pageable set,
+ * so no alert that would page is ever invisible in the popover.
+ */
+export function summarizeAlerts(alerts: readonly AdminAlert[]): AdminAlertsSummary {
+  const pageable = alerts.filter((alert) => alert.pageable);
+  return {
+    commercePageableCount: pageable.filter((alert) => alert.lane === "commerce").length,
+    commerceTotalCount: alerts.filter((alert) => alert.lane === "commerce").length,
+    platformPageableCount: pageable.filter((alert) => alert.lane === "platform").length,
+    snoozedCount: 0,
+    maxOpenSeverity: worstSeverity(alerts),
+  };
+}
+
+export function buildHeartbeat(row: WatchdogHeartbeatRow, now: Date): AdminAlertsHeartbeat {
+  const lastSuccessAt = row?.last_success_at ?? null;
+  const parsed = lastSuccessAt ? Date.parse(lastSuccessAt) : Number.NaN;
+  const stale =
+    !Number.isFinite(parsed) || now.getTime() - parsed > WATCHDOG_STALE_AFTER_SECONDS * 1000;
+  return {
+    lastSuccessAt: Number.isFinite(parsed) ? new Date(parsed).toISOString() : null,
+    staleAfterSeconds: WATCHDOG_STALE_AFTER_SECONDS,
+    stale,
+  };
+}
+
+/**
+ * Staleness beats severity: if the watchdog has not reported recently we do not
+ * know the current state, and "unknown" is the only honest answer. There is no
+ * path here that renders a green "systems ok" from missing data.
+ */
+export function deriveHealth(
+  summary: AdminAlertsSummary,
+  heartbeat: AdminAlertsHeartbeat,
+): AdminAlertHealth {
+  if (heartbeat.stale) return "unknown";
+  if (summary.maxOpenSeverity === "p0") return "down";
+  if (summary.maxOpenSeverity === "p1") return "degraded";
+  return "ok";
+}
+
+/** Alerts returned to the client; counts above stay accurate even when this is truncated. */
+export const ADMIN_ALERTS_LIST_LIMIT = 50;
+
+function compareForDisplay(a: AdminAlert, b: AdminAlert): number {
+  const bySeverity = SEVERITY_RANK[a.severity] - SEVERITY_RANK[b.severity];
+  if (bySeverity !== 0) return bySeverity;
+  return Date.parse(b.lastSeenAt) - Date.parse(a.lastSeenAt);
+}
+
+export function buildAlertsOverview(
+  rows: readonly PlatformAlertLedgerRow[],
+  heartbeatRow: WatchdogHeartbeatRow,
+  now: Date,
+): AdminAlertsOverviewResponse {
+  const openRows = rows.filter(isOpen);
+  const alerts = openRows
+    .filter((row) => isLive(row, now))
+    .map((row) => toAdminAlert(row, now))
+    .sort(compareForDisplay);
+  const snoozedAlerts = openRows
+    .filter((row) => isSnoozed(row.snoozed_until, now))
+    .map((row) => toAdminAlert(row, now))
+    .sort(compareForDisplay);
+  const summary = {
+    ...summarizeAlerts(alerts),
+    snoozedCount: snoozedAlerts.length,
+  };
+  const heartbeat = buildHeartbeat(heartbeatRow, now);
+  return {
+    health: deriveHealth(summary, heartbeat),
+    summary,
+    heartbeat,
+    alerts: alerts.slice(0, ADMIN_ALERTS_LIST_LIMIT),
+    // Deliberately separate from the active list's limit: controlled exceptions
+    // are relevant audit context, but must not turn the health pill red.
+    snoozedAlerts,
+    generatedAt: now.toISOString(),
+  };
+}

package/src/operations/alertPagingPolicy.ts

@@ -0,0 +1,50 @@
+import type { AlertSeverity } from "./contracts/observabilityContracts.js";
+const ALERT_SEVERITIES: readonly AlertSeverity[] = ["p0", "p1", "p2", "p3"];
+
+/**
+ * Paging policy for platform watchdog alerts.
+ *
+ * The alert ledger records every severity, but only sufficiently severe alerts
+ * should page an on-call channel (e.g. ntfy). Lower-severity alerts stay
+ * ledger-only so real incidents are not buried under routine noise.
+ *
+ * The tiering is settled: **p0 pages** (customers cannot buy, renewals cannot
+ * charge, the platform or database is down); **p1 is panel-urgent** and turns
+ * the admin health pill `degraded` without waking anyone; **p2/p3** are the
+ * panel list and the ledger. An unknown severity still pages: the fail-open
+ * rule is unchanged, because silence must never be the result of a
+ * classification error.
+ *
+ * Lower rank == more severe.
+ */
+const SEVERITY_RANK: Record<AlertSeverity, number> = { p0: 0, p1: 1, p2: 2, p3: 3 };
+
+/** Alerts at or above this severity page by default; below it are ledger-only. */
+export const DEFAULT_PAGING_MIN_SEVERITY: AlertSeverity = "p0";
+
+/**
+ * Whether an alert of `severity` should page given the `minSeverity` threshold.
+ *
+ * Fail-safe: an unknown/unparseable severity always pages (treated as most
+ * urgent). Silence must never be the result of a classification error.
+ */
+export function shouldPage(
+  severity: string,
+  minSeverity: AlertSeverity = DEFAULT_PAGING_MIN_SEVERITY,
+): boolean {
+  const rank = SEVERITY_RANK[severity as AlertSeverity];
+  if (rank === undefined) return true;
+  return rank <= SEVERITY_RANK[minSeverity];
+}
+
+/**
+ * Parse a paging threshold from configuration (e.g. an env var), falling back to
+ * {@link DEFAULT_PAGING_MIN_SEVERITY} for any missing or invalid value.
+ */
+export function parsePagingMinSeverity(value: string | null | undefined): AlertSeverity {
+  const normalized = value?.trim().toLowerCase();
+  if (normalized && (ALERT_SEVERITIES as readonly string[]).includes(normalized)) {
+    return normalized as AlertSeverity;
+  }
+  return DEFAULT_PAGING_MIN_SEVERITY;
+}

package/src/operations/alertThrottlePolicy.ts

@@ -0,0 +1,22 @@
+import type { AlertSeverity } from "./contracts/observabilityContracts.js";
+
+/**
+ * Per-severity re-notification cadence for platform watchdog alerts.
+ *
+ * A firing alert re-pages at most once per this window (keyed off
+ * `last_notified_at`). Lower severities re-page less often so a persistent
+ * low-severity alert cannot flood the channel, while p0 stays loud.
+ */
+const THROTTLE_SECONDS_BY_SEVERITY: Record<AlertSeverity, number> = {
+  p0: 1 * 60 * 60, // 1h
+  p1: 4 * 60 * 60, // 4h
+  p2: 12 * 60 * 60, // 12h
+  p3: 24 * 60 * 60, // 24h
+};
+
+/** Fallback window for an unknown/unparseable severity. */
+export const DEFAULT_THROTTLE_SECONDS = 60 * 60;
+
+export function throttleSecondsForSeverity(severity: string): number {
+  return THROTTLE_SECONDS_BY_SEVERITY[severity as AlertSeverity] ?? DEFAULT_THROTTLE_SECONDS;
+}

package/src/operations/clients.ts

@@ -0,0 +1,44 @@
+import type { z } from "zod";
+import { adminSettingsReadResponseSchema, adminSettingsUpdateResponseSchema, adminPipelineReadResponseSchema } from "./schemas.js";
+import { adminAlertsOverviewResponseSchema } from "./adminAlertsSchemas.js";
+import type { AdminSettingsReadResponse, AdminSettingsUpdateRequest, AdminSettingsUpdateResponse, AdminPipelineReadResponse } from "./contracts/admin.js";
+import type { AdminAlertsOverviewResponse } from "./contracts/adminAlertsContracts.js";
+
+/** The existing BFF requester owns fetch, envelope validation, cancellation and diagnostics. */
+export interface OperationsRequestOptions extends Omit<RequestInit, "body"> {
+  body?: unknown;
+  fetcher?: typeof fetch;
+  timeoutMs?: number;
+}
+export type OperationsRequestBff = <T>(path: string, schema: z.ZodType<T>, options?: OperationsRequestOptions) => Promise<T>;
+
+/** Bind the existing browser calls without installing an ambient fetch implementation. */
+export function createOperationsClients(requestBff: OperationsRequestBff) {
+  return {
+    getAdminSettings(accessToken: string, options: OperationsRequestOptions = {}): Promise<AdminSettingsReadResponse> {
+      return requestBff("/api/bff/admin/platform/settings", adminSettingsReadResponseSchema, {
+        ...options, method: "GET", headers: authHeaders(accessToken, options),
+      });
+    },
+    updateAdminSetting(accessToken: string, request: AdminSettingsUpdateRequest, options: OperationsRequestOptions = {}): Promise<AdminSettingsUpdateResponse> {
+      return requestBff("/api/bff/admin/platform/settings/update", adminSettingsUpdateResponseSchema, {
+        ...options, method: "POST", headers: authHeaders(accessToken, options), body: request,
+      });
+    },
+    getAdminPipeline(accessToken: string, options: OperationsRequestOptions = {}): Promise<AdminPipelineReadResponse> {
+      return requestBff("/api/bff/admin/platform/pipeline", adminPipelineReadResponseSchema, {
+        ...options, method: "GET", headers: authHeaders(accessToken, options),
+      });
+    },
+    getAdminAlertsOverview(accessToken: string, options: OperationsRequestOptions = {}): Promise<AdminAlertsOverviewResponse> {
+      return requestBff("/api/bff/admin/platform/alerts", adminAlertsOverviewResponseSchema, {
+        ...options, method: "GET", headers: authHeaders(accessToken, options),
+      });
+    },
+  };
+}
+function authHeaders(accessToken: string, options: OperationsRequestOptions): Headers {
+  const headers = new Headers(options.headers);
+  headers.set("Authorization", `Bearer ${accessToken}`);
+  return headers;
+}

package/src/operations/contracts/admin.ts

@@ -0,0 +1,24 @@
+/** DTOs for the existing operational settings, pipeline and control-plane surfaces. */
+export type AdminPipelineTester = { id: string; status: string; email_sequence_step: number | null; email_sequence_paused: boolean | null };
+export type AdminPipelineEmailTemplate = { id: string; name: string; sequence_order: number | null };
+export type AdminPipelineEmailEvent = { event_type: string };
+export type AdminPipelineReadRequest = Record<string, never>;
+export type AdminPipelineReadResponse = { testers: AdminPipelineTester[]; templates: AdminPipelineEmailTemplate[]; emailSendCount: number; emailEvents: AdminPipelineEmailEvent[] };
+export type AdminPipelineDhlTrackingRefreshRequest = Record<string, never>;
+export type AdminPipelineDhlTrackingRefreshResponse = { checked: number; updated: number };
+export type AdminSettingsAdminUser = { id: string; email: string | null; role: string | null };
+export type AdminSettingsReadRequest = Record<string, never>;
+export type AdminSettingsReadResponse = { settings: Record<string, unknown>; adminUsers: AdminSettingsAdminUser[] };
+export type AdminSettingWriteValue = string | number | boolean | null;
+export type AdminSettingsUpdateRequest = { key: string; value: AdminSettingWriteValue };
+export type AdminSettingsUpdateResponse = { key: string; saved: true };
+export type PlatformControlPlaneReadRequest = Record<string, never>;
+export type PlatformControlPlaneReadResponse = {
+  controls: { controlKey: string; enabled: boolean; revision: number; updatedAt: string }[];
+  jobs: { jobName: string; enabled: boolean; activeDriver: "worker" | "scheduler" | "operator"; lastStatus: "running" | "success" | "failed" | "skipped" | null; lastStartedAt: string | null; lastFinishedAt: string | null; lastSuccessAt: string | null }[];
+  alerts: { dedupeKey: string; severity: "p0" | "p1" | "p2" | "p3"; status: "open" | "acknowledged" | "resolved"; owner: string; title: string; firstSeenAt: string; lastSeenAt: string; resolvedAt: string | null }[];
+};
+export type PlatformControlPlaneMutation =
+  | { action: "set-control"; idempotencyKey: string; controlKey: string; enabled: boolean }
+  | { action: "record-heartbeat"; idempotencyKey: string; health: "healthy" | "degraded" | "failed"; firingCount: number; maxSeverity: "p0" | "p1" | "p2" | "p3" | null; promotionReady: boolean };
+export type PlatformControlPlaneMutationResponse = { action: "set-control" | "record-heartbeat"; replayed: boolean; revision: number | null; recordedAt: string };

package/src/operations/contracts/adminAlertsContracts.ts

@@ -0,0 +1,13 @@
+/** Operator projection; persistence and read authority remain host-owned. */
+export type AdminAlertSeverity = "p0" | "p1" | "p2" | "p3";
+export type AdminAlertLane = "commerce" | "platform";
+export type AdminAlertHealth = "ok" | "degraded" | "down" | "unknown";
+export type AdminAlert = {
+  id: string; dedupeKey: string; lane: AdminAlertLane; owner: string;
+  severity: AdminAlertSeverity; status: "open" | "acknowledged"; pageable: boolean;
+  title: string; message: string; supportCode: string | null; runbookUrl: string | null;
+  firstSeenAt: string; lastSeenAt: string; snoozedUntil: string | null;
+};
+export type AdminAlertsHeartbeat = { lastSuccessAt: string | null; staleAfterSeconds: number; stale: boolean };
+export type AdminAlertsSummary = { commercePageableCount: number; commerceTotalCount: number; platformPageableCount: number; snoozedCount: number; maxOpenSeverity: AdminAlertSeverity | null };
+export type AdminAlertsOverviewResponse = { health: AdminAlertHealth; summary: AdminAlertsSummary; heartbeat: AdminAlertsHeartbeat; alerts: AdminAlert[]; snoozedAlerts: AdminAlert[]; generatedAt: string };

package/src/operations/contracts/alertHumanContext.ts

@@ -0,0 +1,17 @@
+export type AlertIncidentClass =
+  | "customer_communication_failure"
+  | "scheduled_job_failed"
+  | "scheduled_job_missed"
+  | "fulfillment_tracking_stalled"
+  | "configuration_drift"
+  | "data_integrity"
+  | "queue_backlog"
+  | "recipient_configuration_failure"
+  | "platform_watchdog";
+
+export type AlertHumanContext = {
+  incidentClass: AlertIncidentClass;
+  impact: string;
+  firstAction: string;
+  urgency: string;
+};

package/src/operations/contracts/index.ts

@@ -0,0 +1,6 @@
+export * from "./admin.js";
+export * from "./adminAlertsContracts.js";
+export * from "./ports.js";
+export * from "./observabilityContracts.js";
+export * from "./observabilityPorts.js";
+export * from "./alertHumanContext.js";

package/src/operations/contracts/observabilityContracts.ts

@@ -0,0 +1,40 @@
+export type AlertSeverity = "p0" | "p1" | "p2" | "p3";
+/** Opaque host-owned transport key; this module declares no vendor capability. */
+export type AlertChannel = string;
+export type WatchdogSnapshot = { checkedAt: string };
+
+export type AlertDecision<Channel extends string = AlertChannel> = {
+  dedupeKey: string;
+  severity: AlertSeverity;
+  owner: string;
+  runbookUrl: string;
+  title: string;
+  message: string; humanContext?: import("./alertHumanContext.js").AlertHumanContext;
+  channels: Channel[];
+  payload: Record<string, unknown>; paging?: "default" | "never";
+};
+
+export type OpenAlert = {
+  id: string;
+  dedupeKey: string;
+  status: "open" | "acknowledged";
+  severity: AlertSeverity;
+  lastNotifiedAt: string | null;
+  /** Most recent watchdog delivery decision, including skipped/failed attempts. */
+  lastNotificationAttemptAt?: string | null;
+  lastNotificationStatus?: AlertNotificationOutcome["status"] | null;
+  /** Earliest time the watchdog may create another delivery-attempt ledger row. */
+  nextNotificationAttemptAt?: string | null;
+  /** Consecutive failed webhook attempts; reset by sent/skipped outcomes. */
+  notificationFailureCount?: number;
+  /** Operator silence window; when set and in the future, paging is suppressed. */
+  snoozedUntil?: string | null;
+};
+
+export type AlertNotificationOutcome<Channel extends string = AlertChannel> = {
+  channel: Channel;
+  status: "sent" | "failed" | "skipped";
+  provider?: string | null;
+  providerResponse?: Record<string, unknown> | null;
+  error?: string | null;
+};

package/src/operations/contracts/observabilityPorts.ts

@@ -0,0 +1,30 @@
+import type {
+  AlertDecision,
+  AlertNotificationOutcome,
+  WatchdogSnapshot,
+  OpenAlert,
+} from "./observabilityContracts.js";
+
+export type ObservabilityEvidencePort<Snapshot extends WatchdogSnapshot = WatchdogSnapshot> = {
+  collectSnapshot(now: Date): Promise<Snapshot>;
+};
+
+export type AlertLedgerPort<Channel extends string = string> = {
+  listOpenAlerts(): Promise<OpenAlert[]>;
+  upsertOpenAlert: (decision: AlertDecision<Channel>, now: Date) => Promise<OpenAlert>;
+  resolveAlert(dedupeKey: string, now: Date): Promise<void>;
+  recordNotification: (
+    alertId: string,
+    /** The kernel retains its existing webhook-keyed skipped-attempt audit rows. */
+    outcome: AlertNotificationOutcome<Channel | "webhook">,
+    now: Date,
+    schedule: {
+      nextAttemptAt: Date;
+      failureCount: number;
+    },
+  ) => Promise<void>;
+};
+
+export type AlertSinkPort<Channel extends string = string> = {
+  send: (decision: AlertDecision<Channel>, alert: OpenAlert) => Promise<AlertNotificationOutcome<Channel>>;
+};

package/src/operations/contracts/ports.ts

@@ -0,0 +1,22 @@
+import type {
+  AdminPipelineReadRequest, AdminPipelineReadResponse,
+  AdminSettingsReadRequest, AdminSettingsReadResponse,
+  AdminSettingsUpdateRequest, AdminSettingsUpdateResponse,
+  PlatformControlPlaneReadRequest, PlatformControlPlaneReadResponse,
+  PlatformControlPlaneMutation, PlatformControlPlaneMutationResponse,
+} from "./admin.js";
+
+export interface AdminPipelineReadPort {
+  readPipeline(request: AdminPipelineReadRequest): Promise<AdminPipelineReadResponse>;
+}
+export interface AdminSettingsOperationsPort {
+  readSettings(request: AdminSettingsReadRequest): Promise<AdminSettingsReadResponse>;
+  updateSetting(request: AdminSettingsUpdateRequest): Promise<AdminSettingsUpdateResponse>;
+}
+export interface PlatformControlPlanePort {
+  readControlPlane(request: PlatformControlPlaneReadRequest): Promise<PlatformControlPlaneReadResponse>;
+  mutateControlPlane(request: PlatformControlPlaneMutation): Promise<PlatformControlPlaneMutationResponse>;
+}
+export type OperationsAuthorizationResult =
+  | { ok: true }
+  | { ok: false; code: "UNAUTHORIZED" | "FORBIDDEN"; message: string };

package/src/operations/errors.ts

@@ -0,0 +1,6 @@
+export class PlatformControlPlaneConflictError extends Error {
+  override readonly name = "PlatformControlPlaneConflictError";
+}
+export class PlatformControlPlaneUnavailableError extends Error {
+  override readonly name = "PlatformControlPlaneUnavailableError";
+}

package/src/operations/index.ts

@@ -0,0 +1,9 @@
+/** Browser-safe operational contracts, validation and operator projections. */
+export * from "./contracts/index.js";
+export * from "./schemas.js";
+export * from "./adminAlertsSchemas.js";
+export * from "./adminAlertsView.js";
+export * from "./alertPagingPolicy.js";
+export * from "./alertThrottlePolicy.js";
+export * from "./errors.js";
+export * from "./clients.js";

package/src/operations/schemas.ts

@@ -0,0 +1,122 @@
+import { z } from "./validation.js";
+
+export const adminPipelineTesterSchema = z.object({
+  id: z.string().min(1),
+  status: z.string().min(1),
+  email_sequence_step: z.number().int().min(0).nullable(),
+  email_sequence_paused: z.boolean().nullable(),
+});
+
+export const adminPipelineEmailTemplateSchema = z.object({
+  id: z.string().min(1),
+  name: z.string().min(1),
+  sequence_order: z.number().int().min(0).nullable(),
+});
+
+export const adminPipelineEmailEventSchema = z.object({
+  event_type: z.string().min(1),
+});
+
+export const adminPipelineReadRequestSchema = z.object({}).strict();
+
+export const adminPipelineReadResponseSchema = z.object({
+  testers: z.array(adminPipelineTesterSchema),
+  templates: z.array(adminPipelineEmailTemplateSchema),
+  emailSendCount: z.number().int().min(0),
+  emailEvents: z.array(adminPipelineEmailEventSchema),
+});
+
+export const adminPipelineDhlTrackingRefreshRequestSchema = z.object({}).strict();
+
+export const adminPipelineDhlTrackingRefreshResponseSchema = z.object({
+  checked: z.number().int().min(0),
+  updated: z.number().int().min(0),
+});
+
+export const adminSettingsReadRequestSchema = z.object({}).strict();
+
+export const adminSettingsAdminUserSchema = z.object({
+  id: z.string().min(1),
+  email: z.string().nullable(),
+  role: z.string().nullable(),
+});
+
+export const adminSettingsReadResponseSchema = z.object({
+  settings: z.record(z.string(), z.unknown()),
+  adminUsers: z.array(adminSettingsAdminUserSchema),
+});
+
+export const adminSettingWriteValueSchema = z.union([
+  z.string(),
+  z.number(),
+  z.boolean(),
+  z.null(),
+]);
+
+export const adminSettingsUpdateRequestSchema = z.object({
+  key: z.string().trim().min(1),
+  value: adminSettingWriteValueSchema,
+});
+
+export const adminSettingsUpdateResponseSchema = z.object({
+  key: z.string().min(1),
+  saved: z.literal(true),
+});
+
+const platformControlKeySchema = z.string().trim().regex(/^[A-Za-z0-9][A-Za-z0-9._:-]{0,119}$/);
+const platformOperationKeySchema = z.string().trim().regex(/^[A-Za-z0-9][A-Za-z0-9._:-]{0,255}$/);
+const platformTimestampSchema = z.string().datetime({ offset: true });
+
+export const platformControlPlaneReadRequestSchema = z.object({}).strict();
+
+export const platformControlPlaneReadResponseSchema = z.object({
+  controls: z.array(z.object({
+    controlKey: platformControlKeySchema,
+    enabled: z.boolean(),
+    revision: z.number().int().min(1),
+    updatedAt: platformTimestampSchema,
+  })),
+  jobs: z.array(z.object({
+    jobName: z.string().min(1),
+    enabled: z.boolean(),
+    activeDriver: z.enum(["worker", "scheduler", "operator"]),
+    lastStatus: z.enum(["running", "success", "failed", "skipped"]).nullable(),
+    lastStartedAt: platformTimestampSchema.nullable(),
+    lastFinishedAt: platformTimestampSchema.nullable(),
+    lastSuccessAt: platformTimestampSchema.nullable(),
+  })),
+  alerts: z.array(z.object({
+    dedupeKey: z.string().min(1),
+    severity: z.enum(["p0", "p1", "p2", "p3"]),
+    status: z.enum(["open", "acknowledged", "resolved"]),
+    owner: z.string().min(1),
+    title: z.string().min(1),
+    firstSeenAt: platformTimestampSchema,
+    lastSeenAt: platformTimestampSchema,
+    resolvedAt: platformTimestampSchema.nullable(),
+  })),
+});
+
+export const platformControlPlaneMutationSchema = z.union([
+  z.object({
+    action: z.literal("set-control"),
+    idempotencyKey: platformOperationKeySchema,
+    controlKey: platformControlKeySchema,
+    enabled: z.boolean(),
+  }).strict(),
+  z.object({
+    action: z.literal("record-heartbeat"),
+    idempotencyKey: platformOperationKeySchema,
+    health: z.enum(["healthy", "degraded", "failed"]),
+    firingCount: z.number().int().min(0),
+    maxSeverity: z.enum(["p0", "p1", "p2", "p3"]).nullable(),
+    promotionReady: z.boolean(),
+  }).strict(),
+]);
+
+export const platformControlPlaneMutationResponseSchema = z.object({
+  action: z.enum(["set-control", "record-heartbeat"]),
+  replayed: z.boolean(),
+  revision: z.number().int().min(1).nullable(),
+  recordedAt: platformTimestampSchema,
+});