typefully-cli 0.1.0__py3-none-any.whl

typefully_cli/client.py

@@ -0,0 +1,267 @@
+"""Typefully API client. Thin HTTP wrapper over the v2 API."""
+
+from __future__ import annotations
+
+import time
+
+import httpx
+
+from typefully_cli.exceptions import AccountError, APIError
+
+
+class TypefullyClient:
+    BASE_URL = "https://api.typefully.com/v2"
+    RATE_LIMIT_DELAY = 0.3
+
+    def __init__(self, api_key: str, base_url: str | None = None):
+        self._client = httpx.Client(
+            base_url=base_url or self.BASE_URL,
+            headers={
+                "Authorization": f"Bearer {api_key}",
+                "Content-Type": "application/json",
+            },
+            timeout=30.0,
+            follow_redirects=True,
+        )
+        self._social_sets_cache: list[dict] | None = None
+
+    def close(self) -> None:
+        self._client.close()
+
+    def __enter__(self) -> TypefullyClient:
+        return self
+
+    def __exit__(self, *args: object) -> None:
+        self.close()
+
+    # --- Core request ---
+
+    def _request(self, method: str, path: str, **kwargs: object) -> dict | None:
+        try:
+            resp = self._client.request(method, path, **kwargs)
+        except httpx.TimeoutException:
+            raise APIError(0, "Request timed out")
+        except httpx.HTTPError as e:
+            raise APIError(0, f"Network error: {e}")
+        if resp.status_code == 204:
+            return None
+        if not resp.is_success:
+            raise APIError(resp.status_code, resp.text)
+        try:
+            return resp.json()
+        except (ValueError, KeyError):
+            raise APIError(resp.status_code, "Invalid JSON response")
+
+    # --- Account resolution ---
+
+    def get_social_sets(self) -> list[dict]:
+        if self._social_sets_cache is not None:
+            return self._social_sets_cache
+        data = self._request("GET", "/social-sets", params={"limit": 50})
+        self._social_sets_cache = data.get("results", []) if data else []
+        return self._social_sets_cache
+
+    def resolve_account(self, name_or_id: str | None, config_default: str = "") -> int:
+        """Resolve account to social_set_id.
+
+        Priority: name_or_id arg > config_default.
+        Matches: exact numeric ID > case-insensitive username > case-insensitive name.
+        """
+        value = name_or_id or config_default
+        if not value:
+            raise AccountError()
+
+        sets = self.get_social_sets()
+        if not sets:
+            raise AccountError(
+                "No social sets found for this API key",
+                hint="Check your Typefully account has connected social profiles",
+            )
+
+        # Try exact numeric ID
+        try:
+            numeric_id = int(value)
+            for s in sets:
+                if s.get("id") == numeric_id:
+                    return numeric_id
+        except ValueError:
+            pass
+
+        # Case-insensitive username match
+        lower = value.lower()
+        for s in sets:
+            if s.get("username", "").lower() == lower:
+                return s["id"]
+
+        # Case-insensitive name match
+        for s in sets:
+            if s.get("name", "").lower() == lower:
+                return s["id"]
+
+        available = ", ".join(
+            s.get("username") or s.get("name", str(s.get("id", "?"))) for s in sets
+        )
+        raise AccountError(
+            f"Account '{value}' not found",
+            hint=f"Available accounts: {available}",
+        )
+
+    # --- User ---
+
+    def me(self) -> dict:
+        return self._request("GET", "/me") or {}
+
+    # --- Social sets ---
+
+    def get_social_set(self, social_set_id: int) -> dict:
+        return self._request("GET", f"/social-sets/{social_set_id}") or {}
+
+    # --- Drafts ---
+
+    def create_draft(self, social_set_id: int, payload: dict) -> dict:
+        return self._request("POST", f"/social-sets/{social_set_id}/drafts", json=payload) or {}
+
+    def get_draft(self, social_set_id: int, draft_id: str) -> dict:
+        return self._request("GET", f"/social-sets/{social_set_id}/drafts/{draft_id}") or {}
+
+    def update_draft(self, social_set_id: int, draft_id: str, payload: dict) -> dict:
+        return (
+            self._request("PATCH", f"/social-sets/{social_set_id}/drafts/{draft_id}", json=payload)
+            or {}
+        )
+
+    def delete_draft(self, social_set_id: int, draft_id: str) -> None:
+        self._request("DELETE", f"/social-sets/{social_set_id}/drafts/{draft_id}")
+
+    def list_drafts(self, social_set_id: int, **params: object) -> dict:
+        return (
+            self._request("GET", f"/social-sets/{social_set_id}/drafts", params=params) or {}
+        )
+
+    # --- Tags ---
+
+    def list_tags(self, social_set_id: int, limit: int = 50, offset: int = 0) -> dict:
+        return (
+            self._request(
+                "GET",
+                f"/social-sets/{social_set_id}/tags",
+                params={"limit": limit, "offset": offset},
+            )
+            or {}
+        )
+
+    def create_tag(self, social_set_id: int, name: str) -> dict:
+        return (
+            self._request("POST", f"/social-sets/{social_set_id}/tags", json={"name": name}) or {}
+        )
+
+    def ensure_tags(self, social_set_id: int, tag_names: list[str]) -> list[str]:
+        """Create any tags that don't exist yet. Returns list of warnings."""
+        if not tag_names:
+            return []
+        warnings: list[str] = []
+        existing_names: set[str] = set()
+        offset = 0
+        while True:
+            page = self.list_tags(social_set_id, limit=50, offset=offset)
+            results = page.get("results", [])
+            existing_names.update(t.get("name", "").lower() for t in results)
+            if len(results) < 50:
+                break
+            offset += 50
+        for name in tag_names:
+            if name.lower() not in existing_names:
+                try:
+                    self.create_tag(social_set_id, name)
+                except APIError:
+                    warnings.append(f"Could not create tag '{name}'")
+        return warnings
+
+    # --- Media ---
+
+    def request_upload(self, social_set_id: int, file_name: str) -> dict:
+        return (
+            self._request(
+                "POST",
+                f"/social-sets/{social_set_id}/media/upload",
+                json={"file_name": file_name},
+            )
+            or {}
+        )
+
+    def upload_to_s3(self, upload_url: str, file_path: str) -> None:
+        """Upload file to S3 presigned URL. No Content-Type header (breaks signature)."""
+        with open(file_path, "rb") as f:
+            resp = httpx.put(upload_url, content=f.read(), timeout=120.0)
+        if not resp.is_success:
+            raise APIError(resp.status_code, "S3 upload failed")
+
+    def poll_media(
+        self,
+        social_set_id: int,
+        media_id: str,
+        interval: float = 2.0,
+        max_attempts: int = 30,
+    ) -> dict:
+        """Poll media status until ready or timeout."""
+        for _ in range(max_attempts):
+            time.sleep(interval)
+            data = self._request("GET", f"/social-sets/{social_set_id}/media/{media_id}") or {}
+            status = data.get("status", "unknown")
+            if status in ("ready", "completed"):
+                return data
+        return data  # return last status even if not ready
+
+    # --- Recent (with pagination) ---
+
+    def list_recent(
+        self,
+        social_set_id: int,
+        limit: int = 3,
+        since: str = "",
+        until: str = "",
+    ) -> list[dict]:
+        """List recently published posts. Paginates if date range given."""
+        if not since and not until:
+            data = self.list_drafts(
+                social_set_id,
+                status="published",
+                order_by="-published_at",
+                limit=limit,
+            )
+            return data.get("results", [])
+
+        # Paginate through date range
+        results: list[dict] = []
+        offset = 0
+        page_size = 50
+        while True:
+            data = self.list_drafts(
+                social_set_id,
+                status="published",
+                order_by="-published_at",
+                limit=page_size,
+                offset=offset,
+            )
+            page = data.get("results", [])
+            if not page:
+                break
+            for d in page:
+                raw_pub = d.get("published_at")
+                if not raw_pub:
+                    continue
+                pub = raw_pub[:10]
+                if until and pub > until:
+                    continue
+                if since and pub < since:
+                    return results
+                results.append(d)
+            if len(page) < page_size:
+                break
+            offset += page_size
+        return results
+
+    # --- Rate-limited batch operations ---
+
+    def rate_delay(self) -> None:
+        time.sleep(self.RATE_LIMIT_DELAY)

