@get-asset/sdk

Cashflow Card

Headless compound rendering starting and ending bank balances per period, with the net change in cash for each. Periods come from the range the card resolves — the AssetProvider's shared range (driven by the DatePicker) unless dateFrom / dateTo pin it. A range that is exactly one month, quarter or year renders two periods, that period and the one before it; any other range renders the calendar months it overlaps, with the figures clipped to the range.

Anatomy

Import the primitive and compose the parts you need.

<CashflowCard.Root>
  <CashflowCard.Success>
    <CashflowCard.Periods>
      {/* one render per period on screen */}
      <CashflowCard.PeriodLabel />
      <CashflowCard.StartingBalance />
      <CashflowCard.EndingBalance />
      <CashflowCard.Tone>
        <CashflowCard.ChangeInCash />
      </CashflowCard.Tone>
    </CashflowCard.Periods>
  </CashflowCard.Success>
  <CashflowCard.Loading>…</CashflowCard.Loading>
  <CashflowCard.Empty>No cashflow data yet.</CashflowCard.Empty>
</CashflowCard.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 card from the AssetProvider's shared range entirely; must be paired with dateTo (passing one side alone throws). Use periodDateRange to derive the pair from a month, quarter or 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.
`periods`	`CashflowPeriodOverride[]`	—	Override fetched data — one entry per period on screen. Each entry: { start, startingBalance, endingBalance, changeInCash? }.
`state`	`"loading" \| "error"`	—	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
`CashflowCard.Root`	Fetches period data and provides context.

Success

Renders when period data is available.

Part	Description
`CashflowCard.Success`	State wrapper. Compose the period table inside.
`CashflowCard.Periods`	Renders its children once per period, within a per-period context.
`CashflowCard.PeriodLabel` `asChild?, format?`	Renders the current period's label (default: "Apr 2026" for month, "Q2 2026" for quarter, "2026" for year). Pass format(start, granularity) to override.
`CashflowCard.StartingBalance` `asChild?`	Starting balance for the current period.
`CashflowCard.EndingBalance` `asChild?`	Ending balance for the current period.
`CashflowCard.ChangeInCash` `asChild?`	Net change in cash for the current period.
`CashflowCard.Tone` `asChild?`	Wrapper that adds data-tone to its child based on the sign of the change.

Loading

Renders while the fetch is in flight.

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

Empty

Renders when the fetch succeeded but returned no periods.

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

Error

Renders when the fetch fails.

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

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
`CashflowCard.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
`CashflowCard.Unlocked`	State wrapper. Renders children whenever the card isn't locked.

Hooks

Part	Description
`useCashflowCard()`	Hook returning data, granularity, periodStarts (the periods the card resolved, known before the data lands), loading, error, locked, retry.
`useCashflowPeriod()`	Hook for components inside a Periods iteration; returns the active period.