XFEServerManager

export type Locale = 'zh-CN' | 'en-US';

export type ConnectionState = 'connecting' | 'online' | 'offline' | 'degraded';

export type Role = 'observer' | 'helper' | 'moderator' | 'administrator' | 'owner';

export interface SessionActor {
  id: string;
  displayName: string;
  roles: Role[];
  permissions: string[];
  totpVerified: boolean;
  totpEnabled?: boolean;
  reauthenticationRequired?: boolean;
}

export interface SessionInfo {
  authenticated: boolean;
  actor?: SessionActor;
  csrfToken?: string;
  bootstrapRequired?: boolean;
  expiresAt?: string;
}

export interface ApiMeta {
  name: string;
  apiVersion: string;
  setupRequired: boolean;
  serverReady: boolean;
}

export interface TotpEnrollment {
  secret: string;
  provisioningUri: string;
  expiresAt: string;
}

export interface TotpConfirmation {
  recoveryCodes: string[];
}

export interface AccountView {
  id: string;
  username: string;
  role: Role;
  totpEnabled: boolean;
  disabled: boolean;
  createdAt: string;
  updatedAt: string;
  lastLoginAt: string | null;
}

export interface MetricSeriesPoint {
  at: string;
  tps?: number;
  mspt?: number;
}

export interface DimensionStatus {
  id: string;
  loadedChunks: number;
  entities: number;
}

export interface ServerStatus {
  sampledAt: string;
  serverName?: string;
  minecraftVersion?: string;
  forgeVersion?: string;
  onlineMode?: boolean;
  uptimeSeconds: number;
  tps?: number;
  mspt?: {
    average?: number;
    p95?: number;
    p99?: number;
    jitter?: number;
  };
  cpuLoad?: number;
  heapUsedBytes?: number;
  heapMaxBytes?: number;
  gcPauseMs?: number;
  diskFreeBytes?: number;
  playersOnline: number;
  playersMax?: number;
  averagePingMs?: number;
  dimensions?: DimensionStatus[];
  samples?: MetricSeriesPoint[];
}

export interface PlayerLocation {
  dimension: string;
  x: number;
  y: number;
  z: number;
}

export interface PlayerSummary {
  uuid: string;
  name: string;
  online: boolean;
  pingMs?: number;
  opLevel?: number;
  roles?: Role[];
  gameMode?: string;
  health?: number;
  foodLevel?: number;
  location?: PlayerLocation;
  connectedAt?: string;
}

export type PlayerContainer = 'inventory' | 'ender-chest';

export interface InventorySlot {
  slot: number;
  itemId: string;
  count: number;
  structuredData: Record<string, string>;
  opaqueDataPresent: boolean;
  opaqueDataFingerprint: string;
}

export interface InventorySnapshot {
  playerUuid: string;
  container: 'inventory' | 'ender_chest';
  revision: number;
  online: boolean;
  slots: InventorySlot[];
}

export interface InventorySlotDiff {
  slot: number;
  before: InventorySlot;
  after: InventorySlot;
}

export interface InventoryUpdateResult extends OperationStatus {
  revision: number;
  diffs: InventorySlotDiff[];
}

export type PolicyEffect = 'PASS_THROUGH' | 'DENY' | 'GRANT' | 'CONSTRAIN';
export type PolicyState = 'DRAFT' | 'ACTIVE' | 'ARCHIVED';

export interface CommandPolicySummary {
  id: string;
  version: number;
  name: string;
  description?: string;
  state: PolicyState;
  effect?: PolicyEffect;
  ruleCount: number;
  groupCount?: number;
  updatedAt: string;
  updatedBy?: string;
}

export interface PolicyValidation {
  valid: boolean;
  errors: Array<string | { ruleId?: string; code?: string; message: string }>;
  warnings: Array<string | { ruleId?: string; code?: string; message: string }>;
}

export type PolicyCommandSource = 'server' | 'trigger';

