gloomberb 0.20.2 → 0.20.3

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (362) hide show
  1. package/README.md +1 -1
  2. package/README.zh-CN.md +1 -1
  3. package/package.json +2 -1
  4. package/src/account/auth-form.tsx +13 -8
  5. package/src/account/upgrade-dialog.tsx +1 -1
  6. package/src/api-client/central-bank-rates.ts +5 -0
  7. package/src/api-client/data.ts +17 -4
  8. package/src/api-client/debt-maturities.ts +45 -2
  9. package/src/api-client/earnings.ts +4 -2
  10. package/src/api-client/errors.ts +21 -11
  11. package/src/api-client/index.ts +1 -0
  12. package/src/api-client/paths.ts +9 -1
  13. package/src/api-client/social-mentions.ts +47 -0
  14. package/src/api-client/types/econ.ts +4 -0
  15. package/src/app.tsx +11 -1
  16. package/src/cli/command-options.ts +2 -1
  17. package/src/cli/commands/market.ts +111 -29
  18. package/src/cli/commands/options-chain.ts +23 -6
  19. package/src/cli/commands/overview.ts +13 -5
  20. package/src/cli/commands/plugins.ts +49 -18
  21. package/src/cli/commands/search.ts +25 -6
  22. package/src/cli/commands/ticker.ts +4 -2
  23. package/src/cli/fx-quote-rate.ts +49 -1
  24. package/src/cli/glossary.ts +95 -15
  25. package/src/cli/history-rows.ts +9 -25
  26. package/src/cli/index.ts +6 -38
  27. package/src/cli/known-gaps.ts +3 -3
  28. package/src/cli/listing-arg.ts +78 -18
  29. package/src/cli/name-entries.ts +3 -2
  30. package/src/cli/not-a-ticker.ts +6 -2
  31. package/src/cli/pane-functions/capabilities.ts +12 -1
  32. package/src/cli/pane-functions/function-help.ts +23 -11
  33. package/src/cli/pane-functions/headless.ts +3 -1
  34. package/src/cli/pane-functions/index.ts +32 -4
  35. package/src/cli/pane-functions/market-session.ts +8 -3
  36. package/src/cli/pane-functions/resolver.ts +18 -11
  37. package/src/cli/pane-functions/screenshot-payload.ts +36 -6
  38. package/src/cli/pane-functions/screenshot-render.ts +4 -0
  39. package/src/cli/quote-answer.ts +10 -0
  40. package/src/cli/report-tables.ts +22 -2
  41. package/src/cli/result.ts +7 -3
  42. package/src/cli/spreadsheet-hint.ts +43 -0
  43. package/src/cli/symbol-list.ts +58 -4
  44. package/src/cli/symbol-rows.ts +49 -2
  45. package/src/cli/ticker-resolution.ts +98 -5
  46. package/src/cli/unknown-command.ts +88 -0
  47. package/src/components/command-bar/assist/model.ts +6 -1
  48. package/src/components/command-bar/commands/direct/index.ts +9 -1
  49. package/src/components/command-bar/commands/registry.ts +18 -0
  50. package/src/components/command-bar/pane-actions.ts +30 -13
  51. package/src/components/command-bar/panel/index.tsx +6 -3
  52. package/src/components/command-bar/panel/prompt-binding.ts +4 -0
  53. package/src/components/command-bar/panel/types.ts +3 -0
  54. package/src/components/command-bar/routes/header-market.ts +108 -0
  55. package/src/components/command-bar/routes/root/command-items.ts +5 -0
  56. package/src/components/command-bar/routes/root/provider-search.ts +190 -32
  57. package/src/components/command-bar/routes/root/results.ts +3 -0
  58. package/src/components/command-bar/routes/root/runtime.ts +28 -5
  59. package/src/components/command-bar/routes/ticker-search/results.ts +53 -6
  60. package/src/components/command-bar/routing/list-state.ts +38 -0
  61. package/src/components/command-bar/selection-hint.ts +28 -0
  62. package/src/components/command-bar/surface/index.tsx +41 -3
  63. package/src/components/command-bar/view-model.ts +15 -0
  64. package/src/components/command-bar/workflow/tickers.ts +3 -2
  65. package/src/components/company-logo.tsx +20 -2
  66. package/src/components/data-table/export.ts +13 -8
  67. package/src/components/feedback-dialog.tsx +2 -1
  68. package/src/components/form-modal/field-row.tsx +2 -1
  69. package/src/components/input-search-bar.tsx +2 -2
  70. package/src/components/layout/double-escape-close.ts +8 -5
  71. package/src/components/layout/header.tsx +75 -44
  72. package/src/components/layout/market-summary.ts +322 -116
  73. package/src/components/layout/pane/footer/index.tsx +26 -8
  74. package/src/components/layout/pane/footer/model.ts +46 -20
  75. package/src/components/layout/pane/header.tsx +3 -2
  76. package/src/components/layout/shell/chrome.ts +15 -15
  77. package/src/components/layout/status-bar.tsx +8 -7
  78. package/src/components/layout/status-widget-space.ts +8 -0
  79. package/src/components/markdown-editor.tsx +2 -2
  80. package/src/components/onboarding/account-step/form-panel.tsx +0 -3
  81. package/src/components/onboarding/onboarding-keyboard.ts +15 -6
  82. package/src/components/onboarding/onboarding-wizard.tsx +61 -11
  83. package/src/components/onboarding/portfolio-step/broker-fields-panel.tsx +0 -1
  84. package/src/components/onboarding/portfolio-step/positions-panel.tsx +0 -2
  85. package/src/components/price-sparkline/model.ts +26 -10
  86. package/src/components/ticker/list-table-view.tsx +29 -4
  87. package/src/components/ui/button.tsx +13 -2
  88. package/src/components/ui/column-grid.tsx +18 -9
  89. package/src/components/ui/data-table/index.tsx +1 -1
  90. package/src/components/ui/data-table/opentui/index.tsx +2 -1
  91. package/src/components/ui/data-table/types.ts +18 -0
  92. package/src/components/ui/delayed-mark.tsx +3 -2
  93. package/src/components/ui/field-grid.tsx +0 -2
  94. package/src/components/ui/fields.tsx +7 -4
  95. package/src/components/ui/inline-quick-add.tsx +2 -2
  96. package/src/components/ui/key-hint-words.ts +153 -0
  97. package/src/components/ui/key-hints.tsx +73 -0
  98. package/src/components/ui/menu.tsx +3 -1
  99. package/src/components/ui/message-composer.tsx +2 -2
  100. package/src/components/ui/shortcut-hint.tsx +28 -3
  101. package/src/components/ui/tabs.tsx +7 -0
  102. package/src/components/ui/text-prompt-dialog.tsx +2 -1
  103. package/src/core/state/app/command-bar-launch.ts +3 -0
  104. package/src/data/config/store/normalize.ts +6 -0
  105. package/src/docs/snapshot.json +120 -69
  106. package/src/i18n/es.ts +24 -1
  107. package/src/i18n/ja.ts +24 -1
  108. package/src/i18n/ko.ts +24 -1
  109. package/src/i18n/zh-cn.ts +24 -1
  110. package/src/i18n/zh-tw.ts +24 -1
  111. package/src/layout/pane-manager/gridlock.ts +11 -0
  112. package/src/market-data/bars-per-year.ts +27 -9
  113. package/src/market-data/coordinator/quotes.ts +22 -3
  114. package/src/market-data/futures-board.ts +80 -0
  115. package/src/market-data/futures-contract.ts +9 -3
  116. package/src/market-data/market/change-basis.ts +2 -2
  117. package/src/market-data/market/dated-previous-close.ts +163 -47
  118. package/src/market-data/market/format.ts +14 -3
  119. package/src/market-data/market/freshness.ts +24 -7
  120. package/src/market-data/market/header-market.ts +154 -0
  121. package/src/market-data/market/index-level.ts +29 -0
  122. package/src/market-data/market/index-session-venues.ts +44 -0
  123. package/src/market-data/market/status.ts +7 -2
  124. package/src/market-data/market/venue-session.ts +72 -0
  125. package/src/market-data/model-dividend-yield.ts +23 -8
  126. package/src/market-data/options-alternatives.ts +39 -4
  127. package/src/market-data/published-apac-sessions.ts +40 -2
  128. package/src/market-data/quotes/export-identity.ts +76 -0
  129. package/src/market-data/quotes/freshness.ts +22 -0
  130. package/src/market-data/quotes/time.ts +42 -1
  131. package/src/market-data/realized-volatility.ts +11 -7
  132. package/src/market-data/tax-equivalent.ts +145 -27
  133. package/src/plugins/builtin/account-management/pane.tsx +2 -2
  134. package/src/plugins/builtin/alerts/alert-engine.ts +12 -6
  135. package/src/plugins/builtin/alerts/alert-log.ts +6 -2
  136. package/src/plugins/builtin/alerts/calendar-events.ts +74 -12
  137. package/src/plugins/builtin/alerts/cli-forms.ts +11 -1
  138. package/src/plugins/builtin/alerts/cli-move.ts +234 -0
  139. package/src/plugins/builtin/alerts/cli.ts +224 -33
  140. package/src/plugins/builtin/alerts/command.ts +33 -6
  141. package/src/plugins/builtin/alerts/event-rows.ts +18 -4
  142. package/src/plugins/builtin/alerts/events-pane.tsx +6 -2
  143. package/src/plugins/builtin/alerts/events.ts +9 -0
  144. package/src/plugins/builtin/alerts/format.ts +40 -15
  145. package/src/plugins/builtin/alerts/headless.ts +31 -18
  146. package/src/plugins/builtin/alerts/history.ts +1 -0
  147. package/src/plugins/builtin/alerts/index.tsx +86 -12
  148. package/src/plugins/builtin/alerts/live.ts +2 -1
  149. package/src/plugins/builtin/alerts/move-checks.ts +155 -0
  150. package/src/plugins/builtin/alerts/move.ts +160 -0
  151. package/src/plugins/builtin/alerts/pane.tsx +52 -22
  152. package/src/plugins/builtin/alerts/price-text.ts +62 -0
  153. package/src/plugins/builtin/alerts/price.ts +17 -0
  154. package/src/plugins/builtin/alerts/quotes.ts +84 -3
  155. package/src/plugins/builtin/alerts/scheduled-check.ts +7 -1
  156. package/src/plugins/builtin/alerts/storage.ts +20 -7
  157. package/src/plugins/builtin/alerts/types.ts +13 -0
  158. package/src/plugins/builtin/analytics/risk-client.ts +60 -39
  159. package/src/plugins/builtin/analytics/risk-episodes.ts +18 -0
  160. package/src/plugins/builtin/analytics/risk-headless.ts +20 -4
  161. package/src/plugins/builtin/analytics/risk-model.ts +68 -1
  162. package/src/plugins/builtin/analytics/risk-pane.tsx +15 -3
  163. package/src/plugins/builtin/backtest/engine.ts +4 -2
  164. package/src/plugins/builtin/backtest/window.ts +3 -1
  165. package/src/plugins/builtin/broker-manager/sign-in-end.ts +1 -1
  166. package/src/plugins/builtin/central-bank-rates/client.ts +4 -0
  167. package/src/plugins/builtin/central-bank-rates/headless.ts +1 -1
  168. package/src/plugins/builtin/central-bank-rates/model.ts +18 -8
  169. package/src/plugins/builtin/central-bank-rates/pane.tsx +6 -3
  170. package/src/plugins/builtin/chart-composer/cli-options.ts +5 -0
  171. package/src/plugins/builtin/chart-composer/headless-schema.ts +17 -1
  172. package/src/plugins/builtin/chart-composer/headless.ts +2 -0
  173. package/src/plugins/builtin/cloud/upgrade-status-widget.tsx +9 -2
  174. package/src/plugins/builtin/crypto-board/headless.ts +82 -17
  175. package/src/plugins/builtin/crypto-board/index.tsx +24 -2
  176. package/src/plugins/builtin/crypto-board/model.ts +5 -2
  177. package/src/plugins/builtin/crypto-board/pane.tsx +4 -1
  178. package/src/plugins/builtin/debt-maturities/client.ts +111 -6
  179. package/src/plugins/builtin/debt-maturities/headless.ts +84 -1
  180. package/src/plugins/builtin/debt-maturities/model.ts +97 -14
  181. package/src/plugins/builtin/debt-maturities/pane.tsx +165 -15
  182. package/src/plugins/builtin/debt-maturities/series.ts +3 -1
  183. package/src/plugins/builtin/dividend-yield/client.ts +22 -6
  184. package/src/plugins/builtin/dividend-yield/headless.ts +113 -46
  185. package/src/plugins/builtin/dividend-yield/model.ts +5 -2
  186. package/src/plugins/builtin/dividend-yield/pane.tsx +6 -3
  187. package/src/plugins/builtin/dividend-yield/ranking-reads.ts +11 -4
  188. package/src/plugins/builtin/dividend-yield/ranking.ts +113 -18
  189. package/src/plugins/builtin/dividend-yield/types.ts +2 -0
  190. package/src/plugins/builtin/dividend-yield/view.ts +3 -0
  191. package/src/plugins/builtin/econ/calendar-model.ts +21 -3
  192. package/src/plugins/builtin/econ/detail-view.tsx +5 -3
  193. package/src/plugins/builtin/econ/figures.ts +13 -0
  194. package/src/plugins/builtin/econ/fred-catalog.ts +6 -3
  195. package/src/plugins/builtin/econ/index.tsx +5 -3
  196. package/src/plugins/builtin/econ/types.ts +5 -0
  197. package/src/plugins/builtin/equity-screener/footer.ts +45 -0
  198. package/src/plugins/builtin/equity-screener/pane.tsx +4 -18
  199. package/src/plugins/builtin/equity-screener/ticker-check.tsx +2 -1
  200. package/src/plugins/builtin/fixed-income/model.ts +1 -0
  201. package/src/plugins/builtin/futures/table.tsx +1 -1
  202. package/src/plugins/builtin/futures-curve/model.ts +3 -10
  203. package/src/plugins/builtin/help/function-card.tsx +2 -1
  204. package/src/plugins/builtin/help/function-index.ts +1 -0
  205. package/src/plugins/builtin/insider/client.ts +31 -14
  206. package/src/plugins/builtin/insider/signals-model.ts +2 -7
  207. package/src/plugins/builtin/iv-history/headless.ts +1 -2
  208. package/src/plugins/builtin/iv-history/model.ts +33 -23
  209. package/src/plugins/builtin/iv-history/screen-pane.tsx +0 -3
  210. package/src/plugins/builtin/kelly-sizer/headless.ts +64 -16
  211. package/src/plugins/builtin/kelly-sizer/history.ts +37 -28
  212. package/src/plugins/builtin/kelly-sizer/pane.tsx +43 -10
  213. package/src/plugins/builtin/kelly-sizer/sections.tsx +7 -2
  214. package/src/plugins/builtin/kelly-sizer/units.ts +29 -0
  215. package/src/plugins/builtin/news/index.tsx +7 -13
  216. package/src/plugins/builtin/news/overview-headlines.tsx +117 -0
  217. package/src/plugins/builtin/news/ticker-news.ts +35 -0
  218. package/src/plugins/builtin/news/wire/news/detail-view.tsx +8 -6
  219. package/src/plugins/builtin/news/wire/news/row.ts +49 -0
  220. package/src/plugins/builtin/news/wire/news/table.tsx +9 -20
  221. package/src/plugins/builtin/options/analytics.ts +7 -2
  222. package/src/plugins/builtin/options/live-quotes.ts +6 -1
  223. package/src/plugins/builtin/options/table.ts +3 -2
  224. package/src/plugins/builtin/options/view.tsx +11 -9
  225. package/src/plugins/builtin/options-scenario/client.ts +3 -0
  226. package/src/plugins/builtin/options-scenario/headless.ts +1 -1
  227. package/src/plugins/builtin/perps/client.ts +5 -4
  228. package/src/plugins/builtin/perps/headless.ts +134 -124
  229. package/src/plugins/builtin/perps/markets-section.tsx +2 -2
  230. package/src/plugins/builtin/perps/model.ts +8 -4
  231. package/src/plugins/builtin/perps/open-market.ts +4 -4
  232. package/src/plugins/builtin/perps/venue-markets.ts +3 -6
  233. package/src/plugins/builtin/portfolio-list/cell-version.ts +1 -0
  234. package/src/plugins/builtin/portfolio-list/cli/bulk-symbols.ts +34 -10
  235. package/src/plugins/builtin/portfolio-list/cli/period-report.ts +28 -2
  236. package/src/plugins/builtin/portfolio-list/cli/portfolio-command.ts +7 -3
  237. package/src/plugins/builtin/portfolio-list/cli/render.ts +66 -22
  238. package/src/plugins/builtin/portfolio-list/grid.tsx +5 -3
  239. package/src/plugins/builtin/portfolio-list/pane/data.ts +34 -1
  240. package/src/plugins/builtin/portfolio-list/pane/index.tsx +6 -0
  241. package/src/plugins/builtin/portfolio-list/pane/streaming.ts +15 -6
  242. package/src/plugins/builtin/portfolio-list/quick-add/resolution.ts +19 -7
  243. package/src/plugins/builtin/portfolio-list/table.tsx +30 -4
  244. package/src/plugins/builtin/realized-vol/evidence.ts +33 -6
  245. package/src/plugins/builtin/realized-vol/fx-proxy.ts +135 -0
  246. package/src/plugins/builtin/realized-vol/headless.ts +44 -8
  247. package/src/plugins/builtin/realized-vol/model.ts +9 -5
  248. package/src/plugins/builtin/realized-vol/pane.tsx +49 -15
  249. package/src/plugins/builtin/sec/headless.ts +48 -6
  250. package/src/plugins/builtin/sec/index.tsx +6 -4
  251. package/src/plugins/builtin/sec/model.ts +4 -1
  252. package/src/plugins/builtin/shared/earnings-calendar.ts +2 -0
  253. package/src/plugins/builtin/shared/market-cap-bands.ts +12 -0
  254. package/src/plugins/builtin/shared/report-freshness.ts +3 -1
  255. package/src/plugins/builtin/shared/use-quote-board.ts +5 -3
  256. package/src/plugins/builtin/shared/volatility/options.ts +63 -2
  257. package/src/plugins/builtin/social-mentions/headless.ts +72 -3
  258. package/src/plugins/builtin/social-mentions/index.tsx +8 -4
  259. package/src/plugins/builtin/social-mentions/lock-note.ts +6 -2
  260. package/src/plugins/builtin/social-mentions/outliers-client.ts +101 -0
  261. package/src/plugins/builtin/social-mentions/outliers-model.ts +162 -0
  262. package/src/plugins/builtin/social-mentions/outliers-names.ts +51 -0
  263. package/src/plugins/builtin/social-mentions/outliers.tsx +276 -0
  264. package/src/plugins/builtin/social-mentions/pane.tsx +32 -3
  265. package/src/plugins/builtin/supply-chain/graph-pane.tsx +2 -2
  266. package/src/plugins/builtin/thirteenf/api.ts +36 -2
  267. package/src/plugins/builtin/thirteenf/data.ts +4 -1
  268. package/src/plugins/builtin/thirteenf/headless.ts +14 -6
  269. package/src/plugins/builtin/thirteenf/model.ts +56 -1
  270. package/src/plugins/builtin/thirteenf/pane.tsx +8 -8
  271. package/src/plugins/builtin/thirteenf/report-notes.ts +11 -0
  272. package/src/plugins/builtin/thirteenf/table.ts +2 -1
  273. package/src/plugins/builtin/thirteenf/types.ts +6 -0
  274. package/src/plugins/builtin/ticker-detail/data-panes/historical-prices.tsx +23 -3
  275. package/src/plugins/builtin/ticker-detail/financials/model.ts +5 -0
  276. package/src/plugins/builtin/ticker-detail/headless-schema.ts +2 -1
  277. package/src/plugins/builtin/ticker-detail/headless.ts +21 -66
  278. package/src/plugins/builtin/ticker-detail/index.tsx +5 -0
  279. package/src/plugins/builtin/ticker-detail/overview/components.tsx +13 -1
  280. package/src/plugins/builtin/ticker-detail/overview/model.ts +6 -4
  281. package/src/plugins/builtin/ticker-detail/overview/pane.tsx +15 -0
  282. package/src/plugins/builtin/ticker-detail/overview/tax-equivalent.ts +69 -0
  283. package/src/plugins/builtin/ticker-detail/overview-tab.tsx +41 -6
  284. package/src/plugins/builtin/ticker-detail/quote-monitor/card.tsx +47 -24
  285. package/src/plugins/builtin/ticker-detail/quote-monitor/export.ts +46 -0
  286. package/src/plugins/builtin/ticker-detail/quote-monitor/index.tsx +20 -1
  287. package/src/plugins/builtin/ticker-detail/quote-monitor/rows.ts +120 -0
  288. package/src/plugins/builtin/ticker-detail/research-tabs.ts +1 -5
  289. package/src/plugins/builtin/ticker-detail/settings.ts +6 -6
  290. package/src/plugins/builtin/treasury-auctions/cache.ts +85 -19
  291. package/src/plugins/builtin/treasury-auctions/index.tsx +22 -11
  292. package/src/plugins/builtin/treasury-auctions/model.ts +23 -0
  293. package/src/plugins/builtin/treasury-auctions/treasury-direct.ts +128 -0
  294. package/src/plugins/builtin/world-indices/client.ts +2 -0
  295. package/src/plugins/compat.ts +15 -0
  296. package/src/plugins/host-link.ts +6 -1
  297. package/src/plugins/installer.ts +8 -3
  298. package/src/portfolio/column-values.ts +14 -4
  299. package/src/portfolio/listed-symbol.ts +78 -0
  300. package/src/portfolio/real-return.ts +172 -0
  301. package/src/public/__snapshots__/public-api.test.ts.snap +1 -0
  302. package/src/renderers/browser/config-host.ts +56 -15
  303. package/src/renderers/browser/main.tsx +3 -1
  304. package/src/renderers/browser/ui-host.tsx +1 -0
  305. package/src/renderers/cloudflare/http-proxy.ts +1 -0
  306. package/src/renderers/dom/boot-frame.ts +2 -2
  307. package/src/renderers/dom/data-table/row.tsx +4 -1
  308. package/src/renderers/dom/desktop/controls.tsx +4 -4
  309. package/src/renderers/dom/desktop/dialog-actions.tsx +60 -41
  310. package/src/renderers/dom/dom-ui-host.tsx +3 -1
  311. package/src/renderers/dom/host/input.tsx +4 -1
  312. package/src/renderers/dom/host/tabs.tsx +10 -1
  313. package/src/renderers/dom/styles.css +33 -13
  314. package/src/renderers/electrobun/bun/desktop/app-name.ts +1 -1
  315. package/src/renderers/opentui/host.tsx +2 -1
  316. package/src/sources/gloomberb-cloud/fred-series.ts +12 -0
  317. package/src/sources/gloomberb-cloud/index.ts +31 -2
  318. package/src/sources/gloomberb-cloud/normalizers.ts +29 -3
  319. package/src/sources/provider-router/cached-routes.ts +19 -7
  320. package/src/state/pane-table-export-registry.ts +19 -6
  321. package/src/test-support/preload.ts +5 -1
  322. package/src/theme/colors.ts +9 -1
  323. package/src/theme/themes.ts +62 -15
  324. package/src/theme/tone-contrast.ts +40 -0
  325. package/src/theme/ui-tokens.ts +23 -3
  326. package/src/tickers/batched-lookups.ts +57 -8
  327. package/src/tickers/company-name-listing.ts +156 -14
  328. package/src/tickers/company-name.ts +30 -6
  329. package/src/tickers/list.ts +7 -0
  330. package/src/tickers/search/home-listing.ts +31 -9
  331. package/src/tickers/search/index.ts +13 -3
  332. package/src/tickers/search/listing-index.ts +558 -0
  333. package/src/tickers/search/major-listings.chunk.ts +10 -0
  334. package/src/tickers/search/major-listings.json +3346 -0
  335. package/src/tickers/search/ranking.ts +68 -1
  336. package/src/tickers/search/types.ts +4 -0
  337. package/src/tickers/terminal-codes.ts +26 -1
  338. package/src/time-series/calendar-month-returns.ts +47 -0
  339. package/src/time-series/currency-conversion.ts +130 -0
  340. package/src/time-series/hooks.ts +2 -0
  341. package/src/time-series/price-comparison.ts +34 -11
  342. package/src/time-series/resolve-context.ts +3 -0
  343. package/src/time-series/resolve.ts +14 -2
  344. package/src/time-series/spec.ts +1 -0
  345. package/src/time-series/studies/indicators.ts +4 -1
  346. package/src/time-series/types.ts +8 -0
  347. package/src/types/config.ts +8 -0
  348. package/src/types/data-provider.ts +28 -0
  349. package/src/types/financials.ts +20 -2
  350. package/src/types/headless.ts +12 -0
  351. package/src/ui/host.tsx +8 -0
  352. package/src/utils/datetime-format.ts +17 -3
  353. package/src/utils/display-number.ts +15 -0
  354. package/src/utils/double-escape-close.ts +61 -16
  355. package/src/utils/float32-price.ts +24 -0
  356. package/src/utils/forward-dividend.ts +81 -16
  357. package/src/utils/fx-market-hours.ts +11 -0
  358. package/src/utils/plugin-proxy-hosts.json +2 -1
  359. package/src/utils/price-history.ts +7 -6
  360. package/src/utils/report-timing.ts +62 -0
  361. package/src/utils/sec-filings.ts +32 -0
  362. package/src/utils/utc-time.ts +5 -0
