@hostwebhook/node-types 1.69.0 → 1.71.0

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

@@ -0,0 +1,78 @@
+/**
+ * Google Sheets operation enum + form schema — single source of truth across
+ * the API, Dashboard, and Message Broker. Used by:
+ *   - sheetsAction entity / DTO (api): operation field + validation
+ *   - dashboard SheetsAction detail page: the whole operation form
+ *
+ * The api already accepts these six; the dashboard's own `SheetsAction` type
+ * only listed four (it never learned about appendOrUpdateRow and
+ * createSpreadsheet), which is exactly the drift this enum removes.
+ */
+export declare const SHEETS_OPERATIONS: readonly ["appendRow", "updateRow", "appendOrUpdateRow", "readRange", "getRows", "createSpreadsheet"];
+export type SheetsOperation = (typeof SHEETS_OPERATIONS)[number];
+/** Type guard — useful when validating untrusted input (DTOs, AI tool calls). */
+export declare function isSheetsOperation(value: unknown): value is SheetsOperation;
+/**
+ * Per-operation form schema, same idea as SLACK_OPERATION_SPECS and
+ * GOOGLE_CONTACTS_OPERATION_SPECS: the detail page renders it with one loop
+ * instead of a branch per operation.
+ *
+ * Two things make this node's schema different from the others, and both are
+ * deliberate:
+ *
+ * 1. **The values are top-level entity fields, not an `operationConfig`
+ *    record.** `name` here is the property on the sheetsAction document
+ *    (`spreadsheetId`, `sheetName`, …), and `columnMapping` is a complex field.
+ *    A renderer copied from Contacts would write to the wrong place.
+ * 2. **Half the fields are discovered at run time.** The column list comes from
+ *    the chosen sheet's header row, fetched live. So the schema names the
+ *    *picker* rather than carrying options — the same trick Discord's
+ *    `channel` / `guild` / `role` types use.
+ */
+export interface SheetsParamSpec {
+    /** Field key — the property name on the sheetsAction document. */
+    name: string;
+    /** UI label. Empty string where the control has never shown one. */
+    label: string;
+    /**
+     * Param type for form rendering.
+     *
+     * - `string` — one-line input with `{{payload.x}}` templating.
+     * - `spreadsheet` — the spreadsheet picker **plus** the "or paste ID / URL"
+     *   input that sits under it. They are one field with two ways in, not two
+     *   fields, and the paste box extracts the id out of a full URL.
+     * - `sheetTab` — the tab picker for the chosen spreadsheet. Picking a tab
+     *   clears `columnMapping`, because the headers just changed.
+     * - `headerColumn` — a dropdown of the sheet's live header row.
+     * - `columnMapping` — the header-to-template editor. It owns the three
+     *   states of the header fetch (loading, loaded, failed), which is what
+     *   used to be six copies of the same conditional in the page.
+     */
+    type: 'string' | 'spreadsheet' | 'sheetTab' | 'headerColumn' | 'columnMapping';
+    /** Required by the operation. Metadata — the form does not gate on it. */
+    required?: boolean;
+    /** Help text under the control. Absent where the form shows none. */
+    description?: string;
+    /** Hint shown inside the input. */
+    placeholder?: string;
+    /**
+     * Section this field is rendered inside. Fields without one share the first
+     * section with the operation picker; the mapping fields sit in a second
+     * section whose title changes per operation ("Columns to Append",
+     * "Update Row", "Match & Upsert").
+     */
+    section?: string;
+    /** `columnMapping` only — the line shown while no column has been added. */
+    emptyText?: string;
+}
+export interface SheetsOperationSpec {
+    /** UI label for the operation picker. */
+    label: string;
+    /** Sub-line under the label in the picker. */
+    description: string;
+    /** googleapis call the operation maps to (sheets v4). */
+    apiMethod: string;
+    /** Parameter schema. Order matters for form rendering. */
+    params: SheetsParamSpec[];
+}
+export declare const SHEETS_OPERATION_SPECS: Record<SheetsOperation, SheetsOperationSpec>;

