refactor(frontend): consume structured metadata and remove flow heuristics

Author: gildesmarais

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

@@ -1,7 +1,7 @@
-import { describe, it, expect } from 'vitest';
+import { describe, it, expect, beforeEach } from 'vitest';
 import { render, screen, fireEvent, waitFor } from '@testing-library/preact';
 import { http, HttpResponse } from 'msw';
-import { server, buildFeedResponse } from './mocks/server';
+import { server, buildFeedResponse, buildStructuredErrorResponse } from './mocks/server';
 import { App } from '../components/App';
 
 describe('App contract', () => {
@@ -11,20 +11,15 @@ describe('App contract', () => {
     globalThis.history.replaceState({}, '', 'http://localhost:3000/create');
     globalThis.localStorage.clear();
     globalThis.sessionStorage.clear();
-  });
-
-  const authenticate = () => {
     globalThis.sessionStorage.setItem('html2rss_access_token', token);
-  };
-
-  it('shows feed result when API responds with success', async () => {
-    authenticate();
+  });
 
+  it('shows feed result when the API returns structured create and status payloads', async () => {
     server.use(
       http.post('/api/v1/feeds', async ({ request }) => {
-        const body = (await request.json()) as { url: string; strategy: string };
+        const body = (await request.json()) as { url: string };
 
-        expect(body).toEqual({ url: 'https://example.com/articles', strategy: 'faraday' });
+        expect(body).toEqual({ url: 'https://example.com/articles' });
         expect(request.headers.get('authorization')).toBe(`Bearer ${token}`);
 
         return HttpResponse.json(
@@ -33,9 +28,29 @@ describe('App contract', () => {
             feed_token: 'generated-token',
             public_url: '/api/v1/feeds/generated-token',
             json_public_url: '/api/v1/feeds/generated-token.json',
-          })
+            conversion: {
+              readiness_phase: 'link_created',
+              preview_status: 'pending',
+              warnings: [],
+            },
+          }),
+          { status: 201 }
         );
       }),
+      http.get('/api/v1/feeds/generated-token/status', () =>
+        HttpResponse.json(
+          buildFeedResponse({
+            feed_token: 'generated-token',
+            public_url: '/api/v1/feeds/generated-token',
+            json_public_url: '/api/v1/feeds/generated-token.json',
+            conversion: {
+              readiness_phase: 'feed_ready',
+              preview_status: 'ready',
+              warnings: [],
+            },
+          })
+        )
+      ),
       http.get('/api/v1/feeds/generated-token.json', ({ request }) => {
         expect(request.headers.get('accept')).toBe('application/feed+json');
 
@@ -60,101 +75,47 @@ describe('App contract', () => {
     render(<App />);
 
     await waitFor(() => {
-      expect(screen.getByRole('button', { name: 'Generate feed URL' })).toBeEnabled();
+      expect(screen.getByLabelText('Page URL')).toBeInTheDocument();
     });
     expect(screen.queryByRole('combobox')).not.toBeInTheDocument();
 
     const urlInput = screen.getByLabelText('Page URL') as HTMLInputElement;
     fireEvent.input(urlInput, { target: { value: 'https://example.com/articles' } });
-
     fireEvent.click(screen.getByRole('button', { name: 'Generate feed URL' }));
 
-    await waitFor(
-      () => {
-        expect(screen.getByText('Feed created')).toBeInTheDocument();
-        expect(screen.getByText('Example Feed')).toBeInTheDocument();
-        expect(document.querySelector('.result-shell')).toHaveAttribute('data-state', 'warming');
-        expect(screen.getByLabelText('Feed URL')).toBeInTheDocument();
-        expect(screen.getByRole('button', { name: 'Copy feed URL' })).toBeInTheDocument();
-        expect(screen.getByRole('button', { name: 'Create another feed' })).toBeInTheDocument();
-        expect(screen.getByText('Preview')).toBeInTheDocument();
-        expect(screen.getByText('Latest items from this feed')).toBeInTheDocument();
-      },
-      { timeout: 3000 }
-    );
-  });
-
-  it('loads instance metadata from /api/v1 without trailing slash', async () => {
-    let slashlessMetadataRequests = 0;
-    let trailingSlashMetadataRequests = 0;
-
-    server.use(
-      http.get('/api/v1', () => {
-        slashlessMetadataRequests += 1;
-
-        return HttpResponse.json({
-          success: true,
-          data: {
-            api: {
-              name: 'html2rss-web API',
-              description: 'RESTful API for converting websites to RSS feeds',
-              openapi_url: 'http://example.test/openapi.yaml',
-            },
-            instance: {
-              feed_creation: {
-                enabled: true,
-                access_token_required: true,
-              },
-              featured_feeds: [],
-            },
-          },
-        });
-      }),
-      http.get('/api/v1/', () => {
-        trailingSlashMetadataRequests += 1;
-
-        return HttpResponse.text('', { status: 404 });
-      })
-    );
-
-    render(<App />);
-
-    await screen.findByLabelText('Page URL');
-
-    expect(screen.getByRole('button', { name: 'Generate feed URL' })).toBeInTheDocument();
-    expect(screen.queryByText('Instance metadata unavailable')).not.toBeInTheDocument();
-    expect(slashlessMetadataRequests).toBeGreaterThanOrEqual(1);
-    expect(trailingSlashMetadataRequests).toBe(0);
-  });
-
-  it('shows the metadata unavailable notice when /api/v1 responds with non-JSON content', async () => {
-    server.use(
-      http.get('/api/v1', () => HttpResponse.text('not-json', { status: 502 })),
-      http.get('/api/v1/', () => HttpResponse.text('', { status: 404 }))
-    );
-
-    render(<App />);
-
-    await screen.findByText('Instance metadata unavailable');
-
-    expect(screen.getByText('Invalid response format from API metadata')).toBeInTheDocument();
+    await waitFor(() => {
+      expect(screen.getByText('Feed ready')).toBeInTheDocument();
+      expect(screen.getByText('Example Feed')).toBeInTheDocument();
+      expect(document.querySelector('.result-shell')).toHaveAttribute('data-state', 'ready');
+      expect(screen.getByLabelText('Feed URL')).toBeInTheDocument();
+      expect(screen.getByRole('button', { name: 'Copy feed URL' })).toBeInTheDocument();
+      expect(screen.getByRole('button', { name: 'Create another feed' })).toBeInTheDocument();
+      expect(screen.getByText('Latest items from this feed')).toBeInTheDocument();
+    });
   });
 
-  it('reopens token recovery when a saved token is rejected by /api/v1/feeds', async () => {
-    authenticate();
-
+  it('reopens token recovery when a saved token is rejected by structured auth metadata', async () => {
     server.use(
       http.post('/api/v1/feeds', async () =>
-        HttpResponse.json({ success: false, error: { message: 'Unauthorized' } }, { status: 401 })
+        HttpResponse.json(
+          buildStructuredErrorResponse({
+            code: 'UNAUTHORIZED',
+            message: 'Authentication required',
+            kind: 'auth',
+            retryable: false,
+            next_action: 'enter_token',
+            retry_action: 'none',
+          }),
+          { status: 401 }
+        )
       )
     );
 
     render(<App />);
 
     await waitFor(() => {
-      expect(screen.getByRole('button', { name: 'Generate feed URL' })).toBeEnabled();
+      expect(screen.getByLabelText('Page URL')).toBeInTheDocument();
     });
-    expect(screen.queryByRole('combobox')).not.toBeInTheDocument();
 
     fireEvent.input(screen.getByLabelText('Page URL'), {
       target: { value: 'https://example.com/articles' },