@hostwebhook/node-types 1.68.0 → 1.70.0

package/dist/esm/openrouter.d.ts

@@ -0,0 +1,142 @@
+/**
+ * El catálogo VIVO de OpenRouter: la forma de lo que devuelve su API y cómo se
+ * convierte en las mismas opciones que ya pintan los desplegables.
+ *
+ * ## Por qué este proveedor no tiene lista en `llm-models.ts`
+ *
+ * Porque no es un laboratorio, es un router: revende ~425 modelos de otros
+ * detrás de una sola clave, y el conjunto se mueve solo. La lista entera está
+ * en `GET https://openrouter.ai/api/v1/models`, que es **abierto y sin clave**
+ * —se puede pedir antes de que el usuario haya pegado ninguna— y cada entrada
+ * trae su `context_length` y **su propio precio**. Copiar eso a mano a
+ * `LLM_MODELS` y a `MODEL_PRICING` sería mantener a mano lo que la API ya da,
+ * con 425 oportunidades de que se quede viejo en silencio.
+ *
+ * ## El reparto, que es lo que hay que entender antes de tocar esto
+ *
+ * De la MISMA respuesta salen dos cosas, y viven en paquetes distintos porque
+ * son de dueños distintos:
+ *
+ *   - **el catálogo** (id, nombre, ventana de contexto) → aquí, porque el
+ *     catálogo de modelos es de este fichero desde siempre;
+ *   - **la tarifa** (`pricing`) → `tarifaDeOpenRouter` en
+ *     `@hostwebhook/platform-contracts`, porque el precio de un token es de
+ *     ese paquete y no de éste.
+ *
+ * Y no al revés: este paquete NO puede importar `ModelPricing`
+ * —`platform-contracts` depende de éste, no al contrario—, así que el tipo que
+ * cruza es el crudo `ModeloDeOpenRouter`. Quien pinte el selector hace UN solo
+ * fetch y pasa cada entrada por las dos funciones.
+ *
+ * ## ⚠️ Esto es una respuesta de red, no un fichero nuestro
+ *
+ * Todo lo que no sea `id` va opcional a propósito. No porque OpenRouter lo
+ * omita hoy, sino porque nada nuestro impide que lo omita mañana, y un campo
+ * declarado obligatorio que llega `undefined` no falla al parsear —TypeScript
+ * no valida en runtime—: falla más tarde y más lejos, leyendo una propiedad de
+ * algo que no está. `id` es la única excepción porque sin él la entrada no
+ * identifica a ningún modelo y no hay nada que ofrecer.
+ *
+ * Verificado contra la respuesta real el 2026-08-31: 425 modelos, los 425 con
+ * `pricing.prompt` y `pricing.completion`, y algunos con un
+ * `top_provider.context_length` MENOR que su `context_length` anunciado.
+ */
+import type { LlmModelOption } from './llm-models.js';
+/** El endpoint del catálogo. Abierto: no lleva `Authorization`. */
+export declare const URL_DE_MODELOS_DE_OPENROUTER = "https://openrouter.ai/api/v1/models";
+/**
+ * El bloque `pricing` de un modelo.
+ *
+ * ⚠️ Dos trampas, las dos verificadas contra la respuesta real:
+ *
+ *   1. Los valores son **cadenas**, no números: `"0.0000001"`.
+ *   2. Son **por token**, no por millón. `"0.0000001"` = $0,10 por millón.
+ *
+ * O sea que ninguno de estos números se puede meter en un `ModelPricing` sin
+ * pasar por `tarifaDeOpenRouter`, que hace las dos conversiones.
+ *
+ * Se tipa como índice abierto porque OpenRouter publica más claves de las que
+ * usamos (`request`, `image`, `web_search`, `internal_reasoning`, y las de
+ * caché) y añade más sin avisar.
+ */
+export interface PrecioDeOpenRouter {
+    /** USD por token de ENTRADA, como cadena. */
+    prompt?: string | null;
+    /** USD por token de SALIDA, como cadena. */
+    completion?: string | null;
+    /** USD por token leído de caché. Hoy no se usa: ver `tarifaDeOpenRouter`. */
+    input_cache_read?: string | null;
+    /** USD por token escrito en caché. Hoy no se usa. */
+    input_cache_write?: string | null;
+    /** Caché de una hora, cuando el modelo la ofrece. Hoy no se usa. */
+    input_cache_write_1h?: string | null;
+    [otras: string]: unknown;
+}
+/** Una entrada del catálogo de OpenRouter. */
+export interface ModeloDeOpenRouter {
+    /**
+     * Lo que se le manda a la API como `model`, con el laboratorio delante:
+     * `"anthropic/claude-sonnet-5"`, `"openai/gpt-5.6-luna"`.
+     *
+     * ⚠️ Ese prefijo es parte del id y NO se quita. Un `"anthropic/..."`
+     * recortado a `"claude-sonnet-5"` cobraría la tarifa de la tabla estática
+     * —la de comprarle a Anthropic directamente— y OpenRouter no cobra eso.
+     */
+    id: string;
+    /** El id sin el sufijo de variante (`:free`, `:nitro`, `:floor`). */
+    canonical_slug?: string;
+    /** Nombre para humanos: `"Anthropic: Claude Sonnet 5"`. */
+    name?: string;
+    /** Ventana efectiva en TOKENS, tal y como la publica el proveedor. */
+    context_length?: number | null;
+    pricing?: PrecioDeOpenRouter | null;
+    architecture?: {
+        input_modalities?: string[];
+        output_modalities?: string[];
+        tokenizer?: string;
+        [otras: string]: unknown;
+    } | null;
+    top_provider?: {
+        context_length?: number | null;
+        max_completion_tokens?: number | null;
+        is_moderated?: boolean;
+        [otras: string]: unknown;
+    } | null;
+    /** Qué parámetros acepta: `"tools"`, `"reasoning"`, `"structured_outputs"`… */
+    supported_parameters?: string[] | null;
+    [otras: string]: unknown;
+}
+/** El sobre: `{ data: [...] }`. */
+export interface RespuestaDeModelosDeOpenRouter {
+    data?: ModeloDeOpenRouter[] | null;
+}
+/**
+ * Las opciones del desplegable a partir de la respuesta cruda.
+ *
+ * Devuelve `LlmModelOption`, el MISMO tipo que `LLM_MODELS`, para que el
+ * selector no tenga dos formas de modelo según el proveedor: la única
+ * diferencia entre un catálogo y el otro es de dónde salió la lista.
+ *
+ * ⚠️ Ninguna opción sale `recommended`. En los catálogos estáticos esa marca
+ * la pone una persona que ha mirado los precios; aquí no hay nadie mirando, y
+ * una recomendación automática —«el primero», «el más barato»— sería una
+ * decisión de producto tomada por accidente. Sin `recommended`,
+ * `getDefaultModel('openrouter')` sigue siendo `''` y elegir es del usuario.
+ *
+ * Acepta el sobre entero o el array suelto porque quien llama a veces ya lo ha
+ * desenvuelto, y tolera basura (`null`, entradas sin `id`) devolviendo lo que
+ * sí sirve: un catálogo a medias es utilizable, una excepción a media pantalla
+ * no.
+ */
+export declare function opcionesDeModelosDeOpenRouter(respuesta: RespuestaDeModelosDeOpenRouter | ModeloDeOpenRouter[] | null | undefined): LlmModelOption[];
+/**
+ * La ventana de contexto de un modelo de OpenRouter, en tokens, o `undefined`.
+ *
+ * Aparte y con nombre propio porque hay DOS sitios donde viene y no siempre
+ * coinciden: `context_length` es lo que anuncia el modelo, y
+ * `top_provider.context_length` lo que sirve de verdad el proveedor que
+ * OpenRouter va a usar. Gana el más PEQUEÑO de los dos: quien trocea para
+ * resumir prefiere quedarse corto —más llamadas— a que el proveedor le
+ * rechace la petición por pasarse.
+ */
+export declare function ventanaDeContextoDeOpenRouter(modelo: ModeloDeOpenRouter | null | undefined): number | undefined;