@@ -1,5 +1,5 @@
1
1
  import type { PerpBoardPayload, PerpBoardRow, PerpDepthRow, PerpLiquidationMarket, PerpLiquidationPrint, PerpLiquidationsPayload } from "../../../api-client/perps";
2
- import type { HeadlessBundleSection, HeadlessPaneColumn, HeadlessPaneLoadArgs, HeadlessPaneRow } from "../../../types/headless";
2
+ import type { HeadlessBundleResult, HeadlessBundleSection, HeadlessPaneColumn, HeadlessPaneContext, HeadlessPaneLoadArgs, HeadlessPaneRow } from "../../../types/headless";
3
3
  import type { HeadlessPaneDefinition } from "../../../types/plugin";
4
4
  import { DEPTH_COLUMN_IDS, depthBandTotals, depthCellText, depthColumnLabel, depthFreshness, depthStaleNote, downStreams, LIQUIDATION_COLUMN_IDS, liquidationCellText, liquidationColumnLabel, liquidationFreshness,
5
5
  PRINT_COLUMN_IDS, printCellText, printColumnLabel, type DepthColumnId, type LiquidationColumnId, type PrintColumnId } from "./cascade";
@@ -8,6 +8,7 @@ import { perpFreshness } from "./freshness";
8
8
  import { aprFootnote, ASSET_FILTERS, BOARD_COLUMNS, BOARD_SORTS, collectedVenueCount, COMPARE_COLUMNS, compact, fundingSpread, HISTORY_METRICS, label, marketLabel, observed, openingTab, PERP_TABS, perpCellText,
9
9
  perpColumnLabel, percent, perpHistoryProText, positioningFields, price, RANKING_COLUMNS, rankingRows, RANKINGS, ratioText, share, time, uncoveredVenueNote, VENUES, venueName, venuesOf, IDENTITY_VENUES, type PerpColumnId } from "./model";
