Skip to content

Evenfire is an intelligence layer platform for running LLM agents that take real actions, on your infrastructure

TypeScript
154 KB
Raw Blame
'use client'

import {
  CONTROL_UI_SESSION_INVALIDATION_EVENT,
  METADATA_READ_CACHE_MAX_ENTRIES,
  METADATA_READ_TTL_MS,
} from '@constants/readRequests'
import type { ApiRequestError, ApiRequestOptions } from './api.types'
import type { GenericDiscoveryPrefill } from './oauthGeneric.types'
import type {
  McpSecretSummary,
  OAuthCallbackConfig,
  OAuthCredentialManifest,
  OAuthInstallSubmit,
} from './oauthInstall.types'
import {
  clearReadRequestPrincipal,
  completeReadRequestRecovery,
  getReadRequestCacheEntry,
  getReadRequestCacheGeneration,
  getReadRequestCooldown,
  getReadRequestPrincipal,
  getReadRequestRecovery,
  invalidateReadRequestCacheEntry,
  joinReadRequestRecovery,
  reserveReadRequestRecovery,
  setReadRequestCacheEntry,
  setReadRequestCooldown,
  setReadRequestInvalidationHandler,
  setReadRequestPrincipal,
} from './readRequestCache'
import {
  DEFAULT_MCP_SERVER_SECRET_NAMESPACE,
  DEFAULT_SANDBOX_SECRET_NAMESPACE,
  type RecipeSecretNamespaces,
} from './recipeSecretNamespaces'

export type AnyRecord = Record<string, unknown>

export type SecretIdentity = {
  uid: string
  resourceVersion: string
}

function readSecretIdentity(raw: unknown, operation: string): SecretIdentity | undefined {
  const value = (raw ?? {}) as {
    name?: unknown
    namespace?: unknown
    uid?: unknown
    resourceVersion?: unknown
  }
  const hasUid = value.uid !== undefined
  const hasResourceVersion = value.resourceVersion !== undefined
  if (!hasUid && !hasResourceVersion) return undefined
  if (
    typeof value.uid !== 'string' ||
    !value.uid.trim() ||
    typeof value.resourceVersion !== 'string' ||
    !value.resourceVersion.trim()
  ) {
    // This error is the operator's only pointer to the object that now needs
    // manual repair: the Secret WAS created, but without a complete CAS
    // identity the UI refuses to roll it back. Name it so "repair" is actionable.
    const subject =
      typeof value.name === 'string' && value.name
        ? ` for Secret "${value.name}"${
            typeof value.namespace === 'string' && value.namespace ? ` in ${value.namespace}` : ''
          }`
        : ''
    throw new Error(
      `${operation} returned an incomplete Secret identity${subject}; repair is required`
    )
  }
  return { uid: value.uid, resourceVersion: value.resourceVersion }
}

const SECRET_ERROR_MESSAGES: Record<string, string> = {
  secret_identity_precondition_required:
    'A current Secret identity is required before it can be deleted. Refresh the page and review the latest state before taking further action.',
  secret_identity_unavailable:
    'The server could not verify the current Secret identity. Refresh the page and review the Secret before taking further action.',
  secret_identity_changed:
    'This Secret changed since it was loaded. Refresh the page and review the latest state before taking further action.',
  mcp_secret_in_use:
    'This Secret is still in use by one or more connectors. Remove or update its references before deleting it.',
  mcp_secret_reference_check_unavailable:
    'The server could not verify whether this Secret is in use. Refresh the page and review its references before taking further action.',
}

// Global error handler for 401s - managed by AuthContext
let globalHandleAuthError: (() => void) | null = null

export function setGlobalAuthErrorHandler(handler: () => void) {
  globalHandleAuthError = handler
}

function getGlobalAuthErrorHandler() {
  return globalHandleAuthError
}

export class AuthExpiredError extends Error {
  status = 401
  silent = true

  constructor() {
    super('Session expired')
    this.name = 'AuthExpiredError'
  }
}

export function isSilentApiError(error: unknown): boolean {
  return Boolean(error && typeof error === 'object' && (error as { silent?: unknown }).silent)
}

/** Route non-JSON authenticated transports through the same session-expiry handler as API calls. */
export function handleControlUIUnauthorized(): void {
  clearAdminAuthToken()
  getGlobalAuthErrorHandler()?.()
}

function handleUnauthorized(): never {
  handleControlUIUnauthorized()
  throw new AuthExpiredError()
}

export type Metadata = {
  name?: string
  namespace?: string
  labels?: Record<string, string>
  annotations?: Record<string, string>
  /**
   * Server-assigned version of the read. Carried back on save as the AP-6
   * optimistic-concurrency precondition (docs/architecture/stateless-invariants.md).
   */
  resourceVersion?: string
  generation?: number
  /** K8s-standard creation timestamp (RFC3339). Not in the type for older
   *  endpoints but carried by the new admin payloads. */
  creationTimestamp?: string
  /** K8s-standard resource UID. Same caveat as creationTimestamp. */
  uid?: string
}

const API_BASE = process.env.NEXT_PUBLIC_CONTROL_API_BASE_URL || '/control-api'
const ADMIN_TOKEN_STORAGE_KEY = 'controlUiAdminToken'
const API_REQUEST_TIMEOUT_MS = 30000
// Legacy JSON GFS uploads send file bytes base64-encoded inside a request body. The
// v2 path uses binary indexed parts and does not use this timeout/body contract;
// this constant remains only for the compatibility helper and old API callers.
export const GFS_UPLOAD_TIMEOUT_MS = 300000
const inFlightGetRequests = new Map<string, Promise<unknown>>()
type SharedMetadataRead = {
  promise: Promise<unknown>
  controller: AbortController
  consumers: Set<{ signal?: AbortSignal }>
  settled: boolean
}
const inFlightMetadataReads = new Map<string, SharedMetadataRead>()
const activeGetControllers = new Set<AbortController>()
let sessionEpoch = 0

setReadRequestInvalidationHandler(abortActiveGetRequests)

function qs(params: Record<string, string | undefined>) {
  const search = new URLSearchParams()
  Object.entries(params).forEach(([k, v]) => {
    if (v !== undefined && v !== '') search.set(k, v)
  })
  const value = search.toString()
  return value ? `?${value}` : ''
}

function authHeaders(): HeadersInit {
  return {}
}

/** Build a Control API URL using the same configured base as API requests. */
export function controlApiUrl(path: string): string {
  return `${API_BASE}${path}`
}

export function retryAfterSeconds(
  headers: Headers,
  body: Record<string, unknown> | null,
  nowMs = Date.now()
): number | undefined {
  const raw = headers.get('retry-after')?.trim()
  if (raw && /^\d+$/.test(raw)) {
    const seconds = Number(raw)
    if (Number.isSafeInteger(seconds) && seconds > 0) return seconds
  }
  if (raw) {
    const at = Date.parse(raw)
    if (Number.isFinite(at) && at > nowMs) return Math.ceil((at - nowMs) / 1000)
  }
  const seconds = body?.retryAfterSeconds
  return typeof seconds === 'number' && Number.isSafeInteger(seconds) && seconds > 0
    ? seconds
    : undefined
}

async function parseJsonResponse(res: Response): Promise<unknown> {
  const text = await res.text()
  if (!text.trim()) return undefined
  return JSON.parse(text)
}

export function formatApiError(res: Response, text: string): Error {
  let detail: string
  let parsedBody: Record<string, unknown> | null = null
  try {
    const parsed = JSON.parse(text) as { error?: unknown; message?: unknown }
    if (parsed && typeof parsed === 'object') parsedBody = parsed as Record<string, unknown>
    const nestedError =
      parsed.error && typeof parsed.error === 'object'
        ? (parsed.error as Record<string, unknown>)
        : null
    detail =
      (typeof parsed.message === 'string' && parsed.message) ||
      (typeof nestedError?.message === 'string' && nestedError.message) ||
      (typeof parsed.error === 'string' && parsed.error) ||
      text
  } catch {
    detail = text
  }
  const errorCode = typeof parsedBody?.error === 'string' ? parsedBody.error : undefined
  const friendlyDetail =
    (errorCode ? SECRET_ERROR_MESSAGES[errorCode] : undefined) ??
    (detail === 'duplicate_username'
      ? 'That username is already taken.'
      : detail === 'duplicate_email'
        ? 'That email is already registered.'
        : detail === 'invalid_invitation'
          ? 'This admin invitation is invalid or expired.'
          : detail === 'member password must be between 8 and 256 characters'
            ? 'Desktop App password must be between 8 and 256 characters.'
            : detail === 'password must be between 8 and 256 characters'
              ? 'Password must be between 8 and 256 characters.'
              : detail === 'precondition_failed'
                ? 'This item changed since it was loaded. Reload the page, review the latest state, and try again.'
                : detail === 'agent_grant_precondition_required'
                  ? 'Agent access could not be updated because the page did not include its current access state. Reload the page and try again.'
                  : detail === 'deleted_agent_history_limit_exceeded'
                    ? 'Agent access was not updated because the deleted-agent history limit was reached. No existing history was removed. Reload the page, review the current access, and try again.'
                    : // Exact match is correct HERE: control-ui calls control-api directly,
                      // so a member-registration 503 arrives as the bare { error: '<code>' }
                      // body. profile-ui reaches these same codes through external-rest-api,
                      // whose error middleware wraps any 5xx into { message: '...: <code>' },
                      // so it must use .includes() instead — the two matchers differ on purpose.
                      detail === 'member_registration_unavailable'
                      ? "Invitations are unavailable — the member-registration service isn't configured or can't be reached. Check the server logs for details."
                      : detail === 'member_registration_misconfigured'
                        ? 'Invitations are unavailable — member registration is misconfigured. Check the server logs for details.'
                        : detail)
  const hasServerMessage =
    typeof parsedBody?.message === 'string' && Boolean(parsedBody.message.trim())
  const throttleSeconds =
    res.status === 429 ? retryAfterSeconds(res.headers, parsedBody) : undefined
  let throttleDetail: string
  if (res.status === 429) {
    throttleDetail = hasServerMessage
      ? friendlyDetail
      : throttleSeconds !== undefined
        ? `Too many requests. Try again in ${throttleSeconds} seconds.`
        : 'Too many requests. Try again later.'
  } else {
    throttleDetail = `${res.status} ${res.statusText} - ${friendlyDetail}`
  }
  const error = new Error(throttleDetail) as ApiRequestError
  error.status = res.status
  // Preserve the machine-readable error code and full JSON body so callers can
  // render structured, actionable errors (e.g. unpriced_models, price_in_use_by_budget)
  // instead of the generic message string.
  if (parsedBody) {
    const nestedError =
      parsedBody.error && typeof parsedBody.error === 'object'
        ? (parsedBody.error as Record<string, unknown>)
        : null
    error.code =
      typeof parsedBody.code === 'string'
        ? parsedBody.code
        : typeof parsedBody.error === 'string'
          ? parsedBody.error
          : typeof nestedError?.code === 'string'
            ? nestedError.code
            : undefined
    error.body = parsedBody
  }
  if (throttleSeconds !== undefined) {
    error.retryAfterSeconds = throttleSeconds
    error.retryAtMs = Date.now() + throttleSeconds * 1000
  }
  return error
}

function abortActiveGetRequests(remote = false): void {
  sessionEpoch += 1
  for (const controller of activeGetControllers) controller.abort()
  activeGetControllers.clear()
  inFlightGetRequests.clear()
  inFlightMetadataReads.clear()
  if (remote && typeof window !== 'undefined') {
    window.dispatchEvent(new Event(CONTROL_UI_SESSION_INVALIDATION_EVENT))
  }
}

function readPrincipalKey(): string | null {
  const current = getReadRequestPrincipal()
  return current ? JSON.stringify([current.principalId, current.scope]) : null
}

function sameReadContext(epoch: number, principalContext: string | null): boolean {
  if (typeof window === 'undefined') return true
  return epoch === sessionEpoch && readPrincipalKey() === principalContext
}

function readRequestCacheKey(url: string, epoch: number): string | null {
  if (typeof window === 'undefined') return null
  const principalContext = getReadRequestPrincipal()
  if (!principalContext) return null
  const absoluteUrl = new URL(url, window.location.origin).href
  return JSON.stringify([absoluteUrl, epoch, principalContext.principalId, principalContext.scope])
}

function waitForRead<T>(request: Promise<T>, signal?: AbortSignal): Promise<T> {
  if (!signal) return request
  if (signal.aborted)
    return Promise.reject(new DOMException('The read was cancelled', 'AbortError'))
  return new Promise<T>((resolve, reject) => {
    const onAbort = () => reject(new DOMException('The read was cancelled', 'AbortError'))
    signal.addEventListener('abort', onAbort, { once: true })
    request.then(resolve, reject).finally(() => signal.removeEventListener('abort', onAbort))
  })
}

function subscribeMetadataRead(shared: SharedMetadataRead, signal?: AbortSignal): Promise<unknown> {
  const consumer = { signal }
  shared.consumers.add(consumer)
  const release = () => {
    shared.consumers.delete(consumer)
    if (!shared.settled && shared.consumers.size === 0) shared.controller.abort()
  }
  // Release synchronously on abort so an immediate remount cannot join a
  // request whose last previous subscriber has already left.
  signal?.addEventListener('abort', release, { once: true })
  return waitForRead(shared.promise, signal)
    .then(value => structuredClone(value))
    .finally(() => {
      signal?.removeEventListener('abort', release)
      release()
    })
}

async function apiPublicPost<T>(path: string, body: unknown): Promise<T> {
  const controller = new AbortController()
  const timeoutId = window.setTimeout(() => controller.abort(), 15000)
  try {
    const res = await fetch(`${API_BASE}${path}`, {
      method: 'POST',
      credentials: 'include',
      headers: { 'Content-Type': 'application/json' },
      body: JSON.stringify(body),
      signal: controller.signal,
    })
    if (!res.ok) {
      const text = await res.text()
      throw formatApiError(res, text)
    }
    return (await parseJsonResponse(res)) as T
  } catch (error) {
    if (error instanceof Error && (error.name === 'AbortError' || error.name === 'TimeoutError')) {
      throw new Error(
        'Request timed out. Check that Control API and member-registration-service are running.'
      )
    }
    throw error
  } finally {
    window.clearTimeout(timeoutId)
  }
}

async function fetchWithTimeout(
  input: RequestInfo | URL,
  init: RequestInit = {},
  timeoutMs: number = API_REQUEST_TIMEOUT_MS
): Promise<Response> {
  const controller = new AbortController()
  // A non-positive or non-finite override means "use the default", never "abort
  // immediately" — this matches the server proxy's resolveProxyTimeoutMs semantics.
  const effectiveTimeoutMs =
    Number.isFinite(timeoutMs) && timeoutMs > 0 ? timeoutMs : API_REQUEST_TIMEOUT_MS
  const timeoutId = globalThis.setTimeout(() => controller.abort(), effectiveTimeoutMs)
  const signal = init.signal ? AbortSignal.any([init.signal, controller.signal]) : controller.signal
  try {
    return await fetch(input, {
      ...init,
      credentials: init.credentials || 'include',
      signal,
    })
  } catch (error) {
    if (error instanceof Error && (error.name === 'AbortError' || error.name === 'TimeoutError')) {
      if (init.signal?.aborted) throw error
      throw new Error('Request timed out. Check that Control API is reachable.')
    }
    throw error
  } finally {
    globalThis.clearTimeout(timeoutId)
  }
}

export function apiGet(
  path: string,
  query: Record<string, string | undefined> = {},
  options: ApiRequestOptions = {}
) {
  return apiRead(path, query, options)
}

async function apiRead(
  path: string,
  query: Record<string, string | undefined>,
  options: ApiRequestOptions,
  recoveringFamily = false
) {
  const url = `${controlApiUrl(path)}${qs(query)}`
  const headers = { ...authHeaders() }
  const requestEpoch = sessionEpoch
  const requestPrincipalKey = readPrincipalKey()
  const requestGeneration = getReadRequestCacheGeneration()
  const cacheKey = `${url}|${requestEpoch}`
  const metadataKey = options.metadataRead ? readRequestCacheKey(url, requestEpoch) : null
  // Capabilities, connection lists and model catalogs share one server quota.
  // Coordinate its cooldown across URLs without combining their result caches.
  const familyKey = metadataKey
    ? readRequestCacheKey(`${API_BASE}/#admin-subscription-read`, requestEpoch)
    : null
  const assertCurrent = () => {
    if (!sameReadContext(requestEpoch, requestPrincipalKey)) throw new AuthExpiredError()
    if (metadataKey && requestGeneration !== getReadRequestCacheGeneration()) {
      throw new DOMException('The metadata read was invalidated', 'AbortError')
    }
    if (options.signal?.aborted) throw new DOMException('The read was cancelled', 'AbortError')
  }
  assertCurrent()
  if (metadataKey && !options.refresh) {
    const cached = getReadRequestCacheEntry(metadataKey)
    if (cached !== undefined) {
      const value = await Promise.resolve(cached)
      assertCurrent()
      return value
    }
  }
  if (familyKey) {
    const cooldown = getReadRequestCooldown(familyKey)
    if (cooldown) {
      joinReadRequestRecovery(familyKey, options.signal)
      throw cooldown
    }
    if (!recoveringFamily) {
      const recovery = getReadRequestRecovery(familyKey)
      if (recovery) {
        joinReadRequestRecovery(familyKey, options.signal)
        try {
          await waitForRead(recovery, options.signal)
        } catch (error) {
          assertCurrent()
          // The recovery rejects with its first failing member. Members reread
          // before that failure are cached; their waiters get their own result,
          // not a sibling's denial.
          const own = metadataKey ? getReadRequestCacheEntry(metadataKey) : undefined
          if (own !== undefined) return own
          // Every registered interest left and the recovery was cancelled. A
          // waiter without a signal cannot be registered, yet it still wants
          // the result: read for itself now that the deadline has passed.
          if (error instanceof DOMException && error.name === 'AbortError') {
            return apiRead(path, query, options)
          }
          throw error
        }
        assertCurrent()
        return apiRead(path, query, options)
      }
    }
  }
  const metadataFlightKey = metadataKey ? `${metadataKey}|generation:${requestGeneration}` : null
  if (metadataFlightKey) {
    const existing = inFlightMetadataReads.get(metadataFlightKey)
    if (existing && !existing.controller.signal.aborted) {
      const value = await subscribeMetadataRead(existing, options.signal)
      assertCurrent()
      return value
    }
    if (options.refresh) invalidateReadRequestCacheEntry(metadataKey!)
  } else if (typeof window !== 'undefined' && !options.signal) {
    const existing = inFlightGetRequests.get(cacheKey)
    if (existing) {
      const value = await existing
      assertCurrent()
      return value
    }
  }

  const controller = new AbortController()
  const consumers = new Set<{ signal?: AbortSignal }>()
  const assertNetworkCurrent = () => {
    if (!sameReadContext(requestEpoch, requestPrincipalKey)) throw new AuthExpiredError()
    if (metadataKey && requestGeneration !== getReadRequestCacheGeneration()) {
      throw new DOMException('The metadata read was invalidated', 'AbortError')
    }
    if (controller.signal.aborted) throw new DOMException('The read was cancelled', 'AbortError')
  }
  const request = (async () => {
    if (typeof window !== 'undefined') activeGetControllers.add(controller)
    try {
      const res = await fetchWithTimeout(url, {
        cache: 'no-store',
        headers,
        signal:
          !metadataKey && options.signal
            ? AbortSignal.any([options.signal, controller.signal])
            : controller.signal,
      })
      assertNetworkCurrent()
      if (!res.ok) {
        if (res.status === 401) {
          if (options.silentUnauthorized) {
            clearAdminAuthToken()
            throw new AuthExpiredError()
          }
          handleUnauthorized()
        }
        // Prefer a server-provided human-safe message while preserving the
        // existing non-429 GET status-text contract and structured error data.
        const text = await res.text().catch(() => '')
        assertNetworkCurrent()
        let message = `${res.status} ${res.statusText}`
        let code: string | undefined
        let body: Record<string, unknown> | undefined
        try {
          const parsed = JSON.parse(text) as unknown
          if (parsed && typeof parsed === 'object') {
            body = parsed as Record<string, unknown>
            if (typeof body.message === 'string' && body.message.trim()) {
              message = body.message
            }
            if (typeof body.code === 'string') code = body.code
            else if (typeof body.error === 'string') code = body.error
          }
        } catch {
          /* non-JSON error body: keep the status-text message */
        }
        const seconds =
          res.status === 429 ? retryAfterSeconds(res.headers, body ?? null) : undefined
        if (res.status === 429) {
          if (typeof body?.message !== 'string' || !body.message.trim()) {
            message =
              seconds !== undefined
                ? `Too many requests. Try again in ${seconds} seconds.`
                : 'Too many requests. Try again later.'
          }
        }
        const error = new Error(message) as ApiRequestError
        error.status = res.status
        if (code) error.code = code
        if (body) error.body = body
        if (seconds !== undefined) {
          error.retryAfterSeconds = seconds
          error.retryAtMs = Date.now() + seconds * 1000
        }
        if (familyKey && res.status === 429) {
          // One clock reading, so the recovery deadline equals the cooldown's
          // retry time and a consumer released by one is never refused by the other.
          const deniedAtMs = Date.now()
          const delayMs = setReadRequestCooldown(familyKey, error, seconds, deniedAtMs)
          reserveReadRequestRecovery(
            familyKey,
            deniedAtMs + delayMs,
            metadataKey ?? url,
            signal =>
              sameReadContext(requestEpoch, requestPrincipalKey)
                ? apiRead(path, query, { ...options, signal, refresh: false }, true)
                : Promise.reject(new AuthExpiredError()),
            metadataKey ? Array.from(consumers, consumer => consumer.signal) : [options.signal]
          )
        }
        throw error
      }
      const parsed = await parseJsonResponse(res)
      assertNetworkCurrent()
      if (metadataKey) setReadRequestCacheEntry(metadataKey, parsed, METADATA_READ_TTL_MS)
      if (familyKey && metadataKey && !getReadRequestCooldown(familyKey)) {
        completeReadRequestRecovery(familyKey, metadataKey)
      }
      return parsed
    } catch (error) {
      assertNetworkCurrent()
      throw error
    } finally {
      activeGetControllers.delete(controller)
    }
  })()
  const shared: SharedMetadataRead = { promise: request, controller, consumers, settled: false }
  const settled = () => {
    shared.settled = true
    if (metadataFlightKey && inFlightMetadataReads.get(metadataFlightKey) === shared) {
      inFlightMetadataReads.delete(metadataFlightKey)
    }
    if (inFlightGetRequests.get(cacheKey) === request) inFlightGetRequests.delete(cacheKey)
  }
  request.then(settled, settled)
  if (metadataFlightKey) {
    while (inFlightMetadataReads.size >= METADATA_READ_CACHE_MAX_ENTRIES) {
      const oldest = inFlightMetadataReads.keys().next().value
      if (oldest === undefined) break
      inFlightMetadataReads.get(oldest)?.controller.abort()
      inFlightMetadataReads.delete(oldest)
    }
    inFlightMetadataReads.set(metadataFlightKey, shared)
    const value = await subscribeMetadataRead(shared, options.signal)
    assertCurrent()
    return value
  }
  if (typeof window !== 'undefined' && !options.signal) {
    inFlightGetRequests.set(cacheKey, request)
  }
  const value = await request
  assertCurrent()
  return value
}