package/dist/esm/openrouter.js

@@ -0,0 +1,99 @@
+/**
+ * El catálogo VIVO de OpenRouter: la forma de lo que devuelve su API y cómo se
+ * convierte en las mismas opciones que ya pintan los desplegables.
+ *
+ * ## Por qué este proveedor no tiene lista en `llm-models.ts`
+ *
+ * Porque no es un laboratorio, es un router: revende ~425 modelos de otros
+ * detrás de una sola clave, y el conjunto se mueve solo. La lista entera está
+ * en `GET https://openrouter.ai/api/v1/models`, que es **abierto y sin clave**
+ * —se puede pedir antes de que el usuario haya pegado ninguna— y cada entrada
+ * trae su `context_length` y **su propio precio**. Copiar eso a mano a
+ * `LLM_MODELS` y a `MODEL_PRICING` sería mantener a mano lo que la API ya da,
+ * con 425 oportunidades de que se quede viejo en silencio.
+ *
+ * ## El reparto, que es lo que hay que entender antes de tocar esto
+ *
+ * De la MISMA respuesta salen dos cosas, y viven en paquetes distintos porque
+ * son de dueños distintos:
+ *
+ *   - **el catálogo** (id, nombre, ventana de contexto) → aquí, porque el
+ *     catálogo de modelos es de este fichero desde siempre;
+ *   - **la tarifa** (`pricing`) → `tarifaDeOpenRouter` en
+ *     `@hostwebhook/platform-contracts`, porque el precio de un token es de
+ *     ese paquete y no de éste.
+ *
+ * Y no al revés: este paquete NO puede importar `ModelPricing`
+ * —`platform-contracts` depende de éste, no al contrario—, así que el tipo que
+ * cruza es el crudo `ModeloDeOpenRouter`. Quien pinte el selector hace UN solo
+ * fetch y pasa cada entrada por las dos funciones.
+ *
+ * ## ⚠️ Esto es una respuesta de red, no un fichero nuestro
+ *
+ * Todo lo que no sea `id` va opcional a propósito. No porque OpenRouter lo
+ * omita hoy, sino porque nada nuestro impide que lo omita mañana, y un campo
+ * declarado obligatorio que llega `undefined` no falla al parsear —TypeScript
+ * no valida en runtime—: falla más tarde y más lejos, leyendo una propiedad de
+ * algo que no está. `id` es la única excepción porque sin él la entrada no
+ * identifica a ningún modelo y no hay nada que ofrecer.
+ *
+ * Verificado contra la respuesta real el 2026-08-31: 425 modelos, los 425 con
+ * `pricing.prompt` y `pricing.completion`, y algunos con un
+ * `top_provider.context_length` MENOR que su `context_length` anunciado.
+ */
+/** El endpoint del catálogo. Abierto: no lleva `Authorization`. */
+export const URL_DE_MODELOS_DE_OPENROUTER = 'https://openrouter.ai/api/v1/models';
+/**
+ * Las opciones del desplegable a partir de la respuesta cruda.
+ *
+ * Devuelve `LlmModelOption`, el MISMO tipo que `LLM_MODELS`, para que el
+ * selector no tenga dos formas de modelo según el proveedor: la única
+ * diferencia entre un catálogo y el otro es de dónde salió la lista.
+ *
+ * ⚠️ Ninguna opción sale `recommended`. En los catálogos estáticos esa marca
+ * la pone una persona que ha mirado los precios; aquí no hay nadie mirando, y
+ * una recomendación automática —«el primero», «el más barato»— sería una
+ * decisión de producto tomada por accidente. Sin `recommended`,
+ * `getDefaultModel('openrouter')` sigue siendo `''` y elegir es del usuario.
+ *
+ * Acepta el sobre entero o el array suelto porque quien llama a veces ya lo ha
+ * desenvuelto, y tolera basura (`null`, entradas sin `id`) devolviendo lo que
+ * sí sirve: un catálogo a medias es utilizable, una excepción a media pantalla
+ * no.
+ */
+export function opcionesDeModelosDeOpenRouter(respuesta) {
+    const modelos = Array.isArray(respuesta) ? respuesta : respuesta?.data;
+    if (!Array.isArray(modelos))
+        return [];
+    const opciones = [];
+    for (const modelo of modelos) {
+        if (!modelo || typeof modelo.id !== 'string' || modelo.id === '')
+            continue;
+        opciones.push({
+            value: modelo.id,
+            label: typeof modelo.name === 'string' && modelo.name !== ''
+                ? modelo.name
+                : modelo.id,
+        });
+    }
+    return opciones;
+}
+/**
+ * La ventana de contexto de un modelo de OpenRouter, en tokens, o `undefined`.
+ *
+ * Aparte y con nombre propio porque hay DOS sitios donde viene y no siempre
+ * coinciden: `context_length` es lo que anuncia el modelo, y
+ * `top_provider.context_length` lo que sirve de verdad el proveedor que
+ * OpenRouter va a usar. Gana el más PEQUEÑO de los dos: quien trocea para
+ * resumir prefiere quedarse corto —más llamadas— a que el proveedor le
+ * rechace la petición por pasarse.
+ */
+export function ventanaDeContextoDeOpenRouter(modelo) {
+    const candidatas = [
+        modelo?.context_length,
+        modelo?.top_provider?.context_length,
+    ].filter((n) => typeof n === 'number' && Number.isFinite(n) && n > 0);
+    if (candidatas.length === 0)
+        return undefined;
+    return Math.min(...candidatas);
+}

