creatorloop 0.1.0__py3-none-any.whl

creatorloop/auth_cli.py

@@ -0,0 +1,133 @@
+"""Helper CLI: exchange tokens and find your Instagram professional account ID.
+
+Usage:
+    uv run creatorloop-auth exchange --short-token <TOKEN> [--write]
+    uv run creatorloop-auth whoami [--write]
+    uv run creatorloop-auth check
+"""
+
+from __future__ import annotations
+
+import argparse
+import sys
+from datetime import UTC, datetime, timedelta
+from pathlib import Path
+
+import httpx
+
+from creatorloop import DISCLAIMER, paths
+from creatorloop.config import load_settings
+
+ENV_PATH = paths.home_dir() / ".env"
+
+
+def _get(url: str, params: dict[str, str]) -> dict:
+    resp = httpx.get(url, params=params, timeout=30)
+    body = resp.json()
+    if "error" in body:
+        err = body["error"]
+        sys.exit(f"Graph API error: {err.get('message')} (code={err.get('code')})")
+    return body
+
+
+def _write_env(key: str, value: str, path: Path = ENV_PATH) -> None:
+    path.parent.mkdir(parents=True, exist_ok=True)
+    lines = path.read_text(encoding="utf-8").splitlines() if path.exists() else []
+    for i, line in enumerate(lines):
+        if line.split("=", 1)[0].strip() == key:
+            lines[i] = f"{key}={value}"
+            break
+    else:
+        lines.append(f"{key}={value}")
+    path.write_text("\n".join(lines) + "\n", encoding="utf-8")
+    print(f"  -> saved {key} to {path}")
+
+
+def cmd_exchange(args: argparse.Namespace) -> None:
+    s = load_settings()
+    if not (s.app_id and s.app_secret):
+        sys.exit(f"Set META_APP_ID and META_APP_SECRET in {ENV_PATH} first.")
+    body = _get(
+        f"{s.base_url}/oauth/access_token",
+        {
+            "grant_type": "fb_exchange_token",
+            "client_id": s.app_id,
+            "client_secret": s.app_secret,
+            "fb_exchange_token": args.short_token,
+        },
+    )
+    token = body["access_token"]
+    expires_in = int(body.get("expires_in") or 0)
+    expiry = (datetime.now(UTC) + timedelta(seconds=expires_in)).date() if expires_in else "unknown (~60 days)"
+    print(f"Long-lived token received, expires: {expiry}")
+    if args.write:
+        _write_env("IG_ACCESS_TOKEN", token)
+    else:
+        print(token)
+
+
+def cmd_whoami(args: argparse.Namespace) -> None:
+    s = load_settings()
+    if not s.access_token:
+        sys.exit("IG_ACCESS_TOKEN is empty.")
+    body = _get(
+        f"{s.base_url}/me/accounts",
+        {"fields": "name,instagram_business_account{id,username,followers_count}", "access_token": s.access_token},
+    )
+    found = []
+    for page in body.get("data", []):
+        ig = page.get("instagram_business_account")
+        status = f"IG @{ig['username']} id={ig['id']} followers={ig.get('followers_count')}" if ig else "no IG linked"
+        print(f"Facebook Page '{page.get('name')}': {status}")
+        if ig:
+            found.append(ig["id"])
+    if not found:
+        sys.exit(
+            "No Instagram professional account found. Check that IG is Business/Creator, linked to a Facebook Page, "
+            "and the token has instagram_basic + pages_show_list."
+        )
+    if args.write:
+        _write_env("IG_USER_ID", found[0])
+
+
+def cmd_check(_: argparse.Namespace) -> None:
+    s = load_settings()
+    s.require_credentials()
+    body = _get(f"{s.base_url}/{s.ig_user_id}", {"fields": "username,followers_count", "access_token": s.access_token})
+    print(f"OK: @{body.get('username')} followers={body.get('followers_count')} api={s.api_version}")
+    dbg = _get(f"{s.base_url}/debug_token", {"input_token": s.access_token, "access_token": s.access_token})
+    exp = dbg.get("data", {}).get("expires_at") or 0
+    if exp:
+        left = (datetime.fromtimestamp(exp, UTC) - datetime.now(UTC)).days
+        print(f"Token expires {datetime.fromtimestamp(exp, UTC).date()} ({left} days left)")
+    else:
+        print("Token never expires")
+
+
+def main() -> None:
+    parser = argparse.ArgumentParser(prog="creatorloop-auth", description=__doc__.split("\n")[0], epilog=DISCLAIMER)
+    sub = parser.add_subparsers(required=True)
+
+    p = sub.add_parser("exchange", help="Exchange short-lived user token for a long-lived (60 days) one")
+    p.add_argument("--short-token", required=True)
+    p.add_argument("--write", action="store_true", help="Save to .env instead of printing")
+    p.set_defaults(func=cmd_exchange)
+
+    p = sub.add_parser("whoami", help="List Facebook Pages and linked Instagram account IDs")
+    p.add_argument("--write", action="store_true", help="Save the first IG_USER_ID to .env")
+    p.set_defaults(func=cmd_whoami)
+
+    p = sub.add_parser("check", help="Verify .env credentials with a test request")
+    p.set_defaults(func=cmd_check)
+
+    args = parser.parse_args()
+    try:
+        args.func(args)
+    except RuntimeError as exc:  # missing settings etc.: show the message, not a traceback
+        sys.exit(f"Error: {exc}")
+    except httpx.HTTPError as exc:
+        sys.exit(f"Network error: {exc}")
+
+
+if __name__ == "__main__":
+    main()

