typefully-cli 0.2.1__tar.gz → 0.3.0__tar.gz

{typefully_cli-0.2.1 → typefully_cli-0.3.0}/.github/workflows/ci.yml

@@ -8,13 +8,13 @@ on:
 
 jobs:
   test:
-    runs-on: ubuntu-latest
+    runs-on: ubuntu-22.04  # Python 3.9 remains supported; avoid ubuntu-latest image drift.
     strategy:
       matrix:
         python-version: ["3.9", "3.10", "3.11", "3.12", "3.13"]
 
     steps:
-      - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd  # v6.0.2
+      - uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0  # v7.0.0
 
       - name: Set up Python ${{ matrix.python-version }}
         uses: actions/setup-python@a309ff8b426b58ec0e2a45f0f869d46889d02405  # v6.2.0
@@ -25,7 +25,7 @@ jobs:
         run: pip install -e ".[dev]"
 
       - name: Lint
-        run: ruff check src/ tests/
+        run: ruff check --isolated --select E4,E7,E9,F --target-version py39 --line-length 100 src/ tests/ scripts/
 
       - name: Test
         run: python -m pytest tests/ -v

typefully_cli-0.3.0/.github/workflows/monitor.yml

@@ -0,0 +1,72 @@
+name: Monitor Typefully API & Competitors
+
+on:
+  schedule:
+    - cron: "0 8 * * 1,4"  # Mon & Thu 8am UTC (1:30pm IST)
+  workflow_dispatch: {}
+
+concurrency:
+  group: typefully-upstream-monitor
+  cancel-in-progress: false
+
+permissions:
+  issues: write
+  contents: read
+
+jobs:
+  monitor:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0  # v7.0.0
+
+      - name: Restore cache
+        uses: actions/cache/restore@27d5ce7f107fe9357f9df03efb73ab90386fccae  # v5.0.5
+        with:
+          path: .monitor-cache
+          key: monitor-cache-${{ github.run_id }}
+          restore-keys: monitor-cache-
+
+      - name: Fetch and validate public upstream sources
+        run: python3 scripts/monitor.py
+
+      - name: Report changes or degraded monitoring
+        env:
+          GH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+        run: |
+          python3 - <<'PYTHON'
+          import json
+          import subprocess
+          from pathlib import Path
+
+          cache = Path(".monitor-cache")
+          result = json.loads((cache / "result.json").read_text())
+          if result["report_needed"]:
+              # A stable title deduplicates the same unresolved change/failure.
+              issues = json.loads(subprocess.check_output([
+                  "gh", "issue", "list", "--state", "open", "--search",
+                  result["fingerprint"] + " in:title",
+                  "--json", "title", "--limit", "100",
+              ], text=True))
+              if not any(issue["title"] == result["title"] for issue in issues):
+                  subprocess.run([
+                      "gh", "issue", "create", "--title", result["title"],
+                      "--body-file", str(cache / "report.md"),
+                  ], check=True)
+          subprocess.run(["python3", "scripts/monitor.py", "--commit"], check=True)
+          PYTHON
+
+      - name: Save cache
+        uses: actions/cache/save@27d5ce7f107fe9357f9df03efb73ab90386fccae  # v5.0.5
+        with:
+          path: .monitor-cache
+          key: monitor-cache-${{ github.run_id }}
+
+      - name: Fail visibly on degraded monitoring
+        run: |
+          python3 - <<'PYTHON'
+          import json
+          from pathlib import Path
+          result = json.loads(Path(".monitor-cache/result.json").read_text())
+          if result["failed"]:
+              raise SystemExit("Upstream fetch failed; see monitoring issue and result.json")
+          PYTHON

{typefully_cli-0.2.1 → typefully_cli-0.3.0}/.github/workflows/publish.yml

@@ -11,7 +11,7 @@ jobs:
       id-token: write  # trusted publishing
 
     steps:
