x-post-cli 0.1.0__tar.gz

x_post_cli-0.1.0/.claude/settings.local.json

@@ -0,0 +1,9 @@
+{
+  "permissions": {
+    "allow": [
+      "Bash(uv run pytest:*)",
+      "Bash(git -C /Users/andrei/Developer/ai-first/x-post-cli add src/x/client.py src/x/cli.py tests/test_client.py)",
+      "Bash(git -C:*)"
+    ]
+  }
+}

x_post_cli-0.1.0/.gitignore

@@ -0,0 +1,7 @@
+.env
+__pycache__/
+*.pyc
+.venv/
+dist/
+*.egg-info/
+.pytest_cache/

x_post_cli-0.1.0/PKG-INFO

@@ -0,0 +1,6 @@
+Metadata-Version: 2.4
+Name: x-post-cli
+Version: 0.1.0
+Requires-Python: >=3.11
+Requires-Dist: requests
+Requires-Dist: requests-oauthlib

x_post_cli-0.1.0/README.md

@@ -0,0 +1,54 @@
+# x-post-cli
+
+CLI utility for publishing tweets to Twitter/X via the official API.
+
+## Install
+
+```bash
+# Run directly (no install needed)
+uvx x-post-cli "Hello world!"
+
+# Or install globally
+uv tool install x-post-cli
+```
+
+## Prerequisites
+
+1. Create a project and app at https://developer.x.com
+2. In **User authentication settings** → Enable OAuth 2.0
+3. Type of App: **Native App** (public client, PKCE)
+4. Callback URL: `http://localhost:8000/callback`
+5. Copy `Client ID` and `Client Secret`
+
+## Usage
+
+```bash
+# First run — you'll be prompted for Client ID and Client Secret
+x-post-cli "My first tweet via API!"
+
+# From file
+x-post-cli --from-file draft.txt
+
+# Interactive input (Ctrl+D to send)
+x-post-cli
+
+# With an image (prompts for OAuth 1.0a keys on first use)
+x-post-cli --image photo.jpg "Check this out!"
+
+# Reply to a tweet (threading)
+x-post-cli --reply-to 123456789 "Replying!"
+
+# Re-authorize (clears OAuth 2.0 tokens)
+x-post-cli --reset-auth "Hello again"
+
+# Clear all credentials and start fresh
+x-post-cli --reset-keys "Starting over"
+```
+
+Credentials are requested interactively on first run and saved to `~/.config/x-post/config.json`. On subsequent runs no prompts are needed. The config file can also be edited manually.
+
+## Tests
+
+```bash
+uv run pytest
+```

x_post_cli-0.1.0/pyproject.toml

@@ -0,0 +1,24 @@
+[project]
+name = "x-post-cli"
+version = "0.1.0"
+requires-python = ">=3.11"
+dependencies = ["requests", "requests-oauthlib"]
+
+[project.scripts]
+x-post-cli = "x_post.cli:main"
+
+[tool.pytest.ini_options]
+testpaths = ["tests"]
+pythonpath = ["tests"]
+
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[dependency-groups]
+dev = [
+    "pytest>=9.0.2",
+]
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/x_post"]

x_post_cli-0.1.0/src/x_post/auth.py