creatorloop/comments.py

@@ -0,0 +1,111 @@
+"""Comments on own posts: digest of new / unanswered comments and replies (only after user approval).
+
+Needs the token permission instagram_manage_comments (README, section 3).
+"""
+
+from __future__ import annotations
+
+import asyncio
+from typing import Any
+
+from creatorloop import analytics
+from creatorloop.graph_client import GraphAPIError
+
+COMMENT_FIELDS = "id,text,username,timestamp,like_count,replies{id,text,username,timestamp,like_count}"
+MAX_REPLY = 2200
+PERMISSION_CODES = {10, 200}  # (#10) / (#200) permission errors
+
+
+class CommentsError(RuntimeError):
+    pass
+
+
+def _permission_hint(exc: GraphAPIError) -> CommentsError:
+    if exc.code in PERMISSION_CODES or "permission" in exc.message.lower():
+        return CommentsError(
+            "The token has no instagram_manage_comments permission. Regenerate it in Graph API Explorer with "
+            "instagram_manage_comments added, then run `uv run creatorloop-auth exchange --short-token <TOKEN> "
+            f"--write` (README, section 3). Graph API said: {exc}"
+        )
+    return CommentsError(f"Graph API error: {exc}")
+
+
+def _unanswered(c: dict[str, Any], me: str) -> list[dict[str, Any]]:
+    """Messages in one thread (top-level comment + its replies) written by others AFTER my last word there.
+
+    A thread I already answered still yields new items when the person writes again. Instagram only allows
+    replies to top-level comments, so every item carries `reply_to` = the top-level id to answer in that thread.
+    """
+    replies = list((c.get("replies") or {}).get("data") or [])
+    if all(r.get("timestamp") for r in replies):
+        replies.sort(key=lambda r: r["timestamp"])  # chronological; otherwise keep the API order
+    msgs = [c] + replies
+    own = [i for i, x in enumerate(msgs) if (x.get("username") or "").lower() == me]
+    last_mine = own[-1] if own else -1
+    items = []
+    for i, x in enumerate(msgs):
+        if i <= last_mine or (x.get("username") or "").lower() == me:
+            continue  # mine, or already answered by a later message of mine
+        in_thread = x is not c
+        items.append({
+            "comment_id": x["id"],
+            "reply_to": c["id"],
+            "username": x.get("username"),
+            "text": x.get("text"),
+            "timestamp": x.get("timestamp"),
+            "likes": x.get("like_count"),
+            "in_thread": in_thread,
+            "thread_start": {"username": c.get("username"), "text": c.get("text")} if in_thread else None,
+        })
+    return items
+
+
+async def new_comments(svc, *, days: int = 14, only_new: bool = True, mark_seen: bool = True) -> dict[str, Any]:
+    me = (await svc.my_username()).lower()
+    media = [m for m in analytics.media_since(await svc.my_media(limit=50, refresh=True), days)
+             if (m.get("comments_count") or 0) > 0]
+    sem = asyncio.Semaphore(4)
+
+    async def fetch(m: dict[str, Any]) -> tuple[dict[str, Any], list[dict[str, Any]]]:
+        async with sem:
+            try:
+                items = await svc.client.paginate(f"/{m['id']}/comments", {"fields": COMMENT_FIELDS}, max_items=100)
+            except GraphAPIError as exc:
+                raise _permission_hint(exc) from exc
+        return m, items
+
+    results = await asyncio.gather(*(fetch(m) for m in media))
+    out = []
+    for m, items in results:
+        post = {"media_id": m["id"], "permalink": m.get("permalink"), "hook": analytics.caption_hook(m.get("caption"), 80)}
+        for c in items:
+            for item in _unanswered(c, me):
+                seen = svc.storage.comment_seen(item["comment_id"])
+                if only_new and seen:
+                    continue
+                out.append({**item, "post": post, "already_seen": bool(seen)})
+    if mark_seen:
+        for c in out:
+            svc.storage.comment_mark(c["comment_id"], c["post"]["media_id"])
+    out.sort(key=lambda c: c["timestamp"] or "", reverse=True)
+    return {
+        "comments": out,
+        "posts_checked": len(media),
+        "next": "Draft a short reply for each (same language as the comment, the user's tone). Send with "
+        "reply_comment(comment_id=<reply_to>) ONLY after the user explicitly approves that exact text; "
+        "in_thread items are answers inside a thread, thread_start shows what they reply to.",
+    }
+
+
+async def reply(svc, comment_id: str, message: str) -> dict[str, Any]:
+    text = message.strip()
+    if not text:
+        raise CommentsError("Empty reply")
+    if len(text) > MAX_REPLY:
+        raise CommentsError(f"Reply is {len(text)} chars (max {MAX_REPLY})")
+    try:
+        body = await svc.client.post(f"/{comment_id}/replies", {"message": text})
+    except GraphAPIError as exc:
+        raise _permission_hint(exc) from exc
+    svc.storage.comment_mark(comment_id, None, reply_id=body.get("id"))
+    return {"replied": True, "reply_id": body.get("id"), "comment_id": comment_id, "text": text}

