feat(zoho-desk): canonical selectors and BlockMeta skills

The block picked its organization with an ad-hoc `combobox` + `fetchOptions`.
Only five blocks in the repo did that, and the other four are core blocks
(agent/credential/function/logs) - no other OAuth integration used it. Every
other resource a user has to identify was a bare short-input taking an opaque
numeric id.

Zoho Desk now uses the same machinery as the other 25 selector providers:
hooks/selectors/providers/zoho-desk/selectors.ts registered in the selector
registry, consumed from the block as basic selector + advanced manual input
sharing one canonicalParamId, for organization, update-ticket department, and
the list-tickets department filter. The trigger's org field moves to the same
selector. zoho-desk-org-options.ts is deleted rather than left beside the new
path, so blocks/ has zero fetchOptions usages outside the core blocks.

Wire params are unchanged (orgId, departmentId, departmentIds, assigneeId,
ticketId, contactId) - this is a UI change, not an API change.

The organizations route now resolves the credential server-side. It previously
had the browser fetch an access token and POST it back, which an earlier audit
flagged as the one place a Zoho token left the server; the new selector-credential
resolver keeps it server-side for both the OAuth and service-account credential
types and re-anchors every outbound host to the Zoho apex allowlist.

No agents selector: the endpoint is documented but its OAuth scope is not, and
the nearest evidence points at Desk.agents.READ, which we do not request. Adding
it would force every existing Zoho Desk user to reconnect for a convenience
field, so assigneeId stays a manual input until the scope can be confirmed
against a live org.

Adds the skills array BlockMeta was missing - 227 of 300 blocks declare one and
this did not. Seven skills, each grounded in a use case Zoho or the ecosystem
actually advertises (auto-triage, SLA escalation, digest, AI draft reply,
customer context, engineering handoff, knowledge-gap report) and each exercising
only tools in tools.access. CSAT surveys, ticket creation, dedup and keyword
search were deliberately left out: the integration has no tool for them, and a
skill implying an unsupported action is worse than a shorter list.

Author: waleedlatif1

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

