Skip to content

sergebulaev/x-skills / .codex-marketplace/x-skills

x-marketing

Verified

Plan, draft, audit, and publish posts and threads for X (Twitter). Use when the user wants to write a single tweet or an auto-numbered thread, build a long-form tweetstorm, remove AI tells from a draft, reverse-engineer the hook from a viral tweet, draft a reply or quote tweet, or plan a week of X content. Tweets and threads publish via the Publora API, which auto-splits long content into a numbered thread. User provides notes or a tweet URL, the skill drafts, the user approves, then it publishes.

lib/apify_client.py

View on GitHub
"""Apify read client for the X (Twitter) Skills project.

The read layer: given a handle or a niche query, pull tweets with their author
and engagement so a skill can see what is working, who is engaging, and how a
competitor performs. Uses the run-sync-get-dataset-items endpoint (one HTTP
request, no polling).

Auth: APIFY_TOKEN env var (or constructor arg). Get one at
https://console.apify.com/account/integrations (free tier included).

Actor (verified live 2026-07-14): xquik/x-tweet-scraper. Accepts twitterHandles,
searchTerms, startUrls (tweet/profile/search URLs), or tweetIds, and returns
tweets with author {userName, followers}, likeCount, replyCount, viewCount,
conversationId, isReply, createdAt. ~$0.15 per 1,000 tweets, no cookies.

What X does NOT expose reliably: the list of who LIKED a tweet (X gates
like-visibility). The engagement signal here is REPLIERS and tweet performance,
not likers. That is a platform wall, not a client limitation.

Caching: in-process LRU (256 entries, 6h TTL). force_refresh=True to bypass.
Retries transient 429/5xx (3 attempts, exponential backoff + jitter).
"""
from __future__ import annotations
import os
import random
import time
from collections import OrderedDict
from typing import Any, Optional

import requests
from ._env import load_env

ACTOR = "xquik~x-tweet-scraper"
RUN_SYNC = "https://api.apify.com/v2/acts/{actor}/run-sync-get-dataset-items"
RETRYABLE_STATUSES = {429, 500, 502, 503, 504}
CACHE_MAX_ENTRIES = 256
CACHE_TTL_SECONDS = 6 * 60 * 60
SIGNUP_URL = "https://console.apify.com/account/integrations"


class ApifyError(RuntimeError):
    pass


class ApifyAuthError(ApifyError):
    """No token configured. Message explains the free path + paste fallback."""


def _retry(attempts: int = 3, base_delay: float = 0.6):
    def decorator(fn):
        def wrapper(*args, **kwargs):
            last: Optional[Exception] = None
            for i in range(attempts):
                try:
                    return fn(*args, **kwargs)
                except ApifyError as e:
                    if getattr(e, "status", None) not in RETRYABLE_STATUSES or i == attempts - 1:
                        raise
                    last = e
                    time.sleep(base_delay * (2 ** i) + random.uniform(0, 0.3))
            if last:
                raise last
        return wrapper
    return decorator


def _tweet(t: dict) -> dict:
    au = t.get("author") or {}
    handle = au.get("username") or au.get("userName") or au.get("screen_name")
    return {
        "id": t.get("id"),
        "text": t.get("text") or t.get("fullText"),
        "author": handle,
        "author_name": au.get("name"),
        "author_followers": au.get("followers"),
        "likes": t.get("likeCount", 0),
        "replies": t.get("replyCount", 0),
        "reposts": t.get("retweetCount", t.get("quoteCount", 0)),
        "views": t.get("viewCount"),
        "is_reply": t.get("isReply", False),
        "conversation_id": t.get("conversationId"),
        "created_at": t.get("createdAt"),
        "url": (f"https://x.com/{handle}/status/{t.get('id')}"
                if handle and t.get("id") else None),
    }


