useCapxulClientOrNull

Returns the bootstrapped CapxulClient from the surrounding CapxulProvider, or null while the bootstrap is still in flight (or has failed).

This is the advanced escape hatch: use it when you need a client method that has no dedicated hook yet, and wrap the call in your own TanStack useQuery or useMutation. The built-in query hooks use it internally — that is how they sit in isPending (as a disabled query) until the client resolves instead of throwing during bootstrap. If a hook exists for what you need, use the hook.

Import

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

Usage

Pair the client with your own useQuery under a ["capxul", ...] key, gate on client !== null, and unwrap the CapxulResult yourself:

"use client";

import { useQuery } from "@tanstack/react-query";
import { useCapxulClientOrNull } from "@capxul/sdk-react";

function RequestPreview({ linkToken }: { linkToken: string }) {
  const client = useCapxulClientOrNull();

  const request = useQuery({
    queryKey: ["capxul", "requestByLink", linkToken],
    enabled: client !== null,
    queryFn: async () => {
      if (client === null) throw new Error("unreachable: query is disabled");
      const result = await client.paymentRequests.getByLink(linkToken);
      if (!result.ok) throw result.error;
      return result.value;
    },
  });

  if (request.isPending) return <p>Loading…</p>;
  if (request.error) return <p>{request.error.message}</p>;
  if (request.data === null) return <p>No such request.</p>;

  return (
    <p>
      {request.data.reference}: {request.data.amount.value}{" "}
      {request.data.amount.currency} ({request.data.status})
    </p>
  );
}

The pieces that make this behave like a built-in hook:

• enabled: client !== null — the query stays pending during bootstrap and wakes up on its own once the client resolves, exactly like the shipped hooks.
• ["capxul", ...] query key — the provider clears capxul-scoped queries when the client changes (re-bootstrap, retry). Keying your custom queries under "capxul" opts them into that hygiene so no data leaks across clients.
• Unwrapping — client methods return a CapxulResult; throw result.error (a CapxulError) so it lands on the query's error field.

See Using the raw client for the full pattern, including mutations and cache invalidation.

Parameters

The hook takes no parameters.

Return type

import type { CapxulClient } from "@capxul/sdk";
// CapxulClient | null

null while the provider is bootstrapping and when the bootstrap has failed (check useCapxul to tell those apart). In injected client mode the injected client is returned from the first render.

The hook never throws for "not ready" — it returns null instead.

Errors

Calling the hook outside a CapxulProvider throws — missing provider is a wiring bug, not a pending state.