typefully-cli 0.1.0__tar.gz

typefully_cli-0.1.0/.github/workflows/ci.yml

@@ -0,0 +1,31 @@
+name: CI
+
+on:
+  push:
+    branches: [main]
+  pull_request:
+    branches: [main]
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python-version: ["3.9", "3.10", "3.11", "3.12", "3.13"]
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Set up Python ${{ matrix.python-version }}
+        uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python-version }}
+
+      - name: Install dependencies
+        run: pip install -e ".[dev]"
+
+      - name: Lint
+        run: ruff check src/ tests/
+
+      - name: Test
+        run: python -m pytest tests/ -v

typefully_cli-0.1.0/.gitignore

@@ -0,0 +1,13 @@
+__pycache__/
+*.py[cod]
+*.egg-info/
+dist/
+build/
+.eggs/
+*.egg
+.venv/
+venv/
+.env
+.ruff_cache/
+.pytest_cache/
+.mypy_cache/

typefully_cli-0.1.0/CHANGELOG.md

@@ -0,0 +1,34 @@
+# Changelog
+
+## 0.1.0 (2026-03-26)
+
+Initial release.
+
+### Commands
+- `config set`, `config show`, `config path` -- manage configuration
+- `me` -- show authenticated user
+- `accounts`, `account-detail` -- list and inspect connected social sets
+- `draft`, `thread` -- create single posts and multi-post threads
+- `get`, `update`, `delete` -- manage existing drafts
+- `drafts` -- list drafts with filtering (status, tag, limit, offset, order)
+- `recent` -- list published posts with date range pagination
+- `tags`, `tag-create` -- list and create tags (auto-created via `--tag`)
+- `upload` -- upload media files (S3 presigned URL + poll)
+- `batch` -- batch create drafts/threads from text file with dry-run support
+
+### Features
+- Agent-first JSON output by default, `--text` for human-readable Rich output
+- Structured error JSON on stderr with exit codes (0/1/2/3)
+- Auth chain: `--api-key` flag > `TYPEFULLY_API_KEY` env var > config file > 1Password
+- Account resolution by name, username, or numeric ID
+- Partial failure handling for delete and batch (exit 3 with both streams)
+- Cross-platform posting: X, LinkedIn, Threads, Bluesky, Mastodon
+- Media filename sanitization (spaces/special chars replaced with `_`)
+- Rate limiting on batch operations (0.3s between requests)
+
+### QA fixes
+- Rich markup escaping for all user/API content in `--text` mode
+- Date validation for `--since` / `--until` (YYYY-MM-DD required)
+- Local limit validation (1-50) for `drafts`, `tags`, `recent`
+- Clean error payloads in partial-failure stdout (no raw upstream bodies)
+- README accuracy: limit caps, date validation, tag/media lifecycle scope

typefully_cli-0.1.0/CLAUDE.md