package/dist/esm/sheets-operations.js

@@ -0,0 +1,150 @@
+/**
+ * Google Sheets operation enum + form schema — single source of truth across
+ * the API, Dashboard, and Message Broker. Used by:
+ *   - sheetsAction entity / DTO (api): operation field + validation
+ *   - dashboard SheetsAction detail page: the whole operation form
+ *
+ * The api already accepts these six; the dashboard's own `SheetsAction` type
+ * only listed four (it never learned about appendOrUpdateRow and
+ * createSpreadsheet), which is exactly the drift this enum removes.
+ */
+export const SHEETS_OPERATIONS = [
+    'appendRow',
+    'updateRow',
+    'appendOrUpdateRow',
+    'readRange',
+    'getRows',
+    'createSpreadsheet',
+];
+/** Type guard — useful when validating untrusted input (DTOs, AI tool calls). */
+export function isSheetsOperation(value) {
+    return (typeof value === 'string' &&
+        SHEETS_OPERATIONS.includes(value));
+}
+/* Fields most operations share. The spreadsheet and its tab are the same two
+   controls everywhere they appear — createSpreadsheet is the only operation
+   that shows neither, because there is no document yet to point at. */
+const spreadsheet = () => ({
+    name: 'spreadsheetId',
+    label: 'Select Spreadsheet',
+    type: 'spreadsheet',
+    required: true,
+});
+const sheetTab = () => ({
+    name: 'sheetName',
+    label: 'Sheet Name',
+    type: 'sheetTab',
+    required: true,
+});
+/** The mapping editor, whose label, section and empty line change per op. */
+const columnMapping = (over = {}) => ({
+    name: 'columnMapping',
+    label: 'Columns to Update',
+    type: 'columnMapping',
+    emptyText: 'No columns selected. Add columns to update.',
+    ...over,
+});
+/** Which row to touch: the column to search in, and the value to look for. */
+const matchFields = (section) => [
+    {
+        name: 'matchColumn',
+        label: 'Match Column',
+        type: 'headerColumn',
+        required: true,
+        description: 'Select the column to find the row to update',
+        section,
+    },
+    {
+        /* No static placeholder or description: both are built from the chosen
+           column at render time ({{payload.<column>}} and 'Template to match
+           against "<column>"'), so the schema cannot carry them. */
+        name: 'matchValueTemplate',
+        label: 'Match Value',
+        type: 'string',
+        required: true,
+        section,
+    },
+];
+export const SHEETS_OPERATION_SPECS = {
+    appendRow: {
+        label: 'Append Row',
+        description: 'Add a new row at the bottom',
+        apiMethod: 'spreadsheets.values.batchUpdate',
+        params: [
+            spreadsheet(),
+            sheetTab(),
+            columnMapping({
+                /* The append editor has never carried a label of its own — the section
+                   title above it already says "Columns to Append". */
+                label: '',
+                section: 'Columns to Append',
+                emptyText: 'No columns selected. Add columns to populate in the new row.',
+            }),
+        ],
+    },
+    updateRow: {
+        label: 'Update Row',
+        description: 'Update cells in a specific range',
+        apiMethod: 'spreadsheets.values.batchUpdate',
+        params: [
+            spreadsheet(),
+            sheetTab(),
+            ...matchFields('Update Row'),
+            columnMapping({ section: 'Update Row' }),
+        ],
+    },
+    appendOrUpdateRow: {
+        label: 'Append or Update',
+        description: 'Update if row exists, append if not',
+        apiMethod: 'spreadsheets.values.batchUpdate',
+        /* Same fields as updateRow — only the section title differs. The label
+           inside still reads "Columns to Update", which is what the page has always
+           shown. */
+        params: [
+            spreadsheet(),
+            sheetTab(),
+            ...matchFields('Match & Upsert'),
+            columnMapping({ section: 'Match & Upsert' }),
+        ],
+    },
+    readRange: {
+        label: 'Read Range',
+        description: 'Read cells from a specific range',
+        apiMethod: 'spreadsheets.values.get',
+        params: [
+            spreadsheet(),
+            sheetTab(),
+            {
+                name: 'rangeTemplate',
+                label: 'Range Template',
+                type: 'string',
+                required: true,
+                placeholder: 'e.g. A2:D100',
+            },
+        ],
+    },
+    getRows: {
+        label: 'Get Rows',
+        description: 'Read all rows with headers as keys',
+        apiMethod: 'spreadsheets.values.get',
+        params: [spreadsheet(), sheetTab()],
+    },
+    createSpreadsheet: {
+        label: 'Create Spreadsheet',
+        description: 'Create a new Google Sheets spreadsheet',
+        apiMethod: 'spreadsheets.create',
+        /* `sheetName` means the **new document's title** here, not a tab — the one
+           field in this node that changes meaning *and* control between
+           operations. The api uses it for both the file name and its first tab. */
+        params: [
+            {
+                name: 'sheetName',
+                label: 'Spreadsheet Title',
+                type: 'string',
+                required: true,
+                placeholder: 'My New Spreadsheet',
+                description: 'Name of the new spreadsheet. Supports {{payload.field}} templates.',
+            },
+        ],
+    },
+};

