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.jsonindex 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.jsonindex 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.mdindex 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 viewerdiff --git a/VERSION b/VERSIONindex 88541566..21574090 100644--- a/VERSION+++ b/VERSION@@ -1 +1 @@-0.21.0+0.22.0diff --git a/openclaw/README.md b/openclaw/README.mdindex 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 statediff --git a/openclaw/bin/publish_pending.py b/openclaw/bin/publish_pending.pynew file mode 100755index 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.shindex 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 ]]; docase "$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[@]}"; doadd_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+echoecho "Installed/verified Toprank OpenClaw cron jobs:"openclaw cron list | grep -i 'Toprank' || truediff --git a/openclaw/install/notfair-publisher.md b/openclaw/install/notfair-publisher.mdnew file mode 100644index 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.pynew file mode 100644index 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.mdindex 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.