@hostwebhook/node-types 1.69.0 → 1.71.0

package/dist/esm/jira-operations.js

@@ -0,0 +1,470 @@
+/**
+ * Las operaciones del nodo `jiraAction` — la lista que comparten la api, el
+ * dashboard y el broker.
+ *
+ * Mismo patrón que `github-operations.ts` y `shopify-operations.ts`.
+ *
+ * ── Contra qué está escrito ──
+ *
+ * Jira Cloud, **REST API v3**, servida en
+ * `https://api.atlassian.com/ex/jira/{cloudId}/rest/api/3/…`. El `cloudId` sale
+ * de la credencial `oauth2_atlassian`, que ya existe: la montó el trigger de
+ * Jira y aquí se reutiliza entera.
+ *
+ * El permiso que hace falta para escribir es **`write:jira-work`**. Se añadió a
+ * los de por defecto en api#384; toda credencial anterior a eso es de sólo
+ * lectura hasta que su dueño la reconecte, y el síntoma es un 403 al ejecutar,
+ * no un fallo al guardar.
+ *
+ * ── La decisión que ordena todo lo demás: ADF ──
+ *
+ * En la v3, `description` y el `body` de un comentario **no son texto**: son
+ * Atlassian Document Format, un árbol JSON de nodos tipados. Mandar una cadena
+ * da 400.
+ *
+ * La salida fácil sería escribir con la v2, que sí acepta texto plano y sigue
+ * soportada. No se hace, y el motivo está escrito en nuestro propio repositorio
+ * desde antes de este nodo: `jira-watch.service.ts` excluye `description` al
+ * hidratar campos y explica por qué — *"la REST devuelve ADF —un objeto— pero
+ * el webhook manda texto plano; mezclar formas rompería las plantillas de
+ * abajo, que esperan cadenas"*.
+ *
+ * O sea: si este nodo leyera con una versión y escribiera con otra,
+ * `{{payload.fields.description}}` significaría una cosa cuando el flujo lo
+ * dispara un trigger de Jira y otra cuando lo consulta este nodo. Por eso:
+ *
+ *   - **Todo en v3**, para leer y para escribir.
+ *   - Al escribir, el texto del usuario se envuelve en ADF.
+ *   - Al leer, el ADF se aplana a texto, y el árbol original viaja en una clave
+ *     hermana para quien lo necesite.
+ *   - `bodyFormat` deja pegar ADF crudo a quien quiera tablas o paneles.
+ *
+ * ── La otra trampa: la búsqueda cambió de sitio ──
+ *
+ * `GET/POST /rest/api/3/search` está **deprecado**. El sustituto es
+ * `POST /rest/api/3/search/jql`, y no es un renombre: pagina con
+ * `nextPageToken` en vez de `startAt`, **no devuelve `total`** (para contar hay
+ * `/search/approximate-count`) y los campos hay que pedirlos explícitamente.
+ * Casi todo ejemplo que hay por internet usa el endpoint muerto.
+ *
+ * ── Lo que NO es una operación ──
+ *
+ * Listar proyectos, tipos de incidencia, transiciones, estados o usuarios
+ * asignables **no** son operaciones: son endpoints del controlador que alimentan
+ * los selectores, como Drive alimenta su selector de ficheros. Una operación
+ * existe para producir payload en una corrida; esto otro es para rellenar el
+ * formulario. Mezclarlos llena el desplegable de cosas que nadie quiere
+ * ejecutar.
+ *
+ * ── Decisiones propias de Jira ──
+ *
+ *   - El proyecto y el tipo de incidencia se ELIGEN de una lista viva. Un
+ *     `issuetype` se identifica por un id numérico que nadie sabe de memoria.
+ *   - **Las transiciones no son una lista fija.** Dependen del flujo de trabajo
+ *     Y del estado actual de la incidencia, así que el selector las pide para
+ *     esa incidencia concreta. Ofrecer una lista global sería ofrecer
+ *     transiciones que fallan al ejecutarse.
+ *   - Los campos personalizados van en JSON crudo. Cada tipo tiene su forma
+ *     (`select`, `date`, `relation`, usuario…) y fingir que caben en tres
+ *     campos genéricos produce un 400 que no nombra el campo.
+ *   - Ninguna operación declarada sin implementar: el enum ES el contrato de la
+ *     pantalla, y una operación declarada se pinta en el desplegable y falla al
+ *     ejecutarse.
+ */
+export const JIRA_OPERATIONS = [
+    // Incidencias
+    'createIssue', // POST   /issue
+    'getIssue', // GET    /issue/{key}
+    'updateIssue', // PUT    /issue/{key}
+    'deleteIssue', // DELETE /issue/{key}
+    'assignIssue', // PUT    /issue/{key}/assignee
+    'transitionIssue', // POST   /issue/{key}/transitions
+    // Comentarios
+    'addComment', // POST   /issue/{key}/comment
+    'getComments', // GET    /issue/{key}/comment      → iterable
+    // Adjuntos y trabajo
+    'addAttachment', // POST   /issue/{key}/attachments
+    'addWorklog', // POST   /issue/{key}/worklog
+    // Relaciones
+    'linkIssues', // POST   /issueLink
+    // Transversal
+    'searchIssues', // POST   /search/jql              → iterable
+];
+/** Type guard — para validar entrada no fiable (DTOs, tool calls). */
+export function isJiraOperation(value) {
+    return (typeof value === 'string' &&
+        JIRA_OPERATIONS.includes(value));
+}
+/**
+ * Las operaciones que devuelven un ARRAY y por tanto obligan a marcar
+ * `_meta.iterable` en `getOutputPayload`.
+ *
+ * Vive aquí y no sólo en la api porque olvidarlo no falla al compilar: falla
+ * en producción, callado, con el nodo de abajo recibiendo el sobre entero en
+ * vez de un elemento y el PayloadViewer pintando rutas con corchetes que nadie
+ * puede usar.
+ */
+export const JIRA_ITERABLE_OPERATIONS = [
+    'getComments',
+    'searchIssues',
+];
+/* Ayudantes — repetir el mismo objeto doce veces es cómo se desincronizan las
+   descripciones. */
+const project = (required = true) => ({
+    name: 'projectKey',
+    label: 'Project',
+    type: 'jiraProject',
+    required,
+    description: 'De la lista de proyectos que alcanza esta credencial. Se guarda la clave (ACME).',
+});
+const issueKey = (label = 'Issue') => ({
+    name: 'issueKey',
+    label,
+    type: 'jiraIssueKey',
+    required: true,
+    placeholder: '{{payload.issueKey}}',
+    description: 'La clave que se ve en la URL (ACME-42), no el id interno. El trigger de Jira la deja en issueKey.',
+});
+/**
+ * El interruptor de formato para todo campo que Jira quiere en ADF.
+ *
+ * Por defecto `text`: se escribe normal y el nodo lo envuelve. `adf` es la
+ * salida para quien necesita tablas, paneles o menciones — cosas que el texto
+ * plano no sabe expresar y que no vale la pena inventarse un lenguaje para
+ * cubrir.
+ */
+const bodyFormat = () => ({
+    name: 'bodyFormat',
+    label: 'Format',
+    type: 'select',
+    default: 'text',
+    advanced: true,
+    options: [
+        { value: 'text', label: 'Plain text (se convierte a ADF)' },
+        { value: 'adf', label: 'Atlassian Document Format en crudo' },
+    ],
+    description: 'Jira v3 guarda estos campos como ADF. En "plain text" el nodo lo envuelve por ti: un párrafo por bloque y salto de línea donde lo escribas.',
+});
+const customFields = () => ({
+    name: 'customFields',
+    label: 'Other fields (JSON)',
+    type: 'json',
+    advanced: true,
+    placeholder: '{ "customfield_10042": { "accountId": "..." }, "labels": ["urgente"] }',
+    description: 'Se mezcla tal cual dentro de `fields`. Cada tipo de campo de Jira tiene su forma; el esquema real se lee con el selector de campos de la pantalla.',
+});
+const maxResults = () => ({
+    name: 'maxResults',
+    label: 'How many at most',
+    type: 'number',
+    default: 50,
+    min: 1,
+    max: 100,
+    advanced: true,
+    description: 'Jira no devuelve más de 100 por página.',
+});
+export const JIRA_OPERATION_SPECS = {
+    createIssue: {
+        label: 'Create issue',
+        description: 'Crea una incidencia en un proyecto.',
+        apiRoute: 'POST /rest/api/3/issue',
+        params: [
+            project(),
+            {
+                name: 'issueTypeId',
+                label: 'Issue type',
+                type: 'jiraIssueType',
+                required: true,
+                description: 'Los tipos son del proyecto, no globales: se piden después de elegirlo.',
+            },
+            {
+                name: 'summary',
+                label: 'Summary',
+                type: 'template',
+                required: true,
+                placeholder: 'Fallo al exportar el informe',
+                description: 'El título. Es el único campo que Jira exige siempre.',
+            },
+            {
+                name: 'description',
+                label: 'Description',
+                type: 'textarea',
+                placeholder: 'Lo que pasó, con {{payload.x}} si hace falta.',
+            },
+            bodyFormat(),
+            {
+                name: 'assigneeAccountId',
+                label: 'Assignee',
+                type: 'jiraUser',
+                advanced: true,
+                description: 'Se guarda el accountId, que es como lo pide Jira.',
+            },
+            {
+                name: 'parentKey',
+                label: 'Parent issue',
+                type: 'template',
+                advanced: true,
+                placeholder: 'ACME-10',
+                description: 'Sólo para subtareas: la incidencia padre. Con un tipo que no sea subtarea, Jira lo rechaza.',
+            },
+            customFields(),
+        ],
+    },
+    getIssue: {
+        label: 'Get issue',
+        description: 'Lee una incidencia por su clave.',
+        apiRoute: 'GET /rest/api/3/issue/{issueIdOrKey}',
+        params: [
+            issueKey(),
+            {
+                name: 'fields',
+                label: 'Fields',
+                type: 'template',
+                advanced: true,
+                placeholder: 'summary,status,assignee',
+                description: 'Separados por comas. Vacío trae los de siempre. Pedir sólo lo que usas hace la respuesta mucho más pequeña.',
+            },
+        ],
+    },
+    updateIssue: {
+        label: 'Update issue',
+        description: 'Cambia campos de una incidencia.',
+        apiRoute: 'PUT /rest/api/3/issue/{issueIdOrKey}',
+        params: [
+            issueKey(),
+            {
+                name: 'summary',
+                label: 'Summary',
+                type: 'template',
+                description: 'Vacío = no se toca.',
+            },
+            {
+                name: 'description',
+                label: 'Description',
+                type: 'textarea',
+                description: 'Vacío = no se toca. REEMPLAZA la descripción entera.',
+            },
+            bodyFormat(),
+            customFields(),
+        ],
+    },
+    deleteIssue: {
+        label: 'Delete issue',
+        description: 'Borra una incidencia. No hay papelera.',
+        apiRoute: 'DELETE /rest/api/3/issue/{issueIdOrKey}',
+        params: [
+            issueKey(),
+            {
+                name: 'deleteSubtasks',
+                label: 'Delete its subtasks too',
+                type: 'booleanSelect',
+                options: [
+                    { value: '', label: '— sin tocar —' },
+                    { value: 'true', label: 'Sí, borrar las subtareas' },
+                    { value: 'false', label: 'No' },
+                ],
+                description: 'Con subtareas y sin esto, Jira se niega a borrar y devuelve 400.',
+            },
+        ],
+    },
+    assignIssue: {
+        label: 'Assign issue',
+        description: 'Cambia a quién está asignada.',
+        apiRoute: 'PUT /rest/api/3/issue/{issueIdOrKey}/assignee',
+        params: [
+            issueKey(),
+            {
+                name: 'accountId',
+                label: 'Assignee',
+                type: 'jiraUser',
+                required: true,
+                description: 'Vacío deja la incidencia sin asignar.',
+            },
+        ],
+    },
+    transitionIssue: {
+        label: 'Move issue',
+        description: 'Mueve la incidencia de columna (transición del flujo).',
+        apiRoute: 'POST /rest/api/3/issue/{issueIdOrKey}/transitions',
+        params: [
+            issueKey(),
+            {
+                name: 'transitionId',
+                label: 'Transition',
+                type: 'jiraTransition',
+                required: true,
+                description: 'Las transiciones legales dependen del flujo de trabajo Y del estado actual, así que se piden para esta incidencia. Una que no aplique falla al ejecutarse.',
+            },
+            {
+                name: 'comment',
+                label: 'Comment (optional)',
+                type: 'textarea',
+                advanced: true,
+                description: 'Jira permite comentar en el mismo paso de la transición.',
+            },
+            bodyFormat(),
+        ],
+    },
+    addComment: {
+        label: 'Add comment',
+        description: 'Comenta en una incidencia.',
+        apiRoute: 'POST /rest/api/3/issue/{issueIdOrKey}/comment',
+        params: [
+            issueKey(),
+            {
+                name: 'body',
+                label: 'Comment',
+                type: 'textarea',
+                required: true,
+                placeholder: 'Desplegado en producción: {{payload.version}}',
+            },
+            bodyFormat(),
+        ],
+    },
+    getComments: {
+        label: 'Get comments',
+        description: 'Trae los comentarios de una incidencia.',
+        apiRoute: 'GET /rest/api/3/issue/{issueIdOrKey}/comment',
+        params: [
+            issueKey(),
+            {
+                name: 'orderBy',
+                label: 'Order',
+                type: 'select',
+                default: '-created',
+                advanced: true,
+                options: [
+                    { value: '-created', label: 'Los más nuevos primero' },
+                    { value: 'created', label: 'Los más viejos primero' },
+                ],
+            },
+            maxResults(),
+        ],
+    },
+    addAttachment: {
+        label: 'Attach file',
+        description: 'Sube un fichero a una incidencia.',
+        apiRoute: 'POST /rest/api/3/issue/{issueIdOrKey}/attachments',
+        params: [
+            issueKey(),
+            {
+                name: 'fileField',
+                label: 'File from payload',
+                type: 'template',
+                required: true,
+                placeholder: '{{payload.file}}',
+                description: 'La ruta del payload donde viene el fichero — lo que dejan el nodo de ficheros o un adjunto de Gmail.',
+            },
+            {
+                name: 'fileName',
+                label: 'File name',
+                type: 'template',
+                advanced: true,
+                placeholder: 'informe.pdf',
+                description: 'Vacío usa el nombre que traiga el propio fichero.',
+            },
+        ],
+    },
+    addWorklog: {
+        label: 'Log work',
+        description: 'Apunta tiempo trabajado en una incidencia.',
+        apiRoute: 'POST /rest/api/3/issue/{issueIdOrKey}/worklog',
+        params: [
+            issueKey(),
+            {
+                name: 'timeSpent',
+                label: 'Time spent',
+                type: 'template',
+                required: true,
+                placeholder: '3h 30m',
+                description: 'En el formato de Jira: 2d, 3h, 30m, o combinados. No admite decimales.',
+            },
+            {
+                name: 'comment',
+                label: 'Comment',
+                type: 'textarea',
+                advanced: true,
+            },
+            bodyFormat(),
+            {
+                name: 'started',
+                label: 'When',
+                type: 'template',
+                advanced: true,
+                placeholder: '{{payload.timestamp}}',
+                description: 'Vacío usa el momento de la ejecución.',
+            },
+        ],
+    },
+    linkIssues: {
+        label: 'Link issues',
+        description: 'Relaciona dos incidencias entre sí.',
+        apiRoute: 'POST /rest/api/3/issueLink',
+        params: [
+            {
+                name: 'inwardIssueKey',
+                label: 'From issue',
+                type: 'jiraIssueKey',
+                required: true,
+                placeholder: '{{payload.issueKey}}',
+            },
+            {
+                name: 'linkType',
+                label: 'Relationship',
+                type: 'jiraLinkType',
+                required: true,
+                description: 'Los tipos los define cada sitio: "Blocks", "Relates", "Duplicates"… Se piden a Jira.',
+            },
+            {
+                name: 'outwardIssueKey',
+                label: 'To issue',
+                type: 'jiraIssueKey',
+                required: true,
+                placeholder: 'ACME-99',
+            },
+        ],
+    },
+    searchIssues: {
+        label: 'Search issues (JQL)',
+        description: 'Busca incidencias con JQL. Devuelve una lista iterable.',
+        /* ⚠️ `/search/jql`, NO `/search`. El viejo está deprecado y pagina distinto:
+           `nextPageToken` en vez de `startAt`, y sin `total` en la respuesta. */
+        apiRoute: 'POST /rest/api/3/search/jql',
+        params: [
+            {
+                name: 'jql',
+                label: 'JQL',
+                type: 'textarea',
+                required: true,
+                placeholder: 'project = ACME AND status != Done ORDER BY created DESC',
+                description: 'La misma consulta que escribirías en el buscador de Jira. Admite {{payload.x}}.',
+            },
+            {
+                name: 'fields',
+                label: 'Fields',
+                type: 'template',
+                advanced: true,
+                placeholder: 'summary,status,assignee',
+                description: 'Separados por comas. En este endpoint los campos hay que pedirlos: sin esto sólo llegan las claves.',
+            },
+            maxResults(),
+            {
+                name: 'nextPageToken',
+                label: 'Page token',
+                type: 'template',
+                advanced: true,
+                placeholder: '{{payload.nextPageToken}}',
+                description: 'Para pedir la página siguiente desde un Loop. La salida de esta operación lo devuelve.',
+            },
+        ],
+    },
+};
+/**
+ * Lo que se ofrece en el desplegable de operación.
+ *
+ * Hoy son todas. Existe como constante aparte —y no como alias de
+ * `JIRA_OPERATIONS`— porque es el punto donde otros nodos han necesitado
+ * esconder una operación sin sacarla del enum: retirarla del enum rompe las que
+ * ya estaban guardadas en la base de datos.
+ */
+export const JIRA_DROPDOWN_OPERATIONS = JIRA_OPERATIONS;

