feat(posts): opt-in attachments on the posts list (API + agent tool)

[giladresisi]

What kind of change does this PR introduce?

Feature (backend public API + agent/MCP tool). Adds an opt-in includeAttachments flag to GET /public/v1/posts (query param on GetPostsDto) and to postsListTool (boolean input). When set, each post gains an attachments array of { id, path, thumbnail } parsed from the post's image column in PostsService.getPosts; PostsRepository.getPosts only selects image when the flag is on, following the includeIntegration pattern of getPost. The raw image string is never exposed. The tool description and the agent system prompt tell the agent to list with the flag and pass the returned paths straight back to integrationSchedulePostTool when duplicating or mirroring posts. Default is off on both surfaces, so existing responses are byte-identical; the calendar path (getPostsMinified) is untouched. No frontend, migration or env changes.

Why was this change needed?

A customer asked the Postiz agent to mirror all their upcoming Instagram and TikTok posts onto a new YouTube channel. The agent could read the post text but not the attached videos, because neither the List Posts API nor postsListTool returned attachments, so it could not copy the media and the request failed. There is no single-post read endpoint either, so the list is the only place an agent can learn what media a post carries.

The flag is opt-in rather than always-on because of payload size: a post row is roughly 480 bytes today and each attachment adds about 140 bytes (about 230 bytes with a thumbnail), so a 10-image carousel quadruples its row and a 500-post window of such posts would grow by roughly 0.7 to 1.1 MB. Most list calls (calendar-style browsing, status checks) do not need media, so the default keeps them unchanged and the agent is instructed to ask for attachments only when it needs to reuse media.

Other information:

Related PRs, both to be merged only after this one is deployed:

• Docs: docs: includeAttachments flag on List Posts and postsListTool postiz-docs#247 (List Posts parameter + response field, postsListTool in the MCP tools page)
• CLI + skill: feat(posts:list): --includeAttachments flag to reuse media when reposting postiz-agent#22 (posts:list --includeAttachments, skill rule to reuse listed paths)

QA

1. Call GET /public/v1/posts?startDate=...&endDate=... for a window containing a post with media, with no extra param: the response is unchanged, no attachments and no image key on any post
2. Repeat with &includeAttachments=false: same as step 1
3. Repeat with &includeAttachments=true: every post has an attachments array; posts with media list { id, path, thumbnail } entries (thumbnail null when absent), posts without media have []; still no image key
4. Repeat with &includeAttachments=yes: HTTP 400
5. Over MCP, call tools/list and check postsListTool shows the includeAttachments input and the attachments output field
6. Call postsListTool without the flag: items have no attachments; with includeAttachments: true: items carry the same attachments as step 3
7. Create a draft on another channel (API or integrationSchedulePostTool) passing one of the returned path values as the attachment, then list that window with the flag: the new draft shows the identical attachment path
8. Open the calendar in the app for the same window: the /posts response still has no image/attachment data, with or without includeAttachments=true appended
9. In the app's Agent page with a target channel selected, ask it to mirror an existing post with an image to that channel as a draft: it reports the source post's attachment, asks for confirmation, and the created draft carries the same media path without an upload

Checklist:

• I have read the CONTRIBUTING guide.
• I have signed the Contributor License Agreement (CLA) (ICLA for individuals, CCLA for entities).
• I confirm I have not used AI to submit this PR or generate code for it.
• I checked that there were no similar issues or PRs already open for this.
• This PR fixes just ONE issue
• I have filled in the QA section above with real steps to verify this change.

[strix-security]

Strix Security Review

No security issues found.

_{Updated for 21b1922.}

---

Reviewed by Strix
_{Re-run review · Configure security review settings}

[postiz-agent]

✅ Snyk checks have passed. No issues have been found so far.

Status	Scan Engine	Critical	High	Medium	Low	Total (0)
✅	Open Source Security	0	0	0	0	0 issues
✅	Licenses	0	0	0	0	0 issues
✅	Code Security	0	0	0	0	0 issues

💻 Catch issues earlier using the plugins for VS Code, JetBrains IDEs, Visual Studio, and Eclipse.