@hostwebhook/platform-contracts 0.9.0 → 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,6 +47,24 @@
  * 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)
  *
  *   - (RESUELTO, ver `umbralEntrada`) Contexto largo. Ya se modela en los diez
@@ -160,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).
  *
@@ -190,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,6 +48,24 @@
  * 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)
  *
  *   - (RESUELTO, ver `umbralEntrada`) Contexto largo. Ya se modela en los diez
@@ -306,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 ───────────────────────────────────────────────────────── */
@@ -339,13 +387,51 @@ 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);
+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.
@@ -356,17 +442,23 @@ function calculateCost(model, inputTokens, outputTokens, cacheReadInputTokens =
      * hay que confirmarla antes de que alguien empiece a rellenarlos.
      */
     const entradaParaElTramo = inputTokens + cacheReadInputTokens + cacheCreationInputTokens;
-    const tarifa = tarifaDelTramo(pricing, entradaParaElTramo);
-    const inputCost = (inputTokens / 1000000) * tarifa.input;
-    const outputCost = (outputTokens / 1000000) * tarifa.output;
+    /* `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;
-    // Sobre `tarifa.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) * tarifa.input * cacheReadMul;
-    const cacheCreationCost = (cacheCreationInputTokens / 1000000) * tarifa.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.9.0",
+  "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"
   }
 }