@capxul/sdk-react 2.3.1 → 2.4.0

package/README.md

@@ -35,6 +35,19 @@ export function Providers({ children }: { children: React.ReactNode }) {
 - Rich-data hooks such as `useCapxulProfile`, `useCapxulOrgs`, members, roles,
   treasury, and money hooks remain TanStack Query projections. Personal
   holdings and activity reads start only after the Account is claimed.
+- `CapxulActivity` is the compound activity component. One root owns fetching,
+  paging, filtering, searching, the summary numbers, row meaning, memo saving
+  and CSV building, and draws nothing. The `.Summary`, `.Filters`, `.Search`,
+  `.Rows`, `.LoadMore`, `.Detail` and `.Export` region parts each hand the
+  screen one finished slice, so the same component serves a ten-row dashboard
+  card and a full transactions page. Paging is infinite scroll through a
+  sentinel ref; `.Export` pages at the backend maximum and stops at 5,000 rows
+  rather than draining a ledger. Detail state and reads stay scoped to the root
+  actor.
+- `capxulKeys` is the public query-key catalog. An application invalidates SDK
+  lanes with it instead of keeping a parallel key namespace.
+- `useCapxulHoldings` takes an optional `actor`, and its cache entry is keyed by
+  that actor.
 - `CapxulSendMoney` is the compound send component. One root owns the send
   behaviour and draws nothing. The `.Asset`, `.Amount`, `.Recipient`, and
   `.Actions` region parts each hand the screen one finished slice. The engine

package/dist/{controllers-VwUPB619.mjs → controllers-DLBe4-OP.mjs}

@@ -104,12 +104,24 @@ const capxulKeys = {
 		includeHidden ? "all" : "visible"
 	],
 	activity: ["capxul", "activity"],
-	activityDetail: (reference) => [
+	activityDetail: (reference, actor = void 0) => [
 		"capxul",
 		"activity",
+		actor ?? "self",
 		reference ?? "pending"
 	],
-	holdings: ["capxul", "holdings"],
+	activitySummary: (actor, window) => [
+		"capxul",
+		"activity",
+		"summary",
+		actor ?? "self",
+		window ?? "all"
+	],
+	holdings: (actor) => [
+		"capxul",
+		"holdings",
+		actor ?? "self"
+	],
 	payments: ["capxul", "payments"],
 	payment: (paymentId) => [
 		"capxul",

package/dist/index.d.mts

@@ -1,7 +1,7 @@
 import { A as useCapxulAuth, C as CreateOrganizationSubmission, D as ProfileDetails, E as OrganizationDetails, M as useCapxulIdentity, N as useCapxulSend, O as SendResult, P as useCapxulTransitions, S as CapxulSend, T as InvocationOptions, _ as ReadyDestination, a as AuthenticationSlots, b as Slot, c as ControllerAction, d as OnboardingControllerProps, f as OrgFailure, g as ProfileSlotProps, h as PendingAuthState, i as AuthenticatedState, j as useCapxulDestination, k as entered, l as FaultedState, m as OtpPendingState, n as AccountProgress, o as CapxulAuthenticationController, p as OrgProgress, r as ActionResult, s as CapxulOnboardingController, t as AccountFailure, u as NavigationAction, v as RetryAction, w as Destination, x as CapxulAuth, y as SignedOutState } from "./controllers-BT4YzBr9.mjs";
-import { ReactNode } from "react";
+import { ReactNode, RefCallback } from "react";
 import { QueryClient, UseMutationResult, UseQueryResult } from "@tanstack/react-query";
-import { Account, AccountRequirement, ActivityAnnotationInput, ActivityDetail, ActivityListParams, ActivityPage, ActivityReference, AddressBookEntry, CapxulClient, CapxulError, CapxulSigner, CreateOrgInput, CurrentHoldings, HostObservability, IdentityDestination, InviteMemberInput, MemberView, Money, MoneyParseErrorReason, MovementAnnotation, OrgId, OrgView, OrganizationPaymentBatchInput, OrganizationPaymentInput, PartyId, Payment, PaymentTiming, PaymentsPayInput, Permission, PermissionReadResult, Profile, RoleView, isClaimed, isRestoring } from "@capxul/sdk";
+import { Account, AccountRequirement, ActivityAnnotation, ActivityAnnotationInput, ActivityDetail, ActivityKind, ActivityListParams, ActivityPage, ActivityPhase, ActivityRange, ActivityReference, ActorReference, AddressBookEntry, CapxulClient, CapxulError, CapxulSigner, CreateOrgInput, CurrentHoldings, HostObservability, IdentityDestination, InviteMemberInput, MemberView, Money, MoneyParseErrorReason, OrgId, OrgView, OrganizationPaymentBatchInput, OrganizationPaymentInput, PartyId, Payment, PaymentDirection, PaymentDocumentRef, PaymentDocumentRender, PaymentStatus, PaymentTiming, PaymentType, PaymentsPayInput, Permission, PermissionReadResult, Profile, RoleView, isClaimed, isRestoring } from "@capxul/sdk";
 
 //#region src/provider.d.ts
 type CapxulProviderSharedProps = {
@@ -127,7 +127,7 @@ declare const useCapxulPermissionCreate: (orgId: OrgId) => UseMutationResult<{
     readonly permissionId: PermissionId;
     readonly orgId: string;
     readonly type: "budget" | "managePeople";
-    readonly state: "active" | "pending" | "quarantined" | "revoked" | "superseded" | "suspended";
+    readonly state: "active" | "pending" | "revoked" | "superseded" | "suspended";
     readonly revision: number;
     readonly roleKey: RoleKey;
     readonly tokenAddress?: Address | undefined;
@@ -137,7 +137,7 @@ declare const useCapxulPermissionCreate: (orgId: OrgId) => UseMutationResult<{
     readonly permissionId: PermissionId;
     readonly orgId: string;
     readonly type: "budget" | "managePeople";
-    readonly state: "active" | "pending" | "quarantined" | "revoked" | "superseded" | "suspended";
+    readonly state: "active" | "pending" | "revoked" | "superseded" | "suspended";
     readonly revision: number;
     readonly roleKey: RoleKey;
     readonly tokenAddress?: Address | undefined;
@@ -153,7 +153,7 @@ declare const useCapxulPermissionCreate: (orgId: OrgId) => UseMutationResult<{
       readonly kind: "organization";
       readonly orgId: string;
     };
-    readonly state: "active" | "pending" | "quarantined" | "revoked" | "superseded" | "suspended";
+    readonly state: "active" | "pending" | "revoked" | "superseded" | "suspended";
   };
 }, CapxulError, import("@capxul/sdk").PermissionCreateInput>;
 declare const useCapxulPermissionChange: (orgId: OrgId) => UseMutationResult<{
@@ -165,7 +165,7 @@ declare const useCapxulPermissionChange: (orgId: OrgId) => UseMutationResult<{
     readonly permissionId: PermissionId;
     readonly orgId: string;
     readonly type: "budget" | "managePeople";
-    readonly state: "active" | "pending" | "quarantined" | "revoked" | "superseded" | "suspended";
+    readonly state: "active" | "pending" | "revoked" | "superseded" | "suspended";
     readonly revision: number;
     readonly roleKey: RoleKey;
     readonly tokenAddress?: Address | undefined;
@@ -175,7 +175,7 @@ declare const useCapxulPermissionChange: (orgId: OrgId) => UseMutationResult<{
     readonly permissionId: PermissionId;
     readonly orgId: string;
     readonly type: "budget" | "managePeople";
-    readonly state: "active" | "pending" | "quarantined" | "revoked" | "superseded" | "suspended";
+    readonly state: "active" | "pending" | "revoked" | "superseded" | "suspended";
     readonly revision: number;
     readonly roleKey: RoleKey;
     readonly tokenAddress?: Address | undefined;
@@ -191,7 +191,7 @@ declare const useCapxulPermissionChange: (orgId: OrgId) => UseMutationResult<{
       readonly kind: "organization";
       readonly orgId: string;
     };
-    readonly state: "active" | "pending" | "quarantined" | "revoked" | "superseded" | "suspended";
+    readonly state: "active" | "pending" | "revoked" | "superseded" | "suspended";
   };
 }, CapxulError, import("@capxul/sdk").PermissionChangeInput>;
 declare const useCapxulPermissionAssign: (orgId: OrgId) => UseMutationResult<{
@@ -203,7 +203,7 @@ declare const useCapxulPermissionAssign: (orgId: OrgId) => UseMutationResult<{
     readonly permissionId: PermissionId;
     readonly orgId: string;
     readonly type: "budget" | "managePeople";
-    readonly state: "active" | "pending" | "quarantined" | "revoked" | "superseded" | "suspended";
+    readonly state: "active" | "pending" | "revoked" | "superseded" | "suspended";
     readonly revision: number;
     readonly roleKey: RoleKey;
     readonly tokenAddress?: Address | undefined;
@@ -213,7 +213,7 @@ declare const useCapxulPermissionAssign: (orgId: OrgId) => UseMutationResult<{
     readonly permissionId: PermissionId;
     readonly orgId: string;
     readonly type: "budget" | "managePeople";
-    readonly state: "active" | "pending" | "quarantined" | "revoked" | "superseded" | "suspended";
+    readonly state: "active" | "pending" | "revoked" | "superseded" | "suspended";
     readonly revision: number;
     readonly roleKey: RoleKey;
     readonly tokenAddress?: Address | undefined;
@@ -229,7 +229,7 @@ declare const useCapxulPermissionAssign: (orgId: OrgId) => UseMutationResult<{
       readonly kind: "organization";
       readonly orgId: string;
     };
-    readonly state: "active" | "pending" | "quarantined" | "revoked" | "superseded" | "suspended";
+    readonly state: "active" | "pending" | "revoked" | "superseded" | "suspended";
   };
 }, CapxulError, import("@capxul/sdk").PermissionAssignInput>;
 declare const useCapxulPermissionRevoke: (orgId: OrgId) => UseMutationResult<{
@@ -241,7 +241,7 @@ declare const useCapxulPermissionRevoke: (orgId: OrgId) => UseMutationResult<{
     readonly permissionId: PermissionId;
     readonly orgId: string;
     readonly type: "budget" | "managePeople";
-    readonly state: "active" | "pending" | "quarantined" | "revoked" | "superseded" | "suspended";
+    readonly state: "active" | "pending" | "revoked" | "superseded" | "suspended";
     readonly revision: number;
     readonly roleKey: RoleKey;
     readonly tokenAddress?: Address | undefined;
@@ -251,7 +251,7 @@ declare const useCapxulPermissionRevoke: (orgId: OrgId) => UseMutationResult<{
     readonly permissionId: PermissionId;
     readonly orgId: string;
     readonly type: "budget" | "managePeople";
-    readonly state: "active" | "pending" | "quarantined" | "revoked" | "superseded" | "suspended";
+    readonly state: "active" | "pending" | "revoked" | "superseded" | "suspended";
     readonly revision: number;
     readonly roleKey: RoleKey;
     readonly tokenAddress?: Address | undefined;
@@ -267,7 +267,7 @@ declare const useCapxulPermissionRevoke: (orgId: OrgId) => UseMutationResult<{
       readonly kind: "organization";
       readonly orgId: string;
     };
-    readonly state: "active" | "pending" | "quarantined" | "revoked" | "superseded" | "suspended";
+    readonly state: "active" | "pending" | "revoked" | "superseded" | "suspended";
   };
 }, CapxulError, import("@capxul/sdk").PermissionRevokeInput>;
 declare const useCapxulPermissionReplace: (orgId: OrgId) => UseMutationResult<{
@@ -279,7 +279,7 @@ declare const useCapxulPermissionReplace: (orgId: OrgId) => UseMutationResult<{
     readonly permissionId: PermissionId;
     readonly orgId: string;
     readonly type: "budget" | "managePeople";
-    readonly state: "active" | "pending" | "quarantined" | "revoked" | "superseded" | "suspended";
+    readonly state: "active" | "pending" | "revoked" | "superseded" | "suspended";
     readonly revision: number;
     readonly roleKey: RoleKey;
     readonly tokenAddress?: Address | undefined;
@@ -289,7 +289,7 @@ declare const useCapxulPermissionReplace: (orgId: OrgId) => UseMutationResult<{
     readonly permissionId: PermissionId;
     readonly orgId: string;
     readonly type: "budget" | "managePeople";
-    readonly state: "active" | "pending" | "quarantined" | "revoked" | "superseded" | "suspended";
+    readonly state: "active" | "pending" | "revoked" | "superseded" | "suspended";
     readonly revision: number;
     readonly roleKey: RoleKey;
     readonly tokenAddress?: Address | undefined;
@@ -305,7 +305,7 @@ declare const useCapxulPermissionReplace: (orgId: OrgId) => UseMutationResult<{
       readonly kind: "organization";
       readonly orgId: string;
     };
-    readonly state: "active" | "pending" | "quarantined" | "revoked" | "superseded" | "suspended";
+    readonly state: "active" | "pending" | "revoked" | "superseded" | "suspended";
   };
 }, CapxulError, import("@capxul/sdk").PermissionReplaceInput>;
 declare function useCapxulPermissions(orgId: OrgId, options?: {
@@ -315,11 +315,15 @@ declare function useCapxulPermission(orgId: OrgId, permissionId: string | undefi
 //#endregion
 //#region src/hooks/use-capxul-activity.d.ts
 declare function useCapxulActivity(params?: ActivityListParams): UseQueryResult<ActivityPage, CapxulError>;
-declare function useCapxulActivityDetail(reference: ActivityReference | undefined): UseQueryResult<ActivityDetail | null, CapxulError>;
-declare function useCapxulAnnotateMovement(): UseMutationResult<MovementAnnotation, CapxulError, ActivityAnnotationInput>;
+declare function useCapxulActivityDetail(reference: ActivityReference | undefined, actor?: ActorReference): UseQueryResult<ActivityDetail | null, CapxulError>;
+declare function useCapxulAnnotateMovement(): UseMutationResult<ActivityAnnotation, CapxulError, ActivityAnnotationInput>;
 //#endregion
 //#region src/hooks/use-capxul-holdings.d.ts
-declare function useCapxulHoldings(): UseQueryResult<CurrentHoldings, CapxulError>;
+interface UseCapxulHoldingsParams {
+  /** Omitted = the signed-in person. SDK core already accepts one. */
+  readonly actor?: ActorReference;
+}
+declare function useCapxulHoldings(params?: UseCapxulHoldingsParams): UseQueryResult<CurrentHoldings, CapxulError>;
 //#endregion
 //#region src/hooks/use-capxul-orgs.d.ts
 /**
@@ -600,13 +604,13 @@ interface CapxulContactsProps {
   readonly onFailed: (error: CapxulError) => void;
   readonly children: ReactNode;
 }
-declare function Root$3({
+declare function Root$4({
   actor,
   onAdded,
   onFailed,
   children
 }: CapxulContactsProps): import("react/jsx-runtime").JSX.Element;
-declare function Summary({
+declare function Summary$1({
   children
 }: {
   readonly children: (slice: ContactsSummarySlice) => ReactNode;
@@ -624,12 +628,216 @@ declare function Add({
   readonly children: (slice: ContactsAddSlice) => ReactNode;
 }): import("react/jsx-runtime").JSX.Element;
 /** The compound shape the app's own design system already uses (`StatusTabs`). */
-declare const CapxulContacts: typeof Root$3 & {
-  Summary: typeof Summary;
+declare const CapxulContacts: typeof Root$4 & {
+  Summary: typeof Summary$1;
   List: typeof List;
   Add: typeof Add;
 };
 //#endregion
+//#region src/headless/activity/types.d.ts
+/** The settled transfer a row was built from. The app builds the explorer URL. */
+interface ActivityReceipt {
+  readonly chainId: number;
+  readonly transactionHash: string;
+}
+/**
+ * One finished row. A DISCRIMINATED UNION on `kind`, because a Movement has no
+ * payment status: one flat shape carrying `status` for both kinds cannot
+ * compile. The two branches match the two branches every app mapper already
+ * writes.
+ */
+type ActivityRow = {
+  readonly kind: "payment";
+  readonly reference: ActivityReference;
+  readonly direction: PaymentDirection;
+  readonly counterpartyLabel: string;
+  readonly amountDisplay: string;
+  readonly signedAmountDisplay: string;
+  readonly createdAt: number;
+  readonly ledgerKind: "Payment" | "Payout" | "Deposit";
+  readonly paymentType: PaymentType;
+  readonly status: PaymentStatus;
+  readonly phase: ActivityPhase;
+  readonly receipt: ActivityReceipt | null;
+} | {
+  readonly kind: "movement";
+  readonly reference: ActivityReference;
+  readonly direction: PaymentDirection;
+  readonly counterpartyLabel: string;
+  readonly amountDisplay: string;
+  readonly signedAmountDisplay: string;
+  readonly createdAt: number;
+  readonly classification: "movement_only_outflow";
+  readonly phase: ActivityPhase;
+  readonly receipt: ActivityReceipt;
+};
+/**
+ * `"last30days"` is the last 30 whole UTC days including today. Quantizing to
+ * the UTC day keeps the cache key stable for a whole day instead of changing
+ * on every render.
+ */
+type SummaryWindow = "all" | "last30days" | ActivityRange;
+/**
+ * Finished money strings for ONE currency bucket, so no consumer indexes an
+ * array of per-currency totals. All four strings are `null` and `count` is `0`
+ * when the window holds no activity — we say there is nothing, the app says it
+ * in its own words.
+ */
+interface ActivitySummarySlice {
+  readonly currency: string | null;
+  readonly moneyIn: string | null;
+  readonly moneyOut: string | null;
+  readonly net: string | null;
+  readonly pending: string | null;
+  /** A count is not money, so it is not formatted. */
+  readonly count: number;
+  readonly isLoading: boolean;
+  readonly error: CapxulError | null;
+}
+interface ActivityFilterValues {
+  readonly kind?: ActivityKind;
+  readonly direction?: PaymentDirection;
+  readonly status?: readonly PaymentStatus[];
+}
+interface ActivityFiltersSlice {
+  readonly values: ActivityFilterValues;
+  readonly set: {
+    readonly kind: (value?: ActivityKind) => void;
+    readonly direction: (value?: PaymentDirection) => void; /** REPLACES the array; it does not toggle one value. */
+    readonly status: (value: readonly PaymentStatus[]) => void;
+    readonly clear: () => void;
+  };
+  /** CODES, never labels. There is no `{value, label}` pair in this seam. */
+  readonly options: {
+    readonly kind: readonly ActivityKind[];
+    readonly direction: readonly PaymentDirection[];
+    readonly status: readonly PaymentStatus[];
+  };
+}
+interface ActivitySearchSlice {
+  readonly value: string;
+  readonly change: (text: string) => void;
+}
+interface ActivityRowsSlice {
+  /** Already filtered and already searched. */
+  readonly rows: readonly ActivityRow[];
+  readonly isLoading: boolean;
+  readonly error: CapxulError | null;
+  readonly retry: () => void;
+  /** Server read time of the newest page, so the app can say which read is older. */
+  readonly observedAt: number | null;
+}
+interface ActivityLoadMoreSlice {
+  readonly hasMore: boolean;
+  readonly loadMore: () => void;
+  readonly isLoadingMore: boolean;
+  /**
+   * Attach to whatever the screen renders at the bottom of the list. Where
+   * `IntersectionObserver` is undefined — server rendering, and the jsdom test
+   * environment — attaching is a no-op and `loadMore()` stays callable.
+   *
+   * A CALLBACK ref, not the wider `Ref<HTMLElement>`: `RefObject` is invariant,
+   * so `Ref<HTMLElement>` refuses to attach to a `<div>`, which is exactly what
+   * a screen renders at the bottom of its list.
+   */
+  readonly sentinelRef: RefCallback<HTMLElement>;
+}
+interface ActivityDetailSlice {
+  /** ONE finished document, never the array, so no consumer writes `documents[0]`. */
+  readonly receiptDocument: PaymentDocumentRef | null;
+  readonly openReceiptDocument: () => Promise<PaymentDocumentRender>;
+  readonly isOpeningDocument: boolean;
+  readonly memo: string;
+  readonly setMemo: (text: string) => void;
+  readonly saveMemo: () => void;
+  readonly isSavingMemo: boolean;
+  readonly isLoading: boolean;
+  readonly error: CapxulError | null;
+}
+interface CsvExport {
+  readonly text: string;
+  readonly rowCount: number;
+  /** The 5,000-row ceiling was reached and rows were left unread. */
+  readonly truncated: boolean;
+}
+interface ActivityExportSlice {
+  readonly toCsv: () => Promise<CsvExport>;
+  readonly isExporting: boolean;
+}
+//#endregion
+//#region src/headless/activity/activity.d.ts
+interface CapxulActivityProps {
+  /** Omitted = the signed-in person. */
+  readonly actor?: ActorReference;
+  /**
+   * 1..100, default 25. The root CLAMPS an out-of-range value into that band
+   * and warns once in development; it never throws, because a bad prop must not
+   * blank a screen. The band is the backend's own.
+   */
+  readonly pageSize?: number;
+  readonly children: ReactNode;
+}
+declare function Root$3({
+  actor,
+  pageSize,
+  children
+}: CapxulActivityProps): import("react/jsx-runtime").JSX.Element;
+/**
+ * The one part that holds a query rather than reading the engine's: it takes a
+ * `window` prop, and two placements can ask for different windows, so a single
+ * pre-fetched result cannot serve both. It still holds no logic and draws
+ * nothing.
+ */
+declare function Summary({
+  window,
+  children
+}: {
+  readonly window?: SummaryWindow;
+  readonly children: (slice: ActivitySummarySlice) => ReactNode;
+}): import("react/jsx-runtime").JSX.Element;
+declare function Filters({
+  children
+}: {
+  readonly children: (slice: ActivityFiltersSlice) => ReactNode;
+}): import("react/jsx-runtime").JSX.Element;
+declare function Search({
+  children
+}: {
+  readonly children: (slice: ActivitySearchSlice) => ReactNode;
+}): import("react/jsx-runtime").JSX.Element;
+declare function Rows({
+  children
+}: {
+  readonly children: (slice: ActivityRowsSlice) => ReactNode;
+}): import("react/jsx-runtime").JSX.Element;
+declare function LoadMore({
+  children
+}: {
+  readonly children: (slice: ActivityLoadMoreSlice) => ReactNode;
+}): import("react/jsx-runtime").JSX.Element;
+declare function Detail({
+  reference,
+  children
+}: {
+  readonly reference?: ActivityReference;
+  readonly children: (slice: ActivityDetailSlice) => ReactNode;
+}): import("react/jsx-runtime").JSX.Element;
+declare function Export({
+  children
+}: {
+  readonly children: (slice: ActivityExportSlice) => ReactNode;
+}): import("react/jsx-runtime").JSX.Element;
+/** The compound shape the app's own design system already uses (`StatusTabs`). */
+declare const CapxulActivity: typeof Root$3 & {
+  Summary: typeof Summary;
+  Filters: typeof Filters;
+  Search: typeof Search;
+  Rows: typeof Rows;
+  LoadMore: typeof LoadMore;
+  Detail: typeof Detail;
+  Export: typeof Export;
+};
+//#endregion
 //#region src/headless/send-money/use-recipient-resolution.d.ts
 type SendMoneyRecipientMethod = "username" | "email-address";
 type SendMoneyRecipientStatus = "empty" | "checking" | "found" | "not-found" | "failed";
@@ -834,4 +1042,31 @@ declare const CapxulDashboardAccess: typeof Root & {
   Granted: typeof Granted;
 };
 //#endregion
-export { type AccountFailure, type AccountProgress, type ActionResult, type AuthenticatedState, type AuthenticationSlots, type CanReason, type CapxulAuth, CapxulAuthenticationController, type CapxulBootstrapState, type CapxulBootstrapStatus, CapxulContacts, type CapxulContactsProps, CapxulDashboardAccess, type CapxulDashboardAccessProps, CapxulOnboardingController, CapxulOrgMember, type CapxulOrgMemberProps, 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 CreateOrganizationSubmission, type DashboardAccessErrorSlice, type DashboardAccessPhase, type DashboardAccessRedirectSlice, type DashboardScope, type Destination, type FaultedState, 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 PendingAuthState, type ProfileDetails, type ProfileDraft, type ProfileSlotProps, type ReadyDestination, type RetryAction, type SendActor, type SendMoneyActionsSlice, type SendMoneyAmountSlice, type SendMoneyAssetError, type SendMoneyAssetOption, type SendMoneyAssetSlice, type SendMoneyRecipientMethod, type SendMoneyRecipientSlice, type SendMoneyRecipientStatus, type SendResult, type SentPayment, type SignedOutState, type Slot, type UseCapxulAccountBalanceOptions, type UseCapxulAccountBalanceReturn, type UseCapxulAccountFundReturn, type UseCapxulCreateCommitmentReturn, type UseCapxulCreateOrgReturn, 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 UseCapxulUsernameAvailabilityReturn, type UsernameAvailability, acknowledgeOnboardingDestination, activeOnboardingRecovery, clearOnboardingJourney, currentOnboardingJourneyId, entered, invalidateOnboardingJourneyObservation, isClaimed, isRestoring, loadOnboardingJourney, onboardingJourneyPosition, saveOnboardingJourney, startOnboardingJourney, useCapxul, useCapxulAccountBalance, useCapxulAccountFund, useCapxulActivity, useCapxulActivityDetail, useCapxulAnnotateMovement, useCapxulAuth, useCapxulCancelPayment, useCapxulClaimPayment, useCapxulClientOrNull, useCapxulCreateCommitment, useCapxulCreateOrg, useCapxulDestination, useCapxulHoldings, useCapxulIdentity, useCapxulImageUpload, useCapxulInviteMember, useCapxulOrgMembers, useCapxulOrgRoles, useCapxulOrgTreasury, useCapxulOrganizationPay, useCapxulOrganizationPayBatch, useCapxulOrgs, useCapxulPay, useCapxulPayment, useCapxulPayments, useCapxulPermission, useCapxulPermissionAssign, useCapxulPermissionChange, useCapxulPermissionCreate, useCapxulPermissionReplace, useCapxulPermissionRevoke, useCapxulPermissions, useCapxulProfile, useCapxulRedirectPayment, useCapxulSend, useCapxulTransitions, useCapxulUsernameAvailability };
+//#region src/internal/reactivity-keys.d.ts
+declare const capxulKeys: {
+  root: readonly ["capxul"];
+  profile: readonly ["capxul", "profile"];
+  usernameAvailability: (username: string) => readonly ["capxul", "profile", "username-availability", string];
+  account: readonly ["capxul", "account"];
+  provisioning: readonly ["capxul", "provisioning"];
+  binding: readonly ["capxul", "binding"];
+  accountBalance: readonly ["capxul", "accountBalance"];
+  orgs: readonly ["capxul", "orgs"];
+  org: (orgId: OrgId | undefined) => readonly ["capxul", "org", "pending" | OrgId];
+  orgMembers: (orgId: OrgId | undefined) => readonly ["capxul", "org", "pending" | OrgId, "members"];
+  orgRoles: (orgId: OrgId | undefined) => readonly ["capxul", "org", "pending" | OrgId, "roles"];
+  orgTreasury: (orgId: OrgId | undefined) => readonly ["capxul", "org", "pending" | OrgId, "treasury"];
+  orgPermissions: (orgId: OrgId | undefined) => readonly ["capxul", "org", "pending" | OrgId, "permissions"];
+  orgMe: (orgId: OrgId | undefined) => readonly ["capxul", "org", "pending" | OrgId, "me"];
+  orgLifecycle: (orgId: OrgId | undefined) => readonly ["capxul", "org", "pending" | OrgId, "lifecycle"];
+  contacts: (scope: string) => readonly ["capxul", "contacts", string];
+  contactsList: (scope: string, includeHidden: boolean) => readonly ["capxul", "contacts", string, "all" | "visible"];
+  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];
+  holdings: (actor?: ActorReference) => readonly ["capxul", "holdings", "self" | ActorReference];
+  payments: readonly ["capxul", "payments"];
+  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, 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 CreateOrganizationSubmission, type CsvExport, type DashboardAccessErrorSlice, type DashboardAccessPhase, type DashboardAccessRedirectSlice, type DashboardScope, type Destination, type FaultedState, 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 PendingAuthState, type ProfileDetails, type ProfileDraft, type ProfileSlotProps, type ReadyDestination, type RetryAction, type SendActor, type SendMoneyActionsSlice, type SendMoneyAmountSlice, type SendMoneyAssetError, type SendMoneyAssetOption, type SendMoneyAssetSlice, type SendMoneyRecipientMethod, type SendMoneyRecipientSlice, type SendMoneyRecipientStatus, type SendResult, type SentPayment, type SignedOutState, type Slot, type SummaryWindow, type UseCapxulAccountBalanceOptions, type UseCapxulAccountBalanceReturn, type UseCapxulAccountFundReturn, type UseCapxulCreateCommitmentReturn, type UseCapxulCreateOrgReturn, 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 UseCapxulUsernameAvailabilityReturn, type UsernameAvailability, 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, useCapxulHoldings, useCapxulIdentity, useCapxulImageUpload, useCapxulInviteMember, useCapxulOrgMembers, useCapxulOrgRoles, useCapxulOrgTreasury, useCapxulOrganizationPay, useCapxulOrganizationPayBatch, useCapxulOrgs, useCapxulPay, useCapxulPayment, useCapxulPayments, useCapxulPermission, useCapxulPermissionAssign, useCapxulPermissionChange, useCapxulPermissionCreate, useCapxulPermissionReplace, useCapxulPermissionRevoke, useCapxulPermissions, useCapxulProfile, useCapxulRedirectPayment, useCapxulSend, useCapxulTransitions, useCapxulUsernameAvailability };

package/dist/index.mjs

@@ -1,8 +1,8 @@
 "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-VwUPB619.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-DLBe4-OP.mjs";
 import { createContext, useCallback, useContext, useEffect, useMemo, useRef, useState, useSyncExternalStore } from "react";
-import { useMutation, useQuery, useQueryClient } from "@tanstack/react-query";
-import { CapxulError, Errors, fingerprintPaymentIntent, formatMoney, isClaimed, isClaimed as isClaimed$1, isMoneyParseError, isRestoring, isRestoring as isRestoring$1, parseMoney, resolveIdentityDestination } from "@capxul/sdk";
+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";
 import { Fragment, jsx } from "react/jsx-runtime";
 //#region src/internal/require-bootstrapped-client.ts
 /**
@@ -429,14 +429,14 @@ function useCapxulActivity(params) {
 		enabled: client !== null && identity !== null && isClaimed$1(identity)
 	});
 }
-function useCapxulActivityDetail(reference) {
+function useCapxulActivityDetail(reference, actor) {
 	const client = useCapxulClientOrNull();
 	const identity = useCapxulIdentityOrNull();
 	return useQuery({
-		queryKey: capxulKeys.activityDetail(reference),
+		queryKey: capxulKeys.activityDetail(reference, actor),
 		queryFn: async () => {
 			if (reference === void 0) throw Errors.invalidInput("reference", "required for activity.get");
-			return unwrapCapxulResult(await requireBootstrappedClient(client, "activity.get").activity.get(reference));
+			return unwrapCapxulResult(await requireBootstrappedClient(client, "activity.get").activity.get(reference, actor === void 0 ? void 0 : { actor }));
 		},
 		enabled: client !== null && reference !== void 0 && identity !== null && isClaimed$1(identity)
 	});
@@ -453,13 +453,14 @@ function useCapxulAnnotateMovement() {
 }
 //#endregion
 //#region src/hooks/use-capxul-holdings.ts
-function useCapxulHoldings() {
+function useCapxulHoldings(params) {
 	const client = useCapxulClientOrNull();
 	const identity = useCapxulIdentityOrNull();
+	const actor = params?.actor;
 	return useQuery({
-		queryKey: capxulKeys.holdings,
+		queryKey: capxulKeys.holdings(actor),
 		queryFn: async () => {
-			return unwrapCapxulResult(await requireBootstrappedClient(client, "holdings.current").holdings.current());
+			return unwrapCapxulResult(await requireBootstrappedClient(client, "holdings.current").holdings.current(actor === void 0 ? void 0 : { actor }));
 		},
 		enabled: client !== null && identity !== null && isClaimed$1(identity)
 	});
@@ -1013,7 +1014,7 @@ function useContactsContext() {
 	if (engine === null) throw new Error("CapxulContacts parts must be used inside <CapxulContacts>");
 	return engine;
 }
-function Root$3({ actor, onAdded, onFailed, children }) {
+function Root$4({ actor, onAdded, onFailed, children }) {
 	const engine = useContacts({
 		actor,
 		onAdded,
@@ -1024,7 +1025,7 @@ function Root$3({ actor, onAdded, onFailed, children }) {
 		children
 	});
 }
-function Summary({ children }) {
+function Summary$1({ children }) {
 	return /* @__PURE__ */ jsx(Fragment, { children: children(useContactsSummary(useContactsContext())) });
 }
 function List({ limit, show, children }) {
@@ -1037,12 +1038,672 @@ function Add({ children }) {
 	return /* @__PURE__ */ jsx(Fragment, { children: children(useContactsContext().add) });
 }
 /** The compound shape the app's own design system already uses (`StatusTabs`). */
-const CapxulContacts = Object.assign(Root$3, {
-	Summary,
+const CapxulContacts = Object.assign(Root$4, {
+	Summary: Summary$1,
 	List,
 	Add
 });
 //#endregion
+//#region src/internal/as-capxul-error.ts
+/**
+* TanStack types a query error as `Error`. Every query in this package throws
+* through `unwrapCapxulResult` or `requireBootstrappedClient`, so the value IS a
+* `CapxulError`. Anything else is a defect inside this package: it is WRAPPED
+* with the `UNKNOWN` code and its cause, never swallowed, because a slice hands
+* the app an error VALUE carrying a code and the app writes the sentence
+* (ADR-0023).
+*/
+function asCapxulError(error) {
+	if (error === null) return null;
+	return isCapxulError(error) ? error : Errors.unknown(error);
+}
+//#endregion
+//#region src/headless/activity/enabled.ts
+/**
+* The one gate every read under `CapxulActivity` shares — the engine, each
+* `.Summary` lane, and each `.Detail` lane. One function, because a gate that
+* differs between the list and the detail lets a screen load rows it can never
+* open.
+*
+* Every backend activity read resolves the authenticated Account before it
+* resolves either a personal or Organization actor. Wait for that Account so a
+* new session cannot issue requests the backend must refuse.
+*/
+function useActivityEnabled() {
+	const client = useCapxulClientOrNull();
+	const identity = useCapxulIdentityOrNull();
+	return client !== null && identity !== null && isClaimed$1(identity);
+}
+//#endregion
+//#region src/headless/activity/detail.ts
+/**
+* ONE finished document, never the array, so no consumer writes `documents[0]`:
+* the payslip, else the receipt, else nothing. Those two kinds are the ones the
+* Download receipt button is for. A Movement detail carries no documents.
+*/
+function pickReceiptDocument(detail) {
+	if (detail === null || detail.kind !== "payment") return null;
+	const documents = detail.payment.documents;
+	return documents.find((document) => document.kind === "payslip") ?? documents.find((document) => document.kind === "receipt") ?? null;
+}
+/**
+* The root actor and the whole reference are included. A payment reference can
+* carry its own actor, and a Movement reference relies on the root actor. A key
+* of kind and id alone would show one actor's draft memo on the other actor's
+* row, and save it there.
+*
+* The parts go into an ARRAY, and the array is what gets serialized. A joined
+* string collides: an organization whose id is the sentinel `self`, or any id
+* that carries the separator, produces another reference's key. Serializing the
+* reference OBJECT collides the other way, because property order is not part of
+* a reference's meaning and a literal written `{ id, kind }` must not read as a
+* different row. The array is ordered here, by this function, so neither the
+* caller's property order nor the content of an id can move a part.
+*/
+function actorKey(actor) {
+	if (actor === void 0) return null;
+	return actor.kind === "organization" ? [actor.kind, actor.organizationId] : [actor.kind];
+}
+function activityDetailKey(actor, reference) {
+	if (reference === void 0) return JSON.stringify([actorKey(actor), null]);
+	const referenceActor = reference.kind === "payment" ? reference.actor : void 0;
+	return JSON.stringify([actorKey(actor), [
+		reference.kind,
+		reference.id,
+		actorKey(referenceActor)
+	]]);
+}
+function useActivityDetail(reference, actor) {
+	const client = useCapxulClientOrNull();
+	const enabled = useActivityEnabled() && reference !== void 0;
+	const detail = useQuery({
+		queryKey: capxulKeys.activityDetail(reference, actor),
+		queryFn: async () => {
+			if (reference === void 0) throw Errors.invalidInput("reference", "required for activity.get");
+			return unwrapCapxulResult(await requireBootstrappedClient(client, "activity.get").activity.get(reference, actor === void 0 ? void 0 : { actor }));
+		},
+		enabled
+	});
+	const receiptDocument = pickReceiptDocument(detail.data ?? null);
+	const [isOpeningDocument, setIsOpeningDocument] = useState(false);
+	const openReceiptDocument = useCallback(async () => {
+		if (reference === void 0 || receiptDocument === null) throw Errors.invalidInput("receiptDocument", "no renderable document on this row");
+		setIsOpeningDocument(true);
+		try {
+			return unwrapCapxulResult(await requireBootstrappedClient(client, "paymentDocuments.render").paymentDocuments.render(receiptDocument.documentHash));
+		} finally {
+			setIsOpeningDocument(false);
+		}
+	}, [
+		client,
+		receiptDocument,
+		reference
+	]);
+	const [typed, setTyped] = useState(null);
+	const annotate = useCapxulAnnotateMovement();
+	const saveMemo = useCallback(() => {
+		if (reference === void 0 || typed === null) return;
+		annotate.mutate({
+			...actor === void 0 ? {} : { actor },
+			reference,
+			memo: typed
+		});
+	}, [
+		actor,
+		annotate,
+		reference,
+		typed
+	]);
+	return {
+		receiptDocument,
+		openReceiptDocument,
+		isOpeningDocument,
+		memo: typed ?? detail.data?.annotation?.memo ?? "",
+		setMemo: setTyped,
+		saveMemo,
+		isSavingMemo: annotate.isPending,
+		isLoading: enabled && detail.isLoading,
+		error: asCapxulError(detail.error) ?? annotate.error ?? null
+	};
+}
+//#endregion
+//#region src/headless/activity/summary.ts
+const DAY_MS = 864e5;
+/**
+* `"last30days"` is the last 30 whole UTC days including today. Quantizing to
+* the UTC day keeps the cache key stable for a whole day instead of changing on
+* every render.
+*/
+function resolveWindow(window, now) {
+	if (window === "all") return void 0;
+	if (window === "last30days") return { from: Math.floor(now / DAY_MS) * DAY_MS - 29 * DAY_MS };
+	return window;
+}
+/** An integer raw-unit string lifted into a major-unit decimal string. */
+function majorUnits(raw, decimals) {
+	const negative = raw.startsWith("-");
+	const digits = negative ? raw.slice(1) : raw;
+	const sign = negative ? "-" : "";
+	if (decimals === 0) return `${sign}${digits}`;
+	const padded = digits.padStart(decimals + 1, "0");
+	const cut = padded.length - decimals;
+	return `${sign}${padded.slice(0, cut)}.${padded.slice(cut)}`;
+}
+function absoluteNet(total) {
+	const net = BigInt(total.net);
+	return net < 0n ? -net : net;
+}
+/**
+* Buckets carry different `decimals`, so their raw integers are not comparable.
+* Both are scaled to the wider precision before the magnitudes are ordered.
+*/
+function compareNet(left, right) {
+	const width = Math.max(left.decimals, right.decimals);
+	const scaledLeft = absoluteNet(left) * 10n ** BigInt(width - left.decimals);
+	const scaledRight = absoluteNet(right) * 10n ** BigInt(width - right.decimals);
+	if (scaledLeft === scaledRight) return 0;
+	return scaledLeft < scaledRight ? -1 : 1;
+}
+/**
+* Which currency `.Summary` shows: the bucket matching the primary holding's
+* currency, else the bucket with the largest absolute `net`, breaking a tie on
+* currency code ascending so the choice is stable across reloads.
+*
+* The primary holding is matched on `available.currency` — the consumer
+* `CurrencyCode` — and NOT on `Holding.symbol`, which is the raw token ticker
+* ("USDX") and can never equal a bucket's currency ("USD"). See the contract
+* correction on #1449.
+*/
+function pickBucket(totals, primaryCurrency) {
+	if (primaryCurrency !== null) {
+		const matched = totals.find((total) => total.currency === primaryCurrency);
+		if (matched !== void 0) return matched;
+	}
+	let best = null;
+	for (const total of totals) {
+		if (best === null) {
+			best = total;
+			continue;
+		}
+		const order = compareNet(total, best);
+		if (order > 0 || order === 0 && total.currency < best.currency) best = total;
+	}
+	return best;
+}
+/**
+* The current UTC day number, which advances ON ITS OWN at UTC midnight.
+*
+* The day is NOT held in state. It is read at every render, so it can never be
+* stale — not after a mount that sat through midnight, and not when a part
+* mounted on a fixed window is later switched to a rolling one. State holds
+* only `tick`, whose single job is to force the render that a screen sitting
+* idle would otherwise never do: React recomputes nothing on its own, so an
+* untouched summary would hold yesterday's boundary indefinitely.
+*
+* The effect depends on `tick`, not on the day, so the timer re-arms whatever
+* the clock says when it fires. A wake a millisecond early re-arms for the
+* boundary still ahead instead of silently ending the rollover, and a wake
+* hours late — a throttled tab, a sleeping machine — lands on the true day
+* rather than drifting one day per sleep.
+*
+* `active` is false for the windows that do not roll, so a fixed window arms no
+* timer at all.
+*/
+function useUtcDay(active) {
+	const [tick, setTick] = useState(0);
+	useEffect(() => {
+		if (!active) return;
+		const timer = setTimeout(() => {
+			setTick((value) => value + 1);
+		}, DAY_MS - Date.now() % DAY_MS + 1);
+		return () => {
+			clearTimeout(timer);
+		};
+	}, [active, tick]);
+	return Math.floor(Date.now() / DAY_MS);
+}
+function useActivitySummary(actor, window) {
+	const client = useCapxulClientOrNull();
+	const enabled = useActivityEnabled();
+	const range = resolveWindow(window, useUtcDay(window === "last30days") * DAY_MS);
+	const summary = useQuery({
+		queryKey: capxulKeys.activitySummary(actor, range),
+		queryFn: async () => {
+			const params = {};
+			if (actor !== void 0) params.actor = actor;
+			if (range !== void 0) params.window = range;
+			return unwrapCapxulResult(await requireBootstrappedClient(client, "activity.summary").activity.summary(params));
+		},
+		enabled
+	});
+	const primary = useQuery({
+		queryKey: [...capxulKeys.holdings(actor), "primary"],
+		queryFn: async () => {
+			return unwrapCapxulResult(await requireBootstrappedClient(client, "holdings.primary").holdings.primary(actor === void 0 ? void 0 : { actor }));
+		},
+		enabled
+	});
+	const totals = summary.data?.totals;
+	const primaryCurrency = primary.data?.available.currency ?? null;
+	const isLoading = summary.isLoading || primary.isLoading;
+	const bucket = useMemo(() => totals === void 0 || isLoading ? null : pickBucket(totals, primaryCurrency), [
+		isLoading,
+		primaryCurrency,
+		totals
+	]);
+	if (bucket === null) return {
+		currency: null,
+		moneyIn: null,
+		moneyOut: null,
+		net: null,
+		pending: null,
+		count: summary.data?.count ?? 0,
+		isLoading,
+		error: asCapxulError(summary.error)
+	};
+	const display = (raw) => formatMoney({
+		currency: bucket.currency,
+		value: majorUnits(raw, bucket.decimals),
+		decimals: bucket.decimals
+	});
+	return {
+		currency: bucket.currency,
+		moneyIn: display(bucket.in),
+		moneyOut: display(bucket.out),
+		net: display(bucket.net),
+		pending: display(bucket.pendingIn),
+		count: summary.data?.count ?? 0,
+		isLoading,
+		error: asCapxulError(summary.error)
+	};
+}
+//#endregion
+//#region src/headless/activity/rows.ts
+/**
+* A Movement's phase is DERIVED, not asserted: `movementItems` returns `null`
+* for any Movement whose `canonicalState` is not `"finalized"`
+* (`activityList.ts:120`), so a Movement that reaches a page is finished and
+* carries no verdict of its own.
+*/
+const MOVEMENT_PHASE = Object.freeze({
+	terminal: true,
+	outcome: "neutral",
+	needsAction: false
+});
+/** The sign grammar of the app's `formatDirectionalAmount` — unsigned for `self`. */
+const SIGN = Object.freeze({
+	in: "+",
+	out: "-",
+	self: ""
+});
+function toActivityRow(item, actor) {
+	const amountDisplay = formatMoney(item.amount);
+	const signedAmountDisplay = `${SIGN[item.direction]}${amountDisplay}`;
+	if (item.kind === "movement") return {
+		kind: "movement",
+		reference: {
+			kind: "movement",
+			id: item.id
+		},
+		direction: item.direction,
+		counterpartyLabel: item.counterpartyLabel,
+		amountDisplay,
+		signedAmountDisplay,
+		createdAt: item.createdAt,
+		classification: item.classification,
+		phase: MOVEMENT_PHASE,
+		receipt: item.receipt
+	};
+	return {
+		kind: "payment",
+		reference: actor === void 0 ? {
+			kind: "payment",
+			id: item.id
+		} : {
+			kind: "payment",
+			id: item.id,
+			actor
+		},
+		direction: item.direction,
+		counterpartyLabel: item.counterpartyLabel,
+		amountDisplay,
+		signedAmountDisplay,
+		createdAt: item.createdAt,
+		ledgerKind: item.ledgerKind,
+		paymentType: item.paymentType,
+		status: item.status,
+		phase: paymentPhase(item.status),
+		receipt: item.receipt
+	};
+}
+/**
+* The exact field set `.Search` matches, case-insensitively, joined with a
+* space. Two of today's searchable strings drop out on purpose: `account` is
+* the currency-to-name guess this item deletes, and `statusLabel` is app copy —
+* the Status dropdown, wired up in the same change, is the affordance for
+* filtering by status and it uses the app's own words.
+*/
+function searchableText(row) {
+	return (row.kind === "payment" ? [
+		row.counterpartyLabel,
+		row.amountDisplay,
+		row.status,
+		row.paymentType,
+		row.ledgerKind
+	] : [
+		row.counterpartyLabel,
+		row.amountDisplay,
+		row.classification
+	]).join(" ").toLowerCase();
+}
+function matchesSearch(row, query) {
+	const needle = query.trim().toLowerCase();
+	return needle === "" || searchableText(row).includes(needle);
+}
+//#endregion
+//#region src/headless/activity/csv.ts
+/** In this order. A header row is always written, even with no rows. */
+const COLUMNS = [
+	"Date",
+	"Kind",
+	"Type",
+	"Counterparty",
+	"Direction",
+	"Amount",
+	"Currency",
+	"Status",
+	"Reference",
+	"Transaction hash"
+];
+const FORMULA_LEAD = /^[=+\-@\t\r\n]/;
+const PLAIN_NUMBER = /^-?\d+(\.\d+)?$/;
+/**
+* RFC 4180: every field is quoted, and an embedded quote is doubled. A field
+* that would open a formula is first prefixed with an apostrophe, which the
+* spreadsheet consumes and renders as text.
+*/
+function escape(field) {
+	return `"${(FORMULA_LEAD.test(field) && !PLAIN_NUMBER.test(field) ? `'${field}` : field).replaceAll("\"", "\"\"")}"`;
+}
+function record(fields) {
+	return fields.map(escape).join(",");
+}
+/**
+* `Amount` is the major-unit decimal value, not the display string, because a
+* CSV is data and the sheet has its own `Currency` column to pair it with. The
+* sign lives in `Direction`, which is the code the row carries.
+*/
+function buildCsv(items, actor, search) {
+	const records = [record(COLUMNS)];
+	for (const item of items) {
+		const row = toActivityRow(item, actor);
+		if (!matchesSearch(row, search)) continue;
+		records.push(record([
+			new Date(row.createdAt).toISOString(),
+			row.kind,
+			row.kind === "payment" ? row.paymentType : row.classification,
+			row.counterpartyLabel,
+			row.direction,
+			item.amount.value,
+			item.amount.currency,
+			row.kind === "payment" ? row.status : "",
+			row.reference.id,
+			row.receipt?.transactionHash ?? ""
+		]));
+	}
+	return {
+		text: records.join("\r\n"),
+		rowCount: records.length - 1
+	};
+}
+//#endregion
+//#region src/headless/activity/use-activity.ts
+/** The band is the backend's own — it hard-rejects a limit outside it. */
+const MIN_PAGE_SIZE = 1;
+const MAX_PAGE_SIZE = 100;
+const DEFAULT_PAGE_SIZE = 25;
+/**
+* The export ceiling is HARD: 50 pages of 100 is at most 5,000 rows. An
+* unbounded `do…while (cursor)` drain is the exact defect this item deletes
+* from the app; re-creating it inside the SDK would move the bug, not fix it.
+*/
+const EXPORT_PAGE_SIZE = MAX_PAGE_SIZE;
+const EXPORT_PAGE_CEILING = 50;
+const KIND_OPTIONS = Object.freeze(["payment", "movement"]);
+/** Clamps into 1..100. A non-number, or a fraction, lands on the default band. */
+function clampPageSize(pageSize) {
+	if (pageSize === void 0 || !Number.isFinite(pageSize)) return DEFAULT_PAGE_SIZE;
+	return Math.min(MAX_PAGE_SIZE, Math.max(MIN_PAGE_SIZE, Math.trunc(pageSize)));
+}
+function useActivity(input) {
+	const { actor, pageSize } = input;
+	const client = useCapxulClientOrNull();
+	const enabled = useActivityEnabled();
+	const limit = clampPageSize(pageSize);
+	const warned = useRef(false);
+	useEffect(() => {
+		if (warned.current || pageSize === void 0 || pageSize === limit) return;
+		warned.current = true;
+		if (process.env.NODE_ENV !== "production") console.warn(`CapxulActivity: pageSize ${String(pageSize)} is outside 1..100 and was clamped to ${String(limit)}.`);
+	}, [limit, pageSize]);
+	const [kind, setKind] = useState(void 0);
+	const [direction, setDirection] = useState(void 0);
+	const [status, setStatus] = useState([]);
+	const [searchText, setSearchText] = useState("");
+	const values = useMemo(() => ({
+		...kind === void 0 ? {} : { kind },
+		...direction === void 0 ? {} : { direction },
+		...status.length === 0 ? {} : { status }
+	}), [
+		direction,
+		kind,
+		status
+	]);
+	const filter = useMemo(() => Object.keys(values).length === 0 ? void 0 : values, [values]);
+	const listParams = useCallback((cursor, pageLimit) => {
+		const params = { limit: pageLimit };
+		if (actor !== void 0) params.actor = actor;
+		if (cursor !== void 0) params.cursor = cursor;
+		if (filter !== void 0) params.filter = filter;
+		return params;
+	}, [actor, filter]);
+	const query = useInfiniteQuery({
+		queryKey: [
+			...capxulKeys.activity,
+			"list",
+			actor ?? "self",
+			limit,
+			filter ?? "none"
+		],
+		queryFn: async ({ pageParam }) => {
+			return unwrapCapxulResult(await requireBootstrappedClient(client, "activity.list").activity.list(listParams(pageParam, limit)));
+		},
+		initialPageParam: void 0,
+		getNextPageParam: (last) => last.cursor ?? void 0,
+		enabled
+	});
+	const pages = query.data?.pages;
+	const rows = useMemo(() => {
+		return (pages?.flatMap((page) => page.items) ?? []).map((item) => toActivityRow(item, actor)).filter((row) => matchesSearch(row, searchText));
+	}, [
+		actor,
+		pages,
+		searchText
+	]);
+	const { fetchNextPage, hasNextPage, isFetchingNextPage, refetch } = query;
+	const pagingRef = useRef({
+		fetchNextPage,
+		hasNextPage,
+		isFetchingNextPage
+	});
+	useEffect(() => {
+		pagingRef.current = {
+			fetchNextPage,
+			hasNextPage,
+			isFetchingNextPage
+		};
+	});
+	const loadMore = useCallback(() => {
+		const paging = pagingRef.current;
+		if (!paging.hasNextPage || paging.isFetchingNextPage) return;
+		paging.fetchNextPage();
+	}, []);
+	const observerRef = useRef(null);
+	const sentinelRef = useCallback((node) => {
+		observerRef.current?.disconnect();
+		observerRef.current = null;
+		if (node === null || typeof IntersectionObserver === "undefined") return;
+		const observer = new IntersectionObserver((entries) => {
+			if (entries.some((entry) => entry.isIntersecting)) loadMore();
+		}, {
+			root: null,
+			rootMargin: "200px",
+			threshold: 0
+		});
+		observer.observe(node);
+		observerRef.current = observer;
+	}, [loadMore]);
+	const [isExporting, setIsExporting] = useState(false);
+	const toCsv = useCallback(async () => {
+		setIsExporting(true);
+		try {
+			const bootstrapped = requireBootstrappedClient(client, "activity.list");
+			const items = [];
+			let cursor;
+			for (let page = 0; page < EXPORT_PAGE_CEILING; page += 1) {
+				const result = unwrapCapxulResult(await bootstrapped.activity.list(listParams(cursor, EXPORT_PAGE_SIZE)));
+				items.push(...result.items);
+				cursor = result.cursor ?? void 0;
+				if (cursor === void 0) break;
+			}
+			return {
+				...buildCsv(items, actor, searchText),
+				truncated: cursor !== void 0
+			};
+		} finally {
+			setIsExporting(false);
+		}
+	}, [
+		actor,
+		client,
+		listParams,
+		searchText
+	]);
+	const clear = useCallback(() => {
+		setKind(void 0);
+		setDirection(void 0);
+		setStatus([]);
+	}, []);
+	const retry = useCallback(() => {
+		refetch();
+	}, [refetch]);
+	return {
+		actor,
+		filters: {
+			values,
+			set: {
+				kind: setKind,
+				direction: setDirection,
+				status: setStatus,
+				clear
+			},
+			options: {
+				kind: KIND_OPTIONS,
+				direction: PAYMENT_DIRECTIONS,
+				status: PAYMENT_STATUSES
+			}
+		},
+		search: {
+			value: searchText,
+			change: setSearchText
+		},
+		rows: {
+			rows,
+			isLoading: query.isLoading,
+			error: asCapxulError(query.error),
+			retry,
+			observedAt: pages === void 0 ? null : pages[pages.length - 1]?.observedAt ?? null
+		},
+		loadMore: {
+			hasMore: hasNextPage,
+			loadMore,
+			isLoadingMore: isFetchingNextPage,
+			sentinelRef
+		},
+		csv: {
+			toCsv,
+			isExporting
+		}
+	};
+}
+//#endregion
+//#region src/headless/activity/activity.tsx
+const ActivityContext = createContext(null);
+function useActivityContext() {
+	const engine = useContext(ActivityContext);
+	if (engine === null) throw new Error("CapxulActivity parts must be used inside <CapxulActivity>");
+	return engine;
+}
+function Root$3({ actor, pageSize, children }) {
+	const engine = useActivity({
+		...actor === void 0 ? {} : { actor },
+		...pageSize === void 0 ? {} : { pageSize }
+	});
+	return /* @__PURE__ */ jsx(ActivityContext.Provider, {
+		value: engine,
+		children
+	});
+}
+/**
+* The one part that holds a query rather than reading the engine's: it takes a
+* `window` prop, and two placements can ask for different windows, so a single
+* pre-fetched result cannot serve both. It still holds no logic and draws
+* nothing.
+*/
+function Summary({ window = "all", children }) {
+	return /* @__PURE__ */ jsx(Fragment, { children: children(useActivitySummary(useActivityContext().actor, window)) });
+}
+function Filters({ children }) {
+	return /* @__PURE__ */ jsx(Fragment, { children: children(useActivityContext().filters) });
+}
+function Search({ children }) {
+	return /* @__PURE__ */ jsx(Fragment, { children: children(useActivityContext().search) });
+}
+function Rows({ children }) {
+	return /* @__PURE__ */ jsx(Fragment, { children: children(useActivityContext().rows) });
+}
+function LoadMore({ children }) {
+	return /* @__PURE__ */ jsx(Fragment, { children: children(useActivityContext().loadMore) });
+}
+/**
+* The second part that holds a query: it takes a `reference` prop and the root
+* has no idea which row was clicked. With no `reference` it issues no request.
+*/
+function DetailInstance({ actor, reference, children }) {
+	return /* @__PURE__ */ jsx(Fragment, { children: children(useActivityDetail(reference, actor)) });
+}
+function Detail({ reference, children }) {
+	const { actor } = useActivityContext();
+	return /* @__PURE__ */ jsx(DetailInstance, {
+		actor,
+		reference,
+		children
+	}, activityDetailKey(actor, reference));
+}
+function Export({ children }) {
+	return /* @__PURE__ */ jsx(Fragment, { children: children(useActivityContext().csv) });
+}
+/** The compound shape the app's own design system already uses (`StatusTabs`). */
+const CapxulActivity = Object.assign(Root$3, {
+	Summary,
+	Filters,
+	Search,
+	Rows,
+	LoadMore,
+	Detail,
+	Export
+});
+//#endregion
 //#region src/headless/send-money/signer-status.ts
 const NO_SUBSCRIPTION = () => () => {};
 function useSignerStatus(client) {
@@ -1556,4 +2217,4 @@ const CapxulDashboardAccess = Object.assign(Root, {
 	Granted
 });
 //#endregion
-export { CapxulAuthenticationController, CapxulContacts, CapxulDashboardAccess, CapxulOnboardingController, CapxulOrgMember, CapxulProvider, CapxulSendMoney, acknowledgeOnboardingDestination, activeOnboardingRecovery, clearOnboardingJourney, currentOnboardingJourneyId, entered, invalidateOnboardingJourneyObservation, isClaimed, isRestoring, loadOnboardingJourney, onboardingJourneyPosition, saveOnboardingJourney, startOnboardingJourney, useCapxul, useCapxulAccountBalance, useCapxulAccountFund, useCapxulActivity, useCapxulActivityDetail, useCapxulAnnotateMovement, useCapxulAuth, useCapxulCancelPayment, useCapxulClaimPayment, useCapxulClientOrNull, useCapxulCreateCommitment, useCapxulCreateOrg, useCapxulDestination, useCapxulHoldings, useCapxulIdentity, useCapxulImageUpload, useCapxulInviteMember, useCapxulOrgMembers, useCapxulOrgRoles, useCapxulOrgTreasury, useCapxulOrganizationPay, useCapxulOrganizationPayBatch, useCapxulOrgs, useCapxulPay, useCapxulPayment, useCapxulPayments, useCapxulPermission, useCapxulPermissionAssign, useCapxulPermissionChange, useCapxulPermissionCreate, useCapxulPermissionReplace, useCapxulPermissionRevoke, useCapxulPermissions, useCapxulProfile, useCapxulRedirectPayment, useCapxulSend, useCapxulTransitions, useCapxulUsernameAvailability };
+export { CapxulActivity, CapxulAuthenticationController, CapxulContacts, CapxulDashboardAccess, CapxulOnboardingController, CapxulOrgMember, CapxulProvider, CapxulSendMoney, 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, useCapxulHoldings, useCapxulIdentity, useCapxulImageUpload, useCapxulInviteMember, useCapxulOrgMembers, useCapxulOrgRoles, useCapxulOrgTreasury, useCapxulOrganizationPay, useCapxulOrganizationPayBatch, useCapxulOrgs, useCapxulPay, useCapxulPayment, useCapxulPayments, useCapxulPermission, useCapxulPermissionAssign, useCapxulPermissionChange, useCapxulPermissionCreate, useCapxulPermissionReplace, useCapxulPermissionRevoke, useCapxulPermissions, useCapxulProfile, useCapxulRedirectPayment, useCapxulSend, useCapxulTransitions, useCapxulUsernameAvailability };

package/dist/testing/index.mjs

@@ -1,4 +1,4 @@
-import { n as CapxulOnboardingController, r as CapxulProvider, t as CapxulAuthenticationController } from "../controllers-VwUPB619.mjs";
+import { n as CapxulOnboardingController, r as CapxulProvider, t as CapxulAuthenticationController } from "../controllers-DLBe4-OP.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.3.1",
+  "version": "2.4.0",
   "repository": {
     "type": "git",
     "url": "git+https://github.com/Xelmar-tech/infrastructure.git",
@@ -26,7 +26,7 @@
     "access": "public"
   },
   "dependencies": {
-    "@capxul/sdk": "2.3.1"
+    "@capxul/sdk": "2.4.0"
   },
   "devDependencies": {
     "@tanstack/react-query": "^5.66.9",