package/dist/esm/package.json

@@ -0,0 +1,4 @@
+{
+  "type": "module",
+  "sideEffects": false
+}

package/dist/esm/postgres-operations.d.ts

@@ -0,0 +1,60 @@
+/**
+ * Postgres operation enum + metadatos por operación — una sola copia para la
+ * api, el Dashboard y el broker.
+ *
+ * ── Por qué esto no trae un esquema de formulario ──
+ * A diferencia de Slack, Discord, Sheets, Telegram, Contacts y Drive,
+ * `postgresAction` **no tiene campos por operación**: el mismo formulario —SQL,
+ * Parameters, Statement timeout— se pinta para las cinco. Su eje real es `mode`
+ * (`single` / `transaction`). Así que aquí no hay `*_OPERATION_SPECS` de params,
+ * porque saldrían idénticos cinco veces; lo que sí había era la lista escrita a
+ * mano **nueve veces**, y eso es lo que esto quita:
+ *
+ *   api    dto: @ApiProperty enum, @IsIn, la unión TS   (3)
+ *   api    entity: @Prop enum, la unión TS              (2)
+ *   dash   lib/api.ts: la unión TS                      (1)
+ *   dash   PostgresTablePicker: la unión en un prop      (1)
+ *   dash   PostgresActionDetail: OPERATIONS             (1)
+ *   dash   PostgresNode + FlowPanel: opLabels idénticos  (2)
+ *
+ * Las **clases de color no están aquí**: son presentación (Tailwind), y se
+ * quedan en el dashboard, igual que los `ICONOS` de Telegram y de Drive.
+ */
+export declare const POSTGRES_OPERATIONS: readonly ["query", "insertOne", "update", "delete", "execute"];
+export type PostgresOperation = (typeof POSTGRES_OPERATIONS)[number];
+/** Type guard — útil al validar entrada que no controlas (DTOs, tool calls). */
+export declare function isPostgresOperation(value: unknown): value is PostgresOperation;
+/**
+ * Cómo se ejecuta el nodo. `single` es una sentencia; `transaction` es una lista
+ * ordenada dentro de BEGIN / COMMIT con rollback condicional.
+ */
+export declare const POSTGRES_MODES: readonly ["single", "transaction"];
+export type PostgresMode = (typeof POSTGRES_MODES)[number];
+export interface PostgresOperationSpec {
+    /**
+     * Etiqueta corta, para la píldora estrecha del lienzo y del panel. Estaba
+     * escrita **idéntica** en `PostgresNode.tsx` y en `FlowPanel.tsx`.
+     */
+    label: string;
+    /**
+     * La etiqueta larga del título del editor de SQL en la página de detalle,
+     * donde hay sitio para el paréntesis aclaratorio. **No es la misma que
+     * `label` y no debe unificarse**: son dos anchos distintos y las dos se ven.
+     */
+    labelLong: string;
+    /** Una línea de cuándo usar esta operación. */
+    description: string;
+    /** SQL de ejemplo, el `placeholder` del editor. */
+    sqlPlaceholder: string;
+    /**
+     * Si la operación devuelve filas **siempre**. Sólo `execute` no: ahí depende
+     * de `returnRows` en la entidad, porque puede ser DDL.
+     *
+     * Este invariante vivía en dos sitios y en uno era un comentario: la api lo
+     * calculaba con `entity.operation !== 'execute' || entity.returnRows`, y el
+     * dashboard lo expresaba como `localOperation === "execute"` para decidir si
+     * enseñaba el interruptor. Es el mismo hecho, dicho aquí una vez.
+     */
+    returnsRowsAlways: boolean;
+}
+export declare const POSTGRES_OPERATION_SPECS: Record<PostgresOperation, PostgresOperationSpec>;

