fix(quartr): address review findings — null-safe query building, string boolean toggles, accurate descriptions, NestJS validation error extractor

Author: waleedlatif1

apps/docs/content/docs/en/integrations/quartr.mdx

@@ -55,7 +55,7 @@ List companies covered by Quartr, filterable by ticker, ISIN, CIK, OpenFIGI, cou
 | `openfigis` | string | No | Comma-separated list of OpenFIGI codes \(figi, compositeFigi, or shareClassFigi\) |
 | `updatedAfter` | string | No | Only return data updated after this ISO 8601 date \(e.g., "2024-01-01"\) |
 | `updatedBefore` | string | No | Only return data updated before this ISO 8601 date \(e.g., "2024-12-31"\) |
-| `limit` | number | No | Maximum number of items to return in a single request \(default: 10\) |
+| `limit` | number | No | Maximum number of items to return in a single request \(default: 10, max: 500\) |
 | `cursor` | number | No | Pagination cursor from the previous response \(nextCursor\) for the next page |
 | `direction` | string | No | Sort direction by id: "asc" or "desc" \(default: asc\) |
 
@@ -130,9 +130,9 @@ List corporate events (earnings calls, capital markets days, etc.) from Quartr,
 | `sortBy` | string | No | Field to sort by: "id" or "date" \(default: id\) |
 | `updatedAfter` | string | No | Only return data updated after this ISO 8601 date \(e.g., "2024-01-01"\) |
 | `updatedBefore` | string | No | Only return data updated before this ISO 8601 date \(e.g., "2024-12-31"\) |
-| `limit` | number | No | Maximum number of items to return in a single request \(default: 10\) |
+| `limit` | number | No | Maximum number of items to return in a single request \(default: 10, max: 500\) |
 | `cursor` | number | No | Pagination cursor from the previous response \(nextCursor\) for the next page |
-| `direction` | string | No | Sort direction by id: "asc" or "desc" \(default: asc\) |
+| `direction` | string | No | Sort direction applied to the sortBy field: "asc" or "desc" \(default: asc\) |
 
 #### Output
 
@@ -197,7 +197,7 @@ Retrieve the AI-generated summary of a corporate event from Quartr, with selecta
 
 | Parameter | Type | Description |
 | --------- | ---- | ----------- |
-| `summary` | string | AI-generated event summary in Markdown |
+| `summary` | string | AI-generated event summary in Markdown \(includes embedded document source tags unless a plain-text summary is requested\) |
 | `sources` | array | Source documents referenced by the summary |
 |   ↳ `sourceId` | string | ID linking the source document to tags embedded in the summary |
 |   ↳ `documentId` | number | Quartr document ID of the source |
@@ -217,7 +217,7 @@ List the event types available in Quartr (e.g., earnings calls), useful for filt
 | Parameter | Type | Required | Description |
 | --------- | ---- | -------- | ----------- |
 | `apiKey` | string | Yes | Quartr API key |
-| `limit` | number | No | Maximum number of items to return in a single request \(default: 10\) |
+| `limit` | number | No | Maximum number of items to return in a single request \(default: 10, max: 500\) |
 | `cursor` | number | No | Pagination cursor from the previous response \(nextCursor\) for the next page |
 | `direction` | string | No | Sort direction by id: "asc" or "desc" \(default: asc\) |
 
@@ -256,7 +256,7 @@ List documents of all kinds (reports, slide decks, and transcripts) from Quartr,
 | `expandEvent` | boolean | No | Include expanded event details on each document |
 | `updatedAfter` | string | No | Only return data updated after this ISO 8601 date \(e.g., "2024-01-01"\) |
 | `updatedBefore` | string | No | Only return data updated before this ISO 8601 date \(e.g., "2024-12-31"\) |
-| `limit` | number | No | Maximum number of items to return in a single request \(default: 10\) |
+| `limit` | number | No | Maximum number of items to return in a single request \(default: 10, max: 500\) |
 | `cursor` | number | No | Pagination cursor from the previous response \(nextCursor\) for the next page |
 | `direction` | string | No | Sort direction by id: "asc" or "desc" \(default: asc\) |
 
@@ -290,7 +290,7 @@ List the document types available in Quartr (e.g., 10-Q quarterly reports), usef
 | Parameter | Type | Required | Description |
 | --------- | ---- | -------- | ----------- |
 | `apiKey` | string | Yes | Quartr API key |