export async function apiSend(
  method: 'POST' | 'PUT' | 'PATCH' | 'DELETE',
  path: string,
  body?: unknown,
  query: Record<string, string | undefined> = {},
  extraHeaders: Record<string, string> = {},
  options: { timeoutMs?: number } = {}
) {
  const res = await fetchWithTimeout(
    `${API_BASE}${path}${qs(query)}`,
    {
      method,
      headers: {
        'Content-Type': 'application/json',
        ...authHeaders(),
        ...extraHeaders,
      },
      body: body ? JSON.stringify(body) : undefined,
    },
    options.timeoutMs
  )
  if (!res.ok) {
    const text = await res.text()
    if (res.status === 401) {
      handleUnauthorized()
    }
    throw formatApiError(res, text)
  }
  return parseJsonResponse(res)
}

// ── Global File System operator delegation (grant/share) ────────────────────
// Like registryKeysRequest: unlike apiSend (friendly-remaps the message), these
// routes need the machine-readable error CODE (e.g. escalation_rejected,
// resource_invalid) so the operator panel can surface the precise verdict.
export type GfsUserSubjectInput = { type: 'user'; id: string }
export type GfsTeamSubjectInput = { type: 'team'; id: string }
export type GfsHostSubjectInput = { type: 'host'; id: string }
export type GfsOperatorSubjectInput = { type: 'operator' }
export type GfsContextSubjectInput = { type: 'context'; id: string }

export type GfsBulkGrantSubjectInput =
  | GfsUserSubjectInput
  | GfsTeamSubjectInput
  | GfsHostSubjectInput
export type GfsBulkShareSubjectInput = GfsUserSubjectInput | GfsTeamSubjectInput
export type GfsSubjectInput =
  | GfsBulkGrantSubjectInput
  | GfsOperatorSubjectInput
  | GfsContextSubjectInput

type GfsSubjectMutationInput<TBulkSubject extends GfsSubjectInput> =
  | { subject: GfsSubjectInput; subjects?: never }
  | { subject?: never; subjects: TBulkSubject[] }

type GfsMutationRequestBody = {
  drive?: string
  resourceId: string
  permissions: string[]
}

export type GfsGrantRequestBody = GfsMutationRequestBody &
  GfsSubjectMutationInput<GfsBulkGrantSubjectInput> & {
    inherit?: boolean
  }

export type GfsShareRequestBody = GfsMutationRequestBody &
  GfsSubjectMutationInput<GfsBulkShareSubjectInput> & {
    includeDescendants?: boolean
  }

export type GfsMutationResponse = {
  ok: true
  resourceId: string
  updated: GfsSubjectInput[]
  count: number
}

export type GfsGrantListItem = {
  id: string
  drive: string
  resourceId: string
  subject: GfsSubjectInput
  permissions: string[]
  inherit: boolean
}

export type GfsShareListItem = {
  id: string
  drive: string
  resourceId: string
  subject: GfsSubjectInput
  permissions: string[]
  includeDescendants: boolean
}

export type GfsGrantListResponse = { items: GfsGrantListItem[] }
export type GfsShareListResponse = { items: GfsShareListItem[] }

export type GfsGrantError = Error & {
  status?: number
  code?: string
  serverMessage?: string
  invalidIndexes?: number[]
}

async function gfsMutate(
  method: 'PUT' | 'POST' | 'DELETE',
  path: string,
  body?: unknown
): Promise<unknown> {
  const res = await fetchWithTimeout(`${API_BASE}${path}`, {
    method,
    cache: 'no-store',
    headers: {
      ...(body ? { 'Content-Type': 'application/json' } : {}),
      ...authHeaders(),
    },
    body: body ? JSON.stringify(body) : undefined,
  })
  if (!res.ok) {
    if (res.status === 401) handleUnauthorized()
    let code = ''
    let serverMessage = ''
    let invalidIndexes: number[] | undefined
    try {
      const parsed = (await res.json()) as {
        error?: string
        message?: unknown
        invalidIndexes?: unknown
      }
      code = parsed?.error ?? ''
      if (typeof parsed?.message === 'string') serverMessage = parsed.message
      if (Array.isArray(parsed?.invalidIndexes)) {
        invalidIndexes = parsed.invalidIndexes.filter(
          (index): index is number =>
            typeof index === 'number' && Number.isInteger(index) && index >= 0
        )
      }
    } catch {
      /* no body */
    }
    const detail =
      code && serverMessage && serverMessage !== code
        ? `${code}: ${serverMessage}`
        : serverMessage || code || res.statusText
    const error = new Error(`${res.status} ${detail}`) as GfsGrantError
    error.status = res.status
    error.code = code
    error.serverMessage = serverMessage
    error.invalidIndexes = invalidIndexes
    throw error
  }
  if (res.status === 204) return undefined
  return parseJsonResponse(res)
}

/** Operator grants a Layer-1/2 folder grant (PUT /api/v1/gfs/grants). */
export async function putGfsGrant(body: GfsGrantRequestBody): Promise<GfsMutationResponse> {
  return (await gfsMutate('PUT', '/api/v1/gfs/grants', body)) as GfsMutationResponse
}

/** Lists direct grants configured on one resource. Inherited effective access is not expanded. */
export async function getGfsGrants(
  resourceId: string,
  drive = 'main',
  signal?: AbortSignal
): Promise<GfsGrantListResponse> {
  return (await apiGet(
    '/api/v1/gfs/grants',
    { drive, resourceId },
    { signal }
  )) as GfsGrantListResponse
}

export async function deleteGfsGrant(id: string): Promise<void> {
  await gfsMutate('DELETE', `/api/v1/gfs/grants/${encodeURIComponent(id)}`)
}

/** Operator creates a URI share (POST /api/v1/gfs/shares). */
export async function postGfsShare(body: GfsShareRequestBody): Promise<GfsMutationResponse> {
  return (await gfsMutate('POST', '/api/v1/gfs/shares', body)) as GfsMutationResponse
}

/** Lists direct URI shares configured on one resource. */
export async function getGfsShares(
  resourceId: string,
  drive = 'main',
  signal?: AbortSignal
): Promise<GfsShareListResponse> {
  return (await apiGet(
    '/api/v1/gfs/shares',
    { drive, resourceId },
    { signal }
  )) as GfsShareListResponse
}

export async function deleteGfsShare(id: string): Promise<void> {
  await gfsMutate('DELETE', `/api/v1/gfs/shares/${encodeURIComponent(id)}`)
}

export type GfsResourceByPathView = {
  resourceId: string
  rid: string
  gfsUri: string
  drive: string
  name: string
  kind: string
  path: string | null
  /** Authoritative GFS version used as the mutation `ifMatch` precondition. */
  version: number
  updatedAt: string
}

/** Resolves one drive path to its canonical resource view (GET /api/v1/gfs/by-path). */
export async function getGfsResourceByPath(
  drive: string,
  path: string,
  signal?: AbortSignal
): Promise<GfsResourceByPathView> {
  return (await apiGet('/api/v1/gfs/by-path', { drive, path }, { signal })) as GfsResourceByPathView
}

export type AdminLoginResponse = {
  me: { id: string; username?: string; email?: string | null; role: 'admin' }
}

export function clearAdminAuthToken(options: { sessionChanged?: boolean } = {}): void {
  clearReadRequestPrincipal(options)
  if (typeof window === 'undefined') return
  // Remove the legacy browser-readable admin JWT if it exists. Active admin
  // sessions now live in an HttpOnly cookie set by control-api.
  window.localStorage.removeItem(ADMIN_TOKEN_STORAGE_KEY)
}

export function setControlUIReadPrincipal(principalId: string, scope: string): void {
  setReadRequestPrincipal(principalId, scope)
}

export async function loginControlUI(
  username: string,
  password: string
): Promise<AdminLoginResponse> {
  clearAdminAuthToken()
  const res = await fetch(`${API_BASE}/api/v1/admin/auth/login`, {
    method: 'POST',
    credentials: 'include',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({ username, password }),
  })
  if (!res.ok) {
    const text = await res.text()
    throw new Error(`${res.status} ${res.statusText} - ${text}`)
  }
  const data = (await res.json()) as AdminLoginResponse
  // The shared cookie now belongs to the new session; tell every peer tab.
  clearAdminAuthToken({ sessionChanged: true })
  return data
}

export async function logoutControlUI(): Promise<void> {
  clearAdminAuthToken()
  try {
    await apiSend('POST', '/api/v1/admin/auth/logout')
  } catch {
    // Logout is best-effort: a stale token or backend revoke failure should not
    // keep the local admin session alive or surface a dev/runtime overlay.
  } finally {
    clearAdminAuthToken({ sessionChanged: true })
  }
}

export async function getControlUIAuthMe(): Promise<{
  me: { id?: string; username?: string; email?: string | null; role?: string }
  namespaces?: { sandbox?: string; mcpServer?: string }
}> {
  return apiGet('/api/v1/admin/auth/me', {}, { silentUnauthorized: true }) as Promise<{
    me: { id?: string; username?: string; email?: string | null; role?: string }
    namespaces?: { sandbox?: string; mcpServer?: string }
  }>
}

export type ControlAdminProfile = {
  id: string
  username: string
  email: string | null
  role: 'admin'
  pendingEmailChange?: {
    email: string
    expiresAt: string
    createdAt: string
  } | null
}

export type ControlAdminBridgeStatus = {
  admin: {
    id: string
    username: string
    email: string | null
    emailConfirmed: boolean
    pendingEmailChange?: {
      email: string
      expiresAt: string
      createdAt: string
    } | null
  }
  member: { id: string; email: string } | null
}

export type ControlAdminListItem = {
  id: string
  username: string
  email: string | null
  memberId?: string | null
  status: 'active' | 'disabled' | 'pending_password'
  passwordPending?: boolean
  invitationId?: string
  replaceInviter?: boolean
  invitedByAdminId?: string | null
  gfsOperatorLink?: {
    desktopUserId: string
    controlAdminId: string
    source: 'initial_setup' | 'unknown'
    createdAt: string | null
    status: 'active' | 'inactive_admin' | 'revoked' | 'error'
    generation?: number | null
    rowVersion?: number | null
    revocationReason?: string | null
  } | null
  gfsOperatorLinkStatus?: 'none' | 'active' | 'inactive_admin' | 'revoked' | 'error'
  lastLoginAt: string | null
  createdAt: string
}

export type ControlAdminInvitationItem = {
  id: string
  email: string
  status: 'pending' | 'accepted' | 'revoked'
  expiresAt: string
  createdAt: string
  acceptedAt?: string | null
}

export type ControlAdminEmailConfirmationItem = {
  id: string
  email: string
  status: 'pending' | 'confirmed' | 'revoked'
  expiresAt: string
  createdAt: string
}

export async function getControlUISettingsMe(): Promise<{ me: ControlAdminProfile }> {
  return apiGet('/api/v1/admin/settings/me') as Promise<{ me: ControlAdminProfile }>
}

export async function getControlAdminBridgeStatus(): Promise<ControlAdminBridgeStatus> {
  return apiGet('/api/v1/admin/settings/bridge-status') as Promise<ControlAdminBridgeStatus>
}

export async function updateControlUISettingsUsername(username: string): Promise<{
  me: ControlAdminProfile
}> {
  return apiSend('PATCH', '/api/v1/admin/settings/username', { username }) as Promise<{
    me: ControlAdminProfile
  }>
}

export async function requestControlUISettingsEmailChange(email: string): Promise<{
  confirmation: ControlAdminEmailConfirmationItem
}> {
  return apiSend('POST', '/api/v1/admin/settings/email-change', { email }) as Promise<{
    confirmation: ControlAdminEmailConfirmationItem
  }>
}

export async function updateControlUISettingsPassword(payload: {
  currentPassword: string
  newPassword: string
}): Promise<{ updated: true }> {
  return apiSend('POST', '/api/v1/admin/settings/password', payload) as Promise<{ updated: true }>
}

export async function getControlAdmins(): Promise<{
  admins: ControlAdminListItem[]
  invitations: ControlAdminInvitationItem[]
}> {
  return apiGet('/api/v1/admin/control-admins') as Promise<{
    admins: ControlAdminListItem[]
    invitations: ControlAdminInvitationItem[]
  }>
}

export async function inviteControlAdmin(
  email: string,
  options?: { createDesktopAccess?: boolean; teams?: Array<{ teamId: string; role: TeamRole }> }
): Promise<{
  invitation: ControlAdminInvitationItem
}> {
  return apiSend('POST', '/api/v1/admin/control-admin-invitations', {
    email,
    createDesktopAccess: options?.createDesktopAccess === true,
    teams: options?.teams || [],
  }) as Promise<{ invitation: ControlAdminInvitationItem }>
}

export async function cancelControlAdminInvitation(invitationId: string): Promise<{
  revoked: true
}> {
  return apiSend('DELETE', `/api/v1/admin/control-admin-invitations/${invitationId}`) as Promise<{
    revoked: true
  }>
}

export async function deleteControlAdmin(adminId: string): Promise<{ deleted: true }> {
  return apiSend('DELETE', `/api/v1/admin/control-admins/${adminId}`) as Promise<{
    deleted: true
  }>
}

export async function revokeControlAdminGfsOperatorLink(
  adminId: string,
  payload: { rowVersion?: number | null; reason?: string } = {}
): Promise<{
  revoked: boolean
  gfsOperatorLinkStatus: 'revoked'
  controlAdminId: string
  desktopUserId: string | null
  generation?: number | null
  rowVersion?: number | null
}> {
  return apiSend(
    'DELETE',
    `/api/v1/admin/control-admins/${encodeURIComponent(adminId)}/gfs-operator-link`,
    payload
  ) as Promise<{
    revoked: boolean
    gfsOperatorLinkStatus: 'revoked'
    controlAdminId: string
    desktopUserId: string | null
    generation?: number | null
    rowVersion?: number | null
  }>
}

export async function reactivateControlAdminGfsOperatorLink(
  adminId: string,
  payload: { rowVersion: number; reason: string }
): Promise<{
  reactivated: boolean
  gfsOperatorLinkStatus: 'active' | 'revoked'
  controlAdminId: string
  desktopUserId: string | null
  generation?: number | null
  rowVersion?: number | null
}> {
  return apiSend(
    'POST',
    `/api/v1/admin/control-admins/${encodeURIComponent(adminId)}/gfs-operator-link/reactivate`,
    payload
  ) as Promise<{
    reactivated: boolean
    gfsOperatorLinkStatus: 'active' | 'revoked'
    controlAdminId: string
    desktopUserId: string | null
    generation?: number | null
    rowVersion?: number | null
  }>
}

export async function createMemberFromControlAdmin(
  adminId: string,
  payload: { reusePassword: boolean; teams: Array<{ teamId: string; role: TeamRole }> }
): Promise<{ created: boolean; user: { id: string; email: string; name: string | null } }> {
  return apiSend('POST', `/api/v1/admin/control-admins/${encodeURIComponent(adminId)}/member`, {
    reusePassword: payload.reusePassword,
    teams: payload.teams,
  }) as Promise<{ created: boolean; user: { id: string; email: string; name: string | null } }>
}

export async function validateControlAdminInvitation(token: string): Promise<{
  valid: true
  email: string
  invitationUuid: string
}> {
  return apiPublicPost('/api/v1/admin/auth/control-admin-invitations/validate', { token })
}

export async function completeControlAdminInvitation(payload: {
  token: string
  email: string
  username: string
  password: string
  useSameMemberPassword?: boolean
  memberPassword?: string
}): Promise<{ completed: true; desktopAccessCompleted?: boolean; login: { username: string } }> {
  return apiPublicPost('/api/v1/admin/auth/control-admin-invitations/complete', payload)
}

export async function validateControlAdminEmailConfirmation(token: string): Promise<{
  valid: true
  email: string
  confirmationUuid: string
}> {
  return apiPublicPost('/api/v1/admin/auth/control-admin-email-confirmations/validate', { token })
}

export async function completeControlAdminEmailConfirmation(payload: {
  token: string
  email?: string
}): Promise<{ completed: true; alreadyConfirmed?: boolean; login: { username: string } }> {
  return apiPublicPost('/api/v1/admin/auth/control-admin-email-confirmations/complete', payload)
}

export async function requestControlAdminPasswordReset(username: string): Promise<{
  requested: true
}> {
  return apiPublicPost('/api/v1/admin/auth/password-reset/request', { username })
}

