@capxul/sdk 3.1.0 → 4.0.0

package/README.md

@@ -90,14 +90,20 @@ 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.
 
-Onboarding uses explicit domain objects. Personal completion accepts
-`{ profile }`; Organization completion accepts independently validated
-`{ profile, organization }`. The latter makes the Member Profile and personal
-Account/Safe ready before the first Organization write, then returns the exact
-`orgId` and its `OrgLifecycle`. A failed lifecycle after creation is returned
-with that `orgId`; Organization-list timing is not a success gate.
-Public Profile reads include the durable `onboarded` flag and optional
-`withdrawalAddress`, and `toEvmAddress` validates form-sourced withdrawal values.
+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.
 
 ## Published entry points
 
@@ -105,7 +111,7 @@ 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.
+  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,

package/dist/{OAuthBearerAuthClient-DfS4QOg7.mjs → OAuthBearerAuthClient-BHvDR8_0.mjs}

@@ -1,4 +1,4 @@
-import { F as toEmail, I as toEpochMs, K as toSessionToken, L as toEpochSeconds, R as toJwtToken, Z as Errors, c as ClockError, k as toAuthUserId, l as ClockPortTag, t as readClockNow, u as authClientPortFromPromiseAdapter } from "./clock-m_aHLaNm.mjs";
+import { A as toAuthUserId, B as toJwtToken, I as toEmail, J as toSessionToken, L as toEpochMs, R as toEpochSeconds, c as ClockError, l as ClockPortTag, t as readClockNow, tt as Errors, u as authClientPortFromPromiseAdapter } from "./clock-C2AUlq1V.mjs";
 import { Effect, Layer } from "effect";
 //#region src/adapters/clock/SystemClockAdapter.ts
 var SystemClockAdapter = class {

package/dist/{OAuthBearerAuthClient-BxTiv8dg.d.mts → OAuthBearerAuthClient-D-DLYlKj.d.mts}

@@ -1,4 +1,4 @@
-import { _ as ClockPort, v as AuthClientPort } from "./signer-BpjdawiY.mjs";
+import { _ as ClockPort, v as AuthClientPort } from "./signer-C0hZ6Kiy.mjs";
 //#region src/adapters/auth-client/OAuthBearerAuthClient.d.ts
 interface OAuthBearerAuthClientInput {
   /** The exchange endpoint: `{authBaseUrl}/api/auth/agent/exchange`. */

package/dist/{clock-m_aHLaNm.mjs → clock-C2AUlq1V.mjs}

@@ -1,5 +1,5 @@
-import { concat, encodeAbiParameters, encodeFunctionData, encodePacked, getContractAddress, keccak256, padHex, stringToHex, toBytes, toEventSelector, toFunctionSelector, toFunctionSignature } from "viem";
 import { Context, Data, Effect, Layer, Result } from "effect";
+import { concat, encodeAbiParameters, encodeFunctionData, encodePacked, getContractAddress, keccak256, padHex, stringToHex, toBytes, toEventSelector, toFunctionSelector, toFunctionSignature } from "viem";
 //#region ../errors/src/secret-material.ts
 const SENSITIVE_MATERIAL_PATTERNS = [
 	/(?:^|[^a-fA-F0-9])(?<!0[xX])[a-fA-F0-9]{64}(?:$|[^a-fA-F0-9])/u,
@@ -601,6 +601,10 @@ function decodeConvexError(err) {
 	return null;
 }
 //#endregion
+//#region ../errors/src/index.ts
+/** Canonical handle syntax shared by validation and branded constructors. */
+const HANDLE_RE = /^[a-z0-9_-]{3,30}$/;
+//#endregion
 //#region ../types/src/index.ts
 const EVM_ADDRESS_RE = /^0x[0-9a-f]{40}$/i;
 const BYTES32_RE = /^0x[0-9a-f]{64}$/i;
@@ -661,6 +665,10 @@ function toPartyId(raw) {
 	if (typeof raw !== "string" || !PARTY_ID_RE.test(raw)) throw Errors.invalidInput("partyId", invalidValueReason("must be party_ plus an alphanumeric id", raw));
 	return raw;
 }
+function toHandle(raw) {
+	if (typeof raw !== "string" || !HANDLE_RE.test(raw)) throw Errors.invalidInput("handle", invalidValueReason("must be 3-30 characters of a-z, 0-9, underscore, or hyphen", raw));
+	return raw;
+}
 function toBudgetId(raw) {
 	return toNonEmptyStringBrand(raw, "budgetId");
 }
@@ -718,6 +726,10 @@ function currencySymbolFor(code) {
 	if (symbol === void 0) throw Errors.invalidInput("currencyCode", `no symbol registered for "${String(code)}"`);
 	return symbol;
 }
+function toTesterKind(raw) {
+	if (raw !== "human" && raw !== "e2e" && raw !== "agent") throw Errors.invalidInput("testerKind", "must be human, e2e, or agent");
+	return raw;
+}
 function toKycTier(raw) {
 	if (typeof raw !== "number" || !Number.isInteger(raw) || raw < 0 || raw > 3) throw Errors.invalidInput("kycTier", invalidValueReason("must be an integer in [0, 3]", raw));
 	return raw;
@@ -757,6 +769,27 @@ function invalidValueReason(prefix, raw) {
 	return `${prefix}: ${String(raw)}`;
 }
 //#endregion
+//#region ../config/src/handle.ts
+const RESERVED_HANDLES = /* @__PURE__ */ new Set([
+	"admin",
+	"api",
+	"capxul",
+	"help",
+	"root",
+	"support",
+	"system",
+	"www"
+]);
+function normalizeHandle(raw) {
+	return raw.trim().toLowerCase().replace(/^@/, "");
+}
+function validateHandle(raw) {
+	const handle = normalizeHandle(raw);
+	if (!HANDLE_RE.test(handle)) throw Errors.invalidInput("handle", "must be 3-30 characters of a-z, 0-9, underscore, or hyphen");
+	if (RESERVED_HANDLES.has(handle)) throw Errors.invalidInput("handle", "handle is reserved");
+	return handle;
+}
+//#endregion
 //#region ../config/src/tokens.ts
 /** `TestUSDC` ("USDX") — Base Sepolia, 6 decimals, open `mint`. (Canon §1.) */
 const USDX_ADDRESS_BASE_SEPOLIA = "0xf09fcbb6df9f8f918e58f9c8ab15a76ade862b77";
@@ -1857,4 +1890,4 @@ async function readClockNow(clock) {
 	}
 }
 //#endregion
-export { CHAIN_UPSTREAMS as $, toBudgetId as A, toOrgId as B, ZERO_BYTES32 as C, toAllowedOrigin as D, toAddress as E, toEmail as F, toRoleKey as G, toPayrollGroupId as H, toEpochMs as I, CAPXUL_ERROR_CODES as J, toSessionToken as K, toEpochSeconds as L, toCountryCode as M, toCurrencyCode as N, toAppId as O, toDurationMs as P, isCapxulError as Q, toJwtToken as R, WEI_RE as S, toAccountId as T, toPayrollRunId as U, toPartyId as V, toPublishableKey as W, EXPECTED_OPERATION_OUTCOMES as X, CapxulError as Y, Errors as Z, deriveCapxulSafeAddress as _, parseCachedJwt as a, failureFingerprint as at, EVM_ADDRESS_RE as b, ClockError as c, revertSummaryText as ct, AuthClientError as d, FAILURE_MODES as et, AuthClientPortTag as f, BASE_SEPOLIA_CHAIN_ID as g, normalizeBindingEmail as h, parseAuthSession as i, decodeChainCause as it, toChainId as j, toAuthUserId as k, ClockPortTag as l, containsSensitiveMaterial as lt, CAPXUL_PAYMENTS_V2_ADDRESS as m, InMemoryAuthCacheAdapter as n, chainCauseProperties as nt, AuthCacheError as o, isChainUpstream as ot, orgRoleKeyForLabel as p, decodeConvexError as q, BrowserAuthCacheAdapter as r, chainEvidenceLabel as rt, AuthCachePortTag as s, isFailureMode as st, readClockNow as t, boundedResponseHeaders as tt, authClientPortFromPromiseAdapter as u, redactSecrets as ut, APP_ID_RE as v, currencySymbolFor as w, SUPPORTED_CURRENCY_CODES as x, BYTES32_RE as y, toKycTier as z };
+export { CapxulError as $, toAuthUserId as A, toJwtToken as B, WEI_RE as C, toAddress as D, toAccountId as E, toDurationMs as F, toPayrollRunId as G, toOrgId as H, toEmail as I, toSessionToken as J, toPublishableKey as K, toEpochMs as L, toChainId as M, toCountryCode as N, toAllowedOrigin as O, toCurrencyCode as P, CAPXUL_ERROR_CODES as Q, toEpochSeconds as R, SUPPORTED_CURRENCY_CODES as S, currencySymbolFor as T, toPartyId as U, toKycTier as V, toPayrollGroupId as W, HANDLE_RE as X, toTesterKind as Y, decodeConvexError as Z, deriveCapxulSafeAddress as _, parseCachedJwt as a, boundedResponseHeaders as at, BYTES32_RE as b, ClockError as c, decodeChainCause as ct, AuthClientError as d, isFailureMode as dt, EXPECTED_OPERATION_OUTCOMES as et, AuthClientPortTag as f, revertSummaryText as ft, BASE_SEPOLIA_CHAIN_ID as g, normalizeBindingEmail as h, parseAuthSession as i, FAILURE_MODES as it, toBudgetId as j, toAppId as k, ClockPortTag as l, failureFingerprint as lt, CAPXUL_PAYMENTS_V2_ADDRESS as m, redactSecrets as mt, InMemoryAuthCacheAdapter as n, isCapxulError as nt, AuthCacheError as o, chainCauseProperties as ot, orgRoleKeyForLabel as p, containsSensitiveMaterial as pt, toRoleKey as q, BrowserAuthCacheAdapter as r, CHAIN_UPSTREAMS as rt, AuthCachePortTag as s, chainEvidenceLabel as st, readClockNow as t, Errors as tt, authClientPortFromPromiseAdapter as u, isChainUpstream as ut, validateHandle as v, ZERO_BYTES32 as w, EVM_ADDRESS_RE as x, APP_ID_RE as y, toHandle as z };