-      - uses: actions/checkout@de0fac2e4500dabe0009e67214ff5f5447ce83dd  # v6.0.2
+      - uses: actions/checkout@9c091bb21b7c1c1d1991bb908d89e4e9dddfe3e0  # v7.0.0
 
       - name: Set up Python
         uses: actions/setup-python@a309ff8b426b58ec0e2a45f0f869d46889d02405  # v6.2.0

{typefully_cli-0.2.1 → typefully_cli-0.3.0}/CHANGELOG.md

@@ -1,5 +1,16 @@
 # Changelog
 
+## 0.3.0 (2026-10-29)
+
+- Add schema-backed `draft-payload` request-file input with offline validation, per-post fields and null/false clearing; keep `--json` as output-only.
+- Add X reply/subscriber/community flags, LinkedIn first-comment/reshare fields, upload alt text and media metadata updates.
+- Follow social-set pagination, accept repeated tag filters and reject negative offsets; document every public API operation and unverified MCP/product-only boundaries.
+
+
+- Repair upstream monitoring: validate official public sources, expose fetch failures, deduplicate reports, and advance baselines only after successful reporting.
+- Pin CI to Ubuntu 22.04 to retain Python 3.9 compatibility; isolate Fish completion tests from the real home directory.
+- Extend `--quote-post-url` / `--qrt` to the documented Threads, Bluesky, Mastodon and Substack quote targets.
+
 ## 0.2.1 (2026-08-21)
 
 - Fix trusted PyPI publishing workflow action pin.

{typefully_cli-0.2.1 → typefully_cli-0.3.0}/CLAUDE.md

@@ -2,13 +2,15 @@
 
 ## Overview
 
-Python CLI wrapping the Typefully API v2. Agent-first design: JSON output by default, structured errors on stderr, deterministic behavior. 24 Click commands for drafts, threads, batch, media, analytics, queue, LinkedIn, tags, accounts, config, completions.
+Python CLI wrapping the Typefully API v2. Agent-friendly structured JSON output with `--json`, structured errors on stderr, and configurable text output. See `skills/typefully-cli/SKILL.md` for current agent usage and `docs/upstream-parity.md` for evidence and limitations.
 
 ## Architecture
 
 ```
 src/typefully_cli/
-  cli.py        -- 24 Click commands, shared options, error handler, payload builder
+  cli.py        -- Click commands, shared options, error handler, payload builder
+  payloads.py   -- Explicit JSON request input, local schema validation, media metadata
+  request-schemas.json -- Reviewed public create/update schema snapshot
   client.py     -- httpx wrapper over Typefully API v2 (rate-limited, account resolution)
   completions.py -- Shell completions install/show (bash/zsh/fish)
   auth.py       -- API key resolution chain: flag > env > config > 1Password
@@ -29,7 +31,7 @@ src/typefully_cli/
 - **Timezone conversion:** Config `timezone` (IANA name) converts naive schedule datetimes to UTC before API call. Already-tz-aware values pass through unchanged.
 - **Partial failure:** Delete and batch loops catch per-item errors. `_handle_multi_result()` handles the 3-branch contract (all succeed / partial / all fail).
 - **Error sanitization:** `APIError.user_message` property strips raw upstream bodies from stdout payloads. Full details stay on stderr.
-- **API parity:** Tracks all Typefully API v2 endpoints including analytics, queue management, and LinkedIn org resolution.
+- **API parity:** Map each public operation in docs/upstream-parity.md. Do not claim exhaustive MCP parity; analytics and legacy convenience fields are not verified by the current public schema.
 
 ## Dev setup
 
@@ -41,19 +43,15 @@ pip install -e ".[dev]"
 
 ```bash
 python3 -m pytest tests/ -v
