@agg-build/ui 2.1.1 → 2.1.2

package/dist/trading.mjs

@@ -5,8 +5,10 @@ import {
   PlaceOrderSuccessView,
   SettlementDetails,
   parseAmount,
-  parseVenue
-} from "./chunk-XHDGSRG7.mjs";
+  parseVenue,
+  useClaimWinnings,
+  useResolvedMarketClaim
+} from "./chunk-ZOECARZW.mjs";
 import {
   SETTLEMENT_SECTION_ID,
   Settlement,
@@ -21,9 +23,9 @@ import {
   getTradingValueLabel,
   getTradingVenueLabel,
   useEventTradingContext
-} from "./chunk-TERG43WW.mjs";
-import "./chunk-RPXRTXCY.mjs";
-import "./chunk-YJO6LMRT.mjs";
+} from "./chunk-5RBHMMY3.mjs";
+import "./chunk-75AMJAWR.mjs";
+import "./chunk-TBD3N4T4.mjs";
 export {
   PlaceOrder,
   PlaceOrderFailureView,
@@ -43,5 +45,7 @@ export {
   getTradingVenueLabel,
   parseAmount,
   parseVenue,
-  useEventTradingContext
+  useClaimWinnings,
+  useEventTradingContext,
+  useResolvedMarketClaim
 };

package/dist/types/events/shared/format-event-title.d.mts

@@ -0,0 +1,25 @@
+type EventCategoryLike = {
+    id?: string | null;
+    category?: {
+        id?: string | null;
+        name?: string | null;
+        displayName?: string | null;
+        parentId?: string | null;
+    } | null;
+};
+type FormatEventTitleWithDateSuffixParams = {
+    title: string;
+    categories?: readonly EventCategoryLike[] | null;
+    structureType?: string | null;
+    /**
+     * Scheduled kickoff of the underlying game. Preferred over `endDate` for
+     * the date suffix because `endDate` is the market close/expiration, which
+     * can sit well after the game (e.g. Kalshi World Cup markets expire weeks
+     * later — a June 22 game would otherwise read "- July 6").
+     */
+    gameStartTime?: string | null;
+    endDate?: string | null;
+    locale?: string;
+};
+export declare const formatEventTitleWithDateSuffix: ({ title, categories, structureType, gameStartTime, endDate, locale, }: FormatEventTitleWithDateSuffixParams) => string;
+export {};

package/dist/types/events/shared/format-event-title.d.ts

@@ -0,0 +1,25 @@
+type EventCategoryLike = {
+    id?: string | null;
+    category?: {
+        id?: string | null;
+        name?: string | null;
+        displayName?: string | null;
+        parentId?: string | null;
+    } | null;
+};
+type FormatEventTitleWithDateSuffixParams = {
+    title: string;
+    categories?: readonly EventCategoryLike[] | null;
+    structureType?: string | null;
+    /**
+     * Scheduled kickoff of the underlying game. Preferred over `endDate` for
+     * the date suffix because `endDate` is the market close/expiration, which
+     * can sit well after the game (e.g. Kalshi World Cup markets expire weeks
+     * later — a June 22 game would otherwise read "- July 6").
+     */
+    gameStartTime?: string | null;
+    endDate?: string | null;
+    locale?: string;
+};
+export declare const formatEventTitleWithDateSuffix: ({ title, categories, structureType, gameStartTime, endDate, locale, }: FormatEventTitleWithDateSuffixParams) => string;
+export {};

package/dist/types/events/shared/select-best-outcome.d.mts

@@ -0,0 +1,88 @@
+import type { LiveBestPriceCandidate } from "@agg-build/hooks";
+/** Which data tier produced the winning price + venue. */
+export type BestOutcomeSource = "ws" | "rest-best" | "rest-midpoint" | "static";
+/**
+ * The single, unified result for an outcome pill: price and venue resolved
+ * together from the *same* tier, so the displayed price and the venue logo can
+ * never disagree. `venueMarketId`, `source` and `updatedAt` are carried for
+ * telemetry/debugging and to let callers reason about freshness.
+ */
+export interface BestOutcomeCandidate {
+    price: number;
+    venue: string | undefined;
+    venueMarketId: string | undefined;
+    outcomeId: string;
+    source: BestOutcomeSource;
+    updatedAt: number | undefined;
+}
+export interface SelectBestOutcomeArgs {
+    outcomeId: string | null | undefined;
+    outcomeLabel?: string | null | undefined;
+    /** Active trade side. When set, the best ask (buy) / best bid (sell) wins. */
+    selection?: "buy" | "sell" | undefined;
+    /**
+     * Live WS candidate for this outcome — already folded across all venues for
+     * the outcome's MVMO group (see `buildLiveBestPriceCandidates`). Carries the
+     * venue that owns each side, so when a different venue takes the best live
+     * price the logo follows the price.
+     */
+    live?: LiveBestPriceCandidate | null | undefined;
+    /** REST cross-venue best bid/ask (fallback when WS hasn't landed). */
+    restBest?: {
+        bestBid?: number;
+        bestAsk?: number;
+    } | null | undefined;
+    /** REST venue that produced each side of `restBest`. */
+    restBestVenues?: {
+        bestBidVenue?: string;
+        bestAskVenue?: string;
+    } | null | undefined;
+    /** REST per-outcome midpoint (display-path fallback). */
+    restMidpoint?: number | null | undefined;
+    /** Venue that produced `restMidpoint`. */
+    restMidpointVenue?: string | null | undefined;
+    /** Cluster-wide "Yes" reference midpoint (display path, "yes" labels only). */
+    bestMidpoint?: number | null | undefined;
+    /** Venue that produced `bestMidpoint`. */
+    bestMidpointVenue?: string | null | undefined;
+    /** Final static fallback — the outcome's payload price. */
+    staticPrice?: number | null | undefined;
+    /** Venue for the static fallback (typically the local market's own venue). */
+    staticVenue?: string | null | undefined;
+    /** Resolves a venue name → its venueMarketId within the cluster (best effort). */
+    venueMarketIdByVenue?: ReadonlyMap<string, string> | null | undefined;
+}
+/**
+ * Resolve the single best price + venue for an outcome across all venues.
+ *
+ * Candidate priority (price and venue are always taken from the SAME tier):
+ *   With a trade selection (buy/sell):
+ *     1. fresh WS best ask/bid for that side  → source "ws"
+ *     2. REST best ask/bid for that side       → source "rest-best"
+ *     3. fresh WS midpoint                      → source "ws"
+ *     4. REST per-outcome midpoint              → source "rest-midpoint"
+ *     5. static outcome price                   → source "static"
+ *   Display path (no selection):
+ *     1. fresh WS midpoint                      → source "ws"
+ *     2. cluster "Yes" reference (yes labels)   → source "rest-midpoint"
+ *     3. REST per-outcome midpoint              → source "rest-midpoint"
+ *     4. static outcome price                   → source "static"
+ *
+ * Because WS is preferred per side over REST, a stale REST snapshot can never
+ * override newer live data — and because the venue is read from whichever tier
+ * supplied the price, the logo and the price switch together.
+ */
+export declare const selectBestOutcomeCandidate: (args: SelectBestOutcomeArgs) => BestOutcomeCandidate | undefined;
+/**
+ * Build a venue-name → venueMarketId lookup across a cluster (including matched
+ * siblings). First occurrence wins. Used to resolve the winning venue's market
+ * id for {@link selectBestOutcomeCandidate}.
+ */
+export declare const buildVenueMarketIdByVenue: (venueMarkets: ReadonlyArray<{
+    id?: string;
+    venue?: string | null;
+    matchedVenueMarkets?: ReadonlyArray<{
+        id?: string;
+        venue?: string | null;
+    }> | null;
+}> | null | undefined) => Map<string, string>;

package/dist/types/events/shared/select-best-outcome.d.ts

@@ -0,0 +1,88 @@
+import type { LiveBestPriceCandidate } from "@agg-build/hooks";
+/** Which data tier produced the winning price + venue. */
+export type BestOutcomeSource = "ws" | "rest-best" | "rest-midpoint" | "static";
+/**
+ * The single, unified result for an outcome pill: price and venue resolved
+ * together from the *same* tier, so the displayed price and the venue logo can
+ * never disagree. `venueMarketId`, `source` and `updatedAt` are carried for
+ * telemetry/debugging and to let callers reason about freshness.
+ */
+export interface BestOutcomeCandidate {
+    price: number;
+    venue: string | undefined;
+    venueMarketId: string | undefined;
+    outcomeId: string;
+    source: BestOutcomeSource;
+    updatedAt: number | undefined;
+}
+export interface SelectBestOutcomeArgs {
+    outcomeId: string | null | undefined;
+    outcomeLabel?: string | null | undefined;
+    /** Active trade side. When set, the best ask (buy) / best bid (sell) wins. */
+    selection?: "buy" | "sell" | undefined;
+    /**
+     * Live WS candidate for this outcome — already folded across all venues for
+     * the outcome's MVMO group (see `buildLiveBestPriceCandidates`). Carries the
+     * venue that owns each side, so when a different venue takes the best live
+     * price the logo follows the price.
+     */
+    live?: LiveBestPriceCandidate | null | undefined;
+    /** REST cross-venue best bid/ask (fallback when WS hasn't landed). */
+    restBest?: {
+        bestBid?: number;
+        bestAsk?: number;
+    } | null | undefined;
+    /** REST venue that produced each side of `restBest`. */
+    restBestVenues?: {
+        bestBidVenue?: string;
+        bestAskVenue?: string;
+    } | null | undefined;
+    /** REST per-outcome midpoint (display-path fallback). */
+    restMidpoint?: number | null | undefined;
+    /** Venue that produced `restMidpoint`. */
+    restMidpointVenue?: string | null | undefined;
+    /** Cluster-wide "Yes" reference midpoint (display path, "yes" labels only). */
+    bestMidpoint?: number | null | undefined;
+    /** Venue that produced `bestMidpoint`. */
+    bestMidpointVenue?: string | null | undefined;
+    /** Final static fallback — the outcome's payload price. */
+    staticPrice?: number | null | undefined;
+    /** Venue for the static fallback (typically the local market's own venue). */
+    staticVenue?: string | null | undefined;
+    /** Resolves a venue name → its venueMarketId within the cluster (best effort). */
+    venueMarketIdByVenue?: ReadonlyMap<string, string> | null | undefined;
+}
+/**
+ * Resolve the single best price + venue for an outcome across all venues.
+ *
+ * Candidate priority (price and venue are always taken from the SAME tier):
+ *   With a trade selection (buy/sell):
+ *     1. fresh WS best ask/bid for that side  → source "ws"
+ *     2. REST best ask/bid for that side       → source "rest-best"
+ *     3. fresh WS midpoint                      → source "ws"
+ *     4. REST per-outcome midpoint              → source "rest-midpoint"
+ *     5. static outcome price                   → source "static"
+ *   Display path (no selection):
+ *     1. fresh WS midpoint                      → source "ws"
+ *     2. cluster "Yes" reference (yes labels)   → source "rest-midpoint"
+ *     3. REST per-outcome midpoint              → source "rest-midpoint"
+ *     4. static outcome price                   → source "static"
+ *
+ * Because WS is preferred per side over REST, a stale REST snapshot can never
+ * override newer live data — and because the venue is read from whichever tier
+ * supplied the price, the logo and the price switch together.
+ */
+export declare const selectBestOutcomeCandidate: (args: SelectBestOutcomeArgs) => BestOutcomeCandidate | undefined;
+/**
+ * Build a venue-name → venueMarketId lookup across a cluster (including matched
+ * siblings). First occurrence wins. Used to resolve the winning venue's market
+ * id for {@link selectBestOutcomeCandidate}.
+ */
+export declare const buildVenueMarketIdByVenue: (venueMarkets: ReadonlyArray<{
+    id?: string;
+    venue?: string | null;
+    matchedVenueMarkets?: ReadonlyArray<{
+        id?: string;
+        venue?: string | null;
+    }> | null;
+}> | null | undefined) => Map<string, string>;

package/dist/types/pages/event-market/event-market.types.d.mts

@@ -1,5 +1,6 @@
 import type { VenueEventWithMarkets } from "../../events/item/event-list-item.types";
 import type { PlaceOrderResolvedClaimSummary } from "../../trading";
+import type { PlaceOrderProps } from "../../trading/place-order/index.place-order.types";
 export type EventMarketPageClassNames = Partial<{
     root: string;
     content: string;
@@ -44,6 +45,12 @@ export type EventMarketPageBaseProps = {
     defaultOutcomeId?: string;
     /** Whether to render the place-order panel. */
     showPlaceOrder?: boolean;
+    /**
+     * Pre-flight gate run before the internal quote execution, forwarded to the
+     * place-order panel. When it resolves the order fills as usual; return
+     * `false` to cancel or throw to abort. See `PlaceOrderProps.onBeforePrimaryAction`.
+     */
+    onBeforePrimaryAction?: PlaceOrderProps["onBeforePrimaryAction"];
     executionMode?: "live" | "paper";
     /** Optional resolved-event claim summary shown inside the read-only order panel. */
     resolvedClaim?: PlaceOrderResolvedClaimSummary;

package/dist/types/pages/event-market/event-market.types.d.ts

@@ -1,5 +1,6 @@
 import type { VenueEventWithMarkets } from "../../events/item/event-list-item.types";
 import type { PlaceOrderResolvedClaimSummary } from "../../trading";
+import type { PlaceOrderProps } from "../../trading/place-order/index.place-order.types";
 export type EventMarketPageClassNames = Partial<{
     root: string;
     content: string;
@@ -44,6 +45,12 @@ export type EventMarketPageBaseProps = {
     defaultOutcomeId?: string;
     /** Whether to render the place-order panel. */
     showPlaceOrder?: boolean;
+    /**
+     * Pre-flight gate run before the internal quote execution, forwarded to the
+     * place-order panel. When it resolves the order fills as usual; return
+     * `false` to cancel or throw to abort. See `PlaceOrderProps.onBeforePrimaryAction`.
+     */
+    onBeforePrimaryAction?: PlaceOrderProps["onBeforePrimaryAction"];
     executionMode?: "live" | "paper";
     /** Optional resolved-event claim summary shown inside the read-only order panel. */
     resolvedClaim?: PlaceOrderResolvedClaimSummary;

package/dist/types/primitives/search/search.utils.d.mts

@@ -1,4 +1,6 @@
 import type { AggUiLabels } from "@agg-build/hooks";
 import type { VenueEventWithMarkets } from "../../events/item";
 import type { SearchResultItem } from "./search.types";
-export declare const mapVenueEventToSearchResult: (event: VenueEventWithMarkets, labels: AggUiLabels, formatPercent: (value: number) => string, formatCompactCurrency: (value: number) => string) => SearchResultItem | null;
+export declare const mapVenueEventToSearchResult: (event: VenueEventWithMarkets, labels: AggUiLabels, formatPercent: (value: number) => string, formatCompactCurrency: (value: number) => string, options?: {
+    locale?: string;
+}) => SearchResultItem | null;

package/dist/types/primitives/search/search.utils.d.ts

@@ -1,4 +1,6 @@
 import type { AggUiLabels } from "@agg-build/hooks";
 import type { VenueEventWithMarkets } from "../../events/item";
 import type { SearchResultItem } from "./search.types";
-export declare const mapVenueEventToSearchResult: (event: VenueEventWithMarkets, labels: AggUiLabels, formatPercent: (value: number) => string, formatCompactCurrency: (value: number) => string) => SearchResultItem | null;
+export declare const mapVenueEventToSearchResult: (event: VenueEventWithMarkets, labels: AggUiLabels, formatPercent: (value: number) => string, formatCompactCurrency: (value: number) => string, options?: {
+    locale?: string;
+}) => SearchResultItem | null;

package/dist/types/trading/index.d.mts

@@ -4,3 +4,5 @@ export * from "./settlement";
 export * from "./settlement/settlement-details";
 export * from "./place-order";
 export * from "./trading-context";
+export * from "./use-claim-winnings";
+export * from "./use-resolved-market-claim";

package/dist/types/trading/index.d.ts

@@ -4,3 +4,5 @@ export * from "./settlement";
 export * from "./settlement/settlement-details";
 export * from "./place-order";
 export * from "./trading-context";
+export * from "./use-claim-winnings";
+export * from "./use-resolved-market-claim";

package/dist/types/trading/place-order/index.d.mts

@@ -5,6 +5,6 @@ export { PlaceOrderSuccessView } from "./index.place-order.success";
 export type { PlaceOrderSuccessViewProps } from "./index.place-order.success";
 export type { PlaceOrderClassNames, PlaceOrderExecutionSummary, PlaceOrderResolvedClaimSummary, PlaceOrderTradingLabels, } from "./index.place-order.types";
 export declare const PlaceOrder: {
-    ({ className, classNames, eventTradingState, executionMode, isLoading, isPrimaryActionDisabled, isPrimaryActionLoading, chainBalancesOverride, onAmountChange, onClose, onOutcomeChange, onPrimaryAction, onTabChange, onSuccess, onError, onExecutionStateChange, resolvedClaim, midpointsResult, }: PlaceOrderProps): JSX.Element;
+    ({ className, classNames, eventTradingState, executionMode, isLoading, isPrimaryActionDisabled, isPrimaryActionLoading, chainBalancesOverride, onAmountChange, onClose, onOutcomeChange, onPrimaryAction, onBeforePrimaryAction, onTabChange, onSuccess, onError, onExecutionStateChange, resolvedClaim, midpointsResult, }: PlaceOrderProps): JSX.Element;
     displayName: string;
 };

package/dist/types/trading/place-order/index.d.ts

@@ -5,6 +5,6 @@ export { PlaceOrderSuccessView } from "./index.place-order.success";
 export type { PlaceOrderSuccessViewProps } from "./index.place-order.success";
 export type { PlaceOrderClassNames, PlaceOrderExecutionSummary, PlaceOrderResolvedClaimSummary, PlaceOrderTradingLabels, } from "./index.place-order.types";
 export declare const PlaceOrder: {
-    ({ className, classNames, eventTradingState, executionMode, isLoading, isPrimaryActionDisabled, isPrimaryActionLoading, chainBalancesOverride, onAmountChange, onClose, onOutcomeChange, onPrimaryAction, onTabChange, onSuccess, onError, onExecutionStateChange, resolvedClaim, midpointsResult, }: PlaceOrderProps): JSX.Element;
+    ({ className, classNames, eventTradingState, executionMode, isLoading, isPrimaryActionDisabled, isPrimaryActionLoading, chainBalancesOverride, onAmountChange, onClose, onOutcomeChange, onPrimaryAction, onBeforePrimaryAction, onTabChange, onSuccess, onError, onExecutionStateChange, resolvedClaim, midpointsResult, }: PlaceOrderProps): JSX.Element;
     displayName: string;
 };

package/dist/types/trading/place-order/index.place-order.types.d.mts

@@ -22,11 +22,33 @@ export type PlaceOrderProps = {
     onClose?: () => void;
     /** Called when the selected outcome changes. */
     onOutcomeChange?: (outcomeId: string) => void;
-    /** Called when the primary action is triggered. */
+    /**
+     * Called when the primary action is triggered, in place of the internal
+     * quote execution. When provided, the component delegates the fill entirely
+     * to this callback and does NOT run its own execution. For a pre-flight gate
+     * that should run *before* the normal fill (and let it proceed), use
+     * `onBeforePrimaryAction` instead.
+     */
     onPrimaryAction?: (context?: {
         quoteId?: string;
         mode?: ExecutionMode;
     }) => void;
+    /**
+     * Called when the primary action is triggered, BEFORE the internal quote
+     * execution. Unlike `onPrimaryAction`, this does not replace the fill — it
+     * runs in between and, when it resolves, the order is filled as usual. Use it
+     * for a partner gate such as a verification/KYC modal that must complete
+     * before the order goes through.
+     *
+     * The returned promise is awaited before execution proceeds:
+     * - resolve (return `undefined`/`true`) → continue with the normal fill
+     * - return `false` → cancel silently; the panel returns to idle
+     * - throw → abort and surface the error as submission feedback
+     */
+    onBeforePrimaryAction?: (context?: {
+        quoteId?: string;
+        mode?: ExecutionMode;
+    }) => void | boolean | Promise<void | boolean>;
     /** Called when the slippage control value changes. */
     onSlippageChange?: (value: string) => void;
     /** Called when the active trade tab changes. */

package/dist/types/trading/place-order/index.place-order.types.d.ts

@@ -22,11 +22,33 @@ export type PlaceOrderProps = {
     onClose?: () => void;
     /** Called when the selected outcome changes. */
     onOutcomeChange?: (outcomeId: string) => void;
-    /** Called when the primary action is triggered. */
+    /**
+     * Called when the primary action is triggered, in place of the internal
+     * quote execution. When provided, the component delegates the fill entirely
+     * to this callback and does NOT run its own execution. For a pre-flight gate
+     * that should run *before* the normal fill (and let it proceed), use
+     * `onBeforePrimaryAction` instead.
+     */
     onPrimaryAction?: (context?: {
         quoteId?: string;
         mode?: ExecutionMode;
     }) => void;
+    /**
+     * Called when the primary action is triggered, BEFORE the internal quote
+     * execution. Unlike `onPrimaryAction`, this does not replace the fill — it
+     * runs in between and, when it resolves, the order is filled as usual. Use it
+     * for a partner gate such as a verification/KYC modal that must complete
+     * before the order goes through.
+     *
+     * The returned promise is awaited before execution proceeds:
+     * - resolve (return `undefined`/`true`) → continue with the normal fill
+     * - return `false` → cancel silently; the panel returns to idle
+     * - throw → abort and surface the error as submission feedback
+     */
+    onBeforePrimaryAction?: (context?: {
+        quoteId?: string;
+        mode?: ExecutionMode;
+    }) => void | boolean | Promise<void | boolean>;
     /** Called when the slippage control value changes. */
     onSlippageChange?: (value: string) => void;
     /** Called when the active trade tab changes. */

package/dist/types/trading/use-claim-winnings.d.mts

@@ -0,0 +1,84 @@
+/**
+ * Shape of the `notifications.claim` label block consumed by the claim flow.
+ * Mirrors the typed labels so callers can reason about the toast copy.
+ */
+export type ClaimNotificationLabels = {
+    pendingTitle: string;
+    pendingMessage: string;
+    submittedTitle: string;
+    submittedMessage: string;
+    successTitle: string;
+    successMessage: string;
+    partialTitle: string;
+    partialMessage: (errorReason?: string) => string;
+    failedTitle: string;
+    failedMessage: (errorReason?: string) => string;
+    missingOutcomeMessage: string;
+};
+/** Terminal lifecycle summary forwarded to `onClaimResult`. */
+export type ClaimLifecycleResult = {
+    allConfirmed: boolean;
+    anyFailed: boolean;
+    errorMessage: string | null;
+};
+/** A single claim request keyed by `claimKey`. */
+export type ClaimWinningsInput<TPayload = void> = {
+    /** Stable identifier for the position being claimed (e.g. `marketId`). */
+    claimKey: string;
+    /** Winning venue-market-outcome ids to redeem. */
+    winningOutcomeIds: string[];
+    /** Opaque payload forwarded verbatim to a caller-provided `onClaim`. */
+    payload?: TPayload;
+};
+export type UseClaimWinningsOptions<TPayload = void> = {
+    /**
+     * Caller-owned claim handler. When provided, the hook delegates the actual
+     * redeem to this callback and toasts a simple pending → success/failure
+     * lifecycle (no WS lifecycle tracking). Partners who own the claim flow pass
+     * this; omit it to let the hook drive the internal redeem mutation.
+     */
+    onClaim?: (payload: TPayload) => Promise<void> | void;
+    /**
+     * Fired once per redeem when its WS lifecycle reaches terminal. Only fired on
+     * the internal claim path (i.e. when `onClaim` is omitted).
+     */
+    onClaimResult?: (claimKey: string, lifecycle: ClaimLifecycleResult) => void;
+    /**
+     * Fired when the redeem mutation itself rejects (transport error, validation
+     * error, or all legs ineligible/rejected at submit time). The redeem never
+     * enters the WS lifecycle in these cases, so `onClaimResult` does NOT fire.
+     */
+    onClaimSubmitError?: (claimKey: string, error: Error) => void;
+    /**
+     * Caller-owned spinner map. When provided, it fully replaces the hook's
+     * lifecycle-derived spinner state for display purposes (mirrors the legacy
+     * `claimingPositionKeys ?? internal` behavior).
+     */
+    externalClaimingKeys?: Record<string, boolean>;
+};
+export type UseClaimWinningsResult<TPayload = void> = {
+    /** Start a claim for a single position. Resolves once the submit settles. */
+    claim: (input: ClaimWinningsInput<TPayload>) => Promise<void>;
+    /** Map of claim key → in-flight flag, suitable to pass to a row renderer. */
+    claimingKeys: Record<string, boolean>;
+    /** Whether a given claim key is currently in-flight (submit or lifecycle). */
+    isClaiming: (claimKey: string) => boolean;
+};
+/**
+ * Encapsulates the full "claim winnings" (redeem) lifecycle so multiple
+ * surfaces (the profile positions list, the resolved market trade panel) can
+ * share one implementation instead of duplicating the redeem → WS lifecycle →
+ * toast → cache-invalidation orchestration.
+ *
+ * The flow has two paths:
+ *  - **Internal** (`onClaim` omitted): submit via the redeem mutation, bucket
+ *    the response legs (submitted / confirmed / ineligible / rejected), track
+ *    EVM async legs through their WS lifecycle, and toast pending → submitted →
+ *    success/partial/failed.
+ *  - **Delegated** (`onClaim` provided): the caller performs the redeem; the
+ *    hook only toasts pending → success/failure.
+ *
+ * Both paths invalidate balances, positions, the claimable count, the activity
+ * feed, and the current-user query so dependent UI refreshes.
+ */
+export declare function useClaimWinnings<TPayload = void>(options?: UseClaimWinningsOptions<TPayload>): UseClaimWinningsResult<TPayload>;

package/dist/types/trading/use-claim-winnings.d.ts

@@ -0,0 +1,84 @@
+/**
+ * Shape of the `notifications.claim` label block consumed by the claim flow.
+ * Mirrors the typed labels so callers can reason about the toast copy.
+ */
+export type ClaimNotificationLabels = {
+    pendingTitle: string;
+    pendingMessage: string;
+    submittedTitle: string;
+    submittedMessage: string;
+    successTitle: string;
+    successMessage: string;
+    partialTitle: string;
+    partialMessage: (errorReason?: string) => string;
+    failedTitle: string;
+    failedMessage: (errorReason?: string) => string;
+    missingOutcomeMessage: string;
+};
+/** Terminal lifecycle summary forwarded to `onClaimResult`. */
+export type ClaimLifecycleResult = {
+    allConfirmed: boolean;
+    anyFailed: boolean;
+    errorMessage: string | null;
+};
+/** A single claim request keyed by `claimKey`. */
+export type ClaimWinningsInput<TPayload = void> = {
+    /** Stable identifier for the position being claimed (e.g. `marketId`). */
+    claimKey: string;
+    /** Winning venue-market-outcome ids to redeem. */
+    winningOutcomeIds: string[];
+    /** Opaque payload forwarded verbatim to a caller-provided `onClaim`. */
+    payload?: TPayload;
+};
+export type UseClaimWinningsOptions<TPayload = void> = {
+    /**
+     * Caller-owned claim handler. When provided, the hook delegates the actual
+     * redeem to this callback and toasts a simple pending → success/failure
+     * lifecycle (no WS lifecycle tracking). Partners who own the claim flow pass
+     * this; omit it to let the hook drive the internal redeem mutation.
+     */
+    onClaim?: (payload: TPayload) => Promise<void> | void;
+    /**
+     * Fired once per redeem when its WS lifecycle reaches terminal. Only fired on
+     * the internal claim path (i.e. when `onClaim` is omitted).
+     */
+    onClaimResult?: (claimKey: string, lifecycle: ClaimLifecycleResult) => void;
+    /**
+     * Fired when the redeem mutation itself rejects (transport error, validation
+     * error, or all legs ineligible/rejected at submit time). The redeem never
+     * enters the WS lifecycle in these cases, so `onClaimResult` does NOT fire.
+     */
+    onClaimSubmitError?: (claimKey: string, error: Error) => void;
+    /**
+     * Caller-owned spinner map. When provided, it fully replaces the hook's
+     * lifecycle-derived spinner state for display purposes (mirrors the legacy
+     * `claimingPositionKeys ?? internal` behavior).
+     */
+    externalClaimingKeys?: Record<string, boolean>;
+};
+export type UseClaimWinningsResult<TPayload = void> = {
+    /** Start a claim for a single position. Resolves once the submit settles. */
+    claim: (input: ClaimWinningsInput<TPayload>) => Promise<void>;
+    /** Map of claim key → in-flight flag, suitable to pass to a row renderer. */
+    claimingKeys: Record<string, boolean>;
+    /** Whether a given claim key is currently in-flight (submit or lifecycle). */
+    isClaiming: (claimKey: string) => boolean;
+};
+/**
+ * Encapsulates the full "claim winnings" (redeem) lifecycle so multiple
+ * surfaces (the profile positions list, the resolved market trade panel) can
+ * share one implementation instead of duplicating the redeem → WS lifecycle →
+ * toast → cache-invalidation orchestration.
+ *
+ * The flow has two paths:
+ *  - **Internal** (`onClaim` omitted): submit via the redeem mutation, bucket
+ *    the response legs (submitted / confirmed / ineligible / rejected), track
+ *    EVM async legs through their WS lifecycle, and toast pending → submitted →
+ *    success/partial/failed.
+ *  - **Delegated** (`onClaim` provided): the caller performs the redeem; the
+ *    hook only toasts pending → success/failure.
+ *
+ * Both paths invalidate balances, positions, the claimable count, the activity
+ * feed, and the current-user query so dependent UI refreshes.
+ */
+export declare function useClaimWinnings<TPayload = void>(options?: UseClaimWinningsOptions<TPayload>): UseClaimWinningsResult<TPayload>;

package/dist/types/trading/use-resolved-market-claim.d.mts

@@ -0,0 +1,26 @@
+import { type VenueMarket } from "@agg-build/hooks";
+import type { PlaceOrderResolvedClaimSummary } from "./place-order";
+export type UseResolvedMarketClaimOptions = {
+    /** The resolved market whose claimable winnings should be summarized. */
+    market?: VenueMarket | null;
+    /** Gate fetching/computation (e.g. only when the trade panel is resolved). */
+    enabled?: boolean;
+    /** Execution mode — paper positions are fetched from the paper bucket. */
+    executionMode?: "live" | "paper";
+};
+/**
+ * Derives the resolved-market claim summary (resolution date, winning shares,
+ * total payout, and a wired claim action) for the position the current user
+ * holds in `market`, reusing the same redeem flow as the profile positions
+ * list via {@link useClaimWinnings}.
+ *
+ * Returns `undefined` (so the caller renders the plain resolved view) when:
+ *  - fetching is disabled, the user is unauthenticated, or the market is open;
+ *  - the user holds no position in this market;
+ *  - the user's position lost (no winning outcome with shares).
+ *
+ * When the user won but the position is already redeemed / pending / ineligible
+ * (i.e. not `eligible`), the summary is returned WITHOUT an `onClaim` action so
+ * the earnings show without a duplicate claim CTA.
+ */
+export declare function useResolvedMarketClaim(options?: UseResolvedMarketClaimOptions): PlaceOrderResolvedClaimSummary | undefined;

package/dist/types/trading/use-resolved-market-claim.d.ts

@@ -0,0 +1,26 @@
+import { type VenueMarket } from "@agg-build/hooks";
+import type { PlaceOrderResolvedClaimSummary } from "./place-order";
+export type UseResolvedMarketClaimOptions = {
+    /** The resolved market whose claimable winnings should be summarized. */
+    market?: VenueMarket | null;
+    /** Gate fetching/computation (e.g. only when the trade panel is resolved). */
+    enabled?: boolean;
+    /** Execution mode — paper positions are fetched from the paper bucket. */
+    executionMode?: "live" | "paper";
+};
+/**
+ * Derives the resolved-market claim summary (resolution date, winning shares,
+ * total payout, and a wired claim action) for the position the current user
+ * holds in `market`, reusing the same redeem flow as the profile positions
+ * list via {@link useClaimWinnings}.
+ *
+ * Returns `undefined` (so the caller renders the plain resolved view) when:
+ *  - fetching is disabled, the user is unauthenticated, or the market is open;
+ *  - the user holds no position in this market;
+ *  - the user's position lost (no winning outcome with shares).
+ *
+ * When the user won but the position is already redeemed / pending / ineligible
+ * (i.e. not `eligible`), the summary is returned WITHOUT an `onClaim` action so
+ * the earnings show without a duplicate claim CTA.
+ */
+export declare function useResolvedMarketClaim(options?: UseResolvedMarketClaimOptions): PlaceOrderResolvedClaimSummary | undefined;