/** A command that can be selected by a command-policy rule. */
export interface PolicyCommandCatalogEntry {
  /** Canonical policy identifier, for example `minecraft:kill` or a trigger command id. */
  id: string;
  /** Root literal as registered in Brigadier, without a leading slash. */
  root: string;
  usages: string[];
  aliases?: string[];
  source: PolicyCommandSource;
  triggerId?: string;
  triggerName?: string;
  arguments?: string[];
}

export interface PolicyCommandCatalog {
  commands: PolicyCommandCatalogEntry[];
}

export type PolicyRuleTier = 'DEFAULT' | 'OP_LEVEL' | 'ROLE' | 'UUID' | 'HARD_SAFETY';
export type PolicySourceKind = 'PLAYER' | 'CONSOLE' | 'COMMAND_BLOCK' | 'FUNCTION' | 'SCHEDULED_FUNCTION' | 'WEB_CONSOLE' | 'SYSTEM' | 'UNKNOWN';
export type PolicySelectorType = 'SELF' | 'NEAREST_PLAYER' | 'RANDOM_PLAYER' | 'ALL_PLAYERS' | 'ALL_ENTITIES' | 'DIRECT' | 'UNKNOWN';
export type PolicySelectorSort = 'NEAREST' | 'FURTHEST' | 'RANDOM' | 'ARBITRARY' | 'UNSPECIFIED';

export interface CommandPolicyRule {
  id: string;
  enabled: boolean;
  groupId: string;
  groupName: string;
  groupEnabled: boolean;
  tier: PolicyRuleTier;
  subject: {
    actorIds: string[];
    roles: string[];
    minimumOpLevel: number | null;
    maximumOpLevel: number | null;
    sources: PolicySourceKind[];
    onlineMode: boolean | null;
  };
  command: { commandIds: string[]; pathPrefix: string[] };
  effect: PolicyEffect;
  constraints: {
    selector: {
      deniedSelectorTypes: PolicySelectorType[];
      deniedSorts: PolicySelectorSort[];
      allowBroadSelectorWithExplicitType: boolean;
      maximumTargets: number | null;
      maximumDistance: number | null;
      allowedEntityTypes: string[];
      deniedEntityTypes: string[];
      allowTagFilters: boolean;
      allowNbtFilters: boolean;
      allowPredicateFilters: boolean;
    };
    item: {
      allowedItemIds: string[];
      deniedItemIds: string[];
      allowedItemTags: string[];
      deniedItemTags: string[];
      maximumCount: number | null;
      allowedDataKeys: string[];
      deniedDataKeys: string[];
    };
    allowedFunctionIds: string[];
    denyUnlistedFunctions: boolean;
  };
  reason: string;
}

export interface CommandPolicyDetail extends CommandPolicySummary {
  checksum: string;
  rules: CommandPolicyRule[];
  validation: PolicyValidation;
}

export interface PolicySimulation {
  decision: PolicyEffect;
  explanation: string[];
  matchedRuleIds?: string[];
  normalizedCommand?: string;
}

export interface AuditEvent {
  id: string;
  at: string;
  actor: string;
  source: string;
  action: string;
  target?: string;
  reason?: string;
  result: 'SUCCESS' | 'DENIED' | 'FAILED' | 'PARTIAL' | string;
  durationMs?: number;
  requestId?: string;
}

export interface ModerationCase {
  id: string;
  playerUuid: string;
  playerName?: string;
  type: 'WARN' | 'MUTE' | 'KICK' | 'TEMPBAN' | 'BAN' | string;
  state: 'ACTIVE' | 'EXPIRED' | 'REVOKED' | string;
  reason: string;
  message?: string;
  remainingSeconds?: number;
  createdAt: string;
  expiresAt?: string;
  actor: string;
  history?: Array<{
    id: string;
    type: string;
    reason: string;
    message?: string;
    issuedBy: string;
    issuedAt: string;
    expiresAt?: string;
    revokedBy?: string;
    revokedAt?: string;
  }>;
}

export interface MaintenanceSchedule {
  id: string;
  kind: string;
  executeAt: string;
  status: string;
  attempts: number;
  lastError?: string;
  createdBy: string;
}