-| `limit` | number | No | Maximum number of items to return in a single request \(default: 10\) |
+| `limit` | number | No | Maximum number of items to return in a single request \(default: 10, max: 500\) |
 | `cursor` | number | No | Pagination cursor from the previous response \(nextCursor\) for the next page |
 | `direction` | string | No | Sort direction by id: "asc" or "desc" \(default: asc\) |
 
@@ -332,7 +332,7 @@ List filings and reports (10-K, 10-Q, earnings releases, etc.) from Quartr, filt
 | `expandEvent` | boolean | No | Include expanded event details on each document |
 | `updatedAfter` | string | No | Only return data updated after this ISO 8601 date \(e.g., "2024-01-01"\) |
 | `updatedBefore` | string | No | Only return data updated before this ISO 8601 date \(e.g., "2024-12-31"\) |
-| `limit` | number | No | Maximum number of items to return in a single request \(default: 10\) |
+| `limit` | number | No | Maximum number of items to return in a single request \(default: 10, max: 500\) |
 | `cursor` | number | No | Pagination cursor from the previous response \(nextCursor\) for the next page |
 | `direction` | string | No | Sort direction by id: "asc" or "desc" \(default: asc\) |
 
@@ -413,7 +413,7 @@ List slide presentations from Quartr, filterable by company, event, document typ
 | `expandEvent` | boolean | No | Include expanded event details on each document |
 | `updatedAfter` | string | No | Only return data updated after this ISO 8601 date \(e.g., "2024-01-01"\) |
 | `updatedBefore` | string | No | Only return data updated before this ISO 8601 date \(e.g., "2024-12-31"\) |
-| `limit` | number | No | Maximum number of items to return in a single request \(default: 10\) |
+| `limit` | number | No | Maximum number of items to return in a single request \(default: 10, max: 500\) |
 | `cursor` | number | No | Pagination cursor from the previous response \(nextCursor\) for the next page |
 | `direction` | string | No | Sort direction by id: "asc" or "desc" \(default: asc\) |
 
@@ -494,7 +494,7 @@ List event transcripts from Quartr, filterable by company, event, document type,
 | `expandEvent` | boolean | No | Include expanded event details on each document |
 | `updatedAfter` | string | No | Only return data updated after this ISO 8601 date \(e.g., "2024-01-01"\) |
 | `updatedBefore` | string | No | Only return data updated before this ISO 8601 date \(e.g., "2024-12-31"\) |
-| `limit` | number | No | Maximum number of items to return in a single request \(default: 10\) |
+| `limit` | number | No | Maximum number of items to return in a single request \(default: 10, max: 500\) |
 | `cursor` | number | No | Pagination cursor from the previous response \(nextCursor\) for the next page |
 | `direction` | string | No | Sort direction by id: "asc" or "desc" \(default: asc\) |
 
@@ -573,7 +573,7 @@ List archived event audio recordings from Quartr, filterable by company, event,
 | `expandEvent` | boolean | No | Include expanded event details on each audio recording |
 | `updatedAfter` | string | No | Only return data updated after this ISO 8601 date \(e.g., "2024-01-01"\) |
 | `updatedBefore` | string | No | Only return data updated before this ISO 8601 date \(e.g., "2024-12-31"\) |
-| `limit` | number | No | Maximum number of items to return in a single request \(default: 10\) |
+| `limit` | number | No | Maximum number of items to return in a single request \(default: 10, max: 500\) |
 | `cursor` | number | No | Pagination cursor from the previous response \(nextCursor\) for the next page |
 | `direction` | string | No | Sort direction by id: "asc" or "desc" \(default: asc\) |
 
@@ -657,13 +657,13 @@ List live and upcoming events from Quartr with live audio and transcript stream
 | `ciks` | string | No | Comma-separated list of SEC CIKs \(e.g., "0000320193"\) |
 | `countries` | string | No | Comma-separated list of ISO 3166-1 alpha-2 country codes \(e.g., "US,SE"\) |
 | `exchanges` | string | No | Comma-separated list of exchange symbols, without whitespace \(e.g., "NasdaqGS"\) |
