feat(hex): expand API coverage, fix ID trimming, add cursor pagination (#5372)

* feat(hex): expand API coverage, fix ID trimming, add cursor pagination

- Add hex_update_collection, hex_create_group, hex_update_group,
  hex_delete_group, hex_deactivate_user tools + block wiring
- Add missing run_project fields (viewId, notifications) and
  get_project_runs runTriggerFilter
- Add after/before cursor pagination to list_projects, list_groups,
  list_data_connections, list_collections
- Add .trim() on all interpolated ID path params to guard against
  copy-paste whitespace

* fix(hex): guard JSON.parse on user-supplied array/object params

Wrap JSON.parse calls for memberUserIds, addUserIds, removeUserIds,
inputParams, and notifications in try/catch so malformed input throws
a clear error instead of an opaque parse exception.

* fix(hex): forward empty collection description on update

update_collection's params() mapping only copied collectionDescription
when truthy, so clearing it to an empty string in the UI never reached
the API. Untouched fields resolve to null (not undefined), so use a
loose null check to distinguish "cleared" from "never touched" without
sending description: null on every unrelated update.

* fix(hex): close remaining API coverage gaps found via raw OpenAPI spec

Pulled Hex's actual OpenAPI spec (static.hex.site/openapi.json) as
ground truth for a final verification pass:

- list_users was missing after/before cursor pagination and the
  userIds filter, which the spec confirms it supports (an earlier
  doc-summary pass had incorrectly flagged this as unverifiable)
- list_users response also exposes lastLoginDate per user, not
  previously surfaced
- list_projects was missing includeComponents, includeTrashed,
  creatorEmail, ownerEmail, collectionId, categories, sortBy, and
  sortDirection filters that the spec confirms are real query params

* fix(hex): trim remaining user-suppliable IDs for consistency

Trim collectionId (list_projects filter), viewId (run_project body),
and group member UUIDs (create_group/update_group) to match the
.trim() convention already applied to path-segment IDs elsewhere.

* fix(hex): validate parsed JSON is actually an array before iterating

categories, memberUserIds, addUserIds, and removeUserIds could parse
as valid JSON that isn't an array (e.g. an object), which would throw
an opaque "not iterable"/"map is not a function" error deeper in the
call. Validate Array.isArray after parsing and fail with a clear
message instead.

* fix(hex): validate array element types, send explicit ALL trigger filter

- notifications now gets the same Array.isArray guard already applied
  to categories/memberUserIds/addUserIds/removeUserIds
- member/category array elements are now validated as strings before
  .trim()/append, instead of crashing on non-string entries
- runTriggerFilter "All" option now sends the documented ALL enum
  value explicitly instead of relying on omission

Author: waleedlatif1

apps/sim/blocks/blocks/hex.ts

@@ -30,7 +30,7 @@ export const cancelRunTool: ToolConfig<HexCancelRunParams, HexCancelRunResponse>
 
   request: {
     url: (params) =>
-      `https://app.hex.tech/api/v1/projects/${params.projectId}/runs/${params.runId}`,
+      `https://app.hex.tech/api/v1/projects/${params.projectId.trim()}/runs/${params.runId.trim()}`,
     method: 'DELETE',
     headers: (params) => ({
       Authorization: `Bearer ${params.apiKey}`,

apps/sim/tools/hex/cancel_run.ts

@@ -0,0 +1,78 @@
+import type { HexCreateGroupParams, HexCreateGroupResponse } from '@/tools/hex/types'
+import type { ToolConfig } from '@/tools/types'
+
+export const createGroupTool: ToolConfig<HexCreateGroupParams, HexCreateGroupResponse> = {
+  id: 'hex_create_group',
+  name: 'Hex Create Group',
+  description: 'Create a new group in the Hex workspace, optionally with initial members.',
+  version: '1.0.0',
+
+  params: {
+    apiKey: {
+      type: 'string',
+      required: true,
+      visibility: 'user-only',
+      description: 'Hex API token (Personal or Workspace)',
+    },
+    name: {
+      type: 'string',
+      required: true,
+      visibility: 'user-or-llm',
+      description: 'Name for the new group',
+    },
+    memberUserIds: {
+      type: 'json',
+      required: false,
+      visibility: 'user-or-llm',
+      description:
+        'JSON array of user UUIDs to add as initial group members (e.g., ["uuid1", "uuid2"])',
+    },
+  },
+
+  request: {
+    url: 'https://app.hex.tech/api/v1/groups',
+    method: 'POST',
+    headers: (params) => ({
+      Authorization: `Bearer ${params.apiKey}`,
+      'Content-Type': 'application/json',
+    }),
+    body: (params) => {
+      const body: Record<string, unknown> = { name: params.name }
+      if (params.memberUserIds) {
+        let userIds: unknown
+        try {
+          userIds =
+            typeof params.memberUserIds === 'string'
+              ? JSON.parse(params.memberUserIds)
+              : params.memberUserIds
+        } catch {
+          throw new Error('memberUserIds must be a valid JSON array of user UUID strings')
+        }
+        if (!Array.isArray(userIds) || !userIds.every((id) => typeof id === 'string')) {
+          throw new Error('memberUserIds must be a valid JSON array of user UUID strings')
+        }
+        body.members = { users: userIds.map((id: string) => ({ id: id.trim() })) }
+      }
+      return body
+    },
+  },
+
+  transformResponse: async (response: Response) => {
+    const data = await response.json()
+
+    return {
+      success: true,
+      output: {
+        id: data.id ?? null,
+        name: data.name ?? null,
+        createdAt: data.createdAt ?? null,
+      },
+    }
+  },
+
+  outputs: {
+    id: { type: 'string', description: 'Newly created group UUID' },
+    name: { type: 'string', description: 'Group name' },
+    createdAt: { type: 'string', description: 'Creation timestamp' },
+  },
+}

apps/sim/tools/hex/create_group.ts

@@ -0,0 +1,60 @@
+import type { HexDeactivateUserParams, HexDeactivateUserResponse } from '@/tools/hex/types'
+import type { ToolConfig } from '@/tools/types'
+
+export const deactivateUserTool: ToolConfig<HexDeactivateUserParams, HexDeactivateUserResponse> = {
+  id: 'hex_deactivate_user',
+  name: 'Hex Deactivate User',
+  description: 'Deactivate a user in the Hex workspace.',
+  version: '1.0.0',
+
+  params: {
+    apiKey: {
+      type: 'string',
+      required: true,
+      visibility: 'user-only',
+      description: 'Hex API token (Personal or Workspace)',
+    },
+    userId: {
+      type: 'string',
+      required: true,
+      visibility: 'user-or-llm',
+      description: 'The UUID of the user to deactivate',
+    },
+  },
+
+  request: {
+    url: (params) => `https://app.hex.tech/api/v1/users/${params.userId.trim()}/deactivate`,
+    method: 'POST',
+    headers: (params) => ({
+      Authorization: `Bearer ${params.apiKey}`,
+      'Content-Type': 'application/json',
+    }),
+  },
+
+  transformResponse: async (response: Response, params) => {
+    if (response.status === 204 || response.ok) {
+      return {
+        success: true,
+        output: {
+          success: true,
+          userId: params?.userId ?? '',
+        },
+      }
+    }
+
+    const data = await response.json().catch(() => ({}))
+    return {
+      success: false,
+      output: {
+        success: false,
+        userId: params?.userId ?? '',
+      },
+      error: (data as Record<string, string>).message ?? 'Failed to deactivate user',
+    }
+  },
+
+  outputs: {
+    success: { type: 'boolean', description: 'Whether the user was successfully deactivated' },
+    userId: { type: 'string', description: 'User UUID that was deactivated' },
+  },
+}

apps/sim/tools/hex/deactivate_user.ts

@@ -0,0 +1,60 @@
+import type { HexDeleteGroupParams, HexDeleteGroupResponse } from '@/tools/hex/types'
+import type { ToolConfig } from '@/tools/types'
+
+export const deleteGroupTool: ToolConfig<HexDeleteGroupParams, HexDeleteGroupResponse> = {
+  id: 'hex_delete_group',
+  name: 'Hex Delete Group',
+  description: 'Delete a group from the Hex workspace.',
+  version: '1.0.0',
+
+  params: {
+    apiKey: {
+      type: 'string',
+      required: true,
+      visibility: 'user-only',
+      description: 'Hex API token (Personal or Workspace)',
+    },
+    groupId: {
+      type: 'string',
+      required: true,
+      visibility: 'user-or-llm',
+      description: 'The UUID of the group to delete',
+    },
+  },
+
+  request: {
+    url: (params) => `https://app.hex.tech/api/v1/groups/${params.groupId.trim()}`,
+    method: 'DELETE',
+    headers: (params) => ({
+      Authorization: `Bearer ${params.apiKey}`,
+      'Content-Type': 'application/json',
+    }),
+  },
+
+  transformResponse: async (response: Response, params) => {
+    if (response.status === 204 || response.ok) {
+      return {
+        success: true,
+        output: {
+          success: true,
+          groupId: params?.groupId ?? '',
+        },
+      }
+    }
+
+    const data = await response.json().catch(() => ({}))
+    return {
+      success: false,
+      output: {
+        success: false,
+        groupId: params?.groupId ?? '',
+      },
+      error: (data as Record<string, string>).message ?? 'Failed to delete group',
+    }
+  },
+
+  outputs: {
+    success: { type: 'boolean', description: 'Whether the group was successfully deleted' },
+    groupId: { type: 'string', description: 'Group UUID that was deleted' },
+  },
+}

apps/sim/tools/hex/delete_group.ts

@@ -23,7 +23,7 @@ export const getCollectionTool: ToolConfig<HexGetCollectionParams, HexGetCollect
   },
 
   request: {
-    url: (params) => `https://app.hex.tech/api/v1/collections/${params.collectionId}`,
+    url: (params) => `https://app.hex.tech/api/v1/collections/${params.collectionId.trim()}`,
     method: 'GET',
     headers: (params) => ({
       Authorization: `Bearer ${params.apiKey}`,

apps/sim/tools/hex/get_collection.ts

@@ -27,7 +27,8 @@ export const getDataConnectionTool: ToolConfig<
   },
 
   request: {
-    url: (params) => `https://app.hex.tech/api/v1/data-connections/${params.dataConnectionId}`,
+    url: (params) =>
+      `https://app.hex.tech/api/v1/data-connections/${params.dataConnectionId.trim()}`,
     method: 'GET',
     headers: (params) => ({
       Authorization: `Bearer ${params.apiKey}`,

apps/sim/tools/hex/get_data_connection.ts

@@ -23,7 +23,7 @@ export const getGroupTool: ToolConfig<HexGetGroupParams, HexGetGroupResponse> =
   },
 
   request: {
-    url: (params) => `https://app.hex.tech/api/v1/groups/${params.groupId}`,
+    url: (params) => `https://app.hex.tech/api/v1/groups/${params.groupId.trim()}`,
     method: 'GET',
     headers: (params) => ({
       Authorization: `Bearer ${params.apiKey}`,

apps/sim/tools/hex/get_group.ts

@@ -24,7 +24,7 @@ export const getProjectTool: ToolConfig<HexGetProjectParams, HexGetProjectRespon
   },
 
   request: {
-    url: (params) => `https://app.hex.tech/api/v1/projects/${params.projectId}`,
+    url: (params) => `https://app.hex.tech/api/v1/projects/${params.projectId.trim()}`,
     method: 'GET',
     headers: (params) => ({
       Authorization: `Bearer ${params.apiKey}`,

apps/sim/tools/hex/get_project.ts

@@ -40,6 +40,12 @@ export const getProjectRunsTool: ToolConfig<HexGetProjectRunsParams, HexGetProje
       description:
         'Filter by run status: PENDING, RUNNING, ERRORED, COMPLETED, KILLED, UNABLE_TO_ALLOCATE_KERNEL',
     },
+    runTriggerFilter: {
+      type: 'string',
+      required: false,
+      visibility: 'user-or-llm',
+      description: 'Filter by how the run was triggered: ALL, API, SCHEDULED, or APP_REFRESH',
+    },
   },
 
   request: {
@@ -48,8 +54,9 @@ export const getProjectRunsTool: ToolConfig<HexGetProjectRunsParams, HexGetProje
       if (params.limit) searchParams.set('limit', String(params.limit))
       if (params.offset) searchParams.set('offset', String(params.offset))
       if (params.statusFilter) searchParams.set('statusFilter', params.statusFilter)
+      if (params.runTriggerFilter) searchParams.set('runTriggerFilter', params.runTriggerFilter)
       const qs = searchParams.toString()
-      return `https://app.hex.tech/api/v1/projects/${params.projectId}/runs${qs ? `?${qs}` : ''}`
+      return `https://app.hex.tech/api/v1/projects/${params.projectId.trim()}/runs${qs ? `?${qs}` : ''}`
     },
     method: 'GET',
     headers: (params) => ({
@@ -78,6 +85,8 @@ export const getProjectRunsTool: ToolConfig<HexGetProjectRunsParams, HexGetProje
         })),
         total: runs.length,
         traceId: data.traceId ?? null,
+        nextPage: data.nextPage ?? null,
+        previousPage: data.previousPage ?? null,
       },
     }
   },
@@ -111,5 +120,11 @@ export const getProjectRunsTool: ToolConfig<HexGetProjectRunsParams, HexGetProje
     },
     total: { type: 'number', description: 'Total number of runs returned' },
     traceId: { type: 'string', description: 'Top-level trace ID', optional: true },
+    nextPage: { type: 'string', description: 'Cursor for the next page of runs', optional: true },
+    previousPage: {
+      type: 'string',
+      description: 'Cursor for the previous page of runs',
+      optional: true,
+    },
   },
 }