typefully-cli 0.1.0__py3-none-any.whl

typefully_cli/output.py

@@ -0,0 +1,188 @@
+"""Output formatting: JSON envelope (default) and Rich human-readable (--text)."""
+
+from __future__ import annotations
+
+from rich.console import Console as RichConsole
+from rich.markup import escape as _esc
+from rich.table import Table
+
+
+_console = RichConsole()
+
+
+def print_user(data: dict) -> None:
+    _console.print(f"  Name:  {_esc(data.get('name', '?'))}")
+    _console.print(f"  Email: {_esc(data.get('email', '?'))}")
+    _console.print(f"  Key:   {_esc(data.get('api_key_label', '?'))}")
+
+
+def print_accounts(results: list[dict]) -> None:
+    table = Table(title="Social Sets")
+    table.add_column("Username")
+    table.add_column("ID", style="dim")
+    table.add_column("Name")
+    table.add_column("Platforms")
+    for s in results:
+        platforms = ", ".join(s.get("platforms", {}).keys()) if isinstance(s.get("platforms"), dict) else ""
+        table.add_row(
+            _esc(s.get("username", "?")),
+            str(s.get("id", "?")),
+            _esc(s.get("name", "")),
+            _esc(platforms),
+        )
+    _console.print(table)
+
+
+def print_account_detail(data: dict) -> None:
+    _console.print(f"  Name: {_esc(data.get('name', '?'))}")
+    _console.print(f"  ID:   {data.get('id', '?')}")
+    team = data.get("team")
+    if team:
+        _console.print(f"  Team: {_esc(team.get('name', '?'))} (ID: {team.get('id', '?')})")
+    platforms = data.get("platforms", {})
+    if platforms:
+        _console.print("\n  Connected platforms:")
+        for name, info in platforms.items():
+            if not info or not isinstance(info, dict):
+                continue
+            username = info.get("username", "?")
+            profile = info.get("profile_url", "")
+            _console.print(f"    \\[{_esc(name.upper())}] @{_esc(username)}")
+            if profile:
+                _console.print(f"      {profile}")
+
+
+def print_draft(data: dict) -> None:
+    _console.print(f"  ID:     {data.get('id', '?')}")
+    _console.print(f"  Status: {data.get('status', '?')}")
+    for key in ("created_at", "updated_at", "draft_title", "scheduled_date", "published_at"):
+        val = data.get(key, "")
+        if val:
+            label = key.replace("_", " ").title()
+            _console.print(f"  {label}: {_esc(str(val)[:19])}")
+    tags = data.get("tags", [])
+    if tags:
+        tag_str = ", ".join(
+            t.get("name", t.get("slug", "?")) if isinstance(t, dict) else str(t)
+            for t in tags
+        )
+        _console.print(f"  Tags: {_esc(tag_str)}")
+    for url_key in ("share_url", "private_url", "x_published_url", "linkedin_published_url"):
+        val = data.get(url_key, "")
+        if val:
+            label = url_key.replace("_", " ").title()
+            _console.print(f"  {label}: {val}")
+    scratchpad = data.get("scratchpad_text", "")
+    if scratchpad:
+        _console.print(f"  Scratchpad: {_esc(scratchpad)}")
+    # Posts per platform
+    for platform, pdata in data.get("platforms", {}).items():
+        if not isinstance(pdata, dict) or not pdata.get("enabled"):
+            continue
+        posts = pdata.get("posts", [])
+        _console.print(f"\n  \\[{_esc(platform.upper())}] ({len(posts)} post{'s' if len(posts) != 1 else ''})")
+        for i, p in enumerate(posts):
+            if i > 0:
+                _console.print("    ---")
+            _console.print(f"    {_esc(p.get('text', '(no text)'))}")
+
+
+def print_draft_short(data: dict) -> None:
+    _console.print(f"  ID:     {data.get('id', '?')}")
+    _console.print(f"  Status: {data.get('status', '?')}")
+    share_url = data.get("share_url", "")
+    if share_url:
+        _console.print(f"  Share:  {share_url}")
+    private_url = data.get("private_url", "")
+    if private_url:
+        _console.print(f"  Edit:   {private_url}")
+
+
+def print_drafts_list(data: dict) -> None:
+    count = data.get("count", "?")
+    results = data.get("results", [])
+    if not results:
+        _console.print("  (none)")
+        return
+    _console.print(f"  Showing {len(results)} of {count} total\n")
+    for d in results:
+        status = d.get("status", "?")
+        # Get text from platforms or preview
+        text = ""
+        platforms = d.get("platforms", {})
+        if isinstance(platforms, dict) and "x" in platforms:
+            posts = platforms.get("x", {}).get("posts", [])
+            if posts:
+                text = posts[0].get("text", "")
+        if not text:
+            text = d.get("preview", "(no text)")
+        preview = text[:80] + "..." if len(text) > 80 else text
+        draft_id = d.get("id", "?")
+        tags = d.get("tags", [])
+        tag_str = ""
+        if tags:
+            tag_str = " " + " ".join(
+                f"#{t['name'] if isinstance(t, dict) else t}" for t in tags
+            )
+        _console.print(f"  \\[{_esc(status)}] {_esc(preview)} (ID: {draft_id}){_esc(tag_str)}")
+
+
+def print_recent(posts: list[dict]) -> None:
+    if not posts:
+        _console.print("  (none)")
+        return
+    for d in posts:
+        pub = d.get("published_at", "?")[:10]
+        draft_id = d.get("id", "?")
+        text = ""
+        platforms = d.get("platforms", {})
+        if isinstance(platforms, dict) and "x" in platforms:
+            pp = platforms.get("x", {}).get("posts", [])
+            if pp:
+                text = "\n  ---\n".join(p.get("text", "") for p in pp)
+        if not text:
+            text = d.get("preview", "(no text)")
+        x_url = d.get("x_published_url", "")
+        _console.print(f"--- \\[{_esc(pub)}] (ID: {draft_id}) ---")
+        _console.print(f"  {_esc(text)}")
+        if x_url:
+            _console.print(f"  -> {x_url}")
+        _console.print()
+
+
+def print_tags(results: list[dict]) -> None:
+    if not results:
+        _console.print("  (none)")
+        return
+    for t in results:
+        _console.print(f"  {_esc(t.get('name', '?'))} (slug: {_esc(t.get('slug', '?'))})")
+
+
+def print_batch_dry_run(entries: list[dict]) -> None:
+    for i, e in enumerate(entries):
+        n = len(e.get("posts", []))
+        label = "thread" if n > 1 else "single"
+        preview = _esc(e["posts"][0][:60]) if e.get("posts") else "(empty)"
+        sched = e.get("schedule") or "(no schedule)"
+        tags = ", ".join(e.get("tags", [])) or "(no tags)"
+        _console.print(f"  \\[{i+1}] {label} ({n} post{'s' if n > 1 else ''}) | {_esc(sched)} | {_esc(tags)}")
+        _console.print(f"      {preview}")
+        _console.print()
+
+
+def print_batch_result(result: dict) -> None:
+    total = result.get("total", 0)
+    created = result.get("created", [])
+    errors = result.get("errors", [])
+    _console.print(f"\n  Done: {len(created)} created, {len(errors)} errors (of {total} total)")
+
+
+def print_delete_result(result: dict) -> None:
+    deleted = result.get("deleted", [])
+    errors = result.get("errors", [])
+    _console.print(f"  Deleted: {len(deleted)}, Errors: {len(errors)}")
+
+
+def print_upload_result(data: dict) -> None:
+    _console.print(f"  Media ID: {data.get('media_id', '?')}")
+    _console.print(f"  Status:   {data.get('status', '?')}")