export interface MaintenanceState {
  enabled: boolean;
  message: string;
  defaultMessageSender: string;
  allowedPlayers: string[];
  revision: number;
  schedules: MaintenanceSchedule[];
}

export interface ClaimSummary {
  id: string;
  name?: string;
  dimension: string;
  ownerUuid: string;
  ownerName?: string;
  chunks: Array<{ x: number; z: number }>;
  members: Record<string, 'manager' | 'member' | 'trusted'>;
  flags: Record<string, boolean>;
  revision: number;
  updatedAt?: string;
}

export interface WorldChangeSummary {
  id: string;
  at: string;
  actor?: string;
  action: string;
  resourceId?: string;
  dimension: string;
  x: number;
  y: number;
  z: number;
  transactionId?: string;
}

export interface RollbackPreview {
  id: string;
  watermark: number;
  confirmationToken: string;
  expiresAt?: string;
  matched: number;
  applicable: number;
  conflicts: number;
  unloadedChunks: number;
  gaps: number;
  incompatible: number;
}

export interface OperationStatus {
  id: string;
  kind: string;
  state: 'QUEUED' | 'RUNNING' | 'SUCCEEDED' | 'FAILED' | 'CANCELLED' | string;
  progress?: number;
  message?: string;
  createdAt?: string;
  completedAt?: string;
  expiresAt?: string;
  previewToken?: string;
  targets?: Array<{ uuid: string; name?: string }>;
  policy?: CommandPolicySummary;
  restartRequired?: boolean;
}

export interface FeatureFlags {
  consoleEnabled: boolean;
  moderationEnabled: boolean;
  claimsEnabled: boolean;
  worldTrackingEnabled: boolean;
  rollbackEnabled: boolean;
  joinExperienceEnabled?: boolean;
  metricsEnabled?: boolean;
}

export interface ServerSettings {
  bindAddress: string;
  port: number;
  publicBaseUrl: string;
  trustedProxyCidrs: string[];
  idleSessionSeconds: number;
  absoluteSessionSeconds: number;
  recentAuthenticationSeconds: number;
  httpThreads: number;
  maximumSseClients: number;
  webConsoleEnabled: boolean;
  rawItemEditingEnabled: boolean;
  metricsEnabled: boolean;
  moderationEnabled: boolean;
  claimsEnabled: boolean;
  worldTrackingEnabled: boolean;
  rollbackEnabled: boolean;
  joinExperienceEnabled: boolean;
  defaultMessageSender: string;
  joinWelcomeEnabled: boolean;
  joinWelcomeMessage: string;
  firstJoinMessageEnabled: boolean;
  firstJoinMessage: string;
  dailyAnnouncementsEnabled: boolean;
  dailyAnnouncements: string[];
  announcementTimeZone: string;
  rulesReminderEnabled: boolean;
  rulesMessage: string;
  maintenanceJoinReminderEnabled: boolean;
  crashProtection: CrashProtectionSettings;
  restartRequired?: boolean;
  features: FeatureFlags;
  serverLocale?: Locale;
  metricsRequireToken?: boolean;
  blueMapDetected?: boolean;
  sparkDetected?: boolean;
  offlineMode?: boolean;
}

export interface CrashProtectionSettings {
  enabled: boolean;
  scanIntervalTicks: number;
  itemEntitiesPerDimension: number;
  itemEntitiesPerChunk: number;
  livingEntitiesPerDimension: number;
  livingEntitiesPerChunk: number;
  totalEntitiesPerDimension: number;
  totalEntitiesPerChunk: number;
  entitiesPerNamespacePerDimension: number;
  loadedChunksPerDimension: number;
  spawnBurstLimit: number;
  spawnBurstWindowTicks: number;
  commandBlockCommandsPerSecond: number;
  slowTickMillis: number;
  consecutiveSlowTicks: number;
  heapUsagePercent: number;
  blockExcessSpawns: boolean;
  removeExcessItems: boolean;
  stopRunawayCommandBlocks: boolean;
}

