CapxulClient

@capxul/sdk exposes one factory: createCapxulClient. It resolves the platform bootstrap for your publishable key and returns a CapxulClient — imperative method bundles covering auth, accounts, payments, receivables, organizations, payroll, and onboarding. Every React hook wraps one of these methods; in a React app, CapxulProvider creates and owns the client for you.

Use the client directly when there is no React tree — a script, a server, an agent backend. See Node & servers.

Create a client

import { createCapxulClient } from "@capxul/sdk";

const result = await createCapxulClient({
  publishableKey: process.env.CAPXUL_PUBLISHABLE_KEY!,
  requirement: "counterfactual",
});

if (!result.ok) {
  throw result.error;
}

const client = result.value;
await client.auth.signIn({ email: "user@example.com" });

createCapxulClient returns Promise<CapxulResult<CapxulClient>> — a failed bootstrap comes back as an error value, not an exception.

Parameters

The factory accepts a single CapxulClientInput object with exactly three fields. The SDK resolves everything else — the bootstrap host, the runtime, request timeouts, and session caching — internally.

publishableKey

string — required.

The key that identifies your app to the platform. Create sandbox keys with the @capxul/sandbox CLI.

requirement

"none" | "counterfactual" | "deployed" — optional, defaults to "none".

The account-readiness target the SDK works toward after sign-in. With "none" no account setup runs at all; the other two values start the account lane automatically once a user signs in. Full semantics are on Node & servers.

signer

CapxulSigner — optional.

The consumer-held signing key for requirement: "deployed". Required outside the browser; browser apps omit it and the SDK provisions one automatically.

Results, not exceptions

Every method on every bundle returns Promise<CapxulResult<T>>:

import type { CapxulResult } from "@capxul/sdk";

type CapxulResult<T> =
  | { readonly ok: true; readonly value: T }
  | { readonly ok: false; readonly error: CapxulError };

Check ok to narrow the result; on failure, error is always a structured CapxulError. The React hooks unwrap this shape into TanStack Query data / error fields for you — explicit narrowing is only needed when you call the client directly:

const account = await client.accounts.read();
if (!account.ok) {
  console.error(account.error.code, account.error.message);
  return;
}
console.log(`${account.value.balance.value} ${account.value.balance.currency}`);

See Error handling for the error catalog and recovery patterns.

Method bundles

The client groups its methods into domain bundles. Each row links the hook family that wraps it. Bundles marked client-only have no hooks yet — in a React app, reach them through useCapxulClientOrNull.

Org scoping is explicit: client.org(orgId) resolves a bundle for that one organization on every call — there is no stateful "active org" on the client.

Off the surface

The client also carries a _internal namespace — an observation and testing seam. Nothing under _internal is consumer API; do not build on it. Likewise, factory inputs beyond the three documented above (self-hosted origins, fetch and runtime overrides, timeout and cache tuning) live on internal entrypoints for hermetic tests and platform tooling — never on createCapxulClient.