@openlup/platform 0.28.0 → 0.30.0

package/dist/operations/clients.d.ts

@@ -0,0 +1,17 @@
+import type { z } from "zod";
+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 declare function createOperationsClients(requestBff: OperationsRequestBff): {
+    getAdminSettings(accessToken: string, options?: OperationsRequestOptions): Promise<AdminSettingsReadResponse>;
+    updateAdminSetting(accessToken: string, request: AdminSettingsUpdateRequest, options?: OperationsRequestOptions): Promise<AdminSettingsUpdateResponse>;
+    getAdminPipeline(accessToken: string, options?: OperationsRequestOptions): Promise<AdminPipelineReadResponse>;
+    getAdminAlertsOverview(accessToken: string, options?: OperationsRequestOptions): Promise<AdminAlertsOverviewResponse>;
+};

package/dist/operations/clients.js

@@ -0,0 +1,32 @@
+import { adminSettingsReadResponseSchema, adminSettingsUpdateResponseSchema, adminPipelineReadResponseSchema } from "./schemas.js";
+import { adminAlertsOverviewResponseSchema } from "./adminAlertsSchemas.js";
+/** Bind the existing browser calls without installing an ambient fetch implementation. */
+export function createOperationsClients(requestBff) {
+    return {
+        getAdminSettings(accessToken, options = {}) {
+            return requestBff("/api/bff/admin/platform/settings", adminSettingsReadResponseSchema, {
+                ...options, method: "GET", headers: authHeaders(accessToken, options),
+            });
+        },
+        updateAdminSetting(accessToken, request, options = {}) {
+            return requestBff("/api/bff/admin/platform/settings/update", adminSettingsUpdateResponseSchema, {
+                ...options, method: "POST", headers: authHeaders(accessToken, options), body: request,
+            });
+        },
+        getAdminPipeline(accessToken, options = {}) {
+            return requestBff("/api/bff/admin/platform/pipeline", adminPipelineReadResponseSchema, {
+                ...options, method: "GET", headers: authHeaders(accessToken, options),
+            });
+        },
+        getAdminAlertsOverview(accessToken, options = {}) {
+            return requestBff("/api/bff/admin/platform/alerts", adminAlertsOverviewResponseSchema, {
+                ...options, method: "GET", headers: authHeaders(accessToken, options),
+            });
+        },
+    };
+}
+function authHeaders(accessToken, options) {
+    const headers = new Headers(options.headers);
+    headers.set("Authorization", `Bearer ${accessToken}`);
+    return headers;
+}

package/dist/operations/contracts/admin.d.ts

