feat(api): contract types and adapters for trips and trip photos - #38

Part of #20

contract.ts mirrors the backend OpenAPI draft 0.0.5. The mock now answers trips and trip photos in contract shapes, so the mock and the real backend go through the same adapters and the screens see one format. Adds photo, upload-item and batch adapters with tests, image expiry fields, and a nullable uploaded_at.

Suggested new body:

Summary

Introduce a shared API contract and adapter layer for incremental integration between the React frontend and Go backend.

Screens access data through src/api/client.ts, which selects live or mock implementations per endpoint. Backend responses are converted into frontend view models through dedicated adapters, keeping API-specific structures out of UI components.

Changes

API contracts and adapters

Separate backend API representations from frontend view models:

• src/api/contract.ts — Defines TypeScript interfaces based on the backend's OpenAPI specification (draft 0.0.5), covering trips, photos, pagination, upload registration, signed upload targets, processing batches, and API errors. Fields anticipated by the frontend design but not yet defined in OpenAPI are marked optional.
• src/api/types.ts — Defines frontend-facing models consumed by React components, independently of the backend's wire format.
• src/api/adapters.ts — Converts API responses into frontend models, normalizing field differences and supplying neutral defaults where backend data is not yet available.
• src/api/http.ts — Centralizes HTTP requests, Firebase ID token handling and refresh, and structured API errors.
• src/api/client.ts — Provides the data-access interface used by screens, selecting live or mock implementations independently for each endpoint.

This separation allows backend endpoints to be integrated incrementally without coupling UI components to the API's representation.

The contract definitions also prepare for future photo and upload integration. In particular, they distinguish original EXIF coordinates from effective locations after user correction, represent accepted and rejected upload files, and establish cursor-based pagination structures.

These are TypeScript declarations rather than runtime validation schemas. Defining a contract does not imply that its corresponding endpoint is already implemented.

Live trip integration

Connect three operations to the Go backend when VITE_API_URL is configured:

The frontend attaches Firebase ID tokens to authenticated requests and converts backend responses into its existing trip models.

These operations have been verified against backend feat/trip-persistence, which provides PostgreSQL-backed, owner-scoped trip records when database-backed user resolution is enabled.

Mock/live data boundaries

Prevent unrelated demonstration data from appearing alongside persistent trip records:

• Real trips return an empty photo collection until the backend photo-listing endpoint is available.
• getSummary() returns null when trip operations are live but GET /api/me/summary is unavailable, rather than falling back to mock statistics and photos.
• The Dashboard handles unavailable summaries explicitly while continuing to display persistent trip cards.
• Standalone mock mode retains its existing demonstration data.

Map data, uploads, place search, location correction, and other unintegrated operations remain mock-backed.

Testing

Introduce separate Playwright suites for live API integration and mock/live boundary regression, alongside the existing frontend acceptance tests.

Live API integration — npm run test:integration

• Verify trip creation, retrieval, listing, and response adaptation.
• Check authentication, input validation, and expected HTTP error responses.
• Verify bidirectional trip ownership isolation between two Firebase accounts, including distinct application-user identities.

Mock/live boundary regression — npm run test:boundaries

• Verify that standalone mock mode retains demonstration statistics and recent photos.
• Verify that live trip mode does not fall back to mock summary data or request the unimplemented summary endpoint.
• Use separate Vite instances for the two configurations without requiring a running backend.

The existing mock-based acceptance tests remain independent of the live integration suite.

Verification completed:

• All automated test suites, type checks, linting, and production build passed.
• Trip records persisted after restarting the Go backend.
• Two distinct Firebase accounts could not list or retrieve each other's trips, including through direct URLs.
• Persistent trips rendered correctly in the frontend.

Documentation

Update the README to clarify the current backend integration status, API boundaries, Firebase identity resolution, test configurations, and known limitations.

Remaining work

• Integrate trip photo listing, uploads, processing, and Dashboard summaries.
• Replace mock map data, place search, and location correction with backend services.
• Implement photo sharing and access control.
• Support cursor-based pagination when available on the backend.

These are follow-up integrations and remain outside the scope of this PR.