useSession - Calm

useSession({ address }) calls the active modality’s session-creation callback on mount and on a 50-minute interval, keeping the 1-hour calm_session cookie fresh ahead of expiry. The same hook exposes a clear() method that deletes the server-side calm_session cookie and drops the cached session.

Import

import { useSession } from "@calm-xyz/react";

Usage

app/page.tsx

"use client";
import { useCalm, useSession } from "@calm-xyz/react";

function SignedIn() {
  const { address } = useCalm();
  const { data, isPending, error } = useSession({ address });
  if (isPending) return <div>Loading…</div>;
  if (error) return <div>Auth error: {error.message}</div>;
  return <div>Signed in as {data?.wallet}</div>;
}

Parameters

import { type UseSessionParameters } from "@calm-xyz/react";

`address`

string The wallet address the session is bound to. Must match the wallet the active provider is configured for.

Return Type

import { type UseSessionReturnType } from "@calm-xyz/react";

UseQueryResult<SessionResponse, ApiError> from @tanstack/react-query augmented with a clear() method.

`data`

SessionResponse | undefined The session-creation response: { wallet, expires_at }. wallet is lowercased and 0x-prefixed; expires_at is the ISO timestamp the calm_session cookie expires at (1 hour from creation).

`isPending`

boolean true until the first session-creation call resolves. Use to gate loading UI.

`error`

ApiError | null The structured error from the modality’s session creation. See Errors for the full code table.

`status`

"pending" | "error" | "success" The react-query status.

`refetch`

() => Promise<UseQueryResult<SessionResponse, ApiError>> Manually trigger a session refresh.

`clear`

() => Promise<void> Clear the server-side session cookie and drop the cached useSession entry so subsequent reads don’t show stale data. See Sign out. See the @tanstack/react-query useQuery docs for the full set of fields on the return type.

Sign out

The SDK sits downstream of your wallet / identity stack — sign out at that layer first (e.g. usePrivy().logout(), useDisconnect() from wagmi, handleLogOut() from Dynamic). The provider observes the address going away and unmounts naturally. To also clear the server-side calm_session cookie immediately (rather than waiting for the 1-hour TTL):

"use client";
import { useCallback } from "react";
import { useCalm, useSession } from "@calm-xyz/react";
import { useDisconnect } from "wagmi";

function SignOut() {
  const { address } = useCalm();
  const { clear } = useSession({ address });
  const { disconnect } = useDisconnect();
  const handle = useCallback(async () => {
    await clear();
    disconnect();
  }, [clear, disconnect]);
  return <button onClick={handle}>Sign out</button>;
}

​Import

​Usage

​Parameters

​address

​Return Type

​data

​isPending

​error

​status

​refetch

​clear

​Sign out