package/dist/esm/sheets-toolkit.d.ts

@@ -0,0 +1,49 @@
+/**
+ * Google Sheets AI Toolkit — las herramientas que un sheetsAction expone
+ * cuando `aiEnabled` está encendido.
+ *
+ * **Se escribe una sola vez.**
+ *
+ * Cuando esto se escribió, las especificaciones de los demás nodos vivían dos
+ * veces —una copia en el dashboard y otra en
+ * `api/src/mcp-servers/toolkit-specs.ts`, las dos a mano y sin nada que las
+ * ate— y de ahí salió que Contacts anunciara 15 herramientas y expusiera una.
+ *
+ * Ya no es así, y este comentario decía lo contrario hasta 2026-08-12: hoy en
+ * el paquete viven **siete** toolkits —Gmail, native email, Calendar, Drive,
+ * Telegram, Sheets y Docs— y los que siguen duplicados a mano son WhatsApp,
+ * Discord, Slack y Contacts. El paquete es el sitio por defecto para uno
+ * nuevo; los cuatro rezagados están pendientes de migrar.
+ *
+ * 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 de herramientas del servidor MCP.
+ */
+import type { SheetsOperation } from './sheets-operations.js';
+export interface SheetsToolkitParameter {
+    name: string;
+    /** El esquema MCP sólo admite estos tres; lo estructurado viaja como JSON
+     *  en un `string`, igual que el `contacts` del toolkit de Contacts. */
+    type: 'string' | 'number' | 'boolean';
+    description: string;
+    required: boolean;
+}
+export interface SheetsToolkitSpec {
+    operation: SheetsOperation;
+    label: string;
+    toolName: string;
+    description: string;
+    parameters: SheetsToolkitParameter[];
+    /** Escribe en la hoja del usuario. Lo usa la confirmación previa del AI Node. */
+    destructive?: boolean;
+}
+export declare const SHEETS_TOOLKIT_SPECS: SheetsToolkitSpec[];
+/** Las herramientas por nombre, para despachar una llamada del modelo. */
+export declare const SHEETS_TOOLKIT_BY_TOOL_NAME: Record<string, SheetsToolkitSpec>;
+/**
+ * Los dos parámetros que el nodo puede rellenar por defecto. Se exporta para
+ * que la api y el dashboard no vuelvan a escribir la lista a mano —
+ * `create_spreadsheet` no declara ninguno de los dos y por eso se queda fuera
+ * de la inyección sin necesidad de excepciones.
+ */
+export declare const SHEETS_TOOLKIT_DEFAULTABLE: readonly ["spreadsheetId", "sheetName"];

package/dist/esm/sheets-toolkit.js