export async function validateControlAdminPasswordReset(token: string): Promise<{
  valid: true
  email: string
  resetUuid: string
}> {
  return apiPublicPost('/api/v1/admin/auth/password-reset/validate', { token })
}

export async function completeControlAdminPasswordReset(payload: {
  token: string
  email: string
  password: string
}): Promise<{ completed: true; login: { username: string } }> {
  return apiPublicPost('/api/v1/admin/auth/password-reset/complete', payload)
}

/**
 * Resolve the recipe-secret namespaces this control-api enforces. In an MCC
 * per-tenant deployment these are suffixed (sandbox-recipes-<slug> /
 * mcp-server-<slug>); control-ui must write recipe secrets to them rather than
 * the bare defaults. Sourced from GET /admin/auth/me (the UI already calls it).
 * Falls back to the bare single-tenant defaults if the field is absent (older
 * control-api) or the request fails, so single-tenant behavior is unchanged.
 */
export async function getControlUINamespaces(): Promise<RecipeSecretNamespaces> {
  try {
    const res = await getControlUIAuthMe()
    return {
      sandbox: res.namespaces?.sandbox || DEFAULT_SANDBOX_SECRET_NAMESPACE,
      mcpServer: res.namespaces?.mcpServer || DEFAULT_MCP_SERVER_SECRET_NAMESPACE,
    }
  } catch (err) {
    console.warn(
      'getControlUINamespaces: could not resolve recipe-secret namespaces from control-api; ' +
        'falling back to single-tenant defaults (sandbox-recipes/mcp-server). In a per-tenant ' +
        'deployment, recipe secret writes may then 400 until control-api is reachable.',
      err
    )
    return {
      sandbox: DEFAULT_SANDBOX_SECRET_NAMESPACE,
      mcpServer: DEFAULT_MCP_SERVER_SECRET_NAMESPACE,
    }
  }
}

export type TeamRole = 'admin' | 'inviter' | 'member'
export type InviteRole = TeamRole

export type TeamSummary = {
  id: string
  name: string
  role: TeamRole
}
export type TeamListItem = { id: string; name: string; memberCount: number }
export type SharedFileSystemSpec = {
  size?: string
  storageClassName?: string
  accessModes?: string[]
  annotations?: Record<string, string>
  directories?: string[]
  security?: { runAsUser?: number; runAsGroup?: number; fsGroup?: number }
  retainOnDelete?: boolean
}
export type SharedFileSystemStatus = {
  phase?: 'Provisioning' | 'Initializing' | 'Ready' | 'Degraded' | 'Failed'
  pvcName?: string
  capacity?: string
  storageClassName?: string
  serviceName?: string
  mountedByContexts?: Array<{ namespace: string; name: string }>
  lastInitJob?: { name?: string; completedAt?: string; error?: string }
  conditions?: Array<{
    type: string
    status: 'True' | 'False' | 'Unknown'
    reason?: string
    message?: string
    lastTransitionTime?: string
  }>
}
export type SharedFileSystemResource = {
  metadata?: Metadata
  spec?: SharedFileSystemSpec
  status?: SharedFileSystemStatus
}
export type ContextSharedFileSystemRef = {
  name: string
  mountPath: string
}
export type ContextSharedFileSystemStatus = {
  name: string
  mountPath: string
  phase: 'Resolving' | 'Mounted' | 'MissingTarget' | 'Failed'
  pvcName?: string
  message?: string
}
export type ContextSpec = {
  contextId: string
  // Editable, human-visible name (free text). Optional/new: existing contexts
  // won't have it, so consumers fall back to `metadata.name`.
  displayName?: string
  description?: string
  mcpServers: string[]
  sharedFileSystems?: ContextSharedFileSystemRef[]
}
export type ContextResource = {
  metadata?: Metadata
  spec?: ContextSpec
  status?: { sharedFileSystems?: ContextSharedFileSystemStatus[] }
}
export type HostLifecycleSpec = { stateless?: boolean }
export type HostStatusCondition = {
  type?: string
  status?: string
  reason?: string
  message?: string
}
export type HostResource = {
  metadata?: Metadata
  spec?: AnyRecord & {
    contextRef?: string
    model?: { provider?: string; name?: string }
    lifecycle?: HostLifecycleSpec
  }
  status?: AnyRecord & {
    lifecycle?: { state?: string; reason?: string }
    conditions?: HostStatusCondition[]
  }
}
/**
 * Condition entry on `status.conditions[]` of the McpServer CRD, as written by
 * the HCC reconciler (host-context-controller/src/reconciler.ts). `status` is
 * the K8s-standard string tri-state, not a boolean. `lastTransitionTime` only
 * advances when `status` itself changes (writeStatusCondition) — the UI relies
 * on that to tell "this rollout" apart from a stale prior condition (issue #223,
 * Fase 3 requisito 6).
 */
export type McpServerCondition = {
  observedGeneration?: number
  type: string
  status: 'True' | 'False' | 'Unknown'
  reason: string
  message: string
  lastTransitionTime: string
}

export type McpServerResource = {
  metadata?: Metadata
  spec?: AnyRecord
  status?: { conditions?: McpServerCondition[] }
}

// Installed guardrail hook CRs (LlmHook). Reconciler-written status follows the
// same conditions[] convention as McpServer, plus hook-specific fields.
export type LlmHookCondition = {
  type: string
  status: 'True' | 'False' | 'Unknown'
  reason?: string
  message?: string
  lastTransitionTime?: string
}
export type LlmHookStatus = {
  conditions?: LlmHookCondition[]
  observedDigest?: string
  readyReplicas?: number
  lastReconciled?: string
}
export type LlmHookResource = {
  metadata?: Metadata
  spec?: AnyRecord
  status?: LlmHookStatus
}
export type ContextUser = {
  id: string
  email: string
  name: string | null
  displayName: string | null
}
export type ContextTeam = {
  id: string
  name: string
}
export type AgentUser = ContextUser
export type AgentTeam = ContextTeam
export type UserContextAccess = {
  userId: string
  contextIds: string[]
  deletedContextIds?: string[]
}
export type TeamContextAccess = {
  teamId: string
  contextIds: string[]
  deletedContextIds?: string[]
}
export type UserAgentAccess = {
  userId: string
  agentNames: string[]
  deletedAgentNames: string[]
  deletedHistoryLimit: number
}
export type TeamAgentAccess = {
  teamId: string
  agentNames: string[]
  deletedAgentNames: string[]
  deletedHistoryLimit: number
}
export type TeamMember = {
  id: string
  email: string
  name?: string
  role: TeamRole
  status?: string
  display_name?: string | null
}

export type AdminTeamPendingInvitation = {
  id: string
  team_id: string | null
  teamId?: string | null
  email: string
  role: InviteRole
  teams?: Array<{ id: string; name: string; role: InviteRole }>
  status: 'pending'
  created_at: string
  expires_at?: string
}

/** Pending invite with team name (admin home list). */
export type AdminPendingInvitationListItem = AdminTeamPendingInvitation & {
  team_name: string | null
}
export type AdminUser = {
  id: string
  email: string
  name: string | null
  picture: string | null
  displayName: string | null
  controlAdminId?: string | null
  activeTeamCount: number
  teams?: Array<{ id: string; name: string; role: TeamRole }>
  passwordPendingFromAcceptedInvitation?: boolean
}
// `keys` are the Secret's data-key NAMES only (never values); the detail bundle
// populates them via listHostSecrets. Optional for compat with older payloads.
export type HostSecretResource = { name: string; keys?: string[] }

/**
 * Host/LLM Secret metadata only. `keys` are Kubernetes data-key names; values
 * are never returned. SDK target editors use this rather than recipe-scoped
 * sandbox secrets because promptBridge credentials resolve from host Secrets.
 */
export async function listLlmHostSecrets() {
  return apiGet('/api/v1/admin/secrets') as Promise<{ items?: HostSecretResource[] }>
}

export type HostDetailBundle = {
  host: HostResource
  contexts: ContextResource[]
  secrets: HostSecretResource[]
  users: AdminUser[]
  teams: TeamListItem[]
  agentUsers: AgentUser[]
  agentTeams: AgentTeam[]
}
export type ProfileAdminOverview = {
  teams: TeamListItem[]
  users: AdminUser[]
  pendingInvitations: AdminPendingInvitationListItem[]
  teamAgentCounts: Record<string, number>
  teamContextCounts: Record<string, number>
}
export type AdminUserChannels = {
  emails: string[]
  slackUserNames: string[]
  telegramIds: string[]
}
export type AdminUserContext = {
  id: string
  email: string
  name: string | null
  picture: string | null
  displayName: string | null
  channels: AdminUserChannels
}

export async function getAdminUsers(q = '') {
  return apiGet('/api/v1/admin/users', { q }) as Promise<{ items?: AdminUser[] }>
}

export async function getHostDetailBundle(name: string) {
  return apiGet(
    `/api/v1/admin/hosts/${encodeURIComponent(name)}/detail`
  ) as Promise<HostDetailBundle>
}

export async function getProfileAdminOverview() {
  return apiGet('/api/v1/admin/profile-admin/overview') as Promise<ProfileAdminOverview>
}

export async function createAdminUserApi(email: string, name: string) {
  return apiSend('POST', '/api/v1/admin/users', { email, name }) as Promise<{
    id: string
    email: string
    name: string | null
  }>
}

export async function getContexts() {
  return apiGet('/api/v1/admin/contexts') as Promise<{ items?: ContextResource[] }>
}

export async function getHosts() {
  return apiGet('/api/v1/admin/hosts') as Promise<{ items?: HostResource[] }>
}

export async function getHost(name: string) {
  return apiGet(`/api/v1/admin/hosts/${encodeURIComponent(name)}`) as Promise<HostResource>
}

export type HostPersonalization = {
  identity: string
  soul: string
  agents: string
  user: string
  resourceVersion: string
}

export async function getHostPersonalization(name: string): Promise<HostPersonalization> {
  return apiGet(
    `/api/v1/admin/hosts/${encodeURIComponent(name)}/personalization`
  ) as Promise<HostPersonalization>
}

export async function updateHostPersonalization(
  name: string,
  payload: {
    identity?: string
    soul?: string
    agents?: string
    user?: string
    resourceVersion: string
  }
): Promise<{ resourceVersion: string }> {
  return apiSend(
    'PUT',
    `/api/v1/admin/hosts/${encodeURIComponent(name)}/personalization`,
    payload
  ) as Promise<{ resourceVersion: string }>
}

export async function getContext(name: string) {
  return apiGet(`/api/v1/admin/contexts/${encodeURIComponent(name)}`) as Promise<ContextResource>
}

export async function createContext(payload: { metadata: { name: string }; spec: ContextSpec }) {
  return apiSend('POST', '/api/v1/admin/contexts', payload) as Promise<ContextResource>
}

export async function updateContext(
  name: string,
  payload: { metadata: { resourceVersion: string }; spec: ContextSpec }
) {
  return apiSend(
    'PUT',
    `/api/v1/admin/contexts/${encodeURIComponent(name)}`,
    payload
  ) as Promise<ContextResource>
}

export async function deleteContext(name: string) {
  return apiSend('DELETE', `/api/v1/admin/contexts/${encodeURIComponent(name)}`)
}

export async function getMcpServers() {
  return apiGet('/api/v1/admin/mcp-servers') as Promise<{ items?: McpServerResource[] }>
}

// ── Installed guardrail hooks (LlmHook CRDs) — read + uninstall ─────────────
// Creation is via the org-scoped registry install-hook saga, not a raw write.
export async function getLlmHooks() {
  return apiGet('/api/v1/admin/llm-hooks') as Promise<{ items?: LlmHookResource[] }>
}

export async function getLlmHook(name: string) {
  return apiGet(`/api/v1/admin/llm-hooks/${encodeURIComponent(name)}`) as Promise<LlmHookResource>
}

export async function deleteLlmHook(name: string) {
  return apiSend('DELETE', `/api/v1/admin/llm-hooks/${encodeURIComponent(name)}`)
}

// ── SharedFileSystem CRD admin + per-SFS file browsing ──────────────────

export async function getSharedFileSystems() {
  return apiGet('/api/v1/admin/shared-filesystems') as Promise<{
    items?: SharedFileSystemResource[]
  }>
}

export async function getSharedFileSystem(name: string) {
  return apiGet(
    `/api/v1/admin/shared-filesystems/${encodeURIComponent(name)}`
  ) as Promise<SharedFileSystemResource>
}

export type CreateSharedFileSystemInput = {
  name: string
  size?: string
  accessModes?: string[]
  storageClassName?: string
  directories?: string[]
  retainOnDelete?: boolean
  security?: { runAsUser?: number; runAsGroup?: number; fsGroup?: number }
}

export async function createSharedFileSystem(input: CreateSharedFileSystemInput) {
  return apiSend(
    'POST',
    '/api/v1/admin/shared-filesystems',
    input as unknown as Record<string, unknown>
  ) as Promise<SharedFileSystemResource>
}

export async function deleteSharedFileSystem(name: string) {
  return apiSend('DELETE', `/api/v1/admin/shared-filesystems/${encodeURIComponent(name)}`)
}

/**
 * Below: file-browsing endpoints. They proxy through control-api's
 * /admin/shared-filesystems/:name/proxy/v1/* to the per-SFS wfc Service.
 * The control-api proxy substitutes the admin JWT for a fresh wfc browsing
 * token before forwarding, so these helpers just need the standard admin
 * Authorization header (which apiGet/apiSend already attach).
 */
export type WfcDirEntry = {
  name: string
  kind: 'file' | 'directory' | 'other'
  size: number
  mtime: string
}
export type WfcListResponse = {
  ok: true
  data: { path: string; entries: WfcDirEntry[]; truncated: boolean }
}
export type WfcStatResponse = {
  ok: true
  data: { path: string; kind: 'file' | 'directory' | 'other'; size: number; mtime: string }
}

function sfsProxyUrl(name: string, subPath: string): string {
  const base = `/api/v1/admin/shared-filesystems/${encodeURIComponent(name)}/proxy/v1/files`
  return subPath ? `${base}${subPath}` : base
}

export async function sfsListFiles(sfsName: string, relPath: string) {
  return apiGet(sfsProxyUrl(sfsName, ''), { path: relPath }) as Promise<WfcListResponse>
}

export async function sfsStat(sfsName: string, relPath: string) {
  return apiGet(sfsProxyUrl(sfsName, '/stat'), { path: relPath }) as Promise<WfcStatResponse>
}

export function sfsDownloadUrl(sfsName: string, relPath: string): string {
  const base = process.env.NEXT_PUBLIC_CONTROL_API_BASE_URL || '/control-api'
  const q = relPath ? `?path=${encodeURIComponent(relPath)}` : ''
  return `${base}${sfsProxyUrl(sfsName, '/download')}${q}`
}

async function fetchAuthenticatedFileBlob(url: string): Promise<Blob> {
  const resp = await fetch(url, { credentials: 'include' })
  if (!resp.ok) {
    if (resp.status === 401) handleUnauthorized()
    let msg = `Download failed (${resp.status})`
    try {
      const body = (await resp.json()) as {
        error?: string | { message?: string; code?: string }
      }
      if (typeof body.error === 'string') msg = body.error
      else if (body.error?.message || body.error?.code) {
        msg = body.error.message || body.error.code || msg
      }
    } catch {
      /* ignore */
    }
    throw new Error(msg)
  }
  return resp.blob()
}

async function sfsFetchFileBlob(sfsName: string, relPath: string): Promise<Blob> {
  return fetchAuthenticatedFileBlob(sfsDownloadUrl(sfsName, relPath))
}

function sfsFileName(relPath: string): string {
  return relPath.split('/').pop() || 'download'
}

function sfsBrowserCanPreview(blob: Blob, fileName: string): boolean {
  const mime = blob.type.split(';')[0].toLowerCase()
  if (
    mime.startsWith('image/') ||
    mime.startsWith('text/') ||
    mime.startsWith('audio/') ||
    mime.startsWith('video/') ||
    mime === 'application/pdf'
  ) {
    return true
  }

  const ext = fileName.split('.').pop()?.toLowerCase()
  return Boolean(
    ext &&
    [
      'csv',
      'gif',
      'htm',
      'html',
      'jpeg',
      'jpg',
      'json',
      'log',
      'md',
      'pdf',
      'png',
      'svg',
      'txt',
      'webp',
    ].includes(ext)
  )
}

function triggerBlobDownload(blob: Blob, fileName: string): void {
  const url = URL.createObjectURL(blob)
  const a = document.createElement('a')
  a.href = url
  a.download = fileName
  document.body.appendChild(a)
  a.click()
  a.remove()
  // Free the Blob after the click is processed.
  setTimeout(() => URL.revokeObjectURL(url), 1000)
}

/**
 * Trigger a browser download of a single file. The download endpoint sits
 * behind the admin auth gate. We fetch with the HttpOnly session cookie,
 * materialize a Blob, and click a temporary anchor pointing at the object URL.
 */
export async function sfsDownload(sfsName: string, relPath: string): Promise<void> {
  const blob = await sfsFetchFileBlob(sfsName, relPath)
  triggerBlobDownload(blob, sfsFileName(relPath))
}

export async function sfsOpenOrDownload(
  sfsName: string,
  relPath: string,
  targetWindow?: Window | null
): Promise<void> {
  const blob = await sfsFetchFileBlob(sfsName, relPath)
  const fileName = sfsFileName(relPath)

  if (!targetWindow || targetWindow.closed || !sfsBrowserCanPreview(blob, fileName)) {
    if (targetWindow && !targetWindow.closed) targetWindow.close()
    triggerBlobDownload(blob, fileName)
    return
  }

  const url = URL.createObjectURL(blob)
  targetWindow.location.href = url
  setTimeout(() => URL.revokeObjectURL(url), 60_000)
}

export async function sfsMkdir(sfsName: string, relPath: string) {
  return apiSend('POST', sfsProxyUrl(sfsName, '/mkdir'), { path: relPath })
}

export async function sfsMove(sfsName: string, fromPath: string, toPath: string) {
  return apiSend('POST', sfsProxyUrl(sfsName, '/move'), { from: fromPath, to: toPath })
}

export async function sfsDelete(sfsName: string, relPath: string, recursive = false) {
  const q = new URLSearchParams({ path: relPath })
  if (recursive) q.set('recursive', 'true')
  return apiSend('DELETE', `${sfsProxyUrl(sfsName, '')}?${q.toString()}`)
}

/**
 * Multipart upload (or replace). The browser sends the admin JWT; control-api
 * mints a wfc browsing token before forwarding. mode='create' uses POST
 * /upload (409 on conflict); mode='replace' uses PUT /replace (404 if missing).
 */
export async function sfsUpload(
  sfsName: string,
  relPath: string,
  file: File,
  mode: 'create' | 'replace' = 'create'
): Promise<{ ok: true; data: { path: string; kind: 'file'; size: number; mtime: string } }> {
  const base = process.env.NEXT_PUBLIC_CONTROL_API_BASE_URL || '/control-api'
  const url = `${base}${sfsProxyUrl(sfsName, mode === 'create' ? '/upload' : '/replace')}`
  const fd = new FormData()
  fd.append('path', relPath)
  fd.append('file', file)
  const res = await fetch(url, {
    method: mode === 'create' ? 'POST' : 'PUT',
    credentials: 'include',
    body: fd,
  })
  if (!res.ok) {
    const text = await res.text()
    if (res.status === 401) {
      clearAdminAuthToken()
      const handler = getGlobalAuthErrorHandler()
      handler?.()
      throw new Error('401 Unauthorized - session expired, please sign in again')
    }
    let detail: string
    try {
      const parsed = JSON.parse(text) as { error?: { message?: string; code?: string } }
      detail = parsed.error?.message || parsed.error?.code || text
    } catch {
      detail = text
    }
    throw new Error(`${res.status} ${res.statusText} - ${detail}`)
  }
  return res.json()
}

