@hostwebhook/node-types 1.69.0 → 1.70.0

package/dist/esm/google-analytics-operations.js

@@ -0,0 +1,222 @@
+/**
+ * Google Analytics 4 operation enum — single source of truth across the API,
+ * Dashboard, and Message Broker. Used by:
+ *   - googleAnalyticsAction entity / DTO (api): operation field + validation
+ *   - dashboard GoogleAnalyticsAction operation type
+ *   - MCP toolkit specs, si algún día el nodo gana modo toolkit
+ *
+ * Mismo patrón que `drive-operations.ts` y `sheets-operations.ts`.
+ *
+ * ── Por qué sólo dos operaciones ──
+ *
+ * GA4 tiene más superficie (`runPivotReport`, `batchRunReports`,
+ * `checkCompatibility`), pero declarar una op que el servicio todavía no
+ * implementa la pinta en el desplegable y la deja fallar al ejecutarse: el
+ * enum ES el contrato de la pantalla. Entran cuando entre su código.
+ *
+ * ── Lo que NO es una operación ──
+ *
+ * Listar propiedades y listar las dimensiones/métricas disponibles NO son
+ * ops del nodo: son endpoints del controlador, que es como Drive alimenta su
+ * `DriveFilePicker` (`@Get('files/:credentialId')`). Una op existe para
+ * producir payload en una corrida; esto otro es para rellenar el formulario.
+ *
+ * ── Decisiones propias de GA (anti-n8n) ──
+ *
+ *   - La propiedad se ELIGE de una lista, no se teclea. `properties/123456789`
+ *     y `G-XXXXXXX` se confunden todo el rato y el error de GA no lo aclara.
+ *   - Las fechas admiten `NdaysAgo` / `yesterday` / `today` además de
+ *     `YYYY-MM-DD`, que es lo que acepta la API, y son el sitio donde avisar
+ *     de que el dato no está cerrado hasta pasadas ~48 h.
+ *   - El filtro común (una dimensión, un valor) son tres campos; la
+ *     `FilterExpression` cruda queda de escape en Advanced y gana si está.
+ */
+export const GOOGLE_ANALYTICS_OPERATIONS = [
+    'runReport', // informe estándar sobre un rango de fechas
+    'runRealtimeReport', // los últimos ~30 minutos, sin rango de fechas
+];
+/** Type guard — para validar entrada no fiable (DTOs, tool calls). */
+export function isGoogleAnalyticsOperation(value) {
+    return (typeof value === 'string' &&
+        GOOGLE_ANALYTICS_OPERATIONS.includes(value));
+}
+/* Fábricas de los campos que se repiten, para que un cambio de copy no haya
+   que perseguirlo por las dos operaciones —y por las que vengan. */
+const propertyId = () => ({
+    name: 'propertyId',
+    label: 'GA4 Property',
+    type: 'analyticsProperty',
+    required: true,
+    description: 'Pick a property from the connected account, or paste a templated value like {{payload.propertyId}}. This is the numeric property id (properties/123456789), not the G-XXXXXXX measurement id.',
+});
+const metrics = () => ({
+    name: 'metrics',
+    label: 'Metrics',
+    type: 'analyticsMetrics',
+    required: true,
+    description: 'What to measure — activeUsers, sessions, screenPageViews, conversions. At least one is required.',
+});
+const dimensions = () => ({
+    name: 'dimensions',
+    label: 'Dimensions',
+    type: 'analyticsDimensions',
+    description: 'How to break the metrics down — date, country, pagePath, sessionSource. Leave empty for a single total row.',
+});
+const limit = (max, def) => ({
+    name: 'limit',
+    label: 'Row limit',
+    type: 'number',
+    default: def,
+    min: 1,
+    max,
+    description: `Maximum rows to return. The API caps a single request at ${max.toLocaleString('en-US')}.`,
+});
+/** Los tipos de coincidencia de una `stringFilter` de GA4. */
+const MATCH_TYPE_OPTIONS = [
+    { value: 'EXACT', label: 'is exactly' },
+    { value: 'CONTAINS', label: 'contains' },
+    { value: 'BEGINS_WITH', label: 'begins with' },
+    { value: 'ENDS_WITH', label: 'ends with' },
+    { value: 'FULL_REGEXP', label: 'matches regex' },
+];
+/* El filtro simple: una dimensión, una comparación, un valor. Cubre el caso
+   que pide todo el mundo ("country es Spain") sin obligar a escribir una
+   FilterExpression anidada. Quien necesite más tiene `dimensionFilterJson`. */
+const simpleFilter = () => [
+    {
+        name: 'filterDimension',
+        label: 'Filter by dimension',
+        type: 'analyticsDimensions',
+        description: 'Optional. Restrict the report to rows where this dimension matches the value below.',
+    },
+    {
+        name: 'filterMatchType',
+        label: 'Match',
+        type: 'select',
+        default: 'EXACT',
+        options: MATCH_TYPE_OPTIONS,
+        showWhen: { field: 'filterDimension', in: ['*'] },
+    },
+    {
+        name: 'filterValue',
+        label: 'Value',
+        type: 'template',
+        placeholder: 'Spain',
+        description: 'Templates work — e.g. {{payload.country}}.',
+        showWhen: { field: 'filterDimension', in: ['*'] },
+    },
+];
+const dimensionFilterJson = () => ({
+    name: 'dimensionFilterJson',
+    label: 'Raw dimension filter (FilterExpression JSON)',
+    type: 'json',
+    advanced: true,
+    placeholder: '{"andGroup":{"expressions":[{"filter":{"fieldName":"country","stringFilter":{"value":"Spain"}}}]}}',
+    description: 'Escape hatch for AND / OR / NOT groups the simple filter above cannot express. When set, this WINS and the three simple filter fields are ignored.',
+});
+const orderBy = () => [
+    {
+        name: 'orderByField',
+        label: 'Sort by',
+        type: 'template',
+        advanced: true,
+        placeholder: 'activeUsers',
+        description: 'Metric or dimension name to sort on. Must be one of the metrics or dimensions selected above. Empty = the API default order.',
+    },
+    {
+        name: 'orderByDesc',
+        label: 'Sort direction',
+        type: 'booleanSelect',
+        advanced: true,
+        options: [
+            { value: '', label: '— API default —' },
+            { value: 'true', label: 'Descending (highest first)' },
+            { value: 'false', label: 'Ascending (lowest first)' },
+        ],
+        showWhen: { field: 'orderByField', in: ['*'] },
+    },
+];
+export const GOOGLE_ANALYTICS_OPERATION_SPECS = {
+    runReport: {
+        label: 'Run report',
+        description: 'Metrics over a date range, broken down by dimensions.',
+        apiMethod: 'properties.runReport',
+        params: [
+            propertyId(),
+            metrics(),
+            dimensions(),
+            {
+                name: 'startDate',
+                label: 'Start date',
+                type: 'template',
+                required: true,
+                default: '28daysAgo',
+                description: 'YYYY-MM-DD, or a relative value: today, yesterday, NdaysAgo. Note GA4 keeps refining recent data for up to 48h, so a window ending at "today" can change between two runs.',
+            },
+            {
+                name: 'endDate',
+                label: 'End date',
+                type: 'template',
+                required: true,
+                default: 'today',
+                description: 'Same formats as the start date. Inclusive.',
+            },
+            ...simpleFilter(),
+            limit(250000, 100),
+            {
+                name: 'offset',
+                label: 'Row offset',
+                type: 'number',
+                advanced: true,
+                default: 0,
+                min: 0,
+                description: 'Skip this many rows before returning. Use with the row limit to page through a large report.',
+            },
+            ...orderBy(),
+            dimensionFilterJson(),
+            {
+                name: 'keepEmptyRows',
+                label: 'Keep empty rows',
+                type: 'booleanSelect',
+                advanced: true,
+                options: [
+                    { value: '', label: '— API default (drop them) —' },
+                    { value: 'true', label: 'Keep rows whose metrics are all zero' },
+                    { value: 'false', label: 'Drop rows whose metrics are all zero' },
+                ],
+            },
+        ],
+    },
+    runRealtimeReport: {
+        label: 'Run realtime report',
+        description: 'What is happening right now — the last 30 minutes.',
+        apiMethod: 'properties.runRealtimeReport',
+        params: [
+            propertyId(),
+            metrics(),
+            dimensions(),
+            {
+                name: 'minutesAgo',
+                label: 'Window',
+                type: 'select',
+                default: '29',
+                options: [
+                    { value: '4', label: 'Last 5 minutes' },
+                    { value: '14', label: 'Last 15 minutes' },
+                    { value: '29', label: 'Last 30 minutes' },
+                ],
+                description: 'Realtime has no date range — it always looks back from now, and GA4 caps the lookback at 30 minutes.',
+            },
+            ...simpleFilter(),
+            limit(100000, 100),
+            ...orderBy(),
+            dimensionFilterJson(),
+        ],
+    },
+};
+/**
+ * Las operaciones tal y como se listan en el desplegable. Hoy es el enum
+ * entero; existe para que añadir una op interna (sin fila propia) no obligue
+ * a que la página vuelva a decidir por su cuenta qué enseñar.
+ */
+export const GOOGLE_ANALYTICS_DROPDOWN_OPERATIONS = GOOGLE_ANALYTICS_OPERATIONS;

