@openlup/platform 0.28.0 → 0.30.0

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,
+});

package/src/operations/server/adminAlertsHandlers.ts

@@ -0,0 +1,61 @@
+import { createBffResponder, type BffResponderOptions } from "../../bff/index.js";
+import type { HttpRequest, HttpResponse } from "../../http/index.js";
+import { adminAlertsOverviewResponseSchema } from "../index.js";
+import { buildAlertsOverview } from "../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 function createAdminAlertsOverviewHandler({
+  readPort,
+  authorizeAdmin,
+  now = () => new Date(), responseRequestId,
+}: AdminAlertsOverviewDeps) {
+  const { sendBffError, sendBffSuccess, sendMethodNotAllowed } = createBffResponder({ responseRequestId });
+  return async function handler(req: HttpRequest, res: HttpResponse): Promise<void> {
+    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/src/operations/server/adminPipelineHandlers.ts

@@ -0,0 +1,73 @@
+import { createBffResponder, type BffResponderOptions, type BffResponder } from "../../bff/index.js";
+import type { HttpRequest, HttpResponse } from "../../http/index.js";
+import {
+  adminPipelineReadRequestSchema,
+  adminPipelineReadResponseSchema,
+} from "../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 function createAdminPipelineReadHandler({
+  pipelinePort,
+  authorizeAdmin, responseRequestId,
+}: AdminPipelineReadDeps) {
+  const responder = createBffResponder({ responseRequestId });
+  const { sendBffError, sendBffSuccess, sendMethodNotAllowed } = responder;
+  return async function handler(req: HttpRequest, res: HttpResponse): Promise<void> {
+    if (req.method !== "GET") {
+      sendMethodNotAllowed(res, ["GET"]);
+      return;
+    }
+
+    const authorization = await readAuthorization(req, res, authorizeAdmin, responder);
+    if (!authorization) return;
+
+    const request = adminPipelineReadRequestSchema.safeParse(req.query);
+    if (!request.success) {
+      sendBffError(res, "BAD_REQUEST", "Invalid admin pipeline read request", {
+        details: request.error.flatten(),
+      });
+      return;
+    }
+
+    try {
+      const result = await pipelinePort.readPipeline(request.data);
+      const response = adminPipelineReadResponseSchema.safeParse(result);
+      if (!response.success) {
+        sendBffError(res, "INVALID_RESPONSE", "Admin pipeline read returned invalid response");
+        return;
+      }
+
+      sendBffSuccess(res, response.data);
+    } catch {
+      sendBffError(res, "UPSTREAM_UNAVAILABLE", "Admin pipeline read failed");
+    }
+  };
+}
+
+async function readAuthorization(
+  req: HttpRequest,
+  res: HttpResponse,
+  authorizeAdmin: (req: HttpRequest) => Promise<OperationsAuthorizationResult>,
+  { sendBffError }: BffResponder,
+): Promise<true | null> {
+  try {
+    const authorization = await authorizeAdmin(req);
+    if (authorization.ok === false) {
+      sendBffError(res, authorization.code, authorization.message);
+      return null;
+    }
+    return true;
+  } catch {
+    sendBffError(res, "UPSTREAM_UNAVAILABLE", "Admin authorization failed");
+    return null;
+  }
+}

package/src/operations/server/adminSettingsHandlers.ts

@@ -0,0 +1,114 @@
+import { createBffResponder, type BffResponderOptions } from "../../bff/index.js";
+import type { HttpRequest, HttpResponse } from "../../http/index.js";
+import {
+  adminSettingsReadRequestSchema,
+  adminSettingsReadResponseSchema,
+  adminSettingsUpdateRequestSchema,
+  adminSettingsUpdateResponseSchema,
+} from "../index.js";
+import type { AdminSettingsOperationsPort } from "../contracts/index.js";
+import type { OperationsAuthorizationResult } from "../contracts/index.js";
+
+export interface AdminSettingsReadDeps extends BffResponderOptions {
+  settingsPort: Pick<AdminSettingsOperationsPort, "readSettings">;
+  authorizeAdmin: (req: HttpRequest) => Promise<OperationsAuthorizationResult>;
+}
+
+export interface AdminSettingsUpdateDeps extends BffResponderOptions {
+  settingsPort: Pick<AdminSettingsOperationsPort, "updateSetting">;
+  authorizeAdmin: (req: HttpRequest) => Promise<OperationsAuthorizationResult>;
+}
+
+export function createAdminSettingsReadHandler({
+  settingsPort,
+  authorizeAdmin, responseRequestId,
+}: AdminSettingsReadDeps) {
+  const { sendBffError, sendBffSuccess, sendMethodNotAllowed } = createBffResponder({ responseRequestId });
+  return async function handler(req: HttpRequest, res: HttpResponse): Promise<void> {
+    if (req.method !== "GET") {
+      sendMethodNotAllowed(res, ["GET"]);
+      return;
+    }
+
+    let authorization: OperationsAuthorizationResult;
+    try {
+      authorization = await authorizeAdmin(req);
+    } catch {
+      sendBffError(res, "UPSTREAM_UNAVAILABLE", "Admin authorization failed");
+      return;
+    }
+
+    if (authorization.ok === false) {
+      sendBffError(res, authorization.code, authorization.message);
+      return;
+    }
+
+    const request = adminSettingsReadRequestSchema.safeParse(req.query);
+    if (!request.success) {
+      sendBffError(res, "BAD_REQUEST", "Invalid admin settings read request", {
+        details: request.error.flatten(),
+      });
+      return;
+    }
+
+    try {
+      const result = await settingsPort.readSettings(request.data);
+      const response = adminSettingsReadResponseSchema.safeParse(result);
+      if (!response.success) {
+        sendBffError(res, "INVALID_RESPONSE", "Admin settings read returned invalid response");
+        return;
+      }
+
+      sendBffSuccess(res, response.data);
+    } catch {
+      sendBffError(res, "UPSTREAM_UNAVAILABLE", "Admin settings read failed");
+    }
+  };
+}
+
+export function createAdminSettingsUpdateHandler({
+  settingsPort,
+  authorizeAdmin, responseRequestId,
+}: AdminSettingsUpdateDeps) {
+  const { sendBffError, sendBffSuccess, sendMethodNotAllowed } = createBffResponder({ responseRequestId });
+  return async function handler(req: HttpRequest, res: HttpResponse): Promise<void> {
+    if (req.method !== "POST") {
+      sendMethodNotAllowed(res, ["POST"]);
+      return;
+    }
+
+    let authorization: OperationsAuthorizationResult;
+    try {
+      authorization = await authorizeAdmin(req);
+    } catch {
+      sendBffError(res, "UPSTREAM_UNAVAILABLE", "Admin authorization failed");
+      return;
+    }
+
+    if (authorization.ok === false) {
+      sendBffError(res, authorization.code, authorization.message);
+      return;
+    }
+
+    const request = adminSettingsUpdateRequestSchema.safeParse(req.body);
+    if (!request.success) {
+      sendBffError(res, "BAD_REQUEST", "Invalid admin settings update request", {
+        details: request.error.flatten(),
+      });
+      return;
+    }
+
+    try {
+      const result = await settingsPort.updateSetting(request.data);
+      const response = adminSettingsUpdateResponseSchema.safeParse(result);
+      if (!response.success) {
+        sendBffError(res, "INVALID_RESPONSE", "Admin settings update returned invalid response");
+        return;
+      }
+
+      sendBffSuccess(res, response.data);
+    } catch {
+      sendBffError(res, "UPSTREAM_UNAVAILABLE", "Admin settings update failed");
+    }
+  };
+}