free-coding-models 0.1.83 → 0.1.84

package/src/ping.js

@@ -0,0 +1,186 @@
+/**
+ * @file ping.js
+ * @description HTTP ping infrastructure for model availability and latency measurement.
+ *
+ * @details
+ *   This module provides functions for sending ping requests to model providers,
+ *   extracting quota information from response headers, and managing provider
+ *   endpoint quota polling with caching.
+ *
+ *   🎯 Key features:
+ *   - Provider-specific request building (handles Replicate, Cloudflare, OpenRouter)
+ *   - Async ping with timeout and abort controller
+ *   - Quota extraction from rate limit headers (multiple variants supported)
+ *   - Cached provider quota polling with TTL and error backoff
+ *   - Cloudflare account ID resolution from environment
+ *
+ *   → Functions:
+ *   - `resolveCloudflareUrl`: Resolve {account_id} placeholder from CLOUDFLARE_ACCOUNT_ID env var
+ *   - `buildPingRequest`: Build provider-specific HTTP request for pinging
+ *   - `ping`: Send async ping request with timeout; returns { code, ms, quotaPercent }
+ *   - `getHeaderValue`: Helper to extract header value from Headers object or plain object
+ *   - `extractQuotaPercent`: Parse rate limit headers to calculate remaining quota percentage
+ *   - `fetchProviderQuotaPercent`: Fetch quota for a provider from dedicated endpoint/headers
+ *   - `getProviderQuotaPercentCached`: Wrapper for cached provider quota fetching
+ *   - `usagePlaceholderForProvider`: Return display token for Usage column based on provider behavior
+ *
+ *   📦 Dependencies:
+ *   - ../src/constants.js: PING_TIMEOUT
+ *   - ../src/provider-quota-fetchers.js: _fetchProviderQuotaFromModule (quota fetching with cache)
+ *   - ../src/quota-capabilities.js: supportsUsagePercent
+ *
+ *   ⚙️ Configuration:
+ *   - PING_TIMEOUT: Timeout in ms for ping requests (default: 15000)
+ *   - CLOUDFLARE_ACCOUNT_ID: Env var for Cloudflare Workers AI account ID
+ *
+ *   @see {@link ../src/provider-quota-fetchers.js} Quota fetching implementation
+ *   @see {@link ../src/quota-capabilities.js} Quota telemetry + Usage behavior detection
+ */
+
+import { PING_TIMEOUT } from './constants.js'
+import { fetchProviderQuota as _fetchProviderQuotaFromModule } from './provider-quota-fetchers.js'
+import { supportsUsagePercent } from './quota-capabilities.js'
+
+// 📖 resolveCloudflareUrl: Cloudflare's OpenAI-compatible endpoint is account-scoped.
+// 📖 We resolve {account_id} from env so provider setup can stay simple in config.
+export function resolveCloudflareUrl(url) {
+  const accountId = (process.env.CLOUDFLARE_ACCOUNT_ID || '').trim()
+  if (!url.includes('{account_id}')) return url
+  if (!accountId) return url.replace('{account_id}', 'missing-account-id')
+  return url.replace('{account_id}', encodeURIComponent(accountId))
+}
+
+// 📖 buildPingRequest: Build provider-specific ping request.
+// 📖 Handles Replicate's /v1/predictions format, Cloudflare's account_id in URL,
+// 📖 and standard OpenAI-compliant chat completions with provider-specific headers.
+export function buildPingRequest(apiKey, modelId, providerKey, url) {
+  // 📖 ZAI models are stored as "zai/glm-..." in sources.js but the API expects just "glm-..."
+  const apiModelId = providerKey === 'zai' ? modelId.replace(/^zai\//, '') : modelId
+
+  if (providerKey === 'replicate') {
+    // 📖 Replicate uses /v1/predictions with a different payload than OpenAI chat-completions.
+    const replicateHeaders = { 'Content-Type': 'application/json', Prefer: 'wait=4' }
+    if (apiKey) replicateHeaders.Authorization = `Token ${apiKey}`
+    return {
+      url,
+      headers: replicateHeaders,
+      body: { version: modelId, input: { prompt: 'hi' } },
+    }
+  }
+
+  if (providerKey === 'cloudflare') {
+    // 📖 Cloudflare Workers AI uses OpenAI-compatible payload but needs account_id in URL.
+    const headers = { 'Content-Type': 'application/json' }
+    if (apiKey) headers.Authorization = `Bearer ${apiKey}`
+    return {
+      url: resolveCloudflareUrl(url),
+      headers,
+      body: { model: apiModelId, messages: [{ role: 'user', content: 'hi' }], max_tokens: 1 },
+    }
+  }
+
+  const headers = { 'Content-Type': 'application/json' }
+  if (apiKey) headers.Authorization = `Bearer ${apiKey}`
+  if (providerKey === 'openrouter') {
+    // 📖 OpenRouter recommends optional app identification headers.
+    headers['HTTP-Referer'] = 'https://github.com/vava-nessa/free-coding-models'
+    headers['X-Title'] = 'free-coding-models'
+  }
+
+  return {
+    url,
+    headers,
+    body: { model: apiModelId, messages: [{ role: 'user', content: 'hi' }], max_tokens: 1 },
+  }
+}
+
+// 📖 ping: Send a single chat completion request to measure model availability and latency.
+// 📖 providerKey and url determine provider-specific request format.
+// 📖 apiKey can be null — in that case no Authorization header is sent.
+// 📖 A 401 response still tells us the server is UP and gives us real latency.
+// 📖 Returns { code, ms, quotaPercent }
+export async function ping(apiKey, modelId, providerKey, url) {
+  const ctrl  = new AbortController()
+  const timer = setTimeout(() => ctrl.abort(), PING_TIMEOUT)
+  const t0    = performance.now()
+  try {
+    const req = buildPingRequest(apiKey, modelId, providerKey, url)
+    const resp = await fetch(req.url, {
+      method: 'POST', signal: ctrl.signal,
+      headers: req.headers,
+      body: JSON.stringify(req.body),
+    })
+    // 📖 Normalize all HTTP 2xx statuses to "200" so existing verdict/avg logic still works.
+    const code = resp.status >= 200 && resp.status < 300 ? '200' : String(resp.status)
+    return {
+      code,
+      ms: Math.round(performance.now() - t0),
+      quotaPercent: extractQuotaPercent(resp.headers),
+    }
+  } catch (err) {
+    const isTimeout = err.name === 'AbortError'
+    return {
+      code: isTimeout ? '000' : 'ERR',
+      ms: isTimeout ? 'TIMEOUT' : Math.round(performance.now() - t0),
+      quotaPercent: null,
+    }
+  } finally {
+    clearTimeout(timer)
+  }
+}
+
+// 📖 getHeaderValue: Helper to extract header value from Headers object or plain object.
+// 📖 Returns null if headers is null or key is not found.
+function getHeaderValue(headers, key) {
+  if (!headers) return null
+  if (typeof headers.get === 'function') return headers.get(key)
+  return headers[key] ?? headers[key.toLowerCase()] ?? null
+}
+
+// 📖 extractQuotaPercent: Parse rate limit headers to calculate remaining quota percentage.
+// 📖 Checks multiple header variants (x-ratelimit-*, ratelimit-*, etc.).
+// 📖 Returns value clamped 0–100, or null if quota headers not present.
+export function extractQuotaPercent(headers) {
+  const variants = [
+    ['x-ratelimit-remaining', 'x-ratelimit-limit'],
+    ['x-ratelimit-remaining-requests', 'x-ratelimit-limit-requests'],
+    ['ratelimit-remaining', 'ratelimit-limit'],
+    ['ratelimit-remaining-requests', 'ratelimit-limit-requests'],
+  ]
+
+  for (const [remainingKey, limitKey] of variants) {
+    const remainingRaw = getHeaderValue(headers, remainingKey)
+    const limitRaw = getHeaderValue(headers, limitKey)
+    const remaining = parseFloat(remainingRaw)
+    const limit = parseFloat(limitRaw)
+    if (Number.isFinite(remaining) && Number.isFinite(limit) && limit > 0) {
+      const pct = Math.round((remaining / limit) * 100)
+      return Math.max(0, Math.min(100, pct))
+    }
+  }
+
+  return null
+}
+
+// ─── Provider endpoint quota polling ─────────────────────────────────────────
+
+// 📖 fetchProviderQuotaPercent: Fetch quota for a provider from dedicated endpoint/headers.
+// 📖 Delegates to unified module entrypoint (handles openrouter + siliconflow + others).
+// 📖 The module implements TTL cache and error backoff internally.
+export async function fetchProviderQuotaPercent(providerKey, apiKey) {
+  return _fetchProviderQuotaFromModule(providerKey, apiKey)
+}
+
+// 📖 getProviderQuotaPercentCached: Wrapper for cached provider quota fetching.
+// 📖 The module already implements TTL cache and error backoff internally.
+// 📖 This wrapper preserves the existing call-site API from bin/free-coding-models.js.
+export async function getProviderQuotaPercentCached(providerKey, apiKey) {
+  return fetchProviderQuotaPercent(providerKey, apiKey)
+}
+
+// 📖 usagePlaceholderForProvider: Return display token for Usage column.
+// 📖 '--' means this provider can expose a real remaining percentage once telemetry arrives.
+// 📖 '🟢' means the provider is usable, but a live remaining % is not applicable/reliable.
+export function usagePlaceholderForProvider(providerKey) {
+  return supportsUsagePercent(providerKey) ? '--' : '🟢'
+}

package/src/provider-metadata.js

@@ -0,0 +1,218 @@
+/**
+ * @file provider-metadata.js
+ * @description Provider metadata, environment variable names, and OpenCode model ID mapping.
+ *              Extracted from bin/free-coding-models.js to allow shared access by setup wizard,
+ *              Settings overlay, and OpenCode integration helpers.
+ *
+ * @details
+ *   This module owns three separate concerns that all relate to "knowing about providers":
+ *
+ *   1. `PROVIDER_METADATA` — human-readable display info (label, colour, signup URL, rate limits)
+ *      used in the setup wizard (`promptApiKey`) and the Settings overlay.
+ *
+ *   2. `ENV_VAR_NAMES` — maps providerKey → the environment variable name that carries the API key.
+ *      Used when spawning OpenCode child processes so that keys stored only in
+ *      ~/.free-coding-models.json are also visible to the child via `{env:VAR}` references.
+ *
+ *   3. `OPENCODE_MODEL_MAP` — sparse mapping of source model IDs to OpenCode built-in model IDs
+ *      (only entries where the IDs differ need to be listed).  Groq's API aliases short names
+ *      to full names but OpenCode does exact ID matching against its built-in model list.
+ *
+ *   Platform booleans (`isWindows`, `isMac`, `isLinux`) are also exported here so that
+ *   OpenCode Desktop launch logic and auto-update can share them without re-reading `process.platform`.
+ *
+ * @exports
+ *   PROVIDER_METADATA, ENV_VAR_NAMES, OPENCODE_MODEL_MAP,
+ *   isWindows, isMac, isLinux
+ *
+ * @see bin/free-coding-models.js  — consumes all exports from this module
+ * @see src/config.js              — resolveApiKeys / getApiKey use ENV_VAR_NAMES indirectly
+ */
+
+import chalk from 'chalk'
+
+// 📖 Platform detection — used by Desktop launcher and auto-update to pick the right open/start command.
+export const isWindows = process.platform === 'win32'
+export const isMac     = process.platform === 'darwin'
+export const isLinux   = process.platform === 'linux'
+
+// 📖 ENV_VAR_NAMES: maps providerKey → shell env var name for passing resolved keys to child processes.
+// 📖 When a key is stored only in ~/.free-coding-models.json (not in the shell env), we inject it
+// 📖 into the child's env so OpenCode's {env:VAR} references still resolve.
+export const ENV_VAR_NAMES = {
+  nvidia:     'NVIDIA_API_KEY',
+  groq:       'GROQ_API_KEY',
+  cerebras:   'CEREBRAS_API_KEY',
+  sambanova:  'SAMBANOVA_API_KEY',
+  openrouter: 'OPENROUTER_API_KEY',
+  huggingface:'HUGGINGFACE_API_KEY',
+  replicate:  'REPLICATE_API_TOKEN',
+  deepinfra:  'DEEPINFRA_API_KEY',
+  fireworks:  'FIREWORKS_API_KEY',
+  codestral:  'CODESTRAL_API_KEY',
+  hyperbolic: 'HYPERBOLIC_API_KEY',
+  scaleway:   'SCALEWAY_API_KEY',
+  googleai:   'GOOGLE_API_KEY',
+  siliconflow:'SILICONFLOW_API_KEY',
+  together:   'TOGETHER_API_KEY',
+  cloudflare: 'CLOUDFLARE_API_TOKEN',
+  perplexity: 'PERPLEXITY_API_KEY',
+  zai:        'ZAI_API_KEY',
+}
+
+// 📖 OPENCODE_MODEL_MAP: sparse table of model IDs that differ between sources.js and OpenCode's
+// 📖 built-in model registry.  Only add entries where they DIFFER — unmapped models pass through as-is.
+export const OPENCODE_MODEL_MAP = {
+  groq: {
+    'moonshotai/kimi-k2-instruct': 'moonshotai/kimi-k2-instruct-0905',
+    'meta-llama/llama-4-scout-17b-16e-preview': 'meta-llama/llama-4-scout-17b-16e-instruct',
+    'meta-llama/llama-4-maverick-17b-128e-preview': 'meta-llama/llama-4-maverick-17b-128e-instruct',
+  }
+}
+
+// 📖 PROVIDER_METADATA: display info for each provider, used in setup wizard and Settings panel.
+// 📖 `color` is a chalk function for visual distinction in the TUI.
+// 📖 `signupUrl` / `signupHint` guide users through first-time key generation.
+// 📖 `rateLimits` gives a quick reminder of the free-tier quota without opening a browser.
+export const PROVIDER_METADATA = {
+  nvidia: {
+    label: 'NVIDIA NIM',
+    color: chalk.rgb(118, 185, 0),
+    signupUrl: 'https://build.nvidia.com',
+    signupHint: 'Profile → API Keys → Generate',
+    rateLimits: 'Free tier (provider quota by model)',
+  },
+  groq: {
+    label: 'Groq',
+    color: chalk.rgb(249, 103, 20),
+    signupUrl: 'https://console.groq.com/keys',
+    signupHint: 'API Keys → Create API Key',
+    rateLimits: 'Free dev tier (provider quota)',
+  },
+  cerebras: {
+    label: 'Cerebras',
+    color: chalk.rgb(0, 180, 255),
+    signupUrl: 'https://cloud.cerebras.ai',
+    signupHint: 'API Keys → Create',
+    rateLimits: 'Free dev tier (provider quota)',
+  },
+  sambanova: {
+    label: 'SambaNova',
+    color: chalk.rgb(255, 165, 0),
+    signupUrl: 'https://cloud.sambanova.ai/apis',
+    signupHint: 'SambaCloud portal → Create API key',
+    rateLimits: 'Dev tier generous quota',
+  },
+  openrouter: {
+    label: 'OpenRouter',
+    color: chalk.rgb(120, 80, 255),
+    signupUrl: 'https://openrouter.ai/keys',
+    signupHint: 'API Keys → Create',
+    rateLimits: '50 req/day, 20/min (:free shared quota)',
+  },
+  huggingface: {
+    label: 'Hugging Face Inference',
+    color: chalk.rgb(255, 182, 0),
+    signupUrl: 'https://huggingface.co/settings/tokens',
+    signupHint: 'Settings → Access Tokens',
+    rateLimits: 'Free monthly credits (~$0.10)',
+  },
+  replicate: {
+    label: 'Replicate',
+    color: chalk.rgb(120, 160, 255),
+    signupUrl: 'https://replicate.com/account/api-tokens',
+    signupHint: 'Account → API Tokens',
+    rateLimits: 'Developer free quota',
+  },
+  deepinfra: {
+    label: 'DeepInfra',
+    color: chalk.rgb(0, 180, 140),
+    signupUrl: 'https://deepinfra.com/login',
+    signupHint: 'Login → API keys',
+    rateLimits: 'Free dev tier (low-latency quota)',
+  },
+  fireworks: {
+    label: 'Fireworks AI',
+    color: chalk.rgb(255, 80, 50),
+    signupUrl: 'https://fireworks.ai',
+    signupHint: 'Create account → Generate API key',
+    rateLimits: '$1 free credits (new dev accounts)',
+  },
+  codestral: {
+    label: 'Mistral Codestral',
+    color: chalk.rgb(255, 100, 100),
+    signupUrl: 'https://codestral.mistral.ai',
+    signupHint: 'API Keys → Create',
+    rateLimits: '30 req/min, 2000/day',
+  },
+  hyperbolic: {
+    label: 'Hyperbolic',
+    color: chalk.rgb(0, 200, 150),
+    signupUrl: 'https://app.hyperbolic.ai/settings',
+    signupHint: 'Settings → API Keys',
+    rateLimits: '$1 free trial credits',
+  },
+  scaleway: {
+    label: 'Scaleway',
+    color: chalk.rgb(130, 0, 250),
+    signupUrl: 'https://console.scaleway.com/iam/api-keys',
+    signupHint: 'IAM → API Keys',
+    rateLimits: '1M free tokens',
+  },
+  googleai: {
+    label: 'Google AI Studio',
+    color: chalk.rgb(66, 133, 244),
+    signupUrl: 'https://aistudio.google.com/apikey',
+    signupHint: 'Get API key',
+    rateLimits: '14.4K req/day, 30/min',
+  },
+  siliconflow: {
+    label: 'SiliconFlow',
+    color: chalk.rgb(255, 120, 30),
+    signupUrl: 'https://cloud.siliconflow.cn/account/ak',
+    signupHint: 'API Keys → Create',
+    rateLimits: 'Free models: usually 100 RPM, varies by model',
+  },
+  together: {
+    label: 'Together AI',
+    color: chalk.rgb(0, 180, 255),
+    signupUrl: 'https://api.together.ai/settings/api-keys',
+    signupHint: 'Settings → API keys',
+    rateLimits: 'Credits/promos vary by account (check console)',
+  },
+  cloudflare: {
+    label: 'Cloudflare Workers AI',
+    color: chalk.rgb(242, 119, 36),
+    signupUrl: 'https://dash.cloudflare.com',
+    signupHint: 'Create AI API token + set CLOUDFLARE_ACCOUNT_ID',
+    rateLimits: 'Free: 10k neurons/day, text-gen 300 RPM',
+  },
+  perplexity: {
+    label: 'Perplexity API',
+    color: chalk.rgb(0, 210, 190),
+    signupUrl: 'https://www.perplexity.ai/settings/api',
+    signupHint: 'Generate API key (billing may be required)',
+    rateLimits: 'Tiered limits by spend (default ~50 RPM)',
+  },
+  qwen: {
+    label: 'Alibaba Cloud (DashScope)',
+    color: chalk.rgb(255, 140, 0),
+    signupUrl: 'https://modelstudio.console.alibabacloud.com',
+    signupHint: 'Model Studio → API Key → Create (1M free tokens, 90 days)',
+    rateLimits: '1M free tokens per model (Singapore region, 90 days)',
+  },
+  zai: {
+    label: 'ZAI (z.ai)',
+    color: chalk.rgb(0, 150, 255),
+    signupUrl: 'https://z.ai',
+    signupHint: 'Sign up and generate an API key',
+    rateLimits: 'Free tier (generous quota)',
+  },
+  iflow: {
+    label: 'iFlow',
+    color: chalk.rgb(100, 200, 255),
+    signupUrl: 'https://platform.iflow.cn',
+    signupHint: 'Register → Personal Information → Generate API Key (7-day expiry)',
+    rateLimits: 'Free for individuals (no request limits)',
+  },
+}

package/src/quota-capabilities.js

@@ -0,0 +1,112 @@
+/**
+ * @file lib/quota-capabilities.js
+ * @description Provider quota telemetry and Usage-column behavior map.
+ *
+ * Describes how we can observe quota state for each provider:
+ * - header:   Provider sends x-ratelimit-remaining / x-ratelimit-limit headers
+ * - endpoint: Provider has a dedicated usage/quota REST endpoint we can poll
+ * - unknown:  No reliable quota signal available
+ *
+ * The TUI needs an extra distinction beyond telemetry transport:
+ * - `usageDisplay: 'percent'` means we can show a trustworthy remaining %.
+ * - `usageDisplay: 'ok'` means Usage is not meaningfully measurable as a live %,
+ *   so the table shows a green status dot instead of a misleading number.
+ *
+ * `resetCadence` tells the reader when a stored snapshot should be invalidated
+ * even if it is still within the generic freshness TTL.
+ *
+ * supportsEndpoint (optional, for openrouter/siliconflow):
+ *   true  — provider has a known usage endpoint
+ *   false — no endpoint, header-only or unknown
+ *
+ * @exports PROVIDER_CAPABILITIES — full map keyed by providerKey (matches sources.js)
+ * @exports getQuotaTelemetry(providerKey) — returns capability object (defaults to unknown)
+ * @exports isKnownQuotaTelemetry(providerKey) — true when telemetryType !== 'unknown'
+ */
+
+/**
+ * @typedef {Object} ProviderCapability
+ * @property {'header'|'endpoint'|'unknown'} telemetryType
+ * @property {boolean} [supportsEndpoint]
+ * @property {'percent'|'ok'} usageDisplay
+ * @property {'rolling'|'daily'|'unknown'|'none'} resetCadence
+ */
+
+/** @type {Record<string, ProviderCapability>} */
+export const PROVIDER_CAPABILITIES = {
+  // Providers that return x-ratelimit-remaining / x-ratelimit-limit headers
+  nvidia: { telemetryType: 'header', supportsEndpoint: false, usageDisplay: 'ok',      resetCadence: 'none' },
+  groq: { telemetryType: 'header', supportsEndpoint: false, usageDisplay: 'percent', resetCadence: 'daily' },
+  cerebras: { telemetryType: 'header', supportsEndpoint: false, usageDisplay: 'percent', resetCadence: 'unknown' },
+  sambanova: { telemetryType: 'header', supportsEndpoint: false, usageDisplay: 'percent', resetCadence: 'unknown' },
+  deepinfra: { telemetryType: 'header', supportsEndpoint: false, usageDisplay: 'percent', resetCadence: 'unknown' },
+  fireworks: { telemetryType: 'header', supportsEndpoint: false, usageDisplay: 'percent', resetCadence: 'unknown' },
+  together: { telemetryType: 'header', supportsEndpoint: false, usageDisplay: 'percent', resetCadence: 'unknown' },
+  hyperbolic: { telemetryType: 'header', supportsEndpoint: false, usageDisplay: 'percent', resetCadence: 'unknown' },
+  scaleway: { telemetryType: 'header', supportsEndpoint: false, usageDisplay: 'percent', resetCadence: 'unknown' },
+  googleai: { telemetryType: 'header', supportsEndpoint: false, usageDisplay: 'percent', resetCadence: 'daily' },
+  codestral: { telemetryType: 'header', supportsEndpoint: false, usageDisplay: 'percent', resetCadence: 'daily' },
+  perplexity: { telemetryType: 'header', supportsEndpoint: false, usageDisplay: 'percent', resetCadence: 'unknown' },
+  qwen: { telemetryType: 'header', supportsEndpoint: false, usageDisplay: 'percent', resetCadence: 'unknown' },
+
+  // Providers that have a dedicated usage/credits endpoint
+  openrouter: { telemetryType: 'endpoint', supportsEndpoint: true, usageDisplay: 'percent', resetCadence: 'unknown' },
+  siliconflow: { telemetryType: 'endpoint', supportsEndpoint: true, usageDisplay: 'ok',      resetCadence: 'unknown' },
+
+  // Providers with no reliable quota signal
+  huggingface: { telemetryType: 'unknown', supportsEndpoint: false, usageDisplay: 'ok', resetCadence: 'none' },
+  replicate: { telemetryType: 'unknown', supportsEndpoint: false, usageDisplay: 'ok', resetCadence: 'none' },
+  cloudflare: { telemetryType: 'unknown', supportsEndpoint: false, usageDisplay: 'ok', resetCadence: 'daily' },
+  zai: { telemetryType: 'unknown', supportsEndpoint: false, usageDisplay: 'ok', resetCadence: 'none' },
+  iflow: { telemetryType: 'unknown', supportsEndpoint: false, usageDisplay: 'ok', resetCadence: 'none' },
+}
+
+/** Fallback for unrecognized providers */
+const UNKNOWN_CAPABILITY = { telemetryType: 'unknown', supportsEndpoint: false, usageDisplay: 'ok', resetCadence: 'unknown' }
+
+/**
+ * Get quota telemetry capability for a provider.
+ * Returns `{ telemetryType: 'unknown', supportsEndpoint: false }` for unrecognized providers.
+ *
+ * @param {string} providerKey - Provider key matching sources.js (e.g. 'groq', 'openrouter')
+ * @returns {ProviderCapability}
+ */
+export function getQuotaTelemetry(providerKey) {
+  return PROVIDER_CAPABILITIES[providerKey] ?? UNKNOWN_CAPABILITY
+}
+
+/**
+ * Returns true when we have a reliable quota telemetry signal for this provider
+ * (either via response headers or a dedicated endpoint).
+ *
+ * Returns false for 'unknown' providers where quota state must be inferred.
+ *
+ * @param {string} providerKey
+ * @returns {boolean}
+ */
+export function isKnownQuotaTelemetry(providerKey) {
+  return getQuotaTelemetry(providerKey).telemetryType !== 'unknown'
+}
+
+/**
+ * Returns true when the Usage column can show a real remaining percentage for
+ * the given provider.
+ *
+ * @param {string} providerKey
+ * @returns {boolean}
+ */
+export function supportsUsagePercent(providerKey) {
+  return getQuotaTelemetry(providerKey).usageDisplay === 'percent'
+}
+
+/**
+ * Returns true when the provider's quota commonly resets on a daily cadence.
+ * This lets the usage reader invalidate yesterday's snapshots immediately
+ * after midnight instead of waiting for the generic TTL window to expire.
+ *
+ * @param {string} providerKey
+ * @returns {boolean}
+ */
+export function usageResetsDaily(providerKey) {
+  return getQuotaTelemetry(providerKey).resetCadence === 'daily'
+}