Expose json feed URLs and tighten recovery flow

Author: gildesmarais

app/api/v1/feeds.rb

@@ -1,5 +1,7 @@
 # frozen_string_literal: true
 
+require 'html2rss/url'
+
 require_relative 'contract'
 require_relative 'feeds/create_feed'
 require_relative 'feeds/show_feed'
@@ -33,7 +35,9 @@ def create(request)
             # @param url [String]
             # @return [String, nil]
             def extract_site_title(url)
-              CreateFeed.extract_site_title(url)
+              Html2rss::Url.for_channel(url).channel_titleized
+            rescue StandardError
+              nil
             end
           end
         end

app/api/v1/feeds/create_feed.rb

@@ -2,7 +2,6 @@
 
 require 'time'
 require 'json'
-require 'html2rss/url'
 
 require_relative '../../../auth'
 require_relative '../../../auto_source'
@@ -18,12 +17,11 @@ module Api
       module V1
         module Feeds
           ##
-          # Creates stable feed records from authenticated API requests.
-          #
-          # The implementation intentionally keeps parsing, authorization, and
-          # normalization in a single boundary object so callers can rely on one
-          # predictable contract instead of coordinating multiple services.
+          # Creates stable feed records from authenticated API requests with one predictable boundary contract.
           module CreateFeed
+            FEED_ATTRIBUTE_KEYS =
+              %i[id name url strategy feed_token public_url json_public_url created_at updated_at].freeze
+
             class << self
               # Creates a feed and returns a normalized API success payload.
               #
@@ -41,41 +39,19 @@ def call(request)
                 raise
               end
 
-              # Extracts a best-effort human-readable title from the URL.
-              #
-              # @param url [String] target source URL.
-              # @return [String, nil] inferred title or nil when unavailable.
-              def extract_site_title(url)
-                Html2rss::Url.for_channel(url).channel_titleized
-              rescue StandardError
-                nil
-              end
-
               private
 
-              # Enforces feature availability at the API edge to fail fast.
-              #
-              # @return [void]
               def ensure_auto_source_enabled!
                 raise ForbiddenError, Contract::MESSAGES[:auto_source_disabled] unless AutoSource.enabled?
               end
 
-              # Resolves the authenticated account from the request.
-              #
-              # @param request [Rack::Request]
-              # @return [Hash{Symbol=>Object}] authenticated account attributes.
               def require_account(request)
                 account = Auth.authenticate(request)
                 raise UnauthorizedError, 'Authentication required' unless account
 
                 account
               end
 
-              # Validates and normalizes feed creation parameters.
-              #
-              # @param params [Hash{String=>Object}] merged request parameters.
-              # @param account [Hash{Symbol=>Object}] authenticated account.
-              # @return [Html2rss::Web::BoundaryModels::FeedCreateParams]
               def build_create_params(params, account)
                 url = params['url'].to_s.strip
                 raise BadRequestError, 'URL parameter is required' if url.empty?
@@ -89,10 +65,6 @@ def build_create_params(params, account)
                 )
               end
 
-              # Normalizes a strategy value while preserving a default path.
-              #
-              # @param raw_strategy [String, nil]
-              # @return [String]
               def normalize_strategy(raw_strategy)
                 strategy = raw_strategy.to_s.strip
                 strategy = default_strategy if strategy.empty?
@@ -112,24 +84,13 @@ def default_strategy
                 Html2rss::RequestService.default_strategy_name.to_s
               end
 
-              # Shapes feed attributes into the stable API schema.
-              #
-              # @param feed_data [Html2rss::Web::BoundaryModels::FeedMetadata, Hash{Symbol=>Object}] feed record.
-              # @return [Hash{Symbol=>Object}] response-safe feed attributes.
               def feed_attributes(feed_data)
-                typed_feed = feed_data.is_a?(BoundaryModels::FeedMetadata) ? feed_data : BoundaryModels::FeedMetadata.new(**feed_data)
                 timestamp = Time.now.iso8601
