feedkeeper 0.25.1 → 0.26.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "feedkeeper",
-  "version": "0.25.1",
+  "version": "0.26.0",
   "description": "A lightweight, self-hosted RSS reader and remote MCP server for your news, blogs, and AI workflows.",
   "keywords": [
     "rss",

package/server/dist/api/v1/index.js

@@ -38,6 +38,7 @@ const FEATURES = [
     "native-preferences",
     "native-preferences.edition-size",
     "edition.overview",
+    "edition.layout",
     "search.fts",
     "account-capabilities",
     "mcp",

package/server/dist/db/migrations/0034_edition_layout.sql

@@ -0,0 +1,2 @@
+-- Optional presentation plan for native editions; null for automatic and unstructured issues.
+ALTER TABLE editions ADD COLUMN layout TEXT CHECK (layout IS NULL OR json_valid(layout));

package/server/dist/mcp/server.js

@@ -500,7 +500,7 @@ export function createMcpServerForUser(userId, scope) {
     if (scope === "write")
         server.registerTool("publish_edition", {
             title: "Publish curated edition",
-            description: "Publishes an ordered list of 1 to 24 accessible article IDs. Curated editions override automatic ones until expiry (default 24 hours, maximum seven days). App-only hidden sections and muted keywords are respected. Supply the revision from get_edition as expectedRevision and a UUID requestId for conflict detection and safe retries. Optional title and summary are editorial text; original articles stay unchanged.",
+            description: "Publishes an ordered list of 1 to 24 accessible article IDs. Curated editions override automatic ones until expiry (default 24 hours, maximum seven days). App-only hidden sections and muted keywords are respected. Supply the revision from get_edition as expectedRevision and a UUID requestId for conflict detection and safe retries. Optional title and summary are editorial text; original articles stay unchanged. Optional layout (version 1) says how the issue is set: a character (dominant, calm or briefing) and blocks (lead, dossier, feature, standard, briefs, photo, quote) that reference the issue's article IDs at most once each; it never changes the articles.",
             inputSchema: publishEditionFields,
         }, async (input) => capabilityAction("editions", () => publishCuratedEdition(userId, input)));
     if (scope === "write")

package/server/dist/native/editionLayout.js

@@ -0,0 +1,66 @@
+import { z } from "zod";
+import { NativeError } from "./requests.js";
+/**
+ * A presentation plan for an edition. It says what the issue's writer considers important and what belongs together,
+ * never how a screen draws it: clients map the roles onto their own columns, sizes and type.
+ *
+ * Versioned and strict. A client that meets a block type it does not know sets that block's stories as plain ones.
+ */
+const itemId = z.number().int().positive();
+/** A short label above a headline: a classification, not a statement. */
+const kicker = z.string().trim().min(1).max(40)
+    .refine((value) => !/[\r\n]/.test(value) && !/[.!?:;,]$/.test(value), "A kicker is one short phrase without closing punctuation");
+const story = { itemId, kicker: kicker.optional() };
+const block = z.discriminatedUnion("type", [
+    /** The story of the day; only once and only first. */
+    z.object({ type: z.literal("lead"), ...story }).strict(),
+    /** One overview topic (1-based position in `overview`) with the stories it is about. */
+    z.object({ type: z.literal("dossier"), topic: z.number().int().min(1).max(5), itemIds: z.array(itemId).min(1).max(4) }).strict(),
+    z.object({ type: z.literal("feature"), ...story }).strict(),
+    z.object({ type: z.literal("standard"), stories: z.array(z.object(story).strict()).min(1).max(3) }).strict(),
+    z.object({ type: z.literal("briefs"), itemIds: z.array(itemId).min(2).max(8), title: z.string().trim().min(1).max(60).optional() }).strict(),
+    z.object({ type: z.literal("photo"), itemId }).strict(),
+    /** A statement of an article set large. The issuer vouches that the text is quoted from the article. */
+    z.object({ type: z.literal("quote"), itemId, text: z.string().trim().min(1).max(160) }).strict(),
+]);
+export const editionLayoutSchema = z.object({
+    version: z.literal(1),
+    character: z.enum(["dominant", "calm", "briefing"]),
+    blocks: z.array(block).min(1).max(24),
+}).strict();
+function blockItemIds(block) {
+    switch (block.type) {
+        case "standard": return block.stories.map((entry) => entry.itemId);
+        case "dossier":
+        case "briefs": return block.itemIds;
+        default: return [block.itemId];
+    }
+}
+/**
+ * Checks a well-formed plan against the issue it is published with: every story is in the issue and appears once,
+ * the lead stands first, and every topic exists and has one dossier at most.
+ */
+export function checkEditionLayout(layout, itemIds, topicCount) {
+    const allowed = new Set(itemIds);
+    const used = new Set();
+    const topics = new Set();
+    layout.blocks.forEach((block, index) => {
+        if (block.type === "lead" && index !== 0)
+            throw new NativeError("invalid_layout");
+        if (block.type === "dossier") {
+            if (block.topic > topicCount)
+                throw new NativeError("invalid_layout_reference");
+            if (topics.has(block.topic))
+                throw new NativeError("invalid_layout");
+            topics.add(block.topic);
+        }
+        for (const id of blockItemIds(block)) {
+            if (!allowed.has(id))
+                throw new NativeError("invalid_layout_reference");
+            if (used.has(id))
+                throw new NativeError("invalid_layout");
+            used.add(id);
+        }
+    });
+}
+//# sourceMappingURL=editionLayout.js.map

package/server/dist/native/editions.js

@@ -7,6 +7,7 @@ import { canAccessItem } from "../feeds/repository.js";
 import { decodeEntities } from "../feeds/text.js";
 import { editionPeriod, nextEditionBoundary, selectEdition } from "./editionSelection.js";
 import { getNativePreferences } from "./preferences.js";
+import { checkEditionLayout, editionLayoutSchema } from "./editionLayout.js";
 import { NativeError, nativeRequest } from "./requests.js";
 export const overviewSchema = z.array(z.object({
     heading: z.string().trim().min(1).max(160),
@@ -24,7 +25,8 @@ function serialize(row) {
         id: row.edition_id, revision: row.revision, source: row.source,
         createdAt: row.created_at, updatedAt: row.updated_at, expiresAt: row.expires_at,
         period: row.period?.split(":")[1] ?? editionPeriod(new Date(row.created_at), prefs.timeZone).period,
-        title: row.title, summary: row.summary, overview: row.overview ? JSON.parse(row.overview) : null, preferencesRevision: row.preferences_revision,
+        title: row.title, summary: row.summary, overview: row.overview ? JSON.parse(row.overview) : null, layout: row.layout ? JSON.parse(row.layout) : null,
+        preferencesRevision: row.preferences_revision,
         itemIds: JSON.parse(row.item_ids),
     };
 }
@@ -43,18 +45,19 @@ function checkRevision(userId, expectedRevision, now) {
     if (expectedRevision !== undefined && current.revision !== expectedRevision)
         throw new NativeError("revision_conflict", 409, current);
 }
-function writeEdition(userId, itemIds, source, expiry, now, title = null, summary = null, overview = null) {
+function writeEdition(userId, itemIds, source, expiry, now, title = null, summary = null, overview = null, layout = null) {
     const prefs = getNativePreferences(userId);
     const id = randomUUID();
     const revision = (storedEdition(userId)?.revision ?? 0) + 1;
     const created = now.toISOString();
-    db.prepare(`INSERT INTO editions (user_id, edition_id, item_ids, revision, source, status, created_at, updated_at, expires_at, period, title, summary, preferences_revision, overview)
-    VALUES (?, ?, ?, ?, ?, 'active', ?, ?, ?, ?, ?, ?, ?, ?)
+    db.prepare(`INSERT INTO editions (user_id, edition_id, item_ids, revision, source, status, created_at, updated_at, expires_at, period, title, summary, preferences_revision, overview, layout)
+    VALUES (?, ?, ?, ?, ?, 'active', ?, ?, ?, ?, ?, ?, ?, ?, ?)
     ON CONFLICT(user_id) DO UPDATE SET edition_id = excluded.edition_id, item_ids = excluded.item_ids,
       revision = excluded.revision, source = excluded.source, status = 'active', created_at = excluded.created_at,
       updated_at = excluded.updated_at, expires_at = excluded.expires_at, period = excluded.period,
-      title = excluded.title, summary = excluded.summary, preferences_revision = excluded.preferences_revision, overview = excluded.overview`)
-        .run(userId, id, JSON.stringify(itemIds), revision, source, created, created, expiry.toISOString(), editionPeriod(now, prefs.timeZone).key, title, summary, prefs.revision, overview ? JSON.stringify(overview.map((block, index) => ({ id: `topic-${index + 1}`, ...block }))) : null);
+      title = excluded.title, summary = excluded.summary, preferences_revision = excluded.preferences_revision, overview = excluded.overview,
+      layout = excluded.layout`)
+        .run(userId, id, JSON.stringify(itemIds), revision, source, created, created, expiry.toISOString(), editionPeriod(now, prefs.timeZone).key, title, summary, prefs.revision, overview ? JSON.stringify(overview.map((block, index) => ({ id: `topic-${index + 1}`, ...block }))) : null, layout ? JSON.stringify(layout) : null);
     db.prepare("INSERT INTO edition_history (user_id, edition_id, item_ids, revision, created_at) VALUES (?, ?, ?, ?, ?)")
         .run(userId, id, JSON.stringify(itemIds), revision, created);
     db.prepare(`DELETE FROM edition_history WHERE user_id = ? AND edition_id NOT IN
@@ -71,11 +74,14 @@ export const publishEditionFields = {
     title: z.string().trim().min(1).max(200).optional(),
     summary: z.string().trim().min(1).max(2000).optional(),
     overview: overviewSchema.optional(),
+    layout: editionLayoutSchema.optional(),
 };
 const publishSchema = z.object(publishEditionFields).strict().refine((input) => !(input.expiresAt && input.durationHours), "Use expiresAt or durationHours, not both");
 /** Both automatic and MCP editions obey the app's hard exclusions. Read/saved articles
  * may be selected deliberately by an agent, but foreign and muted items cannot be published. */
 export function publishCuratedEdition(userId, input, now = new Date()) {
+    if (input.layout !== undefined && !editionLayoutSchema.safeParse(input.layout).success)
+        throw new NativeError("invalid_layout");
     const parsed = publishSchema.safeParse(input);
     if (!parsed.success)
         throw new NativeError("invalid_input");
@@ -88,6 +94,8 @@ export function publishCuratedEdition(userId, input, now = new Date()) {
             block.segments.some((segment) => segment.itemId !== undefined && !data.itemIds.includes(segment.itemId)))) {
             throw new NativeError("invalid_overview_reference");
         }
+        if (data.layout)
+            checkEditionLayout(data.layout, data.itemIds, data.overview?.length ?? 0);
         const prefs = getNativePreferences(userId);
         for (const id of data.itemIds) {
             if (!canAccessItem(userId, id))
@@ -103,7 +111,7 @@ export function publishCuratedEdition(userId, input, now = new Date()) {
         const expiry = data.expiresAt ? new Date(data.expiresAt) : new Date(now.getTime() + (data.durationHours ?? 24) * 3_600_000);
         if (expiry.getTime() <= now.getTime() || expiry.getTime() > now.getTime() + 168 * 3_600_000)
             throw new NativeError("invalid_expiry");
-        return writeEdition(userId, data.itemIds, "curated", expiry, now, data.title ?? null, data.summary ?? (data.overview?.map((block) => `${block.heading}: ${block.segments.map((segment) => segment.text).join("")}`).join("\n\n").slice(0, 2000).replace(/[\uD800-\uDBFF]$/, "") ?? null), data.overview ?? null);
+        return writeEdition(userId, data.itemIds, "curated", expiry, now, data.title ?? null, data.summary ?? (data.overview?.map((block) => `${block.heading}: ${block.segments.map((segment) => segment.text).join("")}`).join("\n\n").slice(0, 2000).replace(/[\uD800-\uDBFF]$/, "") ?? null), data.overview ?? null, data.layout ?? null);
     }, now);
 }
 /** Compatibility entry point for existing internal callers. New agents supply a

package/server/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@feedkeeper/server",
-  "version": "0.25.1",
+  "version": "0.26.0",
   "private": true,
   "type": "module"
 }