/**
 * Gmail operation enum — single source of truth across the API, Dashboard,
 * and Message Broker. Used by:
 *   - emailAction entity / DTO (api): operation field + validation
 *   - dashboard EmailActionGmailOperation type
 *   - broker hostwebhook types + tool schemas
 *   - trigger / future Gmail-related nodes
 *
 * Adding a new Gmail operation = add it here, bump this package's
 * version, publish to npm, and re-install in the consuming repos.
 * Each consumer still owns its operation-specific config schema (the
 * dashboard owns the UI form schema, the api owns the dispatch logic),
 * but the canonical list of valid operation strings lives here.
 */
export declare const GMAIL_OPERATIONS: readonly ["send", "sendAndWaitForResponse", "createDraft", "sendDraft", "replyToThread", "getMessage", "listMessages", "deleteMessage", "markRead", "markUnread", "addLabel", "removeLabel", "listLabels", "createLabel", "getThread", "trashThread", "untrashThread"];
export type GmailOperation = (typeof GMAIL_OPERATIONS)[number];
/** Type guard — useful when validating untrusted input (DTOs, tool calls). */
export declare function isGmailOperation(value: unknown): value is GmailOperation;
/**
 * Esquema de formulario, grupos del desplegable y toolkits de Gmail.
 *
 * El enum de arriba ya estaba aquí y ya lo importaban la api (DTO + entidad) y
 * el dashboard. Lo que baja ahora es todo lo demás, que vivía escrito a mano en
 * cuatro sitios:
 *
 *   - `OP_SCHEMA` de `OperationFieldsRenderer.tsx` — 17 ops, 53 campos
 *   - `OPERATION_GROUPS` de `OperationSelector.tsx` — 16 ops con etiqueta,
 *     descripción y grupo
 *   - `GMAIL_OPERATION_SPECS` del dashboard y **la misma lista otra vez** en
 *     `api/src/mcp-servers/toolkit-specs.ts` — 16 herramientas cada una
 *   - `NATIVE_EMAIL_OPERATION_SPECS`, igual, por duplicado
 *
 * Las dos copias del toolkit estaban idénticas el día de la mudanza (0
 * divergencias medidas), lo cual es suerte y no diseño: viven en repos
 * distintos, así que **ningún test podía compararlas**. Por eso bajan.
 *
 * OJO CON EL NOMBRE. En el dashboard `GMAIL_OPERATION_SPECS` eran las specs del
 * *toolkit*, al revés que en los otros diez nodos. Aquí se respeta la convención
 * del paquete: `*_OPERATION_SPECS` es el **formulario** y `*_TOOLKIT_SPECS` son
 * las **herramientas**.
 */
/** Encabezados del desplegable, en orden de aparición. */
export declare const GMAIL_OPERATION_GROUPS: readonly ["Messages", "Drafts", "Labels", "Threads"];
export type GmailOperationGroup = (typeof GMAIL_OPERATION_GROUPS)[number];
/**
 * Tipo de control del formulario. Todos tienen precedente en el paquete salvo
 * `emails`, que es propio de este nodo (el `EmailChipsInput` con
 * autocompletado), como el `docPicker` de Docs.
 *
 *   - `string`       — `TemplateInput` de una línea
 *   - `htmlTemplate` — cuerpo con el interruptor Plain <-> Advanced (HTML).
 *                      Igual que en Docs.
 *   - `emails`       — `EmailChipsInput`; se guarda como **array**
 *   - `csvList`      — se guarda como array y se edita como texto separado por
 *                      comas. El mismo de Contacts; perder el array al guardar
 *                      rompe el nodo en ejecución
 *   - `select`       — `<select>`; las etiquetas no son los valores, así que
 *                      `options` es obligatorio
 *   - `number`, `boolean` — lo que parecen
 *
 * No hay `min`/`max`: hoy ningún campo numérico de este nodo los usa, y
 * añadirlos sin que nadie los lea es el `color` que nadie leía en Postgres.
 */
