useCapxulAccountLifecycle

Query hook for post-sign-in account setup state — loading, settingUp, ready, or failed — with a built-in retry.

Reads the account lane — the setup that runs after sign-in to get the user's personal Account ready — as a small state machine: loading → settingUp → ready (or failed). It self-polls while setup is in flight and exposes a retry for the failed state. See the account lane concept page; the money itself is read with useCapxulAccountBalance.

Import

import { useCapxulAccountLifecycle } from "@capxul/sdk-react";

Usage

"use client";

import { useCapxulAccountLifecycle } from "@capxul/sdk-react";

function ProvisioningScreen({ onReady }: { onReady: () => void }) {
  const { lifecycle, isSettingUp, error, retry, isRetrying } =
    useCapxulAccountLifecycle();

  if (lifecycle.status === "ready") {
    onReady();
    return null;
  }

  if (lifecycle.status === "failed") {
    return (
      <section>
        <p>{error?.message ?? "Account setup failed."}</p>
        <button type="button" onClick={() => retry()} disabled={isRetrying}>
          {isRetrying ? "Retrying…" : "Try again"}
        </button>
      </section>
    );
  }

  return (
    <section>
      <h2>Setting up your account…</h2>
      {isSettingUp ? <p>Step: {lifecycle.step}</p> : <p>Preparing…</p>}
    </section>
  );
}

The lane starts automatically after a successful useCapxulVerifyOtp when the provider's requirement is "counterfactual" or "deployed". With the default requirement ("none", auth-only apps) the lane does not run and the lifecycle stays out of the way. While the status is loading or settingUp, the hook refetches every 2 seconds and stops on ready or failed.

Parameters

None.

Return type

import { type UseCapxulAccountLifecycleReturn } from "@capxul/sdk-react";

Unlike most query hooks, this one does not return a raw UseQueryResult — it returns a shaped object that merges the lifecycle query with the retry mutation:

Field	Type	Description
`lifecycle`	`AccountLifecycle`	The current lifecycle snapshot (see below). Never `undefined` — it reads as `{ status: "loading" }` before the first fetch.
`isSettingUp`	`boolean`	`true` while `lifecycle.status === "settingUp"`.
`error`	`CapxulError \| null`	The failure: the `failed` lifecycle's error, or the query's own fetch error.
`isLoading`	`boolean`	`true` during the first fetch.
`isFetching`	`boolean`	`true` whenever a fetch (including a poll) is in flight.
`isError`	`boolean`	`true` when the lifecycle read itself failed.
`retry`	`() => Promise<AccountLifecycle>`	Resume setup after `failed`; resolves with the updated snapshot.
`isRetrying`	`boolean`	`true` while the retry is in flight.

AccountLifecycle is a discriminated union on status:

`status`	Extra fields	Meaning
`"loading"`	—	Not known yet (also shown while signed out).
`"settingUp"`	`step`	Setup in flight. `step` is one of `"connecting"`, `"confirmingIdentity"`, `"registering"`, `"activating"`.
`"ready"`	`accountId`, `canTransact`	The Account exists. `canTransact` is `true` once the account is fully activated for money movement.
`"failed"`	`at`, `error`	Setup stopped at step `at` with a `CapxulError`. Offer `retry`.

If the lifecycle read itself fails while still loading, the hook coerces lifecycle to { status: "failed", at: "connecting", error } so your UI has one failure path to handle.

Query key

["capxul", "accountLifecycle"] — invalidated (background refetch) by useCapxulVerifyOtp, by a successful retry, and by the onboarding mutations (useCapxulCompletePersonalOnboarding, useCapxulCompleteOrganizationOnboarding); reset by useCapxulSignOut.

Errors

Both the query and the retry surface failures as a CapxulError — on the hook's error field, or thrown from retry().

Client method

This hook wraps client.account.getLifecycle() for the read and client.account.retrySetup() for retry on the core SDK.