@hostwebhook/node-types 1.69.0 → 1.70.0

package/dist/esm/llm-models.js

@@ -0,0 +1,230 @@
+/**
+ * Canonical LLM provider + model catalog. Single source of truth for
+ * every place that names a model, used by:
+ *
+ *   - dashboard pickers: AI nodes, LLM credentials, voice agents
+ *   - api defaults: the AI node's `model` @Prop, the cheap model the
+ *     tool generator and the fact extractor pick per provider
+ *   - api summarization: context windows drive the chunk size
+ *
+ * It lived in `dashboard/lib/llm-models.ts` until 2026-08-18, with a
+ * comment arguing model strings were "dashboard chrome only". They were
+ * not: the api had its own hardcoded copies and nothing synced them. The
+ * picker offered `claude-haiku-4-5` while the api minted nodes on
+ * `claude-sonnet-4-20250514`, retired two months earlier. Same class of
+ * bug `credentials.ts` exists to kill — both sides import one list now.
+ *
+ * NOT here: the models HostWebhook runs on its own key (see the api's
+ * `common/llm-models.ts`) and the voice-platform catalogs. Retell and
+ * Vapi accept their own spellings — Retell says `claude-5-sonnet`, Vapi
+ * demands the dated Haiku id — so those live with their backends and
+ * follow the platform's docs, not the provider's.
+ *
+ * Last verified against provider docs: 2026-08-18
+ *  - Anthropic: https://platform.claude.com/docs/en/about-claude/models/overview
+ *  - OpenAI: https://developers.openai.com/api/docs/models
+ *  - Google: https://ai.google.dev/gemini-api/docs/models
+ *  - Groq: https://console.groq.com/docs/models
+ *
+ * NOT verified against docs, and on purpose: OpenRouter. Its catalog is not a
+ * list anybody types — see `LLM_MODELS.openrouter` and `openrouter.ts`.
+ */
+export const LLM_PROVIDERS = [
+    { value: 'anthropic', label: 'Anthropic' },
+    { value: 'openai', label: 'OpenAI' },
+    { value: 'google', label: 'Google' },
+    { value: 'groq', label: 'Groq' },
+    { value: 'openrouter', label: 'OpenRouter' },
+];
+export const LLM_MODELS = {
+    // ── Anthropic ──────────────────────────────────────────────────────────
+    // Current tier (Aug 2026): Fable 5, Opus 5, Sonnet 5, Haiku 4.5. The 4.x
+    // Opus/Sonnet line is still served but sits under "legacy" in the docs.
+    // Haiku 4.5 stays recommended: the only current-tier model in the
+    // $1/MTok bracket, so new nodes keep their cost profile.
+    // claude-sonnet-4-20250514 + claude-opus-4-20250514 retired 2026-06-15.
+    // claude-mythos-5 is omitted on purpose — invitation-only (Glasswing).
+    anthropic: [
+        { value: 'claude-haiku-4-5', label: 'Claude Haiku 4.5', recommended: true },
+        { value: 'claude-sonnet-5', label: 'Claude Sonnet 5' },
+        { value: 'claude-opus-5', label: 'Claude Opus 5' },
+        { value: 'claude-fable-5', label: 'Claude Fable 5' },
+        { value: 'claude-opus-4-8', label: 'Claude Opus 4.8 (legacy)' },
+        { value: 'claude-opus-4-7', label: 'Claude Opus 4.7 (legacy)' },
+        { value: 'claude-opus-4-6', label: 'Claude Opus 4.6 (legacy)' },
+        { value: 'claude-sonnet-4-6', label: 'Claude Sonnet 4.6 (legacy)' },
+    ],
+    // ── OpenAI ─────────────────────────────────────────────────────────────
+    // GPT-5.6 (Sol / Terra / Luna) is the current frontier family, released
+    // 2026-07-09. Luna is the cheap tier and the recommended default. 5.5 /
+    // 5.4-mini / 4o are still served but no longer listed as frontier, so
+    // they are kept only so existing nodes keep a friendly label.
+    // o1 removed — shut down 2025-07-28.
+    openai: [
+        { value: 'gpt-5.6-luna', label: 'GPT-5.6 Luna', recommended: true },
+        { value: 'gpt-5.6-terra', label: 'GPT-5.6 Terra' },
+        { value: 'gpt-5.6-sol', label: 'GPT-5.6 Sol' },
+        { value: 'gpt-5.5', label: 'GPT-5.5 (legacy)' },
+        { value: 'gpt-5.4-mini', label: 'GPT-5.4 mini (legacy)' },
+        { value: 'gpt-4o', label: 'GPT-4o (legacy)' },
+        { value: 'gpt-4o-mini', label: 'GPT-4o mini (legacy)' },
+    ],
+    // ── Google Gemini ──────────────────────────────────────────────────────
+    // The 3.x line went stable: 3.7/3.6/3.5 Flash and 3.1 Flash Lite no
+    // longer carry a -preview suffix. 3.5 Flash Lite is the cheapest current
+    // tier and the recommended default.
+    // gemini-3.1-flash-lite-preview and gemini-3-pro-preview were shut down —
+    // the first one used to be our default, so nodes still on it fail until
+    // the user repicks.
+    google: [
+        {
+            value: 'gemini-3.5-flash-lite',
+            label: 'Gemini 3.5 Flash Lite',
+            recommended: true,
+        },
+        { value: 'gemini-3.7-flash', label: 'Gemini 3.7 Flash' },
+        { value: 'gemini-3.6-flash', label: 'Gemini 3.6 Flash' },
+        { value: 'gemini-3.5-flash', label: 'Gemini 3.5 Flash' },
+        { value: 'gemini-3.1-flash-lite', label: 'Gemini 3.1 Flash Lite' },
+        { value: 'gemini-3.1-pro-preview', label: 'Gemini 3.1 Pro (preview)' },
+        { value: 'gemini-2.5-flash', label: 'Gemini 2.5 Flash (legacy)' },
+        { value: 'gemini-2.5-flash-lite', label: 'Gemini 2.5 Flash Lite (legacy)' },
+        { value: 'gemini-2.5-pro', label: 'Gemini 2.5 Pro (legacy)' },
+    ],
+    // ── Groq ───────────────────────────────────────────────────────────────
+    // llama-3.1-8b-instant + llama-3.3-70b-versatile were retired 2026-08-16
+    // for free/developer tiers — removed. The first one was our recommended
+    // default, so nodes still on it fail until the user repicks.
+    // Groq's own replacements: 8b-instant → gpt-oss-20b, 70b-versatile →
+    // gpt-oss-120b or qwen3.6-27b.
+    groq: [
+        { value: 'openai/gpt-oss-20b', label: 'GPT OSS 20B', recommended: true },
+        { value: 'openai/gpt-oss-120b', label: 'GPT OSS 120B' },
+        { value: 'groq/compound', label: 'Compound' },
+        { value: 'groq/compound-mini', label: 'Compound Mini' },
+        { value: 'qwen/qwen3.6-27b', label: 'Qwen 3.6 27B (preview)' },
+    ],
+    // ── OpenRouter ─────────────────────────────────────────────────────────
+    // EMPTY ON PURPOSE. Not a gap, not a TODO — read this before filling it.
+    //
+    // Every other provider above is a lab with a dozen models, each with a
+    // price we look up in `MODEL_PRICING` over in platform-contracts. OpenRouter
+    // is a router: ~425 models from everybody else, and the set moves on its own
+    // — models appear, get deprecated and change price without anyone here
+    // touching a file. Typing them out has three separate costs:
+    //
+    //   1. It goes stale silently. That is the exact failure this whole file
+    //      exists to kill (the picker offering a model the api had retired),
+    //      only this time with 425 chances to happen instead of eight.
+    //   2. The price would have to be hand-copied into `MODEL_PRICING` too —
+    //      425 rows of a number the API already hands us with each model. A
+    //      wrong row there does not fail loudly: it makes a dollar spending cap
+    //      cut in the wrong place, or never.
+    //   3. Nobody wants a 425-entry dropdown anyway. The dashboard has to
+    //      search/filter it live regardless of what we ship here.
+    //
+    // So the catalog is FETCHED: `GET https://openrouter.ai/api/v1/models` is
+    // open, needs no key, and each entry carries id, name, context_length AND
+    // its own pricing. `openrouter.ts` types that payload and maps it to the
+    // very same `LlmModelOption` the pickers already render; the pricing half
+    // is `tarifaDeOpenRouter` in `@hostwebhook/platform-contracts`, which turns
+    // it into a `ModelPricing` you hand to `calculateCost(..., tarifa)`.
+    //
+    // Consequence, stated out loud because it is the surprising part:
+    // `getDefaultModel('openrouter')` is `''`. There is no honest default among
+    // 425 models we do not curate — any pick here would be a guess that can be
+    // deprecated out from under us — so choosing a model is REQUIRED when the
+    // provider is OpenRouter. See `getDefaultModel` below.
+    openrouter: [],
+};
+/**
+ * Effective context window per model, in TOKENS. The api sizes
+ * summarization chunks from this; a miss falls back to a conservative
+ * 32k window, which still produces a summary — just chopped into far
+ * more map calls than needed. That silence is why this table went four
+ * months without a single current model in it.
+ *
+ * Includes ids the pickers no longer offer: the AI node's model field is
+ * a free-text datalist, so a node may hold one by hand.
+ *
+ * ⚠️ NOT here: OpenRouter's ids. Same reason its models are not in
+ * `LLM_MODELS` — its API publishes `context_length` per model, so the number
+ * travels with the model instead of being copied 425 times into this table.
+ * Whoever chunks for an OpenRouter model reads it from the fetched entry
+ * (`ModeloDeOpenRouter.context_length`); a lookup here misses and falls back
+ * to the conservative 32k, which still summarizes, just in more calls.
+ */
+export const MODEL_CONTEXT_WINDOWS = {
+    // Anthropic — the 4.6 generation onward is 1M; Haiku and the 4.5 line
+    // stay at 200k. Retired ids left out: claude-sonnet-4-20250514 and
+    // claude-opus-4-1 (both gone 2026-06-15).
+    'claude-fable-5': 1000000,
+    'claude-opus-5': 1000000,
+    'claude-sonnet-5': 1000000,
+    'claude-haiku-4-5': 200000,
+    'claude-opus-4-8': 1000000,
+    'claude-opus-4-7': 1000000,
+    'claude-opus-4-6': 1000000,
+    'claude-sonnet-4-6': 1000000,
+    'claude-sonnet-4-5': 200000,
+    'claude-opus-4-5': 200000,
+    // OpenAI — the GPT-5.6 family is 1.05M. 'gpt-5.6' is the documented
+    // alias for Sol, so it needs its own key: the prefix fallback in the
+    // api stems on three dash-segments and would not reach 'gpt-5.6-sol'.
+    'gpt-5.6': 1050000,
+    'gpt-5.6-sol': 1050000,
+    'gpt-5.6-terra': 1050000,
+    'gpt-5.6-luna': 1050000,
+    'gpt-4o': 128000,
+    'gpt-4o-mini': 128000,
+    'gpt-4-turbo': 128000,
+    'gpt-4.1': 1000000,
+    // Google — the whole Gemini 3.x line is 1M. gemini-2.0-flash left out
+    // (shut down). 2.5 Pro is its real 1M input limit, not the 2M the api
+    // used to claim — that produced chunks the model would reject.
+    'gemini-3.7-flash': 1000000,
+    'gemini-3.6-flash': 1000000,
+    'gemini-3.5-flash': 1000000,
+    'gemini-3.5-flash-lite': 1000000,
+    'gemini-3.1-flash-lite': 1000000,
+    'gemini-3.1-pro-preview': 1000000,
+    'gemini-2.5-pro': 1000000,
+    'gemini-2.5-flash': 1000000,
+    'gemini-2.5-flash-lite': 1000000,
+};
+/**
+ * The model catalog for a provider. Accepts both the raw provider name
+ * (`"anthropic"`) and the `llm_*` credential type prefix
+ * (`"llm_anthropic"`) so call sites that key off credential type can
+ * pass the type directly without stripping.
+ */
+export function getModelsFor(provider) {
+    const key = provider.replace(/^llm_/, '');
+    return LLM_MODELS[key] ?? [];
+}
+/**
+ * The suggested default model for a provider, or `''` for one we do not
+ * catalog (Ollama runs whatever the user pulled, so it has no entry —
+ * callers fall back to the node's own model there).
+ *
+ * ⚠️ `'openrouter'` is the second `''`, and unlike Ollama it IS a provider in
+ * `LLM_PROVIDERS`, so callers that assumed "every provider in the list has a
+ * default" now have a case to handle. It is deliberate: its catalog is live
+ * (see `LLM_MODELS.openrouter`) and no static pick would survive. Treat `''`
+ * as "the user must choose", not as "fall back to something" — a node born
+ * with an empty model must not be sent to the API as-is.
+ */
+export function getDefaultModel(provider) {
+    const models = getModelsFor(provider);
+    const recommended = models.find((m) => m.recommended);
+    return recommended?.value ?? models[0]?.value ?? '';
+}
+/** The friendly label for a model value, or the value itself. */
+export function getModelLabel(value) {
+    for (const models of Object.values(LLM_MODELS)) {
+        const found = models.find((m) => m.value === value);
+        if (found?.label)
+            return found.label;
+    }
+    return value;
+}

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