export type TriggerMode = 'visual' | 'code';
export type TriggerConditionMode = 'all' | 'any';

export interface TriggerEventSpec {
  type: string;
  configuration: Record<string, string>;
  /** Typed Brigadier alternatives. Legacy servers may omit this and use configuration.arguments. */
  arguments?: TriggerCommandArgument[];
  /** Trigger-owned strongly typed state, exposed as var.<name>. */
  variables?: TriggerStateVariableDefinition[];
}

export interface TriggerCommandArgument {
  name: string;
  type: string;
  literal: string;
  optional: boolean;
  errorMessage: string;
  minimum: string;
  maximum: string;
  suggestions: string[];
  children: TriggerCommandArgument[];
}

export interface TriggerStateVariableDefinition {
  name: string;
  type: string;
  initialValue: string;
  /** Omitted by legacy definitions and therefore treated as trigger-local. */
  visibility?: 'trigger' | 'global';
  /** Omitted by legacy definitions and therefore stored against the declaring trigger. */
  storage?: 'server' | 'player' | 'dimension' | 'trigger';
}

export interface TriggerVariableValues {
  triggerId: string;
  values: Record<string, unknown>;
  observedAt: string;
}

export interface TriggerCondition {
  field: string;
  operator: string;
  value: string;
}

export interface TriggerAction {
  type: string;
  parameters: Record<string, string>;
  /** Only structural condition actions contain children; omitted by legacy persisted actions. */
  children?: TriggerAction[];
}

export interface TriggerProgram {
  event: TriggerEventSpec;
  conditionMode: TriggerConditionMode;
  conditions: TriggerCondition[];
  actions: TriggerAction[];
}

export interface TriggerValidation extends TriggerProgram {
  valid: boolean;
}

export interface TriggerDefinition {
  id: string;
  groupId: string;
  name: string;
  description: string;
  enabled: boolean;
  mode: TriggerMode;
  event: TriggerEventSpec;
  conditionMode: TriggerConditionMode;
  conditions: TriggerCondition[];
  actions: TriggerAction[];
  script: string;
  revision: number;
  createdBy: string;
  createdAt: string;
  updatedAt: string;
  migrated: boolean;
}

export interface TriggerGroup {
  id: string;
  name: string;
  description: string;
  enabled: boolean;
  revision: number;
  createdBy: string;
  createdAt: string;
  updatedAt: string;
  migrated: boolean;
  triggers: TriggerDefinition[];
}

export interface TriggerWorkspace {
  groups: TriggerGroup[];
  totalTriggers: number;
}

export interface TriggerVariableDefinition {
  /** Variable expression without the surrounding braces. */
  key: string;
  nameZh: string;
  nameEn: string;
  descriptionZh: string;
  descriptionEn: string;
  category: string;
  /** Availability scopes such as global, player-event, schedule, or an exact event type. */
  scopes: string[];
  example?: string;
  sampleValue?: string;
  formatHint?: string;
  /** Optional value metadata supplied by newer servers. */
  type?: string;
  events?: string[];
  templateAllowed?: boolean;
  conditionAllowed?: boolean;
  sensitive?: boolean;
}

export interface TriggerCatalog {
  defaultMessageSender: string;
  events: string[];
  operators: string[];
  actions: string[];
  actionParameters: Record<string, string[]>;
  commandArgumentTypes?: string[];
  triggerVariableTypes?: string[];
  /** Omitted by older servers; clients retain the legacy four-variable fallback. */
  variables?: TriggerVariableDefinition[];
}

export interface MenuControlEvent {
  event: 'click' | 'double_click' | 'change' | 'submit' | 'toggle' | 'hover' | 'focus' | 'blur';
  triggerId: string;
  submenuId: string;
  closeMenu: boolean;
}

export interface MenuControl {
  id: string;
  type: 'text' | 'rich_text' | 'button' | 'icon_button' | 'image' | 'panel' | 'border'
    | 'progress' | 'input' | 'checkbox' | 'slider' | 'item_slot' | 'separator' | 'spacer';
  x: number;
  y: number;
  width: number;
  height: number;
  zIndex: number;
  visibleWhen: string;
  properties: Record<string, string>;
  events: MenuControlEvent[];
}