@@ -0,0 +1,145 @@
+"""OAuth 2.0 PKCE authentication flow for X."""
+
+import base64
+import hashlib
+import http.server
+import secrets
+import sys
+import threading
+import urllib.parse
+import webbrowser
+
+import requests
+
+_AUTH_URL = "https://twitter.com/i/oauth2/authorize"
+_TOKEN_URL = "https://api.x.com/2/oauth2/token"
+_USERINFO_URL = "https://api.x.com/2/users/me"
+_REDIRECT_URI = "http://localhost:8000/callback"
+_SCOPES = "tweet.write tweet.read users.read offline.access"
+
+
+def _generate_pkce() -> tuple[str, str]:
+    """Generate PKCE code_verifier and code_challenge (S256)."""
+    verifier = base64.urlsafe_b64encode(secrets.token_bytes(32)).rstrip(b"=").decode()
+    digest = hashlib.sha256(verifier.encode()).digest()
+    challenge = base64.urlsafe_b64encode(digest).rstrip(b"=").decode()
+    return verifier, challenge
+
+
+def is_token_valid(token: str) -> bool:
+    """Check whether *token* is still accepted by X API."""
+    resp = requests.get(
+        _USERINFO_URL,
+        headers={"Authorization": f"Bearer {token}"},
+        timeout=10,
+    )
+    return resp.status_code == 200
+
+
+def refresh_access_token(
+    client_id: str, client_secret: str, refresh_token: str,
+) -> tuple[str, str]:
+    """Exchange a refresh token for new access + refresh tokens."""
+    resp = requests.post(
+        _TOKEN_URL,
+        auth=(client_id, client_secret),
+        data={
+            "grant_type": "refresh_token",
+            "refresh_token": refresh_token,
+        },
+        timeout=30,
+    )
+    resp.raise_for_status()
+    data = resp.json()
+    return data["access_token"], data["refresh_token"]
+
+
+def authenticate(client_id: str, client_secret: str) -> tuple[str, str]:
+    """Run the full OAuth 2.0 PKCE browser flow.
+
+    Opens the default browser for user consent, captures the redirect
+    on a local server, and exchanges the code for tokens.
+
+    Returns (access_token, refresh_token).
+    """
+    code_verifier, code_challenge = _generate_pkce()
+    state = secrets.token_urlsafe(16)
+
+    auth_code: str | None = None
+    error: str | None = None
+    server_ready = threading.Event()
+
+    class _CallbackHandler(http.server.BaseHTTPRequestHandler):
+        def do_GET(self) -> None:  # noqa: N802
+            nonlocal auth_code, error
+            params = urllib.parse.parse_qs(
+                urllib.parse.urlparse(self.path).query,
+            )
+
+            received_state = params.get("state", [None])[0]
+            if received_state != state:
+                error = "state_mismatch"
+                self._respond("Authorization failed: state mismatch.")
+            elif "code" in params:
+                auth_code = params["code"][0]
+                self._respond("Authorization successful! You can close this tab.")
+            else:
+                error = params.get("error", ["unknown"])[0]
+                self._respond(f"Authorization failed: {error}")
+
+            threading.Thread(target=self.server.shutdown, daemon=True).start()
+
+        def _respond(self, message: str) -> None:
+            self.send_response(200)
+            self.send_header("Content-Type", "text/html; charset=utf-8")
+            self.end_headers()
+            self.wfile.write(
+                f"<html><body><h2>{message}</h2></body></html>".encode(),
+            )
+
+        def log_message(self, format: str, *args: object) -> None:  # noqa: A002
+            pass
+
+    server = http.server.HTTPServer(("localhost", 8000), _CallbackHandler)
+
+    def _serve() -> None:
+        server_ready.set()
+        server.serve_forever()
+
+    thread = threading.Thread(target=_serve, daemon=True)
+    thread.start()
+    server_ready.wait()
+
+    params = urllib.parse.urlencode({
+        "response_type": "code",
+        "client_id": client_id,
+        "redirect_uri": _REDIRECT_URI,
+        "scope": _SCOPES,
+        "state": state,
+        "code_challenge": code_challenge,
+        "code_challenge_method": "S256",
+    })
+    authorization_url = f"{_AUTH_URL}?{params}"
+    print(f"Opening browser for authorization...\n{authorization_url}")
+    webbrowser.open(authorization_url)
+
+    thread.join()
+
+    if error or auth_code is None:
+        print(f"Authorization failed: {error}", file=sys.stderr)
+        sys.exit(1)
+
+    token_resp = requests.post(
+        _TOKEN_URL,
+        auth=(client_id, client_secret),
+        data={
+            "grant_type": "authorization_code",
+            "code": auth_code,
+            "redirect_uri": _REDIRECT_URI,
+            "code_verifier": code_verifier,
+        },
+        timeout=30,
+    )
+    token_resp.raise_for_status()
+    data = token_resp.json()
+    return data["access_token"], data["refresh_token"]

x_post_cli-0.1.0/src/x_post/cli.py

