Accounts List

Reconciliation

The compound has a second job beyond listing accounts: getting a business’s bank statements checked against its books. It stays one compound because it is the same data — the accounts the user already sees, annotated with what each one needs — and it is always on, so every account row carries its statement state.

How the flow is driven

A background job compares each account’s balance against the books. When they disagree for long enough it raises a request_statement task, and that task is the only signal this component reads — there is no reconciliation resource.

1.  A background job compares the account balance against the books.
2.  They disagree for long enough → it raises a `request_statement` task
    carrying `external_account_id` and `month`.
3.  The account row reads "N statements needed".
4.  Opening the row names the months wanted and offers one dropzone. A file is
    tagged with `task_id` only when a single request is open — with several
    there is no telling which file answers which, so the backend reads the
    period off the statement.
5.  The task stays open until the statement has been read, so the row keeps its
    place and shows the progress. The document is polled every 3s. The task
    clears a beat after the document settles, so the tasks are polled too while
    a row reads `ready` — that is what finally clears it.
6.  Once nothing is being asked for and nothing is still being read, Review opens: the bank balance against
    the book balance with the gap between them, over everything posted since
    `last_balanced_at`. Deleting a row refetches both the transactions and the
    ledger, so the summary moves with it.

The Statements column is derived from those open requests:

• disconnected or paused → not_checked— the balance isn’t being compared to anything, so a statement is never asked for. The label is “Not checked”, but the styled column renders nothing for it: the Status column beside it already says Disconnected or Paused.
• one or more open requests → Not reconciled since <date>, taken from the oldest request’s created_at. How long it has been out is what tells the user whether this is urgent — a file count doesn’t. The raw value is on requestedAt so the styled layer formats it.
• otherwise → nothing outstanding. lastBalancedAtcarries the account’s last_balanced_at so the styled column can say Last balanced on Jun 30th— a date is what makes the reassurance worth anything, and an account that has never balanced shows nothing at all rather than claiming to be up to date. The default label stays date-free, since formatting isn’t the headless layer’s job.

The row states the action needed rather than a reconciliation status, because the user is not expected to know the word. Nothing keys off last_statement_end_date: a statement having arrived once says nothing about whether one is wanted now.

The review fetches; it does not take a period

Review covers everything posted to the account since last_balanced_at — the window the background job found the discrepancy in. That comes off the account itself, so no statement period has to be inferred. When the account has never balanced, the start bound is omitted and the review covers everything.

Deleting is irreversible, so RemoveTransaction only arms a per-row confirmation — ConfirmRemove is what calls the API. A successful delete invalidates the transactions and accounts queries, since the balance may now agree.

Editing is partly unbacked. TransactionUpdateItem carries only type, reviewed, status, tags and line_items— nothing that changes a posted transaction’s amount, date or description. TransactionField therefore holds those corrections locally and reports them through onTransactionUpdate, so a host can persist them its own way (typically delete + re-create via POST /transactions, which does accept all three). Until an endpoint takes them, a reload loses them.

Anatomy