export interface MenuDefinition {
  id: string;
  name: string;
  description: string;
  width: number;
  height: number;
  popupPosition: 'center' | 'top' | 'bottom' | 'left' | 'right' | 'top_left' | 'top_right'
    | 'bottom_left' | 'bottom_right' | 'custom';
  offsetX: number;
  offsetY: number;
  pauseGame: boolean;
  backgroundColor: string;
  controls: MenuControl[];
  revision: number;
  createdBy: string;
  createdAt: string;
  updatedAt: string;
}

export interface MenuWorkspace {
  menus: MenuDefinition[];
  totalMenus: number;
}

export interface MenuCatalogTrigger {
  id: string;
  name: string;
  enabled: boolean;
}

export interface MenuCatalog {
  controlTypes: MenuControl['type'][];
  popupPositions: MenuDefinition['popupPosition'][];
  controlEvents: MenuControlEvent['event'][];
  triggers: MenuCatalogTrigger[];
}

export interface MenuImageCatalogItem {
  id?: string;
  reference: string;
  name: string;
  type: 'uploaded' | 'texture' | 'item' | 'block';
  source: string;
  mimeType?: string;
  width?: number;
  height?: number;
  sha256?: string;
  dataUrl?: string;
}

export interface CurrencyDefinition {
  id: string;
  code: string;
  name: string;
  symbol: string;
  icon: string;
  fractionDigits: number;
  initialBalance: string;
  minimumBalance: string;
  maximumBalance: string;
  playerTransferAllowed: boolean;
  enabled: boolean;
  primary: boolean;
  revision: number;
  createdBy: string;
  createdAt: string;
  updatedAt: string;
}

export interface EconomyBalance {
  currencyId: string;
  currencyCode: string;
  currencyName: string;
  symbol: string;
  icon: string;
  fractionDigits: number;
  amount: string;
  revision: number;
  currencyEnabled: boolean;
  updatedAt: string;
}

export interface EconomyAccount {
  playerId: string;
  playerName: string;
  balances: EconomyBalance[];
  updatedAt: string;
}

export interface EconomyTransaction {
  id: string;
  currencyId: string;
  currencyCode: string;
  kind: 'initial' | 'deposit' | 'withdraw' | 'set' | 'transfer';
  sourcePlayerId?: string;
  sourcePlayerName: string;
  targetPlayerId?: string;
  targetPlayerName: string;
  amount: string;
  sourceBalanceBefore: string;
  sourceBalanceAfter: string;
  targetBalanceBefore: string;
  targetBalanceAfter: string;
  reason: string;
  actor: string;
  origin: string;
  correlationId: string;
  createdAt: string;
}

export interface EconomyCurrencySummary {
  currencyId: string;
  code: string;
  name: string;
  symbol: string;
  icon: string;
  fractionDigits: number;
  enabled: boolean;
  primary: boolean;
  accountCount: number;
  totalSupply: string;
  minimumBalance: string;
  maximumBalance: string;
  transactionCount: number;
  transferVolume24h: string;
}

export interface EconomyOverview {
  currencies: EconomyCurrencySummary[];
  observedAt: string;
}

export interface EconomyWorkspace {
  currencies: CurrencyDefinition[];
  overview: EconomyOverview;
}

export interface EconomyChange {
  currency: CurrencyDefinition;
  transaction: EconomyTransaction;
  sourceBalance?: EconomyBalance;
  targetBalance?: EconomyBalance;
}

export interface PageResult<T> {
  items: T[];
  nextCursor?: string;
  total?: number;
}

export interface ApiProblem {
  type?: string;
  title: string;
  status: number;
  detail?: string;
  instance?: string;
  requestId?: string;
  errors?: Record<string, string[]>;
}

export interface StreamEvent<T = unknown> {
  type: string;
  id?: string;
  at?: string;
  data: T;
}