@capxul/sdk 0.2.0-alpha.3 → 0.2.0-alpha.5

package/package.json

@@ -1,92 +1,58 @@
 {
   "name": "@capxul/sdk",
-  "version": "0.2.0-alpha.3",
-  "description": "Headless TypeScript client for Capxul's /v1/* HTTP contract.",
-  "license": "UNLICENSED",
-  "private": false,
-  "type": "module",
-  "homepage": "https://capxul.com",
-  "repository": {
-    "type": "git",
-    "url": "git+https://github.com/Xelmar-tech/Capxul.git",
-    "directory": "packages/sdk"
-  },
-  "bugs": {
-    "url": "https://github.com/Xelmar-tech/Capxul/issues"
-  },
-  "author": "Capxul (Xelmar Tech Ltd.)",
-  "keywords": [
-    "capxul",
-    "sdk",
-    "stablecoin",
-    "payments",
-    "smart-account",
-    "typescript"
+  "version": "0.2.0-alpha.5",
+  "files": [
+    "dist",
+    "package.json",
+    "README.md"
   ],
-  "main": "./dist/index.cjs",
-  "module": "./dist/index.js",
-  "types": "./dist/index.d.ts",
+  "type": "module",
   "exports": {
     ".": {
-      "types": "./dist/index.d.ts",
-      "import": "./dist/index.js",
-      "require": "./dist/index.cjs"
+      "types": "./dist/index.d.mts",
+      "import": "./dist/index.mjs"
     },
-    "./client": {
-      "types": "./dist/client.d.ts",
-      "import": "./dist/client.js",
-      "require": "./dist/client.cjs"
+    "./node": {
+      "types": "./dist/node/index.d.mts",
+      "import": "./dist/node/index.mjs"
     },
-    "./errors": {
-      "types": "./dist/errors.d.ts",
-      "import": "./dist/errors.js",
-      "require": "./dist/errors.cjs"
-    },
-    "./webhooks": {
-      "types": "./dist/webhooks.d.ts",
-      "import": "./dist/webhooks.js",
-      "require": "./dist/webhooks.cjs"
+    "./ports/safe-deployment": {
+      "types": "./dist/ports/safe-deployment.d.mts",
+      "import": "./dist/ports/safe-deployment.mjs"
     }
   },
-  "files": [
-    "dist",
-    "README.md",
-    "LICENSE",
-    "CHANGELOG.md"
-  ],
   "publishConfig": {
     "access": "public"
   },
   "dependencies": {
-    "xstate": "^5",
-    "convex": ">=1.0.0",
-    "@repo/safe-derive": "0.0.1-alpha.0"
-  },
-  "peerDependencies": {
-    "permissionless": ">=0.3.4 <0.4.0",
-    "viem": ">=2.0.0"
+    "@effect/experimental": "^0.60.0",
+    "@effect/platform": "^0.96.1",
+    "@effect/platform-node": "^0.106.0",
+    "@effect/schema": "^0.75.5",
+    "convex": "^1.39.1",
+    "effect": "^3.21.2",
+    "viem": "^2.21.0",
+    "@capxul/config": "0.0.0",
+    "@capxul/observability": "0.0.0",
+    "@capxul/types": "0.0.0",
+    "@capxul/wire": "0.0.0"
   },
   "devDependencies": {
-    "@types/node": "^22.15.3",
+    "@effect/vitest": "^0.29.0",
+    "@vitest/coverage-v8": "4.1.7",
+    "fast-check": "^3.23.2",
     "permissionless": "0.3.4",
-    "tsup": "^8.5.1",
     "typescript": "5.9.2",
-    "viem": "2.47.10",
-    "vitest": "^4.1.2",
-    "zod": "^4.3.6",
-    "@repo/api-contract": "0.0.0",
-    "@repo/backend": "0.0.1-alpha.0",
-    "@repo/config": "0.0.0",
-    "@repo/observability": "0.0.0",
-    "@repo/platform-kernel": "0.0.0",
-    "@repo/typescript-config": "0.0.0",
-    "@repo/safe-derive": "0.0.1-alpha.0"
+    "vitest": "npm:@voidzero-dev/vite-plus-test@0.1.23"
   },
+  "_permissionlessPinReason": "permissionless.toSafeSmartAccount is pinned to 0.3.4 for live Safe deployment E2E. Counterfactual address fixtures captured 2026-05-17 in packages/backend/convex/_shared/__tests__/counterfactual.test.ts and packages/config/tests/safe.test.ts must be re-verified before upgrading.",
   "scripts": {
-    "build": "tsup",
-    "check-types": "tsc --noEmit",
-    "snapshot:api": "tsx scripts/snapshot-convex-api.ts",
-    "test": "vitest run",
-    "test:types": "vitest run --typecheck"
+    "check-types": "tsc -p tsconfig.json --noEmit",
+    "lint": "oxlint -c ../../.oxlintrc.json . --deny-warnings",
+    "build": "vp pack",
+    "_vp-tasks-allowed": "vp-allowed: `test` + `test:coverage` are vp tasks in vite.config.ts so vitest self-writes don't bust cache (#205). `test:coverage:full` keeps the script form because it composes 5 reporters at invocation time.",
+    "test:coverage:full": "CAPXUL_FAST_CHECK_NUM_RUNS=50 vp test run --coverage --coverage.reporter=text --coverage.reporter=json-summary --coverage.reporter=json --coverage.reporter=html --coverage.reporter=clover",
+    "test:e2e": "vp test run --config vitest.e2e.config.ts",
+    "org:domain-live": "vp dlx tsx e2e/org-domain-sdk-live.ts"
   }
 }

package/CHANGELOG.md

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

@@ -1,44 +0,0 @@
-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