+                typed_feed = feed_metadata(feed_data)
 
-                typed_feed.to_h.merge(
-                  created_at: timestamp,
-                  updated_at: timestamp
-                ).slice(:id, :name, :url, :strategy, :feed_token, :public_url, :created_at, :updated_at)
+                typed_feed_attributes(typed_feed, timestamp).slice(*FEED_ATTRIBUTE_KEYS)
               end
 
-              # Parses params with optional JSON body override.
-              #
-              # @param request [Rack::Request]
-              # @return [Hash{String=>Object}] merged request params.
               def request_params(request)
                 return request.params unless json_request?(request)
 
@@ -145,15 +106,11 @@ def request_params(request)
                 raise BadRequestError, 'Invalid JSON payload'
               end
 
-              # @param request [Rack::Request]
-              # @return [Boolean] whether request body should be parsed as JSON.
               def json_request?(request)
                 content_type = request.env['CONTENT_TYPE'].to_s
                 content_type.include?('application/json')
               end
 
-              # @param request [Rack::Request]
-              # @return [Array<(Html2rss::Web::BoundaryModels::FeedCreateParams, Object)>]
               def build_feed_from_request(request)
                 account = require_account(request)
                 ensure_auto_source_enabled!
@@ -165,8 +122,6 @@ def build_feed_from_request(request)
                 [params, feed_data]
               end
 
-              # @param params [Html2rss::Web::BoundaryModels::FeedCreateParams]
-              # @return [void]
               def emit_create_success(params)
                 Observability.emit(
                   event_name: 'feed.create',
@@ -176,8 +131,6 @@ def emit_create_success(params)
                 )
               end
 
-              # @param error [StandardError]
-              # @return [void]
               def emit_create_failure(error)
                 Observability.emit(
                   event_name: 'feed.create',
@@ -186,6 +139,16 @@ def emit_create_failure(error)
                   level: :warn
                 )
               end
+
+              def feed_metadata(feed_data)
+                return feed_data if feed_data.is_a?(BoundaryModels::FeedMetadata)
+
+                BoundaryModels::FeedMetadata.new(**feed_data)
+              end
+
+              def typed_feed_attributes(typed_feed, timestamp)
+                typed_feed.to_h.merge(created_at: timestamp, updated_at: timestamp)
+              end
             end
           end
         end

app/auto_source.rb

@@ -89,18 +89,29 @@ def generate_feed_id(username, url, token)
         # @param identifiers [Hash{Symbol=>String}]
         # @return [Html2rss::Web::BoundaryModels::FeedMetadata]
         def build_feed_data(name, url, token_data, strategy, identifiers)
-          public_url = "/api/v1/feeds/#{identifiers[:feed_token]}"
-
           BoundaryModels::FeedMetadata.new(
             id: identifiers[:feed_id],
             name: name,
             url: url,
             username: token_data[:username],
             strategy: strategy,
             feed_token: identifiers[:feed_token],
-            public_url: public_url
+            public_url: feed_public_url(identifiers[:feed_token]),
+            json_public_url: feed_json_public_url(identifiers[:feed_token])
           )
         end
+
+        # @param feed_token [String]
+        # @return [String]
+        def feed_public_url(feed_token)
+          "/api/v1/feeds/#{feed_token}"
+        end
+
+        # @param feed_token [String]
+        # @return [String]
+        def feed_json_public_url(feed_token)
+          "#{feed_public_url(feed_token)}.json"
+        end
       end
     end
   end

app/boundary_models.rb

@@ -16,7 +16,7 @@ def to_h
 
       ##
       # Feed metadata contract used between feed services and API responses.