@@ -0,0 +1,182 @@
+"""CLI entry-point for x-post."""
+
+import argparse
+import pathlib
+import sys
+
+from x_post.auth import authenticate, is_token_valid, refresh_access_token
+from x_post.client import OAuth1Credentials, XClient
+from x_post.config import ConfigStore, JsonConfigStore, prompt_if_missing
+
+_MAX_LENGTH = 280
+
+
+def _parse_args(argv: list[str] | None = None) -> argparse.Namespace:
+    parser = argparse.ArgumentParser(
+        description="Publish a tweet on Twitter/X.",
+    )
+    parser.add_argument("text", nargs="?", help="Tweet text (inline)")
+    parser.add_argument(
+        "--from-file", type=pathlib.Path, help="Read tweet text from a file",
+    )
+    parser.add_argument(
+        "--reply-to",
+        type=str,
+        metavar="TWEET_ID",
+        help="Tweet ID to reply to (for threading)",
+    )
+    parser.add_argument(
+        "--image",
+        type=pathlib.Path,
+        metavar="PATH",
+        help="Attach an image (jpg/png/gif/webp, max 5 MB)",
+    )
+    parser.add_argument(
+        "--reset-auth",
+        action="store_true",
+        help="Clear saved OAuth 2.0 tokens and re-authorize",
+    )
+    parser.add_argument(
+        "--reset-keys",
+        action="store_true",
+        help="Clear all saved credentials and re-prompt from scratch",
+    )
+    return parser.parse_args(argv)
+
+
+def _read_post_text(args: argparse.Namespace) -> str:
+    if args.text:
+        return args.text
+    if args.from_file:
+        return args.from_file.read_text(encoding="utf-8").strip()
+    print("Enter tweet text (Ctrl+D to send):")
+    return sys.stdin.read().strip()
+
+
+def _ensure_token(
+    config: ConfigStore,
+    client_id: str,
+    client_secret: str,
+    *,
+    force: bool,
+) -> str:
+    """Return a valid access token, running OAuth if needed."""
+    access_token = config.get("access_token")
+    refresh_token = config.get("refresh_token")
+
+    if not force and access_token and is_token_valid(access_token):
+        return access_token
+
+    if not force and refresh_token:
+        try:
+            new_access, new_refresh = refresh_access_token(
+                client_id, client_secret, refresh_token,
+            )
+            config.set_many({
+                "access_token": new_access,
+                "refresh_token": new_refresh,
+            })
+            return new_access
+        except Exception:
+            pass  # fall through to full auth
+
+    new_access, new_refresh = authenticate(client_id, client_secret)
+    config.set_many({"access_token": new_access, "refresh_token": new_refresh})
+    return new_access
+
+
+def _ensure_oauth1(config: ConfigStore) -> OAuth1Credentials:
+    """Return OAuth 1.0a credentials, prompting for any missing keys."""
+    if not config.get("api_key"):
+        print(
+            "\n"
+            "Image upload requires OAuth 1.0a credentials\n"
+            "=============================================\n"
+            "In your app at https://developer.x.com:\n"
+            "\n"
+            "1. Go to Keys and Tokens tab\n"
+            "2. Under Consumer Keys, copy API Key and API Key Secret\n"
+            "3. Under Authentication Tokens, generate Access Token and Secret\n"
+            "   (make sure the token has Read and Write permissions)\n",
+        )
+
+    return OAuth1Credentials(
+        api_key=prompt_if_missing(config, "api_key", "API Key"),
+        api_key_secret=prompt_if_missing(config, "api_key_secret", "API Key Secret"),
+        access_token=prompt_if_missing(config, "oauth1_access_token", "OAuth 1.0a Access Token"),
+        access_token_secret=prompt_if_missing(
+            config, "oauth1_access_token_secret", "OAuth 1.0a Access Token Secret",
+        ),
+    )
+
+
+def main(argv: list[str] | None = None, *, _config: ConfigStore | None = None) -> None:
+    args = _parse_args(argv)
+    config = _config or JsonConfigStore()
+
+    if args.reset_keys:
+        config.remove([
+            "client_id", "client_secret",
+            "access_token", "refresh_token",
+            "api_key", "api_key_secret",
+            "oauth1_access_token", "oauth1_access_token_secret",
+        ])
+    elif args.reset_auth:
+        config.remove(["access_token", "refresh_token"])
+
+    if not config.get("client_id"):
+        print(
+            "\n"
+            "First-time setup\n"
+            "================\n"
+            "You need OAuth 2.0 credentials from the X Developer Portal.\n"
+            "\n"
+            "1. Go to https://developer.x.com and create a project & app\n"
+            "2. In User authentication settings, enable OAuth 2.0\n"
+            "3. Set type to Native App, callback URL: http://localhost:8000/callback\n"
+            "4. Copy the Client ID and Client Secret below\n",
+        )
+
+    client_id = prompt_if_missing(config, "client_id", "Client ID")
+    client_secret = prompt_if_missing(config, "client_secret", "Client Secret")
+
+    text = _read_post_text(args)
+    if not text:
+        print("Empty tweet text, aborting.", file=sys.stderr)
+        sys.exit(1)
+    if len(text) > _MAX_LENGTH:
+        print(
+            f"Tweet too long: {len(text)}/{_MAX_LENGTH} characters.",
+            file=sys.stderr,
+        )
+        sys.exit(1)
+
+    access_token = _ensure_token(
+        config, client_id, client_secret,
+        force=args.reset_auth,
+    )
+
+    oauth1: OAuth1Credentials | None = None
+    if args.image:
+        oauth1 = _ensure_oauth1(config)
+
+    client = XClient(access_token, oauth1=oauth1)
+
+    media_ids: list[str] | None = None
+    if args.image:
+        if not args.image.exists():
+            print(f"Image not found: {args.image}", file=sys.stderr)
+            sys.exit(1)
+        try:
+            media_id = client.upload_media(args.image)
+        except ValueError as exc:
+            print(str(exc), file=sys.stderr)
+            sys.exit(1)
+        media_ids = [media_id]
+
+    result = client.create_tweet(
+        text, reply_to_tweet_id=args.reply_to, media_ids=media_ids,
+    )
+    print(f"Tweet published!\n{result.url}")
+    print(f"\nTo continue this thread:\n"
+          f"x-post-cli --reply-to {result.tweet_id} \"Next tweet text\"")