package/dist/esm/google-contacts-operations.d.ts

@@ -0,0 +1,93 @@
+/**
+ * Google People API operation enum — single source of truth across the
+ * API, Dashboard, and Message Broker. Used by:
+ *   - googleContactsAction entity / DTO (api): operation field + validation
+ *   - dashboard OperationSection
+ *   - broker hostwebhook types + tool schemas
+ *
+ * Two tiers because the action shipped V1 first (read + simple writes)
+ * and V2 second (bulk + group management). Both ship in the same package
+ * version; the api-side DTO gates which tier its accept-list includes.
+ */
+export declare const GOOGLE_CONTACTS_OPERATIONS_V1: readonly ["listContacts", "searchContacts", "getContact", "createContact", "updateContact", "deleteContact", "listContactGroups", "addContactToGroup", "removeContactFromGroup"];
+export declare const GOOGLE_CONTACTS_OPERATIONS_V2: readonly ["batchCreateContacts", "batchUpdateContacts", "batchDeleteContacts", "createContactGroup", "updateContactGroup", "deleteContactGroup"];
+export declare const GOOGLE_CONTACTS_OPERATIONS: readonly ["listContacts", "searchContacts", "getContact", "createContact", "updateContact", "deleteContact", "listContactGroups", "addContactToGroup", "removeContactFromGroup", "batchCreateContacts", "batchUpdateContacts", "batchDeleteContacts", "createContactGroup", "updateContactGroup", "deleteContactGroup"];
+export type GoogleContactsOperation = (typeof GOOGLE_CONTACTS_OPERATIONS)[number];
+export declare function isGoogleContactsOperation(value: unknown): value is GoogleContactsOperation;
+/**
+ * Per-operation form schema, same idea as SLACK_OPERATION_SPECS and
+ * DISCORD_OPERATION_SPECS: the dashboard detail page renders it with one loop
+ * instead of a branch per operation.
+ *
+ * Unlike Slack's, this one drives the **form only**. The AI-toolkit / MCP tool
+ * schema for this node lives apart (dashboard
+ * `google-contacts-operations-schemas.ts`, api `mcp-servers/toolkit-specs.ts`),
+ * which is why `description` is optional here — a handful of fields have never
+ * shown help text and inventing copy for them is not this change's job.
+ */
+export interface GoogleContactsParamSpec {
+    /** Field key — also the property name on operationConfig / payload. */
+    name: string;
+    /** UI label, shown as the section title. Carries any "(optional)" suffix. */
+    label: string;
+    /**
+     * Param type for form rendering.
+     *
+     * `string`, `text`, `number` and `boolean` mean the same as in
+     * SlackParamSpec. The rest are this node's own:
+     *   - `csvList` — stored as a string **array**, edited as comma-separated
+     *     text. Losing the array on save breaks the node at run time, so the
+     *     renderer must join on the way in and split on the way out.
+     *   - `json`   — stored parsed when the text is valid JSON, and as the raw
+     *     string when it is not, so a half-typed array survives a keystroke.
+     *   - `plain`  — a bare input, no templating. Same control Discord calls
+     *     `emoji`, a name inherited from Slack that fits neither field here.
+     *     Unifying the two is a coordinated rename, so for now both exist.
+     */
+    type: 'string' | 'text' | 'plain' | 'csvList' | 'json' | 'number' | 'boolean';
+    /** Required by the People API. Metadata — the form does not gate on it. */
+    required?: boolean;
+    /** Help text under the input. Absent where the form has never shown any. */
+    description?: string;
+    /** Hint shown inside the input. */
+    placeholder?: string;
+    /** Value to show when the stored one is undefined. */
+    default?: string | number | boolean;
+    /** `number` only — and enforced on change, not just by the input. */
+    min?: number;
+    max?: number;
+    /** `text` / `json` only — height of the textarea. */
+    rows?: number;
+    /** `boolean` only — the line beside the switch. */
+    switchLabel?: string;
+}
+/** Group headings of the operation dropdown, in display order. */
+export declare const GOOGLE_CONTACTS_OPERATION_GROUPS: readonly ["Read", "Write", "Groups", "Bulk", "Group management"];
+export type GoogleContactsOperationGroup = (typeof GOOGLE_CONTACTS_OPERATION_GROUPS)[number];
+export interface GoogleContactsOperationSpec {
+    /** UI label for the operation picker. */
+    label: string;
+    /** Line under the picker, and the picker's own description. */
+    description: string;
+    /** googleapis call the operation maps to (people v1). */
+    apiMethod: string;
+    /** Which half of the OAuth scope the operation needs. */
+    scope: 'read' | 'write';
+    /** Group heading it sits under in the dropdown. */
+    group: GoogleContactsOperationGroup;
+    /** Parameter schema. Order matters for form rendering. */
+    params: GoogleContactsParamSpec[];
+}
+/**
+ * personFields the read operations request when nobody overrides them. Lived in
+ * the dashboard page until this schema landed; it belongs next to the field
+ * that defaults to it.
+ */
+export declare const GOOGLE_CONTACTS_DEFAULT_PERSON_FIELDS = "names,emailAddresses,phoneNumbers,addresses,organizations,memberships";
+/**
+ * Key order below is the dropdown order **within each group** — most-common
+ * operation first, which is why Read starts at searchContacts and not at the
+ * enum's listContacts. The dashboard groups these entries by `group` and keeps
+ * this order, so moving a key moves the dropdown.
+ */
+export declare const GOOGLE_CONTACTS_OPERATION_SPECS: Record<GoogleContactsOperation, GoogleContactsOperationSpec>;

