fix(convex): separate List Documents page cursor from deltas cursor and surface HTTP errors in transforms

Author: waleedlatif1

apps/sim/blocks/blocks/convex.ts

@@ -105,7 +105,7 @@ Return ONLY the JSON object - no explanations, no markdown, no extra text.`,
       condition: { field: 'operation', value: 'list_documents' },
     },
     {
-      id: 'cursor',
+      id: 'pageCursor',
       title: 'Cursor',
       type: 'short-input',
       mode: 'advanced',
@@ -144,6 +144,15 @@ Return ONLY the JSON object - no explanations, no markdown, no extra text.`,
             throw new Error(`Invalid Convex operation: ${params.operation}`)
         }
       },
+      params: (params) => {
+        const { pageCursor, ...rest } = params
+
+        if (params.operation === 'list_documents') {
+          rest.cursor = pageCursor
+        }
+
+        return rest
+      },
     },
   },
   inputs: {
@@ -153,8 +162,9 @@ Return ONLY the JSON object - no explanations, no markdown, no extra text.`,
     functionPath: { type: 'string', description: 'Function path (e.g., messages:list)' },
     args: { type: 'json', description: 'Named arguments for the function' },
     tableName: { type: 'string', description: 'Table to read from (empty for all tables)' },
-    snapshot: { type: 'string', description: 'Snapshot timestamp for pagination' },
-    cursor: { type: 'string', description: 'Pagination cursor' },
+    snapshot: { type: 'string', description: 'Snapshot timestamp for List Documents pagination' },
+    cursor: { type: 'string', description: 'Timestamp cursor for Document Deltas' },
+    pageCursor: { type: 'string', description: 'Pagination cursor for List Documents' },
   },
   outputs: {
     value: {

apps/sim/tools/convex/document_deltas.ts

@@ -1,5 +1,9 @@
-import type { ConvexDocumentDeltasParams, ConvexDocumentDeltasResponse } from '@/tools/convex/types'
-import { convexApiUrl, convexAuthHeaders } from '@/tools/convex/utils'
+import type {
+  ConvexDocumentDeltasApiResponse,
+  ConvexDocumentDeltasParams,
+  ConvexDocumentDeltasResponse,
+} from '@/tools/convex/types'
+import { convexApiUrl, convexAuthHeaders, parseConvexResponse } from '@/tools/convex/utils'
 import type { ToolConfig } from '@/tools/types'
 
 export const documentDeltasTool: ToolConfig<
@@ -57,7 +61,7 @@ export const documentDeltasTool: ToolConfig<
   },
 
   transformResponse: async (response: Response) => {
-    const data = await response.json()
+    const data = (await parseConvexResponse(response)) as ConvexDocumentDeltasApiResponse
 
     return {
       success: true,

apps/sim/tools/convex/list_documents.ts

@@ -1,5 +1,9 @@
-import type { ConvexListDocumentsParams, ConvexListDocumentsResponse } from '@/tools/convex/types'
-import { convexApiUrl, convexAuthHeaders } from '@/tools/convex/utils'
+import type {
+  ConvexListDocumentsParams,
+  ConvexListDocumentsResponse,
+  ConvexListSnapshotApiResponse,
+} from '@/tools/convex/types'
+import { convexApiUrl, convexAuthHeaders, parseConvexResponse } from '@/tools/convex/utils'
 import type { ToolConfig } from '@/tools/types'
 
 export const listDocumentsTool: ToolConfig<ConvexListDocumentsParams, ConvexListDocumentsResponse> =
@@ -59,7 +63,7 @@ export const listDocumentsTool: ToolConfig<ConvexListDocumentsParams, ConvexList
     },
 
     transformResponse: async (response: Response) => {
-      const data = await response.json()
+      const data = (await parseConvexResponse(response)) as ConvexListSnapshotApiResponse
 
       return {
         success: true,

apps/sim/tools/convex/list_tables.ts

@@ -1,5 +1,5 @@
 import type { ConvexListTablesParams, ConvexListTablesResponse } from '@/tools/convex/types'
-import { convexApiUrl, convexAuthHeaders } from '@/tools/convex/utils'
+import { convexApiUrl, convexAuthHeaders, parseConvexResponse } from '@/tools/convex/utils'
 import type { ToolConfig } from '@/tools/types'
 
 export const listTablesTool: ToolConfig<ConvexListTablesParams, ConvexListTablesResponse> = {
@@ -30,7 +30,7 @@ export const listTablesTool: ToolConfig<ConvexListTablesParams, ConvexListTables
   },
 
   transformResponse: async (response: Response) => {
-    const data = await response.json()
+    const data = await parseConvexResponse(response)
     const schemas =
       data !== null && typeof data === 'object' && !Array.isArray(data)
         ? (data as Record<string, unknown>)

apps/sim/tools/convex/types.ts

@@ -60,6 +60,34 @@ export interface ConvexDocumentDeltasResponse extends ToolResponse {
   }
 }
 
+/**
+ * Raw wire shape of Convex function-call responses (`/api/query`, `/api/mutation`,
+ * `/api/action`, `/api/run/{identifier}`).
+ * @see https://docs.convex.dev/http-api/#post-apiquery-apimutation-apiaction
+ */
+export interface ConvexFunctionCallApiResponse {
+  status?: 'success' | 'error'
+  value?: unknown
+  logLines?: string[]
+  errorMessage?: string
+  errorData?: unknown
+}
+
+/** Raw wire shape of `/api/list_snapshot` responses. */
+export interface ConvexListSnapshotApiResponse {
+  values?: unknown[]
+  hasMore?: boolean
+  snapshot?: number | string | null
+  cursor?: number | string | null
+}
+
+/** Raw wire shape of `/api/document_deltas` responses. */
+export interface ConvexDocumentDeltasApiResponse {
+  values?: unknown[]
+  hasMore?: boolean
+  cursor?: number | string | null
+}
+
 export interface ConvexResponse extends ToolResponse {
   output: {
     value?: unknown

apps/sim/tools/convex/utils.ts

@@ -1,4 +1,8 @@
-import type { ConvexFunctionCallResponse } from '@/tools/convex/types'
+import { truncate } from '@sim/utils/string'
+import type {
+  ConvexFunctionCallApiResponse,
+  ConvexFunctionCallResponse,
+} from '@/tools/convex/types'
 
 /**
  * Builds a Convex deployment API URL from the user-provided deployment URL.
@@ -47,6 +51,20 @@ export function parseFunctionArgs(
   return args
 }
 
+/**
+ * Parses a Convex API response body, surfacing non-OK HTTP statuses (e.g. 401
+ * from an invalid deploy key) as descriptive errors instead of empty results.
+ */
+export async function parseConvexResponse(response: Response): Promise<unknown> {
+  if (!response.ok) {
+    const text = await response.text().catch(() => '')
+    throw new Error(
+      `Convex request failed (HTTP ${response.status})${text ? `: ${truncate(text.trim(), 300)}` : ''}`
+    )
+  }
+  return response.json()
+}
+
 /**
  * Transforms a Convex function-call response. Convex returns HTTP 200 with an
  * in-band `status: "error"` payload when the function itself fails, so errors
@@ -57,7 +75,7 @@ export async function transformFunctionCallResponse(
   response: Response,
   functionType: 'query' | 'mutation' | 'action' | 'function'
 ): Promise<ConvexFunctionCallResponse> {
-  const data = await response.json()
+  const data = (await parseConvexResponse(response)) as ConvexFunctionCallApiResponse
 
   if (data.status === 'error') {
     const details =