10
10
  import { freePreviewNote } from "../shared/free-preview";
11
+ import { REPORT_ROWS } from "../shared/headless-options";
11
12
  import { basisSpotSymbol } from "../futures-curve/model";
12
13
 
13
14
  // Text columns only: the text report shows these, JSON keeps every field of every row. Rates, premiums and
@@ -183,7 +184,7 @@ const listMetadata = (data: Pick<PerpBoardPayload, "asOf" | "access" | "status">
183
184
 
184
185
  export const perpsHeadless: HeadlessPaneDefinition<"bundle"> = {
185
186
  shape: "bundle", argument: { kind: "free-text", optional: true, placeholder: "market",
186
- description: "A base asset, underlying, canonical market identity or Market column label, such as BTC, hyperliquid:xyz:TSLA or SP500 · XYZ. Opens its history; with --tab board it searches the board, with --tab compare, liquidations or depth it is the base asset. Without one, the board." },
187
+ description: "A base asset, underlying, canonical market identity or Market column label, such as BTC, hyperliquid:xyz:TSLA or xyz:TSLA. Opens its history; with --tab board it searches the board, with --tab compare, liquidations or depth it is the base asset. Without one, the board." },
187
188
  options: [
188
189
  { key: "tab", type: "enum", settingKey: "tab", values: PERP_TABS.map((value) => ({ value })), description: "Board, rankings, compare, liquidations, depth, history or evidence. Board without a market, history with one." },
189
190
  { key: "asset-class", type: "enum", settingKey: "assetClass", values: ASSET_FILTERS.map((value) => ({ value })), defaultValue: "all", description: "Board asset class." },
@@ -192,6 +193,7 @@ export const perpsHeadless: HeadlessPaneDefinition<"bundle"> = {
192
193
  { key: "sort", type: "enum", settingKey: "sort", values: BOARD_SORTS.map((value) => ({ value })), defaultValue: "oi", description: "Board order: open interest, funding, open-interest change, premium or long share of accounts." },
193
194
  { key: "days", type: "enum", settingKey: "days", values: ["1", "7", "30", "90", "365"].map((value) => ({ value })), defaultValue: "7", description: "History lookback in days." },
194
195
  { key: "metric", type: "enum", settingKey: "metric", values: HISTORY_METRICS.map((value) => ({ value })), defaultValue: "funding", description: "Displayed history chart; JSON retains every series." },
196
+ { key: "limit", type: "integer", shot: REPORT_ROWS, minimum: 1, maximum: 5000, description: "Rows to list in each table, in its order: every row unless given.", example: "--limit 10" },
195
197
  ],
196
198
  discovery: { aliases: ["PERP"], dataRequirements: ["Perpetual market observations"], limitations: ["Free accounts see a fixed preview of the board, rankings and comparisons, and latest values for one market.", "Pro unlocks every market, full rankings and history.", "Rankings list up to ten markets each.", "Rates, premiums and changes are fractions in JSON.", "Open-interest history begins at first collection.", "Funding APR is a simple annualization, not a forecast.",
197
199
  "Long/short account shares: venue definitions differ; history begins at first collection.",
@@ -199,127 +201,135 @@ export const perpsHeadless: HeadlessPaneDefinition<"bundle"> = {
199
201
  "Order book depth is read hourly for each venue's 50 largest markets; a band wider than the book a venue returns is a floor (≥). Free shows the latest; Pro the week's history."] },
200
202
  describe: (args) => TITLES[tabOf(args)],
201
203
  async load(args, ctx) {
202
- const requested = requestedOf(args);
203
- const tab = tabOf(args);
204
- if (tab === "board") {
205
- const assetClass = String(args.options["asset-class"] ?? "all"), venue = String(args.options.venue ?? "all"), sort = String(args.options.sort ?? "oi");
206
- const board = await fetchPerpsBoard({ ...(assetClass !== "all" ? { assetClass } : {}), ...(venue !== "all" ? { venue } : {}),
207
- ...(requested ? { search: boardSearchText(requested) } : {}), sort }, ctx.apiClient);
208
- // The server answers a venue with its own markets; a server that does not filter by venue answers every venue's.
209
- const rows = venue === "all" ? board.rows : board.rows.filter((row) => row.venue === venue);
210
- const lock = venue === "all" ? more(board.locked, "markets") : venuePreviewLine(venue, rows, board.rows);
211
- return { sections: [{ ...marketSection("Markets", BOARD_TEXT_COLUMNS, rows), ...lockedTable(board.locked && !rows.length) }], complete: !board.locked && board.status === "ok",
212
- errors: board.locked ? [lock] : [], ...aprNote(rows), freshness: perpFreshness(rows, { funding: rows, venue }),
213
- metadata: { ...listMetadata(board), total: board.total, assetClass, venue, sort, ...(requested ? { search: requested } : {}) } };
214
- }
215
- if (tab === "rankings") {
216
- const rankings = await fetchPerpsRankings(ctx.apiClient);
217
- // A ranking the free view leaves empty is locked, left out and said on the Pro line; one that has none to rank says so.
218
- const sections: HeadlessBundleSection[] = RANKINGS.map((ranking) => {
219
- const rows = rankingRows(rankings, ranking.key);
220
- return { ...marketSection(ranking.label, rankingTextColumns(ranking), rows), ...lockedTable(rankings.locked && !rows.length) };
221
- });
222
- const notices = venueUnused(String(args.options.venue ?? "all"), "rankings");
223
- // Only the funding lists show funding.
224
- const funding = RANKINGS.filter((ranking) => ranking.field === "fundingRate8h").flatMap((ranking) => rankingRows(rankings, ranking.key));
225
- // The rankings show neither APR % nor Long %, only OI USD.
226
- const ranked = RANKINGS.flatMap((ranking) => rankingRows(rankings, ranking.key));
227
- return { sections, complete: !rankings.locked && rankings.status === "ok", errors: rankings.locked ? ["Full rankings need Gloom Pro"] : [],
228
- ...aprNote(ranked, { apr: false, longShare: false }),
229
- freshness: perpFreshness(RANKINGS.flatMap((ranking) => rankingRows(rankings, ranking.key)), { funding }), metadata: { ...(notices.length ? { notices } : {}), ...listMetadata(rankings) } };
230
- }
231
- if (tab === "compare") {
232
- // A canonical identity names one contract; its base asset is what the venues share.
233
- const identity = marketQuery(requested);
234
- const asked = identity.includes(":") ? (await fetchPerpSelection(identity, ctx.apiClient)).rows[0]?.baseAsset ?? identity : (requested || DEFAULT_MARKET).toUpperCase();
235
- // A pair or plain name (BTC-USD, bitcoin) compares the base asset it stands for; the rows say which.
236
- const compare = await fetchPerpsCompare(asked, ctx.apiClient);
237
- if (!compare.rows.length && !compare.locked) throw noMarket(requested || asked, await nearestPerpMarkets(requested || asked, ctx.apiClient));
238
- const base = compare.rows[0]?.baseAsset ?? asked;
239
- const spread = fundingSpread(compare.rows);
240
- const notices = [...(requested ? [] : [`Showing ${DEFAULT_MARKET}. Try fn PERP ${EXAMPLE_MARKETS[1]} --tab compare.`]),
241
- ...requested && !identity.includes(":") && base.toUpperCase() !== asked ? readAs(base, requested) : [], ...venueUnused(String(args.options.venue ?? "all"), "compare")];
242
- return { sections: [{ ...marketSection("Contracts", COMPARE_TEXT_COLUMNS, compare.rows), ...lockedTable(compare.locked) },
243
- ...(spread ? [{ title: "Funding spread", entries: [{ key: "fundingSpread8h", label: "Funding spread 8h", value: spread.value, formatted: `${spread.text} ${spread.detail}` }] }] : [])],
244
- complete: !compare.locked && compare.status === "ok", errors: compare.locked ? [more(compare.locked, compare.locked === 1 ? "contract" : "contracts")] : [],
245
- ...aprNote(compare.rows), freshness: perpFreshness(compare.rows, { funding: compare.rows }),
246
- metadata: { ...(requested ? {} : { defaultArgument: DEFAULT_MARKET }), ...(notices.length ? { notices } : {}),
247
- ...listMetadata(compare), total: compare.total, baseAsset: base,
248
- ...(spread ? { fundingSpread8h: spread.value, fundingSpreadHigh: spread.high.marketId, fundingSpreadLow: spread.low.marketId } : {}) } };
249
- }
250
- if (tab === "liquidations" || tab === "depth") {
251
- // A canonical identity names one contract; its base asset is what the venues share. A pair or plain name reads as its base asset.
252
- const identity = marketQuery(requested);
253
- const asked = identity.includes(":") ? (await fetchPerpSelection(identity, ctx.apiClient)).rows[0]?.baseAsset ?? identity : (requested || DEFAULT_MARKET).toUpperCase();
254
- const notices = (base: string) => [...(requested ? [] : [`Showing ${DEFAULT_MARKET}. Try fn PERP ${EXAMPLE_MARKETS[1]} --tab ${tab}.`]),
255
- ...requested && !identity.includes(":") && base.toUpperCase() !== asked ? readAs(base, requested) : [], ...venueUnused(String(args.options.venue ?? "all"), tab)];
256
- if (tab === "liquidations") {
257
- const data = await fetchPerpsLiquidations(asked, ctx.apiClient);
258
- if (!data.markets.length && data.status !== "unavailable") throw noMarket(requested || asked, await nearestPerpMarkets(requested || asked, ctx.apiClient));
259
- const told = notices(data.baseAsset);
260
- const locked = lockedTable(data.locked);
261
- const entries = (["long24h", "short24h", "long7d", "short7d"] as const).map((key) => ({ key, label: `${key.startsWith("long") ? "Longs" : "Shorts"} liquidated ${key.endsWith("24h") ? "24h" : "7d"}`,
262
- value: data.totals[key], formatted: `${compact(data.totals[key])} USD` }));
263
- return { sections: [{ title: "Totals", entries: [...entries, { key: "collectingSince", label: "Collecting since", value: data.collectingSince, formatted: time(data.collectingSince) }] },
264
- { title: "By contract", columns: LIQUIDATION_TEXT_COLUMNS, rows: data.markets.map((row) => ({ ...row })) },
265
- { title: "Hourly", columns: HOURLY_COLUMNS, rows: data.hourly.map((row) => ({ ...row })), ...locked },
266
- // The prints are the window's, not the 24 hours beside them: the heading says which.
267
- { title: "Largest prints", textTitle: windowDays(data) ? `Largest prints, ${windowDays(data)}` : "Largest prints", columns: printTextColumns(data.baseAsset), rows: data.largest.map((row) => ({ ...row })) }],
268
- complete: !data.locked && data.status === "ok" && !downStreams(data).length, notes: data.notes,
269
- errors: data.locked ? [freePreviewNote({ shows: "liquidation totals and the three largest prints", adds: "the hourly series and the twenty largest prints" })] : [],
270
- freshness: liquidationFreshness(data),
271
- metadata: { ...(requested ? {} : { defaultArgument: DEFAULT_MARKET }), ...(told.length ? { notices: told } : {}), baseAsset: data.baseAsset, asOf: data.asOf, from: data.from,
272
- access: data.access, locked: data.locked, status: data.status, collectingSince: data.collectingSince, streams: data.streams, notionalCurrency: "USD" } };
273
- }
274
- const data = await fetchPerpsDepth(asked, ctx.apiClient);
275
- if (!data.rows.length && data.status !== "unavailable") throw noMarket(requested || asked, await nearestPerpMarkets(requested || asked, ctx.apiClient));
276
- const told = notices(data.baseAsset);
277
- const staleNote = depthStaleNote(data.rows);
278
- // The band totals over the current books, as the tab's figures show them; a floor (≥) when a book ends inside the band.
279
- const bands = depthBandTotals(data.rows).map((band) => ({ key: `band${band.key}`, label: band.label, value: band.bids + band.asks,
280
- formatted: `${band.floor ? "≥" : ""}${compact(band.bids + band.asks)} USD (bids ${compact(band.bids)} · asks ${compact(band.asks)}, ${band.books} ${band.books === 1 ? "book" : "books"})` }));
281
- return { sections: [...bands.length ? [{ title: "Band totals", entries: bands }] : [],
282
- { title: "Order books", columns: DEPTH_TEXT_COLUMNS, rows: data.rows.map((row) => ({ ...row })) },
283
- { title: "Hourly depth", columns: DEPTH_HISTORY_COLUMNS, rows: data.history.map((row) => ({ ...row })), ...lockedTable(data.locked) }],
284
- complete: !data.locked && data.status === "ok" && !staleNote, notes: [...staleNote ? [staleNote] : [], ...data.notes],
285
- errors: data.locked ? [freePreviewNote({ shows: "each book's latest depth", adds: "the week's hourly depth" })] : [],
286
- freshness: depthFreshness(data),
287
- metadata: { ...(requested ? {} : { defaultArgument: DEFAULT_MARKET }), ...(told.length ? { notices: told } : {}), baseAsset: data.baseAsset, asOf: data.asOf,
288
- access: data.access, locked: data.locked, status: data.status, sources: data.sources, notionalCurrency: "USD", reach: "fraction of mid" } };
289
- }
290
- const search = requested || DEFAULT_MARKET, venue = String(args.options.venue ?? "all");
291
- const market = await fetchPerpSelection(search, ctx.apiClient, venue !== "all" ? venue : undefined);
292
- const selected = market.rows[0];
293
- if (!selected) throw noMarket(search, market.suggestions);
294
- const notices = [...(requested ? [] : [`Showing ${DEFAULT_MARKET}. Try fn PERP ${EXAMPLE_MARKETS[1]}.`]),
295
- ...market.resolved ? readAs(marketLabel(selected), requested, market.resolved.others) : [], ...venueNotice(venue, selected, requested, market.access)];
296
- const metadata = { ...(requested ? {} : { defaultArgument: DEFAULT_MARKET }), ...(notices.length ? { notices } : {}), marketId: selected.marketId, sourceUrl: selected.sourceUrl, observedAt: selected.observedAt, sourceAsOf: selected.sourceAsOf,
297
- rates: "fraction", quoteCurrency: selected.quoteCurrency, oiCurrency: "USD", fundingIntervalHours: selected.fundingIntervalHours };
298
- // The venue's market as last polled, with the funding its latest row shows.
299
- const freshness = perpFreshness([selected], { funding: [selected] });
300
- // The same Positioning lines the pane's Evidence shows; JSON keeps the raw reading on the market row.
301
- const positioning = positioningFields(selected);
302
- if (tab === "evidence") return {
303
- sections: [marketSection("Market evidence", MARKET_COLUMNS, market.rows),
304
- // Where the figures were read, as the pane's Evidence names it: the venue's own endpoint and its time.
305
- { title: "Source", entries: [{ key: "sourceUrl", label: "URL", value: selected.sourceUrl },
306
- { key: "sourceAsOf", label: "Venue as of", value: selected.sourceAsOf, formatted: time(selected.sourceAsOf) }] },
307
- ...(positioning ? [{ title: "Positioning", entries: positioning.map((field) => ({ key: field.key, label: field.label, value: field.value,
308
- formatted: field.detail ? `${field.text} · ${field.detail}` : field.text })) }] : []),
309
- { title: "Observation revisions", columns: REVISION_COLUMNS, rows: market.evidence.map((row) => ({ ...row })), ...lockedTable(market.access !== "pro") }],
310
- // Positioning dates the long share itself.
311
- complete: market.access === "pro" && market.status === "ok", ...aprNote(market.rows, { longShare: false }), freshness,
312
- errors: market.access !== "pro" ? [freePreviewNote({ shows: `${marketLabel(selected)}'s latest evidence and positioning`, adds: "its observation revisions" })] : [],
313
- metadata: { ...metadata, asOf: market.asOf, access: market.access, locked: market.locked, status: market.status },
314
- };
315
- const history = await fetchPerpsHistory({ marketId: selected.marketId, from: new Date(Date.now() - Number(args.options.days ?? 7) * 86_400_000).toISOString(), resolution: "auto", limit: 5000 }, ctx.apiClient);
316
- const locked = lockedTable(history.locked);
317
- return { sections: [marketSection("Latest market", MARKET_COLUMNS, [selected]), { title: "Own observations", columns: observationColumns(selected.quoteCurrency), rows: history.rows.map((row) => ({ ...row })), ...locked },
318
- { title: "Paid funding", columns: FUNDING_COLUMNS, rows: history.funding.map((row) => ({ ...row })), ...locked }, { title: "Hourly candles", columns: candleColumns(selected.quoteCurrency), rows: history.candles.map((row) => ({ ...row })), ...locked },
319
- { title: "Long/short history", columns: LONG_SHORT_COLUMNS, rows: (history.longShortRatio ?? []).map((row) => ({ ...row })), ...locked }],
320
- complete: !history.locked && !history.truncated && history.status === "ok", ...aprNote([selected]), freshness,
321
- errors: history.locked ? [historyLock(selected, collectedVenueCount(market.sources))] : history.truncated ? ["History reached the 5,000-observation limit; narrow the range"] : [],
322
- metadata: { ...metadata, asOf: history.asOf, access: history.access, locked: history.locked, status: history.status, from: history.from, to: history.to, resolution: history.resolution, truncated: history.truncated ?? false },
323
- };
204
+ const result = await loadPerpTab(args, ctx);
205
+ // `--limit` lists the first rows of each table, in its own order.
206
+ const limit = args.options.limit == null ? null : Number(args.options.limit);
207
+ return limit == null ? result : { ...result, sections: result.sections.map((section) => section.rows ? { ...section, rows: section.rows.slice(0, limit) } : section) };
324
208
  },
325
209
  };
210
+
211
+ /** One tab of PERP, every row the server sent. */
212
+ async function loadPerpTab(args: HeadlessPaneLoadArgs, ctx: HeadlessPaneContext): Promise<HeadlessBundleResult> {
213
+ const requested = requestedOf(args);
214
+ const tab = tabOf(args);
215
+ if (tab === "board") {
216
+ const assetClass = String(args.options["asset-class"] ?? "all"), venue = String(args.options.venue ?? "all"), sort = String(args.options.sort ?? "oi");
217
+ const board = await fetchPerpsBoard({ ...(assetClass !== "all" ? { assetClass } : {}), ...(venue !== "all" ? { venue } : {}),
218
+ ...(requested ? { search: boardSearchText(requested) } : {}), sort }, ctx.apiClient);
219
+ // The server answers a venue with its own markets; a server that does not filter by venue answers every venue's.
220
+ const rows = venue === "all" ? board.rows : board.rows.filter((row) => row.venue === venue);
221
+ const lock = venue === "all" ? more(board.locked, "markets") : venuePreviewLine(venue, rows, board.rows);
222
+ return { sections: [{ ...marketSection("Markets", BOARD_TEXT_COLUMNS, rows), ...lockedTable(board.locked && !rows.length) }], complete: !board.locked && board.status === "ok",
223
+ errors: board.locked ? [lock] : [], ...aprNote(rows), freshness: perpFreshness(rows, { funding: rows, venue }),
224
+ metadata: { ...listMetadata(board), total: board.total, assetClass, venue, sort, ...(requested ? { search: requested } : {}) } };
225
+ }
226
+ if (tab === "rankings") {
227
+ const rankings = await fetchPerpsRankings(ctx.apiClient);
228
+ // A ranking the free view leaves empty is locked, left out and said on the Pro line; one that has none to rank says so.
229
+ const sections: HeadlessBundleSection[] = RANKINGS.map((ranking) => {
230
+ const rows = rankingRows(rankings, ranking.key);
231
+ return { ...marketSection(ranking.label, rankingTextColumns(ranking), rows), ...lockedTable(rankings.locked && !rows.length) };
232
+ });
233
+ const notices = venueUnused(String(args.options.venue ?? "all"), "rankings");
234
+ // Only the funding lists show funding.
235
+ const funding = RANKINGS.filter((ranking) => ranking.field === "fundingRate8h").flatMap((ranking) => rankingRows(rankings, ranking.key));
236
+ // The rankings show neither APR % nor Long %, only OI USD.
237
+ const ranked = RANKINGS.flatMap((ranking) => rankingRows(rankings, ranking.key));
238
+ return { sections, complete: !rankings.locked && rankings.status === "ok", errors: rankings.locked ? ["Full rankings need Gloom Pro"] : [],
239
+ ...aprNote(ranked, { apr: false, longShare: false }),
240
+ freshness: perpFreshness(RANKINGS.flatMap((ranking) => rankingRows(rankings, ranking.key)), { funding }), metadata: { ...(notices.length ? { notices } : {}), ...listMetadata(rankings) } };
241
+ }
242
+ if (tab === "compare") {
243
+ // A canonical identity names one contract; its base asset is what the venues share.
244
+ const identity = marketQuery(requested);
245
+ const asked = identity.includes(":") ? (await fetchPerpSelection(identity, ctx.apiClient)).rows[0]?.baseAsset ?? identity : (requested || DEFAULT_MARKET).toUpperCase();
246
+ // A pair or plain name (BTC-USD, bitcoin) compares the base asset it stands for; the rows say which.
247
+ const compare = await fetchPerpsCompare(asked, ctx.apiClient);
248
+ if (!compare.rows.length && !compare.locked) throw noMarket(requested || asked, await nearestPerpMarkets(requested || asked, ctx.apiClient));
249
+ const base = compare.rows[0]?.baseAsset ?? asked;
250
+ const spread = fundingSpread(compare.rows);
251
+ const notices = [...(requested ? [] : [`Showing ${DEFAULT_MARKET}. Try fn PERP ${EXAMPLE_MARKETS[1]} --tab compare.`]),
252
+ ...requested && !identity.includes(":") && base.toUpperCase() !== asked ? readAs(base, requested) : [], ...venueUnused(String(args.options.venue ?? "all"), "compare")];
253
+ return { sections: [{ ...marketSection("Contracts", COMPARE_TEXT_COLUMNS, compare.rows), ...lockedTable(compare.locked) },
254
+ ...(spread ? [{ title: "Funding spread", entries: [{ key: "fundingSpread8h", label: "Funding spread 8h", value: spread.value, formatted: `${spread.text} ${spread.detail}` }] }] : [])],
255
+ complete: !compare.locked && compare.status === "ok", errors: compare.locked ? [more(compare.locked, compare.locked === 1 ? "contract" : "contracts")] : [],
256
+ ...aprNote(compare.rows), freshness: perpFreshness(compare.rows, { funding: compare.rows }),
257
+ metadata: { ...(requested ? {} : { defaultArgument: DEFAULT_MARKET }), ...(notices.length ? { notices } : {}),
258
+ ...listMetadata(compare), total: compare.total, baseAsset: base,
259
+ ...(spread ? { fundingSpread8h: spread.value, fundingSpreadHigh: spread.high.marketId, fundingSpreadLow: spread.low.marketId } : {}) } };
260
+ }
261
+ if (tab === "liquidations" || tab === "depth") {
262
+ // A canonical identity names one contract; its base asset is what the venues share. A pair or plain name reads as its base asset.
263
+ const identity = marketQuery(requested);
264
+ const asked = identity.includes(":") ? (await fetchPerpSelection(identity, ctx.apiClient)).rows[0]?.baseAsset ?? identity : (requested || DEFAULT_MARKET).toUpperCase();
265
+ const notices = (base: string) => [...(requested ? [] : [`Showing ${DEFAULT_MARKET}. Try fn PERP ${EXAMPLE_MARKETS[1]} --tab ${tab}.`]),
266
+ ...requested && !identity.includes(":") && base.toUpperCase() !== asked ? readAs(base, requested) : [], ...venueUnused(String(args.options.venue ?? "all"), tab)];
267
+ if (tab === "liquidations") {
268
+ const data = await fetchPerpsLiquidations(asked, ctx.apiClient);
269
+ if (!data.markets.length && data.status !== "unavailable") throw noMarket(requested || asked, await nearestPerpMarkets(requested || asked, ctx.apiClient));
270
+ const told = notices(data.baseAsset);
271
+ const locked = lockedTable(data.locked);
272
+ const entries = (["long24h", "short24h", "long7d", "short7d"] as const).map((key) => ({ key, label: `${key.startsWith("long") ? "Longs" : "Shorts"} liquidated ${key.endsWith("24h") ? "24h" : "7d"}`,
273
+ value: data.totals[key], formatted: `${compact(data.totals[key])} USD` }));
274
+ return { sections: [{ title: "Totals", entries: [...entries, { key: "collectingSince", label: "Collecting since", value: data.collectingSince, formatted: time(data.collectingSince) }] },
275
+ { title: "By contract", columns: LIQUIDATION_TEXT_COLUMNS, rows: data.markets.map((row) => ({ ...row })) },
276
+ { title: "Hourly", columns: HOURLY_COLUMNS, rows: data.hourly.map((row) => ({ ...row })), ...locked },
277
+ // The prints are the window's, not the 24 hours beside them: the heading says which.
278
+ { title: "Largest prints", textTitle: windowDays(data) ? `Largest prints, ${windowDays(data)}` : "Largest prints", columns: printTextColumns(data.baseAsset), rows: data.largest.map((row) => ({ ...row })) }],
279
+ complete: !data.locked && data.status === "ok" && !downStreams(data).length, notes: data.notes,
280
+ errors: data.locked ? [freePreviewNote({ shows: "liquidation totals and the three largest prints", adds: "the hourly series and the twenty largest prints" })] : [],
281
+ freshness: liquidationFreshness(data),
282
+ metadata: { ...(requested ? {} : { defaultArgument: DEFAULT_MARKET }), ...(told.length ? { notices: told } : {}), baseAsset: data.baseAsset, asOf: data.asOf, from: data.from,
283
+ access: data.access, locked: data.locked, status: data.status, collectingSince: data.collectingSince, streams: data.streams, notionalCurrency: "USD" } };
284
+ }
285
+ const data = await fetchPerpsDepth(asked, ctx.apiClient);
286
+ if (!data.rows.length && data.status !== "unavailable") throw noMarket(requested || asked, await nearestPerpMarkets(requested || asked, ctx.apiClient));
287
+ const told = notices(data.baseAsset);
288
+ const staleNote = depthStaleNote(data.rows);
289
+ // The band totals over the current books, as the tab's figures show them; a floor (≥) when a book ends inside the band.
290
+ const bands = depthBandTotals(data.rows).map((band) => ({ key: `band${band.key}`, label: band.label, value: band.bids + band.asks,
291
+ formatted: `${band.floor ? "≥" : ""}${compact(band.bids + band.asks)} USD (bids ${compact(band.bids)} · asks ${compact(band.asks)}, ${band.books} ${band.books === 1 ? "book" : "books"})` }));
292
+ return { sections: [...bands.length ? [{ title: "Band totals", entries: bands }] : [],
293
+ { title: "Order books", columns: DEPTH_TEXT_COLUMNS, rows: data.rows.map((row) => ({ ...row })) },
294
+ { title: "Hourly depth", columns: DEPTH_HISTORY_COLUMNS, rows: data.history.map((row) => ({ ...row })), ...lockedTable(data.locked) }],
295
+ complete: !data.locked && data.status === "ok" && !staleNote, notes: [...staleNote ? [staleNote] : [], ...data.notes],
296
+ errors: data.locked ? [freePreviewNote({ shows: "each book's latest depth", adds: "the week's hourly depth" })] : [],
297
+ freshness: depthFreshness(data),
298
+ metadata: { ...(requested ? {} : { defaultArgument: DEFAULT_MARKET }), ...(told.length ? { notices: told } : {}), baseAsset: data.baseAsset, asOf: data.asOf,
299
+ access: data.access, locked: data.locked, status: data.status, sources: data.sources, notionalCurrency: "USD", reach: "fraction of mid" } };
300
+ }
301
+ const search = requested || DEFAULT_MARKET, venue = String(args.options.venue ?? "all");
302
+ const market = await fetchPerpSelection(search, ctx.apiClient, venue !== "all" ? venue : undefined);
303
+ const selected = market.rows[0];
304
+ if (!selected) throw noMarket(search, market.suggestions);
305
+ const notices = [...(requested ? [] : [`Showing ${DEFAULT_MARKET}. Try fn PERP ${EXAMPLE_MARKETS[1]}.`]),
306
+ ...market.resolved ? readAs(marketLabel(selected), requested, market.resolved.others) : [], ...venueNotice(venue, selected, requested, market.access)];
307
+ const metadata = { ...(requested ? {} : { defaultArgument: DEFAULT_MARKET }), ...(notices.length ? { notices } : {}), marketId: selected.marketId, sourceUrl: selected.sourceUrl, observedAt: selected.observedAt, sourceAsOf: selected.sourceAsOf,
308
+ rates: "fraction", quoteCurrency: selected.quoteCurrency, oiCurrency: "USD", fundingIntervalHours: selected.fundingIntervalHours };
309
+ // The venue's market as last polled, with the funding its latest row shows.
310
+ const freshness = perpFreshness([selected], { funding: [selected] });
311
+ // The same Positioning lines the pane's Evidence shows; JSON keeps the raw reading on the market row.
312
+ const positioning = positioningFields(selected);
313
+ if (tab === "evidence") return {
314
+ sections: [marketSection("Market evidence", MARKET_COLUMNS, market.rows),
315
+ // Where the figures were read, as the pane's Evidence names it: the venue's own endpoint and its time.
316
+ { title: "Source", entries: [{ key: "sourceUrl", label: "URL", value: selected.sourceUrl },
317
+ { key: "sourceAsOf", label: "Venue as of", value: selected.sourceAsOf, formatted: time(selected.sourceAsOf) }] },
318
+ ...(positioning ? [{ title: "Positioning", entries: positioning.map((field) => ({ key: field.key, label: field.label, value: field.value,
319
+ formatted: field.detail ? `${field.text} · ${field.detail}` : field.text })) }] : []),
320
+ { title: "Observation revisions", columns: REVISION_COLUMNS, rows: market.evidence.map((row) => ({ ...row })), ...lockedTable(market.access !== "pro") }],
321
+ // Positioning dates the long share itself.
322
+ complete: market.access === "pro" && market.status === "ok", ...aprNote(market.rows, { longShare: false }), freshness,
323
+ errors: market.access !== "pro" ? [freePreviewNote({ shows: `${marketLabel(selected)}'s latest evidence and positioning`, adds: "its observation revisions" })] : [],
324
+ metadata: { ...metadata, asOf: market.asOf, access: market.access, locked: market.locked, status: market.status },
325
+ };
326
+ const history = await fetchPerpsHistory({ marketId: selected.marketId, from: new Date(Date.now() - Number(args.options.days ?? 7) * 86_400_000).toISOString(), resolution: "auto", limit: 5000 }, ctx.apiClient);
327
+ const locked = lockedTable(history.locked);
328
+ return { sections: [marketSection("Latest market", MARKET_COLUMNS, [selected]), { title: "Own observations", columns: observationColumns(selected.quoteCurrency), rows: history.rows.map((row) => ({ ...row })), ...locked },
329
+ { title: "Paid funding", columns: FUNDING_COLUMNS, rows: history.funding.map((row) => ({ ...row })), ...locked }, { title: "Hourly candles", columns: candleColumns(selected.quoteCurrency), rows: history.candles.map((row) => ({ ...row })), ...locked },
330
+ { title: "Long/short history", columns: LONG_SHORT_COLUMNS, rows: (history.longShortRatio ?? []).map((row) => ({ ...row })), ...locked }],
331
+ complete: !history.locked && !history.truncated && history.status === "ok", ...aprNote([selected]), freshness,
332
+ errors: history.locked ? [historyLock(selected, collectedVenueCount(market.sources))] : history.truncated ? ["History reached the 5,000-observation limit; narrow the range"] : [],
333
+ metadata: { ...metadata, asOf: history.asOf, access: history.access, locked: history.locked, status: history.status, from: history.from, to: history.to, resolution: history.resolution, truncated: history.truncated ?? false },
334
+ };
335
+ }
@@ -18,7 +18,7 @@ import { loadPerpsCompare, loadPerpsEquity } from "./client";
18
18
  import { perpEquityIdentity } from "./equity-identity";
19
19
  import { useLivePerpRows } from "./live-rows";
20
20
  import { compact, perpCell, percent, price, readingTime, venueName } from "./model";
21
- import { useOpenPerpMarket } from "./open-market";
21
+ import { openPerpLabel, useOpenPerpMarket } from "./open-market";
22
22
  import { contractText, foldSmallMarkets, mergeVenueMarkets, type PerpVenueMarket } from "./venue-markets";
23
23
 
24
24
  const STOCK_TYPES = new Set(["STK", "EQUITY", "STOCK", "COMMON STOCK"]);
@@ -119,7 +119,7 @@ export function PerpMarketsSection({ symbol, exchange, instrumentType, quote, wi
119
119
  const cell = (column: Column, market: PerpVenueMarket, row: PerpBoardRow): ColumnGridCell => {
120
120
  if (column.id === "venue") {
121
121
  return { text: venueName(market.venue), color: row.stale ? colors.textDim : colors.textBright,
122
- link: { label: tf("Open {label}", { label: `PERP ${row.baseAsset} · ${venueName(market.venue)}` }), onOpen: () => openMarket(row.marketId) } };
122
+ link: { label: openPerpLabel(row), onOpen: () => openMarket(row.marketId) } };
123
123
  }
124
124
  if (column.id === "contract") return { text: contractText(market), color: colors.textMuted };
125
125
  if (column.id === "mark") return { text: price(row.markPrice ?? row.lastPrice), color: colors.text };
@@ -49,7 +49,11 @@ export function underlyingTicker(row: Pick<PerpBoardRow, "underlyingSymbol" | "u
49
49
  : row.underlying?.symbol.toUpperCase() === symbol ? row.underlying.listingExchange : undefined;
50
50
  return !listing || isUsListingExchange(listing) ? symbol : publicTickerKey(symbol, listing);
51
51
  }
52
- export const marketLabel = (row: Pick<PerpBoardRow, "dex" | "baseAsset">) => row.dex && row.dex !== "default" ? `${row.baseAsset} · ${row.dex.toUpperCase()}` : row.baseAsset;
52
+ /**
53
+ * A market as the Market column, the pane title and the CLI name it: its base asset, or for a market on a Hyperliquid
54
+ * builder dex Hyperliquid's own name for it, the dex before a colon (`xyz:NVDA`), which is also its contract symbol.
55
+ */
56
+ export const marketLabel = (row: Pick<PerpBoardRow, "dex" | "baseAsset">) => row.dex && row.dex !== "default" ? `${row.dex.toLowerCase()}:${row.baseAsset}` : row.baseAsset;
53
57
 
54
58
  /**
55
59
  * Plain names for markets, as the Market column writes the contracts to try, nearest first. A name the board does
@@ -58,7 +62,7 @@ export const marketLabel = (row: Pick<PerpBoardRow, "dex" | "baseAsset">) => row
58
62
  */
59
63
  const PLAIN_NAMES: Readonly<Record<string, readonly string[]>> = {
60
64
  bitcoin: ["BTC"], ethereum: ["ETH"], ether: ["ETH"], solana: ["SOL"], dogecoin: ["DOGE"], ripple: ["XRP"],
61
- brent: ["BZ", "BRENTOIL · XYZ"], brentcrude: ["BZ", "BRENTOIL · XYZ"], wti: ["CL"], wticrude: ["CL"], naturalgas: ["NATGAS · XYZ"],
65
+ brent: ["BZ", "xyz:BRENTOIL"], brentcrude: ["BZ", "xyz:BRENTOIL"], wti: ["CL"], wticrude: ["CL"], naturalgas: ["xyz:NATGAS"],
62
66
  };
63
67
  /** A pair as exchanges and charts write it: BTC-USD, BTC/USD, BTCUSD, BTCUSDT, BTC-PERP, BTC/USDT:USDT. */
64
68
  const QUOTED_PAIR = /^([A-Z0-9]{1,15}?)([-/_ ]?)(?:USDT|USDC|USD|PERP)(?::[A-Z]{3,4})?$/;
@@ -73,8 +77,8 @@ export function perpBaseCandidates(input: string): string[] {
73
77
  const pair = QUOTED_PAIR.exec(input.trim().toUpperCase());
74
78
  return pair ? [pair[1]!] : [];
75
79
  }
76
- /** The base asset a Market column label names: `BRENTOIL · XYZ` is BRENTOIL. */
77
- export const baseOfLabel = (label: string) => label.split("·")[0]!.trim();
80
+ /** The base asset a Market column label names: `xyz:BRENTOIL` is BRENTOIL. */
81
+ export const baseOfLabel = (label: string) => label.replace(/^[a-z][a-z0-9]*:/, "");
78
82
  /** The base asset of a pair written with a separator (BTC-USD, BTC/USD), which no board symbol spells; null for anything else. */
79
83
  export function separatedPairBase(input: string): string | null {
80
84
  const pair = QUOTED_PAIR.exec(input.trim().toUpperCase());
@@ -2,7 +2,7 @@ import { useCallback } from "react";
2
2
  import type { PerpBoardRow } from "../../../api-client/perps";
3
3
  import { tf } from "../../../i18n";
4
4
  import { usePluginAppActions } from "../../../public/react";
5
- import { venueLabel } from "./model";
5
+ import { marketLabel, venueLabel } from "./model";
6
6
 
7
7
  /** Opens PERP on one market: where a stock's perpetual links from DES, QQ and the watchlist and portfolio columns. */
8
8
  export function useOpenPerpMarket(): (marketId: string) => void {
@@ -10,6 +10,6 @@ export function useOpenPerpMarket(): (marketId: string) => void {
10
10
  return useCallback((marketId: string) => createPaneFromTemplate("perps-pane", { arg: marketId }), [createPaneFromTemplate]);
11
11
  }
12
12
 
13
- /** The pane menu's entry for a link to one market. */
14
- export const openPerpLabel = (row: Pick<PerpBoardRow, "baseAsset" | "venue">) =>
15
- tf("Open {label}", { label: `PERP ${row.baseAsset} · ${venueLabel(row)}` });
13
+ /** The pane menu's entry for a link to one market, named as the PERP pane it opens is titled. */
14
+ export const openPerpLabel = (row: Pick<PerpBoardRow, "baseAsset" | "dex" | "venue">) =>
15
+ tf("Open {label}", { label: `PERP ${marketLabel(row)} · ${venueLabel(row)}` });
@@ -84,13 +84,10 @@ export function foldSmallMarkets(markets: readonly PerpVenueMarket[], { minShare
84
84
  }
85
85
 
86
86
  /**
87
- * The contract a venue's row reads from, as the venue settles it (`USDT`, `USD inverse`, a Hyperliquid builder dex
88
- * such as `xyz`), and how many more it stands for: `USDT +2`.
87
+ * The contract a venue's row reads from, by its symbol on the venue as PERP's Contract column writes it (`BTCUSDT`,
88
+ * `BTC-USDT-SWAP`, `xyz:NVDA` on a Hyperliquid builder dex), and how many more it stands for: `BTCUSDT +2`.
89
89
  */
90
90
  export function contractText(market: PerpVenueMarket): string {
91
- const row = market.primary;
92
- const own = row.venue === "hyperliquid" && row.dex && row.dex !== "default" ? row.dex
93
- : row.contractType === "inverse" ? `${row.quoteCurrency} inverse` : row.quoteCurrency;
94
91
  const others = market.contracts.length - 1;
95
- return others > 0 ? `${own} +${others}` : own;
92
+ return others > 0 ? `${market.primary.symbol} +${others}` : market.primary.symbol;
96
93
  }
@@ -69,6 +69,7 @@ export function columnContextVersion(columnId: string, ctx: ColumnContext): stri
69
69
  if (PERPETUAL_COLUMN_IDS.has(columnId)) version += `|${ctx.perpetualsVersion ?? 0}`;
70
70
  if (FUTURES_TERMS_COLUMN_IDS.has(columnId)) version += `|${ctx.futuresTermsVersion ?? 0}`;
71
71
  if (columnId === "pnl" || columnId === "pnl_pct") version += `|${ctx.periodPnl ? ctx.periodPnlVersion ?? 0 : "cost"}`;
72
+ if (columnId === "ticker") version += `|${ctx.homeMarket ?? ""}`;
72
73
  if (columnId === "latency") version += `|${ctx.now}`;
73
74
  if (DAY_CLOCK_COLUMN_IDS.has(columnId)) version += `|${Math.floor(ctx.now / DAY_MS)}`;
74
75
  return version;
@@ -256,20 +256,44 @@ export function retryNotice(ctx: CliCommandContext): (count: number, waitMs: num
256
256
  };
257
257
  }
258
258
 
259
- /** A list this long says how far its lookup has got, so a long add never looks stuck. */
260
- const PROGRESS_FROM = 50;
259
+ /** A lookup this slow says how far it has got, so an add never looks stuck: first after two seconds, then every five. */
260
+ const PROGRESS_AFTER_MS = 2_000;
261
261
  const PROGRESS_EVERY_MS = 5_000;
262
262
 
263
263
  /**
264
- * Lines on standard error while a long add looks its symbols up: "Looked up
265
- * 120 of 300 symbols." every few seconds, and nothing for a short list.
264
+ * Lines on standard error while an add of several symbols is slow to look
265
+ * them up: "Looking up 10 symbols." two seconds in when none is settled yet,
266
+ * else "Looked up 4 of 10 symbols.", which it says again every five seconds
267
+ * until all are. Nothing for one symbol or a lookup that is quick. It is told
268
+ * (0, total) as the lookup starts and each symbol as it settles; the lines
269
+ * come from a timer, so a lookup waiting on one slow answer still says so.
266
270
  */
267
- export function progressNotice(ctx: CliCommandContext, now = () => Date.now()): (looked: number, total: number) => void {
268
- let last = now();
269
- return (looked, total) => {
270
- if (ctx.cliOptions.quiet || total < PROGRESS_FROM || looked >= total || now() - last < PROGRESS_EVERY_MS) return;
271
- last = now();
272
- console.error(cliStyles.muted(`Looked up ${looked} of ${total} symbols.`));
271
+ export function progressNotice(
272
+ ctx: Pick<CliCommandContext, "cliOptions">,
273
+ { afterMs = PROGRESS_AFTER_MS, everyMs = PROGRESS_EVERY_MS }: { afterMs?: number; everyMs?: number } = {},
274
+ ): (looked: number, total: number) => void {
275
+ let timer: ReturnType<typeof setTimeout> | undefined;
276
+ let looked = 0, total = 0, told = false;
277
+ const tell = () => {
278
+ timer = undefined;
279
+ if (looked >= total) return;
280
+ console.error(cliStyles.muted(told || looked > 0 ? `Looked up ${looked} of ${total} symbols.` : `Looking up ${total} symbols.`));
281
+ told = true;
282
+ schedule(everyMs);
283
+ };
284
+ const schedule = (ms: number) => {
285
+ timer = setTimeout(tell, ms);
286
+ // The add's own end, not this line, decides when the process exits.
287
+ (timer as { unref?: () => void }).unref?.();
288
+ };
289
+ return (settled, of) => {
290
+ if (ctx.cliOptions.quiet || of < 2) return;
291
+ looked = settled;
292
+ total = of;
293
+ if (looked >= total) {
294
+ if (timer) clearTimeout(timer);
295
+ timer = undefined;
296
+ } else if (!timer) schedule(afterMs);
273
297
  };
274
298
  }
275
299
 
@@ -15,6 +15,8 @@ import type { CliCommandContext } from "../../../../types/plugin";
15
15
  import type { Portfolio, TickerRecord } from "../../../../types/ticker";
16
16
  import { cliStyles, colorBySign, renderTable } from "../../../../utils/cli-output";
17
17
  import type { PriceWindow } from "../../../../utils/price-window";
18
+ import { apiClient } from "../../../../api-client";
19
+ import { inflationMethodText, loadPeriodInflation, monthText, realReturn } from "../../../../portfolio/real-return";
18
20
  import { loadPeriodPnl, periodBasisText, periodBoughtText, periodSharedDay, periodUnpricedText, type LoadedPeriodPnl } from "../period-pnl";
19
21
 
20
22
  const signedPercent = (value: number | null) => value == null || !Number.isFinite(value) ? "—"
@@ -29,7 +31,7 @@ const dayText = (day: string, year: number) => periodDayText(day, year);
29
31
  * book's currency. JSON and CSV carry the same rows, the FX line and the
30
32
  * total as rows of their own, as `portfolio show` exports its cash and total.
31
33
  */
32
- export async function showPeriodPnl({ ctx, portfolio, name, tickers, currency, window, provider, fxHistory, quotes, futures, source, listingLabel, explain = false }: {
34
+ export async function showPeriodPnl({ ctx, portfolio, name, tickers, currency, window, provider, fxHistory, quotes, futures, source, listingLabel, explain = false, real = false, cpi = apiClient }: {
33
35
  ctx: CliCommandContext;
34
36
  portfolio: Portfolio;
35
37
  name: string;
@@ -45,10 +47,26 @@ export async function showPeriodPnl({ ctx, portfolio, name, tickers, currency, w
45
47
  listingLabel: (ticker: TickerRecord) => string;
46
48
  /** `--explain`: follow the report with what its terms mean (Contribution). */
47
49
  explain?: boolean;
50
+ /** `--real`: the total's return after the book currency's consumer prices too. */
51
+ real?: boolean;
52
+ /** Where the CPI is read; Gloom Cloud by default. */
53
+ cpi?: Parameters<typeof loadPeriodInflation>[2];
48
54
  }) {
49
55
  const explained = explain ? reportGlossary("PF", "Contribution") : [];
50
56
  const structured = ctx.cliOptions?.format != null && ctx.cliOptions.format !== "text";
51
- const result: LoadedPeriodPnl = await loadPeriodPnl({ tickers, portfolioId: portfolio.id, currency, window, provider, fxHistory, quotes, futures, refresh: !!ctx.cliOptions?.refresh });
57
+ const [result, inflation]: [LoadedPeriodPnl, Awaited<ReturnType<typeof loadPeriodInflation>> | null] = await Promise.all([
58
+ loadPeriodPnl({ tickers, portfolioId: portfolio.id, currency, window, provider, fxHistory, quotes, futures, refresh: !!ctx.cliOptions?.refresh }),
59
+ real ? loadPeriodInflation(currency, window, cpi) : null,
60
+ ]);
61
+ // The total's return after consumer prices: (1 + nominal) / (1 + inflation) - 1, on the same book value as Contribution.
62
+ const deflated = inflation && !("error" in inflation) && result.totalContribution != null
63
+ ? { ...inflation, nominal: result.totalContribution / 100, real: realReturn(result.totalContribution / 100, inflation.inflation) }
64
+ : null;
65
+ const realNote = !inflation ? null : "error" in inflation ? cliStyles.warning(`Real return: ${inflation.error}`)
66
+ : deflated && inflation.fromMonth === inflation.toMonth
67
+ ? `Real: ${signedPercent(deflated.real * 100)}, the total itself: no ${inflation.source.label} month after ${monthText(inflation.fromMonth)} is out by the end.`
68
+ : deflated ? `Real: ${signedPercent(deflated.real * 100)} after ${inflation.source.label} ${signedPercent(inflation.inflation * 100)}, ${monthText(inflation.fromMonth)} to ${monthText(inflation.toMonth)}${inflation.latestPublished ? " (the latest published)" : ""}; ${inflationMethodText(inflation)}. (1 + total) / (1 + inflation) - 1.`
69
+ : cliStyles.warning("Real return: the total has no return to deflate.");
52
70
  const bySymbol = new Map(tickers.map((ticker) => [ticker.metadata.ticker, ticker]));
53
71
  const label = (symbol: string) => {
54
72
  const ticker = bySymbol.get(symbol);
@@ -91,6 +109,13 @@ export async function showPeriodPnl({ ctx, portfolio, name, tickers, currency, w
91
109
  complete: result.unpriced.length === 0, unpricedSymbols: result.unpriced, unpriced: result.unpricedReasons, failures: result.failures,
92
110
  boughtInWindowSymbols: result.boughtInWindow, latestPriceAt: result.latestPriceAt == null ? null : new Date(result.latestPriceAt).toISOString(),
93
111
  ...(explain ? { glossary: explained.map(({ term, definition }) => ({ term, definition })) } : {}),
112
+ ...(inflation ? { real: "error" in inflation ? { error: inflation.error } : {
113
+ cpi: inflation.source.label, publisher: inflation.source.publisher, method: inflationMethodText(inflation),
114
+ fromMonth: inflation.fromMonth, toMonth: inflation.toMonth, latestPublished: inflation.latestPublished,
115
+ inflationPercent: inflation.inflation * 100, nominalPercent: deflated ? deflated.nominal * 100 : null, realPercent: deflated ? deflated.real * 100 : null,
116
+ // The published values it was read from, as the source gives them: levels, or changes in percent.
117
+ readings: inflation.readings,
118
+ } } : {}),
94
119
  method: "Each holding's price move times the units held now (contracts times their size for a future), converted at the end's FX rate; the FX line is each holding's start value times its currency's move. Contribution divides by the book's value at the start, gross when it holds a short.",
95
120
  }, freshness }, { rows: (rows) => [...(rows as Record<string, unknown>[]), ...extraRows] });
96
121
  return;
@@ -144,6 +169,7 @@ export async function showPeriodPnl({ ctx, portfolio, name, tickers, currency, w
144
169
  };
145
170
  if (fxRows.length) notes.push(`FX: ${[...new Set(fxRows.map(rateText))].join("; ")}. P&L converts at the end's rate; the FX line is the currency's move on the start value.`);
146
171
  if (contributionNote) notes.push(contributionNote);
172
+ if (realNote) notes.push(realNote);
147
173
  const unpricedText = periodUnpricedText(result, label);
148
174
  if (unpricedText) notes.push(cliStyles.warning(unpricedText));
149
175
  const boughtText = periodBoughtText(result, label);
@@ -973,7 +973,7 @@ export const portfolioCliCommand: CliCommandDef = {
973
973
  usage: [
974
974
  "portfolio [list]",
975
975
  "portfolio show <name> [--close] [--explain] [--drip [--years 1-5] [--withholding <pct>]]",
976
- "portfolio show <name> --from <date> [--to <date>]",
976
+ "portfolio show <name> --from <date> [--to <date>] [--real]",
977
977
  "portfolio create <name> [--currency <code>]",
978
978
  "portfolio delete <name>",
979
979
  "portfolio add <portfolio> <symbols...> [--file <path>]",
@@ -993,6 +993,7 @@ export const portfolioCliCommand: CliCommandDef = {
993
993
  { flags: "--close", description: "show: value the book at the regular close (futures at the settlement), not the latest print" },
994
994
  { flags: "--from <date>", description: "show: P&L and contribution by position from the close before this date (a year or a date)" },
995
995
  { flags: "--to <date>", description: "show --from: to the last close on or before this date (default today)" },
996
+ { flags: "--real", description: "show --from: the total's return after the portfolio currency's consumer prices too (USD and TRY), and the CPI months it used" },
996
997
  { flags: "--drip", description: "show: project the shares and income reinvested dividends add, year by year" },
997
998
  { flags: "--years <1-5>", description: `show --drip: how many years to project (default ${DRIP_DEFAULT_YEARS})` },
998
999
  { flags: "--withholding <pct>", description: "show --drip: tax withheld from each dividend, in percent (default 0)" },
@@ -1055,13 +1056,16 @@ export const portfolioCliCommand: CliCommandDef = {
1055
1056
  const hasWithholding = args.some((arg) => arg === "--withholding" || arg.startsWith("--withholding="));
1056
1057
  const yearsText = hasYears ? takeOption(args, "--years") ?? "" : undefined;
1057
1058
  const withholdingText = hasWithholding ? takeOption(args, "--withholding") ?? "" : undefined;
1059
+ const real = takeFlag(args, "--real");
1058
1060
  const hasFrom = args.some((arg) => arg === "--from" || arg.startsWith("--from="));
1059
1061
  const hasTo = args.some((arg) => arg === "--to" || arg.startsWith("--to="));
1060
1062
  const fromText = hasFrom ? takeOption(args, "--from") ?? "" : undefined;
1061
1063
  const toText = hasTo ? takeOption(args, "--to") ?? "" : undefined;
1062
1064
  // A bare name shows the portfolio, as `show` does.
1063
1065
  const shows = action === "show" || (action != null && !KNOWN_ACTIONS.has(action));
1064
- const periodUsage = "Usage: gloom portfolio show <name> --from <date> [--to <date>]";
1066
+ const periodUsage = "Usage: gloom portfolio show <name> --from <date> [--to <date>] [--real]";
1067
+ if (real && !shows) ctx.fail(`--real is an option of portfolio show --from, not portfolio ${action ?? "list"}.`, periodUsage);
1068
+ if (real && !hasFrom) ctx.fail("--real deflates the return between two dates by consumer prices; add --from <date>.", periodUsage);
1065
1069
  if ((hasFrom || hasTo) && !shows) ctx.fail(`${hasFrom ? "--from" : "--to"} is an option of portfolio show, not portfolio ${action ?? "list"}.`, periodUsage);
1066
1070
  let period: PriceWindow | undefined;
1067
1071
  try {
@@ -1121,7 +1125,7 @@ export const portfolioCliCommand: CliCommandDef = {
1121
1125
  if (action === "show") {
1122
1126
  const name = args.slice(1).join(" ");
1123
1127
  if (!name) ctx.fail("Usage: gloom portfolio show <name> [--close] [--explain] [--drip] [--from <date> [--to <date>]]");
1124
- await showCollection(name, ctx, { explain, basis, drip, ...(period ? { period } : {}) });
1128
+ await showCollection(name, ctx, { explain, basis, drip, ...(period ? { period } : {}), ...(real ? { real } : {}) });
1125
1129
  return;
1126
1130
  }
1127
1131