@@ -0,0 +1,56 @@
+/**
+ * Mailchimp Marketing API operations — single source of truth across the
+ * api, the dashboard and downstream consumers (MCP server).
+ *
+ * ## Three, out of one hundred and eighty-one
+ *
+ * The Marketing API has 181 routes. This node exposes three, and the choice
+ * is argued in `api/docs/ADR-0003-mailchimp.md`: a menu of 181 is how a node
+ * becomes unusable, and these three cover what people actually automate —
+ * put someone in a list, tag them, drop them into a journey.
+ *
+ * Campaign creation and sending were considered and left out of v1: a
+ * campaign needs a template, a segment and a schedule, which is a
+ * configuration surface of its own and not something anyone drives from a
+ * webhook on day one.
+ *
+ * ## Every field here exists in Mailchimp's OpenAPI schema
+ *
+ * Taken from `api.mailchimp.com/schema/3.0/Swagger.json`, not from memory.
+ * If you add a parameter, check it there first — an invented field is
+ * accepted, ignored, and then read back by the next maintainer as if it did
+ * something.
+ */
+export declare const MAILCHIMP_OPERATIONS: readonly ["upsertContact", "setTags", "triggerJourney"];
+export type MailchimpOperation = (typeof MAILCHIMP_OPERATIONS)[number];
+/** Type guard — for DTOs and AI tool calls, where the input is untrusted. */
+export declare function isMailchimpOperation(value: unknown): value is MailchimpOperation;
+/**
+ * Contact status. `pending` is the default everywhere on purpose.
+ *
+ * Writing `subscribed` for someone who never consented is a legal problem,
+ * not a technical one — and a default of `subscribed` is exactly what makes
+ * it easy. `pending` sends Mailchimp's confirmation email, which is the
+ * behaviour someone should have to opt *out* of.
+ */
+export declare const MAILCHIMP_CONTACT_STATUSES: readonly ["pending", "subscribed", "unsubscribed", "cleaned", "transactional"];
+export type MailchimpContactStatus = (typeof MAILCHIMP_CONTACT_STATUSES)[number];
+export interface MailchimpParamSpec {
+    /** Field key — also the property name on operationConfig. */
+    name: string;
+    label: string;
+    /** Param type, so the dashboard renders the right control. `audience`
+     *  and `journeyStep` are pickers backed by live Mailchimp lookups. */
+    type: 'audience' | 'journeyStep' | 'email' | 'string' | 'status' | 'tags' | 'json' | 'boolean';
+    required?: boolean;
+    description: string;
+    placeholder?: string;
+}
+export interface MailchimpOperationSpec {
+    label: string;
+    description: string;
+    /** The Marketing API route this maps to, so the mapping is checkable. */
+    apiRoute: string;
+    params: MailchimpParamSpec[];
+}
+export declare const MAILCHIMP_OPERATION_SPECS: Record<MailchimpOperation, MailchimpOperationSpec>;

