@capxul/sdk-react 0.1.0-alpha.0

package/CHANGELOG.md

@@ -0,0 +1,31 @@
+# @capxul/sdk-react
+
+Changelog managed by [changesets](https://github.com/changesets/changesets) —
+see `.changeset/README.md` for the operator workflow.
+
+## 0.1.0-alpha.0
+
+### Minor Changes
+
+- Initial alpha publish.
+
+  `@capxul/sdk` ships the headless TypeScript client for Capxul's
+  `/v1/*` HTTP contract — auth, me, accounts, payments, organizations,
+  withdrawals, documents, and three XState v5 flow machines. Errors
+  are typed `CapxulError` instances with narrowed `code` unions per
+  method; `tryCatch` returns the canonical `[error, data]` tuple.
+
+  `@capxul/sdk-react` ships the React provider and hooks. The lazy-DX
+  `<CapxulProvider publishableKey="cap_pk_…">` mounts synchronously
+  and bootstraps runtime URLs through `/v1/client/bootstrap` on the
+  first SDK call. `useCapxulStatus()` exposes the canonical 5-state
+  transport lifecycle through `useSyncExternalStore`. Read hooks
+  return the canonical `QueryResult<T>` three-state discriminated
+  union (loading / data / error) — never throws on "still loading".
+
+  See each package's `README.md` for the public surface.
+
+### Patch Changes
+
+- Updated dependencies
+  - @capxul/sdk@0.1.0-alpha.0

package/LICENSE

@@ -0,0 +1,44 @@
+Copyright (c) 2026 Xelmar Tech Ltd. ("Capxul"). All rights reserved.
+
+This software ("@capxul/sdk-react", the "Software") is proprietary to
+Capxul. The Software is licensed, not sold, and is made available
+solely to registered Capxul customers under the Capxul Terms of
+Service or a separate written commercial agreement between Capxul and
+the licensee.
+
+Two-layer trust
+---------------
+Capxul's value-bearing on-chain logic — Safe v1.4.1, ERC-4337 modules,
+and any contract that custodies, transfers, or signs over user funds —
+is open source under permissive licenses and is published in a
+separate, auditable repository. See:
+
+  https://github.com/Xelmar-tech/Capxul
+
+The orchestration layer in this package — React provider, hooks,
+state-machine wiring, integration glue, and any code that translates
+customer intent into transactions or routes data between subsystems —
+is the proprietary product of Capxul and is governed by this license.
+
+Customers of the Capxul platform may use this Software solely:
+  (a) to access Capxul's hosted services they have contracted for,
+  (b) within the scope of their active subscription or trial, and
+  (c) in accordance with the Capxul Terms of Service.
+
+Without limiting the foregoing, you may NOT:
+  (i)   redistribute, sublicense, sell, lease, or rent the Software,
+  (ii)  reverse-engineer, decompile, or disassemble the Software,
+        except to the limited extent applicable mandatory law
+        permits, and
+  (iii) remove or alter copyright, trademark, or other proprietary
+        notices in the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS
+OR IMPLIED, INCLUDING BUT NOT LIMITED TO WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE, AND NONINFRINGEMENT. IN NO EVENT
+SHALL CAPXUL OR ITS AFFILIATES BE LIABLE FOR ANY CLAIM, DAMAGES, OR
+OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT, OR OTHERWISE,
+ARISING FROM, OUT OF, OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR
+OTHER DEALINGS IN THE SOFTWARE.
+
+Contact: legal@capxul.com

package/README.md

@@ -0,0 +1,173 @@
+# @capxul/sdk-react
+
+React provider + hooks for Capxul. Wraps [`@capxul/sdk`](https://www.npmjs.com/package/@capxul/sdk)
+in a synchronously-mounting provider with lazy bootstrap and a
+discriminated-union return shape on every read hook.
+
+> **Alpha — `0.x` is pre-release.** APIs can change between alpha
+> versions. Pin to an exact version and read the changelog before
+> upgrading.
+
+## Install
+
+```bash
+pnpm add @capxul/sdk @capxul/sdk-react react @tanstack/react-query
+# or: npm install @capxul/sdk @capxul/sdk-react react @tanstack/react-query
+```
+
+Peer requirements:
+
+- React `>= 19.0.0`
+- `@tanstack/react-query` `^5`
+- `@xstate/react` `^5` (only if you use the flow hooks)
+
+## Two-layer trust
+
+This package is the **orchestration** half of Capxul's two-layer
+architecture. Funds are custodied by audited, open-source Safe v1.4.1
+contracts published in the [Capxul GitHub repo](https://github.com/Xelmar-tech/Capxul/tree/main/packages/contracts).
+The React glue here is proprietary — see [`LICENSE`](./LICENSE).
+
+## Quickstart
+
+Wrap your app once with `CapxulProvider`. Pass a publishable key
+(`cap_pk_live_…` / `cap_pk_test_…`). The provider mounts synchronously
+— no Suspense gate, no async-mount stall — and lazily bootstraps the
+runtime URLs from `/v1/client/bootstrap` on the first SDK call:
+
+```tsx
+import { CapxulProvider } from "@capxul/sdk-react";
+
+export default function RootLayout({ children }) {
+  return (
+    <CapxulProvider publishableKey={process.env.NEXT_PUBLIC_CAPXUL_KEY!}>
+      {children}
+    </CapxulProvider>
+  );
+}
+```
+
+Inside the tree, read identity with `useMe()`. The hook collapses the
+multi-step lifecycle (not-bootstrapped, bootstrapping, no-session,
+no-data, live) into three states the consumer cares about:
+
+```tsx
+import { useMe } from "@capxul/sdk-react";
+
+function Header() {
+  const me = useMe();
+
+  if (me.isPending) return <span>Loading…</span>;
+  if (me.isError) return <span>Couldn't load profile.</span>;
+  return <span>Hi, {me.data.username}</span>;
+}
+```
+
+Drive an OTP sign-in flow with `useAuthFlow()` — a
+[`useActor`](https://stately.ai/docs/xstate-react#useactor) observer
+over the canonical XState v5 machine in `@capxul/sdk`:
+
+```tsx
+import { useAuthFlow } from "@capxul/sdk-react";
+import { toEmail } from "@capxul/sdk";
+
+function SignIn() {
+  const { snapshot, send } = useAuthFlow();
+
+  if (snapshot.matches("idle")) {
+    return (
+      <button
+        onClick={() =>
+          send({ type: "REQUEST_OTP", email: toEmail("alice@example.com") })
+        }
+      >
+        Send code
+      </button>
+    );
+  }
+  // … handle "sending_otp", "otp_requested", "verifying", "authenticated"
+}
+```
+
+## Lifecycle observability — `useCapxulStatus()`
+
+Need a status indicator or a gate UI? Subscribe to the underlying
+transport state machine:
+
+```tsx
+import { useCapxulStatus } from "@capxul/sdk-react";
+
+function Banner() {
+  const status = useCapxulStatus();
+
+  switch (status.status) {
+    case "idle":           // no network call yet
+    case "bootstrapping":  // /v1/client/bootstrap in flight
+      return <Spinner />;
+    case "ready":          // bootstrapped, no session
+    case "authenticated":  // bootstrapped + session live
+      return null;
+    case "error":
+      return <ErrorBanner error={status.error} />;
+  }
+}
+```
+
+`useCapxulStatus()` is a thin
+[`useSyncExternalStore`](https://react.dev/reference/react/useSyncExternalStore)
+subscription against the transport singleton — only the components
+that actually call it re-render when state changes. The provider
+itself never re-renders.
+
+## Hooks catalogue
+
+| Surface | Hook |
+|---|---|
+| Imperative client | `useCapxul()` |
+| Identity | `useMe`, `useAccount` |
+| Organizations | `useOrganization`, `useOrganizations`, `useMember`, `useMembers` |
+| Payments | `usePayment`, `usePayments`, `useOrgPayments` |
+| Transfers | `useTransfer`, `useTransfers`, `useOrgTransfers` |
+| Withdrawals | `useWithdrawal`, `useWithdrawals`, `useOrgWithdrawals` |
+| Documents | `useDocument`, `useDocuments`, `useOrgDocuments` |
+| Sub-accounts / virtual | `useSubAccount`, `useSubAccounts`, `useVirtualAccount`, `useVirtualAccounts`, `useVirtualCard`, `useVirtualCards` |
+| Settings | `useApiKey`, `useApiKeys`, `useWebhookEndpoint`, `useWebhookEndpoints`, `useWebhookEvent`, `useExternalAccount`, `useExternalAccounts`, `useBalanceLedgerEntry`, `useBalanceLedger` |
+| KYC / KYB | `useKycProfile`, `useKybProfile` |
+| Treasury | `useTreasury`, `useSafe` |
+| Operations | `useOperation` (correlation join key per CANON.md §3.3) |
+| Lifecycle | `useCapxulStatus` |
+| Flows | `useAuthFlow`, `useOnboardingFlow`, `useProvisioningFlow` |
+
+Most "not-yet-implemented" verticals return a `QueryResult<T>` in the
+`error` state with `code: "NOT_IMPLEMENTED"` — they compile, render
+without crashing, and surface a clear runtime signal.
+
+## Three-state read shape (`QueryResult<T>`)
+
+Read hooks return a discriminated union:
+
+```ts
+type QueryResult<T> =
+  | { readonly status: "loading" }
+  | { readonly status: "data";  readonly data: T }
+  | { readonly status: "error"; readonly error: CapxulError };
+```
+
+Hooks **never throw** for a "still loading" condition. Pattern-match
+on `status`. (`useMe()` is the first hook migrated to TanStack Query
+— it returns `UseQueryResult<Account, CapxulError>` for now; the
+remaining hooks lift to that shape over time.)
+
+## Server / CLI consumers
+
+`@capxul/sdk-react` is browser-only. For server, CLI, and harness
+code, build a `CapxulClient` directly with `createCapxulClient` from
+`@capxul/sdk` — no provider, no React. See that package's README.
+
+## License
+
+Proprietary — see [`LICENSE`](./LICENSE). The orchestration code in
+this package is governed by the Capxul Terms of Service. The
+value-bearing custody contracts are open source.
+
+Contact: [legal@capxul.com](mailto:legal@capxul.com)