@get-asset/sdk

Cashflow Report

Headless compound that fetches a cashflow report over the reporting range — the provider's DatePicker-driven range unless dateFrom / dateTo detach it — and breaks it down by the chosen breakdown. The API returns one bucket per period; the compound zips those buckets into a single tree where each line carries an amounts array (one entry per period column). Iterate Periods for column headers and again inside each Line for per-period amounts. Breakdown is user-controlled state, exposed via useCashflowReport().setBreakdown: one column per year, quarter, or month the range covers. Columns stay calendar-aligned even when the range starts or ends mid-period (the API buckets by calendar period), while the request itself is clipped to the range, and columns that start after today are dropped.

Anatomy

Import the primitive and compose the parts you need.

<CashflowReport.Root defaultBreakdown="year">
  <CashflowReport.Success>
    <CashflowReport.Periods>
      <CashflowReport.PeriodLabel />
    </CashflowReport.Periods>
    <CashflowReport.Sections>
      <CashflowReport.Lines>
        <CashflowReport.Line>
          <CashflowReport.LineName />
          <CashflowReport.Periods>
            <CashflowReport.LineAmount />
          </CashflowReport.Periods>
        </CashflowReport.Line>
      </CashflowReport.Lines>
    </CashflowReport.Sections>
  </CashflowReport.Success>
  <CashflowReport.Loading>…</CashflowReport.Loading>
  <CashflowReport.Empty>No data yet.</CashflowReport.Empty>
</CashflowReport.Root>

Required scopes

The access token used by AssetProvider must include this scope for this primitive to fetch data successfully:

report:read

API reference

Root props

Prop	Type	Default	Description
`dateFrom`	`CalendarDateString`	—	Inclusive start (YYYY-MM-DD) of a fixed reporting range. Detaches the report from the provider's shared range entirely; must be paired with dateTo (passing one without the other throws). Use periodDateRange to derive the pair from a month/quarter/year. Omit both to follow the provider's DatePicker-driven range.
`dateTo`	`CalendarDateString`	—	Inclusive end (YYYY-MM-DD) of the fixed reporting range. Must be paired with dateFrom.
`defaultBreakdown`	`"month" \| "quarter" \| "year"`	—	Initial period breakdown. Defaults to "year". The report renders one column per year, quarter, or month the range covers. Ignored when the range is exactly one calendar month or quarter — the breakdown is then forced to match and setBreakdown is a no-op. Consumers can update at runtime via setBreakdown from the hook.
`records`	`ReportLine[]`	—	Override fetched data with a single snapshot — primarily for testing/storybook.
`state`	`"loading" \| "error" \| "empty"`	—	Force a specific state for testing.
`basis`	`"accrual" \| "modified_cash"`	—	Report on a specific accounting basis. Omit to inherit the AssetProvider's basis, which itself falls back to the Business's country — Canadian Businesses report on Accrual, everyone else on Cash.
`basisToggle`	`boolean`	—	Let the end user flip between Cash and Accrual. Off by default — BasisSelect renders nothing until it's set. Flipping the control moves every component that inherits the provider's basis, so it can't leave a screen half cash and half accrual.
`onLedgerSelect`	`(ledgerId: string) => void`	—	Called with a row's ledger id when the viewer picks it (click or keyboard). Each line surfaces it pre-bound as selectLedger on the line hook — present only when the row names a ledger — and the Line part renders such rows as interactive links. Group headings and calculated rows stay inert.
`children`required	`ReactNode`	—	Compound parts.

Parts

Container

Always rendered. Provides data and context to its children.

Part	Description
`CashflowReport.Root`	Fetches the multi-period cashflow report and provides context.

Breakdown selector

Headless primitives that wire a Select-shaped UI to the report's breakdown state — no hook plumbing required.

