@capxul/sdk 2.5.5 → 2.6.0

package/dist/{InMemoryAuthCacheAdapter-uOcqpqu8.mjs → InMemoryAuthCacheAdapter-VZBv1fOH.mjs}

@@ -1,4 +1,135 @@
 import { Context, Data, Effect, Layer } from "effect";
+//#region ../errors/src/chain-cause.ts
+/**
+* Why an operation failed — the one flat vocabulary. The first four are the
+* auth/provider diagnoses that predate this file. The rest name the chain
+* path. `FailureMode` is derived from this list so a runtime membership check
+* (the SDK's `$exception` projection, the observability schema) and the type
+* can never drift apart.
+*/
+const FAILURE_MODES = [
+	"auth-origin-mismatch",
+	"stale-openfort-cache",
+	"app-env-allowlist",
+	"no-secure-context",
+	"rate-limited",
+	"timeout",
+	"upstream-down",
+	"revert",
+	"insufficient-balance",
+	"insufficient-allowance",
+	"rejected",
+	"unauthorized",
+	"unknown"
+];
+function isFailureMode(value) {
+	return typeof value === "string" && FAILURE_MODES.includes(value);
+}
+/** Who answered. `alto` is the bundler; `gateway` is the AA gateway's own logic. */
+const CHAIN_UPSTREAMS = [
+	"alchemy",
+	"infura",
+	"public",
+	"alto",
+	"gateway"
+];
+function isChainUpstream(value) {
+	return typeof value === "string" && CHAIN_UPSTREAMS.includes(value);
+}
+const PROVIDER_MESSAGE_MAX = 300;
+const METHOD_MAX = 64;
+const REVERT_NAME_MAX = 64;
+const REVERT_ARG_KEY_MAX = 32;
+const REVERT_ARG_VALUE_MAX = 128;
+const REVERT_ARGS_MAX = 8;
+const SELECTOR_RE = /^0x(?:[0-9a-fA-F]{8})?$/u;
+const MASKS = [
+	[/\bBearer\s+[^\s,;]+/giu, "Bearer [REDACTED]"],
+	[/\beyJ[A-Za-z0-9_-]+\.[A-Za-z0-9_-]+\.[A-Za-z0-9_-]+\b/gu, "[REDACTED]"],
+	[/\b0x[a-fA-F0-9]{40,}\b/gu, "[REDACTED]"],
+	[/(^|[^a-fA-F0-9])[a-fA-F0-9]{64}(?=$|[^a-fA-F0-9])/gu, "$1[REDACTED]"],
+	[/(?:(?:sk|pk|rk)_(?:live|test)|(?:phc|phx|ghp|gho|ghu|ghs|ghr|whsec)_|github_pat_|xox[baprs]-|AKIA[0-9A-Z]{16}|AIza)[A-Za-z0-9_-]*/giu, "[REDACTED]"],
+	[/(https?:\/\/[^\s"']+?\/v[0-9]\/)[A-Za-z0-9_-]{16,}/giu, "$1[REDACTED]"],
+	[/\b(api[ _-]?key|access[ _-]?token|token|secret|password|passphrase|private[ _-]?key|authorization|cookie|signature|credential|otp)\b\s*[:=]\s*(?:"[^"]*"|'[^']*'|[^\s,;&]+)/giu, "$1=[REDACTED]"]
+];
+/** Mask credential-shaped content, then cap the length. Total on any string. */
+function boundedEvidence(value, max) {
+	let text = value;
+	for (const [pattern, replacement] of MASKS) text = text.replace(pattern, replacement);
+	return text.length <= max ? text : text.slice(0, max);
+}
+function isRecord(value) {
+	return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function decodeRevert(value) {
+	if (!isRecord(value)) return null;
+	if (value.name !== null && typeof value.name !== "string") return null;
+	if (typeof value.selector !== "string" || !SELECTOR_RE.test(value.selector)) return null;
+	if (!isRecord(value.args)) return null;
+	const args = {};
+	for (const [key, arg] of Object.entries(value.args).slice(0, REVERT_ARGS_MAX)) {
+		if (typeof arg !== "string") return null;
+		args[boundedEvidence(key, REVERT_ARG_KEY_MAX)] = boundedEvidence(arg, REVERT_ARG_VALUE_MAX);
+	}
+	return {
+		name: value.name === null ? null : boundedEvidence(value.name, REVERT_NAME_MAX),
+		selector: value.selector,
+		args
+	};
+}
+/**
+* Decode a `ChainCause` from untrusted wire data (gateway JSON-RPC `error.data`,
+* a Convex error payload). Every string is masked and bounded; an unrecognized
+* shape yields null, because a consumer must never invent a cause.
+*/
+function decodeChainCause(value) {
+	if (!isRecord(value)) return null;
+	if (!isFailureMode(value.mode) || !isChainUpstream(value.upstream)) return null;
+	if (typeof value.method !== "string" || typeof value.retryable !== "boolean") return null;
+	const cause = {
+		mode: value.mode,
+		upstream: value.upstream,
+		method: boundedEvidence(value.method, METHOD_MAX),
+		retryable: value.retryable
+	};
+	if (typeof value.httpStatus === "number" && Number.isInteger(value.httpStatus)) cause.httpStatus = value.httpStatus;
+	if (typeof value.rpcCode === "number" && Number.isInteger(value.rpcCode)) cause.rpcCode = value.rpcCode;
+	const revert = decodeRevert(value.revert);
+	if (revert !== null) cause.revert = revert;
+	if (typeof value.providerMessage === "string") cause.providerMessage = boundedEvidence(value.providerMessage, PROVIDER_MESSAGE_MAX);
+	return cause;
+}
+/**
+* The cause as flat PostHog properties. Same keys from every producer, so one
+* filter (`failure_mode = 'rate-limited'`) finds the gateway's, the backend's,
+* and the SDK's rows alike.
+*/
+function chainCauseProperties(chain) {
+	return {
+		failure_mode: chain.mode,
+		chain_upstream: chain.upstream,
+		chain_method: chain.method,
+		chain_retryable: chain.retryable,
+		...chain.httpStatus === void 0 ? {} : { chain_http_status: chain.httpStatus },
+		...chain.rpcCode === void 0 ? {} : { chain_rpc_code: chain.rpcCode },
+		...chain.revert === void 0 ? {} : {
+			chain_revert_name: chain.revert.name ?? "unknown",
+			chain_revert_selector: chain.revert.selector,
+			chain_revert_args: chain.revert.args
+		},
+		...chain.providerMessage === void 0 ? {} : { chain_provider_message: chain.providerMessage }
+	};
+}
+/**
+* The error-tracking fingerprint for a failure: the code, the one-word cause,
+* and the operation. PostHog groups `$exception` rows by this value, so one
+* issue is one cause at one operation instead of every provider failure in
+* one bucket (money-path audit 2026-09-02, row P1).
+*/
+function failureFingerprint(code, mode, operation) {
+	return `${code}:${mode ?? "none"}:${operation}`;
+}
+//#endregion
 //#region ../errors/src/errors.ts
 const CAPXUL_ERROR_CODES = [
 	"NOT_AUTHENTICATED",
@@ -60,6 +191,10 @@ var CapxulError = class extends Error {
 	details;
 	correlationId;
 	layer;
+	/** The one-word cause (`FailureMode`). `chain.mode` when a chain cause is set. */
+	mode;
+	/** The structured chain-path cause. Never rewritten by a later layer. */
+	chain;
 	constructor(code, message, options = {}) {
 		super(message, "cause" in options ? { cause: options.cause } : void 0);
 		this.name = "CapxulError";
@@ -67,6 +202,10 @@ var CapxulError = class extends Error {
 		if (options.details !== void 0) this.details = options.details;
 		if (options.correlationId !== void 0) this.correlationId = options.correlationId;
 		if (options.layer !== void 0) this.layer = options.layer;
+		const legacy = options.details?.failure_mode;
+		const mode = options.chain?.mode ?? (isFailureMode(options.mode) ? options.mode : void 0) ?? (isFailureMode(legacy) ? legacy : void 0);
+		if (mode !== void 0) this.mode = mode;
+		if (options.chain !== void 0) this.chain = options.chain;
 	}
 };
 function isCapxulError(value) {
@@ -76,7 +215,9 @@ function deserializeCapxulError(serialized) {
 	return new CapxulError(serialized.code, serialized.message, compactErrorOptions({
 		details: serialized.details,
 		correlationId: serialized.correlationId,
-		layer: serialized.layer
+		layer: serialized.layer,
+		mode: serialized.mode,
+		chain: serialized.chain === void 0 ? void 0 : decodeChainCause(serialized.chain) ?? void 0
 	}));
 }
 function compactErrorOptions(options) {
@@ -85,6 +226,8 @@ function compactErrorOptions(options) {
 	if (options.details !== void 0) result.details = options.details;
 	if (options.correlationId !== void 0) result.correlationId = options.correlationId;
 	if (options.layer !== void 0) result.layer = options.layer;
+	if (options.mode !== void 0) result.mode = options.mode;
+	if (options.chain !== void 0) result.chain = options.chain;
 	return result;
 }
 const Errors = {
@@ -100,11 +243,14 @@ const Errors = {
 			provider,
 			operation
 		};
-		if (opts?.failure_mode) details.failure_mode = opts.failure_mode;
+		const mode = opts?.chain?.mode ?? opts?.failure_mode;
+		if (mode !== void 0) details.failure_mode = mode;
 		if (opts?.httpStatus !== void 0) details.httpStatus = opts.httpStatus;
 		return new CapxulError("PROVIDER_ERROR", `Provider error: ${provider} ${operation}`, {
 			cause,
-			details
+			details,
+			...mode === void 0 ? {} : { mode },
+			...opts?.chain === void 0 ? {} : { chain: opts.chain }
 		});
 	},
 	capabilityUnavailable: (provider, operation) => new CapxulError("CAPABILITY_UNAVAILABLE", "Provider capability is unavailable", { details: {
@@ -209,12 +355,18 @@ function isCapxulCode(value) {
 }
 function reconstruct(serialized) {
 	if (!isCapxulCode(serialized.code)) return null;
-	return deserializeCapxulError({
+	const payload = {
 		code: serialized.code,
 		message: typeof serialized.message === "string" ? serialized.message : String(serialized.code),
 		...typeof serialized.details === "object" && serialized.details !== null && !Array.isArray(serialized.details) ? { details: serialized.details } : {},
 		...typeof serialized.correlationId === "string" ? { correlationId: serialized.correlationId } : {},
-		...typeof serialized.layer === "string" ? { layer: serialized.layer } : {}
+		...typeof serialized.layer === "string" ? { layer: serialized.layer } : {},
+		...isFailureMode(serialized.mode) ? { mode: serialized.mode } : {}
+	};
+	const chain = decodeChainCause(serialized.chain);
+	return deserializeCapxulError(chain === null ? payload : {
+		...payload,
+		chain
 	});
 }
 function decodeConvexError(err) {
@@ -496,4 +648,4 @@ Layer.effect(AuthCachePortTag, Effect.sync(() => new InMemoryAuthCacheAdapter())
 	cause
 }))));
 //#endregion
-export { toPartyId as A, Errors as B, toDurationMs as C, toJwtToken as D, toEpochSeconds as E, toSessionToken as F, decodeConvexError as I, CAPXUL_ERROR_CODES as L, toPayrollRunId as M, toPublishableKey as N, toKycTier as O, toRoleKey as P, CapxulError as R, toCurrencyCode as S, toEpochMs as T, isCapxulError as V, toAppId as _, AuthCacheError as a, toChainId as b, BYTES32_RE as c, WEI_RE as d, ZERO_BYTES32 as f, toAllowedOrigin as g, toAddress as h, parseCachedJwt as i, toPayrollGroupId as j, toOrgId as k, EVM_ADDRESS_RE as l, toAccountId as m, BrowserAuthCacheAdapter as n, AuthCachePortTag as o, currencySymbolFor as p, parseAuthSession as r, APP_ID_RE as s, InMemoryAuthCacheAdapter as t, SUPPORTED_CURRENCY_CODES as u, toAuthUserId as v, toEmail as w, toCountryCode as x, toBudgetId as y, EXPECTED_OPERATION_OUTCOMES as z };
+export { toPartyId as A, Errors as B, toDurationMs as C, toJwtToken as D, toEpochSeconds as E, toSessionToken as F, failureFingerprint as G, CHAIN_UPSTREAMS as H, decodeConvexError as I, isFailureMode as K, CAPXUL_ERROR_CODES as L, toPayrollRunId as M, toPublishableKey as N, toKycTier as O, toRoleKey as P, CapxulError as R, toCurrencyCode as S, toEpochMs as T, FAILURE_MODES as U, isCapxulError as V, chainCauseProperties as W, toAppId as _, AuthCacheError as a, toChainId as b, BYTES32_RE as c, WEI_RE as d, ZERO_BYTES32 as f, toAllowedOrigin as g, toAddress as h, parseCachedJwt as i, toPayrollGroupId as j, toOrgId as k, EVM_ADDRESS_RE as l, toAccountId as m, BrowserAuthCacheAdapter as n, AuthCachePortTag as o, currencySymbolFor as p, parseAuthSession as r, APP_ID_RE as s, InMemoryAuthCacheAdapter as t, SUPPORTED_CURRENCY_CODES as u, toAuthUserId as v, toEmail as w, toCountryCode as x, toBudgetId as y, EXPECTED_OPERATION_OUTCOMES as z };