@capxul/sdk-react 4.2.0-rc.11 → 4.2.0-rc.13

package/dist/capxul-source.json

@@ -1,11 +1,11 @@
 {
   "source": {
-    "commit": "12a590f10914e8b056ce54732e6f484f36e060f3",
-    "tree": "90adc6656be3c1fb0a6e18170877d46081fa2538",
+    "commit": "887920e1ba54e17bd8465975fcbc6e1537dfb6b8",
+    "tree": "deed16dc942ed9d6b587ceead4dbf8b0b4174e2c",
     "branch": "codex/programme-rc",
     "repository": "https://github.com/Xelmar-tech/infrastructure",
     "lockfileSha256": "5870f53b72706d103220c1bcf733cb4fb71196aea32a9cfbdc277d73cc959264"
   },
   "name": "@capxul/sdk-react",
-  "version": "4.2.0-rc.11"
+  "version": "4.2.0-rc.13"
 }

package/dist/index.d.mts

@@ -833,8 +833,19 @@ type DashboardScope = {
   readonly orgId?: string;
 };
 type DashboardAccessPhase = "checking" | "error" | "redirect" | "granted";
+/**
+ * Which of the three probes produced the error the screen is showing. The
+ * error code alone cannot say: a provider failure reads the same whether the
+ * session read, the membership list or the lifecycle read raised it, and a
+ * consumer that reports a displayed gate error has to keep those apart
+ * (#1963 R05-2). It names the SOURCE only; `retry` still re-runs every failed
+ * probe, exactly as before.
+ */
+type DashboardAccessProbe = "session" | "membership" | "lifecycle";
 interface DashboardAccessErrorSlice {
   readonly error: CapxulError;
+  /** The probe the surfaced error came from, in the frozen precedence order. */
+  readonly probe: DashboardAccessProbe;
   /** Re-runs each failed probe. */
   readonly retry: () => void;
 }