package/dist/esm/postgres-operations.js

@@ -0,0 +1,75 @@
+/**
+ * Postgres operation enum + metadatos por operación — una sola copia para la
+ * api, el Dashboard y el broker.
+ *
+ * ── Por qué esto no trae un esquema de formulario ──
+ * A diferencia de Slack, Discord, Sheets, Telegram, Contacts y Drive,
+ * `postgresAction` **no tiene campos por operación**: el mismo formulario —SQL,
+ * Parameters, Statement timeout— se pinta para las cinco. Su eje real es `mode`
+ * (`single` / `transaction`). Así que aquí no hay `*_OPERATION_SPECS` de params,
+ * porque saldrían idénticos cinco veces; lo que sí había era la lista escrita a
+ * mano **nueve veces**, y eso es lo que esto quita:
+ *
+ *   api    dto: @ApiProperty enum, @IsIn, la unión TS   (3)
+ *   api    entity: @Prop enum, la unión TS              (2)
+ *   dash   lib/api.ts: la unión TS                      (1)
+ *   dash   PostgresTablePicker: la unión en un prop      (1)
+ *   dash   PostgresActionDetail: OPERATIONS             (1)
+ *   dash   PostgresNode + FlowPanel: opLabels idénticos  (2)
+ *
+ * Las **clases de color no están aquí**: son presentación (Tailwind), y se
+ * quedan en el dashboard, igual que los `ICONOS` de Telegram y de Drive.
+ */
+export const POSTGRES_OPERATIONS = [
+    'query', // SELECT — devuelve filas
+    'insertOne', // INSERT, normalmente con RETURNING *
+    'update', // UPDATE ... WHERE
+    'delete', // DELETE ... WHERE
+    'execute', // SQL cualquiera: DDL, transacciones, multi-sentencia
+];
+/** Type guard — útil al validar entrada que no controlas (DTOs, tool calls). */
+export function isPostgresOperation(value) {
+    return typeof value === 'string' && POSTGRES_OPERATIONS.includes(value);
+}
+/**
+ * Cómo se ejecuta el nodo. `single` es una sentencia; `transaction` es una lista
+ * ordenada dentro de BEGIN / COMMIT con rollback condicional.
+ */
+export const POSTGRES_MODES = ['single', 'transaction'];
+export const POSTGRES_OPERATION_SPECS = {
+    query: {
+        label: 'SELECT',
+        labelLong: 'SELECT (query)',
+        description: 'Run a SELECT and return rows',
+        sqlPlaceholder: 'SELECT id, email FROM users WHERE org_id = {{payload.orgId}} ORDER BY created_at DESC LIMIT 50',
+        returnsRowsAlways: true,
+    },
+    insertOne: {
+        label: 'INSERT',
+        labelLong: 'INSERT',
+        description: 'Insert a row (with RETURNING * recommended)',
+        sqlPlaceholder: 'INSERT INTO events (kind, payload) VALUES ({{payload.kind}}, {{payload.data}}) RETURNING *',
+        returnsRowsAlways: true,
+    },
+    update: {
+        label: 'UPDATE',
+        labelLong: 'UPDATE',
+        description: 'Update rows matching WHERE',
+        sqlPlaceholder: 'UPDATE users SET last_seen = NOW() WHERE id = {{payload.userId}} RETURNING id',
+        returnsRowsAlways: true,
+    },
+    delete: {
+        label: 'DELETE',
+        labelLong: 'DELETE',
+        description: 'Delete rows matching WHERE',
+        sqlPlaceholder: 'DELETE FROM sessions WHERE expires_at < NOW() RETURNING id',
+        returnsRowsAlways: true,
+    },
+    execute: {
+        label: 'EXEC',
+        labelLong: 'EXEC (raw)',
+        description: 'Run any SQL — DDL, transactions, or multi-stmt. Toggle returnRows for INSERT ... RETURNING.',
+        sqlPlaceholder: 'CREATE TEMP TABLE x AS SELECT 1; ANALYZE; -- DDL or batch',
+        returnsRowsAlways: false,
+    },
+};