@@ -490,7 +490,7 @@ Trigger a workflow when a Zoho Desk event occurs (ticket, comment, thread, conta
 | Parameter | Type | Required | Description |
 | --------- | ---- | -------- | ----------- |
 | `triggerCredentials` | string | Yes | This trigger creates and manages a webhook subscription in your Zoho Desk account. |
-| `orgId` | combobox | Yes | The Zoho Desk organization \(portal\) to subscribe in. |
+| `orgId` | project-selector | Yes | The Zoho Desk organization \(portal\) to subscribe in. |
 | `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/departments/route.ts

@@ -0,0 +1,119 @@
+import { createLogger } from '@sim/logger'
+import { getErrorMessage } from '@sim/utils/errors'
+import { type NextRequest, NextResponse } from 'next/server'
+import { zohoDeskDepartmentsSelectorContract } from '@/lib/api/contracts/selectors'
+import { parseRequest } from '@/lib/api/server'
+import { secureFetchWithValidation } from '@/lib/core/security/input-validation.server'
+import { generateRequestId } from '@/lib/core/utils/request'
+import { withRouteHandler } from '@/lib/core/utils/with-route-handler'
+import { resolveZohoDeskSelectorCredential } from '@/app/api/tools/zoho_desk/selector-credential'
+import { assertZohoUrl } from '@/tools/zoho_desk/host-allowlist'
+import { buildZohoDeskHeaders, getZohoDeskErrorMessage } from '@/tools/zoho_desk/utils'
+
+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.
+ * 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.
+ */
+const DEPARTMENT_PAGE_SIZE = 200
+const MAX_DEPARTMENT_PAGES = 20
+
+interface ZohoDepartment {
+  id?: string | number
+  name?: string
+  nameInCustomerPortal?: string
+}
+
+/** Backs the `zoho_desk.departments` selector. */
+export const POST = withRouteHandler(async (request: NextRequest) => {
+  const requestId = generateRequestId()
+
+  const parsed = await parseRequest(zohoDeskDepartmentsSelectorContract, request, {})
+  if (!parsed.success) return parsed.response
+  const { credential, workflowId, orgId } = parsed.data.body
+
+  const resolved = await resolveZohoDeskSelectorCredential(request, {
+    credentialId: credential,
+    workflowId,
+    requestId,
+  })
+  if (!resolved.ok) return resolved.response
+  const { accessToken, apiBase } = resolved.credential
+
+  const headers = buildZohoDeskHeaders({ accessToken, orgId })
+  const departments: Array<{ id: string; name: string }> = []
+
+  try {
+    for (let page = 0; page < MAX_DEPARTMENT_PAGES; page++) {
+      let departmentsUrl: URL
+      try {
+        departmentsUrl = assertZohoUrl(`${apiBase}/departments`)
+      } catch {
+        return NextResponse.json(
+          { error: 'Credential resolved to a non-Zoho host' },
+          { status: 400 }
+        )
+      }
+      departmentsUrl.searchParams.set('from', String(page * DEPARTMENT_PAGE_SIZE))
+      departmentsUrl.searchParams.set('limit', String(DEPARTMENT_PAGE_SIZE))
+
+      // Same rationale as the organizations/attachment routes: pin the resolved
+      // IP, block private/reserved hops, and drop the token if a Zoho-side
+      // redirect leaves the original origin.
+      const response = await secureFetchWithValidation(departmentsUrl.toString(), {
+        method: 'GET',
+        headers,
+        timeout: 15_000,
+        stripAuthOnRedirect: true,
+      })
+
+      const body: { data?: unknown } = await response
+        .json()
+        .then((json) => (json && typeof json === 'object' ? (json as { data?: unknown }) : {}))
+        .catch(() => ({}))
+
+      // Zoho answers 204 with no body once the offset runs past the last
+      // department, which is a successful end-of-list, not an error.
+      if (response.status === 204) break
+
+      if (!response.ok) {
+        const message = getZohoDeskErrorMessage(
+          body,
+          `Failed to list departments (HTTP ${response.status})`
+        )
+        logger.warn('Failed to list Zoho Desk departments', { status: response.status, message })
+        return NextResponse.json(
+          { error: message },
+          { status: response.status >= 400 && response.status < 500 ? response.status : 502 }
+        )
+      }
+
+      const pageItems = Array.isArray(body.data) ? (body.data as ZohoDepartment[]) : []
+      for (const department of pageItems) {
+        if (department.id === undefined || department.id === null) continue
+        departments.push({
+          id: String(department.id),
+          name: department.name || department.nameInCustomerPortal || String(department.id),
+        })
+      }
+
+      if (pageItems.length < DEPARTMENT_PAGE_SIZE) break
+      if (page === MAX_DEPARTMENT_PAGES - 1) {
+        logger.warn('Zoho Desk departments listing hit the page cap; list may be incomplete', {
+          pages: MAX_DEPARTMENT_PAGES,
+        })
+      }
+    }
+
+    return NextResponse.json({ departments })
+  } catch (error) {
+    const message = getErrorMessage(error, 'Failed to list departments')
+    logger.error('Error listing Zoho Desk departments', { error: message })
+    return NextResponse.json({ error: message }, { status: 502 })
+  }
+})

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

@@ -1,13 +1,14 @@
 import { createLogger } from '@sim/logger'
 import { getErrorMessage } from '@sim/utils/errors'
 import { type NextRequest, NextResponse } from 'next/server'
-import { zohoDeskListOrganizationsContract } from '@/lib/api/contracts/tools/zoho-desk'
+import { zohoDeskOrganizationsSelectorContract } from '@/lib/api/contracts/selectors'
 import { parseRequest } from '@/lib/api/server'
-import { checkSessionOrInternalAuth } from '@/lib/auth/hybrid'
 import { secureFetchWithValidation } from '@/lib/core/security/input-validation.server'
+import { generateRequestId } from '@/lib/core/utils/request'
 import { withRouteHandler } from '@/lib/core/utils/with-route-handler'
+import { resolveZohoDeskSelectorCredential } from '@/app/api/tools/zoho_desk/selector-credential'
 import { assertZohoUrl } from '@/tools/zoho_desk/host-allowlist'
-import { getZohoDeskApiBase, getZohoDeskErrorMessage } from '@/tools/zoho_desk/utils'
+import { getZohoDeskErrorMessage } from '@/tools/zoho_desk/utils'
 
 export const dynamic = 'force-dynamic'
 
@@ -19,26 +20,29 @@ interface ZohoOrganization {
   portalName?: string
 }
 
+/** Backs the `zoho_desk.organizations` selector. */
 export const POST = withRouteHandler(async (request: NextRequest) => {
-  const authResult = await checkSessionOrInternalAuth(request, { requireWorkflowId: false })
-  if (!authResult.success) {
-    return NextResponse.json({ error: 'Unauthorized' }, { status: 401 })
-  }
+  const requestId = generateRequestId()
 
-  const parsed = await parseRequest(zohoDeskListOrganizationsContract, request, {})
+  const parsed = await parseRequest(zohoDeskOrganizationsSelectorContract, request, {})
   if (!parsed.success) return parsed.response
-  const { accessToken, apiDomain } = parsed.data.body
+  const { credential, workflowId } = parsed.data.body
+
+  const resolved = await resolveZohoDeskSelectorCredential(request, {
+    credentialId: credential,
+    workflowId,
+    requestId,
+  })
+  if (!resolved.ok) return resolved.response
+  const { accessToken, apiBase } = resolved.credential
 
-  // apiDomain is client-supplied, so anchor the outbound host to a Zoho apex
-  // before attaching the OAuth token - otherwise a caller could point the server
-  // at an arbitrary origin and leak the token.
+  // apiBase is already anchored by getZohoDeskApiBase; assert again so the URL
+  // that finally receives the OAuth token is validated at the point of use.
   let organizationsUrl: URL
   try {
-    organizationsUrl = assertZohoUrl(
-      `${getZohoDeskApiBase({ apiDomain: apiDomain ?? undefined })}/organizations`
-    )
+    organizationsUrl = assertZohoUrl(`${apiBase}/organizations`)
   } catch {
-    return NextResponse.json({ error: 'apiDomain must be an https Zoho host' }, { status: 400 })
+    return NextResponse.json({ error: 'Credential resolved to a non-Zoho host' }, { status: 400 })
   }
 
   try {
@@ -84,8 +88,7 @@ export const POST = withRouteHandler(async (request: NextRequest) => {
       .filter((org) => org.id !== undefined && org.id !== null)
       .map((org) => ({
         id: String(org.id),
-        companyName: org.companyName ?? null,
-        portalName: org.portalName ?? null,
+        name: org.companyName || org.portalName || String(org.id),
       }))
 
     return NextResponse.json({ organizations })

apps/sim/app/api/tools/zoho_desk/selector-credential.ts

@@ -0,0 +1,95 @@
+import { db } from '@sim/db'
+import { account } from '@sim/db/schema'
+import { createLogger } from '@sim/logger'
+import { eq } from 'drizzle-orm'
+import { type NextRequest, NextResponse } from 'next/server'
+import { authorizeCredentialUse } from '@/lib/auth/credential-access'
+import { resolveCredentialAccessToken, resolveOAuthAccountId } from '@/app/api/auth/oauth/utils'
+import { extractZohoDeskBaseFromScope } from '@/tools/zoho_desk/host-allowlist'
+import { getZohoDeskApiBase } from '@/tools/zoho_desk/utils'
+
+const logger = createLogger('ZohoDeskSelectorCredential')
+
+interface ResolvedZohoDeskCredential {
+  accessToken: string
+  /** Desk REST base including the `/api/v1` suffix, anchored to the Zoho apex allowlist. */
+  apiBase: string
+}
+
+type ResolveResult =
+  | { ok: true; credential: ResolvedZohoDeskCredential }
+  | { ok: false; response: NextResponse }
+
+/**
+ * Resolve a Zoho Desk credential id into an access token plus the data-center
+ * Desk REST base, for the selector routes.
+ *
+ * Both credential kinds are covered by one path:
+ * - `zoho-desk-service-account` (client credentials): the minter returns the
+ *   data center's Desk base as `apiDomain` on every mint, so it comes straight
+ *   off the token result.
+ * - OAuth connection: the token exchange persists the derived Desk base in the
+ *   credential's scope string, so it is read back from the `account` row.
+ *
+ * The token never leaves the server — unlike the previous combobox, which
+ * fetched it into the browser before posting it back.
+ */
+export async function resolveZohoDeskSelectorCredential(
+  request: NextRequest,
+  params: { credentialId: string; workflowId?: string; requestId: string }
+): Promise<ResolveResult> {
+  const { credentialId, workflowId, requestId } = params
+
+  const authz = await authorizeCredentialUse(request, { credentialId, workflowId })
+  if (!authz.ok || !authz.credentialOwnerUserId) {
+    return {
+      ok: false,
+      response: NextResponse.json({ error: authz.error || 'Unauthorized' }, { status: 403 }),
+    }
+  }
+
+  const tokenResult = await resolveCredentialAccessToken(
+    credentialId,
+    authz.credentialOwnerUserId,
+    requestId
+  )
+  if (!tokenResult?.accessToken) {
+    logger.error('Failed to get Zoho Desk access token', { credentialId })
+    return {
+      ok: false,
+      response: NextResponse.json(
+        { error: 'Could not retrieve access token', authRequired: true },
+        { status: 401 }
+      ),
+    }
+  }
+
+  // Service-account mints carry `apiDomain`; an OAuth connection stores the same
+  // value on its account row instead. Falling through to `undefined` lets
+  // getZohoDeskApiBase apply the US default rather than guessing a host.
+  const apiDomain = tokenResult.apiDomain ?? (await readOAuthApiDomain(credentialId))
+
+  return {
+    ok: true,
+    credential: {
+      accessToken: tokenResult.accessToken,
+      apiBase: getZohoDeskApiBase({ apiDomain }),
+    },
+  }
+}
+
+async function readOAuthApiDomain(credentialId: string): Promise<string | undefined> {
+  try {
+    const resolved = await resolveOAuthAccountId(credentialId)
+    if (!resolved?.accountId) return undefined
+    const [row] = await db
+      .select({ scope: account.scope })
+      .from(account)
+      .where(eq(account.id, resolved.accountId))
+      .limit(1)
+    return extractZohoDeskBaseFromScope(row?.scope)
+  } catch (error) {
+    logger.warn('Failed to resolve Zoho Desk data center from credential', { error })
+    return undefined
+  }
+}