Part	Description
`CashflowReport.BreakdownSelect`	Wraps a single Select-Root-shaped child (e.g. Radix Select.Root) and merges value + onValueChange via React.cloneElement. The consumer keeps full control over trigger, content, and styling.
`CashflowReport.BreakdownItems`	Iterates the three breakdown options (Month / Quarter / Year), setting a per-option context that BreakdownItem reads. When the report is monthLocked (or quarterLocked), every other option carries disabled: true.
`CashflowReport.BreakdownItem` `asChild?`	Renders one option. Pair with asChild and a SelectItem-like child — the SDK injects value, disabled, and the option's label as the child's text.
`CashflowReport.BREAKDOWN_OPTIONS`	The raw [{value, label}, …] list, exported for consumers that want to render their own iteration.

Periods

Header / per-row period iteration.

Part	Description
`CashflowReport.Periods`	Iterates each period column. Sets a period context that PeriodLabel / LineAmount read from. Use it once for the column headers and once inside each row for amounts.
`CashflowReport.PeriodLabel` `asChild?`	Renders the current period's label (e.g. "Apr" for month, "Q2" for quarter, "2026" for year). Month and quarter labels carry a 2-digit year ("Apr 27") when the range spans more than one calendar year.

Success

Renders when records are available.

Part	Description
`CashflowReport.Success`	State wrapper. Compose the table inside.
`CashflowReport.Sections` `hide?: string[]`	Iterates each top-level row as a section. Empty sections (groups whose descendants have no entries / non-zero amounts, or calc leaves with no entries / zero amount) are filtered out. `hide` further filters top-level lines by name.
`CashflowReport.Lines`	Iterates the current section's lines. Must be used inside <Sections> (throws otherwise — use the useCashflowReport().lines hook for raw flat access). Group sections expand into heading → descendants → total; calc-leaf sections yield a single row. Each iteration sets the line context plus a role so <Line> emits the right data attribute.
`CashflowReport.Line` `asChild?`	Wrapper that adds data-depth, data-leaf, data-group, data-section, data-section-heading and data-section-total attributes based on the current line and (when inside Sections) its role. The same template renders headings, descendants and totals — CSS differentiates them by attribute.
`CashflowReport.LineName` `asChild?`	Renders the line name. On a section's total row this is auto-prefixed with "Total " (skipped if the section name already starts with "Total ").
`CashflowReport.LineAmount` `asChild?, format?`	Renders the line's amount for the current period (when used inside Periods) or the most recent period (when used outside). On group section heading rows, the rolled-up amount is hidden by default in the styled drop-in's CSS.

Loading

Renders while the fetch is in flight.

Part	Description
`CashflowReport.Loading`	State wrapper. Render any skeleton or placeholder UI inside.

Empty

Renders when the fetch returned no records.

Part	Description
`CashflowReport.Empty`	State wrapper. Render an empty-state message inside.

Error

Renders on fetch error.

Part	Description
`CashflowReport.Error`	State wrapper. Compose the error UI inside.
`CashflowReport.ErrorMessage` `asChild?`	Renders the error message string.
`CashflowReport.Retry` `asChild?`	Button that re-runs the fetch.

Download

Triggers an XLSX export of the report using the same query parameters that produced the on-screen view.

Part	Description
`CashflowReport.Download` `asChild?`	Button that calls the SDK's download action when clicked. Hits /reports/cash-flow with start_datetime, end_datetime and period (= breakdown) and saves the response as cashflow-{dateFrom}_{dateTo}-{breakdown}.xlsx. No-op when records / state overrides are active.

Hooks

Part	Description
`useCashflowReport()`	Hook returning breakdown, setBreakdown, monthLocked, quarterLocked, periods, start, end, lines, hasData, loading, error, retry, download. monthLocked is true when the resolved range is exactly one calendar month, quarterLocked when it is exactly one quarter — setBreakdown is a no-op while either is set, and consumers should disable the other options in their UI. start / end are the reporting range as Dates (end is exclusive). download() is a Promise<void> that triggers the XLSX export.
`useCashflowReportLine()`	Hook used inside a Lines iteration; returns the current line node (with amounts: number[]).
`useCashflowReportPeriod()`	Hook used inside a Periods iteration; returns the current period info.
`useCashflowSection()`	Hook used inside a Sections iteration; returns the current section ({ row, descendants }).