feat(nan): adaptar la tira al nuevo modelo de créditos de NaN Builders #268

Pre-flight checks

• I searched existing issues and found no duplicate.
• I understand that this proposal requires product review before implementation.

Problem to solve

Desde el 10 de noviembre de 2026, NaN Builders mide la inferencia en créditos y no en una asignación de tokens por modelo. La tira y el detalle de Quorb siguen mostrando un medidor por modelo con tope en tokens, así que en las cuentas que pasaron a créditos el medidor ya no representa lo que limita a la persona.

Según los términos de servicio y la documentación (Choose your model, Getting started, Models):

• «Since November 10, 2026, inference on NaN is measured in credits, except on the Gentle plan. One credit equals 0.02 US dollars of model cost.»
• Un único fondo por cuenta: Inference (nan_member, 70 €/mes) incluye 7.000 créditos por periodo de facturación y Premium (200 €/mes) 20.000. «Every model marked credits draws from that same pool, by its price per token (input, cached input and output), so there is no separate allowance per model.»
• Reinicio: el fondo vuelve a llenarse al empezar el periodo de facturación de Stripe («almost never the 1st»). Los créditos incluidos no se acumulan y se prorratean al empezar o subir de plan a mitad de periodo.
• Packs de créditos: se consumen después de los créditos incluidos, caducan a los 6 meses de la última compra y pueden recargarse automáticamente. Sin créditos, la API responde 402 insufficient_balance.
• Modelos sin contador: gemma4, qwen3.6, qwen3-embedding, rerank, kokoro y whisper no consumen créditos. Las imágenes (flux-2-klein, qwen-image-2.1) tienen su propio límite de 100 solicitudes al mes por mes natural.
• Ventana de glm5.3: 400M tokens por ventana móvil de 4 h, independiente de los créditos; al llenarse responde 429.
• Plan Gentle: no usa créditos y conserva una asignación de tokens por modelo (402 monthly_cap_reached al agotarla).
• API: según Getting started, GET /v1/usage devuelve el uso por día y modelo con los créditos facturados y, además, «your current billing period, whatever window you ask for: your allowance, the credits used and remaining, and your pack credits». La documentación no publica los nombres exactos de esos campos.

Proposed solution

Adaptar el proveedor nan para que la tira refleje el modelo de créditos, sin perder el caso del plan Gentle:

1. Cuentas con créditos (Inference/Premium): un medidor principal de créditos usados frente a la asignación del periodo, con consumo, asignación, restantes y fechas tomados del mismo payload del periodo actual. El ritmo de consumo y la fecha de agotamiento se calculan con ese mismo valor.
2. Packs de créditos: mostrarlos en el detalle como saldo aparte, sin sumarlos al denominador del periodo, salvo que se decida otra cosa en la revisión.
3. Plan Gentle: fuera de esta issue; lo cubre fix(nan): los medidores usan la cuota y el periodo de la cuenta (#252) #261 con los medidores por modelo.
4. Detección del modelo: decidir a partir del payload si la cuenta usa créditos o asignación por modelo, sin suponerlo por el nombre del plan. Si no se puede determinar, mostrarlo en lugar de inventar un tope.
5. Texto de plan y ayudas: retirar las cifras fijas de tokens por modelo para las cuentas con créditos.

Affected area

Application behavior

Scope and non-goals

Requisito previo: capturar con una API key real (censurada, sin claves ni datos personales) la respuesta actual de GET /v1/usage y de GET https://cloud-api.nan.builders/api/usage/quota de una cuenta Inference o Premium. El payload de #252 es del 8 de noviembre, anterior al cambio, y todavía traía cap por modelo. Hay que confirmar:

• Los nombres de los campos del periodo actual (asignación, créditos usados y restantes, packs).
• Si /api/usage/quota sigue devolviendo cap por modelo en las cuentas con créditos o ha cambiado de forma.
• Si alguno de los dos endpoints expone la ventana de 4 h de glm5.3.

Criterios de aceptación (pendientes de confirmar con el payload real):

• En una cuenta con créditos, la tira muestra el porcentaje de créditos del periodo, que coincide con el portal de NaN.
• El ritmo de consumo y la fecha de agotamiento usan la asignación de créditos del periodo.
• Los packs de créditos se distinguen de los créditos incluidos.
• Las cuentas del plan Gentle conservan los medidores por modelo de bug(nan): los medidores dividen por la cuota publicada del modelo y no por la asignación del plan de la cuenta #252.
• Los modelos sin contador y las imágenes no aparecen como consumo de créditos.
• Tests con los payloads reales como fixtures: cuenta con créditos, plan Gentle, primer periodo prorrateado, packs sin créditos incluidos y endpoint caído con fallback señalado.

Fuera de alcance:

• La ventana móvil de 4 h de glm5.3 como medidor propio, salvo que el payload la exponga y se decida incluirla.
• El límite mensual de imágenes.
• Calcular créditos a partir de tokens y precios por modelo: el consumo de créditos debe salir de la API, no de una tabla local.
• Compra o recarga de packs desde Quorb.

Decisión de alcance (cada suscripción con su artefacto):

• fix(nan): los medidores usan la cuota y el periodo de la cuenta (#252) #261 cubre los planes con asignación por modelo (Gentle): medidores por modelo con cap de la cuenta. En cuentas con créditos no muestra medidores por modelo ni el fallback a la cuota publicada.
• Esta issue cubre los planes con créditos (Inference/Premium): el medidor de créditos del periodo. Parte de la detección del tipo de cuenta que introduce fix(nan): los medidores usan la cuota y el periodo de la cuenta (#252) #261.

Alternatives considered