creatorloop/config.py

@@ -0,0 +1,110 @@
+"""Settings loaded from environment variables / .env files (see creatorloop.paths for locations)."""
+
+from __future__ import annotations
+
+import os
+from dataclasses import dataclass
+from datetime import datetime, tzinfo
+from pathlib import Path
+from zoneinfo import ZoneInfo, ZoneInfoNotFoundError
+
+from dotenv import load_dotenv
+
+from creatorloop import paths
+
+DEFAULT_API_VERSION = "v26.0"
+
+
+def _load_env() -> None:
+    # Real environment variables win (override=False), then the user's home .env, then ./.env (development).
+    # Claude Desktop starts the process with an arbitrary cwd, so the home .env is the one that matters.
+    load_dotenv(paths.home_dir() / ".env", override=False)
+    load_dotenv(Path.cwd() / ".env", override=False)
+
+
+def _zone(name: str) -> ZoneInfo | None:
+    try:
+        return ZoneInfo(name.strip()) if name.strip() else None
+    except (ZoneInfoNotFoundError, ValueError):
+        return None
+
+
+def system_timezone(localtime: Path = Path("/etc/localtime"), timezone_file: Path = Path("/etc/timezone")) -> tzinfo:
+    """The computer's timezone: TZ, the /etc/localtime link (macOS, Linux), /etc/timezone (Debian),
+    else the current fixed UTC offset (Windows; set IG_TIMEZONE there to get daylight-saving changes right)."""
+    if tz := _zone(os.getenv("TZ", "").lstrip(":")):
+        return tz
+    try:
+        target = str(localtime.resolve(strict=True))
+        if "zoneinfo/" in target and (tz := _zone(target.split("zoneinfo/", 1)[1])):
+            return tz
+    except OSError:
+        pass
+    try:
+        if tz := _zone(timezone_file.read_text(encoding="utf-8")):
+            return tz
+    except OSError:
+        pass
+    return datetime.now().astimezone().tzinfo or ZoneInfo("UTC")
+
+
+def _int(name: str, default: int) -> int:
+    raw = os.getenv(name, "").strip()
+    return int(raw) if raw else default
+
+
+@dataclass(frozen=True, slots=True)
+class Settings:
+    access_token: str
+    ig_user_id: str
+    api_version: str
+    app_id: str | None
+    app_secret: str | None
+    db_path: Path
+    timezone: tzinfo
+    ttl_profile_s: int
+    ttl_media_s: int
+    ttl_hashtag_s: int
+
+    @property
+    def base_url(self) -> str:
+        return f"https://graph.facebook.com/{self.api_version}"
+
+    def require_credentials(self) -> None:
+        missing = [
+            name
+            for name, value in (("IG_ACCESS_TOKEN", self.access_token), ("IG_USER_ID", self.ig_user_id))
+            if not value
+        ]
+        if missing:
+            raise RuntimeError(
+                f"Missing required settings: {', '.join(missing)}. "
+                f"Fill them in {paths.home_dir() / '.env'} (run creatorloop-setup to create it)."
+            )
+
+
+def _configured_timezone() -> tzinfo:
+    raw = os.getenv("IG_TIMEZONE", "").strip()
+    if not raw:
+        return system_timezone()
+    if tz := _zone(raw):
+        return tz
+    raise RuntimeError(f"IG_TIMEZONE={raw!r} is not a known timezone; use an IANA name like 'Europe/Berlin'.")
+
+
+def load_settings() -> Settings:
+    _load_env()
+    db_raw = os.getenv("IG_DB_PATH", "").strip()
+    db_path = Path(db_raw).expanduser() if db_raw else paths.home_dir() / "creatorloop.db"
+    return Settings(
+        access_token=os.getenv("IG_ACCESS_TOKEN", "").strip(),
+        ig_user_id=os.getenv("IG_USER_ID", "").strip(),
+        api_version=os.getenv("GRAPH_API_VERSION", DEFAULT_API_VERSION).strip() or DEFAULT_API_VERSION,
+        app_id=os.getenv("META_APP_ID", "").strip() or None,
+        app_secret=os.getenv("META_APP_SECRET", "").strip() or None,
+        db_path=db_path,
+        timezone=_configured_timezone(),
+        ttl_profile_s=_int("CACHE_TTL_PROFILE_MIN", 60) * 60,
+        ttl_media_s=_int("CACHE_TTL_MEDIA_MIN", 180) * 60,
+        ttl_hashtag_s=_int("CACHE_TTL_HASHTAG_MIN", 360) * 60,
+    )

