@get-asset/sdk

Balance Sheet Report

Headless compound that fetches a point-in-time balance sheet for a specific date — the last day of the range selected on AssetProvider unless an asOf is given — and exposes it as a flat list of lines with depth metadata. Subtotal rows include their nested totals; leaf rows expose the per-ledger amount.

Anatomy

Import the primitive and compose the parts you need.

<BalanceSheetReport.Root>
  <BalanceSheetReport.AsOf />
  <BalanceSheetReport.Success>
    <BalanceSheetReport.Sections>
      <BalanceSheetReport.Lines>
        <BalanceSheetReport.Line>
          <BalanceSheetReport.LineName />
          <BalanceSheetReport.LineAmount />
        </BalanceSheetReport.Line>
      </BalanceSheetReport.Lines>
    </BalanceSheetReport.Sections>
  </BalanceSheetReport.Success>
  <BalanceSheetReport.Loading>…</BalanceSheetReport.Loading>
  <BalanceSheetReport.Empty>No data yet.</BalanceSheetReport.Empty>
</BalanceSheetReport.Root>

Required scopes

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

report:read
business:read

API reference

Root props

Prop	Type	Default	Description
`asOf`	`Date \| string`	—	The point-in-time the report is taken at. Accepts a Date or any ISO-8601 string, and pins the report to that instant regardless of the provider's range. Omit it to take the report at the end of the range selected on the provider, which includes everything posted on its last day.
`records`	`ReportLine[]`	—	Override fetched data — pass the API tree as-is. Skips the API call.
`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 (see Accounting basis).
`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 (see Accounting basis).
`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
`BalanceSheetReport.Root`	Fetches the balance sheet and provides context.
`BalanceSheetReport.Basis` `asChild?`	Renders the active basis as text ("Accrual" / "Cash") and sets data-basis. Rendered whether or not the toggle is enabled.
`BalanceSheetReport.BasisSelect`	Wires basis state to a Select-Root-shaped child (injects value + onValueChange). Renders nothing unless basisToggle is enabled.
`BalanceSheetReport.BasisItems`	Iterates the Accrual / Cash options, providing per-option context.
`BalanceSheetReport.BasisItem` `asChild?`	Renders one basis option. Injects value and the option label.
`BalanceSheetReport.AsOf` `asChild?, format?`	Renders the resolved as-of date. Defaults to "Mon DD, YYYY". Pass format(date) to override.

Success

Renders when records are available.

Part	Description
`BalanceSheetReport.Success`	State wrapper. Compose the table inside.
`BalanceSheetReport.Sections`	Iterates each top-level section (Assets, Liabilities, Equity). Provides a section context for use inside <Lines>.
`BalanceSheetReport.Lines`	Iterates the current section's lines. Must be used inside <Sections> (throws otherwise — use the useBalanceSheetReport().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.
`BalanceSheetReport.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.
`BalanceSheetReport.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 ").
`BalanceSheetReport.LineAmount` `asChild?, format?`	Renders the line's total_amount. 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
`BalanceSheetReport.Loading`	State wrapper. Render any skeleton or placeholder UI inside.

Empty

Renders when the fetch returned no records.

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

Error

Renders on fetch error.

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

Download

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

Part	Description
`BalanceSheetReport.Download` `asChild?`	Button that calls the SDK's download action when clicked. Hits /reports/balance-sheet on the same as-of point the on-screen report used and saves the response as balance-sheet-{YYYY-MM-DD}.xlsx. No-op when records / state overrides are active.

Hooks

Part	Description
`useBalanceSheetReport()`	Hook returning lines, asOf, hasData, basis, setBasis, loading, error, retry, download. download() is a Promise<void> that triggers the XLSX export on the same as-of date and basis the report is displaying.
`useBalanceSheetReportLine()`	Hook used inside a Lines iteration; returns the current line node.
`useBalanceSheetSection()`	Hook used inside a Sections iteration; returns the current section ({ section, descendants }).

Accounting basis

BalanceSheetReport reports on one of two accounting bases: Accrual (accrual on the wire), which counts invoices and bills when they are issued, or Cash (modified_cash), which counts them when the money moves. Cashflow components take no basis — cashflow is a cash concept.

The basis is resolved per component, first match winning:

the report's own basis prop;
the provider's basis — defaultBasis on AssetProvider, or whatever the toggle was last flipped to;
the Business's country — Canadian Businesses report on Accrual, everyone else on Cash.

Only the last step costs a request — a Business read, which is why every basis-aware component's scopes includes business:read — and it is serial: the report holds its own fetch until the Business answers. One request is shared across every basis-aware component on the screen, but pass defaultBasis on AssetProvider when you already know the basis and skip it entirely. If the lookup fails the report falls back to Cash and stays there — retry() re-runs the report query, not the basis lookup.

basisToggle is off by default: BalanceSheetReport.BasisSelect renders nothing and the report reports on its resolved basis. Turn it on and flipping the control moves every basis-aware component under the provider with it, so the toggle can never leave a screen half cash and half accrual. A component pinned with its own basis prop is the exception — it keeps the basis you gave it and renders no toggle of its own, which is how you show both bases side by side on purpose.

BalanceSheetReport.Basisrenders the active basis as text ("Accrual" / "Cash") and sets data-basis, whether or not the toggle is enabled — use it to label the figures even on a screen that offers no control.

The XLSX export sends the basis currently on screen, so a downloaded file always matches what the viewer was looking at.