@capxul/sdk 0.0.0-rc-2cdddbb91

package/README.md

@@ -0,0 +1,417 @@
+# `@capxul/sdk`
+
+The imperative TypeScript client for Capxul. It owns the public
+`createCapxulClient` factory, domain method bundles, production adapter assembly,
+and the internal Effect-based ports and flows that those methods bridge.
+
+```ts
+import { createCapxulClient } from "@capxul/sdk";
+
+const created = await createCapxulClient({
+  publishableKey: process.env.CAPXUL_PUBLISHABLE_KEY!,
+  requirement: "counterfactual",
+});
+
+if (!created.ok) throw created.error;
+const client = created.value;
+```
+
+Every public operation resolves a `Promise<CapxulResult<T>>`. Domain failures
+are values, not thrown exceptions.
+
+After the Person and personal Account are ready, begin Organization setup and
+store its exact ID before signer interaction:
+
+```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
+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
+
+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(formatAssetAmount(amount)); // 1,000.25 USDC
+}
+```
+
+`parseAssetAmount` returns validation errors as values. Payment, request,
+Budget, Payroll, and activity amounts require AssetAmount. Fiat Money remains
+separate valuation data.
+
+## Value all asset positions
+
+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, valueIn } from "@capxul/sdk";
+
+const valuation = valueIn(amounts, displayCurrency, rates);
+if (valuation.total !== null) {
+  console.log(formatMoney(valuation.total));
+}
+```
+
+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
+
+Hosts can attach the PostHog client they already initialized through one
+product-and-failure module:
+
+```ts
+import { postHogObservability } from "@capxul/sdk";
+
+const created = await createCapxulClient({
+  publishableKey: "cap_pk_…",
+  observability: postHogObservability(posthog, {
+    capxulEnv: "production",
+    context: () => ({ correlationId, journeyId, organizationId }),
+  }),
+});
+```
+
+The SDK initializes no analytics client and preserves host consent. Product
+events and sanitized failures share one enable/context/delivery policy.
+Engineering logs and traces are separate internally, but applications do not
+configure them: the versioned bootstrap response optionally supplies the
+governed PostHog ingest origin, public project token, and environment. The SDK
+derives endpoints, service, producer, and version. Missing or invalid policy
+disables engineering export without failing client creation.
+
+Person onboarding is one Core SDK journey. It requires a normalized, globally
+unique handle before it writes the Profile or starts Account setup:
+
+```ts
+const onboarded = await client.onboarding.completePerson({
+  displayName: "Ada Lovelace",
+  country: "GH",
+  handle: "ada_lovelace",
+});
+```
+
+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:
+
+- `@capxul/sdk` — the client factory, public method and value types, signers,
+  host observability helper, and immutable Base Sepolia Payment contract
+  identity. It also re-exports the canonical Capxul operation vocabulary.
+- `@capxul/sdk/node` — Node-only signer and runtime helpers.
+- `@capxul/sdk/testing` — the real identity runtime assembled over
+  deterministic in-memory ports, with OTP, advance-only clock, transition,
+  observation, seed, and close controls for tests.
+
+The many extra subpaths in `package.json#exports` are workspace development
+surfaces. Do not show them in consumer examples unless `publishConfig.exports`
+also contains them.
+
+```ts
+import { createCapxulTestClient } from "@capxul/sdk/testing";
+
+const testing = createCapxulTestClient();
+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");
+if (!otp) throw new Error("expected a test OTP");
+await testing.client.auth.verifyOtp({ email: "test@example.test", code: otp });
+// Drive the real public client, then inspect testing.transitions.
+await testing.close();
+```
+
+The seeded email is bound to the requested auth user ID, so verifying its OTP
+loads that exact seeded Profile. The public clock exposes only `advance(ms)`;
+the internal clock adapter and its Effect/conformance methods remain private.
+The testing entry is identity-scoped and hermetic. Fine-grained
+`@capxul/sdk/testing/*` adapter paths remain workspace-only.
+
+## Documentation
+
+- [Maintainer context](./CONTEXT.md) — ownership, boundaries, invariants,
+  evidence, and update triggers.
+- [Architecture](./docs/architecture.md) — client assembly, flows, ports,
+  adapters, and proof map.
+- [Observation](./docs/observation.md) — unified host observability,
+  bootstrap-owned engineering policy, and bounded backend linkage.
+- [Public SDK documentation](../../apps/docs/content/docs/sdk/index.mdx) —
+  tutorials, guides, reference, and explanation for npm consumers.
+
+React integration is a separate projection owned by `@capxul/sdk-react`.
+
+## Development
+
+Run package commands through Vite+:
+
+```bash
+vp run --filter @capxul/sdk check-types
+vp run --filter @capxul/sdk test
+vp run --filter @capxul/sdk build
+vp run --filter @capxul/sdk proofs:live
+```
+
+`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.
+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.