creatorloop/env.example

@@ -0,0 +1,33 @@
+# creatorloop settings. `creatorloop-setup` creates this file in your creatorloop home folder;
+# fill in the two required values below and restart Claude Desktop.
+# Commands below are for a PyPI install; from a source checkout use `uv run creatorloop-auth ...`.
+
+# Long-lived user access token (60 days) or a System User token (never expires).
+# Get it with: uvx --from creatorloop creatorloop-auth exchange --short-token <TOKEN> --write
+IG_ACCESS_TOKEN=
+
+# Instagram professional account ID (NOT the username). 17841400000000000-like number.
+# Get it with: uvx --from creatorloop creatorloop-auth whoami --write
+IG_USER_ID=
+
+# Graph API version. Check https://developers.facebook.com/docs/graph-api/changelog
+GRAPH_API_VERSION=v26.0
+
+# Optional: needed only for the token exchange and token expiry check.
+META_APP_ID=
+META_APP_SECRET=
+
+# Optional: SQLite database location (default: creatorloop.db in the creatorloop home folder).
+IG_DB_PATH=
+
+# Optional: IANA timezone for "best time to post" and the queue, e.g. Europe/Berlin.
+# Default: your computer's timezone (on Windows set it explicitly to get daylight-saving changes right).
+IG_TIMEZONE=
+
+# Optional: publishing slots for queue_post(when="next"), local time. Example, not a recommendation.
+QUEUE_SLOTS=Tue,Thu,Sun 19:00
+
+# Cache TTL in minutes.
+CACHE_TTL_PROFILE_MIN=60
+CACHE_TTL_MEDIA_MIN=180
+CACHE_TTL_HASHTAG_MIN=360

creatorloop/graph_client.py