typefully_cli/config.py

@@ -0,0 +1,104 @@
+"""Config file management: ~/.config/typefully/config.toml"""
+
+from __future__ import annotations
+
+import os
+import sys
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Any
+
+if sys.version_info >= (3, 11):
+    import tomllib
+else:
+    try:
+        import tomllib
+    except ModuleNotFoundError:
+        import tomli as tomllib  # type: ignore[no-redef]
+
+
+def _config_path() -> Path:
+    """Return the config file path. Respects XDG_CONFIG_HOME."""
+    base = os.environ.get("XDG_CONFIG_HOME", os.path.expanduser("~/.config"))
+    return Path(base) / "typefully" / "config.toml"
+
+
+@dataclass
+class Config:
+    api_key: str = ""
+    onepassword_item: str = ""
+    default_account: str = ""
+    _path: Path = field(default_factory=_config_path)
+
+    @classmethod
+    def load(cls, path: Path | None = None) -> Config:
+        p = path or _config_path()
+        cfg = cls(_path=p)
+        if not p.exists():
+            return cfg
+        with open(p, "rb") as f:
+            data = tomllib.load(f)
+        auth = data.get("auth", {})
+        cfg.api_key = auth.get("api_key", "")
+        cfg.onepassword_item = auth.get("onepassword_item", "")
+        defaults = data.get("defaults", {})
+        cfg.default_account = defaults.get("account", "")
+        return cfg
+
+    def save(self) -> None:
+        """Write config back to TOML. Minimal hand-written TOML (no dependency)."""
+        self._path.parent.mkdir(parents=True, exist_ok=True)
+        lines: list[str] = []
+        lines.append("[auth]")
+        if self.api_key:
+            lines.append(f'api_key = "{self.api_key}"')
+        if self.onepassword_item:
+            lines.append(f'onepassword_item = "{self.onepassword_item}"')
+        lines.append("")
+        lines.append("[defaults]")
+        if self.default_account:
+            lines.append(f'account = "{self.default_account}"')
+        lines.append("")
+        self._path.write_text("\n".join(lines))
+
+    def to_dict(self, *, redact: bool = True) -> dict[str, Any]:
+        d: dict[str, Any] = {
+            "auth": {
+                "api_key": _redact(self.api_key) if redact else self.api_key,
+            },
+            "defaults": {},
+        }
+        if self.onepassword_item:
+            d["auth"]["onepassword_item"] = self.onepassword_item
+        if self.default_account:
+            d["defaults"]["account"] = self.default_account
+        return d
+
+
+# --- Config set/show helpers ---
+
+_VALID_KEYS = {"api_key", "default_account", "onepassword_item"}
+
+
+def config_set(cfg: Config, key: str, value: str) -> dict:
+    """Set a config key. Returns the result dict (api_key redacted)."""
+    if key not in _VALID_KEYS:
+        raise ValueError(f"Unknown config key: {key}. Valid: {', '.join(sorted(_VALID_KEYS))}")
+    if key == "api_key":
+        cfg.api_key = value
+    elif key == "default_account":
+        cfg.default_account = value
+    elif key == "onepassword_item":
+        cfg.onepassword_item = value
+    cfg.save()
+    display_value = _redact(value) if key == "api_key" else value
+    return {"key": key, "value": display_value}
+
+
+def _redact(key: str) -> str:
+    """Redact an API key: show first 3 and last 4 chars."""
+    if not key:
+        return ""
+    if len(key) <= 7:
+        return "***"
+    return f"{key[:3]}...{key[-4:]}"