-ruff check src/ tests/
+ruff check --isolated --select E4,E7,E9,F --target-version py39 --line-length 100 src/ tests/ scripts/
 ```
 
 ## Auth for live testing
 
-Config at `~/.config/typefully/config.toml`. Test account: BungeeCEO.
-
-```bash
-typefully config set api_key tf_...
-typefully config set default_account BungeeCEO
-typefully config set default_platforms x,linkedin
-typefully config set timezone Asia/Kolkata
-```
+Use existing authorized access from environment/config; never assume an account
+named in documentation is a sandbox. No cloud credential is bundled with this repo.
+Use local `--validate-only` and mocked tests first. Live test writes need explicit
+scope and a verified social set; never publish as part of maintenance tests.
 
 ## Conventions
 

{typefully_cli-0.2.1 → typefully_cli-0.3.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.5
 Name: typefully-cli
-Version: 0.2.1
+Version: 0.3.0
 Summary: CLI for the Typefully API -- manage drafts, threads, and publishing from the terminal
 Project-URL: Homepage, https://github.com/dheeraj-shah/typefully-cli
 Project-URL: Repository, https://github.com/dheeraj-shah/typefully-cli
@@ -37,8 +37,8 @@ Description-Content-Type: text/markdown
 
 Publish to X, LinkedIn, Bluesky, Threads, Mastodon, Substack Notes, and X Articles from your terminal. Goes from idea to post without opening a browser.
 
-[![PyPI](https://img.shields.io/pypi/v/typefully-cli?v=1)](https://pypi.org/project/typefully-cli/)
-[![Python 3.9+](https://img.shields.io/pypi/pyversions/typefully-cli?v=1)](https://pypi.org/project/typefully-cli/)
+[![PyPI](https://img.shields.io/pypi/v/typefully-cli.svg)](https://pypi.org/project/typefully-cli/)
+[![Python 3.9+](https://img.shields.io/pypi/pyversions/typefully-cli.svg)](https://pypi.org/project/typefully-cli/)
 [![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
 
 ## Why
@@ -338,3 +338,41 @@ See [CONTRIBUTING.md](CONTRIBUTING.md).
 ## License
 
 MIT
+
+## Upstream compatibility maintenance
+
+The public-source monitor opens issues for upstream changes or failed checks; it does not
+implement or merge updates. See the [source and capability baseline](docs/upstream-parity.md)
+for monitored sources, known limits, and how maintenance coordinates with Dependabot.
+
+Native quotes route to the matching selected platform (the existing `--qrt` alias still works):
+
+```sh
+typefully draft "My take" --platform bluesky --quote-post-url https://bsky.app/profile/example.com/post/abc
+```
+
+Threads, Bluesky, Mastodon and Substack quotes apply to the first new post. Existing X
+thread behavior is retained. See [quote compatibility notes](docs/quote-parity.md).
+
+### Complete request input and media alt text
+
+`draft-payload create --file draft.json --validate-only` validates the reviewed public
+API schema offline. Remove `--validate-only` and select `--account` to submit.
+Use `draft-payload update --draft-id ID --file update.json` for per-post settings,
+explicit null/false clearing, or advanced fields. This is **request input**;
+`--json` on existing commands only controls output. The new advanced commands
+always emit JSON. Platform arrays replace content: retain posts/comment markers
+and settings you want to keep. `publish_at: "now"` really requests publication.
+
+`upload image.png --alt-text "Description"` sets alt text before attachment.
+`media-update MEDIA_ID --alt-text "New description"` or `--clear-alt-text` changes
+stored media; previously attached drafts keep their existing metadata snapshot.
+See [the full public capability matrix and remaining MCP boundaries](docs/upstream-parity.md).
+
+### Agent skill
+
+The repository's [Typefully CLI skill](skills/typefully-cli/SKILL.md) describes these
+Python CLI commands, local validation and authorization boundaries. It is distinct
+from Typefully's official JavaScript agent skill. Check the installed CLI's help:
+maintenance-branch features are not available in an older published package until
+an approved release is made.

{typefully_cli-0.2.1 → typefully_cli-0.3.0}/README.md

@@ -2,8 +2,8 @@
 
 Publish to X, LinkedIn, Bluesky, Threads, Mastodon, Substack Notes, and X Articles from your terminal. Goes from idea to post without opening a browser.
 
-[![PyPI](https://img.shields.io/pypi/v/typefully-cli?v=1)](https://pypi.org/project/typefully-cli/)
-[![Python 3.9+](https://img.shields.io/pypi/pyversions/typefully-cli?v=1)](https://pypi.org/project/typefully-cli/)
+[![PyPI](https://img.shields.io/pypi/v/typefully-cli.svg)](https://pypi.org/project/typefully-cli/)
+[![Python 3.9+](https://img.shields.io/pypi/pyversions/typefully-cli.svg)](https://pypi.org/project/typefully-cli/)
 [![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
 
 ## Why
@@ -303,3 +303,41 @@ See [CONTRIBUTING.md](CONTRIBUTING.md).
 ## License
 
 MIT
+
+## Upstream compatibility maintenance
+
+The public-source monitor opens issues for upstream changes or failed checks; it does not
+implement or merge updates. See the [source and capability baseline](docs/upstream-parity.md)
+for monitored sources, known limits, and how maintenance coordinates with Dependabot.
+
+Native quotes route to the matching selected platform (the existing `--qrt` alias still works):
+
+```sh
+typefully draft "My take" --platform bluesky --quote-post-url https://bsky.app/profile/example.com/post/abc
+```
+
+Threads, Bluesky, Mastodon and Substack quotes apply to the first new post. Existing X
+thread behavior is retained. See [quote compatibility notes](docs/quote-parity.md).
+
+### Complete request input and media alt text
+
+`draft-payload create --file draft.json --validate-only` validates the reviewed public
+API schema offline. Remove `--validate-only` and select `--account` to submit.
+Use `draft-payload update --draft-id ID --file update.json` for per-post settings,
+explicit null/false clearing, or advanced fields. This is **request input**;
+`--json` on existing commands only controls output. The new advanced commands
+always emit JSON. Platform arrays replace content: retain posts/comment markers
+and settings you want to keep. `publish_at: "now"` really requests publication.
+
+`upload image.png --alt-text "Description"` sets alt text before attachment.
+`media-update MEDIA_ID --alt-text "New description"` or `--clear-alt-text` changes
+stored media; previously attached drafts keep their existing metadata snapshot.
+See [the full public capability matrix and remaining MCP boundaries](docs/upstream-parity.md).
+
+### Agent skill
+
+The repository's [Typefully CLI skill](skills/typefully-cli/SKILL.md) describes these
+Python CLI commands, local validation and authorization boundaries. It is distinct
+from Typefully's official JavaScript agent skill. Check the installed CLI's help:
+maintenance-branch features are not available in an older published package until
+an approved release is made.

typefully_cli-0.3.0/docs/quote-parity.md

@@ -0,0 +1,79 @@
+# Quote-post API parity (verified 2026-10-29)
+
+`draft`, `thread`, and `update` accept `--quote-post-url` (existing alias `--qrt`)
+for X, Threads, Bluesky, Mastodon, and Substack Notes. The URL chooses which
+selected platform receives the quote. LinkedIn reposts are a separate feature.
+
+```sh
+typefully draft "Worth reading" --platform bluesky,linkedin \
+  --quote-post-url https://bsky.app/profile/example.bsky.social/post/abc
+typefully update DRAFT_ID --platform mastodon \
+  --quote-post-url https://mastodon.social/@example/123
+```
+
+Only Bluesky receives the quote in the first example. The second keeps existing
+text. Replacing text replaces posts, so provide the quote flag again to retain a
+quote. Append preserves existing posts and attaches the quote to new content.
+Substack supports one post and cannot append to an existing note.
+
+Known hosts route to their own platform; custom publication paths `/note/c-...`
+and `/p/...` route to Substack when selected. Other hosts prefer Mastodon when
+selected, otherwise the sole quote-capable target. Ambiguous/mismatched targets
+fail locally. The API still validates whether a particular post can be quoted.
+
+For compatibility, X quotes continue to apply to every supplied thread post.
+New quote platforms apply the quote to the first supplied post only. Metadata-only
+quote changes do not rewrite unrelated platforms. No real posts are created by
+the tests.
+
+## Evidence and boundaries
+
+- [API reference](https://typefully.com/docs/api): request schemas for XPost,
+  ThreadsPost, BlueskyPost, MastodonPost and SubstackPost expose `quote_post_url`.
+- [Official quote guide](https://github.com/typefully/agent-skills/blob/main/skills/typefully/references/quotes.md)
+- [Official routing implementation](https://github.com/typefully/agent-skills/blob/main/skills/typefully/scripts/typefully.js):
+  `classifyQuoteUrl` and `resolveQuotePlatform`.
+- [Product changelog](https://typefully.com/changelog): October 9 expanded quotes.
+
+## X and LinkedIn platform fields
+
+The following additive options are available on `draft`, `thread`, and `update`:
+
+| Option | API field and behavior |
+| --- | --- |
+| `--reply-settings following\|mentionedUsers\|subscribers\|verified\|null` | X post `reply_settings`; `null` restores the default reply audience |
+| `--subscribers-only` / `--no-subscribers-only` | X post `subscribers_only`; omission does not change the field |
+| `--share-with-followers` / `--no-share-with-followers` | X `settings.share_with_followers`; requires `--community` or an existing community on an update |
+| `--linkedin-first-comment TEXT` | LinkedIn `settings.first_comment`, at most 1250 characters; `null` or an empty string clears it |
+| `--linkedin-reshare-target URL_OR_URN` | First supplied LinkedIn post `linkedin_reshare_target`, at most 2048 characters; `null` clears it |
+
+LinkedIn reshares accept a full post URL or canonical `urn:li:share:...`,
+`urn:li:ugcPost:...`, or `urn:li:groupPost:...`. Upstream validates and normalizes
+the target; the CLI enforces the documented length limit. Responses expose
+`linkedin_reshare_urn`, which the CLI translates back to the writable
+`linkedin_reshare_target` when preserving existing content.
+
+```sh
+typefully draft "Community update" --platform x --community 123 \
+  --no-share-with-followers --reply-settings following
+typefully update DRAFT_ID --platform linkedin --linkedin-first-comment "More details here"
+typefully update DRAFT_ID --platform x --reply-settings null --no-subscribers-only
+```
+
+X post options apply to all supplied posts; LinkedIn reposts apply to the first
+supplied post. Append applies post options only to newly appended posts and
+merges settings without losing existing values. Metadata-only updates retain
+text (including comment anchors), media, quotes, restrictions, and settings;
+unrelated platforms are not rewritten. Text replacement continues to replace
+posts wholesale. Wrong-platform options, oversized values, and community share
+options without a community fail locally before the draft update request.
+Media plus platform options is handled in the same content-preserving update
+path. A media-only update without `--platform` retains the historical X default.
+
+These fields are verified against `XPost`, `XSettings`, `LinkedInPost`, and
+`LinkedInSettings` in the public [OpenAPI reference](https://typefully.com/docs/api),
+not inferred from MCP or product UI capabilities.
+
+Polls were announced in the product changelog, but no poll request schema was
+found in the current API reference, so no API support is inferred. The MCP OAuth
+connector setup is transport/auth functionality, not an API-key CLI parity gap.

typefully_cli-0.3.0/docs/upstream-parity.md

@@ -0,0 +1,133 @@
+# Typefully upstream parity baseline
+
+Reviewed 2026-10-29 against CLI 0.2.1 / main `82fd5948`.
+
+## Sources and limits
+
+- [Public API reference](https://typefully.com/docs/api): endpoint and payload authority.
+- [Official agent skills](https://github.com/typefully/agent-skills/tree/main/skills/typefully): usage and platform references. The executable reference is `skills/typefully/scripts/typefully.js`, not `/scripts/typefully.js`.
+- [Official MCP guide](https://support.typefully.com/en/articles/13128440-typefully-mcp-server): public capability overview. The MCP endpoint requires authentication and the MCP initialization protocol; unauthenticated `tools/list` is not a valid inventory.
+- [Product changelog](https://typefully.com/changelog): discovery of changes, not evidence that every product feature is exposed through the public API.
+
+This is not a claim of exhaustive behavioral parity. An authenticated MCP inventory was subsequently verified below. Do not guess endpoints from product announcements. The previous CLI `--json` flag controlled output only; it was not request-body passthrough. This maintenance adds an explicit `draft-payload` command, described below.
+
+## Monitor repair
+
+The previous workflow treated the API root greeting as an OpenAPI schema, used a missing agent-skills path, attempted unauthenticated MCP enumeration, and swallowed fetch failures. It could therefore report no changes despite incomplete coverage.
+
+The replacement monitors validated public API documentation, official agent source, public MCP documentation, and the changelog. It ignores scripts/styles in HTML to reduce dynamic-build noise. It does **not** label documentation as an OpenAPI schema, enumerate private MCP tools, require a new credential, or claim a successful fetch proves semantic feature parity. The old npm probe is removed: the official skill source is the maintained reference, and a package version was not established as an authoritative API contract.
+
+First valid reads establish a baseline. Changes or failures create a deduplicated issue. Failures preserve the last good source baseline and mark the workflow failed. Baselines advance only after reporting succeeds, so an issue-delivery failure does not silently lose a change. The existing Monday/Thursday cron and `issues: write` / `contents: read` permissions are unchanged; this remains issue-only automation.
+
+Run public-source validation without creating an issue:
+
+```sh
+python3 scripts/monitor.py --cache-dir /tmp/typefully-monitor-check
+```
+
+This performs public GET requests only. Tests use injected fake responses and never call Typefully accounts.
+
+## Maintenance coordination
+
+Dependabot's existing five open Actions-upgrade PRs (#9, #11, #12, #13, #14 at review time) are not duplicated here. CI is pinned to Ubuntu 22.04 to keep the advertised Python 3.9–3.13 matrix working rather than silently dropping Python 3.9 after `ubuntu-latest` moved to Ubuntu 26.04.
+
+Publishing remains unchanged and is triggered by `v*` tags. Maintenance branches and draft PRs must not create tags, publish packages, merge, or mutate real Typefully content as tests.
+
+
+## Complete public API capability matrix (2026-10-29 snapshot)
+
+The API page embeds an OpenAPI 3.1 specification: **24 HTTP operations across 16 paths**. The following maps every operation, not just newly changed features. Paths below are relative to `/v2`; `S` denotes `/social-sets/{social_set_id}` and `D` denotes `S/drafts/{draft_id}`.
+
+| Public API operation(s) | CLI surface | Evidence / qualification |
+| --- | --- | --- |
+| GET `/me` | `me` | Existing |
+| GET `/social-sets` | `accounts`, account resolution | Now follows all 50-item pages instead of truncating at 50 |
+| GET `S/` | `account` | Existing detail command |
+| GET / POST `S/drafts` | `drafts`; `draft`, `thread`, `batch`, `draft-payload create` | Repeated `--tag` filters supported; JSON input covers per-platform/per-post fields |
+| GET / PATCH / DELETE `D` | `get`; `update`, `publish`, `schedule`, `plan`, `draft-payload update`; `delete` | Explicit JSON null/false/empty arrays survive unchanged; server content/comment rules still apply |
+| POST `S/media/upload` | `upload --alt-text` | Alt text up to 1000 characters, including empty text |
+| GET / PATCH `S/media/{media_id}` | `media-status`; **new `media-update`** | Patch supports replacement and explicit null clearing |
+| GET / POST `S/tags` | `tags`, `tag-create` | Existing |
+| GET / PUT `S/queue/schedule` | `queue-schedule get/set` | Existing |
+| GET `S/queue` | `queue` | Existing |
+| GET `S/linkedin/organizations/resolve` | `linkedin-resolve` | Existing |
+| GET / POST `D/comment-threads` | `comments list/create` | Existing; pagination bounds checked |
+| POST `D/comment-threads/{thread}/comments` | `comments reply` | Existing |
+| POST `D/comment-threads/{thread}/resolve` | `comments resolve` | Existing |
+| PATCH / DELETE `D/comment-threads/{thread}/comments/{comment}` | `comments update/delete --comment-id` | Existing |
+| DELETE `D/comment-threads/{thread}` | `comments delete` without comment ID | Existing |
+
+This is **operation coverage**, not proof that every account-dependent behavior has been exercised against the live service. All maintenance tests are offline/mocked.
+
+### Request fields and platform behavior
+
+- New dedicated create/thread/update flags: X `reply_settings` (`following`, `mentionedUsers`, `subscribers`, `verified`, or `null`), `subscribers_only` including false; community `share_with_followers` including false; LinkedIn `first_comment` (1250 characters, null/empty clears) and `linkedin_reshare_target` (URL or URN, 2048 characters, null clears).
+- Response `linkedin_reshare_urn` is converted to writable `linkedin_reshare_target` when updating copied posts. Other platform posts, settings and comment-marked text are preserved for metadata-only updates.
+- Quotes: X, Threads, Bluesky, Mastodon and Substack supported; LinkedIn uses its separate reshare field, not `quote_post_url`.
+- The explicit request-input command covers the reviewed schema for all **seven** platform keys: X, LinkedIn, Threads, Bluesky, Mastodon, Substack, and X Article. It preserves per-post distinctions, settings, media, tags, scheduling/planning, null-clearing, false toggles, and `force_overwrite_comments` on update. It does not automatically remove comment markers or overwrite comments.
+- `src/typefully_cli/request-schemas.json` is the API page's transitive create/update schema snapshot, with source and retrieval date. The dependency-free validator implements only that snapshot's finite keyword vocabulary; regression tests reject unrecognized future schema keywords. Type, required/unknown fields, conditional fields, lengths, enums and timezone-aware date-time shape are checked locally. Server-side eligibility, URL/URN validity, supported media/platform combinations, scheduling limits and account permissions remain authoritative.
+- Media alt text is snapshotted when attached to a draft. Updating stored media does not silently rewrite already-attached drafts. Intentionally resend draft content to refresh an attachment after updating its media.
+- Existing `--json` remains an **output** switch. New request input uses `--file`, including stdin (`-`). It is explicit, not an arbitrary HTTP escape hatch.
+
+```sh
+# Pure local validation: no account, token or network required.
+typefully draft-payload create --file draft.json --validate-only
+# These commands mutate your chosen account only when explicitly invoked:
+typefully draft-payload create --file draft.json --account my-account
+typefully draft-payload update --draft-id 123 --file update.json --account my-account
+typefully media-update MEDIA_ID --alt-text "Descriptive image text" --account my-account
+typefully media-update MEDIA_ID --clear-alt-text --account my-account
+```
+
+Update payloads containing platform post arrays replace content, rather than magically merging missing posts. Include content/settings to retain. `publish_at: "now"` is a real publication request; `plan_at` is inert planning. Local validation cannot certify that a request will succeed on every social network.
+
+### Remaining boundaries, not fabricated parity
+
+1. **Authenticated MCP inventory verified, behavior bounded.** On 2026-10-29, an explicitly authorized one-off local check using existing authentication initialized server `typefully 1.0.0` (protocol `2025-03-26`) and retrieved all 24 tools, with no continuation page. Every tool maps to the public operation matrix above; no additional MCP-only endpoint was found. Draft create/edit bodies match the reviewed public schemas apart from MCP-only `confirm_publish` (default false, marked `x-mcp-only`), which requires explicit confirmation for immediate publication. This field must not be sent to REST. No MCP tools were invoked. Inventory inspection is not an all-platform publishing test.
+2. **Polls:** product announcements are not a writable public API contract. No poll request schema was found in this snapshot, so no guessed endpoint or flags were added.
+3. **Analytics / follower analytics:** existing CLI routes are preserved, but absent from this particular 24-operation public snapshot. Their current contract is unverified here, not automatically declared supported or removed.
+4. **Webhook management:** a webhook event payload schema exists, but no public management operations in the snapshot. Do not infer create/delete subscription endpoints.
+5. **Legacy `threadify` / auto-retweet / auto-plug convenience fields:** preserved for compatibility, but not in the reviewed draft request schema. New `draft-payload` rejects undocumented fields instead of pretending they are supported.
+6. **Defaults and syntax:** the Python CLI retains its established account/default-platform resolution instead of copying the official agent script's interface. Equivalent supported capabilities do not require identical flags or defaults.
+7. **Product/media rollout differences:** product announcements (for example Substack video) can outpace platform guidance. Do not guarantee an account/platform media combination solely from a changelog item.
+
+Weekly maintenance must re-check this entire matrix, implement verified gaps even if they predate the latest diff, update the request snapshot/validator together, and leave unsupported or inaccessible capabilities explicitly marked. A failed source read is degraded monitoring, not evidence of no change.
+
+
+### Authenticated MCP comparison
+
+Inventory names: `get_me`, `list_social_sets`, `get_social_set_details`, `list_drafts`,
+`create_draft`, `get_draft`, `delete_draft`, `edit_draft`, `create_media_upload`,
+`get_media_status`, `update_media`, `list_tags`, `create_tag`, `get_queue_schedule`,
+`queue_put_queue_schedule`, `get_queue`,
+`linkedin_resolve_linkedin_organization_from_url`, `list_comments`, `create_comment`,
+`comments_add_comment_to_thread`, `comments_resolve_thread`, `delete_comment`,
+`update_comment`, `delete_thread`.
+
+Remaining interface/validation differences are explicit rather than silently
+labelled full parity: MCP exposes social-set limit/offset while CLI auto-paginates;
+MCP requires queue start/end dates whereas CLI can defer missing-date errors to the
+server; several comment/tag length, UUID, and queue-rule constraints are validated
+server-side rather than exhaustively by existing CLI convenience commands. Analytics,
+follower analytics and draft `content_filter` were absent from this MCP inventory.
+
+The MCP read-only annotation on `get_queue_schedule` does **not** imply zero state
+changes: its description says an absent schedule is initialized with defaults.
+Exclude that operation from strictly non-mutating checks. MCP deletion annotations
+also do not establish recoverability or replace applicable user authorization.
+
+### Bounded live smoke test
+
+On 2026-10-29, the user explicitly approved a one-off test using existing local
+credentials and selected the destination account. Exact CLI commit
+`fc19975c755661ba48d92d9d4f11ce7ce6ae31fd` created one labelled private, unscheduled
+X draft (201), read it (200), updated dummy text and `reply_settings: "following"`
+(200), verified the update (200), deleted only the new draft (204), and verified
+absence (404). Readbacks remained draft-only, with null scheduling/publication
+fields and no public share URL. No test draft remains. No credentials or private
+account receipts are included in this repository.
+
+This proves that bounded X draft lifecycle against the live service, not live
+publishing, scheduling, media upload, other platforms, or MCP tool execution.
+The normal maintenance workflow remains cloud-only; the local test was separately
+approved because existing authentication was available there, not in the cloud.

{typefully_cli-0.2.1 → typefully_cli-0.3.0}/pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "typefully-cli"
-version = "0.2.1"
+version = "0.3.0"
 description = "CLI for the Typefully API -- manage drafts, threads, and publishing from the terminal"
 readme = "README.md"
 license = "MIT"