@@ -0,0 +1,127 @@
+/**
+ * Google Sheets AI Toolkit — las herramientas que un sheetsAction expone
+ * cuando `aiEnabled` está encendido.
+ *
+ * **Se escribe una sola vez.**
+ *
+ * Cuando esto se escribió, las especificaciones de los demás nodos vivían dos
+ * veces —una copia en el dashboard y otra en
+ * `api/src/mcp-servers/toolkit-specs.ts`, las dos a mano y sin nada que las
+ * ate— y de ahí salió que Contacts anunciara 15 herramientas y expusiera una.
+ *
+ * Ya no es así, y este comentario decía lo contrario hasta 2026-08-12: hoy en
+ * el paquete viven **siete** toolkits —Gmail, native email, Calendar, Drive,
+ * Telegram, Sheets y Docs— y los que siguen duplicados a mano son WhatsApp,
+ * Discord, Slack y Contacts. El paquete es el sitio por defecto para uno
+ * nuevo; los cuatro rezagados están pendientes de migrar.
+ *
+ * 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 de herramientas del servidor MCP.
+ */
+const p = (name, description, required = true, type = 'string') => ({ name, type, description, required });
+/*
+ * La hoja y la pestaña del nodo van como **defecto**, y el modelo puede
+ * cambiarlas — la misma decisión que el canal por defecto de Slack, y la misma
+ * maquinaria: `toolkitSpecToMcpTool(spec, nombre, { spreadsheetId, sheetName })`
+ * saca esos dos de `required` **y le cuenta el valor al modelo** en la
+ * descripción. Las dos cosas o ninguna: mientras el esquema diga `required`, el
+ * LLM siempre los rellena, nunca los omite, y el valor configurado no se usaría
+ * jamás.
+ *
+ * Por eso aquí se declaran `required: true`: lo son para la API de Google, y es
+ * el defecto del nodo quien los vuelve opcionales, nodo por nodo.
+ *
+ * `create_spreadsheet` es el único que NO los declara —no hay documento todavía
+ * al que apuntar— y su título se llama `title`, no `sheetName`. Si se llamara
+ * `sheetName`, la inyección de defectos vería que la operación declara ese
+ * parámetro y le pasaría como título el nombre de la pestaña del nodo: el
+ * documento nuevo nacería llamándose «Sheet1».
+ */
+const hoja = () => p('spreadsheetId', "Id of the Google Sheets document — the long chunk of its URL, between /d/ and /edit.");
+const pestana = () => p('sheetName', 'Name of the tab inside the document, exactly as it reads on its tab strip.');
+const fila = (que) => p('row', `JSON object holding ${que}. Keys are the sheet's **header names**, spelled exactly as they appear in its title row: {"Name": "Ariel", "Email": "a@b.c"}. A key that is not a header makes the call fail, so when you do not know the headers, call get_rows first.`);
+export const SHEETS_TOOLKIT_SPECS = [
+    {
+        operation: 'appendRow',
+        label: 'Append row',
+        toolName: 'append_row',
+        description: 'Add a new row at the bottom of the tab. It does not check whether the row already exists — when it might, use append_or_update_row instead so you do not duplicate it.',
+        parameters: [fila('the values of the new row'), hoja(), pestana()],
+        destructive: true,
+    },
+    {
+        operation: 'updateRow',
+        label: 'Update row',
+        toolName: 'update_row',
+        description: 'Find a row by the value of one column and overwrite the cells you pass. When no row matches it writes nothing — it does not create one.',
+        parameters: [
+            p('matchColumn', 'Header of the column to search in, e.g. "Email".'),
+            p('matchValue', 'Value to look for inside that column. The whole cell is compared, not a fragment.'),
+            fila('the cells to overwrite; the ones you leave out keep their value'),
+            hoja(),
+            pestana(),
+        ],
+        destructive: true,
+    },
+    {
+        operation: 'appendOrUpdateRow',
+        label: 'Append or update row',
+        toolName: 'append_or_update_row',
+        description: 'Find a row by the value of one column: update it when it exists, append it at the bottom when it does not. This is the one to use to keep a sheet in sync without duplicating rows.',
+        parameters: [
+            p('matchColumn', 'Header of the column that identifies the row, e.g. "Email".'),
+            p('matchValue', 'Value to look for in that column. When it is not there, the row is appended.'),
+            fila('the values of the row, used both to update and to append'),
+            hoja(),
+            pestana(),
+        ],
+        destructive: true,
+    },
+    {
+        operation: 'readRange',
+        label: 'Read range',
+        toolName: 'read_range',
+        description: 'Read the cells of an A1-notation range and return them as rows of text, without reading headers. To read data with its column names, get_rows is more useful.',
+        parameters: [
+            p('range', 'A1-notation range relative to the tab, e.g. "A2:D100". Do not prefix it with the tab name.'),
+            hoja(),
+            pestana(),
+        ],
+    },
+    {
+        operation: 'getRows',
+        label: 'Get rows',
+        toolName: 'get_rows',
+        description: "Read every row of the tab and return them as objects keyed by the sheet's headers. This is how you find out which columns a sheet has before writing to it.",
+        parameters: [hoja(), pestana()],
+    },
+    {
+        operation: 'createSpreadsheet',
+        label: 'Create spreadsheet',
+        toolName: 'create_spreadsheet',
+        description: "Create a new, empty Google Sheets document and return its id and URL. It writes no data: to fill it, call append_row afterwards with the id it returns. It lands wherever the node's Save Location says — you do not choose that.",
+        /*
+         * Sin `folderId` a propósito, y esta es la excepción a «defecto del nodo que
+         * el modelo puede cambiar».
+         *
+         * La hoja sí se le ofrece porque el modelo tiene de dónde sacar un id: se lo
+         * dice quien escribe, o lo devuelve un get_rows. Un id de carpeta de Drive
+         * no: no hay ninguna herramienta aquí que las liste, así que sólo podría
+         * inventárselo, y un id inventado falla mientras uno real acertado por
+         * casualidad escribe en la carpeta de otro. La carpeta la elige la persona
+         * en el nodo, y la api la aplica.
+         */
+        parameters: [p('title', 'Name of the new document.')],
+        destructive: true,
+    },
+];
+/** Las herramientas por nombre, para despachar una llamada del modelo. */
+export const SHEETS_TOOLKIT_BY_TOOL_NAME = Object.fromEntries(SHEETS_TOOLKIT_SPECS.map((s) => [s.toolName, s]));
+/**
+ * Los dos parámetros que el nodo puede rellenar por defecto. Se exporta para
+ * que la api y el dashboard no vuelvan a escribir la lista a mano —
+ * `create_spreadsheet` no declara ninguno de los dos y por eso se queda fuera
+ * de la inyección sin necesidad de excepciones.
+ */
+export const SHEETS_TOOLKIT_DEFAULTABLE = ['spreadsheetId', 'sheetName'];

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

