@capxul/sdk 0.2.0-alpha.4 → 1.0.0-alpha.10

package/README.md

@@ -1,312 +1,9 @@
 # @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.
+Layer 0 SDK package.
 
-> **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.
+- [Getting started](./docs/getting-started.md) — canonical consumer DX
+- [Package docs index](./docs/README.md)
+- [Env module](./docs/env.md)
 
-## 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 config={{ mode: "publishable-key", publishableKey }}>`
-  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
-  config={{
-    mode: "publishable-key",
-    publishableKey: process.env.NEXT_PUBLIC_CAPXUL_PUBLISHABLE_KEY!,
-  }}
->
-  <App />
-</CapxulProvider>;
-```
-
-## Publishable-key transport
-
-The browser transport accepts a publishable key, then lazily resolves
-runtime URLs by POSTing to `/v1/client/bootstrap` on the first auth or
-`ensureRuntime()` call. The successful backend response is intentionally
-small:
-
-```json
-{
-  "authBaseUrl": "https://<deployment>.convex.site/api/auth",
-  "convexUrl": "https://<deployment>.convex.cloud"
-}
-```
-
-The resolved runtime is cached for the lifetime of the transport. Concurrent
-callers share one bootstrap request, successful resolutions are reused, and
-failed bootstrap attempts reset so the next call can retry. Tests and
-non-default deployments can inject both `fetchImpl` and an absolute
-`bootstrapUrl`:
-
-```ts
-import { makeHttpTransport, CapxulError } from "@capxul/sdk";
-
-const transport = makeHttpTransport({
-  mode: "publishable-key",
-  publishableKey: process.env.NEXT_PUBLIC_CAPXUL_PUBLISHABLE_KEY!,
-  bootstrapUrl: "https://api.capxul.com/v1/client/bootstrap",
-  fetchImpl: fetch,
-});
-
-await transport.ensureRuntime();
-```
-
-Local setup errors and backend bootstrap errors both use `CapxulError`, but
-carry different `details.source` values:
-
-```ts
-try {
-  await transport.ensureRuntime();
-} catch (error) {
-  if (error instanceof CapxulError) {
-    if (error.details?.source === "sdk-config") {
-      // Missing or malformed local config, such as publishableKey or bootstrapUrl.
-    }
-    if (error.details?.source === "backend-bootstrap") {
-      // Sanitized backend refusal, such as NOT_AUTHENTICATED or PERMISSION_DENIED.
-    }
-  }
-}
-```
-
-Runtime proof status:
-
-| Surface        | Source support                                                   | Runtime proof                                                                                                                                                           | Status                                                 |
-| -------------- | ---------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------ |
-| SDK transport  | `makeHttpTransport({ mode: "publishable-key", publishableKey })` | `packages/sdk/tests/unit/transport.test.ts` proves config validation, singleflight bootstrap, retry after failure, lifecycle transitions, and sanitized backend errors. | Proven with mocked fetch                               |
-| React provider | `CapxulProvider config={{ mode: "publishable-key", ... }}`       | `packages/sdk-react/ops/proof/react-headless.test.tsx` proves bootstrap before a real `useMe()` read through the provider and lazy Convex data client.                  | Proven with mocked fetch + headless React              |
-| Reference CLI  | `bootstrap probe --mock --json`                                  | `apps/reference-cli/scripts/agent-driver.ts` phase 0 and the direct CLI command prove provider/bootstrap/auth ordering and sanitized output.                            | Proven locally; live endpoint remains manual-key gated |
-
-Copy-paste local replication:
-
-```bash
-corepack pnpm --filter @capxul/sdk check-types
-corepack pnpm --filter @capxul/sdk build
-corepack pnpm --filter @capxul/sdk-react check-types
-corepack pnpm --filter @capxul/sdk-react build
-corepack pnpm --filter @capxul/reference-cli check-types
-corepack pnpm --filter @capxul/reference-cli build
-node apps/reference-cli/dist/cli.js bootstrap probe --mock --json
-```
-
-Run the SDK and React SDK builds before the reference CLI typecheck in a
-fresh checkout; the CLI depends on their generated declaration outputs.
-
-Expected sanitized pass signal:
-
-```json
-{
-  "command": "bootstrap.probe",
-  "ok": true,
-  "mode": "publishable-key",
-  "status": "ready",
-  "bootstrapRequests": 1,
-  "authRequests": 1,
-  "keyLengthClass": "provided",
-  "mocked": true
-}
-```
-
-## 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.withdrawals   // create, retrieve, list
-capxul.documents     // personal invoices first; broader document variants typed
-capxul.flows.{auth, onboarding, provisioning} // XState v5 flows
-```
-
-### Personal invoice documents
-
-The first `documents` runtime surface is the personal invoice pilot.
-It creates immutable open invoice documents with a canonical
-`invoiceHash`. The backend stores the private invoice payload; the
-chain receives only the hash as `documentHash`.
-
-```ts
-const [err, invoice] = await capxul.documents.create({
-  type: "invoice",
-  recipient: { email: "client@example.com" },
-  amount: { value: "25.00", currency: "USD" },
-  lineItems: [
-    { description: "Design", quantity: 1, unitPrice: "25.00", currency: "USD" },
-  ],
-  reference: "May design work",
-  dueAt: "2026-05-20T00:00:00.000Z",
-});
-```
-
-Use `capxul.documents.retrieve(docId)`, `.list({ type: "invoice" })`,
-and `.cancel(docId)` for the rest of the pilot surface. Org-admin
-invoices, file uploads, PDFs, partial payments, and mutable open
-invoices are outside this pilot.
-
-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
-
-## Organizations
-
-Create an organization, manage its treasury, and invite members with
-role-based access:
-
-```ts
-// Create
-const [err, org] = await capxul.organizations.create({ name: "Acme" });
-
-// Invite a member — returns the raw token once
-const [err, { member, inviteToken }] =
-  await capxul.organizations.members.invite({
-    organizationId: org.id,
-    email: "alice@example.com",
-    role: "finance_manager",
-  });
-
-// List members — defaults to active; pass status to filter
-const [err, list] = await capxul.organizations.members.list({
-  organizationId: org.id,
-  status: "pending", // "pending" | "active" | "revoked" | "expired" | "all"
-});
-
-// Accept an invitation (called by the invitee)
-const [err, member] = await capxul.organizations.members.accept({
-  token: inviteToken,
-});
-
-// Revoke a pending invitation
-const [err] = await capxul.organizations.members.revoke({
-  organizationId: org.id,
-  memberId: member.id,
-});
-
-// Remove an active member
-const [err] = await capxul.organizations.members.remove({
-  organizationId: org.id,
-  memberId: member.id,
-});
-```
-
-Member roles: `owner`, `finance_manager`, `payments_operator`,
-`org_admin`, `viewer`, `accountant`. Only `owner` and `org_admin` can
-invite, revoke, remove, or change roles.
-
-Pending invitations auto-accept on first sign-in when the user's email
-matches. Overdue pending invitations expire via a nightly cron.
-
-## 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)
+React apps: [`@capxul/sdk-react` provider docs](../sdk-react/docs/provider.md).