typefully_cli-0.1.0.dist-info/METADATA

@@ -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

typefully_cli-0.1.0.dist-info/RECORD

@@ -0,0 +1,16 @@
+typefully_cli/__init__.py,sha256=uxVKJuwcPuay8W6wYSM3QQ6sYtFWKe1K792y6XHDLuI,104
+typefully_cli/__main__.py,sha256=lAv7csx7EYimOu3qalDWwjV3N-BiGv7VoRiHGg9yhb4,92
+typefully_cli/auth.py,sha256=qYsFhtTj6jZfVvcIW3MQgSMcvSaYZnho-S35t7W2FIw,1567
+typefully_cli/batch.py,sha256=9NR14tSYFz2CrOl75AFE7bX1y1eMu9Ll5iq74qs3Gkk,3846
+typefully_cli/cli.py,sha256=7cL4ChM3YTlwzf7A5uphU6hy8wgWbP274DWoubtoY3k,28418
+typefully_cli/client.py,sha256=yC6JYEmLhnH5_yCbgbN_NblMzT1Yh7j83GVy4N7aG1k,8828
+typefully_cli/config.py,sha256=GBzhwhm1zSOgTg02nbafYJ2tNhKp3G7RaZXDX5bNW_k,3305
+typefully_cli/console.py,sha256=0rfo9SJGeNWX01bf5sPEDTrWfkwCXELJOsIswSbn_jk,1768
+typefully_cli/exceptions.py,sha256=JeXcqF4YBsfF5zG8h7P_3MP-2kYzXDG_VF3W4SIUwtE,2161
+typefully_cli/media.py,sha256=7MXWxK_tpEJ9dOwJ30qls8CbPkzn-zAxCAPpN4-VPNo,2520
+typefully_cli/output.py,sha256=CnSrv5mA4veh_-_dkcPQsaf_qNhKoOKPY5LuqjVKwtE,7027
+typefully_cli-0.1.0.dist-info/METADATA,sha256=NoEEBuoAdbX5lwXKwiGJGY9peb3yR0fPQsNxJSqQ5kg,8259
+typefully_cli-0.1.0.dist-info/WHEEL,sha256=QccIxa26bgl1E6uMy58deGWi-0aeIkkangHcxk2kWfw,87
+typefully_cli-0.1.0.dist-info/entry_points.txt,sha256=j8dzA0OIGtgsNYcFTxZMtSTJgeQ3GzhMDMYChmXcEj4,52
+typefully_cli-0.1.0.dist-info/licenses/LICENSE,sha256=t7C9PE4W_rix38nAz5ECap62B2d04YXw3V8tMf91UaI,1069
+typefully_cli-0.1.0.dist-info/RECORD,,

typefully_cli-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.29.0
+Root-Is-Purelib: true
+Tag: py3-none-any

typefully_cli-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+typefully = typefully_cli.cli:cli

typefully_cli-0.1.0.dist-info/licenses/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.