// ── Global File System file download (operator content proxy) ────────────────
// Mirrors sfsDownload: the operator proxy streams raw bytes from
// GET /api/v1/gfs/proxy/v1/resources/:rid/content (gfsc serveContent). gfsc does
// NOT set Content-Disposition, so the browser can't infer the filename — callers
// pass child.name explicitly. Auth is the same HttpOnly admin cookie the rest of
// control-ui sends (credentials: 'include'); it cannot be a plain <a href>.
export function gfsDownloadUrl(rid: string): string {
  const base = process.env.NEXT_PUBLIC_CONTROL_API_BASE_URL || '/control-api'
  return `${base}/api/v1/gfs/proxy/v1/resources/${encodeURIComponent(rid)}/content`
}

export async function gfsFetchFileBlob(rid: string): Promise<Blob> {
  return fetchAuthenticatedFileBlob(gfsDownloadUrl(rid))
}

/**
 * Trigger a browser download of a single GFS file. Fetches the raw content
 * through the operator-scoped GFS proxy with the admin session cookie,
 * materializes a Blob, and clicks a temporary anchor pointing at the object URL.
 */
export async function gfsDownload(rid: string, fileName: string): Promise<void> {
  const blob = await gfsFetchFileBlob(rid)
  triggerBlobDownload(blob, fileName)
}

export type EnvVar = { name: string; value: string }
export type EnvSecretKeyMapping = { secretKey: string; envVar: string }
export type EnvSecret = { name: string; keys: EnvSecretKeyMapping[] }
export type EgressBinding = {
  egressClass?: 'exact-host' | 'public-web'
  dns?: string
  cidr?: string
  port?: number
  protocol?: 'TCP' | 'UDP'
}

export async function createMcpServer(payload: {
  metadata: { name: string }
  spec: {
    image: string
    contextRef: string
    description?: string
    enabled?: boolean
    managed?: boolean
    transport: {
      type: 'streamableHttp' | 'sse' | 'stdio'
      port?: number
      url?: string
    }
    env?: EnvVar[]
    envSecret?: EnvSecret
    egressBindings?: EgressBinding[]
    command?: string[]
    args?: string[]
  }
}) {
  return apiSend('POST', '/api/v1/admin/mcp-servers', payload) as Promise<McpServerResource>
}

/** Cleanup stages control-api reports as `pending` when an mcp-server uninstall stops. */
export type McpServerUninstallStage =
  | 'contexts'
  | 'dynamic_client'
  | 'oauth_grants'
  | 'secrets'
  | 'mcp_server'

const MCP_SERVER_UNINSTALL_STAGE_LABELS: Record<McpServerUninstallStage, string> = {
  contexts: 'agent access',
  dynamic_client: 'OAuth client registration',
  oauth_grants: 'OAuth grants',
  secrets: 'connector Secrets',
  mcp_server: 'connector resource',
}

export function isMcpServerUninstallStage(value: unknown): value is McpServerUninstallStage {
  return typeof value === 'string' && Object.hasOwn(MCP_SERVER_UNINSTALL_STAGE_LABELS, value)
}

/**
 * The uninstall stopped at a failing cleanup step; repeating the same DELETE
 * resumes it. Keeps `status`/`code`/`body` so generic error handling that
 * inspects them still works. Stages this client does not know are dropped from
 * `pending` (the message then names only the known ones).
 */
export class McpServerUninstallIncompleteError extends Error {
  readonly status = 503
  readonly code = 'mcp_server_uninstall_incomplete'
  /** Human-readable `pending`, e.g. " (pending cleanup: OAuth grants)"; empty when none is known. */
  readonly pendingSummary: string
  /**
   * "is still installed", or "may still be installed" when the CR delete itself
   * failed: that error does not tell whether the API server already accepted it.
   */
  readonly installState: string

  constructor(
    readonly pending: McpServerUninstallStage[],
    readonly deleted: string[],
    readonly body: Record<string, unknown>
  ) {
    const labels = pending.map(stage => MCP_SERVER_UNINSTALL_STAGE_LABELS[stage])
    const pendingSummary = labels.length > 0 ? ` (pending cleanup: ${labels.join(', ')})` : ''
    const installState = pending.includes('mcp_server')
      ? 'may still be installed'
      : 'is still installed'
    super(
      `Connector uninstall is incomplete${pendingSummary}. The connector ${installState}; retry the delete to finish.`
    )
    this.name = 'McpServerUninstallIncompleteError'
    this.pendingSummary = pendingSummary
    this.installState = installState
  }
}

function toMcpServerUninstallIncompleteError(
  err: unknown
): McpServerUninstallIncompleteError | null {
  if (!(err instanceof Error) || (err as Error & { status?: unknown }).status !== 503) {
    return null
  }
  const body = apiErrorBody(err)
  if (
    !body ||
    body.error !== 'mcp_server_uninstall_incomplete' ||
    body.outcome !== 'repair_required'
  ) {
    return null
  }
  const pending = Array.isArray(body.pending) ? body.pending.filter(isMcpServerUninstallStage) : []
  const deleted = Array.isArray(body.deleted)
    ? body.deleted.filter((item): item is string => typeof item === 'string')
    : []
  return new McpServerUninstallIncompleteError(pending, deleted, body)
}

export async function deleteMcpServer(name: string) {
  try {
    return (await apiSend('DELETE', `/api/v1/admin/mcp-servers/${encodeURIComponent(name)}`)) as {
      name: string
      namespace?: string
    }
  } catch (err) {
    throw toMcpServerUninstallIncompleteError(err) ?? err
  }
}

export async function getMcpServer(name: string) {
  return apiGet(
    `/api/v1/admin/mcp-servers/${encodeURIComponent(name)}`
  ) as Promise<McpServerResource>
}

export async function updateMcpServer(
  name: string,
  payload: { spec: Record<string, unknown>; metadata?: { uid?: string; resourceVersion?: string } }
) {
  return apiSend(
    'PUT',
    `/api/v1/admin/mcp-servers/${encodeURIComponent(name)}`,
    payload
  ) as Promise<McpServerResource>
}

export type McpSecretCreateResult =
  | ({
      name: string
      namespace: string
    } & SecretIdentity)
  | {
      name: string
      namespace: string
      uid?: undefined
      resourceVersion?: undefined
    }

export type McpSecretRollbackRepairIdentity = {
  name: string
  namespace: string
} & SecretIdentity

export async function createMcpSecret(
  name: string,
  data: Record<string, string>
): Promise<McpSecretCreateResult> {
  const response = (await apiSend('POST', '/api/v1/admin/mcp-secrets', { name, data })) as {
    name: string
    namespace: string
  }
  const identity = readSecretIdentity(response, 'createMcpSecret')
  return identity ? { ...response, ...identity } : response
}

/**
 * Deletes a Secret in the MCP-servers namespace (hardcoded server-side to
 * `config.mcpServersNamespace`). Used by the Create MCP Server flow to roll
 * back a just-created Secret when the subsequent McpServer CRD creation fails.
 *
 * Current API versions require the server-issued identity. `undefined` is a
 * narrow compatibility path for that rollback only: older create endpoints
 * succeeded without returning identity and accepted the original bodyless
 * DELETE. Primary delete flows must keep their identity precondition.
 */
export async function deleteMcpSecret(name: string, identity: SecretIdentity | undefined) {
  return apiSend(
    'DELETE',
    `/api/v1/admin/mcp-secrets/${encodeURIComponent(name)}`,
    identity
  ) as Promise<{
    name: string
    namespace: string
  }>
}

/**
 * Rotates one or more keys on an EXISTING MCP Server Secret (issue #223).
 * `data` carries only the keys the operator wants to rotate — every other key
 * already on the Secret survives untouched (server-side merge-patch). The
 * response is names-only: `keys` lists the resulting key names (never
 * values), and `affectedConnectors` names every McpServer whose
 * `spec.envSecret.name` matches this Secret, so the UI can tell the operator
 * exactly what is about to restart. Saving does NOT restart anything itself —
 * the HCC's SecretInformer reacts to the Secret change and rolls the affected
 * Deployments; the caller must poll getMcpServer() for DeploymentReady to know
 * whether the rollout actually landed (see control-ui/components/UpdateConnectorCredentials).
 */
export async function updateMcpSecret(name: string, data: Record<string, string>) {
  return apiSend('PUT', `/api/v1/admin/mcp-secrets/${encodeURIComponent(name)}`, {
    data,
  }) as Promise<{
    name: string
    namespace: string
    keys: string[]
    affectedConnectors: string[]
  }>
}

export type RecipeSecretOwnership =
  | { kind: 'shared' }
  | { kind: 'owner-recipe'; recipeName: string }
  | { kind: 'unlabeled' }

export type RecipeSecretItem = {
  name: string
  namespace: string
  keys: string[]
  ownership: RecipeSecretOwnership
  uid?: string
  resourceVersion?: string
}

export async function getRecipeSecrets() {
  return apiGet('/api/v1/admin/recipe-secrets') as Promise<{ items?: RecipeSecretItem[] }>
}

export async function createRecipeSecret(
  name: string,
  data: Record<string, string>,
  ownership: Exclude<RecipeSecretOwnership, { kind: 'unlabeled' }>,
  targetNamespace?: string
) {
  return apiSend('POST', '/api/v1/admin/recipe-secrets', {
    name,
    data,
    ownership,
    ...(targetNamespace ? { targetNamespace } : {}),
  }) as Promise<
    {
      name: string
      namespace: string
      ownership: RecipeSecretOwnership
      created: boolean
    } & SecretIdentity
  >
}

export async function updateRecipeSecret(
  name: string,
  data: Record<string, string>,
  removeKeys: string[] = [],
  targetNamespace?: string
) {
  return apiSend('PUT', '/api/v1/admin/recipe-secrets', {
    name,
    data,
    removeKeys,
    ...(targetNamespace ? { targetNamespace } : {}),
  })
}

export async function deleteRecipeSecret(
  name: string,
  targetNamespace: string | undefined,
  identity: SecretIdentity
) {
  const qs = targetNamespace ? `?targetNamespace=${encodeURIComponent(targetNamespace)}` : ''
  return apiSend(
    'DELETE',
    `/api/v1/admin/recipe-secrets/${encodeURIComponent(name)}${qs}`,
    identity
  )
}

// ── LLM model prices (token-budgets P0b) ──────────────────────────────────
// Per-model LLM pricing that backs cost-unit token budgets. Prices are stored
// per 1,000,000 tokens. control-api returns NUMERIC as numbers (mapped server
// side). See control-api/src/services/llmPrices.ts.

export type LlmModelPrice = {
  id: string
  provider: string
  model: string
  input_token_price: number
  output_token_price: number
  cache_read_token_price: number
  cache_write_token_price: number
  currency: string
  effective_from: string
  enabled: boolean
  created_at: string
  updated_at: string
}

export type UnpricedModel = {
  // `null` when the budget scope pins a model but not a provider — the guard
  // reports the model with no specific provider. The UI must accept it.
  provider: string | null
  model: string
}

// Minimal budget reference returned by the 409 price_in_use_by_budget error.
export type BudgetRef = {
  id: string
  name: string
}

function apiErrorBody(err: unknown): Record<string, unknown> | null {
  if (!(err instanceof Error)) return null
  const body = (err as Error & { body?: unknown }).body
  return body && typeof body === 'object' ? (body as Record<string, unknown>) : null
}

function readMcpSecretRollbackRepairIdentity(raw: unknown): McpSecretRollbackRepairIdentity | null {
  if (!raw || typeof raw !== 'object') return null
  const created = raw as Record<string, unknown>
  if (
    typeof created.name !== 'string' ||
    !created.name.trim() ||
    typeof created.namespace !== 'string' ||
    !created.namespace.trim() ||
    typeof created.uid !== 'string' ||
    !created.uid.trim() ||
    typeof created.resourceVersion !== 'string' ||
    !created.resourceVersion.trim()
  ) {
    return null
  }
  return {
    name: created.name,
    namespace: created.namespace,
    uid: created.uid,
    resourceVersion: created.resourceVersion,
  }
}

/**
 * Returns the CAS identity only from the exact MCP Secret repair response.
 * A rejected create can still have persisted the Secret when the server could
 * not record its rollback permit; partial or unrelated errors must not unlock
 * the legacy bodyless-delete compatibility path.
 */
export function getMcpSecretRollbackRepairIdentity(
  err: unknown,
  expectedName: string
): McpSecretRollbackRepairIdentity | null {
  if (!(err instanceof Error) || (err as Error & { status?: unknown }).status !== 503) {
    return null
  }
  const body = apiErrorBody(err)
  if (
    !body ||
    body.error !== 'mcp_secret_rollback_permit_unavailable' ||
    body.outcome !== 'repair_required'
  ) {
    return null
  }
  const identity = readMcpSecretRollbackRepairIdentity(body.created)
  return identity?.name === expectedName ? identity : null
}

function coerceUnpricedModels(raw: unknown): UnpricedModel[] {
  if (!Array.isArray(raw)) return []
  return raw
    .filter((m): m is UnpricedModel => {
      if (!m || typeof m !== 'object') return false
      const provider = (m as UnpricedModel).provider
      // control-api sends provider: null when the scope pins a model but not a
      // provider — accept null OR string, reject anything else.
      return (
        (provider === null || typeof provider === 'string') &&
        typeof (m as UnpricedModel).model === 'string'
      )
    })
    .map(m => ({ provider: m.provider, model: m.model }))
}

/**
 * When a create/update budget request is rejected with 400 `unpriced_models`
 * (a cost budget whose scope pins model(s) that have no active price), returns
 * the offending models. Returns null for any other error so callers can fall
 * back to a generic message.
 */
export function getUnpricedModelsError(err: unknown): UnpricedModel[] | null {
  const body = apiErrorBody(err)
  if (!body || body.error !== 'unpriced_models') return null
  const models = coerceUnpricedModels(body.models)
  // A matched code with an empty/malformed list would leave both the structured
  // and generic banners hidden — fall through to the generic error instead.
  return models.length ? models : null
}

/**
 * When deleting/disabling/re-keying an active price is rejected with 409
 * `price_in_use_by_budget`, returns the cost budgets still pinning it. Returns
 * null for any other error.
 */
export function getBudgetsUsingPrice(err: unknown): BudgetRef[] | null {
  const body = apiErrorBody(err)
  if (!body || body.error !== 'price_in_use_by_budget') return null
  const raw = body.budgets
  if (!Array.isArray(raw)) return null
  const budgets = raw
    .filter(
      (b): b is BudgetRef =>
        Boolean(b) &&
        typeof (b as BudgetRef).id === 'string' &&
        typeof (b as BudgetRef).name === 'string'
    )
    .map(b => ({ id: b.id, name: b.name }))
  // Empty/malformed list → fall through to the generic error banner.
  return budgets.length ? budgets : null
}

export type CreateLlmPriceInput = {
  provider: string
  model: string
  input_token_price: number
  output_token_price: number
  cache_read_token_price: number
  cache_write_token_price: number
  currency: string
  enabled: boolean
}

export type UpdateLlmPriceInput = Partial<CreateLlmPriceInput>

export async function getLlmPrices() {
  return apiGet('/api/v1/admin/llm-prices') as Promise<{ rows: LlmModelPrice[] }>
}

export async function getUnpricedModels() {
  return apiGet('/api/v1/admin/llm-prices/unpriced') as Promise<{ rows: UnpricedModel[] }>
}

export async function getLlmPrice(id: string) {
  return apiGet(`/api/v1/admin/llm-prices/${encodeURIComponent(id)}`) as Promise<LlmModelPrice>
}

export async function createLlmPrice(input: CreateLlmPriceInput) {
  return apiSend('POST', '/api/v1/admin/llm-prices', input) as Promise<LlmModelPrice>
}

export async function updateLlmPrice(id: string, input: UpdateLlmPriceInput) {
  return apiSend(
    'PUT',
    `/api/v1/admin/llm-prices/${encodeURIComponent(id)}`,
    input
  ) as Promise<LlmModelPrice>
}

export async function deleteLlmPrice(id: string) {
  return apiSend('DELETE', `/api/v1/admin/llm-prices/${encodeURIComponent(id)}`)
}

// ── LLM allowed models (allowlist, spec §3-R3) ────────────────────────────
// Operator-declared allowlist of usable models per provider. Source of truth
// is the control-api `llm_allowed_models` table; a mutation also materializes
// the `clerum-llm-allowed-models` ConfigMap consumed by mcp-host/WRC at runtime.
// This replaces the former static `LLM_MODELS_BY_PROVIDER` catalog in lib/llm.ts.
// See control-api/src/routes/admin/llmModels.ts.

export type LlmAllowedModel = {
  id: string
  provider: string
  model: string
  vendor: string | null
  display_name: string | null
  context_window_tokens: number | null
  enabled: boolean
  // Catalog-lifecycle metadata (spec 09 §7, F1). `source` distinguishes an
  // operator-added row ('manual') from one seeded by discovery ('discovery').
  // `stale` marks a discovery row that vanished from the provider's list but is
  // kept (never auto-removed). Older / not-yet-migrated APIs omit these — the
  // fetch layer normalizes them to 'manual' / false so callers never see undefined.
  source: 'manual' | 'discovery'
  stale: boolean
  discovered_at?: string | null
  last_seen_at?: string | null
  created_at: string
  updated_at: string
}

/**
 * Normalizes a raw allowlist row so the catalog-lifecycle fields are always
 * present (spec 09 §7 F1). Tolerates a pre-migration API that omits `source` /
 * `stale`: defaults to `source:'manual', stale:false` so the table renders the
 * same before and after the backend change. Defensive on the wire value too —
 * any non-'discovery' source collapses to 'manual'.
 */
function normalizeLlmAllowedModel(row: LlmAllowedModel): LlmAllowedModel {
  return {
    ...row,
    source: row.source === 'discovery' ? 'discovery' : 'manual',
    stale: row.stale === true,
    discovered_at: row.discovered_at ?? null,
    last_seen_at: row.last_seen_at ?? null,
  }
}

export type CreateLlmModelInput = {
  provider: string
  model: string
  // `null` explicitly clears the optional column; `undefined` omits it.
  vendor?: string | null
  display_name?: string | null
  context_window_tokens?: number | null
  enabled?: boolean
}

export type UpdateLlmModelInput = Partial<CreateLlmModelInput>

/**
 * True when a create/update/delete was rejected with 503 `configmap_write_failed`.
 * The row was persisted (spec §3-R3.4): only the ConfigMap propagation to the
 * cluster is delayed — surface this as a warning, not a save failure.
 *
 * Matches ONLY the machine-readable code. A bare infra 503 (gateway/pod
 * unavailable, no JSON body → no `code`) means the request may never have
 * reached control-api and the row was NOT saved — that must stay a failure.
 */
export function isLlmModelConfigMapDeferred(err: unknown): boolean {
  if (!(err instanceof Error)) return false
  return (err as Error & { code?: string }).code === 'configmap_write_failed'
}

export async function getLlmModels() {
  const res = (await apiGet('/api/v1/admin/llm-models')) as { rows: LlmAllowedModel[] }
  return { rows: (res.rows ?? []).map(normalizeLlmAllowedModel) }
}

export async function getLlmModel(id: string) {
  const row = (await apiGet(
    `/api/v1/admin/llm-models/${encodeURIComponent(id)}`
  )) as LlmAllowedModel
  return normalizeLlmAllowedModel(row)
}

export async function createLlmModel(input: CreateLlmModelInput) {
  return apiSend('POST', '/api/v1/admin/llm-models', input) as Promise<LlmAllowedModel>
}

