feat: add deterministic agent publishing contract

2026-10-09 15:48:13 +03:00
parent 690c2deed7
commit 00f8e4aee7
6 changed files with 501 additions and 104 deletions
@@ -0,0 +1,75 @@
+# Agent publishing API
+
+Base URL: `https://anwarpy.ai/api/agent/posts`
+
+Authentication: send the current secret in `x-agent-key`. The key is stored only in the deployment environment and the local secret store; it must not appear in source, logs, prompts, or this document.
+
+## Create
+
+`POST /api/agent/posts`
+
+```json
+{
+  "title": "دليل عربي",
+  "slug": "arabic-ai-guide",
+  "dek": "وصف عملي",
+  "teaser": "مطلوب لمقال VIP فقط",
+  "content": { "root": { "type": "root", "children": [] } },
+  "category": "أدوات",
+  "access": "vip",
+  "readingMinutes": 7,
+  "publish": true,
+  "coverImage": {
+    "filename": "arabic-ai-guide.jpg",
+    "dataBase64": "<raw JPEG base64>"
+  }
+}
+```
+
+Rules:
+
+- `slug`: lowercase ASCII kebab-case.
+- `category`: one of `وكلاء`, `نماذج`, `استرجاع`, `سلامة`, `أدوات`, `أعمال`.
+- `access`: `free` or `vip`.
+- VIP requires a non-empty teaser.
+- `coverImage` is optional. When provided it must be JPEG and no larger than 5MB. Otherwise the seeded category cover is used.
+- `publish` omitted or false creates `status=draft`; true creates `status=published` with a server timestamp.
+- Unknown fields, including direct `status`, `publishedAt`, and `level`, return 400.
+- An existing or racing duplicate slug returns 409.
+
+Success: 201.
+
+## Lookup
+
+`GET /api/agent/posts/<slug>`
+
+Returns 200 for a draft or published post, 404 when absent. Authentication is required. The response never includes article or teaser content.
+
+## Promote or republish
+
+`PUT /api/agent/posts/<slug>`
+
+Draft promotion body:
+
+```json
+{ "publish": true }
+```
+
+A full republish uses the same body as create, requires `publish=true`, and requires the body slug to match the URL slug. It updates the existing post and never creates a second slug.
+
+## Response
+
+```json
+{
+  "id": 42,
+  "title": "دليل عربي",
+  "slug": "arabic-ai-guide",
+  "status": "published",
+  "access": "vip",
+  "category": "أدوات",
+  "publishedAt": "2026-10-09T12:00:00.000Z",
+  "url": "https://anwarpy.ai/posts/arabic-ai-guide"
+}
+```
+
+Canonical URLs have no `www` and no trailing slash.