@hostwebhook/platform-contracts 0.8.1 → 0.10.0

package/dist/precios/index.d.ts

@@ -1,11 +1,23 @@
 /**
  * Lo que cuesta un token, por modelo.
  *
- * Un solo módulo por ahora: `tabla-de-precios`. Está en su propia carpeta
- * porque lo que va a crecer aquí son las tarifas —contexto largo, audio,
- * lotes— y no las formas de contrato, que es de lo que va `servicios/`.
+ * Dos módulos, y la diferencia entre ellos es DE DÓNDE SALE EL PRECIO:
+ *
+ *   - `tabla-de-precios`: la tabla que mantenemos a mano, contra la página de
+ *     cada proveedor. Es la fuente para casi todo, y también donde vive el
+ *     cálculo (`calculateCost`, `tarifaDelTramo`).
+ *   - `tarifas-de-openrouter`: el precio que trae el propio proveedor. Sus
+ *     ~425 modelos publican su tarifa junto a la lista, así que se convierten
+ *     y se pasan por el parámetro `tarifa` de `calculateCost` en vez de
+ *     copiarse a la tabla. Un proveedor futuro que también traiga su precio
+ *     entra por aquí, con su propio conversor y el mismo parámetro.
+ *
+ * Están en su propia carpeta porque lo que va a crecer aquí son las tarifas
+ * —contexto largo, audio, lotes, proveedores que se tarifan solos— y no las
+ * formas de contrato, que es de lo que va `servicios/`.
  *
  * ⚠️ Aquí NO van los precios de venta ni los ids de Stripe. Ver la cabecera de
  * `tabla-de-precios.ts`: son cosas distintas que se llaman igual.
  */
 export * from './tabla-de-precios';
+export * from './tarifas-de-openrouter';

package/dist/precios/index.js

@@ -17,11 +17,23 @@ Object.defineProperty(exports, "__esModule", { value: true });
 /**
  * Lo que cuesta un token, por modelo.
  *
- * Un solo módulo por ahora: `tabla-de-precios`. Está en su propia carpeta
- * porque lo que va a crecer aquí son las tarifas —contexto largo, audio,
- * lotes— y no las formas de contrato, que es de lo que va `servicios/`.
+ * Dos módulos, y la diferencia entre ellos es DE DÓNDE SALE EL PRECIO:
+ *
+ *   - `tabla-de-precios`: la tabla que mantenemos a mano, contra la página de
+ *     cada proveedor. Es la fuente para casi todo, y también donde vive el
+ *     cálculo (`calculateCost`, `tarifaDelTramo`).
+ *   - `tarifas-de-openrouter`: el precio que trae el propio proveedor. Sus
+ *     ~425 modelos publican su tarifa junto a la lista, así que se convierten
+ *     y se pasan por el parámetro `tarifa` de `calculateCost` en vez de
+ *     copiarse a la tabla. Un proveedor futuro que también traiga su precio
+ *     entra por aquí, con su propio conversor y el mismo parámetro.
+ *
+ * Están en su propia carpeta porque lo que va a crecer aquí son las tarifas
+ * —contexto largo, audio, lotes, proveedores que se tarifan solos— y no las
+ * formas de contrato, que es de lo que va `servicios/`.
  *
  * ⚠️ Aquí NO van los precios de venta ni los ids de Stripe. Ver la cabecera de
  * `tabla-de-precios.ts`: son cosas distintas que se llaman igual.
  */
 __exportStar(require("./tabla-de-precios"), exports);
+__exportStar(require("./tarifas-de-openrouter"), exports);

package/dist/precios/tabla-de-precios.d.ts

@@ -47,11 +47,52 @@
  * Se conservan modelos retirados a propósito: las trazas históricas siguen
  * consultándose y tienen que seguir cuadrando.
  *
+ * ## Lo que esta tabla deliberadamente NO contiene: OpenRouter
+ *
+ * Sus ~425 modelos NO están aquí y no van a estarlo. No es un hueco: es que su
+ * API publica el precio DE CADA MODELO en la misma respuesta que la lista, así
+ * que copiarlo aquí sería mantener a mano lo que ya nos dan, y quedarse viejo
+ * en silencio 425 veces —que es el fallo del que va la sección de arriba—.
+ *
+ * Se cobran por el otro camino, el que abre el parámetro `tarifa` de
+ * `calculateCost` e `isModelPriced`: quien tiene la respuesta de OpenRouter la
+ * pasa por `tarifaDeOpenRouter` (fichero de al lado) y entrega el
+ * `ModelPricing` resultante. Mismo cálculo, mismos tramos, otro origen del
+ * dato.
+ *
+ * ⚠️ Y por eso el id de OpenRouter NUNCA se recorta para buscarlo aquí:
+ * `"anthropic/claude-sonnet-5"` no es `"claude-sonnet-5"`. Comprarle un
+ * modelo a un revendedor no cuesta lo que comprárselo al laboratorio, así que
+ * dejar que caiga en esta tabla cobraría el precio de otro trato.
+ *
  * ## Lo que esta tabla NO modela (aceptable para estimar coste)
  *
