fix(zoho-desk): make the attachment cap reachable, unbreak selector paging

Final audit round.

The 50 MB attachment ceiling could never be hit. This route returns the file as
base64 inside its JSON body, and the executor reads internal tool responses
through readToolResponseBody, capped at 10 MB. Base64 inflates 4/3, so ~7.5 MB
of raw bytes is the real ceiling - and the old limit meant a larger attachment
was downloaded, encoded and serialized in full (peaking near 250 MB of live
allocation, with nothing bounding concurrent downloads) purely to be rejected
afterwards. The cap is now the reachable size, so the limit enforces itself while
the bytes are still streaming, and an overflow returns 413 with the actual
ceiling instead of a generic 500. Raising it properly means uploading in the
route and returning a file reference, as the WhatsApp media route does - not a
bigger constant.

Selector paging assumed a 0-based `from`. Zoho's docs contradict themselves:
the pagination section says "range 0-4999, default 0" while the listing examples
read as 1-based ("from=5 and limit=50 retrieves records 5 to 54"). Under the
1-based reading, stepping by exactly the page size re-fetches the boundary record
and the dropdown shows a duplicate per page. Rather than pick a base that cannot
be confirmed without a live tenant, the department and agent drains dedupe by id,
which is correct under either reading.

The organization list was unpaginated, and Zoho's listing APIs default to ten per
page. An account with more accessible portals silently got a truncated dropdown,
and since every other selector and every tool call is gated on orgId, a missing
portal was unreachable except through the advanced manual field. Both the
selector route and list_organizations now request the documented maximum.

Docs: regenerated so the trigger table includes manualOrgId, and two
service-account claims are hedged to match what the code already says it cannot
verify - that zsoid equals the Desk orgId header value, and that every tool works
under the requested scopes (Zoho publishes no scope for the attachment content
sub-path).

Also: status and priority move out of advanced mode - they are the fields most
often changed on a ticket update; the custom-fields wand prompt now ends with the
required "Return ONLY" clause; and the shared-orgId rationale comment cites the
mechanism that actually applies (buildCanonicalIndex dedupe plus the first-non-
empty rule in getCanonicalValues) rather than a blocks.test.ts branch that never
evaluates this pair.

Author: waleedlatif1

apps/docs/content/docs/en/integrations/zoho-desk-service-account.mdx

@@ -133,7 +133,9 @@ Add a Zoho Desk block to your workflow. In the credential dropdown, your Self Cl
 
 {/* TODO(screenshot): Zoho Desk block in a workflow with the Self Client selected as the credential */}
 
-The block calls the Zoho Desk REST API with a freshly minted access token — the same requests as the OAuth flow, so every Zoho Desk tool works, subject to the scopes above.
+The block calls the Zoho Desk REST API with a freshly minted access token — the same requests as the OAuth flow, so the Zoho Desk tools work the same way, subject to the scopes above.
+
+One exception is worth knowing: Zoho publishes no OAuth scope for the attachment download sub-path, so **Get Attachment** is the one operation whose scope requirement we could not confirm from Zoho's documentation. If it returns a scope error, the requested scope list needs widening.
 
 ### Triggers still need OAuth
 