@@ -0,0 +1,59 @@
+# typefully-cli
+
+## Overview
+
+Python CLI wrapping the Typefully API v2. Agent-first design: JSON output by default, structured errors on stderr, deterministic behavior. 17 Click commands for drafts, threads, batch, media, tags, accounts, config.
+
+## Architecture
+
+```
+src/typefully_cli/
+  cli.py        -- 17 Click commands, shared options, error handler, payload builder
+  client.py     -- httpx wrapper over Typefully API v2 (rate-limited, account resolution)
+  auth.py       -- API key resolution chain: flag > env > config > 1Password
+  config.py     -- TOML config at ~/.config/typefully/config.toml
+  console.py    -- stderr output (status, warnings, errors) via Rich
+  output.py     -- Rich --text formatting (all user content escaped via rich.markup.escape)
+  batch.py      -- Batch file parser (--- separators, === threads, metadata headers)
+  media.py      -- S3 presigned upload + poll workflow
+  exceptions.py -- TypefullyError hierarchy with structured JSON serialization
+```
+
+## Key patterns
+
+- **Output contract:** Success -> `{"ok": true, "data": ...}` on stdout. Errors -> `{"ok": false, "error": {...}}` on stderr. Exit codes: 0 success, 1 input/auth, 2 API, 3 partial failure.
+- **Rich markup safety:** All user/API text in output.py is wrapped with `_esc()` (rich.markup.escape) before printing. Never pass raw API content to `_console.print()`.
+- **Input validation:** Dates via `_validate_date()`, limits via `_validate_limit()`, both raise `TypefullyError(code="invalid_input")` which exits 1.
+- **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.
+
+## Dev setup
+
+```bash
+pip install -e ".[dev]"
+```
+
+## Test and lint
+
+```bash
+python3 -m pytest tests/ -v
+ruff check src/ tests/
+```
+
+## 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
+```
+
+## Conventions
+
+- Python 3.9+ compatibility (no walrus operator, no `match` statements)
+- Line length: 100 chars (ruff)
+- All new CLI commands get the `@shared_options` decorator and `@error_handler`
+- All new output.py functions must escape user content with `_esc()`
+- Tests use Click's CliRunner with mock client/console/config
+- No emojis in code or docs

typefully_cli-0.1.0/CONTRIBUTING.md

@@ -0,0 +1,80 @@
+# Contributing
+
+## Dev setup
+
+```bash
+git clone https://github.com/nicedevelopers/typefully-cli.git
+cd typefully-cli
+pip install -e ".[dev]"
+```
+
+## Run tests
+
+```bash
+python3 -m pytest tests/ -v
+```
+
+## Lint
+
+```bash
+ruff check src/ tests/
+ruff format --check src/ tests/
+```
+
+## Project structure
+
+```
+src/typefully_cli/
+  cli.py        -- Click commands and shared options
+  client.py     -- Typefully API v2 HTTP client
+  auth.py       -- API key resolution chain
+  config.py     -- TOML config management
+  console.py    -- stderr output (Rich)
+  output.py     -- --text mode formatting (Rich, all user content escaped)
+  batch.py      -- Batch file parser
+  media.py      -- Media upload workflow
+  exceptions.py -- Exception hierarchy
+tests/
+  test_cli.py   -- CLI command tests (CliRunner)
+  test_client.py -- Client and account resolution tests
+  test_batch.py -- Batch parser tests
+  test_media.py -- Filename sanitization tests
+  test_output.py -- Rich markup escaping tests
+  test_auth.py  -- Auth chain and redaction tests
+```
+
+## Conventions
+
+- Python 3.9+ (no walrus, no `match`)
+- Line length: 100 chars
+- All CLI commands use `@shared_options` and `@error_handler`
+- All output.py functions escape user content with `_esc()`
+- Tests mock the Typefully API (no live calls in CI)
+- JSON output is the default; `--text` is opt-in
+
+## PR process
+
+1. Fork and create a branch
+2. Make changes, add tests
+3. `python3 -m pytest tests/ -v` -- all tests pass
+4. `ruff check src/ tests/` -- no lint errors
+5. Open a PR with a clear description
+
+## Output contract
+
+Any new command must follow the output contract:
+
+- Success: `{"ok": true, "data": ...}` on stdout (exit 0)
+- Error: `{"ok": false, "error": {"code": "...", "message": "...", "hint": "..."}}` on stderr (exit 1 or 2)
+- Partial failure: success data on stdout + error envelope on stderr (exit 3)
+
+## Auth for testing
+
+Get an API key from [Typefully Settings > API](https://typefully.com/settings/api). Set it locally:
+
+```bash
+typefully config set api_key tf_your_key
+typefully config set default_account YourAccount
+```
+
+Live API tests are not run in CI. For local validation, use a real account.

typefully_cli-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Dheeraj Shah
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

typefully_cli-0.1.0/PKG-INFO

@@ -0,0 +1,263 @@
+Metadata-Version: 2.4
+Name: typefully-cli
+Version: 0.1.0
+Summary: CLI for the Typefully API -- manage drafts, threads, and publishing from the terminal
+Project-URL: Homepage, https://github.com/nicedevelopers/typefully-cli
+Project-URL: Repository, https://github.com/nicedevelopers/typefully-cli
+Project-URL: Issues, https://github.com/nicedevelopers/typefully-cli/issues
+Project-URL: Changelog, https://github.com/nicedevelopers/typefully-cli/blob/main/CHANGELOG.md
+Author: Dheeraj Shah
+License-Expression: MIT
+License-File: LICENSE
+Keywords: cli,social-media,twitter,typefully,x
+Classifier: Development Status :: 4 - Beta
+Classifier: Environment :: Console
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Programming Language :: Python :: 3.10
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Utilities
+Classifier: Typing :: Typed
+Requires-Python: >=3.9
+Requires-Dist: click>=8.0
+Requires-Dist: httpx>=0.24
+Requires-Dist: rich>=13.0
+Requires-Dist: tomli>=2.0; python_version < '3.11'
+Provides-Extra: dev
+Requires-Dist: pytest-httpx>=0.30; extra == 'dev'
+Requires-Dist: pytest>=7.0; extra == 'dev'
+Requires-Dist: ruff; extra == 'dev'
+Description-Content-Type: text/markdown
+
+# typefully-cli
+
+Manage [Typefully](https://typefully.com) drafts, threads, and publishing from your terminal. Built for AI agents. Works great for humans too.
+
+[![Python 3.9+](https://img.shields.io/badge/python-3.9+-blue.svg)](https://github.com/dheeraj-shah/typefully-cli)
+[![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
+
+## Why
+
+- **Automate publishing** -- schedule and publish from CI/CD pipelines, cron jobs, or scripts
+- **Batch create** -- turn a text file into 50 drafts with one command
+- **Agent-native** -- JSON output, structured errors, deterministic exit codes. Designed for Claude Code, LLM agents, and automation
+
+## Install
+
+```bash
+pipx install typefully-cli        # recommended
+uv tool install typefully-cli     # alternative
+pip install typefully-cli          # fallback
+```
+
+## Quick Start
+
+```bash
+# First-time setup (interactive)
+typefully config init
+
+# Or set your API key directly (get it from typefully.com/settings/api)
+typefully config set api_key tf_your_key_here
+
+# Check auth
+typefully me
+
+# Create a draft
+typefully draft "Hello world" --schedule next
+
+# Create a thread
+typefully thread "First post" "Second post" --tag launch
+
+# Batch create from file
+typefully batch posts.txt --schedule next --tag campaign
+
+# Upload media and attach it
+typefully upload photo.jpg
+typefully draft "Check this out" --media <media_id>
+```
+
+## For Humans
+
+Add `--text` to any command for readable output instead of JSON.
+
+```bash
+typefully drafts --text
+typefully recent --text --since 2025-01-01
+typefully get 12345 --text
+```
+
+**Other handy features:**
+
+- `typefully open 12345` -- open a draft in your browser
+- `typefully recent --format csv` -- export published posts to CSV
+- `typefully config init` -- guided first-time setup
+
+**Shell completions** -- add to your shell rc file:
+
+```bash
+# Bash
+eval "$(_TYPEFULLY_COMPLETE=bash_source typefully)"
+
+# Zsh
+eval "$(_TYPEFULLY_COMPLETE=zsh_source typefully)"
+
+# Fish
+_TYPEFULLY_COMPLETE=fish_source typefully | source
+```
+
+## For Agents
+
+Every command writes structured JSON. Success to stdout, errors to stderr. Parse with `jq`, pipe to other tools, or consume directly from an LLM agent.
+
+### Output contract
+
+```bash
+# Success (stdout)
+{"ok": true, "data": ...}
+
+# Error (stderr)
+{"ok": false, "error": {"code": "auth_failed", "message": "...", "hint": "..."}}
+```
+
+### Exit codes
+
+| Code | Meaning | When |
+|------|---------|------|
+| `0` | Success | Everything worked |
+| `1` | Input/auth error | Bad credentials, missing account, invalid input |
+| `2` | API error | Upstream Typefully API failure |
+| `3` | Partial failure | Some items in a batch/delete succeeded, others failed |
+
+### Error codes
+
+| Code | Trigger |
+|------|---------|
+| `auth_failed` | No API key found in flag, env, config, or 1Password |
+| `no_account` | No account specified or account not found |
+| `api_error` | Non-2xx response from Typefully API |
+| `invalid_input` | Bad date format, limit out of range, single-post thread |
+| `batch_parse_error` | Malformed batch file |
+| `media_upload_error` | Upload failed or unsupported format |
+
+### Partial failure (batch/delete)
+
+When some operations succeed and some fail (exit 3):
+- **stdout**: success data with `deleted`/`created` array + `errors` array
+- **stderr**: `partial_failure` error envelope
+
+When all fail (exit 2): nothing on stdout, `all_failed` on stderr.
+
+### Common patterns
+
+```bash
+# Suppress status messages, keep errors
+typefully accounts --quiet 2>/dev/null
+
+# Extract draft IDs
+typefully drafts | jq '.data.results[].id'
+
+# Get error hint on failure
+typefully me 2>/tmp/err.json || jq '.error.hint' /tmp/err.json
+
+# Batch create and log results
+typefully batch posts.txt --output results.json
+```
+
+### Flags for agents
+
+- `--quiet` -- suppress stderr status messages (errors still shown)
+- `--api-key KEY` -- pass API key directly (skips config/env lookup)
+- `--account NAME` -- target a specific account (accepts name, username, or numeric ID)
+
+## Auth
+
+Resolution order: `--api-key` flag > `TYPEFULLY_API_KEY` env var > config file > 1Password.
+
+Get your API key from [Typefully Settings > API](https://typefully.com/settings/api).
+
+```bash
+# Interactive setup
+typefully config init
+
+# Or manually
+typefully config set api_key tf_your_key_here
+typefully config set default_account MyBrand
+
+# Optional: 1Password fallback (requires op CLI)
+typefully config set onepassword_item "Typefully API"
+```
+
+## Commands
+
+All account-scoped commands accept `--api-key`, `--account`, `--text`, `--quiet`.
+
+| Command | Description |
+|---------|-------------|
+| `me` | Current user info |
+| `accounts` | List connected accounts with IDs |
+| `account-detail [NAME]` | Platform details for an account |
+| `draft "text"` | Create a single-post draft |
+| `thread "p1" "p2" ...` | Create a multi-post thread (min 2 posts) |
+| `get ID` | View a draft |
+| `open ID` | Open a draft in the browser |
+| `update ID ["text"]` | Edit a draft (use `===` to separate thread posts) |
+| `delete ID [ID ...]` | Delete one or more drafts |
+| `drafts` | List drafts (`--status`, `--tag`, `--limit 1-50`, `--offset`, `--order`) |
+| `recent` | Published posts (`-n 1-50`, `--since`, `--until`, `--format csv`) |
+| `upload FILE` | Upload media, returns media ID |
+| `tags` | List tags (`--limit 1-50`, `--offset`) |
+| `tag-create "name"` | Create a tag (usually auto-created via `--tag`) |
+| `batch FILE` | Batch create from text file (`--dry-run`, `--output`, `--schedule`, `--tag`) |
+| `config set KEY VALUE` | Set config (api_key, default_account, onepassword_item) |
+| `config init` | Interactive first-time setup |
+| `config show` | Show config (secrets redacted) |
+| `config path` | Print config file path |
+
+**Draft options:** `--schedule ISO|next|now`, `--tag SLUG` (repeatable, auto-created), `--title`, `--media ID`, `--share`, `--reply-to URL`, `--scratchpad`, `--qrt URL`, `--threadify`, `--auto-retweet/--no-auto-retweet`, `--auto-plug/--no-auto-plug`, `--linkedin`, `--threads`, `--bluesky`, `--mastodon`
+
+Run `typefully COMMAND --help` for full option details.
+
+## Batch File Format
+
+Drafts separated by `---`. Thread posts separated by `===`. Optional metadata headers per block.
+
+```
+tag: launch
+schedule: next
+First post of a thread
+===
+Second post
+---
+A standalone draft
+---
+tag: announcement
+schedule: 2026-04-01T10:00:00Z
+Another standalone draft
+```
+
+Supported metadata: `tag`, `schedule`, `title`, `scratchpad`, `media` (comma-separated IDs). See [docs/batch-format.md](docs/batch-format.md) for the full spec.
+
+## Configuration
+
+Config file: `~/.config/typefully/config.toml`
+
+```toml
+[auth]
+api_key = "tf_..."
+# onepassword_item = "Typefully API"
+
+[defaults]
+account = "MyBrand"
+```
+
+## Contributing
+
+See [CONTRIBUTING.md](CONTRIBUTING.md).
+
+## License
+
+MIT