- *   - Contexto largo: `gemini-3.1-pro` y `gemini-2.5-pro` casi doblan tarifa
- *     por encima de 200k tokens de entrada. Se usa siempre la base, así que
- *     INFRAVALORA los prompts muy largos.
+ *   - (RESUELTO, ver `umbralEntrada`) Contexto largo. Ya se modela en los diez
+ *     modelos que lo publican: los siete de OpenAI 5.4/5.5/5.6 a partir de
+ *     272.000 tokens de entrada, y `gemini-3.1-pro` / `gemini-2.5-pro` a partir
+ *     de 200.000. Es un ACANTILADO: la tarifa alta cubre la petición entera.
+ *   - (!) Lo que del contexto largo SIGUE sin modelarse: en `gpt-5.5` y en
+ *     `gpt-5.4` la ficha dice «for the full SESSION», no por petición. Basta que
+ *     UNA llamada de la sesión cruce 272k para que toda la sesión vaya a tarifa
+ *     alta. `calculateCost` es una función pura por llamada y no tiene noción de
+ *     sesión: ahí INFRAVALORA, y se dice en vez de fingir que se modela.
+ *   - ✅ Anthropic NO tiene tramos, y conviene dejarlo escrito en afirmativo:
+ *     su doc dice que «Claude 4.6 and later models include the full 1M token
+ *     context window at standard pricing». La regla que circula por terceros
+ *     diciendo que Sonnet 4.5 cobra 2x/1.5x por encima de 200k es FALSA. No
+ *     reintroducirla.
+ *   - (!) `gpt-5.6-sol` (y su alias `gpt-5.6`) está a precio PROMOCIONAL: la
+ *     propia tabla dice «available at least through November 21, 2026», y no
+ *     publica a cuánto revierte. Un tope calibrado sobre 4.00/20.00 tiene fecha
+ *     de caducidad documentada.
+ *   - (!) Google factura los tokens de RAZONAMIENTO a precio de salida — el
+ *     encabezado de su columna dice «Output price (including thinking tokens)».
+ *     Quien multiplique sólo los tokens visibles por `output` se queda corto, y
+ *     el razonamiento no se ve en la respuesta pero sí en la factura.
+ *   - (!) Claude 4.7 en adelante usa un tokenizador que produce ~30% MÁS tokens
+ *     para el mismo texto, y eso incluye Sonnet 5, Opus 5, Opus 4.8 y Opus 4.7,
+ *     no sólo Fable 5. Sonnet 5 a $2 frente a Sonnet 4.6 a $3 parece un 33%
+ *     más barato; con un 30% más de tokens el ahorro real se acerca a cero.
  *   - Audio: `gemini-2.5-flash` y `3.1-flash-lite` cobran más el audio que el
  *     texto. Aquí todo va a tarifa de texto.
  *   - Anthropic: `inference_geo` "us" multiplica por 1,1, y el modo rápido de
@@ -67,7 +108,42 @@
 export interface ModelPricing {
     input: number;
     output: number;
+    /**
+     * Tokens de ENTRADA por encima de los cuales la petición cambia de tarifa.
+     * Ausente = tarifa plana en toda la ventana, que es el caso de Anthropic y de
+     * casi todo lo demás.
+     *
+     * El nombre dice qué se mide: los dos proveedores que tienen tramos lo miden
+     * sobre el PROMPT, nunca sobre entrada+salida. En Google la palabra literal de
+     * las tres filas de su tabla es «prompts».
+     *
+     * (!) La comparación es ESTRICTA: OpenAI escribe «>272K» y Google «> 200k».
+     * Exactamente 272.000 va a tarifa base.
+     */
+    umbralEntrada?: number;
+    /**
+     * (!) NO es facturación marginal: es un ACANTILADO. La tarifa alta se aplica
+     * a TODOS los tokens de la petición, no sólo a los que exceden el umbral.
+     *
+     * Un prompt de 272.001 tokens en `gpt-5.5` se cobra ENTERO a $10, no 272.000
+     * a $5 más uno a $10. Cruzar el umbral por un token duplica la factura de
+     * entrada de esa llamada y encarece un 50 % su salida aunque la salida sean
+     * cincuenta tokens.
+     */
+    inputLargo?: number;
+    outputLargo?: number;
 }
+/**
+ * La tarifa que toca, según cuánta entrada lleve la petición.
+ *
+ * Se saca aparte de `calculateCost` porque quien quiera estimar ANTES de llamar
+ * —la reserva del tope de gasto del Chat Trigger— necesita la misma decisión sin
+ * tener aún los tokens de salida.
+ */
+export declare function tarifaDelTramo(precio: ModelPricing, tokensDeEntrada: number): {
+    input: number;
+    output: number;
+};
 export declare const MODEL_PRICING: Record<string, ModelPricing>;
 /**
  * Qué entrada de la tabla pone precio a este modelo, o `null` cuando de verdad
@@ -102,8 +178,36 @@ export declare const MODEL_PRICING: Record<string, ModelPricing>;
  * llamante un número inventado con pinta de bueno.
  */
 export declare function findPricingKey(model: string): string | null;
