@capxul/sdk-react 2.5.4 → 2.6.0

package/README.md

@@ -68,7 +68,10 @@ export function Providers({ children }: { children: React.ReactNode }) {
   `.Actions`. A screen places any subset — the pay-now sheet places all five
   run parts, the group sheet places two. `.Actions.blockedReason` names the
   first false fact as a `CapxulPayrollRunBlockedReason` code, never a
-  sentence. Both engine hooks stay module-scoped.
+  sentence. `.Amounts` prefills a row from the organization's active engagement
+  terms when the run's period can state that rate — the value stays editable,
+  and an amount the caller passed in `prefill` wins over it. Both engine hooks
+  stay module-scoped.
 
 The packed npm package exposes `@capxul/sdk-react` and
 `@capxul/sdk-react/testing`. The workspace-only `@capxul/sdk-react/headless`

package/dist/{controllers-DpScp8c5.mjs → controllers-ClPgcB4L.mjs}

@@ -117,6 +117,13 @@ const capxulKeys = {
 		"payroll",
 		"groups"
 	],
+	payrollTerms: (orgId) => [
+		"capxul",
+		"org",
+		orgId ?? "pending",
+		"payroll",
+		"terms"
+	],
 	activity: ["capxul", "activity"],
 	activityDetail: (reference, actor = void 0) => [
 		"capxul",
@@ -489,7 +496,9 @@ const MAX_CAPXUL_QUERY_RETRIES = 2;
 */
 function shouldRetryCapxulQuery(failureCount, error) {
 	if (failureCount >= MAX_CAPXUL_QUERY_RETRIES) return false;
-	return isCapxulError(error) && RETRYABLE_QUERY_ERROR_CODES.has(error.code);
+	if (!isCapxulError(error)) return false;
+	if (error.chain !== void 0) return error.chain.retryable;
+	return RETRYABLE_QUERY_ERROR_CODES.has(error.code);
 }
 /**
 * The default query client used when the host injects none. Exported so a test

package/dist/index.d.mts

@@ -1287,6 +1287,7 @@ declare const capxulKeys: {
   contactsList: (scope: string, includeHidden: boolean) => readonly ["capxul", "contacts", string, "all" | "visible"];
   payrollRuns: (orgId: OrgId | undefined) => readonly ["capxul", "org", "pending" | OrgId, "payroll", "runs"];
   payrollGroups: (orgId: OrgId | undefined) => readonly ["capxul", "org", "pending" | OrgId, "payroll", "groups"];
+  payrollTerms: (orgId: OrgId | undefined) => readonly ["capxul", "org", "pending" | OrgId, "payroll", "terms"];
   activity: readonly ["capxul", "activity"];
   activityDetail: (reference: ActivityReference | undefined, actor?: ActorReference | undefined) => readonly ["capxul", "activity", "self" | ActorReference, "pending" | ActivityReference];
   activitySummary: (actor?: ActorReference, window?: ActivityRange) => readonly ["capxul", "activity", "summary", "self" | ActorReference, "all" | ActivityRange];

package/dist/index.mjs

@@ -1,5 +1,5 @@
 "use client";
-import { a as useCapxulAuth, c as useCapxulIdentityOrNull, d as capxulKeys, f as useCapxulClientOrNull, i as entered, l as useCapxulSend, n as CapxulOnboardingController, o as useCapxulDestination, p as useCapxul, r as CapxulProvider, s as useCapxulIdentity, t as CapxulAuthenticationController, u as useCapxulTransitions } from "./controllers-DpScp8c5.mjs";
+import { a as useCapxulAuth, c as useCapxulIdentityOrNull, d as capxulKeys, f as useCapxulClientOrNull, i as entered, l as useCapxulSend, n as CapxulOnboardingController, o as useCapxulDestination, p as useCapxul, r as CapxulProvider, s as useCapxulIdentity, t as CapxulAuthenticationController, u as useCapxulTransitions } from "./controllers-ClPgcB4L.mjs";
 import { createContext, useCallback, useContext, useEffect, useMemo, useRef, useState, useSyncExternalStore } from "react";
 import { useInfiniteQuery, useMutation, useQuery, useQueryClient } from "@tanstack/react-query";
 import { CapxulError, Errors, PAYMENT_DIRECTIONS, PAYMENT_STATUSES, fingerprintPaymentIntent, formatMoney, isCapxulError, isClaimed, isClaimed as isClaimed$1, isMoneyParseError, isRestoring, isRestoring as isRestoring$1, parseMoney, paymentPhase, resolveIdentityDestination } from "@capxul/sdk";
@@ -2315,6 +2315,22 @@ function usePayrollRuns(orgId) {
 		enabled: client !== null && orgId !== void 0
 	});
 }
+/**
+* The active engagement terms of the org's employed people (#1638) — the rows
+* ruling Q3 lets `.Amounts` prefill a rate from.
+*
+* The read is gated on `canSpend` server-side, exactly as the groups read is.
+* A member who may not spend therefore reads an error here and composes with no
+* seed, which is the same composer they had before this read existed.
+*/
+function useOrgTerms(orgId) {
+	const client = useCapxulClientOrNull();
+	return useQuery({
+		queryKey: capxulKeys.payrollTerms(orgId),
+		queryFn: async () => unwrapCapxulResult(await scopedClient(client, "org.payroll.terms", orgId).payroll.terms()),
+		enabled: client !== null && orgId !== void 0
+	});
+}
 function useOrgTreasury(orgId) {
 	const client = useCapxulClientOrNull();
 	return useQuery({
@@ -2500,6 +2516,79 @@ const CapxulPayroll = Object.assign(Root$1, {
 	Groups
 });
 //#endregion
+//#region src/headless/payroll/terms-prefill.ts
+/**
+* Is this period exactly one UTC calendar month, CLOSED at both ends?
+*
+* Closed because that is the convention `periodStart` / `periodEnd` already
+* carry: an instant run stores `periodStart === periodEnd`, one instant rather
+* than a half-open window of zero length. One convention, the shipped one — the
+* first run that actually carries a period will assert it here.
+*
+* A `month` rate states what one month costs and nothing else, so anything that
+* is not exactly a month leaves the rate underivable and seeds nothing. Half a
+* month is not half the rate — that would be proration, a policy no layer of
+* this item owns.
+*/
+function spansOneMonth(period) {
+	const at = new Date(period.start);
+	const first = Date.UTC(at.getUTCFullYear(), at.getUTCMonth(), 1);
+	const next = Date.UTC(at.getUTCFullYear(), at.getUTCMonth() + 1, 1);
+	return period.start === first && period.end === next - 1;
+}
+/** A stored `rate` this module can count. Nothing decodes the row before us. */
+const MINOR_UNITS = /^\d+$/u;
+/**
+* The typed-amount text a rate becomes: a plain decimal, NOT a display string.
+* `null` when the stored rate is not minor units at all.
+*
+* The text is what the employer sees in the amount input and what the run
+* submits, so it must survive a round trip back through `parseMoney`.
+* `formatMoney` appends a currency code, which never would.
+*
+* The shape check is not belt-and-braces. `engagementTerms.rate` is a bare
+* `v.string()`, the SDK maps the row rather than decoding it, and this function
+* runs inside a render — so an unhandled `BigInt("")` would take the whole
+* composer down instead of one seed. `sumTypedAmounts` in this same folder
+* skips what it cannot read for the same reason.
+*/
+function typedAmount(terms) {
+	if (!MINOR_UNITS.test(terms.rate)) return null;
+	const value = fromMinorUnits(BigInt(terms.rate), terms).value;
+	return value.includes(".") ? value.replace(/\.?0+$/u, "") : value;
+}
+/**
+* The seed text per party, for the recipients whose terms row states a rate
+* this run can pay.
+*
+* Three facts stop a seed, and each one stops it SILENTLY: a recipient with no
+* seed gets the empty field they had before this read existed, never an error
+* on a value they did not type.
+*
+*   the unit      `paycheck` always states a rate. `month` states one only over
+*                 a month (ruling Q3). `hour`, `week` and `year` state a rate
+*                 for a period the run does not carry.
+*   the currency  `.Amounts` is denominated in the TREASURY asset's currency and
+*                 the one-option dropdown cannot be changed. A rate in another
+*                 currency is not that money, and converting it would be Capxul
+*                 computing pay.
+*   the text      a rate that is not minor units at all, or that does not parse
+*                 back to positive money — a zero rate, or one counted in finer
+*                 units than the asset — would seed a field that is wrong the
+*                 instant it appears.
+*/
+function termsSeeds(terms, asset, period) {
+	const seeds = /* @__PURE__ */ new Map();
+	if (asset === null) return seeds;
+	for (const row of terms) {
+		if (!(row.unit === "paycheck" || row.unit === "month" && spansOneMonth(period)) || row.currency !== asset.currency) continue;
+		const text = typedAmount(row);
+		if (text === null || isMoneyParseError(parseMoney(text, asset))) continue;
+		seeds.set(row.partyId, text);
+	}
+	return seeds;
+}
+//#endregion
 //#region src/headless/payroll/use-payroll-run.ts
 const GRAMMAR = { grammar: "code" };
 /**
@@ -2510,6 +2599,29 @@ const GRAMMAR = { grammar: "code" };
 */
 const CURRENCY_UNREAD = "";
 /**
+* The period this composer composes: an INSTANT run (ruling Q3). `authorizeRun`
+* stamps `start === end === runAt` at submit, and the payslip's period renders
+* that date.
+*
+* WHICH instant it is cannot change a prefill answer, because no single instant
+* spans a calendar month. So the seed asks its question with the SHAPE the run
+* will submit, rather than with a live clock that would rebuild the seed map on
+* every render. A later period-bearing run passes its own window and reaches
+* the `month` branch without a second rule.
+*/
+const INSTANT_RUN_PERIOD = {
+	start: 0,
+	end: 0
+};
+/**
+* The text one `.Amounts` row shows: the employer's own draft, else the terms
+* seed. Read in BOTH places a value is needed — the rendered entries and the
+* parsed totals — so the summary can never state a number the fields do not.
+*/
+function amountText(amounts, seeds, recipientId) {
+	return amounts[recipientId]?.value ?? seeds.get(recipientId) ?? "";
+}
+/**
 * WHICH run the composer is composing, by MEANING rather than by object shape.
 *
 * `recipientIds` order is meaning — it is the order `.Amounts` rows appear in.
@@ -2547,6 +2659,7 @@ function usePayrollRun(input) {
 	const groups = usePayrollGroups(orgId);
 	const treasury = useOrgTreasury(orgId);
 	const me = useOrgMe(orgId);
+	const terms = useOrgTerms(orgId);
 	const [selected, setSelected] = useState(() => prefill?.recipientIds ?? []);
 	const [amounts, setAmounts] = useState(() => initialAmounts(prefill));
 	const composerKey = composerIdentity(orgId, prefill);
@@ -2593,9 +2706,9 @@ function usePayrollRun(input) {
 		}
 		return resolved;
 	}, [refs, selected]);
+	const seeds = useMemo(() => termsSeeds(terms.data ?? [], assetMoney, INSTANT_RUN_PERIOD), [assetMoney, terms.data]);
 	const entries = useMemo(() => selected.map((recipientId) => {
-		const draft = amounts[recipientId];
-		const value = draft?.value ?? "";
+		const value = amountText(amounts, seeds, recipientId);
 		const parsed = assetMoney === null || value.trim() === "" ? null : parseMoney(value, assetMoney);
 		return {
 			recipientId,
@@ -2603,7 +2716,7 @@ function usePayrollRun(input) {
 			value,
 			change: (text) => change(recipientId, text),
 			error: parsed !== null && isMoneyParseError(parsed) ? parsed.reason : null,
-			prefilled: draft?.prefilled ?? false,
+			prefilled: amounts[recipientId]?.prefilled ?? seeds.has(recipientId),
 			currency: assetMoney?.currency ?? CURRENCY_UNREAD
 		};
 	}), [
@@ -2611,13 +2724,14 @@ function usePayrollRun(input) {
 		assetMoney,
 		change,
 		named,
+		seeds,
 		selected
 	]);
 	const parsedAmounts = useMemo(() => {
 		if (assetMoney === null || selected.length === 0) return null;
 		const money = [];
 		for (const recipientId of selected) {
-			const parsed = parseMoney(amounts[recipientId]?.value ?? "", assetMoney);
+			const parsed = parseMoney(amountText(amounts, seeds, recipientId), assetMoney);
 			if (isMoneyParseError(parsed)) return null;
 			money.push(parsed);
 		}
@@ -2625,6 +2739,7 @@ function usePayrollRun(input) {
 	}, [
 		amounts,
 		assetMoney,
+		seeds,
 		selected
 	]);
 	const total = useMemo(() => parsedAmounts === null || assetMoney === null ? null : fromMinorUnits(parsedAmounts.reduce((sum, money) => sum + toMinorUnits(money), 0n), assetMoney), [assetMoney, parsedAmounts]);

package/dist/testing/index.mjs

@@ -1,4 +1,4 @@
-import { n as CapxulOnboardingController, r as CapxulProvider, t as CapxulAuthenticationController } from "../controllers-DpScp8c5.mjs";
+import { n as CapxulOnboardingController, r as CapxulProvider, t as CapxulAuthenticationController } from "../controllers-ClPgcB4L.mjs";
 import "react";
 import { jsx } from "react/jsx-runtime";
 import { createCapxulTestClient } from "@capxul/sdk/testing";

package/package.json

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