Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
4 changes: 2 additions & 2 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -148,8 +148,8 @@ listed under [In progress](#in-progress), and what comes next under [Planned](#p
templates to start from, a search by their words, a download as Markdown, and Undo and Recently deleted instead of a
confirm. Export an asset or a collection as an evidence PDF with everything Lens found about it, or the parts you
pick. Publish a namespace's resources, episodes, timeline activities or text as a private RSS feed or a podcast
feed that any feed reader or podcast app follows, and let a routine fill it on a schedule with what's new, or make
an episode about the week's new resources. ([Podcasts](docs/podcasts.md),
feed that any feed reader or podcast app follows (Feeds, from the Podcasts page), and let a routine fill it on a schedule with
what's new, or make an episode about the week's new resources. ([Podcasts](docs/podcasts.md),
[specs from transcripts](docs/notes.md#specs-from-transcripts), [notes](docs/notes.md),
[evidence PDFs](docs/api.md#evidence-pdfs), [published feeds](docs/feeds.md);
[checks](docs/requirements.md#learn-from-it))
Expand Down
5 changes: 5 additions & 0 deletions changelog.d/feeds-page.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,5 @@
- **Feeds in the web app.** The Feeds page, opened from Podcasts and under Explore once there is a feed, lists your
published feeds; New feed asks for a title, kind and namespace (Enter makes it); a feed's page copies the address in
one click, gets a new one, edits what readers show, takes items out and deletes the feed with Undo instead of a
confirm. The publishing nodes are on the canvas, with the feed picked from a list ([In the web
app](docs/feeds.md#in-the-web-app)).
25 changes: 22 additions & 3 deletions docs/feeds.md
Original file line number Diff line number Diff line change
@@ -1,7 +1,7 @@
# Published feeds (RSS and podcasts)

**Status: in progress.** Feeds, their private addresses, the API, the MCP tools and the workflow nodes that let a
routine fill a feed or make an episode on a schedule are built. The Feeds page in the web app comes next.
**Status: built.** Feeds, their private addresses, the API, the MCP tools, the workflow nodes that let a routine fill a
feed or make an episode on a schedule, and the Feeds page in the web app.

A namespace can publish what's in it as a feed that any feed reader or podcast app follows: new resources, podcast
episodes, things on the timeline, or text a person or an agent wrote. Each feed has a private address; add it to the
Expand Down Expand Up @@ -48,6 +48,24 @@ again adds only what's new. A feed lists its newest items (50 by default, up to
Feed readers poll; the feed answers `304 Not Modified` when nothing changed (its `ETag`), and notes when a reader
last read it (`fetched_at`, at most once a minute), so the web app can show that a podcast app is subscribed.

## In the web app

**Feeds** lists the feeds in the namespaces you can read: each one's kind, namespace, how many items it holds and when
an app last read it. Open it with **Feeds** at the top of the Podcasts page, or Jump to; once there's a feed, it's also
under Explore in the navigation (left out before that, so a phone's menu stays as short as it was). **New feed** asks
for a title (focused; Enter makes it), the kind and the namespace, which is the one picked in the top bar when you can
edit it; the feed opens on its page.

A feed's page shows its address with a **Copy** button, when an app last read it, and **New address** (editors), which
stops the old one at once. Editors change what readers show (title, description, author, language, category, artwork,
how many items a reader sees, and whether a podcast is explicit) and save with Enter. The items are listed newest
first, each a link to what it's about; **Remove** takes one out at once with an Undo in the toast, which adds the same
thing again. **Delete** deletes the feed at once with an Undo, which makes it again with its settings and items, at a
new address (the old token is gone for good). What a feed listed stays in Lens either way.

On the canvas, a graph workflow's palette has the publishing nodes under Data (Select assets, Select activities) and
Keep (Publish to feed, Podcast episode); a feed is picked from a list, and the canvas names it on the node.

## From a routine

A routine fills a feed on a schedule with a graph workflow ([Publishing from the graph](processing.md#publishing-from-the-graph)):
Expand Down Expand Up @@ -76,4 +94,5 @@ Agents use the MCP tools `list_feeds` (each feed's address, or one feed with its

Refine later: artwork Lens makes for a feed without an `image`; Atom and JSON Feed alongside RSS; chapters and
transcripts in a podcast feed (`podcast:transcript`); an automation action that publishes to a feed when something
happens.
happens; a preview of the feed's XML on its page; Try on the canvas listing what Publish to feed would add, item by
item.
6 changes: 4 additions & 2 deletions docs/processing.md
Original file line number Diff line number Diff line change
Expand Up @@ -840,8 +840,10 @@ schedule. Their nodes:
*namespace* named, else the *feed*'s, else where an admin's episode goes; a source its readers couldn't read is left
out. With a *feed*, the episode is added to it and listed once it's made.

A run's result counts what was `published` and the `episodes` made, and its log says what each node did. Try on the
canvas runs a graph workflow over the namespaces you pick and says what each node would do, without publishing. So
A run's result counts what was `published` and the `episodes` made, and its log says what each node did. On the
canvas the nodes are under Data and Keep in a graph workflow's palette, the feed is picked from a list, and the canvas
says what to fix before Publish (a feed to choose, a limit over the most). Try on the canvas runs a graph workflow over
the namespaces you pick and says what each node would do, without publishing. So
Select assets → Podcast episode (feed *Weekly*, length 10) on a routine that runs every Monday makes an episode about
the week's new resources and puts it in your podcast app; Select activities (kinds `asset.added`) → Publish to feed
puts the timeline in your feed reader.
1 change: 1 addition & 0 deletions docs/requirements.md
Original file line number Diff line number Diff line change
Expand Up @@ -178,6 +178,7 @@ request, to another check that proves the same thing; loosening a requirement or
| Undo and Recently deleted instead of a confirm | [test_notebook.py](https://github.com/adeelahmad/lense/blob/main/fastapi_backend/tests/api/test_notebook.py) `test_recently_deleted`; [notes-delete.test.tsx](https://github.com/adeelahmad/lense/blob/main/nextjs-frontend/__tests__/notes-delete.test.tsx) |
| A namespace publishes a private RSS feed or a podcast feed (Apple Podcasts' tags, audio with byte ranges) of resources, episodes, timeline activities and text, holding only what its readers can already read; through the API and MCP | [test_feeds.py](https://github.com/adeelahmad/lense/blob/main/fastapi_backend/tests/api/test_feeds.py) `test_making_filling_and_reading_a_feed`, `test_a_podcast_feed_lists_what_has_audio`, `test_timeline_activities_in_a_feed`, `test_vaults_and_settings`, `test_agents_use_feeds` |
| A routine fills a feed on a schedule, or makes a podcast episode about what's new: graph workflow nodes pick the resources or timeline activities since the last run, add them to a feed, or make an episode about them; Try says what they would do | [test_feed_nodes.py](https://github.com/adeelahmad/lense/blob/main/fastapi_backend/tests/api/test_feed_nodes.py) `test_a_routine_publishes_new_resources_to_a_feed`, `test_a_routine_publishes_the_timeline_and_text`, `test_a_routine_makes_an_episode_and_the_feed_lists_it_once_made`, `test_try_says_what_it_would_do_and_bad_settings_are_refused` |
| Feeds in the web app: a Feeds page, reached from the Podcasts page and under Explore once there is a feed; New feed with the title focused and Enter making it in the current namespace; a feed's page copies the address in one click, gets a new one, edits what readers show, and takes items out or deletes the feed with Undo instead of a confirm; the publishing nodes on the canvas, checked before Publish | [feeds-ui.test.tsx](https://github.com/adeelahmad/lense/blob/main/nextjs-frontend/__tests__/feeds-ui.test.tsx) `the Feeds page lists each feed with its kind, namespace, items and whether an app reads it`, `New feed opens on the title, defaults to the current namespace, and Enter makes it and opens its page`, `a feed's page copies the address, gets a new one, and takes an item out with Undo`, `deleting a feed is undone by making it again with its items, at a new address`, `editors change what readers show, and Enter in a field saves`; [workflow-flow.test.ts](https://github.com/adeelahmad/lense/blob/main/nextjs-frontend/__tests__/workflow-flow.test.ts) `a Select node into Publish to feed or Podcast episode is a whole graph workflow`, `says what to fix: a feed to choose, the limits, and a graph that publishes nothing`, `names the selection and the feed on the canvas`; [nav-groups.test.tsx](https://github.com/adeelahmad/lense/blob/main/nextjs-frontend/__tests__/nav-groups.test.tsx) `feeds are under Explore, after Podcasts, for everyone`, `Feeds is in the nav only once there is a feed, so a phone's nav stays as short as it was` |
| An asset or a collection exported as an evidence PDF, whole or the parts you pick | [test_evidence.py](https://github.com/adeelahmad/lense/blob/main/fastapi_backend/tests/api/test_evidence.py) `test_a_collection_as_one_evidence_pdf`, `test_everything_lens_found_goes_in`, `test_picking_the_parts`; [evidence-parts.test.tsx](https://github.com/adeelahmad/lense/blob/main/nextjs-frontend/__tests__/evidence-parts.test.tsx) |

## Automate it
Expand Down
249 changes: 249 additions & 0 deletions nextjs-frontend/__tests__/feeds-ui.test.tsx
Original file line number Diff line number Diff line change
@@ -0,0 +1,249 @@
import { QueryClient, QueryClientProvider } from "@tanstack/react-query";
import { fireEvent, render, screen, waitFor, within } from "@testing-library/react";
import "@testing-library/jest-dom";
import type { ReactNode } from "react";

import { Feeds } from "@/app/openapi-client";
import type { Feed, FeedItem } from "@/app/openapi-client/types.gen";
import { FeedPage } from "@/components/feeds/feed-page";
import { FeedsScreen } from "@/components/feeds/feeds-screen";
import { ToastProvider } from "@/components/ui/toast";
import { TooltipProvider } from "@/components/ui/tooltip";

jest.mock("@/app/openapi-client", () => ({
Feeds: {
listFeeds: jest.fn(),
createFeed: jest.fn(),
getFeed: jest.fn(),
updateFeed: jest.fn(),
deleteFeed: jest.fn(),
rotateFeedToken: jest.fn(),
listFeedItems: jest.fn(),
publishToFeed: jest.fn(),
removeFeedItem: jest.fn(),
},
}));
jest.mock("next-auth/react", () => ({ useSession: () => ({ data: { accessToken: "t" } }) }));
const push = jest.fn();
const replace = jest.fn();
jest.mock("next/navigation", () => ({ useRouter: () => ({ push, replace }) }));
jest.mock("@/lib/hooks/session", () => ({
useArchive: () => ({
admin: true,
namespace: "home",
namespaces: [
{ id: 3, name: "home" },
{ id: 4, name: "work" },
],
can: () => true,
}),
}));

const ok = (data: unknown) => Promise.resolve({ data, response: { ok: true, status: 200 } });
const m = (f: unknown) => f as jest.Mock;
let writeText: jest.Mock;
beforeAll(() => {
// Radix's checkbox measures itself; jsdom has no ResizeObserver
global.ResizeObserver = class {
observe() {}
unobserve() {}
disconnect() {}
} as unknown as typeof ResizeObserver;
});
beforeEach(() => {
jest.clearAllMocks();
writeText = jest.fn(() => Promise.resolve());
Object.assign(navigator, { clipboard: { writeText } });
});

const WEEKLY: Feed = {
id: 7,
space: 3,
namespace: "home",
kind: "podcast",
title: "Weekly",
author: "Lens",
explicit: false,
max_items: 50,
url: "https://lens.local/api/v1/feeds/public/lfd_secret1",
path: "/api/v1/feeds/public/lfd_secret1",
page: "/feeds/7",
items: 2,
last_item_at: "2026-10-17T10:00:00+00:00",
fetched_at: null,
created_at: "2026-10-10T10:00:00+00:00",
};
const NEWS: Feed = {
...WEEKLY,
id: 8,
kind: "rss",
title: "What’s new",
items: 0,
fetched_at: "2026-10-17T12:00:00+00:00",
};
const ITEMS: FeedItem[] = [
{
id: 1,
feed: 7,
kind: "episode",
guid: "recording/31",
title: "Capsids and shipments",
summary: "Two hosts on the week’s papers.",
published_at: "2026-10-17T10:00:00+00:00",
recording: 31,
by: "routine:2",
},
{
id: 2,
feed: 7,
kind: "text",
guid: "text/digest-41",
title: "Weekly digest",
summary: "2 new this week",
link: "https://example.org/digest/41",
published_at: "2026-10-16T10:00:00+00:00",
},
];

function wrap(ui: ReactNode) {
const qc = new QueryClient({ defaultOptions: { queries: { retry: false } } });
return render(
<QueryClientProvider client={qc}>
<TooltipProvider>
<ToastProvider>{ui}</ToastProvider>
</TooltipProvider>
</QueryClientProvider>,
);
}

test("the Feeds page lists each feed with its kind, namespace, items and whether an app reads it", async () => {
m(Feeds.listFeeds).mockReturnValue(ok([WEEKLY, NEWS]));
wrap(<FeedsScreen />);
const weekly = await screen.findByRole("link", { name: /Weekly/ });
expect(weekly).toHaveAttribute("href", "/feeds/7");
expect(within(weekly).getByText("Podcast")).toBeInTheDocument();
expect(within(weekly).getByText("home")).toBeInTheDocument();
expect(within(weekly).getByText("2 items")).toBeInTheDocument();
expect(within(weekly).getByText("not read by an app yet")).toBeInTheDocument();
const news = screen.getByRole("link", { name: /What’s new/ });
expect(within(news).getByText("RSS")).toBeInTheDocument();
expect(within(news).getByText("Nothing in it yet")).toBeInTheDocument();
expect(within(news).getByText(/^read/)).toBeInTheDocument();
// the top bar's namespace narrows the list
expect(m(Feeds.listFeeds).mock.calls[0][0].query).toEqual({ namespace: "home" });
});

test("New feed opens on the title, defaults to the current namespace, and Enter makes it and opens its page", async () => {
m(Feeds.listFeeds).mockReturnValue(ok([]));
m(Feeds.createFeed).mockReturnValue(ok({ ...NEWS, id: 9, title: "Inbox" }));
wrap(<FeedsScreen />);
expect(await screen.findByText("No feeds yet")).toBeInTheDocument();
fireEvent.click(screen.getAllByRole("button", { name: "New feed" })[0]);
const title = await screen.findByLabelText("Title");
await waitFor(() => expect(title).toHaveFocus());
expect(screen.getByLabelText("Namespace")).toHaveValue("home");
expect(screen.getByLabelText("Kind")).toHaveValue("rss");
fireEvent.change(title, { target: { value: "Inbox" } });
fireEvent.keyDown(title, { key: "Enter" });
await waitFor(() => expect(Feeds.createFeed).toHaveBeenCalledTimes(1));
expect(m(Feeds.createFeed).mock.calls[0][0].body).toEqual({ title: "Inbox", kind: "rss", namespace: "home" });
await waitFor(() => expect(push).toHaveBeenCalledWith("/feeds/9"));
expect(await screen.findByText("Feed made")).toBeInTheDocument();
});

test("a feed's page copies the address, gets a new one, and takes an item out with Undo", async () => {
m(Feeds.getFeed).mockReturnValue(ok(WEEKLY));
m(Feeds.listFeedItems).mockReturnValue(ok(ITEMS));
const rotated = { ...WEEKLY, url: "https://lens.local/api/v1/feeds/public/lfd_secret2" };
m(Feeds.rotateFeedToken).mockImplementation(() => {
m(Feeds.getFeed).mockReturnValue(ok(rotated));
return ok(rotated);
});
m(Feeds.removeFeedItem).mockReturnValue(ok({ ok: true }));
m(Feeds.publishToFeed).mockReturnValue(ok({ added: [1], already: 0, refused: [] }));
wrap(<FeedPage id={7} />);
expect(await screen.findByRole("heading", { level: 1 })).toHaveTextContent("Weekly");
expect(screen.getByText("Podcast feed")).toBeInTheDocument();
expect(screen.getByText(WEEKLY.url)).toBeInTheDocument();
expect(screen.getByText("No app has read it yet.", { exact: false })).toBeInTheDocument();

fireEvent.click(screen.getByRole("button", { name: "Copy the address" }));
await waitFor(() => expect(writeText).toHaveBeenCalledWith(WEEKLY.url));

fireEvent.click(screen.getByRole("button", { name: "New address" }));
expect(await screen.findByText("https://lens.local/api/v1/feeds/public/lfd_secret2")).toBeInTheDocument();
expect(m(Feeds.rotateFeedToken).mock.calls[0][0].path).toEqual({ fid: 7 });
expect(screen.getByText("New address", { selector: "div" })).toBeInTheDocument();

// the items: an episode made by a routine (a link into Lens) and a text item (an outside link)
expect(screen.getByRole("link", { name: "Capsids and shipments" })).toHaveAttribute("href", "/podcasts/31");
expect(screen.getByText("by a routine")).toBeInTheDocument();
expect(screen.getByRole("link", { name: /Weekly digest/ })).toHaveAttribute("href", "https://example.org/digest/41");

fireEvent.click(screen.getByRole("button", { name: "Remove Capsids and shipments" }));
await waitFor(() => expect(Feeds.removeFeedItem).toHaveBeenCalledTimes(1));
expect(m(Feeds.removeFeedItem).mock.calls[0][0].path).toEqual({ fid: 7, iid: 1 });
fireEvent.click(await screen.findByRole("button", { name: "Undo" }));
await waitFor(() => expect(Feeds.publishToFeed).toHaveBeenCalledTimes(1));
expect(m(Feeds.publishToFeed).mock.calls[0][0]).toMatchObject({ path: { fid: 7 }, body: { recordings: [31] } });
});

test("deleting a feed is undone by making it again with its items, at a new address", async () => {
m(Feeds.getFeed).mockReturnValue(ok(WEEKLY));
m(Feeds.listFeedItems).mockReturnValue(ok(ITEMS));
m(Feeds.deleteFeed).mockReturnValue(ok({ ok: true }));
m(Feeds.createFeed).mockReturnValue(ok({ ...WEEKLY, id: 12, items: 0 }));
m(Feeds.publishToFeed).mockReturnValue(ok({ added: [5, 6], already: 0, refused: [] }));
wrap(<FeedPage id={7} />);
await screen.findByRole("link", { name: "Capsids and shipments" });
fireEvent.click(screen.getByRole("button", { name: "Delete" }));
await waitFor(() => expect(Feeds.deleteFeed).toHaveBeenCalledTimes(1));
expect(await screen.findByText("Deleted “Weekly”")).toBeInTheDocument();
expect(replace).toHaveBeenCalledWith("/feeds");
fireEvent.click(screen.getByRole("button", { name: "Undo" }));
await waitFor(() => expect(Feeds.publishToFeed).toHaveBeenCalledTimes(1));
expect(m(Feeds.createFeed).mock.calls[0][0].body).toMatchObject({
namespace: "home",
kind: "podcast",
title: "Weekly",
author: "Lens",
max_items: 50,
});
expect(m(Feeds.publishToFeed).mock.calls[0][0]).toEqual({
client: expect.anything(),
path: { fid: 12 },
body: {
recordings: [31],
activities: [],
texts: [
{
title: "Weekly digest",
summary: "2 new this week",
link: "https://example.org/digest/41",
guid: "digest-41",
},
],
},
});
await waitFor(() => expect(replace).toHaveBeenCalledWith("/feeds/12"));
});

test("editors change what readers show, and Enter in a field saves", async () => {
m(Feeds.getFeed).mockReturnValue(ok(NEWS));
m(Feeds.listFeedItems).mockReturnValue(ok([]));
m(Feeds.updateFeed).mockReturnValue(ok({ ...NEWS, author: "Ada" }));
wrap(<FeedPage id={8} />);
const author = await screen.findByLabelText(/^Author/);
expect(screen.getByRole("button", { name: "Save" })).toBeDisabled();
fireEvent.change(author, { target: { value: "Ada" } });
expect(screen.getByRole("button", { name: "Save" })).toBeEnabled();
fireEvent.submit(author.closest("form")!);
await waitFor(() => expect(Feeds.updateFeed).toHaveBeenCalledTimes(1));
expect(m(Feeds.updateFeed).mock.calls[0][0]).toMatchObject({
path: { fid: 8 },
body: { author: "Ada", title: "What’s new" },
});
expect(await screen.findByText("Saved")).toBeInTheDocument();
expect(screen.queryByLabelText("Explicit content")).not.toBeInTheDocument();
expect(screen.getByText("Nothing in it yet", { selector: "h2" })).toBeInTheDocument();
});
Loading
Loading