@capxul/sdk 4.20.0-beta.4 → 4.20.0-beta.40

package/README.md

@@ -19,51 +19,154 @@ const client = created.value;
 Every public operation resolves a `Promise<CapxulResult<T>>`. Domain failures
 are values, not thrown exceptions.
 
-## Money input and display
+After the Person and personal Account are ready, begin Organization setup and
+store its exact ID before signer interaction:
 
-Use the public money helpers at form and display boundaries. They do not
-convert a money value to a JavaScript number.
+```ts
+const begun = await client.onboarding.beginOrganization({
+  name: "Analytical Engines",
+  handle: "analytical-engines",
+  country: "GH",
+});
+if (!begun.ok) throw begun.error;
+
+const { orgId } = begun.value;
+if (begun.value.setup.status === "awaitingAuthorization") {
+  const authorized = await client.org(orgId).setup.authorize();
+  if (!authorized.ok) throw authorized.error;
+}
+
+const observed = await client.org(orgId).setup.subscribe((snapshot) => {
+  if (snapshot.status === "value") console.log(snapshot.value.status);
+});
+if (!observed.ok) throw observed.error;
+// Call observed.value() when the screen no longer needs updates.
+```
+
+`setup.resume()` requests a backend check for the same Organization. It does
+not ask the signer to submit again. `onboarding.completeOrganization()` runs
+begin, authorization when needed, and observation through `ready`.
+
+An authenticated client can find unfinished founder setups without a local
+recovery file. Read pages until `isDone` is true; omit `cursor` on the first
+request:
 
 ```ts
-import { formatMoney, parseMoney } from "@capxul/sdk";
+let cursor: string | undefined;
+do {
+  const listed = await client.onboarding.listOrganizationSetups(
+    cursor === undefined ? {} : { cursor },
+  );
+  if (!listed.ok) throw listed.error;
+  for (const setup of listed.value.page) console.log(setup.orgId, setup.status);
+  if (listed.value.isDone) break;
+  if (listed.value.cursor === null) throw new Error("Missing setup cursor");
+  cursor = listed.value.cursor;
+} while (true);
+```
+
+`listOrganizationSetups` is a read. It does not authorize, resume, or sign.
+
+## Local Effect DevTools
 