export type GmailParamType = 'string' | 'htmlTemplate' | 'emails' | 'csvList' | 'select' | 'number' | 'boolean';
export interface GmailParamSpec {
    /** Clave dentro de `operationConfig`. */
    name: string;
    /** Etiqueta encima del control. */
    label: string;
    type: GmailParamType;
    /** Lo exige la operación. Metadato: el formulario no bloquea el guardado. */
    required?: boolean;
    /** Texto de ayuda debajo del control (el `help` de antes). */
    description?: string;
    placeholder?: string;
    /** Sólo `htmlTemplate`: lenguaje del editor cuando está en modo Advanced. */
    language?: string;
    /** Sólo `select`. */
    options?: ReadonlyArray<{
        value: string;
        label: string;
    }>;
    /**
     * Se pinta en la pestaña «Advanced» y no en «Config» [2026-09-14]. Igual
     * que Drive, GitHub o Bucket. Lo que va ahí: las cabeceras del hilo
     * (threadId, inReplyTo, references), CC/BCC, y los adjuntos.
     */
    advanced?: boolean;
    /**
     * Sólo `boolean` [2026-10-08]: lo que vale si el nodo no lo tiene guardado.
     * El servidor aplica el mismo valor, así que el formulario lo pinta así y
     * la persona ve lo que va a pasar sin tener que tocarlo. Hoy sólo
     * `createIfMissing` de «Add label».
     */
    default?: boolean;
}
export interface GmailOperationSpec {
    /** Etiqueta del desplegable y de la página. */
    label: string;
    /**
     * Etiqueta corta para la píldora del lienzo, que va en `uppercase` sobre una
     * tarjeta de 260px. Sin esto la tarjeta pintaba el `operation` crudo y decía
     * `SENDANDWAITFORRESPONSE`; es el mismo defecto que tenía Mongo.
     */
    labelShort: string;
    /** Línea debajo de la etiqueta en el desplegable. */
    description?: string;
    /**
     * Grupo del desplegable. **Ausente = no se ofrece en modo de una sola op**,
     * que hoy es el caso de `sendDraft` y sólo de él.
     */
    group?: GmailOperationGroup;
    /** Campos, en orden de pantalla. */
    params: GmailParamSpec[];
}
/**
 * El orden de las claves dentro de cada grupo **es** el orden del desplegable,
 * igual que en Contacts: mover una clave mueve la pantalla.
 *
 * `send` ya no lleva `cc` ni `bcc`. Estaban declaradas y no se pintaban nunca —el
 * renderizador se invocaba tras `operation !== "send"`— y la ruta determinista no
 * las sabe mandar: `emailSender.send` recibe to/subject/html y nada más. Darles
 * soporte es una función nueva, no una mudanza.
 *
 * `attachments` [2026-09-14]: las cuatro operaciones que arman un mensaje
 * (send, sendAndWaitForResponse, createDraft, replyToThread) adjuntan lo que
 * el flujo ya tiene. Es una RUTA del payload, como el «File from payload» de
 * Jira: la api saca las referencias `_file`, las resuelve por el registro con
 * el `orgId` y arma el `multipart/mixed`. No hay subida a mano. Va en Advanced.
 */
export declare const GMAIL_OPERATION_SPECS: Record<GmailOperation, GmailOperationSpec>;
export declare const GMAIL_DROPDOWN_OPERATIONS: readonly GmailOperation[];
export declare const GMAIL_TOOLKIT_OPERATIONS: readonly GmailOperation[];
/**
 * Las herramientas que un emailAction con Gmail expone cuando `aiEnabled` está
 * encendido. La forma es la que ya consume `toolkitSpecToMcpTool` en la api,
 * para que pueda usarse sin adaptador. Los textos van en inglés porque los lee
 * el modelo y quien mire la lista del servidor MCP.
 *
 * `destructive` no se escribe a mano: lo pone `marcarDestructivas` leyendo el
 * verbo del nombre (hoy `delete_email`, `remove_email_label` y
 * `trash_email_thread`). Medido 2026-10-01 con un AI Node: el gate «Block
 * destructive tool calls» para `delete_email`.
 */
export interface GmailToolkitParameter {
    name: string;
    type: 'string' | 'number' | 'boolean';
    description: string;
    required: boolean;
}
export interface GmailToolkitSpec {
    operation: GmailOperation;
    label: string;
    /**
     * Nombre con el que lo llama el LLM. Lleva `_gmail_` o `_email` para no
     * chocar con el `send_telegram_message` ni el `create_event` de Calendar
     * cuando un mismo AI Node tiene varios toolkits encendidos.
     */
    toolName: string;
    description: string;
    parameters: GmailToolkitParameter[];
    /** Pisa o borra. Lo pone `marcarDestructivas` leyendo el verbo del
     *  nombre (ver `clase-de-herramienta.ts`), no se escribe a mano. */
    destructive?: boolean;
}
export declare const GMAIL_TOOLKIT_SPECS: GmailToolkitSpec[];
/**
 * La op que espera, **fuera** del toolkit y aparte a propósito. Sigue haciendo
 * falta para dos cosas que no son el toolkit: reconocer la operación de una
 * herramienta ya guardada (si desapareciera, un `send_email_and_wait` creado antes
 * se quedaría sin etiqueta) y el modo de una sola op elegido como herramienta
 * suelta, donde el pipeline sí espera el clic.
 */