package/dist/esm/google-contacts-operations.js

@@ -0,0 +1,363 @@
+/**
+ * Google People API operation enum — single source of truth across the
+ * API, Dashboard, and Message Broker. Used by:
+ *   - googleContactsAction entity / DTO (api): operation field + validation
+ *   - dashboard OperationSection
+ *   - broker hostwebhook types + tool schemas
+ *
+ * Two tiers because the action shipped V1 first (read + simple writes)
+ * and V2 second (bulk + group management). Both ship in the same package
+ * version; the api-side DTO gates which tier its accept-list includes.
+ */
+export const GOOGLE_CONTACTS_OPERATIONS_V1 = [
+    'listContacts',
+    'searchContacts',
+    'getContact',
+    'createContact',
+    'updateContact',
+    'deleteContact',
+    'listContactGroups',
+    'addContactToGroup',
+    'removeContactFromGroup',
+];
+export const GOOGLE_CONTACTS_OPERATIONS_V2 = [
+    'batchCreateContacts',
+    'batchUpdateContacts',
+    'batchDeleteContacts',
+    'createContactGroup',
+    'updateContactGroup',
+    'deleteContactGroup',
+];
+export const GOOGLE_CONTACTS_OPERATIONS = [
+    ...GOOGLE_CONTACTS_OPERATIONS_V1,
+    ...GOOGLE_CONTACTS_OPERATIONS_V2,
+];
+export function isGoogleContactsOperation(value) {
+    return (typeof value === 'string' &&
+        GOOGLE_CONTACTS_OPERATIONS.includes(value));
+}
+/** Group headings of the operation dropdown, in display order. */
+export const GOOGLE_CONTACTS_OPERATION_GROUPS = [
+    'Read',
+    'Write',
+    'Groups',
+    'Bulk',
+    'Group management',
+];
+/**
+ * personFields the read operations request when nobody overrides them. Lived in
+ * the dashboard page until this schema landed; it belongs next to the field
+ * that defaults to it.
+ */
+export const GOOGLE_CONTACTS_DEFAULT_PERSON_FIELDS = 'names,emailAddresses,phoneNumbers,addresses,organizations,memberships';
+/* Fields several operations share. Each takes overrides because the same key
+   can mean different things: `resourceName` is a contact in five operations
+   and a contact group in two. */
+const contactResourceName = (over = {}) => ({
+    name: 'resourceName',
+    label: 'Contact resourceName',
+    type: 'string',
+    required: true,
+    placeholder: 'people/c12345 OR {{payload.resourceName}}',
+    description: 'The People API id of the contact (e.g. people/c123456789012345). Search or list a contact upstream to discover it, then pass it through.',
+    ...over,
+});
+/** The **group** under its own key, for the two group-management operations. */
+const groupResourceNameAsResourceName = (over = {}) => ({
+    name: 'resourceName',
+    label: 'Group resourceName',
+    type: 'string',
+    required: true,
+    placeholder: 'contactGroups/12345',
+    ...over,
+});
+/** The group alongside a contact, so it needs its own key. */
+const groupResourceName = (over = {}) => ({
+    name: 'groupResourceName',
+    label: 'Group resourceName',
+    type: 'string',
+    required: true,
+    placeholder: 'contactGroups/12345 OR {{payload.groupId}}',
+    description: "The contactGroup's resourceName. Use listContactGroups upstream to discover it, or hardcode if you always target the same group.",
+    ...over,
+});
+const pageSize = () => ({
+    name: 'pageSize',
+    label: 'Page size',
+    type: 'number',
+    default: 100,
+    min: 1,
+    max: 1000,
+    description: 'How many results per page. Use a Loop node downstream to paginate further with `nextPageToken`.',
+});
+/* Shown last on the three read operations, pre-filled with the default rather
+   than merely placeholder-hinted — that is how it has always looked. */
+const personFields = () => ({
+    name: 'personFields',
+    label: 'Person fields (advanced, optional)',
+    type: 'plain',
+    default: GOOGLE_CONTACTS_DEFAULT_PERSON_FIELDS,
+    placeholder: GOOGLE_CONTACTS_DEFAULT_PERSON_FIELDS,
+    description: 'Comma-separated People API fields to include in the response. Default covers the 95% of cases — only change when you need photos, biographies, or to slim the payload.',
+});
+/** The contact body, identical on create and update. */
+const contactBody = () => [
+    {
+        name: 'fullName',
+        label: 'Full name',
+        type: 'string',
+        placeholder: '{{payload.name}} OR Ariel Pérez',
+        description: 'Auto-splits into given + family name. Override with the separate fields below if the heuristic mangles compound surnames.',
+    },
+    {
+        name: 'givenName',
+        label: 'Given name (optional)',
+        type: 'string',
+        placeholder: '{{payload.firstName}}',
+    },
+    {
+        name: 'familyName',
+        label: 'Family name (optional)',
+        type: 'string',
+        placeholder: '{{payload.lastName}}',
+    },
+    {
+        name: 'emailAddresses',
+        label: 'Email addresses (comma-separated)',
+        type: 'csvList',
+        placeholder: '{{payload.email}}',
+    },
+    {
+        name: 'phoneNumbers',
+        label: 'Phone numbers (comma-separated)',
+        type: 'csvList',
+        placeholder: '{{payload.phone}}',
+    },
+    {
+        name: 'notes',
+        label: 'Notes (optional)',
+        type: 'text',
+        rows: 3,
+        placeholder: 'VIP customer · {{payload.context}}',
+    },
+];
+const BATCH_CONTACTS_TEMPLATING = 'Templating works inside string values ({{payload.x}}).';
+/**
+ * Key order below is the dropdown order **within each group** — most-common
+ * operation first, which is why Read starts at searchContacts and not at the
+ * enum's listContacts. The dashboard groups these entries by `group` and keeps
+ * this order, so moving a key moves the dropdown.
+ */
+export const GOOGLE_CONTACTS_OPERATION_SPECS = {
+    // ── Read ───────────────────────────────────────────────────────────
+    searchContacts: {
+        label: 'Search contacts',
+        description: 'Free-text search by name, email, phone, or organization.',
+        apiMethod: 'people.searchContacts',
+        scope: 'read',
+        group: 'Read',
+        params: [
+            {
+                name: 'query',
+                label: 'Query',
+                type: 'string',
+                required: true,
+                placeholder: '{{payload.email}} OR Ariel OR @company.com',
+                description: 'Free-text. Matches against names, email addresses, phone numbers, and organizations.',
+            },
+            personFields(),
+        ],
+    },
+    listContacts: {
+        label: 'List contacts',
+        description: "Paginated list of every contact in the user's address book.",
+        apiMethod: 'people.connections.list',
+        scope: 'read',
+        group: 'Read',
+        params: [pageSize(), personFields()],
+    },
+    getContact: {
+        label: 'Get contact',
+        description: 'Fetch a single contact by its resourceName (e.g. people/c12345).',
+        apiMethod: 'people.get',
+        scope: 'read',
+        group: 'Read',
+        params: [contactResourceName(), personFields()],
+    },
+    // ── Write ──────────────────────────────────────────────────────────
+    createContact: {
+        label: 'Create contact',
+        description: 'Add a new contact. Pass fullName for auto split into given/family.',
+        apiMethod: 'people.createContact',
+        scope: 'write',
+        group: 'Write',
+        params: contactBody(),
+    },
+    updateContact: {
+        label: 'Update contact',
+        description: 'Update fields on an existing contact. Update mask is auto-derived.',
+        apiMethod: 'people.updateContact',
+        scope: 'write',
+        group: 'Write',
+        params: [contactResourceName(), ...contactBody()],
+    },
+    deleteContact: {
+        label: 'Delete contact',
+        description: 'Remove a contact by resourceName. Irreversible.',
+        apiMethod: 'people.deleteContact',
+        scope: 'write',
+        group: 'Write',
+        params: [contactResourceName()],
+    },
+    // ── Groups ─────────────────────────────────────────────────────────
+    listContactGroups: {
+        label: 'List groups',
+        description: 'List all contact groups (labels) the user has.',
+        apiMethod: 'contactGroups.list',
+        scope: 'read',
+        group: 'Groups',
+        params: [pageSize()],
+    },
+    addContactToGroup: {
+        label: 'Add to group',
+        description: 'Idempotent — no error if the contact is already in the group.',
+        apiMethod: 'contactGroups.members.modify',
+        scope: 'write',
+        group: 'Groups',
+        params: [contactResourceName(), groupResourceName()],
+    },
+    removeContactFromGroup: {
+        label: 'Remove from group',
+        description: "Idempotent — no error if the contact wasn't in the group.",
+        apiMethod: 'contactGroups.members.modify',
+        scope: 'write',
+        group: 'Groups',
+        params: [contactResourceName(), groupResourceName()],
+    },
+    // ── Bulk ───────────────────────────────────────────────────────────
+    batchCreateContacts: {
+        label: 'Batch create',
+        description: 'Bulk-create up to 200 contacts in one call. Pass a `contacts` array.',
+        apiMethod: 'people.batchCreateContacts',
+        scope: 'write',
+        group: 'Bulk',
+        params: [
+            {
+                name: 'contacts',
+                label: 'Contacts (JSON array)',
+                type: 'json',
+                required: true,
+                rows: 10,
+                placeholder: `[
+  { "fullName": "Ariel Pérez", "emailAddresses": ["a@b.c"] },
+  { "fullName": "Bob Smith", "phoneNumbers": ["+15551234"] }
+]`,
+                description: `Up to 200 contacts per call. Each entry uses the same shape as createContact (fullName / emailAddresses / phoneNumbers / notes). ${BATCH_CONTACTS_TEMPLATING}`,
+            },
+        ],
+    },
+    batchUpdateContacts: {
+        label: 'Batch update',
+        description: 'Bulk-update up to 200 contacts. Each entry needs a resourceName.',
+        apiMethod: 'people.batchUpdateContacts',
+        scope: 'write',
+        group: 'Bulk',
+        params: [
+            {
+                name: 'contacts',
+                label: 'Contacts (JSON array)',
+                type: 'json',
+                required: true,
+                rows: 10,
+                placeholder: `[
+  { "resourceName": "people/c12345", "fullName": "New Name" }
+]`,
+                description: `Up to 200 contacts per call. Each entry uses the same shape as updateContact — must include \`resourceName\`. ${BATCH_CONTACTS_TEMPLATING}`,
+            },
+            {
+                name: 'updateMask',
+                label: 'Update mask',
+                type: 'plain',
+                required: true,
+                placeholder: 'names,emailAddresses',
+                description: 'Comma-separated People API field paths that the bulk update is allowed to replace. Required.',
+            },
+        ],
+    },
+    batchDeleteContacts: {
+        label: 'Batch delete',
+        description: 'Bulk-delete up to 500 contacts by resourceName. Irreversible.',
+        apiMethod: 'people.batchDeleteContacts',
+        scope: 'write',
+        group: 'Bulk',
+        params: [
+            {
+                name: 'resourceNames',
+                label: 'Resource names (JSON array)',
+                type: 'json',
+                required: true,
+                rows: 6,
+                placeholder: `[
+  "people/c12345",
+  "people/c67890"
+]`,
+                description: 'Up to 500 resourceNames per call. Irreversible.',
+            },
+        ],
+    },
+    // ── Group management ───────────────────────────────────────────────
+    createContactGroup: {
+        label: 'Create group',
+        description: 'Create a new contact group (label).',
+        apiMethod: 'contactGroups.create',
+        scope: 'write',
+        group: 'Group management',
+        params: [
+            {
+                name: 'name',
+                label: 'Group name',
+                type: 'string',
+                required: true,
+                placeholder: '{{payload.groupName}} OR Customers',
+                description: 'Display name for the new group.',
+            },
+        ],
+    },
+    updateContactGroup: {
+        label: 'Rename group',
+        description: 'Rename an existing group.',
+        apiMethod: 'contactGroups.update',
+        scope: 'write',
+        group: 'Group management',
+        /* Name before resourceName: odd, but it is the order the page has always
+           rendered, and reordering is a separate decision. */
+        params: [
+            {
+                name: 'name',
+                label: 'Group name',
+                type: 'string',
+                required: true,
+                placeholder: '{{payload.groupName}} OR Customers',
+                description: 'New display name (renames the existing group).',
+            },
+            groupResourceNameAsResourceName(),
+        ],
+    },
+    deleteContactGroup: {
+        label: 'Delete group',
+        description: 'Delete a group. Optionally delete its contacts too.',
+        apiMethod: 'contactGroups.delete',
+        scope: 'write',
+        group: 'Group management',
+        params: [
+            groupResourceNameAsResourceName(),
+            {
+                name: 'deleteContacts',
+                label: 'Also delete contacts in the group?',
+                type: 'boolean',
+                switchLabel: 'Delete the contacts that are members of this group too.',
+                description: 'Off (default) — contacts stay, just lose this group membership. On — every contact in the group is also deleted. Irreversible.',
+            },
+        ],
+    },
+};