package/dist/esm/mailchimp-operations.js

@@ -0,0 +1,155 @@
+/**
+ * Mailchimp Marketing API operations — single source of truth across the
+ * api, the dashboard and downstream consumers (MCP server).
+ *
+ * ## Three, out of one hundred and eighty-one
+ *
+ * The Marketing API has 181 routes. This node exposes three, and the choice
+ * is argued in `api/docs/ADR-0003-mailchimp.md`: a menu of 181 is how a node
+ * becomes unusable, and these three cover what people actually automate —
+ * put someone in a list, tag them, drop them into a journey.
+ *
+ * Campaign creation and sending were considered and left out of v1: a
+ * campaign needs a template, a segment and a schedule, which is a
+ * configuration surface of its own and not something anyone drives from a
+ * webhook on day one.
+ *
+ * ## Every field here exists in Mailchimp's OpenAPI schema
+ *
+ * Taken from `api.mailchimp.com/schema/3.0/Swagger.json`, not from memory.
+ * If you add a parameter, check it there first — an invented field is
+ * accepted, ignored, and then read back by the next maintainer as if it did
+ * something.
+ */
+export const MAILCHIMP_OPERATIONS = [
+    'upsertContact',
+    'setTags',
+    'triggerJourney',
+];
+/** Type guard — for DTOs and AI tool calls, where the input is untrusted. */
+export function isMailchimpOperation(value) {
+    return (typeof value === 'string' &&
+        MAILCHIMP_OPERATIONS.includes(value));
+}
+/**
+ * Contact status. `pending` is the default everywhere on purpose.
+ *
+ * Writing `subscribed` for someone who never consented is a legal problem,
+ * not a technical one — and a default of `subscribed` is exactly what makes
+ * it easy. `pending` sends Mailchimp's confirmation email, which is the
+ * behaviour someone should have to opt *out* of.
+ */
+export const MAILCHIMP_CONTACT_STATUSES = [
+    'pending',
+    'subscribed',
+    'unsubscribed',
+    'cleaned',
+    'transactional',
+];
+export const MAILCHIMP_OPERATION_SPECS = {
+    upsertContact: {
+        label: 'Add or update contact',
+        description: 'Add a contact to an audience, or update them if the email is already there.',
+        apiRoute: 'PUT /lists/{list_id}/members/{subscriber_hash}',
+        params: [
+            {
+                name: 'audienceId',
+                label: 'Audience',
+                type: 'audience',
+                required: true,
+                description: 'The audience the contact belongs to.',
+            },
+            {
+                name: 'email',
+                label: 'Email address',
+                type: 'email',
+                required: true,
+                description: 'The contact. Mailchimp accepts the address itself here, so no hashing is needed.',
+                placeholder: '{{payload.email}}',
+            },
+            {
+                name: 'statusIfNew',
+                label: 'Status if new',
+                type: 'status',
+                required: true,
+                description: 'Only applies when the contact does not exist yet. An existing contact keeps the status it already had.',
+            },
+            {
+                name: 'mergeFields',
+                label: 'Merge fields',
+                type: 'json',
+                description: 'Mailchimp merge tags, e.g. {"FNAME":"Ada","LNAME":"Lovelace"}. The tags are defined per audience.',
+                placeholder: '{\n  "FNAME": "{{payload.firstName}}"\n}',
+            },
+            {
+                name: 'language',
+                label: 'Language',
+                type: 'string',
+                description: 'Two-letter language code, e.g. "es". Optional.',
+            },
+            {
+                name: 'vip',
+                label: 'Mark as VIP',
+                type: 'boolean',
+                description: 'Mailchimp caps VIP contacts at 5,000 per audience.',
+            },
+        ],
+    },
+    setTags: {
+        label: 'Add or remove tags',
+        description: 'Set tags on a contact. Adding and removing happen in the same call.',
+        apiRoute: 'POST /lists/{list_id}/members/{subscriber_hash}/tags',
+        params: [
+            {
+                name: 'audienceId',
+                label: 'Audience',
+                type: 'audience',
+                required: true,
+                description: 'Tags are scoped to an audience, not to the account.',
+            },
+            {
+                name: 'email',
+                label: 'Email address',
+                type: 'email',
+                required: true,
+                description: 'The contact to tag.',
+                placeholder: '{{payload.email}}',
+            },
+            {
+                name: 'tags',
+                label: 'Tags',
+                type: 'tags',
+                required: true,
+                description: 'Each tag is set active (add) or inactive (remove). One call can do both.',
+            },
+            {
+                name: 'isSyncing',
+                label: 'Skip automations',
+                type: 'boolean',
+                description: 'When on, automations that watch these tags do NOT fire. Use it for a bulk backfill you do not want to trigger emails.',
+            },
+        ],
+    },
+    triggerJourney: {
+        label: 'Add contact to a journey',
+        description: 'Drop a contact into a Customer Journey at a specific step.',
+        apiRoute: 'POST /customer-journeys/journeys/{journey_id}/steps/{step_id}/actions/trigger',
+        params: [
+            {
+                name: 'journeyStep',
+                label: 'Journey step',
+                type: 'journeyStep',
+                required: true,
+                description: 'The journey and the step inside it. The journey must already be running in Mailchimp.',
+            },
+            {
+                name: 'email',
+                label: 'Email address',
+                type: 'email',
+                required: true,
+                description: 'The contact to enrol. They must already exist in the journey audience — this operation does not create them.',
+                placeholder: '{{payload.email}}',
+            },
+        ],
+    },
+};

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