<AccountsList.Root>
  <AccountsList.Success>

    {/* 1 — the accounts table, plus a Statements column */}
    <AccountsList.AccountsScreen>
      <AccountsList.Groups>
        <AccountsList.Accounts>
          <AccountsList.OpenAccount>
            <AccountsList.AccountName />
            <AccountsList.Statements />   {/* "2 statements needed" */}
            <AccountsList.Balance />
          </AccountsList.OpenAccount>
        </AccountsList.Accounts>
      </AccountsList.Groups>
    </AccountsList.AccountsScreen>

    {/* 2 — one account's statements, and what has been asked for */}
    <AccountsList.StatementsScreen>
      <AccountsList.Back>←</AccountsList.Back>
      <AccountsList.OpenAccountName />

      {/* the banner: either the months wanted, or that it's balanced */}
      <AccountsList.StatementRequested>
        <AccountsList.Requests>
          <AccountsList.RequestMonth />     {/* "2026-05" */}
          <AccountsList.RequestedAt />      {/* when we asked */}
          <AccountsList.RequestFileName />  {/* once something is uploaded */}

          <AccountsList.RequestIs status={["needed", "failed"]}>
            <AccountsList.UploadStatement />
          </AccountsList.RequestIs>
          <AccountsList.RequestIs status={["uploading", "processing"]}>
            <AccountsList.RequestStatus />  {/* polls until read */}
          </AccountsList.RequestIs>
          <AccountsList.RequestIs status="failed">
            <AccountsList.RequestError />
          </AccountsList.RequestIs>
        </AccountsList.Requests>
      </AccountsList.StatementRequested>
      <AccountsList.NoStatementRequested>
        <AccountsList.ReviewedSince />   {/* "Last balanced on Jun 30th" */}
      </AccountsList.NoStatementRequested>

      {/* everything held for the account — an upload lands here and polls
          itself from Reading to Processed */}
      <AccountsList.HasStatements>
        <AccountsList.StatementList>
          <AccountsList.StatementName />
          <AccountsList.StatementUploadedAt />
          <AccountsList.StatementDocumentStatus />
          <AccountsList.StatementIs status="failed">
            <AccountsList.StatementError />
          </AccountsList.StatementIs>
        </AccountsList.StatementList>
      </AccountsList.HasStatements>

      {/* hidden until nothing is outstanding and nothing is still being read */}
      <AccountsList.NotReadyToReview>Still waiting…</AccountsList.NotReadyToReview>
      <AccountsList.Review>Review transactions</AccountsList.Review>
    </AccountsList.StatementsScreen>

    {/* 3 — everything posted since the account last balanced */}
    <AccountsList.ReviewScreen>
      <AccountsList.Back>←</AccountsList.Back>
      <AccountsList.ReviewedSince />

      {/* what the user is here to fix */}
      <AccountsList.HasBalances>
        <AccountsList.OpeningBalanceField />   {/* editable */}
        <AccountsList.TransactionsBalance />
        <AccountsList.ClosingBalance />
        <AccountsList.BankBalance />
        <AccountsList.Difference />            {/* the target: zero */}
      </AccountsList.HasBalances>

      <AccountsList.ReviewLoading>…</AccountsList.ReviewLoading>
      <AccountsList.ReviewError>
        <AccountsList.ReviewErrorMessage />
        <AccountsList.ReviewRetry>Try again</AccountsList.ReviewRetry>
      </AccountsList.ReviewError>
      <AccountsList.NoTransactions>Nothing has posted.</AccountsList.NoTransactions>

      <AccountsList.HasTransactions>
        <AccountsList.Transactions>
          <AccountsList.Transaction>
            <AccountsList.TransactionDate />
            <AccountsList.TransactionDescription />

            {/* which statement produced the row, if any */}
            <AccountsList.FromDocument>
              <AccountsList.TransactionSource />
            </AccountsList.FromDocument>
            <AccountsList.NoDocument>No document</AccountsList.NoDocument>

            <AccountsList.TransactionAmount />
            <AccountsList.OpenAccountCurrency />
            <AccountsList.RemoveTransaction>Delete</AccountsList.RemoveTransaction>
          </AccountsList.Transaction>

          {/* deleting is irreversible, so it confirms in place */}
          <AccountsList.Confirming>
            <AccountsList.CancelRemove>Cancel</AccountsList.CancelRemove>
            <AccountsList.ConfirmRemove>Delete</AccountsList.ConfirmRemove>
          </AccountsList.Confirming>
        </AccountsList.Transactions>
        <AccountsList.HasMore>
          <AccountsList.LoadMore>Show more</AccountsList.LoadMore>
        </AccountsList.HasMore>
        <AccountsList.TransactionCount />
      </AccountsList.HasTransactions>
    </AccountsList.ReviewScreen>

  </AccountsList.Success>
</AccountsList.Root>

Scopes

Because reconciliation is always on, AccountsList.scopes includes the statement-request, document and transaction reads it needs. A token minted from an older, smaller set will 401 on the task fetch and the list will show its error state — regenerate delegated tokens from this array.