@capxul/sdk 2.8.0 → 3.0.0

package/dist/index.mjs

@@ -1,5 +1,6 @@
-import { A as postHogFailureObservation, B as injectedWalletSigner, C as fingerprintPaymentIntent, D as failureEvidenceProps, E as failureDetail, F as isSettingUpLifecycle, G as PAYMENT_DIRECTIONS, H as OBSERVATION_CONTEXT_HEADER, I as formatTraceparent, J as BootstrapEnvelope, K as PAYMENT_STATUSES, L as copyInvocationObservation, M as captureExceptionSync, N as version, O as observationContextProps, P as fromWei, Q as BASE_SEPOLIA_CHAIN_ID, R as readInvocationObservation, S as AuthClientPortTag, T as CAPXUL_SDK_EXPECTED_OUTCOME_EVENT, U as encodeObservationContextHeader, V as signerFailure, W as sanitizeObservationContext, X as CAPXUL_PAYMENTS_V2_ADDRESS, Y as EngineeringTelemetryBootstrapPolicy, Z as normalizeBindingEmail, _ as ClockPortTag, a as TelemetryPortTag, b as authClientPortFromPromiseAdapter, c as smartAccountErrorFromCapxul, d as wireChainId, et as destination, f as IdentityPortTag, g as ClockError, h as convexCallErrorFromCapxul, i as PostHogTelemetryLayer, j as captureException, k as observeFailedResult, l as AccountReadPortTag, m as ConvexCallPortTag, n as postHogProductTelemetry, nt as isRestoring, p as identityErrorFromCapxul, q as CAPXUL_FUNCTIONS, r as detectAuthCacheAdapter, s as SmartAccountPortTag, t as assembleCapxulClient, tt as isClaimed, u as accountReadErrorFromCapxul, v as BootstrapPortTag, w as toWei, x as AuthClientError, y as bootstrapErrorFromCapxul, z as causeChain } from "./create-capxul-client-YSN2yN8m.mjs";
-import { B as Errors, C as toDurationMs, D as toJwtToken, E as toEpochSeconds, F as toSessionToken, H as CHAIN_UPSTREAMS, I as decodeConvexError, L as CAPXUL_ERROR_CODES, N as toPublishableKey, O as toKycTier, P as toRoleKey, R as CapxulError, S as toCurrencyCode, T as toEpochMs, U as FAILURE_MODES, V as isCapxulError, b as toChainId, g as toAllowedOrigin, h as toAddress, k as toOrgId, m as toAccountId, o as AuthCachePortTag, p as currencySymbolFor, v as toAuthUserId, w as toEmail, x as toCountryCode } from "./InMemoryAuthCacheAdapter-FptQ2p7C.mjs";
+import { $ as EngineeringTelemetryBootstrapPolicy, A as normalizeExceptionErrorKind, B as isSignerNotReadySignal, C as failureDetail, D as postHogFailureObservation, E as observeFailedResult, F as fromWei, G as readInvocationObservation, H as signerFailure, I as isSettingUpLifecycle, J as sanitizeObservationContext, K as OBSERVATION_CONTEXT_HEADER, L as formatTraceparent, M as projectSdkException, N as safeExceptionLabel, O as EXCEPTION_MESSAGE, P as version, Q as BootstrapEnvelope, R as causeChain, S as CAPXUL_SDK_EXPECTED_OUTCOME_EVENT, T as observationContextProps, U as resolveFailureMode, V as openfortSignerNotReadyCode, W as copyInvocationObservation, X as PAYMENT_STATUSES, Y as PAYMENT_DIRECTIONS, Z as CAPXUL_FUNCTIONS, _ as convexCallErrorFromCapxul, a as AccountReadPortTag, b as fingerprintPaymentIntent, d as retryIdempotentRead, et as destination, f as PRODUCT_INVOCATION, g as ConvexCallPortTag, h as identityErrorFromCapxul, i as smartAccountErrorFromCapxul, j as normalizeExceptionOperation, k as SDK_VERSION$1, l as redactTelemetryProps, m as IdentityPortTag, n as detectAuthCacheAdapter, nt as isRestoring, o as accountReadErrorFromCapxul, p as wireChainId, q as encodeObservationContextHeader, r as SmartAccountPortTag, s as TelemetryPortTag, t as assembleCapxulClient, tt as isClaimed, u as stampTelemetryEnvelope, v as BootstrapPortTag, w as failureEvidenceProps, x as toWei, y as bootstrapErrorFromCapxul, z as injectedWalletSigner } from "./create-capxul-client-DwINzpXZ.mjs";
+import { $ as CHAIN_UPSTREAMS, B as toOrgId, D as toAllowedOrigin, E as toAddress, F as toEmail, G as toRoleKey, I as toEpochMs, J as CAPXUL_ERROR_CODES, K as toSessionToken, L as toEpochSeconds, M as toCountryCode, N as toCurrencyCode, P as toDurationMs, Q as isCapxulError, R as toJwtToken, T as toAccountId, W as toPublishableKey, Y as CapxulError, Z as Errors, d as AuthClientError, et as FAILURE_MODES, f as AuthClientPortTag, g as BASE_SEPOLIA_CHAIN_ID, h as normalizeBindingEmail, j as toChainId, k as toAuthUserId, l as ClockPortTag, m as CAPXUL_PAYMENTS_V2_ADDRESS, q as decodeConvexError, s as AuthCachePortTag, u as authClientPortFromPromiseAdapter, w as currencySymbolFor, z as toKycTier } from "./clock-0c5NM-TY.mjs";
+import { n as SystemClockLayer } from "./OAuthBearerAuthClient-BZ6tXt4m.mjs";
 import { keccak256, recoverAddress, stringToHex } from "viem";
 import { Cause, Context, Data, Duration, Effect, Exit, Layer, Result, Schedule, SchemaIssue, SchemaParser, Scope, Tracer } from "effect";
 import { getFunctionName, makeFunctionReference } from "convex/server";