-| `states` | string | No | Comma-separated list of live states to filter by: notLive, willBeLive, live, liveFailedInterrupted, liveFailedNoAccess |
+| `states` | string | No | Comma-separated list of live states to filter by: notLive, willBeLive, live, liveFailedInterrupted, liveFailedNoAccess, liveFailedNotStarted, processingRecording, processingRecordingFailed, recordingAvailable |
 | `startDate` | string | No | Only return events on or after this ISO 8601 date \(e.g., "2024-01-01"\) |
 | `endDate` | string | No | Only return events on or before this ISO 8601 date \(e.g., "2024-12-31"\) |
 | `transcriptVersion` | string | No | Version of the live transcript stream: "1.6" or "1.7" \(default: 1.6\) |
 | `updatedAfter` | string | No | Only return data updated after this ISO 8601 date \(e.g., "2024-01-01"\) |
 | `updatedBefore` | string | No | Only return data updated before this ISO 8601 date \(e.g., "2024-12-31"\) |
-| `limit` | number | No | Maximum number of items to return in a single request \(default: 10\) |
+| `limit` | number | No | Maximum number of items to return in a single request \(default: 10, max: 500\) |
 | `cursor` | number | No | Pagination cursor from the previous response \(nextCursor\) for the next page |
 | `direction` | string | No | Sort direction by id: "asc" or "desc" \(default: asc\) |
 
@@ -677,7 +677,7 @@ List live and upcoming events from Quartr with live audio and transcript stream
 |   ↳ `companyId` | number | Quartr company ID |
 |   ↳ `date` | string | Scheduled event date \(ISO 8601\) |
 |   ↳ `wentLiveAt` | string | Timestamp when the event went live \(ISO 8601\) |
-|   ↳ `state` | string | Live state \(notLive, willBeLive, live, liveFailedInterrupted, liveFailedNoAccess, recordingAvailable\) |
+|   ↳ `state` | string | Live state \(notLive, willBeLive, live, liveFailedInterrupted, liveFailedNoAccess, liveFailedNotStarted, processingRecording, processingRecordingFailed, recordingAvailable\) |
 |   ↳ `audio` | string | URL of the live audio stream or recording |
 |   ↳ `transcript` | string | URL of the live transcript stream \(JSON Lines\) |
 |   ↳ `createdAt` | string | Creation timestamp \(ISO 8601\) |

apps/sim/blocks/blocks/quartr.ts

@@ -43,6 +43,8 @@ const DATE_RANGE_LIST_OPERATIONS = [
   'list_live_events',
 ]
 