package/dist/esm/registry.d.ts

@@ -0,0 +1,160 @@
+/**
+ * Centralized NODE_REGISTRY — single source of truth for all node metadata.
+ *
+ * When adding a new node type, add ONE entry here. The dashboard derives
+ * all per-node maps (colors, URLs, Redux keys, palette, delete, etc.)
+ * from this registry. No more 18+ touch points.
+ */
+import type { NodeType } from './types.js';
+export type NodeGroup = 'Sources' | 'Flow Control' | 'Actions' | 'Annotations';
+export interface NodeRegistryEntry {
+    /** Canonical type (e.g., "httpAction") */
+    type: NodeType;
+    /** Canvas ID prefix (e.g., "ha") */
+    prefix: string;
+    /** Display label (e.g., "HTTP Action") */
+    label: string;
+    /** Group in palette */
+    group: NodeGroup;
+    /** Detail page path (e.g., "/dashboard/http-actions") */
+    detailPath: string;
+    /** API endpoint base (e.g., "/http-actions") */
+    apiPath: string;
+    /** Redux state key for filtered array (e.g., "httpActions") */
+    stateKey: string;
+    /** Redux state key for all array (e.g., "allHttpActions") */
+    allStateKey: string;
+    /** MiniMap hex color */
+    color: string;
+    /** Whether this node supports test execution */
+    testable: boolean;
+    /**
+     * Optional per-instance predicate marking a node as "tool-only".
+     * When this returns true, the canvas should hide every connectable
+     * handle so the user cannot draw pipeline edges to/from this node —
+     * it lives instead inside an upstream AI Node's tools[] list.
+     *
+     * Lets new toolkit-style nodes opt-in without per-component hardcoding
+     * in the dashboard. Currently only emailAction(aiEnabled=true) uses
+     * this; trigger or future Slack/Discord toolkits could too.
+     *
+     * Predicate must be pure (no side effects) — called on every render.
+     */
+    isToolOnly?: (entity: Record<string, unknown>) => boolean;
+    /**
+     * The versions this node type ships, when it ships more than one.
+     *
+     * Absent means the type does not version, which is true of every type
+     * today. A node type only declares this the day its provider deprecates
+     * something and a second version has to live alongside the first.
+     *
+     * See `docs/ADR-0002-node-versioning.md` in the api repo.
+     */
+    versions?: NodeVersionSpec[];
+}
+/**
+ * One version of a node type.
+ *
+ * Deliberately NOT a schema. The api's DTO stays the validator; all this
+ * needs to know is WHICH config fields a version understands, because that
+ * is what answers the only question the UI has to ask: switching from here
+ * to there, what does the user lose?
+ */
+export interface NodeVersionSpec {
+    /** The number the user sees. Unique within a type. */
+    v: number;
+    /** Shown next to the number in the picker, e.g. "Discord API v10". */
+    label?: string;
+    /**
+     * `current` is what a new node is born on — exactly one per type.
+     * `legacy` still runs but is on its way out. `beta` is opt-in.
+     */
+    status: 'current' | 'legacy' | 'beta';
+    /**
+     * The config fields this version understands.
+     *
+     * Only fields the user configures. Identity and topology — name,
+     * inputNodes, outputNodes, isActive, canvas position — never belong
+     * here: they survive a version change untouched, and listing them
+     * would put them at risk of being unset.
+     */
+    fields: string[];
+    /**
+     * Entering this version keeps nothing. For the case where "v2" is
+     * really a different integration wearing the same node's name.
+     */
+    cleanBreak?: boolean;
+    /** Why it was retired, or what it brings. Shown in picker and dialog. */
+    note?: string;
+}
+export declare const NODE_REGISTRY: Record<NodeType, NodeRegistryEntry>;
+/** Get registry entry by canonical type */
+export declare function getNodeRegistryEntry(type: string): NodeRegistryEntry | undefined;
+/** type → detail page path */
+export declare const NODE_DETAIL_PATHS: Record<string, string>;
+/** type → minimap color */
+export declare const NODE_COLORS: Record<string, string>;
+/** type → [stateKey, allStateKey] */
+export declare const NODE_STATE_KEYS: Record<string, [string, string]>;
+/** prefix → type */
+export declare const PREFIX_TO_NODE_TYPE: Record<string, NodeType>;
+/** type → prefix */
+export declare const NODE_TYPE_TO_PREFIX: Record<string, string>;
+/**
+ * The catalog these helpers read. Every one of them takes it as an
+ * optional last argument defaulting to the real registry: consumers never
+ * pass it, and the tests can exercise a versioned type without waiting
+ * for a real one to exist.
+ */
+export type VersionCatalog = Record<string, Pick<NodeRegistryEntry, 'type' | 'versions'>>;
+/** True when this type ships more than one version. False for every type today. */
+export declare function isVersioned(type: string, catalog?: VersionCatalog): boolean;
+/**
+ * Every declared version, newest first — the order a picker wants.
+ * Empty for a type that does not version.
+ */
+export declare function versionsOf(type: string, catalog?: VersionCatalog): NodeVersionSpec[];
+/** One version's spec, or undefined when the type or the number is unknown. */
+export declare function versionSpec(type: string, v: number, catalog?: VersionCatalog): NodeVersionSpec | undefined;
+/**
+ * The version a new node of this type is born on.
+ *
+ * Returns 1 for a type that does not version, which is also how an entity
+ * with no `nodeVersion` is read. A node created before its type ever
+ * versioned was calling the original endpoints, so calling it version 1
+ * is not a convention — it is the truth.
+ */
+export declare function currentVersion(type: string, catalog?: VersionCatalog): number;
+/**
+ * Config fields present in `from` that `to` does not declare — the exact
+ * list a confirmation dialog should name, and the exact list the server
+ * should unset.
+ *
+ * Returns `null` when the question cannot be answered: the type does not
+ * version, or one of the two versions is not declared. `null` is not the
+ * same as "nothing is lost", and callers must not treat it that way — a
+ * dialog should refuse to offer the switch, and the api should reject the
+ * request. Returning `null` rather than `[]` is what stops "I don't know"
+ * from being read as "nothing".
+ *
+ * This lives here rather than in each consumer because the dialog that
+ * ANNOUNCES the loss and the server that PERFORMS it have to give the
+ * same answer. Two implementations would agree right until the day they
+ * did not, and that day the dialog lies.
+ */
+export declare function fieldsLostBetween(type: string, from: number, to: number, catalog?: VersionCatalog): string[] | null;
+/**
+ * The same answer for two specs already in hand — what `fieldsLostBetween`
+ * delegates to once it has resolved both, and what a caller that already
+ * holds them from `versionsOf()` can use without a second lookup.
+ */
+export declare function fieldsLost(from: NodeVersionSpec, to: NodeVersionSpec): string[];
+/**
+ * Declaration mistakes in the version catalogs, as readable lines.
+ *
+ * A guard rather than a line in a document: what this codebase learned
+ * from fifteen nodes skipping a checklist point everyone had read is that
+ * the written rule prevented nothing and the guard did. Empty means every
+ * catalog is well-formed.
+ */
+export declare function versionCatalogErrors(catalog?: VersionCatalog): string[];