sergebulaev/x-skills / .codex-marketplace/x-skills
x-marketing
VerifiedPlan, 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/publora_client.py
View on GitHub"""Thin Publora REST client for the X (Twitter) Skills project.
Wraps the Publora API endpoints this bundle uses. As of 2026-06 Publora exposes:
- POST /create-post (publish or schedule a post / thread)
- GET /platform-connections (list connected accounts + token health)
X/Twitter has no comment- or reaction-specific endpoint on Publora (those are
LinkedIn-only). On X, a "reply" is just a tweet, but `create-post` does not
expose `in_reply_to`, so reply publishing is draft-only in this bundle. Posts
and threads both flow through `create-post`: pass long `content` and Publora
auto-splits it into a numbered thread at sentence boundaries.
Base URL: https://api.publora.com/api/v1
Auth header: x-publora-key: sk_... (NOT Bearer)
Content-Type: application/json. Server-to-server only (custom headers are not
in the CORS allowlist, so browser calls fail preflight).
Design note: this client is deliberately minimal. Skills call exactly one
method per action, after the user has approved a draft rendered via
`lib/approval.py`. Only the write path retries by design: `_post` (and thus
`create_post`) is wrapped in the shared `@_retry` decorator for transient
408/429/5xx and network blips. The single read method, `list_connections`
(GET /platform-connections), is intentionally NOT retried -- it is a cheap,
idempotent status probe a caller can simply re-run, so a failure surfaces
immediately rather than being masked by silent backoff.
"""
from __future__ import annotations
import os
import time
import random
from typing import Any, Optional
import requests
from ._env import load_env
class PubloraError(RuntimeError):
pass
RETRYABLE_STATUSES = {408, 429, 500, 502, 503, 504}
def _retry(attempts: int = 3, base_delay: float = 0.6):
"""Retry decorator for HTTP methods. Triggers on 408/429/5xx and on
transient network errors. Exponential backoff with jitter."""
def decorator(fn):
def wrapper(*args, **kwargs):
last_exc: Optional[Exception] = None
for attempt in range(attempts):
try:
return fn(*args, **kwargs)
except PubloraError as e:
msg = str(e)
retryable = any(f"HTTP {s}" in msg for s in RETRYABLE_STATUSES)
if not retryable or attempt == attempts - 1:
raise
last_exc = e
except (requests.ConnectionError, requests.Timeout) as e:
if attempt == attempts - 1:
raise
last_exc = e
time.sleep(base_delay * (2**attempt) + random.uniform(0, 0.25))
assert last_exc is not None
raise last_exc
return wrapper
return decorator
# Platform IDs must match Publora's regex: /^[a-z]+-[a-zA-Z0-9_-]+$/
# For X the prefix is `twitter-` (e.g. "twitter-123456789").
PLATFORM_ID_PREFIX = "twitter-"
class PubloraClient:
BASE_URL = "https://api.publora.com/api/v1"
def __init__(self, api_key: Optional[str] = None, timeout: float = 30.0):
load_env()
self.api_key = api_key or os.getenv("PUBLORA_API_KEY")
if not self.api_key:
raise PubloraError(
"PUBLORA_API_KEY not set. Export it or pass api_key= explicitly."
)
self.timeout = timeout
self._session = requests.Session()
self._session.headers.update(
{
"x-publora-key": self.api_key,
"Content-Type": "application/json",
}
)
# ---- Posts and threads ------------------------------------------------
def create_post(
self,
*,
content: str,
platforms: list[str],
scheduled_time: Optional[str] = None,
platform_settings: Optional[dict[str, Any]] = None,
media_urls: Optional[list[str]] = None,
) -> dict[str, Any]:
"""Create a single tweet, a thread, or a cross-platform post.
Args:
content: Post text. Under 280 chars on a standard X account it
ships as one tweet. Longer content (or content with `---`
separators or `\\n\\n` paragraph breaks) is auto-split by
Publora into a numbered thread at sentence boundaries, with
`(1/N)` markers added. X Premium accounts allow up to 25,000
chars in a single tweet.
platforms: List of platform connection IDs, e.g. ["twitter-123"].
Each must match /^[a-z]+-[a-zA-Z0-9_-]+$/. Add more IDs to
cross-post (e.g. ["twitter-123", "threads-456"]).
scheduled_time: ISO 8601 UTC datetime. If omitted, the post is
created as a draft. A past time is silently set to now.
platform_settings: Optional per-platform settings object. Note:
Publora only recognizes tiktok/instagram/youtube/threads/
telegram keys; any `twitter` key is silently dropped.
Returns:
{ "success": true, "postGroupId": "..." } on HTTP 200.
Note: each tweet in a thread counts toward your X API quota, and on a
partial failure Publora returns status "partially_published" with the
IDs that did post.
"""
if not content or not content.strip():
raise PubloraError("content is required (cannot be empty or whitespace)")
if not platforms:
raise PubloraError("at least one platform ID is required")
payload: dict[str, Any] = {
"content": content,
"platforms": platforms,
}
if scheduled_time:
payload["scheduledTime"] = scheduled_time
if platform_settings:
payload["platformSettings"] = platform_settings
if media_urls:
payload["mediaUrls"] = media_urls
return self._post("/create-post", payload)
# ---- Connections (read) -----------------------------------------------
def list_connections(self) -> list[dict[str, Any]]:
"""List connected social accounts with token health.
Returns the `connections` array from GET /platform-connections. Each
entry has platformId, username, displayName, tokenStatus, lastError,
etc. Use it to confirm an X account is connected and which
`twitter-<id>` to pass to `create_post`.
"""
r = self._session.get(
self.BASE_URL + "/platform-connections", allow_redirects=False, timeout=self.timeout
)
data = self._handle(r)
return data.get("connections", [])
def x_connections(self) -> list[dict[str, Any]]:
"""Convenience filter: only the connected X/Twitter accounts."""
return [
c
for c in self.list_connections()
if str(c.get("platformId", "")).startswith(PLATFORM_ID_PREFIX)
]
# ---- Internals --------------------------------------------------------
@_retry()
def _post(self, path: str, json_body: dict[str, Any]) -> dict[str, Any]:
r = self._session.post(
self.BASE_URL + path, json=json_body, allow_redirects=False, timeout=self.timeout
)
return self._handle(r)
@staticmethod
def _handle(r: requests.Response) -> dict[str, Any]:
if r.status_code >= 400:
try:
body = r.json()
except Exception:
body = {"error": r.text[:500]}
raise PubloraError(f"HTTP {r.status_code}: {body}")
return r.json()
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| 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: 472k | Updated | Claude CodeCodex | Verified | Install |
| 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: 472k | Updated | Claude CodeCodex | Verified | Install |
| rea-tool-designmorluto/reaAudit, investigate, design, or change REA investigation tools, CLI/MCP contracts, provider capabilities, and Evidence semantics. | Stars: 472k | Updated | Claude CodeCodex | Verified | Install |
| ponytail-auditDietrichGebert/ponytailQuality audit of the whole repo: bugs, security, real load, missing tests, speed, and what to delete. Most important first. | Stars: 194k | Updated | Claude CodeCodex | Verified | Install |