@get-asset/sdk

CashflowSummaryCard

Headless compound that fetches the cash-flow report for a single fiscal year, broken down by month, and exposes per-month money in and money out. It sums each month's gross inflows (positive movements) and outflows (negative movements) across the report's flow sections — excluding the starting / ending balances and the net-change line. Each value is also available as a 0–1 ratio against a shared scale, so a diverging bar chart can render inflows upward and outflows downward from a common $0 axis. It also exposes the year's net cashflow, money in and money outtotals for the header. The chart always shows 12 months; the AssetProvider's month is ignored.

Anatomy

Import the primitive and compose the parts you need.

<CashflowSummaryCard.Root year={2026}>
  <CashflowSummaryCard.Net />
  <CashflowSummaryCard.TotalIn />
  <CashflowSummaryCard.TotalOut />
  <CashflowSummaryCard.Success>
    <CashflowSummaryCard.Months>
      <CashflowSummaryCard.Month />
      <CashflowSummaryCard.MoneyIn />
      <CashflowSummaryCard.MoneyInBar />
      <CashflowSummaryCard.MoneyOut />
      <CashflowSummaryCard.MoneyOutBar />
    </CashflowSummaryCard.Months>
  </CashflowSummaryCard.Success>
  <CashflowSummaryCard.Loading>…</CashflowSummaryCard.Loading>
  <CashflowSummaryCard.Empty>No data yet.</CashflowSummaryCard.Empty>
</CashflowSummaryCard.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 chart always shows 12 months for the year (the provider's month is ignored).
`months`	`CashflowSummaryMonthOverride[]`	—	Override fetched data. Each entry: { month, moneyIn, moneyOut } (moneyOut positive). Skips the API call.
`scale`	`number`	—	Override the +/- bound for the bar chart. Defaults to a 'nice' value derived from the largest in/out figure.
`state`	`"loading" \| "error" \| "empty"`	—	Force a specific state for testing.
`locked`	`boolean`	—	Gate the report for an unentitled viewer. Activates the Locked state and skips the API fetch. See /docs/sdk/locked-upsell.
`upsell`	`{ title?, description?, ctaLabel?, onUpgrade? }`	—	Locked-state copy + upgrade handler; merged field-by-field over the card's default copy, then the generic fallback.
`children`required	`ReactNode`	—	Compound parts.

Parts

Container

Always rendered. Provides data and context to its children.

Part	Description
`CashflowSummaryCard.Root`	Fetches the cash-flow report and provides per-month money in / out, the year's totals, and a shared scale.
`CashflowSummaryCard.Period` `asChild?, format?`	Renders the resolved year (the card is year-only).

Header totals

Year-level figures for the card header.

Part	Description
`CashflowSummaryCard.Net` `asChild?, format?`	Net cashflow for the year (money in − money out).
`CashflowSummaryCard.TotalIn` `asChild?, format?`	Sum of every month's money in.
`CashflowSummaryCard.TotalOut` `asChild?, format?`	Sum of every month's money out (positive magnitude — format it as an outflow).

Success

Renders when the year has cashflow data.

Part	Description
`CashflowSummaryCard.Success`	State wrapper. Compose the chart inside.
`CashflowSummaryCard.Months`	Iterates the 12 months, setting a per-month context.
`CashflowSummaryCard.Month` `asChild?`	Renders the month number (1-12) for the current month.
`CashflowSummaryCard.MoneyIn / MoneyOut` `asChild?`	Renders the raw cash-in / cash-out amount for the current month.
`CashflowSummaryCard.MoneyInBar / MoneyOutBar` `asChild?`	A bar element whose height is the value's ratio of the scale (data-ratio attribute). MoneyIn renders upward, MoneyOut downward.

Loading

Part	Description
`CashflowSummaryCard.Loading`	State wrapper. Render a skeleton / spinner inside.

Empty

Part	Description
`CashflowSummaryCard.Empty`	State wrapper. Renders when the year has no cashflow movements.

Error

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

Locked

Renders when `locked` is set — the viewer isn't entitled to the report. Mutually exclusive with the other states, and no data is fetched. See the Locked / upsell guide for composing the teaser + upgrade UI.

Part	Description
`CashflowSummaryCard.Locked`	State wrapper. Compose the upgrade / upsell UI inside — see LockedUpsell.

Unlocked

Renders whenever the card is NOT locked — the inverse of Locked.

Part	Description
`CashflowSummaryCard.Unlocked`	State wrapper. Useful for gating extras (like the insights panel) that should also disappear while locked.

Hooks

Part	Description
`useCashflowSummaryCard()`	Hook returning year, months, scale, totalIn, totalOut, net, hasData, loading, error, locked, retry.
`useCashflowSummaryMonth()`	Hook used inside a Months iteration; returns the current month's { month, moneyIn, moneyOut, inRatio, outRatio }.