export declare const GMAIL_SEND_AND_WAIT_TOOL_SPEC: GmailToolkitSpec;
/** Todo lo que el nodo sabe ejecutar, se ofrezca o no como herramienta. */
export declare const GMAIL_ALL_TOOLKIT_SPECS: GmailToolkitSpec[];
/** El toolkit del proveedor nativo (Resend): una sola herramienta. */
export declare const NATIVE_EMAIL_TOOLKIT_SPECS: GmailToolkitSpec[];
export declare const GMAIL_TOOLKIT_BY_TOOL_NAME: Record<string, GmailToolkitSpec>;
export declare const NATIVE_EMAIL_TOOLKIT_BY_TOOL_NAME: Record<string, GmailToolkitSpec>;
/**
 * La descripción que llevaba `delete_email` hasta 1.123.0, cuando la
 * herramienta tenía `permanent`.
 *
 * Hace falta conocerla porque las herramientas se GUARDAN en el AI Node al
 * elegirlas: el selector del panel copia la descripción y los parámetros de
 * la spec de ese día, y el AI Node arma el esquema del modelo con esa copia.
 * Quitar `permanent` del paquete no la toca. Ver
 * `herramientaDeGmailSinBorradoDefinitivo`.
 */
export declare const GMAIL_DELETE_EMAIL_DESCRIPCION_DE_ANTES: string;
/** Lo que se le añade a una descripción escrita a mano que promete borrar para siempre. */
export declare const GMAIL_SOLO_PAPELERA_PARA_EL_MODELO = "It only moves the message to Trash: deleting it for good is not available.";
/** Lo que la función mira de una herramienta guardada en un AI Node. */
export interface HerramientaDeCorreoGuardada {
    kind?: string;
    nodeRefType?: string;
    description?: string;
    parameters?: Array<{
        name: string;
    }>;
}
/**
 * Una herramienta «Delete message» guardada antes de 1.123.1, sin el borrado
 * definitivo que ya no existe [2026-10-02].
 *
 * Google sólo deja borrar un correo para siempre con acceso completo al buzón
 * (`https://mail.google.com/`), que HostWebhook no pide; el `permanent` de
 * `delete_email` fallaba siempre y se quitó. Pero un AI Node que eligió la
 * herramienta antes la tiene guardada con `permanent` en los parámetros y la
 * descripción de antes, y se la seguía ofreciendo al modelo. Esto la deja como
 * la de hoy:
 *
 *   - sin el parámetro `permanent`;
 *   - con la descripción de hoy donde estaba la de antes, sin tocar lo que va
 *     delante (`Gmail "Buzón" · Delete message: …` en un toolkit,
 *     `Delete message: …` en una single operation);
 *   - y si la descripción la escribió el dueño y promete borrar para siempre,
 *     con `GMAIL_SOLO_PAPELERA_PARA_EL_MODELO` al final.
 *
 * `operacion` la decide quien llama, porque cada repo la saca a su manera
 * (`operationOverride` o, en las muy viejas, inferida del nombre y los
 * parámetros). Sólo actúa con `deleteMessage` en un nodo de correo; con
 * cualquier otra cosa —o si ya está al día— devuelve la MISMA herramienta, así
 * que se puede pasar por aquí cada turno sin coste.
 *
 * No cambia la operación ni lo demás: quien despacha debe seguir infiriendo
 * con la herramienta ORIGINAL, que es la que conserva el juego de parámetros
 * de antes.
 */
export declare function herramientaDeGmailSinBorradoDefinitivo<T extends HerramientaDeCorreoGuardada>(tool: T, operacion: string | null | undefined): T;
/**
 * De dónde salen `to` / `subject` / `body` de un `send`.
 *
 * Los tres se guardaban planos en la raíz de la entidad mientras las otras 16
 * operaciones usaban `operationConfig`. Desde la unificación **se escribe
 * siempre en `operationConfig`**, y esto resuelve la lectura para que ninguna
 * fila anterior se rompa: primero `operationConfig`, y si no está, el campo
 * plano.
 *
 * Vive en el paquete a propósito. Si cada repo se escribiera su propio helper
 * volveríamos a tener dos copias de la misma regla, que es justo lo que esta
 * mudanza viene a quitar. Lo usan los 8 sitios que leían los campos planos: el
 * envío, el send-and-wait, las entregas, la página, la tarjeta del lienzo, el
 * resumen del panel y la validación.
 *
 * `??` y no `||`: si el usuario **vacía** los destinatarios, `operationConfig.to`
 * es `[]` y tiene que ganar. Con `||` resucitaría el valor viejo del campo plano.
 */
export interface GmailSendFieldSource {
    to?: unknown;
    subject?: unknown;
    body?: unknown;
    operationConfig?: Record<string, unknown> | null;
}
export interface GmailSendFields {
    to: string[];
    subject: string;
    body: string;
}
/** Los tres campos que un día vivieron en la raíz. */
export declare const GMAIL_SEND_LEGACY_FIELDS: readonly ["to", "subject", "body"];
export declare function resolveGmailSendFields(entity: GmailSendFieldSource | null | undefined): GmailSendFields;