@@ -1302,11 +1303,13 @@ async function safeText(res) {
 }
 var HttpBootstrapAdapter = class {
 	bootstrapBaseUrl;
+	bootstrapHost;
 	fetchImpl;
 	observation;
 	retry;
 	constructor(deps) {
 		this.bootstrapBaseUrl = deps.bootstrapBaseUrl.replace(/\/$/, "");
+		this.bootstrapHost = hostOf(this.bootstrapBaseUrl);
 		this.observation = deps.observation;
 		this.retry = deps.retry ?? DEFAULT_RETRY;
 		this.fetchImpl = deps.fetch ?? ((input, init) => globalThis.fetch(input, init));
@@ -1332,7 +1335,11 @@ var HttpBootstrapAdapter = class {
 					body: JSON.stringify({ publishableKey: input.publishableKey })
 				});
 			},
-			catch: (cause) => bootstrapErrorFromCapxul("network", Errors.networkError("bootstrap", cause))
+			catch: (cause) => bootstrapErrorFromCapxul("network", Errors.networkError("bootstrap", cause, {
+				provider: "bootstrap",
+				failure_mode: "upstream-down",
+				...this.bootstrapHost === void 0 ? {} : { target_host: this.bootstrapHost }
+			}))
 		}).pipe(Effect.flatMap((res) => this.mapResponse(res)));
 	}
 	mapResponse(res) {
@@ -1388,6 +1395,13 @@ var HttpBootstrapAdapter = class {
 function HttpBootstrapLayer(deps) {
 	return Layer.succeed(BootstrapPortTag, new HttpBootstrapAdapter(deps));
 }
+function hostOf(url) {
+	try {
+		return new URL(url).hostname;
+	} catch {
+		return;
+	}
+}
 function normalizeRuntimeUrl(field, raw) {
 	let parsed;
 	try {
@@ -1399,35 +1413,195 @@ function normalizeRuntimeUrl(field, raw) {
 	return parsed.toString().replace(/\/$/, "");
 }
 //#endregion
-//#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));
+//#region src/adapters/convex-call/convex-connection-monitor.ts
+var ConvexConnectionMonitor = class {
+	#connectionId = makeConnectionId();
+	#browser = new BrowserLifecycleMonitor();
+	#lastClose;
+	observedWebSocketConstructor() {
+		const NativeWebSocket = globalThis.WebSocket;
+		if (typeof globalThis.window === "undefined" || NativeWebSocket === void 0) return void 0;
+		return new Proxy(NativeWebSocket, { construct: (Target, args) => {
+			const socket = Reflect.construct(Target, args);
+			socket.addEventListener("close", (event) => {
+				this.#lastClose = this.#browser.socketClose(event);
+			});
+			return socket;
+		} });
+	}
+	close() {
+		this.#browser.close();
+	}
+	observe(client, observer) {
+		const subscribe = client.subscribeToConnectionState?.bind(client);
+		if (subscribe === void 0) return () => this.#browser.close();
+		let previous;
+		const unsubscribe = subscribe((next) => {
+			const diagnostics = this.#diagnostics(previous, next);
+			previous = next;
+			for (const diagnostic of diagnostics) emitDiagnostic(observer, diagnostic);
+		});
+		if (previous === void 0) {
+			const current = safeConnectionState(client);
+			if (current !== void 0) {
+				previous = current;
+				for (const diagnostic of this.#diagnostics(void 0, current)) emitDiagnostic(observer, diagnostic);
+			}
+		}
+		let closed = false;
+		return () => {
+			if (closed) return;
+			closed = true;
+			try {
+				unsubscribe();
+			} finally {
+				this.#browser.close();
+			}
+		};
+	}
+	reconnectEvidence(start, end) {
+		if (!connectionRestarted(start, end)) return void 0;
+		return {
+			kind: "connection-lost-in-flight",
+			connection_id: this.#connectionId,
+			start_connection_count: start.connectionCount,
+			connection_count: end.connectionCount,
+			...end.connectionRetries === void 0 ? {} : { connection_retries: end.connectionRetries },
+			...closeFields(this.#lastClose)
+		};
+	}
+	#diagnostics(previous, next) {
+		const transitions = connectionTransitions(previous, next);
+		if (transitions.length === 0) return [];
+		const oldest = next.timeOfOldestInflightRequest;
+		const oldestInflightMs = oldest instanceof Date && Number.isFinite(oldest.getTime()) ? Math.max(0, Date.now() - oldest.getTime()) : void 0;
+		return transitions.map((transition) => ({
+			connection_id: this.#connectionId,
+			transition,
+			previous_connected: previous?.isWebSocketConnected ?? false,
+			connected: next.isWebSocketConnected,
+			...next.hasEverConnected === void 0 ? {} : { has_ever_connected: next.hasEverConnected },
+			connection_count: next.connectionCount,
+			...next.connectionRetries === void 0 ? {} : { connection_retries: next.connectionRetries },
+			...next.hasInflightRequests === void 0 ? {} : { has_inflight_requests: next.hasInflightRequests },
+			...next.inflightActions === void 0 ? {} : { inflight_actions: next.inflightActions },
+			...next.inflightMutations === void 0 ? {} : { inflight_mutations: next.inflightMutations },
+			...oldestInflightMs === void 0 ? {} : { oldest_inflight_ms: oldestInflightMs },
+			...closeFields(this.#lastClose)
+		}));
+	}
+};
+function connectionRestarted(start, end) {
+	if (start === void 0 || end === void 0) return false;
+	const opensBeforeCancellation = start.isWebSocketConnected ? 1 : 2;
+	return end.connectionCount >= start.connectionCount + opensBeforeCancellation;
+}
+function connectionTransitions(previous, next) {
+	if (previous === void 0) {
+		if (next.isWebSocketConnected) return (next.connectionRetries ?? 0) > 0 ? ["retrying", "connected"] : ["connected"];
+		return (next.connectionRetries ?? 0) > 0 ? ["disconnected", "retrying"] : [];
+	}
+	const transitions = [];
+	if (previous.isWebSocketConnected !== next.isWebSocketConnected) transitions.push(next.isWebSocketConnected ? "connected" : "disconnected");
+	if ((next.connectionRetries ?? 0) > (previous.connectionRetries ?? 0)) transitions.push("retrying");
+	return transitions;
+}
+function emitDiagnostic(observer, diagnostic) {
+	try {
+		observer(diagnostic);
+	} catch {}
+}
+function safeConnectionState(client) {
+	try {
+		return client.connectionState?.();
+	} catch {
+		return;
+	}
+}
+function closeFields(close) {
+	if (close === void 0) return {};
+	return {
+		close_code: close.code,
+		close_was_clean: close.wasClean,
+		close_reason_present: close.reasonPresent,
+		...close.documentVisibility === void 0 ? {} : { document_visibility: close.documentVisibility },
+		...close.navigatorOnline === void 0 ? {} : { navigator_online: close.navigatorOnline },
+		...close.browserEvent === void 0 ? {} : { last_browser_event: close.browserEvent },
+		...close.msSinceBrowserEvent === void 0 ? {} : { ms_since_browser_event: close.msSinceBrowserEvent }
+	};
+}
+var BrowserLifecycleMonitor = class {
+	#listeners = [];
+	#last = {};
+	constructor() {
+		const windowTarget = eventTarget(globalThis.window);
+		const documentTarget = eventTarget(globalThis.document);
+		if (windowTarget === void 0 || documentTarget === void 0) return;
+		this.#listen(documentTarget, "visibilitychange", () => {
+			this.#record(globalThis.document?.visibilityState === "hidden" ? "visibility-hidden" : "visibility-visible");
 		});
+		this.#listen(windowTarget, "pagehide", () => this.#record("pagehide"));
+		this.#listen(windowTarget, "pageshow", () => this.#record("pageshow"));
+		this.#listen(windowTarget, "online", () => this.#record("online"));
+		this.#listen(windowTarget, "offline", () => this.#record("offline"));
+	}
+	socketClose(event) {
+		const now = Date.now();
+		return {
+			code: event.code,
+			wasClean: event.wasClean,
+			reasonPresent: event.reason.length > 0,
+			...this.#last.event === void 0 ? {} : { browserEvent: this.#last.event },
+			...this.#last.at === void 0 ? {} : { msSinceBrowserEvent: Math.max(0, now - this.#last.at) },
+			...globalThis.document?.visibilityState === void 0 ? {} : { documentVisibility: globalThis.document.visibilityState },
+			...globalThis.navigator?.onLine === void 0 ? {} : { navigatorOnline: globalThis.navigator.onLine }
+		};
+	}
+	close() {
+		for (const [target, name, listener] of this.#listeners) target.removeEventListener(name, listener);
+		this.#listeners.length = 0;
+	}
+	#listen(target, name, listener) {
+		target.addEventListener(name, listener);
+		this.#listeners.push([
+			target,
+			name,
+			listener
+		]);
+	}
+	#record(event) {
+		this.#last = {
+			event,
+			at: Date.now()
+		};
 	}
 };
