sergebulaev/facebook-skills / .codex-marketplace/facebook-skills
facebook-marketing
VerifiedPlan, draft, audit, and publish posts for a Facebook Page. Use when the user wants to write a short punchy Page post or a longer story post, remove AI tells from a draft, reverse-engineer the hook from a high-share Page post, draft replies to comments on their Page, or plan a week of Facebook Page content. Page posts publish via the Publora API. User provides notes or a Facebook Page post URL, the skill drafts, the user approves, then it publishes.
lib/publora_client.py
View on GitHub"""Thin Publora REST client for the Facebook Pages Skills project.
Wraps the Publora API endpoints this bundle uses. As of 2026-06 Publora exposes:
- POST /create-post (publish or schedule a Facebook Page post)
- GET /platform-connections (list connected accounts + token health)
Facebook has no comment- or reaction-specific endpoint on Publora (those are
LinkedIn-only). A reply to a comment on a Page post therefore cannot be
published through Publora, so comment replies are draft-only in this bundle
(see lib/backend_selector.py). Page posts of every kind (short text, long story,
link, image, video) flow through `create-post`.
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`. Write methods retry on transient 408/429/5xx via the
shared retry decorator.
"""
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 Facebook Pages the prefix is `facebook-` followed by the page id
# (e.g. "facebook-112233445566").
PLATFORM_ID_PREFIX = "facebook-"
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",
}
)
# ---- Page posts -------------------------------------------------------
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 Facebook Page post (short text, long story, or link post).
Args:
content: Post text. Facebook accepts up to 63,206 chars natively,
but posts under 80 chars get a reported ~66% engagement lift,
so the writer skills favor short. If the text contains a URL,
Facebook auto-generates a link preview (not controlled here).
platforms: List of platform connection IDs, e.g.
["facebook-112233445566"]. Each must match
/^[a-z]+-[a-zA-Z0-9_-]+$/. Add more IDs to post to several
Pages at once (e.g. ["facebook-112233", "facebook-445566"]).
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. Publora
only recognizes tiktok/instagram/youtube/threads/telegram keys;
any `facebook` key is silently dropped, so Page posts do not
use it.
Returns:
{ "success": true, "postGroupId": "..." } on HTTP 200.
Media note: to attach images or a video, create the post first, then
upload media against the returned postGroupId via Publora's media
workflow. The writer skills here produce the text; the user supplies
media in the dashboard when they want it.
"""
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 a Facebook Page is connected and which
`facebook-<pageId>` to pass to `create_post`. Facebook page tokens have
a 59-day lifespan; Publora auto-refreshes them, and tokenStatus flags a
page that needs reconnecting.
"""
r = self._session.get(
self.BASE_URL + "/platform-connections", allow_redirects=False, timeout=self.timeout
)
data = self._handle(r)
return data.get("connections", [])
def facebook_connections(self) -> list[dict[str, Any]]:
"""Convenience filter: only the connected Facebook Pages."""
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 |