@hostwebhook/node-types 1.69.0 → 1.70.0

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

@@ -0,0 +1,190 @@
+/**
+ * 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;
+    }>;
+}
+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.
+ */
+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.
+ *
+ * Ninguna lleva `destructive`, ni `delete_gmail_message` ni `trash_thread`.
+ * Lo merecerían —el toolkit de Drive marca sus borrados— pero hoy ninguna de las
+ * dos copias lo tenía y esto es una mudanza, no un cambio de comportamiento.
+ */
+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[];
+    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>;
+/**
+ * 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;