Publish a post on a Facebook Page via Meta Graph API.

Args: page_id: Numeric Meta Page ID. message: Post message body. image_url: Optional public URL of an image. If config requires images, this MUST be provided (validation will block otherwise). scheduled_at: Optional unix timestamp (seconds). If set, the post is scheduled instead of published immediately. Meta requires 10 minutes <= delta <= 6 months. page_access_token: Optional page-scoped token. Required by Meta in production for posting on a Page (the env-level token is usually a user token; you can derive a page token from /me/accounts). skip_validation: If True, bypasses the pre-publish validator (image required, banned topics, anti-duplicate). Default False — strongly recommended to keep validation on.

Returns: Dict with ok, post_id (if success), error (if failure), and a validation block when validation ran.

Run all guard-rails BEFORE publishing.

Checks: - image_required (per-page config) - banned_topics (substring, accent-insensitive) - length (10..63206 chars) - anti_duplicate (Jaccard 4-grams vs recent posts, lookback per config)

Args: page_id: Numeric Meta Page ID. message: Candidate post text. image_url: Optional candidate image URL. fetch_recent: If True (default), fetches recent posts from Meta to run the anti-duplicate check. Set False to skip network. page_access_token: Optional page-scoped token (used only if fetch_recent).

Returns: Dict with verdict ("go"|"block"), per-check details, errors.

Compare a candidate message against recent posts on the page.

Args: page_id: Numeric Meta Page ID. message: Candidate text to score. lookback_days: Max age of posts to compare against (default 14). similarity_threshold: Jaccard threshold above which it's "too similar" (default 0.5; 0.0=identical, 1.0=nothing in common — careful, that's inverted intuitively. 0.5 = ~half the 4-grams overlap). page_access_token: Optional page-scoped token.

Returns: Dict with is_duplicate, closest_post_id, closest_similarity, posts_compared, lookback_days.

Generate an image for a candidate post and return a usable URL.

Does NOT publish. Caller is expected to take the returned image_url and pass it to fb_publish_post (or further validate via fb_validate_pre_publish). This separation lets the LLM iterate on the visual without burning Meta API quota.

Args: page_id: Numeric Meta Page ID (used only to resolve provider defaults). prompt: Image generation prompt (English recommended). image_provider: "openai" | "fal". Defaults to config.image_providers.default.

Returns: Dict with image_url, provider, model, prompt.