// A disable (PUT enabled→false) or delete of a referenced model is gated by
// control-api (Fase 3): without `?force` it answers 409 `model_in_use` with the
// impact. Passing `{ force: true }` appends `?force=true`, which the operator
// confirms only after seeing that impact — never automatically.
export async function updateLlmModel(
  id: string,
  input: UpdateLlmModelInput,
  opts: { force?: boolean } = {}
) {
  return apiSend(
    'PUT',
    `/api/v1/admin/llm-models/${encodeURIComponent(id)}`,
    input,
    opts.force ? { force: 'true' } : {}
  ) as Promise<LlmAllowedModel>
}

export async function deleteLlmModel(id: string, opts: { force?: boolean } = {}) {
  return apiSend(
    'DELETE',
    `/api/v1/admin/llm-models/${encodeURIComponent(id)}`,
    undefined,
    opts.force ? { force: 'true' } : {}
  )
}

// ── Model references, 409 impact + operator attention feed ─────────────────
// See control-api/src/services/llmAttention.ts and llmModelImpact.ts. The 409
// `model_in_use` impact body (Fase 3) and each attention item (Fase 5, Pieza C)
// carry the SAME `hostsAffected`/`grantsAffected` shape, so both surfaces render
// the references identically.

/** A Host CR that references a (provider, model) pair, with the matched roles. */
export type ModelHostReference = {
  namespace: string
  name: string
  // 'primary' | 'allowedModels' | 'fallback' — kept as string[] so an unknown
  // role from a newer backend renders rather than being dropped.
  roles: string[]
}

/** A capability grant that references a (provider, model) pair. */
export type ModelGrantReference = {
  id: string
  recipeNamespace: string
  recipeName: string
  capabilityFamily: string
}

/** Live references to a (provider, model) pair, shared by both surfaces. */
export type ModelReferences = {
  hostsAffected: ModelHostReference[]
  grantsAffected: ModelGrantReference[]
}

/**
 * One actionable operator-attention item. `kind` is an OPEN string union — today
 * only `'stale_model_referenced'`; the banner switches on it and ignores kinds
 * it does not recognize. `displayName` is optional (omitted, not null).
 */
export type AdminAttentionItem = ModelReferences & {
  kind: string
  provider: string
  model: string
  displayName?: string
}

/** The `GET /admin/attention` response contract consumed by the banner. */
export type AdminAttentionReport = {
  items: AdminAttentionItem[]
  generatedAt: string
}

/** The 409 `model_in_use` impact body (Fase 3): the model plus its references. */
export type ModelInUseImpact = ModelReferences & {
  provider: string
  model: string
}

function coerceModelHostReferences(raw: unknown): ModelHostReference[] {
  if (!Array.isArray(raw)) return []
  return raw.flatMap(entry => {
    if (!entry || typeof entry !== 'object') return []
    const rec = entry as Record<string, unknown>
    if (typeof rec.namespace !== 'string' || typeof rec.name !== 'string') return []
    const roles = Array.isArray(rec.roles)
      ? rec.roles.filter((r): r is string => typeof r === 'string')
      : []
    return [{ namespace: rec.namespace, name: rec.name, roles }]
  })
}

function coerceModelGrantReferences(raw: unknown): ModelGrantReference[] {
  if (!Array.isArray(raw)) return []
  return raw.flatMap(entry => {
    if (!entry || typeof entry !== 'object') return []
    const rec = entry as Record<string, unknown>
    if (
      typeof rec.id !== 'string' ||
      typeof rec.recipeNamespace !== 'string' ||
      typeof rec.recipeName !== 'string' ||
      typeof rec.capabilityFamily !== 'string'
    ) {
      return []
    }
    return [
      {
        id: rec.id,
        recipeNamespace: rec.recipeNamespace,
        recipeName: rec.recipeName,
        capabilityFamily: rec.capabilityFamily,
      },
    ]
  })
}

// Keep every item whose (kind, provider, model) are strings — including unknown
// kinds, so the banner (not the fetch layer) decides what to render. Malformed
// items are dropped rather than tumbling the whole feed.
function coerceAttentionItem(raw: unknown): AdminAttentionItem[] {
  if (!raw || typeof raw !== 'object') return []
  const rec = raw as Record<string, unknown>
  if (
    typeof rec.kind !== 'string' ||
    typeof rec.provider !== 'string' ||
    typeof rec.model !== 'string'
  ) {
    return []
  }
  const item: AdminAttentionItem = {
    kind: rec.kind,
    provider: rec.provider,
    model: rec.model,
    hostsAffected: coerceModelHostReferences(rec.hostsAffected),
    grantsAffected: coerceModelGrantReferences(rec.grantsAffected),
  }
  if (typeof rec.displayName === 'string') item.displayName = rec.displayName
  return [item]
}

export async function getAdminAttention(): Promise<AdminAttentionReport> {
  const raw = (await apiGet('/api/v1/admin/attention')) as {
    items?: unknown
    generatedAt?: unknown
  }
  return {
    items: Array.isArray(raw.items) ? raw.items.flatMap(coerceAttentionItem) : [],
    generatedAt: typeof raw.generatedAt === 'string' ? raw.generatedAt : '',
  }
}

/**
 * When a disable (PUT enabled→false) or delete is rejected with 409
 * `model_in_use` — the model is still referenced and `?force` was not sent —
 * returns the impact so the caller can show it and offer a forced retry. Returns
 * null for any other error. Mirrors `getBudgetsUsingPrice`: reads the structured
 * `.body` `formatApiError` preserves.
 */
export function getModelInUseImpact(err: unknown): ModelInUseImpact | null {
  if ((err as { status?: number })?.status !== 409) return null
  const body = apiErrorBody(err)
  if (!body || body.error !== 'model_in_use') return null
  const impact = body.impact
  if (!impact || typeof impact !== 'object') return null
  const rec = impact as Record<string, unknown>
  const hostsAffected = coerceModelHostReferences(rec.hostsAffected)
  const grantsAffected = coerceModelGrantReferences(rec.grantsAffected)
  // A matched code with an empty/malformed impact would open the "still in use"
  // confirm with no references to show — fall through to the generic error
  // banner instead, matching getBudgetsUsingPrice/getUnpricedModelsError.
  if (hostsAffected.length === 0 && grantsAffected.length === 0) return null
  return {
    provider: typeof rec.provider === 'string' ? rec.provider : '',
    model: typeof rec.model === 'string' ? rec.model : '',
    hostsAffected,
    grantsAffected,
  }
}

// ── Catalog discovery (spec 09 §7, F2) ────────────────────────────────────
// Discovery pulls the public models.dev catalog into `llm_allowed_models` as
// `source='discovery', enabled=false`. The operator reviews and enables from a
// fresh catalog. These wrappers drive the Discovery Review section on the
// unified /llm-models surface; enable/disable/delete of discovered rows reuse
// the existing update/delete routes above (no dedicated discovery mutation
// endpoint).

// `live` = fetched from the upstream catalog; `vendored` = served from the
// bundled snapshot fallback (upstream unreachable).
export type LlmDiscoverySource = 'live' | 'vendored'

// Result of a sync run: what the reconciliation did to `llm_allowed_models`.
export type LlmDiscoverySyncResult = {
  source: LlmDiscoverySource
  // Catalog acquisition time (when models.dev was fetched/loaded).
  fetchedAt: string
  // DB commit time of this run — matches the status endpoint's `ranAt`, so the
  // "last synced" label is stable across a reload.
  ranAt: string
  added: number
  updated: number
  staled: number
}

// Last-run summary from the optional status endpoint. `null` when discovery has
// never run or the endpoint is not deployed.
export type LlmDiscoveryStatus = {
  ranAt: string
  source: LlmDiscoverySource
  added: number
  updated: number
  staled: number
}

// Runs the catalog sync. Rows are inserted disabled — this never changes what
// the runtime serves; it only refreshes the review queue.
export async function syncDiscovery() {
  return apiSend(
    'POST',
    '/api/v1/admin/llm-models/discovery/sync'
  ) as Promise<LlmDiscoverySyncResult>
}

// Reads the last sync run. The endpoint is optional (spec 09 §7 F2): a missing
// route (404) or an empty body means "never run" — surfaced as `null` rather
// than an error so the page renders without a prior run.
export async function getDiscoveryStatus(): Promise<LlmDiscoveryStatus | null> {
  try {
    // control-api wraps the run in `{ lastRun }` (null when never run).
    const res = (await apiGet('/api/v1/admin/llm-models/discovery/status')) as {
      lastRun: LlmDiscoveryStatus | null
    } | null
    return res?.lastRun ?? null
  } catch (e) {
    if (isSilentApiError(e)) throw e
    if ((e as { status?: number })?.status === 404) return null
    throw e
  }
}

// ── Token budgets (token-budgets P0c) ─────────────────────────────────────
// Budget policies that cap LLM consumption per dimension. In P0c they ship in
// observation mode: the create form defaults new budgets to enforcement 'warn'
// (the server/DB column default stays 'block' per spec). The list/detail
// endpoints attach live `spent`/`remaining`/`unpriced` computed from usage
// rollups; the create/update/patch responses return the bare row (absent).
// See control-api/src/services/budgets/* and routes/admin/budgets.ts.

export type BudgetUnit = 'cost' | 'tokens'
export type BudgetPeriod = 'daily' | 'weekly' | 'monthly'
export type BudgetEnforcement = 'block' | 'warn'

// Mirrors usageReader's `UsageFilters` shape: keys AND, values within a key OR,
// `{}` = global. Keys are restricted server-side to the allowed dimensions.
export type BudgetScope = Record<string, string[]>

export type TokenBudget = {
  id: string
  name: string
  enabled: boolean
  scope: BudgetScope
  unit: BudgetUnit
  currency: string | null
  limit_amount: number
  period: BudgetPeriod
  timezone: string
  min_start_amount: number
  max_task_amount: number | null
  enforcement: BudgetEnforcement
  created_at: string
  updated_at: string
  // Present on list/detail (withSpend); absent on create/update/patch responses.
  spent?: number
  remaining?: number
  unpriced?: UnpricedModel[]
}

export type CreateTokenBudgetInput = {
  name: string
  enabled?: boolean
  scope?: BudgetScope
  unit: BudgetUnit
  currency?: string | null
  limit_amount: number
  period: BudgetPeriod
  timezone?: string
  min_start_amount?: number
  max_task_amount?: number | null
  enforcement?: BudgetEnforcement
}

export type UpdateTokenBudgetInput = Partial<CreateTokenBudgetInput>

export async function getTokenBudgets() {
  return apiGet('/api/v1/admin/budgets') as Promise<{ rows: TokenBudget[] }>
}

export async function getTokenBudget(id: string) {
  return apiGet(`/api/v1/admin/budgets/${encodeURIComponent(id)}`) as Promise<TokenBudget>
}

export async function createTokenBudget(input: CreateTokenBudgetInput) {
  return apiSend('POST', '/api/v1/admin/budgets', input) as Promise<TokenBudget>
}

export async function updateTokenBudget(id: string, input: UpdateTokenBudgetInput) {
  return apiSend(
    'PUT',
    `/api/v1/admin/budgets/${encodeURIComponent(id)}`,
    input
  ) as Promise<TokenBudget>
}

export async function setTokenBudgetEnabled(id: string, enabled: boolean) {
  return apiSend('PATCH', `/api/v1/admin/budgets/${encodeURIComponent(id)}`, {
    enabled,
  }) as Promise<TokenBudget>
}

export async function deleteTokenBudget(id: string) {
  return apiSend('DELETE', `/api/v1/admin/budgets/${encodeURIComponent(id)}`)
}

export async function getContextUsers(contextId: string) {
  return apiGet(`/api/v1/admin/contexts/${encodeURIComponent(contextId)}/users`) as Promise<{
    items?: ContextUser[]
  }>
}

export async function getContextTeams(contextId: string) {
  return apiGet(`/api/v1/admin/contexts/${encodeURIComponent(contextId)}/teams`) as Promise<{
    items?: ContextTeam[]
  }>
}

export async function getAgentUsers(agentName: string) {
  return apiGet(`/api/v1/admin/agents/${encodeURIComponent(agentName)}/users`) as Promise<{
    items?: AgentUser[]
  }>
}

export async function getAgentTeams(agentName: string) {
  return apiGet(`/api/v1/admin/agents/${encodeURIComponent(agentName)}/teams`) as Promise<{
    items?: AgentTeam[]
  }>
}

/**
 * Replace the full set of users authorized for an agent in a single atomic call.
 * Used when creating or editing an agent. Prefer this over looping
 * updateAdminUserAgents() for each user — it's atomic, idempotent, and
 * avoids race conditions with concurrent admins.
 */
export async function updateAgentUsers(agentName: string, userIds: string[]) {
  return apiSend('PUT', `/api/v1/admin/agents/${encodeURIComponent(agentName)}/users`, {
    userIds,
  }) as Promise<{ agentName: string; userIds: string[] }>
}

/**
 * Replace the full set of teams authorized for an agent in a single atomic call.
 * Mirrors updateAgentUsers for team-level access.
 */
export async function updateAgentTeams(agentName: string, teamIds: string[]) {
  return apiSend('PUT', `/api/v1/admin/agents/${encodeURIComponent(agentName)}/teams`, {
    teamIds,
  }) as Promise<{ agentName: string; teamIds: string[] }>
}

export async function getAdminUserContexts(userId: string) {
  return apiGet(
    `/api/v1/admin/users/${encodeURIComponent(userId)}/contexts`
  ) as Promise<UserContextAccess>
}

export async function updateAdminUserContexts(userId: string, contextIds: string[]) {
  return apiSend('PUT', `/api/v1/admin/users/${encodeURIComponent(userId)}/contexts`, {
    contextIds,
  }) as Promise<UserContextAccess>
}

export async function getAdminUserAgents(userId: string) {
  return apiGet(
    `/api/v1/admin/users/${encodeURIComponent(userId)}/agents`
  ) as Promise<UserAgentAccess>
}

export async function updateAdminUserAgents(
  userId: string,
  agentNames: string[],
  expectedCurrentAgentNames: string[]
) {
  return apiSend('PUT', `/api/v1/admin/users/${encodeURIComponent(userId)}/agents`, {
    agentNames,
    expectedCurrentAgentNames,
  }) as Promise<UserAgentAccess>
}

export async function getAdminUserTeams(userId: string) {
  return apiGet(`/api/v1/admin/users/${encodeURIComponent(userId)}/teams`) as Promise<{
    currentTeamId?: string
    items?: TeamSummary[]
  }>
}

export async function getAdminTeams() {
  return apiGet('/api/v1/admin/teams') as Promise<{ items?: TeamListItem[] }>
}

export async function getAdminTeam(teamId: string) {
  return apiGet(`/api/v1/admin/teams/${encodeURIComponent(teamId)}`) as Promise<{
    id: string
    name: string
  }>
}

export async function getAdminTeamContexts(teamId: string) {
  return apiGet(
    `/api/v1/admin/teams/${encodeURIComponent(teamId)}/contexts`
  ) as Promise<TeamContextAccess>
}

export async function updateAdminTeamContexts(teamId: string, contextIds: string[]) {
  return apiSend('PUT', `/api/v1/admin/teams/${encodeURIComponent(teamId)}/contexts`, {
    contextIds,
  }) as Promise<TeamContextAccess>
}

export async function getAdminTeamAgents(teamId: string) {
  return apiGet(
    `/api/v1/admin/teams/${encodeURIComponent(teamId)}/agents`
  ) as Promise<TeamAgentAccess>
}

export async function updateAdminTeamAgents(
  teamId: string,
  agentNames: string[],
  expectedCurrentAgentNames: string[]
) {
  return apiSend('PUT', `/api/v1/admin/teams/${encodeURIComponent(teamId)}/agents`, {
    agentNames,
    expectedCurrentAgentNames,
  }) as Promise<TeamAgentAccess>
}

export async function getAdminUserContext(userId: string) {
  return apiGet(
    `/api/v1/admin/users/${encodeURIComponent(userId)}/context`
  ) as Promise<AdminUserContext>
}

export async function updateAdminUserContext(
  userId: string,
  payload: { email: string; name?: string; channels: AdminUserChannels }
) {
  return apiSend(
    'PUT',
    `/api/v1/admin/users/${encodeURIComponent(userId)}/context`,
    payload
  ) as Promise<AdminUserContext>
}

export async function getAdminTeamMembers(teamId: string) {
  return apiGet(`/api/v1/admin/teams/${encodeURIComponent(teamId)}/members`) as Promise<{
    items?: TeamMember[]
  }>
}

export async function getAdminTeamPendingInvitations(teamId: string) {
  return apiGet(`/api/v1/admin/teams/${encodeURIComponent(teamId)}/invitations`) as Promise<{
    items?: AdminTeamPendingInvitation[]
  }>
}

export async function getAdminAllPendingInvitations() {
  return apiGet('/api/v1/admin/pending-invitations') as Promise<{
    items?: AdminPendingInvitationListItem[]
  }>
}

export async function revokeAdminTeamInvitation(
  teamId: string | null | undefined,
  invitationId: string
) {
  if (!teamId) {
    return apiSend(
      'DELETE',
      `/api/v1/admin/invitations/${encodeURIComponent(invitationId)}`
    ) as Promise<{ revoked: boolean; id: string; email: string }>
  }
  return apiSend(
    'DELETE',
    `/api/v1/admin/teams/${encodeURIComponent(teamId)}/invitations/${encodeURIComponent(invitationId)}`
  ) as Promise<{ revoked: boolean; id: string; email: string }>
}

export async function createAdminTeam(name: string) {
  return apiSend('POST', '/api/v1/admin/teams', { name }) as Promise<{
    id: string
    name: string
  }>
}

export async function addAdminTeamMember(teamId: string, userId: string, role: TeamRole) {
  return apiSend('POST', `/api/v1/admin/teams/${encodeURIComponent(teamId)}/members`, {
    userId,
    role,
  })
}

export async function renameAdminTeam(teamId: string, name: string) {
  return apiSend('PUT', `/api/v1/admin/teams/${encodeURIComponent(teamId)}/name`, { name })
}

export async function inviteAdminTeamMember(
  teamId: string | null | undefined,
  payload: {
    name: string
    email: string
    role: InviteRole
    teams?: Array<{ teamId: string; role: InviteRole }>
  }
) {
  if (!teamId) {
    return apiSend('POST', '/api/v1/admin/invitations', payload) as Promise<{
      id: string
      team_id: string | null
      invitee_name: string | null
      email: string
      role: InviteRole
      token: string
      status: 'pending'
      created_at: string
    }>
  }
  return apiSend(
    'POST',
    `/api/v1/admin/teams/${encodeURIComponent(teamId)}/invitations`,
    payload
  ) as Promise<{
    id: string
    team_id: string | null
    invitee_name: string | null
    email: string
    role: InviteRole
    token: string
    status: 'pending'
    created_at: string
  }>
}

export async function resendAdminTeamInvitation(
  teamId: string | null | undefined,
  invitationId: string
) {
  if (!teamId) {
    return apiSend(
      'POST',
      `/api/v1/admin/invitations/${encodeURIComponent(invitationId)}/resend`
    ) as Promise<{ sent: true; id: string; email: string }>
  }
  return apiSend(
    'POST',
    `/api/v1/admin/teams/${encodeURIComponent(teamId)}/invitations/${encodeURIComponent(invitationId)}/resend`
  ) as Promise<{ sent: true; id: string; email: string }>
}

export async function resendAdminUserPasswordSetupInvitation(userId: string) {
  return apiSend(
    'POST',
    `/api/v1/admin/users/${encodeURIComponent(userId)}/invitations/password-setup/resend`
  ) as Promise<{ sent: true; id: string; email: string; teamId: string | null }>
}

export async function updateAdminMemberRole(teamId: string, userId: string, role: TeamRole) {
  return apiSend(
    'PATCH',
    `/api/v1/admin/teams/${encodeURIComponent(teamId)}/members/${encodeURIComponent(userId)}/role`,
    { role }
  )
}

export async function deleteAdminMember(teamId: string, userId: string) {
  return apiSend(
    'DELETE',
    `/api/v1/admin/teams/${encodeURIComponent(teamId)}/members/${encodeURIComponent(userId)}`
  )
}

