feat(api): add versioned REST API with OpenAPI 3.1 spec

Expose /api/v1/* for feed and email management (feeds CRUD, email list/get/delete, stats) so the service can be automated without scraping the admin UI. Built on @hono/zod-openapi; the OpenAPI 3.1 spec is served at /api/openapi.json with a Scalar reference at /api/docs. Auth is token-based (Authorization: Bearer <ADMIN_PASSWORD>) plus the existing reverse-proxy headers — no cookie, no CSRF. Extracted the auth primitives into src/lib/auth.ts and the feed create/update/delete orchestration into src/lib/feed-service.ts so the admin UI and the REST API share a single source of truth. Co-Authored-By: Claude Opus 4.7 <noreply@anthropic.com>
2026-06-20 22:03:48 +00:00 · 2026-05-23 23:01:15 +02:00
parent 7f5b913576
commit 45d2a14a12
14 changed files with 1398 additions and 234 deletions
@@ -9,7 +9,9 @@
      "version": "0.1.0",
      "license": "MIT",
      "dependencies": {
+        "@hono/zod-openapi": "^1.4.0",
        "@hono/zod-validator": "^0.8.0",
+        "@scalar/hono-api-reference": "^0.10.19",
        "escape-html": "^1.0.3",
        "feed": "5.2.1",
        "hono": "4.12.22",
@@ -37,6 +39,18 @@
        "wrangler": "4.94.0"
      }
    },
+    "node_modules/@asteasolutions/zod-to-openapi": {
+      "version": "8.5.0",
+      "resolved": "https://registry.npmjs.org/@asteasolutions/zod-to-openapi/-/zod-to-openapi-8.5.0.tgz",
+      "integrity": "sha512-SABbKiObg5dLRiTFnqiW1WWwGcg1BJfmHtT2asIBnBHg6Smy/Ms2KHc650+JI4Hw7lSkdiNebEGXpwoxfben8Q==",
+      "license": "MIT",
+      "dependencies": {
+        "openapi3-ts": "^4.1.2"
+      },
+      "peerDependencies": {
+        "zod": "^4.0.0"
+      }
+    },
    "node_modules/@babel/helper-string-parser": {
      "version": "7.27.1",
      "resolved": "https://registry.npmjs.org/@babel/helper-string-parser/-/helper-string-parser-7.27.1.tgz",
@@ -822,6 +836,24 @@
        "node": "^20.19.0 || ^22.13.0 || >=24"
      }
    },
+    "node_modules/@hono/zod-openapi": {
+      "version": "1.4.0",
+      "resolved": "https://registry.npmjs.org/@hono/zod-openapi/-/zod-openapi-1.4.0.tgz",
+      "integrity": "sha512-AFchqR1N/NxfI4hUOSGI2/g8zLROxA1OE7Oh5JJFlTaGxhrdRyH+93gd0tIBpb0z8s9r8hUoNnaOBfHbdb4NMw==",
+      "license": "MIT",
+      "dependencies": {
+        "@asteasolutions/zod-to-openapi": "^8.5.0",
+        "@hono/zod-validator": "^0.8.0",
+        "openapi3-ts": "^4.5.0"
+      },
+      "engines": {
+        "node": ">=16.0.0"
+      },
+      "peerDependencies": {
+        "hono": ">=4.10.0",
+        "zod": "^4.0.0"
+      }
+    },
    "node_modules/@hono/zod-validator": {
      "version": "0.8.0",
      "resolved": "https://registry.npmjs.org/@hono/zod-validator/-/zod-validator-0.8.0.tgz",
@@ -1954,6 +1986,99 @@
      "dev": true,
      "license": "MIT"
    },
+    "node_modules/@scalar/client-side-rendering": {
+      "version": "0.1.12",
+      "resolved": "https://registry.npmjs.org/@scalar/client-side-rendering/-/client-side-rendering-0.1.12.tgz",
+      "integrity": "sha512-prwHK4ozTU268BHZ/5OstoKB23JSidDuvddAOp0bVz9c29ZxsyzzxPtPcVgF7X16LiZnS1OzY030FoDCM+iC9Q==",
+      "license": "MIT",
+      "dependencies": {
+        "@scalar/schemas": "0.3.2",
+        "@scalar/types": "0.12.2",
+        "@scalar/validation": "0.6.0"
+      },
+      "engines": {
+        "node": ">=22"
+      }
+    },
+    "node_modules/@scalar/helpers": {
+      "version": "0.8.0",
+      "resolved": "https://registry.npmjs.org/@scalar/helpers/-/helpers-0.8.0.tgz",
+      "integrity": "sha512-gmOC6VravNB9VDl6wnt/GOj4K/hn48tj5bpW4AM4MhH8Ubil6uu7g1DSoKHwltu8Ks79KEtR6JmOrROi9R7jaQ==",
+      "license": "MIT",
+      "engines": {
+        "node": ">=22"
+      }
+    },
+    "node_modules/@scalar/hono-api-reference": {
+      "version": "0.10.19",
+      "resolved": "https://registry.npmjs.org/@scalar/hono-api-reference/-/hono-api-reference-0.10.19.tgz",
+      "integrity": "sha512-6EfwN/lfPvePzAxe9UE8fr/ZuAAqS6ttUwQu9JTgk2Xl/clicaVVSOc0gyGt+8GLXdysoNinjZ74we8xqNWyCA==",
+      "license": "MIT",
+      "dependencies": {
+        "@scalar/client-side-rendering": "0.1.12"
+      },
+      "engines": {
+        "node": ">=22"
+      },
+      "peerDependencies": {
+        "hono": "^4.12.5"
+      }
+    },
+    "node_modules/@scalar/schemas": {
+      "version": "0.3.2",
+      "resolved": "https://registry.npmjs.org/@scalar/schemas/-/schemas-0.3.2.tgz",
+      "integrity": "sha512-iadXBgJ02XUU5C5s6/xh/PmGLzUPd7X8upXIvPWBXDcQ4FHACNgkG8PPZ/beYM8UPDDkTUPM3ygEs0G6jKwGjQ==",
+      "license": "MIT",
+      "dependencies": {
+        "@scalar/helpers": "0.8.0",
+        "@scalar/validation": "0.6.0"
+      },
+      "engines": {
+        "node": ">=22"
+      }
+    },
+    "node_modules/@scalar/types": {
+      "version": "0.12.2",
+      "resolved": "https://registry.npmjs.org/@scalar/types/-/types-0.12.2.tgz",
+      "integrity": "sha512-EzLkubCb7xioiTm9eYnmn/032akaq4kkrrdclgV2uezwtniR8ErQICjhMl2AjBWL6nstHiFZ9RnPZm2Z2/KM0Q==",
+      "license": "MIT",
+      "dependencies": {
+        "@scalar/helpers": "0.8.0",
+        "nanoid": "^5.1.6",
+        "type-fest": "^5.3.1",
+        "zod": "^4.3.5"
+      },
+      "engines": {
+        "node": ">=22"
+      }
+    },
+    "node_modules/@scalar/types/node_modules/nanoid": {
+      "version": "5.1.11",
+      "resolved": "https://registry.npmjs.org/nanoid/-/nanoid-5.1.11.tgz",
+      "integrity": "sha512-v+KEsUv2ps74PaSKv0gHTxTCgMXOIfBEbaqa6w6ISIGC7ZsvHN4N9oJ8d4cmf0n5oTzQz2SLmThbQWhjd/8eKg==",
+      "funding": [
+        {
+          "type": "github",
+          "url": "https://github.com/sponsors/ai"
+        }
+      ],
+      "license": "MIT",
+      "bin": {
+        "nanoid": "bin/nanoid.js"
+      },
+      "engines": {
+        "node": "^18 || >=20"
+      }
+    },
+    "node_modules/@scalar/validation": {
+      "version": "0.6.0",
+      "resolved": "https://registry.npmjs.org/@scalar/validation/-/validation-0.6.0.tgz",
+      "integrity": "sha512-tpmmG+/xRE2Kn9RpflU3AIyZv08v10+E1ZrJCx7z6+/91zHVxy0M73kC1LT4/8PbYNt85ywyC8+n+D99JdMcGA==",
+      "license": "MIT",
+      "engines": {
+        "node": ">=20"
+      }
+    },
    "node_modules/@sindresorhus/is": {
      "version": "7.2.0",
      "resolved": "https://registry.npmjs.org/@sindresorhus/is/-/is-7.2.0.tgz",
@@ -4459,6 +4584,15 @@
        "url": "https://github.com/sponsors/sindresorhus"
      }
    },
+    "node_modules/openapi3-ts": {
+      "version": "4.5.0",
+      "resolved": "https://registry.npmjs.org/openapi3-ts/-/openapi3-ts-4.5.0.tgz",
+      "integrity": "sha512-jaL+HgTq2Gj5jRcfdutgRGLosCy/hT8sQf6VOy+P+g36cZOjI1iukdPnijC+4CmeRzg/jEllJUboEic2FhxhtQ==",
+      "license": "MIT",
+      "dependencies": {
+        "yaml": "^2.8.0"
+      }
+    },
    "node_modules/optionator": {
      "version": "0.9.4",
      "resolved": "https://registry.npmjs.org/optionator/-/optionator-0.9.4.tgz",
@@ -5026,7 +5160,6 @@
      "version": "1.0.0",
      "resolved": "https://registry.npmjs.org/tagged-tag/-/tagged-tag-1.0.0.tgz",
      "integrity": "sha512-yEFYrVhod+hdNyx7g5Bnkkb0G6si8HJurOoOEgC8B/O0uXLHlaey/65KRv6cuWBNhBgHKAROVpc7QyYqE5gFng==",
-      "dev": true,
      "license": "MIT",
      "engines": {
        "node": ">=20"
@@ -5150,7 +5283,6 @@
      "version": "5.6.0",
      "resolved": "https://registry.npmjs.org/type-fest/-/type-fest-5.6.0.tgz",
      "integrity": "sha512-8ZiHFm91orbSAe2PSAiSVBVko18pbhbiB3U9GglSzF/zCGkR+rxpHx6sEMCUm4kxY4LjDIUGgCfUMtwfZfjfUA==",
-      "dev": true,
      "license": "(MIT OR CC0-1.0)",
      "dependencies": {
        "tagged-tag": "^1.0.0"
@@ -6097,9 +6229,7 @@
      "version": "2.9.0",
      "resolved": "https://registry.npmjs.org/yaml/-/yaml-2.9.0.tgz",
      "integrity": "sha512-2AvhNX3mb8zd6Zy7INTtSpl1F15HW6Wnqj0srWlkKLcpYl/gMIMJiyuGq2KeI2YFxUPjdlB+3Lc10seMLtL4cA==",
-      "dev": true,
      "license": "ISC",
-      "optional": true,
      "bin": {
        "yaml": "bin.mjs"
      },