@@ -0,0 +1,61 @@
+/**
+ * MongoDB operation enum + esquema del formulario — una sola copia para la api,
+ * el Dashboard y el broker.
+ *
+ * ── Lo que quita ──
+ * La lista estaba escrita a mano **cinco veces sólo en la api** (tres en el DTO,
+ * dos en la entidad) y otras tantas en el dashboard. Y de los siete valores,
+ * el lienzo sólo conocía **cinco**: `findAll` y `findOneAndUpdate` no estaban en
+ * sus mapas de etiqueta y color, así que se pintaban grises y con el nombre
+ * crudo en camelCase mientras el panel sí les daba azul y ámbar.
+ *
+ * ── Lo fácil de Mongo ──
+ * Al contrario que Drive o Calendar, aquí **no hay capa de renombrado**: el
+ * `name` de cada param es la prop de la entidad tal cual, y el `apiUpdate` de la
+ * página es un passthrough de una línea. Es la forma de guardado más simple de
+ * la tanda.
+ */
+export declare const MONGO_OPERATIONS: readonly ["insertOne", "findOne", "findAll", "updateOne", "findOneAndUpdate", "deleteOne", "aggregate"];
+export type MongoOperation = (typeof MONGO_OPERATIONS)[number];
+/** Type guard — útil al validar entrada que no controlas (DTOs, tool calls). */
+export declare function isMongoOperation(value: unknown): value is MongoOperation;
+export type MongoParamType = 
+/** El `TemplateEditor` de JSON, con autocompletado de `{{payload.*}}`. */
+'jsonTemplate'
+/** El componente `UpdateBuilder` (arma `$set`, `$inc`… sin escribir JSON). */
+ | 'updateBuilder'
+/**
+ * Un `Switch` que se guarda **al instante** (`updateFieldInstant`) y se lee de
+ * la entidad, no de los locales. Se conserva así porque es como estaba.
+ */
+ | 'booleanInstant';
+export interface MongoParamSpec {
+    /** La prop de la entidad. Sin renombrado: es también la clave del cable. */
+    name: string;
+    label: string;
+    type: MongoParamType;
+    /** Texto de ayuda. Llano: el paquete no lleva React. */
+    description?: string;
+    placeholder?: string;
+    /** Sólo para `jsonTemplate`: la altura del editor. */
+    minHeight?: number;
+    maxHeight?: number;
+}
+export interface MongoOperationSpec {
+    /** La del desplegable de la página de detalle: «Insert One». */
+    label: string;
+    /**
+     * La de la píldora estrecha del lienzo y del panel: «INSERT».
+     *
+     * **Son dos etiquetas a propósito**, como en Calendar: dos anchos distintos y
+     * las dos se ven. Antes había una TERCERA convención, porque el panel pintaba
+     * `operation.toUpperCase()` y decía «FINDONEANDUPDATE» donde el lienzo decía
+     * «UPDATE». Ahora los dos leen esta.
+     */
+    labelShort: string;
+    /** Sub-línea del desplegable. */
+    description: string;
+    /** Orden de pantalla. */
+    params: MongoParamSpec[];
+}
+export declare const MONGO_OPERATION_SPECS: Record<MongoOperation, MongoOperationSpec>;