/** Hard-deletes the team and cascades memberships, invitations, team context/agent links. */
export async function deleteAdminTeam(teamId: string) {
  return apiSend('DELETE', `/api/v1/admin/teams/${encodeURIComponent(teamId)}`) as Promise<{
    deleted: boolean
    id: string
  }>
}

export type DeleteAdminUserRequest = {
  /** Persisted with the governed retirement operation for its audit trail. */
  reason?: string
  /** Reuse this on a transport retry of the same user action. */
  idempotencyKey?: string
  /** Connects the browser request to the Control API retirement audit row. */
  correlationId?: string
}

const UUID_ANY_RE = /^[0-9a-f]{8}-[0-9a-f]{4}-[1-5][0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$/i

function generateRetirementRequestId(): string {
  if (typeof crypto !== 'undefined' && typeof crypto.randomUUID === 'function') {
    return crypto.randomUUID()
  }
  // The Control API accepts a correlation header only when it is UUID-shaped.
  // This compatibility branch keeps embedded/legacy browser retries traceable.
  return 'xxxxxxxx-xxxx-4xxx-yxxx-xxxxxxxxxxxx'.replace(/[xy]/g, marker => {
    const nibble = Math.floor(Math.random() * 16)
    return (marker === 'x' ? nibble : (nibble & 0x3) | 0x8).toString(16)
  })
}

/** Creates one stable request identity for all transport retries in a UI operation. */
export function createDeleteAdminUserRequest(
  reason = 'control_ui_user_retirement'
): Required<DeleteAdminUserRequest> {
  return {
    reason,
    idempotencyKey: generateRetirementRequestId(),
    correlationId: generateRetirementRequestId(),
  }
}

/**
 * Retires the user through the governed lifecycle contract. A caller may retain
 * the supplied key when retrying the same action; an ordinary UI action gets a
 * new request identity and an explicit audit reason.
 */
export async function deleteAdminUser(userId: string, request: DeleteAdminUserRequest = {}) {
  const idempotencyKey = request.idempotencyKey?.trim() || generateRetirementRequestId()
  const providedCorrelationId = request.correlationId?.trim() || ''
  const correlationId = UUID_ANY_RE.test(providedCorrelationId)
    ? providedCorrelationId.toLowerCase()
    : generateRetirementRequestId()
  const reason = request.reason?.trim() || 'control_ui_user_retirement'
  return apiSend(
    'DELETE',
    `/api/v1/admin/users/${encodeURIComponent(userId)}`,
    { reason },
    {},
    {
      'Idempotency-Key': idempotencyKey,
      'x-correlation-id': correlationId,
    }
  ) as Promise<{
    deleted: boolean
    id: string
  }>
}

// ── WorkflowRecipe types ─────────────────────────────────────────────────────

export type WorkflowRecipePhase =
  | 'candidate'
  | 'pending-approval'
  | 'approved'
  | 'pending'
  | 'pending-operator-input'
  | 'deploying'
  | 'testing'
  | 'active'
  | 'degraded'
  | 'rolling-back'
  | 'failed'
  | 'deprecated'
  | 'rollback-failed'

export type WorkflowExecutionPhase =
  | 'pending'
  | 'initializing'
  | 'running'
  | 'completed'
  | 'failed'
  | 'cancelled'
  | 'recovering'

export type WorkflowRecipeStatus = {
  phase?: WorkflowRecipePhase
  workloads?: Array<{ id: string; ready: boolean; replicas?: number }>
  message?: string
  workflowExecution?: { phase?: WorkflowExecutionPhase; [key: string]: unknown }
  [key: string]: unknown
}

export type WorkflowRecipeResource = {
  apiVersion?: string
  kind?: string
  metadata?: {
    name: string
    namespace?: string
    creationTimestamp?: string
    labels?: Record<string, string>
    annotations?: Record<string, string>
  }
  spec?: Record<string, unknown>
  status?: WorkflowRecipeStatus
}

export type PendingWorkflowCredentialRef = {
  kind: string
  secretName: string
  namespace: string
  keys: string[]
  field: string
  fields?: string[]
}

export type WorkflowRecipeMutationResponse = WorkflowRecipeResource & {
  pendingCredentials?: PendingWorkflowCredentialRef[]
}

// ── WorkflowRecipe API functions ──────────────────────────────────────────────

export async function getRecipes() {
  return apiGet('/api/v1/admin/recipes') as Promise<{ items?: WorkflowRecipeResource[] }>
}

export async function getRecipe(name: string) {
  return apiGet(
    `/api/v1/admin/recipes/${encodeURIComponent(name)}`
  ) as Promise<WorkflowRecipeResource>
}

export async function createRecipe(payload: {
  metadata: { name: string; namespace?: string; annotations?: Record<string, string> }
  spec: Record<string, unknown>
}) {
  return apiSend(
    'POST',
    '/api/v1/admin/recipes',
    payload
  ) as Promise<WorkflowRecipeMutationResponse>
}

export type ServerValidationError = {
  field: string
  message: string
  // Set for policy/invariant violations (e.g. agenticWorkflowContextRefBlocked).
  // Undefined for structural errors from validateRecipeBody.
  rule?: string
}

export type ServerValidationResult =
  | { valid: true; pendingCredentials?: PendingWorkflowCredentialRef[] }
  | { valid: false; errors: ServerValidationError[] }

// Server-side recipe validation (distinct from the client-side parser in
// `lib/recipeValidator.ts` which only checks JSON shape). Runs the same
// structural checks as `POST /recipes` plus policy invariants that require
// cluster state (e.g. matching WorkflowRecipePolicy existence).
//
// Uses `fetch` directly (NOT `apiSend`) because 422 is a legitimate business
// response — the backend returns `{ valid: false, errors }` at 422 for both
// structural and policy rejections. `apiSend` would throw on any non-2xx,
// forcing callers into try/catch for the normal "invalid recipe" path.
// Other HTTP errors (401, 5xx) still throw so the editor can soft-fail and
// let the reconciler catch at L4.
export async function validateRecipeServer(
  recipe: {
    metadata: { name: string; namespace?: string; annotations?: Record<string, string> }
    spec: Record<string, unknown>
  },
  opts: { mode?: 'create' | 'edit' } = {}
): Promise<ServerValidationResult> {
  // `mode=edit` tells the server to skip the name-collision check — the
  // recipe is expected to exist. Default 'create' is the stricter path.
  const mode = opts.mode === 'edit' ? 'edit' : 'create'
  const res = await fetch(`${API_BASE}/api/v1/admin/recipes/validate?mode=${mode}`, {
    method: 'POST',
    headers: { 'Content-Type': 'application/json', ...authHeaders() },
    body: JSON.stringify(recipe),
  })
  if (res.status === 200 || res.status === 422) {
    return (await res.json()) as ServerValidationResult
  }
  if (res.status === 401) {
    handleUnauthorized()
  }
  const text = await res.text()
  throw new Error(`${res.status} ${res.statusText} - ${text}`)
}

export async function updateRecipe(
  name: string,
  payload: {
    spec: Record<string, unknown>
    metadata?: { annotations?: Record<string, string> }
  }
) {
  return apiSend(
    'PUT',
    `/api/v1/admin/recipes/${encodeURIComponent(name)}`,
    payload
  ) as Promise<WorkflowRecipeMutationResponse>
}

export async function deleteRecipe(name: string) {
  return apiSend('DELETE', `/api/v1/admin/recipes/${encodeURIComponent(name)}`)
}

export async function retryRecipe(name: string) {
  return apiSend('POST', `/api/v1/admin/recipes/${encodeURIComponent(name)}/retry`) as Promise<{
    name: string
    phase: string
  }>
}

export async function getRecipeStatus(name: string) {
  return apiGet(
    `/api/v1/admin/recipes/${encodeURIComponent(name)}/status`
  ) as Promise<WorkflowRecipeStatus>
}

// ── Recipe OAuth (Path B — background OAuth) ─────────────────────────────────
//
// Admin-only "connect for the recipe" surface. The connect route mints a
// `service` authorize URL the operator opens in a browser; status/disconnect
// inspect and revoke the recipe-owned grant.

export async function getRecipeOauthStatus(
  recipeName: string,
  oauthClientId: string
): Promise<{ connected: boolean }> {
  return apiGet(
    `/api/v1/admin/recipes/${encodeURIComponent(recipeName)}/oauth/${encodeURIComponent(oauthClientId)}/status`
  ) as Promise<{ connected: boolean }>
}

export async function connectRecipeOauth(
  recipeName: string,
  oauthClientId: string
): Promise<{ authorizeUrl: string }> {
  return apiSend(
    'POST',
    `/api/v1/admin/recipes/${encodeURIComponent(recipeName)}/oauth/${encodeURIComponent(oauthClientId)}/connect`
  ) as Promise<{ authorizeUrl: string }>
}

// DELETE returns 204 with no body — apiSend's res.json() would throw on the
// empty response, so this one calls fetch directly.
export async function disconnectRecipeOauth(
  recipeName: string,
  oauthClientId: string
): Promise<void> {
  const res = await fetch(
    `${API_BASE}/api/v1/admin/recipes/${encodeURIComponent(recipeName)}/oauth/${encodeURIComponent(oauthClientId)}/grant`,
    { method: 'DELETE', headers: { ...authHeaders() } }
  )
  if (!res.ok) {
    if (res.status === 401) handleUnauthorized()
    const text = await res.text()
    const error = new Error(`${res.status} ${res.statusText} - ${text}`)
    ;(error as Error & { status?: number }).status = res.status
    throw error
  }
}

// ── Per-user grant oversight (admin read-only list + force-revoke) ────────────
//
// Lists individual user grants for a specific background OAuth client, and lets
// an admin force-revoke any user's grant. Additive — does not change the
// existing service-grant connect/disconnect surface.

export type UserGrant = { userId: string; background: boolean; updatedAt: string }

export async function adminListUserGrants(
  recipeName: string,
  oauthClientId: string
): Promise<{ users: UserGrant[] }> {
  return apiGet(
    `/api/v1/admin/recipes/${encodeURIComponent(recipeName)}/oauth/${encodeURIComponent(oauthClientId)}/user-grants`
  ) as Promise<{ users: UserGrant[] }>
}

// DELETE returns 204 with no body — call fetch directly (same pattern as disconnectRecipeOauth).
export async function adminRevokeUserGrant(
  recipeName: string,
  oauthClientId: string,
  userId: string
): Promise<void> {
  const res = await fetch(
    `${API_BASE}/api/v1/admin/recipes/${encodeURIComponent(recipeName)}/oauth/${encodeURIComponent(oauthClientId)}/user-grants/${encodeURIComponent(userId)}`,
    { method: 'DELETE', headers: { ...authHeaders() } }
  )
  if (!res.ok) {
    if (res.status === 401) handleUnauthorized()
    const text = await res.text()
    const error = new Error(`${res.status} ${res.statusText} - ${text}`)
    ;(error as Error & { status?: number }).status = res.status
    throw error
  }
}

export type RecipePodContainer = {
  name: string
  ready: boolean
  state: 'waiting' | 'terminated' | 'running'
  reason: string | null
  message: string | null
  restartCount: number
}

export type RecipePod = {
  name: string
  namespace: string
  workloadId: string | null
  phase: string
  reason: string | null
  message: string | null
  restarts: number
  createdAt: string | null
  containers: RecipePodContainer[]
}

export async function getRecipePods(name: string): Promise<{ pods: RecipePod[] }> {
  return apiGet(`/api/v1/admin/recipes/${encodeURIComponent(name)}/pods`) as Promise<{
    pods: RecipePod[]
  }>
}

export type ArtifactInfo = {
  name: string
  format: string
  sizeBytes: number
  path?: string
  createdAt: string
}

export async function getRecipeArtifacts(name: string) {
  return apiGet(`/api/v1/admin/recipes/${encodeURIComponent(name)}/artifacts`) as Promise<{
    artifacts: ArtifactInfo[]
  }>
}

export function getArtifactDownloadUrl(recipeName: string, artifactName: string): string {
  return `${API_BASE}/api/v1/admin/recipes/${encodeURIComponent(recipeName)}/artifacts/${encodeURIComponent(artifactName)}/download`
}

export function getWorkflowRunArtifactDownloadUrl(
  namespace: string,
  name: string,
  runId: string,
  artifactName: string
): string {
  return `${API_BASE}/api/v1/admin/workflows/${encodeURIComponent(namespace)}/${encodeURIComponent(name)}/runs/${encodeURIComponent(runId)}/artifacts/${encodeURIComponent(artifactName)}/download`
}

export async function getWorkflowRunArtifacts(
  namespace: string,
  name: string,
  runId: string
): Promise<{ artifacts: ArtifactInfo[] }> {
  return apiGet(
    `/api/v1/admin/workflows/${encodeURIComponent(namespace)}/${encodeURIComponent(name)}/runs/${encodeURIComponent(runId)}/artifacts`
  ) as Promise<{ artifacts: ArtifactInfo[] }>
}

// ── Workflow runs (admin-only) ─────────────────────────────────────────────
// Per-recipe list of WorkflowRun rows, ordered newest-first. Backed by
// `GET /api/v1/admin/workflows/:ns/:name/runs?limit=N`. Combines live DB rows
// with audit-only rows for runs that finished and got purged from the live
// table — server-side dedup happens by run_id.

export type WorkflowRunSummary = {
  id: string
  source: 'live' | 'audit' | 'status' | string
  approvalRequestId?: string | null
  phase: string
  triggeredAt: string | null
  startedAt: string | null
  completedAt: string | null
  message: string | null
  actor: { type?: string; userId?: string; adminUserId?: string; hostRef?: string } | null
  executionRef: { namespace: string; name: string } | null

  // Legacy/older UI callers tolerated these fields before Control API moved
  // workflow run reads to the canonical DTO. Keep them optional so current API
  // responses type-check while older fixtures still render.
  recipeNamespace?: string
  recipeName?: string
  triggerSource?: 'onDemand' | 'schedule' | 'autonomous' | string
  finalPhase?: string | null
  errorMessage?: string | null
  triggerer?: { kind?: string; userId?: string; hostRef?: string } | null
}

export async function getWorkflowRuns(
  namespace: string,
  name: string,
  limit = 20
): Promise<{ items: WorkflowRunSummary[]; count: number }> {
  return apiGet(
    `/api/v1/admin/workflows/${encodeURIComponent(namespace)}/${encodeURIComponent(name)}/runs?limit=${limit}`
  ) as Promise<{ items: WorkflowRunSummary[]; count: number }>
}

export async function getWorkflowRun(
  namespace: string,
  name: string,
  runId: string,
  signal?: AbortSignal
): Promise<WorkflowRunSummary> {
  return apiGet(
    `/api/v1/admin/workflows/${encodeURIComponent(namespace)}/${encodeURIComponent(name)}/runs/${encodeURIComponent(runId)}`,
    {},
    { signal }
  ) as Promise<WorkflowRunSummary>
}

// ── Workflow grants (admin-only) ───────────────────────────────────────────
// Per-recipe list of users authorized to trigger the workflow from the
// Desktop App. Backed by `PUT /api/v1/admin/workflows/:ns/:name/grants`
// with bulk-replace semantics (mirrors `/admin/agents/:agentName/users`).
// See .ralph/plans/whimsical-mixing-pine.md for context.

export type WorkflowGrantUser = {
  id: string
  email: string
  name: string | null
  displayName: string | null
}

export type WorkflowGrantTeam = {
  id: string
  name: string
}

export type WorkflowApprovalAllowedTeam = {
  id: string
  name: string
  createdAt: string
}

export async function listWorkflowGrants(ns: string, name: string) {
  return apiGet(
    `/api/v1/admin/workflows/${encodeURIComponent(ns)}/${encodeURIComponent(name)}/grants`
  ) as Promise<{ items: WorkflowGrantUser[] }>
}

export async function setWorkflowGrants(ns: string, name: string, userIds: string[]) {
  return apiSend(
    'PUT',
    `/api/v1/admin/workflows/${encodeURIComponent(ns)}/${encodeURIComponent(name)}/grants`,
    { userIds }
  ) as Promise<{ userIds: string[] }>
}

export async function listWorkflowTeamGrants(ns: string, name: string) {
  return apiGet(
    `/api/v1/admin/workflows/${encodeURIComponent(ns)}/${encodeURIComponent(name)}/team-grants`
  ) as Promise<{ items: WorkflowGrantTeam[] }>
}

export async function setWorkflowTeamGrants(ns: string, name: string, teamIds: string[]) {
  return apiSend(
    'PUT',
    `/api/v1/admin/workflows/${encodeURIComponent(ns)}/${encodeURIComponent(name)}/team-grants`,
    { teamIds }
  ) as Promise<{ teamIds: string[]; added: string[]; removed: string[] }>
}

export async function listWorkflowApprovalAllowedTeams(ns: string, name: string) {
  return apiGet(
    `/api/v1/admin/workflow-recipes/${encodeURIComponent(ns)}/${encodeURIComponent(
      name
    )}/allowed-teams`
  ) as Promise<{ items: WorkflowApprovalAllowedTeam[] }>
}

export async function allowWorkflowApprovalTeam(ns: string, name: string, teamId: string) {
  return apiSend(
    'PUT',
    `/api/v1/admin/workflow-recipes/${encodeURIComponent(ns)}/${encodeURIComponent(
      name
    )}/allowed-teams/${encodeURIComponent(teamId)}`
  ) as Promise<{ teamId: string }>
}

export async function revokeWorkflowApprovalTeam(ns: string, name: string, teamId: string) {
  return apiSend(
    'DELETE',
    `/api/v1/admin/workflow-recipes/${encodeURIComponent(ns)}/${encodeURIComponent(
      name
    )}/allowed-teams/${encodeURIComponent(teamId)}`
  ) as Promise<{ teamId: string }>
}

export async function deleteRecipeArtifact(recipeName: string, artifactName: string) {
  const url = `${API_BASE}/api/v1/admin/recipes/${encodeURIComponent(recipeName)}/artifacts/${encodeURIComponent(artifactName)}`
  const resp = await fetch(url, {
    method: 'DELETE',
    credentials: 'include',
  })
  if (!resp.ok) {
    const errBody = await resp.text()
    throw new Error(`${resp.status}: ${errBody}`)
  }
}

export async function deleteAllRecipeArtifacts(recipeName: string) {
  const url = `${API_BASE}/api/v1/admin/recipes/${encodeURIComponent(recipeName)}/artifacts`
  const resp = await fetch(url, {
    method: 'DELETE',
    credentials: 'include',
  })
  if (!resp.ok) {
    const errBody = await resp.text()
    throw new Error(`${resp.status}: ${errBody}`)
  }
}

export async function deleteWorkflowRunArtifact(
  namespace: string,
  name: string,
  runId: string,
  artifactName: string
) {
  const url = `${API_BASE}/api/v1/admin/workflows/${encodeURIComponent(namespace)}/${encodeURIComponent(name)}/runs/${encodeURIComponent(runId)}/artifacts/${encodeURIComponent(artifactName)}`
  const resp = await fetch(url, {
    method: 'DELETE',
    credentials: 'include',
  })
  if (!resp.ok) {
    const errBody = await resp.text()
    throw new Error(`${resp.status}: ${errBody}`)
  }
}

export async function deleteWorkflowRunArtifacts(namespace: string, name: string, runId: string) {
  const url = `${API_BASE}/api/v1/admin/workflows/${encodeURIComponent(namespace)}/${encodeURIComponent(name)}/runs/${encodeURIComponent(runId)}/artifacts`
  const resp = await fetch(url, {
    method: 'DELETE',
    credentials: 'include',
  })
  if (!resp.ok) {
    const errBody = await resp.text()
    throw new Error(`${resp.status}: ${errBody}`)
  }
}

// ── Host (chat mode) artifact API functions ───────────────────────────────────

export type HostArtifactInfo = {
  name: string
  format: string
  sizeBytes: number
  createdAt: string
}
export type WorkflowOutputRow = {
  recipeName: string
  namespace: string
  runId: string
  fileName: string
  format: string
  sizeBytes?: number
  completedAt: string
}
export type ChatArtifactOutputRow = {
  hostRef: string
  fileName: string
  format: string
  sizeBytes: number
  createdAt: string
}
export type AdminOutputsOverview = {
  workflowOutputs: WorkflowOutputRow[]
  chatArtifacts: ChatArtifactOutputRow[]
  warnings?: string[]
}

export async function getHostArtifacts(hostRef: string) {
  return apiGet(`/api/v1/admin/hosts/${encodeURIComponent(hostRef)}/artifacts`) as Promise<{
    artifacts: HostArtifactInfo[]
    hostRef: string
    podName: string
  }>
}

export function getHostArtifactDownloadUrl(hostRef: string, artifactName: string): string {
  return `${API_BASE}/api/v1/admin/hosts/${encodeURIComponent(hostRef)}/artifacts/${encodeURIComponent(artifactName)}/download`
}

export async function getAdminOutputsOverview() {
  return apiGet('/api/v1/admin/outputs') as Promise<AdminOutputsOverview>
}

export function safeJson(value: unknown): string {
  return JSON.stringify(
    value,
    (key, val) => {
      const k = key.toLowerCase()
      if (
        k.includes('secret') ||
        k.includes('token') ||
        k.includes('password') ||
        k.includes('stringdata') ||
        k === 'data' ||
        k === 'stringData'
      ) {
        return '[REDACTED]'
      }
      return val
    },
    2
  )
}

// ────────────────────────────────────────────────────────────────────
// Registry — BFF client for /api/v1/admin/registry/* on control-api
// Mirrors snake_case shapes returned by the Clerum Registry service
// (see control-api/src/services/registryClient.ts and the unified
// spec in MiVault: projects/clerum/wro/clerum-registry-unified-specification.md).
// ────────────────────────────────────────────────────────────────────

export type RegistryEntry = {
  id: string
  name: string
  version: string
  entry_type: string // "mcp-server" | "recipe" | "llm-hook"
  description: string
  author: string
  origin: string
  category: string
  tags: string[]
  trust_level: string // "high" | "mid" | "low"
  quality_tier: string // "verified" | "unverified"
  visibility?: 'public' | 'private' // present on full registry rows; absent on older/partial rows
  status: string // "published" | "deprecated" | "removed"
  server_mode: string | null // "local" | "remote" (mcp-server entries)
  transport: string | null // "streamableHttp" | "sse" | "stdio"
  recipe_type: string | null // "workflow" | "only-workloads"
  mcp_server_meta:
    | (Record<string, unknown> & {
        credentialSchema?: CredentialSchema
        tools?: string[]
        remoteEndpoints?: Array<{ url: string; region?: string; description?: string }>
        egressSummary?: { domains?: string[]; ports?: number[]; wideCidr?: boolean }
        authHeaders?: Record<string, string>
      })
    | null
  recipe_meta:
    | (Record<string, unknown> & {
        recipeYaml?: string
        stepCount?: number
      })
    | null
  // Present on `entry_type: "llm-hook"` (guardrail hook) entries. Mirrors the
  // registry's hook_meta shape: where the hook runs (image/service/remote), which
  // lifecycle points it hooks, the callback path, its credential schema, default
  // config, and any egress it requires. See control-api install-hook contract.
  hook_meta?:
    | (Record<string, unknown> & {
        // Exactly one of image | service | remote — each an object, not a string.
        target?: {
          image?: { ref?: string; port?: number; security?: { addCapabilities?: string[] } }
          service?: { name?: string; namespace?: string; port?: number }
          remote?: { baseUrl?: string }
        }
        // The CRD enumerates six: the four LLM-lane points below plus the tool
        // lane's preToolUse/postToolUse.
        lifecyclePoints?: string[] // "preCall" | "moderate" | "postCallSuccess" | "onError" | "preToolUse" | "postToolUse"
        path?: string
        credentialSchema?: CredentialSchema
        defaultConfig?: Record<string, unknown>
        requiredEgress?: unknown
        // What the hook author says the hook needs to function. Advisory: it
        // seeds the install form, but the operator's selection is the grant and
        // stays bounded by Host.spec.guardrails.capabilityCeiling.
        requiredCapabilities?: HookCapability[]
        // The author's suggested runtime posture, used to pre-fill the install
        // form. `orderHint` is a word, not the CRD's numeric `order`.
        authorDefaults?: {
          failMode?: 'open' | 'closed'
          orderHint?: string
          timeoutMs?: number
          onUnavailable?: {
            mode?: 'strict' | 'breaker'
            failureThreshold?: number
            cooldownMs?: number
          }
        }
      })
    | null
  artifact_refs: Record<string, unknown> | null
  downloads: number
  installs: number
  created_at: string
}

export type CredentialKey = {
  name: string // e.g. "API_KEY"
  label: string // human-readable label
  kind: string // "api-key" | "oauth-token" | "connection-string" | "password" | "text"
  semanticType?: string
  description?: string
  enumValues?: string[]
}

export type CredentialSchema = {
  required: boolean
  authType: string // "api-key" | "bearer-token" | "connection-string" | "platform-credentials" | "none"
  keys: CredentialKey[]
}

export type RegistrySearchParams = {
  q?: string
  entryType?: string
  category?: string
  serverMode?: string
  transport?: string
  trustLevel?: string
  sort?: string
  limit?: string
  offset?: string
}

export type RegistryEntryListResponse = {
  data: RegistryEntry[]
  // `meta` is optional; when present, only `total` is guaranteed. `limit` and
  // `offset` are only returned when the BFF paginates explicitly — keeping them
  // optional matches the real wire contract and avoids forcing callers to
  // fabricate pagination state they don't use (e.g. RegistryCatalog reads only
  // `meta.total` for the "X of Y" counter).
  meta?: { total: number; limit?: number; offset?: number }
}
export type RegistryInstalledState = {
  catalogKeys: string[]
  serverNames: string[]
  recipeKeys: string[]
  hookKeys?: string[]
}
export type RegistryCatalogResponse = RegistryEntryListResponse & {
  categories: string[]
  installed: RegistryInstalledState
}

// The registry's `tags` column is nullable, so an entry can arrive with
// `tags: null`. RegistryCatalog and the entry detail page call
// entry.tags.length / .some / .map directly, so a null crashes the whole page
// with "Cannot read properties of null (reading 'length')". Coerce tags to a
// real array at the wrapper boundary so RegistryEntry.tags is always the
// string[] its type claims.
function normalizeRegistryEntry(entry: RegistryEntry): RegistryEntry {
  return Array.isArray(entry.tags) ? entry : { ...entry, tags: [] }
}

export async function getRegistryEntries(
  params: RegistrySearchParams = {}
): Promise<RegistryEntryListResponse> {
  const res = (await apiGet('/api/v1/admin/registry/entries', params)) as RegistryEntryListResponse
  return { ...res, data: (res?.data ?? []).map(normalizeRegistryEntry) }
}

export async function getRegistryCatalog(
  params: RegistrySearchParams = {}
): Promise<RegistryCatalogResponse> {
  const res = (await apiGet('/api/v1/admin/registry/catalog', params)) as RegistryCatalogResponse
  return { ...res, data: (res?.data ?? []).map(normalizeRegistryEntry) }
}

export async function getRegistryEntryVersion(
  name: string,
  version: string
): Promise<RegistryEntry> {
  const entry = (await apiGet(
    `/api/v1/admin/registry/entries/${encodeURIComponent(name)}/versions/${encodeURIComponent(version)}`
  )) as RegistryEntry
  return normalizeRegistryEntry(entry)
}

export async function getRegistryCategories(): Promise<{ data: string[] }> {
  return apiGet('/api/v1/admin/registry/categories') as Promise<{ data: string[] }>
}

export async function getRegistryCredentialSchema(
  name: string,
  version: string
): Promise<CredentialSchema> {
  return apiGet(
    `/api/v1/admin/registry/entries/${encodeURIComponent(name)}/versions/${encodeURIComponent(version)}/credential-schema`
  ) as Promise<CredentialSchema>
}

/**
 * The credential-form manifest for a baked OAuth provider (S1-U4, D-B1). control-ui
 * renders the install form from `fields`; `secret: true` fields are masked and never
 * echoed back. control-api 404s for a non-baked provider id.
 */
export async function getOAuthCredentialManifest(
  provider: string
): Promise<OAuthCredentialManifest> {
  return apiGet(
    `/api/v1/admin/oauth/providers/${encodeURIComponent(provider)}/credential-manifest`
  ) as Promise<OAuthCredentialManifest>
}

/**
 * The deployment's public OAuth callback for Marketplace OAuth installs. control-api
 * owns CONTROL_API_OAUTH_CALLBACK_BASE_URL and returns the exact redirect-URI template
 * (over `{oauthClientId}`), or `configured: false` when none is set.
 */
export async function getOAuthCallbackConfig(): Promise<OAuthCallbackConfig> {
  return apiGet('/api/v1/admin/oauth/callback') as Promise<OAuthCallbackConfig>
}

/**
 * Dry-run generic AS discovery (E-19.5, D-A6). Posts the operator-typed issuer/URL and
 * resolves to the prefill SUGGESTION the wizard offers on Apply. No writes. On failure
 * the thrown Error carries `.code`/`.body` (the `discovery_failed` detail kind or a
 * kernel §4 400 message), mapped to UI copy by `mapRemoteDiscoverError`.
 */
export async function discoverGenericOAuth(url: string): Promise<GenericDiscoveryPrefill> {
  return apiSend('POST', '/api/v1/admin/oauth/discover', {
    url,
  }) as Promise<GenericDiscoveryPrefill>
}

/**
 * Lists MCP Server Secrets as names + keys only — never values (E-16.1). The OAuth
 * install wizard's reference mode uses this to verify that a chosen Secret and its
 * id/secret keys exist before the operator submits (D-B3 / Fam. B(1)).
 */
export async function listMcpSecrets(): Promise<{ items: McpSecretSummary[] }> {
  return apiGet('/api/v1/admin/mcp-secrets') as Promise<{ items: McpSecretSummary[] }>
}

export type InstallFromRegistryRequest = {
  serverName?: string
  namespace?: string
  contextRef: string
  registryEntryName: string
  registryEntryVersion: string
  credentials?: Record<string, string>
  egressBindings?: EgressBinding[]
  // Present only when the catalog entry declares OAuth (S1-U4). `oauth.id` is
  // never sent — control-api derives and validates it (D-B5). The client_secret
  // in `oauth.secret` (managed mode) lives only in this request body.
  oauth?: OAuthInstallSubmit
}

export type InstallFromRegistryResponse = {
  installed: boolean
  serverName: string
  namespace: string
  contextRef: string
  // The saga endpoint returns additional fields (correlationId, addedToContext, etc.)
  // — we keep it open so callers can read whatever the BFF chooses to surface.
  [key: string]: unknown
}

export async function installFromRegistry(
  req: InstallFromRegistryRequest
): Promise<InstallFromRegistryResponse> {
  return apiSend(
    'POST',
    '/api/v1/admin/registry/install',
    req
  ) as Promise<InstallFromRegistryResponse>
}

export type InstallRecipeFromRegistryRequest = {
  recipeName?: string
  registryEntryName: string
  registryEntryVersion: string
  recipeManifest?: string
  inputValues?: Record<string, unknown>
}

export type InstallRecipeFromRegistryResponse = {
  recipeName: string
  registryEntry: string
  registryVersion: string
  correlationId: string
  pendingCredentials?: PendingWorkflowCredentialRef[]
}

export async function installRecipeFromRegistry(
  req: InstallRecipeFromRegistryRequest
): Promise<InstallRecipeFromRegistryResponse> {
  return apiSend(
    'POST',
    '/api/v1/admin/registry/install-recipe',
    req
  ) as Promise<InstallRecipeFromRegistryResponse>
}

// Guardrail-hook install: binds a registry `llm-hook` entry to a target Host as an
// LlmHook CR. Mirrors installFromRegistry / installRecipeFromRegistry but hits the
// admin install-hook route. Backend enforces trust floor, §8.4 content-egress, the
// capability ceiling, and the may_deny ⇒ fail-closed rule; error bodies arrive as
// { error, reason? } (surfaced via the thrown Error's `.body`/`.code`).
export type HookCapability =
  | 'may_deny'
  | 'may_rewrite'
  | 'may_substitute_result'
  | 'may_add_context'

export type InstallHookFromRegistryRequest = {
  hostRef: string
  registryEntryName: string
  registryEntryVersion: string
  capabilities?: HookCapability[]
  order?: number
  failMode?: 'open' | 'closed'
  credentials?: Record<string, string>
}

export type InstallHookFromRegistryResponse = {
  hookName: string
  namespace: string
  hostRef: string
  trustLevel: string
  lifecyclePoints: string[]
  registryEntry: string
  registryVersion: string
  correlationId: string
  pendingCredentials?: PendingWorkflowCredentialRef[]
}

export async function installHookFromRegistry(
  req: InstallHookFromRegistryRequest
): Promise<InstallHookFromRegistryResponse> {
  return apiSend(
    'POST',
    '/api/v1/admin/registry/install-hook',
    req
  ) as Promise<InstallHookFromRegistryResponse>
}

export type TriggerWorkflowRequest = {
  inputs?: Record<string, unknown>
  intermediateParameters?: Record<string, unknown>
  outputOverrides?: Record<string, unknown>
}

// Mirrors mapDbRun in control-api/src/routes/admin/workflows.ts. The server
// can return additional fields, so we keep this open via index signature.
export type WorkflowRunRow = {
  runId: string
  recipeNamespace: string
  recipeName: string
  triggeredAt: string | null
  startedAt?: string | null
  completedAt?: string | null
  finalPhase?: string | null
  errorMessage?: string | null
  [key: string]: unknown
}

export async function triggerWorkflow(
  ns: string,
  name: string,
  body: TriggerWorkflowRequest,
  idempotencyKey: string
): Promise<WorkflowRunRow> {
  return apiSend(
    'POST',
    `/api/v1/admin/workflows/${encodeURIComponent(ns)}/${encodeURIComponent(name)}/trigger`,
    body,
    {},
    { 'Idempotency-Key': idempotencyKey }
  ) as Promise<WorkflowRunRow>
}

export async function publishToRegistry(payload: Record<string, unknown>): Promise<RegistryEntry> {
  return apiSend('POST', '/api/v1/admin/registry/entries', payload) as Promise<RegistryEntry>
}

// Resolved publish target for the current caller, sourced from control-api
// (which asks the registry's whoami/discovery — registry stays authoritative).
// `scope` is the org scope this client publishes under (e.g. "newtenantwf"),
// or null when the caller publishes into the curated public catalog. `curator`
// is true for the curated-catalog machine client. `orgName` is the human-facing
// org label when bound to an org. The publish form only DISPLAYS this — the bare
// `name` input and the submitted payload are unchanged; control-api applies the
// scope to the name server-side.
export type PublishScope = {
  scope: string | null
  curator: boolean
  orgName: string | null
  // Static config value (not registry-derived); absent/undefined is treated as
  // enabled for backward compat with a control-api that doesn't send it yet.
  publisherUiEnabled?: boolean
}

export async function getPublishScope(): Promise<PublishScope> {
  return apiGet('/api/v1/admin/registry/publish-scope') as Promise<PublishScope>
}

// ─── Publisher — owned entries, cross-org grants, granted-to-me ────────────
// Contract built by the parallel control-api session; mocked in tests here.
// Owned entries use a dedicated /owned-entries route (the existing /entries is
// the general catalog — reusing it would collide). Grant create/revoke go
// through registryCodedRequest so the typed { error: <code> } body is surfaced
// on `.code` for inline rendering (grantee_not_found / self_grant / plugin_public …).

export type OwnedRegistryEntry = {
  name: string // scoped "@org/name" or bare "name"
  version: string
  visibility: 'public' | 'private'
  status: string // "published" | "deprecated" | "removed"
  // The registry's /org/:org/entries returns the type as `entryType` (camelCase),
  // NOT `entry_type`; keep both so the Publisher's Type column reads it directly
  // instead of mis-inferring "Plugin" for llm-hook entries (see OwnedEntries).
  entryType?: string // "mcp-server" | "recipe" | "llm-hook"
  entry_type?: string
  // Present ("local"/"remote") for mcp-servers, null/absent for others.
  serverMode?: string | null
}
export type OwnedRegistryEntriesResponse = {
  data: OwnedRegistryEntry[]
  meta?: { total: number }
}
export type OrgGrant = {
  id: string
  pluginName: string // scoped "@org/name"
  granteeOrg: string // grantee org slug
  createdAt?: string
}
export type CreateOrgGrantInput = {
  pluginName: string
  granteeOrg: string
}
export type GrantedToMeItem = {
  pluginName: string // scoped "@ownerOrg/name"
  ownerOrg: string
  createdAt?: string
}

// The control-api proxy forwards the registry's grant / granted-to-me items
// verbatim, and the registry's catalog rows are snake_case (entry_type,
// created_at, …). The grant item field naming is not pinned by either side's
// tests, so normalize defensively here — accept camelCase OR snake_case — and
// hand components one canonical camelCase shape. This keeps the mocked→live
// transition safe regardless of which the registry emits, and avoids silent
// empty lists (GrantAccessModal filters on pluginName) or "@undefined" rows.
type RawOrgGrant = {
  id?: string
  pluginName?: string
  plugin_name?: string
  granteeOrg?: string
  grantee_org?: string
  createdAt?: string
  created_at?: string
}
type RawGrantedToMeItem = {
  pluginName?: string
  plugin_name?: string
  ownerOrg?: string
  owner_org?: string
  createdAt?: string
  created_at?: string
}
function normalizeOrgGrant(r: RawOrgGrant): OrgGrant {
  return {
    id: r.id ?? '',
    pluginName: r.pluginName ?? r.plugin_name ?? '',
    granteeOrg: r.granteeOrg ?? r.grantee_org ?? '',
    createdAt: r.createdAt ?? r.created_at,
  }
}
function normalizeGrantedToMeItem(r: RawGrantedToMeItem): GrantedToMeItem {
  return {
    pluginName: r.pluginName ?? r.plugin_name ?? '',
    ownerOrg: r.ownerOrg ?? r.owner_org ?? '',
    createdAt: r.createdAt ?? r.created_at,
  }
}

export async function getOwnedRegistryEntries(): Promise<OwnedRegistryEntriesResponse> {
  // The registry's /org/:org/entries returns { entries: [...] } — its real wire
  // shape — and control-api forwards that body verbatim. This wrapper's contract
  // (and OwnedEntries, which reads response.data) expects { data: [...] }, so
  // tolerate either key and ALWAYS return a { data } array. Without this the
  // component does setEntries(undefined) and crashes on `entries.length`.
  // Owned-entry fields (name/version/visibility/status) are naming-neutral and
  // entry_type is not rendered, so no per-item normalization is needed here.
  const raw = (await apiGet('/api/v1/admin/registry/owned-entries')) as {
    data?: OwnedRegistryEntry[]
    entries?: OwnedRegistryEntry[]
    meta?: { total: number }
  }
  return { data: raw?.data ?? raw?.entries ?? [], meta: raw?.meta }
}

export async function listOrgGrants(pluginName?: string): Promise<{ grants: OrgGrant[] }> {
  const raw = (await apiGet('/api/v1/admin/registry/grants', { pluginName })) as {
    grants?: RawOrgGrant[]
  }
  return { grants: (raw?.grants ?? []).map(normalizeOrgGrant) }
}

export async function createOrgGrant(input: CreateOrgGrantInput): Promise<OrgGrant> {
  const raw = (await registryCodedRequest('POST', '/api/v1/admin/registry/grants', input)) as
    | RawOrgGrant
    | undefined
  return normalizeOrgGrant(raw ?? {})
}

export async function revokeOrgGrant(id: string): Promise<void> {
  await registryCodedRequest('DELETE', `/api/v1/admin/registry/grants/${encodeURIComponent(id)}`)
}

export async function listGrantedToMe(): Promise<{ grants: GrantedToMeItem[] }> {
  const raw = (await apiGet('/api/v1/admin/registry/granted-to-me')) as {
    grants?: RawGrantedToMeItem[]
  }
  return { grants: (raw?.grants ?? []).map(normalizeGrantedToMeItem) }
}

export type UpdateRegistryEntryFields = {
  description?: string
  tags?: string[]
  visibility?: string
  mcpServer?: {
    egressSummary?: { domains?: string[]; ports?: number[]; wideCidr?: boolean } | null
  }
}

export async function updateRegistryEntry(
  name: string,
  version: string,
  fields: UpdateRegistryEntryFields
): Promise<RegistryEntry> {
  const entry = (await apiSend(
    'PUT',
    `/api/v1/admin/registry/entries/${encodeURIComponent(name)}/versions/${encodeURIComponent(version)}`,
    fields
  )) as RegistryEntry
  return normalizeRegistryEntry(entry)
}

export async function deleteRegistryEntry(
  name: string,
  version: string
): Promise<{ deleted: boolean }> {
  return apiSend(
    'DELETE',
    `/api/v1/admin/registry/entries/${encodeURIComponent(name)}/versions/${encodeURIComponent(version)}`
  ) as Promise<{ deleted: boolean }>
}

// ─── Per-Host env vars ─────────────────────────────────────────────────────

export type HostEnvEntry = {
  key: string
  secret: boolean
  updatedAt?: string
}

export type HostEnvWriteEntry = {
  key: string
  value: string
  secret: boolean
}

export type HostEnvWriteResult = {
  keys: HostEnvEntry[]
  /** Plaintext echo for secrets created/updated in this PUT only. */
  showOnce: Record<string, string>
}

export async function listHostEnv(hostRef: string): Promise<{ items: HostEnvEntry[] }> {
  return apiGet(`/api/v1/admin/hosts/${encodeURIComponent(hostRef)}/env`) as Promise<{
    items: HostEnvEntry[]
  }>
}

export async function putHostEnv(
  hostRef: string,
  entries: HostEnvWriteEntry[]
): Promise<HostEnvWriteResult> {
  return apiSend(
    'PUT',
    `/api/v1/admin/hosts/${encodeURIComponent(hostRef)}/env`,
    entries
  ) as Promise<HostEnvWriteResult>
}

export async function deleteHostEnvKey(hostRef: string, key: string): Promise<void> {
  // Direct fetch (not apiSend): 204 No Content has no JSON body.
  const path = `/api/v1/admin/hosts/${encodeURIComponent(hostRef)}/env/${encodeURIComponent(key)}`
  const res = await fetch(`${API_BASE}${path}`, {
    method: 'DELETE',
    headers: { ...authHeaders() },
  })
  if (!res.ok) {
    const text = await res.text()
    if (res.status === 401) {
      handleUnauthorized()
    }
    throw new Error(`${res.status} ${res.statusText} - ${text}`)
  }
}

// ─── Usage tracking ───────────────────────────────────────────────────────

export type UsageInterval = '5min' | 'hour' | 'day'

export type UsageGroupBy =
  | 'model'
  | 'provider'
  | 'host_ref'
  | 'team_id'
  | 'recipe_name'
  | 'llm_secret_name'
  | 'user_id'
  | 'sender'
  | 'channel_type'
  | 'source_kind'

export type UsageFilters = Partial<Record<UsageGroupBy, string[]>>

export type UsageSeriesRow = {
  bucket: string
  group: string | null
  input_tokens: number
  output_tokens: number
  total_tokens: number
  request_count: number
}

export type UsageTotalsRow = {
  group: string | null
  input_tokens: number
  output_tokens: number
  total_tokens: number
  request_count: number
}

export type UsageSeriesResponse = {
  from: string
  to: string
  interval: UsageInterval
  groupBy: UsageGroupBy
  rows: UsageSeriesRow[]
}

export type UsageTotalsResponse = {
  from: string
  to: string
  interval: UsageInterval
  groupBy: UsageGroupBy
  rows: UsageTotalsRow[]
}

function buildUsageQuery(params: {
  from: string
  to: string
  interval: UsageInterval
  groupBy: UsageGroupBy
  filters?: UsageFilters
  limit?: number
}): Record<string, string | undefined> {
  const out: Record<string, string | undefined> = {
    from: params.from,
    to: params.to,
    interval: params.interval,
    groupBy: params.groupBy,
  }
  if (params.filters && Object.keys(params.filters).length > 0) {
    out.filters = JSON.stringify(params.filters)
  }
  if (params.limit !== undefined) out.limit = String(params.limit)
  return out
}

export async function fetchUsageSeries(params: {
  from: string
  to: string
  interval: UsageInterval
  groupBy: UsageGroupBy
  filters?: UsageFilters
}): Promise<UsageSeriesResponse> {
  return apiGet('/api/v1/admin/usage/llm', buildUsageQuery(params)) as Promise<UsageSeriesResponse>
}

export async function fetchUsageTotals(params: {
  from: string
  to: string
  interval: UsageInterval
  groupBy: UsageGroupBy
  filters?: UsageFilters
  limit?: number
}): Promise<UsageTotalsResponse> {
  return apiGet(
    '/api/v1/admin/usage/llm/totals',
    buildUsageQuery(params)
  ) as Promise<UsageTotalsResponse>
}

// ─── Plugin Workload SDK (admin) ────────────────────────────────────────

export type PluginWorkloadSdkFamily = 'promptBridge' | 'clientNotifications'

export type PluginWorkloadSdkModelPolicy = {
  provider: string
  model: string
  temperature?: number
  maxCostUsd?: number
}

export type PluginWorkloadSdkPromptTarget = {
  targetRef: string
  provider: string
  model: string
  // Identity of a provider-owned secret data key; never a secret value.
  // Empty for oauth-broker (Codex) targets, which have no static Secret key.
  credentialSlot: string
  // Codex subscription connection key the target executes against. Only set
  // for oauth-broker providers; the grant must already exist (choose, don't
  // create) and offer the selected model.
  connectionRef?: string
}

export type PluginWorkloadSdkQuotaLimits = {
  /**
   * @deprecated No longer enforced (issue #348); platform per-minute ENV rate
   * limits apply. Still returned on legacy grants; never sent by this UI.
   */
  maxRequestsPerRun?: number
  /**
   * @deprecated No longer enforced (issue #348); platform per-minute ENV rate
   * limits apply. Still returned on legacy grants; never sent by this UI.
   */
  maxNotificationsPerRun?: number
  maxInvocationsPerMinute?: number
  maxNotificationsPerMinute?: number
  /**
   * @deprecated No longer enforced; the Codex ChatGPT wire discards
   * max_output_tokens, so no layer capped the response by token count. Still
   * returned on legacy grants; never sent by this UI.
   */
  maxOutputTokens?: number
}

export type PluginWorkloadSdkGrant = {
  id: string
  recipeNamespace: string
  recipeName: string
  capabilityFamily: PluginWorkloadSdkFamily
  // Explicit provider bound to a promptBridge grant (R1). `null` for older
  // grants written before the column existed (and for clientNotifications).
  // Null promptBridge grants are legacy/unreviewed; the editor must require an
  // explicit operator resave and never infer a routable provider from models.
  provider: string | null
  allowedModels: string[]
  allowedEventTypes: string[]
  allowedTargetRefs: string[]
  allowedUserRefs: string[]
  allowedCallers: string[]
  quotaLimits: PluginWorkloadSdkQuotaLimits
  modelPolicies: Record<string, PluginWorkloadSdkModelPolicy>
  promptTargets: PluginWorkloadSdkPromptTarget[]
  defaultTargetRef: string | null
  policyState: 'active' | 'legacy_unreviewed' | 'revoking' | 'disabled'
  revocationId: string | null
  policyRevision: number
  createdAt: string
  updatedAt: string
}

export type PluginWorkloadSdkLegacyGrantInventoryItem = {
  id: string
  recipeNamespace: string
  recipeName: string
  policyState: string
  policyRevision: number
  providerPresent: boolean
  promptTargetsCount: number
  defaultTargetRefPresent: boolean
  reasons: string[]
}

export type PluginWorkloadSdkLegacyGrantInventory = {
  totalPromptBridgeGrants: number
  legacyPromptBridgeGrants: number
  activationReady: boolean
  items: PluginWorkloadSdkLegacyGrantInventoryItem[]
}

export type PluginWorkloadSdkGrantInput = {
  recipeNamespace: string
  recipeName: string
  capabilityFamily: PluginWorkloadSdkFamily
  // Required for promptBridge grants; omitted for clientNotifications.
  provider?: string
  allowedModels?: string[]
  allowedEventTypes?: string[]
  allowedTargetRefs?: string[]
  allowedUserRefs?: string[]
  allowedCallers?: string[]
  // Input type omits the deprecated per-run keys (issue #348): this UI never
  // sends them and the server strips them on write. The response
  // PluginWorkloadSdkQuotaLimits still carries them for legacy grants.
  // `maxOutputTokens` is NOT among them — it is a live per-grant
  // ceiling on API-key providers.
  quotaLimits?: Omit<PluginWorkloadSdkQuotaLimits, 'maxRequestsPerRun' | 'maxNotificationsPerRun'>
  modelPolicies?: Record<string, PluginWorkloadSdkModelPolicy>
  promptTargets?: PluginWorkloadSdkPromptTarget[]
  defaultTargetRef?: string
}

export type PluginWorkloadSdkQuotaCounter = {
  recipeNamespace: string
  recipeName: string
  periodStart: string
  promptBridgeCount: number
  notificationCount: number
  lastUpdated: string
}

export type PluginWorkloadSdkInvocationStatus =
  | 'in_progress'
  | 'complete'
  | 'failed'
  | 'provider_unavailable'
  | 'accepted'
  | 'delivered'

export type PluginWorkloadSdkInvocation = {
  id: string
  recipeNamespace: string
  recipeName: string
  callerRef: string
  correlationId: string | null
  method: PluginWorkloadSdkFamily
  detail: string
  purpose: string | null
  status: PluginWorkloadSdkInvocationStatus
  quotaConsumed: boolean
  authorizationDecision: string
  createdAt: string
  completedAt: string | null
}

export async function listPluginWorkloadSdkGrants(filter?: {
  recipeNamespace?: string
  recipeName?: string
}): Promise<{ items?: PluginWorkloadSdkGrant[] }> {
  return apiGet('/api/v1/admin/plugin-workload-sdk/grants', {
    recipeNamespace: filter?.recipeNamespace,
    recipeName: filter?.recipeName,
  }) as Promise<{ items?: PluginWorkloadSdkGrant[] }>
}

export async function getPluginWorkloadSdkLegacyInventory(filter?: {
  recipeNamespace?: string
  recipeName?: string
}): Promise<PluginWorkloadSdkLegacyGrantInventory> {
  return apiGet('/api/v1/admin/plugin-workload-sdk/legacy-inventory', {
    recipeNamespace: filter?.recipeNamespace,
    recipeName: filter?.recipeName,
  }) as Promise<PluginWorkloadSdkLegacyGrantInventory>
}

export async function upsertPluginWorkloadSdkGrant(
  grant: PluginWorkloadSdkGrantInput
): Promise<{ grant: PluginWorkloadSdkGrant }> {
  return apiSend('POST', '/api/v1/admin/plugin-workload-sdk/grants', grant) as Promise<{
    grant: PluginWorkloadSdkGrant
  }>
}

export async function deletePluginWorkloadSdkGrant(
  id: string,
  recipeNamespace: string,
  recipeName: string
): Promise<{ deleted: boolean }> {
  return apiSend(
    'DELETE',
    `/api/v1/admin/plugin-workload-sdk/grants/${encodeURIComponent(id)}`,
    undefined,
    { recipeNamespace, recipeName }
  ) as Promise<{ deleted: boolean }>
}

export async function getPluginWorkloadSdkQuota(
  recipeNamespace: string,
  recipeName: string
): Promise<{ items?: PluginWorkloadSdkQuotaCounter[] }> {
  return apiGet(
    `/api/v1/admin/plugin-workload-sdk/quota/${encodeURIComponent(recipeNamespace)}/${encodeURIComponent(recipeName)}`
  ) as Promise<{ items?: PluginWorkloadSdkQuotaCounter[] }>
}

export async function searchPluginWorkloadSdkInvocations(filter?: {
  recipeNamespace?: string
  recipeName?: string
  method?: string
  status?: string
  limit?: string
}): Promise<{ items?: PluginWorkloadSdkInvocation[] }> {
  return apiGet('/api/v1/admin/plugin-workload-sdk/invocations', {
    recipeNamespace: filter?.recipeNamespace,
    recipeName: filter?.recipeName,
    method: filter?.method,
    status: filter?.status,
    limit: filter?.limit,
  }) as Promise<{ items?: PluginWorkloadSdkInvocation[] }>
}

// ─── Org-scoped registry publish API keys (efrk_) ─────────────────────────

export type RegistryApiKey = {
  id: string
  key_prefix: string
  description: string | null
  scopes: string[]
  created_by_username: string
  created_at: string
  expires_at: string | null
  last_used_at: string | null
}
export type CreatedRegistryApiKey = {
  id: string
  key: string
  key_prefix: string
  scopes: string[]
  expires_at: string | null
  // Additive push-credential fields — present only when the minted key carries
  // registry:publish (parallel control-api/registry session). Absent pre-wiring.
  // (username is fixed to "_" by the registry, so the UI hardcodes it rather
  // than reading it back.)
  dockerconfigjson?: string
  registry?: string
}
export type CreateRegistryApiKeyInput = {
  description?: string
  scopes?: string[]
  expiresInDays?: number
}

// Dedicated wrapper: unlike apiGet (discards body) and apiSend (friendly-remaps),
// these routes need the machine-readable error CODE for the panel's state machine.
async function registryCodedRequest(
  method: 'GET' | 'POST' | 'DELETE',
  path: string,
  body?: unknown
): Promise<unknown> {
  const res = await fetchWithTimeout(`${API_BASE}${path}`, {
    method,
    cache: 'no-store',
    headers: {
      ...(body ? { 'Content-Type': 'application/json' } : {}),
      ...authHeaders(),
    },
    body: body ? JSON.stringify(body) : undefined,
  })
  if (!res.ok) {
    let code = ''
    let org: string | undefined
    try {
      const parsed = (await res.json()) as { error?: string; org?: string }
      code = parsed?.error ?? ''
      org = parsed?.org
    } catch {
      /* no body */
    }
    // A 401 is a genuine session-expiry (→ force re-auth) UNLESS it carries the
    // connect-claim endpoint's `claim_rejected` overload: control-api maps the
    // registry's invalid_pop / invalid_claim_token to 401 { error:'claim_rejected' }
    // so the operator sees an inline "token was rejected" message instead of being
    // bounced to login. Every other 401 (Unauthorized / unauthorized) means the
    // session is gone. (Registry keys 401 → 502 server-side, so never reaches here.)
    if (res.status === 401 && code !== 'claim_rejected') handleUnauthorized()
    const error = new Error(`${res.status} ${code || res.statusText}`) as Error & {
      status?: number
      code?: string
      org?: string
    }
    error.status = res.status
    error.code = code
    if (org !== undefined) error.org = org
    throw error
  }
  if (res.status === 204) return undefined
  return parseJsonResponse(res)
}

export async function listRegistryApiKeys(): Promise<{ org: string; keys: RegistryApiKey[] }> {
  return registryCodedRequest('GET', '/api/v1/admin/registry/keys') as Promise<{
    org: string
    keys: RegistryApiKey[]
  }>
}
export async function createRegistryApiKey(
  body: CreateRegistryApiKeyInput
): Promise<CreatedRegistryApiKey> {
  return registryCodedRequest(
    'POST',
    '/api/v1/admin/registry/keys',
    body
  ) as Promise<CreatedRegistryApiKey>
}
export async function revokeRegistryApiKey(id: string): Promise<void> {
  await registryCodedRequest('DELETE', `/api/v1/admin/registry/keys/${encodeURIComponent(id)}`)
}

// ─── Org container images (real repos + tags from the registry) ────────────
export type OrgImage = {
  name: string
  visibility: string
  createdAt: string
  tags: string[]
}
export async function listOrgImages(): Promise<{ org: string; images: OrgImage[] }> {
  const raw = (await registryCodedRequest('GET', '/api/v1/admin/registry/images')) as {
    org?: string
    images?: OrgImage[]
  }
  return { org: raw?.org ?? '', images: raw?.images ?? [] }
}

// ─── Self-hosted registry connect flow (spec §6.1/§6.3) ───────────────────────
// Drives control-api's /api/v1/admin/registry/connect endpoints
// (control-api/src/routes/admin/registryConnect.ts). GET is READ-ONLY and polls
// the registry status endpoint, so state ∈ disconnected | pending | connecting |
// approved | rejected | connected — the panel renders one view per state.
//
// `connecting` means the registry AUTO-APPROVED (open registration) and the
// inline claim has not completed. It is finished by recoverRegistryConnection(),
// never by pasting a token — under auto-approval no operator ever sees one.
// `approved` keeps its original meaning: an operator approved and a human must
// paste the token they were given out of band.
//
// GET fields by state: connected → { deploymentId, org, authEnabled };
// connecting → { deploymentId, requestedOrgName, authEnabled, recoveryError? };
// pending/approved/rejected → { deploymentId, requestedOrgName };
// disconnected → {}. There is NO rejection_reason in the contract.
//
// Uses registryCodedRequest so callers can branch on err.code: not_self_hosted,
// already_connected, recovery_in_progress, not_pending, not_recoverable,
// org_name_taken, registration_capacity, rate_limited, invalid_contact_email,
// org_blocklisted, claim_expired, claim_rejected, already_claimed,
// deployment_suspended, client_unavailable, connection_superseded,
// registry_signing_material_unavailable.

export type RegistryConnectionState =
  | 'disconnected'
  | 'pending'
  | 'connecting'
  | 'approved'
  | 'rejected'
  | 'connected'

export type RegistryRecoveryError =
  | 'already_claimed'
  | 'deployment_suspended'
  | 'client_unavailable'
  | 'connection_superseded'
  | 'claim_expired'

export type RegistryConnectionStatus = {
  state: RegistryConnectionState
  deploymentId?: string
  requestedOrgName?: string
  org?: string
  authEnabled?: boolean
  recoveryError?: RegistryRecoveryError
}

export async function getRegistryConnection(): Promise<RegistryConnectionStatus> {
  return registryCodedRequest(
    'GET',
    '/api/v1/admin/registry/connect'
  ) as Promise<RegistryConnectionStatus>
}

export async function requestRegistryConnection(input: {
  requestedOrgName: string
  contactEmail: string
}): Promise<RegistryConnectionStatus> {
  return registryCodedRequest('POST', '/api/v1/admin/registry/connect/request', {
    requested_org_name: input.requestedOrgName,
    contact_email: input.contactEmail,
  }) as Promise<RegistryConnectionStatus>
}

export async function submitRegistryClaim(input: {
  claimToken: string
}): Promise<{ state: 'connected'; org: string }> {
  return registryCodedRequest('POST', '/api/v1/admin/registry/connect/claim', {
    claim_token: input.claimToken,
  }) as Promise<{ state: 'connected'; org: string }>
}

export async function disconnectRegistryConnection(): Promise<void> {
  await registryCodedRequest('DELETE', '/api/v1/admin/registry/connect')
}

export async function recoverRegistryConnection(): Promise<RegistryConnectionStatus> {
  return registryCodedRequest(
    'POST',
    '/api/v1/admin/registry/connect/recover'
  ) as Promise<RegistryConnectionStatus>
}