@capxul/sdk-react 4.1.2 → 4.1.3

package/README.md

@@ -73,6 +73,13 @@ export function Providers({ children }: { children: React.ReactNode }) {
   and an amount the caller passed in `prefill` wins over it. Both engine hooks
   stay module-scoped.
 
+Payroll confirmation restores a saved run before enabling submission. An
+uncertain run keeps its period, amounts, recipients, and SDK request key across
+close/reopen and reload. Its fields remain fixed until Core confirms success or terminal closure.
+Use `.Actions.recovery` and `.Actions.recoveryError` to present recovery and
+storage errors. Group editors without `.Actions` keep their editable drafts.
+The application still owns the surrounding sheet and error copy.
+
 The packed npm package exposes `@capxul/sdk-react` and
 `@capxul/sdk-react/testing`. The workspace-only `@capxul/sdk-react/headless`
 subpath is not published.

package/dist/index.d.mts

@@ -946,6 +946,8 @@ interface PayrollRunSummarySlice {
   readonly funds: "available" | "insufficient" | "unknown";
 }
 interface PayrollRunActionsSlice {
+  readonly recovery: "none" | "restoring" | "required" | "unavailable";
+  readonly recoveryError: CapxulError | null;
   readonly submit: () => void;
   readonly isSubmitting: boolean;
   readonly blocked: boolean;

package/dist/index.mjs

@@ -86,7 +86,7 @@ async function invalidateMoneyState(queryClient, input) {
 const STORAGE_PREFIX = "capxul.payment.request-key.v3";
 const attemptReleases = /* @__PURE__ */ new Set();
 let pagehideInstalled = false;
-async function storageKey(operation, intent) {
+async function storageKey$1(operation, intent) {
 	return `${STORAGE_PREFIX}:${await fingerprintPaymentIntent({
 		operation,
 		intent
@@ -145,7 +145,7 @@ async function beginPaymentRequestKey(operation, intent) {
 	let releaseAttemptLock;
 	let forgetPagehideRelease;
 	try {
-		const storageSlot = await storageKey(operation, intent);
+		const storageSlot = await storageKey$1(operation, intent);
 		const attemptId = `attempt_${crypto.randomUUID()}`;
 		releaseAttemptLock = await holdAttemptLock(attemptLockName(storageSlot, attemptId));
 		forgetPagehideRelease = releaseAttemptOnPagehide(releaseAttemptLock);
@@ -1443,7 +1443,7 @@ const PLAIN_NUMBER = /^-?\d+(\.\d+)?$/;
 function escape(field) {
 	return `"${(FORMULA_LEAD.test(field) && !PLAIN_NUMBER.test(field) ? `'${field}` : field).replaceAll("\"", "\"\"")}"`;
 }
-function record(fields) {
+function record$1(fields) {
 	return fields.map(escape).join(",");
 }
 /**
@@ -1452,11 +1452,11 @@ function record(fields) {
 * sign lives in `Direction`, which is the code the row carries.
 */
 function buildCsv(items, actor, search) {
-	const records = [record(COLUMNS)];
+	const records = [record$1(COLUMNS)];
 	for (const item of items) {
 		const row = toActivityRow(item, actor);
 		if (!matchesSearch(row, search)) continue;
-		records.push(record([
+		records.push(record$1([
 			new Date(row.createdAt).toISOString(),
 			row.kind,
 			row.kind === "payment" ? row.paymentType : row.classification,
@@ -2648,6 +2648,180 @@ const CapxulPayroll = Object.assign(Root$1, {
 	Groups
 });
 //#endregion
+//#region src/headless/payroll/run-draft.ts
+function record(value) {
+	if (typeof value !== "object" || value === null || Array.isArray(value)) throw Errors.invalidInput("payrollDraft", "Invalid run draft");
+	return value;
+}
+function identifier(value) {
+	if (typeof value !== "string" || !/^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$/u.test(value)) throw Errors.invalidInput("payrollDraft", "Invalid draft identifier");
+	return value;
+}
+function minorAmount(value) {
+	if (typeof value !== "string" || !/^\d+$/u.test(value) || BigInt(value) <= 0n) throw Errors.invalidInput("payrollDraft", "Invalid draft amount");
+	return value;
+}
+function decodeDraft(value, scope) {
+	const row = record(value);
+	const asset = record(row.asset);
+	const input = record(row.input);
+	const period = record(input.period);
+	if (row.version !== 1 || row.scope !== scope || typeof asset.currency !== "string" || !/^[A-Z][A-Z0-9]{1,11}$/u.test(asset.currency) || typeof asset.decimals !== "number" || !Number.isInteger(asset.decimals) || asset.decimals < 0 || asset.decimals > 255 || typeof period.start !== "number" || !Number.isSafeInteger(period.start) || period.start <= 0 || period.end !== period.start || !Array.isArray(input.items) || input.items.length === 0) throw Errors.invalidInput("payrollDraft", "Invalid run draft");
+	const items = input.items.map((raw) => {
+		const item = record(raw);
+		const to = record(item.to);
+		const partyId = toPartyId(identifier(item.partyId));
+		if (to.kind !== "party" || to.partyId !== partyId || item.gross !== item.net || !Array.isArray(item.adjustments) || item.adjustments.length !== 0) throw Errors.invalidInput("payrollDraft", "Invalid draft recipient");
+		const net = minorAmount(item.net);
+		return {
+			to: {
+				kind: "party",
+				partyId
+			},
+			partyId,
+			gross: net,
+			net,
+			adjustments: []
+		};
+	});
+	if (new Set(items.map((item) => item.partyId)).size !== items.length) throw Errors.invalidInput("payrollDraft", "Duplicate draft recipient");
+	return {
+		version: 1,
+		scope,
+		asset: {
+			id: identifier(asset.id),
+			currency: asset.currency,
+			decimals: asset.decimals
+		},
+		input: {
+			permissionId: identifier(input.permissionId),
+			period: {
+				start: period.start,
+				end: period.start
+			},
+			items,
+			...input.requestKey === void 0 ? {} : { requestKey: identifier(input.requestKey) }
+		}
+	};
+}
+function runDraftError(cause) {
+	return cause instanceof CapxulError ? cause : Errors.providerError("sdk-react", "payrollDraft", cause);
+}
+function storageKey(scope) {
+	return `capxul.payroll.run-draft.v1:${scope}`;
+}
+function readRunDraft(scope) {
+	try {
+		const raw = localStorage.getItem(storageKey(scope));
+		if (raw === null) return null;
+		let value;
+		try {
+			value = JSON.parse(raw);
+		} catch {
+			throw Errors.invalidInput("payrollDraft", "Invalid run draft JSON");
+		}
+		return decodeDraft(value, scope);
+	} catch (cause) {
+		throw runDraftError(cause);
+	}
+}
+function sameDraft(left, right) {
+	const { requestKey: _leftKey, ...leftInput } = left.input;
+	const { requestKey: _rightKey, ...rightInput } = right.input;
+	return left.scope === right.scope && JSON.stringify(left.asset) === JSON.stringify(right.asset) && JSON.stringify(leftInput) === JSON.stringify(rightInput);
+}
+/** Hold the draft across the Core call, including component unmount. A reload releases the native lock. */
+async function executeRunDraft(candidate, work) {
+	try {
+		if (navigator.locks === void 0) throw Errors.invalidInput("payrollDraft", "Web Locks are required for run drafts");
+		return await navigator.locks.request(storageKey(candidate.scope), { ifAvailable: true }, async (lock) => {
+			if (lock === null) throw Errors.wrongState({
+				method: CAPXUL_OPERATIONS.payroll.authorizeRun,
+				currentState: "run-in-flight",
+				validStates: ["run-idle"]
+			});
+			let draft = readRunDraft(candidate.scope) ?? decodeDraft(candidate, candidate.scope);
+			if (!sameDraft(draft, candidate)) throw Errors.wrongState({
+				method: CAPXUL_OPERATIONS.payroll.authorizeRun,
+				currentState: "unresolved-run-draft",
+				validStates: ["resolved-run-draft"]
+			});
+			localStorage.setItem(storageKey(draft.scope), JSON.stringify(draft));
+			const clear = () => {
+				const stored = readRunDraft(draft.scope);
+				if (stored === null || !sameDraft(stored, draft) || stored.input.requestKey !== draft.input.requestKey) throw Errors.invalidInput("payrollDraft", "Run draft changed during submission");
+				localStorage.removeItem(storageKey(draft.scope));
+			};
+			const run = await work(draft, (key) => {
+				const next = decodeDraft({
+					...draft,
+					input: {
+						...draft.input,
+						requestKey: key
+					}
+				}, draft.scope);
+				localStorage.setItem(storageKey(draft.scope), JSON.stringify(next));
+				draft = next;
+			}, clear);
+			clear();
+			return run;
+		});
+	} catch (cause) {
+		throw runDraftError(cause);
+	}
+}
+/** Persistence becomes active only in a payable composer, never in the group editor. */
+function useRunDraft(client, orgId, apply) {
+	const identity = useCapxulIdentityOrNull();
+	const ownerId = identity?.phase === "authenticated" ? identity.session.authUserId : null;
+	const draftScope = client === null || ownerId === null || orgId === void 0 ? null : JSON.stringify([
+		client._internal.bootstrap.convexUrl,
+		client._internal.bootstrap.chainId,
+		ownerId,
+		orgId
+	]);
+	const currentScope = useRef(draftScope);
+	currentScope.current = draftScope;
+	const [active, setActive] = useState(false);
+	const activateDraft = useCallback(() => setActive(true), []);
+	const [restoredScope, setRestoredScope] = useState(null);
+	const [stored, setDraft] = useState(null);
+	const [draftError, setDraftError] = useState(null);
+	const draft = active && stored?.scope === draftScope ? stored : null;
+	const restorationPending = active && (draftScope === null || restoredScope !== draftScope);
+	const restoreDraft = useCallback((scope) => {
+		try {
+			const restored = readRunDraft(scope);
+			setDraft(restored);
+			setDraftError(null);
+			if (restored !== null) apply(restored);
+		} catch (cause) {
+			setDraft(null);
+			setDraftError(runDraftError(cause));
+		}
+		setRestoredScope(scope);
+	}, [apply]);
+	useEffect(() => {
+		if (active && draftScope !== null) restoreDraft(draftScope);
+	}, [
+		active,
+		draftScope,
+		restoreDraft
+	]);
+	return {
+		draftScope,
+		currentScope,
+		draft,
+		draftError,
+		restorationPending,
+		activateDraft,
+		restoreDraft,
+		setDraft,
+		recovery: !active || restorationPending ? "restoring" : draftError !== null ? "unavailable" : draft !== null ? "required" : "none",
+		draftBlocked: !active || restorationPending || draftError !== null
+	};
+}
+//#endregion
 //#region src/headless/payroll/terms-prefill.ts
 /**
 * Is this period exactly one UTC calendar month, CLOSED at both ends?
@@ -2757,13 +2931,15 @@ function amountText(amounts, seeds, recipientId) {
 * employer's in-progress edits with it. An absent `prefill` and one that seeds
 * nothing open the same empty composer, so they share a key on purpose.
 */
-function composerIdentity(orgId, prefill) {
+function composerIdentity(orgId, prefill, scope, frozen) {
+	if (frozen) prefill = void 0;
 	const seeds = Object.entries(initialAmounts(prefill)).map(([recipientId, draft]) => `${recipientId}=${draft.value}`).sort();
 	return [
 		orgId ?? "",
 		...prefill?.recipientIds ?? [],
 		"|",
-		...seeds
+		...seeds,
+		scope ?? "pending"
 	].join("\0");
 }
 /** Seeded from `prefill` on first render; the employer owns it after that. */
@@ -2779,6 +2955,7 @@ function usePayrollRun(input) {
 	const { orgId, prefill, onRun, onFailed } = input;
 	const client = useCapxulClientOrNull();
 	const queryClient = useQueryClient();
+	const submitGate = useRef(false);
 	const signerStatus = useSignerStatus(client);
 	const roster = useOrgRoster(orgId);
 	const groups = usePayrollGroups(orgId);
@@ -2787,24 +2964,55 @@ function usePayrollRun(input) {
 	const terms = useOrgTerms(orgId);
 	const [selected, setSelected] = useState(() => prefill?.recipientIds ?? []);
 	const [amounts, setAmounts] = useState(() => initialAmounts(prefill));
-	const composerKey = composerIdentity(orgId, prefill);
+	const restoreCurrency = treasury.data?.available.currency;
+	const { draftScope, currentScope, draft, draftError, restorationPending, activateDraft, restoreDraft, setDraft, recovery, draftBlocked } = useRunDraft(client, orgId, useCallback((restored) => {
+		setSelected(restored.input.items.map((item) => item.partyId));
+		if (restoreCurrency !== void 0 && restoreCurrency === restored.asset.currency) setAmounts(Object.fromEntries(restored.input.items.map((item) => [item.partyId, {
+			value: fromMinorUnits(BigInt(item.net), {
+				currency: restoreCurrency,
+				decimals: restored.asset.decimals
+			}).value,
+			prefilled: false
+		}])));
+	}, [restoreCurrency]));
+	const frozen = draft !== null;
+	const composerKey = composerIdentity(orgId, prefill, draftScope, frozen);
 	const [seededKey, setSeededKey] = useState(composerKey);
 	if (seededKey !== composerKey) {
 		setSeededKey(composerKey);
-		setSelected(prefill?.recipientIds ?? []);
-		setAmounts(initialAmounts(prefill));
+		if (!frozen) {
+			setSelected(prefill?.recipientIds ?? []);
+			setAmounts(initialAmounts(prefill));
+		}
 	}
-	const toggle = useCallback((id) => setSelected((current) => current.includes(id) ? current.filter((held) => held !== id) : [...current, id]), []);
-	const remove = useCallback((id) => setSelected((current) => current.filter((held) => held !== id)), []);
+	const toggle = useCallback((id) => {
+		if (submitGate.current || frozen || restorationPending || draftError !== null) return;
+		setSelected((current) => current.includes(id) ? current.filter((held) => held !== id) : [...current, id]);
+	}, [
+		frozen,
+		restorationPending,
+		draftError
+	]);
+	const remove = useCallback((id) => {
+		if (!submitGate.current && !frozen && !restorationPending && draftError === null) setSelected((current) => current.filter((held) => held !== id));
+	}, [
+		frozen,
+		restorationPending,
+		draftError
+	]);
 	const change = useCallback((id, text) => {
-		setAmounts((current) => ({
+		if (!submitGate.current && !frozen && !restorationPending && draftError === null) setAmounts((current) => ({
 			...current,
 			[id]: {
 				value: text,
 				prefilled: false
 			}
 		}));
-	}, []);
+	}, [
+		frozen,
+		restorationPending,
+		draftError
+	]);
 	const account = treasury.data ?? null;
 	const assetOptions = useMemo(() => account === null ? [] : [{
 		id: account.id,
@@ -2817,8 +3025,8 @@ function usePayrollRun(input) {
 	}, [assetOptions, selectedAssetId]);
 	const selectedAsset = assetOptions.find((option) => option.id === selectedAssetId) ?? null;
 	const selectAsset = useCallback((id) => {
-		setSelectedAssetId((current) => assetOptions.some((option) => option.id === id) ? id : current);
-	}, [assetOptions]);
+		if (!submitGate.current && !frozen) setSelectedAssetId((current) => assetOptions.some((option) => option.id === id) ? id : current);
+	}, [assetOptions, frozen]);
 	const assetMoney = selectedAsset !== null && account !== null ? account.available : null;
 	const named = useMemo(() => new Map(roster.options.map((option) => [option.id, option])), [roster.options]);
 	const refs = roster.refs;
@@ -2877,34 +3085,34 @@ function usePayrollRun(input) {
 	const budgets = me.data?.budgets ?? [];
 	const blockedReason = firstFalseFact({
 		signerReady: signerStatus === "ready",
-		budgetCount: budgets.length,
-		hasAsset: selectedAsset !== null,
+		...runAuthorityFacts(draft, budgets, selectedAsset, assetMoney, funds),
 		recipientCount: payableRefs === null ? 0 : selected.length,
-		amountsParse: total !== null,
-		funds
+		amountsParse: total !== null
 	});
 	const authorize = useMutation({
-		mutationFn: async (command) => {
-			const runAt = Date.now();
-			return unwrapCapxulResult(await scopedClient(client, CAPXUL_OPERATIONS.org.payroll.authorizeRun, orgId).payroll.authorizeRun({
-				permissionId: command.permissionId,
-				period: {
-					start: runAt,
-					end: runAt
-				},
-				items: command.items
-			}));
+		mutationFn: async (candidate) => {
+			if (candidate.scope !== currentScope.current) throw Errors.notAuthenticated();
+			return executeRunDraft(candidate, async (persisted, onRequestKey, onResolved) => {
+				if (candidate.scope === currentScope.current) setDraft(persisted);
+				return unwrapCapxulResult(await scopedClient(client, CAPXUL_OPERATIONS.org.payroll.authorizeRun, orgId).payroll.authorizeRun(persisted.input, {
+					onResolved,
+					onRequestKey: (key) => {
+						if (candidate.scope !== currentScope.current) throw Errors.notAuthenticated();
+						onRequestKey(key);
+					}
+				}));
+			});
 		},
-		onSettled: () => {
+		onSettled: (_run, _error, candidate) => {
 			queryClient.invalidateQueries({ queryKey: capxulKeys.payrollRuns(orgId) });
+			if (candidate.scope === currentScope.current) restoreDraft(candidate.scope);
 		}
 	});
-	const submitGate = useRef(false);
 	const totalDisplay = total === null ? null : formatMoney(total, GRAMMAR);
 	const authorizeMutate = authorize.mutate;
 	const submit = useCallback(() => {
 		const permissionId = budgets[0]?.id;
-		if (blockedReason !== null || submitGate.current) return;
+		if (blockedReason !== null || submitGate.current || draftBlocked || draftScope === null || assetMoney === null || selectedAsset === null) return;
 		if (permissionId === void 0 || totalDisplay === null || parsedAmounts === null) return;
 		if (payableRefs === null) return;
 		const recipientCount = selected.length;
@@ -2915,30 +3123,60 @@ function usePayrollRun(input) {
 			if (to === void 0 || parsed === void 0) return;
 			const raw = toMinorUnits(parsed).toString();
 			items.push({
-				to,
+				to: {
+					kind: "party",
+					partyId: toPartyId(recipientId)
+				},
 				partyId: recipientId,
 				gross: raw,
 				net: raw,
 				adjustments: []
 			});
 		}
+		const runAt = Date.now();
+		const candidate = frozen ? draft : {
+			version: 1,
+			scope: draftScope,
+			asset: {
+				id: selectedAsset.id,
+				currency: assetMoney.currency,
+				decimals: assetMoney.decimals
+			},
+			input: {
+				permissionId,
+				period: {
+					start: runAt,
+					end: runAt
+				},
+				items
+			}
+		};
 		submitGate.current = true;
-		authorizeMutate({
-			permissionId,
-			items
-		}, {
-			onSuccess: (run) => onRun({
-				id: run.id,
-				totalDisplay,
-				recipientCount
-			}),
-			onError: onFailed,
+		authorizeMutate(candidate, {
+			onSuccess: (run) => {
+				if (candidate.scope === currentScope.current) onRun({
+					id: run.id,
+					totalDisplay,
+					recipientCount
+				});
+			},
+			onError: (error) => {
+				if (candidate.scope === currentScope.current) onFailed(error);
+			},
 			onSettled: () => {
 				submitGate.current = false;
 			}
 		});
 	}, [
 		authorizeMutate,
+		draft,
+		frozen,
+		draftScope,
+		restorationPending,
+		draftError,
+		draftBlocked,
+		assetMoney,
+		selectedAsset,
 		blockedReason,
 		budgets,
 		onFailed,
@@ -2949,6 +3187,7 @@ function usePayrollRun(input) {
 		totalDisplay
 	]);
 	return {
+		activateDraft,
 		recipients: {
 			options: roster.options,
 			groups: (groups.data ?? []).map((group) => ({
@@ -2974,17 +3213,30 @@ function usePayrollRun(input) {
 		summary: {
 			recipientCount: selected.length,
 			totalDisplay,
-			balanceAfterDisplay: totalRaw === null || availableRaw === null || assetMoney === null ? null : formatMoney(fromMinorUnits(availableRaw - totalRaw, assetMoney), GRAMMAR),
+			balanceAfterDisplay: remainingBalanceDisplay(availableRaw, totalRaw, assetMoney),
 			funds
 		},
 		actions: {
 			submit,
 			isSubmitting: authorize.isPending,
-			blocked: blockedReason !== null,
-			blockedReason
+			blocked: blockedReason !== null || draftBlocked,
+			blockedReason,
+			recovery,
+			recoveryError: draftError
 		}
 	};
 }
+function remainingBalanceDisplay(available, total, asset) {
+	return available === null || total === null || asset === null ? null : formatMoney(fromMinorUnits(available - total, asset), GRAMMAR);
+}
+/** Persisted replay keeps its authorized Budget and asset; a prior debit cannot block its own recovery. */
+function runAuthorityFacts(draft, budgets, asset, money, funds) {
+	return {
+		budgetCount: draft !== null && !budgets.some((budget) => budget.id === draft.input.permissionId) ? 0 : budgets.length,
+		hasAsset: asset !== null && (draft === null || draft.asset.id === asset.id && draft.asset.currency === money?.currency && draft.asset.decimals === money?.decimals),
+		funds: draft?.input.requestKey === void 0 ? funds : "available"
+	};
+}
 /**
 * The seven facts, in the ONE order the contract fixes. Exactly one code comes
 * out, and it is always the first thing that is false — so two problems never
@@ -3032,7 +3284,9 @@ function Summary({ children }) {
 	return /* @__PURE__ */ jsx(Fragment, { children: children(usePayrollRunContext().summary) });
 }
 function Actions({ children }) {
-	return /* @__PURE__ */ jsx(Fragment, { children: children(usePayrollRunContext().actions) });
+	const engine = usePayrollRunContext();
+	useEffect(engine.activateDraft, [engine.activateDraft]);
+	return /* @__PURE__ */ jsx(Fragment, { children: children(engine.actions) });
 }
 /** The compound shape the app's own design system already uses (`StatusTabs`). */
 const CapxulPayrollRun = Object.assign(Root, {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@capxul/sdk-react",
-  "version": "4.1.2",
+  "version": "4.1.3",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/Xelmar-tech/infrastructure.git",
@@ -26,7 +26,7 @@
     "access": "public"
   },
   "dependencies": {
-    "@capxul/sdk": "4.1.2"
+    "@capxul/sdk": "4.1.3"
   },
   "devDependencies": {
     "@tanstack/react-query": "^5.66.9",