-/** True cuando la tabla sabe de verdad cuánto vale este modelo. */
-export declare function isModelPriced(model: string): boolean;
+/**
+ * True cuando sabemos de verdad cuánto vale este modelo.
+ *
+ * ## El segundo argumento: cuando el precio NO sale de la tabla
+ *
+ * Hay proveedores que traen su tarifa con el modelo —OpenRouter publica el
+ * precio de cada uno de sus ~425 en la misma respuesta que la lista—, y meter
+ * eso en `MODEL_PRICING` sería mantener a mano un dato que la API ya da. Para
+ * esos, quien llama trae la tarifa ya convertida y la pasa aquí.
+ *
+ * Los tres estados son distintos y hay que respetarlos:
+ *
+ *   - `undefined` (no se pasa nada) → decide la tabla, como siempre. Ningún
+ *     llamador de los de antes cambia de comportamiento.
+ *   - un `ModelPricing` → **sí lo sabemos**, y lo sabemos mejor que la tabla:
+ *     viene del proveedor. `true` sin mirar la tabla, aunque el modelo no esté
+ *     —que es justo el caso: `"anthropic/claude-sonnet-5"` no está ni va a
+ *     estar—.
+ *   - `null` → se preguntó y **no se sabe**. `false`.
+ *
+ * ⚠️ Ese `null` no es adorno. `tarifaDeOpenRouter` devuelve `null` cuando el
+ * modelo no publica precio utilizable, siguiendo el mismo criterio que
+ * `findPricingKey`: antes decir «no lo sé» que devolver un número inventado.
+ * Encadenarlos —`isModelPriced(id, tarifaDeOpenRouter(m))`— conserva esa
+ * distinción de punta a punta. Convertir el `null` en `undefined` por el
+ * camino (un `?? undefined`, un `||`) la pierde: preguntaría a la tabla, la
+ * tabla tampoco lo sabría, y saldría el mismo `false` por casualidad hoy y no
+ * mañana.
+ */
+export declare function isModelPriced(model: string, tarifa?: ModelPricing | null): boolean;
 /**
  * Coste en USD, redondeado a 6 decimales (precisión de micro-dólar).
  *
@@ -132,8 +236,30 @@ export declare function isModelPriced(model: string): boolean;
  * Antes se sumaba `reasoningTokens * precio_de_salida` ENCIMA de
  * `outputTokens` para openai y google: eso cobraba dos veces el mismo
  * pensamiento. El parámetro se conserva para no romper a quien ya lo pasa.
+ *
+ * ## `tarifa`: el precio que trae el proveedor
+ *
+ * Último y opcional, para que ningún llamador de los que ya existen cambie.
+ * Cuando se pasa, ES la tarifa: la tabla no se consulta y `model` sólo sirve
+ * ya para detectar el proveedor de los multiplicadores de caché. Es lo que
+ * usa OpenRouter, cuyos ~425 modelos publican su propio precio y por eso NO
+ * están en `MODEL_PRICING`; sirve igual para cualquier proveedor futuro que
+ * traiga el suyo.
+ *
+ * Los tres estados son los mismos que en `isModelPriced`: `undefined` decide
+ * la tabla, un objeto manda, y `null` significa «se preguntó y no se sabe» →
+ * coste 0, igual que un modelo ausente de la tabla, y con la misma trampa: 0
+ * no es gratis. Pregunta antes con `isModelPriced(model, tarifa)`.
+ *
+ * ⚠️ La tarifa que llega por parámetro pasa por `tarifaDelTramo` EXACTAMENTE
+ * igual que la de la tabla, y es a propósito que sea el mismo camino y no uno
+ * paralelo. Hoy nadie la usa con tramo —OpenRouter no publica umbrales, así
+ * que sus tarifas salen sin `umbralEntrada` y `tarifaDelTramo` las devuelve
+ * tal cual—, pero el día que un proveedor publique uno, funciona sin tocar
+ * nada. Un segundo camino sin tramos sería un acantilado que sólo se cobra por
+ * un lado.
  */
-export declare function calculateCost(model: string, inputTokens: number, outputTokens: number, cacheReadInputTokens?: number, cacheCreationInputTokens?: number, _reasoningTokens?: number): number;
+export declare function calculateCost(model: string, inputTokens: number, outputTokens: number, cacheReadInputTokens?: number, cacheCreationInputTokens?: number, _reasoningTokens?: number, tarifa?: ModelPricing | null): number;
 /** Los modelos que la tabla sabe poner en precio, en orden de declaración. */
 export declare function getKnownModels(): string[];
 /**

package/dist/precios/tabla-de-precios.js

@@ -48,11 +48,52 @@
  * Se conservan modelos retirados a propósito: las trazas históricas siguen
  * consultándose y tienen que seguir cuadrando.
  *
+ * ## Lo que esta tabla deliberadamente NO contiene: OpenRouter
+ *
+ * Sus ~425 modelos NO están aquí y no van a estarlo. No es un hueco: es que su
+ * API publica el precio DE CADA MODELO en la misma respuesta que la lista, así
+ * que copiarlo aquí sería mantener a mano lo que ya nos dan, y quedarse viejo
+ * en silencio 425 veces —que es el fallo del que va la sección de arriba—.
+ *
+ * Se cobran por el otro camino, el que abre el parámetro `tarifa` de
+ * `calculateCost` e `isModelPriced`: quien tiene la respuesta de OpenRouter la
+ * pasa por `tarifaDeOpenRouter` (fichero de al lado) y entrega el
+ * `ModelPricing` resultante. Mismo cálculo, mismos tramos, otro origen del
+ * dato.
+ *
+ * ⚠️ Y por eso el id de OpenRouter NUNCA se recorta para buscarlo aquí:
+ * `"anthropic/claude-sonnet-5"` no es `"claude-sonnet-5"`. Comprarle un
+ * modelo a un revendedor no cuesta lo que comprárselo al laboratorio, así que
+ * dejar que caiga en esta tabla cobraría el precio de otro trato.
+ *
  * ## Lo que esta tabla NO modela (aceptable para estimar coste)
  *
- *   - Contexto largo: `gemini-3.1-pro` y `gemini-2.5-pro` casi doblan tarifa
- *     por encima de 200k tokens de entrada. Se usa siempre la base, así que
- *     INFRAVALORA los prompts muy largos.
+ *   - (RESUELTO, ver `umbralEntrada`) Contexto largo. Ya se modela en los diez
+ *     modelos que lo publican: los siete de OpenAI 5.4/5.5/5.6 a partir de
+ *     272.000 tokens de entrada, y `gemini-3.1-pro` / `gemini-2.5-pro` a partir
+ *     de 200.000. Es un ACANTILADO: la tarifa alta cubre la petición entera.
+ *   - (!) Lo que del contexto largo SIGUE sin modelarse: en `gpt-5.5` y en
+ *     `gpt-5.4` la ficha dice «for the full SESSION», no por petición. Basta que
+ *     UNA llamada de la sesión cruce 272k para que toda la sesión vaya a tarifa
+ *     alta. `calculateCost` es una función pura por llamada y no tiene noción de
+ *     sesión: ahí INFRAVALORA, y se dice en vez de fingir que se modela.
+ *   - ✅ Anthropic NO tiene tramos, y conviene dejarlo escrito en afirmativo:
+ *     su doc dice que «Claude 4.6 and later models include the full 1M token
+ *     context window at standard pricing». La regla que circula por terceros
+ *     diciendo que Sonnet 4.5 cobra 2x/1.5x por encima de 200k es FALSA. No
+ *     reintroducirla.
+ *   - (!) `gpt-5.6-sol` (y su alias `gpt-5.6`) está a precio PROMOCIONAL: la
+ *     propia tabla dice «available at least through November 21, 2026», y no
+ *     publica a cuánto revierte. Un tope calibrado sobre 4.00/20.00 tiene fecha
+ *     de caducidad documentada.
+ *   - (!) Google factura los tokens de RAZONAMIENTO a precio de salida — el
+ *     encabezado de su columna dice «Output price (including thinking tokens)».
+ *     Quien multiplique sólo los tokens visibles por `output` se queda corto, y
+ *     el razonamiento no se ve en la respuesta pero sí en la factura.
+ *   - (!) Claude 4.7 en adelante usa un tokenizador que produce ~30% MÁS tokens
+ *     para el mismo texto, y eso incluye Sonnet 5, Opus 5, Opus 4.8 y Opus 4.7,
+ *     no sólo Fable 5. Sonnet 5 a $2 frente a Sonnet 4.6 a $3 parece un 33%
+ *     más barato; con un 30% más de tokens el ahorro real se acerca a cero.
  *   - Audio: `gemini-2.5-flash` y `3.1-flash-lite` cobran más el audio que el
  *     texto. Aquí todo va a tarifa de texto.
  *   - Anthropic: `inference_geo` "us" multiplica por 1,1, y el modo rápido de
@@ -67,25 +108,44 @@
  */
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.MODEL_ALTERNATIVES = exports.MODEL_PRICING = void 0;
+exports.tarifaDelTramo = tarifaDelTramo;
 exports.findPricingKey = findPricingKey;
 exports.isModelPriced = isModelPriced;
 exports.calculateCost = calculateCost;
 exports.getKnownModels = getKnownModels;
 exports.getSuggestedAlternative = getSuggestedAlternative;