-      FeedMetadata = Data.define(:id, :name, :url, :username, :strategy, :feed_token, :public_url) do
+      FeedMetadata = Data.define(:id, :name, :url, :username, :strategy, :feed_token, :public_url, :json_public_url) do
         # @return [Hash{Symbol=>Object}]
         def to_h
           {
@@ -26,7 +26,8 @@ def to_h
             username: username,
             strategy: strategy,
             feed_token: feed_token,
-            public_url: public_url
+            public_url: public_url,
+            json_public_url: json_public_url
           }
         end
       end

frontend/src/__tests__/App.contract.test.tsx

@@ -26,10 +26,11 @@ describe('App contract', () => {
             url: body.url,
             feed_token: 'generated-token',
             public_url: '/api/v1/feeds/generated-token',
+            json_public_url: '/api/v1/feeds/generated-token.json',
           })
         );
       }),
-      http.get('/api/v1/feeds/generated-token', ({ request }) => {
+      http.get('/api/v1/feeds/generated-token.json', ({ request }) => {
         expect(request.headers.get('accept')).toBe('application/feed+json');
 
         return HttpResponse.json(
@@ -57,6 +58,10 @@ describe('App contract', () => {
       expect(screen.getByLabelText('Feed URL')).toBeInTheDocument();
       expect(screen.getByRole('button', { name: 'Copy feed URL' })).toBeInTheDocument();
       expect(screen.getByRole('link', { name: 'Open feed' })).toBeInTheDocument();
+      expect(screen.getByRole('link', { name: 'JSON Feed' })).toHaveAttribute(
+        'href',
+        'http://localhost:3000/api/v1/feeds/generated-token.json'
+      );
       expect(screen.getByRole('button', { name: 'Create another feed' })).toBeInTheDocument();
       expect(screen.getByText('Feed preview')).toBeInTheDocument();
       expect(screen.getByText('Contract Item')).toBeInTheDocument();

frontend/src/__tests__/App.test.tsx

@@ -33,6 +33,7 @@ describe('App', () => {
   const mockSaveToken = vi.fn();
   const mockClearToken = vi.fn();
   const mockConvertFeed = vi.fn();
+  const mockClearConversionError = vi.fn();
   const mockClearResult = vi.fn();
 
   beforeEach(() => {
@@ -70,6 +71,7 @@ describe('App', () => {
       result: null,
       error: null,
       convertFeed: mockConvertFeed,
+      clearError: mockClearConversionError,
       clearResult: mockClearResult,
     });
 
@@ -131,9 +133,11 @@ describe('App', () => {
         strategy: 'ssrf_filter',
         feed_token: 'example-token',
         public_url: '/api/v1/feeds/example-token',
+        json_public_url: '/api/v1/feeds/example-token.json',
       },
       error: null,
       convertFeed: mockConvertFeed,
+      clearError: mockClearConversionError,
       clearResult: mockClearResult,
     });
 
@@ -198,6 +202,59 @@ describe('App', () => {
     });
   });
 
+  it('reopens the token prompt when a saved token is rejected', async () => {
+    mockUseAccessToken.mockReturnValue({
+      token: 'saved-token',
+      hasToken: true,
+      saveToken: mockSaveToken,
+      clearToken: mockClearToken,
+      isLoading: false,
+      error: null,
+    });
+    mockConvertFeed.mockRejectedValueOnce(new Error('Unauthorized'));
+
+    render(<App />);
+
+    fireEvent.input(screen.getByLabelText('Page URL'), {
+      target: { value: 'https://example.com/articles' },
+    });
+    fireEvent.click(screen.getByRole('button', { name: 'Generate feed URL' }));
+
+    await waitFor(() => {
+      expect(screen.getByText('Add access token')).toBeInTheDocument();
+      expect(
+        screen.getByText('Access token was rejected. Paste a valid token to continue.')
+      ).toBeInTheDocument();
+      expect(mockClearToken).toHaveBeenCalled();
+      expect(mockClearConversionError).toHaveBeenCalled();
+    });
+  });
+
+  it('clears stale conversion error when backing out of token recovery', async () => {
+    mockUseAccessToken.mockReturnValue({
+      token: 'saved-token',
+      hasToken: true,
+      saveToken: mockSaveToken,
+      clearToken: mockClearToken,
+      isLoading: false,
+      error: null,
+    });
+    mockConvertFeed.mockRejectedValueOnce(new Error('Unauthorized'));
+
+    render(<App />);
+
+    fireEvent.input(screen.getByLabelText('Page URL'), {
+      target: { value: 'https://example.com/articles' },
+    });
+    fireEvent.click(screen.getByRole('button', { name: 'Generate feed URL' }));
+
+    await screen.findByText('Access token was rejected. Paste a valid token to continue.');
+    fireEvent.click(screen.getByRole('button', { name: 'Back' }));
+
+    expect(screen.queryByText('Feed generation failed')).not.toBeInTheDocument();
+    expect(screen.queryByText('Unauthorized')).not.toBeInTheDocument();
+  });
+
   it('submits the token prompt with Enter', async () => {
     render(<App />);
 

frontend/src/__tests__/ResultDisplay.test.tsx

@@ -12,6 +12,7 @@ describe('ResultDisplay', () => {
     strategy: 'ssrf_filter',
     feed_token: 'test-feed-token',
     public_url: 'https://example.com/feed.xml',
+    json_public_url: 'https://example.com/feed.json',
   };
 
   beforeEach(() => {
@@ -34,16 +35,33 @@ describe('ResultDisplay', () => {
     expect(screen.getByText('Test Feed')).toBeInTheDocument();
     expect(screen.getByRole('button', { name: 'Copy feed URL' })).toBeInTheDocument();
     expect(screen.getByRole('link', { name: 'Open feed' })).toBeInTheDocument();
+    expect(screen.getByRole('link', { name: 'JSON Feed' })).toHaveAttribute(
+      'href',
+      'https://example.com/feed.json'
+    );
     await waitFor(() => {
       expect(screen.getByText('Item One')).toBeInTheDocument();
       expect(screen.getByText(/points by canpan/i)).toBeInTheDocument();
       expect(screen.getByText('Item Two')).toBeInTheDocument();
     });
-    expect(window.fetch).toHaveBeenCalledWith('https://example.com/feed.xml', {
+    expect(window.fetch).toHaveBeenCalledWith('https://example.com/feed.json', {
       headers: { Accept: 'application/feed+json' },
     });
   });
 
+  it('surfaces preview fetch failures as a result-state message', async () => {
+    vi.mocked(window.fetch).mockResolvedValueOnce({
+      ok: false,
+      json: async () => ({}),
+    } as Response);
+
+    render(<ResultDisplay result={mockResult} onCreateAnother={mockOnCreateAnother} />);
+
+    await waitFor(() => {
+      expect(screen.getByText('Preview unavailable right now.')).toBeInTheDocument();
+    });
+  });
+
   it('calls onCreateAnother when the reset button is clicked', () => {
     render(<ResultDisplay result={mockResult} onCreateAnother={mockOnCreateAnother} />);
 

frontend/src/__tests__/mocks/server.ts

@@ -49,6 +49,7 @@ export interface FeedResponseOverrides {
   strategy?: string;
   feed_token?: string;
   public_url?: string;
+  json_public_url?: string;
   created_at?: string;
   updated_at?: string;
 }
@@ -66,6 +67,7 @@ export function buildFeedResponse(overrides: FeedResponseOverrides = {}) {
         strategy: overrides.strategy ?? 'ssrf_filter',
         feed_token: overrides.feed_token ?? 'example-token',
         public_url: overrides.public_url ?? '/api/v1/feeds/example-token',
+        json_public_url: overrides.json_public_url ?? '/api/v1/feeds/example-token.json',
         created_at: timestamp,
         updated_at: overrides.updated_at ?? timestamp,
       },