feat(jira): support raw ADF document objects in description and environment fields

Add toAdf() helper that passes through ADF objects as-is or wraps plain
text in a single-paragraph ADF doc. Update write and update routes to
use it, replacing inline ADF wrapping. Update Zod schema to accept
string or object for description. Fully backward compatible — plain
text still works, but callers can now pass rich ADF with expand nodes,
tables, code blocks, etc.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

Author: waleedlatif1

apps/sim/app/api/tools/jira/update/route.ts

@@ -3,7 +3,7 @@ import { type NextRequest, NextResponse } from 'next/server'
 import { z } from 'zod'
 import { checkSessionOrInternalAuth } from '@/lib/auth/hybrid'
 import { validateJiraCloudId, validateJiraIssueKey } from '@/lib/core/security/input-validation'
-import { getJiraCloudId, parseAtlassianErrorMessage } from '@/tools/jira/utils'
+import { getJiraCloudId, parseAtlassianErrorMessage, toAdf } from '@/tools/jira/utils'
 
 export const dynamic = 'force-dynamic'
 
@@ -15,7 +15,7 @@ const jiraUpdateSchema = z.object({
   issueKey: z.string().min(1, 'Issue key is required'),
   summary: z.string().optional(),
   title: z.string().optional(),
-  description: z.string().optional(),
+  description: z.union([z.string(), z.record(z.unknown())]).optional(),
   priority: z.string().optional(),
   assignee: z.string().optional(),
   labels: z.array(z.string()).optional(),
@@ -91,21 +91,7 @@ export async function PUT(request: NextRequest) {
     }
 
     if (description !== undefined && description !== null && description !== '') {
-      fields.description = {
-        type: 'doc',
-        version: 1,
-        content: [
-          {
-            type: 'paragraph',
-            content: [
-              {
-                type: 'text',
-                text: description,
-              },
-            ],
-          },
-        ],
-      }
+      fields.description = toAdf(description)
     }
 
     if (priority !== undefined && priority !== null && priority !== '') {
@@ -136,21 +122,7 @@ export async function PUT(request: NextRequest) {
     }
 
     if (environment !== undefined && environment !== null && environment !== '') {
-      fields.environment = {
-        type: 'doc',
-        version: 1,
-        content: [
-          {
-            type: 'paragraph',
-            content: [
-              {
-                type: 'text',
-                text: environment,
-              },
-            ],
-          },
-        ],
-      }
+      fields.environment = toAdf(environment)
     }
 
     if (

apps/sim/app/api/tools/jira/write/route.ts

@@ -2,7 +2,7 @@ import { createLogger } from '@sim/logger'
 import { type NextRequest, NextResponse } from 'next/server'
 import { checkSessionOrInternalAuth } from '@/lib/auth/hybrid'
 import { validateAlphanumericId, validateJiraCloudId } from '@/lib/core/security/input-validation'
-import { getJiraCloudId, parseAtlassianErrorMessage } from '@/tools/jira/utils'
+import { getJiraCloudId, parseAtlassianErrorMessage, toAdf } from '@/tools/jira/utils'
 
 export const dynamic = 'force-dynamic'
 
@@ -85,21 +85,7 @@ export async function POST(request: NextRequest) {
     }
 
     if (description !== undefined && description !== null && description !== '') {
-      fields.description = {
-        type: 'doc',
-        version: 1,
-        content: [
-          {
-            type: 'paragraph',
-            content: [
-              {
-                type: 'text',
-                text: description,
-              },
-            ],
-          },
-        ],
-      }
+      fields.description = toAdf(description)
     }
 
     if (parent !== undefined && parent !== null && parent !== '') {
@@ -144,21 +130,7 @@ export async function POST(request: NextRequest) {
     }
 
     if (environment !== undefined && environment !== null && environment !== '') {
-      fields.environment = {
-        type: 'doc',
-        version: 1,
-        content: [
-          {
-            type: 'paragraph',
-            content: [
-              {
-                type: 'text',
-                text: environment,
-              },
-            ],
-          },
-        ],
-      }
+      fields.environment = toAdf(environment)
     }
 
     if (

apps/sim/tools/jira/update.ts

@@ -42,7 +42,8 @@ export const jiraUpdateTool: ToolConfig<JiraUpdateParams, JiraUpdateResponse> =
       type: 'string',
       required: false,
       visibility: 'user-or-llm',
-      description: 'New description for the issue',
+      description:
+        'New description for the issue. Accepts plain text (auto-wrapped in ADF) or a raw ADF document object',
     },
     priority: {
       type: 'string',

apps/sim/tools/jira/utils.ts

@@ -5,6 +5,26 @@ const logger = createLogger('JiraUtils')
 
 const MAX_ATTACHMENT_SIZE = 50 * 1024 * 1024
 
+/**
+ * Converts a value to ADF format. If the value is already an ADF document object,
+ * it is returned as-is. If it is a plain string, it is wrapped in a single-paragraph ADF doc.
+ */
+export function toAdf(value: string | Record<string, unknown>): Record<string, unknown> {
+  if (typeof value === 'object' && value.type === 'doc') {
+    return value
+  }
+  return {
+    type: 'doc',
+    version: 1,
+    content: [
+      {
+        type: 'paragraph',
+        content: [{ type: 'text', text: String(value) }],
+      },
+    ],
+  }
+}
+
 /**
  * Extracts plain text from Atlassian Document Format (ADF) content.
  * Returns null if content is falsy.

apps/sim/tools/jira/write.ts

@@ -42,7 +42,8 @@ export const jiraWriteTool: ToolConfig<JiraWriteParams, JiraWriteResponse> = {
       type: 'string',
       required: false,
       visibility: 'user-or-llm',
-      description: 'Description for the issue',
+      description:
+        'Description for the issue. Accepts plain text (auto-wrapped in ADF) or a raw ADF document object',
     },
     priority: {
       type: 'string',