+/**
+ * La tarifa que toca, según cuánta entrada lleve la petición.
+ *
+ * Se saca aparte de `calculateCost` porque quien quiera estimar ANTES de llamar
+ * —la reserva del tope de gasto del Chat Trigger— necesita la misma decisión sin
+ * tener aún los tokens de salida.
+ */
+function tarifaDelTramo(precio, tokensDeEntrada) {
+    if (precio.umbralEntrada === undefined) {
+        return { input: precio.input, output: precio.output };
+    }
+    if (tokensDeEntrada <= precio.umbralEntrada) {
+        return { input: precio.input, output: precio.output };
+    }
+    return { input: precio.inputLargo, output: precio.outputLargo };
+}
 exports.MODEL_PRICING = {
     // OpenAI — GPT series
-    'gpt-5.6-sol': { input: 4.00, output: 20.00 },
+    'gpt-5.6-sol': { input: 4.00, output: 20.00, umbralEntrada: 272000, inputLargo: 8.00, outputLargo: 30.00 },
     // `gpt-5.6` a secas es el alias documentado de Sol, y sin esta entrada caia
     // por prefijo en `gpt-5` — otro modelo y otro precio.
-    'gpt-5.6': { input: 4.00, output: 20.00 },
-    'gpt-5.6-terra': { input: 2.00, output: 12.00 },
-    'gpt-5.6-luna': { input: 0.20, output: 1.20 },
-    'gpt-5.5-pro': { input: 30.00, output: 180.00 },
-    'gpt-5.5': { input: 5.00, output: 30.00 },
-    'gpt-5.4-pro': { input: 30.00, output: 180.00 },
-    'gpt-5.4': { input: 2.50, output: 15.00 },
+    'gpt-5.6': { input: 4.00, output: 20.00, umbralEntrada: 272000, inputLargo: 8.00, outputLargo: 30.00 },
+    'gpt-5.6-terra': { input: 2.00, output: 12.00, umbralEntrada: 272000, inputLargo: 4.00, outputLargo: 18.00 },
+    'gpt-5.6-luna': { input: 0.20, output: 1.20, umbralEntrada: 272000, inputLargo: 0.40, outputLargo: 1.80 },
+    'gpt-5.5-pro': { input: 30.00, output: 180.00, umbralEntrada: 272000, inputLargo: 60.00, outputLargo: 270.00 },
+    'gpt-5.5': { input: 5.00, output: 30.00, umbralEntrada: 272000, inputLargo: 10.00, outputLargo: 45.00 },
+    'gpt-5.4-pro': { input: 30.00, output: 180.00, umbralEntrada: 272000, inputLargo: 60.00, outputLargo: 270.00 },
+    'gpt-5.4': { input: 2.50, output: 15.00, umbralEntrada: 272000, inputLargo: 5.00, outputLargo: 22.50 },
     'gpt-5.4-mini': { input: 0.75, output: 4.50 },
     'gpt-5.4-nano': { input: 0.20, output: 1.25 },
+    // (!) SIN tramo, y es deliberado: es el unico *-pro de la familia 5.x cuya
+    // ficha no publica umbral de contexto largo. Verificado fila a fila.
     'gpt-5.2-pro': { input: 21.00, output: 168.00 },
     'gpt-5.2': { input: 1.75, output: 14.00 },
     'gpt-5.1': { input: 1.25, output: 10.00 },
@@ -169,10 +229,10 @@ exports.MODEL_PRICING = {
     'gemini-3.6-flash': { input: 0.75, output: 3.75 },
     'gemini-3.5-flash-lite': { input: 0.30, output: 2.50 },
     'gemini-3.5-flash': { input: 1.50, output: 9.00 },
-    'gemini-3.1-pro': { input: 2.00, output: 12.00 },
+    'gemini-3.1-pro': { input: 2.00, output: 12.00, umbralEntrada: 200000, inputLargo: 4.00, outputLargo: 18.00 },
     'gemini-3.1-flash-lite': { input: 0.25, output: 1.50 },
     'gemini-3-flash': { input: 0.50, output: 3.00 },
-    'gemini-2.5-pro': { input: 1.25, output: 10.00 },
+    'gemini-2.5-pro': { input: 1.25, output: 10.00, umbralEntrada: 200000, inputLargo: 2.50, outputLargo: 15.00 },
     'gemini-2.5-flash': { input: 0.30, output: 2.50 },
     'gemini-2.5-flash-lite': { input: 0.10, output: 0.40 },
     'gemini-2.0-flash': { input: 0.10, output: 0.40 },
@@ -264,8 +324,38 @@ function findPricingKey(model) {
     }
     return mejor;
 }
-/** True cuando la tabla sabe de verdad cuánto vale este modelo. */
-function isModelPriced(model) {
+/**
+ * True cuando sabemos de verdad cuánto vale este modelo.
+ *
+ * ## El segundo argumento: cuando el precio NO sale de la tabla
+ *
+ * Hay proveedores que traen su tarifa con el modelo —OpenRouter publica el
+ * precio de cada uno de sus ~425 en la misma respuesta que la lista—, y meter
+ * eso en `MODEL_PRICING` sería mantener a mano un dato que la API ya da. Para
+ * esos, quien llama trae la tarifa ya convertida y la pasa aquí.
+ *
+ * Los tres estados son distintos y hay que respetarlos:
+ *
+ *   - `undefined` (no se pasa nada) → decide la tabla, como siempre. Ningún
+ *     llamador de los de antes cambia de comportamiento.
+ *   - un `ModelPricing` → **sí lo sabemos**, y lo sabemos mejor que la tabla:
+ *     viene del proveedor. `true` sin mirar la tabla, aunque el modelo no esté
+ *     —que es justo el caso: `"anthropic/claude-sonnet-5"` no está ni va a
+ *     estar—.
+ *   - `null` → se preguntó y **no se sabe**. `false`.
+ *
+ * ⚠️ Ese `null` no es adorno. `tarifaDeOpenRouter` devuelve `null` cuando el
+ * modelo no publica precio utilizable, siguiendo el mismo criterio que
+ * `findPricingKey`: antes decir «no lo sé» que devolver un número inventado.
+ * Encadenarlos —`isModelPriced(id, tarifaDeOpenRouter(m))`— conserva esa
+ * distinción de punta a punta. Convertir el `null` en `undefined` por el
+ * camino (un `?? undefined`, un `||`) la pierde: preguntaría a la tabla, la
+ * tabla tampoco lo sabría, y saldría el mismo `false` por casualidad hoy y no
+ * mañana.
+ */
+function isModelPriced(model, tarifa) {
+    if (tarifa !== undefined)
+        return tarifa !== null;
     return findPricingKey(model) !== null;
 }
 /* ── Coste ───────────────────────────────────────────────────────── */
@@ -297,20 +387,78 @@ function isModelPriced(model) {
  * Antes se sumaba `reasoningTokens * precio_de_salida` ENCIMA de
  * `outputTokens` para openai y google: eso cobraba dos veces el mismo
  * pensamiento. El parámetro se conserva para no romper a quien ya lo pasa.
+ *
+ * ## `tarifa`: el precio que trae el proveedor
+ *
+ * Último y opcional, para que ningún llamador de los que ya existen cambie.
+ * Cuando se pasa, ES la tarifa: la tabla no se consulta y `model` sólo sirve
+ * ya para detectar el proveedor de los multiplicadores de caché. Es lo que
+ * usa OpenRouter, cuyos ~425 modelos publican su propio precio y por eso NO
+ * están en `MODEL_PRICING`; sirve igual para cualquier proveedor futuro que
+ * traiga el suyo.
+ *
+ * Los tres estados son los mismos que en `isModelPriced`: `undefined` decide
+ * la tabla, un objeto manda, y `null` significa «se preguntó y no se sabe» →
+ * coste 0, igual que un modelo ausente de la tabla, y con la misma trampa: 0
+ * no es gratis. Pregunta antes con `isModelPriced(model, tarifa)`.
+ *
+ * ⚠️ La tarifa que llega por parámetro pasa por `tarifaDelTramo` EXACTAMENTE
+ * igual que la de la tabla, y es a propósito que sea el mismo camino y no uno
+ * paralelo. Hoy nadie la usa con tramo —OpenRouter no publica umbrales, así
+ * que sus tarifas salen sin `umbralEntrada` y `tarifaDelTramo` las devuelve
+ * tal cual—, pero el día que un proveedor publique uno, funciona sin tocar
+ * nada. Un segundo camino sin tramos sería un acantilado que sólo se cobra por
+ * un lado.
  */
-function calculateCost(model, inputTokens, outputTokens, cacheReadInputTokens = 0, cacheCreationInputTokens = 0, _reasoningTokens = 0) {
-    const key = findPricingKey(model);
-    if (!key)
-        return 0;
-    const pricing = exports.MODEL_PRICING[key];
-    const provider = detectProvider(key);
-    const inputCost = (inputTokens / 1000000) * pricing.input;
-    const outputCost = (outputTokens / 1000000) * pricing.output;
+function calculateCost(model, inputTokens, outputTokens, cacheReadInputTokens = 0, cacheCreationInputTokens = 0, _reasoningTokens = 0, tarifa) {
+    let pricing;
+    /* Sobre qué cadena se detecta el proveedor de los multiplicadores de caché:
+       con tabla, sobre la CLAVE que ganó (`claude-sonnet-4-6-20260101` resuelve
+       a `claude-sonnet-4-6`); con tarifa por parámetro no hay clave, así que
+       sobre el modelo pedido — que en OpenRouter lleva el laboratorio delante
+       (`anthropic/claude-sonnet-5`) y `detectProvider` reconoce igual. */
+    let paraDetectarProveedor;
+    if (tarifa !== undefined) {
+        if (tarifa === null)
+            return 0; // se preguntó y no se sabe
+        pricing = tarifa;
+        paraDetectarProveedor = model;
+    }
+    else {
+        const key = findPricingKey(model);
+        if (!key)
+            return 0;
+        pricing = exports.MODEL_PRICING[key];
+        paraDetectarProveedor = key;
+    }
+    const provider = detectProvider(paraDetectarProveedor);
+    /**
+     * Los tokens cacheados CUENTAN para decidir el tramo: fisicamente son el
+     * prompt, y en un tope de gasto errar del lado caro es errar del lado seguro.
+     *
+     * (!) Ninguno de los dos proveedores lo dice explicitamente, asi que es una
+     * decision nuestra, no una cita. Hoy es INERTE —los llamadores pasan tres
+     * argumentos y el emisor de trazas nunca rellena los campos de cache—, pero
+     * hay que confirmarla antes de que alguien empiece a rellenarlos.
+     */
+    const entradaParaElTramo = inputTokens + cacheReadInputTokens + cacheCreationInputTokens;
+    /* `tarifaAplicada` y no `tarifa` a secas porque `tarifa` es ahora el
+       PARÁMETRO, y son dos cosas distintas a propósito: `tarifa` es lo que trajo
+       quien llama —o nada—, y esto es lo que se cobra de verdad tras decidir el
+       tramo. Las dos pasan por aquí, venga el precio de la tabla o de fuera. */
+    const tarifaAplicada = tarifaDelTramo(pricing, entradaParaElTramo);
+    const inputCost = (inputTokens / 1000000) * tarifaAplicada.input;
+    const outputCost = (outputTokens / 1000000) * tarifaAplicada.output;
     // Caché: multiplicadores por proveedor
     const cacheReadMul = CACHE_READ_MULTIPLIERS[provider] ?? 0.1;
     const cacheCreationMul = CACHE_CREATION_MULTIPLIERS[provider] ?? 0;
-    const cacheReadCost = (cacheReadInputTokens / 1000000) * pricing.input * cacheReadMul;
-    const cacheCreationCost = (cacheCreationInputTokens / 1000000) * pricing.input * cacheCreationMul;
+    // Sobre `tarifaAplicada.input`, no sobre `pricing.input`: en tramo alto la
+    // cache tambien se encarece, que es lo que dice la tabla de Google —su fila
+    // de cache esta partida por tamano de prompt igual que las otras dos.
+    const cacheReadCost = (cacheReadInputTokens / 1000000) * tarifaAplicada.input * cacheReadMul;
+    const cacheCreationCost = (cacheCreationInputTokens / 1000000) *
+        tarifaAplicada.input *
+        cacheCreationMul;
     return (Math.round((inputCost + outputCost + cacheReadCost + cacheCreationCost) * 1000000) / 1000000);
 }
 /** Los modelos que la tabla sabe poner en precio, en orden de declaración. */

package/dist/precios/tarifas-de-openrouter.d.ts

@@ -0,0 +1,99 @@
+/**
+ * De lo que publica OpenRouter a un `ModelPricing` nuestro.
+ *
+ * ## Por qué hace falta convertir nada
+ *
+ * Porque las dos puntas miden distinto, y en las dos dimensiones a la vez:
+ *
+ *   | | OpenRouter | `ModelPricing` |
+ *   |-|-|-|
+ *   | unidad | **por token** | **por millón de tokens** |
+ *   | tipo   | **cadena**    | **número** |
+ *
+ * `{"prompt": "0.0000001"}` son $0,10 el millón. Un `parseFloat` sin el
+ * `* 1_000_000` cobra un millón de veces de menos, y como el resultado
+ * redondea a cero micro-dólares, un tope de gasto puesto encima no salta
+ * jamás. Es el mismo modo de fallo que un modelo ausente de la tabla: sale 0 y
+ * nadie se entera.
+ *
+ * ## La decisión que importa: `"0"` NO es lo mismo que ausente
+ *
+ * Los dos casos existen HOY, contados sobre la respuesta real (2026-08-31, 425
+ * modelos):
+ *
+ *   - **21 modelos gratis de verdad**, los `:free`, con `pricing` a `"0"`. Eso
+ *     es un precio CONOCIDO que resulta ser cero, y hay que poder cobrarlo como
+ *     tal: `{ input: 0, output: 0 }`.
+ *   - **5 modelos con `"-1"`**: `openrouter/auto`, `auto-beta`, `fusion`,
+ *     `pareto-code` y `bodybuilder`. Son routers dentro del router — lo que
+ *     cuesten depende de a dónde acaben enrutando, y OpenRouter lo dice con ese
+ *     `-1`. Eso es **no lo sabemos**, y ahí se devuelve `null`.
+ *
+ * Un modelo sin `pricing`, con el campo a `null` o con basura no numérica cae
+ * también en `null`. Hoy no hay ninguno —los 425 traen `prompt` y `completion`—
+ * pero es una respuesta de red y nada nuestro lo garantiza mañana.
+ *
+ * El criterio es el que ya tiene `findPricingKey`: antes decir «no lo sé» que
+ * devolver un número inventado. Los dos casos acaban en un coste de 0 dólares
+ * si nadie mira, y significan lo contrario: «esta llamada no cuesta nada»
+ * frente a «esta llamada puede costar cualquier cosa». Quien ponga un tope
+ * tiene que preguntar con `isModelPriced(id, tarifa)`, que distingue el objeto
+ * del `null`, y no mirar el número.
+ *
+ * ⚠️ Un `-1` que pasara el filtro se convertiría en −$1.000.000 el millón: el
+ * gasto acumulado BAJARÍA al usarlo, y el tope se alejaría cuanto más se
+ * gastara. Cualquier cosa que no sea un número finito y ≥ 0 es desconocido.
+ *
+ * ## Lo que esta conversión NO trae, y se dice en vez de fingir
+ *
+ *   - **La caché.** `input_cache_read`, `input_cache_write` y hasta
+ *     `input_cache_write_1h` vienen en la respuesta y aquí se ignoran, porque
+ *     `ModelPricing` no tiene dónde meterlos: el modelo de caché de
+ *     `calculateCost` son multiplicadores por proveedor, no precios absolutos.
+ *     Consecuencia concreta: a un modelo de OpenRouter la caché se le estima
+ *     con el multiplicador que salga de `detectProvider` sobre su id, no con su
+ *     precio real. Hoy es inerte —el emisor de trazas no rellena los campos de
+ *     caché— pero deja de serlo el día que alguien los rellene. Cerrarlo es
+ *     dar campos absolutos de caché a `ModelPricing`, no parchear esto.
+ *   - **Tramos de contexto largo.** OpenRouter no publica umbrales, así que
+ *     las tarifas salen SIN `umbralEntrada` y `tarifaDelTramo` las devuelve
+ *     planas. No es que se ignore un tramo: es que no hay ninguno que leer.
+ *   - **Lo que no se cobra por token**: `request` (precio por petición),
+ *     `image`, `web_search`, `internal_reasoning`. Un modelo con `request` > 0
+ *     sale INFRAVALORADO por lo que cueste la petición en sí.
+ */
+import type { ModeloDeOpenRouter, PrecioDeOpenRouter } from '@hostwebhook/node-types';
+import type { ModelPricing } from './tabla-de-precios';
+/**
+ * La tarifa de un modelo de OpenRouter, o `null` cuando no se sabe.
+ *
+ * Acepta el modelo entero —que es lo que se tiene tras el fetch— o su bloque
+ * `pricing` suelto.
+ *
+ * ⚠️ Hacen falta LAS DOS mitades. Con `prompt` pero sin `completion` no se
+ * devuelve media tarifa poniendo la salida a 0: la salida es la cara —un 5x
+ * sobre la entrada es lo normal—, así que una tarifa a medias no infravalora
+ * un poco, infravalora justo por donde duele. O se sabe entero o no se sabe.
+ */
+export declare function tarifaDeOpenRouter(modelo: ModeloDeOpenRouter | PrecioDeOpenRouter | null | undefined): ModelPricing | null;
+/**
+ * Un índice `id → tarifa` a partir del catálogo entero.
+ *
+ * Para quien va a tarifar muchas llamadas contra una sola respuesta —el
+ * selector del dashboard, o un caché de proceso en la api— en vez de recorrer
+ * los 425 por cada llamada.
+ *
+ * ⚠️ Los modelos cuya tarifa no se conoce **NO entran en el mapa**, y esa
+ * ausencia es la información: `mapa.get(id)` devuelve `undefined`, que es
+ * precisamente lo que `calculateCost` interpreta como «mira la tabla» y NO
+ * como «no se sabe». Quien consulte este mapa tiene que convertir ese hueco en
+ * un `null` explícito antes de pasarlo:
+ *
+ *     const tarifa = mapa.get(id) ?? null;   // ← el `?? null` es obligatorio
+ *     if (!isModelPriced(id, tarifa)) { … }
+ *
+ * Se deja así, y no metiendo `null`s en el mapa, porque un `Map` con valores
+ * nulos invita a `mapa.has(id)` como si fuera «lo sé», que es la pregunta
+ * equivocada.
+ */
+export declare function tarifasDeOpenRouter(modelos: ModeloDeOpenRouter[] | null | undefined): Map<string, ModelPricing>;

package/dist/precios/tarifas-de-openrouter.js

@@ -0,0 +1,154 @@
+"use strict";
+/**
+ * De lo que publica OpenRouter a un `ModelPricing` nuestro.
+ *
+ * ## Por qué hace falta convertir nada
+ *
+ * Porque las dos puntas miden distinto, y en las dos dimensiones a la vez:
+ *
+ *   | | OpenRouter | `ModelPricing` |
+ *   |-|-|-|
+ *   | unidad | **por token** | **por millón de tokens** |
+ *   | tipo   | **cadena**    | **número** |
+ *
+ * `{"prompt": "0.0000001"}` son $0,10 el millón. Un `parseFloat` sin el
+ * `* 1_000_000` cobra un millón de veces de menos, y como el resultado
+ * redondea a cero micro-dólares, un tope de gasto puesto encima no salta
+ * jamás. Es el mismo modo de fallo que un modelo ausente de la tabla: sale 0 y
+ * nadie se entera.
+ *
+ * ## La decisión que importa: `"0"` NO es lo mismo que ausente
+ *
+ * Los dos casos existen HOY, contados sobre la respuesta real (2026-08-31, 425
+ * modelos):
+ *
+ *   - **21 modelos gratis de verdad**, los `:free`, con `pricing` a `"0"`. Eso
+ *     es un precio CONOCIDO que resulta ser cero, y hay que poder cobrarlo como
+ *     tal: `{ input: 0, output: 0 }`.
+ *   - **5 modelos con `"-1"`**: `openrouter/auto`, `auto-beta`, `fusion`,
+ *     `pareto-code` y `bodybuilder`. Son routers dentro del router — lo que
+ *     cuesten depende de a dónde acaben enrutando, y OpenRouter lo dice con ese
+ *     `-1`. Eso es **no lo sabemos**, y ahí se devuelve `null`.
+ *
+ * Un modelo sin `pricing`, con el campo a `null` o con basura no numérica cae
+ * también en `null`. Hoy no hay ninguno —los 425 traen `prompt` y `completion`—
+ * pero es una respuesta de red y nada nuestro lo garantiza mañana.
+ *
+ * El criterio es el que ya tiene `findPricingKey`: antes decir «no lo sé» que
+ * devolver un número inventado. Los dos casos acaban en un coste de 0 dólares
+ * si nadie mira, y significan lo contrario: «esta llamada no cuesta nada»
+ * frente a «esta llamada puede costar cualquier cosa». Quien ponga un tope
+ * tiene que preguntar con `isModelPriced(id, tarifa)`, que distingue el objeto
+ * del `null`, y no mirar el número.
+ *
+ * ⚠️ Un `-1` que pasara el filtro se convertiría en −$1.000.000 el millón: el
+ * gasto acumulado BAJARÍA al usarlo, y el tope se alejaría cuanto más se
+ * gastara. Cualquier cosa que no sea un número finito y ≥ 0 es desconocido.
+ *
+ * ## Lo que esta conversión NO trae, y se dice en vez de fingir
+ *
+ *   - **La caché.** `input_cache_read`, `input_cache_write` y hasta
+ *     `input_cache_write_1h` vienen en la respuesta y aquí se ignoran, porque
+ *     `ModelPricing` no tiene dónde meterlos: el modelo de caché de
+ *     `calculateCost` son multiplicadores por proveedor, no precios absolutos.
+ *     Consecuencia concreta: a un modelo de OpenRouter la caché se le estima
+ *     con el multiplicador que salga de `detectProvider` sobre su id, no con su
+ *     precio real. Hoy es inerte —el emisor de trazas no rellena los campos de
+ *     caché— pero deja de serlo el día que alguien los rellene. Cerrarlo es
+ *     dar campos absolutos de caché a `ModelPricing`, no parchear esto.
+ *   - **Tramos de contexto largo.** OpenRouter no publica umbrales, así que
+ *     las tarifas salen SIN `umbralEntrada` y `tarifaDelTramo` las devuelve
+ *     planas. No es que se ignore un tramo: es que no hay ninguno que leer.
+ *   - **Lo que no se cobra por token**: `request` (precio por petición),
+ *     `image`, `web_search`, `internal_reasoning`. Un modelo con `request` > 0
+ *     sale INFRAVALORADO por lo que cueste la petición en sí.
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.tarifaDeOpenRouter = tarifaDeOpenRouter;
+exports.tarifasDeOpenRouter = tarifasDeOpenRouter;
+/** Tokens por unidad de `ModelPricing`. El nombre está para que el `* 1e6` de
+ *  abajo no parezca una constante mágica: es exactamente este cambio de
+ *  unidad, de por-token a por-millón. */
+const TOKENS_POR_UNIDAD_DE_TARIFA = 1000000;
+/**
+ * USD por millón a partir de un campo por token, o `null` si no se sabe.
+ *
+ * El redondeo a 9 decimales no es cosmético: `parseFloat('0.0000001') * 1e6`
+ * da `0.09999999999999999` en coma flotante, no `0.1`. Sin recortar, cada
+ * tarifa llegaría con una cola de basura que luego aparece en cualquier
+ * comparación y en cualquier importe mostrado. Nueve decimales borra la cola
+ * —que vive quince órdenes de magnitud más abajo— sin tocar el precio más
+ * ridículo que OpenRouter llegue a publicar.
+ */
+function porMillon(valor) {
+    /* Se aceptan cadena y número. La API manda cadenas, pero un consumidor que
+       haya normalizado el JSON antes de llegar aquí no tiene por qué perder el
+       dato por eso. */
+    const crudo = typeof valor === 'string' ? Number.parseFloat(valor)
+        : typeof valor === 'number' ? valor
+            : NaN;
+    // NaN, Infinity y negativos: desconocido, no cero. Ver la cabecera.
+    if (!Number.isFinite(crudo) || crudo < 0)
+        return null;
+    const porMillonDeTokens = crudo * TOKENS_POR_UNIDAD_DE_TARIFA;
+    return Math.round(porMillonDeTokens * 1e9) / 1e9;
+}
+/**
+ * La tarifa de un modelo de OpenRouter, o `null` cuando no se sabe.
+ *
+ * Acepta el modelo entero —que es lo que se tiene tras el fetch— o su bloque
+ * `pricing` suelto.
+ *
+ * ⚠️ Hacen falta LAS DOS mitades. Con `prompt` pero sin `completion` no se
+ * devuelve media tarifa poniendo la salida a 0: la salida es la cara —un 5x
+ * sobre la entrada es lo normal—, así que una tarifa a medias no infravalora
+ * un poco, infravalora justo por donde duele. O se sabe entero o no se sabe.
+ */
+function tarifaDeOpenRouter(modelo) {
+    if (!modelo || typeof modelo !== 'object')
+        return null;
+    const pricing = 'pricing' in modelo
+        ? modelo.pricing
+        : modelo;
+    if (!pricing || typeof pricing !== 'object')
+        return null;
+    const input = porMillon(pricing.prompt);
+    const output = porMillon(pricing.completion);
+    if (input === null || output === null)
+        return null;
+    /* Sin `umbralEntrada`: OpenRouter no publica tramos. Ver la cabecera. */
+    return { input, output };
+}
+/**
+ * Un índice `id → tarifa` a partir del catálogo entero.
+ *
+ * Para quien va a tarifar muchas llamadas contra una sola respuesta —el
+ * selector del dashboard, o un caché de proceso en la api— en vez de recorrer
+ * los 425 por cada llamada.
+ *
+ * ⚠️ Los modelos cuya tarifa no se conoce **NO entran en el mapa**, y esa
+ * ausencia es la información: `mapa.get(id)` devuelve `undefined`, que es
+ * precisamente lo que `calculateCost` interpreta como «mira la tabla» y NO
+ * como «no se sabe». Quien consulte este mapa tiene que convertir ese hueco en
+ * un `null` explícito antes de pasarlo:
+ *
+ *     const tarifa = mapa.get(id) ?? null;   // ← el `?? null` es obligatorio
+ *     if (!isModelPriced(id, tarifa)) { … }
+ *
+ * Se deja así, y no metiendo `null`s en el mapa, porque un `Map` con valores
+ * nulos invita a `mapa.has(id)` como si fuera «lo sé», que es la pregunta
+ * equivocada.
+ */
+function tarifasDeOpenRouter(modelos) {
+    const mapa = new Map();
+    if (!Array.isArray(modelos))
+        return mapa;
+    for (const modelo of modelos) {
+        if (!modelo || typeof modelo.id !== 'string' || modelo.id === '')
+            continue;
+        const tarifa = tarifaDeOpenRouter(modelo);
+        if (tarifa)
+            mapa.set(modelo.id, tarifa);
+    }
+    return mapa;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hostwebhook/platform-contracts",
-  "version": "0.8.1",
+  "version": "0.10.0",
   "description": "Contratos compartidos entre los servicios de HostWebhook: addons del plan, identidad interna, y las formas que cruzan una frontera de red",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
@@ -26,6 +26,6 @@
   },
   "peerDependencies": {
     "@nestjs/common": ">=11.0.0 <12",
-    "@hostwebhook/node-types": ">=1.67.0 <2"
+    "@hostwebhook/node-types": ">=1.68.0 <2"
   }
 }