package/dist/esm/llm-models.d.ts

@@ -0,0 +1,101 @@
+/**
+ * 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 type LlmProvider = 'anthropic' | 'openai' | 'google' | 'groq'
+/**
+ * A router, not a lab: OpenRouter resells ~425 models from everybody else
+ * behind one key. That is why it is the first provider here whose catalog
+ * is EMPTY below and fetched live instead — the shape of the entry is in
+ * `openrouter.ts`, and the price of each model travels with the model.
+ */
+ | 'openrouter';
+export interface LlmProviderOption {
+    value: LlmProvider;
+    label: string;
+}
+export interface LlmModelOption {
+    value: string;
+    /** Friendly label for pickers; defaults to `value` when absent. */
+    label?: string;
+    /**
+     * The suggested default for new selections — exactly one per provider.
+     *
+     * It carries more weight than "preselected in a dropdown": the api
+     * reads it through `getDefaultModel` for the model a new AI node is
+     * born with, and for the cheap model it picks when generating a tool
+     * definition or extracting memory facts. So the recommended entry must
+     * be the cheapest CURRENT-tier model of that provider — pick a
+     * flagship here and every background call gets expensive at once.
+     */
+    recommended?: boolean;
+}
+export declare const LLM_PROVIDERS: ReadonlyArray<LlmProviderOption>;
+export declare const LLM_MODELS: Record<LlmProvider, ReadonlyArray<LlmModelOption>>;
+/**
+ * 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 declare const MODEL_CONTEXT_WINDOWS: Record<string, number>;
+/**
+ * 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 declare function getModelsFor(provider: string): ReadonlyArray<LlmModelOption>;
+/**
+ * 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 declare function getDefaultModel(provider: string): string;
+/** The friendly label for a model value, or the value itself. */
+export declare function getModelLabel(value: string): string;