fix(helpscout): strict custom field and snooze input, unsafe connector reconciliation, safe inbox IDs

Author: waleedlatif1

apps/sim/connectors/helpscout/helpscout.ts

@@ -84,7 +84,6 @@ const ConversationPageSchema = z
       .passthrough()
       .optional(),
     _links: LinksSchema,
-    page: z.object({ totalElements: z.number().optional() }).passthrough().optional(),
   })
   .passthrough()
 
@@ -219,7 +218,9 @@ function conversationChangeMarker(conversation: HelpScoutConversation): string {
     conversation.preview ?? '',
     conversation.mailboxId ?? '',
     conversation.assignee?.id ?? '',
+    conversation.assignee ? personName(conversation.assignee) : '',
     conversation.primaryCustomer?.email ?? '',
+    conversation.primaryCustomer ? personName(conversation.primaryCustomer) : '',
     (conversation.tags ?? [])
       .map((tag) => tag.tag ?? '')
       .sort(compareStrings)
@@ -335,8 +336,6 @@ export const helpScoutConnector: ConnectorConfig = {
     const seen = new Set<number>()
     const documents: ExternalDocument[] = []
     let capped = false
-    let firstTotal: number | undefined
-    let lastTotal: number | undefined
     const maxPages = Math.ceil(maxConversations / CONVERSATIONS_PER_PAGE) + 5
 
     for (let page = 1; ; page++) {
@@ -351,8 +350,6 @@ export const helpScoutConnector: ConnectorConfig = {
       const data = ConversationPageSchema.parse(
         await helpScoutGet('/conversations', accessToken, query)
       )
-      lastTotal = data.page?.totalElements
-      if (page === 1) firstTotal = lastTotal
       for (const conversation of data._embedded?.conversations ?? []) {
         if (seen.has(conversation.id) || !isIndexedConversation(conversation)) continue
         if (documents.length >= maxConversations) {
@@ -369,25 +366,21 @@ export const helpScoutConnector: ConnectorConfig = {
       }
     }
 
-    /**
-     * Pages are numbered, so a conversation that leaves the filtered set mid-scan shifts later
-     * ones up a page and one can be skipped. A changed total means that may have happened, so
-     * this listing must not drive deletion.
-     */
-    const totalChanged = firstTotal !== undefined && lastTotal !== firstTotal
-    if (syncContext) {
-      if (capped) syncContext.listingCapped = true
-      if (totalChanged) syncContext.reconciliationUnsafe = true
-    }
+    if (capped && syncContext) syncContext.listingCapped = true
     if (capped) {
-      logger.warn(
-        'Help Scout listing truncated by Max Conversations; skipping deletion reconciliation',
-        { count: documents.length, maxConversations }
-      )
+      logger.warn('Help Scout listing truncated by Max Conversations', {
+        count: documents.length,
+        maxConversations,
+      })
     } else {
-      logger.info('Listed Help Scout conversations', { count: documents.length, totalChanged })
+      logger.info('Listed Help Scout conversations', { count: documents.length })
     }
-    return { documents, hasMore: false }
+    /**
+     * Pages are numbered, so a conversation that leaves the filtered set mid-scan shifts later
+     * ones up a page and one can be skipped even when the total stays the same. Absence from
+     * this listing is therefore never treated as a deletion.
+     */
+    return { documents, hasMore: false, reconciliationSafe: false }
   },
 
   getDocument: async (
@@ -402,7 +395,9 @@ export const helpScoutConnector: ConnectorConfig = {
         await helpScoutGet(`/conversations/${externalId}`, accessToken)
       )
       // A merged conversation redirects to the conversation it was merged into.
-      if (conversation.state === 'deleted' || String(conversation.id) !== externalId) return null
+      if (!isIndexedConversation(conversation) || String(conversation.id) !== externalId) {
+        return null
+      }
       const threads = (await listThreads(externalId, accessToken)).filter((thread) =>
         isIndexedThread(thread, includeNotes)
       )

apps/sim/connectors/helpscout/meta.ts

@@ -80,7 +80,7 @@ export const helpScoutConnectorMeta: ConnectorMeta = {
       required: false,
       placeholder: `e.g. 200 (default: ${DEFAULT_MAX_CONVERSATIONS})`,
       description:
-        'Maximum number of conversations to sync, newest first. When more exist, conversations deleted in Help Scout stay in the knowledge base until the limit covers them.',
+        'Maximum number of conversations to sync, newest first. Conversations deleted in Help Scout are not removed from the knowledge base automatically.',
     },
   ],
 

apps/sim/lib/selectors/server/providers/helpscout.ts

@@ -26,8 +26,8 @@ type HelpScoutSelectorKey = Extract<
 >
 
 const MAX_PAGE_ITEMS = 1_000
-/** Help Scout documents no single-team endpoint, so a team detail scans at most this many pages. */
-const MAX_TEAM_DETAIL_PAGES = 5
+/** Help Scout documents no single-team endpoint, so a team detail scans the teams list. */
+const MAX_TEAM_DETAIL_PAGES = 200
 
 const idSchema = z.number().int().positive().max(Number.MAX_SAFE_INTEGER)
 

apps/sim/lib/webhooks/providers/helpscout.ts

@@ -60,10 +60,11 @@ function readEventType(headers: Record<string, string>): string {
 function resolveInboxFilter(config: Record<string, unknown>): number | undefined {
   const raw = toStringOrNull(config.triggerMailboxId)?.trim()
   if (!raw) return undefined
-  if (!HELPSCOUT_ID_PATTERN.test(raw)) {
+  const id = Number(raw)
+  if (!HELPSCOUT_ID_PATTERN.test(raw) || !Number.isSafeInteger(id) || id <= 0) {
     throw new WebhookDeploymentConfigurationError('The Help Scout inbox ID must be numeric.')
   }
-  return Number(raw)
+  return id
 }
 
 /**

apps/sim/tools/helpscout/snooze-conversation.ts

@@ -13,18 +13,28 @@ import {
 } from '@/tools/helpscout/utils'
 import type { ToolConfig } from '@/tools/types'
 
-/** Help Scout requires a future ISO 8601 time no later than the year 2100. */
+const ISO_DATE_TIME_PATTERN =
+  /^(\d{4})-(\d{2})-(\d{2})T\d{2}:\d{2}(:\d{2}(\.\d+)?)?(Z|[+-]\d{2}:\d{2})$/
+
+/** Help Scout requires a future ISO 8601 time, in whole seconds, no later than the year 2100. */
 function parseSnoozeUntil(value: string): string {
   const text = value?.trim() ?? ''
+  const match = ISO_DATE_TIME_PATTERN.exec(text)
   const time = Date.parse(text)
-  if (!text || Number.isNaN(time)) {
+  if (!match || Number.isNaN(time)) {
     throw new Error('snoozedUntil must be an ISO 8601 date-time, e.g. 2025-02-15T12:00:00Z')
   }
-  if (time <= Date.now()) throw new Error('snoozedUntil must be in the future')
-  if (new Date(time).getUTCFullYear() > 2100) {
+  const [year, month, day] = [Number(match[1]), Number(match[2]), Number(match[3])]
+  const calendarDate = new Date(Date.UTC(year, month - 1, day))
+  if (calendarDate.getUTCMonth() !== month - 1 || calendarDate.getUTCDate() !== day) {
+    throw new Error(`snoozedUntil has an invalid calendar date: ${match[0].slice(0, 10)}`)
+  }
+  const wholeSeconds = Math.ceil(time / 1000) * 1000
+  if (wholeSeconds <= Date.now()) throw new Error('snoozedUntil must be in the future')
+  if (new Date(wholeSeconds).getUTCFullYear() > 2100) {
     throw new Error('snoozedUntil must not be after the year 2100')
   }
-  return new Date(time).toISOString().replace(/\.\d{3}Z$/, 'Z')
+  return new Date(wholeSeconds).toISOString().replace(/\.\d{3}Z$/, 'Z')
 }
 
 export const helpScoutSnoozeConversationTool: ToolConfig<

apps/sim/tools/helpscout/update-custom-fields.ts

@@ -16,14 +16,15 @@ import {
 import type { ToolConfig } from '@/tools/types'
 
 function parseCustomFields(value: unknown): Array<{ id: number; value: string }> {
-  const parsed = parseJsonParam(value, 'customFields') ?? []
+  // Sending an empty list clears every field, so only an explicit JSON array is accepted.
+  const parsed = parseJsonParam(value, 'customFields')
   if (!Array.isArray(parsed)) {
     throw new Error('customFields must be a JSON array of { "id": number, "value": string }')
   }
   return parsed.map((entry) => {
     const field = entry as { id?: unknown; value?: unknown }
-    if (field.value === undefined || field.value === null) {
-      throw new Error('Every custom field needs a value; use an empty string to clear one')
+    if (typeof field.value !== 'string' && typeof field.value !== 'number') {
+      throw new Error('Every custom field value must be a string or number; use "" to clear one')
     }
     return { id: parseHelpScoutId(field.id, 'customFields[].id'), value: String(field.value) }
   })