typefully_cli/console.py

@@ -0,0 +1,56 @@
+"""Centralized stderr output for status, progress, and warnings."""
+
+from __future__ import annotations
+
+import json
+import sys
+from typing import Any
+
+from rich.console import Console as RichConsole
+from rich.progress import Progress, SpinnerColumn, TextColumn, BarColumn, TimeElapsedColumn
+
+
+class Console:
+    """All non-data output goes through here, always to stderr.
+
+    --quiet suppresses status/progress/warning but NOT error JSON.
+    """
+
+    def __init__(self, quiet: bool = False):
+        self._quiet = quiet
+        self._rich = RichConsole(stderr=True)
+
+    def status(self, msg: str) -> None:
+        if not self._quiet:
+            self._rich.print(f"[dim]{msg}[/dim]")
+
+    def success(self, msg: str) -> None:
+        if not self._quiet:
+            self._rich.print(f"[green]{msg}[/green]")
+
+    def warning(self, msg: str) -> None:
+        if not self._quiet:
+            self._rich.print(f"[yellow]Warning: {msg}[/yellow]")
+
+    def error_json(self, error_dict: dict) -> None:
+        """Write structured error JSON as the last line of stderr. Never suppressed."""
+        envelope = {"ok": False, "error": error_dict}
+        sys.stderr.write(json.dumps(envelope) + "\n")
+        sys.stderr.flush()
+
+    def progress(self, description: str = "Processing...") -> Progress:
+        return Progress(
+            SpinnerColumn(),
+            TextColumn("[progress.description]{task.description}"),
+            BarColumn(),
+            TimeElapsedColumn(),
+            console=self._rich,
+            disable=self._quiet,
+        )
+
+
+def write_success(data: Any) -> None:
+    """Write success JSON envelope to stdout."""
+    envelope = {"ok": True, "data": data}
+    sys.stdout.write(json.dumps(envelope, default=str) + "\n")
+    sys.stdout.flush()

typefully_cli/exceptions.py