x_post_cli-0.1.0/src/x_post/client.py

@@ -0,0 +1,146 @@
+"""X API client for creating posts."""
+
+from __future__ import annotations
+
+import pathlib
+from dataclasses import dataclass
+from typing import Protocol
+
+import requests
+from requests_oauthlib import OAuth1
+
+_BASE_URL = "https://api.x.com/2"
+_UPLOAD_URL = "https://upload.twitter.com/1.1/media/upload.json"
+_SUPPORTED_IMAGE_TYPES = {".jpg", ".jpeg", ".png", ".gif", ".webp"}
+_MAX_IMAGE_SIZE = 5 * 1024 * 1024  # 5 MB
+
+
+@dataclass(frozen=True)
+class OAuth1Credentials:
+    """OAuth 1.0a credentials required for media uploads."""
+
+    api_key: str
+    api_key_secret: str
+    access_token: str
+    access_token_secret: str
+
+
+@dataclass(frozen=True)
+class TweetResult:
+    """Result of publishing a tweet."""
+
+    tweet_id: str
+    url: str
+
+
+class XAPI(Protocol):
+    """Interface for X API operations."""
+
+    def get_username(self) -> str:
+        """Return the authenticated user's username."""
+        ...
+
+    def create_tweet(
+        self,
+        text: str,
+        *,
+        reply_to_tweet_id: str | None = None,
+        media_ids: list[str] | None = None,
+    ) -> TweetResult:
+        """Publish a tweet and return the result with ID and URL."""
+        ...
+
+
+class XClient:
+    """HTTP client for X REST API v2.
+
+    Usage::
+
+        client = XClient(access_token="...")
+        url = client.create_tweet("Hello X!")
+    """
+
+    def __init__(
+        self,
+        access_token: str,
+        *,
+        oauth1: OAuth1Credentials | None = None,
+    ) -> None:
+        self._session = requests.Session()
+        self._session.headers.update({
+            "Authorization": f"Bearer {access_token}",
+        })
+        self._oauth1 = oauth1
+        self._username: str | None = None
+
+    def get_username(self) -> str:
+        """Return the authenticated user's @username (cached)."""
+        if self._username is None:
+            resp = self._session.get(f"{_BASE_URL}/users/me")
+            resp.raise_for_status()
+            self._username = resp.json()["data"]["username"]
+        return self._username
+
+    def upload_media(self, path: pathlib.Path) -> str:
+        """Upload an image file and return the media_id string.
+
+        Requires OAuth 1.0a credentials (passed via ``oauth1`` at construction).
+        Supports jpg, png, gif, webp up to 5 MB.
+        Raises ``ValueError`` for unsupported format, oversized files,
+        or missing OAuth 1.0a credentials.
+        """
+        if self._oauth1 is None:
+            raise ValueError(
+                "OAuth 1.0a credentials are required for media uploads.",
+            )
+        suffix = path.suffix.lower()
+        if suffix not in _SUPPORTED_IMAGE_TYPES:
+            raise ValueError(
+                f"Unsupported image format '{suffix}'. "
+                f"Supported: {', '.join(sorted(_SUPPORTED_IMAGE_TYPES))}",
+            )
+        size = path.stat().st_size
+        if size > _MAX_IMAGE_SIZE:
+            raise ValueError(
+                f"Image too large ({size / 1024 / 1024:.1f} MB). "
+                f"Maximum: {_MAX_IMAGE_SIZE / 1024 / 1024:.0f} MB",
+            )
+        auth = OAuth1(
+            self._oauth1.api_key,
+            self._oauth1.api_key_secret,
+            self._oauth1.access_token,
+            self._oauth1.access_token_secret,
+        )
+        with open(path, "rb") as f:
+            resp = requests.post(_UPLOAD_URL, files={"media": f}, auth=auth)
+        if not resp.ok:
+            raise requests.HTTPError(
+                f"{resp.status_code}: {resp.text}", response=resp,
+            )
+        return str(resp.json()["media_id"])
+
+    def create_tweet(
+        self,
+        text: str,
+        *,
+        reply_to_tweet_id: str | None = None,
+        media_ids: list[str] | None = None,
+    ) -> TweetResult:
+        """Publish a tweet, optionally with media or as a reply."""
+        body: dict = {"text": text}
+        if reply_to_tweet_id is not None:
+            body["reply"] = {"in_reply_to_tweet_id": reply_to_tweet_id}
+        if media_ids is not None:
+            body["media"] = {"media_ids": media_ids}
+
+        resp = self._session.post(f"{_BASE_URL}/tweets", json=body)
+        if not resp.ok:
+            raise requests.HTTPError(
+                f"{resp.status_code}: {resp.text}", response=resp,
+            )
+        tweet_id = resp.json()["data"]["id"]
+        username = self.get_username()
+        return TweetResult(
+            tweet_id=tweet_id,
+            url=f"https://x.com/{username}/status/{tweet_id}",
+        )

