feat: posts:settings command (patch a post's provider settings)

[giladresisi]

What

Adds a postiz posts:settings <id> --settings '<json>' CLI command that calls the new backend endpoint PUT /public/v1/posts/:id/settings to patch a post's provider-specific settings without recreating the post. Modeled exactly on the existing posts:status command (same file structure, error handling, ✅/❌ output, yargs shape).

• src/api.ts — updatePostSettings(postId, settings)
• src/commands/posts.ts — updatePostSettings handler (requires id + --settings, parses the JSON string client-side before hitting the network, ✅ success / ❌ + exit 1 on failure)
• src/index.ts — posts:settings <id> registration
• Docs: SKILL.md, README.md, CHANGELOG.md

# Flip a TikTok draft to direct publishing
postiz posts:settings <id> --settings '{"content_posting_method":"DIRECT_POST"}'

Behavior (enforced server-side, surfaced in help/docs)

• Merged — only the keys you pass change; everything else on the post is preserved, so pass a partial object.
• DRAFT/QUEUE only — published posts are rejected with a 400.
• __type is added by the backend from the integration — don't include it (the backend overwrites it if you do).
• posts:list responses now include each post's current settings (returned as a JSON string — JSON.parse it). Intended workflow: posts:list (read) → posts:settings (patch).

Testing

Verified end-to-end against a local backend: happy path, JSON-parse guard (errors before any network call), missing --settings (yargs demandOption), bad post id (404 via ❌ path), merge semantics (cumulative, non-destructive), __type overwrite, and published-post rejection (400, surfaced cleanly). pnpm build passes with no TS errors.

Related PRs

• Backend endpoint: feat(agent): update a post's settings via a tool and the public API postiz-app#1752
• Docs: docs: Update Post Settings endpoint + postSettingsTool postiz-docs#233

🤖 Generated with Claude Code

Summary by CodeRabbit

• New Features

  • Added a posts:settings command for updating provider-specific settings on unpublished DRAFT and QUEUE posts.
  • Settings updates merge with existing values, changing only the provided keys.
  • Added API support for updating post settings.
  • posts:list responses now include each post’s current settings.

• Documentation

  • Updated CLI guides, quick references, API documentation, and usage guidance for managing post settings.

[postiz-contribution]

Contribution-checker quality warning
Heuristic score: 0/100 (low). This is a non-blocking warning surfaced by the project's quality settings.

Heuristics that flagged:

• Excessive emojis in body: 6 emojis (>2)
• Excessive inline code references: 32 inline refs (>3)
• AI watermark phrase: Matched: "Generated with Claude Code"
• Commit message too long: Longest: 559 chars
• Excessive added comments: 9 added comment lines (ratio 0.12)

If this is a genuine contribution, please add detail to your PR description and tighten the diff scope before reviewers look at it.

[coderabbitai]

📝 Walkthrough

Walkthrough

Adds a posts:settings CLI command that parses partial JSON settings and updates unpublished posts through a new API method. Documentation now covers settings retrieval, merge behavior, restrictions, endpoint usage, and examples.

Changes

Post settings management

Layer / File(s)	Summary
Settings command request flow src/api.ts, src/commands/posts.ts, src/index.ts	Registers posts:settings <id>, validates and parses the JSON input, sends it with PUT /public/v1/posts/:id/settings, and reports the result or errors.
Settings workflow documentation README.md, SKILL.md, CHANGELOG.md	Documents current post settings in posts:list, partial merge semantics, DRAFT/QUEUE restrictions, identifier requirements, endpoint usage, and command examples.

Estimated code review effort: 3 (Moderate) | ~20 minutes

Suggested reviewers: nevo-david

Sequence Diagram(s)

sequenceDiagram
  participant User
  participant PostizCLI
  participant PostizAPI
  participant SettingsEndpoint
  User->>PostizCLI: Run posts:settings with post id and JSON settings
  PostizCLI->>PostizAPI: Parse and submit settings
  PostizAPI->>SettingsEndpoint: PUT post settings
  SettingsEndpoint-->>PostizAPI: Return update response
  PostizAPI-->>PostizCLI: Return result
  PostizCLI-->>User: Log success or error

Loading

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title clearly summarizes the main change: adding the posts:settings command to patch a post's provider settings.
Docstring Coverage	✅ Passed	No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

✨ Finishing Touches

📝 Generate docstrings

• Create stacked PR
• Commit on current branch

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch feat/agent-update-posts

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}

[coderabbitai]

🧹 Nitpick comments (1)

src/commands/posts.ts (1)

222-228: 🗄️ Data Integrity & Integration | 🔵 Trivial | 💤 Low value

Ensure parsed JSON is a plain object.

JSON.parse will successfully parse primitives (e.g., 'true' or '"string"') and arrays. Since the downstream api.updatePostSettings contract expects a Record<string, any>, consider validating that the parsed output is a plain object to gracefully reject invalid inputs before making the API request.

💡 Proposed optional refactor

   let settings: any;
   try {
     settings = JSON.parse(args.settings);
+    if (typeof settings !== 'object' || settings === null || Array.isArray(settings)) {
+      throw new Error('Settings must be a JSON object');
+    }
   } catch (error: any) {
     console.error('❌ Failed to parse settings JSON:', error.message);
     process.exit(1);
   }

🤖 Prompt for AI Agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

In `@src/commands/posts.ts` around lines 222 - 228, Validate the result assigned
to settings in the JSON parsing block before calling api.updatePostSettings,
rejecting null, arrays, and non-object primitives so settings remains a plain
object compatible with the Record<string, any> contract. Reuse the existing
parse-error handling to report invalid input and exit without making the API
request.

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Nitpick comments:
In `@src/commands/posts.ts`:
- Around line 222-228: Validate the result assigned to settings in the JSON
parsing block before calling api.updatePostSettings, rejecting null, arrays, and
non-object primitives so settings remains a plain object compatible with the
Record<string, any> contract. Reuse the existing parse-error handling to report
invalid input and exit without making the API request.

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: defaults

Review profile: CHILL

Plan: Pro

Run ID: 81c5a71c-424b-4806-8ae2-5b60b347bb9d

📥 Commits

Reviewing files that changed from the base of the PR and between 41c5a9d and e41dc9b.

📒 Files selected for processing (6)

• CHANGELOG.md
• README.md
• SKILL.md
• src/api.ts
• src/commands/posts.ts
• src/index.ts