# App API Contract Notes

This is a handoff snapshot, not the product SSOT.

Product SSOT: mall-docs report-notebooklm docs, snapshot date: 2026-06-03.

For full API/data details, read `../report-notebooklm-api/docs/API_AND_DATA.md` from the monorepo root.

## Configuration

The App reads the API base URL from:

```text
RNB_API_BASE
```

If `RNB_API_BASE` is missing, live API requests throw an error. This is intentional to avoid silently pointing production builds at a debug backend.

## Endpoints Currently Consumed

| Method | Path | App use |
|---|---|---|
| `GET` | `/feed/recommended` | Recommended feed cards. |
| `GET` | `/reports` | Report list. |
| `GET` | `/reports/{report_id}` | Report detail skeleton and modules. |
| `GET` | `/reports/{report_id}/modules/{module_id}` | Module detail page content. |
| `GET` | `/institutions` | Institution list. |
| `GET` | `/institutions/{institution_id}` | Institution detail and recent reports. |
| `GET` | `/listen` | Listen list and mini-player entry. |

## Response Fields Currently Used

Report cards:

- `report_id`
- `title_cn`
- `subtitle_cn`
- `one_liner`
- `institution`
- `topics`
- `released_at`
- `has_audio`
- `interpretation_label`
- `source_tier`
- `cache_version`

Report detail:

- `report_id`
- `title_cn`
- `subtitle_cn`
- `original_title`
- `one_liner`
- `institution`
- `source`
- `topics`
- `has_audio`
- `interpretation_label`
- `risk_disclaimer`
- `released_at`
- `cache_version`
- `modules`

Display modules:

- `module_id`
- `type`
- `layer`
- `render_mode`
- `has_detail_page`
- `is_publish_blocking`
- `requires_human_review`
- `sort_order`
- `title_cn`
- `content`
- `preview`
- `content_ref`
- `content_etag`

Listen items:

- `audio_id`
- `title_cn`
- `duration_sec`
- `report_id`
- `report_title_cn`
- `institution`
- `released_at`
- `cache_version`

Institution:

- `institution_id`
- `name_cn`
- `name_en`
- `institution_type`
- `source_tier`
- `website_url`
- `covered_topics`
- `report_count`
- `latest_report_at`
- `credibility_note`
- `intro_cn`
- `latest_report`
- `recent_reports`

## Module Rendering Behavior

- `render_mode=inline`: App renders `content` on the report detail page.
- `render_mode=card_plus_page`: App renders `preview` on the report detail page and opens module detail for full content.
- Unknown module `type` should not crash the App; it should fall back to a generic or hidden renderer.

Current renderer coverage includes:

- `basic_info`
- `executive_overview`
- `core_insights`
- `key_data`
- `source_compliance`
- `audio`
- `institution`
- `timeline`
- `study_guide`
- `structure_graph`
- `related_sources`
- `differentiated_view`
- `weaknesses`

## Endpoints Not Yet Consumed

- `GET /audio/{audio_id}/stream`
- Auth endpoints.
- `/me` personal-state endpoints.
- `POST /outbound/events`

The UI currently uses placeholders for these blocked flows:

- Login prompt.
- Favorite action.
- Browse/history sync.
- Saved listen.
- Playback progress.
- Outbound confirmation.
- Real audio playback.

## Public Field Boundary

The App must not rely on or display:

- `display_version`
- module `version`
- raw artifact payload
- raw NotebookLM IDs
- private object-storage references
- local paths
- auth internals

The App should use `cache_version` as the public cache/version signal.