Skip to content

Open-source SEO, GEO, and marketing skills for AI agents.

v0.22.0 feat: opt-in OpenClaw cron publisher to NotFair webhook

Claudecd3581796e5d
diff --git a/.claude-plugin/marketplace.json b/.claude-plugin/marketplace.json
index a854217e..5150387b 100644
--- a/.claude-plugin/marketplace.json
+++ b/.claude-plugin/marketplace.json
@@ -5,14 +5,14 @@
},
"metadata": {
"description": "The official Google Ads + Meta Ads + SEO + GEO plugin from NotFair. SEO, GEO, Google Ads, and Meta Ads skills for Claude Code.",
- "version": "0.21.0"
+ "version": "0.22.0"
},
"plugins": [
{
"name": "toprank",
"source": "./",
- "description": "The official Google Ads + Meta Ads + SEO + GEO plugin from NotFair. SEO analysis, Google Ads management, Meta (Facebook + Instagram) Ads management, GSC-driven content planning + local calendar viewer, keyword research, content optimization, schema markup, meta tags optimization, broken link checker, single-page deep audit, and Generative Engine Optimization for AI search.",
- "version": "0.21.0",
+ "description": "The official Google Ads + Meta Ads + SEO + GEO plugin from NotFair. SEO analysis, Google Ads management, Meta (Facebook + Instagram) Ads management, GSC-driven content planning + local calendar viewer, opt-in OpenClaw cron publisher to a NotFair webhook, keyword research, content optimization, schema markup, meta tags optimization, broken link checker, single-page deep audit, and Generative Engine Optimization for AI search.",
+ "version": "0.22.0",
"author": {
"name": "NotFair",
"url": "https://notfair.co"
diff --git a/.claude-plugin/plugin.json b/.claude-plugin/plugin.json
index f4a5c866..abc83d14 100644
--- a/.claude-plugin/plugin.json
+++ b/.claude-plugin/plugin.json
@@ -1,6 +1,6 @@
{
"name": "toprank",
- "version": "0.21.0",
+ "version": "0.22.0",
"description": "The official Google Ads + Meta Ads + SEO + GEO plugin from NotFair. SEO analysis, Google Ads management, Meta (Facebook + Instagram) Ads management, keyword research, content optimization, schema markup tools, broken link checker, single-page deep audit, and Generative Engine Optimization (GEO) for AI search engines — powered by Google Search Console, Google Ads, and Meta Marketing APIs.",
"author": {
"name": "NotFair",
diff --git a/CHANGELOG.md b/CHANGELOG.md
index 0af0f6d8..1cde1fe5 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -11,6 +11,61 @@ The format follows [Keep a Changelog](https://keepachangelog.com/en/1.0.0/).
---
+## [0.22.0] — 2026-05-15
+
+### Added — opt-in OpenClaw cron publisher
+
+- **`openclaw/bin/publish_pending.py`** — stdlib Python publisher. Reads
+ `content-calendar.json`, finds entries with `status: "ready_to_publish"`
+ and a `bodyPath`, POSTs each to `$NOTFAIR_PUBLISH_URL` (default:
+ `https://notfair.co/api/blog/publish`) with `Authorization: Bearer
+ $NOTFAIR_PUBLISH_TOKEN`. Dry-run by default — needs `--commit` (or
+ `OPENCLAW_PUBLISH_COMMIT=1`) to actually fire. Response handling:
+ 2xx → `published` with stored URL; 4xx → `failed` (non-retryable);
+ 5xx / network error → entry stays `ready_to_publish`, exits non-zero so
+ the next cron pass retries.
+- **`openclaw/install/install-openclaw-cron.sh --enable-publisher`** — new
+ opt-in flag that registers a recurring `Toprank NotFair Publisher` cron
+ job via `openclaw cron add`. Default interval: 15m (override with
+ `--publisher-every`). Existing installs are unaffected — without the
+ flag, the publisher is not registered.
+- **`openclaw/install/notfair-publisher.md`** — webhook contract for the
+ Next.js side: endpoint, auth, request payload shape, expected
+ responses, idempotency, status-code semantics, versioning. Single source
+ of truth — keep `publish_pending.py` and the Next.js handler in lockstep
+ via this doc.
+- **`seo/content-planner/SKILL.md`** — schema now documents
+ `ready_to_publish` / `published` / `failed` statuses and `bodyPath`,
+ `featuredImage`, `inlineImages`, `structuredData`, `metaDescription`
+ fields. Includes a status-lifecycle table. The planner never
+ auto-promotes — the hand-flip to `ready_to_publish` is the user's
+ explicit go-ahead.
+- **15 unit tests** (`openclaw/tests/test_publish_pending.py`) covering
+ missing calendar, no ready entries, missing token, dry-run, 2xx /
+ 4xx / 5xx / network, missing body file, multiple entries, site filter,
+ payload shape, and CLI/env-var precedence.
+
+### Changed — opt-in carve-out, not policy flip
+
+- **`openclaw/README.md`** "What it is not" — narrowed from "not a
+ production auto-publisher" (absolute) to "not an auto-publisher by
+ default" (opt-in carve-out). Existing installs stay read-only /
+ advisory; users explicitly opt in with `--enable-publisher`.
+
+### Notes — what's intentionally NOT here
+
+- No dependency on `gbrain` (Garry Tan's open-source memory/scheduler
+ runtime). It's a real and capable project, but for a stateless
+ POST-on-a-timer the marginal value over `openclaw cron` is zero and the
+ dependency surface is large. The publisher is runtime-agnostic stdlib
+ Python — if someone later wants to drive it from gbrain or plain
+ crontab, they wire up a one-line shell job pointing at
+ `publish_pending.py`.
+- No HMAC signing in v1. Add `X-NotFair-Signature` and bump
+ `schemaVersion` if needed.
+
+---
+
## [0.21.0] — 2026-05-15
### Added — `/content-planner` skill + local calendar viewer
diff --git a/VERSION b/VERSION
index 88541566..21574090 100644
--- a/VERSION
+++ b/VERSION
@@ -1 +1 @@
-0.21.0
+0.22.0
diff --git a/openclaw/README.md b/openclaw/README.md
index 725f6d50..37dea4ff 100644
--- a/openclaw/README.md
+++ b/openclaw/README.md
@@ -38,7 +38,13 @@ In practice, this means OpenClaw can continuously work a portfolio of sites by r
- not a second copy of the SEO skill library
- not a replacement for the Claude plugin surface
-- not a production auto-publisher
+- **not an auto-publisher by default** — publishing is an explicit opt-in. The
+ base install is read-only / advisory. If you want OpenClaw to POST ready
+ blog posts to a NotFair Next.js webhook on a cron, pass
+ `--enable-publisher` to `install-openclaw-cron.sh` and export
+ `NOTFAIR_PUBLISH_TOKEN` in the cron environment. The publisher only fires
+ for content-calendar entries the user has explicitly flipped to
+ `status: "ready_to_publish"`. Contract: `openclaw/install/notfair-publisher.md`.
## Runtime state
diff --git a/openclaw/bin/publish_pending.py b/openclaw/bin/publish_pending.py
new file mode 100755
index 00000000..066b1a51
--- /dev/null
+++ b/openclaw/bin/publish_pending.py
@@ -0,0 +1,299 @@
+#!/usr/bin/env python3
+"""publish_pending.py — publish ready blog posts from a NotFair content calendar.
+
+Reads content-calendar.json, finds entries marked status: "ready_to_publish"
+that have a `bodyPath` pointing at a written file, POSTs each to the configured
+NotFair Next.js webhook, and updates the entry to status: "published" or
+"failed" based on the response.
+
+Designed to run as an OpenClaw cron job. Safe by default:
+
+- Dry-run unless --commit is passed (or OPENCLAW_PUBLISH_COMMIT=1)
+- Stops cleanly when the calendar is missing or has nothing ready
+- 2xx → entry becomes status: "published", publishedAt + response stored
+- 4xx → entry becomes status: "failed", lastError stored (non-retryable)
+- 5xx → entry stays "ready_to_publish", lastError stored, exit non-zero
+- Network err → entry stays "ready_to_publish", lastError stored, exit non-zero
+
+Environment:
+ NOTFAIR_PUBLISH_URL webhook URL (default: https://notfair.co/api/blog/publish)
+ NOTFAIR_PUBLISH_TOKEN Bearer token; required in --commit mode
+ OPENCLAW_PUBLISH_COMMIT "1" → write mode without passing --commit
+ OPENCLAW_PUBLISH_CALENDAR explicit calendar path
+
+Webhook contract: see openclaw/install/notfair-publisher.md.
+"""
+from __future__ import annotations
+
+import argparse
+import json
+import os
+import sys
+import urllib.error
+import urllib.request
+from datetime import datetime, timezone
+from pathlib import Path
+from typing import Any
+
+DEFAULT_WEBHOOK = "https://notfair.co/api/blog/publish"
+DEFAULT_TIMEOUT_SECS = 30
+READY_STATUS = "ready_to_publish"
+PUBLISHED_STATUS = "published"
+FAILED_STATUS = "failed"
+
+
+def now_iso() -> str:
+ return (
+ datetime.now(timezone.utc)
+ .replace(microsecond=0)
+ .isoformat()
+ .replace("+00:00", "Z")
+ )
+
+
+def resolve_calendar_path(explicit: str | None) -> Path:
+ if explicit:
+ return Path(explicit).expanduser().resolve()
+ env = os.environ.get("OPENCLAW_PUBLISH_CALENDAR")
+ if env:
+ return Path(env).expanduser().resolve()
+ project = Path.cwd() / ".notfair" / "content-calendar.json"
+ if project.is_file():
+ return project
+ return Path.home() / ".notfair" / "content-calendar.json"
+
+
+def load_calendar(path: Path) -> dict | None:
+ if not path.is_file():
+ return None
+ return json.loads(path.read_text(encoding="utf-8"))
+
+
+def save_calendar(path: Path, calendar: dict) -> None:
+ path.parent.mkdir(parents=True, exist_ok=True)
+ path.write_text(
+ json.dumps(calendar, indent=2, ensure_ascii=False) + "\n",
+ encoding="utf-8",
+ )
+
+
+def read_body(body_path: str, calendar_dir: Path) -> str:
+ p = Path(body_path).expanduser()
+ if not p.is_absolute():
+ p = (calendar_dir / p).resolve()
+ return p.read_text(encoding="utf-8")
+
+
+def build_payload(entry: dict, body: str) -> dict[str, Any]:
+ """Map a calendar entry to the webhook payload.
+
+ The Next.js endpoint contract is documented in
+ openclaw/install/notfair-publisher.md — keep them in sync.
+ """
+ return {
+ "schemaVersion": "1",
+ "slug": entry.get("id"),
+ "title": entry.get("title"),
+ "primaryKeyword": entry.get("primaryKeyword"),
+ "secondaryKeywords": entry.get("secondaryKeywords") or [],
+ "intent": entry.get("intent"),
+ "type": entry.get("type", "blog"),
+ "metaDescription": entry.get("metaDescription"),
+ "body": body,
+ "bodyFormat": entry.get("bodyFormat", "markdown"),
+ "featuredImage": entry.get("featuredImage"),
+ "inlineImages": entry.get("inlineImages") or [],
+ "structuredData": entry.get("structuredData"),
+ "scheduledAt": entry.get("scheduledDate"),
+ "source": {"tool": "toprank", "skill": "content-planner", "version": "1"},
+ }
+
+
+def post_to_webhook(
+ url: str, token: str, payload: dict, timeout: int = DEFAULT_TIMEOUT_SECS
+) -> tuple[int, dict | str]:
+ """POST payload to the webhook. Returns (status_code, parsed_body_or_text)."""
+ data = json.dumps(payload).encode("utf-8")
+ req = urllib.request.Request(
+ url,
+ data=data,
+ method="POST",
+ headers={
+ "Content-Type": "application/json",
+ "Accept": "application/json",
+ "Authorization": f"Bearer {token}",
+ "User-Agent": "toprank-publisher/1",
+ },
+ )
+ try:
+ with urllib.request.urlopen(req, timeout=timeout) as resp:
+ raw = resp.read().decode("utf-8", errors="replace")
+ return resp.status, _try_parse(raw)
+ except urllib.error.HTTPError as exc:
+ raw = exc.read().decode("utf-8", errors="replace") if hasattr(exc, "read") else str(exc)
+ return exc.code, _try_parse(raw)
+
+
+def _try_parse(raw: str) -> dict | str:
+ try:
+ return json.loads(raw)
+ except (json.JSONDecodeError, ValueError):
+ return raw
+
+
+def ready_entries(calendar: dict, site_filter: str | None) -> list[dict]:
+ out = []
+ for entry in calendar.get("topics") or []:
+ if entry.get("status") != READY_STATUS:
+ continue
+ if not entry.get("bodyPath"):
+ continue
+ if site_filter and entry.get("site") != site_filter:
+ continue
+ out.append(entry)
+ return out
+
+
+def publish_one(
+ entry: dict,
+ *,
+ webhook: str,
+ token: str,
+ calendar_dir: Path,
+ dry_run: bool,
+) -> dict:
+ body_path = entry["bodyPath"]
+ try:
+ body = read_body(body_path, calendar_dir)
+ except OSError as exc:
+ entry["status"] = FAILED_STATUS
+ entry["lastError"] = f"could not read bodyPath '{body_path}': {exc}"
+ entry["lastAttemptAt"] = now_iso()
+ return {"id": entry.get("id"), "outcome": "skipped", "reason": "body unreadable"}
+
+ payload = build_payload(entry, body)
+
+ if dry_run:
+ return {
+ "id": entry.get("id"),
+ "outcome": "dry-run",
+ "would_post_to": webhook,
+ "payload_bytes": len(json.dumps(payload)),
+ }
+
+ try:
+ status, body_resp = post_to_webhook(webhook, token, payload)
+ except (urllib.error.URLError, TimeoutError, OSError) as exc:
+ entry["lastError"] = f"network: {exc}"
+ entry["lastAttemptAt"] = now_iso()
+ return {"id": entry.get("id"), "outcome": "network-error", "error": str(exc)}
+
+ entry["lastAttemptAt"] = now_iso()
+
+ if 200 <= status < 300:
+ entry["status"] = PUBLISHED_STATUS
+ entry["publishedAt"] = now_iso()
+ if isinstance(body_resp, dict):
+ url = body_resp.get("url") or body_resp.get("publishedUrl")
+ if url:
+ entry["publishedUrl"] = url
+ entry["response"] = body_resp
+ entry.pop("lastError", None)
+ return {"id": entry.get("id"), "outcome": "published", "status": status}
+
+ if 400 <= status < 500:
+ entry["status"] = FAILED_STATUS
+ entry["lastError"] = f"HTTP {status}: {body_resp}"
+ return {"id": entry.get("id"), "outcome": "failed", "status": status}
+
+ entry["lastError"] = f"HTTP {status}: {body_resp}"
+ return {"id": entry.get("id"), "outcome": "retry", "status": status}
+
+
+def run(
+ *,
+ calendar_path: Path,
+ webhook: str,
+ token: str | None,
+ dry_run: bool,
+ site_filter: str | None,
+) -> dict:
+ calendar = load_calendar(calendar_path)
+ if calendar is None:
+ return {"ok": True, "processed": [], "note": f"no calendar at {calendar_path}"}
+
+ candidates = ready_entries(calendar, site_filter)
+ if not candidates:
+ return {"ok": True, "processed": [], "note": "no entries ready_to_publish"}
+
+ if not token and not dry_run:
+ return {
+ "ok": False,
+ "processed": [],
+ "error": "NOTFAIR_PUBLISH_TOKEN is unset; refusing to publish. Set the env var or pass --dry-run.",
+ }
+
+ processed = []
+ any_retry_or_network = False
+
+ for entry in candidates:
+ result = publish_one(
+ entry,
+ webhook=webhook,
+ token=token or "",
+ calendar_dir=calendar_path.parent,
+ dry_run=dry_run,
+ )
+ processed.append(result)
+ if result["outcome"] in ("retry", "network-error"):
+ any_retry_or_network = True
+
+ if not dry_run:
+ save_calendar(calendar_path, calendar)
+
+ return {
+ "ok": not any_retry_or_network,
+ "processed": processed,
+ "calendar": str(calendar_path),
+ "dryRun": dry_run,
+ }
+
+
+def parse_args(argv: list[str] | None = None) -> argparse.Namespace:
+ p = argparse.ArgumentParser(prog="publish_pending")
+ p.add_argument("--calendar", default=None,
+ help="Path to content-calendar.json (default: ./.notfair/... → ~/.notfair/...)")
+ p.add_argument("--site", default=None,
+ help="Only publish entries matching this site id")
+ p.add_argument("--webhook", default=None,
+ help=f"Webhook URL (default: $NOTFAIR_PUBLISH_URL or {DEFAULT_WEBHOOK})")
+ p.add_argument("--commit", action="store_true",
+ help="Actually POST. Default is dry-run.")
+ p.add_argument("--dry-run", action="store_true",
+ help="Force dry-run even if OPENCLAW_PUBLISH_COMMIT=1.")
+ return p.parse_args(argv)
+
+
+def main(argv: list[str] | None = None) -> int:
+ args = parse_args(argv)
+
+ commit_env = os.environ.get("OPENCLAW_PUBLISH_COMMIT") == "1"
+ dry_run = args.dry_run or not (args.commit or commit_env)
+
+ calendar_path = resolve_calendar_path(args.calendar)
+ webhook = args.webhook or os.environ.get("NOTFAIR_PUBLISH_URL") or DEFAULT_WEBHOOK
+ token = os.environ.get("NOTFAIR_PUBLISH_TOKEN")
+
+ result = run(
+ calendar_path=calendar_path,
+ webhook=webhook,
+ token=token,
+ dry_run=dry_run,
+ site_filter=args.site,
+ )
+ print(json.dumps(result, indent=2, ensure_ascii=False))
+ return 0 if result.get("ok") else 1
+
+
+if __name__ == "__main__":
+ sys.exit(main())
diff --git a/openclaw/install/install-openclaw-cron.sh b/openclaw/install/install-openclaw-cron.sh
index 2f8e6d35..1cf34c98 100755
--- a/openclaw/install/install-openclaw-cron.sh
+++ b/openclaw/install/install-openclaw-cron.sh
@@ -20,6 +20,15 @@ Options:
--sites <csv> Comma-separated sites. Default: active sites from ~/.toprank/openclaw/portfolio.json.
--runtime-home <path> Toprank runtime home. Default: ~/.toprank/openclaw.
--repo-root <path> Toprank repo root. Default: auto-detected from this script.
+
+Publisher (opt-in; off by default — see openclaw/install/notfair-publisher.md):
+ --enable-publisher Register a recurring publisher job that POSTs ready
+ blog posts to NotFair. Requires NOTFAIR_PUBLISH_TOKEN
+ in the cron environment.
+ --publisher-every <dur> Publisher interval. Default: 15m.
+ --publisher-calendar <p> Explicit calendar path passed to publish_pending.py
+ (default: auto-resolve to ./.notfair/... → ~/.notfair/...).
+
-h, --help Show this help.
Examples:
@@ -40,6 +49,9 @@ TIMEZONE="America/Los_Angeles"
WEEKLY_TIME="06:30"
SCHEDULER_EVERY="1h"
SITES_CSV=""
+ENABLE_PUBLISHER=0
+PUBLISHER_EVERY="15m"
+PUBLISHER_CALENDAR=""
while [[ $# -gt 0 ]]; do
case "$1" in
@@ -54,6 +66,9 @@ while [[ $# -gt 0 ]]; do
--sites) SITES_CSV="$2"; shift 2 ;;
--runtime-home) RUNTIME_HOME="$2"; shift 2 ;;
--repo-root) REPO_ROOT="$2"; shift 2 ;;
+ --enable-publisher) ENABLE_PUBLISHER=1; shift ;;
+ --publisher-every) PUBLISHER_EVERY="$2"; shift 2 ;;
+ --publisher-calendar) PUBLISHER_CALENDAR="$2"; shift 2 ;;
-h|--help) usage; exit 0 ;;
*) echo "Unknown argument: $1" >&2; usage >&2; exit 1 ;;
esac
@@ -167,6 +182,37 @@ for i in "${!sites[@]}"; do
add_job_if_missing "Toprank Weekly Review — $site" "${weekly_args[@]}"
done
+if [[ "$ENABLE_PUBLISHER" -eq 1 ]]; then
+ if [[ ! -x "$REPO_ROOT/openclaw/bin/publish_pending.py" ]]; then
+ echo "ERROR: --enable-publisher set but $REPO_ROOT/openclaw/bin/publish_pending.py is missing" >&2
+ exit 1
+ fi
+ publisher_cmd="OPENCLAW_PUBLISH_COMMIT=1 TOPRANK_OPENCLAW_HOME=\"$RUNTIME_HOME\" python3 \"$REPO_ROOT/openclaw/bin/publish_pending.py\" --commit"
+ if [[ -n "$PUBLISHER_CALENDAR" ]]; then
+ publisher_cmd+=" --calendar \"$PUBLISHER_CALENDAR\""
+ fi
+ publisher_msg="Run the Toprank publisher. Execute exactly: $publisher_cmd. Parse the JSON stdout. If processed is empty, reply exactly NO_REPLY. Otherwise summarize: how many published, how many failed (with reasons), how many retried. If the command exits non-zero, report the blocker. Do not retry the publisher in this turn — the next cron pass picks up retryable failures."
+
+ publisher_args=(
+ --every "$PUBLISHER_EVERY"
+ --session isolated
+ --light-context
+ --message "$publisher_msg"
+ --tools exec
+ )
+ [[ -n "$MODEL" ]] && publisher_args+=(--model "$MODEL")
+ publisher_args+=("${delivery_args[@]}")
+
+ add_job_if_missing "Toprank NotFair Publisher" "${publisher_args[@]}"
+
+ if [[ -z "${NOTFAIR_PUBLISH_TOKEN:-}" ]]; then
+ echo
+ echo "WARNING: NOTFAIR_PUBLISH_TOKEN is not set in your environment."
+ echo "The publisher cron job is registered but will fail until the token is exported"
+ echo "in the cron environment. See openclaw/install/notfair-publisher.md."
+ fi
+fi
+
echo
echo "Installed/verified Toprank OpenClaw cron jobs:"
openclaw cron list | grep -i 'Toprank' || true
diff --git a/openclaw/install/notfair-publisher.md b/openclaw/install/notfair-publisher.md
new file mode 100644
index 00000000..7276a105
--- /dev/null
+++ b/openclaw/install/notfair-publisher.md
@@ -0,0 +1,145 @@
+# NotFair Publisher — Webhook Contract
+
+`openclaw/bin/publish_pending.py` POSTs ready blog posts from a Toprank content
+calendar to a NotFair-hosted Next.js webhook. This file is the contract: the
+Next.js handler on `notfair.co` must accept exactly this shape.
+
+If you change either side, update this file in the same commit. Keep the
+publisher and the handler in lockstep.
+
+---
+
+## Endpoint
+
+```
+POST https://notfair.co/api/blog/publish
+```
+
+Configurable via `NOTFAIR_PUBLISH_URL`. For local Next.js dev, point at
+`http://localhost:3000/api/blog/publish`.
+
+## Auth
+
+```
+Authorization: Bearer <NOTFAIR_PUBLISH_TOKEN>
+```
+
+The token is a long-lived secret the user provisions in the NotFair admin and
+exports as `NOTFAIR_PUBLISH_TOKEN` in their OpenClaw cron environment. The
+handler MUST reject requests without a valid Bearer token (401).
+
+There is no HMAC signing in v1. If you need request integrity, add an
+`X-NotFair-Signature` header in a future version and bump `schemaVersion`.
+
+## Request body
+
+`Content-Type: application/json`
+
+```json
+{
+ "schemaVersion": "1",
+ "slug": "facebook-seo-optimization",
+ "title": "Facebook SEO Optimization: 7 Tactics That Actually Move Pipeline",
+ "primaryKeyword": "facebook seo optimization",
+ "secondaryKeywords": ["facebook page seo", "facebook search ranking"],
+ "intent": "informational",
+ "type": "blog",
+ "metaDescription": "...",
+ "body": "# ...\n\nMarkdown body of the post.",
+ "bodyFormat": "markdown",
+ "featuredImage": {
+ "url": "https://cdn.notfair.co/blog/facebook-seo/featured.webp",
+ "alt": "...",
+ "width": 1200,
+ "height": 1200
+ },
+ "inlineImages": [
+ { "url": "...", "alt": "...", "placement": "after-h2-1" }
+ ],
+ "structuredData": { "@context": "https://schema.org", "@type": "BlogPosting", "...": "..." },
+ "scheduledAt": "2026-05-22",
+ "source": { "tool": "toprank", "skill": "content-planner", "version": "1" }
+}
+```
+
+**Field notes:**
+
+- `slug` (required) — used as the URL slug. Must be stable; re-publishing the
+ same slug is treated as an update by the Next.js side.
+- `body` (required) — Markdown. The Next.js handler is responsible for
+ rendering to HTML, sanitization, and CMS persistence.
+- `bodyFormat` — currently always `"markdown"`. Reserved for future `"html"`
+ or `"mdx"` values.
+- `featuredImage` — may be `null` if the planner couldn't generate one;
+ handler should reject with 400 if your site requires it.
+- `inlineImages` — array; `placement` is an opaque hint ("after-h2-1",
+ "after-h2-2", etc.) the handler can use to position images.
+- `structuredData` — JSON-LD object; handler should embed verbatim in `<head>`.
+
+## Response — 2xx (success)
+
+```json
+{
+ "ok": true,
+ "url": "https://notfair.co/blog/facebook-seo-optimization",
+ "publishedAt": "2026-05-22T14:30:00Z"
+}
+```
+
+The publisher reads `url` (or `publishedUrl`) and stores it on the calendar
+entry as `publishedUrl`. The full response body is stored under
+`entry.response` for audit.
+
+## Response — 4xx (non-retryable failure)
+
+```json
+{
+ "ok": false,
+ "error": "invalid slug",
+ "code": "slug_collision"
+}
+```
+
+The publisher marks the calendar entry as `status: "failed"` and stores the
+response body in `entry.lastError`. The cron will **not** retry. The user must
+fix the entry (rename slug, add missing fields, etc.) and flip status back to
+`ready_to_publish` to try again.
+
+Common 4xx cases the handler should map:
+- `400` — schema validation failure (missing required field, bad format)
+- `401` — missing or invalid Bearer token
+- `409` — slug collision with an existing post
+- `413` — body too large
+
+## Response — 5xx (retryable failure)
+
+The publisher leaves the entry as `ready_to_publish` and stores the response
+body in `entry.lastError`. The cron will retry on its next pass.
+
+The handler should return 5xx **only for transient failures** — DB unavailable,
+upstream timeout, etc. Return 4xx for permanent errors so the publisher stops
+hammering.
+
+## Idempotency
+
+The handler MUST tolerate the same `slug` being submitted more than once:
+
+- If the previous publish succeeded and the cron retries (e.g. response was
+ lost mid-flight), the handler returns 2xx with the same `url`.
+- If the body has changed, treat as an update — overwrite the existing post.
+
+The publisher does not currently send an idempotency key; rely on `slug`.
+
+## Rate
+
+The cron runs at the interval configured via `--scheduler-every` (default 1h
+for the OpenClaw scheduler; the publisher job defaults to every 15 min — see
+`install-openclaw-cron.sh --enable-publisher`). A single run POSTs once per
+ready entry, sequentially, with no concurrency. No backoff between requests.
+
+## Versioning
+
+Bump `schemaVersion` when adding required fields or changing semantics. The
+handler should accept `schemaVersion: "1"` for the foreseeable future; minor
+field additions are backward-compatible. Drop support only after every
+deployed publisher has rolled forward.
diff --git a/openclaw/tests/test_publish_pending.py b/openclaw/tests/test_publish_pending.py
new file mode 100644
index 00000000..d27e15e5
--- /dev/null
+++ b/openclaw/tests/test_publish_pending.py
@@ -0,0 +1,360 @@
+"""Tests for openclaw/bin/publish_pending.py."""
+from __future__ import annotations
+
+import contextlib
+import io
+import json
+import os
+import sys
+import tempfile
+import unittest
+import urllib.error
+from pathlib import Path
+from unittest import mock
+
+BIN_DIR = Path(__file__).resolve().parents[1] / "bin"
+if str(BIN_DIR) not in sys.path:
+ sys.path.insert(0, str(BIN_DIR))
+
+import publish_pending as pp
+
+
+def _calendar_with(entries):
+ return {
+ "schema_version": "1",
+ "generated": "2026-05-15T00:00:00Z",
+ "site": "https://example.com",
+ "topics": entries,
+ "warnings": [],
+ }
+
+
+def _ready_entry(idx=1, body="# Hello\n\nBody.", with_body_path=True, **overrides):
+ """Return (entry, body_path) — body_path is None if with_body_path is False."""
+ return {
+ "id": f"post-{idx}",
+ "title": "Hook-Driven Title",
+ "primaryKeyword": "test keyword",
+ "secondaryKeywords": ["k1", "k2"],
+ "intent": "informational",
+ "type": "blog",
+ "metaDescription": "meta",
+ "scheduledDate": "2026-05-22",
+ "status": "ready_to_publish",
+ "priority": "P0",
+ "bodyPath": f"bodies/post-{idx}.md" if with_body_path else None,
+ **overrides,
+ }
+
+
+class PublishPendingTest(unittest.TestCase):
+ def setUp(self):
+ self.tmp = tempfile.TemporaryDirectory()
+ self.root = Path(self.tmp.name)
+ self.calendar_path = self.root / "content-calendar.json"
+ (self.root / "bodies").mkdir()
+
+ def tearDown(self):
+ self.tmp.cleanup()
+
+ def _write_calendar(self, entries):
+ pp.save_calendar(self.calendar_path, _calendar_with(entries))
+
+ def _write_body(self, idx, body="# Hello\n\nBody."):
+ (self.root / "bodies" / f"post-{idx}.md").write_text(body)
+
+ # ── Calendar resolution / empty cases ───────────────────────────────
+
+ def test_missing_calendar_returns_ok_no_processing(self):
+ result = pp.run(
+ calendar_path=self.root / "nope.json",
+ webhook="https://x",
+ token="t",
+ dry_run=False,
+ site_filter=None,
+ )
+ self.assertTrue(result["ok"])
+ self.assertEqual(result["processed"], [])
+ self.assertIn("no calendar at", result["note"])
+
+ def test_calendar_with_no_ready_entries_is_a_noop(self):
+ self._write_calendar([
+ {"id": "planned-1", "status": "planned", "bodyPath": "bodies/planned-1.md"},
+ {"id": "published-1", "status": "published", "bodyPath": "bodies/x.md"},
+ ])
+ result = pp.run(
+ calendar_path=self.calendar_path, webhook="https://x", token="t",
+ dry_run=False, site_filter=None,
+ )
+ self.assertTrue(result["ok"])
+ self.assertEqual(result["processed"], [])
+ self.assertEqual(result["note"], "no entries ready_to_publish")
+
+ def test_ready_entry_without_body_path_is_skipped(self):
+ self._write_calendar([_ready_entry(1, with_body_path=False)])
+ result = pp.run(
+ calendar_path=self.calendar_path, webhook="https://x", token="t",
+ dry_run=False, site_filter=None,
+ )
+ self.assertEqual(result["processed"], [])
+
+ # ── Safety / commit gating ──────────────────────────────────────────
+
+ def test_commit_mode_without_token_refuses(self):
+ self._write_calendar([_ready_entry(1)])
+ self._write_body(1)
+ result = pp.run(
+ calendar_path=self.calendar_path, webhook="https://x", token=None,
+ dry_run=False, site_filter=None,
+ )
+ self.assertFalse(result["ok"])
+ self.assertIn("NOTFAIR_PUBLISH_TOKEN", result["error"])
+
+ cal = pp.load_calendar(self.calendar_path)
+ self.assertEqual(cal["topics"][0]["status"], "ready_to_publish")
+
+ def test_dry_run_does_not_post_and_does_not_mutate(self):
+ self._write_calendar([_ready_entry(1)])
+ self._write_body(1)
+ with mock.patch.object(pp, "post_to_webhook") as mocked:
+ result = pp.run(
+ calendar_path=self.calendar_path, webhook="https://x", token=None,
+ dry_run=True, site_filter=None,
+ )
+ mocked.assert_not_called()
+ self.assertTrue(result["ok"])
+ self.assertEqual(result["processed"][0]["outcome"], "dry-run")
+
+ cal = pp.load_calendar(self.calendar_path)
+ self.assertEqual(cal["topics"][0]["status"], "ready_to_publish")
+ self.assertNotIn("publishedAt", cal["topics"][0])
+
+ # ── Success path ───────────────────────────────────────────────────
+
+ def test_2xx_marks_published_and_stores_url(self):
+ self._write_calendar([_ready_entry(1)])
+ self._write_body(1)
+ with mock.patch.object(
+ pp, "post_to_webhook",
+ return_value=(201, {"ok": True, "url": "https://notfair.co/blog/post-1"}),
+ ):
+ result = pp.run(
+ calendar_path=self.calendar_path, webhook="https://x", token="t",
+ dry_run=False, site_filter=None,
+ )
+ self.assertTrue(result["ok"])
+ self.assertEqual(result["processed"][0]["outcome"], "published")
+
+ cal = pp.load_calendar(self.calendar_path)
+ entry = cal["topics"][0]
+ self.assertEqual(entry["status"], "published")
+ self.assertEqual(entry["publishedUrl"], "https://notfair.co/blog/post-1")
+ self.assertIn("publishedAt", entry)
+ self.assertEqual(entry["response"]["ok"], True)
+
+ # ── 4xx / failed ───────────────────────────────────────────────────
+
+ def test_400_marks_failed_and_records_error(self):
+ self._write_calendar([_ready_entry(1)])
+ self._write_body(1)
+ with mock.patch.object(
+ pp, "post_to_webhook",
+ return_value=(400, {"ok": False, "error": "invalid slug"}),
+ ):
+ result = pp.run(
+ calendar_path=self.calendar_path, webhook="https://x", token="t",
+ dry_run=False, site_filter=None,
+ )
+ # 4xx is non-retryable but not a "system" failure for the publisher,
+ # so the run is still ok (the entry is marked failed for the user).
+ self.assertTrue(result["ok"])
+ self.assertEqual(result["processed"][0]["outcome"], "failed")
+ self.assertEqual(result["processed"][0]["status"], 400)
+
+ cal = pp.load_calendar(self.calendar_path)
+ entry = cal["topics"][0]
+ self.assertEqual(entry["status"], "failed")
+ self.assertIn("HTTP 400", entry["lastError"])
+
+ # ── 5xx / retry ────────────────────────────────────────────────────
+
+ def test_5xx_leaves_entry_ready_and_exits_non_ok(self):
+ self._write_calendar([_ready_entry(1)])
+ self._write_body(1)
+ with mock.patch.object(
+ pp, "post_to_webhook",
+ return_value=(503, "service unavailable"),
+ ):
+ result = pp.run(
+ calendar_path=self.calendar_path, webhook="https://x", token="t",
+ dry_run=False, site_filter=None,
+ )
+ self.assertFalse(result["ok"])
+ self.assertEqual(result["processed"][0]["outcome"], "retry")
+
+ cal = pp.load_calendar(self.calendar_path)
+ entry = cal["topics"][0]
+ self.assertEqual(entry["status"], "ready_to_publish")
+ self.assertIn("HTTP 503", entry["lastError"])
+
+ # ── Network error ──────────────────────────────────────────────────
+
+ def test_network_error_leaves_entry_ready_and_exits_non_ok(self):
+ self._write_calendar([_ready_entry(1)])
+ self._write_body(1)
+ with mock.patch.object(
+ pp, "post_to_webhook",
+ side_effect=urllib.error.URLError("connection refused"),
+ ):
+ result = pp.run(
+ calendar_path=self.calendar_path, webhook="https://x", token="t",
+ dry_run=False, site_filter=None,
+ )
+ self.assertFalse(result["ok"])
+ self.assertEqual(result["processed"][0]["outcome"], "network-error")
+
+ cal = pp.load_calendar(self.calendar_path)
+ entry = cal["topics"][0]
+ self.assertEqual(entry["status"], "ready_to_publish")
+ self.assertIn("network:", entry["lastError"])
+
+ # ── Body unreadable ────────────────────────────────────────────────
+
+ def test_missing_body_file_marks_failed(self):
+ # Calendar references body but file isn't created
+ self._write_calendar([_ready_entry(1)])
+ # No _write_body call
+ with mock.patch.object(pp, "post_to_webhook") as mocked:
+ result = pp.run(
+ calendar_path=self.calendar_path, webhook="https://x", token="t",
+ dry_run=False, site_filter=None,
+ )
+ mocked.assert_not_called()
+ self.assertEqual(result["processed"][0]["outcome"], "skipped")
+
+ cal = pp.load_calendar(self.calendar_path)
+ entry = cal["topics"][0]
+ self.assertEqual(entry["status"], "failed")
+ self.assertIn("could not read bodyPath", entry["lastError"])
+
+ # ── Multiple entries ───────────────────────────────────────────────
+
+ def test_multiple_entries_processed_independently(self):
+ self._write_calendar([
+ _ready_entry(1),
+ _ready_entry(2),
+ {"id": "planned", "status": "planned", "bodyPath": "bodies/x.md"}, # not ready
+ ])
+ self._write_body(1)
+ self._write_body(2)
+
+ def fake_post(url, token, payload, timeout=30):
+ if payload["slug"] == "post-1":
+ return 201, {"ok": True, "url": "https://notfair.co/blog/post-1"}
+ return 400, {"error": "nope"}
+
+ with mock.patch.object(pp, "post_to_webhook", side_effect=fake_post):
+ result = pp.run(
+ calendar_path=self.calendar_path, webhook="https://x", token="t",
+ dry_run=False, site_filter=None,
+ )
+
+ outcomes = {r["id"]: r["outcome"] for r in result["processed"]}
+ self.assertEqual(outcomes, {"post-1": "published", "post-2": "failed"})
+
+ cal = pp.load_calendar(self.calendar_path)
+ statuses = {t["id"]: t["status"] for t in cal["topics"]}
+ self.assertEqual(
+ statuses,
+ {"post-1": "published", "post-2": "failed", "planned": "planned"},
+ )
+
+ # ── Site filter ────────────────────────────────────────────────────
+
+ def test_site_filter_only_publishes_matching_entries(self):
+ self._write_calendar([
+ _ready_entry(1, site="a.com"),
+ _ready_entry(2, site="b.com"),
+ ])
+ self._write_body(1)
+ self._write_body(2)
+ with mock.patch.object(
+ pp, "post_to_webhook", return_value=(200, {"ok": True, "url": "x"}),
+ ) as mocked:
+ result = pp.run(
+ calendar_path=self.calendar_path, webhook="https://x", token="t",
+ dry_run=False, site_filter="a.com",
+ )
+ self.assertEqual(len(result["processed"]), 1)
+ self.assertEqual(result["processed"][0]["id"], "post-1")
+ mocked.assert_called_once()
+
+ # ── Payload shape ──────────────────────────────────────────────────
+
+ def test_payload_includes_required_fields(self):
+ self._write_calendar([_ready_entry(1, featuredImage={"url": "https://x/img.png", "alt": "a"})])
+ self._write_body(1, body="# Body\n\nText.")
+ captured = {}
+
+ def capture(url, token, payload, timeout=30):
+ captured["payload"] = payload
+ captured["token"] = token
+ captured["url"] = url
+ return 200, {"ok": True, "url": "https://x/published"}
+
+ with mock.patch.object(pp, "post_to_webhook", side_effect=capture):
+ pp.run(
+ calendar_path=self.calendar_path, webhook="https://hook.example",
+ token="secret-token", dry_run=False, site_filter=None,
+ )
+
+ p = captured["payload"]
+ self.assertEqual(p["schemaVersion"], "1")
+ self.assertEqual(p["slug"], "post-1")
+ self.assertEqual(p["title"], "Hook-Driven Title")
+ self.assertEqual(p["primaryKeyword"], "test keyword")
+ self.assertEqual(p["body"], "# Body\n\nText.")
+ self.assertEqual(p["bodyFormat"], "markdown")
+ self.assertEqual(p["featuredImage"], {"url": "https://x/img.png", "alt": "a"})
+ self.assertEqual(p["source"], {"tool": "toprank", "skill": "content-planner", "version": "1"})
+ self.assertEqual(captured["token"], "secret-token")
+ self.assertEqual(captured["url"], "https://hook.example")
+
+ # ── CLI / main ──────────────────────────────────────────────────────
+
+ def test_main_dry_run_default_when_no_flags(self):
+ self._write_calendar([_ready_entry(1)])
+ self._write_body(1)
+ with mock.patch.object(pp, "post_to_webhook") as mocked, \
+ mock.patch.dict(os.environ, {}, clear=False):
+ os.environ.pop("OPENCLAW_PUBLISH_COMMIT", None)
+ os.environ.pop("NOTFAIR_PUBLISH_TOKEN", None)
+ buf = io.StringIO()
+ with contextlib.redirect_stdout(buf):
+ rc = pp.main(["--calendar", str(self.calendar_path)])
+ mocked.assert_not_called()
+ self.assertEqual(rc, 0)
+ out = json.loads(buf.getvalue())
+ self.assertTrue(out["dryRun"])
+
+ def test_main_commit_via_env_var(self):
+ self._write_calendar([_ready_entry(1)])
+ self._write_body(1)
+ with mock.patch.object(
+ pp, "post_to_webhook", return_value=(200, {"ok": True, "url": "x"}),
+ ) as mocked, mock.patch.dict(
+ os.environ,
+ {"OPENCLAW_PUBLISH_COMMIT": "1", "NOTFAIR_PUBLISH_TOKEN": "tok"},
+ clear=False,
+ ):
+ buf = io.StringIO()
+ with contextlib.redirect_stdout(buf):
+ rc = pp.main(["--calendar", str(self.calendar_path)])
+ mocked.assert_called_once()
+ self.assertEqual(rc, 0)
+ out = json.loads(buf.getvalue())
+ self.assertFalse(out["dryRun"])
+
+
+if __name__ == "__main__":
+ unittest.main()
diff --git a/seo/content-planner/SKILL.md b/seo/content-planner/SKILL.md
index 7533a25e..c8656404 100644
--- a/seo/content-planner/SKILL.md
+++ b/seo/content-planner/SKILL.md
@@ -146,10 +146,30 @@ Schedule one post per week, P0s first. Format every entry against this schema:
},
"rationale": "<one sentence: why this topic, why now>",
"writerPrompt": "<the exact prompt to paste into /content-writer when it's time to write>",
- "refreshTarget": "<URL of existing page, only set when type=refresh>"
+ "refreshTarget": "<URL of existing page, only set when type=refresh>",
+ "bodyPath": "<relative path to written markdown body, set after /content-writer runs>",
+ "metaDescription": "<set after /content-writer runs>",
+ "featuredImage": { "url": "...", "alt": "..." },
+ "inlineImages": [{ "url": "...", "alt": "...", "placement": "..." }],
+ "structuredData": { "@context": "https://schema.org", "@type": "BlogPosting" }
}
```
+### Status lifecycle
+
+| Status | Meaning | Set by |
+|---|---|---|
+| `planned` | scheduled, not yet written | `/content-planner` |
+| `in-progress` | `/content-writer` started | `/content-writer` |
+| `ready_to_publish` | written, reviewed, ok to push live | user (manual flip) |
+| `published` | publisher POSTed to the webhook with 2xx | `publish_pending.py` |
+| `failed` | publisher got 4xx; needs user fix | `publish_pending.py` |
+
+The publisher (`openclaw/bin/publish_pending.py`, opt-in via OpenClaw cron)
+only picks up entries with `status === "ready_to_publish"` AND a non-empty
+`bodyPath`. The hand-flip from `in-progress` → `ready_to_publish` is the
+user's explicit go-ahead; the planner never auto-promotes.
+
Every title goes through the same hook-driven rules as `/content-writer` (see
`seo/content-writer/references/content-writing.md` → "Title Hook Patterns").
Don't ship a calendar with bare-keyword titles.