/**
 * Rate-limit type stubs for sandcode.
 *
 * The upstream rateLimits service (GrowthBook-driven rate-limit tiers,
 * subscription overage messaging, console-served quota envelopes) is removed
 * from sandcode — no first-party rate-limit pipeline exists in this fork.
 *
 * This module survives because three call sites still destructure the
 * legacy shape:
 *   - services/api/errors.ts: builds a {@link SandcodeLimits} object from
 *     `anthropic-ratelimit-unified-*` HTTP headers when an upstream provider
 *     happens to send them, so it can format a user-facing message
 *   - services/api/messages.ts: reads {@link currentLimits}.isUsingOverage
 *     to gate cache-control behavior and a few other paths
 *   - cli/print.ts: subscribes to {@link statusListeners} for the
 *     non-interactive rate-limit banner
 *
 * Everything here returns dormant/no-op values; the destructured shape is
 * present so the tree compiles and the callers' `??` fallbacks fire cleanly.
 * Strip these call sites and this file together when sandcode grows its own
 * rate-limit story (or when we decide it never will).
 */

export type OverageDisabledReason =
  | 'overage_not_provisioned'
  | 'org_level_disabled'
  | 'org_level_disabled_until'
  | 'out_of_credits'
  | 'seat_tier_level_disabled'
  | 'member_level_disabled'
  | 'seat_tier_zero_credit_limit'
  | 'group_zero_credit_limit'
  | 'member_zero_credit_limit'
  | 'org_service_level_disabled'
  | 'org_service_zero_credit_limit'
  | 'no_limits_configured'
  | 'unknown'

export type RateLimitStatus = 'allowed' | 'allowed_warning' | 'rejected'

export type RateLimitInfo = {
  status: RateLimitStatus
  resetsAt?: number
  rateLimitType?: string
  utilization?: number
  overageStatus?: RateLimitStatus
  overageResetsAt?: number
  overageDisabledReason?: OverageDisabledReason
  isUsingOverage: boolean
  surpassedThreshold?: number
  unifiedRateLimitFallbackAvailable: boolean
}

/** Surviving alias used by callers that haven't been migrated to RateLimitInfo. */
export type RateLimits = RateLimitInfo
/** Sandcode-named alias, used by errors.ts and cli/print.ts. */
export type SandcodeLimits = RateLimitInfo

export const statusListeners: Set<(limits: RateLimitInfo | undefined) => void> = new Set()

/** Dormant snapshot used by messages.ts to gate cache-control and overage paths. */
export const currentLimits: RateLimitInfo = {
  status: 'allowed',
  isUsingOverage: false,
  unifiedRateLimitFallbackAvailable: false,
}

/**
 * Returns a user-facing error message for a rate-limit response, or null
 * when the caller's fallback path (e.g. Opus → Sonnet) should handle it
 * silently. The model arg is unused in the stub but kept in the signature
 * so call sites compile without rewrites.
 */
export function getRateLimitErrorMessage(_limits: RateLimitInfo, _model?: string): string | null {
  return 'Rate limit exceeded.'
}

/**
 * No-op — rate-limit mocking pipeline was removed with the upstream service.
 * Optional arg accepted to match legacy `(isSubscribedUser())` call shape
 * without forcing a caller-side rewrite.
 */
export function shouldProcessRateLimits(_isSubscribed?: boolean): boolean {
  return false
}

/** Utilization fraction (0..1) of the current rate-limit window. No data → 0. */
export function getRawUtilization(): number {
  return 0
}

/**
 * Best-effort extractor for `anthropic-ratelimit-unified-*` headers on a 429
 * response. Sandcode's removal of the first-party quota pipeline means we
 * have nothing meaningful to return, but errors.ts builds its own shape from
 * the headers directly, so the no-op here is safe.
 */
export function extractQuotaStatusFromError(_error: unknown): RateLimitInfo | null {
  return null
}

/** Same shape as {@link extractQuotaStatusFromError} but for raw response headers. */
export function extractQuotaStatusFromHeaders(_headers: unknown): RateLimitInfo | null {
  return null
}
