@get-asset/sdk

CashflowReport

Headless compound that fetches a cashflow report for a single fiscal year 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: year → 1 column, quarter → 4 columns (Q1-Q4), month → 12 columns (Jan-Dec).

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
`year`	`number`	—	Override the AssetProvider's year. The report is always scoped to a single fiscal year.
`month`	`number \| null`	—	Override the AssetProvider's month (1-12). When set, the report locks to that single month — breakdown is forced to "month" and consumers should disable other breakdowns in their UI. null / omit to inherit.
`defaultBreakdown`	`"month" \| "quarter" \| "year"`	—	Initial period breakdown. Defaults to "year". year → 1 column, quarter → 4 columns, month → 12 columns. Ignored when month is locked. 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.
`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, Quarter and Year carry 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).

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-{year}-{breakdown}.xlsx. No-op when records / state overrides are active.

Hooks

Part	Description
`useCashflowReport()`	Hook returning breakdown, setBreakdown, monthLocked, periods, lines, hasData, loading, error, retry, download. monthLocked is true when a specific month is selected — setBreakdown is a no-op while it is, and consumers should disable Quarter / Year in their UI. 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 }).