---
title: Add transactions markdown output-format
type: task
status: planned
description: >-
  Add ?format=markdown to GET /api/leagues/:id/transactions following the existing data-views
  export_format + redis_cache convention; split out of the context-docs task.
base_uri: user:task/league/add-transactions-markdown-output-format.md
created_at: '2026-07-17T20:09:38.335Z'
entity_id: 8513392f-ef29-457f-81ec-7ac3ec2d3880
owner_identity_uri: █████████████████████████
priority: Low
public_read: true
tags:
  - user:tag/league-xo-football.md
updated_at: '2026-07-17T20:09:38.335Z'
visibility_analyzed_at: '2026-11-05T23:48:20.641Z'
---

# Implementation Plan: Transactions Markdown Output-Format

## Overview

- Add `?format=markdown` output-format support to the existing `GET /api/leagues/:leagueId/transactions` endpoint so an agent (or the league context doc's "full transaction log" link) can fetch a human-readable, filterable transaction log directly as markdown.
- Split out of `add-league-team-markdown-context-docs.md` per surgical scope — that task ships the four self-contained context docs; the deep, filterable transaction log is a record stream that belongs behind API content negotiation, not a curated doc.
- Impact: the league context doc can link to a markdown transaction log (currently it carries only a recent-~10 inline summary); establishes nothing new architecturally because the convention already exists (see Background).

## Background

- The codebase already has `?export_format=` content negotiation in `api/routes/data-views.mjs` (supports `csv`/`json`/`md`/`html` via a local `convert_to_markdown_table` and a `switch` on the param) and in `api/routes/selection-combinations.mjs`, both caching through the shared `redis_cache` (exported from `libs-server/index.mjs`). This task follows that established pattern rather than introducing a new generic helper.
- `GET /api/leagues/:leagueId/transactions` (`api/routes/leagues/transactions.mjs`) returns `pid`-keyed rows with a numeric `type`, supporting `limit/offset/types/teams/pid/since`.
- Human-readable resolution: `transaction_type_display_names` (`libs-shared/constants/transaction-constants.mjs`); player names via a `player`-table lookup; team names/managers via the `get_team_managers` helper created by the parent task (`libs-server/context-docs/`).

### Assumptions

- The `export_format` convention in `data-views.mjs` is the intended house style for API output-format support (checked: two existing consumers use it).
- The parent task's `get_players` / `get_team_managers` resolvers are available to reuse (dependency: parent task ships them).

## Design

- Follow the in-repo `data-views.mjs` convention: read a `format` query param, `switch` on it (`json` default, `markdown`), and render markdown inline; do not add a new generic `respond-with-format` abstraction until a third consumer justifies it.
- Naming: use the full word `format=markdown` (not `md`), consistent with the `text/markdown` content type; document the `Accept: text/markdown` → `format=markdown` correspondence if header negotiation is added.
- Reuse the parent task's markdown table helper and `get_players`/`get_team_managers` resolvers plus `transaction_type_display_names`.
- Caching: reuse `redis_cache` only if profiling shows the rendered log is a hot path; otherwise render on request (the query is already filterable and bounded by `limit`).

### Knowledge Base Impact

- Update `docs/context-documents.md` (created by the parent task) to note the transaction log is available at `/api/leagues/:id/transactions?format=markdown`. No new entity.

## Plan

### Core Implementation

- [ ] **Add markdown rendering to the transactions route**
  - File: modify `api/routes/leagues/transactions.mjs`; reuse the parent task's `libs-server/context-docs` markdown helper + `get_players` + `get_team_managers`.
  - Purpose: serve the filterable transaction log as markdown.
  - Changes: read `format` query param; on `markdown`, resolve player/team/type display values and render a table via the shared helper, respond `text/markdown`; default path returns JSON unchanged.
  - Verify: `curl -s '/api/leagues/1/transactions?format=markdown&limit=20'` returns a markdown table; the default (no param) returns JSON unchanged; `yarn test:local` for the added case passes.

### Knowledge Base Updates

- [ ] **Document the endpoint**
  - File: modify `docs/context-documents.md`
  - Verify: `npx prettier --check docs/context-documents.md`.