-const amount = parseMoney("1,000.25", {
-  currency: account.available.currency,
-  decimals: account.available.decimals,
+Start the repository collector with `vp run devtools:serve`, then create a
+development client:
+
+```ts
+const created = await createCapxulClient({
+  publishableKey,
+  devToolsUrl: "ws://127.0.0.1:34439",
 });
+```
+
+Run an operation and read its spans and metrics with `vp run devtools:snapshot`.
+For the editor view, start its Effect DevTools server and run the collector with
+`vp run devtools:serve --vscode`. Browser and
+Node hosts use the same option. Omit it to disable the connection. Call
+`client.close()` when the host no longer needs the client; close also releases
+DevTools. The URL must use `ws` or `wss` on `localhost`, `127.0.0.1`, `[::1]`, or
+`host.docker.internal`, without credentials, a query, or a fragment.
+This local connection carries native debug detail. It does not change remote
+telemetry configuration. See the [development workflow](../../docs/canon/development-and-verification.md)
+for agent access and the shared local collector.
+
+## Invitation updates
+
+Use `client.org(orgId).invitations.subscribe({ invitationId }, listener, { signal })`
+to observe one offer. The listener receives `loading`, then validated `value`
+snapshots or a terminal typed `error`. The successful result holds an idempotent
+unsubscribe function. Abort, sign-out, account replacement, and client close
+stop delivery. A late registration handle is released when it arrives.
+This read never accepts an offer or retries a write. Bound a wait through the
+caller’s AbortSignal; per-call timeout options do not define stream lifetime.
+
+## Asset amount input and display
+
+Use the asset helpers at Payment form and display boundaries. They keep the
+exact AssetId and do not convert a value to a JavaScript number.
+
+```ts
+import { formatAssetAmount, parseAssetAmount, requireAsset, TOKENS } from "@capxul/sdk";
+
+const amount = parseAssetAmount("1,000.25", requireAsset(TOKENS.BASE_SEPOLIA.CAPXUL_TEST_USDC));
 
 if ("kind" in amount) {
   console.error(amount.reason); // closed code — the app owns the sentence (ADR-0023)
 } else {
-  console.log(formatMoney(amount)); // $1,000.25
-  console.log(formatMoney(amount, { grammar: "code" })); // 1,000.25 USD
+  console.log(formatAssetAmount(amount)); // 1,000.25 USDC
 }
 ```
 
-`parseMoney` returns validation errors as values. `formatMoney` rejects a
-malformed `Money` record with `INVALID_INPUT`.
+`parseAssetAmount` returns validation errors as values. Payment, request,
+Budget, Payroll, and activity amounts require AssetAmount. Fiat Money remains
+separate valuation data.
 
-## The asset a screen shows
+## Value all asset positions
 
-`holdings.primary` picks the one asset a hero balance or a summary total
-should show. It returns the renderable holding with the largest available
-balance. A chain row that carries no `decimals`, no `symbol`, or a symbol that
-stands for no supported currency is skipped, because it cannot be rendered.
+Use `holdings.current` for raw positions. Use `valueIn` to value exact asset
+quantities in a display currency. A token symbol does not identify an asset.
+Quantities from different assets cannot be compared as a headline balance.
 
 ```ts
-import { formatMoney, type Holding } from "@capxul/sdk";
+import { formatMoney, valueIn } from "@capxul/sdk";
 
-const result = await client.holdings.primary();
-
-if (result.ok && result.value !== null) {
-  const holding: Holding = result.value;
-  console.log(holding.symbol); // "USDX" — the token symbol the chain reported
-  console.log(formatMoney(holding.available, { grammar: "code" })); // e.g. "1,250.50 USD"
+const valuation = valueIn(amounts, displayCurrency, rates);
+if (valuation.total !== null) {
+  console.log(formatMoney(valuation.total));
 }
 ```
 
-`null` means no row is renderable. It is a value, not an error, so give the
-screen its own rule for showing nothing.
+Keep `valuation.unrated` visible beside the known subtotal. A missing rate
+does not mean a zero balance.
+
+## Approvals
+
+Every signature a person makes goes through one approval. A caller with no
+key, such as the CLI or an agent, prepares the Payment and hands the person
+the link. Nothing is signed or sent until the person approves it there.
+
+```ts
+const prepared = await client.approvals.prepare({
+  to: { kind: "email", email: "ada@example.com" },
+  amount: { asset: usdc.assetId, value: "25" },
+});
+if (!prepared.ok) throw prepared.error;
+console.log(prepared.value.url, prepared.value.summary);
+
+// Sends the approved operation once, then waits until its Payment settles.
+const outcome = await client.approvals.wait(prepared.value.approvalId, { signal });
+```
+
+The approval page runs as the same person, with their own signer:
+
+```ts
+await client.approvals.review(approvalId); // the first open is recorded
+const approved = await client.approvals.approve(approvalId); // or reject(approvalId)
+```
+
+`approve` signs only the digest the approval's operation describes, and only
+with the approval's signer. The backend checks the signature and never signs.
+A rejected or expired approval ends `wait` with that state.
 
 ## Observability
 
@@ -105,6 +208,11 @@ The backend remains the authority for reserved names and global uniqueness.
 The method returns only after the client requirement reaches a ready Account.
 The React frontend does not use this journey yet.
 
+A Node host that keeps login outside the browser can pass `openfortSignerFactory`.
+The factory receives only the validated Openfort and auth bootstrap fields. Its
+browser page can use `createOpenfortBrowserSigner` with host-owned access-token
+and encryption-session callbacks. It does not need a second login or private SDK import.
+
 ## Published entry points
 
 The packed npm package exposes only:
@@ -125,7 +233,10 @@ also contains them.
 import { createCapxulTestClient } from "@capxul/sdk/testing";
 
 const testing = createCapxulTestClient();
-await testing.seedIdentity({ authUserId: "auth_seeded_test", email: "test@example.test" });
+await testing.seedIdentity({
+  authUserId: "auth_seeded_test",
+  email: "test@example.test",
+});
 await testing.clock.advance(1_000);
 await testing.client.auth.signIn({ email: "test@example.test" });
 const otp = testing.peekOtp("test@example.test");
@@ -165,11 +276,150 @@ vp run --filter @capxul/sdk build
 vp run --filter @capxul/sdk proofs:live
 ```
 
-`proofs:live` runs the deterministic Organization Core SDK journey against the
-configured live Convex deployment and Base Sepolia. Live proofs require
-operator secrets and prove only the path named by the command. See
-[maintainer context](./CONTEXT.md#capability-and-proof-boundaries).
+`proofs:live` runs the Organization Core SDK journey against the configured
+Convex deployment and Base Sepolia. Run it with the synchronized candidate.
+The package tests prove local SDK behavior.
+See [maintainer context](./CONTEXT.md#capability-and-proof-boundaries).
 
 The browser production path owns its Openfort signer when no signer is supplied.
-Current integration recovery evidence and its published-package boundary are
-tracked in the [#870 receipt](../../docs/receipts/issue-870-openfort-signer-recovery-RECEIPT-2026-07-19.md).
+Integration recovery evidence and its published-package boundary were recorded
+in the #870 receipt (since deleted; see git history).
+
+### Node session storage
+
+A Node host can pass `nodeSessionStorage: { load, save }` to
+`createCapxulClient`. Both methods return promises. `load` returns an opaque
+BetterAuth credential or `null`; `save` receives the credential or `null` on
+logout. Store it with owner-only access and isolate it by application and
+environment. Do not print it or use a cached `AuthSession` as backend authority.
+The SDK validates the credential and expiry with BetterAuth on process restart.
+With durable storage, each adapter serializes session reads, OTP verification,
+sign-out, and Convex token reads. A delayed response cannot clear or rotate a
+credential from a later operation on that adapter. Cancellation while queued
+returns immediately and prevents that operation from reaching the provider.
+Hosts that share storage across clients or processes must fence writes, for
+example with an atomic compare-and-set; the adapter cannot order other clients.
+
+For separate OTP request and verification processes, retain the email and
+original request timestamp. After `auth.getSession()` confirms signed-out state,
+call `auth.resumeOtp({ email, requestedAt })`, then `auth.verifyOtp({ email,
+code })`. Resume restores pending input only. It does not send another OTP or
+authenticate the caller. Keep OTP values out of arguments, logs, and stored data.
+
+### Existing financial documents
+
+Use `paymentDocuments.verify({ documentHash, contentHash })` to verify stored
+content. Use `paymentDocuments.render` with the same pair for safe semantic HTML.
+Call `paymentDocuments.get` only for a deliberate download. Its `bytesBase64`
+contains the exact stored bytes. Do not log document results or error payloads.
+Get references from Payment or Movement activity detail. References include
+kind, format, and role. A hash is not permission to read a document.
+Reads check current Payment participants or current Movement actor access.
+Missing and unauthorized pairs return the same refusal. These methods do not
+create documents or add Payment links.
+
+## Inbox documents
+
+Personal Account and Organization Inbox reads include `documents` on each
+item. An unpaid issued Invoice can have document references before a Payment
+exists. Requests without an attached document return an empty array. The
+references preserve the document and content hashes needed by
+`paymentDocuments.get`, `verify`, and `render`. Inbox listing does not render
+or download documents. Existing issuer and payer access checks still apply.
+
+Issued requests and Inbox items retain a linked `paymentId` when preparation
+has started. Invoice Inbox items also retain the stored `issuerSafe`. These
+fields do not mean that the Payment has settled.
+
+`inbox.paymentTerms(requestId)` reads exact private terms without a signer or
+write. It returns the issued Invoice instruction or a deterministic Memo
+instruction for a generic request. Prepared requests retain their stored
+instruction. Only the addressed payer can read these terms.
+
+`inbox.fulfill(confirmation, { onPrepared })` executes the confirmed request
+through the existing signer. `onPrepared({ paymentIds })` receives verified
+durable IDs before signing. If the callback fails, signing stops. Do not await
+the fulfillment call inside this callback. Organization confirmation requires
+an admitted Permission; personal confirmation does not accept one. The backend
+checks the payer, exact amount, issuer Safe, release, and frozen instruction.
+
+## Fixed offers and checkout
+
+`account.offers` and `org(id).offers` manage reusable fixed-price offers with
+explicit quantity limits. Creation uses a caller request key. Revisions append
+immutable prices and require the expected revision.
+
+`checkouts.offer(id)` is a public read and creates no purchase. `checkouts.create`
+uses a UUID v4 purchase key, selected revision, quantity, and funding wallet to
+freeze one purchase. `checkouts.get` restores its exact snapshot. `checkouts.prepare`
+returns unsigned approval and Payments-contract transactions for that wallet.
+The consumer checks chain, balance, allowance, and gas. Preparation does not sign,
+submit, or prove settlement. No checkout URL is returned before the page exists.
+
+## Fixed offer checkout candidate
+
+The checkout APIs below are source candidate APIs. The published beta17 baseline
+does not include them. Consume a matching packed candidate for local integration.
+
+`account.offers` and `org(id).offers` provide create, list, get, revise, and
+deactivate. Create uses a caller replay key. Revision and deactivation require the
+current revision. Each offer has one asset, an exact unit amount, and bounded whole
+unit quantities. An offer revision does not change an existing purchase.
+
+Public `checkouts.offer(id)` reads approved offer fields. `checkouts.create(input)`
+explicitly freezes the offer revision, quantity, funding wallet, recipient, amount,
+network, contract, instruction, and settlement identity. Reuse the same UUID v4
+purchase key after a lost reply. Different terms with the same key refuse.
+`checkouts.get(id)` recovers the frozen snapshot. These methods do not sign.
+
+`checkouts.prepare({ checkoutId, sourceWallet })` returns exact unsigned approval
+and payment transactions. The consumer checks network, balance, gas, and allowance
+before requesting wallet action. A connection or submission is not settlement.
+
+`checkouts.state(id)` performs a checked read. It returns historical receipt data
+separately from current verification: `unpaid`, `verified`, `orphaned`, or
+`unavailable`. Provider failure cannot prove that a receipt was removed.
+`checkouts.reconcile({ checkoutId, transactionHash })` returns the candidate result
+and independently checked stored state. An unrelated candidate cannot change a
+valid stored payment. Canonical occurrence correction retains logical identity.
+
+These offer methods do not implement recurring billing.
+`checkouts.payRegistered({ checkoutId, payer, permissionId? })` prepares, verifies,
+and submits through the existing registered signer. Account and Organization
+authority remain mandatory. Submission does not establish settlement. Public
+Invoice funding and frontend registered-payer adoption remain separate work.
+
+`isCheckoutSettlementConsumed(error, settlementId)` decodes the contract's refusal
+for the exact frozen ID. Use it for structured or raw RPC errors. Error message
+text alone does not establish that an ID was consumed.
+
+## Invoice checkout candidate
+
+`checkouts.invoice(linkToken)` exposes only the approved payment summary.
+Itemization, notes, billing identity and document bytes remain restricted to the
+issuer and named debtor. Funding does not change that debtor or grant document
+access. Existing link tokens resolve the original obligation.
+
+`prepareInvoice({ linkToken, sourceWallet })` returns unsigned transactions.
+`invoiceState(linkToken)` checks current receipt evidence. `reconcileInvoice`
+verifies an explicitly supplied transaction against the fixed terms. Late exact
+payments remain visible after expiry or cancellation. Conflicting consumption is
+unavailable, never paid, and does not create another settlement identity.
+
+`payInvoiceRegistered({ linkToken, payer, sourceWallet, permissionId? })` uses the
+existing registered signer. The selected Safe must match the backend's current
+spending authority. The response omits private source commands and document
+bundles. Existing private preparations retain their original settlement ID.
+
+`checkoutUrl(frontendOrigin, reference)` constructs an offer or Invoice route.
+The caller supplies the selected environment's frontend origin. The consumer
+still validates the reference and reads authoritative backend terms. Constructing
+a URL does not prove that its consumer is deployed.
+
+### Browser failure capture
+
+Use the optional `failureCapture` callback for a host-owned synchronous browser
+capture bridge. The callback receives immutable masked factory words only for
+the SDK's original typed failure. Omission preserves current capture behavior.
+See [Configure SDK observability](../../apps/docs/content/docs/sdk/how-to/observation.mdx#browser-failure-capture)
+for the fixed message paths and host privacy contract.