Skip to content

feat: payments as an Excel file, beside the CSV (#298) - #319

Merged
Lexirieru merged 3 commits into
mainfrom
feat/be-payments-xlsx
Nov 13, 2026
Merged

Lexirieru merged 3 commits into
mainfrom
feat/be-payments-xlsx

Conversation

@Lin1er

@Lin1er Lin1er commented Nov 13, 2026

Copy link
Copy Markdown
Contributor

@Lexirieru for review. Fixes the Excel note on #298 (Axel's go-ahead: #298 (comment)).

Why

A comma CSV opens in one column in Excel on a locale whose list separator is ;, like Indonesian (Ancung's test on #298). No single CSV separator fits every locale: with ; the amounts would also need comma decimals, which breaks English-locale Excel, and sep=, adds a junk first row in Google Sheets and LibreOffice. An .xlsx has typed cells, so it opens in columns everywhere. The CSV stays exactly as it is.

What changed

  • BE: GET /v1/minds/{mindId}/payments.xlsx (owner only, like the CSV).
    • It has the same rows and columns as the CSV. The rows are now built once in paymentRows, and the CSV output is unchanged.
    • src/xlsx.ts is a small writer with no new dependency: a stored zip using zlib.crc32.
    • Cells are typed: the date is a UTC date serial with a date format, the amount a number, the NearBlocks link a hyperlink, and everything else inline text (never a formula).
    • The header is bold and frozen, with a filter.
  • FE: an Excel button next to Download CSV in Wallet ▸ Recent activity. It is fetched the same way: with the session cookie, saved as a blob named from Content-Disposition.
  • Docs:
    • the new path in docs/openapi.json, next to payments.csv, so it shows in the Endpoints tab;
    • a row in apps/docs/api.mdx and a note on the Payments CSV page;
    • docs/api-contract.md, apps/be/CLAUDE.md and apps/fe/CLAUDE.md.

Tests (local, ct-dev-env)

  • BE: typecheck OK. bun run test: 157 pass, 0 fail, 1 skipped (an existing skip).
    • The new Excel test unzips the response, checks every entry's CRC, the typed cells, the hyperlink and the escaping of a note like =1+1 <tag> & "q", and that the file is owner only (404 for another owner, 401 without a session).
    • The CSV test passes unchanged.
  • Load: bun run load:shop: xlsx 220 requests, p95 277 ms; csv p95 281 ms; 0 errors. bun run load: 0 errors.
  • FE (fresh bun install): lint OK, typecheck OK, vitest 280/280.
  • Docs: mint@4.2.1184 validate OK, openapi-check docs/openapi.json valid, broken-links --check-anchors none.
  • A generated workbook reads correctly in ExcelJS 4.4.0 and SheetJS 0.18.5: date, number, hyperlink, bold frozen header and filter, and =1+1 stays text.

Not checked

A comma CSV opens in one column in Excel on a comma-decimal locale
(Indonesian Excel splits on ';'), and no single CSV separator fits every
locale: with ';' the amounts would also need comma decimals, which breaks
English-locale Excel. An .xlsx has typed cells, so it opens right
everywhere.

GET /v1/minds/{id}/payments.xlsx returns the same rows as the CSV (now
built once in paymentRows; the CSV output is unchanged). src/xlsx.ts is a
small writer with no new dependency: a stored zip with zlib.crc32, dates as
UTC date serials, amounts as numbers, the explorer link as a hyperlink, text
as inline strings (never formulas), bold frozen header with a filter.

Tests (local, ct-dev-env): typecheck OK; bun run test 157 pass, 0 fail,
1 skipped (the existing skip); the new Excel test unzips the response,
checks every CRC and the typed cells, and that it is owner only; the CSV
test passes unchanged. bun run load:shop: xlsx 220 requests p95 277 ms,
csv p95 281 ms, 0 errors; bun run load: 0 errors. A generated workbook
also read correctly with ExcelJS 4.4.0 and SheetJS 0.18.5 (date, number,
hyperlink, bold frozen header, filter; "=1+1" stays text).
Wallet's Recent activity gets an "Excel" button next to "Download CSV",
fetching GET /v1/minds/{id}/payments.xlsx the same way (with the session
cookie, saved as a blob named from Content-Disposition). Excel on an
Indonesian locale opens it in columns, which it doesn't do with the CSV.

Tests (local, ct-dev-env, fresh bun install): lint OK, typecheck OK,
vitest 280/280.
Adds GET /v1/minds/{mindId}/payments.xlsx to docs/openapi.json next to
payments.csv, so it shows in the Endpoints tab on docs.hellonear.xyz
(Axel's ask on #298), and to the API table and the Payments CSV page.
Only the new path is added to the spec; the rest of the file is byte for
byte the same.

Checks (local): mint@4.2.1184 openapi-check docs/openapi.json "OpenAPI
definition is valid"; mint validate exit 0; mint broken-links
--check-anchors "no broken links found". BE typecheck OK, bun run test
157 pass, 0 fail, 1 skipped (existing).
@Lexirieru
Lexirieru merged commit 9323c25 into main Nov 13, 2026
4 checks passed
@Lexirieru

Copy link
Copy Markdown
Contributor

@Lin1er Merged into main (9323c25) with Axel's approval; it follows the usual deploy after merge. @AncungAulia once it is on the demo, please open the Excel file from Wallet ▸ Recent activity on your Indonesian-locale Excel and report on #298 whether the columns split.

@Lin1er

Lin1er commented Nov 13, 2026

Copy link
Copy Markdown
Contributor Author

Live on the hosted demo: main 9323c25 (automatic deploy after the merge).

  • Before: 90466f1, and the box matched git at that revision. CI: passed: mintlify,build,test,Mintlify Deployment.
  • GET /v1/health → {"ok":true,"engine":true,"revision":"9323c25"}. No rollback.
  • Rollback target: 90466f1 (/opt/hellonear/release-old).

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants