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

[waleedlatif1]

Summary

• Add toAdf() helper to jira/utils.ts — passes through ADF document objects as-is, wraps plain text strings in single-paragraph ADF
• Update write and update routes to use toAdf(), replacing inline ADF wrapping
• Update update route Zod schema to accept string | object for description
• Fully backward compatible — plain text still works identically, but callers can now pass rich ADF with expand nodes, tables, code blocks, etc.

Test plan

• Create a Jira issue with a plain text description — verify it renders as before
• Update a Jira issue with a plain text description — verify it renders as before
• Update a Jira issue with a raw ADF object (e.g., with expand nodes) — verify rich formatting renders in Jira
• Verify existing workflows using the Jira block are unaffected

[vercel]

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
docs	Ready	Preview, Comment	Apr 14, 2026 10:10pm

[cursor]

PR Summary

Medium Risk
Medium risk because it changes the shape/validation of Jira write/update request payloads and how rich-text fields are serialized, which could affect existing integrations if malformed ADF is passed through.

Overview
Jira issue create/update now accepts rich Atlassian Document Format (ADF) for the description and environment fields, while remaining compatible with plain-text inputs.

This introduces a shared toAdf() helper in jira/utils.ts to normalize strings/JSON/objects into an ADF document and updates the Jira write/update API routes to use it instead of inline ADF wrapping. The update route schema is widened so description/environment can be string or an object, and tool parameter docs are updated to reflect the new input options.

^{Reviewed by Cursor Bugbot for commit d799f3a. Configure here.}

[greptile-apps]

Greptile Summary

This PR adds a toAdf() helper to jira/utils.ts that normalises plain strings, partial ADF nodes, and full ADF documents into a valid ADF doc, then wires it into both the write and update Jira routes in place of the previous inline string-only wrapping.

• JiraUpdateParams.description, JiraUpdateParams.environment, JiraWriteParams.description, and JiraWriteParams.environment in types.ts are still typed as string | undefined — the Zod schema in the update route was widened but the shared TypeScript interfaces were not, so any typed caller attempting to pass an ADF object will get a compile error.
• The tool param definitions in write.ts and update.ts retain type: 'string' for description and environment while the human-readable descriptions now claim object support; using type: 'json' would expose a proper JSON editor and let upstream block outputs pass through as objects rather than forcing users to stringify manually.

Confidence Score: 4/5

Safe to merge once the TypeScript interface types are widened — the runtime behaviour is correct but the type system currently rejects the new feature.

The route logic and toAdf implementation are solid, but JiraUpdateParams and JiraWriteParams still declare description and environment as string-only, meaning any typed caller trying to use the advertised ADF object support will hit a TypeScript compile error. That is a present type-correctness defect, not a speculative concern.

apps/sim/tools/jira/types.ts — description and environment fields need widening in both JiraUpdateParams and JiraWriteParams

Important Files Changed

Filename	Overview
apps/sim/tools/jira/utils.ts	Adds toAdf() helper that correctly handles full ADF docs (pass-through), partial ADF nodes (wrap in doc envelope), JSON-serialized ADF strings (parse + detect), and plain text (wrap in paragraph). The three-case fallback and JSON.stringify for unrecognized objects is well-reasoned and addresses the previous review thread concern.
apps/sim/app/api/tools/jira/update/route.ts	Zod schema correctly widened to z.union([z.string(), z.record(z.unknown())]) for description and environment. Inline ADF wrapping replaced cleanly with toAdf(). Logic is correct.
apps/sim/app/api/tools/jira/write/route.ts	Inline ADF wrapping replaced with toAdf() for description and environment. The route lacks Zod validation (pre-existing), but toAdf handles all incoming types gracefully.
apps/sim/tools/jira/update.ts	Description text updated to mention ADF object support, but type: 'string' and JiraUpdateParams still typed as string — both need widening to match the new capability.
apps/sim/tools/jira/write.ts	Same as update.ts — description text updated but type: 'string' and JiraWriteParams are not updated to reflect object support for description and environment.

Flowchart

%%{init: {'theme': 'neutral'}}%%
flowchart TD
    A[Caller passes description / environment] --> B{typeof value}
    B -->|object| C{value.type === 'doc'?}
    C -->|yes| D[Return as-is]
    C -->|no| E{value.type && Array.isArray content?}
    E -->|yes| F[Wrap in doc envelope]
    E -->|no| G[JSON.stringify as plain text]
    B -->|string| H{JSON.parse succeeds?}
    H -->|yes, type==='doc'| D
    H -->|yes, type + content array| F
    H -->|yes, other JSON| I[Treat original string as plain text]
    H -->|no, parse error| I
    I --> J[Wrap in paragraph ADF]
    F --> K[Valid ADF document]
    D --> K
    G --> J
    J --> K
    K --> L[POST/PUT to Jira API]

Loading

Comments Outside Diff (1)

1. apps/sim/tools/jira/types.ts, line 979-986 (link)

   TypeScript interfaces not updated to reflect new ADF object support

   JiraUpdateParams and JiraWriteParams still declare description and environment as string | undefined. The Zod schema in update/route.ts was updated to accept z.union([z.string(), z.record(z.unknown())]), but the shared TypeScript interfaces weren't updated. Any typed consumer (e.g., another block or executor utility) constructing these params will get a compile error when passing an ADF object, undermining the feature's stated goal.

   Both interfaces need their description and environment fields widened:

   // JiraUpdateParams (line 979/986) and JiraWriteParams (line 1007/1018)
   description?: string | Record<string, unknown>
   environment?: string | Record<string, unknown>

_{Reviews (3): Last reviewed commit: "updated lobkc" | Re-trigger Greptile}

[waleedlatif1]

@greptile

[waleedlatif1]

@cursor review

[waleedlatif1]

@greptile

[waleedlatif1]

@cursor review

[cursor]

✅ Bugbot reviewed your changes and found no new issues!

Comment @cursor review or bugbot run to trigger another review on this PR

^{Reviewed by Cursor Bugbot for commit d799f3a. Configure here.}