@capxul/sdk 0.1.0-alpha.9 → 0.2.0-alpha.4

package/CHANGELOG.md

@@ -1,5 +1,131 @@
 # @capxul/sdk
 
+## 0.2.0-alpha.4
+
+### Minor Changes
+
+- b6c1f94: Complete the auth dogfooding epic around the canonical auth surface.
+
+  The SDK now carries the guarded OTP proof path, bootstrap continuation states,
+  canonical auth service behavior, and final funnel proof support needed for
+  first-run auth dogfooding. The React SDK aligns its auth hooks and provider
+  state with that canonical flow, including signout cleanup, bootstrap-required
+  continuations, and funnel telemetry integration.
+
+### Patch Changes
+
+- 50d3c55: Bundle the internal Safe derivation package into the SDK artifact instead of
+  publishing it as a runtime dependency, and add a packaging guard that fails when
+  publishable packages leak private `@repo/*` runtime dependencies.
+
+## 0.2.0-alpha.3
+
+### Patch Changes
+
+- 5b99a9b: **Publishable-key path + error classification (#675).** Two tangled bugs landed in the consumer-path proof.
+
+  **Reference-cli was on the wrong path.** `build-browser-config.ts` had a `build-time-urls` fallback that fired silently whenever `CAPXUL_REF_PUBLISHABLE_KEY` was unset, so the CLI routed direct to Convex URLs and bypassed `/v1/client/bootstrap` entirely. It "worked" through a code path no external SDK consumer will ever run, masking publishable-key path breakage.
+
+  Reference-cli now:
+  - Requires `CAPXUL_REF_PUBLISHABLE_KEY`. The repo ships a long-lived shared sandbox key at `apps/reference-cli/.env.example` so `git clone && export $(...)` works; the key targets `elated-oyster-269`, is environment `test` (`cap_pk_test_*`), and is intentionally shareable.
+  - Strips the `build-time-urls` arm entirely. There is no silent fallback — missing env produces a structured `ENV_MISSING` envelope with an actionable message.
+  - Keeps `bootstrap probe --mock` working env-less (the mock factory bypasses `buildBrowserInputs()`).
+
+  **Error classification.** The SDK's auth-layer catch was swallowing typed bootstrap errors. A bad publishable key produced HTTP 401 + `NOT_AUTHENTICATED: "Publishable key is invalid or revoked."` from the bootstrap endpoint, but `postBetterAuth`'s `catch (cause)` wrapped any throw from `transport.fetch()` as `NETWORK_ERROR: "BetterAuth … network failure."`, burying the real diagnosis on `cause`. Reference-cli then flattened further to `AUTH_ERROR`.
+
+  The SDK now:
+  - Preserves `CapxulError` verbatim in `postBetterAuth` and `exchangeConvexToken` catches. Genuine non-`CapxulError` throws still fall back to `NETWORK_ERROR`.
+  - Widens `SendOtpCodes` + `VerifyOtpCodes` to include `NOT_AUTHENTICATED` and `PERMISSION_DENIED` so consumers can exhaustively narrow bootstrap-layer errors.
+
+  **Consumer impact:** SDK consumers that switch on `err.code` from `auth.sendOtp` / `auth.verifyOtp` should now expect `NOT_AUTHENTICATED` (bad/revoked publishable key) and `PERMISSION_DENIED` (origin not on the key's allow-list) as additional possible codes alongside the existing BetterAuth + rate-limit codes. No type-narrowing regressions — the unions only widened.
+
+## 0.2.0-alpha.2
+
+### Minor Changes
+
+- 995383f: Epic 660: Unified auth surface
+  - Introduces AuthService promise-based auth API replacing the imperative capxul.auth.\* tuple interface
+  - Adds SignerProvisioner for deterministic Safe v1.4.1 address derivation from viem signers
+  - Adds useAuth() React hook with reactive state + promise-based methods
+  - Deprecates useAuthFlow and useAuthBootstrapFlow in favor of useAuth()
+  - Migrates reference CLI auth commands (send-otp, verify-otp, signout) to useAuth()
+  - Migrates test surfaces: walkthroughs, type tests, e2e harness signup, lazy-dx provider
+  - Adds @repo/safe-derive workspace package for Safe address derivation utilities
+  - Aligns CapxulConfig.data to \_data with internal SDK transport ownership (Epic 652)
+  - Pins esbuild to 0.25.12 to fix binary-version skew in fresh worktrees
+
+- 2ef4ee3: Reshape the organizations members surface around a single Membership entity
+  with a status lifecycle (`pending | active | revoked | expired`).
+  - Replaces the prior invitation/membership split (which produced a phantom
+    `MemberInvitation` type that never compiled) with a single `Member` type
+    exposing `status`, `email`, `acceptedAt`, `expiresAt`, and `resentCount`.
+  - New methods on `organizations.members.*`: `accept(token)`, `revoke(memberId)`,
+    `resend(memberId)`. `invite()` now returns a `MemberInviteResponse`
+    containing the raw invite token (returned once).
+  - Auto-accepts pending invitations on first sign-in for the matching email
+    via a BetterAuth post-signup hook.
+  - Nightly Convex cron expires overdue pending invitations.
+
+  Public type changes:
+  - Removed: `MemberInvitation` (was never exported; type didn't compile).
+  - Added: `MembershipStatus`, `MemberInviteResponse`.
+  - Updated: `Member` shape — see SDK reference for the full delta.
+
+  React hooks:
+  - New: `useAcceptInvitation`, `useRevokeMember`, `useResendInvitation`.
+  - Updated: `useInviteMember` returns `MemberInviteResponse` (was returning a
+    type that didn't exist).
+
+  Reference CLI:
+  - New commands: `org members invite`, `org members list`, `org members retrieve`,
+    `org members accept`, `org members updateRole`, `org members revoke`,
+    `org members remove`, `org members resend`.
+
+- c7146bf: **Transport ownership (#656):** The SDK now owns construction of the
+  authenticated `ConvexHttpClient`. Consumers no longer wire `data` manually
+  or provide `auth.createDataClient`. After `verifyOtp` exchanges a Convex
+  JWT, the SDK builds the default data client internally via
+  `createDefaultDataClient` and stores it on `config._data`.
+  - `CapxulConfig.data` renamed to `_data` (internal test seam).
+  - `CapxulAuthConfig.createDataClient` removed from public types.
+  - `convex` moved from `peerDependencies` to `dependencies`.
+
+### Patch Changes
+
+- Updated dependencies [995383f]
+  - @repo/safe-derive@0.0.1-alpha.0
+
+## 0.2.0-alpha.1
+
+### Minor Changes
+
+- **Transport ownership (#656):** The SDK now owns construction of the
+  authenticated `ConvexHttpClient`. Consumers no longer wire `data` manually
+  or provide `auth.createDataClient`. After `verifyOtp` exchanges a Convex
+  JWT, the SDK builds the default data client internally via
+  `createDefaultDataClient` and stores it on `config._data`.
+  - `CapxulConfig.data` renamed to `_data` (internal test seam).
+  - `CapxulAuthConfig.createDataClient` removed from public types.
+  - `convex` moved from `peerDependencies` to `dependencies`.
+
+### Patch Changes
+
+- Bundle `@repo/safe-derive` into the published artifact so the new
+  `SignerProvisioner` class works for external consumers.
+
+## 0.1.0-alpha.12
+
+### Minor Changes
+
+- Publish the post-alpha.11 SDK and React SDK surface: funds v1 sub-account
+  runtime coverage, React hook wiring, payments list support, and the latest
+  generated Convex API snapshots used by current alpha consumers.
+
+  Note: alpha.10 and alpha.11 were intermediate runner artifacts from the
+  prior release pipeline (manual `package.json` bumps that were never folded
+  back into the repo). alpha.12 reconciles `package.json`, the changesets
+  state, and npm to a single consistent version.
+
 ## 0.1.0-alpha.9
 
 ### Minor Changes

package/README.md

@@ -30,10 +30,10 @@ React-flavored entry point lives in `@capxul/sdk-react`. Pick:
 
 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` |
+| 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
@@ -94,7 +94,10 @@ runtime URLs by POSTing to `/v1/client/bootstrap` on the first auth or
 small:
 
 ```json
-{ "authBaseUrl": "https://<deployment>.convex.site/api/auth", "convexUrl": "https://<deployment>.convex.cloud" }
+{
+  "authBaseUrl": "https://<deployment>.convex.site/api/auth",
+  "convexUrl": "https://<deployment>.convex.cloud"
+}
 ```
 
 The resolved runtime is cached for the lifetime of the transport. Concurrent
@@ -136,11 +139,11 @@ try {
 
 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 |
+| 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:
 
@@ -160,7 +163,16 @@ 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}
+{
+  "command": "bootstrap.probe",
+  "ok": true,
+  "mode": "publishable-key",
+  "status": "ready",
+  "bootstrapRequests": 1,
+  "authRequests": 1,
+  "keyLengthClass": "provided",
+  "mocked": true
+}
 ```
 
 ## Public surface (alpha)
@@ -171,12 +183,36 @@ 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   // create, retrieve, list
-capxul.documents     // KYC uploads, invoices, receipts, tax forms
+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
@@ -186,6 +222,54 @@ Helpers:
 - 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
@@ -196,9 +280,12 @@ 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
+    case "PROFILE_NOT_FOUND":
+      return router.push("/onboarding");
+    case "NOT_AUTHENTICATED":
+      return router.push("/login");
+    default:
+      throw err; // unhandled — bubble to the error boundary
   }
 }
 ```