@capxul/sdk 0.1.0-alpha.0

package/CHANGELOG.md

@@ -0,0 +1,26 @@
+# @capxul/sdk
+
+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.

package/LICENSE

@@ -0,0 +1,44 @@
+Copyright (c) 2026 Xelmar Tech Ltd. ("Capxul"). All rights reserved.
+
+This software ("@capxul/sdk", 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 — workflow logic, business
+rules, integration glue, the contents of /v1/* clients, 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,143 @@
+# @capxul/sdk
+
+Headless TypeScript client for Capxul — issue and accept stablecoin
+payments, manage organization treasuries, and orchestrate on-chain
+flows backed by audited custody contracts.
+
+> **Alpha — `0.x` is pre-release.** APIs can change between alpha
+> versions. Pin to an exact version (`@capxul/sdk@0.1.0-alpha.0`) and
+> read the changelog before upgrading.
+
+## Install
+
+```bash
+pnpm add @capxul/sdk @capxul/sdk-react
+# or: npm install @capxul/sdk @capxul/sdk-react
+```
+
+`@capxul/sdk` is the headless contract — flows, types, errors. The
+React-flavored entry point lives in `@capxul/sdk-react`. Pick:
+
+- **Browser apps (recommended).** Install both. Use
+  `<CapxulProvider publishableKey="cap_pk_…">` from `@capxul/sdk-react`
+  and the `useMe` / `useCapxulStatus` hooks. See that package's
+  README for the lazy-DX example.
+- **Server / CLI / scripts.** Install only `@capxul/sdk`. Build a
+  `CapxulClient` directly with your own auth and Convex adapters
+  (see "Server-side construction" below).
+
+## Two-layer trust
+
+Capxul splits the platform into two layers with different licenses:
+
+| Layer | What it does | License |
+|---|---|---|
+| Custody (on-chain) | Safe v1.4.1 + ERC-4337 modules — every contract that holds, transfers, or signs over user funds | Open source, audited, in the [Capxul GitHub repo](https://github.com/Xelmar-tech/Capxul/tree/main/packages/contracts) |
+| Orchestration (this package) | Workflow logic, business rules, integration glue, the `/v1/*` HTTP client | Proprietary — see `LICENSE` |
+
+You don't have to take our word for the parts that hold money — those
+contracts are open and auditable. The parts that orchestrate workflows
+on top are our product.
+
+## Quickstart (server / CLI)
+
+```ts
+import { createCapxulClient, createLocalSigner, tryCatch } from "@capxul/sdk";
+
+const signer = createLocalSigner(process.env.CAPXUL_PRIVATE_KEY!);
+const capxul = createCapxulClient({
+  apiKey: process.env.CAPXUL_API_KEY!, // server-to-server partner key
+  signer,
+});
+
+const [err, payment] = await tryCatch(
+  capxul.payments.create({
+    to: { email: "vendor@example.com" },
+    amount: { value: "100", currency: "USD" },
+  }),
+);
+
+if (err) {
+  if (err.code === "INSUFFICIENT_BALANCE") {
+    // narrow `err.code` to route the UI / reply
+  }
+  throw err;
+}
+
+console.log(payment.id);
+```
+
+## Quickstart (browser via React)
+
+See [`@capxul/sdk-react`](https://www.npmjs.com/package/@capxul/sdk-react).
+The browser path uses a publishable key (`cap_pk_…`) and bootstraps
+runtime URLs lazily — no need to ship secrets to the client:
+
+```tsx
+import { CapxulProvider, useMe, useCapxulStatus } from "@capxul/sdk-react";
+
+<CapxulProvider publishableKey="cap_pk_live_…">
+  <App />
+</CapxulProvider>;
+```
+
+## Public surface (alpha)
+
+```ts
+capxul.auth          // sendOtp, verifyOtp, signOut, serviceTokenMint
+capxul.me            // get, update — first-party caller identity
+capxul.accounts      // create, retrieve, list
+capxul.organizations // CRUD + members + payments + treasury
+capxul.payments      // create, retrieve, list
+capxul.invoices      // create, retrieve, list
+capxul.withdrawals   // request, retrieve, list
+capxul.documents     // KYC uploads, invoices, receipts, tax forms
+capxul.flows.{auth, onboarding, provisioning} // XState v5 flows
+```
+
+Helpers:
+
+- `tryCatch(promise)` — error tuple `[error, data]`; routes on
+  `error.code` (typed `CapxulErrorCode` union)
+- `matchError`, `matchStatus`, `matchAction` — exhaustive pattern
+  matchers per CANON.md §4.44
+- Branded type constructors — `toEmail`, `toAccountId`,
+  `toOrganizationId`, … — never cast raw strings
+
+## Error model
+
+Every method returns a `CapxulResult<T, Codes>` tuple. Errors are
+instances of `CapxulError` with a typed `code` (narrowed per method).
+
+```ts
+const [err, account] = await tryCatch(capxul.me.get());
+
+if (err) {
+  switch (err.code) {
+    case "PROFILE_NOT_FOUND": return router.push("/onboarding");
+    case "NOT_AUTHENTICATED": return router.push("/login");
+    default: throw err; // unhandled — bubble to the error boundary
+  }
+}
+```
+
+There is no second error type. Backend `CapxulError` → Convex
+serialization → SDK deserialization → frontend `CapxulError` — one
+class, 34 codes, end-to-end.
+
+## Telemetry (opt-out)
+
+The SDK reports operational telemetry (operation IDs, latencies,
+correlation IDs, error codes) to Capxul. **PII is never sent** — events
+are scrubbed at the source. Disable by passing
+`{ telemetry: { enabled: false } }` (coming in `0.2.0`); current alpha
+sends only operational signals which Capxul Terms disclose explicitly.
+
+## 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 — see "Two-layer trust"
+above.
+
+Contact: [legal@capxul.com](mailto:legal@capxul.com)