@@ -0,0 +1,224 @@
+"""Thin async client for the Facebook Graph API (Instagram API with Facebook Login)."""
+
+from __future__ import annotations
+
+import asyncio
+import json
+import logging
+from dataclasses import dataclass, field
+from pathlib import Path
+from typing import Any
+
+import httpx
+
+log = logging.getLogger(__name__)
+
+# https://developers.facebook.com/docs/graph-api/overview/rate-limiting
+RATE_LIMIT_CODES = {4, 17, 32, 613, 80001, 80002, 80006}
+TRANSIENT_CODES = {1, 2}
+TOKEN_ERROR_CODE = 190
+RUPLOAD_HOST = "https://rupload.facebook.com"  # resumable video uploads (Reels)
+
+
+class GraphAPIError(Exception):
+    """Error returned by the Graph API."""
+
+    def __init__(
+        self,
+        message: str,
+        *,
+        code: int | None = None,
+        subcode: int | None = None,
+        status: int | None = None,
+        fbtrace_id: str | None = None,
+        transient: bool = False,
+    ) -> None:
+        super().__init__(message)
+        self.message = message
+        self.code = code
+        self.subcode = subcode
+        self.status = status
+        self.fbtrace_id = fbtrace_id
+        self.transient = transient
+
+    def __str__(self) -> str:
+        parts = [self.message]
+        if self.code is not None:
+            parts.append(f"code={self.code}")
+        if self.subcode is not None:
+            parts.append(f"subcode={self.subcode}")
+        if self.fbtrace_id:
+            parts.append(f"fbtrace_id={self.fbtrace_id}")
+        return " | ".join(parts)
+
+
+class RateLimitError(GraphAPIError):
+    """Rate limit reached. Retrying immediately makes it worse, so we do not retry."""
+
+
+class TokenError(GraphAPIError):
+    """Access token is invalid or expired."""
+
+
+@dataclass(slots=True)
+class UsageInfo:
+    """Last seen rate-limit usage headers."""
+
+    app_usage: dict[str, Any] = field(default_factory=dict)
+    business_usage: dict[str, Any] = field(default_factory=dict)
+    instagram_usage: dict[str, Any] = field(default_factory=dict)
+
+
+def _parse_json_header(value: str | None) -> dict[str, Any]:
+    if not value:
+        return {}
+    try:
+        parsed = json.loads(value)
+    except ValueError:
+        return {}
+    return parsed if isinstance(parsed, dict) else {}
+
+
+class GraphClient:
+    def __init__(
+        self,
+        base_url: str,
+        access_token: str,
+        *,
+        timeout: float = 30.0,
+        max_retries: int = 3,
+        transport: httpx.AsyncBaseTransport | None = None,
+    ) -> None:
+        self._access_token = access_token
+        self._max_retries = max_retries
+        self._client = httpx.AsyncClient(base_url=base_url, timeout=timeout, transport=transport)
+        self.usage = UsageInfo()
+
+    async def aclose(self) -> None:
+        await self._client.aclose()
+
+    async def get(self, path: str, params: dict[str, Any] | None = None) -> dict[str, Any]:
+        return await self._request("GET", path, params, retries=self._max_retries)
+
+    async def post(self, path: str, params: dict[str, Any] | None = None, *, retries: int = 0) -> dict[str, Any]:
+        """POST with form params. No retries by default: repeating a publish call could post twice."""
+        return await self._request("POST", path, params, retries=retries)
+
+    async def _request(self, method: str, path: str, params: dict[str, Any] | None, *, retries: int) -> dict[str, Any]:
+        query = {k: v for k, v in (params or {}).items() if v is not None}
+        query.setdefault("access_token", self._access_token)
+
+        attempt = 0
+        while True:
+            attempt += 1
+            try:
+                if method == "GET":
+                    response = await self._client.get(path, params=query)
+                else:
+                    response = await self._client.post(path, data=query)
+            except httpx.TransportError as exc:
+                if attempt > retries:
+                    raise GraphAPIError(f"Network error: {exc}", transient=True) from exc
+                await self._backoff(attempt, reason=str(exc))
+                continue
+
+            self._record_usage(response)
+            try:
+                return self._handle(response)
+            except GraphAPIError as exc:
+                retryable = exc.transient or (exc.status is not None and exc.status >= 500)
+                if isinstance(exc, (RateLimitError, TokenError)) or not retryable or attempt > retries:
+                    raise
+                await self._backoff(attempt, reason=str(exc))
+
+    @property
+    def api_version(self) -> str:
+        return str(self._client.base_url).rstrip("/").rsplit("/", 1)[-1]
+
+    async def upload_video(self, container_id: str, path: Path, *, timeout: float = 600.0) -> dict[str, Any]:
+        """Resumable upload of a local video into a REELS container created with upload_type=resumable.
+
+        POST https://rupload.facebook.com/ig-api-upload/<version>/<container_id>, headers Authorization/offset/file_size.
+        Sent in one request from offset 0. Not retried automatically (a partial upload is simply redone by prepare).
+        """
+        url = f"{RUPLOAD_HOST}/ig-api-upload/{self.api_version}/{container_id}"
+        data = await asyncio.to_thread(path.read_bytes)
+        headers = {"Authorization": f"OAuth {self._access_token}", "offset": "0", "file_size": str(len(data))}
+        try:
+            response = await self._client.post(url, content=data, headers=headers, timeout=timeout)
+        except httpx.TransportError as exc:
+            raise GraphAPIError(f"Video upload failed: {exc}", transient=True) from exc
+        try:
+            body = response.json()
+        except ValueError:
+            body = {}
+        if not response.is_success or not body.get("success"):
+            debug = body.get("debug_info") or body.get("error") or response.text[:300]
+            raise GraphAPIError(f"Video upload rejected (HTTP {response.status_code}): {debug}", status=response.status_code)
+        return body
+
+    async def paginate(
+        self, path: str, params: dict[str, Any] | None = None, *, max_items: int = 100
+    ) -> list[dict[str, Any]]:
+        """Follow cursor pagination (`paging.cursors.after`) until max_items."""
+        items: list[dict[str, Any]] = []
+        page_params = dict(params or {})
+        while len(items) < max_items:
+            page_params["limit"] = min(page_params.get("limit") or 50, max_items - len(items), 100)
+            body = await self.get(path, page_params)
+            items.extend(body.get("data", []))
+            after = body.get("paging", {}).get("cursors", {}).get("after")
+            if not after or not body.get("paging", {}).get("next"):
+                break
+            page_params["after"] = after
+        return items[:max_items]
+
+    async def _backoff(self, attempt: int, *, reason: str) -> None:
+        delay = min(2 ** (attempt - 1), 8)
+        log.warning("Graph API retry %s in %ss: %s", attempt, delay, reason)
+        await asyncio.sleep(delay)
+
+    def _record_usage(self, response: httpx.Response) -> None:
+        headers = response.headers
+        if app := _parse_json_header(headers.get("x-app-usage")):
+            self.usage.app_usage = app
+        if biz := _parse_json_header(headers.get("x-business-use-case-usage")):
+            self.usage.business_usage = biz
+        if ig := _parse_json_header(headers.get("x-ig-business-use-case-usage")):
+            self.usage.instagram_usage = ig
+
+    @staticmethod
+    def _handle(response: httpx.Response) -> dict[str, Any]:
+        try:
+            body = response.json()
+        except ValueError:
+            if response.is_success:
+                raise GraphAPIError("Non-JSON response from Graph API", status=response.status_code) from None
+            raise GraphAPIError(
+                f"HTTP {response.status_code}: {response.text[:300]}", status=response.status_code
+            ) from None
+
+        if response.is_success and "error" not in body:
+            return body
+
+        err = body.get("error", {}) if isinstance(body, dict) else {}
+        message = err.get("error_user_msg") or err.get("message") or f"HTTP {response.status_code}"
+        code = err.get("code")
+        kwargs = dict(
+            code=code,
+            subcode=err.get("error_subcode"),
+            status=response.status_code,
+            fbtrace_id=err.get("fbtrace_id"),
+            transient=bool(err.get("is_transient")) or code in TRANSIENT_CODES,
+        )
+        if code in RATE_LIMIT_CODES:
+            raise RateLimitError(
+                f"Rate limit reached: {message}. Wait before the next request (see get_api_status).",
+                **kwargs,
+            )
+        if code == TOKEN_ERROR_CODE:
+            raise TokenError(
+                f"Access token problem: {message}. Refresh IG_ACCESS_TOKEN (README, section 'Token').",
+                **kwargs,
+            )
+        raise GraphAPIError(message, **kwargs)