@@ -853,6 +864,12 @@ declare function Checking({ children }: {
 declare function DashboardError({ children }: {
   readonly children: (slice: DashboardAccessErrorSlice) => ReactNode;
 }): import("react/jsx-runtime").JSX.Element | null;
+/**
+ * Hands the destination and draws nothing. Reaching this part is a REQUEST to
+ * navigate, never an arrival: the app may cancel or supersede it, so nothing
+ * here — and nothing a consumer hangs off it — may claim a completed redirect
+ * (#1963 R05-1). The destination page's own normalized pageview proves arrival.
+ */
 declare function Redirect({ children }: {
   readonly children: (slice: DashboardAccessRedirectSlice) => ReactNode;
 }): import("react/jsx-runtime").JSX.Element | null;
@@ -891,8 +908,14 @@ interface PayrollSummarySlice {
 }
 interface PayrollGroupsSlice {
   readonly groups: readonly PayrollGroupRow[];
-  readonly save: (input: PayrollGroupInput) => Promise<CapxulResult<PayrollGroupRow>>;
-  readonly remove: (id: PayrollGroupId) => Promise<CapxulResult<void>>;
+  /**
+   * R13 (#1968): `options` is the browser attempt the caller captured before the
+   * employer pressed the button. It reaches the SDK operation unchanged, so the
+   * group's `ui_payroll_action_completed` and the durable `payroll_group_changed`
+   * share one correlation. Absent, the write keeps its own invocation context.
+   */
+  readonly save: (input: PayrollGroupInput, options?: InvocationOptions) => Promise<CapxulResult<PayrollGroupRow>>;
+  readonly remove: (id: PayrollGroupId, options?: InvocationOptions) => Promise<CapxulResult<void>>;
   readonly isSaving: boolean;
   readonly isLoading: boolean;
   readonly error: CapxulError | null;
@@ -984,7 +1007,14 @@ interface PayrollRunSummarySlice {
 interface PayrollRunActionsSlice {
   readonly recovery: "none" | "restoring" | "required" | "unavailable";
   readonly recoveryError: CapxulError | null;
-  readonly submit: () => void;
+  /**
+   * R13 (#1968): `options` is the browser attempt captured before the employer
+   * confirmed. It reaches `authorizeRun` unchanged, so the sheet's own
+   * `ui_payroll_action_completed` and the durable `payroll_run_transitioned`
+   * rows share one correlation. It is NEVER written into the persisted draft —
+   * a restored run keeps its own identity, not a stale attempt's.
+   */
+  readonly submit: (options?: InvocationOptions) => void;
   readonly isSubmitting: boolean;
   readonly blocked: boolean;
   readonly blockedReason: CapxulPayrollRunBlockedReason | null;
@@ -1068,4 +1098,4 @@ declare const capxulKeys: {
   payment: (paymentId: string | undefined) => readonly ["capxul", "payments", string];
 };
 //#endregion
-export { type AccountFailure, type AccountProgress, type ActionResult, type ActivityDetailSlice, type ActivityExportSlice, type ActivityFilterValues, type ActivityFiltersSlice, type ActivityLoadMoreSlice, type ActivityReceipt, type ActivityRow, type ActivityRowsSlice, type ActivitySearchSlice, type ActivitySummarySlice, type AuthenticatedState, type AuthenticationSlots, type CanReason, CapxulActivity, type CapxulActivityProps, type CapxulAuth, CapxulAuthenticationController, type CapxulBootstrapState, type CapxulBootstrapStatus, CapxulContacts, type CapxulContactsProps, CapxulDashboardAccess, type CapxulDashboardAccessProps, CapxulOnboardingController, CapxulOrgMember, type CapxulOrgMemberProps, CapxulPayroll, type CapxulPayrollProps, CapxulPayrollRun, type CapxulPayrollRunBlockedReason, type CapxulPayrollRunProps, CapxulProvider, type CapxulProviderProps, type CapxulSend, CapxulSendMoney, type CapxulSendMoneyBlockedReason, type CapxulSendMoneyProps, type Contact, type ContactRelationship, type ContactRow, type ContactsActor, type ContactsAddBlockedReason, type ContactsAddError, type ContactsAddSlice, type ContactsListOptions, type ContactsListSlice, type ContactsRefusal, type ContactsSummarySlice, type ControllerAction, type CreateOrganizationFailure, type CreateOrganizationSubmission, type CsvExport, type DashboardAccessErrorSlice, type DashboardAccessPhase, type DashboardAccessRedirectSlice, type DashboardScope, type Destination, type FaultedState, type HandleAvailability, type ImageUploadInput, type ImageUploadTarget, type InvocationOptions, type NavigationAction, type OnboardingControllerProps, type OnboardingIntent, type OnboardingJourney, type OnboardingJourneyPosition, type OnboardingOrigin, type OnboardingStep, type OrgFailure, type OrgMemberAction, type OrgMemberCanSlice, type OrgMemberStanding, type OrgMemberStandingSlice, type OrgProgress, type OrganizationDetails, type OrganizationDraft, type OtpPendingState, type PayoutDraftChain, type PayoutDraftEntry, type PayrollGroupRow, type PayrollGroupsSlice, type PayrollRecipientOption, type PayrollRunActionsSlice, type PayrollRunAmountEntry, type PayrollRunAmountsSlice, type PayrollRunAssetSlice, type PayrollRunGroupOption, type PayrollRunPrefill, type PayrollRunRecipientsSlice, type PayrollRunStatus, type PayrollRunSummarySlice, type PayrollSummarySlice, type PendingAuthState, type ProfileDetails, type ProfileDraft, type ProfileSlotProps, type ReadyDestination, type RetryAction, type SendActor, type SendMoneyActionsSlice, type SendMoneyAmountSlice, type SendMoneyAssetError, type SendMoneyAssetOption, type SendMoneyAssetSlice, type SendMoneyRecipientSlice, type SendMoneyRecipientStatus, type SendMoneySourceError, type SendMoneySourceOption, type SendMoneySourceSlice, type SendResult, type SentPayment, type SentPayrollRun, type SignedOutState, type Slot, type SummaryWindow, type UseCapxulAccountBalanceOptions, type UseCapxulAccountBalanceReturn, type UseCapxulAccountFundReturn, type UseCapxulCreateCommitmentReturn, type UseCapxulCreateOrgReturn, type UseCapxulHandleAvailabilityReturn, type UseCapxulImageUploadReturn, type UseCapxulInviteMemberReturn, type UseCapxulOrgMembersOptions, type UseCapxulOrgMembersReturn, type UseCapxulOrgRolesOptions, type UseCapxulOrgRolesReturn, type UseCapxulOrgTreasuryOptions, type UseCapxulOrgTreasuryReturn, type UseCapxulOrgsReturn, type UseCapxulPayReturn, type UseCapxulPaymentReturn, type UseCapxulPaymentsReturn, type UseCapxulProfileReturn, type UseCapxulRedirectPaymentReturn, type UseCapxulUploadImageReturn, acknowledgeOnboardingDestination, activeOnboardingRecovery, capxulKeys, clearOnboardingJourney, currentOnboardingJourneyId, entered, invalidateOnboardingJourneyObservation, isClaimed, isRestoring, loadOnboardingJourney, onboardingJourneyPosition, saveOnboardingJourney, startOnboardingJourney, useCapxul, useCapxulAccountBalance, useCapxulAccountFund, useCapxulActivity, useCapxulActivityDetail, useCapxulAnnotateMovement, useCapxulAuth, useCapxulCancelPayment, useCapxulClaimPayment, useCapxulClientOrNull, useCapxulCreateCommitment, useCapxulCreateOrg, useCapxulDestination, useCapxulHandleAvailability, useCapxulHoldings, useCapxulIdentity, useCapxulImageUpload, useCapxulInviteMember, useCapxulOrgMembers, useCapxulOrgRoles, useCapxulOrgTreasury, useCapxulOrganizationPay, useCapxulOrganizationPayBatch, useCapxulOrgs, useCapxulPay, useCapxulPayment, useCapxulPayments, useCapxulPermission, useCapxulPermissionAssign, useCapxulPermissionChange, useCapxulPermissionCreate, useCapxulPermissionReplace, useCapxulPermissionRevoke, useCapxulPermissions, useCapxulProfile, useCapxulRedirectPayment, useCapxulSend, useCapxulTransitions, useCapxulUploadImage };
+export { type AccountFailure, type AccountProgress, type ActionResult, type ActivityDetailSlice, type ActivityExportSlice, type ActivityFilterValues, type ActivityFiltersSlice, type ActivityLoadMoreSlice, type ActivityReceipt, type ActivityRow, type ActivityRowsSlice, type ActivitySearchSlice, type ActivitySummarySlice, type AuthenticatedState, type AuthenticationSlots, type CanReason, CapxulActivity, type CapxulActivityProps, type CapxulAuth, CapxulAuthenticationController, type CapxulBootstrapState, type CapxulBootstrapStatus, CapxulContacts, type CapxulContactsProps, CapxulDashboardAccess, type CapxulDashboardAccessProps, CapxulOnboardingController, CapxulOrgMember, type CapxulOrgMemberProps, CapxulPayroll, type CapxulPayrollProps, CapxulPayrollRun, type CapxulPayrollRunBlockedReason, type CapxulPayrollRunProps, CapxulProvider, type CapxulProviderProps, type CapxulSend, CapxulSendMoney, type CapxulSendMoneyBlockedReason, type CapxulSendMoneyProps, type Contact, type ContactRelationship, type ContactRow, type ContactsActor, type ContactsAddBlockedReason, type ContactsAddError, type ContactsAddSlice, type ContactsListOptions, type ContactsListSlice, type ContactsRefusal, type ContactsSummarySlice, type ControllerAction, type CreateOrganizationFailure, type CreateOrganizationSubmission, type CsvExport, type DashboardAccessErrorSlice, type DashboardAccessPhase, type DashboardAccessProbe, type DashboardAccessRedirectSlice, type DashboardScope, type Destination, type FaultedState, type HandleAvailability, type ImageUploadInput, type ImageUploadTarget, type InvocationOptions, type NavigationAction, type OnboardingControllerProps, type OnboardingIntent, type OnboardingJourney, type OnboardingJourneyPosition, type OnboardingOrigin, type OnboardingStep, type OrgFailure, type OrgMemberAction, type OrgMemberCanSlice, type OrgMemberStanding, type OrgMemberStandingSlice, type OrgProgress, type OrganizationDetails, type OrganizationDraft, type OtpPendingState, type PayoutDraftChain, type PayoutDraftEntry, type PayrollGroupRow, type PayrollGroupsSlice, type PayrollRecipientOption, type PayrollRunActionsSlice, type PayrollRunAmountEntry, type PayrollRunAmountsSlice, type PayrollRunAssetSlice, type PayrollRunGroupOption, type PayrollRunPrefill, type PayrollRunRecipientsSlice, type PayrollRunStatus, type PayrollRunSummarySlice, type PayrollSummarySlice, type PendingAuthState, type ProfileDetails, type ProfileDraft, type ProfileSlotProps, type ReadyDestination, type RetryAction, type SendActor, type SendMoneyActionsSlice, type SendMoneyAmountSlice, type SendMoneyAssetError, type SendMoneyAssetOption, type SendMoneyAssetSlice, type SendMoneyRecipientSlice, type SendMoneyRecipientStatus, type SendMoneySourceError, type SendMoneySourceOption, type SendMoneySourceSlice, type SendResult, type SentPayment, type SentPayrollRun, type SignedOutState, type Slot, type SummaryWindow, type UseCapxulAccountBalanceOptions, type UseCapxulAccountBalanceReturn, type UseCapxulAccountFundReturn, type UseCapxulCreateCommitmentReturn, type UseCapxulCreateOrgReturn, type UseCapxulHandleAvailabilityReturn, type UseCapxulImageUploadReturn, type UseCapxulInviteMemberReturn, type UseCapxulOrgMembersOptions, type UseCapxulOrgMembersReturn, type UseCapxulOrgRolesOptions, type UseCapxulOrgRolesReturn, type UseCapxulOrgTreasuryOptions, type UseCapxulOrgTreasuryReturn, type UseCapxulOrgsReturn, type UseCapxulPayReturn, type UseCapxulPaymentReturn, type UseCapxulPaymentsReturn, type UseCapxulProfileReturn, type UseCapxulRedirectPaymentReturn, type UseCapxulUploadImageReturn, acknowledgeOnboardingDestination, activeOnboardingRecovery, capxulKeys, clearOnboardingJourney, currentOnboardingJourneyId, entered, invalidateOnboardingJourneyObservation, isClaimed, isRestoring, loadOnboardingJourney, onboardingJourneyPosition, saveOnboardingJourney, startOnboardingJourney, useCapxul, useCapxulAccountBalance, useCapxulAccountFund, useCapxulActivity, useCapxulActivityDetail, useCapxulAnnotateMovement, useCapxulAuth, useCapxulCancelPayment, useCapxulClaimPayment, useCapxulClientOrNull, useCapxulCreateCommitment, useCapxulCreateOrg, useCapxulDestination, useCapxulHandleAvailability, useCapxulHoldings, useCapxulIdentity, useCapxulImageUpload, useCapxulInviteMember, useCapxulOrgMembers, useCapxulOrgRoles, useCapxulOrgTreasury, useCapxulOrganizationPay, useCapxulOrganizationPayBatch, useCapxulOrgs, useCapxulPay, useCapxulPayment, useCapxulPayments, useCapxulPermission, useCapxulPermissionAssign, useCapxulPermissionChange, useCapxulPermissionCreate, useCapxulPermissionReplace, useCapxulPermissionRevoke, useCapxulPermissions, useCapxulProfile, useCapxulRedirectPayment, useCapxulSend, useCapxulTransitions, useCapxulUploadImage };

package/dist/index.mjs

@@ -880,7 +880,7 @@ function useCapxulUploadImage() {
 //#endregion
 //#region src/headless/contacts/use-contacts.ts
 /** One captured snapshot, or nothing — never a fabricated empty options object. */
-const carry = (options) => options === void 0 ? {} : { options };
+const carry$1 = (options) => options === void 0 ? {} : { options };
 function useContacts(input) {
 	const { actor, onAdded, onFailed } = input;
 	const client = useCapxulClientOrNull();
@@ -922,7 +922,7 @@ function useContacts(input) {
 		setAddError(null);
 		addMutate({
 			ref: refFromTypedText(value),
-			...carry(attempt)
+			...carry$1(attempt)
 		}, {
 			onSuccess: (entry) => {
 				setValue("");
@@ -955,17 +955,17 @@ function useContacts(input) {
 			kind: "rename",
 			id,
 			name,
-			...carry(toInvocationOptions(options))
+			...carry$1(toInvocationOptions(options))
 		}), [writeMutate]),
 		hide: useCallback((id, options) => writeMutate({
 			kind: "hide",
 			id,
-			...carry(toInvocationOptions(options))
+			...carry$1(toInvocationOptions(options))
 		}), [writeMutate]),
 		unhide: useCallback((id, options) => writeMutate({
 			kind: "unhide",
 			id,
-			...carry(toInvocationOptions(options))
+			...carry$1(toInvocationOptions(options))
 		}), [writeMutate]),
 		add: {
 			value,
@@ -2315,6 +2315,16 @@ function decidePhase(input) {
 	if (input.orgLaneSettled && input.destination !== null) return "redirect";
 	return "checking";
 }
+/**
+* Which probe produced the surfaced error — the SAME precedence `error` itself
+* is chosen by, written once so the code and its source can never disagree.
+*/
+function probeOf(session, membership, lifecycle) {
+	if (session !== null) return "session";
+	if (membership !== null) return "membership";
+	if (lifecycle !== null) return "lifecycle";
+	return null;
+}
 /** The engine — all the logic. NOT exported from the package barrel. */
 function useDashboardAccess(scope) {
 	const client = useCapxulClientOrNull();
@@ -2351,6 +2361,7 @@ function useDashboardAccess(scope) {
 		lifecycle.refetch
 	]);
 	const error = sessionError ?? membershipError ?? lifecycleError;
+	const probe = probeOf(sessionError, membershipError, lifecycleError);
 	const phase = decidePhase({
 		error,
 		settled: client !== null && identity !== null && !isRestoring$1(identity) && membershipsSettled && lifecycleSettled,
@@ -2361,11 +2372,13 @@ function useDashboardAccess(scope) {
 	return useMemo(() => ({
 		phase,
 		error,
+		probe,
 		destination,
 		retry
 	}), [
 		phase,
 		error,
+		probe,
 		destination,
 		retry
 	]);
@@ -2410,12 +2423,19 @@ function Checking({ children }) {
 }
 function DashboardError({ children }) {
 	const state = usePart("error");
-	if (state === null || state.error === null) return null;
+	if (state === null || state.error === null || state.probe === null) return null;
 	return /* @__PURE__ */ jsx(Fragment, { children: children({
 		error: state.error,
+		probe: state.probe,
 		retry: state.retry
 	}) });
 }
+/**
+* Hands the destination and draws nothing. Reaching this part is a REQUEST to
+* navigate, never an arrival: the app may cancel or supersede it, so nothing
+* here — and nothing a consumer hangs off it — may claim a completed redirect
+* (#1963 R05-1). The destination page's own normalized pageview proves arrival.
+*/
 function Redirect({ children }) {
 	const state = usePart("redirect");
 	if (state === null || state.destination === null) return null;
@@ -2579,6 +2599,14 @@ function scopedClient(client, method, orgId) {
 //#region src/headless/payroll/use-payroll.ts
 /** Money reads the same way everywhere on this screen: amount then code. */
 const GRAMMAR$1 = { grammar: "code" };
+/**
+* One captured snapshot, or nothing — never a fabricated empty options object,
+* and never a DOM event a screen wired straight to `onClick`.
+*/
+function carry(options) {
+	const attempt = toInvocationOptions(options);
+	return attempt === void 0 ? {} : { options: attempt };
+}
 function toPayrollGroupRow(group) {
 	const currency = new Set(group.members.map((member) => member.currency)).size === 1 ? group.members[0]?.currency : void 0;
 	return {
@@ -2618,16 +2646,17 @@ function usePayroll(orgId) {
 	const write = useMutation({
 		mutationFn: async (command) => {
 			const payroll = scopedClient(client, CAPXUL_OPERATIONS.org.payroll.groups[command.kind], orgId).payroll;
+			const controls = toInvocationControls(command.options);
 			if (command.kind === "remove") {
-				unwrapCapxulResult(await payroll.groups.remove(command.id));
+				unwrapCapxulResult(await payroll.groups.remove(command.id, controls));
 				return null;
 			}
-			return unwrapCapxulResult(await payroll.groups.save(command.input));
+			return unwrapCapxulResult(await payroll.groups.save(command.input, controls));
 		},
 		onSettled: invalidate
 	});
 	const mutateAsync = write.mutateAsync;
-	const save = useCallback(async (input) => {
+	const save = useCallback(async (input, options) => {
 		const refusal = invalidGroup(input);
 		if (refusal !== null) return {
 			ok: false,
@@ -2636,7 +2665,8 @@ function usePayroll(orgId) {
 		try {
 			const saved = await mutateAsync({
 				kind: "save",
-				input
+				input,
+				...carry(options)
 			});
 			return saved === null ? {
 				ok: false,
@@ -2652,11 +2682,12 @@ function usePayroll(orgId) {
 			};
 		}
 	}, [mutateAsync]);
-	const remove = useCallback(async (id) => {
+	const remove = useCallback(async (id, options) => {
 		try {
 			await mutateAsync({
 				kind: "remove",
-				id
+				id,
+				...carry(options)
 			});
 			return {
 				ok: true,
@@ -3174,11 +3205,12 @@ function usePayrollRun(input) {
 		amountsParse: total !== null
 	});
 	const authorize = useMutation({
-		mutationFn: async (candidate) => {
+		mutationFn: async ({ candidate, options }) => {
 			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, {
+					...toInvocationControls(options),
 					onResolved,
 					onRequestKey: (key) => {
 						if (candidate.scope !== currentScope.current) throw Errors.notAuthenticated();
@@ -3187,14 +3219,15 @@ function usePayrollRun(input) {
 				}));
 			});
 		},
-		onSettled: (_run, _error, candidate) => {
+		onSettled: (_run, _error, { candidate }) => {
 			queryClient.invalidateQueries({ queryKey: capxulKeys.payrollRuns(orgId) });
 			if (candidate.scope === currentScope.current) restoreDraft(candidate.scope);
 		}
 	});
 	const totalDisplay = total === null ? null : formatMoney(total, GRAMMAR);
 	const authorizeMutate = authorize.mutate;
-	const submit = useCallback(() => {
+	const submit = useCallback((options) => {
+		const attempt = toInvocationOptions(options);
 		const permissionId = budgets[0]?.id;
 		if (blockedReason !== null || submitGate.current || draftBlocked || draftScope === null || assetMoney === null || selectedAsset === null) return;
 		if (permissionId === void 0 || totalDisplay === null || parsedAmounts === null) return;
@@ -3236,7 +3269,10 @@ function usePayrollRun(input) {
 			}
 		};
 		submitGate.current = true;
-		authorizeMutate(candidate, {
+		authorizeMutate({
+			candidate,
+			...attempt === void 0 ? {} : { options: attempt }
+		}, {
 			onSuccess: (run) => {
 				if (candidate.scope === currentScope.current) onRun({
 					id: run.id,

package/package.json

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