@hostwebhook/node-types 1.69.0 → 1.70.0

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>;

package/dist/esm/shopify-operations.js

@@ -0,0 +1,259 @@
+/**
+ * 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 const SHOPIFY_OPERATIONS = [
+    'upsertCustomer',
+    'setTags',
+    'adjustInventory',
+    'findRecords',
+];
+/** Type guard — for DTOs and AI tool calls, where the input is untrusted. */
+export function isShopifyOperation(value) {
+    return (typeof value === 'string' &&
+        SHOPIFY_OPERATIONS.includes(value));
+}
+/**
+ * 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 const SHOPIFY_TAGGABLE_RESOURCES = [
+    'order',
+    'customer',
+    'product',
+    'draftOrder',
+];
+/** What `findRecords` can read back. */
+export const SHOPIFY_SEARCHABLE_RESOURCES = [
+    'orders',
+    'customers',
+    'products',
+];
+export const SHOPIFY_OPERATION_SPECS = {
+    upsertCustomer: {
+        label: 'Add or update customer',
+        description: 'Look the customer up by email, then create them or update the fields you set.',
+        apiRoute: 'mutation customerCreate / customerUpdate (lookup by email first)',
+        params: [
+            {
+                name: 'email',
+                label: 'Email address',
+                type: 'email',
+                required: true,
+                description: 'Identifies the customer. This is what decides between creating and updating — there is no separate "id" to keep.',
+                placeholder: '{{payload.email}}',
+            },
+            {
+                name: 'firstName',
+                label: 'First name',
+                type: 'string',
+                description: 'Left untouched on an existing customer if you leave it empty.',
+                placeholder: '{{payload.firstName}}',
+            },
+            {
+                name: 'lastName',
+                label: 'Last name',
+                type: 'string',
+                description: 'Left untouched on an existing customer if you leave it empty.',
+                placeholder: '{{payload.lastName}}',
+            },
+            {
+                name: 'phone',
+                label: 'Phone',
+                type: 'string',
+                description: 'Shopify wants it in E.164 (+52…). A malformed number fails the whole mutation, not just the field.',
+            },
+            {
+                name: 'tags',
+                label: 'Tags',
+                type: 'tags',
+                description: 'Tags to set on the customer. Note these REPLACE the customer tags — to add without losing the existing ones, use the tag operation instead.',
+            },
+            {
+                name: 'note',
+                label: 'Note',
+                type: 'string',
+                description: 'Internal note, visible to staff in the Shopify admin.',
+            },
+            {
+                name: 'emailMarketingConsent',
+                label: 'Email marketing consent',
+                type: 'json',
+                description: 'Leave this EMPTY unless the customer actually consented. Omitting it leaves their consent exactly as it was; writing a subscribed state for someone who never opted in is a legal problem, not a technical one. Shape: {"marketingState":"SUBSCRIBED","marketingOptInLevel":"SINGLE_OPT_IN"}.',
+            },
+        ],
+    },
+    setTags: {
+        label: 'Add or remove tags',
+        description: 'Tag an order, a customer or a product. Adding and removing are separate calls, so one node does one of the two.',
+        apiRoute: 'mutation tagsAdd / tagsRemove',
+        params: [
+            {
+                name: 'resource',
+                label: 'What to tag',
+                type: 'taggableResource',
+                required: true,
+                description: 'Shopify tags many resource types through the same mutation; this only picks which id you are passing.',
+            },
+            {
+                name: 'resourceId',
+                label: 'Resource id',
+                type: 'gid',
+                required: true,
+                description: 'The Shopify global id, e.g. gid://shopify/Order/1234. A Shopify trigger gives you this directly in the payload.',
+                placeholder: '{{payload.admin_graphql_api_id}}',
+            },
+            {
+                name: 'tags',
+                label: 'Tags',
+                type: 'tags',
+                required: true,
+                description: 'One or more tags.',
+            },
+            {
+                name: 'remove',
+                label: 'Remove instead of add',
+                type: 'boolean',
+                description: 'Off adds the tags (tagsAdd); on removes them (tagsRemove). Unlike Mailchimp, Shopify cannot do both in one call.',
+            },
+        ],
+    },
+    adjustInventory: {
+        label: 'Adjust inventory',
+        description: 'Move stock by a delta at one location. For the case where the real stock lives in another system.',
+        apiRoute: 'mutation inventoryAdjustQuantities',
+        params: [
+            {
+                name: 'inventoryItemId',
+                label: 'Inventory item id',
+                type: 'gid',
+                required: true,
+                description: 'gid://shopify/InventoryItem/1234. This is the inventory item, NOT the product or the variant — a variant points at one.',
+                placeholder: '{{payload.inventory_item_id}}',
+            },
+            {
+                name: 'locationId',
+                label: 'Location',
+                type: 'location',
+                required: true,
+                description: 'Which location the stock moves at. A store with one location still has to name it.',
+            },
+            {
+                name: 'delta',
+                label: 'Change by',
+                type: 'number',
+                required: true,
+                description: 'A DELTA, not a total. 5 adds five units and -5 removes five. Sending the absolute stock level here is the mistake that silently multiplies inventory.',
+                placeholder: '{{payload.delta}}',
+            },
+            {
+                name: 'name',
+                label: 'Quantity type',
+                type: 'string',
+                required: true,
+                description: 'Which quantity is being changed. "available" is the documented value; check the reference before using another.',
+                placeholder: 'available',
+            },
+            {
+                name: 'reason',
+                label: 'Reason',
+                type: 'string',
+                required: true,
+                description: 'Why the stock moved — it lands in the store\'s inventory history. "correction" is the documented value; check the reference before using another.',
+                placeholder: 'correction',
+            },
+            {
+                name: 'referenceDocumentUri',
+                label: 'Reference',
+                type: 'string',
+                description: 'Optional audit-trail link back to whatever caused the change, so someone reading Shopify\'s inventory history can find it.',
+            },
+        ],
+    },
+    findRecords: {
+        label: 'Find orders, customers or products',
+        description: 'Read back what the store knows, to enrich a payload that came from somewhere else.',
+        apiRoute: 'query orders / customers / products (with search syntax)',
+        params: [
+            {
+                name: 'resource',
+                label: 'What to look for',
+                type: 'searchableResource',
+                required: true,
+                description: 'Which collection to search.',
+            },
+            {
+                name: 'query',
+                label: 'Search',
+                type: 'string',
+                required: true,
+                description: 'Shopify search syntax, e.g. email:someone@example.com or financial_status:paid. Empty would return the newest records, which is rarely what anyone means.',
+                placeholder: 'email:{{payload.email}}',
+            },
+            {
+                name: 'first',
+                label: 'How many',
+                type: 'number',
+                description: 'Defaults to 1, which is the enrichment case. Asking for many costs more against the query-cost budget, not more calls.',
+                placeholder: '1',
+            },
+        ],
+    },
+};