@capxul/sdk 4.2.0 → 4.20.0-beta.1

package/dist/testing/index.d.mts

@@ -1,5 +1,85 @@
-import { $n as TelemetryGroupInput, Qn as TelemetryEvent, dr as IdentityTransition, er as TelemetryIdentifyInput, n as ObservationAdapter, u as CapxulClient } from "../observation-vegBPfXj.mjs";
+import { h as CapxulResult } from "../OAuthBearerAuthClient-C-ip-z8M.mjs";
+import { er as TelemetryEvent, f as CapxulClient, i as ObservationAdapter, n as ProductionSignerControls, nr as TelemetryIdentifyInput, pr as IdentityTransition, t as CapxulClientInput, tr as TelemetryGroupInput } from "../production-DvGDNIwu.mjs";
 import { Effect, Layer } from "effect";
+//#region src/testing/production-client.d.ts
+/** Create the one production client with per-client controls at its signing boundaries. */
+declare function createCapxulProductionTestClient(input: CapxulClientInput, controls: ProductionSignerControls): Promise<CapxulResult<CapxulClient>>;
+//#endregion
+//#region src/testing/signer-faults.d.ts
+/**
+ * Which provider refusal to inject. The codes are the ones the SDK's own
+ * classifiers decode (`src/signer.ts`), so a fault reaches the public error
+ * contract through the real decode path rather than a shortcut.
+ *
+ * - `missing-signer` — Openfort's typed not-ready code. `openfortSignerNotReadyCode`
+ *   decodes it, so the production recovery wrapper runs its single retry (A02).
+ * - `user-rejected` — the EIP-1193 4001 result. `signerFailure` decodes it to
+ *   `SIGNER_REJECTED`, an expected refusal (A08).
+ * - `unexpected` — no provider code at all, so it stays an unexpected
+ *   `PROVIDER_ERROR` (A09).
+ */
+type SignerFaultKind = "missing-signer" | "user-rejected" | "unexpected";
+/** The value a controlled fault throws. Named so a test can assert its origin. */
+declare class ControlledSignerFault extends Error {
+  readonly kind: SignerFaultKind;
+  /** Provider code the SDK classifiers read; absent for `unexpected`. */
+  readonly code: string | number | undefined;
+  constructor(kind: SignerFaultKind);
+}
+/** Build one fault value without the harness, for a caller that writes its own control. */
+declare function signerFaultCause(kind: SignerFaultKind): ControlledSignerFault;
+interface SignerFaultPlan {
+  /**
+   * Fault the next embedded signature ONCE, beneath the production recovery
+   * wrapper, then delegate every later call to the real signer. The address
+   * read and the readiness cycle still run first, so the fault lands at the
+   * actual final signing boundary after the prepared-command equality checks.
+   */
+  readonly signOnce?: SignerFaultKind;
+  /**
+   * Call the production signer's own `resetSession()` ONCE, immediately before
+   * the next signature and after the command is prepared. The delegate then
+   * re-runs the real readiness cycle, so the configure request under test is
+   * the first one the browser observes after the `reset-session` record (A03).
+   *
+   * Throws when the composed signer owns no session — a silently skipped reset
+   * would leave the run looking green while proving nothing.
+   */
+  readonly resetSessionBeforeNextSign?: boolean;
+}
+/** What the seam did. JSON-serializable, so a browser test can read it back. */
+interface SignerSeamRecord {
+  readonly boundary: "reset-session" | "embedded-sign";
+  /** 1-based count of calls at that boundary. */
+  readonly attempt: number;
+  readonly hash?: string;
+  /** Present only on the call that actually threw. */
+  readonly fault?: SignerFaultKind;
+  readonly atMs: number;
+}
+interface ArmedSignerSeam {
+  /** Hand these to `createCapxulProductionTestClient`. */
+  readonly controls: ProductionSignerControls;
+  /** Oldest first. Empty until the client reaches a signing boundary. */
+  readonly records: () => readonly SignerSeamRecord[];
+  /** True once every armed one-shot has fired. */
+  readonly spent: () => boolean;
+}
+/**
+ * Arm one-shot faults on the production embedded signer.
+ *
+ * ```ts
+ * const seam = armSignerFaults({ signOnce: "user-rejected" });
+ * const client = await createCapxulProductionTestClient(input, seam.controls);
+ * const result = await client.org(orgId).permissions.create(command);
+ * // result.error.code === "SIGNER_REJECTED"; nothing was submitted.
+ * // seam.records() names the boundary that refused.
+ * ```
+ *
+ * An empty plan installs no controls, which composes the ordinary client.
+ */
+declare function armSignerFaults(plan?: SignerFaultPlan): ArmedSignerSeam;
+//#endregion
 //#region src/testing/telemetry/RecordingTelemetryAdapter.d.ts
 type RecordingTelemetryOperation = {
   readonly type: "emit";
@@ -51,4 +131,4 @@ interface CapxulTestObservation {
  */
 declare function createCapxulTestClient(options?: CreateCapxulTestClientOptions): CapxulTestClient;
 //#endregion
-export { CapxulTestClient, CapxulTestClock, CapxulTestObservation, CreateCapxulTestClientOptions, SeedTestIdentityInput, createCapxulTestClient };
+export { type ArmedSignerSeam, CapxulTestClient, CapxulTestClock, CapxulTestObservation, ControlledSignerFault, CreateCapxulTestClientOptions, type ProductionSignerControls, SeedTestIdentityInput, type SignerFaultKind, type SignerFaultPlan, type SignerSeamRecord, armSignerFaults, createCapxulProductionTestClient, createCapxulTestClient, signerFaultCause };

package/dist/testing/index.mjs

@@ -1,8 +1,105 @@
-import { M as fromWei, Z as redactTelemetryEvent, f as identityErrorFromCapxul, g as bootstrapErrorFromCapxul, i as smartAccountErrorFromCapxul, m as convexCallErrorFromCapxul, o as accountReadErrorFromCapxul, t as assembleCapxulClient, u as wireChainId, v as toWei } from "../create-capxul-client-B6PUjdld.mjs";
-import { $ as CapxulError, A as toAuthUserId, B as toJwtToken, D as toAddress, E as toAccountId, F as toDurationMs, I as toEmail, J as toSessionToken, K as toPublishableKey, L as toEpochMs, M as toChainId, N as toCountryCode, O as toAllowedOrigin, R as toEpochSeconds, V as toKycTier, _ as deriveCapxulSafeAddress, k as toAppId, n as InMemoryAuthCacheAdapter, t as readClockNow, tt as Errors, u as authClientPortFromPromiseAdapter, v as validateHandle, z as toHandle } from "../clock-DIfTX44d.mjs";
-import { Effect, Result, Semaphore } from "effect";
+import { D as fromWei, P as redactTelemetryEvent, a as smartAccountErrorFromCapxul, c as identityErrorFromCapxul, i as assembleCapxulClient, l as convexCallErrorFromCapxul, n as createCapxulClientWithSignerControls, o as accountReadErrorFromCapxul, s as wireChainId, u as bootstrapErrorFromCapxul, v as toWei } from "../production-BmsFhDUr.mjs";
+import { G as toHandle, H as toEmail, I as toAuthUserId, K as toJwtToken, M as toAddress, N as toAllowedOrigin, P as toAppId, Q as toPublishableKey, R as toChainId, U as toEpochMs, V as toDurationMs, W as toEpochSeconds, ct as CapxulError, d as authClientPortFromPromiseAdapter, et as toSessionToken, it as validateHandle, j as toAccountId, n as readClockNow, q as toKycTier, r as InMemoryAuthCacheAdapter, ut as Errors, y as deriveCapxulSafeAddress, z as toCountryCode } from "../OAuthBearerAuthClient-DDD0JlaI.mjs";
 import { keccak256 } from "viem";
+import { Effect, Result, Semaphore } from "effect";
 import { getFunctionName } from "convex/server";
+//#region src/testing/production-client.ts
+/** Create the one production client with per-client controls at its signing boundaries. */
+function createCapxulProductionTestClient(input, controls) {
+	return createCapxulClientWithSignerControls(input, controls);
+}
+//#endregion
+//#region src/testing/signer-faults.ts
+const FAULT_CODES = {
+	"missing-signer": "MISSING_SIGNER",
+	"user-rejected": 4001,
+	unexpected: void 0
+};
+/** The value a controlled fault throws. Named so a test can assert its origin. */
+var ControlledSignerFault = class extends Error {
+	kind;
+	/** Provider code the SDK classifiers read; absent for `unexpected`. */
+	code;
+	constructor(kind) {
+		super(`controlled signer fault (${kind})`);
+		this.name = "ControlledSignerFault";
+		this.kind = kind;
+		this.code = FAULT_CODES[kind];
+	}
+};
+/** Build one fault value without the harness, for a caller that writes its own control. */
+function signerFaultCause(kind) {
+	return new ControlledSignerFault(kind);
+}
+/**
+* Arm one-shot faults on the production embedded signer.
+*
+* ```ts
+* const seam = armSignerFaults({ signOnce: "user-rejected" });
+* const client = await createCapxulProductionTestClient(input, seam.controls);
+* const result = await client.org(orgId).permissions.create(command);
+* // result.error.code === "SIGNER_REJECTED"; nothing was submitted.
+* // seam.records() names the boundary that refused.
+* ```
+*
+* An empty plan installs no controls, which composes the ordinary client.
+*/
+function armSignerFaults(plan = {}) {
+	const records = [];
+	let pendingFault = plan.signOnce;
+	let pendingReset = plan.resetSessionBeforeNextSign === true;
+	let resetCalls = 0;
+	let embeddedCalls = 0;
+	function record(entry) {
+		records.push({
+			...entry,
+			atMs: Date.now()
+		});
+	}
+	const resetThenSign = async (hash, signer) => {
+		if (pendingReset) {
+			pendingReset = false;
+			resetCalls += 1;
+			if (signer.resetSession === void 0) throw new Error("armSignerFaults: resetSessionBeforeNextSign needs the embedded browser signer; this client composed a signer with no session");
+			signer.resetSession();
+			record({
+				boundary: "reset-session",
+				attempt: resetCalls,
+				hash
+			});
+		}
+		return signer.signUserOpHash(hash);
+	};
+	const faultThenDelegate = async (hash, delegate) => {
+		embeddedCalls += 1;
+		const fault = pendingFault;
+		if (fault === void 0) {
+			record({
+				boundary: "embedded-sign",
+				attempt: embeddedCalls,
+				hash
+			});
+			return delegate(hash);
+		}
+		pendingFault = void 0;
+		record({
+			boundary: "embedded-sign",
+			attempt: embeddedCalls,
+			hash,
+			fault
+		});
+		throw signerFaultCause(fault);
+	};
+	return {
+		controls: {
+			...plan.resetSessionBeforeNextSign === true ? { signUserOpHash: resetThenSign } : {},
+			...plan.signOnce === void 0 ? {} : { signEmbeddedUserOpHash: faultThenDelegate }
+		},
+		records: () => records.slice(),
+		spent: () => pendingFault === void 0 && !pendingReset
+	};
+}
+//#endregion
 //#region src/testing/account/InMemoryAccountReadAdapter.ts
 var InMemoryAccountReadAdapter = class {
 	#deps;
@@ -909,4 +1006,4 @@ function createCapxulTestClient(options = {}) {
 	};
 }
 //#endregion
-export { createCapxulTestClient };
+export { ControlledSignerFault, armSignerFaults, createCapxulProductionTestClient, createCapxulTestClient, signerFaultCause };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@capxul/sdk",
-  "version": "4.2.0",
+  "version": "4.20.0-beta.1",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/Xelmar-tech/infrastructure.git",
@@ -30,14 +30,14 @@
     "access": "public"
   },
   "dependencies": {
-    "@effect/platform-node": "4.0.0-beta.105",
+    "@effect/platform-node": "4.0.0-rc.112",
     "@openfort/openfort-js": "^1.3.6",
     "convex": "^1.39.1",
-    "effect": "4.0.0-beta.105",
+    "effect": "4.0.0-rc.112",
     "viem": "^2.53.1"
   },
   "devDependencies": {
-    "@effect/vitest": "4.0.0-beta.105",
+    "@effect/vitest": "4.0.0-rc.112",
     "@typescript/native": "npm:typescript@7.0.2",
     "@vitest/coverage-v8": "4.1.11",
     "fast-check": "^3.23.2",
@@ -48,11 +48,11 @@
     "vite-plus": "0.3.0",
     "vitest": "4.1.11",
     "@capxul/config": "0.3.0",
-    "@capxul/errors": "0.3.0",
     "@capxul/typescript-config": "0.0.0",
     "@capxul/types": "0.3.0",
-    "@capxul/wire": "0.7.0",
-    "@capxul/observability": "4.2.0"
+    "@capxul/errors": "0.3.0",
+    "@capxul/wire": "0.8.0-beta.0",
+    "@capxul/observability": "4.20.0-beta.1"
   },
   "_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": {

package/dist/OAuthBearerAuthClient-ByPzJZr8.mjs

@@ -1,211 +0,0 @@
-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-DIfTX44d.mjs";
-import { Effect, Layer } from "effect";
-//#region src/adapters/clock/SystemClockAdapter.ts
-var SystemClockAdapter = class {
-	now = Effect.try({
-		try: () => toEpochMs(Date.now()),
-		catch: (cause) => new ClockError({
-			operation: "now",
-			cause
-		})
-	});
-	sleep(duration) {
-		return Effect.callback((resume) => {
-			const timeout = setTimeout(() => resume(Effect.void), duration);
-			return Effect.sync(() => clearTimeout(timeout));
-		});
-	}
-};
-function SystemClockLayer() {
-	return Layer.succeed(ClockPortTag, new SystemClockAdapter());
-}
-//#endregion
-//#region src/adapters/auth-client/OAuthBearerAuthClient.ts
-const PROVIDER = "agent-exchange";
-/** Re-exchange this far ahead of expiry, matching the JWT cache eviction margin. */
-const REFRESH_MARGIN_MS = 3e4;
-/**
-* `AuthSession.token` is a Better Auth session handle. This flow has none, and
-* the access token must never be copied into it, so the slot holds a placeholder.
-*/
-const OAUTH_SESSION_TOKEN = toSessionToken("oauth-bearer");
-var OAuthBearerAuthClient = class {
-	#exchangeUrl;
-	#exchangeSecret;
-	#accessToken;
-	#fetchImpl;
-	#clock;
-	#cached = null;
-	constructor(input) {
-		this.#exchangeUrl = input.exchangeUrl;
-		this.#exchangeSecret = input.exchangeSecret;
-		this.#accessToken = input.accessToken;
-		this.#fetchImpl = input.fetch ?? fetch;
-		this.#clock = input.clock ?? new SystemClockAdapter();
-	}
-	async canSendOtp() {
-		return refuse("canSendOtp");
-	}
-	async sendOtp() {
-		return refuse("sendOtp");
-	}
-	async verifyOtp() {
-		return refuse("verifyOtp");
-	}
-	/**
-	* The authorization server owns the token's lifetime, so revoking it there is
-	* the sign-out. Reporting success here would claim a token was dropped.
-	*/
-	async signOut() {
-		return refuse("signOut");
-	}
-	/**
-	* The exchanged identity. Unlike the Better Auth adapters this never answers
-	* `null`: the consumer holds a usable access token or a refused one, and a
-	* refused one is a NOT_AUTHENTICATED failure, not the absence of a session.
-	*/
-	async getSession(options) {
-		const exchange = await this.#exchange("getSession", options);
-		if (!exchange.ok) return exchange;
-		return {
-			ok: true,
-			value: {
-				authUserId: toAuthUserId(exchange.value.authUserId),
-				email: toEmail(exchange.value.email),
-				token: OAUTH_SESSION_TOKEN,
-				expiresAt: toEpochMs(exchange.value.expiresAt)
-			}
-		};
-	}
-	async getConvexJwt(options) {
-		const exchange = await this.#exchange("getConvexJwt", options);
-		if (!exchange.ok) return exchange;
-		return {
-			ok: true,
-			value: {
-				token: toJwtToken(exchange.value.token),
-				expEpochSeconds: toEpochSeconds(Math.floor(exchange.value.expiresAt / 1e3))
-			}
-		};
-	}
-	/**
-	* The cached exchange while it is fresh, otherwise a new one. A failed
-	* exchange never replaces the cache, so a stale token is never served.
-	*
-	* lazy: no in-flight de-duplication — two concurrent reads past the margin
-	* each mint a JWT. Minting is idempotent, so the cost is one extra request.
-	*/
-	async #exchange(operation, options) {
-		if (options?.signal?.aborted) return {
-			ok: false,
-			error: Errors.cancelled({ operation })
-		};
-		const cached = this.#cached;
-		if (cached !== null && options?.forceRefresh !== true) {
-			const now = await readClockNow(this.#clock);
-			if (!now.ok) return now;
-			if (now.value < cached.expiresAt - REFRESH_MARGIN_MS) return {
-				ok: true,
-				value: cached
-			};
-		}
-		return this.#postExchange(operation, options?.signal);
-	}
-	async #postExchange(operation, signal) {
-		let res;
-		try {
-			res = await this.#fetchImpl(this.#exchangeUrl, {
-				method: "POST",
-				headers: {
-					"content-type": "application/json",
-					authorization: `Bearer ${this.#exchangeSecret}`
-				},
-				body: JSON.stringify({ accessToken: this.#accessToken }),
-				...signal === void 0 ? {} : { signal }
-			});
-		} catch (cause) {
-			return {
-				ok: false,
-				error: signal?.aborted === true || isAbortError(cause) ? Errors.cancelled({ operation }) : Errors.networkError(operation, cause)
-			};
-		}
-		if (signal?.aborted === true) return {
-			ok: false,
-			error: Errors.cancelled({ operation })
-		};
-		const body = await res.json().catch(() => null);
-		if (!res.ok) return {
-			ok: false,
-			error: exchangeRefused(operation, res.status, readErrorCode(body))
-		};
-		const exchange = readExchange(body);
-		if (exchange === null) return {
-			ok: false,
-			error: Errors.providerError(PROVIDER, operation, /* @__PURE__ */ new Error("unexpected body"), { httpStatus: res.status })
-		};
-		this.#cached = exchange;
-		return {
-			ok: true,
-			value: exchange
-		};
-	}
-};
-/**
-* `AuthClientPort` over the backend agent-token exchange. Build one per OAuth
-* access token and hand it to `createCapxulClient({ authClient })`.
-*/
-function oauthBearerAuthClient(input) {
-	return authClientPortFromPromiseAdapter(new OAuthBearerAuthClient(input));
-}
-/** The OTP verbs belong to the email flow; `validStates` names it for the caller. */
-function refuse(method) {
-	return {
-		ok: false,
-		error: Errors.wrongState({
-			method,
-			currentState: "oauth-bearer",
-			validStates: ["email-otp"]
-		})
-	};
-}
-/**
-* The error catalog has no FORBIDDEN code, so 403 (`insufficient_scope`) and
-* 503 (`exchange_unconfigured`) both land on PROVIDER_ERROR. `httpStatus` and
-* `details.reason` carry which one the backend reported. Only 401 becomes
-* NOT_AUTHENTICATED, because only 401 is answered by a new access token.
-*/
-function exchangeRefused(operation, status, reason) {
-	if (status === 401) return Errors.notAuthenticated("The exchange refused this OAuth access token");
-	return Errors.providerError(PROVIDER, operation, /* @__PURE__ */ new Error(`HTTP ${status}`), {
-		httpStatus: status,
-		...reason === void 0 ? {} : { details: { reason } }
-	});
-}
-/** An abort raised by something other than the caller's own signal. */
-function isAbortError(cause) {
-	return readField(cause, "name") === "AbortError";
-}
-function readErrorCode(body) {
-	const error = readField(body, "error");
-	return typeof error === "string" ? error : void 0;
-}
-function readField(value, key) {
-	if (typeof value !== "object" || value === null) return void 0;
-	return value[key];
-}
-function readExchange(body) {
-	if (typeof body !== "object" || body === null) return null;
-	const { token, expiresAt, authUserId, email } = body;
-	if (typeof token !== "string" || token.length === 0) return null;
-	if (typeof expiresAt !== "number" || !Number.isFinite(expiresAt)) return null;
-	if (typeof authUserId !== "string" || authUserId.length === 0) return null;
-	if (typeof email !== "string" || email.length === 0) return null;
-	return {
-		token,
-		expiresAt,
-		authUserId,
-		email
-	};
-}
-//#endregion
-export { SystemClockLayer as n, oauthBearerAuthClient as t };

package/dist/OAuthBearerAuthClient-D-DLYlKj.d.mts

@@ -1,19 +0,0 @@
-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`. */
-  readonly exchangeUrl: string;
-  /** The shared secret the exchange endpoint checks. The caller holds it. */
-  readonly exchangeSecret: string;
-  /** The agent's OAuth access token. */
-  readonly accessToken: string;
-  readonly fetch?: typeof fetch;
-  readonly clock?: ClockPort;
-}
-/**
- * `AuthClientPort` over the backend agent-token exchange. Build one per OAuth
- * access token and hand it to `createCapxulClient({ authClient })`.
- */
-declare function oauthBearerAuthClient(input: OAuthBearerAuthClientInput): AuthClientPort;
-//#endregion
-export { oauthBearerAuthClient as n, OAuthBearerAuthClientInput as t };