+const UPDATED_RANGE_LIST_OPERATIONS = ['list_companies', ...DATE_RANGE_LIST_OPERATIONS]
+
 export const QuartrBlock: BlockConfig<ToolResponse> = {
   type: 'quartr',
   name: 'Quartr',
@@ -302,7 +304,7 @@ export const QuartrBlock: BlockConfig<ToolResponse> = {
       title: 'Updated After',
       type: 'short-input',
       placeholder: 'ISO 8601 date (e.g., 2024-01-01)',
-      condition: { field: 'operation', value: ALL_LIST_OPERATIONS },
+      condition: { field: 'operation', value: UPDATED_RANGE_LIST_OPERATIONS },
       mode: 'advanced',
       wandConfig: {
         enabled: true,
@@ -316,7 +318,7 @@ export const QuartrBlock: BlockConfig<ToolResponse> = {
       title: 'Updated Before',
       type: 'short-input',
       placeholder: 'ISO 8601 date (e.g., 2024-12-31)',
-      condition: { field: 'operation', value: ALL_LIST_OPERATIONS },
+      condition: { field: 'operation', value: UPDATED_RANGE_LIST_OPERATIONS },
       mode: 'advanced',
       wandConfig: {
         enabled: true,
@@ -443,7 +445,8 @@ export const QuartrBlock: BlockConfig<ToolResponse> = {
     },
     summary: {
       type: 'string',
-      description: 'AI-generated event summary in Markdown',
+      description:
+        'AI-generated event summary in Markdown (includes embedded document source tags unless a plain-text summary is requested)',
       condition: { field: 'operation', value: 'get_event_summary' },
     },
     sources: {

apps/sim/tools/error-extractors.ts

@@ -145,6 +145,31 @@ const ERROR_EXTRACTORS: ErrorExtractorConfig[] = [
       return undefined
     },
   },
+  {
+    id: 'nestjs-validation-errors',
+    description: 'NestJS validation errors with a message array of field/message objects',
+    examples: ['Quartr API'],
+    extract: (errorInfo) => {
+      const message = errorInfo?.data?.message
+      if (!Array.isArray(message) || message.length === 0) return undefined
+
+      const entries = message
+        .map((entry) => {
+          if (typeof entry === 'string') return entry
+          if (entry && typeof entry === 'object' && typeof entry.message === 'string') {
+            return typeof entry.field === 'string' && entry.field
+              ? `${entry.field}: ${entry.message}`
+              : entry.message
+          }
+          return undefined
+        })
+        .filter((entry): entry is string => Boolean(entry))
+      if (entries.length === 0) return undefined
+
+      const prefix = typeof errorInfo?.data?.error === 'string' ? `${errorInfo.data.error}: ` : ''
+      return `${prefix}${entries.join('; ')}`
+    },
+  },
   {
     id: 'hunter-errors',
     description: 'Hunter API error details',
@@ -275,6 +300,7 @@ export const ErrorExtractorId = {
   DETAILS_ARRAY: 'details-array',
   DETAILS_STRING_ARRAY: 'details-string-array',
   BATCH_VALIDATION_ERRORS: 'batch-validation-errors',
+  NESTJS_VALIDATION_ERRORS: 'nestjs-validation-errors',
   HUNTER_ERRORS: 'hunter-errors',
   ERRORS_ARRAY_STRING: 'errors-array-string',
   TELEGRAM_DESCRIPTION: 'telegram-description',

apps/sim/tools/quartr/get_event_summary.ts

@@ -5,7 +5,12 @@ import {
   type QuartrSingleDto,
   type QuartrSummaryDto,
 } from '@/tools/quartr/types'
-import { buildQuartrUrl, mapQuartrSummarySource, parseQuartrResponse } from '@/tools/quartr/utils'
+import {
+  buildQuartrUrl,
+  isQuartrToggleEnabled,
+  mapQuartrSummarySource,
+  parseQuartrResponse,
+} from '@/tools/quartr/utils'
 import type { ToolConfig } from '@/tools/types'
 
 export const quartrGetEventSummaryTool: ToolConfig<
@@ -49,7 +54,7 @@ export const quartrGetEventSummaryTool: ToolConfig<
     url: (params) =>
       buildQuartrUrl(`/events/${encodeURIComponent(String(params.eventId).trim())}/summary`, {
         length: params.summaryLength,
-        plain: params.plainSummary === true ? true : undefined,
+        plain: isQuartrToggleEnabled(params.plainSummary) ? true : undefined,
       }),
     method: 'GET',
     headers: (params) => ({ 'x-api-key': params.apiKey }),
@@ -77,7 +82,8 @@ export const quartrGetEventSummaryTool: ToolConfig<
   outputs: {
     summary: {
       type: 'string',
-      description: 'AI-generated event summary in Markdown',
+      description:
+        'AI-generated event summary in Markdown (includes embedded document source tags unless a plain-text summary is requested)',
     },
     sources: {
       type: 'array',

apps/sim/tools/quartr/list_audio.ts

@@ -8,8 +8,9 @@ import {
 import {
   buildQuartrListQuery,
   buildQuartrUrl,
+  isQuartrToggleEnabled,
   mapQuartrAudio,
-  normalizeQuartrIdList,
+  normalizeQuartrCommaList,
   parseQuartrResponse,
 } from '@/tools/quartr/utils'
 import type { ToolConfig } from '@/tools/types'
@@ -105,7 +106,7 @@ export const quartrListAudioTool: ToolConfig<QuartrListAudioParams, QuartrListAu
       type: 'number',
       required: false,
       visibility: 'user-or-llm',
-      description: 'Maximum number of items to return in a single request (default: 10)',
+      description: 'Maximum number of items to return in a single request (default: 10, max: 500)',
     },
     cursor: {
       type: 'number',
@@ -125,11 +126,11 @@ export const quartrListAudioTool: ToolConfig<QuartrListAudioParams, QuartrListAu
     url: (params) =>
       buildQuartrUrl('/audio', {
         ...buildQuartrListQuery(params),
-        companyIds: normalizeQuartrIdList(params.companyIds),
-        eventIds: normalizeQuartrIdList(params.eventIds),
+        companyIds: normalizeQuartrCommaList(params.companyIds),
+        eventIds: normalizeQuartrCommaList(params.eventIds),
         startDate: params.startDate,
         endDate: params.endDate,
-        expand: params.expandEvent === true ? 'event' : undefined,
+        expand: isQuartrToggleEnabled(params.expandEvent) ? 'event' : undefined,
       }),
     method: 'GET',
     headers: (params) => ({ 'x-api-key': params.apiKey }),

apps/sim/tools/quartr/list_companies.ts

@@ -9,7 +9,7 @@ import {
   buildQuartrListQuery,
   buildQuartrUrl,
   mapQuartrCompany,
-  normalizeQuartrIdList,
+  normalizeQuartrCommaList,
   parseQuartrResponse,
 } from '@/tools/quartr/utils'
 import type { ToolConfig } from '@/tools/types'
@@ -91,7 +91,7 @@ export const quartrListCompaniesTool: ToolConfig<
       type: 'number',
       required: false,
       visibility: 'user-or-llm',
-      description: 'Maximum number of items to return in a single request (default: 10)',
+      description: 'Maximum number of items to return in a single request (default: 10, max: 500)',
     },
     cursor: {
       type: 'number',
@@ -111,8 +111,8 @@ export const quartrListCompaniesTool: ToolConfig<
     url: (params) =>
       buildQuartrUrl('/companies', {
         ...buildQuartrListQuery(params),
-        ids: normalizeQuartrIdList(params.companyIds),
-        openfigis: normalizeQuartrIdList(params.openfigis),
+        ids: normalizeQuartrCommaList(params.companyIds),
+        openfigis: normalizeQuartrCommaList(params.openfigis),
       }),
     method: 'GET',
     headers: (params) => ({ 'x-api-key': params.apiKey }),

apps/sim/tools/quartr/list_document_types.ts

@@ -29,7 +29,7 @@ export const quartrListDocumentTypesTool: ToolConfig<
       type: 'number',
       required: false,
       visibility: 'user-or-llm',
-      description: 'Maximum number of items to return in a single request (default: 10)',
+      description: 'Maximum number of items to return in a single request (default: 10, max: 500)',
     },
     cursor: {
       type: 'number',

apps/sim/tools/quartr/list_documents.ts

@@ -122,7 +122,7 @@ export const quartrListDocumentsTool: ToolConfig<
       type: 'number',
       required: false,
       visibility: 'user-or-llm',
-      description: 'Maximum number of items to return in a single request (default: 10)',
+      description: 'Maximum number of items to return in a single request (default: 10, max: 500)',
     },
     cursor: {
       type: 'number',

apps/sim/tools/quartr/list_event_types.ts

@@ -29,7 +29,7 @@ export const quartrListEventTypesTool: ToolConfig<
       type: 'number',
       required: false,
       visibility: 'user-or-llm',
-      description: 'Maximum number of items to return in a single request (default: 10)',
+      description: 'Maximum number of items to return in a single request (default: 10, max: 500)',
     },
     cursor: {
       type: 'number',

apps/sim/tools/quartr/list_events.ts

@@ -9,7 +9,7 @@ import {
   buildQuartrListQuery,
   buildQuartrUrl,
   mapQuartrEvent,
-  normalizeQuartrIdList,
+  normalizeQuartrCommaList,
   parseQuartrResponse,
 } from '@/tools/quartr/utils'
 import type { ToolConfig } from '@/tools/types'
@@ -105,7 +105,7 @@ export const quartrListEventsTool: ToolConfig<QuartrListEventsParams, QuartrList
       type: 'number',
       required: false,
       visibility: 'user-or-llm',
-      description: 'Maximum number of items to return in a single request (default: 10)',
+      description: 'Maximum number of items to return in a single request (default: 10, max: 500)',
     },
     cursor: {
       type: 'number',
@@ -117,16 +117,16 @@ export const quartrListEventsTool: ToolConfig<QuartrListEventsParams, QuartrList
       type: 'string',
       required: false,
       visibility: 'user-only',
-      description: 'Sort direction by id: "asc" or "desc" (default: asc)',
+      description: 'Sort direction applied to the sortBy field: "asc" or "desc" (default: asc)',
     },
   },
 
   request: {
     url: (params) =>
       buildQuartrUrl('/events', {
         ...buildQuartrListQuery(params),
-        companyIds: normalizeQuartrIdList(params.companyIds),
-        typeIds: normalizeQuartrIdList(params.eventTypeIds),
+        companyIds: normalizeQuartrCommaList(params.companyIds),
+        typeIds: normalizeQuartrCommaList(params.eventTypeIds),
         startDate: params.startDate,
         endDate: params.endDate,
         sortBy: params.sortBy,