class ApifyClient:
    def __init__(self, token: Optional[str] = None, timeout: int = 120):
        load_env()
        self.token = token or os.environ.get("APIFY_TOKEN")
        self.timeout = timeout
        self._cache: "OrderedDict[str, tuple[float, Any]]" = OrderedDict()

    def _require(self) -> str:
        if not self.token:
            raise ApifyAuthError(
                "No APIFY_TOKEN set. Get one free at "
                f"{SIGNUP_URL}. Or paste the tweets/replies you already have and "
                "the skill will run the same analysis on them."
            )
        return self.token

    def _cget(self, k):
        h = self._cache.get(k)
        if h and (time.time() - h[0]) < CACHE_TTL_SECONDS:
            self._cache.move_to_end(k)
            return h[1]
        return None

    def _cput(self, k, v):
        self._cache[k] = (time.time(), v)
        self._cache.move_to_end(k)
        while len(self._cache) > CACHE_MAX_ENTRIES:
            self._cache.popitem(last=False)

    @_retry()
    def _run(self, payload: dict) -> list[dict]:
        try:
            r = requests.post(RUN_SYNC.format(actor=ACTOR),
                              params={"token": self._require()}, json=payload,
                              allow_redirects=False, timeout=self.timeout)
        except requests.RequestException as e:
            err = ApifyError(f"network error: {e}"); err.status = 503; raise err
        if r.status_code >= 400:
            err = ApifyError(f"actor returned {r.status_code}: {r.text[:200]}")
            err.status = r.status_code; raise err
        data = r.json()
        if not isinstance(data, list):
            raise ApifyError(f"unexpected response shape: {str(data)[:150]}")
        # the actor emits a single diagnostic object when the input is empty/invalid
        if data and isinstance(data[0], dict) and data[0].get("resultType") == "diagnostic":
            raise ApifyError(f"actor diagnostic: {data[0].get('message')}")
        return data

    # ---- public read methods ----
    def fetch_user_tweets(self, handle: str, max_items: int = 30,
                          force_refresh: bool = False) -> list[dict]:
        """A handle's recent tweets (self or competitor). Verified path."""
        h = handle.lstrip("@")
        ck = f"user:{h}:{max_items}"
        if not force_refresh and (c := self._cget(ck)) is not None:
            return c
        # No queryType here: the actor ignores it for account timelines.
        rows = self._run({"twitterHandles": [h], "maxItems": max_items})
        out = [_tweet(t) for t in rows if isinstance(t, dict) and t.get("id")]
        self._cput(ck, out)
        return out

    QUERY_TYPES = ("Top", "Latest", "Latest + Top")

    def fetch_niche_top(self, query: str, max_items: int = 30, sort: str = "Top",
                        force_refresh: bool = False) -> list[dict]:
        """Top/latest tweets for a niche query. Search reliability on X varies;
        prefer fetch_user_tweets on known accounts when search returns nothing.

        `sort` is one of QUERY_TYPES and reaches the actor as `queryType`. It was
        sent as `sort` until v1.0.29, which that actor has no input for, so every
        search silently ran as Latest: measured on one query, `sort="Top"` gave a
        median of 0 likes and overlapped the default 8 results in 10, while
        `queryType="Top"` gave a median of 681 and overlapped none of them.
        """
        if sort not in self.QUERY_TYPES:
            raise ValueError(f"sort must be one of {self.QUERY_TYPES}, got {sort!r}")
        ck = f"search:{query}:{max_items}:{sort}"
        if not force_refresh and (c := self._cget(ck)) is not None:
            return c
        rows = self._run({"searchTerms": [query], "maxItems": max_items, "queryType": sort})
        out = [_tweet(t) for t in rows if isinstance(t, dict) and t.get("id")]
        self._cput(ck, out)
        return out

    def fetch_tweet(self, url_or_id: str,
                    force_refresh: bool = False) -> Optional[dict]:
        """One tweet, by URL or bare id, normalized like every other read.

        `fetch_tweet_replies` keeps only rows where `isReply` is true, so the
        tweet a user actually pasted was the one thing the read layer could not
        return. x-hook-extractor and x-reply-drafter both take a tweet URL and
        both had to ask for a paste because of it. The actor answers for
        `tweetIds` directly, which is the same run and the same cost.

        Returns None when the tweet is not retrievable (deleted, protected, or
        an id that does not exist), so callers fall back to asking for a paste.
        """
        from .url_parser import parse_x_url

        tweet_id = parse_x_url(url_or_id).get("tweet_id")
        if not tweet_id:
            raise ValueError(f"not a tweet URL or id: {url_or_id!r}")
        ck = f"tweet:{tweet_id}"
        if not force_refresh and (c := self._cget(ck)) is not None:
            return c
        rows = self._run({"tweetIds": [tweet_id], "maxItems": 1})
        hit = next((t for t in rows
                    if isinstance(t, dict) and str(t.get("id")) == tweet_id), None)
        out = _tweet(hit) if hit else None
        self._cput(ck, out)
        return out

    def fetch_tweet_replies(self, tweet_url: str, max_items: int = 50,
                           force_refresh: bool = False) -> list[dict]:
        """Replies on a tweet (the X engagement signal, since likers are gated).
        Pulls the conversation via the tweet URL and keeps the replies."""
        ck = f"replies:{tweet_url}:{max_items}"
        if not force_refresh and (c := self._cget(ck)) is not None:
            return c
        rows = self._run({"startUrls": [tweet_url], "maxItems": max_items})
        out = [_tweet(t) for t in rows if isinstance(t, dict) and t.get("id") and t.get("isReply")]
        self._cput(ck, out)
        return out


if __name__ == "__main__":
    import json as _json
    print(_json.dumps(ApifyClient().fetch_user_tweets("naval", 3), indent=2))
rea-analysis-optimizationmorluto/reaOptimize REA providers and shared analysis workflows for agent context, latency, CPU, and memory while preserving correctness and Evidence. Use for analysis bottlenecks and cache or query design; CI/test-suite optimization belongs to rea-ci-tests-audit.Stars: 472kUpdated Claude CodeCodexVerifiedInstall
rea-ci-tests-auditmorluto/reaAudit REA CI and test suites for correctness, fixture drift, false passes, and measured performance; use for suite or workflow investigations and efficiency changes, rather than ordinary feature testing or a single test failure.Stars: 472kUpdated Claude CodeCodexVerifiedInstall
rea-tool-designmorluto/reaAudit, investigate, design, or change REA investigation tools, CLI/MCP contracts, provider capabilities, and Evidence semantics.Stars: 472kUpdated Claude CodeCodexVerifiedInstall
ponytail-auditDietrichGebert/ponytailQuality audit of the whole repo: bugs, security, real load, missing tests, speed, and what to delete. Most important first.Stars: 194kUpdated Claude CodeCodexVerifiedInstall