package/dist/esm/mongo-operations.js

@@ -0,0 +1,120 @@
+/**
+ * MongoDB operation enum + esquema del formulario — una sola copia para la api,
+ * el Dashboard y el broker.
+ *
+ * ── Lo que quita ──
+ * La lista estaba escrita a mano **cinco veces sólo en la api** (tres en el DTO,
+ * dos en la entidad) y otras tantas en el dashboard. Y de los siete valores,
+ * el lienzo sólo conocía **cinco**: `findAll` y `findOneAndUpdate` no estaban en
+ * sus mapas de etiqueta y color, así que se pintaban grises y con el nombre
+ * crudo en camelCase mientras el panel sí les daba azul y ámbar.
+ *
+ * ── Lo fácil de Mongo ──
+ * Al contrario que Drive o Calendar, aquí **no hay capa de renombrado**: el
+ * `name` de cada param es la prop de la entidad tal cual, y el `apiUpdate` de la
+ * página es un passthrough de una línea. Es la forma de guardado más simple de
+ * la tanda.
+ */
+export const MONGO_OPERATIONS = [
+    'insertOne', // inserta un documento
+    'findOne', // devuelve el primero que casa
+    'findAll', // devuelve todos los que casan (tope 1000)
+    'updateOne', // actualiza el primero que casa
+    'findOneAndUpdate', // actualiza y devuelve el documento
+    'deleteOne', // borra el primero que casa
+    'aggregate', // pipeline de agregación
+];
+/** Type guard — útil al validar entrada que no controlas (DTOs, tool calls). */
+export function isMongoOperation(value) {
+    return typeof value === 'string' && MONGO_OPERATIONS.includes(value);
+}
+/* Los campos que comparten varias operaciones. */
+const queryTemplate = () => ({
+    name: 'queryTemplate',
+    label: 'Query Template',
+    type: 'jsonTemplate',
+    placeholder: '{"email": "{{payload.email}}"}',
+    minHeight: 100,
+    maxHeight: 200,
+});
+const updateTemplate = () => ({
+    name: 'updateTemplate',
+    label: 'Update Operations',
+    type: 'updateBuilder',
+});
+export const MONGO_OPERATION_SPECS = {
+    insertOne: {
+        label: 'Insert One',
+        labelShort: 'INSERT',
+        description: 'Insert a single document',
+        params: [
+            {
+                name: 'documentTemplate',
+                label: 'Document Template',
+                type: 'jsonTemplate',
+                placeholder: '{"name": "{{payload.name}}", "email": "{{payload.email}}"}',
+                minHeight: 100,
+                maxHeight: 200,
+            },
+        ],
+    },
+    findOne: {
+        label: 'Find One',
+        labelShort: 'FIND',
+        description: 'Find a single matching document',
+        params: [queryTemplate()],
+    },
+    findAll: {
+        label: 'Find All',
+        /* Antes no estaba en el mapa del lienzo y salía el crudo `findAll`. */
+        labelShort: 'FIND ALL',
+        description: 'Find all matching documents (limit 1000)',
+        params: [
+            /* El interruptor va ANTES del query, que es el orden en que se pintaba. */
+            {
+                name: 'includeCount',
+                label: 'Include Count',
+                type: 'booleanInstant',
+                description: 'Return total count of matching documents alongside results',
+            },
+            queryTemplate(),
+        ],
+    },
+    updateOne: {
+        label: 'Update One',
+        labelShort: 'UPDATE',
+        description: 'Update a single matching document',
+        params: [queryTemplate(), updateTemplate()],
+    },
+    findOneAndUpdate: {
+        label: 'Find & Update',
+        /* Tampoco estaba: salía el crudo `findOneAndUpdate` en el lienzo y
+           `FINDONEANDUPDATE` en el panel. */
+        labelShort: 'FIND & UPDATE',
+        description: 'Find, update, and return the document',
+        params: [queryTemplate(), updateTemplate()],
+    },
+    deleteOne: {
+        label: 'Delete One',
+        labelShort: 'DELETE',
+        description: 'Delete a single matching document',
+        params: [queryTemplate()],
+    },
+    aggregate: {
+        label: 'Aggregate',
+        labelShort: 'AGGREGATE',
+        description: 'Run aggregation pipeline ($match, $group, $sort...)',
+        params: [
+            {
+                /* Mismo campo que en las demás, con otro título y otro ejemplo: por eso
+                   los params se declaran por operación y no en un registro global. */
+                name: 'queryTemplate',
+                label: 'Pipeline Template',
+                type: 'jsonTemplate',
+                placeholder: '[{"$match": {"status": "active"}}, {"$group": {"_id": "$category"}}]',
+                minHeight: 100,
+                maxHeight: 200,
+            },
+        ],
+    },
+};