@@ -150,7 +152,7 @@ Access tokens minted from a Self Client live for one hour and there is **no refr
 
 <FAQ items={[
   { question: "Why a Self Client instead of OAuth?", answer: "A Self Client authenticates as your Zoho organization, not as a person — nothing expires when someone leaves or their login lapses. Sim mints short-lived tokens from the stored client ID and secret whenever a workflow runs." },
-  { question: "Where do I find the Organization ID?", answer: "In Zoho Desk, go to Setup (gear icon) → Developer Space → API. The numeric Organization ID shown there is the value to paste. It is the same ID that Zoho Desk API calls send in the orgId header." },
+  { question: "Where do I find the Organization ID?", answer: "In Zoho Desk, go to Setup (gear icon) → Developer Space → API. The numeric Organization ID shown there is the value to paste. This is expected to be the same ID that Zoho Desk API calls send in the orgId header; if Zoho rejects it with missing_org_info, paste the full ZohoDesk.<your-org-id> value instead." },
   { question: "Zoho rejects my credentials with invalid_client — why?", answer: "Either the client ID or secret was mistyped, or the client you created is not a Self Client. Only Self Clients support the client-credentials grant — in the Zoho API Console, Add Client → Self Client. Copy both values from the client's Client Secret tab." },
   { question: "Zoho returns missing_org_info or rejects the organization — why?", answer: "Zoho could not resolve a Desk organization from the ID you pasted. Re-copy the numeric Organization ID from Setup → Developer Space → API in the Desk portal you want to use. If your Zoho account has multiple Desk portals, make sure it is the ID of the right one." },
   { question: "Can I use a Self Client with a non-US Zoho account?", answer: "Yes, for the US, EU, IN, and AU data centers. Set the Data center field to us, eu, in, or au when you add the credential, and Sim mints tokens against that region's accounts server and calls the Desk host in the same region. Leaving it blank means US. The JP, CA, SA, CN, and UK data centers are not supported yet, and the interactive OAuth connection remains US-only." },

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

@@ -491,6 +491,7 @@ Trigger a workflow when a Zoho Desk event occurs (ticket, comment, thread, conta
 | --------- | ---- | -------- | ----------- |
 | `triggerCredentials` | string | Yes | This trigger creates and manages a webhook subscription in your Zoho Desk account. |
 | `orgId` | project-selector | Yes | The Zoho Desk organization \(portal\) to subscribe in. |
+| `manualOrgId` | string | Yes | Type an organization ID instead of picking one from the list. |
 | `eventType` | string | Yes | Event |
 | `triggerDepartmentIds` | string | No | Restrict events to these departments. Leave empty for all departments. |
 | `fields` | string | No | For Ticket Updated: only fire when one of these fields changes \(max 5\). Previous values are included in the payload. |

apps/sim/app/api/tools/zoho_desk/agents/route.ts

@@ -16,7 +16,7 @@ const logger = createLogger('ZohoDeskAgentsAPI')
 
 /**
  * `GET /api/v1/agents` is index-paginated exactly like `/departments`: `from` is
- * a 0-based offset and `limit` caps at 200 (default 10). A short page means the
+ * an index offset and `limit` caps at 200 (default 10). A short page means the
  * list is exhausted. The page cap bounds the drain so a provider that keeps
  * returning full pages cannot loop forever.
  */
@@ -70,6 +70,10 @@ export const POST = withRouteHandler(async (request: NextRequest) => {
 
   const headers = buildZohoDeskHeaders({ accessToken, orgId })
   const agents: Array<{ id: string; name: string }> = []
+  // Zoho's docs disagree on whether `from` is 0- or 1-based (pagination section
+  // says "range 0-4999, default 0"; listing examples read as 1-based). Deduping
+  // by id is correct under both, so the drain never yields a repeated agent.
+  const seenIds = new Set<string>()
 
   try {
     for (let page = 0; page < MAX_AGENT_PAGES; page++) {
@@ -120,7 +124,10 @@ export const POST = withRouteHandler(async (request: NextRequest) => {
       const pageItems = Array.isArray(body.data) ? (body.data as ZohoAgent[]) : []
       for (const agent of pageItems) {
         if (agent.id === undefined || agent.id === null) continue
-        agents.push({ id: String(agent.id), name: getAgentLabel(agent) })
+        const id = String(agent.id)
+        if (seenIds.has(id)) continue
+        seenIds.add(id)
+        agents.push({ id, name: getAgentLabel(agent) })
       }
 
       if (pageItems.length < AGENT_PAGE_SIZE) break

apps/sim/app/api/tools/zoho_desk/attachment/route.ts

@@ -5,6 +5,7 @@ import { zohoDeskGetAttachmentContract } from '@/lib/api/contracts/tools/zoho-de
 import { parseRequest } from '@/lib/api/server'
 import { checkInternalAuth } from '@/lib/auth/hybrid'
 import { secureFetchWithValidation } from '@/lib/core/security/input-validation.server'
+import { isPayloadSizeLimitError } from '@/lib/core/utils/stream-limits'
 import { withRouteHandler } from '@/lib/core/utils/with-route-handler'
 import { isZohoHost } from '@/tools/zoho_desk/host-allowlist'
 import {
@@ -18,7 +19,25 @@ export const dynamic = 'force-dynamic'
 
 const logger = createLogger('ZohoDeskAttachmentAPI')
 
-const MAX_ATTACHMENT_BYTES = 50 * 1024 * 1024
+/**
+ * Ceiling on a downloaded attachment.
+ *
+ * This route returns the file base64-encoded inside its JSON body, and the
+ * executor reads an internal tool response through `readToolResponseBody`, which
+ * caps at `MAX_TOOL_RESPONSE_BODY_BYTES` (10 MB). Base64 inflates by 4/3, so the
+ * largest attachment that can actually survive the round trip is ~7.5 MB of raw
+ * bytes. A larger ceiling here is not merely useless - it is actively harmful:
+ * the route would download, encode, and serialize the whole file (peaking around
+ * 250 MB of live allocation for a 50 MB attachment, with nothing limiting
+ * concurrent downloads) only for the executor to reject the oversized body
+ * afterwards. Capping at the reachable size makes the transport limit enforce
+ * itself early, while the bytes are still being streamed.
+ *
+ * Raising this requires uploading in the route and returning a file reference
+ * instead of inline base64, the way the WhatsApp media and Typeform file routes
+ * do - not a bigger number here.
+ */
+const MAX_ATTACHMENT_BYTES = 7 * 1024 * 1024
 
 export const POST = withRouteHandler(async (request: NextRequest) => {
   const authResult = await checkInternalAuth(request, { requireWorkflowId: false })
@@ -91,6 +110,21 @@ export const POST = withRouteHandler(async (request: NextRequest) => {
       },
     })
   } catch (error) {
+    // An oversized attachment is a client-visible limit, not a server fault -
+    // surface it as 413 with the actual ceiling, mirroring the WhatsApp media
+    // route, instead of collapsing it into a generic 500.
+    if (isPayloadSizeLimitError(error)) {
+      logger.warn('Zoho Desk attachment exceeds the download limit', {
+        maxBytes: MAX_ATTACHMENT_BYTES,
+      })
+      return NextResponse.json(
+        {
+          success: false,
+          error: `Attachment exceeds the ${Math.floor(MAX_ATTACHMENT_BYTES / (1024 * 1024))} MB download limit`,
+        },
+        { status: 413 }
+      )
+    }
     logger.error('Error downloading Zoho Desk attachment', { error: getErrorMessage(error) })
     return NextResponse.json(
       { success: false, error: getErrorMessage(error, 'Failed to download attachment') },

apps/sim/app/api/tools/zoho_desk/departments/route.ts

@@ -15,10 +15,21 @@ export const dynamic = 'force-dynamic'
 const logger = createLogger('ZohoDeskDepartmentsAPI')
 
 /**
- * `GET /api/v1/departments` is index-paginated: `from` is a 0-based offset and
- * `limit` caps at 200 (default 10). A short page means the list is exhausted.
+ * `GET /api/v1/departments` is index-paginated with `limit` capped at 200
+ * (default 10). A short page means the list is exhausted.
+ *
+ * Zoho's docs contradict themselves on whether `from` is 0- or 1-based: the
+ * pagination section documents "range 0-4999, default 0", while the listing
+ * examples read "from=5 and limit=50 retrieves records 5 to 54" (1-based). Under
+ * the 1-based reading, stepping by exactly PAGE_SIZE re-fetches the boundary
+ * record. Rather than guess a base we cannot confirm without a live tenant, the
+ * accumulator dedupes by id, which is correct under BOTH readings — the worst
+ * case is one redundant record per page boundary, never a duplicate entry or a
+ * skipped one.
+ *
  * The page cap bounds the drain so a provider that keeps returning full pages
- * cannot loop forever — 20 x 200 covers any realistic Desk portal.
+ * cannot loop forever — 20 x 200 covers any realistic Desk portal and keeps the
+ * maximum `from` inside Zoho's documented 4999 ceiling.
  */
 const DEPARTMENT_PAGE_SIZE = 200
 const MAX_DEPARTMENT_PAGES = 20
@@ -47,6 +58,7 @@ export const POST = withRouteHandler(async (request: NextRequest) => {
 
   const headers = buildZohoDeskHeaders({ accessToken, orgId })
   const departments: Array<{ id: string; name: string }> = []
+  const seenIds = new Set<string>()
 
   try {
     for (let page = 0; page < MAX_DEPARTMENT_PAGES; page++) {
@@ -96,8 +108,13 @@ export const POST = withRouteHandler(async (request: NextRequest) => {
       const pageItems = Array.isArray(body.data) ? (body.data as ZohoDepartment[]) : []
       for (const department of pageItems) {
         if (department.id === undefined || department.id === null) continue
+        const id = String(department.id)
+        // Dedupe: see the pagination note above — a 1-based `from` would repeat
+        // the boundary record on every page after the first.
+        if (seenIds.has(id)) continue
+        seenIds.add(id)
         departments.push({
-          id: String(department.id),
+          id,
           name: department.name || department.nameInCustomerPortal || String(department.id),
         })
       }

apps/sim/app/api/tools/zoho_desk/organizations/route.ts

@@ -41,6 +41,14 @@ export const POST = withRouteHandler(async (request: NextRequest) => {
   let organizationsUrl: URL
   try {
     organizationsUrl = assertZohoUrl(`${apiBase}/organizations`)
+    // Zoho's listing APIs default to a page size of 10. Without an explicit
+    // limit, an account with more than ten accessible portals would silently get
+    // a truncated dropdown - and because every other selector and every tool
+    // call is gated on orgId, a missing portal is unreachable except through the
+    // advanced manual field. 200 is the documented per-page ceiling on the
+    // sibling listing endpoints and is far above any real portal count, so this
+    // needs no drain loop.
+    organizationsUrl.searchParams.set('limit', '200')
   } catch {
     return NextResponse.json({ error: 'Credential resolved to a non-Zoho host' }, { status: 400 })
   }

apps/sim/blocks/blocks/zoho-desk.ts

@@ -180,15 +180,13 @@ export const ZohoDeskBlock: BlockConfig<ZohoDeskResponse> = {
       type: 'short-input',
       placeholder: 'e.g. Open, Closed',
       condition: { field: 'operation', value: ['update_ticket', 'list_tickets'] },
-      mode: 'advanced',
     },
     {
       id: 'priority',
       title: 'Priority',
       type: 'short-input',
       placeholder: 'e.g. High',
       condition: { field: 'operation', value: ['update_ticket', 'list_tickets'] },
-      mode: 'advanced',
     },
     {
       id: 'assigneeId',
@@ -297,7 +295,8 @@ export const ZohoDeskBlock: BlockConfig<ZohoDeskResponse> = {
       mode: 'advanced',
       wandConfig: {
         enabled: true,
-        prompt: 'Generate a JSON object of Zoho Desk custom field API names to values.',
+        prompt:
+          'Generate a JSON object mapping Zoho Desk custom field API names (they start with cf_) to values. Return ONLY the JSON object - no explanations, no extra text.',
         generationType: 'json-object',
       },
     },

apps/sim/tools/zoho_desk/list_organizations.ts

@@ -31,7 +31,9 @@ export const zohoDeskListOrganizationsTool: ToolConfig<
   request: {
     // The organizations endpoint is the only Desk call that does not require the
     // orgId header, so it can be listed before an organization is selected.
-    url: (params) => `${getZohoDeskApiBase(params)}/organizations`,
+    // limit=200: Zoho's listing APIs default to 10 per page, which would
+    // silently truncate an account with more accessible portals than that.
+    url: (params) => `${getZohoDeskApiBase(params)}/organizations?limit=200`,
     method: 'GET',
     headers: (params) => {
       if (!params.accessToken) throw new Error('Zoho Desk access token is required')

apps/sim/triggers/zoho_desk/webhook.ts

@@ -67,11 +67,18 @@ export const zohoDeskWebhookTrigger: TriggerConfig = {
       // `triggerDepartmentIds` below). An organization is the portal the whole
       // block talks to and means exactly the same thing in either mode, so one
       // shared value is the correct behavior — switching the block between tool
-      // and trigger mode keeps the portal the user already picked. The platform
-      // supports this explicitly: `buildCanonicalIndex` refuses to let a
-      // `trigger`-mode subblock overwrite a basicId claimed by a non-trigger
-      // one, and `blocks.test.ts` blesses basic/trigger id sharing as "valid
-      // pattern 2".
+      // and trigger mode keeps the portal the user already picked.
+      //
+      // The platform supports it: `buildCanonicalIndex` dedupes the repeated id
+      // and refuses to let a `trigger`-mode subblock overwrite a basicId claimed
+      // by a non-trigger one, and `isSubBlockVisibleForTriggerMode` renders only
+      // the active mode's twin, so the field never appears twice.
+      //
+      // A distinct id here would be actively worse, not merely inconsistent: a
+      // separate `triggerManualOrgId` would put two entries in this group's
+      // `advancedIds`, and `getCanonicalValues` returns the first non-empty one
+      // in array order — so a stale tool-mode `manualOrgId` could silently
+      // supply the trigger's organization.
       id: 'orgId',
       title: 'Organization',
       type: 'project-selector',
@@ -112,7 +119,7 @@ export const zohoDeskWebhookTrigger: TriggerConfig = {
       mode: 'trigger',
     },
     {
-      // Deliberately distinct from the block's tool-mode `departmentIds` filter.
+      // NOTE: distinct from the block's tool-mode `departmentIds` filter.
       // `block.subBlocks` is keyed by id, so a shared id would let a value typed
       // as a list_tickets filter silently become the webhook's department filter
       // (and vice versa) when the block is switched between tool and trigger mode.