mirror of
https://github.com/juherr/kill-the-news.git
synced 2026-06-21 06:13:48 +00:00
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>
This commit is contained in:
Julien Herr
@@ -0,0 +1,284 @@
|
||||
import { describe, it, expect, beforeEach } from "vitest";
|
||||
import { Hono } from "hono";
|
||||
import { apiApp } from "./index";
|
||||
import { createMockEnv } from "../../test/setup";
|
||||
import { Env } from "../../types";
|
||||
|
||||
const PASSWORD = "test-password";
|
||||
const authHeaders = { Authorization: `Bearer ${PASSWORD}` };
|
||||
|
||||
describe("REST API (/api/v1)", () => {
|
||||
let testApp: Hono;
|
||||
let mockEnv: Env;
|
||||
let request: (path: string, init?: RequestInit) => Promise<Response>;
|
||||
|
||||
beforeEach(() => {
|
||||
mockEnv = createMockEnv() as unknown as Env;
|
||||
testApp = new Hono();
|
||||
testApp.route("/api", apiApp);
|
||||
request = (path, init = {}) =>
|
||||
Promise.resolve(testApp.request(path, init, mockEnv));
|
||||
});
|
||||
|
||||
async function createFeed(title = "Test Feed"): Promise<string> {
|
||||
const res = await request("/api/v1/feeds", {
|
||||
method: "POST",
|
||||
headers: { ...authHeaders, "Content-Type": "application/json" },
|
||||
body: JSON.stringify({ title }),
|
||||
});
|
||||
expect(res.status).toBe(201);
|
||||
const body = (await res.json()) as { id: string };
|
||||
return body.id;
|
||||
}
|
||||
|
||||
describe("Authentication", () => {
|
||||
it("rejects requests without a token", async () => {
|
||||
const res = await request("/api/v1/feeds");
|
||||
expect(res.status).toBe(401);
|
||||
expect((await res.json()) as { error: string }).toEqual({
|
||||
error: "Unauthorized",
|
||||
});
|
||||
});
|
||||
|
||||
it("rejects requests with a wrong token", async () => {
|
||||
const res = await request("/api/v1/feeds", {
|
||||
headers: { Authorization: "Bearer nope" },
|
||||
});
|
||||
expect(res.status).toBe(401);
|
||||
});
|
||||
|
||||
it("accepts a valid Bearer token", async () => {
|
||||
const res = await request("/api/v1/feeds", { headers: authHeaders });
|
||||
expect(res.status).toBe(200);
|
||||
});
|
||||
|
||||
it("accepts proxy auth headers", async () => {
|
||||
const proxyApp = new Hono();
|
||||
proxyApp.route("/api", apiApp);
|
||||
const proxyEnv = {
|
||||
...createMockEnv(),
|
||||
PROXY_TRUSTED_IPS: "10.0.0.1",
|
||||
PROXY_AUTH_SECRET: "proxy-secret",
|
||||
} as unknown as Env;
|
||||
const res = await proxyApp.request(
|
||||
"/api/v1/feeds",
|
||||
{
|
||||
headers: {
|
||||
"CF-Connecting-IP": "10.0.0.1",
|
||||
"X-Auth-Proxy-Secret": "proxy-secret",
|
||||
"Remote-User": "alice",
|
||||
},
|
||||
},
|
||||
proxyEnv,
|
||||
);
|
||||
expect(res.status).toBe(200);
|
||||
});
|
||||
});
|
||||
|
||||
describe("Feeds CRUD", () => {
|
||||
it("creates, reads, lists, updates and deletes a feed", async () => {
|
||||
// Create
|
||||
const createRes = await request("/api/v1/feeds", {
|
||||
method: "POST",
|
||||
headers: { ...authHeaders, "Content-Type": "application/json" },
|
||||
body: JSON.stringify({
|
||||
title: "Daily Digest",
|
||||
description: "news",
|
||||
allowedSenders: ["News@Example.com"],
|
||||
}),
|
||||
});
|
||||
expect(createRes.status).toBe(201);
|
||||
const created = (await createRes.json()) as {
|
||||
id: string;
|
||||
title: string;
|
||||
allowedSenders: string[];
|
||||
emailAddress: string;
|
||||
rssUrl: string;
|
||||
atomUrl: string;
|
||||
emailCount: number;
|
||||
};
|
||||
expect(created.title).toBe("Daily Digest");
|
||||
// senders are normalized to lowercase
|
||||
expect(created.allowedSenders).toEqual(["news@example.com"]);
|
||||
expect(created.emailCount).toBe(0);
|
||||
expect(created.rssUrl).toContain(`/rss/${created.id}`);
|
||||
|
||||
// Get
|
||||
const getRes = await request(`/api/v1/feeds/${created.id}`, {
|
||||
headers: authHeaders,
|
||||
});
|
||||
expect(getRes.status).toBe(200);
|
||||
expect((await getRes.json()) as { id: string }).toMatchObject({
|
||||
id: created.id,
|
||||
title: "Daily Digest",
|
||||
});
|
||||
|
||||
// List
|
||||
const listRes = await request("/api/v1/feeds", { headers: authHeaders });
|
||||
const list = (await listRes.json()) as { feeds: { id: string }[] };
|
||||
expect(list.feeds.map((f) => f.id)).toContain(created.id);
|
||||
|
||||
// Update
|
||||
const patchRes = await request(`/api/v1/feeds/${created.id}`, {
|
||||
method: "PATCH",
|
||||
headers: { ...authHeaders, "Content-Type": "application/json" },
|
||||
body: JSON.stringify({ title: "Renamed" }),
|
||||
});
|
||||
expect(patchRes.status).toBe(200);
|
||||
expect((await patchRes.json()) as { title: string }).toMatchObject({
|
||||
title: "Renamed",
|
||||
});
|
||||
|
||||
// Delete
|
||||
const delRes = await request(`/api/v1/feeds/${created.id}`, {
|
||||
method: "DELETE",
|
||||
headers: authHeaders,
|
||||
});
|
||||
expect(delRes.status).toBe(200);
|
||||
expect((await delRes.json()) as { ok: boolean }).toEqual({ ok: true });
|
||||
|
||||
// Gone from the list
|
||||
const after = await request("/api/v1/feeds", { headers: authHeaders });
|
||||
const afterList = (await after.json()) as { feeds: { id: string }[] };
|
||||
expect(afterList.feeds.map((f) => f.id)).not.toContain(created.id);
|
||||
});
|
||||
|
||||
it("returns 400 for an invalid create body", async () => {
|
||||
const res = await request("/api/v1/feeds", {
|
||||
method: "POST",
|
||||
headers: { ...authHeaders, "Content-Type": "application/json" },
|
||||
body: JSON.stringify({ title: "" }),
|
||||
});
|
||||
expect(res.status).toBe(400);
|
||||
expect((await res.json()) as { error: string }).toHaveProperty("error");
|
||||
});
|
||||
|
||||
it("returns 404 when getting a missing feed", async () => {
|
||||
const res = await request("/api/v1/feeds/does-not-exist", {
|
||||
headers: authHeaders,
|
||||
});
|
||||
expect(res.status).toBe(404);
|
||||
});
|
||||
|
||||
it("returns 404 when deleting a missing feed", async () => {
|
||||
const res = await request("/api/v1/feeds/does-not-exist", {
|
||||
method: "DELETE",
|
||||
headers: authHeaders,
|
||||
});
|
||||
expect(res.status).toBe(404);
|
||||
});
|
||||
|
||||
it("returns 404 when updating a missing feed", async () => {
|
||||
const res = await request("/api/v1/feeds/does-not-exist", {
|
||||
method: "PATCH",
|
||||
headers: { ...authHeaders, "Content-Type": "application/json" },
|
||||
body: JSON.stringify({ title: "x" }),
|
||||
});
|
||||
expect(res.status).toBe(404);
|
||||
});
|
||||
});
|
||||
|
||||
describe("Emails", () => {
|
||||
it("lists, reads and deletes an email", async () => {
|
||||
const feedId = await createFeed();
|
||||
|
||||
// Seed an email directly into KV (mirrors storeEmail's key shape).
|
||||
const receivedAt = 1737000000000;
|
||||
const key = `feed:${feedId}:email:${receivedAt}`;
|
||||
await mockEnv.EMAIL_STORAGE.put(
|
||||
key,
|
||||
JSON.stringify({
|
||||
subject: "Hello",
|
||||
from: "news@example.com",
|
||||
content: "<p>hi</p>",
|
||||
receivedAt,
|
||||
headers: {},
|
||||
}),
|
||||
);
|
||||
await mockEnv.EMAIL_STORAGE.put(
|
||||
`feed:${feedId}:metadata`,
|
||||
JSON.stringify({
|
||||
emails: [{ key, subject: "Hello", receivedAt }],
|
||||
}),
|
||||
);
|
||||
|
||||
// List
|
||||
const listRes = await request(`/api/v1/feeds/${feedId}/emails`, {
|
||||
headers: authHeaders,
|
||||
});
|
||||
expect(listRes.status).toBe(200);
|
||||
const list = (await listRes.json()) as {
|
||||
emails: { entryId: number; subject: string }[];
|
||||
};
|
||||
expect(list.emails).toHaveLength(1);
|
||||
expect(list.emails[0]).toMatchObject({
|
||||
entryId: receivedAt,
|
||||
subject: "Hello",
|
||||
});
|
||||
|
||||
// Get single
|
||||
const getRes = await request(
|
||||
`/api/v1/feeds/${feedId}/emails/${receivedAt}`,
|
||||
{ headers: authHeaders },
|
||||
);
|
||||
expect(getRes.status).toBe(200);
|
||||
expect((await getRes.json()) as { content: string }).toMatchObject({
|
||||
from: "news@example.com",
|
||||
content: "<p>hi</p>",
|
||||
});
|
||||
|
||||
// Delete
|
||||
const delRes = await request(
|
||||
`/api/v1/feeds/${feedId}/emails/${receivedAt}`,
|
||||
{ method: "DELETE", headers: authHeaders },
|
||||
);
|
||||
expect(delRes.status).toBe(200);
|
||||
expect(await mockEnv.EMAIL_STORAGE.get(key)).toBeNull();
|
||||
|
||||
// Gone
|
||||
const after = await request(
|
||||
`/api/v1/feeds/${feedId}/emails/${receivedAt}`,
|
||||
{ headers: authHeaders },
|
||||
);
|
||||
expect(after.status).toBe(404);
|
||||
});
|
||||
|
||||
it("returns 404 listing emails for a missing feed", async () => {
|
||||
const res = await request("/api/v1/feeds/missing/emails", {
|
||||
headers: authHeaders,
|
||||
});
|
||||
expect(res.status).toBe(404);
|
||||
});
|
||||
});
|
||||
|
||||
describe("Stats", () => {
|
||||
it("returns monitoring counters", async () => {
|
||||
await createFeed();
|
||||
const res = await request("/api/v1/stats", { headers: authHeaders });
|
||||
expect(res.status).toBe(200);
|
||||
const stats = (await res.json()) as {
|
||||
feeds_created: number;
|
||||
active_feeds: number;
|
||||
attachments_enabled: boolean;
|
||||
};
|
||||
expect(stats.feeds_created).toBeGreaterThanOrEqual(1);
|
||||
expect(stats.active_feeds).toBeGreaterThanOrEqual(1);
|
||||
expect(typeof stats.attachments_enabled).toBe("boolean");
|
||||
});
|
||||
});
|
||||
|
||||
describe("OpenAPI document", () => {
|
||||
it("serves a public OpenAPI 3.1 spec", async () => {
|
||||
const res = await request("/api/openapi.json");
|
||||
expect(res.status).toBe(200);
|
||||
const doc = (await res.json()) as {
|
||||
openapi: string;
|
||||
paths: Record<string, unknown>;
|
||||
};
|
||||
expect(doc.openapi).toBe("3.1.0");
|
||||
expect(doc.paths).toHaveProperty("/v1/feeds");
|
||||
expect(doc.paths).toHaveProperty("/v1/feeds/{feedId}");
|
||||
expect(doc.paths).toHaveProperty("/v1/stats");
|
||||
});
|
||||
});
|
||||
});
|
||||
@@ -0,0 +1,397 @@
|
||||
import { OpenAPIHono, createRoute, z } from "@hono/zod-openapi";
|
||||
import { Scalar } from "@scalar/hono-api-reference";
|
||||
import { Env, FeedConfig } from "../../types";
|
||||
import { apiAuthMiddleware } from "../../lib/auth";
|
||||
import {
|
||||
createFeedRecord,
|
||||
updateFeedRecord,
|
||||
deleteFeedRecord,
|
||||
} from "../../lib/feed-service";
|
||||
import { listAllFeeds, deleteAttachmentsForEmails } from "../admin/helpers";
|
||||
import {
|
||||
getFeedConfig,
|
||||
getFeedMetadata,
|
||||
getEmailData,
|
||||
} from "../../utils/storage";
|
||||
import { getStats } from "../../utils/stats";
|
||||
import { feedEmailAddress, feedRssUrl, feedAtomUrl } from "../../utils/urls";
|
||||
import {
|
||||
ErrorSchema,
|
||||
FeedIdParam,
|
||||
EntryIdParam,
|
||||
FeedCreateSchema,
|
||||
FeedUpdateSchema,
|
||||
FeedSchema,
|
||||
FeedListSchema,
|
||||
EmailListSchema,
|
||||
EmailSchema,
|
||||
StatsSchema,
|
||||
} from "./schemas";
|
||||
|
||||
type AppEnv = { Bindings: Env };
|
||||
|
||||
const OkSchema = z.object({ ok: z.boolean() }).openapi("Ok");
|
||||
|
||||
const jsonContent = <T>(schema: T, description: string) => ({
|
||||
content: { "application/json": { schema } },
|
||||
description,
|
||||
});
|
||||
|
||||
const bearer = [{ bearerAuth: [] }];
|
||||
|
||||
function normalizeSenders(senders?: string[]): string[] | undefined {
|
||||
return senders?.map((s) => s.trim().toLowerCase()).filter(Boolean);
|
||||
}
|
||||
|
||||
function toFeed(
|
||||
id: string,
|
||||
config: FeedConfig,
|
||||
emailCount: number,
|
||||
env: Env,
|
||||
): z.infer<typeof FeedSchema> {
|
||||
return {
|
||||
id,
|
||||
title: config.title,
|
||||
description: config.description,
|
||||
language: config.language,
|
||||
allowedSenders: config.allowed_senders ?? [],
|
||||
blockedSenders: config.blocked_senders ?? [],
|
||||
createdAt: config.created_at,
|
||||
updatedAt: config.updated_at,
|
||||
expiresAt: config.expires_at,
|
||||
emailCount,
|
||||
emailAddress: feedEmailAddress(id, env),
|
||||
rssUrl: feedRssUrl(id, env),
|
||||
atomUrl: feedAtomUrl(id, env),
|
||||
};
|
||||
}
|
||||
|
||||
export const apiApp = new OpenAPIHono<AppEnv>({
|
||||
defaultHook: (result, c) => {
|
||||
if (!result.success) {
|
||||
const message = result.error.issues
|
||||
.map((i) => `${i.path.join(".")}: ${i.message}`)
|
||||
.join("; ");
|
||||
return c.json({ error: `Validation failed: ${message}` }, 400);
|
||||
}
|
||||
},
|
||||
});
|
||||
|
||||
// Token auth on every /v1 route. The spec + docs stay public.
|
||||
apiApp.use("/v1/*", apiAuthMiddleware);
|
||||
|
||||
apiApp.openAPIRegistry.registerComponent("securitySchemes", "bearerAuth", {
|
||||
type: "http",
|
||||
scheme: "bearer",
|
||||
description: "Use the admin password as the bearer token.",
|
||||
});
|
||||
|
||||
// ── Feeds ─────────────────────────────────────────────────────────────────────
|
||||
|
||||
apiApp.openapi(
|
||||
createRoute({
|
||||
method: "get",
|
||||
path: "/v1/feeds",
|
||||
tags: ["Feeds"],
|
||||
summary: "List all feeds",
|
||||
security: bearer,
|
||||
responses: {
|
||||
200: jsonContent(FeedListSchema, "The list of feeds"),
|
||||
401: jsonContent(ErrorSchema, "Unauthorized"),
|
||||
},
|
||||
}),
|
||||
async (c) => {
|
||||
const env = c.env;
|
||||
const feeds = await listAllFeeds(env.EMAIL_STORAGE);
|
||||
return c.json(
|
||||
{
|
||||
feeds: feeds.map((f) => ({
|
||||
id: f.id,
|
||||
title: f.title,
|
||||
description: f.description,
|
||||
expiresAt: f.expires_at,
|
||||
emailAddress: feedEmailAddress(f.id, env),
|
||||
rssUrl: feedRssUrl(f.id, env),
|
||||
atomUrl: feedAtomUrl(f.id, env),
|
||||
})),
|
||||
},
|
||||
200,
|
||||
);
|
||||
},
|
||||
);
|
||||
|
||||
apiApp.openapi(
|
||||
createRoute({
|
||||
method: "post",
|
||||
path: "/v1/feeds",
|
||||
tags: ["Feeds"],
|
||||
summary: "Create a feed",
|
||||
security: bearer,
|
||||
request: {
|
||||
body: { content: { "application/json": { schema: FeedCreateSchema } } },
|
||||
},
|
||||
responses: {
|
||||
201: jsonContent(FeedSchema, "The created feed"),
|
||||
400: jsonContent(ErrorSchema, "Invalid request body"),
|
||||
401: jsonContent(ErrorSchema, "Unauthorized"),
|
||||
},
|
||||
}),
|
||||
async (c) => {
|
||||
const env = c.env;
|
||||
const body = c.req.valid("json");
|
||||
const { feedId, config } = await createFeedRecord(env, {
|
||||
title: body.title,
|
||||
description: body.description,
|
||||
language: body.language,
|
||||
allowedSenders: normalizeSenders(body.allowedSenders) ?? [],
|
||||
blockedSenders: normalizeSenders(body.blockedSenders) ?? [],
|
||||
lifetimeHours: body.lifetimeHours,
|
||||
});
|
||||
return c.json(toFeed(feedId, config, 0, env), 201);
|
||||
},
|
||||
);
|
||||
|
||||
apiApp.openapi(
|
||||
createRoute({
|
||||
method: "get",
|
||||
path: "/v1/feeds/{feedId}",
|
||||
tags: ["Feeds"],
|
||||
summary: "Get a feed",
|
||||
security: bearer,
|
||||
request: { params: FeedIdParam },
|
||||
responses: {
|
||||
200: jsonContent(FeedSchema, "The feed"),
|
||||
401: jsonContent(ErrorSchema, "Unauthorized"),
|
||||
404: jsonContent(ErrorSchema, "Feed not found"),
|
||||
},
|
||||
}),
|
||||
async (c) => {
|
||||
const env = c.env;
|
||||
const { feedId } = c.req.valid("param");
|
||||
const config = await getFeedConfig(env.EMAIL_STORAGE, feedId);
|
||||
if (!config) return c.json({ error: "Feed not found" }, 404);
|
||||
const metadata = await getFeedMetadata(env.EMAIL_STORAGE, feedId);
|
||||
return c.json(
|
||||
toFeed(feedId, config, metadata?.emails.length ?? 0, env),
|
||||
200,
|
||||
);
|
||||
},
|
||||
);
|
||||
|
||||
apiApp.openapi(
|
||||
createRoute({
|
||||
method: "patch",
|
||||
path: "/v1/feeds/{feedId}",
|
||||
tags: ["Feeds"],
|
||||
summary: "Update a feed",
|
||||
security: bearer,
|
||||
request: {
|
||||
params: FeedIdParam,
|
||||
body: { content: { "application/json": { schema: FeedUpdateSchema } } },
|
||||
},
|
||||
responses: {
|
||||
200: jsonContent(FeedSchema, "The updated feed"),
|
||||
400: jsonContent(ErrorSchema, "Invalid request body"),
|
||||
401: jsonContent(ErrorSchema, "Unauthorized"),
|
||||
404: jsonContent(ErrorSchema, "Feed not found"),
|
||||
409: jsonContent(ErrorSchema, "Feed has expired"),
|
||||
},
|
||||
}),
|
||||
async (c) => {
|
||||
const env = c.env;
|
||||
const { feedId } = c.req.valid("param");
|
||||
const body = c.req.valid("json");
|
||||
const result = await updateFeedRecord(env, feedId, {
|
||||
title: body.title,
|
||||
description: body.description,
|
||||
language: body.language,
|
||||
allowedSenders: normalizeSenders(body.allowedSenders),
|
||||
blockedSenders: normalizeSenders(body.blockedSenders),
|
||||
lifetimeHours: body.lifetimeHours,
|
||||
});
|
||||
if (result.status === "not_found")
|
||||
return c.json({ error: "Feed not found" }, 404);
|
||||
if (result.status === "expired")
|
||||
return c.json({ error: "Feed has expired and cannot be modified" }, 409);
|
||||
const metadata = await getFeedMetadata(env.EMAIL_STORAGE, feedId);
|
||||
return c.json(
|
||||
toFeed(feedId, result.config, metadata?.emails.length ?? 0, env),
|
||||
200,
|
||||
);
|
||||
},
|
||||
);
|
||||
|
||||
apiApp.openapi(
|
||||
createRoute({
|
||||
method: "delete",
|
||||
path: "/v1/feeds/{feedId}",
|
||||
tags: ["Feeds"],
|
||||
summary: "Delete a feed",
|
||||
security: bearer,
|
||||
request: { params: FeedIdParam },
|
||||
responses: {
|
||||
200: jsonContent(OkSchema, "The feed was deleted"),
|
||||
401: jsonContent(ErrorSchema, "Unauthorized"),
|
||||
404: jsonContent(ErrorSchema, "Feed not found"),
|
||||
},
|
||||
}),
|
||||
async (c) => {
|
||||
const env = c.env;
|
||||
const { feedId } = c.req.valid("param");
|
||||
const removed = await deleteFeedRecord(c, env, feedId);
|
||||
if (!removed) return c.json({ error: "Feed not found" }, 404);
|
||||
return c.json({ ok: true }, 200);
|
||||
},
|
||||
);
|
||||
|
||||
// ── Emails ──────────────────────────────────────────────────────────────────
|
||||
|
||||
apiApp.openapi(
|
||||
createRoute({
|
||||
method: "get",
|
||||
path: "/v1/feeds/{feedId}/emails",
|
||||
tags: ["Emails"],
|
||||
summary: "List a feed's emails",
|
||||
security: bearer,
|
||||
request: { params: FeedIdParam },
|
||||
responses: {
|
||||
200: jsonContent(EmailListSchema, "The feed's emails"),
|
||||
401: jsonContent(ErrorSchema, "Unauthorized"),
|
||||
404: jsonContent(ErrorSchema, "Feed not found"),
|
||||
},
|
||||
}),
|
||||
async (c) => {
|
||||
const env = c.env;
|
||||
const { feedId } = c.req.valid("param");
|
||||
const metadata = await getFeedMetadata(env.EMAIL_STORAGE, feedId);
|
||||
if (!metadata) return c.json({ error: "Feed not found" }, 404);
|
||||
return c.json(
|
||||
{
|
||||
emails: metadata.emails.map((e) => ({
|
||||
entryId: e.receivedAt,
|
||||
subject: e.subject,
|
||||
receivedAt: e.receivedAt,
|
||||
size: e.size,
|
||||
attachmentIds: e.attachmentIds,
|
||||
})),
|
||||
},
|
||||
200,
|
||||
);
|
||||
},
|
||||
);
|
||||
|
||||
apiApp.openapi(
|
||||
createRoute({
|
||||
method: "get",
|
||||
path: "/v1/feeds/{feedId}/emails/{entryId}",
|
||||
tags: ["Emails"],
|
||||
summary: "Get a single email",
|
||||
security: bearer,
|
||||
request: { params: EntryIdParam },
|
||||
responses: {
|
||||
200: jsonContent(EmailSchema, "The email"),
|
||||
401: jsonContent(ErrorSchema, "Unauthorized"),
|
||||
404: jsonContent(ErrorSchema, "Email not found"),
|
||||
},
|
||||
}),
|
||||
async (c) => {
|
||||
const env = c.env;
|
||||
const { feedId, entryId } = c.req.valid("param");
|
||||
const receivedAt = parseInt(entryId, 10);
|
||||
const metadata = await getFeedMetadata(env.EMAIL_STORAGE, feedId);
|
||||
const metaEntry = metadata?.emails.find((e) => e.receivedAt === receivedAt);
|
||||
if (!metaEntry) return c.json({ error: "Email not found" }, 404);
|
||||
const data = await getEmailData(env.EMAIL_STORAGE, metaEntry.key);
|
||||
if (!data) return c.json({ error: "Email not found" }, 404);
|
||||
return c.json(
|
||||
{
|
||||
entryId: receivedAt,
|
||||
subject: data.subject,
|
||||
from: data.from,
|
||||
receivedAt: data.receivedAt,
|
||||
content: data.content,
|
||||
attachments: (data.attachments ?? []).map((a) => ({
|
||||
id: a.id,
|
||||
filename: a.filename,
|
||||
contentType: a.contentType,
|
||||
size: a.size,
|
||||
url: `/files/${a.id}/${encodeURIComponent(a.filename)}`,
|
||||
})),
|
||||
},
|
||||
200,
|
||||
);
|
||||
},
|
||||
);
|
||||
|
||||
apiApp.openapi(
|
||||
createRoute({
|
||||
method: "delete",
|
||||
path: "/v1/feeds/{feedId}/emails/{entryId}",
|
||||
tags: ["Emails"],
|
||||
summary: "Delete a single email",
|
||||
security: bearer,
|
||||
request: { params: EntryIdParam },
|
||||
responses: {
|
||||
200: jsonContent(OkSchema, "The email was deleted"),
|
||||
401: jsonContent(ErrorSchema, "Unauthorized"),
|
||||
404: jsonContent(ErrorSchema, "Email not found"),
|
||||
},
|
||||
}),
|
||||
async (c) => {
|
||||
const env = c.env;
|
||||
const emailStorage = env.EMAIL_STORAGE;
|
||||
const { feedId, entryId } = c.req.valid("param");
|
||||
const receivedAt = parseInt(entryId, 10);
|
||||
const metadata = await getFeedMetadata(emailStorage, feedId);
|
||||
const metaEntry = metadata?.emails.find((e) => e.receivedAt === receivedAt);
|
||||
if (!metadata || !metaEntry)
|
||||
return c.json({ error: "Email not found" }, 404);
|
||||
|
||||
await emailStorage.delete(metaEntry.key);
|
||||
await deleteAttachmentsForEmails(env, metadata.emails, [metaEntry.key]);
|
||||
metadata.emails = metadata.emails.filter((e) => e.key !== metaEntry.key);
|
||||
await emailStorage.put(`feed:${feedId}:metadata`, JSON.stringify(metadata));
|
||||
|
||||
return c.json({ ok: true }, 200);
|
||||
},
|
||||
);
|
||||
|
||||
// ── Stats ─────────────────────────────────────────────────────────────────────
|
||||
|
||||
apiApp.openapi(
|
||||
createRoute({
|
||||
method: "get",
|
||||
path: "/v1/stats",
|
||||
tags: ["Stats"],
|
||||
summary: "Read monitoring counters",
|
||||
security: bearer,
|
||||
responses: {
|
||||
200: jsonContent(StatsSchema, "Monitoring counters"),
|
||||
401: jsonContent(ErrorSchema, "Unauthorized"),
|
||||
},
|
||||
}),
|
||||
async (c) => {
|
||||
return c.json(await getStats(c.env), 200);
|
||||
},
|
||||
);
|
||||
|
||||
// ── OpenAPI document + docs (public) ───────────────────────────────────────────
|
||||
|
||||
apiApp.doc31("/openapi.json", {
|
||||
openapi: "3.1.0",
|
||||
info: {
|
||||
title: "kill-the-news API",
|
||||
version: "1.0.0",
|
||||
description:
|
||||
"REST API for managing email-to-RSS feeds, their emails, and monitoring counters.",
|
||||
},
|
||||
servers: [{ url: "/api" }],
|
||||
});
|
||||
|
||||
apiApp.get(
|
||||
"/docs",
|
||||
Scalar({
|
||||
url: "/api/openapi.json",
|
||||
pageTitle: "kill-the-news API",
|
||||
}),
|
||||
);
|
||||
@@ -0,0 +1,153 @@
|
||||
import { z } from "@hono/zod-openapi";
|
||||
|
||||
// ── Shared ──────────────────────────────────────────────────────────────────
|
||||
|
||||
export const ErrorSchema = z
|
||||
.object({
|
||||
error: z.string().openapi({ example: "Feed not found" }),
|
||||
})
|
||||
.openapi("Error");
|
||||
|
||||
export const FeedIdParam = z.object({
|
||||
feedId: z
|
||||
.string()
|
||||
.min(1)
|
||||
.openapi({
|
||||
param: { name: "feedId", in: "path" },
|
||||
example: "happy-otter-1234",
|
||||
}),
|
||||
});
|
||||
|
||||
export const EntryIdParam = FeedIdParam.extend({
|
||||
entryId: z
|
||||
.string()
|
||||
.regex(/^\d+$/, "entryId must be the email's receivedAt timestamp")
|
||||
.openapi({
|
||||
param: { name: "entryId", in: "path" },
|
||||
example: "1737000000000",
|
||||
}),
|
||||
});
|
||||
|
||||
// ── Feeds ───────────────────────────────────────────────────────────────────
|
||||
|
||||
export const FeedCreateSchema = z
|
||||
.object({
|
||||
title: z.string().min(1).openapi({ example: "Daily Tech Digest" }),
|
||||
description: z.string().optional(),
|
||||
language: z.string().optional().default("en"),
|
||||
allowedSenders: z.array(z.string()).optional().default([]),
|
||||
blockedSenders: z.array(z.string()).optional().default([]),
|
||||
lifetimeHours: z.number().int().positive().optional().openapi({
|
||||
description:
|
||||
"Hours until the feed expires. Ignored when the server enforces a fixed FEED_TTL_HOURS.",
|
||||
}),
|
||||
})
|
||||
.openapi("FeedCreate");
|
||||
|
||||
export const FeedUpdateSchema = z
|
||||
.object({
|
||||
title: z.string().min(1).optional(),
|
||||
description: z.string().optional(),
|
||||
language: z.string().optional(),
|
||||
allowedSenders: z.array(z.string()).optional(),
|
||||
blockedSenders: z.array(z.string()).optional(),
|
||||
lifetimeHours: z.number().int().positive().optional().openapi({
|
||||
description: "Reset the feed's lifetime to this many hours from now.",
|
||||
}),
|
||||
})
|
||||
.openapi("FeedUpdate");
|
||||
|
||||
export const FeedSummarySchema = z
|
||||
.object({
|
||||
id: z.string(),
|
||||
title: z.string(),
|
||||
description: z.string().optional(),
|
||||
expiresAt: z.number().optional(),
|
||||
emailAddress: z.string(),
|
||||
rssUrl: z.string(),
|
||||
atomUrl: z.string(),
|
||||
})
|
||||
.openapi("FeedSummary");
|
||||
|
||||
export const FeedListSchema = z
|
||||
.object({ feeds: z.array(FeedSummarySchema) })
|
||||
.openapi("FeedList");
|
||||
|
||||
export const FeedSchema = z
|
||||
.object({
|
||||
id: z.string(),
|
||||
title: z.string(),
|
||||
description: z.string().optional(),
|
||||
language: z.string(),
|
||||
allowedSenders: z.array(z.string()),
|
||||
blockedSenders: z.array(z.string()),
|
||||
createdAt: z.number(),
|
||||
updatedAt: z.number().optional(),
|
||||
expiresAt: z.number().optional(),
|
||||
emailCount: z.number(),
|
||||
emailAddress: z.string(),
|
||||
rssUrl: z.string(),
|
||||
atomUrl: z.string(),
|
||||
})
|
||||
.openapi("Feed");
|
||||
|
||||
// ── Emails ──────────────────────────────────────────────────────────────────
|
||||
|
||||
export const EmailSummarySchema = z
|
||||
.object({
|
||||
entryId: z.number().openapi({
|
||||
description: "Email receivedAt timestamp; used as the path id.",
|
||||
}),
|
||||
subject: z.string(),
|
||||
receivedAt: z.number(),
|
||||
size: z.number().optional(),
|
||||
attachmentIds: z.array(z.string()).optional(),
|
||||
})
|
||||
.openapi("EmailSummary");
|
||||
|
||||
export const EmailListSchema = z
|
||||
.object({ emails: z.array(EmailSummarySchema) })
|
||||
.openapi("EmailList");
|
||||
|
||||
export const AttachmentSchema = z
|
||||
.object({
|
||||
id: z.string(),
|
||||
filename: z.string(),
|
||||
contentType: z.string(),
|
||||
size: z.number(),
|
||||
url: z.string(),
|
||||
})
|
||||
.openapi("Attachment");
|
||||
|
||||
export const EmailSchema = z
|
||||
.object({
|
||||
entryId: z.number(),
|
||||
subject: z.string(),
|
||||
from: z.string(),
|
||||
receivedAt: z.number(),
|
||||
content: z.string(),
|
||||
attachments: z.array(AttachmentSchema),
|
||||
})
|
||||
.openapi("Email");
|
||||
|
||||
// ── Stats ───────────────────────────────────────────────────────────────────
|
||||
|
||||
export const StatsSchema = z
|
||||
.object({
|
||||
feeds_created: z.number(),
|
||||
feeds_deleted: z.number(),
|
||||
emails_received: z.number(),
|
||||
emails_rejected: z.number(),
|
||||
unsubscribes_sent: z.number(),
|
||||
active_feeds: z.number(),
|
||||
websub_subscriptions_active: z.number(),
|
||||
attachments_enabled: z.boolean(),
|
||||
last_email_at: z.string().optional(),
|
||||
last_feed_created_at: z.string().optional(),
|
||||
first_seen: z.string().optional(),
|
||||
attachments_bytes: z.number().optional(),
|
||||
attachments_count: z.number().optional(),
|
||||
kv_bytes_estimated: z.number().optional(),
|
||||
storage_scanned_at: z.string().optional(),
|
||||
})
|
||||
.openapi("Stats");
|
||||
Reference in New Issue
Block a user