x_post_cli-0.1.0/src/x_post/config.py

@@ -0,0 +1,88 @@
+"""Persistent JSON config store for credentials."""
+
+from __future__ import annotations
+
+import json
+import os
+import pathlib
+import sys
+from typing import Callable, Protocol
+
+_DEFAULT_PATH = pathlib.Path.home() / ".config" / "x-post" / "config.json"
+
+
+class ConfigStore(Protocol):
+    """Read/write access to persistent key-value config."""
+
+    def get(self, key: str) -> str | None: ...
+    def set(self, key: str, value: str) -> None: ...
+    def set_many(self, items: dict[str, str]) -> None: ...
+    def remove(self, keys: list[str]) -> None: ...
+
+
+class JsonConfigStore:
+    """Config store backed by a JSON file (default ``~/.config/x-post/config.json``).
+
+    Creates the directory and file on first write.  Sets ``0o600`` permissions
+    after each write to protect secrets.
+    """
+
+    def __init__(self, path: pathlib.Path = _DEFAULT_PATH) -> None:
+        self._path = path
+
+    def get(self, key: str) -> str | None:
+        data = self._read()
+        return data.get(key)
+
+    def set(self, key: str, value: str) -> None:
+        data = self._read()
+        data[key] = value
+        self._write(data)
+
+    def set_many(self, items: dict[str, str]) -> None:
+        data = self._read()
+        data.update(items)
+        self._write(data)
+
+    def remove(self, keys: list[str]) -> None:
+        data = self._read()
+        for k in keys:
+            data.pop(k, None)
+        self._write(data)
+
+    def _read(self) -> dict[str, str]:
+        if not self._path.exists():
+            return {}
+        return json.loads(self._path.read_text(encoding="utf-8"))
+
+    def _write(self, data: dict[str, str]) -> None:
+        self._path.parent.mkdir(parents=True, exist_ok=True)
+        self._path.write_text(
+            json.dumps(data, indent=2) + "\n", encoding="utf-8",
+        )
+        os.chmod(self._path, 0o600)
+
+
+def prompt_if_missing(
+    config: ConfigStore,
+    key: str,
+    display_name: str,
+    *,
+    prompt_fn: Callable[[str], str] | None = None,
+) -> str:
+    """Return the value for *key*, prompting the user if it's not stored yet.
+
+    Saves the prompted value into *config* for next time.
+    Exits if the user provides an empty value.
+    """
+    value = config.get(key)
+    if value:
+        return value
+    _prompt = prompt_fn or input
+    value = _prompt(f"{display_name}: ")
+    if not value or not value.strip():
+        print("Value required. Aborting.", file=sys.stderr)
+        sys.exit(1)
+    value = value.strip()
+    config.set(key, value)
+    return value

x_post_cli-0.1.0/tests/conftest.py

@@ -0,0 +1 @@
+"""Shared test fixtures."""