useCapxulSession

Query hook for the signed-in session — Session when signed in, null when signed out.

Reads the current session. data is the Session when someone is signed in and null when no one is — the primary signal for gating signed-in UI. Pair it with useCapxulSignIn / useCapxulVerifyOtp to establish a session and useCapxulSignOut to end it.

Import

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

Usage

"use client";

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

function AccountHeader() {
  const session = useCapxulSession();

  if (session.isLoading) return <p>Loading…</p>;
  if (session.error) return <p>{session.error.message}</p>;

  if (!session.data) return <a href="/login">Sign in</a>;

  return (
    <div>
      <p>Signed in as {session.data.email}</p>
      <p>User id: {session.data.authUserId}</p>
    </div>
  );
}

Parameters

None. The query is gated automatically: it stays pending until the provider finishes bootstrapping, with no manual enabled wiring needed.

Return type

import { type UseCapxulSessionReturn } from "@capxul/sdk-react";
// UseQueryResult<Session | null, CapxulError>

data is a Session — the authUserId, the signed-in email, the session token, and expiresAt (epoch milliseconds) — or null when no one is signed in. null is a successful result, not an error: check session.data, not session.isError, to branch on auth state.

The hook returns TanStack Query's UseQueryResult. The most-used fields:

Field	Description
`data`	The query data (typed per hook, shown above). `undefined` until the first success.
`error`	A `CapxulError` when the last fetch failed, otherwise `null`.
`status`	`'pending'` \| `'error'` \| `'success'`.
`isLoading`	`true` during the first fetch (no data yet).
`isFetching`	`true` whenever a fetch is in flight, including background refetches.
`refetch`	Manually refetch the query.

Capxul query hooks stay pending until the provider finishes bootstrapping — you do not need to gate them on useCapxul() yourself. The full field list is in the TanStack Query useQuery reference; see also the TanStack Query integration guide.

Query key

["capxul", "session"] — invalidated (background refetch) by useCapxulVerifyOtp on successful verification, and reset (dropped immediately) by useCapxulSignOut.

Client method

This hook wraps client.auth.getSession() on the core SDK.