@capxul/sdk 0.1.0-alpha.0 → 0.1.0-alpha.11

package/CHANGELOG.md

@@ -1,5 +1,141 @@
 # @capxul/sdk
 
+## 0.1.0-alpha.11
+
+### Patch Changes
+
+- 4822b87: Auth-error surfacing on OTP send + SDK error-code union widening.
+
+  PR #586 merged 2026-05-07. SDK now exposes `PROVIDER_ERROR`,
+  `INTERNAL_ERROR`, `ENV_MISSING`, and `UNKNOWN` in the public error
+  union (ADR-020) so consumers can narrow exhaustively. Anti-enumeration
+  timing is equalized via symmetric cooldown + bounded random sleep
+  (ADR-021); per-IP rate limit is the residual gap tracked at #584.
+
+  Closes the silent-200 OTP delivery bug (#579) that blocked Pi-setup.
+
+## 0.1.0-alpha.9
+
+### Minor Changes
+
+- Add the canonical auth bootstrap flow.
+
+  `verifyOtp()` now resolves a verified email session into either an
+  `existing_member` identity or a `bootstrap_required` continuation. New and
+  incomplete members continue through `completeBootstrap()`, which validates a
+  server-issued bootstrap token, claims the username, provisions the account/Safe
+  through the backend bootstrap path, and returns the authenticated product
+  identity. The React SDK adds `useAuthBootstrapFlow()` as the typed first-run
+  flow wrapper.
+
+## 0.1.0-alpha.8
+
+### Minor Changes
+
+- 57203a4: Withdrawals v1 W2 (#465) — public surface tightening + org-scope create
+  - `WithdrawalsCreateInput.destination` no longer accepts `kind`. The
+    backend now resolves the `external_account` row by FK and infers
+    the kind + rail server-side. Anything that doesn't route to
+    `chain_wallet` (or is chain_wallet but non-EVM in slice 1) returns
+    `VERIFICATION_REQUIRED` with `details.rail` + `details.currentKind`.
+  - `organizations.withdrawals.create` is now a real mutation (no
+    longer a `NOT_IMPLEMENTED` stub). Returns the `processing` row
+    only — Safe + Zodiac submission orchestration ships in W3+.
+  - `Errors.verificationRequired({ rail, currentKind })` factory
+    added; the `VERIFICATION_REQUIRED` code now broadens to cover
+    both KYC tier gates and unsupported withdrawal rails.
+
+  **Migration:** Remove `destination.kind` from any
+  `capxul.withdrawals.create({ destination: { kind, externalAccountId } })`
+  call sites. Pass only `externalAccountId`.
+
+## 0.1.0-alpha.4
+
+### Minor Changes
+
+- Post-alpha hardening — WAVE 1 + WAVE 2 cumulative
+
+  **WAVE 1 (merged 2026-05-03 12:44Z):**
+  - S2 story 1: wire onboarding readback hooks (#469) — `me.update`, `accounts.retrieve`, `accounts.update`, `useAccount`, `useSafe`
+  - S3 phase 1: Ink reference CLI scaffold + `auth+me` end-to-end against live alpha-3 Convex (#470). Stickiness gate (D3) fired.
+  - S5: split `CapxulProvider` into public single-input `BrowserCapxulConfig` + test-only `CapxulTestProvider` from `@capxul/sdk-react/proof` (#473). Q1 lock honored. 7 type-level provider-shape guards including `@ts-expect-error` against test-provider leaking to public barrel.
+
+  **WAVE 2 (merged 2026-05-03 12:54-13:16Z):**
+  - S3 phase 2: per-domain CLI commands closing #458 (#476) — `account retrieve/update`, `safe retrieve`, `payment retrieve`, `withdrawal retrieve/list`. 12/12 agent-driver tests pass.
+  - S2 story 2: `capxul.tokenTransfers.*` non-canonical SDK namespace (#479) — Option A per #477 (canon-aligned `transfers.*` shape deferred to alpha.5+ pending backend canon work). New `useTokenTransfers` + `useTokenTransfer` hooks; new `getByTxLogIndex` backend query. Hook proof matrix length unchanged at 41 (non-canonical hooks deliberately excluded).
+
+  **S1 (#456) closed no-op** — alpha publish infrastructure (tsup, lazy-DX, transport state machine, npm metadata, READMEs, CHANGELOG, changesets, OIDC release workflow) physically merged into `api-first` via PRs #449-#452 earlier the same day; the slice merge produced 0 file changes per clean-room probe.
+
+  **Friction issues filed for alpha.4+ polish:**
+  - #474 — `me.get` returns `NOT_IMPLEMENTED` when `config.data` is undefined; should be `NOT_AUTHENTICATED`.
+  - #475 — `@capxul/sdk/headless` slim entry point excludes xstate flow machines + brand constructors (1.6 MB → much smaller).
+  - #477 / #478 — `transfers.*` / `balanceLedger.*` / `treasury` canon-shape alignment with indexer feed.
+  - #471 — Vercel-capxul-web preview-deploy systemic failure on api-first base (separate from epic).
+
+## 0.1.0-alpha.3
+
+### Patch Changes
+
+- Re-export `tryCatch` from `@capxul/sdk`.
+
+  `tryCatch` is referenced in `packages/sdk/README.md` (live on npm at
+  `0.1.0-alpha.2`) and in `.claude/rules/sdk.md` as the canonical
+  async-error helper for SDK operations:
+
+  ```ts
+  import { tryCatch } from "@capxul/sdk";
+
+  const [err, payment] = await tryCatch(capxul.payments.create({ ... }));
+  ```
+
+  The helper lives at `@repo/observability/try-catch.ts` and is bundled
+  into the SDK dist via tsup `noExternal`, but it was never re-exported
+  from `packages/sdk/src/index.ts`. Consumers following the README example
+  hit `Module '"@capxul/sdk"' has no exported member 'tryCatch'.` at
+  import time.
+
+  Caught during alpha.2 spike-install verification (REVIEW.html, "What's
+  not proven" row 6). One-line public-export addition; no runtime change.
+
+## 0.1.0-alpha.2
+
+### Patch Changes
+
+- Add `convex` as a peer dependency.
+
+  `@capxul/sdk`'s bundled `_generated/api` snapshot calls
+  `anyApi` / `componentsGeneric` from `convex/server` at runtime — they
+  are not just types — and tsup correctly externalizes `convex` /
+  `convex/server` / `convex/react` so the consumer's own Convex install
+  is reused. The peer was missing from the published manifest, so
+  `require('@capxul/sdk')` failed with `Cannot find module 'convex/server'`
+  in any spike that hadn't already installed `convex`.
+
+  `@capxul/sdk-react` mirrors the peer because its bundle re-exports
+  flow-machine constructors from `@capxul/sdk` and may transitively
+  pull in the same module.
+
+  Caught during alpha.1 spike-install verification.
+
+## 0.1.0-alpha.1
+
+### Patch Changes
+
+- Move workspace `@repo/*` packages from `dependencies` to
+  `devDependencies` so the published `package.json` doesn't list them
+  as runtime deps. The tsup pipeline bundles every `@repo/*` import
+  inline (`noExternal`), so the published code has zero references to
+  those packages — but until now the published `package.json` still
+  declared them, and `npm install @capxul/sdk@0.1.0-alpha.0` failed
+  trying to resolve `@repo/api-contract@0.0.0` etc. on the public
+  registry.
+
+  `@capxul/sdk-react` keeps `@capxul/sdk` as a runtime dep — that one
+  is published.
+
+  No public surface changes. Pure publish-metadata correction caught
+  during alpha.0 spike-install verification.
+
 Changelog managed by [changesets](https://github.com/changesets/changesets) —
 see `.changeset/README.md` for the operator workflow.
 

package/README.md

@@ -19,9 +19,9 @@ pnpm add @capxul/sdk @capxul/sdk-react
 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.
+  `<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).
@@ -76,11 +76,93 @@ 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_…">
+<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
@@ -90,7 +172,7 @@ 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.withdrawals   // create, retrieve, list
 capxul.documents     // KYC uploads, invoices, receipts, tax forms
 capxul.flows.{auth, onboarding, provisioning} // XState v5 flows
 ```