@@ -0,0 +1,93 @@
+/** 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/dist/operations/contracts/admin.js

@@ -0,0 +1 @@
+export {};

package/dist/operations/contracts/adminAlertsContracts.d.ts

@@ -0,0 +1,40 @@
+/** 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/dist/operations/contracts/adminAlertsContracts.js

@@ -0,0 +1 @@
+export {};

package/dist/operations/contracts/alertHumanContext.d.ts

@@ -0,0 +1,7 @@
+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/dist/operations/contracts/alertHumanContext.js

@@ -0,0 +1 @@
+export {};

package/dist/operations/contracts/index.d.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/dist/operations/contracts/index.js

@@ -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/dist/operations/contracts/observabilityContracts.d.ts

@@ -0,0 +1,41 @@
+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/dist/operations/contracts/observabilityContracts.js

@@ -0,0 +1 @@
+export {};

package/dist/operations/contracts/observabilityPorts.d.ts

@@ -0,0 +1,18 @@
+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/dist/operations/contracts/observabilityPorts.js

@@ -0,0 +1 @@
+export {};

package/dist/operations/contracts/ports.d.ts

@@ -0,0 +1,19 @@
+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/dist/operations/contracts/ports.js

@@ -0,0 +1 @@
+export {};

package/dist/operations/errors.d.ts

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

package/dist/operations/errors.js

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

package/dist/operations/index.d.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/dist/operations/index.js

@@ -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/dist/operations/schemas.d.ts

@@ -0,0 +1,138 @@
+import { z } from "./validation.js";
+export declare const adminPipelineTesterSchema: z.ZodObject<{
+    id: z.ZodString;
+    status: z.ZodString;
+    email_sequence_step: z.ZodNullable<z.ZodNumber>;
+    email_sequence_paused: z.ZodNullable<z.ZodBoolean>;
+}, z.core.$strip>;
+export declare const adminPipelineEmailTemplateSchema: z.ZodObject<{
+    id: z.ZodString;
+    name: z.ZodString;
+    sequence_order: z.ZodNullable<z.ZodNumber>;
+}, z.core.$strip>;
+export declare const adminPipelineEmailEventSchema: z.ZodObject<{
+    event_type: z.ZodString;
+}, z.core.$strip>;
+export declare const adminPipelineReadRequestSchema: z.ZodObject<{}, z.core.$strict>;
+export declare const adminPipelineReadResponseSchema: z.ZodObject<{
+    testers: z.ZodArray<z.ZodObject<{
+        id: z.ZodString;
+        status: z.ZodString;
+        email_sequence_step: z.ZodNullable<z.ZodNumber>;
+        email_sequence_paused: z.ZodNullable<z.ZodBoolean>;
+    }, z.core.$strip>>;
+    templates: z.ZodArray<z.ZodObject<{
+        id: z.ZodString;
+        name: z.ZodString;
+        sequence_order: z.ZodNullable<z.ZodNumber>;
+    }, z.core.$strip>>;
+    emailSendCount: z.ZodNumber;
+    emailEvents: z.ZodArray<z.ZodObject<{
+        event_type: z.ZodString;
+    }, z.core.$strip>>;
+}, z.core.$strip>;
+export declare const adminPipelineDhlTrackingRefreshRequestSchema: z.ZodObject<{}, z.core.$strict>;
+export declare const adminPipelineDhlTrackingRefreshResponseSchema: z.ZodObject<{
+    checked: z.ZodNumber;
+    updated: z.ZodNumber;
+}, z.core.$strip>;
+export declare const adminSettingsReadRequestSchema: z.ZodObject<{}, z.core.$strict>;
+export declare const adminSettingsAdminUserSchema: z.ZodObject<{
+    id: z.ZodString;
+    email: z.ZodNullable<z.ZodString>;
+    role: z.ZodNullable<z.ZodString>;
+}, z.core.$strip>;
+export declare const adminSettingsReadResponseSchema: z.ZodObject<{
+    settings: z.ZodRecord<z.ZodString, z.ZodUnknown>;
+    adminUsers: z.ZodArray<z.ZodObject<{
+        id: z.ZodString;
+        email: z.ZodNullable<z.ZodString>;
+        role: z.ZodNullable<z.ZodString>;
+    }, z.core.$strip>>;
+}, z.core.$strip>;
+export declare const adminSettingWriteValueSchema: z.ZodUnion<readonly [z.ZodString, z.ZodNumber, z.ZodBoolean, z.ZodNull]>;
+export declare const adminSettingsUpdateRequestSchema: z.ZodObject<{
+    key: z.ZodString;
+    value: z.ZodUnion<readonly [z.ZodString, z.ZodNumber, z.ZodBoolean, z.ZodNull]>;
+}, z.core.$strip>;
+export declare const adminSettingsUpdateResponseSchema: z.ZodObject<{
+    key: z.ZodString;
+    saved: z.ZodLiteral<true>;
+}, z.core.$strip>;
+export declare const platformControlPlaneReadRequestSchema: z.ZodObject<{}, z.core.$strict>;
+export declare const platformControlPlaneReadResponseSchema: z.ZodObject<{
+    controls: z.ZodArray<z.ZodObject<{
+        controlKey: z.ZodString;
+        enabled: z.ZodBoolean;
+        revision: z.ZodNumber;
+        updatedAt: z.ZodString;
+    }, z.core.$strip>>;
+    jobs: z.ZodArray<z.ZodObject<{
+        jobName: z.ZodString;
+        enabled: z.ZodBoolean;
+        activeDriver: z.ZodEnum<{
+            operator: "operator";
+            scheduler: "scheduler";
+            worker: "worker";
+        }>;
+        lastStatus: z.ZodNullable<z.ZodEnum<{
+            failed: "failed";
+            skipped: "skipped";
+            success: "success";
+            running: "running";
+        }>>;
+        lastStartedAt: z.ZodNullable<z.ZodString>;
+        lastFinishedAt: z.ZodNullable<z.ZodString>;
+        lastSuccessAt: z.ZodNullable<z.ZodString>;
+    }, z.core.$strip>>;
+    alerts: z.ZodArray<z.ZodObject<{
+        dedupeKey: z.ZodString;
+        severity: z.ZodEnum<{
+            p0: "p0";
+            p1: "p1";
+            p2: "p2";
+            p3: "p3";
+        }>;
+        status: z.ZodEnum<{
+            open: "open";
+            resolved: "resolved";
+            acknowledged: "acknowledged";
+        }>;
+        owner: z.ZodString;
+        title: z.ZodString;
+        firstSeenAt: z.ZodString;
+        lastSeenAt: z.ZodString;
+        resolvedAt: z.ZodNullable<z.ZodString>;
+    }, z.core.$strip>>;
+}, z.core.$strip>;
+export declare const platformControlPlaneMutationSchema: z.ZodUnion<readonly [z.ZodObject<{
+    action: z.ZodLiteral<"set-control">;
+    idempotencyKey: z.ZodString;
+    controlKey: z.ZodString;
+    enabled: z.ZodBoolean;
+}, z.core.$strict>, z.ZodObject<{
+    action: z.ZodLiteral<"record-heartbeat">;
+    idempotencyKey: z.ZodString;
+    health: z.ZodEnum<{
+        failed: "failed";
+        degraded: "degraded";
+        healthy: "healthy";
+    }>;
+    firingCount: z.ZodNumber;
+    maxSeverity: z.ZodNullable<z.ZodEnum<{
+        p0: "p0";
+        p1: "p1";
+        p2: "p2";
+        p3: "p3";
+    }>>;
+    promotionReady: z.ZodBoolean;
+}, z.core.$strict>]>;
+export declare const platformControlPlaneMutationResponseSchema: z.ZodObject<{
+    action: z.ZodEnum<{
+        "set-control": "set-control";
+        "record-heartbeat": "record-heartbeat";
+    }>;
+    replayed: z.ZodBoolean;
+    revision: z.ZodNullable<z.ZodNumber>;
+    recordedAt: z.ZodString;
+}, z.core.$strip>;

package/dist/operations/schemas.js

@@ -0,0 +1,104 @@
+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,
+});

package/dist/operations/server/adminAlertsHandlers.d.ts

@@ -0,0 +1,16 @@
+import { type BffResponderOptions } from "../../bff/index.js";
+import type { HttpRequest, HttpResponse } from "../../http/index.js";
+import type { PlatformAlertLedgerRow, WatchdogHeartbeatRow } from "../index.js";
+import type { OperationsAuthorizationResult } from "../contracts/index.js";
+type AuthorizeAdmin = () => Promise<OperationsAuthorizationResult>;
+export interface AdminAlertsReadPort {
+    listLiveAlerts(): Promise<PlatformAlertLedgerRow[]>;
+    readWatchdogHeartbeat(): Promise<WatchdogHeartbeatRow>;
+}
+export interface AdminAlertsOverviewDeps extends BffResponderOptions {
+    readPort: AdminAlertsReadPort;
+    authorizeAdmin: AuthorizeAdmin;
+    now?: () => Date;
+}
+export declare function createAdminAlertsOverviewHandler({ readPort, authorizeAdmin, now, responseRequestId, }: AdminAlertsOverviewDeps): (req: HttpRequest, res: HttpResponse) => Promise<void>;
+export {};

package/dist/operations/server/adminAlertsHandlers.js

@@ -0,0 +1,35 @@
+import { createBffResponder } from "../../bff/index.js";
+import { adminAlertsOverviewResponseSchema } from "../index.js";
+import { buildAlertsOverview } from "../index.js";
+export function createAdminAlertsOverviewHandler({ readPort, authorizeAdmin, now = () => new Date(), responseRequestId, }) {
+    const { sendBffError, sendBffSuccess, sendMethodNotAllowed } = createBffResponder({ responseRequestId });
+    return async function handler(req, res) {
+        if (req.method !== "GET") {
+            sendMethodNotAllowed(res, ["GET"]);
+            return;
+        }
+        const authorization = await authorizeAdmin();
+        if (authorization.ok === false) {
+            sendBffError(res, authorization.code, authorization.message);
+            return;
+        }
+        try {
+            // Heartbeat and alerts are read together: an empty alert list is only
+            // "healthy" if the watchdog actually reported recently.
+            const [alerts, heartbeat] = await Promise.all([
+                readPort.listLiveAlerts(),
+                readPort.readWatchdogHeartbeat(),
+            ]);
+            const overview = buildAlertsOverview(alerts, heartbeat, now());
+            const response = adminAlertsOverviewResponseSchema.safeParse(overview);
+            if (!response.success) {
+                sendBffError(res, "INVALID_RESPONSE", "Admin alerts overview returned invalid response");
+                return;
+            }
+            sendBffSuccess(res, response.data);
+        }
+        catch {
+            sendBffError(res, "UPSTREAM_UNAVAILABLE", "Admin alerts overview failed");
+        }
+    };
+}

package/dist/operations/server/adminPipelineHandlers.d.ts

@@ -0,0 +1,12 @@
+import { type BffResponderOptions } from "../../bff/index.js";
+import type { HttpRequest, HttpResponse } from "../../http/index.js";
+import type { AdminPipelineReadPort } from "../contracts/index.js";
+import type { OperationsAuthorizationResult } from "../contracts/index.js";
+interface AdminPipelineBaseDeps extends BffResponderOptions {
+    authorizeAdmin: (req: HttpRequest) => Promise<OperationsAuthorizationResult>;
+}
+export interface AdminPipelineReadDeps extends AdminPipelineBaseDeps {
+    pipelinePort: Pick<AdminPipelineReadPort, "readPipeline">;
+}
+export declare function createAdminPipelineReadHandler({ pipelinePort, authorizeAdmin, responseRequestId, }: AdminPipelineReadDeps): (req: HttpRequest, res: HttpResponse) => Promise<void>;
+export {};