feat(api): expose documented usage and quota for API-key clients #98

Context

The public API reference and its machine-readable OpenAPI description cover the OpenAI-compatible inference API (/v1/models, chat/completions, embeddings, etc.), but do not expose an account usage or quota endpoint.

The NaN CLI documentation says the CLI displays usage for 24 hours, 30 days, and all time. It also says nan auth login (which obtains a nan_session) is needed for Profile, Usage, and Costs; an API key alone is only needed for inference/tool setup. In the public helmcode/nan-cli client, GetMetricsUsage calls GET https://cloud-api.nan.builders/api/metrics/usage with a Cookie: nan_session=... header. This is not part of the published inference OpenAPI contract.

That leaves extensions and other API-key clients without a supported way to display account-wide usage or remaining quota. Community projects appear to call other cloud-api.nan.builders usage routes, but their existence is not a stability or support guarantee.

Goal

Provide a stable, officially supported way for an API-key client to retrieve account usage/quota, and document its contract and authentication.

Requested scope

• Confirm whether an existing endpoint is intended for third-party/API-key integrations; if so, document its exact URL, auth method, response schema, windows, reset semantics, rate limits, and errors.
• Otherwise, consider an inference-key-authenticated endpoint returning account/model usage and available quota, without requiring browser cookies or a dashboard session.
• Make the contract machine-readable (for example, in the published OpenAPI spec) and describe its support/stability policy.

Why this matters

A VS Code provider stores only the user's inference API key in VS Code SecretStorage. Reusing a browser cookie or undocumented dashboard endpoint would require a second credential and couple the extension to an unsupported internal implementation. The extension therefore keeps only locally observed token usage and does not claim that it is account-wide quota.

Related integration request: svg153/nan-vscode#7