-function SystemClockLayer() {
-	return Layer.succeed(ClockPortTag, new SystemClockAdapter());
+function eventTarget(value) {
+	if (typeof value !== "object" || value === null || !("addEventListener" in value) || typeof value.addEventListener !== "function" || !("removeEventListener" in value) || typeof value.removeEventListener !== "function") return;
+	return value;
+}
+let fallbackConnectionId = 0;
+function makeConnectionId() {
+	try {
+		return `convex_${globalThis.crypto.randomUUID()}`;
+	} catch {
+		fallbackConnectionId += 1;
+		return `convex_${Date.now().toString(36)}_${fallbackConnectionId.toString(36)}`;
+	}
 }
 //#endregion
 //#region src/adapters/convex-call/ConvexCallAdapter.ts
 /** Exact floor-first allowlist; every additional handler must migrate its validator first. */
 const OBSERVED_CONVEX_ACTIONS = /* @__PURE__ */ new Set([
+	"account/actions:readBalance",
+	"holdings/actions:current",
 	"smartAccount/actions:claim",
 	"org/actions:prepareFounderAccount",
 	"org/actions:prepareBootstrap",
 	"org/actions:submitBootstrap",
 	"org/actions:resumeBootstrapSubmission",
-	"org/actions:confirmBootstrap"
+	"org/actions:confirmBootstrap",
+	"org/actions:readTreasury"
 ]);
 const OBSERVED_CONVEX_QUERIES = /* @__PURE__ */ new Set([
 	"identity/queries:loadByAuthUserId",
@@ -1448,8 +1622,11 @@ var ConvexCallAdapter = class {
 	#tokenProvider;
 	#applicationId;
 	#observation;
+	#connectionMonitor;
 	constructor(deps) {
-		this.#client = deps.client ?? new ConvexClient(deps.convexUrl);
+		this.#connectionMonitor = new ConvexConnectionMonitor();
+		const webSocketConstructor = this.#connectionMonitor.observedWebSocketConstructor();
+		this.#client = deps.client ?? new ConvexClient(deps.convexUrl, webSocketConstructor === void 0 ? {} : { webSocketConstructor });
 		this.#tokenProvider = deps.tokenProvider;
 		this.#applicationId = deps.applicationId;
 		this.#observation = deps.observation;
@@ -1458,6 +1635,9 @@ var ConvexCallAdapter = class {
 	refreshAuth() {
 		if (this.#tokenProvider) this.#client.setAuth(this.#tokenProvider);
 	}
+	observeConnection(observer) {
+		return this.#connectionMonitor.observe(this.#client, observer);
+	}
 	query(fn, args) {
 		const path = getFunctionName(fn);
 		return Effect.serviceOption(Tracer.ParentSpan).pipe(Effect.flatMap((parent) => {
@@ -1482,10 +1662,14 @@ var ConvexCallAdapter = class {
 		const path = getFunctionName(fn);
 		return Effect.serviceOption(Tracer.ParentSpan).pipe(Effect.flatMap((parent) => {
 			const traceparent = parent._tag === "Some" ? formatTraceparent(parent.value) : void 0;
+			const connectionAtStart = connectionState(this.#client);
 			return Effect.tryPromise({
 				try: () => this.#client.action(fn, this.#observedArgs(OBSERVED_CONVEX_ACTIONS, path, args, traceparent)),
-				catch: (cause) => mapToConvexCallError(path, cause)
-			});
+				catch: (cause) => {
+					const transport = this.#connectionMonitor.reconnectEvidence(connectionAtStart, connectionState(this.#client));
+					return mapToConvexCallError(path, cause, transport);
+				}
+			}).pipe(Effect.tapError((error) => logActionTransportFailure(path, error)));
 		}));
 	}
 	#observedArgs(allowlist, path, args, traceparent) {
@@ -1539,24 +1723,52 @@ var ConvexCallAdapter = class {
 		})));
 	}
 	async close() {
+		this.#connectionMonitor.close();
 		await this.#client.close();
 	}
 };
 function ConvexCallLayer(deps) {
 	return Layer.effect(ConvexCallPortTag, Effect.acquireRelease(Effect.sync(() => new ConvexCallAdapter(deps)), (adapter) => Effect.promise(() => adapter.close()).pipe(Effect.orDie)));
 }
-function mapToCapxulError(operation, err) {
+function mapToCapxulError(operation, err, transport) {
 	const decoded = decodeConvexError(err);
 	if (decoded !== null) return decoded;
 	if (err instanceof CapxulError) return err;
+	if (transport !== void 0) {
+		const { kind: _kind, start_connection_count: _start, ...connection } = transport;
+		return Errors.networkError(operation, err, {
+			provider: "convex",
+			failure_mode: "upstream-down",
+			reason: "connection-lost-in-flight",
+			...connection
+		});
+	}
 	if (err instanceof Error) {
-		if (isTransportError(err)) return Errors.networkError(operation, err);
+		if (isTransportError(err)) return Errors.networkError(operation, err, { provider: "convex" });
 		return Errors.providerError("convex", operation, err);
 	}
 	return Errors.providerError("convex", operation, new Error(String(err)));
 }
-function mapToConvexCallError(operation, err) {
-	return convexCallErrorFromCapxul(operation, mapToCapxulError(operation, err));
+function mapToConvexCallError(operation, err, transport) {
+	return convexCallErrorFromCapxul(operation, mapToCapxulError(operation, err, transport), transport);
+}
+function connectionState(client) {
+	try {
+		const state = client.connectionState?.();
+		return typeof state?.connectionCount === "number" ? state : void 0;
+	} catch {
+		return;
+	}
+}
+function logActionTransportFailure(operation, error) {
+	if (error.transport === void 0) return Effect.void;
+	const { kind, ...connection } = error.transport;
+	return Effect.logWarning("convex.action.connection_lost").pipe(Effect.annotateLogs({
+		operation,
+		failure_mode: "upstream-down",
+		reason: kind,
+		...connection
+	}), Effect.catchCause(() => Effect.void));
 }
 const TRANSPORT_ERROR_CODES = /* @__PURE__ */ new Set([
 	"EAI_AGAIN",
@@ -1647,12 +1859,14 @@ const DEFAULT_FUNCTIONS$3 = {
 var ConvexAccountAdapter = class {
 	#convex;
 	#fns;
+	#telemetry;
 	constructor(deps) {
 		this.#convex = deps.convex;
 		this.#fns = deps.functions ?? DEFAULT_FUNCTIONS$3;
+		this.#telemetry = deps.telemetry;
 	}
 	readBalance(input) {
-		return this.#convex.action(this.#fns.readBalance, { chainId: wireChainId(input.chainId) }).pipe(Effect.mapError((error) => accountReadErrorFromCapxul("readBalance", error.publicError, error)), Effect.flatMap((wire) => brandAccountEffect("readBalance", wire)), Effect.catchDefect((cause) => Effect.fail(accountReadErrorFromUnknown("readBalance", cause))));
+		return retryIdempotentRead(this.#convex.action(this.#fns.readBalance, copyInvocationObservation(input, { chainId: wireChainId(input.chainId) })), "accounts.read", this.#telemetry, input).pipe(Effect.mapError((error) => accountReadErrorFromCapxul("readBalance", error.publicError, error)), Effect.flatMap((wire) => brandAccountEffect("readBalance", wire)), Effect.catchDefect((cause) => Effect.fail(accountReadErrorFromUnknown("readBalance", cause))));
 	}
 	fundFromFaucet(input) {
 		const operation = "fundFromFaucet";
@@ -1666,7 +1880,10 @@ var ConvexAccountAdapter = class {
 	}
 };
 function ConvexAccountLayer() {
-	return Layer.effect(AccountReadPortTag, Effect.map(ConvexCallPortTag, (convex) => new ConvexAccountAdapter({ convex })));
+	return Layer.effect(AccountReadPortTag, Effect.all([ConvexCallPortTag, TelemetryPortTag]).pipe(Effect.map(([convex, telemetry]) => new ConvexAccountAdapter({
+		convex,
+		telemetry
+	}))));
 }
 function brandAccountEffect(operation, wire) {
 	return Effect.try({
@@ -1901,15 +2118,17 @@ const DEFAULT_FUNCTIONS$1 = {
 var ConvexOrganizationAdapter = class {
 	#convex;
 	#fns;
+	#telemetry;
 	constructor(input) {
 		this.#convex = input.convex;
 		this.#fns = input.functions ?? DEFAULT_FUNCTIONS$1;
+		this.#telemetry = input.telemetry;
 	}
 	createOrg(_input) {
 		return Effect.fail(orgErrorFromCapxul("createOrg", Errors.notImplemented("organizationSetup", "use onboarding.completeOrganization")));
 	}
-	listOrgs(_input) {
-		return this.#convex.query(this.#fns.listAll, {}).pipe(Effect.mapError((error) => orgErrorFromCapxul("listOrgs", error.publicError, error)), Effect.flatMap((wires) => Effect.forEach(wires, (wire) => this.#readTreasuryWire(wire.orgId).pipe(Effect.map((treasury) => {
+	listOrgs(input) {
+		return this.#convex.query(this.#fns.listAll, copyInvocationObservation(input, {})).pipe(Effect.mapError((error) => orgErrorFromCapxul("listOrgs", error.publicError, error)), Effect.flatMap((wires) => Effect.forEach(wires, (wire) => this.#readTreasuryWire(copyInvocationObservation(input, { orgId: toOrgId(wire.orgId) })).pipe(Effect.map((treasury) => {
 			const viewerRole = wire.viewerRole.trim();
 			if (viewerRole.length === 0) throw Errors.wrongState({
 				method: "listOrgs",
@@ -1920,7 +2139,7 @@ var ConvexOrganizationAdapter = class {
 		})))), Effect.catchDefect((cause) => Effect.fail(toOrgError("listOrgs", cause))));
 	}
 	readTreasury(input) {
-		return this.#readTreasuryWire(String(input.orgId)).pipe(Effect.catchDefect((cause) => Effect.fail(toOrgError("readTreasury", cause))));
+		return this.#readTreasuryWire(input).pipe(Effect.catchDefect((cause) => Effect.fail(toOrgError("readTreasury", cause))));
 	}
 	listRoles(input) {
 		return this.#convex.query(this.#fns.listRoles, { orgId: input.orgId }).pipe(Effect.mapError((error) => orgErrorFromCapxul("listRoles", error.publicError, error)), Effect.flatMap((rows) => rows.length === 0 ? Effect.fail(partialOrgTruth("listRoles", "activeRoleMissing")) : Effect.succeed(rows.map(brandOrgRole))), Effect.catchDefect((cause) => Effect.fail(toOrgError("listRoles", cause))));
@@ -1947,8 +2166,9 @@ var ConvexOrganizationAdapter = class {
 	detectAndAcceptPendingInvitations(_input) {
 		return this.#convex.action(this.#fns.detectInvitations, {}).pipe(Effect.mapError((error) => orgErrorFromCapxul("detectAndAcceptPendingInvitations", error.publicError, error)), Effect.map((result) => ({ matched: result.matched.map(toOrgId) })), Effect.catchDefect((cause) => Effect.fail(toOrgError("detectAndAcceptPendingInvitations", cause))));
 	}
-	#readTreasuryWire(orgId) {
-		return this.#convex.action(this.#fns.readTreasury, { orgId }).pipe(Effect.mapError((error) => orgErrorFromCapxul("readTreasury", error.publicError, error)), Effect.map((wire) => {
+	#readTreasuryWire(input) {
+		const orgId = String(input.orgId);
+		return retryIdempotentRead(this.#convex.action(this.#fns.readTreasury, copyInvocationObservation(input, { orgId })), "org.treasury", this.#telemetry, input).pipe(Effect.mapError((error) => orgErrorFromCapxul("readTreasury", error.publicError, error)), Effect.map((wire) => {
 			if (wire.orgId !== orgId) throw Errors.invalidInput("orgId", "Organization treasury scope does not match");
 			const balance = fromWei(wire.rawBalance, wire.decimals, wire.currency);
 			const available = fromWei(wire.rawAvailableBalance, wire.decimals, wire.currency);
@@ -2239,6 +2459,90 @@ function fail(error) {
 	};
 }
 //#endregion
+//#region src/adapters/telemetry/PostHogTelemetryAdapter.ts
+var PostHogTelemetryAdapter = class {
+	#capture;
+	#identify;
+	#group;
+	#reset;
+	constructor(deps) {
+		this.#capture = deps.capture;
+		this.#identify = deps.identify ?? (() => void 0);
+		this.#group = deps.group ?? (() => void 0);
+		this.#reset = deps.reset ?? (() => void 0);
+	}
+	emit(event) {
+		return this.#run(() => this.#capture(event.name, redactTelemetryProps(event.name, cloneProps(event.props)), event), "emit", event.name);
+	}
+	identify(input) {
+		return this.#run(() => this.#identify(cloneIdentifyInput(input)), "identify");
+	}
+	group(input) {
+		return this.#run(() => this.#group(cloneGroupInput(input)), "group");
+	}
+	reset() {
+		return this.#run(() => this.#reset(), "reset");
+	}
+	#run(operation, operationName, eventName) {
+		const diagnose = Effect.logWarning("product.telemetry.transport.dropped").pipe(Effect.annotateLogs({
+			operation: operationName,
+			...eventName === void 0 ? {} : { product_event: eventName }
+		}), Effect.catchCause(() => Effect.void));
+		return Effect.suspend(() => {
+			let pending;
+			try {
+				pending = operation();
+			} catch {
+				return diagnose;
+			}
+			if (pending === void 0) return Effect.void;
+			const transport = Effect.tryPromise({
+				try: () => pending,
+				catch: () => void 0
+			}).pipe(Effect.catch(() => diagnose));
+			return Effect.forkDetach(transport, { startImmediately: true }).pipe(Effect.asVoid);
+		});
+	}
+};
+function PostHogTelemetryLayer(deps) {
+	return Layer.succeed(TelemetryPortTag, new PostHogTelemetryAdapter(deps));
+}
+function cloneIdentifyInput(input) {
+	const traits = input.traits === void 0 ? void 0 : cloneProps(input.traits);
+	const properties = input.properties === void 0 ? void 0 : cloneProps(input.properties);
+	return {
+		distinctId: input.distinctId,
+		...input.anonDistinctId === void 0 ? {} : { anonDistinctId: input.anonDistinctId },
+		...traits === void 0 ? {} : { traits },
+		...properties === void 0 ? {} : { properties }
+	};
+}
+function cloneGroupInput(input) {
+	const properties = input.properties === void 0 ? void 0 : cloneProps(input.properties);
+	return properties === void 0 ? {
+		groupType: input.groupType,
+		groupKey: input.groupKey
+	} : {
+		groupType: input.groupType,
+		groupKey: input.groupKey,
+		properties
+	};
+}
+function cloneProps(props) {
+	if (props === void 0) return void 0;
+	const cloned = {};
+	for (const [key, value] of Object.entries(props)) cloned[key] = cloneTelemetryValue(value);
+	return cloned;
+}
+function cloneTelemetryValue(value) {
+	if (Array.isArray(value)) return value.map(cloneTelemetryValue);
+	if (value === null || typeof value !== "object") return value;
+	if (Object.getPrototypeOf(value) !== Object.prototype) return value;
+	const cloned = {};
+	for (const [key, nested] of Object.entries(value)) cloned[key] = cloneTelemetryValue(nested);
+	return cloned;
+}
+//#endregion
 //#region src/adapters/diagnostic/ConsoleDiagnosticAdapter.ts
 const DEFAULT_ACCOUNT_SETUP_LOG_PREFIX = "[capxul:account-setup]";
 var ConsoleDiagnosticAdapter = class {
@@ -2564,8 +2868,59 @@ function createOpenfortBrowserSignerFromBootstrap(bootstrap, options = {}) {
 		embeddedWallet: openfort.embeddedWallet,
 		ensureWalletReady: ensureOpenfortWalletReady
 	});
+	const resetReadiness = () => {
+		walletReadyPromise = null;
+		clearStaleOpenfortBrowserStorage(bootstrap.openfortPublishableKey);
+		signer.resetAddressCache();
+		setStatus("unknown");
+	};
+	const signUserOpHash = async (hash) => {
+		try {
+			return await signer.signUserOpHash(hash);
+		} catch (cause) {
+			const providerErrorCode = openfortSignerNotReadyCode(cause);
+			if (providerErrorCode === void 0) throw cause;
+			diagnostic?.trace("openfort.signerRecovery", {
+				outcome: "started",
+				attempt: 1,
+				failure_mode: "signer-not-ready"
+			});
+			resetReadiness();
+			try {
+				await ensureOpenfortWalletReady();
+				const signature = await signer.signUserOpHash(hash);
+				diagnostic?.trace("openfort.signerRecovery", {
+					outcome: "succeeded",
+					attempt: 1,
+					failure_mode: "signer-not-ready"
+				});
+				return signature;
+			} catch (retryCause) {
+				const retryFailure = signerFailure("openfort-embedded", "signUserOpHash", retryCause);
+				if (retryFailure.code === "SIGNER_REJECTED") throw retryFailure;
+				if (isSignerNotReadySignal(retryCause)) {
+					walletReadyPromise = null;
+					signer.resetAddressCache();
+					setStatus("unavailable");
+				}
+				diagnostic?.trace("openfort.signerRecovery", {
+					outcome: "failed",
+					attempt: 1,
+					failure_mode: isSignerNotReadySignal(retryCause) ? "signer-not-ready" : "unknown"
+				});
+				throw Errors.providerError("openfort", "signerRecovery", retryCause, {
+					failure_mode: "signer-not-ready",
+					details: {
+						provider_error_source: "openfort",
+						provider_error_code: providerErrorCode
+					}
+				});
+			}
+		}
+	};
 	return {
 		...signer,
+		signUserOpHash,
 		statusStore,
 		ensureWalletReady: ensureOpenfortWalletReady,
 		getAddress: async () => {
@@ -2581,12 +2936,7 @@ function createOpenfortBrowserSignerFromBootstrap(bootstrap, options = {}) {
 				throw openfortProviderError("getAddress", cause);
 			}
 		},
-		resetSession: () => {
-			walletReadyPromise = null;
-			clearStaleOpenfortBrowserStorage(bootstrap.openfortPublishableKey);
-			signer.resetAddressCache();
-			setStatus("unknown");
-		}
+		resetSession: resetReadiness
 	};
 }
 function normalizeBetterAuthBaseUrl(raw) {
@@ -2594,6 +2944,73 @@ function normalizeBetterAuthBaseUrl(raw) {
 	return trimmed.endsWith("/api/auth") ? trimmed : `${trimmed}/api/auth`;
 }
 //#endregion
+//#region src/telemetry/from-posthog.ts
+/**
+* Drop props that must never cross to a host-owned external sink. Today that is
+* the `$exception` `details` blob: `captureException` serializes
+* `CapxulError.details` (e.g. `{ asset, available, required }`, `{ name }`,
+* `{ accountId }` — errors.ts) into it, and the shared redactor has no
+* `$exception` rule, so it is stripped here at the boundary (infra#1037). The
+* safe fields (error code, operation, failure_mode, the fixed leak-safe message,
+* stack frames) are preserved.
+*/
+function stripHostUnsafeProps(props) {
+	if (props === void 0) return void 0;
+	const { details: _details, ...safe } = props;
+	return safe;
+}
+/**
+* The subset of a posthog-js client the seam calls. `identify` / `group` /
+* `reset` are optional — a host that only wants event capture can omit them.
+*/
+/**
+* Adapt the host's already-initialized posthog-like client into a
+* `TelemetryPort` for the `telemetry` prop / input. This port SUPPLANTS the
+* SDK's no-op default telemetry sink (`production.ts` binds it via
+* `Layer.succeed`, not `compose` — there is no client-side success relay to
+* compose with); it is additive to Capxul's backend first-party record and
+* never owns the client.
+*/
+function postHogProductTelemetry(policy, fixedSnapshot) {
+	const telemetry = new PostHogTelemetryAdapter({
+		capture: (name, props, source) => {
+			const snapshot = readInvocationObservation(source) ?? fixedSnapshot ?? policy.snapshot();
+			if (!snapshot.active || policy.client === null || policy.client === void 0) return;
+			const event = stampTelemetryEnvelope({
+				name,
+				props
+			}, {
+				capxul_env: policy.capxulEnv,
+				producer: "sdk"
+			});
+			policy.deliver(() => policy.client.capture(name, {
+				...stripHostUnsafeProps(event.props),
+				...observationContextProps(snapshot.context)
+			}));
+		},
+		identify: (input) => {
+			if (!(fixedSnapshot ?? policy.snapshot()).active || policy.client?.identify === void 0) return;
+			policy.deliver(() => policy.client.identify(input.distinctId, {
+				...input.traits,
+				...input.properties
+			}));
+		},
+		group: (input) => {
+			if (!(fixedSnapshot ?? policy.snapshot()).active || policy.client?.group === void 0) return;
+			policy.deliver(() => policy.client.group(input.groupType, input.groupKey, input.properties === void 0 ? void 0 : { ...input.properties }));
+		},
+		reset: () => {
+			if (!(fixedSnapshot ?? policy.snapshot()).active || policy.client?.reset === void 0) return;
+			policy.deliver(() => policy.client.reset());
+		}
+	});
+	Object.defineProperty(telemetry, PRODUCT_INVOCATION, {
+		enumerable: false,
+		value: (source) => postHogProductTelemetry(policy, readInvocationObservation(source) ?? fixedSnapshot ?? policy.snapshot())
+	});
+	return telemetry;
+}
+//#endregion
 //#region src/host-observability.ts
 const HOST_INVOCATION = Symbol("capxul.host-observability-invocation");
 /** Build the SDK's one host module around an already-initialized PostHog client. */
@@ -2732,7 +3149,10 @@ function makeProductionAdapterLayerEntries(input) {
 		},
 		{
 			name: "org",
-			layer: Layer.effect(OrgPortTag, Effect.map(ConvexCallPortTag, (convex) => new ConvexOrganizationAdapter({ convex })))
+			layer: Layer.effect(OrgPortTag, Effect.all([ConvexCallPortTag, TelemetryPortTag]).pipe(Effect.map(([convex, telemetry]) => new ConvexOrganizationAdapter({
+				convex,
+				telemetry
+			}))))
 		}
 	];
 }
@@ -2741,10 +3161,13 @@ function mergeProductionAdapterLayers(entries) {
 	for (const entry of entries) byName.set(entry.name, entry.layer);
 	const authClientLayer = byName.get("authClient");
 	const convexCallLayer = byName.get("convexCall");
+	const telemetryLayer = byName.get("telemetry");
 	const convexCallReadyLayer = convexCallLayer === void 0 || authClientLayer === void 0 ? convexCallLayer : convexCallLayer.pipe(Layer.provide(authClientLayer));
+	const observedConvexCallLayer = convexCallReadyLayer === void 0 ? telemetryLayer : telemetryLayer === void 0 ? convexCallReadyLayer : Layer.merge(convexCallReadyLayer, telemetryLayer);
 	return entries.map((entry) => {
 		const layer = byName.get(entry.name) ?? entry.layer;
 		if (entry.name === "convexCall") return convexCallReadyLayer ?? layer;
+		if (entry.name === "accountRead" || entry.name === "org") return observedConvexCallLayer === void 0 ? layer : layer.pipe(Layer.provide(observedConvexCallLayer));
 		if (isConvexDependentLayer(entry.name)) return convexCallReadyLayer === void 0 ? layer : layer.pipe(Layer.provide(convexCallReadyLayer));
 		return layer;
 	}).reduce((current, layer) => Layer.merge(current, layer), Layer.empty);
@@ -2756,7 +3179,7 @@ function productionBootstrapPortLayer(bootstrap) {
 	return Layer.succeed(BootstrapPortTag, bootstrap);
 }
 function productionAuthClientLayer(input, refreshConvexAuthRef, resetSignerSessionRef) {
-	return (input.runtime === "browser" ? BetterAuthBrowserLayer({
+	return (input.authClient !== void 0 ? Layer.succeed(AuthClientPortTag, input.authClient) : input.runtime === "browser" ? BetterAuthBrowserLayer({
 		authBaseUrl: input.runtimeUrls.authBaseUrl,
 		...input.fetch === void 0 ? {} : { fetch: input.fetch },
 		...input.observation === void 0 ? {} : { observation: input.observation }
@@ -2897,6 +3320,7 @@ async function createProductionAdapters(input) {
 			applicationId: bootstrapResult.value.applicationId,
 			...observation === void 0 ? {} : { observation },
 			...input.authCache === void 0 ? {} : { authCache: input.authCache },
+			...input.authClient === void 0 ? {} : { authClient: input.authClient },
 			...telemetry === void 0 ? {} : { telemetry },
 			...injectedClient === void 0 ? {} : { convexClient: injectedClient },
 			...input.fetch === void 0 ? {} : { fetch: input.fetch },
@@ -2905,13 +3329,22 @@ async function createProductionAdapters(input) {
 		}));
 		const applicationLayer = Layer.merge(portsLayer, optionalEngineeringTelemetryLayer(bootstrapResult.value.engineeringTelemetry, resolvedInput.value.runtime));
 		const context = await Effect.runPromise(Layer.buildWithScope(applicationLayer, scope));
+		const ports = await Effect.runPromise(collectProductionFlowPorts.pipe(Effect.provide(context)));
+		const stopConnectionObservation = observeProductionConvexConnection(ports.convexCall, context);
+		const close = idempotentClose(async () => {
+			try {
+				stopConnectionObservation();
+			} finally {
+				await closeScope();
+			}
+		});
 		return {
 			ok: true,
 			value: {
 				context,
-				ports: await Effect.runPromise(collectProductionFlowPorts.pipe(Effect.provide(context))),
+				ports,
 				bootstrap: bootstrapResult.value,
-				close: closeScope
+				close
 			}
 		};
 	} catch (cause) {
@@ -2922,6 +3355,18 @@ async function createProductionAdapters(input) {
 		};
 	}
 }
+function observeProductionConvexConnection(convexCall, context) {
+	if (!("observeConnection" in convexCall) || typeof convexCall.observeConnection !== "function") return () => {};
+	const runPromise = Effect.runPromiseWith(context);
+	try {
+		return convexCall.observeConnection((diagnostic) => {
+			const message = diagnostic.transition === "connected" ? Effect.logInfo("convex.connection.changed") : Effect.logWarning("convex.connection.changed");
+			runPromise(message.pipe(Effect.annotateLogs(diagnostic), Effect.catchCause(() => Effect.void))).catch(() => void 0);
+		});
+	} catch {
+		return () => {};
+	}
+}
 function optionalEngineeringTelemetryLayer(policy, runtime) {
 	if (policy === void 0) return Layer.empty;
 	try {
@@ -3204,4 +3649,155 @@ async function createCapxulClient(input) {
 	return createCapxulClient$1(input);
 }
 //#endregion
+//#region src/telemetry/stack-frame-parser.ts
+/**
+* Regex for V8/Chrome stack trace frame lines.
+* Matches:
+*   `at functionName (url:line:col)`
+*   `at url:line:col`
+*   `at async functionName (url:line:col)`
+*   `at new ClassName (url:line:col)`
+*/
+const V8_FRAME_RE = /^\s*at\s+(?:(.+?)\s+\()?(?:(.+?)(?::(\d+):(\d+))?|(.+?))\)?\s*$/;
+function isNonUrlName(name) {
+	return name === "<anonymous>" || name.startsWith("eval") || name.startsWith("new ") || name.startsWith("async ");
+}
+/**
+* Parse a V8/Chrome-style stack trace string into PostHog `ExceptionFrame` objects.
+* Returns an empty array when `error.stack` is absent or empty.
+*
+* Handles:
+* - Standard `at functionName (url:line:col)`
+* - Bare `at url:line:col` (no function name)
+* - `at async functionName (url:line:col)`
+* - `at new ClassName (url:line:col)`
+* - Native frames: `at Array.forEach (<anonymous>)`
+*/
+function parseV8StackFrames(error) {
+	const stack = error.stack;
+	if (stack === void 0 || stack === null || stack === "") return [];
+	const lines = stack.split("\n");
+	const frames = [];
+	for (const line of lines) {
+		const trimmed = line.trim();
+		if (!trimmed.startsWith("at ")) continue;
+		const match = V8_FRAME_RE.exec(trimmed);
+		if (match === null) continue;
+		if (match[1] !== void 0) frames.push({
+			function: match[1],
+			filename: match[2],
+			lineno: match[3] !== void 0 ? Number(match[3]) : null,
+			colno: match[4] !== void 0 ? Number(match[4]) : null
+		});
+		else if (match[2] !== void 0 && !isNonUrlName(match[2])) frames.push({
+			function: "<anonymous>",
+			filename: match[2],
+			lineno: match[3] !== void 0 ? Number(match[3]) : null,
+			colno: match[4] !== void 0 ? Number(match[4]) : null
+		});
+		else frames.push({
+			function: match[1] ?? match[2] ?? match[5] ?? "<anonymous>",
+			filename: match[2] ?? match[5] ?? "<anonymous>",
+			lineno: match[3] !== void 0 ? Number(match[3]) : null,
+			colno: match[4] !== void 0 ? Number(match[4]) : null
+		});
+	}
+	return frames;
+}
+/** Fixed, leak-safe frame used when the error carries no parseable stack. */
+const SDK_BOUNDARY_FILENAME = "capxul-sdk-observation://boundary";
+/**
+* Build PostHog's `$exception_list` (always a single entry). Error Tracking
+* groups on `type`, so it is ALWAYS present (the CapxulError code) — the
+* previous `[{ frames }]` shape omitted it and PostHog dropped the event as
+* "missing field `type`". When the error has no parseable stack, a synthetic
+* boundary frame stands in so the event still ingests as a real Issue (#1031).
+*/
+function buildExceptionList(input) {
+	const frames = input.frames.length > 0 ? input.frames : [{
+		filename: SDK_BOUNDARY_FILENAME,
+		function: input.operation ?? "unknown",
+		lineno: 1,
+		colno: 1
+	}];
+	return [{
+		type: input.type,
+		value: input.value,
+		mechanism: {
+			handled: true,
+			type: "capxul_sdk_boundary"
+		},
+		stacktrace: { frames }
+	}];
+}
+//#endregion
+//#region src/telemetry/capture-exception.ts
+/**
+* Capture an error as a `$exception` event through the telemetry port,
+* formatted for PostHog Error Tracking.
+*
+* Parses stack traces into `$exception_list` format, extracts structured
+* metadata from CapxulError objects, and supplements with context props.
+* Fire-and-forget: telemetry defects are silently swallowed.
+* Returns `Effect<void, never>` for use in Effect pipelines; the underlying
+* adapter work is synchronous, so callers outside Effect contexts can
+* use `Effect.runSync`.
+*/
+function captureException(telemetry, error, context) {
+	return Effect.catchDefect(Effect.sync(() => {
+		const frames = error instanceof Error ? parseV8StackFrames(error) : [];
+		const capxulError = isCapxulError(error) ? error : null;
+		const errorCode = normalizeExceptionErrorKind(capxulError?.code ?? context?.capxul_error_code);
+		const { chain_provider_message: _providerMessage, chain_revert_args: _revertArguments, ...safeDetail } = failureDetail(error) ?? {};
+		const operation = normalizeExceptionOperation(context?.operation ?? safeDetail.provider_operation);
+		const failureMode = resolveFailureMode(error, context?.failure_mode);
+		const detail = {
+			...safeDetail,
+			failure_mode: failureMode
+		};
+		const properties = {
+			capxul_error_code: errorCode,
+			...detail,
+			error_message: EXCEPTION_MESSAGE,
+			error_details: detail,
+			error_cause: detail.reason ?? failureMode,
+			layer: safeExceptionLabel(capxulError?.layer ?? context?.layer),
+			provider: detail.provider ?? safeExceptionLabel(context?.provider)
+		};
+		for (const key of Object.keys(properties)) if (properties[key] === void 0) delete properties[key];
+		const props = projectSdkException({
+			properties,
+			sdkVersion: SDK_VERSION$1,
+			operation,
+			errorKind: errorCode,
+			failureMode,
+			message: EXCEPTION_MESSAGE,
+			issueDescription: detail.reason ?? failureMode,
+			...detail.chain_upstream === void 0 ? {} : { chainUpstream: detail.chain_upstream },
+			...detail.chain_method === void 0 ? {} : { chainMethod: detail.chain_method },
+			exceptionList: buildExceptionList({
+				type: errorCode,
+				value: EXCEPTION_MESSAGE,
+				operation,
+				frames
+			})
+		});
+		return telemetry.emit({
+			name: "$exception",
+			props
+		});
+	}).pipe(Effect.flatten), () => Effect.void);
+}
+/**
+* Synchronous fire-and-forget capture. Runs the Effect inline with
+* `Effect.runSync` so callers outside an Effect context can report errors
+* without awaiting. Core SDK public methods use the assembled observation
+* boundary instead.
+*/
+function captureExceptionSync(telemetry, error, context) {
+	try {
+		Effect.runSync(captureException(telemetry, error, context));
+	} catch {}
+}
+//#endregion
 export { CAPXUL_ERROR_CODES, CAPXUL_PAYMENTS_V2_ADDRESS, CAPXUL_SDK_EXPECTED_OUTCOME_EVENT, CHAIN_UPSTREAMS, CapxulError, Errors, FAILURE_MODES, PAYMENT_DIRECTIONS, PAYMENT_STATUSES, captureException, captureExceptionSync, createCapxulClient, deriveDevPrivateKey, devPrivateKeySigner, eip1193AccountProvider, embeddedSigner, fingerprintPaymentIntent, formatMoney, inboxPhase, injectedWalletSigner, isCapxulError, isClaimed, isMoneyParseError, isRestoring, isSettingUpLifecycle, localPrivateKeyAccountProvider, openfortEmbeddedSigner, openfortEmbeddedSignerFromWallet, openfortEmbeddedWalletPort, parseMoney, paymentPhase, postHogObservability, requestPhase, destination as resolveIdentityDestination, toCountryCode, toAddress as toEvmAddress };