@@ -0,0 +1,95 @@
+/**
+ * Shopify Admin API operations — single source of truth across the api, the
+ * dashboard and downstream consumers (MCP server).
+ *
+ * ## Four, out of several hundred
+ *
+ * The Admin API has hundreds of mutations. This node exposes four, and the
+ * choice is argued in `api/docs/ADR-0007-shopify.md`: a menu of everything is
+ * how a node becomes unusable, and these four cover what people actually
+ * automate — put a customer in the store, tag something, sync stock, and read
+ * back what the store already knows.
+ *
+ * Product creation and order fulfilment were considered and left out of v1.
+ * A product means variants, media and prices; a fulfilment means a location, a
+ * fulfilment service and a state machine. Each is a configuration surface of
+ * its own, not a field.
+ *
+ * ## GraphQL only, and the version is not ours to drift on
+ *
+ * REST went legacy in October 2024 and public apps have been GraphQL-only
+ * since April 2025, so there is no REST path here to fall back to. Every
+ * `apiRoute` below is a GraphQL mutation or query name, checkable against
+ * `shopify.dev/docs/api/admin-graphql`. The API version lives in ONE constant
+ * on the api side (`SHOPIFY_API_VERSION`) — never interpolated per call site.
+ *
+ * ## What was verified, and what was not (2026-08-25)
+ *
+ * Checked against the Admin GraphQL reference, not from memory:
+ *
+ * - `tagsAdd(id: ID!, tags: [String!]!)` and `tagsRemove` with the same
+ *   shape. Both accept Order, DraftOrder, Customer, Product, Article and
+ *   DiscountNode.
+ * - `customerCreate(input: CustomerInput!)` and `customerUpdate(input:
+ *   CustomerInput!)` — for the update, **the id goes inside the input**, not
+ *   as a sibling argument.
+ * - `inventoryAdjustQuantities(input: InventoryAdjustQuantitiesInput!)`, whose
+ *   input requires `reason`, `name` and a `changes[]` of
+ *   `{ delta, inventoryItemId, locationId }`.
+ *
+ * ⚠️ **NOT verified, and deliberately left loose below** — do not turn either
+ * into a hard-coded dropdown until someone reads the enumeration:
+ *
+ * - The full vocabulary of `reason`. Only `"correction"` is documented by
+ *   example.
+ * - The full vocabulary of `name`. Only `"available"` is documented by
+ *   example; the docs mention `on_hand` moving as a consequence, which is not
+ *   the same as it being a valid input.
+ * - The exact search syntax for finding a customer by email
+ *   (`customers(query: "email:…")`). It is the obvious shape and almost
+ *   certainly right, which is exactly why it is worth confirming rather than
+ *   assuming.
+ *
+ * ⚠️ **`@idempotent` is mandatory.** As of API version 2026-04,
+ * `inventoryAdjustQuantities` must be sent with the `@idempotent` directive
+ * and an idempotency key. A stock adjustment is the one operation here where a
+ * silent retry is a real inventory error, so this is not boilerplate.
+ */
+export declare const SHOPIFY_OPERATIONS: readonly ["upsertCustomer", "setTags", "adjustInventory", "findRecords"];
+export type ShopifyOperation = (typeof SHOPIFY_OPERATIONS)[number];
+/** Type guard — for DTOs and AI tool calls, where the input is untrusted. */
+export declare function isShopifyOperation(value: unknown): value is ShopifyOperation;
+/**
+ * The resources `tagsAdd` / `tagsRemove` accept. Taken from the mutation
+ * reference — this list is the API's, not a subset we chose.
+ *
+ * `article` and `discountNode` are left out of the node's own picker on
+ * purpose: neither is something a HostWebhook flow tags in practice, and every
+ * extra option is a field the user has to read past.
+ */
+export declare const SHOPIFY_TAGGABLE_RESOURCES: readonly ["order", "customer", "product", "draftOrder"];
+export type ShopifyTaggableResource = (typeof SHOPIFY_TAGGABLE_RESOURCES)[number];
+/** What `findRecords` can read back. */
+export declare const SHOPIFY_SEARCHABLE_RESOURCES: readonly ["orders", "customers", "products"];
+export type ShopifySearchableResource = (typeof SHOPIFY_SEARCHABLE_RESOURCES)[number];
+export interface ShopifyParamSpec {
+    /** Field key — also the property name on operationConfig. */
+    name: string;
+    label: string;
+    /** Param type, so the dashboard renders the right control. `location` is a
+     *  picker backed by a live lookup of the store's locations; `gid` is a
+     *  Shopify global id, which is almost always templated from the payload
+     *  rather than typed. */
+    type: 'gid' | 'location' | 'email' | 'string' | 'number' | 'tags' | 'taggableResource' | 'searchableResource' | 'json' | 'boolean';
+    required?: boolean;
+    description: string;
+    placeholder?: string;
+}
+export interface ShopifyOperationSpec {
+    label: string;
+    description: string;
+    /** The GraphQL operation this maps to, so the mapping is checkable. */
+    apiRoute: string;
+    params: ShopifyParamSpec[];
+}
+export declare const SHOPIFY_OPERATION_SPECS: Record<ShopifyOperation, ShopifyOperationSpec>;