@@ -0,0 +1,80 @@
+"""Exception hierarchy for Typefully CLI."""
+
+from __future__ import annotations
+
+
+class TypefullyError(Exception):
+    """Base exception for all Typefully CLI errors."""
+
+    code: str = "unknown"
+    hint: str = ""
+
+    def __init__(self, message: str, *, code: str | None = None, hint: str = ""):
+        super().__init__(message)
+        if code is not None:
+            self.code = code
+        if hint:
+            self.hint = hint
+
+    def to_dict(self) -> dict:
+        d: dict = {"code": self.code, "message": str(self)}
+        if self.hint:
+            d["hint"] = self.hint
+        return d
+
+
+class AuthError(TypefullyError):
+    """Authentication or credential error."""
+
+    code = "auth_failed"
+
+    def __init__(self, message: str = "No API key found", *, hint: str = ""):
+        if not hint:
+            hint = (
+                "Set TYPEFULLY_API_KEY, pass --api-key, "
+                "or run: typefully config set api_key <key>"
+            )
+        super().__init__(message, hint=hint)
+
+
+class APIError(TypefullyError):
+    """HTTP error from the Typefully API."""
+
+    code = "api_error"
+
+    def __init__(self, status_code: int, body: str, *, hint: str = ""):
+        self.status_code = status_code
+        super().__init__(f"API returned {status_code}: {body[:200]}", hint=hint)
+
+    @property
+    def user_message(self) -> str:
+        """Clean message without raw upstream body, safe for stdout."""
+        return f"API error (HTTP {self.status_code})"
+
+    def to_dict(self) -> dict:
+        d = super().to_dict()
+        d["status"] = self.status_code
+        return d
+
+
+class AccountError(TypefullyError):
+    """Account resolution error."""
+
+    code = "no_account"
+
+    def __init__(self, message: str = "No account specified", *, hint: str = ""):
+        if not hint:
+            hint = "Pass --account NAME or run: typefully config set default_account NAME"
+        super().__init__(message, hint=hint)
+
+
+class BatchParseError(TypefullyError):
+    """Error parsing a batch file."""
+
+    code = "batch_parse_error"
+
+
+class MediaUploadError(TypefullyError):
+    """Error during media upload."""
+
+    code = "media_upload_error"

typefully_cli/media.py

@@ -0,0 +1,70 @@
+"""Media upload: presigned URL + S3 PUT + poll for ready."""
+
+from __future__ import annotations
+
+import os
+import re
+
+from typefully_cli.client import TypefullyClient
+from typefully_cli.console import Console
+from typefully_cli.exceptions import MediaUploadError
+
+ALLOWED_EXTENSIONS = {"jpg", "jpeg", "png", "webp", "gif", "mp4", "mov", "pdf"}
+SAFE_NAME_RE = re.compile(r"[^a-zA-Z0-9_.()\-]")
+
+
+def _sanitize_filename(name: str) -> str:
+    """Sanitize filename to match Typefully's allowed charset.
+
+    Replaces disallowed characters with underscore. Validates extension.
+    """
+    stem, _, ext = name.rpartition(".")
+    if not ext or ext.lower() not in ALLOWED_EXTENSIONS:
+        raise MediaUploadError(
+            f"Unsupported file type: .{ext}" if ext else "No file extension",
+            hint=f"Supported: {', '.join(sorted(ALLOWED_EXTENSIONS))}",
+        )
+    safe_stem = SAFE_NAME_RE.sub("_", stem) or "upload"
+    return f"{safe_stem}.{ext}"
+
+
+def upload_media(
+    client: TypefullyClient,
+    social_set_id: int,
+    file_path: str,
+    console: Console,
+) -> dict:
+    """Upload a media file and poll until ready. Returns {media_id, status}."""
+    if not os.path.isfile(file_path):
+        raise MediaUploadError(f"File not found: {file_path}")
+
+    file_name = _sanitize_filename(os.path.basename(file_path))
+
+    # Step 1: Get presigned upload URL
+    console.status(f"Requesting upload URL for {file_name}...")
+    upload_response = client.request_upload(social_set_id, file_name)
+    media_id = upload_response.get("media_id", "")
+    upload_url = upload_response.get("upload_url", "")
+    if not media_id or not upload_url:
+        raise MediaUploadError("API did not return media_id or upload_url")
+
+    # Step 2: Upload to S3
+    console.status(f"Uploading {file_name}...")
+    client.upload_to_s3(upload_url, file_path)
+
+    # Step 3: Poll for processing
+    console.status("Processing...")
+    with console.progress("Processing media...") as progress:
+        task = progress.add_task("Processing...", total=30)
+        data = {}
+        for attempt in range(30):
+            import time
+
+            time.sleep(2)
+            progress.advance(task)
+            data = client._request("GET", f"/social-sets/{social_set_id}/media/{media_id}") or {}
+            status = data.get("status", "unknown")
+            if status in ("ready", "completed"):
+                return {"media_id": media_id, "status": "ready"}
+
+    return {"media_id": media_id, "status": data.get("status", "unknown")}